source: rtems-docs/user/bsps/bsps-x86_64.rst @ 4c2ca04

5
Last change on this file since 4c2ca04 was 4c2ca04, checked in by Amaan Cheval <amaan.cheval@…>, on 07/13/18 at 07:32:27

user: Add x86_64 BSP chapter

  • Property mode set to 100644
File size: 4.8 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2.. comment Copyright (c) 2018 Amaan Cheval <amaan.cheval@gmail.com>
3.. comment Copyright (c) 2018 embedded brains GmbH
4
5x86_64
6******
7
8amd64
9=====
10
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).
14
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.
18
19Build Configuration Options
20---------------------------
21
22There are no options available to ``configure`` at build time, at the moment.
23
24Testing with QEMU
25-----------------
26
27To test with QEMU, we need to:
28
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.
33
34Building TianoCore's UEFI firmware, OVMF
35^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
36
37Complete detailed instructions are available at `TianoCore's Github's wiki
38<https://github.com/tianocore/tianocore.github.io/wiki/How-to-build-OVMF>`_.
39
40Quick instructions (which may fall out of date) are:
41
42.. code-block:: shell
43
44    $ git clone git://github.com/tianocore/edk2.git
45    $ cd edk2
46    $ make -C BaseTools
47    $ . edksetup.sh
48
49Then edit ``Conf/target.txt`` to set:
50
51::
52
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
58
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
61shell.
62
63You can find the ``OVMF.fd`` file like this as well in the edk2 directory:
64
65.. code-block:: shell
66
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
72
73Boot RTEMS via FreeBSD's bootloader
74-----------------------------------
75
76The RTEMS executable produced (an ELF file) needs to be placed in the FreeBSD's
77``/boot/kernel/kernel``'s place.
78
79To do that, we first need a hard-disk image with FreeBSD installed on
80it. `Download FreeBSD's installer "memstick" image for amd64
81<https://www.freebsd.org/where.html>`_ and then run the following commands,
82replacing paths as appropriate.
83
84.. code-block:: shell
85
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
92
93The first time you do this, continue through and install FreeBSD. `FreeBSD's
94installation guide may prove useful
95<https://www.freebsd.org/doc/handbook/bsdinstall-start.html>`_ if required.
96
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).
102
103If your host system supports mounting UFS filesystems as read-write
104(eg. FreeBSD), go ahead and:
105
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``
110
111If your host doesn't support mounting UFS filesystems (eg. most Linux kernels),
112do something to the effect of the following.
113
114On the host
115
116.. code-block:: shell
117
118   # Upload hello.exe anywhere accessible within the host
119   $ curl --upload-file hello.exe https://transfer.sh/rtems
120
121Then on the guest (FreeBSD), login with ``root`` and
122
123.. code-block:: shell
124
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 https://host.com/path/to/rtems/hello.exe
131   # Replace default kernel
132   $ cp hello.exe /boot/kernel/kernel
133   $ reboot
134
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.
138
139Clock Driver
140------------
141
142The clock driver currently uses the idle thread clock driver.
143
144Console Driver
145--------------
146
147The console driver defaults to using the ``COM1`` UART port (at I/O port
148``0x3F8``), using the ``NS16550`` polled driver.
Note: See TracBrowser for help on using the repository browser.