Changeset 4c2ca04 in rtems-docs

07/13/18 07:32:27 (5 years ago)
Amaan Cheval <amaan.cheval@…>
5, am, master
Amaan Cheval <amaan.cheval@…> (07/13/18 07:32:27)
Joel Sherrill <joel@…> (07/18/18 17:43:10)

user: Add x86_64 BSP chapter

1 edited


  • user/bsps/bsps-x86_64.rst

    rc765aa0 r4c2ca04  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2.. comment Copyright (c) 2018 Amaan Cheval <>
    23.. comment Copyright (c) 2018 embedded brains GmbH
    7 There are no x86_64 BSPs yet.
     11This BSP offers only one variant, ``amd64``. The BSP can run on UEFI-capable
     12systems by using FreeBSD's bootloader, which then loads the RTEMS executable (an
     13ELF image).
     15Currently only the console driver and context initialization and switching are
     16functional (to a bare minimum), but this is enough to run the ``hello.exe`` sample
     17in the RTEMS testsuite.
     19Build Configuration Options
     22There are no options available to ``configure`` at build time, at the moment.
     24Testing with QEMU
     27To test with QEMU, we need to:
     29- Build / install QEMU (most distributions should have it available on the
     30  package manager).
     31- Build UEFI firmware that QEMU can use to simulate an x86-64 system capable of
     32  booting a UEFI-aware kernel, through the ``--bios`` flag.
     34Building TianoCore's UEFI firmware, OVMF
     37Complete detailed instructions are available at `TianoCore's Github's wiki
     40Quick instructions (which may fall out of date) are:
     42.. code-block:: shell
     44    $ git clone git://
     45    $ cd edk2
     46    $ make -C BaseTools
     47    $ .
     49Then edit ``Conf/target.txt`` to set:
     53    ACTIVE_PLATFORM       = OvmfPkg/OvmfPkgX64.dsc
     54    TARGET                = DEBUG
     55    TARGET_ARCH           = X64
     56    # You can use GCC46 as well, if you'd prefer
     57    TOOL_CHAIN_TAG        = GCC5
     59Then run ``build`` in the ``edk2`` directory - the output should list the
     60location of the ``OVMF.fd`` file, which can be used with QEMU to boot into a UEFI
     63You can find the ``OVMF.fd`` file like this as well in the edk2 directory:
     65.. code-block:: shell
     67    $ find . -name "*.fd"
     68    ./Build/OvmfX64/DEBUG_GCC5/FV/MEMFD.fd
     69    ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd <-- the file we're looking for
     70    ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_CODE.fd
     71    ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_VARS.fd
     73Boot RTEMS via FreeBSD's bootloader
     76The RTEMS executable produced (an ELF file) needs to be placed in the FreeBSD's
     77``/boot/kernel/kernel``'s place.
     79To do that, we first need a hard-disk image with FreeBSD installed on
     80it. `Download FreeBSD's installer "memstick" image for amd64
     81<>`_ and then run the following commands,
     82replacing paths as appropriate.
     84.. code-block:: shell
     86   $ qemu-img create freebsd.img 8G
     87   $ OVMF_LOCATION=/path/to/ovmf/OVMF.fd
     88   $ FREEBSD_MEMSTICK=/path/to/FreeBSD-11.2-amd64-memstick.img
     89   $ qemu-system-x86_64 -m 1024 -serial stdio --bios $OVMF_LOCATION \
     90       -drive format=raw,file=freebsd.img \
     91       -drive format=raw,file=$FREEBSD_MEMSTICK
     93The first time you do this, continue through and install FreeBSD. `FreeBSD's
     94installation guide may prove useful
     95<>`_ if required.
     97Once installed, build your RTEMS executable (an ELF file), for
     98eg. ``hello.exe``. We need to transfer this executable into ``freebsd.img``'s
     99filesystem, at either ``/boot/kernel/kernel`` or ``/boot/kernel.old/kernel`` (or
     100elsewhere, if you don't mind user FreeBSD's ``loader``'s prompt to boot your
     101custom kernel).
     103If your host system supports mounting UFS filesystems as read-write
     104(eg. FreeBSD), go ahead and:
     1061. Mount ``freebsd.img`` as read-write
     1072. Within the filesystem, back the existing FreeBSD kernel up (i.e. effectively
     108   ``cp -r /boot/kernel /boot/kernel.old``).
     1093. Place your RTEMS executable at ``/boot/kernel/kernel``
     111If your host doesn't support mounting UFS filesystems (eg. most Linux kernels),
     112do something to the effect of the following.
     114On the host
     116.. code-block:: shell
     118   # Upload hello.exe anywhere accessible within the host
     119   $ curl --upload-file hello.exe
     121Then on the guest (FreeBSD), login with ``root`` and
     123.. code-block:: shell
     125   # Back the FreeBSD kernel up
     126   $ cp -r /boot/kernel/ /boot/kernel.old
     127   # Bring networking online if it isn't already
     128   $ dhclient em0
     129   # You may need to add the --no-verify-peer depending on your server
     130   $ fetch
     131   # Replace default kernel
     132   $ cp hello.exe /boot/kernel/kernel
     133   $ reboot
     135After rebooting, the RTEMS kernel should run after the UEFI firmware and
     136FreeBSD's bootloader. The ``-serial stdio`` QEMU flag will let the RTEMS console
     137send its output to the host's ``stdio`` stream.
     139Clock Driver
     142The clock driver currently uses the idle thread clock driver.
     144Console Driver
     147The console driver defaults to using the ``COM1`` UART port (at I/O port
     148``0x3F8``), using the ``NS16550`` polled driver.
Note: See TracChangeset for help on using the changeset viewer.