rtems/c/src/lib/libbsp/m68k/mvme167/README

#
#  $Id$
#

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

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

Charles-Antoine Gauthier
Software Engineering Group
Institute for Information Technology
National Research Council of Canada
Ottawa, ON, K1A 0R6
Canada

charles.gauthier@iit.nrc.ca
  

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 coff images, which we download to the target, skipping over
the first 0xA8 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 console driver that supports all
four serial ports on the MVME167 model. The RTEMS console, /dev/console,
corresponds to channel 1 in the CD2401. This corresponds to Serial Port
2/TTY01 on the MVME712M. Serial Port 1/Console is normally used by 167Bug;
do not open /dev/tty00 if you are debugging using 167Bug.

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.

Limited support is provided for polled terminal I/O. This is used when running
the timing tests. Set the CD2401_POLLED_IO manifest constant to 1 in
rtems/c/src/lib/libbsp/m68k/mvme167/console/console.c to enable polled I/O.
In this case, I/O is done through 167Bug, usually to the Serial Port 1/Console

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.


Miscellaneous

port. Interrupt-driven and polled I/O cannot be mixed in the MVME167.

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.

The port does not have a network driver.

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, witht he 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;
    - Cygnus newlib 1.8.0 with RTEMS 4.0.0 patches.

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

    - Cygnus newlib 1.8.0 with RTEMS 4.0.0 patches.


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.

