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 | |
---|
5 | x86_64 |
---|
6 | ****** |
---|
7 | |
---|
8 | amd64 |
---|
9 | ===== |
---|
10 | |
---|
11 | This BSP offers only one variant, ``amd64``. The BSP can run on UEFI-capable |
---|
12 | systems by using FreeBSD's bootloader, which then loads the RTEMS executable (an |
---|
13 | ELF image). |
---|
14 | |
---|
15 | Currently only the console driver and context initialization and switching are |
---|
16 | functional (to a bare minimum), but this is enough to run the ``hello.exe`` sample |
---|
17 | in the RTEMS testsuite. |
---|
18 | |
---|
19 | Build Configuration Options |
---|
20 | --------------------------- |
---|
21 | |
---|
22 | There are no options available to ``configure`` at build time, at the moment. |
---|
23 | |
---|
24 | Testing with QEMU |
---|
25 | ----------------- |
---|
26 | |
---|
27 | To 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 | |
---|
34 | Building TianoCore's UEFI firmware, OVMF |
---|
35 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
36 | |
---|
37 | Complete detailed instructions are available at `TianoCore's Github's wiki |
---|
38 | <https://github.com/tianocore/tianocore.github.io/wiki/How-to-build-OVMF>`_. |
---|
39 | |
---|
40 | Quick 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 | |
---|
49 | Then 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 | |
---|
59 | Then run ``build`` in the ``edk2`` directory - the output should list the |
---|
60 | location of the ``OVMF.fd`` file, which can be used with QEMU to boot into a UEFI |
---|
61 | shell. |
---|
62 | |
---|
63 | You 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 | |
---|
73 | Boot RTEMS via FreeBSD's bootloader |
---|
74 | ----------------------------------- |
---|
75 | |
---|
76 | The RTEMS executable produced (an ELF file) needs to be placed in the FreeBSD's |
---|
77 | ``/boot/kernel/kernel``'s place. |
---|
78 | |
---|
79 | To do that, we first need a hard-disk image with FreeBSD installed on |
---|
80 | it. `Download FreeBSD's installer "memstick" image for amd64 |
---|
81 | <https://www.freebsd.org/where.html>`_ and then run the following commands, |
---|
82 | replacing 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 | |
---|
93 | The first time you do this, continue through and install FreeBSD. `FreeBSD's |
---|
94 | installation guide may prove useful |
---|
95 | <https://www.freebsd.org/doc/handbook/bsdinstall-start.html>`_ if required. |
---|
96 | |
---|
97 | Once installed, build your RTEMS executable (an ELF file), for |
---|
98 | eg. ``hello.exe``. We need to transfer this executable into ``freebsd.img``'s |
---|
99 | filesystem, at either ``/boot/kernel/kernel`` or ``/boot/kernel.old/kernel`` (or |
---|
100 | elsewhere, if you don't mind user FreeBSD's ``loader``'s prompt to boot your |
---|
101 | custom kernel). |
---|
102 | |
---|
103 | If your host system supports mounting UFS filesystems as read-write |
---|
104 | (eg. FreeBSD), go ahead and: |
---|
105 | |
---|
106 | 1. Mount ``freebsd.img`` as read-write |
---|
107 | 2. Within the filesystem, back the existing FreeBSD kernel up (i.e. effectively |
---|
108 | ``cp -r /boot/kernel /boot/kernel.old``). |
---|
109 | 3. Place your RTEMS executable at ``/boot/kernel/kernel`` |
---|
110 | |
---|
111 | If your host doesn't support mounting UFS filesystems (eg. most Linux kernels), |
---|
112 | do something to the effect of the following. |
---|
113 | |
---|
114 | On 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 | |
---|
121 | Then 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 | |
---|
135 | After rebooting, the RTEMS kernel should run after the UEFI firmware and |
---|
136 | FreeBSD's bootloader. The ``-serial stdio`` QEMU flag will let the RTEMS console |
---|
137 | send its output to the host's ``stdio`` stream. |
---|
138 | |
---|
139 | Clock Driver |
---|
140 | ------------ |
---|
141 | |
---|
142 | The clock driver currently uses the idle thread clock driver. |
---|
143 | |
---|
144 | Console Driver |
---|
145 | -------------- |
---|
146 | |
---|
147 | The console driver defaults to using the ``COM1`` UART port (at I/O port |
---|
148 | ``0x3F8``), using the ``NS16550`` polled driver. |
---|