Subversion Repositories openrisc_2011-10-31

+-----------------------------------------------------------------------------+

| RTEMS 4.5.0 PC386 BSP HOWTO - 1998/04/21                                    |

|                                                                             |

+-----------------------------------------------------------------------------+

| (C) Copyright 1998 -                                                        |

| - NavIST Group - Real-Time Distributed Systems and Industrial Automation    |

|                                                                             |

| http://pandora.ist.utl.pt                                                   |

|                                                                             |

| Instituto Superior Tecnico * Lisboa * PORTUGAL                              |

+-----------------------------------------------------------------------------+

| Disclaimer:                                                                 |

|                                                                             |

| This file is provided "AS IS" without warranty of any kind, either          |

| expressed or implied.                                                       |

+-----------------------------------------------------------------------------+

| History:                                                                    |

|  12 June 2000 - Updated to 4.5 (Joel)                                       |

+-----------------------------------------------------------------------------+

CVS Revision: $Id: HOWTO,v 1.2 2001-09-27 11:59:47 chris Exp $

1. Introduction

---------------

    This tries to explain how to setup the RTEMS host environment so

that RTEMS applications can be built for and run in a bare PC 386 or

above.

    It covers essentially the aspects of loading images, since

information concerning other issues such as building the development

tools and the RTEMS distribution can be found in the 'RTEMS 4.0.0

On-Line Library' under 'Getting Started with RTEMS for C/C++ Users'.

    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. Building the GNU C/C++ Cross Compiler Toolset

------------------------------------------------

    Obtaining, building and installing the tools for building the

PC386 BSP of RTEMS is covered in detail in the 'RTEMS 4.5.0 On-Line

Library' -> 'Getting Started with RTEMS for C/C++ Users'.  You can

either use pre-built toolset executables or build your own from

the instructions given there.

    This BSP is designed to work only with ELF toolset configurations.

This is format used by the i386-rtems target.

4. Building RTEMS

-----------------

    Obtaining, building and installing the tools for building the

PC386 BSP is covered in detail in the 'RTEMS 4.5.0 On-Line Library' ->

'Getting Started with RTEMS for C/C++ Users' -> 'Building RTEMS'.

    When running configure, use the following values for the listed

options with an i386-rtems toolset:

          --target=i386-rtems

          --enable-rtemsbsp=pc386

5. RTEMS Tests

--------------

    If you've completed the last step successfully, you'll find the

RTEMS sample and test files that can be loaded with GRUB in the

'/pc386/tests' directory, RTEMS sample and test files in

a format suitable for use with NetBoot in the

'/pc386/BootImgs' directory.

6. Loading RTEMS PC386 applications

-----------------------------------

6.1. Unarchiving

----------------

    Files which have been "tarred, gzipped" (i.e. .tar.gz or .tgz

extension) may be unarchived with a command similar to one of the

following:

      zcat .tgz | tar xvof -

    OR

      gunzip -c .tgz | tar xvof -

    OR

      tar xzvf .tgz

    NOTE: gunzip -c is equivalent to zcat. On commercial (non-Linux)

Unices, since the GNU utilities are not the standard 'tar' will be

gtar (GNU tar) and 'zcat' will be 'gzcat'.

    Given that the necessary utility programs are installed, any of

the above commands will extract the contents of .tar.gz into the

current directory. To view the contents of an archive without

restoring any files, use a command similar to the following:

      zcat .tgz | tar tvf -

6.2 Using GRUB to load RTEMS PC386 applications

-----------------------------------------------

    Using GRUB (GRand Unified Bootloader) is the simplest way to load

and run your PC386 BSP samples, tests and programs.

    You can get the latest release of GRUB from its homepage:

    - http://www.gnu.org/grub/

NOTE: The former location was http://www.uruk.org/grub and ftp from

      ftp://ftp.uruk.org/public/grub.

    Once you obtain the .tar.gz archive 'grub-0.4.tar.gz', change to a

temporary directory (you won't need the grub files after this and can

just go ahead and delete the whole directory structure that was

generated) and unarchive 'grub-0.4.tar.gz' following the instructions

given above in [2. Unarchiving].

    After this is done change the directory to:

      grub-0.4/bin_std

and there you'll find the two files you'll need from this archive:

'stage1' and 'stage2'.

    You should have two (2) formatted diskettes available. One of

these will only be used temporarily to create the other one, and we'll

refer to it as 'RAW GRUB' diskette (you can label it accordingly if

you wish). The other diskette, which we will refer to as 'GRUB FS'

should be high-level formatted with one of GRUB's supported file

systems, which are: DOS FAT, BSD FFS, and Linux ext2fs.

    A DOS FAT diskette can, obviously, be created under DOS with the

'FORMAT' command. Under Linux, the following commands are available to

add file systems to low-level formatted diskettes:

    1. To add a DOS FAT file system to a low-level formatted diskette:

      a) If you have mtools installed:

           'mformat a:'.

      b) Assuming that you are formatting the diskette in the first

         floppy disk drive ('/dev/fd0' under Linux):

           'mkdosfs /dev/fd0' or

           'mkfs.msdos /dev/fd0'.

    2. To add a Linux ext2fs file system to a low-level formatted

       diskette, assuming that you are formatting the diskette in the

       first floppy disk drive ('/dev/fd0' under Linux):

         'mke2fs /dev/fd0' or

         'mkfs.ext2 /dev/fd0'.

   Next we will install using 'rawrite' or 'dd' to the 'GRUB RAW'

