eCos - the Embedded Configurable Operating System - release 1.3.1 README
========================================================================

March 2000


Welcome to the eCos 1.3.1 public net release.


This README contains a detailed list of known problems with the
eCos 1.3.1 release. At the bottom of the README is a short list of
host and target specific notes.


-----------------------------------------------------------------------------
eCos 1.3.1 Errata
-----------------

This errata details problems found as a result of QA testing. These problems
will be resolved in forthcoming releases of eCos and its associated tools. 

Please note that each problem is identified with a problem ID -
PRxxxxx, or CRxxxxxx. Older problems have been logged using the PRMS
system (PRxxxxx), and more recent problems using the support
management system (CRxxxxxx).

-----------------------------------------------------------------------------
eCos 1.3.1 Documentation Errata
-------------------------------

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

PR19871
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:
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.

PR20024
Problem:        The eCos serial filter tool (ser_filter) is not
                documented in the manuals.
Workaround:     Refer to the file packages/io/serial/<version>/tests/README
                under the base of the eCos installation for details of
                this tool.

CR100880
Target:         ARM, SH, PowerPC
Problem:        The prebuilt test, thread_gdb, does not contain the
                GDB stubs, which means that C-c does not work as
                described in the Running Applications on the Target chapter.
Workaround:     Set breakpoint on cyg_test_exit before starting the test.



-----------------------------------------------------------------------------
eCos 1.3.1 Known Problems
-------------------------

The following problems were found in the final stages of QA testing
for this release. These problems will be resolved in forthcoming
releases of eCos.

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.

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.

PR19822
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.

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.

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


CR100885
Target:         PowerPC/QUICC
Problem:        Serial driver cannot reliably change baud rate on the
                fly as is required in the serial4 test.
Workaround:     There is no workaround.


CR101058
Target:         All
Problem:        Control-C only interrupts a running program when the
                program prints output using the HAL diagnostic output,
                when device drivers are enabled.
                The problem is that device drivers install their own
                serial ISR which replaces the one used normally to
                process Ctrl-C.  
Workaround:     Disable device driver support, or force the program to use
                the diagnostic output when required.

CR101059
Target:         All
Problem:        Kernel exceptions fail to be delivered when GDB stubs
                are included. This causes the except1 and kexcept1
                tests to fail.
Workaround:     Do not enable the "Include GDB stubs" option if the
                program uses kernel exceptions.

CR101393
Targer:         All
Problem:        Libc malloc does not use all available memory on
                target.
Workaround:     Manually set malloc memory pool as large as required
                (CYGNUM_LIBC_MALLOC_MEMPOOL_SIZE).

PR20223
CR901428
Targets:        ARM9, CMA230, EBSA285, EDB7xxx
Problem:        k/except1 and signal2 tests do not succeed in
                generating bad alignment exceptions.
Workaround:     There is no known workaround.

CR902157
Host:           All
Problem:        Changing compiler flags with either the eCos Configuration
                Tool or by editing the ecos.ecc save file does not result in
                automatic rebuild of all affected files.
Workaround:     Delete all object files with 'make clean'.

CR902158
Host:           All
Problem:        Deleting object files in the build tree does not cause
                them to be rebuilt.
Workaround:     Delete the dependency file (.d) to force a rebuild.

CR902226
Target:         ARM
Problem:        CygMon does not handle breakpoints after the
                application starts to execute.
Workaround:     Use eCos GDB stubs instead of CygMon in the ROM/FLASH,
                or include GDB stubs support when configuring eCos for
                the application.

CR902232
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.

CR902250
Target:         ARM AEB Revision C
Problem:        Enabling the CPU cache causes random failures
Workaround:     As a temporary measure, the CPU cache is not enabled by
                default for the AEB Rev C.
                

CR902255
Host:           Windows
Problem:        eCos Config and Package Admin Tools may not have the correct
                installation path if you re-install eCos in a different
                location.  The paths to the Build and User tools may also be
                incorrect in the Config Tool.
