readme: add NXP iMX8X to supported platforms
[barrelfish] / README
1 ##########################################################################
2 Copyright (c) 2009-2018, ETH Zurich.
3 All rights reserved.
4
5 This file is distributed under the terms in the attached LICENSE file.
6 If you do not find this file, copies can be found by writing to:
7 ETH Zurich D-INFK, Universitaetsstrasse 6, CH-8092 Zurich. Attn: Systems Group.
8 ##########################################################################
9
10 Barrelfish Overview
11 --------------------------------
12
13 Barrelfish currently runs on:
14
15  * x86 CPUs in AMD64 mode. The following are known to work:
16
17    - Intel Xeon Clovertown, Gainestown, Beckton, IvyBridge, Haswell (X5355,
18      E5520, X7560, L5520, L7555, E5-2670v2, E3-1245v3)
19    - AMD Opteron Italy, Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
20      (275, 2220, 8350, 8374, 8380, 8431, 6174)
21    - Intel Xeon Phi Knights Corner
22    - QEMU simulator (2.2.10)
23
24  * ARM CPUs, specifically ARMv8 and ARMv7. The following platforms are known to work:
25
26    - ARMv7: The Texas Instruments OMAP4460 Pandaboard ES SoC
27      (Barrelfish runs on both the A9 and the M3 cores)
28    - ARMv7: The ARM VExpress EMM board as simulated by GEM5
29    - ARMv8: Cavium ThunderX2
30    - ARMv8: Applied Micro X-Gene
31    - ARMv8: NXP i.MX 8 SoC on a Toradex iMX8X Colibri board
32    - There is also limited support for the Netronome i8000 card, incorporating
33      a single Intel iXP2800 processor
34
35 This README file provides instructions for the x86 architecture. For other
36 architectures, please refer to the architecture-specific technical notes (e.g.,
37 see TN 06 for the SCC, and TN 17 for ARM).
38
39 You can either generate the latest documentation from this source-code
40 (instructions at end of this file), or visit the Barrelfish_ website
41 to download them.
42
43 .. _Barrelfish: http://www.barrelfish.org/
44
45 Supported PC hardware
46 --------------------------------
47
48 The biggest compatibility problems are likely to be in the PCI/ACPI code. We
49 usually discover new quirks (or missing functionality in the ACPI glue code)
50 on each new machine we test. The following systems are known to work:
51
52  * Intel x5000XVN
53  * Tyan n6650W and S4985
54  * Supermicro H8QM3-2
55  * Dell PowerEdge R610 and R905
56  * Sun Fire X2270 and X4440
57  * Intel/Quanta QSSC-S4R
58  * Lenovo X200 and X301 laptops
59  * ASUS Eee PC 1015PEM netbooks
60
61 We have support for the following NICs:
62     * The e1000n should work with most recent Intel gigabit ethernet
63       controllers (see the list in devices/e1000.dev). We've mostly used the
64       82572EI (PCI device ID 0x1082). 
65     * Intel i82599 (or X520) 10GbE
66     * Solarflare sfn5122f 10GbE
67
68 You should also be able to boot Barrelfish on a recent version of QEMU (2.14);
69 note that the e1000 device emulated by QEMU is not supported by our driver.
70
71 Required Tools
72 --------------------------------
73
74 Our toolchain tracks Ubuntu LTS releases, and this is what we use to
75 run our nightly tests.  If you are running Ubuntu LTS (18.04.1 at time
76 of writing), this means the following:
77
78  * GCC 7.4.0 for x86_64, ARMv7 and ARMv8
79    - On Ubuntu LTS install packages:
80      build-essential g++
81      gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
82      gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
83  * GNU binutils (2.30 is supported)
84  * GNU make
85  * GHC v8.0.2 and Parsec 3.1
86    - On Ubuntu LTS, install the following packages: 
87      cabal-install libghc-src-exts-dev libghc-ghc-paths-dev
88      libghc-parsec3-dev libghc-random-dev libghc-ghc-mtl-dev
89      libghc-async-dev libghc-aeson-pretty-dev libghc-aeson-dev
90      libghc-missingh-dev
91    - Then, run cabal update && cabal install bytestring-trie pretty-simple
92  * FreeBSD's libelf:
93    - On Ubuntu install the following packages:
94      libelf-freebsd-dev freebsd-glue
95  * Optional: LibUSB 1.0 (for the usbboot tool):
96    - On Ubuntu install libusb-1.0-0-dev
97
98  * Optional: QEMU with e1000e EFI ROM:
99    - On Ubuntu install qemu-system-x86 qemu-efi qemu-ipxe
100    - Then cd /usr/lib/ipxe/qemu/ &&
101      sudo wget https://github.com/qemu/qemu/raw/master/pc-bios/efi-e1000e.rom
102
103  * Optional ARMv8 support:
104     - prefix all deb entries in /etc/apt/sources.list with [arch=amd64]
105     - add "deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports bionic main universe"
106       to sources.list
107     - dpkg --add-architecture arm64 && apt update && apt install gnu-efi:arm64 libefiboot-dev
108
109 Building
110 --------------------------------
111
112 1. Assuming you have already unpacked the sources, create a build directory ::
113
114     $ mkdir build && cd build
115
116 1. Run ``hake.sh``, giving it the path to the source directory and target
117 architecture(s) ::
118
119     $ ../hake/hake.sh -s ../ -a x86_64
120
121 This will configure the build directory and use GHC to compile and then run
122 hake, a tool used to generate the ``Makefile``.
123
124 3. Optionally, edit the configuration parameters in ``hake/Config.hs`` and
125 run ``make rehake`` to apply them.
126
127 4. Run make, and wait ::
128
129     $ make X86_64_Basic
130
131 5. If everything worked, you should now be able to run Barrelfish inside QEMU 
132    (make sure you have followed the optional qemu step in required tools) ::
133
134     $ make qemu_x86_64
135
136 Installing and Booting
137 --------------------------------
138
139 Barrelfish requires a Multiboot-compliant bootloader that is capable of loading
140 an ELF64 image. At the time of writing, this doesn't include the default GRUB.
141 Your options are either:
142
143  * use the pre-loader "elver" that can be found in the tools directory
144  * patch GRUB to support a 64-bit kernel image, using this patch_.
145
146 .. _patch: http://savannah.gnu.org/bugs/?17963
147
148 "Installing" Barrelfish currently consists of copying the ELF files for the CPU
149 driver and user programs to a location that the target machine can boot from,
150 and writing a suitable menu.lst file that instructs the bootloader (GRUB) which
151 programs to load and the arguments to pass them.
152
153 If you specify an appropriate INSTALL_PREFIX, ``make install`` will copy the
154 binaries to the right place for you, eg ::
155
156     $ make install INSTALL_PREFIX=/tftpboot/barrelfish
157
158 We usually boot Barrelfish via PXE/TFTP, although loading from a local disk
159 also works. Instructions for setting up GRUB to do this are beyond the scope of
160 this document. Assuming you have such a setup, a sample menu.lst can
161 be found in build/x86/menu.lst.x86_64 after executin make qemu_x86_64. It
162 is a basic diskless boot that doesn't do anything useful beyond probing the
163 PCI buses and starting a basic shell.
164
165 There are many other programs you can load (take a look around the usr tree for
166 examples). To start a program on a core other than the BSP core, pass
167 ``core=N`` as its first argument.
168
169 If things work, you should see output on both the VGA console and COM1.
170
171 Generating Documentation
172 --------------------------------
173
174 Barrelfish documentation can be found on Barrelfish website
175 (http://www.barrelfish.org/). And it can be also generated from the code tree.
176 For documentation generation, you will need ``latex`` packages installed,
177 including support for ``pdflatex``.  Following are the instructions for
178 generating the documentation assuming you have already unpacked the sources ::
179
180     $ mkdir build && cd build
181     $ ../hake/hake.sh -s ../
182     $ make docs
183
184 You will find all the technotes in ``docs/`` directory.
185
186 Known Issues
187 --------------------------------
188
189 There are many. Those you're likely to encounter include:
190
191  * The documentation is incomplete and out of date.
192  * Some drivers and user programs are known not to build, and are
193    not included in the default set of targets (MODULES) in the Makefile.
194
195 Likely FAQs
196 --------------------------------
197
198 Q: How do I run a program?
199 A: Add it to the boot sequence by specifying the module in your menu.lst file.
200    For example, to run the memtest program, add the line:
201        module /PATH/x86_64/sbin/memtest
202    to the end of menu.lst, where PATH is relative either to your TFTP
203    server's root directory (when booting on hardware) or to your build
204    directory (when using a simulator such as QEMU).
205    If memtest runs, you should see it output "memtest passed successfully!".
206
207 Q: How do develop a program?
208 A: Check out Technote 18, Practical Guide. Either on barrelfish.org or
209    in the generated technotes (see Generating Documentation)
210
211
212 Q: Where's the CPU driver?
213 A: It's in the directory named kernel :) But don't worry, it really does run
214    independently on each core.
215
216 Q: Where is the source for the SPLASH2 benchmarks? It seems to be missing.
217 A: The license for these prevents redistribution, so we were forced to ship our
218    changes as a patch. See usr/splash2/README for further instructions.
219
220 Q: Can I use a debugger?
221 A: Maybe. There are two options at the moment:
222     * On a simulator, using whatever debug interfaces it supports.
223       For QEMU, you could try the "debugsim" target.
224     * On hardware, using the kernel-mode remote GDB stubs that operate on the
225       primary serial port and are entered in response to a kernel trap or
226       exception. However, these are not well maintained, and may not be usable
227       beyond reading/writing memory locations and inspecting the stack.
228    When debugging the kernel, beware that it is relocated to an address
229    determined at core boot time. Look for output such as:
230    "Kernel starting at address 0xffffffffc072b000".
231
232 Q: Where can I find more information, including papers and new releases?
233 A: http://www.barrelfish.org/
234    http://wiki.barrelfish.org/
235
236 Q: Can I contribute?
237 A: We'd certainly like to hear from you. Feel free to send patches (or even
238    git merge requests) to the Barrelfish mailing list.
239
240    To keep track of contributions to Barrelfish, we use a sign-off procedure
241    similar to the Linux kernel:
242
243    The sign-off is a simple line at the end of the explanation for the patch,
244    which certifies that you wrote it or otherwise have the right to pass it on
245    as an open-source patch.  The rules are pretty simple: if you can certify
246    the below:
247
248         Developer's Certificate of Origin 1.1
249
250         By making a contribution to this project, I certify that:
251
252         (a) The contribution was created in whole or in part by me and I
253             have the right to submit it under the open source license
254             indicated in the file; or
255
256         (b) The contribution is based upon previous work that, to the best
257             of my knowledge, is covered under an appropriate open source
258             license and I have the right under that license to submit that
259             work with modifications, whether created in whole or in part
260             by me, under the same open source license (unless I am
261             permitted to submit under a different license), as indicated
262             in the file; or
263
264         (c) The contribution was provided directly to me by some other
265             person who certified (a), (b) or (c) and I have not modified
266             it.
267
268         (d) I understand and agree that this project and the contribution
269             are public and that a record of the contribution (including all
270             personal information I submit with it, including my sign-off) is
271             maintained indefinitely and may be redistributed consistent with
272             this project or the open source license(s) involved.
273
274    then you just add a line saying
275
276         Signed-off-by: Random J Developer <random@developer.example.org>
277
278    Note that git has support for adding such a message in the end of the commit
279    log message.