1 |
30 |
unneback |
+-----------------------------------------------------------------------------+
|
2 |
|
|
| RTEMS 4.5.0 PC386 BSP HOWTO - 1998/04/21 |
|
3 |
|
|
| |
|
4 |
|
|
+-----------------------------------------------------------------------------+
|
5 |
|
|
| (C) Copyright 1998 - |
|
6 |
|
|
| - NavIST Group - Real-Time Distributed Systems and Industrial Automation |
|
7 |
|
|
| |
|
8 |
|
|
| http://pandora.ist.utl.pt |
|
9 |
|
|
| |
|
10 |
|
|
| Instituto Superior Tecnico * Lisboa * PORTUGAL |
|
11 |
|
|
+-----------------------------------------------------------------------------+
|
12 |
|
|
| Disclaimer: |
|
13 |
|
|
| |
|
14 |
|
|
| This file is provided "AS IS" without warranty of any kind, either |
|
15 |
|
|
| expressed or implied. |
|
16 |
|
|
+-----------------------------------------------------------------------------+
|
17 |
|
|
| History: |
|
18 |
|
|
| 12 June 2000 - Updated to 4.5 (Joel) |
|
19 |
|
|
+-----------------------------------------------------------------------------+
|
20 |
|
|
|
21 |
|
|
CVS Revision: $Id: HOWTO,v 1.2 2001-09-27 11:59:47 chris Exp $
|
22 |
|
|
|
23 |
|
|
|
24 |
|
|
1. Introduction
|
25 |
|
|
---------------
|
26 |
|
|
|
27 |
|
|
This tries to explain how to setup the RTEMS host environment so
|
28 |
|
|
that RTEMS applications can be built for and run in a bare PC 386 or
|
29 |
|
|
above.
|
30 |
|
|
|
31 |
|
|
It covers essentially the aspects of loading images, since
|
32 |
|
|
information concerning other issues such as building the development
|
33 |
|
|
tools and the RTEMS distribution can be found in the 'RTEMS 4.0.0
|
34 |
|
|
On-Line Library' under 'Getting Started with RTEMS for C/C++ Users'.
|
35 |
|
|
|
36 |
|
|
Please note that everything in the following text using the
|
37 |
|
|
notation '<...>' is just an alias to something and should always be
|
38 |
|
|
substituted by the real thing!
|
39 |
|
|
|
40 |
|
|
|
41 |
|
|
2. Building the GNU C/C++ Cross Compiler Toolset
|
42 |
|
|
------------------------------------------------
|
43 |
|
|
|
44 |
|
|
Obtaining, building and installing the tools for building the
|
45 |
|
|
PC386 BSP of RTEMS is covered in detail in the 'RTEMS 4.5.0 On-Line
|
46 |
|
|
Library' -> 'Getting Started with RTEMS for C/C++ Users'. You can
|
47 |
|
|
either use pre-built toolset executables or build your own from
|
48 |
|
|
the instructions given there.
|
49 |
|
|
|
50 |
|
|
This BSP is designed to work only with ELF toolset configurations.
|
51 |
|
|
This is format used by the i386-rtems target.
|
52 |
|
|
|
53 |
|
|
|
54 |
|
|
4. Building RTEMS
|
55 |
|
|
-----------------
|
56 |
|
|
Obtaining, building and installing the tools for building the
|
57 |
|
|
PC386 BSP is covered in detail in the 'RTEMS 4.5.0 On-Line Library' ->
|
58 |
|
|
'Getting Started with RTEMS for C/C++ Users' -> 'Building RTEMS'.
|
59 |
|
|
|
60 |
|
|
When running configure, use the following values for the listed
|
61 |
|
|
options with an i386-rtems toolset:
|
62 |
|
|
|
63 |
|
|
--target=i386-rtems
|
64 |
|
|
--enable-rtemsbsp=pc386
|
65 |
|
|
|
66 |
|
|
|
67 |
|
|
5. RTEMS Tests
|
68 |
|
|
--------------
|
69 |
|
|
|
70 |
|
|
If you've completed the last step successfully, you'll find the
|
71 |
|
|
RTEMS sample and test files that can be loaded with GRUB in the
|
72 |
|
|
'/pc386/tests' directory, RTEMS sample and test files in
|
73 |
|
|
a format suitable for use with NetBoot in the
|
74 |
|
|
'/pc386/BootImgs' directory.
|
75 |
|
|
|
76 |
|
|
|
77 |
|
|
6. Loading RTEMS PC386 applications
|
78 |
|
|
-----------------------------------
|
79 |
|
|
|
80 |
|
|
6.1. Unarchiving
|
81 |
|
|
----------------
|
82 |
|
|
|
83 |
|
|
Files which have been "tarred, gzipped" (i.e. .tar.gz or .tgz
|
84 |
|
|
extension) may be unarchived with a command similar to one of the
|
85 |
|
|
following:
|
86 |
|
|
|
87 |
|
|
zcat .tgz | tar xvof -
|
88 |
|
|
|
89 |
|
|
OR
|
90 |
|
|
|
91 |
|
|
gunzip -c .tgz | tar xvof -
|
92 |
|
|
|
93 |
|
|
OR
|
94 |
|
|
|
95 |
|
|
tar xzvf .tgz
|
96 |
|
|
|
97 |
|
|
NOTE: gunzip -c is equivalent to zcat. On commercial (non-Linux)
|
98 |
|
|
Unices, since the GNU utilities are not the standard 'tar' will be
|
99 |
|
|
gtar (GNU tar) and 'zcat' will be 'gzcat'.
|
100 |
|
|
|
101 |
|
|
Given that the necessary utility programs are installed, any of
|
102 |
|
|
the above commands will extract the contents of .tar.gz into the
|
103 |
|
|
current directory. To view the contents of an archive without
|
104 |
|
|
restoring any files, use a command similar to the following:
|
105 |
|
|
|
106 |
|
|
zcat .tgz | tar tvf -
|
107 |
|
|
|
108 |
|
|
|
109 |
|
|
6.2 Using GRUB to load RTEMS PC386 applications
|
110 |
|
|
-----------------------------------------------
|
111 |
|
|
|
112 |
|
|
Using GRUB (GRand Unified Bootloader) is the simplest way to load
|
113 |
|
|
and run your PC386 BSP samples, tests and programs.
|
114 |
|
|
|
115 |
|
|
You can get the latest release of GRUB from its homepage:
|
116 |
|
|
|
117 |
|
|
- http://www.gnu.org/grub/
|
118 |
|
|
|
119 |
|
|
NOTE: The former location was http://www.uruk.org/grub and ftp from
|
120 |
|
|
ftp://ftp.uruk.org/public/grub.
|
121 |
|
|
|
122 |
|
|
Once you obtain the .tar.gz archive 'grub-0.4.tar.gz', change to a
|
123 |
|
|
temporary directory (you won't need the grub files after this and can
|
124 |
|
|
just go ahead and delete the whole directory structure that was
|
125 |
|
|
generated) and unarchive 'grub-0.4.tar.gz' following the instructions
|
126 |
|
|
given above in [2. Unarchiving].
|
127 |
|
|
|
128 |
|
|
After this is done change the directory to:
|
129 |
|
|
|
130 |
|
|
grub-0.4/bin_std
|
131 |
|
|
|
132 |
|
|
and there you'll find the two files you'll need from this archive:
|
133 |
|
|
'stage1' and 'stage2'.
|
134 |
|
|
|
135 |
|
|
You should have two (2) formatted diskettes available. One of
|
136 |
|
|
these will only be used temporarily to create the other one, and we'll
|
137 |
|
|
refer to it as 'RAW GRUB' diskette (you can label it accordingly if
|
138 |
|
|
you wish). The other diskette, which we will refer to as 'GRUB FS'
|
139 |
|
|
should be high-level formatted with one of GRUB's supported file
|
140 |
|
|
systems, which are: DOS FAT, BSD FFS, and Linux ext2fs.
|
141 |
|
|
|
142 |
|
|
A DOS FAT diskette can, obviously, be created under DOS with the
|
143 |
|
|
'FORMAT' command. Under Linux, the following commands are available to
|
144 |
|
|
add file systems to low-level formatted diskettes:
|
145 |
|
|
|
146 |
|
|
1. To add a DOS FAT file system to a low-level formatted diskette:
|
147 |
|
|
|
148 |
|
|
a) If you have mtools installed:
|
149 |
|
|
|
150 |
|
|
'mformat a:'.
|
151 |
|
|
|
152 |
|
|
b) Assuming that you are formatting the diskette in the first
|
153 |
|
|
floppy disk drive ('/dev/fd0' under Linux):
|
154 |
|
|
|
155 |
|
|
'mkdosfs /dev/fd0' or
|
156 |
|
|
|
157 |
|
|
'mkfs.msdos /dev/fd0'.
|
158 |
|
|
|
159 |
|
|
2. To add a Linux ext2fs file system to a low-level formatted
|
160 |
|
|
diskette, assuming that you are formatting the diskette in the
|
161 |
|
|
first floppy disk drive ('/dev/fd0' under Linux):
|
162 |
|
|
|
163 |
|
|
'mke2fs /dev/fd0' or
|
164 |
|
|
|
165 |
|
|
'mkfs.ext2 /dev/fd0'.
|
166 |
|
|
|
167 |
|
|
Next we will install using 'rawrite' or 'dd' to the 'GRUB RAW'
|
168 |
|
|
diskette.
|
169 |
|
|
|
170 |
|
|
NOTE: This will destroy any data currently on the diskette.
|
171 |
|
|
|
172 |
|
|
Execute your OS's equivalent of (this should work for recent
|
173 |
|
|
FreeBSD versions and Linux just fine):
|
174 |
|
|
|
175 |
|
|
dd if=stage1 of=/dev/fd0 bs=512 count=1
|
176 |
|
|
dd if=stage2 of=/dev/fd0 bs=512 seek=1
|
177 |
|
|
|
178 |
|
|
Under DOS/Windows/NT, courtesy of Eric Hanchrow (erich@microsoft.com):
|
179 |
|
|
|
180 |
|
|
* Use the copy /b command to binary concatenate the stage1 and
|
181 |
|
|
stage2 files together via:
|
182 |
|
|
|
183 |
|
|
copy /b stage1 stage2 grub.raw
|
184 |
|
|
|
185 |
|
|
* Use rawrite.exe (which is available in many places on the net and
|
186 |
|
|
in some Linux distributions) to write grub.raw to a diskette.
|
187 |
|
|
|
188 |
|
|
Next stage: copy the 'stage1' and 'stage2' files to the 'GRUB FS'
|
189 |
|
|
diskette (if you are using Linux you can mount the diskette in an
|
190 |
|
|
appropriate mount point and then 'cp' the files to it, if it is either
|
191 |
|
|
a DOS FAT or an EXT2FS diskette, or in the case of a DOS FAT diskette
|
192 |
|
|
you can use 'mcopy' from 'mtools'.)
|
193 |
|
|
|
194 |
|
|
After this is done boot a PC using the 'GRUB RAW' diskette. After
|
195 |
|
|
this is done, you will get GRUB's command line interface. Exchange
|
196 |
|
|
'GRUB RAW' with the 'GRUB FS' diskette in the drive and issue the
|
197 |
|
|
following command from GRUB's prompt:
|
198 |
|
|
|
199 |
|
|
install=(fd0)/stage1 (fd0) (fd0)/stage2 0x8000 (fd0)/grubmenu
|
200 |
|
|
|
201 |
|
|
This command will make the 'GRUB FS' diskette bootable. After this
|
202 |
|
|
is done, you won't require the 'GRUB RAW' diskette anymore and you can
|
203 |
|
|
delete the 'stage1' file from the 'GRUB FS' diskette.
|
204 |
|
|
|
205 |
|
|
Next copy all the files you wish to load to the diskette. The GRUB
|
206 |
|
|
loadable test and sample files in the RTEMS distribution have '.exe'
|
207 |
|
|
extension and can be found under the build point in the 'pc386/tests'
|
208 |
|
|
directory. You can compress this files with gzip to save space if you
|
209 |
|
|
wish. GRUB loads 'gzipped' files transparently.
|
210 |
|
|
|
211 |
|
|
Finally you have to create a GRUB menu configuration file. We will
|
212 |
|
|
call this file 'grubmenu'. You can call it anything as long as you use
|
213 |
|
|
the correct name in the 'install' command where we used 'grubmenu'.
|
214 |
|
|
|
215 |
|
|
The 'grubmenu' file, as far as we are interested has the following
|
216 |
|
|
syntax:
|
217 |
|
|
|
218 |
|
|
title= Hello World Test
|
219 |
|
|
kernel= (fd0)/hello.exe.gz
|
220 |
|
|
|
221 |
|
|
You can add as many of this entries as you want to the 'grubmenu'
|
222 |
|
|
file. There should be one for each program you wish to load. The
|
223 |
|
|
'title=' line provides a description for the program that will appear
|
224 |
|
|
after boot in the GRUB menu for the user to choose and the 'kernel='
|
225 |
|
|
line describes where the file can be found by GRUB (you should leave
|
226 |
|
|
the '(fd0)/' part and just substitute the rest if you've copied the
|
227 |
|
|
files to the root directory of the diskette.
|
228 |
|
|
|
229 |
|
|
Just boot the PC with the 'GRUB FS' diskette and you will be able
|
230 |
|
|
to choose which program you want to load from GRUB's menu.
|
231 |
|
|
|
232 |
|
|
The GRUB documentation is available in HTML format in the 'docs'
|
233 |
|
|
directory of the GRUB tree starting with the 'index.html' file.
|
234 |
|
|
|
235 |
|
|
|
236 |
|
|
6.3 Using NetBoot to load RTEMS PC386 applications
|
237 |
|
|
---------------------------------------------------
|
238 |
|
|
|
239 |
|
|
To load the '*.bt' files you can
|
240 |
|
|
|
241 |
|
|
Alternatively, if you have a PC connected to a network with a
|
242 |
|
|
BOOTP server and a TFTP server (this can very well be you're Linux
|
243 |
|
|
RTEMS host system), you can use Gero Kuhlmann's NetBoot loader, to
|
244 |
|
|
load RTEMS to a diskless PC across a network. You can get it from:
|
245 |
|
|
|
246 |
|
|
ftp://sunsite.unc.edu/pub/Linux/system/boot/ethernet/netboot-0.7.3.tar.gz
|
247 |
|
|
|
248 |
|
|
or in any of Sunsite's mirrors. It is also available from NetBoot's
|
249 |
|
|
homepage:
|
250 |
|
|
|
251 |
|
|
http://www.han.de/~gero/netboot
|
252 |
|
|
|
253 |
|
|
After unarchiving 'netboot-0.7.3.tar.gz' you should change to the
|
254 |
|
|
base directory of this and run:
|
255 |
|
|
|
256 |
|
|
./configure --disable-mknbi-dos --disable-mknbi-linux --disable-mknbi-mgl
|
257 |
|
|
|
258 |
|
|
Afterwards, you should follow the instructions contained in the
|
259 |
|
|
'INSTALL' file also contained in the base directory, on how to setup the
|
260 |
|
|
server(s) and to build a boot ROM for the client PC network card, or a
|
261 |
|
|
boot diskette, and the PC client should be able to load the '*.bt' files
|
262 |
|
|
from the server.
|
263 |
|
|
|
264 |
|
|
The important sections to check in the 'INSTALL FILE' are the last two:
|
265 |
|
|
|
266 |
|
|
- Setup of the server (only the BOOTP and TFTP parts - ignore NFS).
|
267 |
|
|
===================
|
268 |
|
|
|
269 |
|
|
- Setup of the client including building the bootrom
|
270 |
|
|
==================================================
|
271 |
|
|
|
272 |
|
|
all the rest can be safely ignored if you don't care to examine it.
|
273 |
|
|
|
274 |
|
|
|
275 |
|
|
7. Technical Information
|
276 |
|
|
------------------------
|
277 |
|
|
|
278 |
|
|
NOTE: All the following paths are relative to the base directory
|
279 |
|
|
of the RTEMS distribution.
|
280 |
|
|
|
281 |
|
|
As of the writing of this HOWTO, PC386 images can be loaded either
|
282 |
|
|
in low memory 0x10000 (64KB) until 0x97C00 (607K) using NetBoot or in
|
283 |
|
|
high memory from 0x100000 (1024KB) until the top of the available
|
284 |
|
|
memory using either NetBoot or GRUB.
|
285 |
|
|
|
286 |
|
|
If you want to change the default loading address from 1024KB to
|
287 |
|
|
something else, just change the value of the variable RELOCADDR in the
|
288 |
|
|
'make/custom/pc386.cfg' file to the new value you want (make sure you
|
289 |
|
|
follow the instructions indicated before the definition of RELOCADDR).
|
290 |
|
|
|
291 |
|
|
Remember that GRUB restricts the loading addresses to values above
|
292 |
|
|
0x100000 (1024KB), only NetBoot can load images in low memory.
|
293 |
|
|
|
294 |
|
|
After you make any changes to RELOCADDR and if you are using
|
295 |
|
|
NetLoader, you'll have to recompile the
|
296 |
|
|
'c/src/lib/libbsp/i386/pc386/start/start16.s' file. The easiest way to
|
297 |
|
|
achieve this is just to 'make clean' and the 'make all' again. The
|
298 |
|
|
quickest way is to change to
|
299 |
|
|
'/c/src/lib/libbsp/i386/pc386/start' and 'make
|
300 |
|
|
RTEMS_BSP=pc386 clean all'.
|
301 |
|
|
|
302 |
|
|
When programming interrupt handlers take into account that the PIC
|
303 |
|
|
is reprogrammed and so you should use the interface functions provided
|
304 |
|
|
in '/pc386/lib/include/irq.h> to guarantee that everything
|
305 |
|
|
works ok.
|