Workaround:     On startup, the eCos Config tool will prompt you for the
                path to the packages directory within eCos (e.g.
                D:\Red Hat\eCos\packages) and the Package Admin Tool will
                prompt you for the ecos.db file (e.g.
                D:\Red Hat\eCos\packages\ecos.db).

                To correct the paths for the Build tools, in the Config Tool
                select "Tools->Paths->Build Tools" and enter the correct
                path (e.g.
                D:\Red Hat\eCos\ecos-99r1-991015\H-i686-cygwin32\bin) and
                for the User tools select "Tools->Paths->User Tools" and
                enter the correct path (e.g.
                D:\cygnus\gnupro\i686-cygwin32\
                i686-cygwin32\unsupported-990805\H-i686-cygwin32\bin).

CR902263
Target:         Various
Problem:        Some targets use the same architecture or platform HAL, but
                with different options. Prebuilts are only provided
                for the target's default configuration.
Workaround:     You will have to build tests for the target yourself
                in order to verify that GDB communicates properly with
                the target.

CR902538
Target:         ARM PID Thumb
Problem:        Enabling GDB break support causes the kernel to fail
                with ramdom memory corruption.
Workaround:     Do not enable GDB BREAK support in this release.
                The next CVS snapshot will contain a fix for this problem.

CR902540
Host:           Windows
Problem:        Viewing [headers] with "associated viewer" in the
                Configuration Tool does not work.
Workaround:     Specify the viewer as "use this viewer".  Problems have
                been observed using WordPad to view headers.  Notepad
                seems reliable.

CR902543
Target:         i386/PC
Problem:        HAL requires the kernel package.
Workaround:     Do not disable the kernel package. This will be fixed
                in the first CVS snapshot.

CR902544
Target:         i386/PC
Problem:        Interrupt chaining is not supported in this beta release of
                the i386/PC HAL. Enabling it will cause a compiler error.
Workaround:     Do not enable interrupt chaining.

CR902545
Target:         Various
Problem:        uItron testintr test may cause unwarranted failures
                due to a synchronization problem.
Workaround:     Disregard "No second tick" failures.


Problem:        Do not enable CYGDBG_USE_TRACING since it causes a
                compilation error.  This error is due to a change in the type
                specification used by the compiler for the
                __PRETTY_FUNCTION__ macro. It is now defined to be
                const char * where it used to be simply char *. This results
                in a type mismatch for one of the tracing system functions. A
                patch for this will be forthcoming.

-----------------------------------------------------------------------------
Tools for eCos 1.3.1 Known Problems
-----------------------------------

The following problems were found in the final stages of QA testing
for this release. These problems will be resolved in forthcoming
releases of the tools.

PR17574
Host:           All
Problem:        The Insight 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:        Mixing some operations between the Insight GUI and
                console window can cause problems. 
Workaround:     Avoid use of the Insight 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.

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 Insight 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 debug 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
PR19970
PR19981
CR101030
Targets:        ARM, MIPS, MN10300
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:     For ARM, using the option -mno-sched-prolog can improve
                matters in some cases. Other than that, the only workaround
                is to compile at a lower optimization level such as -O1.

PR19978
Host:           All
Problem:        Sometimes the download progress dialog is not opened
                when starting a download in Insight.
Workaround:     Download progress is shown in the main window's
                status bar.

PR19980
Host:           All
Problem:        The dots identifying breakpoints sometimes change
                color from pink (thread-breakpoint) to red (global
                breakpoint).
Workaround:     The tooltip displayed when the pointer is moved over
                a breakpoint dot shows if the breakpoint is
                thread-specific or global.

PR20402
Target:         PowerPC Sim
Problem:        Simulator fails with "events.c:165: assertion failed -
                (events->time_from_event >= 0) == (events->queue !=
                NULL)"
Workaround:     There is no known workaround.

