readme

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

	Console driver ports (0xFFFC0002 - 1 byte)
	  Set the following bits in the byte to select the console and printk ports:
	    bit 0 & 1 select the RTEMS console port
        00 - /dev/tty0, Serial Port 1/Console on the MVME712M.
        01 - /dev/tty1, Serial Port 2/TTY01 on the MVME712M.
        10 - /dev/tty2, Serial Port 3 on the MVME712M.
        11 - /dev/tty3, Serial Port 4 on the MVME712M.
	    bit 4 & 5 select the RTEMS printk port
        00 - /dev/tty0, Serial Port 1/Console on the MVME712M.
        01 - /dev/tty1, Serial Port 2/TTY01 on the MVME712M.
        10 - /dev/tty2, Serial Port 3 on the MVME712M.
        11 - /dev/tty3, Serial Port 4 on the MVME712M.
    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.
    
	IP Address (0xFFFC0004 - 4 bytes)
		write the hexadecimal representation of the IP address of the board in this
		locatio, e.g. 192.168.1.2 = 0xC0A80102
		default: obtain the IP address from an rtems_bsdnet_ifconfig structure

	Netmask (0xFFFC0008 - 4 bytes)
		write the hexadecimal representation of the netmask in this location
		for example, 255.255.255.0 = 0xFFFFFF00
		default: obtain the netmask from an rtems_bsdnet_ifconfig structure
		
	Ethernet Address (0xFFFC000C - 6 bytes)
		write the Ethernet address of the board in this location
		default: obtain the hardware address from an rtems_bsdnet_ifconfig
		         structure

	Processor ID (0xFFFC0012 - 2 bytes)
		reserved for future use
		
	RMA start (0xFFFC0014 - 4 bytes)
		reserved for future use
		
	VMA start (0xFFFC0018 - 4 bytes)
		reserved for future use
		
	RamSize (0xFFFC001C - 4 bytes)
		reserved for future use


Cache Control and Memory Mapping
--------------------------------

If configuration is not obtained from non-volatile RAM (ie. J1-4 is off),
cache control is done through the remaining J1 jumpers as follows:

If Jumper J1-7 is installed, the data cache will be turned on. If Jumper
J1-6 is installed, the instruction cache will be turned on. (If a jumper
is off, its corresponding cache will remain disabled).

If Jumper J1-5 is installed, the data cache will be placed in copyback
mode. If it is removed, it will be placed in writethrough mode.

Currently, block address translation is set up to map the virtual
0x00000000--0x7FFFFFFF to the physical range 0x00000000--0x7FFFFFFF. The
port relies on the hardware to raise exceptions when addressing
non-existent memory. Caching is not controllable on a finer grain.


Networking
----------

If configuration is not obtained from non-volatile RAM (ie. J1-4 is off),
the networking parameters shown above must be specified in an initialized
rtems_bsdnet_ifconfig struct. This structure is declared and initialized to
specify any network devices and includes entries for ip_address, ip_netmask
and hardware_address. See the Network Device Configuration section of the
RTEMS Networking Supplement.

When non-default (non-zero) networking paramaters are provided in NVRAM (ie.
j1-4 is on), the user MUST ensure that the corresponding entries in the
ifconfig struct are NULL. Failing to do so is an error, because it causes
the memory allocated for the initialized struct values to be lost.


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

The timer and clock drivers were patterned after the MVME162 and MVME152
ports.

At this time, we do not have an MPCI layer for the MVME167. We are planning
to write one.

This port supplies its own fatal_error_handler, which attempts to print some
error message through 167Bug (on the Serial Port 1/Console on the MVME712M).


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

The port was initially developed on an RS-6000 running AIX 4.2. The following
tools were used:

    - GNU gcc 2.8.1 configured for a powerpc-ibm-aix4.2.0.0 host and
      m68k-rtems target;
    - GNU binutils 2.9.1 configured for a powerpc-ibm-aix4.2.0.0 host and
      m68k-rtems target;

It was also tested on a Pentium II-based PC running Windows NT Workstation 4.0
and the Cygnus Cygwin32 release b20.1 environment, with the following tools:

    - EGCS 1.1.1 configured for a i586-cygwin32 host and m68k-rtems target;
    - GNU binutils 2.9.4 configured for a i586-cygwin32 host and m68k-rtems
      target;

With the latter environment, be patient; builds take a very looong time...

Current development is done on a Pentium III PC running RedHat Linux 6.1.
At the time this README was composed, the latest working compiler that was
used successfully was gcc version 2.96 20000213 (experimental). Both the C
and C++ compilers were working. Binutils 2.10 are used.


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

Polled I/O without termios may not work very well on input. The problem
is that input processing is not done: applications may get characters too
early, and may get characters that they normally would not get, such as
backspace or delete. Furthermore, input is not buffered at all. The latest
versions of rtems seem to set the count field in the rtems_libio_rw_args_t
argument to the buffer size, not to the number of characters expected on
input. Rather than wait for 1024 characters on each call, the driver
returns each character when it is received.

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.

Output stops prematurely in the termios test when the console is operating in
interrupt-driven mode because the serial port is re-initialized before all
characters in the last raw output buffer are sent. Adding calls to tcdrain()
in the test task helps, but it does not solve the problem. What happens is
that the CD2401 raises a transmit interrupt when the last character in the
DMA buffer is written into the transmit FIFO, not when the last character
has been transmitted. When tcdrain() returns, there might be up to 16
characters in the output FIFO. The call to tcsetattr() causes the serial port
to re-initialize, at which point the output FIFO is cleared. We could not find
a way to detect whether characters are still in the FIFO and to wait for them
to be transmitted.

The first raw buffer to be transmitted after the console is re-initialized
with tcsetattr() is garbled. At this time, it does not seem worth while to
track this problem down.

In the stackchk test, an access fault exception is raised after the stack is
blown. This is one case were overwritting the first or last 16 bytes of the
stack does cause problems (but hey, an exception occurred, which is better
than propagating the error).

In the stackchk test, an access fault exception is raised after the stack is
blown. This is one case were overwritting the first or last 16 bytes of the
stack does cause problems (but hey, an exception occurred, which is better
than propagating the error).

When using interrupt-driven I/O, psx08 produces all the expected output, but
it does not return control to 167Bug. Is this test supposed to work with
interrupt-driven console I/O?


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

Support for Java is being actively worked on.


Thanks
------

- to On-Line Applications Research Corporation (OAR) for developing
RTEMS and making it available on a Technology Transfer basis;

- to FSF and Cygnus Support for great free software;


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

Board:                Motorola MVME167
CPU:                  Motorola MC68040
Clock Speed:          25 MHz
RAM:                  4 MBytes of 32-bit DRAM with parity
Cache Configuration:  Instruction cache on; data cache on, copyback mode.
Times Reported in:    microseconds
Timer Source:         VMEchip2 Tick Timer 1
GCC Flags:            -m68040 -g -O4 -fomit-frame-pointer
Console:              Operate in polled mode. Set CD2401_POLLED_IO to 1 in
                      rtems/c/src/lib/libbsp/m68k/mvme167/console/console.c.     


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

Single processor tests:  All tests passed, except the following ones:

  - paranoia required the FPSP and the default variants of libm (and libc and
    libgcc) for us. It may work with the msoft-float variants for you, but it
    does require the FPSP.
  
  - 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 -- No MPCI layer yet.


Timing tests: See rtems/c/src/lib/libbsp/m68k/mvme167/times