The cpuuse and malloctest tests do not work properly, either with polled I/O
or interrupt-driven I/O. They are known not to work with interrupt-driven I/O,
but should work with polled I/O?

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

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's new
----------


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:

	Context Switch

    context switch: no floating point contexts 12
    context switch: self 3
    context switch: to another task 3
    fp context switch: restore 1st FP task 14
    fp context switch: save idle, restore initialized 5
    fp context switch: save idle, restore idle 15
    fp context switch: save initialized, restore initialized 5
    
    
  Miscellaneous
  
    _ISR_Disable 1
    _ISR_Flash 0
    _ISR_Enable 0
    
    _Thread_Disable_dispatch 0
    _Thread_Enable_dispatch 3
    _Thread_Set_state 9
    _Thread_Disptach (NO FP) 16
    _Thread_Resume 6
    _Thread_Unblock 4
    _Thread_Ready 6
    _Thread_Get 3
    _Thread_Get: invalid id 0
    
    _Semaphore_Get 2


	Task Manager

    rtems_task_create 56
    rtems_task_ident 106
    rtems_task_start 21
    rtems_task_restart: calling task 24
    rtems_task_restart: suspended task -- returns to caller 27
    rtems_task_restart: blocked task -- returns to caller 36
    rtems_task_restart: ready task -- returns to caller 27
    rtems_task_restart: suspended task -- preempts caller 40
    rtems_task_restart: blocked task -- preempts caller 51
    rtems_task_restart: ready task -- preempts caller 52
    rtems_task_delete: calling task 67
    rtems_task_delete: suspended task 52
    rtems_task_delete: blocked task 54
    rtems_task_delete: ready task 54
    rtems_task_suspend: calling task 23
    rtems_task_suspend: returns to caller 12
    rtems_task_resume: task readied -- returns to caller 13
    rtems_task_resume: task readied -- preempts caller 22
    rtems_task_set_priority: obtain current priority 8
    rtems_task_set_priority: returns to caller 16
    rtems_task_set_priority: preempts caller 34
    rtems_task_mode: obtain current mode 4
    rtems_task_mode: no reschedule 5
    rtems_task_mode: reschedule -- returns to caller 12
    rtems_task_mode: reschedule -- preempts caller 26
    rtems_task_get_note 8
    rtems_task_set_note 8
    rtems_task_wake_after: yield -- returns to caller 4
    rtems_task_wake_after: yields -- preempts caller 19
    rtems_task_wake_when 36


	Interrupt Manager

    interrupt entry overhead: returns to nested interrupt 5
    interrupt entry overhead: returns to interrupted task 9
    interrupt entry overhead: returns to preempting task 7
    interrupt exit overhead: returns to nested interrupt 1
    interrupt exit overhead: returns to interrupted task 2
    interrupt exit overhead: returns to preempting task 26


	Clock Manager

    rtems_clock_set 20
    rtems_clock_get <1
    rtems_clock_tick 8


	Timer Manager

    rtems_timer_create 8
  	rtems_timer_ident 104
    rtems_timer_delete: inactive 12
    rtems_timer_delete: active 13
    rtems_timer_fire_after: inactive 17
    rtems_timer_fire_after: active 18
    rtems_timer_fire_when: inactive 23
    rtems_timer_fire_when: active 23
    rtems_timer_reset: inactive 16
    rtems_timer_reset: active 17
    rtems_timer_cancel: inactive 9
    rtems_timer_cancel: active 10


	Semaphore Manager

    rtems_semaphore_create 22
    rtems_semaphore_ident 119
    rtems_semaphore_delete 24
    rtems_semaphore_obtain: available 10
    rtems_semaphore_obtain: not available -- NO_WAIT 10
    rtems_semaphore_obtain: not available -- caller blocks 35
    rtems_semaphore_release: no waiting tasks 11
    rtems_semaphore_release: task readied -- returns to caller 17
    rtems_semaphore_release: task readied -- preempts caller 27


	Message Queue Manager

    rtems_message_queue_create 85
    rtems_message_queue_ident 103
    rtems_message_queue_delete 32
    rtems_message_queue_send: no waiting tasks 25
    rtems_message_queue_send: task readied -- returns to caller 27
    rtems_message_queue_send: task readied -- preempts caller 39
    rtems_message_queue_urgent: no waiting tasks 26
    rtems_message_queue_urgent: task readied -- returns to caller 28
    rtems_message_queue_urgent: task readied -- preempts caller 39
    rtems_message_queue_broadcast: no waiting tasks 13
    rtems_message_queue_broadcast: task readied -- returns to caller 37
    rtems_message_queue_broadcast: task readied -- preempts caller 45
    rtems_message_queue_receive: available 21
    rtems_message_queue_receive: not available -- NO_WAIT 11
    rtems_message_queue_receive: not available -- caller blocks 37
    rtems_message_queue_flush: no messages flushed 7
    rtems_message_queue_flush: messages flushed 10


	Event Manager

    rtems_event_send: no task readied 7
    rtems_event_send: task readied -- returns to caller 18
    rtems_event_send: task readied -- preempts caller 29
    rtems_event_receive: obtain current events <1
    rtems_event_receive: available 10
    rtems_event_receive: not available -- NO_WAIT 5
    rtems_event_receive: not available -- caller blocks 28


	Signal Manager

    rtems_signal_catch 5
    rtems_signal_send: returns to caller 15
    rtems_signal_send: signal to self 24
    exit ASR overhead: returns to calling task 20
    exit ASR overhead: returns to preempting task 21


	Partition Manager

    rtems_partition_create 30
    rtems_partition_ident 103
    rtems_partition_delete 14
    rtems_partition_get_buffer: available 14
    rtems_partition_get_buffer: not available 9
    rtems_partition_return_buffer 18


	Region Manager

    rtems_region_create 25
    rtems_region_ident 105
    rtems_region_delete 13
    rtems_region_get_segment: available 13
    rtems_region_get_segment: not available -- NO_WAIT 17
    rtems_region_get_segment: not available -- caller blocks 49
    rtems_region_return_segment: no waiting tasks 16
    rtems_region_return_segment: task readied -- returns to caller 35
    rtems_region_return_segment: task readied -- preempts caller 58


	Dual-Ported Memory Manager

    rtems_port_create 13
	  rtems_port_ident 103
    rtems_port_delete 14
    rtems_port_external_to_internal 5
    rtems_port_internal_to_external 5


	IO Manager

    rtems_io_initialize <1
    rtems_io_open <1
    rtems_io_close <1
    rtems_io_read <1
    rtems_io_write <1
    rtems_io_control <1


	Rate Monotonic Manager

    rtems_rate_monotonic_create 15
	  rtems_rate_monotonic_ident 103
    rtems_rate_monotonic_cancel 16
    rtems_rate_monotonic_delete: active 18
    rtems_rate_monotonic_delete: inactive 20
    rtems_rate_monotonic_period: initiate period -- returns to caller 23
    rtems_rate_monotonic_period: conclude periods -- caller blocks 25
    rtems_rate_monotonic_period: obtain status 13


Network tests:
       Network driver is not implemented.