CR100877
Target:         PowerPC
Problem:        The list of threads presented in Insight when setting a
                thread-specific breakpoint may contain garbage
                ASCII strings from the GDB protocol.
Workaround:     This does not happen when using the 'info thread' or
                Thread List window. Use these to find the thread
                number and use the GDB CLI console to set the
                thread-specific breakpoints.

CR100881
Host:           All
Problem:        Insight's Download Progress window doesn't
                reset the progress bars if it is left open after an
                earlier download.
Workaround:     Close the Download Progress window before starting a new
                download.

CR100886
Host:           All
Problem:        Insight has bad performance when doing many operations
                on threads. This is because the complete thread state of all
                threads is transferred from the target every time the target
                stops.
Workaround:     Close unnecessary windows in Insight so that Insight
                does not need to update as much information when the target
                stops.

CR100914
Host:           All
Problem:        Insight reports "DOWNLOAD CANCELLED" even after a
                successful download.
Workaround:     Ignore this message.

CR101035
Host:           Windows
Problem:        Ctrl-C fails to work as expected inside a "bash"
                shell. If GDB is used in command-line mode, sometimes
                both it and the bash shell will receive the Ctrl-C. In
                other cases, if programs are run in the background in
                a bash shell, and Ctrl-C is pressed, then those
                programs will be terminated as well.
Workaround:     Use GDB in graphical mode (Insight) and use the
                "console" window to control GDB. Alternatively start
                GDB from within a normal "Command Prompt" window,
                setting the path up in the same way as the develop.bat
                file in the eCos installation directory. For other
                programs, there is no known workaround.

CR101036
Host:           All
Problem:        GDB can lose track of what breakpoints are installed
                when per-thread breakpoints are used with eCos. It
                reports hitting a "SIGTRAP Trace/Breakpoint trap",
                instead of just reporting a breakpoint.
                This problem only appears rarely.
Workaround:     Ignore the extra traps and just continue anyway.

CR101293
Problem:        If asked to show the thread list after hitting a
                breakpoint in a function with varargs/string inputs
                which are long, Insight may hang.
Workaround:     If you experience this problem, use the CLI 'info
                threads' command instead of the thread list window.

CR902240
Host:           Windows
Problem:        Control-C used in GDB CLI mode also affects bash, 
                causing further input to randomly be read by either
                GDB or bash.
Workaround:     The problem does not occur when launching GDB from a
                DOS command prompt.

CR902267
Problem:        When running an application which produces large amounts
                of output, selecting "q <return>" when presented with 
                the prompt:
                  ---Type <return> to continue, or q <return> to quit---
                gdb will hang if you select "q <return>" and then try to
                exit gdb, reattach to the target, or other various gdb
                operations.
Workaround:     Do not select "q <return>".  Instead select "<return>"
                and press ^C to halt the application. Alternatively, remove
                the prompts with the GDB command "set height 0".

-----------------------------------------------------------------------------
                       Host and target specific notes
-----------------------------------------------------------------------------

--------------------------------------------------------------------------
DRAM Refresh on Cirrus Logic EP7211 and EP7212 Development Boards
-----------------------------------------------------------------

The current revision of the Cirrus Logic EP7211 (rev C) and EP7212 (rev C)
do not properly perform DRAM refresh cycles when the CPU is running at high
clock speeds (>37MHz).  When configured for this speed, over time the
contents of DRAM will change. The changes are unpredictable, depending upon
current access patterns and other factors.

The eCos kernel offers a workaround for this problem. By default if the
processor clock is set above 37Mhz a small loop is inserted as part of the
normal system timer processing. This adds approximately 250us overhead to
the timer processing every 10ms (in other words about 2%).

As an alternative workaround, configuring the CPU to run at 37Mhz or lower
will cause the DRAM refresh to work correctly. This can be controlled
with the HAL configuration option titled "Processor clock rate" (also
known as CYGHWR_HAL_ARM_EDB7XXX_PROCESSOR_CLOCK).