diskette.

   NOTE: This will destroy any data currently on the diskette.

   Execute your OS's equivalent of (this should work for recent

FreeBSD versions and Linux just fine):

     dd if=stage1 of=/dev/fd0 bs=512 count=1

     dd if=stage2 of=/dev/fd0 bs=512 seek=1

   Under DOS/Windows/NT, courtesy of Eric Hanchrow (erich@microsoft.com):

     * Use the copy /b command to binary concatenate the stage1 and

       stage2 files together via:

         copy /b stage1 stage2 grub.raw

     * Use rawrite.exe (which is available in many places on the net and

       in some Linux distributions) to write grub.raw to a diskette.

   Next stage: copy the 'stage1' and 'stage2' files to the 'GRUB FS'

diskette (if you are using Linux you can mount the diskette in an

appropriate mount point and then 'cp' the files to it, if it is either

a DOS FAT or an EXT2FS diskette, or in the case of a DOS FAT diskette

you can use 'mcopy' from 'mtools'.)

   After this is done boot a PC using the 'GRUB RAW' diskette. After

this is done, you will get GRUB's command line interface. Exchange

'GRUB RAW' with the 'GRUB FS' diskette in the drive and issue the

following command from GRUB's prompt:

     install=(fd0)/stage1 (fd0) (fd0)/stage2 0x8000 (fd0)/grubmenu

   This command will make the 'GRUB FS' diskette bootable. After this

is done, you won't require the 'GRUB RAW' diskette anymore and you can

delete the 'stage1' file from the 'GRUB FS' diskette.

   Next copy all the files you wish to load to the diskette. The GRUB

loadable test and sample files in the RTEMS distribution have '.exe'

extension and can be found under the build point in the 'pc386/tests'

directory. You can compress this files with gzip to save space if you

wish. GRUB loads 'gzipped' files transparently.

   Finally you have to create a GRUB menu configuration file. We will

call this file 'grubmenu'. You can call it anything as long as you use

the correct name in the 'install' command where we used 'grubmenu'.

   The 'grubmenu' file, as far as we are interested has the following

syntax:

     title=  Hello World Test

     kernel= (fd0)/hello.exe.gz

   You can add as many of this entries as you want to the 'grubmenu'

file. There should be one for each program you wish to load. The

'title=' line provides a description for the program that will appear

after boot in the GRUB menu for the user to choose and the 'kernel='

line describes where the file can be found by GRUB (you should leave

the '(fd0)/' part and just substitute the rest if you've copied the

files to the root directory of the diskette.

   Just boot the PC with the 'GRUB FS' diskette and you will be able

to choose which program you want to load from GRUB's menu.

   The GRUB documentation is available in HTML format in the 'docs'

directory of the GRUB tree starting with the 'index.html' file.

6.3  Using NetBoot to load RTEMS PC386 applications

---------------------------------------------------

    To load the '*.bt' files you can

    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/ethernet/netboot-0.7.3.tar.gz

or in any of Sunsite's mirrors. It is also available from NetBoot's

homepage:

      http://www.han.de/~gero/netboot

    After unarchiving 'netboot-0.7.3.tar.gz' you should change to the

base directory of this and run:

      ./configure --disable-mknbi-dos --disable-mknbi-linux --disable-mknbi-mgl

    Afterwards, you should follow the instructions contained in the

'INSTALL' file also contained in the base directory, on how to setup the

server(s) and to build a boot ROM for the client PC network card, or a

boot diskette, and the PC client should be able to load the '*.bt' files

from the server.

    The important sections to check in the 'INSTALL FILE' are the last two:

    - Setup of the server (only the BOOTP and TFTP parts - ignore NFS).

      ===================

    - Setup of the client including building the bootrom

      ==================================================

all the rest can be safely ignored if you don't care to examine it.

7. Technical Information

------------------------

    NOTE: All the following paths are relative to the base directory

of the RTEMS distribution.

    As of the writing of this HOWTO, PC386 images can be loaded either

in low memory 0x10000 (64KB) until 0x97C00 (607K) using NetBoot or in

high memory from 0x100000 (1024KB) until the top of the available

memory using either NetBoot or GRUB.

    If you want to change the default loading address from 1024KB to

something else, just change the value of the variable RELOCADDR in the

'make/custom/pc386.cfg' file to the new value you want (make sure you

follow the instructions indicated before the definition of RELOCADDR).

    Remember that GRUB restricts the loading addresses to values above

0x100000 (1024KB), only NetBoot can load images in low memory.

    After you make any changes to RELOCADDR and if you are using

NetLoader, you'll have to recompile the

'c/src/lib/libbsp/i386/pc386/start/start16.s' file. The easiest way to

achieve this is just to 'make clean' and the 'make all' again. The

quickest way is to change to

'/c/src/lib/libbsp/i386/pc386/start' and 'make

RTEMS_BSP=pc386 clean all'.

    When programming interrupt handlers take into account that the PIC

is reprogrammed and so you should use the interface functions provided

in '/pc386/lib/include/irq.h> to guarantee that everything

works ok.