readme

RTEMS (Real-Time Executive for Multiprocessor Systems) is a free open source real-time operating sys

initialized. Consequently, to debug startup code using printk prior to the
initialization of the serial driver, use mode 2: polled I/O through EPPC-Bug,
and read the next section.


EPPC-Bug and I/O
----------------

IMPORTANT: When using EPPC-Bug 1.1 for polled I/O, only the SMC1 port is
usable. This is a deficiency of the firmware which may be fixed in later
revision. When using this monitor with UARTS_IO_MODE set to 2, CONSOLE_MINOR
must be set to SMC1_MINOR. Similarly, if PRINTK_IO_MODE set to 2,
PRINTK_MINOR must be set to SMC1_MINOR. When UARTS_IO_MODE is set to 2,
only SMC1 is usable.

Be warned that when EPPC-Bug does I/O through a serial port, all interrupts
get turned off in the SIMASK register! This is a definite bug in release 1.1
of the firmware. It may have been fixed in later releases. EPPB-Bug does
I/O through its debug port whenever it is given control, e.g. after a
breakpoint is hit, not just when it is used to perform polled I/O on behalf
of RTEMS applications. In particular, in our configuration, we have gdb
communication with EPPC-Bug through SMC1.

To solve this problem, whenever the BSP manipulates the SIMASK, it makes a
copy of the written value in a global variable called 'simask_copy'. That
value must be restored by GDB before execution resumes. The following commands
placed in the .gdbinit file takes care of this:

# GDB Initialization file for EPPC-Bug.

define hook-stepi
set language c
set *(int *)0xFA200014=simask_copy
set language auto
end

define hook-step
set language c
set *(int *)0xFA200014=simask_copy
set language auto
end

define hook-continue
set language c
set *(int *)0xFA200014=simask_copy
set language auto
end

define hook-nexti
set language c
set *(int *)0xFA200014=simask_copy
set language auto
end

define hook-next
set language c
set *(int *)0xFA200014=simask_copy
set language auto
end

define hook-finish
set language c
set *(int *)0xFA200014=simask_copy
set language auto
end

IMPORTANT: When using EPPC-Bug on SMC1, either for debugging or for polled I/O,
EPPCBUG_SMC1 must be defined in rtems/make/custom/mbx8xx.cfg, or the eppc_bug
field set to non-zero in NVRAM. Defining this constant prevents the device
driver from re-initializing SMC1. It also causes the network driver, the clock
driver, and the asynchronous serial line driver to maintain simask_copy for use
by gdb.

Polled I/O through EPPC-Bug is pretty funky... If your are old enough, it might
bring back fond memories of the days of 300 baud modems. If not, you can
experience for yourself what the state of the art used to be.


Floating-point
--------------

The MPC860 and MPC821 do not have floating-point units. All code should
get compiled with the appropriate -mcpu flag. The nof variants of the gcc
runtime libraries should be used for linking.


Configuration Parameters
------------------------

