eCos - the Embedded Cygnus Operating System - release 1.2.1 README
==================================================================

April 1999

This readme file details problems found in the final stages of QA testing after
the documentation was printed. These problems will be resolved in forthcoming
releases of eCos and its associated tools. Check the upcoming eCos Sourceware
anonymous cvs repository for fixes and feature updates. This readme covers both
the Developer's Kit CD and the Sourceware releases of eCos.


-------------------------------------------------------------------------------
eCos 1.2.1 Documentation Errata
-------------------------------

PR17569
Host:		All
Problem:	The appearance of asterisks against configuration items in the
		eCos Configuration Tool is not mentioned in the documentation.
Workaround:	Users should note that an asterisk appears against
		configuration items which have changed since the configuration
		was last saved.

PR19731
Target:		SPARClite
Problem:	With a SPARClite target, kernel exceptions may not work as
		expected when support for CygMon is enabled. This is the
		default configuration when building for the SPARClite
		evaluation board with RAM startup. This problem occurs
		because certain hardware exception vectors are handled
		directly by CygMon, rather than eCos. As a result, registering
		an exception handler for those exceptions will not have any
		effect. This problem is exhibited in the kernel	tests except1
		and kexcept1.
Workaround:	For the exceptions to be handled correctly the option
		CYG_HAL_USE_ROM_MONITOR_CYGMON must be disabled in
		<pkgconf/hal.h>. However, it will no longer be possible to
		interactively debug the target.

PR19737
Host:		Windows
Problem:	Use of the BASE_DIR expression within Chapter 12 of
		'Getting Started with eCos' is not clear.
Workaround:	The user should substitute the location of the eCos repository
		wherever BASE_DIR is encountered (eg /usr/local/ecos-1.2.1).
		Note also that pkgconf.tcl is located at
		BASE_DIR/packages/pkgconf.tcl and not as otherwise specified in
		this chapter.

PR19739
Target:		All
Problem:	The need to specify the architecture-specific version of GDB
		while following the tutorial text in Chapter 13 of
		'Getting Started with eCos' is not clear.
Workaround:	The user should substitute the appropriate architecture-
		specific version of GDB (eg 'sparclite-elf-gdb') wherever 'gdb' 
		is encountered in the documentation.

PR19871
Target:		All
Problem:	HAL stack size symbols are not documented.
Workaround:	HALs now define some symbols to make it easier to create stacks
		of a suitable size for the system in question, if writing code
		for many different eCos targets. This is target-dependent
		because of the varying memory needs for stack frames and for
		interrupt handling.
 
		The supported symbols are:

			CYGNUM_HAL_STACK_SIZE_MINIMUM
		and
			CYGNUM_HAL_STACK_SIZE_TYPICAL

		which are recommended for a thread which does almost nothing,
		such as the idle thread and for one which makes substantial use
		of system calls, a more typical thread, respectively. If your
		threads have stack variables of any size, you should add their
		size (in bytes) to these symbols when defining your stacks.

		If you enable asserts (CYGPKG_INFRA_DEBUG, CYGDBG_USE_ASSERTS),
		then threads with stack size smaller than
		CYGNUM_HAL_STACK_SIZE_MINIMUM will not be allowed to start; an
		assert will fire, halting the system.

		These symbols are typically made up of others which may be
		defined depending on architecture; an example is
		CYGNUM_HAL_STACK_FRAME_SIZE which represents the stack space
		needed to make a function call.  See your cyg/hal/hal_arch.h
		file for details, or others that it includes, for the stack
		requirements may vary with the number of simultaneously active
		interrupt sources, for example.
 
		In future releases, these sizes may change depending on
		configuration. Specifically, some target architectures are
		undergoing HAL improvements for future releases that will
		enable all interrupt processing code, including DSRs, to
		execute on a single separate dedicated stack; this will mean
		that normal thread stacks do not all need to have enough space
		for fielding all possible simultaneous interrupts, but instead
		just enough space to enter the interrupt system once.  This may
		reduce memory requirements considerably, depending on target,
		and so the values of these symbols will reduce to match in
		versions where this feature is supported.

