Inclusion of PC386 BSP submitted by Pedro Miguel Da Cruz Neto Romano

<pmcnr@camoes.rnl.ist.utl.pt> and Jose Rufino <ruf@asterix.ist.utl.pt>
of NavIST (http://pandora.ist.utl.pt/).

1 files changed, 496 insertions, 0 deletions

diff --git a/c/src/lib/libbsp/i386/pc386/HOWTO b/c/src/lib/libbsp/i386/pc386/HOWTO
new file mode 100644
index 0000000000..1c239b6f92
--- /dev/null
+++ b/c/src/lib/libbsp/i386/pc386/HOWTO
@@ -0,0 +1,496 @@
+#
+#  $Id$
+#
+
+Joel's Note:
+
+This has some information which is specific to 3.6.0.  Other parts of the
+document should be merged with the main RTEMS READMEs.  Procedures for
+building a boot floppy, from a network server, and other information
+specific to this BSP should remain in this file.
+
+-----------
+
+RTEMS PC386 BSP HOWTO:
+
+1. Introduction
+---------------
+
+    This howto tries to explain how to setup the RTEMS host
+environment on a Linux based PC so that RTEMS applications can be
+built for and run in a bare PC 386+.
+
+    Please note that everything in the following text using the
+notation '<...>' is just an alias to something and should always be
+substituted by the real thing!
+
+2. Unarchiving
+--------------
+
+    Files which have been "tarred, zipped" (i.e. .tar.gz or .tgz
+extension) may be unarchived with a command similar to one of the
+following:
+
+      gzcat <file>.tgz | tar xvof -
+
+    OR
+
+      gunzip -c <file>.tgz | tar xvof -
+
+    OR
+
+      gtar xzvf <file>.tgz
+
+    NOTE: gunzip -c is equivalent to gzcat, while gtar is GNU tar.
+
+    Given that the necessary utility programs are installed, any of
+the above commands will extract the contents of <file>.tar.gz into the
+current directory. All of the RTEMS components will be extracted into
+the subdirectory rtems-3.2.0. To view the contents of a component
+without restoring any files, use a command similar to the following:
+
+      gzcat <file>.tgz | tar tvf -
+
+3. The building tools (gcc, binutils, et al.)
+---------------------------------------------
+
+    The PC386 BSP was developed so that the Linux native building
+tools can be used to build the RTEMS binaries.
+
+    With this in mind all you have to do is check if you have gcc +
+binutils (as, ld, ar, objcopy) installed in your system (which most
+probably you'll have) and check their versions. You can do so with:
+
+    - 'gcc -v' (for gcc);      --> version 2.7.2.1
+    - 'ld -v'  (for binutils). --> version 2.8.1 (with BFD linux-2.8.1.0.1)
+
+    The above mentioned versions of gcc and binutils are almost
+certainly guaranteed to work (their the ones we've been using). More
+recent versions should also be ok, and older versions may be ok too.
+
+    The only known problem is with older versions of binutils which
+still don't have a 'binary' target in 'objcopy'. We need objcopy's
+binary target to produce our final binaries (this will probably be
+enhanced in the future, so we get them directly from the 'elf32-i386'
+object, but for now this is how we do it). There's a possible
+workaround this, using older versions of 'objdump' with the flags used
+to produce the Linux kernel binary. You can investigate this in the
+Linux source makefiles. This hasn't been tested.
+
+    It should be ok to build a cross-compilation environment (gcc +
+binutils) that supports the 'elf32-i386' target, so that you can use a
+host system other than Linux. This hasn't been tested.
+
+    You can get 'gcc' and 'binutils', both pre-compiled binaries for
+Linux and sources from:
+
+    ftp://sunsite.unc.edu/pub/Linux/GCC/
+
+      binutils-2.8.1.0.1.bin.tar.gz
+      binutils-2.8.1.0.1.tar.gz
+      gcc-2.7.2.1.bin.tar.gz
+
+as well as from several other mirrors and sites.
+
+4. Creating aliases for gcc and the binutils
+--------------------------------------------
+
+    The NEWLIB expects to be compiled by a cross-compiler. The easiest
+(as far as we could find out) way to do this, short of changing the
+configuration files is to make symbolic links from cross-compiler
+style names (the usual names with a 'i386-elf32-rtems-' prefix) to the
+real name.
+
+    You can use the following shell script to create these links
+quickly. It assumes that the native Linux 'gcc' and 'binutils' reside
+in their usual place (i.e. '/usr/bin/'). It also assumes that you're
+running it in the directory where the aliases will reside (which we
+will refer to as <elf32-tools>). You should then add <elf32-tools> to
+you path. This is necessary for building the NEWLIB package.
+
+--- CUT HERE --- CUT HERE --- CUT HERE --- CUT HERE --- CUT HERE ---
+
+#!sh
+ln -sf /usr/bin/ar i386-elf32-rtems-ar
+ln -sf /usr/bin/as i386-elf32-rtems-as
+ln -sf /usr/bin/cpp i386-elf32-rtems-cpp
+ln -sf /usr/bin/gasp i386-elf32-rtems-gasp
+ln -sf /usr/bin/gcc i386-elf32-rtems-gcc
+ln -sf /usr/bin/ld i386-elf32-rtems-ld
+ln -sf /usr/bin/objcopy i386-elf32-rtems-objcopy
+ln -sf /usr/bin/objdump i386-elf32-rtems-objdump
+ln -sf /usr/bin/ranlib i386-elf32-rtems-ranlib
+
+--- CUT HERE --- CUT HERE --- CUT HERE --- CUT HERE --- CUT HERE ---
+ 
+5. Building Newlib
+------------------
+
+    The next step is to build and install the NEWLIB package. The
+version we've been using and have tested is:
+
+      newlib-1.7.0-posix-rtems-3.6.0.tgz
+
+    You can get it from:
+
+      ftp://lancelot.gcs.redstone.army.mil/pub/rtems/releases/current/c/
+
+    After unarchiving the NEWLIB distribution (discussed earlier), the
+NEWLIB package must be configured for the desired host and target.
+
+    This is accomplished by changing the current directory to the top
+level of the NEWLIB source tree and executing the configure script
+with the appropriate arguments. This step configures the NEWLIB source
+for the 'i386-elf32-rtems' target configuration. The libraries and
+include files will be installed at <install_point>. The --verbose
+option to the ./configure script is recommended so you can check how
+the configuration process is progressing. Meanwhile we must do a
+little patching: 'install.sh' and 'config.sub' are missing from the
+'libgloss' sub-directory. A command sequence similar to the following
+should be used:
+
+      cd newlib-<NEWLIB_Version>
+
+      cp configure.sub libgloss
+      cp install.sh libgloss
+
+      CC=gcc CFLAGS="-O4 -g" ./configure --verbose \
+             --target=i386-elf32-rtems \
+             --prefix=<install_point>
+
+    If the configure script successfully completes, then NEWLIB may be
+built. This step builds the NEWLIB package in the local directory and
+does NOT install any files. The example commands specifies that gcc
+should be used as the C compiler and the arguments to be used by gcc.
+
+    A command similar to the following should be used:
+
+      make CC="gcc" CFLAGS="-O4 -g"
+
+    If the build process successfully completes, then the NEWLIB
+package is ready to install. A command similar to the following should
+be used:
+
+      make CC="gcc" CFLAGS="-O4 -g" install
+
+    If this successfully completes, then the NEWLIB package has been
+installed at <install_point>.
+
+    The documentation for the NEWLIB package is formatted using
+TeX. If TeX and some supporting tools are installed on the development
+system, then the following command may be used to produce the
+documentation in the "DVI" format:
+
+      gmake CC="gcc" CFLAGS="-O4 -g" dvi
+
+    If while the documentation is being formatted, the message "Cross reference values unknown; you must run TeX again." is printed, then the "DVI" files generated by this command (e.g. *.dvi in every subdirectory with documentation) must be removed and the command reexecuted.
+
+6. Modules
+----------
+
+    Modules eases the process of manipulating the environment
+variables required to build RTEMS. If, for whatever reason, you do not
+wish to use Modules, then it will be necessary to manually modify
+shell initialization files and set the required RTEMS shell variables
+"manually." In this case, the Modules files are still the best place
+to look for information on what variables to set and example values.
+
+    The Modules package was utilized by the RTEMS developers to make
+the initialization process shell independent. The Modules files used
+by the RTEMS developers to configure their user environment while
+working on a particular target board are included in the
+distribution. These require only simple modifications to be
+"localized" for the RTEMS developer. The modifications to these ASCII
+files can be made with an editor such as vi or emacs.
+
+    The Modules Homepage is:
+
+      http://www.modules.org/
+
+    You can get the Modules distribution (the latest version, which
+we've been using, is '3.0pre') via the homepage or directly from:
+
+      ftp://ftp.modules.org/pub/distrib/Modules-3.0pre.tar.gz
+
+
+    6.1. New Modules users
+    ----------------------
+
+    Install Modules on the development system following the
+instructions in the file README in the main Modules directory. When
+Modules has been installed and a user account setup to use Modules,
+then proceed to the section Current Modules Users.
+
+    6.2. Current Modules users
+    --------------------------
+
+    If the host computer already utilizes the Modules package, then
+the assistance of the system administrator responsible for the Modules
+package will be required to perform the modifications described below.
+
+    The system administrator must integrate the RTEMS modules into the
+existing Modules configuration. A first alternative is to copy all of
+the module files provided with RTEMS into an existing modulefiles
+directory. This requires that future updates of RTEMS modules will
+also have to be integrated into the existing modulefiles
+directory. This alternative is not recommended.
+
+    The more preferable alternative is to add the RTEMS modulefiles
+directory to the MODULEPATH. This can be accomplished on an individual
+user or system wide basis. For individual users, the RTEMS modules
+directory can be added to the MODULEPATH of those users requiring
+access to RTEMS. The default MODULEPATH is established by the Modules
+initialization routine. Thus, the RTEMS modules directory must be
+added to the MODULEPATH in the user's shell initialization file
+(~/.profile or ~/.cshrc for example) following the Modules
+initialization statement. The proper way to accomplish this is to use
+the Modules use statement. For example, the following line should be
+added to the user's shell initialization file:
+
+      module use <rtems_path>/modules/modulefiles
+
+    For system wide access, the RTEMS modulefiles directory can be
+added to each of the shell initialization scripts in the existing
+Modules package. This will require modifying the initialization of
+MODULEPATH in each shell initialization file.
+
+    After integrating RTEMS modules with the existing modules, one may
+proceed to the Configuring An RTEMS User section.
+
+7. RTEMS
+--------
+
+    You can get the latest free release of the C distribuition of
+RTEMS (version 3.6.0), from:
+
+      ftp://lancelot.gcs.redstone.army.mil/pub/rtems/releases/current/c/
+
+    Where you'll find:
+
+      rtems-3.6.0.tgz    or    rtems-c_src.tgz - RTEMS sources;
+
+      rtems-3.5.1-c_doc.tgz or rtems-c_doc.tgz - RTEMS documentation;
+
+      individual_manuals/ - Sub-directory where you can get the
+                            manuals individually.
+
+    Please note that the RTEMS documentation is slightly outdated
+(most noticeably some RTEMS primitives have different protoypes) since
+it refers to the previous release (3.5.1.) of RTEMS.
+
+    After unarchiving the RTEMS distribution (discussed earlier), it
+is necessary to add the PC386 BSP to the source tree. This is done in
+two steps.
+
+    The first step consists in unarchiving the
+'rtems-3.6.0-PC386-BSP.tgz' archive over the standard rtems-3.6.0
+distribution. It should be done in the same directory where
+'rtems-3.6.0.tgz' was unarchived.
+
+    Next you'll need to apply the patch in
+'rtems-3.6.0-PC386-BSP.diff.gz' to the RTEMS source tree. The
+following command should be used:
+
+      gzip -d -c rtems-3.6.0-PC386-BSP.diff.gz | patch
+
+also from the same directory where 'rtems-3.6.0.tgz' was unarchived.
+
+    At this stage we have RTEMS + PC386 BSP, the user environment must
+be setup to build and install RTEMS.
+
+    Using this process, you'll know which files are patched and which
+files are new.
+
+    7.1. Board Support Package
+    --------------------------
+
+    A Board Support Package (BSP) is a collection of device drivers,
+initialization code, and linker scripts necessary to execute RTEMS on
+a particular target board. The minimum set of device drivers for a
+single processor target includes a Clock, Console I/O, and Benchmark
+Timer device drivers.
+
+    The source code for the PC386 BSP can be found in the directory 'c/src/lib/libbsp/i386/pc386.
+
+    7.2. Makefile Configuration Files
+    ---------------------------------
+
+    There are two target specific configuration files used by the
+Makefile system. These configuration files specify detailed
+information about the toolset, the compilation process, as well as
+some general configuration information regarding the target and the
+development environment. The following is a list of these
+configuration files:
+
+      c/make/compilers/gcc-pc386.cfg
+
+      c/make/custom/pc386.cfg
+
+    If you're compiling to a i386+ with FPU in a standard Linux
+environment, you shouldn't require any changes to these files in order
+to build RTEMS (though you'll probably want to fine tune them later
+on).
+
+    7.3 Creating a Customized Modules File
+    --------------------------------------
+
+    Files which the Modules packages may use to customize a user's
+environment for building, installing, and modifying RTEMS are found in
+the c/Modules/rtems directory. Each of the files in this directory
+corresponds to the configuration used by the RTEMS developers for
+building and installing RTEMS for a particular target board. These
+files contain the Modules commands necessary to set the following
+environment variables:
+
+       Variable                      Description
+
+      RTEMS_BSP            The name of the target BSP (e.g.
+                                 mvme136 or cvme961).
+
+      RTEMS_ROOT        The full path of root directory of the
+                                  RTEMS source code.
+
+    RTEMS_GNUTOOLS     The full path of the root directory for
+                         the cross-development toolset to be
+                                        used.
+
+      RTEMS_HOST         The name of the operating system for
+                               the development system.
+
+    RTEMS_LIBC_DIR     The full path of the root directory for
+                          the Standard C Library to be used.
+
+
+    The Modules file for the PC386 BSP is: 'c/Modules/rtems/nav-pc386'.
+
+    You MUST edit this file and set the following variables to the
+correct values in your system:
+
+      - RTEMS_ROOT;
+      - RTEMS_GNUTOOLS (this is the directory where the links in 4.
+                        were created);
+      - RTEMS_LIBC_DIR (this is the directory where the Newlib target
+                        specific root is installed, and with reference
+                        to 5. should be '<install_point>/i386-elf32-rtems').
+ 
+    7.4 Configuring an RTEMS User Using Modules
+    -------------------------------------------
+
+    Each user building and installing RTEMS must have their
+environment configured. The user environment must have a set of
+variables set in it which indicate the target BSP, host operating
+system, and numerous paths.
+
+    If you'll just be using the PC386 BSP then a line of the following
+type may be added to the initialization file for your shell after the
+Modules initialization statement.
+
+     module load nav-pc386
+
+    Note that you must logout and login before any changes to the shell
+initialization files will take effect.
+
+    If you don't wish the RTEMS environment configuration to be added
+to your shell initialization file, then the "module load" statement
+may be entered at the command line.
+
+    You may switch from one RTEMS configuration to another with either
+of the following command sequences:
+
+      module unload <old_rtems_modulefile>
+      module load <new_rtems_modulefile>
+
+    OR
+
+      module switch <old_rtems_modulefile> <new_rtems_modulefile>
+
+    The command "module avail" may be used to obtain a list of the
+Module files which are available to be loaded using the "module load"
+command.
+
+    The command "module list" provides a list of the currently loaded
+Modules.
+ 
+    7.5. Building RTEMS
+    -------------------
+
+    By default, the PC386 RTEMS BSP is installed into the directory
+'c/pc386_i386'. If this is not the desired installation point, then
+modify the following line in the file 'c/make/custom/pc386.cfg':
+
+      PROJECT_HOME=$(PROJECT_ROOT)/$(RTEMS_BSP)
+
+    Once the root directory of the install point has been set, the
+following steps are required to build and install RTEMS (NOTE: If the
+Modules files are used, the environment variable '$r' is set to point
+to the top directory for the RTEMS implementation selected in the
+current environment. This is the directory 'c' in the RTEMS
+distribution.):
+
+      cd $r
+      make install
+
+    If this completes successfully, then RTEMS has been built and
+installed.
+
+8. RTEMS Tests
+--------------
+
+    If you've completed the last step successfully, you'll find the
+RTEMS sample and test files in the 'c/pc386_i386/tests' directory.
+
+    The 'sp*.bt' are the single processor tests and should all work
+correctly. The same applies to the 'tm*.bt' which are the timing
+tests.
+
+    The other sample ('*.bt') files should also work with the
+exception of 'spfatal.bt' and 'stackchk.bt' (see 9.).
+
+    To load the '*.bt' files you can either run the 'diskboot.exe'
+(which can be found in 'c/pc386_i386/build-tools') under DOS with a
+command line like (this is just a quick and dirty loader - you'll have
+to press return twice after entering it):
+
+      diskboot sp01.bt
+
+    Alternatively, if you have a PC connected to a network with a
+BOOTP server and a TFTP server (this can very well be you're Linux
+RTEMS host system), you can use Gero Kuhlmann's netboot loader, to
+load RTEMS to a diskless PC across a network. You can get it from:
+
+      ftp://sunsite.unc.edu/pub/Linux/system/boot/netboot-0.7.2.tar.gz
+
+    Follow the instructions contained in the package to setup the
+server(s) and to build a boot ROM for the client PC network card, or a
+boot diskette, and the client should be able to load the '*.bt' files
+from the server.
+
+    For the network loader every relocation address from 0x10200 to
+0x80200 are known to work correctly. For the DOS loader, relocation
+addresses 0x20200, 0x40200 and 0x80200 are known to work under DOS
+5.00, DOS 6.xx and DOS 7.00. You can set the relocation address in
+'c/make/compilers/gcc-pc386.cfg' by setting the value of the
+'RELOCADDR' variable.
+ 
+9. Important Notes
+------------------
+
+    The optional stack checker extension ('stackchk') doesn't seem to
+be working properly. It reports blown task stacks even if everything
+seems to work properly when 'stackchk' isn't activated... This should
+be properly investigated: the problem can reside with the 'PC386 BSP',
+or in the interface between 'stackchk' and the BSP (maybe something
+isn't being correctly initialized...). Since this doesn't seem to be a
+serious BSP problem, it hasn't been dealt with, due to more prioritary
+problems.
+
+    The tests which exercise the fatal error mecanisms don't work
+correctly either. I've been told by Joe that 'spfatal' is outdated, and
+so this really isn't surprising.
+
+    This issues may be important and should be investigated as soon as
+possible.
+
+    When programming interrupt handlers take into account that the PIC
+is reprogrammed and so you should use the interface functions provided
+to garantee that everything works ok.