path: root/c/src/lib/libbsp/powerpc/mbx8xx/README

This is a README file for the MBX860/MBX821 port of RTEMS 4.5.0

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

Darlene A. Stewart
Software Engineering Group
Institute for Information Technology
National Research Council of Canada
Ottawa, ON, K1A 0R6
Canada

Darlene.Stewart@nrc.ca
  


Disclaimer
----------

The National Research Council of Canada is distributing this RTEMS
board support package for the Motorola MBX860 and MBX821 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.


Summary
-------

BSP NAME:           mbx8xx
BOARD:              Motorola MBX860 and MBX821 Embedded Controllers
BUS:                No backplane. On-board ISA, PCI, PC/104 and PCMCIA.
CPU FAMILY:         PowerPC
CPU:                PowerPC MPC860 or MPC821
COPROCESSORS:       Built-in Motorola QUICC
MODE:               32 bit mode

DEBUG MONITOR:      EPPC-Bug

PERIPHERALS
===========
TIMERS:             PIT / Timebase
  RESOLUTION:       1 microsecond / frequency = clock-speed / 16
SERIAL PORTS:       2 or 4 SCCs (SCC1 is hardwired for Ethernet)
                    2 SMC
                    1 SIO
REAL-TIME CLOCK:    Many. Look at documentation.
DMA:                Each SCC and SMC.
VIDEO:              None on-board. MPC821 has a built-in LCD panel driver.
SCSI:               None on-board.
NETWORKING:         Ethernet (10 Mbps) on SCC1
		   

DRIVER INFORMATION
==================
CLOCK DRIVER:       yes
CONSOLE DRIVER:     yes
SHMSUPP:            N/A
TIMER DRIVER:       yes
NETWORK DRIVER:	    yes

NOTES
=====
On-chip resources:
	SCC1		network or console
	SCC2		serial port
	SMC1		gdb debug console/application console
	SMC2		application console
	CLK1		network
	CLK2		network
	CLK3
	CLK4
	CLK5
	CLK6
	CLK7
	CLK8
	BRG1		console
	BRG2		console
	BRG3		console
	BRG4		console
	RTC
	PIT		clock
	TB
	DEC
	SWT	
	*CS0		FLASH
	*CS1		DRAM bank (onboard)
	*CS2		DRAM bank 0 (1st half of DIMM)
	*CS3		DRAM bank 1 (2nd half of DIMM)
	*CS4		Battery-Backed SRAM
	*CS5		QSPAN PCI
	*CS6		QSPAN
	*CS7		Boot ROM
	UPMA
	UPMB
	IRQ0
	IRQ1
	IRQ2		
	IRQ3		
	IRQ4		
	IRQ5	
	IRQ6
	IRQ7
	IRQ_LVL0	
	IRQ_LVL1
	IRQ_LVL2
	IRQ_LVL3
	IRQ_LVL4
	IRQ_LVL5
	IRQ_LVL6
	IRQ_LVL7
	

Board description
-----------------
Clock rate:	50MHz Entry level boards, 40 MHz others.
Bus width:	8/32 bit Flash, 32 bit DRAM
FLASH:		  2-4MB, 120ns
RAM:		    4-16MB EDO, 60ns DRAM DIMM


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

All MBX821/MBX860 ports share the same source code base. The MPC821 does
not have SCC3 and SCC4. Instead, it has an LCD panel driver. Otherwise,
the MBX821 and MBX860 boards are essentially identical. Entry level boards
do not have all connectors and peripheral devices present. This has no
impact on the source code base; it merely means that some functionality
is not available on these entry level boards. For the most part, the port
uses the standard build process for powerpc targets. However, you must
specify the EXACT model of MBX board that you are building for as the
argument to the RTEMS_BSP make variable. If you do not, the build process
will build for a MBX860-002. Look at rtems/make/custom/mbx8xx.cfg for the
specific list of boards supported and their corresponding names. An
example build command is:

	make RTEMS_BSP=mbx821_001 VARIANT=DEBUG

