			RBL Example Programs
			--------------------

This directory contains three example programs that show how
application code can use the RBL API. The first program, sertest,
operates over a serial line. The second program, nettest, uses TCP/IP
instead. The third program, transact, is intended primarily for
testing and demonstrates the use of the vector and transaction-based
update and load functions.


Building the Examples
---------------------

Usually the contents of this directory will be copied elsewhere, to
avoid polluting an eCos source repository with builds. The supplied
makefile should be edited, changing the INSTALL_DIR variable to point
at the install subdirectory of a suitable eCos build.

The sertest program is built using the source files sertest.c and
xyzModem.c. The latter file has been taken from the RedBoot sources,
with minor changes to allow it to be built independently from RedBoot.
The program assumes a default eCos configuration to which the RBL
(CYGPKG_RBL) and CRC (CYGPKG_CRC) packages have been added.

The nettest program is built using the nettest.c source file. It
assumes that eCos has been configured with TCP/IP functionality, which
usually involves creating a configuration with the net template. The
RBL package should then be added to this configuration.

Both programs assume that the target hardware has a suitable RedBoot
installation with RBL support. These programs are then programmed into
flash via the "rbl newcode" command, and run via "rbl boot" - either
manually or via a configured boot script. The makefile will generate
suitable stripped versions of the executables in addition to the
default ELF executables.


Running sertest
---------------

The sertest program runs over the default HAL diagnostics channel,
which will usually be a serial port. It is assumed that nothing else,
including gdb, is using this channel. The program allows users to
choose from a simple menu.

  sertest: built Nov 29 2003 17:34:19

    1) show flash details
    2) show flash blocks
    3) show rbl blocks
    4) show current data
    5) update code (ymodem upload)
    6) update data (ymodem upload)
    7) reset
    Action (1-7)?

The first three options provide some simple information on the flash
hardware available and how it is being used by the RBL code inside
RedBoot. The fourth option will display the current persistent data.
It is assumed that this will be a small amount of ascii text, and
suitable files data1 and data2 can be found in this directory.

Options 5 and 6 allow the user to install new versions of the code or
the persistent data. After selecting the menu option the user should
initiate a ymodem upload using whatever facilities are provided by the
terminal emulator being used. Once the new code or data has been
uploaded the program will update the appropriate flash blocks using
the RBL API.

The final option can be used to restart the hardware.


Running nettest
---------------

The nettest program provides two TCP/IP services. First it runs a
simple telnet daemon listening on the standard telnet port 23. The
user can connect to the target using any standard telnet client and
get information about the flash hardware and how it is being used by
the RBL code inside RedBoot. This corresponds to options 1 to 4 of the
sertest menu.

Second the program provides a tftp service. This allows users to
receive a file "data" containing the current persistent data. It is
also possible to send files "data" or "code" to perform an RBL update.
The exact details will depend on the tftp client being used, but a
typical invocation might look like:

$ tftp 10.1.1.135
tftp> binary
tftp> get data
tftp> put nettest.strip code
tftp> quit
$

This will retrieve the current persistent data, saving it to a file
"data" in the current directory. It will then upload the stripped
executable "nettest.strip" to a remote file "code". At the end of the
transfer the flash will be updated.


Running transact
----------------

The transact program is intended to be debugged as an ordinary eCos
testcase using gdb over a serial line or ethernet. It assumes that
there are already valid code and data images programmed into flash.
Both images should occupy several flash blocks. The test simply
performs a number of data loads and code and data updates based on
these existing images, and leaves the flash still containing valid
images. There is no user interaction and at the end of the run the
code will cyg_test_exit() like any other eCos testcase.