PR19935:
Target:		All
Problem:	The configuration option
		CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER is documented but
		is no longer accessible from the eCos Configuration Tool.
Workaround:	Do not use CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER.

PR19954
Host:		Windows
Problem:	The format of output generated by the eCos Configuration Tool
		while running tests is not documented.
Workaround:	Developers should note that each line of output is prefixed by
		<tt.t/aa.a> which indicates the time at which the line was
		output.

		  tt.t is the time from the start of test execution
		  aa.a is the time since the output of the previous line

		Both quantities are measured in CPU seconds in the case of
		execution in simulators and in elapsed seconds in the case of
		execution on hardware.
 
PR19958
Target:		TX39, MN10300
Problem:	Developer Kit users only. The eCos documentation does not
		explain how to configure GDBTk to run eCos applications in the
		simulator.
Workaround:	Developers should note that the simulator switches (following
		'target sim') described in the documentation for running
		tests in the GDB simulator should be added to the simulator
		options	edit box in the	GDBTk target settings dialog box. For
		example, the GDB command for using the MN10300 simulator is
		as follows:

			target sim --board=stdeval1

		When using GDBTk, the developer should therefore enter the
		following in the simulator options edit box:

			--board=stdeval1

PR19987
Target:		TX39
Problem:	The command necessary to run CygMon in the simulator is
		incorrect in the GNUPro Reference for eCos (Toshiba TX39)
		document.
Workaround:	The correct command line is as follows:

		  mips-tx39-elf-run --board=jmr3904 --memory-region 0xffff8000,0x900 --memory-region 0xffffe000,0x4 --memory-region 0xb2100000,0x4 --sockser-addr=localhost:XXXX cygmon50.rom

PR20017
Target:		ARM
Problem:	In chapter 2 of 'Getting Started with eCos', the section 'ROM
		monitor image' does not mention the need to enable GDB stub
		support when debugging capabilities are required for the ARM
		evaluation boards.
Workaround:	Enable all the options grouped under 'Source-level debugging'
		in the eCos Configuration Tool.

PR20024
Problem:	The eCos serial filter tool (ser_filter) is not documented.
Workaround:	Refer to the file ser_filter.txt located in the tools/bin
		directory under the base of the eCos installation for details
		of this tool.

PR20025
Target:		ARM AEB-1
Problem:	In the examples Makefile, the XCC line is incorrect for the
		ARM AEB-1 evaluation board. The line for the ARM PID board
		is correct.
Workaround:	Modify the line by removing an 'm' character such that the
		line reads:

		  #XCC = arm-elf-gcc -mcpu=arm7di


-------------------------------------------------------------------------------
eCos 1.2.1 Known Problems
-------------------------

PR17485
PR19988
Host:		All
Problem:	In certain situations, pkgconf does not remove old header
		files when packages are added/removed from an existing
		build tree.
Workaround:	When packages are added/removed, the developer is recommended
		to save the revised configuration to a new build tree.

PR17814
Host:		Windows
Problem:	InstallShield incorrectly calculates the amount of disk
		free-space. It calculates available space on a character, not
		disk allocation unit basis. As the eCos distribution contains
		many small files, this can lead to installation being allowed
		to proceed when there is insufficient disk space available.
Workaround:	Please manually check that enough disk space exists after
		consulting the installation requirements in the documentation.

PR18848
Target:		Linux Synthetic Target
Problem:	The Linux getitimer returns [period, period] rather than
		[period, period-elapsed]. This causes HAL_CLOCK_READ to fail.
		The Linux synthetic target support is an alpha release.
Workaround:	There is no known workaround.

PR18956
Target:		Linux Synthetic Target
Problem:	An additional linker output section is required when linking
		eCos tests compiled for the i386-linux synthetic target with
		CYGIMP_LIBC_MALLOC_CXX_DELETE_CALLS_FREE enabled. The Linux
		synthetic target support is an alpha release.
Workaround:	Add a .rel.got linker-defined memory section to the memory
		layout when building eCos under these conditions.

PR19234
Target:		MN10300
Problem:	When using the eCos based GDB stub with the MN10300 target,
		the downloaded program cannot be executed.