This problem will be fixed in future CPU revisions.


--------------------------------------------------------------------------
Building ser_filter using VC++
------------------------------

In order to build ser_filter under VC++, logical drive V: must
exist. This can be created using the 'subst' command:

DOS> subst V: C:\Temp

This drive is used for the build directories.

--------------------------------------------------------------------------
PID board and ROM-startups in big-endian mode
---------------------------------------------

 When programming the FLASH with big-endian application or stub there
 are two options:

  1) Program FLASH using the little-endian FLASH tool. After powering
     off, replace the ROM controller with the special big-endian
     version which can be acquired from ARM. (This has not been tested
     by Red Hat)

  2) Use a special big-endian version of the FLASH tool which
     byte-swaps all the words as they are written to the FLASH.

     Build this tool by enabling the "Build flash programming tool for
     BE images on LE boards" option (CYGBLD_BUILD_FLASH_TOOL_BE),
     resulting in a utility with the prefix
     "prog_flash_BE_image_LE_system" which should be used instead of
     "prog_flash".

     Note that there is a limitation to this method: no sub-word data
     can be read from the ROM. To work around this, the .rodata
     section is folded into the .data section and thus copied to RAM
     before the system starts.

     Given that Thumb instructions are 16 bit, it is not possible to
     run ROM-startup Thumb binaries on the PID board using this
     method.

--------------------------------------------------------------------------
SPARClite simulator
-------------------

When using the default template, conflicts are reported that, when
resolved, result in libc standard I/O being disabled. This is because
serial device drivers (including the pseudo-device driver to the HAL
diagnostic channel) are not included.

This can be fixed by editing the ecos.db file. Find the following
entry:

target sparclite_sim {
        alias           { "SPARClite simulator" sl_sim sparcl_sim }
        packages        { CYGPKG_HAL_SPARCLITE CYGPKG_HAL_SPARCLITE_SIM }
        description "
            The sparclite_sim target provides the packages need to run eCos
            on the SPARClite simulator."
} 

and add CYGPKG_IO_SERIAL to the packages line.

This problem will be fixed in the next CVS snapshot.


--------------------------------------------------------------------------
i386 Architecture
-----------------

A subtle runtime problem found very late in the QA testing was fixed in the
release. Unfortunately the fix causes compilation to fail when building eCos
with assertions enabled, i.e. when the options CYGPKG_INFRA_DEBUG and
CYGDBG_USE_ASSERTS are enabled.

A patch for these simple compile errors will be available off the problem list
page on sourceware.cygnus.com. Please see
http://sourceware.cygnus.com/ecos/problemlist.html

These problems will be fixed in the next CVS snapshot.


--------------------------------------------------------------------------
i386 PC
-------

When starting a new configuration for this target, there are CDL
conflicts in the default case. This should not happen as all targets,
by default, should be conflict-free.

If you are using the graphical Configuration Tool, simply accept all
changes when prompted. If using the command-line ecosconfig tool, then
run "ecosconfig resolve". As always, it is advised to use "ecosconfig
check" to verify the validity of your configuration.

--------------------------------------------------------------------------
Linux Synthetic Target
----------------------

Problem 1:

The synthetic target is set to use tools with a prefix of
"i686-pc-linux-gnu-". However, when building tools for the host, the
installed binaries will not be given a prefix. To work around this
problem, set the option CYGBLD_COMMAND_PREFIX to "" when making an
eCos configuration.


Problem 2:

Instruction stepping in recent versions of GDB, using the 'stepi' (or
`si') command is not possible by default in the linux synthetic
target. The reason is that the alarm signals used to drive the eCos
"clock" interfere with the debugging system.

As a workaround, you can disable the configuration option "Use Linux
real-time timer" (CYGSEM_HAL_I386_LINUX_REAL_TIME). This will use the
virtual timer instead of the real-time timer. Unfortunately this may
lead to slightly different timing behaviour.

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