1 | +-----------------------------------------------------------------------------+ |
---|
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$ |
---|
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 | '<build_point>/pc386/tests' directory, RTEMS sample and test files in |
---|
73 | a format suitable for use with NetBoot in the |
---|
74 | '<build_point>/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 <file>.tgz | tar xvof - |
---|
88 | |
---|
89 | OR |
---|
90 | |
---|
91 | gunzip -c <file>.tgz | tar xvof - |
---|
92 | |
---|
93 | OR |
---|
94 | |
---|
95 | tar xzvf <file>.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 <file>.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 <file>.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 | '<build_point>/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 '<build_point>/pc386/lib/include/irq.h> to guarantee that everything |
---|
305 | works ok. |
---|