# # $Id$ # This is a README file for the MBX860/MBX821 port of RTEMS 4.5.0 Please send any comments, improvements, or bug reports to: Charles-Antoine Gauthier charles.gauthier@nrc.ca or Darlene Stewart Darlene.Stewart@nrc.ca 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 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, or in NVRAM if that option is enabled in the rtems/make/custom/mbx8xx.cfg file. 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. If NVRAM_CONFIGURE is set to 1 in rtems/make/custom/mbx8xx.cfg, the mode of operation of the driver is determined at boot time from the values stored in the user area in NVRAM. See the Configuration Parameters section below for instructions on setting up NVRAM. Otherwise, the mode of operation of the serial driver is determined at build time in part 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, if NVRAM_CONFIGURE is not set to 1 in rtems/make/custom/mbx8xx.cfg, 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. Alternatively, if NVRAM_CONFIGURE is set to 1 in rtems/make/custom/mbx8xx.cfg, the printk port is selected based on data that is stored in the user area in NVRAM. See the Configuration Parameters section below for instructions on setting up NVRAM. 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 - polled 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 did not work, although we think that it should have. It would have been of dubious value anyways. If interrupt-driven I/O is selected (value of 1), the driver defaults to using polled I/O through the RTEMS driver. IMPORTANT: Polled I/O through the RTEMS driver requires that the driver be 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 (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.