source: rtems/c/src/lib/libbsp/powerpc/mbx8xx/README @ 867ab080

4.104.114.84.95
Last change on this file since 867ab080 was 00ff4cd, checked in by Joel Sherrill <joel.sherrill@…>, on Aug 25, 2000 at 5:24:49 PM

2000-08-11 Charles-Antoine Gauthier <charles.gauthier@…>

  • README:
  • console/console.c:
  • include/bsp.h:
  • network/network.c:
  • startup/bspstart.c: Add support for configuration parameters in NVRAM
  • Property mode set to 100644
File size: 17.1 KB
Line 
1#
2#  $Id$
3#
4
5This is a README file for the MBX860/MBX821 port of RTEMS 4.5.0
6
7Please send any comments, improvements, or bug reports to:
8
9Charles-Antoine Gauthier
10charles.gauthier@nrc.ca
11
12or
13
14Darlene Stewart
15Darlene.Stewart@nrc.ca
16 
17Software Engineering Group
18Institute for Information Technology
19National Research Council of Canada
20Ottawa, ON, K1A 0R6
21Canada 
22
23
24Disclaimer
25----------
26
27The National Research Council of Canada is distributing this RTEMS
28board support package for the Motorola MBX860 and MBX821 as free
29software; you can redistribute it and/or modify it under terms of
30the GNU General Public License as published by the Free Software
31Foundation; either version 2, or (at your option) any later version.
32This software is distributed in the hope that it will be useful, but
33WITHOUT ANY WARRANTY; without even the implied warranty of
34MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
35General Public License for more details. You should have received a
36copy of the GNU General Public License along with RTEMS; see file
37COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
38Cambridge, MA 02139, USA.
39
40Under no circumstances will the National Research Council of Canada
41nor Her Majesty the Queen in right of Canada assume any liablility
42for the use this software, nor any responsibility for its quality or
43its support.
44
45
46Summary
47-------
48
49BSP NAME:           mbx8xx
50BOARD:              Motorola MBX860 and MBX821 Embedded Controllers
51BUS:                No backplane. On-board ISA, PCI, PC/104 and PCMCIA.
52CPU FAMILY:         PowerPC
53CPU:                PowerPC MPC860 or MPC821
54COPROCESSORS:       Built-in Motorola QUICC
55MODE:               32 bit mode
56
57DEBUG MONITOR:      EPPC-Bug
58
59PERIPHERALS
60===========
61TIMERS:             PIT / Timebase
62  RESOLUTION:       1 microsecond / frequency = clock-speed / 16
63SERIAL PORTS:       2 or 4 SCCs (SCC1 is hardwired for Ethernet)
64                    2 SMC
65                    1 SIO
66REAL-TIME CLOCK:    Many. Look at documentation.
67DMA:                Each SCC and SMC.
68VIDEO:              None on-board. MPC821 has a built-in LCD panel driver.
69SCSI:               None on-board.
70NETWORKING:         Ethernet (10 Mbps) on SCC1
71                   
72
73DRIVER INFORMATION
74==================
75CLOCK DRIVER:       yes
76CONSOLE DRIVER:     yes
77SHMSUPP:            N/A
78TIMER DRIVER:       yes
79NETWORK DRIVER:     yes
80
81NOTES
82=====
83On-chip resources:
84        SCC1            network or console
85        SCC2            serial port
86        SMC1            gdb debug console/application console
87        SMC2            application console
88        CLK1            network
89        CLK2            network
90        CLK3
91        CLK4
92        CLK5
93        CLK6
94        CLK7
95        CLK8
96        BRG1            console
97        BRG2            console
98        BRG3            console
99        BRG4            console
100        RTC
101        PIT             clock
102        TB
103        DEC
104        SWT     
105        *CS0            FLASH
106        *CS1            DRAM bank (onboard)
107        *CS2            DRAM bank 0 (1st half of DIMM)
108        *CS3            DRAM bank 1 (2nd half of DIMM)
109        *CS4            Battery-Backed SRAM
110        *CS5            QSPAN PCI
111        *CS6            QSPAN
112        *CS7            Boot ROM
113        UPMA
114        UPMB
115        IRQ0
116        IRQ1
117        IRQ2           
118        IRQ3           
119        IRQ4           
120        IRQ5   
121        IRQ6
122        IRQ7
123        IRQ_LVL0       
124        IRQ_LVL1
125        IRQ_LVL2
126        IRQ_LVL3
127        IRQ_LVL4
128        IRQ_LVL5
129        IRQ_LVL6
130        IRQ_LVL7
131       
132
133Board description
134-----------------
135Clock rate:     50MHz Entry level boards, 40 MHz others.
136Bus width:      8/32 bit Flash, 32 bit DRAM
137FLASH:          2-4MB, 120ns
138RAM:            4-16MB EDO, 60ns DRAM DIMM
139
140
141Installation
142------------
143
144All MBX821/MBX860 ports share the same source code base. The MPC821 does
145not have SCC3 and SCC4. Instead, it has an LCD panel driver. Otherwise,
146the MBX821 and MBX860 boards are essentially identical. Entry level boards
147do not have all connectors and peripheral devices present. This has no
148impact on the source code base; it merely means that some functionality
149is not available on these entry level boards. For the most part, the port
150uses the standard build process for powerpc targets. However, you must
151specify the EXACT model of MBX board that you are building for as the
152argument to the RTEMS_BSP make variable. If you do not, the build process
153will build for a MBX860-002. Look at rtems/make/custom/mbx8xx.cfg for the
154specific list of boards supported and their corresponding names. An
155example build command is:
156
157        make RTEMS_BSP=mbx821_001 VARIANT=DEBUG
158
159This will build the debug version of all RTEMS libraries, samples and tests
160(if the latter are enabled).
161
162The Software Engineering Group of the Institute for Information Technology
163only owns an MBX821-001 and MBX86-002. The only provided config files are
164mbx821_001.cfg and mbx860_002.cfg. A SPECIFIC CONFIG FILE IS REQUIRED. Use
165one of the provided files as a template to create a specific config file for
166another model.
167 
168We rely on EPPC-BUG to download to the targets. We use the "PLH" command.
169We enabled a TFTP deamon on our development host.
170
171
172Port Description
173Console driver
174---------------
175
176This BSP includes an termios-capable asynchronous serial line driver that
177supports SMC1, SMC2, SCC2, and SCC3 and SCC4 if present. The RTEMS console is
178selected in rtems/make/custom/mbx8xx.cfg with the CONSOLE_MINOR variable, or
179in NVRAM if that option is enabled in the rtems/make/custom/mbx8xx.cfg file.
180We normally run with the RTEMS application console on SMC2. SMC1 is used by
181the debugger.
182
183Support is provided for five different modes of operation:
184
185  1. polled I/O done by EPPC-Bug with termios support,
186  2. polled I/O done by EPPC-Bug without termios support,
187  3. polled I/O done by the supplied device driver with termios support,
188  4. polled I/O done by the supplied device driver without termios support,
189  5. interrupt-driven I/O done by the supplied device driver with termios
190     support.
191     
192If NVRAM_CONFIGURE is set to 1 in rtems/make/custom/mbx8xx.cfg, the mode of
193operation of the driver is determined at boot time from the values stored
194in the user area in NVRAM. See the Configuration Parameters section below for
195instructions on setting up NVRAM. Otherwise, the mode of operation of the
196serial driver is determined at build time in part by the value of the
197UARTS_IO_MODE constant in rtems/make/custom/mbx8xx.cfg. Edit the file to select
198the type of I/O desired before building RTEMS. The choices are:
199
200  0 - polled I/O done by the supplied device driver,
201  1 - interrupt-driven I/O done by the supplied device driver,
202  2 - polled I/O done by EPPC-Bug.
203 
204Also, if NVRAM_CONFIGURE is not set to 1 in rtems/make/custom/mbx8xx.cfg, set
205the value of UARTS_USE_TERMIOS to select whether termios should be used to
206perform buffering and input/output processing. Without termios support, input
207processing is limited to the substitution of LF for a received CR, and output
208processing is limited to the transmission of a CR following the transmission of
209a LF. The choices for UARTS_USE_TERMIOS are:
210
211  0 - do not use termios
212  1 - use termios
213
214In most real-time applications, the driver should be configured to use
215termios and interrupt-driven I/O. Special requirements may dictate otherwise.
216
217Polled I/O must be used when running the timing tests. It must also be used
218to run some other tests and some samples, such as the cdtest. Some tests
219change the interrupt mask and will hang interrupt-driven I/O indefinitely.
220Others, such as cdtest, perform console output from the static constructors
221before the console is opened, causing the test to hang. Still other tests
222produce output that is supposed to be in some specific order. For these
223tests, termios should not be used, as termios buffers output and the
224transmission of the buffers occur at somewhat unpredictable times.
225
226The real solution is to fix the tests so that they work with interrupt-driven
227I/O and termios.
228
229
230printk() and debug output
231-----------------------
232
233The implementation of printk() in RTEMS is mostly independent of most system
234services. The printk() function can therefore be used to print messages to a
235debug console, particularly when debugging startup code or device drivers,
236i.e. code that runs before the console driver is opened or that runs with
237interrupts disabled.
238
239Support is provided to send printk output to any port. Specify the desired
240port at build time in rtems/make/custom/mbx8xx.cfg by setting the value
241of PRINTK_MINOR to one of SMC1_MINOR, SMC2_MINOR, SCC2_MINOR, SCC3_MINOR,
242or SCC4_MINOR. Alternatively, if NVRAM_CONFIGURE is set to 1 in
243rtems/make/custom/mbx8xx.cfg, the printk port is selected based on data that
244is stored in the user area in NVRAM. See the Configuration Parameters section
245below for instructions on setting up NVRAM.
246
247Select the type of output desired for printk() by setting the value of
248PRINTK_IO_MODE in rtems/make/custom/mbx8xx.cfg. The choices are:
249
250  0 - polled I/O done by the supplied device driver,
251  1 - polled I/O done by the supplied device driver,
252  2 - polled I/O done by EPPC-Bug.
253 
254printk() does not use termios.
255
256If the printk() port is opened by RTEMS, then PRINK_IO_MODE mode must have
257the same value as UARTS_IO_MODE, otherwise the I/O functions will be in
258conflict. Interrupt-driven printk() output did not work, although we think
259that it should have. It would have been of dubious value anyways. If
260interrupt-driven I/O is selected (value of 1), the driver defaults to using
261polled I/O through the RTEMS driver.
262
263IMPORTANT: Polled I/O through the RTEMS driver requires that the driver be
264initialized. Consequently, to debug startup code using printk prior to the
265initialization of the serial driver, use mode 2: polled I/O through EPPC-Bug,
266and read the next section.
267
268
269EPPC-Bug and I/O
270----------------
271
272IMPORTANT: When using EPPC-Bug 1.1 for polled I/O, only the SMC1 port is
273usable. This is a deficiency of the firmware which may be fixed in later
274revision. When using this monitor with UARTS_IO_MODE set to 2, CONSOLE_MINOR
275must be set to SMC1_MINOR. Similarly, if PRINTK_IO_MODE set to 2,
276PRINTK_MINOR must be set to SMC1_MINOR. When UARTS_IO_MODE is set to 2,
277only SMC1 is usable.
278
279Be warned that when EPPC-Bug does I/O through a serial port, all interrupts
280get turned off in the SIMASK register! This is a definite bug in release 1.1
281of the firmware. It may have been fixed in later releases. EPPB-Bug does
282I/O through its debug port whenever it is given control, e.g. after a
283breakpoint is hit, not just when it is used to perform polled I/O on behalf
284of RTEMS applications. In particular, in our configuration, we have gdb
285communication with EPPC-Bug through SMC1.
286
287To solve this problem, whenever the BSP manipulates the SIMASK, it makes a
288copy of the written value in a global variable called 'simask_copy'. That
289value must be restored by GDB before execution resumes. The following commands
290placed in the .gdbinit file takes care of this:
291
292# GDB Initialization file for EPPC-Bug.
293
294define hook-stepi
295set language c
296set *(int *)0xFA200014=simask_copy
297set language auto
298end
299
300define hook-step
301set language c
302set *(int *)0xFA200014=simask_copy
303set language auto
304end
305
306define hook-continue
307set language c
308set *(int *)0xFA200014=simask_copy
309set language auto
310end
311
312define hook-nexti
313set language c
314set *(int *)0xFA200014=simask_copy
315set language auto
316end
317
318define hook-next
319set language c
320set *(int *)0xFA200014=simask_copy
321set language auto
322end
323
324define hook-finish
325set language c
326set *(int *)0xFA200014=simask_copy
327set language auto
328end
329
330IMPORTANT: When using EPPC-Bug on SMC1, either for debugging or for polled I/O,
331EPPCBUG_SMC1 must be defined in rtems/make/custom/mbx8xx.cfg, or the eppc_bug
332field set to non-zero in NVRAM. Defining this constant prevents the device
333driver from re-initializing SMC1. It also causes the network driver, the clock
334driver, and the asynchronous serial line driver to maintain simask_copy for use
335by gdb.
336
337Polled I/O through EPPC-Bug is pretty funky... If your are old enough, it might
338bring back fond memories of the days of 300 baud modems. If not, you can
339experience for yourself what the state of the art used to be.
340
341
342Floating-point
343--------------
344
345The MPC860 and MPC821 do not have floating-point units. All code should
346get compiled with the appropriate -mcpu flag. The nof variants of the gcc
347runtime libraries should be used for linking.
348
349
350Configuration Parameters
351------------------------
352
353If NVRAM_CONFIGURE is set in rtems/make/custom/mbx8xx.cfg, certain
354configuration parameters will be read from the first 31 bytes of the  NVRAM
355User Area, which starts at 0xFA001000. The user is responsible for writing
356the appropriate values in NVRAM (via EPPC-Bug). The paramaters
357that are configurable and their default settings are described below.
358               
359  Cache Mode (0xFA001000 - 1 byte)
360    Set the following bits in the byte to control the caches:
361      bit 0
362        0 - data cache disable
363        1 - data cache enable
364      bit 1
365        0 - instruction cache disable
366        1 - instruction cache enable
367    If enabled, all of RAM except for the last 512 KB will be cached using
368    copyback mode. The last 512 KB of RAMis for the use of EPPC-Bug.
369   
370  Console driver I/O mode (0xFA001001 - 1 byte)
371    Set the following bits in the byte to set the desired I/O mode
372    for the rtems ports:
373      bit 0
374        0 - do not use termios
375        1 - use termios
376      bit 2 & 1
377        00 - polled I/O through RTEMS driver
378        01 - interrupt-driven I/O
379        10 - polled I/O through EPPC-Bug
380    Set the following bits in the byte to set the desired I/O mode
381    for printk:
382      bit 5 & 4
383        00 - polled I/O through RTEMS driver
384        01 - polled I/O through RTEMS driver
385        10 - polled I/O through EPPC-Bug
386
387  Console driver ports (0xFA001002 - 1 byte)
388    Set the following bits in the byte to select the console and printk ports:
389    bit 2, 1  & 0 select the RTEMS console port
390        000 - /dev/tty0, SMC1
391        001 - /dev/tty1, SMC2
392        011 - /dev/tty2, SCC2
393        100 - /dev/tty3, SCC3
394        101 - /dev/tty4, SCC4
395    bit 6, 5 & 4 select the RTEMS printk port
396        000 - /dev/tty0, SMC1
397        001 - /dev/tty1, SMC2
398        011 - /dev/tty2, SCC2
399        100 - /dev/tty3, SCC3
400        101 - /dev/tty4, SCC4
401  If the printk port is the same as some other port that will be opened by an
402  RTEMS application, then the driver must use polled I/O, or the printk port
403  must not be used.
404
405  EPPC-Bug in use on SMC1 (0xFA001003 - 1 byte)
406    Set to non-zero to indicate that EPPC-Bug is using SMC1. This will prevent
407    the SMC1 port from being re-initialized.
408
409  IP Address (0xFA001004 - 4 bytes)
410    Write the hexadecimal representation of the IP address of the board in this
411    location, e.g. 192.168.1.2 = 0xC0A80102
412
413  Netmask (0xFA001008 - 4 bytes)
414    Write the hexadecimal representation of the netmask in this location
415    for example, 255.255.255.0 = 0xFFFFFF00
416
417  Ethernet Address (0xFA00100C - 6 bytes)
418    Write the Ethernet address of the board in this location
419
420  Processor ID (0xFA001012 - 2 bytes)
421    Reserved for future use
422               
423  RMA start (0xFA001014 - 4 bytes)
424    Reserved for future use
425               
426  VMA start (0xFA001018 - 4 bytes)
427    Reserved for future use
428               
429  RamSize (0xFA00101C - 4 bytes)
430    Reserved for future use
431
432
433Miscellaneous
434-------------
435
436All development was based on the eth_comm port.
437
438
439Host System
440-----------
441
442The port was developed on Pentiums II and III running RedHat Linux 6.0 and
4436.1. The following tools were used:
444
445    - GNU gcc snapshot dated 20000214 configured for powerpc-rtems;
446    - GNU binutils 2.10 configured for powerpc-rtems;
447
448Gcc 2.95.2 also worked. Gcc 2.95.1 will not compile the console driver with
449-O4 or -O3. Compile it manually with -O2.
450
451
452Known Problems
453--------------
454
455The cdtest will not run with interrupt-driven I/O. The reason is that the
456constructors for the static objects are called at boot time when the
457interrupts are still disabled. The output buffer fills up, but never empties,
458and the application goes into an infinite loop waiting for buffer space. This
459should have been documented in the rtems/c/src/tests/PROBLEMS file. The moral
460of this story is: do not do I/O from the constructors or destructors of static
461objects.
462
463When using interrupt-driven I/O, psx08 fails with an internal assertion error.
464
465
466What is new
467----------
468
469All known problems with use of the caches on the MBX860-002 and MBX821-001
470have been resolved.
471
472Configuration of the console and network is now possible at boot time through
473NVRAM parameters.
474
475
476Thanks
477------
478
479- to Jay Monkman (jmonkman@frasca.com) of Frasca International, Inc.
480  for his eth_comm port.
481 
482- to On-Line Applications Research Corporation (OAR) for developing
483  RTEMS and making it available on a Technology Transfer basis;
484
485- to the FSF and to Cygnus Support for great free software;
486
487
488Test Configuration
489------------------
490
491Board:                MBX821-001, MBX860-002
492CPU:                  Motorola MPC821, MPC860
493Clock Speed:          50 MHz, 40 MHz
494RAM:                  4 MBytes of 32-bit DRAM
495Cache Configuration:  Instruction cache on; data cache on, copyback mode.
496Times Reported in:    clock ticks: TMBCLK = system clock / 16.
497Timer Source:         Timebase clock
498GCC Flags:            -O4 -fno-keep-inline-functions -mcpu=(821/860)
499Console:              Operates in polled mode on SMC2. No I/O through EPPC-Bug.   
500
501
502Test Results
503------------
504
505Single processor tests:  All tests passed, except the following ones:
506 
507  - cpuuse and malloctest did not work.
508 
509  - The stackchk test got an access fault exception before the RTEMS stack
510    checker had had a chance to detect the corrupted stack.
511                         
512                         
513Multi-processort tests:  not applicable.
514
515
516Timing tests:
517        See the times-mbx821 and times-mbx860 files for the results of the
518        timing tests.
519
520
521Network tests:
522       Worked.
523
524
525
Note: See TracBrowser for help on using the repository browser.