source: rtems/c/src/lib/libbsp/i386/pc386/HOWTO @ 7150f00f

4.104.114.84.95
Last change on this file since 7150f00f was 7150f00f, checked in by Joel Sherrill <joel.sherrill@…>, on Dec 1, 1997 at 10:06:48 PM

Inclusion of PC386 BSP submitted by Pedro Miguel Da Cruz Neto Romano
<pmcnr@…> and Jose Rufino <ruf@…>
of NavIST (http://pandora.ist.utl.pt/).

  • Property mode set to 100644
File size: 18.8 KB
Line 
1#
2#  $Id$
3#
4
5Joel's Note:
6
7This has some information which is specific to 3.6.0.  Other parts of the
8document should be merged with the main RTEMS READMEs.  Procedures for
9building a boot floppy, from a network server, and other information
10specific to this BSP should remain in this file.
11
12-----------
13
14RTEMS PC386 BSP HOWTO:
15
161. Introduction
17---------------
18
19    This howto tries to explain how to setup the RTEMS host
20environment on a Linux based PC so that RTEMS applications can be
21built for and run in a bare PC 386+.
22
23    Please note that everything in the following text using the
24notation '<...>' is just an alias to something and should always be
25substituted by the real thing!
26
272. Unarchiving
28--------------
29
30    Files which have been "tarred, zipped" (i.e. .tar.gz or .tgz
31extension) may be unarchived with a command similar to one of the
32following:
33
34      gzcat <file>.tgz | tar xvof -
35
36    OR
37
38      gunzip -c <file>.tgz | tar xvof -
39
40    OR
41
42      gtar xzvf <file>.tgz
43
44    NOTE: gunzip -c is equivalent to gzcat, while gtar is GNU tar.
45
46    Given that the necessary utility programs are installed, any of
47the above commands will extract the contents of <file>.tar.gz into the
48current directory. All of the RTEMS components will be extracted into
49the subdirectory rtems-3.2.0. To view the contents of a component
50without restoring any files, use a command similar to the following:
51
52      gzcat <file>.tgz | tar tvf -
53
543. The building tools (gcc, binutils, et al.)
55---------------------------------------------
56
57    The PC386 BSP was developed so that the Linux native building
58tools can be used to build the RTEMS binaries.
59
60    With this in mind all you have to do is check if you have gcc +
61binutils (as, ld, ar, objcopy) installed in your system (which most
62probably you'll have) and check their versions. You can do so with:
63
64    - 'gcc -v' (for gcc);      --> version 2.7.2.1
65    - 'ld -v'  (for binutils). --> version 2.8.1 (with BFD linux-2.8.1.0.1)
66
67    The above mentioned versions of gcc and binutils are almost
68certainly guaranteed to work (their the ones we've been using). More
69recent versions should also be ok, and older versions may be ok too.
70
71    The only known problem is with older versions of binutils which
72still don't have a 'binary' target in 'objcopy'. We need objcopy's
73binary target to produce our final binaries (this will probably be
74enhanced in the future, so we get them directly from the 'elf32-i386'
75object, but for now this is how we do it). There's a possible
76workaround this, using older versions of 'objdump' with the flags used
77to produce the Linux kernel binary. You can investigate this in the
78Linux source makefiles. This hasn't been tested.
79
80    It should be ok to build a cross-compilation environment (gcc +
81binutils) that supports the 'elf32-i386' target, so that you can use a
82host system other than Linux. This hasn't been tested.
83
84    You can get 'gcc' and 'binutils', both pre-compiled binaries for
85Linux and sources from:
86
87    ftp://sunsite.unc.edu/pub/Linux/GCC/
88
89      binutils-2.8.1.0.1.bin.tar.gz
90      binutils-2.8.1.0.1.tar.gz
91      gcc-2.7.2.1.bin.tar.gz
92
93as well as from several other mirrors and sites.
94
954. Creating aliases for gcc and the binutils
96--------------------------------------------
97
98    The NEWLIB expects to be compiled by a cross-compiler. The easiest
99(as far as we could find out) way to do this, short of changing the
100configuration files is to make symbolic links from cross-compiler
101style names (the usual names with a 'i386-elf32-rtems-' prefix) to the
102real name.
103
104    You can use the following shell script to create these links
105quickly. It assumes that the native Linux 'gcc' and 'binutils' reside
106in their usual place (i.e. '/usr/bin/'). It also assumes that you're
107running it in the directory where the aliases will reside (which we
108will refer to as <elf32-tools>). You should then add <elf32-tools> to
109you path. This is necessary for building the NEWLIB package.
110
111--- CUT HERE --- CUT HERE --- CUT HERE --- CUT HERE --- CUT HERE ---
112
113#!sh
114ln -sf /usr/bin/ar i386-elf32-rtems-ar
115ln -sf /usr/bin/as i386-elf32-rtems-as
116ln -sf /usr/bin/cpp i386-elf32-rtems-cpp
117ln -sf /usr/bin/gasp i386-elf32-rtems-gasp
118ln -sf /usr/bin/gcc i386-elf32-rtems-gcc
119ln -sf /usr/bin/ld i386-elf32-rtems-ld
120ln -sf /usr/bin/objcopy i386-elf32-rtems-objcopy
121ln -sf /usr/bin/objdump i386-elf32-rtems-objdump
122ln -sf /usr/bin/ranlib i386-elf32-rtems-ranlib
123
124--- CUT HERE --- CUT HERE --- CUT HERE --- CUT HERE --- CUT HERE ---
125 
1265. Building Newlib
127------------------
128
129    The next step is to build and install the NEWLIB package. The
130version we've been using and have tested is:
131
132      newlib-1.7.0-posix-rtems-3.6.0.tgz
133
134    You can get it from:
135
136      ftp://lancelot.gcs.redstone.army.mil/pub/rtems/releases/current/c/
137
138    After unarchiving the NEWLIB distribution (discussed earlier), the
139NEWLIB package must be configured for the desired host and target.
140
141    This is accomplished by changing the current directory to the top
142level of the NEWLIB source tree and executing the configure script
143with the appropriate arguments. This step configures the NEWLIB source
144for the 'i386-elf32-rtems' target configuration. The libraries and
145include files will be installed at <install_point>. The --verbose
146option to the ./configure script is recommended so you can check how
147the configuration process is progressing. Meanwhile we must do a
148little patching: 'install.sh' and 'config.sub' are missing from the
149'libgloss' sub-directory. A command sequence similar to the following
150should be used:
151
152      cd newlib-<NEWLIB_Version>
153
154      cp configure.sub libgloss
155      cp install.sh libgloss
156
157      CC=gcc CFLAGS="-O4 -g" ./configure --verbose \
158             --target=i386-elf32-rtems \
159             --prefix=<install_point>
160
161    If the configure script successfully completes, then NEWLIB may be
162built. This step builds the NEWLIB package in the local directory and
163does NOT install any files. The example commands specifies that gcc
164should be used as the C compiler and the arguments to be used by gcc.
165
166    A command similar to the following should be used:
167
168      make CC="gcc" CFLAGS="-O4 -g"
169
170    If the build process successfully completes, then the NEWLIB
171package is ready to install. A command similar to the following should
172be used:
173
174      make CC="gcc" CFLAGS="-O4 -g" install
175
176    If this successfully completes, then the NEWLIB package has been
177installed at <install_point>.
178
179    The documentation for the NEWLIB package is formatted using
180TeX. If TeX and some supporting tools are installed on the development
181system, then the following command may be used to produce the
182documentation in the "DVI" format:
183
184      gmake CC="gcc" CFLAGS="-O4 -g" dvi
185
186    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.
187
1886. Modules
189----------
190
191    Modules eases the process of manipulating the environment
192variables required to build RTEMS. If, for whatever reason, you do not
193wish to use Modules, then it will be necessary to manually modify
194shell initialization files and set the required RTEMS shell variables
195"manually." In this case, the Modules files are still the best place
196to look for information on what variables to set and example values.
197
198    The Modules package was utilized by the RTEMS developers to make
199the initialization process shell independent. The Modules files used
200by the RTEMS developers to configure their user environment while
201working on a particular target board are included in the
202distribution. These require only simple modifications to be
203"localized" for the RTEMS developer. The modifications to these ASCII
204files can be made with an editor such as vi or emacs.
205
206    The Modules Homepage is:
207
208      http://www.modules.org/
209
210    You can get the Modules distribution (the latest version, which
211we've been using, is '3.0pre') via the homepage or directly from:
212
213      ftp://ftp.modules.org/pub/distrib/Modules-3.0pre.tar.gz
214
215
216    6.1. New Modules users
217    ----------------------
218
219    Install Modules on the development system following the
220instructions in the file README in the main Modules directory. When
221Modules has been installed and a user account setup to use Modules,
222then proceed to the section Current Modules Users.
223
224    6.2. Current Modules users
225    --------------------------
226
227    If the host computer already utilizes the Modules package, then
228the assistance of the system administrator responsible for the Modules
229package will be required to perform the modifications described below.
230
231    The system administrator must integrate the RTEMS modules into the
232existing Modules configuration. A first alternative is to copy all of
233the module files provided with RTEMS into an existing modulefiles
234directory. This requires that future updates of RTEMS modules will
235also have to be integrated into the existing modulefiles
236directory. This alternative is not recommended.
237
238    The more preferable alternative is to add the RTEMS modulefiles
239directory to the MODULEPATH. This can be accomplished on an individual
240user or system wide basis. For individual users, the RTEMS modules
241directory can be added to the MODULEPATH of those users requiring
242access to RTEMS. The default MODULEPATH is established by the Modules
243initialization routine. Thus, the RTEMS modules directory must be
244added to the MODULEPATH in the user's shell initialization file
245(~/.profile or ~/.cshrc for example) following the Modules
246initialization statement. The proper way to accomplish this is to use
247the Modules use statement. For example, the following line should be
248added to the user's shell initialization file:
249
250      module use <rtems_path>/modules/modulefiles
251
252    For system wide access, the RTEMS modulefiles directory can be
253added to each of the shell initialization scripts in the existing
254Modules package. This will require modifying the initialization of
255MODULEPATH in each shell initialization file.
256
257    After integrating RTEMS modules with the existing modules, one may
258proceed to the Configuring An RTEMS User section.
259
2607. RTEMS
261--------
262
263    You can get the latest free release of the C distribuition of
264RTEMS (version 3.6.0), from:
265
266      ftp://lancelot.gcs.redstone.army.mil/pub/rtems/releases/current/c/
267
268    Where you'll find:
269
270      rtems-3.6.0.tgz    or    rtems-c_src.tgz - RTEMS sources;
271
272      rtems-3.5.1-c_doc.tgz or rtems-c_doc.tgz - RTEMS documentation;
273
274      individual_manuals/ - Sub-directory where you can get the
275                            manuals individually.
276
277    Please note that the RTEMS documentation is slightly outdated
278(most noticeably some RTEMS primitives have different protoypes) since
279it refers to the previous release (3.5.1.) of RTEMS.
280
281    After unarchiving the RTEMS distribution (discussed earlier), it
282is necessary to add the PC386 BSP to the source tree. This is done in
283two steps.
284
285    The first step consists in unarchiving the
286'rtems-3.6.0-PC386-BSP.tgz' archive over the standard rtems-3.6.0
287distribution. It should be done in the same directory where
288'rtems-3.6.0.tgz' was unarchived.
289
290    Next you'll need to apply the patch in
291'rtems-3.6.0-PC386-BSP.diff.gz' to the RTEMS source tree. The
292following command should be used:
293
294      gzip -d -c rtems-3.6.0-PC386-BSP.diff.gz | patch
295
296also from the same directory where 'rtems-3.6.0.tgz' was unarchived.
297
298    At this stage we have RTEMS + PC386 BSP, the user environment must
299be setup to build and install RTEMS.
300
301    Using this process, you'll know which files are patched and which
302files are new.
303
304    7.1. Board Support Package
305    --------------------------
306
307    A Board Support Package (BSP) is a collection of device drivers,
308initialization code, and linker scripts necessary to execute RTEMS on
309a particular target board. The minimum set of device drivers for a
310single processor target includes a Clock, Console I/O, and Benchmark
311Timer device drivers.
312
313    The source code for the PC386 BSP can be found in the directory 'c/src/lib/libbsp/i386/pc386.
314
315    7.2. Makefile Configuration Files
316    ---------------------------------
317
318    There are two target specific configuration files used by the
319Makefile system. These configuration files specify detailed
320information about the toolset, the compilation process, as well as
321some general configuration information regarding the target and the
322development environment. The following is a list of these
323configuration files:
324
325      c/make/compilers/gcc-pc386.cfg
326
327      c/make/custom/pc386.cfg
328
329    If you're compiling to a i386+ with FPU in a standard Linux
330environment, you shouldn't require any changes to these files in order
331to build RTEMS (though you'll probably want to fine tune them later
332on).
333
334    7.3 Creating a Customized Modules File
335    --------------------------------------
336
337    Files which the Modules packages may use to customize a user's
338environment for building, installing, and modifying RTEMS are found in
339the c/Modules/rtems directory. Each of the files in this directory
340corresponds to the configuration used by the RTEMS developers for
341building and installing RTEMS for a particular target board. These
342files contain the Modules commands necessary to set the following
343environment variables:
344
345       Variable                      Description
346
347      RTEMS_BSP            The name of the target BSP (e.g.
348                                 mvme136 or cvme961).
349
350      RTEMS_ROOT        The full path of root directory of the
351                                  RTEMS source code.
352
353    RTEMS_GNUTOOLS     The full path of the root directory for
354                         the cross-development toolset to be
355                                        used.
356
357      RTEMS_HOST         The name of the operating system for
358                               the development system.
359
360    RTEMS_LIBC_DIR     The full path of the root directory for
361                          the Standard C Library to be used.
362
363
364    The Modules file for the PC386 BSP is: 'c/Modules/rtems/nav-pc386'.
365
366    You MUST edit this file and set the following variables to the
367correct values in your system:
368
369      - RTEMS_ROOT;
370      - RTEMS_GNUTOOLS (this is the directory where the links in 4.
371                        were created);
372      - RTEMS_LIBC_DIR (this is the directory where the Newlib target
373                        specific root is installed, and with reference
374                        to 5. should be '<install_point>/i386-elf32-rtems').
375 
376    7.4 Configuring an RTEMS User Using Modules
377    -------------------------------------------
378
379    Each user building and installing RTEMS must have their
380environment configured. The user environment must have a set of
381variables set in it which indicate the target BSP, host operating
382system, and numerous paths.
383
384    If you'll just be using the PC386 BSP then a line of the following
385type may be added to the initialization file for your shell after the
386Modules initialization statement.
387
388     module load nav-pc386
389
390    Note that you must logout and login before any changes to the shell
391initialization files will take effect.
392
393    If you don't wish the RTEMS environment configuration to be added
394to your shell initialization file, then the "module load" statement
395may be entered at the command line.
396
397    You may switch from one RTEMS configuration to another with either
398of the following command sequences:
399
400      module unload <old_rtems_modulefile>
401      module load <new_rtems_modulefile>
402
403    OR
404
405      module switch <old_rtems_modulefile> <new_rtems_modulefile>
406
407    The command "module avail" may be used to obtain a list of the
408Module files which are available to be loaded using the "module load"
409command.
410
411    The command "module list" provides a list of the currently loaded
412Modules.
413 
414    7.5. Building RTEMS
415    -------------------
416
417    By default, the PC386 RTEMS BSP is installed into the directory
418'c/pc386_i386'. If this is not the desired installation point, then
419modify the following line in the file 'c/make/custom/pc386.cfg':
420
421      PROJECT_HOME=$(PROJECT_ROOT)/$(RTEMS_BSP)
422
423    Once the root directory of the install point has been set, the
424following steps are required to build and install RTEMS (NOTE: If the
425Modules files are used, the environment variable '$r' is set to point
426to the top directory for the RTEMS implementation selected in the
427current environment. This is the directory 'c' in the RTEMS
428distribution.):
429
430      cd $r
431      make install
432
433    If this completes successfully, then RTEMS has been built and
434installed.
435
4368. RTEMS Tests
437--------------
438
439    If you've completed the last step successfully, you'll find the
440RTEMS sample and test files in the 'c/pc386_i386/tests' directory.
441
442    The 'sp*.bt' are the single processor tests and should all work
443correctly. The same applies to the 'tm*.bt' which are the timing
444tests.
445
446    The other sample ('*.bt') files should also work with the
447exception of 'spfatal.bt' and 'stackchk.bt' (see 9.).
448
449    To load the '*.bt' files you can either run the 'diskboot.exe'
450(which can be found in 'c/pc386_i386/build-tools') under DOS with a
451command line like (this is just a quick and dirty loader - you'll have
452to press return twice after entering it):
453
454      diskboot sp01.bt
455
456    Alternatively, if you have a PC connected to a network with a
457BOOTP server and a TFTP server (this can very well be you're Linux
458RTEMS host system), you can use Gero Kuhlmann's netboot loader, to
459load RTEMS to a diskless PC across a network. You can get it from:
460
461      ftp://sunsite.unc.edu/pub/Linux/system/boot/netboot-0.7.2.tar.gz
462
463    Follow the instructions contained in the package to setup the
464server(s) and to build a boot ROM for the client PC network card, or a
465boot diskette, and the client should be able to load the '*.bt' files
466from the server.
467
468    For the network loader every relocation address from 0x10200 to
4690x80200 are known to work correctly. For the DOS loader, relocation
470addresses 0x20200, 0x40200 and 0x80200 are known to work under DOS
4715.00, DOS 6.xx and DOS 7.00. You can set the relocation address in
472'c/make/compilers/gcc-pc386.cfg' by setting the value of the
473'RELOCADDR' variable.
474 
4759. Important Notes
476------------------
477
478    The optional stack checker extension ('stackchk') doesn't seem to
479be working properly. It reports blown task stacks even if everything
480seems to work properly when 'stackchk' isn't activated... This should
481be properly investigated: the problem can reside with the 'PC386 BSP',
482or in the interface between 'stackchk' and the BSP (maybe something
483isn't being correctly initialized...). Since this doesn't seem to be a
484serious BSP problem, it hasn't been dealt with, due to more prioritary
485problems.
486
487    The tests which exercise the fatal error mecanisms don't work
488correctly either. I've been told by Joe that 'spfatal' is outdated, and
489so this really isn't surprising.
490
491    This issues may be important and should be investigated as soon as
492possible.
493
494    When programming interrupt handlers take into account that the PIC
495is reprogrammed and so you should use the interface functions provided
496to garantee that everything works ok.
Note: See TracBrowser for help on using the repository browser.