From eb36d1198cdf9dc1e2f776ef6e1e38755f6d13c5 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 25 Apr 2018 15:06:08 +0200 Subject: bsps: Move documentation, etc. files to bsps This patch is a part of the BSP source reorganization. Update #3285. --- c/src/lib/libbsp/m68k/mvme167/README | 435 ----------------------------------- 1 file changed, 435 deletions(-) delete mode 100644 c/src/lib/libbsp/m68k/mvme167/README (limited to 'c/src/lib/libbsp/m68k/mvme167') diff --git a/c/src/lib/libbsp/m68k/mvme167/README b/c/src/lib/libbsp/m68k/mvme167/README deleted file mode 100644 index 886ee7cc2c..0000000000 --- a/c/src/lib/libbsp/m68k/mvme167/README +++ /dev/null @@ -1,435 +0,0 @@ -This is a README file for the MVME167 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 MVME167 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. - - -Installation ------------- - -Nothing unique to the MVME167. It uses the standard build process for -m68k targets. You will need to edit linkcmds to put in the start address -of your board. We do TFTP transfers to our target. The mvme167.cfg file -builds only the ELF images, which we download to the target, skipping -over the first 0x54 bytes; Motorola S-records are not generated. Edit -this file if you want S-records. - - -Port Description - -Console driver ---------------- - -This BSP includes an termios-capable interrupt-driven I/O console driver -that supports all four serial ports on the MVME167 model. The port labelled -Serial Port 1/Console on the MVME712 is normally used by 167Bug; do not open -/dev/tty00 if you are debugging using 167Bug. - -Limited support is provided for polled terminal I/O. This is used when -running the timing tests, and by the printk() debug output function. -Polled I/O may use termios, or it may bypass those services. The printk() -function does not use termios. When polled I/O is used, the terminal settings -must be set through 167-Bug; trying to change the line settings through RTEMS -has no effect. - -Three is no support for using interrupt-driven I/O without termios support. - -The default configuration is to use polled I/O and to bypass termios. This -is done so the test can be built at the same time as the rest of the system. -It is highly recommended that the defaults be changed in the mvme167.cfg file -to reflect the desired defaults, or that the appropriate parameters be set up -in NVRAM to select the appropriate I/O modes at boot time. - -When configured for interrupt-driven I/O, the console is initialized with -whatever parameters are set up in termios before it calls the firtOpen driver -callback, EXCEPT THAT HARDWARE HANDSHAKING IS TURNED OFF, i.e. CLOCAL is set -in the struct termios c_cflag field. We use 3-wire cables for I/O, and find -hardware handshaking a pain. If you enable hardware handshaking, you must drive -CTS* low on the CD2401 for output to occur. If the port is in the DTE -configuration, you must drive the RS-232 CTS line to space; if the port is -in the DCE configuration, you must drive the RS-232 RTS line to space. - -To use interrupt-driven I/O, set the CD2401_IO_MODE manifest constant to 1 in -rtems/make/custom/mvme167.cfg, or configure the appropriate parameter in -User Area Non-volatile RAM. See the Configuration Parameters section below -for instructions on setting up NVRAM. - -To use termios, set the CD2401_USE_TERMIOS manifest constant to 1 in -rtems/make/custom/mvme167.cfg, or configure the appropriate parameter in -User Area Non-volatile RAM. See the Configuration Parameters section -below for instructions on setting up NVRAM. - -The RTEMS console, i.e. the port used by stdin, stdout and stderr (do not -confuse it with the port labelled Console on the MVME712), must be -specified in the rtems/make/custom/mvme167.cfg file, or in the NVRAM -parameters. Set the value of CONSOLE_MINOR appropriately. See below for a -list of choices. See the Configuration Parameters section below for -instructions on setting up NVRAM. - -The RTEMS printk port, i.e. the port where printk sends it debugging output -text, must be specified in the rtems/make/custom/mvme167.cfg file, or in the -NVRAM parameters. Set the value of PRINTK_MINOR appropriately. See below for a -list of choices. See the Configuration Parameters section below for -instructions on setting up NVRAM. - -Interrupt-driven and polled I/O cannot be mixed in the MVME167, except that -printk always used polled I/O without termios. If interrupt-driven I/O is -used and printk is used, do not open the device that printk uses from an -RTEMS application. - -Console and printk port choices: - - 0 - /dev/tty0, Serial Port 1/Console on the MVME712M. - 1 - /dev/tty1, Serial Port 2/TTY01 on the MVME712M. - 2 - /dev/tty2, Serial Port 3 on the MVME712M. - 3 - /dev/tty3, Serial Port 4 on the MVME712M. - -Setting the RTEMS console to port 0 when interrupt-driven I/O is specified -will prevent 167-Bug from using that port. - -To use polled I/O on port 2 or 3, the port must be configured in 167-Bug. See -the "PF" command in the "Debugging Package for Motorola 68K CISC CPUs User's -Manual", part number 68KBUG. - - -Floating-point --------------- - -The MC68040 has a built-in FPU. This FPU does not implement all the -instruction of the MC68881/MC68882 floating-point coprocessors in -hardware. The -m68040 compilation options instructs gcc to not generate -the missing instructions. All of the RTEMS code is built this way. Some -of the missing functionality must be supplied by external libraries. The -required functions are part of libgcc.a. - -The issue gets complicated because libc, libm and libgcc do not come as -m68040-specific variants. The default variants of these libraries are for the -MC68020 and MC68030. There are specific variants for the MC68000 (which has -limited addressing modes with respect to later family members), and specific -variants for systems without a floating-point unit, either a built-in FPU or -a coprocessor. These latter variants will be referred to as the msoft-float -variants. There is a msoft-float variant for the MC68000, and one for the -other family members. - -The default variants of libc, libm and libgcc appear to work just fine for the -MC68040, AS LONG AS NO FLOATING POINT FUNCTIONS ARE CALLED. In particular, -printf() and scanf() raise unimplemented floating-point instruction exceptions -at run time. Expect almost every function that must compute a floating-point -result to also raise unimplemented floating-point instruction exceptions. Do -not use these variants if your application does any floating-point operations, -unless you use the Motorola FPSP package (described further down). - -The msoft-float variants do print out floating-point numbers properly, but we -have not tested them extensively, so use them with caution. In particular, -the Paranoia test fails when linked with the msoft-float variants of the -libraries; it goes into an infinite loop after milestone 40. - -MSOFT_FLOAT VARIANTS MUST BE USED TOGETHER. If you use the msoft-float variant -of libc and libm, you must also linked with the msoft-float variant of libgcc, -otherwise calls such as printf() print out floating-point values incorrectly. - -RTEMS comes with the Motorola FPSP (Floating-Point Support Package) for the -MC68040 (rtems/c/src/lib/libcp/m68k/m68040/fpsp). This package emulates the -missing floating-point instructions. It is built automatically for the -MVME167 and installed in bsp_start(). - -The FPSP allows the use of the default variants of libc, libm and libgcc. -It also runs the paranoia test properly, and prints out the correct results. -It should probably be used in preference to the msoft-float libraries, as it -appears to work better. The disadvantage of the FPSP is that it increases the -size of the executable by about 60KB and that it relies on run time -exceptions. - -If your application does not do any floating-point operations at all, you -should consider disabling the FPSP. In bsp_start(), emove the call to -M68KFPSPInstallExceptionHandlers(), and uncomment the three lines in -mvme167.cfg that redefine which variants of libc, libm and libgcc to link -against. - - -Configuration Parameters ------------------------- - -If Jumper J1-4 is installed, certain configuration parameters may be read from -the first 31 bytes of User Area NVRAM starting at 0xFFFC0000. In this case, the -remaining J1-[5-7] jumpers are ignored, and the user is responsible for writing -the appropriate values in NVRAM (via 167-Bug) in order to alter the default -behaviour. A zero value in NVRAM results in the default behaviour. The paramaters -that are configurable and their default settings are described below. - - Cache Mode (0xFFFC0000 - 1 byte) - Set the following bits in the byte to set the desired cache mode: - bit 0 - 0 - data cache disable - 1 - data cache enable - bit 1 - 0 - instruction cache disable - 1 - instruction cache enable - bits 2 & 3: - 00 = cachable, write-through - 01 = cachable, copyback - 10 = noncachable, serialized - 11 = noncachable - - Console driver I/O mode (0xFFFC0001 - 1 byte) - Set the following bits in the byte to set the desired I/O mode: - bit 0 - 0 - do not use termios - 1 - use termios - bit 1 - 0 - polled I/O - 1 - interrupt-driven I/O - - Console driver ports (0xFFFC0002 - 1 byte) - Set the following bits in the byte to select the console and printk ports: - bit 0 & 1 select the RTEMS console port - 00 - /dev/tty0, Serial Port 1/Console on the MVME712M. - 01 - /dev/tty1, Serial Port 2/TTY01 on the MVME712M. - 10 - /dev/tty2, Serial Port 3 on the MVME712M. - 11 - /dev/tty3, Serial Port 4 on the MVME712M. - bit 4 & 5 select the RTEMS printk port - 00 - /dev/tty0, Serial Port 1/Console on the MVME712M. - 01 - /dev/tty1, Serial Port 2/TTY01 on the MVME712M. - 10 - /dev/tty2, Serial Port 3 on the MVME712M. - 11 - /dev/tty3, Serial Port 4 on the MVME712M. - 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. - - IP Address (0xFFFC0004 - 4 bytes) - write the hexadecimal representation of the IP address of the board in this - locatio, e.g. 192.168.1.2 = 0xC0A80102 - default: obtain the IP address from an rtems_bsdnet_ifconfig structure - - Netmask (0xFFFC0008 - 4 bytes) - write the hexadecimal representation of the netmask in this location - for example, 255.255.255.0 = 0xFFFFFF00 - default: obtain the netmask from an rtems_bsdnet_ifconfig structure - - Ethernet Address (0xFFFC000C - 6 bytes) - write the Ethernet address of the board in this location - default: obtain the hardware address from an rtems_bsdnet_ifconfig - structure - - Processor ID (0xFFFC0012 - 2 bytes) - reserved for future use - - RMA start (0xFFFC0014 - 4 bytes) - reserved for future use - - VMA start (0xFFFC0018 - 4 bytes) - reserved for future use - - RamSize (0xFFFC001C - 4 bytes) - reserved for future use - - -Cache Control and Memory Mapping --------------------------------- - -If configuration is not obtained from non-volatile RAM (ie. J1-4 is off), -cache control is done through the remaining J1 jumpers as follows: - -If Jumper J1-7 is installed, the data cache will be turned on. If Jumper -J1-6 is installed, the instruction cache will be turned on. (If a jumper -is off, its corresponding cache will remain disabled). - -If Jumper J1-5 is installed, the data cache will be placed in copyback -mode. If it is removed, it will be placed in writethrough mode. - -Currently, block address translation is set up to map the virtual -0x00000000--0x7FFFFFFF to the physical range 0x00000000--0x7FFFFFFF. The -port relies on the hardware to raise exceptions when addressing -non-existent memory. Caching is not controllable on a finer grain. - - -Networking ----------- - -If configuration is not obtained from non-volatile RAM (ie. J1-4 is off), -the networking parameters shown above must be specified in an initialized -rtems_bsdnet_ifconfig struct. This structure is declared and initialized to -specify any network devices and includes entries for ip_address, ip_netmask -and hardware_address. See the Network Device Configuration section of the -RTEMS Networking Supplement. - -When non-default (non-zero) networking paramaters are provided in NVRAM (ie. -j1-4 is on), the user MUST ensure that the corresponding entries in the -ifconfig struct are NULL. Failing to do so is an error, because it causes -the memory allocated for the initialized struct values to be lost. - - -Miscellaneous -------------- - -The timer and clock drivers were patterned after the MVME162 and MVME152 -ports. - -At this time, we do not have an MPCI layer for the MVME167. We are planning -to write one. - -This port supplies its own fatal_error_handler, which attempts to print some -error message through 167Bug (on the Serial Port 1/Console on the MVME712M). - - -Host System ------------ - -The port was initially developed on an RS-6000 running AIX 4.2. The following -tools were used: - - - GNU gcc 2.8.1 configured for a powerpc-ibm-aix4.2.0.0 host and - m68k-rtems target; - - GNU binutils 2.9.1 configured for a powerpc-ibm-aix4.2.0.0 host and - m68k-rtems target; - -It was also tested on a Pentium II-based PC running Windows NT Workstation 4.0 -and the Cygnus Cygwin32 release b20.1 environment, with the following tools: - - - EGCS 1.1.1 configured for a i586-cygwin32 host and m68k-rtems target; - - GNU binutils 2.9.4 configured for a i586-cygwin32 host and m68k-rtems - target; - -With the latter environment, be patient; builds take a very looong time... - -Current development is done on a Pentium III PC running RedHat Linux 6.1. -At the time this README was composed, the latest working compiler that was -used successfully was gcc version 2.96 20000213 (experimental). Both the C -and C++ compilers were working. Binutils 2.10 are used. - - -Known Problems --------------- - -Polled I/O without termios may not work very well on input. The problem -is that input processing is not done: applications may get characters too -early, and may get characters that they normally would not get, such as -backspace or delete. Furthermore, input is not buffered at all. The latest -versions of rtems seem to set the count field in the rtems_libio_rw_args_t -argument to the buffer size, not to the number of characters expected on -input. Rather than wait for 1024 characters on each call, the driver -returns each character when it is received. - -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. - -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). - -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 is new ------------ - -Support for Java is being actively worked on. - - -Thanks ------- - -- to On-Line Applications Research Corporation (OAR) for developing -RTEMS and making it available on a Technology Transfer basis; - -- to FSF and Cygnus Support for great free software; - - -Test Configuration ------------------- - -Board: Motorola MVME167 -CPU: Motorola MC68040 -Clock Speed: 25 MHz -RAM: 4 MBytes of 32-bit DRAM with parity -Cache Configuration: Instruction cache on; data cache on, copyback mode. -Times Reported in: microseconds -Timer Source: VMEchip2 Tick Timer 1 -GCC Flags: -m68040 -g -O4 -fomit-frame-pointer -Console: Operate in polled mode. Set CD2401_POLLED_IO to 1 in - rtems/c/src/lib/libbsp/m68k/mvme167/console/console.c. - - -Test Results ------------- - -Single processor tests: All tests passed, except the following ones: - - - paranoia required the FPSP and the default variants of libm (and libc and - libgcc) for us. It may work with the msoft-float variants for you, but it - does require the FPSP. - - - 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 -- No MPCI layer yet. - - -Timing tests: See rtems/c/src/lib/libbsp/m68k/mvme167/times - -- cgit v1.2.3