This will build the debug version of all RTEMS libraries, samples and tests
(if the latter are enabled).

The Software Engineering Group of the Institute for Information Technology
only owns an MBX821-001 and MBX86-002. The only provided config files are
mbx821_001.cfg and mbx860_002.cfg. A SPECIFIC CONFIG FILE IS REQUIRED. Use
one of the provided files as a template to create a specific config file for
another model.
 
We rely on EPPC-BUG to download to the targets. We use the "PLH" command.
We enabled a TFTP deamon on our development host.


Port Description
Console driver
---------------

This BSP includes an termios-capable asynchronous serial line driver
that supports SMC1, SMC2, SCC2, and SCC3 and SCC4 if present. The RTEMS
console is selected in rtems/make/custom/mbx8xx.cfg with the
CONSOLE_MINOR variable. We normally run with the RTEMS application
console on SMC2. SMC1 is used by the debugger.

Support is provided for five different modes of operation:

  1. polled I/O done by EPPC-Bug with termios support,
  2. polled I/O done by EPPC-Bug without termios support,
  3. polled I/O done by the supplied device driver with termios support,
  4. polled I/O done by the supplied device driver without termios support,
  5. interrupt-driven I/O done by the supplied device driver with termios
     support.
     
The mode of operation of the serial driver is determined at build time
by the value of the UARTS_IO_MODE constant in rtems/make/custom/mbx8xx.cfg.
Edit the file to select the type of I/O desired before building RTEMS.
The choices are:

  0 - polled I/O done by the supplied device driver,
  1 - interrupt-driven I/O done by the supplied device driver,
  2 - polled I/O done by EPPC-Bug.
  
Also set the value of UARTS_USE_TERMIOS to select whether termios should
be used to perform buffering and input/output processing. Without termios
support, input processing is limited to the substitution of LF for a
received CR, and output processing is limited to the transmission of a
CR following the transmission of a LF. The choices for UARTS_USE_TERMIOS are:

  0 - do not use termios
  1 - use termios

In most real-time applications, the driver should be configured to use
termios and interrupt-driven I/O. Special requirements may dictate otherwise.

Polled I/O must be used when running the timing tests. It must also be used
to run some other tests and some samples, such as the cdtest. Some tests
change the interrupt mask and will hang interrupt-driven I/O indefinitely.
Others, such as cdtest, perform console output from the static constructors
before the console is opened, causing the test to hang. Still other tests
produce output that is supposed to be in some specific order. For these
tests, termios should not be used, as termios buffers output and the
transmission of the buffers occur at somewhat unpredictable times.

The real solution is to fix the tests so that they work with interrupt-driven
I/O and termios.


printk() and debug output
-----------------------

The implementation of printk() in RTEMS is mostly independent of most system
services. The printk() function can therefore be used to print messages to a
debug console, particularly when debugging startup code or device drivers,
i.e. code that runs before the console driver is opened or that runs with
interrupts disabled.

Support is provided to send printk output to any port. Specify the desired
port at build time in rtems/make/custom/mbx8xx.cfg by setting the value
of PRINTK_MINOR to one of SMC1_MINOR, SMC2_MINOR, SCC2_MINOR, SCC3_MINOR,
or SCC4_MINOR.

Select the type of output desired for printk() by setting the value of
PRINTK_IO_MODE in rtems/make/custom/mbx8xx.cfg. The choices are:

  0 - polled I/O done by the supplied device driver,
  1 - interrupt-driven I/O done by the supplied device driver,
  2 - polled I/O done by EPPC-Bug.
  
printk() does not use termios.

If the printk() port is opened by RTEMS, then PRINK_IO_MODE mode must have
the same value as UARTS_IO_MODE, otherwise the I/O functions will be in
conflict. Interrupt-driven printk() output is only possible if the port is
opened before hand by an RTEMS application, and is of dubious value...


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


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.


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.

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

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


Thanks
------

- to Jay Monkman (jmonkman@frasca.com) 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.