[96d56b3] | 1 | +-----------------------------------------------------------------------------+ |
---|
[4338045] | 2 | | RTEMS 4.6.0 PC386 BSP HOWTO - 2003/05/08 | |
---|
[df49c60] | 3 | | | |
---|
[96d56b3] | 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 | +-----------------------------------------------------------------------------+ |
---|
[df49c60] | 17 | | History: | |
---|
| 18 | | 12 June 2000 - Updated to 4.5 (Joel) | |
---|
[4338045] | 19 | | 8 May 2003 - PXE GRUB (Chris Johns) | |
---|
[df49c60] | 20 | +-----------------------------------------------------------------------------+ |
---|
| 21 | |
---|
| 22 | CVS Revision: $Id$ |
---|
[7150f00f] | 23 | |
---|
| 24 | |
---|
| 25 | 1. Introduction |
---|
| 26 | --------------- |
---|
| 27 | |
---|
[96d56b3] | 28 | This tries to explain how to setup the RTEMS host environment so |
---|
| 29 | that RTEMS applications can be built for and run in a bare PC 386 or |
---|
| 30 | above. |
---|
| 31 | |
---|
| 32 | It covers essentially the aspects of loading images, since |
---|
| 33 | information concerning other issues such as building the development |
---|
[4338045] | 34 | tools and the RTEMS distribution can be found in the 'RTEMS 4.6.0 |
---|
[96d56b3] | 35 | On-Line Library' under 'Getting Started with RTEMS for C/C++ Users'. |
---|
[7150f00f] | 36 | |
---|
| 37 | Please note that everything in the following text using the |
---|
| 38 | notation '<...>' is just an alias to something and should always be |
---|
| 39 | substituted by the real thing! |
---|
| 40 | |
---|
| 41 | |
---|
[96d56b3] | 42 | 2. Building the GNU C/C++ Cross Compiler Toolset |
---|
| 43 | ------------------------------------------------ |
---|
[7150f00f] | 44 | |
---|
[96d56b3] | 45 | Obtaining, building and installing the tools for building the |
---|
[4338045] | 46 | PC386 BSP of RTEMS is covered in detail in the 'RTEMS 4.6.0 On-Line |
---|
[df49c60] | 47 | Library' -> 'Getting Started with RTEMS for C/C++ Users'. You can |
---|
| 48 | either use pre-built toolset executables or build your own from |
---|
| 49 | the instructions given there. |
---|
[7150f00f] | 50 | |
---|
[df49c60] | 51 | This BSP is designed to work only with ELF toolset configurations. |
---|
| 52 | This is format used by the i386-rtems target. |
---|
[7150f00f] | 53 | |
---|
| 54 | |
---|
[96d56b3] | 55 | 4. Building RTEMS |
---|
| 56 | ----------------- |
---|
| 57 | Obtaining, building and installing the tools for building the |
---|
[4338045] | 58 | PC386 BSP is covered in detail in the 'RTEMS 4.6.0 On-Line Library' -> |
---|
[96d56b3] | 59 | 'Getting Started with RTEMS for C/C++ Users' -> 'Building RTEMS'. |
---|
[7150f00f] | 60 | |
---|
[96d56b3] | 61 | When running configure, use the following values for the listed |
---|
[df49c60] | 62 | options with an i386-rtems toolset: |
---|
[7150f00f] | 63 | |
---|
[fd808ba] | 64 | --target=i386-rtems |
---|
| 65 | --enable-rtemsbsp=pc386 |
---|
[7150f00f] | 66 | |
---|
[96d56b3] | 67 | |
---|
| 68 | 5. RTEMS Tests |
---|
| 69 | -------------- |
---|
[7150f00f] | 70 | |
---|
[96d56b3] | 71 | If you've completed the last step successfully, you'll find the |
---|
| 72 | RTEMS sample and test files that can be loaded with GRUB in the |
---|
| 73 | '<build_point>/pc386/tests' directory, RTEMS sample and test files in |
---|
| 74 | a format suitable for use with NetBoot in the |
---|
| 75 | '<build_point>/pc386/BootImgs' directory. |
---|
[7150f00f] | 76 | |
---|
| 77 | |
---|
[96d56b3] | 78 | 6. Loading RTEMS PC386 applications |
---|
| 79 | ----------------------------------- |
---|
[7150f00f] | 80 | |
---|
[96d56b3] | 81 | 6.1. Unarchiving |
---|
| 82 | ---------------- |
---|
[7150f00f] | 83 | |
---|
[96d56b3] | 84 | Files which have been "tarred, gzipped" (i.e. .tar.gz or .tgz |
---|
| 85 | extension) may be unarchived with a command similar to one of the |
---|
| 86 | following: |
---|
[7150f00f] | 87 | |
---|
[96d56b3] | 88 | zcat <file>.tgz | tar xvof - |
---|
[7150f00f] | 89 | |
---|
[96d56b3] | 90 | OR |
---|
[7150f00f] | 91 | |
---|
[96d56b3] | 92 | gunzip -c <file>.tgz | tar xvof - |
---|
[7150f00f] | 93 | |
---|
[96d56b3] | 94 | OR |
---|
[7150f00f] | 95 | |
---|
[96d56b3] | 96 | tar xzvf <file>.tgz |
---|
[7150f00f] | 97 | |
---|
[96d56b3] | 98 | NOTE: gunzip -c is equivalent to zcat. On commercial (non-Linux) |
---|
| 99 | Unices, since the GNU utilities are not the standard 'tar' will be |
---|
| 100 | gtar (GNU tar) and 'zcat' will be 'gzcat'. |
---|
[7150f00f] | 101 | |
---|
[96d56b3] | 102 | Given that the necessary utility programs are installed, any of |
---|
| 103 | the above commands will extract the contents of <file>.tar.gz into the |
---|
| 104 | current directory. To view the contents of an archive without |
---|
| 105 | restoring any files, use a command similar to the following: |
---|
[7150f00f] | 106 | |
---|
[96d56b3] | 107 | zcat <file>.tgz | tar tvf - |
---|
[7150f00f] | 108 | |
---|
| 109 | |
---|
[4338045] | 110 | 6.2 Using GRUB to load RTEMS PC386 applications from Floppy |
---|
| 111 | ----------------------------------------------------------- |
---|
[7150f00f] | 112 | |
---|
[96d56b3] | 113 | Using GRUB (GRand Unified Bootloader) is the simplest way to load |
---|
[4338045] | 114 | and run your PC386 BSP samples, tests and programs. You will need to build GRUB |
---|
| 115 | so you need a working GCC and friends. The online documentation for GRUB lists |
---|
| 116 | what you need: |
---|
| 117 | |
---|
| 118 | - http://www.gnu.org/manual/grub/html_node/index.html |
---|
[7150f00f] | 119 | |
---|
[96d56b3] | 120 | You can get the latest release of GRUB from its homepage: |
---|
[7150f00f] | 121 | |
---|
[4338045] | 122 | - http://www.gnu.org/software/grub/ |
---|
| 123 | |
---|
| 124 | Once you obtain the .tar.gz archive from: |
---|
| 125 | |
---|
| 126 | - ftp://alpha.gnu.org/gnu/grub/ |
---|
| 127 | |
---|
| 128 | Download the lastest version (grub-0.93.tar.gz), change to a temporary |
---|
| 129 | directory (you won't need the grub files after this and can just go ahead and |
---|
| 130 | delete the whole directory structure that was generated) and unarchive |
---|
| 131 | 'grub-0.93.tar.gz' following the instructions given above in [2. Unarchiving]. |
---|
[7150f00f] | 132 | |
---|
[4338045] | 133 | $ cd /tmp |
---|
| 134 | $ mkdir grub |
---|
| 135 | $ cd grub |
---|
| 136 | $ cat grub-0.93.tar.gz | gzip -d | tar xf - |
---|
[7150f00f] | 137 | |
---|
[4338045] | 138 | after this is done create a build directory and decend into it: |
---|
[7150f00f] | 139 | |
---|
[4338045] | 140 | $ mkdir build |
---|
| 141 | $ cd build |
---|
[7150f00f] | 142 | |
---|
[4338045] | 143 | then configure GRUB with the standard options: |
---|
[7150f00f] | 144 | |
---|
[4338045] | 145 | $ ../grub-0.93/configure |
---|
| 146 | |
---|
| 147 | and if successful run make: |
---|
| 148 | |
---|
| 149 | $ make |
---|
| 150 | |
---|
| 151 | Once complete you should have the 'stage1' and 'stage2' files. They will be |
---|
| 152 | in the directories with the same name. |
---|
[7150f00f] | 153 | |
---|
[96d56b3] | 154 | You should have two (2) formatted diskettes available. One of |
---|
| 155 | these will only be used temporarily to create the other one, and we'll |
---|
| 156 | refer to it as 'RAW GRUB' diskette (you can label it accordingly if |
---|
| 157 | you wish). The other diskette, which we will refer to as 'GRUB FS' |
---|
| 158 | should be high-level formatted with one of GRUB's supported file |
---|
| 159 | systems, which are: DOS FAT, BSD FFS, and Linux ext2fs. |
---|
[7150f00f] | 160 | |
---|
[96d56b3] | 161 | A DOS FAT diskette can, obviously, be created under DOS with the |
---|
| 162 | 'FORMAT' command. Under Linux, the following commands are available to |
---|
| 163 | add file systems to low-level formatted diskettes: |
---|
[7150f00f] | 164 | |
---|
[96d56b3] | 165 | 1. To add a DOS FAT file system to a low-level formatted diskette: |
---|
[7150f00f] | 166 | |
---|
[96d56b3] | 167 | a) If you have mtools installed: |
---|
[7150f00f] | 168 | |
---|
[96d56b3] | 169 | 'mformat a:'. |
---|
[7150f00f] | 170 | |
---|
[96d56b3] | 171 | b) Assuming that you are formatting the diskette in the first |
---|
| 172 | floppy disk drive ('/dev/fd0' under Linux): |
---|
[7150f00f] | 173 | |
---|
[96d56b3] | 174 | 'mkdosfs /dev/fd0' or |
---|
[7150f00f] | 175 | |
---|
[96d56b3] | 176 | 'mkfs.msdos /dev/fd0'. |
---|
[7150f00f] | 177 | |
---|
[96d56b3] | 178 | 2. To add a Linux ext2fs file system to a low-level formatted |
---|
| 179 | diskette, assuming that you are formatting the diskette in the |
---|
| 180 | first floppy disk drive ('/dev/fd0' under Linux): |
---|
[7150f00f] | 181 | |
---|
[96d56b3] | 182 | 'mke2fs /dev/fd0' or |
---|
[7150f00f] | 183 | |
---|
[96d56b3] | 184 | 'mkfs.ext2 /dev/fd0'. |
---|
[7150f00f] | 185 | |
---|
[96d56b3] | 186 | Next we will install using 'rawrite' or 'dd' to the 'GRUB RAW' |
---|
| 187 | diskette. |
---|
[7150f00f] | 188 | |
---|
[96d56b3] | 189 | NOTE: This will destroy any data currently on the diskette. |
---|
[7150f00f] | 190 | |
---|
[96d56b3] | 191 | Execute your OS's equivalent of (this should work for recent |
---|
| 192 | FreeBSD versions and Linux just fine): |
---|
[7150f00f] | 193 | |
---|
[4338045] | 194 | dd if=stage1/stage1 of=/dev/fd0 bs=512 count=1 |
---|
| 195 | dd if=stage2/stage2 of=/dev/fd0 bs=512 seek=1 |
---|
[7150f00f] | 196 | |
---|
[96d56b3] | 197 | Under DOS/Windows/NT, courtesy of Eric Hanchrow (erich@microsoft.com): |
---|
[7150f00f] | 198 | |
---|
[96d56b3] | 199 | * Use the copy /b command to binary concatenate the stage1 and |
---|
| 200 | stage2 files together via: |
---|
[7150f00f] | 201 | |
---|
[4338045] | 202 | copy /b stage1\stage1 stage2\stage2 grub.raw |
---|
[7150f00f] | 203 | |
---|
[96d56b3] | 204 | * Use rawrite.exe (which is available in many places on the net and |
---|
| 205 | in some Linux distributions) to write grub.raw to a diskette. |
---|
[7150f00f] | 206 | |
---|
[4338045] | 207 | (CCJ: I am not sure about the Windows location etc) |
---|
| 208 | |
---|
[96d56b3] | 209 | Next stage: copy the 'stage1' and 'stage2' files to the 'GRUB FS' |
---|
| 210 | diskette (if you are using Linux you can mount the diskette in an |
---|
| 211 | appropriate mount point and then 'cp' the files to it, if it is either |
---|
| 212 | a DOS FAT or an EXT2FS diskette, or in the case of a DOS FAT diskette |
---|
| 213 | you can use 'mcopy' from 'mtools'.) |
---|
[7150f00f] | 214 | |
---|
[96d56b3] | 215 | After this is done boot a PC using the 'GRUB RAW' diskette. After |
---|
| 216 | this is done, you will get GRUB's command line interface. Exchange |
---|
| 217 | 'GRUB RAW' with the 'GRUB FS' diskette in the drive and issue the |
---|
| 218 | following command from GRUB's prompt: |
---|
[7150f00f] | 219 | |
---|
[96d56b3] | 220 | install=(fd0)/stage1 (fd0) (fd0)/stage2 0x8000 (fd0)/grubmenu |
---|
[7150f00f] | 221 | |
---|
[96d56b3] | 222 | This command will make the 'GRUB FS' diskette bootable. After this |
---|
| 223 | is done, you won't require the 'GRUB RAW' diskette anymore and you can |
---|
| 224 | delete the 'stage1' file from the 'GRUB FS' diskette. |
---|
[7150f00f] | 225 | |
---|
[96d56b3] | 226 | Next copy all the files you wish to load to the diskette. The GRUB |
---|
| 227 | loadable test and sample files in the RTEMS distribution have '.exe' |
---|
| 228 | extension and can be found under the build point in the 'pc386/tests' |
---|
| 229 | directory. You can compress this files with gzip to save space if you |
---|
| 230 | wish. GRUB loads 'gzipped' files transparently. |
---|
[7150f00f] | 231 | |
---|
[96d56b3] | 232 | Finally you have to create a GRUB menu configuration file. We will |
---|
| 233 | call this file 'grubmenu'. You can call it anything as long as you use |
---|
| 234 | the correct name in the 'install' command where we used 'grubmenu'. |
---|
[7150f00f] | 235 | |
---|
[96d56b3] | 236 | The 'grubmenu' file, as far as we are interested has the following |
---|
| 237 | syntax: |
---|
[7150f00f] | 238 | |
---|
[96d56b3] | 239 | title= Hello World Test |
---|
| 240 | kernel= (fd0)/hello.exe.gz |
---|
[7150f00f] | 241 | |
---|
[96d56b3] | 242 | You can add as many of this entries as you want to the 'grubmenu' |
---|
| 243 | file. There should be one for each program you wish to load. The |
---|
| 244 | 'title=' line provides a description for the program that will appear |
---|
| 245 | after boot in the GRUB menu for the user to choose and the 'kernel=' |
---|
| 246 | line describes where the file can be found by GRUB (you should leave |
---|
| 247 | the '(fd0)/' part and just substitute the rest if you've copied the |
---|
| 248 | files to the root directory of the diskette. |
---|
[7150f00f] | 249 | |
---|
[96d56b3] | 250 | Just boot the PC with the 'GRUB FS' diskette and you will be able |
---|
| 251 | to choose which program you want to load from GRUB's menu. |
---|
[7150f00f] | 252 | |
---|
[96d56b3] | 253 | The GRUB documentation is available in HTML format in the 'docs' |
---|
| 254 | directory of the GRUB tree starting with the 'index.html' file. |
---|
[7150f00f] | 255 | |
---|
| 256 | |
---|
[4338045] | 257 | 6.3 Using GRUB to load RTEMS PC386 applications via PXE NetBoot |
---|
| 258 | ---------------------------------------------------------------- |
---|
| 259 | |
---|
| 260 | PXE is the Intel Preboot Execution Environment. A number of PC |
---|
| 261 | manufactures provide a PXE option in the BIOS. This is usually a |
---|
| 262 | Net Boot option in a BIOS configuration screen. The simplist way to |
---|
| 263 | load an RTEMS application via PXE is to use GRUB as a first stage |
---|
| 264 | loader. |
---|
| 265 | |
---|
| 266 | You will need to determine your network card, and have a working |
---|
| 267 | network with a DHCP (or BOOTP), and TFTP server. |
---|
| 268 | |
---|
| 269 | You may to find a TFTP server that does not support option |
---|
| 270 | negotiations. A google search shows a number of PC's have a buggy |
---|
| 271 | PXE loader. Supressing option negotiations seems to make them |
---|
| 272 | work. |
---|
| 273 | |
---|
| 274 | You will need to build GRUB for your network card. Follow the |
---|
| 275 | procedure in item 6.2 up to the configure point. At this point |
---|
| 276 | run the following configure command: |
---|
| 277 | |
---|
| 278 | $ ../grub-0.93/configure --enable-diskless --enable-eepro100 |
---|
| 279 | |
---|
| 280 | for an Etherexpress Pro 100 network card, then run make: |
---|
| 281 | |
---|
| 282 | $ make |
---|
| 283 | |
---|
| 284 | Once complete you should have the 'stage2/pxegrub' file. Copy |
---|
| 285 | this to your TFTP server's download directory. Configure your |
---|
| 286 | DHCP server to provide an IP address and download the image. For |
---|
| 287 | the ISC server found on operating systems such as Linux something |
---|
| 288 | like the following should do: |
---|
| 289 | |
---|
| 290 | # |
---|
| 291 | # PC loading RTEMS via PXE and GRUB |
---|
| 292 | # |
---|
| 293 | |
---|
| 294 | group |
---|
| 295 | { |
---|
| 296 | filename "/tftpboot/pxeboot"; |
---|
| 297 | host rtems-pc { hardware ethernet 00:08:c7:73:41:65; } |
---|
| 298 | } |
---|
| 299 | |
---|
| 300 | If all works your PC should boot and load GRUB over the network: |
---|
| 301 | |
---|
| 302 | GRUB version 0.93 (639K lower / 64512K upper memory) |
---|
| 303 | |
---|
| 304 | Address: 10.10.10.10 |
---|
| 305 | NetMask: 255.255.255.0 |
---|
| 306 | Server: 10.10.10.1 |
---|
| 307 | Gateway: 10.10.10.1 |
---|
| 308 | |
---|
| 309 | [ Minimal BASH-like line editing is supported. For the first word, TAB |
---|
| 310 | lists possible command completions. Anywhere else TAB lists the possible |
---|
| 311 | completions of a device/filename. ] |
---|
| 312 | |
---|
| 313 | grub> |
---|
| 314 | |
---|
| 315 | Copy your RTEMS executable to the TFTP server directory then enter |
---|
| 316 | the following GRUB commands: |
---|
| 317 | |
---|
| 318 | grub> root (nd) |
---|
| 319 | Filesystem type is tftp, using whole disk |
---|
| 320 | |
---|
| 321 | grub> kernel ticker.exe |
---|
| 322 | [Multiboot-elf, <0x100000:0x1e5a4:0x2b08>, shtab=0x122140, entry=0x10000c] |
---|
| 323 | |
---|
| 324 | grub> boot |
---|
| 325 | |
---|
| 326 | The GRUB documents how to get GRUB to load a configuration file. |
---|
| 327 | |
---|
| 328 | |
---|
| 329 | 6.4 Using NetBoot to load RTEMS PC386 applications |
---|
[96d56b3] | 330 | --------------------------------------------------- |
---|
[7150f00f] | 331 | |
---|
[96d56b3] | 332 | To load the '*.bt' files you can |
---|
[7150f00f] | 333 | |
---|
[96d56b3] | 334 | Alternatively, if you have a PC connected to a network with a |
---|
| 335 | BOOTP server and a TFTP server (this can very well be you're Linux |
---|
| 336 | RTEMS host system), you can use Gero Kuhlmann's NetBoot loader, to |
---|
| 337 | load RTEMS to a diskless PC across a network. You can get it from: |
---|
[7150f00f] | 338 | |
---|
[7d78f40] | 339 | ftp://sunsite.unc.edu/pub/Linux/system/boot/ethernet/netboot-0.7.3.tar.gz |
---|
[7150f00f] | 340 | |
---|
[96d56b3] | 341 | or in any of Sunsite's mirrors. It is also available from NetBoot's |
---|
| 342 | homepage: |
---|
[7150f00f] | 343 | |
---|
[96d56b3] | 344 | http://www.han.de/~gero/netboot |
---|
[7150f00f] | 345 | |
---|
[96d56b3] | 346 | After unarchiving 'netboot-0.7.3.tar.gz' you should change to the |
---|
| 347 | base directory of this and run: |
---|
[7150f00f] | 348 | |
---|
[96d56b3] | 349 | ./configure --disable-mknbi-dos --disable-mknbi-linux --disable-mknbi-mgl |
---|
[7150f00f] | 350 | |
---|
[96d56b3] | 351 | Afterwards, you should follow the instructions contained in the |
---|
| 352 | 'INSTALL' file also contained in the base directory, on how to setup the |
---|
[7150f00f] | 353 | server(s) and to build a boot ROM for the client PC network card, or a |
---|
[96d56b3] | 354 | boot diskette, and the PC client should be able to load the '*.bt' files |
---|
[7150f00f] | 355 | from the server. |
---|
| 356 | |
---|
[96d56b3] | 357 | The important sections to check in the 'INSTALL FILE' are the last two: |
---|
[fdff6bf2] | 358 | |
---|
[96d56b3] | 359 | - Setup of the server (only the BOOTP and TFTP parts - ignore NFS). |
---|
| 360 | =================== |
---|
[fdff6bf2] | 361 | |
---|
[96d56b3] | 362 | - Setup of the client including building the bootrom |
---|
| 363 | ================================================== |
---|
[fdff6bf2] | 364 | |
---|
[96d56b3] | 365 | all the rest can be safely ignored if you don't care to examine it. |
---|
[fdff6bf2] | 366 | |
---|
[7150f00f] | 367 | |
---|
[96d56b3] | 368 | 7. Technical Information |
---|
| 369 | ------------------------ |
---|
| 370 | |
---|
| 371 | NOTE: All the following paths are relative to the base directory |
---|
| 372 | of the RTEMS distribution. |
---|
| 373 | |
---|
| 374 | As of the writing of this HOWTO, PC386 images can be loaded either |
---|
| 375 | in low memory 0x10000 (64KB) until 0x97C00 (607K) using NetBoot or in |
---|
| 376 | high memory from 0x100000 (1024KB) until the top of the available |
---|
| 377 | memory using either NetBoot or GRUB. |
---|
[7150f00f] | 378 | |
---|
[96d56b3] | 379 | If you want to change the default loading address from 1024KB to |
---|
| 380 | something else, just change the value of the variable RELOCADDR in the |
---|
| 381 | 'make/custom/pc386.cfg' file to the new value you want (make sure you |
---|
| 382 | follow the instructions indicated before the definition of RELOCADDR). |
---|
[7150f00f] | 383 | |
---|
[96d56b3] | 384 | Remember that GRUB restricts the loading addresses to values above |
---|
| 385 | 0x100000 (1024KB), only NetBoot can load images in low memory. |
---|
[7150f00f] | 386 | |
---|
[96d56b3] | 387 | After you make any changes to RELOCADDR and if you are using |
---|
| 388 | NetLoader, you'll have to recompile the |
---|
| 389 | 'c/src/lib/libbsp/i386/pc386/start/start16.s' file. The easiest way to |
---|
| 390 | achieve this is just to 'make clean' and the 'make all' again. The |
---|
| 391 | quickest way is to change to |
---|
| 392 | '<build_point>/c/src/lib/libbsp/i386/pc386/start' and 'make |
---|
| 393 | RTEMS_BSP=pc386 clean all'. |
---|
[7150f00f] | 394 | |
---|
| 395 | When programming interrupt handlers take into account that the PIC |
---|
| 396 | is reprogrammed and so you should use the interface functions provided |
---|
[96d56b3] | 397 | in '<build_point>/pc386/lib/include/irq.h> to guarantee that everything |
---|
| 398 | works ok. |
---|