source: rtems/bsps/m68k/mvme167/README @ 2f6ee01

Last change on this file since 2f6ee01 was eb36d11, checked in by Sebastian Huber <sebastian.huber@…>, on 04/25/18 at 13:06:08

bsps: Move documentation, etc. files to bsps

This patch is a part of the BSP source reorganization.

Update #3285.

  • Property mode set to 100644
File size: 18.1 KB
Line 
1This is a README file for the MVME167 port of RTEMS 4.5.0.
2
3Please send any comments, improvements, or bug reports to:
4
5Charles-Antoine Gauthier
6charles.gauthier@nrc.ca
7
8or
9
10Darlene Stewart
11Darlene.Stewart@nrc.ca
12 
13Software Engineering Group
14Institute for Information Technology
15National Research Council of Canada
16Ottawa, ON, K1A 0R6
17Canada
18
19
20Disclaimer
21----------
22
23The National Research Council of Canada is distributing this RTEMS
24board support package for the Motorola MVME167 as free software; you
25can redistribute it and/or modify it under terms of the GNU General
26Public License as published by the Free Software Foundation; either
27version 2, or (at your option) any later version.  This software is
28distributed in the hope that it will be useful, but WITHOUT ANY
29WARRANTY; without even the implied warranty of MERCHANTABILITY or
30FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
31for more details. You should have received a copy of the GNU General
32Public License along with RTEMS; see file COPYING. If not, write to
33the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
34
35Under no circumstances will the National Research Council of Canada
36nor Her Majesty the Queen in right of Canada assume any liablility
37for the use this software, nor any responsibility for its quality or
38its support.
39
40
41Installation
42------------
43
44Nothing unique to the MVME167. It uses the standard build process for
45m68k targets. You will need to edit linkcmds to put in the start address
46of your board. We do TFTP transfers to our target. The mvme167.cfg file
47builds only the ELF images, which we download to the target, skipping
48over the first 0x54 bytes; Motorola S-records are not generated. Edit
49this file if you want S-records.
50
51
52Port Description
53
54Console driver
55---------------
56
57This BSP includes an termios-capable interrupt-driven I/O console driver
58that supports all four serial ports on the MVME167 model. The port labelled
59Serial Port 1/Console on the MVME712 is normally used by 167Bug; do not open
60/dev/tty00 if you are debugging using 167Bug.
61
62Limited support is provided for polled terminal I/O. This is used when
63running the timing tests, and by the printk() debug output function.
64Polled I/O may use termios, or it may bypass those services. The printk()
65function does not use termios. When polled I/O is used, the terminal settings
66must be set through 167-Bug; trying to change the line settings through RTEMS
67has no effect.
68
69Three is no support for using interrupt-driven I/O without termios support.
70
71The default configuration is to use polled I/O and to bypass termios. This
72is done so the test can be built at the same time as the rest of the system.
73It is highly recommended that the defaults be changed in the mvme167.cfg file
74to reflect the desired defaults, or that the appropriate parameters be set up
75in NVRAM to select the appropriate I/O modes at boot time.
76
77When configured for interrupt-driven I/O, the console is initialized with
78whatever parameters are set up in termios before it calls the firtOpen driver
79callback, EXCEPT THAT HARDWARE HANDSHAKING IS TURNED OFF, i.e. CLOCAL is set
80in the struct termios c_cflag field. We use 3-wire cables for I/O, and find
81hardware handshaking a pain. If you enable hardware handshaking, you must drive
82CTS* low on the CD2401 for output to occur. If the port is in the DTE
83configuration, you must drive the RS-232 CTS line to space; if the port is
84in the DCE configuration, you must drive the RS-232 RTS line to space.
85
86To use interrupt-driven I/O, set the CD2401_IO_MODE manifest constant to 1 in
87rtems/make/custom/mvme167.cfg, or configure the appropriate parameter in
88User Area Non-volatile RAM. See the Configuration Parameters section below
89for instructions on setting up NVRAM.
90
91To use termios, set the CD2401_USE_TERMIOS manifest constant to 1 in
92rtems/make/custom/mvme167.cfg, or configure the appropriate parameter in
93User Area Non-volatile RAM. See the Configuration Parameters section
94below for instructions on setting up NVRAM.
95
96The RTEMS console, i.e. the port used by stdin, stdout and stderr (do not
97confuse it with the port labelled Console on the MVME712), must be
98specified in the rtems/make/custom/mvme167.cfg file, or in the NVRAM
99parameters. Set the value of CONSOLE_MINOR appropriately. See below for a
100list of choices. See the Configuration Parameters section below for
101instructions on setting up NVRAM.
102
103The RTEMS printk port, i.e. the port where printk sends it debugging output
104text, must be specified in the rtems/make/custom/mvme167.cfg file, or in the
105NVRAM parameters. Set the value of PRINTK_MINOR appropriately. See below for a
106list of choices. See the Configuration Parameters section below for
107instructions on setting up NVRAM.
108
109Interrupt-driven and polled I/O cannot be mixed in the MVME167, except that
110printk always used polled I/O without termios. If interrupt-driven I/O is
111used and printk is used, do not open the device that printk uses from an
112RTEMS application.
113
114Console and printk port choices:
115
116  0 - /dev/tty0, Serial Port 1/Console on the MVME712M.
117  1 - /dev/tty1, Serial Port 2/TTY01 on the MVME712M.
118  2 - /dev/tty2, Serial Port 3 on the MVME712M.
119  3 - /dev/tty3, Serial Port 4 on the MVME712M.
120
121Setting the RTEMS console to port 0 when interrupt-driven I/O is specified
122will prevent 167-Bug from using that port.
123
124To use polled I/O on port 2 or 3, the port must be configured in 167-Bug. See
125the "PF" command in the "Debugging Package for Motorola 68K CISC CPUs User's
126Manual", part number 68KBUG.
127
128
129Floating-point
130--------------
131
132The MC68040 has a built-in FPU. This FPU does not implement all the
133instruction of the MC68881/MC68882 floating-point coprocessors in
134hardware. The -m68040 compilation options instructs gcc to not generate
135the missing instructions. All of the RTEMS code is built this way. Some
136of the missing functionality must be supplied by external libraries. The
137required functions are part of libgcc.a.
138
139The issue gets complicated because libc, libm and libgcc do not come as
140m68040-specific variants. The default variants of these libraries are for the
141MC68020 and MC68030. There are specific variants for the MC68000 (which has
142limited addressing modes with respect to later family members), and specific
143variants for systems without a floating-point unit, either a built-in FPU or
144a coprocessor. These latter variants will be referred to as the msoft-float
145variants. There is a msoft-float variant for the MC68000, and one for the
146other family members.
147
148The default variants of libc, libm and libgcc appear to work just fine for the
149MC68040, AS LONG AS NO FLOATING POINT FUNCTIONS ARE CALLED. In particular,
150printf() and scanf() raise unimplemented floating-point instruction exceptions
151at run time. Expect almost every function that must compute a floating-point
152result to also raise unimplemented floating-point instruction exceptions. Do
153not use these variants if your application does any floating-point operations,
154unless you use the Motorola FPSP package (described further down).
155
156The msoft-float variants do print out floating-point numbers properly, but we
157have not tested them extensively, so use them with caution. In particular,
158the Paranoia test fails when linked with the msoft-float variants of the
159libraries; it goes into an infinite loop after milestone 40.
160
161MSOFT_FLOAT VARIANTS MUST BE USED TOGETHER. If you use the msoft-float variant
162of libc and libm, you must also linked with the msoft-float variant of libgcc,
163otherwise calls such as printf() print out floating-point values incorrectly.
164
165RTEMS comes with the Motorola FPSP (Floating-Point Support Package) for the
166MC68040 (rtems/c/src/lib/libcp/m68k/m68040/fpsp). This package emulates the
167missing floating-point instructions. It is built automatically for the
168MVME167 and installed in bsp_start().
169
170The FPSP allows the use of the default variants of libc, libm and libgcc.
171It also runs the paranoia test properly, and prints out the correct results.
172It should probably be used in preference to the msoft-float libraries, as it
173appears to work better. The disadvantage of the FPSP is that it increases the
174size of the executable by about 60KB and that it relies on run time
175exceptions.
176
177If your application does not do any floating-point operations at all, you
178should consider disabling the FPSP. In bsp_start(), emove the call to
179M68KFPSPInstallExceptionHandlers(), and uncomment the three lines in
180mvme167.cfg that redefine which variants of libc, libm and libgcc to link
181against.
182
183
184Configuration Parameters
185------------------------
186
187If Jumper J1-4 is installed, certain configuration parameters may be read from
188the first 31 bytes of User Area NVRAM starting at 0xFFFC0000. In this case, the
189remaining J1-[5-7] jumpers are ignored, and the user is responsible for writing
190the appropriate values in NVRAM (via 167-Bug) in order to alter the default
191behaviour. A zero value in NVRAM results in the default behaviour. The paramaters
192that are configurable and their default settings are described below.
193               
194        Cache Mode (0xFFFC0000 - 1 byte)
195          Set the following bits in the byte to set the desired cache mode:
196            bit 0
197              0 - data cache disable
198              1 - data cache enable
199            bit 1
200              0 - instruction cache disable
201              1 - instruction cache enable
202            bits 2 & 3:
203                    00 = cachable, write-through
204                    01 = cachable, copyback
205                    10 = noncachable, serialized
206                    11 = noncachable
207
208        Console driver I/O mode (0xFFFC0001 - 1 byte)
209          Set the following bits in the byte to set the desired I/O mode:
210            bit 0
211              0 - do not use termios
212              1 - use termios
213            bit 1
214              0 - polled I/O
215              1 - interrupt-driven I/O
216
217        Console driver ports (0xFFFC0002 - 1 byte)
218          Set the following bits in the byte to select the console and printk ports:
219            bit 0 & 1 select the RTEMS console port
220        00 - /dev/tty0, Serial Port 1/Console on the MVME712M.
221        01 - /dev/tty1, Serial Port 2/TTY01 on the MVME712M.
222        10 - /dev/tty2, Serial Port 3 on the MVME712M.
223        11 - /dev/tty3, Serial Port 4 on the MVME712M.
224            bit 4 & 5 select the RTEMS printk port
225        00 - /dev/tty0, Serial Port 1/Console on the MVME712M.
226        01 - /dev/tty1, Serial Port 2/TTY01 on the MVME712M.
227        10 - /dev/tty2, Serial Port 3 on the MVME712M.
228        11 - /dev/tty3, Serial Port 4 on the MVME712M.
229    If the printk port is the same as some other port that will be opened by an
230    RTEMS application, then the driver must use polled I/O, or the printk port
231    must not be used.
232   
233        IP Address (0xFFFC0004 - 4 bytes)
234                write the hexadecimal representation of the IP address of the board in this
235                locatio, e.g. 192.168.1.2 = 0xC0A80102
236                default: obtain the IP address from an rtems_bsdnet_ifconfig structure
237
238        Netmask (0xFFFC0008 - 4 bytes)
239                write the hexadecimal representation of the netmask in this location
240                for example, 255.255.255.0 = 0xFFFFFF00
241                default: obtain the netmask from an rtems_bsdnet_ifconfig structure
242               
243        Ethernet Address (0xFFFC000C - 6 bytes)
244                write the Ethernet address of the board in this location
245                default: obtain the hardware address from an rtems_bsdnet_ifconfig
246                         structure
247
248        Processor ID (0xFFFC0012 - 2 bytes)
249                reserved for future use
250               
251        RMA start (0xFFFC0014 - 4 bytes)
252                reserved for future use
253               
254        VMA start (0xFFFC0018 - 4 bytes)
255                reserved for future use
256               
257        RamSize (0xFFFC001C - 4 bytes)
258                reserved for future use
259
260
261Cache Control and Memory Mapping
262--------------------------------
263
264If configuration is not obtained from non-volatile RAM (ie. J1-4 is off),
265cache control is done through the remaining J1 jumpers as follows:
266
267If Jumper J1-7 is installed, the data cache will be turned on. If Jumper
268J1-6 is installed, the instruction cache will be turned on. (If a jumper
269is off, its corresponding cache will remain disabled).
270
271If Jumper J1-5 is installed, the data cache will be placed in copyback
272mode. If it is removed, it will be placed in writethrough mode.
273
274Currently, block address translation is set up to map the virtual
2750x00000000--0x7FFFFFFF to the physical range 0x00000000--0x7FFFFFFF. The
276port relies on the hardware to raise exceptions when addressing
277non-existent memory. Caching is not controllable on a finer grain.
278
279
280Networking
281----------
282
283If configuration is not obtained from non-volatile RAM (ie. J1-4 is off),
284the networking parameters shown above must be specified in an initialized
285rtems_bsdnet_ifconfig struct. This structure is declared and initialized to
286specify any network devices and includes entries for ip_address, ip_netmask
287and hardware_address. See the Network Device Configuration section of the
288RTEMS Networking Supplement.
289
290When non-default (non-zero) networking paramaters are provided in NVRAM (ie.
291j1-4 is on), the user MUST ensure that the corresponding entries in the
292ifconfig struct are NULL. Failing to do so is an error, because it causes
293the memory allocated for the initialized struct values to be lost.
294
295
296Miscellaneous
297-------------
298
299The timer and clock drivers were patterned after the MVME162 and MVME152
300ports.
301
302At this time, we do not have an MPCI layer for the MVME167. We are planning
303to write one.
304
305This port supplies its own fatal_error_handler, which attempts to print some
306error message through 167Bug (on the Serial Port 1/Console on the MVME712M).
307
308
309Host System
310-----------
311
312The port was initially developed on an RS-6000 running AIX 4.2. The following
313tools were used:
314
315    - GNU gcc 2.8.1 configured for a powerpc-ibm-aix4.2.0.0 host and
316      m68k-rtems target;
317    - GNU binutils 2.9.1 configured for a powerpc-ibm-aix4.2.0.0 host and
318      m68k-rtems target;
319
320It was also tested on a Pentium II-based PC running Windows NT Workstation 4.0
321and the Cygnus Cygwin32 release b20.1 environment, with the following tools:
322
323    - EGCS 1.1.1 configured for a i586-cygwin32 host and m68k-rtems target;
324    - GNU binutils 2.9.4 configured for a i586-cygwin32 host and m68k-rtems
325      target;
326
327With the latter environment, be patient; builds take a very looong time...
328
329Current development is done on a Pentium III PC running RedHat Linux 6.1.
330At the time this README was composed, the latest working compiler that was
331used successfully was gcc version 2.96 20000213 (experimental). Both the C
332and C++ compilers were working. Binutils 2.10 are used.
333
334
335Known Problems
336--------------
337
338Polled I/O without termios may not work very well on input. The problem
339is that input processing is not done: applications may get characters too
340early, and may get characters that they normally would not get, such as
341backspace or delete. Furthermore, input is not buffered at all. The latest
342versions of rtems seem to set the count field in the rtems_libio_rw_args_t
343argument to the buffer size, not to the number of characters expected on
344input. Rather than wait for 1024 characters on each call, the driver
345returns each character when it is received.
346
347The cdtest will not run with interrupt-driven I/O. The reason is that the
348constructors for the static objects are called at boot time when the
349interrupts are still disabled. The output buffer fills up, but never empties,
350and the application goes into an infinite loop waiting for buffer space. This
351should have been documented in the rtems/c/src/tests/PROBLEMS file. The moral
352of this story is: do not do I/O from the constructors or destructors of static
353objects.
354
355Output stops prematurely in the termios test when the console is operating in
356interrupt-driven mode because the serial port is re-initialized before all
357characters in the last raw output buffer are sent. Adding calls to tcdrain()
358in the test task helps, but it does not solve the problem. What happens is
359that the CD2401 raises a transmit interrupt when the last character in the
360DMA buffer is written into the transmit FIFO, not when the last character
361has been transmitted. When tcdrain() returns, there might be up to 16
362characters in the output FIFO. The call to tcsetattr() causes the serial port
363to re-initialize, at which point the output FIFO is cleared. We could not find
364a way to detect whether characters are still in the FIFO and to wait for them
365to be transmitted.
366
367The first raw buffer to be transmitted after the console is re-initialized
368with tcsetattr() is garbled. At this time, it does not seem worth while to
369track this problem down.
370
371In the stackchk test, an access fault exception is raised after the stack is
372blown. This is one case were overwritting the first or last 16 bytes of the
373stack does cause problems (but hey, an exception occurred, which is better
374than propagating the error).
375
376In the stackchk test, an access fault exception is raised after the stack is
377blown. This is one case were overwritting the first or last 16 bytes of the
378stack does cause problems (but hey, an exception occurred, which is better
379than propagating the error).
380
381When using interrupt-driven I/O, psx08 produces all the expected output, but
382it does not return control to 167Bug. Is this test supposed to work with
383interrupt-driven console I/O?
384
385
386What is new
387-----------
388
389Support for Java is being actively worked on.
390
391
392Thanks
393------
394
395- to On-Line Applications Research Corporation (OAR) for developing
396RTEMS and making it available on a Technology Transfer basis;
397
398- to FSF and Cygnus Support for great free software;
399
400
401Test Configuration
402------------------
403
404Board:                Motorola MVME167
405CPU:                  Motorola MC68040
406Clock Speed:          25 MHz
407RAM:                  4 MBytes of 32-bit DRAM with parity
408Cache Configuration:  Instruction cache on; data cache on, copyback mode.
409Times Reported in:    microseconds
410Timer Source:         VMEchip2 Tick Timer 1
411GCC Flags:            -m68040 -g -O4 -fomit-frame-pointer
412Console:              Operate in polled mode. Set CD2401_POLLED_IO to 1 in
413                      rtems/c/src/lib/libbsp/m68k/mvme167/console/console.c.     
414
415
416Test Results
417------------
418
419Single processor tests:  All tests passed, except the following ones:
420
421  - paranoia required the FPSP and the default variants of libm (and libc and
422    libgcc) for us. It may work with the msoft-float variants for you, but it
423    does require the FPSP.
424 
425  - cpuuse and malloctest did not work.
426 
427  - The stackchk test got an access fault exception before the RTEMS stack
428    checker had had a chance to detect the corrupted stack.
429                         
430                         
431Multi-processort tests:  not applicable -- No MPCI layer yet.
432
433
434Timing tests: See rtems/c/src/lib/libbsp/m68k/mvme167/times
435 
Note: See TracBrowser for help on using the repository browser.