source: rtems/c/src/lib/libbsp/m68k/mvme167/README @ d7aecdc

4.104.114.84.95
Last change on this file since d7aecdc was ed09fd77, checked in by Joel Sherrill <joel.sherrill@…>, on 08/11/00 at 19:26:31

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

  • README: Updated
  • console/console.c: Fix polled input. Add support for shared printk. Add support for more flexible polled I/O with and without termios. I/O mode and console is selectable either from NVRAM or from mvme167.cfg. Clean up comments.

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

  • startup/page_table.c (page_table_init): Reorganize NVRAM parameters.
  • include/bsp.h: Reorganize NVRAM parameters. Add support for shared printk.
  • times: These are the times for the MVME167, not the MBX860-002.

2000-08-11 John Cotton <john.cotton@…>

  • network/network.c: Fix NVRAM configuration parameter handling from previous revision. Check J1-4, restructure NVRAM parameter handling.

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

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