If NVRAM_CONFIGURE is set in rtems/make/custom/mbx8xx.cfg, certain
configuration parameters will be read from the first 31 bytes of the  NVRAM
User Area, which starts at 0xFA001000. The user is responsible for writing
the appropriate values in NVRAM (via EPPC-Bug). The paramaters
that are configurable and their default settings are described below. 
		
  Cache Mode (0xFA001000 - 1 byte)
    Set the following bits in the byte to control the caches:
      bit 0
        0 - data cache disable
        1 - data cache enable
      bit 1
        0 - instruction cache disable
        1 - instruction cache enable
    If enabled, all of RAM except for the last 512 KB will be cached using
    copyback mode. The last 512 KB of RAMis for the use of EPPC-Bug.
    
  Console driver I/O mode (0xFA001001 - 1 byte)
    Set the following bits in the byte to set the desired I/O mode
    for the rtems ports:
      bit 0
        0 - do not use termios
        1 - use termios
      bit 2 & 1
        00 - polled I/O through RTEMS driver
        01 - interrupt-driven I/O
	10 - polled I/O through EPPC-Bug
    Set the following bits in the byte to set the desired I/O mode
    for printk:
      bit 5 & 4
        00 - polled I/O through RTEMS driver
        01 - polled I/O through RTEMS driver
	10 - polled I/O through EPPC-Bug

  Console driver ports (0xFA001002 - 1 byte)
    Set the following bits in the byte to select the console and printk ports:
    bit 2, 1  & 0 select the RTEMS console port
        000 - /dev/tty0, SMC1
        001 - /dev/tty1, SMC2
        011 - /dev/tty2, SCC2
        100 - /dev/tty3, SCC3
        101 - /dev/tty4, SCC4
    bit 6, 5 & 4 select the RTEMS printk port
        000 - /dev/tty0, SMC1
        001 - /dev/tty1, SMC2
        011 - /dev/tty2, SCC2
        100 - /dev/tty3, SCC3
        101 - /dev/tty4, SCC4
  If the printk port is the same as some other port that will be opened by an
  RTEMS application, then the driver must use polled I/O, or the printk port
  must not be used.

  EPPC-Bug in use on SMC1 (0xFA001003 - 1 byte)
    Set to non-zero to indicate that EPPC-Bug is using SMC1. This will prevent
    the SMC1 port from being re-initialized.

  IP Address (0xFA001004 - 4 bytes)
    Write the hexadecimal representation of the IP address of the board in this
    location, e.g. 192.168.1.2 = 0xC0A80102

  Netmask (0xFA001008 - 4 bytes)
    Write the hexadecimal representation of the netmask in this location
    for example, 255.255.255.0 = 0xFFFFFF00

  Ethernet Address (0xFA00100C - 6 bytes)
    Write the Ethernet address of the board in this location

  Processor ID (0xFA001012 - 2 bytes)
    Reserved for future use
		
  RMA start (0xFA001014 - 4 bytes)
    Reserved for future use
		
  VMA start (0xFA001018 - 4 bytes)
    Reserved for future use
		
  RamSize (0xFA00101C - 4 bytes)
    Reserved for future use


Miscellaneous
-------------

All development was based on the eth_comm port.


Host System
-----------

The port was developed on Pentiums II and III running RedHat Linux 6.0 and
6.1. The following tools were used:

    - GNU gcc snapshot dated 20000214 configured for powerpc-rtems;
    - GNU binutils 2.10 configured for powerpc-rtems;

Gcc 2.95.2 also worked. Gcc 2.95.1 will not compile the console driver with
-O4 or -O3. Compile it manually with -O2.


Known Problems
--------------

The cdtest will not run with interrupt-driven I/O. The reason is that the
constructors for the static objects are called at boot time when the
interrupts are still disabled. The output buffer fills up, but never empties,
and the application goes into an infinite loop waiting for buffer space. This
should have been documented in the rtems/c/src/tests/PROBLEMS file. The moral
of this story is: do not do I/O from the constructors or destructors of static
objects.

When using interrupt-driven I/O, psx08 fails with an internal assertion error.


What is new
----------

All known problems with use of the caches on the MBX860-002 and MBX821-001
have been resolved.

Configuration of the console and network is now possible at boot time through
NVRAM parameters.


Thanks
------

- to Jay Monkman ([e-mail]) of Frasca International, Inc.
  for his eth_comm port.
  
- to On-Line Applications Research Corporation (OAR) for developing
  RTEMS and making it available on a Technology Transfer basis;

- to the FSF and to Cygnus Support for great free software;


Test Configuration
------------------

Board:                MBX821-001, MBX860-002
CPU:                  Motorola MPC821, MPC860
Clock Speed:          50 MHz, 40 MHz
RAM:                  4 MBytes of 32-bit DRAM
Cache Configuration:  Instruction cache on; data cache on, copyback mode.
Times Reported in:    clock ticks: TMBCLK = system clock / 16.
Timer Source:         Timebase clock
GCC Flags:            -O4 -fno-keep-inline-functions -mcpu=(821/860) 
Console:              Operates in polled mode on SMC2. No I/O through EPPC-Bug.    


Test Results
------------

Single processor tests:  All tests passed, except the following ones:
  
  - cpuuse and malloctest did not work.
  
  - The stackchk test got an access fault exception before the RTEMS stack
    checker had had a chance to detect the corrupted stack.
                         
                         
Multi-processort tests:  not applicable.


Timing tests:
	See the times-mbx821 and times-mbx860 files for the results of the
	timing tests.


Network tests:
       Worked.