Workaround:	Only use provided CygMon ROM monitor with the MN10300.		

PR19235
Target:		TX39
Problem:	When using the eCos based GDB stub with the TX39 target,
		the GDB 'info threads' command lists one thread only.
Workaround:	Use provided CygMon ROM monitor with the TX39.

PR19676
Host:		Windows
Problem:	When running under Windows 95, the eCos Configuration Tool
		does not always display any errors detected during the
		loading of an eCos repository.
Workaround:	There is no known workaround.

PR19695
Target:		TX39
Problem:	The cache locking macros (HAL_DCACHE_LOCK(),
		HAL_DCACHE_UNLOCK(), HAL_ICACHE_LOCK(), HAL_ICACHE_UNLOCK())
		for the TX39 may not lock the intended memory region.
Workaround:	The developer may implement alternative code to lock the
		cache if this functionality is required.

PR19732
Host:		Windows
Problem:	Under certain conditions, it is possible for the eCos
		Configuration Tool to enter a state where it will ignore user
		requests to exit.
Workaround:	Exit the Configuration Tool using the Task Manager.

PR19742
Host:		Windows
Problem:	Under Windows 95, the eCos Configuration Tool may cause an
		exception in USER.EXE while disabling an eCos package.
		Windows 95 support is currently Beta.
Workaround:	There is no known workaround.

PR19787
Host:		Windows
Problem:	Under certain circumstances, the eCos Configuration Tool may
		output a linker script fragment which has a forward reference.
		This results in a linker error of the form "LOADADDR forward
		reference ..." when attempting to build the eCos tests.
Workaround:	When modifying memory layouts, ensure that the order of memory
		sections is preserved during any section relocation.

PR19799
Host:		Windows
Problem:	Linker-defined memory sections which are defined to follow
		a user-defined memory section may not be displayed or output
		correctly by the eCos Configuration Tool.
Workaround:	Avoid specifying memory layouts where a linker-defined section
		follows a user-defined section.

PR19822
Target:		All
Problem:	When using the GDB 'thread' command to switch context to
		another thread, any register values changed by the user are not
		preserved.
Workaround:	There is no known workaround.

PR19823
Host:		Solaris
Problem:	The eCos serial4 test may report an error when running
		ser_filter under Sun Solaris. This is because serial ports on
		the Sun cannot be configured to use two stop bits.
Workaround:	There is no known workaround.

PR19908
Host:		Japanese NT
Problem:	Use of the 'Find' dialog box within the eCos Configuration
		Tool under the Japanese version of Windows NT 4.0 may generate
		an exception.
Workaround:	Avoid use of the 'Find' dialog if this problem is encountered.

PR19912
Target:		MN10300
Problem:	If compiler optimization level is set to -O0, then in very
		rare circumstances the MN10300 HAL cache macros can cause
		lockups.
Workaround:	Do not disable optimization when using the HAL cache macros.

PR19919
Host:		Windows
Problem:	The eCos Configuration Tool may generate an exception if a
		build is stopped while the configuration header files are being
		written.
Workaround:	Avoid stopping the build during this phase of the build
		process.

PR19921
Host:		Windows
Problem:	Problems may be encountered when using the eCos Configuration
		Tool to save eCos build trees with very long paths.
Workaround:	Limit the length of build tree paths if this problem is
		encountered.

PR19922
Host:		Windows
Problem:	eCos will not build correctly on a file system which has been
		mounted using the Cygwin binary mode.
Workaround:	Do not attempt to mount eCos-related file systems in binary
		mode.

PR19942
PR19947
Host:		All
Problem:	The protocol used for negotiating a new serial configuration
		in the eCos serial tests is not reliable when the host machine
		has a high load.
Workaround:	There is no known workaround. A new implementation is planned.

PR19961
Host:		Windows
Problem:	The eCos Configuration Tool may generate an exception if the
		user cancels the message box "Press OK when the target is reset
		ready for test download" when running tests.
Workaround:	Always respond 'OK' to this message box.

PR19976
Host:		Windows
Problem:	If the user halts the execution of a series of tests from the
		eCos Configuration Tool, the tool may be left in a state where
		it is unable to restart test execution.
