readme

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

#
#  $Id: README,v 1.6 2000/08/11 19:26:31 joel Exp $
#

This is a README file for the MVME167 port of RTEMS 4.5.0.

Please send any comments, improvements, or bug reports to:

Charles-Antoine Gauthier
[e-mail]

or

Darlene Stewart
[e-mail]
  
Software Engineering Group
Institute for Information Technology
National Research Council of Canada
Ottawa, ON, K1A 0R6
Canada


Disclaimer
----------

The National Research Council of Canada is distributing this RTEMS
board support package for the Motorola MVME167 as free software; you
can redistribute it and/or modify it under terms of the GNU General
Public License as published by the Free Software Foundation; either
version 2, or (at your option) any later version.  This software is
distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details. You should have received a copy of the GNU General
Public License along with RTEMS; see file COPYING. If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

Under no circumstances will the National Research Council of Canada
nor Her Majesty the Queen in right of Canada assume any liablility
for the use this software, nor any responsibility for its quality or
its support.


Installation
------------

Nothing unique to the MVME167. It uses the standard build process for
m68k targets. You will need to edit linkcmds to put in the start address
of your board. We do TFTP transfers to our target. The mvme167.cfg file
builds only the ELF images, which we download to the target, skipping
over the first 0x54 bytes; Motorola S-records are not generated. Edit
this file if you want S-records.


Port Description

Console driver
---------------

This BSP includes an termios-capable interrupt-driven I/O console driver
that supports all four serial ports on the MVME167 model. The port labelled
Serial Port 1/Console on the MVME712 is normally used by 167Bug; do not open
/dev/tty00 if you are debugging using 167Bug.

Limited support is provided for polled terminal I/O. This is used when
running the timing tests, and by the printk() debug output function.
Polled I/O may use termios, or it may bypass those services. The printk()
function does not use termios. When polled I/O is used, the terminal settings
must be set through 167-Bug; trying to change the line settings through RTEMS
has no effect.

Three is no support for using interrupt-driven I/O without termios support.

The default configuration is to use polled I/O and to bypass termios. This
is done so the test can be built at the same time as the rest of the system.
It is highly recommended that the defaults be changed in the mvme167.cfg file
to reflect the desired defaults, or that the appropriate parameters be set up
in NVRAM to select the appropriate I/O modes at boot time.

When configured for interrupt-driven I/O, the console is initialized with
whatever parameters are set up in termios before it calls the firtOpen driver
callback, EXCEPT THAT HARDWARE HANDSHAKING IS TURNED OFF, i.e. CLOCAL is set
in the struct termios c_cflag field. We use 3-wire cables for I/O, and find
hardware handshaking a pain. If you enable hardware handshaking, you must drive
CTS* low on the CD2401 for output to occur. If the port is in the DTE
configuration, you must drive the RS-232 CTS line to space; if the port is
in the DCE configuration, you must drive the RS-232 RTS line to space.

To use interrupt-driven I/O, set the CD2401_IO_MODE manifest constant to 1 in
rtems/make/custom/mvme167.cfg, or configure the appropriate parameter in
User Area Non-volatile RAM. See the Configuration Parameters section below
for instructions on setting up NVRAM.

To use termios, set the CD2401_USE_TERMIOS manifest constant to 1 in
rtems/make/custom/mvme167.cfg, or configure the appropriate parameter in
User Area Non-volatile RAM. See the Configuration Parameters section
below for instructions on setting up NVRAM.

The RTEMS console, i.e. the port used by stdin, stdout and stderr (do not
confuse it with the port labelled Console on the MVME712), must be
specified in the rtems/make/custom/mvme167.cfg file, or in the NVRAM
parameters. Set the value of CONSOLE_MINOR appropriately. See below for a
list of choices. See the Configuration Parameters section below for
instructions on setting up NVRAM.

The RTEMS printk port, i.e. the port where printk sends it debugging output
text, must be specified in the rtems/make/custom/mvme167.cfg file, or in the
NVRAM parameters. Set the value of PRINTK_MINOR appropriately. See below for a
list of choices. See the Configuration Parameters section below for
instructions on setting up NVRAM.

Interrupt-driven and polled I/O cannot be mixed in the MVME167, except that
printk always used polled I/O without termios. If interrupt-driven I/O is
used and printk is used, do not open the device that printk uses from an
RTEMS application.