Workaround:	Exit and restart the configuration tool.

PR19991
Target:		All
Problem:	There is an race condition in the eCos stress_threads test
		which can cause failures to be erroneously reported if the
		bitmap scheduler has been configured.
Workaround:	There is no known workaround.

PR20020
Target:		All
Problem:	Certain eCos tests do not start the scheduler and so interrupts
		are disabled. When run on hardware, these tests cannot be
		interrupted using Ctrl-C.
Workaround:	There is no workaround.


-------------------------------------------------------------------------------
GNU Compiler Tools for eCos 1.2.1 Known Problems
------------------------------------------------

PR17574
Host:		All
Problem:	Developer's Kit release only. The GDBTk target settings dialog
		can display the selected serial communication speed incorrectly
		when a radix other than 10 has been selected.
Workaround:	Avoid use of the 'set radix' command.

PR17614
Host:		All
Problem:	Developer's Kit release only. Mixing some operations between
		the GDBTk GUI and console window can cause problems.
Workaround:	Avoid use of the GDBTk console window where possible.

PR18007
Host:		All
Problem:	GDB cannot cope with executables whose absolute pathnames are
		longer than 128 characters. This is only a problem when gdb is
		used with hardware. The built in simulators are OK. The failure
		mode is that the application will download correctly, but then
		GDB terminates with an error.
Workaround:	Only attempt to run applications located in a path consisting
		of less than 128 characters.

PR18034
Host:		Windows
Problem:	The Windows hosted compiler must be provided with file
		extension when using the "-o" flag. If no extension is provided
		the compilation fails with an unrelated and misleading error.
Workaround:	Always specify an extension when using "-o"

PR18585
Host:		All
Problem:	GDB does not allow the value of variables of type 'bool' to be
		changed.
Workaround:	There is no known workaround.

PR18615
Host:		All
Problem:	GDB and GDBTk do not list/display inline functions correctly
		for object files which have been created without the gcc -O2
		flag.
Workaround:	Use the -O2 flag of gcc to create object files which call 
		inline functions.

PR18694
Host:		All
Problem:	GDB shows the code associated with a weak symbol when an
		alternative symbol definition has been provided.
Workaround:	The developer may comment out the weak definitions.

PR19388
PR19968
PR19970
PR19981
Target:		All
Problem:	Certain entries in a GDB backtrace may be incorrect and the
		backtrace may be incomplete. The nature of these errors
		is target-dependent.
Workaround:	There is no known workaround.

PR19560
Target:		SPARClite
Problem:	Output from eCos applications running in the SPARClite
		simulator is lost when running under GDBTk under Windows.
		Note that use of the SPARClite simulator is not supported
		by Cygnus.
Workaround:	There is no known workaround.

PR19727
Target:		SPARClite
Problem:	Developer's Kit release only. The SPARClite GDBTk appears to
		clear all breakpoints when an executable is run.
Workaround:	Wait until the executable is running before setting
		breakpoints or use command line gdb.

PR19885
Target:		TX39
Problem:	Setting $pc at the TX39 '(gdb)' prompt can cause GDB to core
		dump.
Workaround:	There is no known workaround.

PR19930
Target:		ARM
Problem:	Developer's Kit release only. Attempts to open the breakpoint
		window in ARM GDBTk can result in an "unknown option" warning
		message being displayed. This is harmless and can be ignored.
Workaround:	There is no known workaround.

PR19945
PR19946
Target:		PowerPC
Problem:	The PowerPC simulator does not correctly communicate certain
		exception conditions to GDB. This causes the eCos kexcept1,
		signal2 and except1 tests to fail.
Workaround:	There is no known workaround.

PR20015
Target:		SPARClite
Problem:	Developer's Kit release only. The 'stop' button on the GDBTk
		toolbar will not halt an application running in the SPARClite
		simulator. Note that use of the SPARClite simulator is not
		supported by Cygnus.
Workaround:	Open the GDBTk console window and type Ctrl-C to halt the
		application.


End of README
-------------------------------------------------------------------------------