Console and printk port choices:

  0 - /dev/tty0, Serial Port 1/Console on the MVME712M.
  1 - /dev/tty1, Serial Port 2/TTY01 on the MVME712M.
  2 - /dev/tty2, Serial Port 3 on the MVME712M.
  3 - /dev/tty3, Serial Port 4 on the MVME712M.

Setting the RTEMS console to port 0 when interrupt-driven I/O is specified
will prevent 167-Bug from using that port.

To use polled I/O on port 2 or 3, the port must be configured in 167-Bug. See
the "PF" command in the "Debugging Package for Motorola 68K CISC CPUs User's
Manual", part number 68KBUG.


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

The MC68040 has a built-in FPU. This FPU does not implement all the
instruction of the MC68881/MC68882 floating-point coprocessors in
hardware. The -m68040 compilation options instructs gcc to not generate
the missing instructions. All of the RTEMS code is built this way. Some
of the missing functionality must be supplied by external libraries. The
required functions are part of libgcc.a.

The issue gets complicated because libc, libm and libgcc do not come as
m68040-specific variants. The default variants of these libraries are for the
MC68020 and MC68030. There are specific variants for the MC68000 (which has
limited addressing modes with respect to later family members), and specific
variants for systems without a floating-point unit, either a built-in FPU or
a coprocessor. These latter variants will be referred to as the msoft-float
variants. There is a msoft-float variant for the MC68000, and one for the
other family members.

The default variants of libc, libm and libgcc appear to work just fine for the
MC68040, AS LONG AS NO FLOATING POINT FUNCTIONS ARE CALLED. In particular,
printf() and scanf() raise unimplemented floating-point instruction exceptions
at run time. Expect almost every function that must compute a floating-point
result to also raise unimplemented floating-point instruction exceptions. Do
not use these variants if your application does any floating-point operations,
unless you use the Motorola FPSP package (described further down).

The msoft-float variants do print out floating-point numbers properly, but we
have not tested them extensively, so use them with caution. In particular,
the Paranoia test fails when linked with the msoft-float variants of the
libraries; it goes into an infinite loop after milestone 40.

MSOFT_FLOAT VARIANTS MUST BE USED TOGETHER. If you use the msoft-float variant
of libc and libm, you must also linked with the msoft-float variant of libgcc,
otherwise calls such as printf() print out floating-point values incorrectly.

RTEMS comes with the Motorola FPSP (Floating-Point Support Package) for the
MC68040 (rtems/c/src/lib/libcp/m68k/m68040/fpsp). This package emulates the
missing floating-point instructions. It is built automatically for the
MVME167 and installed in bsp_start().

The FPSP allows the use of the default variants of libc, libm and libgcc.
It also runs the paranoia test properly, and prints out the correct results.
It should probably be used in preference to the msoft-float libraries, as it
appears to work better. The disadvantage of the FPSP is that it increases the
size of the executable by about 60KB and that it relies on run time
exceptions.

If your application does not do any floating-point operations at all, you
should consider disabling the FPSP. In bsp_start(), emove the call to
M68KFPSPInstallExceptionHandlers(), and uncomment the three lines in
mvme167.cfg that redefine which variants of libc, libm and libgcc to link
against.


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

If Jumper J1-4 is installed, certain configuration parameters may be read from
the first 31 bytes of User Area NVRAM starting at 0xFFFC0000. In this case, the
remaining J1-[5-7] jumpers are ignored, and the user is responsible for writing
the appropriate values in NVRAM (via 167-Bug) in order to alter the default
behaviour. A zero value in NVRAM results in the default behaviour. The paramaters
that are configurable and their default settings are described below. 
		
	Cache Mode (0xFFFC0000 - 1 byte)
	  Set the following bits in the byte to set the desired cache mode:
	    bit 0
	      0 - data cache disable
	      1 - data cache enable
	    bit 1
	      0 - instruction cache disable
	      1 - instruction cache enable
	    bits 2 & 3:
		    00 = cachable, write-through
		    01 = cachable, copyback
		    10 = noncachable, serialized
		    11 = noncachable

	Console driver I/O mode (0xFFFC0001 - 1 byte)
	  Set the following bits in the byte to set the desired I/O mode:
	    bit 0
	      0 - do not use termios
	      1 - use termios
	    bit 1
	      0 - polled I/O
	      1 - interrupt-driven I/O