280 lines
11 KiB
Plaintext
280 lines
11 KiB
Plaintext
##########################################################################
|
|
Copyright (c) 2009-2018, ETH Zurich.
|
|
All rights reserved.
|
|
|
|
This file is distributed under the terms in the attached LICENSE file.
|
|
If you do not find this file, copies can be found by writing to:
|
|
ETH Zurich D-INFK, Universitaetsstrasse 6, CH-8092 Zurich. Attn: Systems Group.
|
|
##########################################################################
|
|
|
|
Barrelfish Overview
|
|
--------------------------------
|
|
|
|
Barrelfish currently runs on:
|
|
|
|
* x86 CPUs in AMD64 mode. The following are known to work:
|
|
|
|
- Intel Xeon Clovertown, Gainestown, Beckton, IvyBridge, Haswell (X5355,
|
|
E5520, X7560, L5520, L7555, E5-2670v2, E3-1245v3)
|
|
- AMD Opteron Italy, Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
|
|
(275, 2220, 8350, 8374, 8380, 8431, 6174)
|
|
- Intel Xeon Phi Knights Corner
|
|
- QEMU simulator (2.2.10)
|
|
|
|
* ARM CPUs, specifically ARMv8 and ARMv7. The following platforms are known to work:
|
|
|
|
- ARMv7: The Texas Instruments OMAP4460 Pandaboard ES SoC
|
|
(Barrelfish runs on both the A9 and the M3 cores)
|
|
- ARMv7: The ARM VExpress EMM board as simulated by GEM5
|
|
- ARMv8: Cavium ThunderX2
|
|
- ARMv8: Applied Micro X-Gene
|
|
- ARMv8: NXP i.MX 8 SoC on a Toradex iMX8X Colibri board
|
|
- There is also limited support for the Netronome i8000 card, incorporating
|
|
a single Intel iXP2800 processor
|
|
|
|
This README file provides instructions for the x86 architecture. For other
|
|
architectures, please refer to the architecture-specific technical notes (e.g.,
|
|
see TN 06 for the SCC, and TN 17 for ARM).
|
|
|
|
You can either generate the latest documentation from this source-code
|
|
(instructions at end of this file), or visit the Barrelfish_ website
|
|
to download them.
|
|
|
|
.. _Barrelfish: http://www.barrelfish.org/
|
|
|
|
Supported PC hardware
|
|
--------------------------------
|
|
|
|
The biggest compatibility problems are likely to be in the PCI/ACPI code. We
|
|
usually discover new quirks (or missing functionality in the ACPI glue code)
|
|
on each new machine we test. The following systems are known to work:
|
|
|
|
* Intel x5000XVN
|
|
* Tyan n6650W and S4985
|
|
* Supermicro H8QM3-2
|
|
* Dell PowerEdge R610 and R905
|
|
* Sun Fire X2270 and X4440
|
|
* Intel/Quanta QSSC-S4R
|
|
* Lenovo X200 and X301 laptops
|
|
* ASUS Eee PC 1015PEM netbooks
|
|
|
|
We have support for the following NICs:
|
|
* The e1000n should work with most recent Intel gigabit ethernet
|
|
controllers (see the list in devices/e1000.dev). We've mostly used the
|
|
82572EI (PCI device ID 0x1082).
|
|
* Intel i82599 (or X520) 10GbE
|
|
* Solarflare sfn5122f 10GbE
|
|
|
|
You should also be able to boot Barrelfish on a recent version of QEMU (2.14);
|
|
note that the e1000 device emulated by QEMU is not supported by our driver.
|
|
|
|
Required Tools
|
|
--------------------------------
|
|
|
|
Our toolchain tracks Ubuntu LTS releases, and this is what we use to
|
|
run our nightly tests. If you are running Ubuntu LTS (18.04.1 at time
|
|
of writing), this means the following:
|
|
|
|
* GCC 7.4.0 for x86_64, ARMv7 and ARMv8
|
|
- On Ubuntu LTS install packages:
|
|
build-essential g++
|
|
gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
|
|
gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
|
|
* GNU binutils (2.30 is supported)
|
|
* GNU make
|
|
* GHC v8.0.2 and Parsec 3.1
|
|
- On Ubuntu LTS, install the following packages:
|
|
cabal-install libghc-src-exts-dev libghc-ghc-paths-dev
|
|
libghc-parsec3-dev libghc-random-dev libghc-ghc-mtl-dev
|
|
libghc-async-dev libghc-aeson-pretty-dev libghc-aeson-dev
|
|
libghc-missingh-dev
|
|
- Then, run cabal update && cabal install bytestring-trie pretty-simple
|
|
* FreeBSD's libelf:
|
|
- On Ubuntu install the following packages:
|
|
libelf-freebsd-dev freebsd-glue
|
|
* Optional: LibUSB 1.0 (for the usbboot tool):
|
|
- On Ubuntu install libusb-1.0-0-dev
|
|
|
|
* Optional: QEMU with e1000e EFI ROM:
|
|
- On Ubuntu install qemu-system-x86 qemu-efi qemu-ipxe
|
|
- Then cd /usr/lib/ipxe/qemu/ &&
|
|
sudo wget https://github.com/qemu/qemu/raw/master/pc-bios/efi-e1000e.rom
|
|
|
|
* Optional ARMv8 support:
|
|
- prefix all deb entries in /etc/apt/sources.list with [arch=amd64]
|
|
- add "deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports bionic main universe"
|
|
to sources.list
|
|
- dpkg --add-architecture arm64 && apt update && apt install gnu-efi:arm64 libefiboot-dev
|
|
|
|
Building
|
|
--------------------------------
|
|
|
|
1. Assuming you have already unpacked the sources, create a build directory ::
|
|
|
|
$ mkdir build && cd build
|
|
|
|
1. Run ``hake.sh``, giving it the path to the source directory and target
|
|
architecture(s) ::
|
|
|
|
$ ../hake/hake.sh -s ../ -a x86_64
|
|
|
|
This will configure the build directory and use GHC to compile and then run
|
|
hake, a tool used to generate the ``Makefile``.
|
|
|
|
3. Optionally, edit the configuration parameters in ``hake/Config.hs`` and
|
|
run ``make rehake`` to apply them.
|
|
|
|
4. Run make, and wait ::
|
|
|
|
$ make X86_64_Basic
|
|
|
|
5. If everything worked, you should now be able to run Barrelfish inside QEMU
|
|
(make sure you have followed the optional qemu step in required tools) ::
|
|
|
|
$ make qemu_x86_64
|
|
|
|
Installing and Booting
|
|
--------------------------------
|
|
|
|
Barrelfish requires a Multiboot-compliant bootloader that is capable of loading
|
|
an ELF64 image. At the time of writing, this doesn't include the default GRUB.
|
|
Your options are either:
|
|
|
|
* use the pre-loader "elver" that can be found in the tools directory
|
|
* patch GRUB to support a 64-bit kernel image, using this patch_.
|
|
|
|
.. _patch: http://savannah.gnu.org/bugs/?17963
|
|
|
|
"Installing" Barrelfish currently consists of copying the ELF files for the CPU
|
|
driver and user programs to a location that the target machine can boot from,
|
|
and writing a suitable menu.lst file that instructs the bootloader (GRUB) which
|
|
programs to load and the arguments to pass them.
|
|
|
|
If you specify an appropriate INSTALL_PREFIX, ``make install`` will copy the
|
|
binaries to the right place for you, eg ::
|
|
|
|
$ make install INSTALL_PREFIX=/tftpboot/barrelfish
|
|
|
|
We usually boot Barrelfish via PXE/TFTP, although loading from a local disk
|
|
also works. Instructions for setting up GRUB to do this are beyond the scope of
|
|
this document. Assuming you have such a setup, a sample menu.lst can
|
|
be found in build/x86/menu.lst.x86_64 after executin make qemu_x86_64. It
|
|
is a basic diskless boot that doesn't do anything useful beyond probing the
|
|
PCI buses and starting a basic shell.
|
|
|
|
There are many other programs you can load (take a look around the usr tree for
|
|
examples). To start a program on a core other than the BSP core, pass
|
|
``core=N`` as its first argument.
|
|
|
|
If things work, you should see output on both the VGA console and COM1.
|
|
|
|
Generating Documentation
|
|
--------------------------------
|
|
|
|
Barrelfish documentation can be found on Barrelfish website
|
|
(http://www.barrelfish.org/). And it can be also generated from the code tree.
|
|
For documentation generation, you will need ``latex`` packages installed,
|
|
including support for ``pdflatex``. Following are the instructions for
|
|
generating the documentation assuming you have already unpacked the sources ::
|
|
|
|
$ mkdir build && cd build
|
|
$ ../hake/hake.sh -s ../
|
|
$ make docs
|
|
|
|
You will find all the technotes in ``docs/`` directory.
|
|
|
|
Known Issues
|
|
--------------------------------
|
|
|
|
There are many. Those you're likely to encounter include:
|
|
|
|
* The documentation is incomplete and out of date.
|
|
* Some drivers and user programs are known not to build, and are
|
|
not included in the default set of targets (MODULES) in the Makefile.
|
|
|
|
Likely FAQs
|
|
--------------------------------
|
|
|
|
Q: How do I run a program?
|
|
A: Add it to the boot sequence by specifying the module in your menu.lst file.
|
|
For example, to run the memtest program, add the line:
|
|
module /PATH/x86_64/sbin/memtest
|
|
to the end of menu.lst, where PATH is relative either to your TFTP
|
|
server's root directory (when booting on hardware) or to your build
|
|
directory (when using a simulator such as QEMU).
|
|
If memtest runs, you should see it output "memtest passed successfully!".
|
|
|
|
Q: How do develop a program?
|
|
A: Check out Technote 18, Practical Guide. Either on barrelfish.org or
|
|
in the generated technotes (see Generating Documentation)
|
|
|
|
|
|
Q: Where's the CPU driver?
|
|
A: It's in the directory named kernel :) But don't worry, it really does run
|
|
independently on each core.
|
|
|
|
Q: Where is the source for the SPLASH2 benchmarks? It seems to be missing.
|
|
A: The license for these prevents redistribution, so we were forced to ship our
|
|
changes as a patch. See usr/splash2/README for further instructions.
|
|
|
|
Q: Can I use a debugger?
|
|
A: Maybe. There are two options at the moment:
|
|
* On a simulator, using whatever debug interfaces it supports.
|
|
For QEMU, you could try the "debugsim" target.
|
|
* On hardware, using the kernel-mode remote GDB stubs that operate on the
|
|
primary serial port and are entered in response to a kernel trap or
|
|
exception. However, these are not well maintained, and may not be usable
|
|
beyond reading/writing memory locations and inspecting the stack.
|
|
When debugging the kernel, beware that it is relocated to an address
|
|
determined at core boot time. Look for output such as:
|
|
"Kernel starting at address 0xffffffffc072b000".
|
|
|
|
Q: Where can I find more information, including papers and new releases?
|
|
A: http://www.barrelfish.org/
|
|
http://wiki.barrelfish.org/
|
|
|
|
Q: Can I contribute?
|
|
A: We'd certainly like to hear from you. Feel free to send patches (or even
|
|
git merge requests) to the Barrelfish mailing list.
|
|
|
|
To keep track of contributions to Barrelfish, we use a sign-off procedure
|
|
similar to the Linux kernel:
|
|
|
|
The sign-off is a simple line at the end of the explanation for the patch,
|
|
which certifies that you wrote it or otherwise have the right to pass it on
|
|
as an open-source patch. The rules are pretty simple: if you can certify
|
|
the below:
|
|
|
|
Developer's Certificate of Origin 1.1
|
|
|
|
By making a contribution to this project, I certify that:
|
|
|
|
(a) The contribution was created in whole or in part by me and I
|
|
have the right to submit it under the open source license
|
|
indicated in the file; or
|
|
|
|
(b) The contribution is based upon previous work that, to the best
|
|
of my knowledge, is covered under an appropriate open source
|
|
license and I have the right under that license to submit that
|
|
work with modifications, whether created in whole or in part
|
|
by me, under the same open source license (unless I am
|
|
permitted to submit under a different license), as indicated
|
|
in the file; or
|
|
|
|
(c) The contribution was provided directly to me by some other
|
|
person who certified (a), (b) or (c) and I have not modified
|
|
it.
|
|
|
|
(d) I understand and agree that this project and the contribution
|
|
are public and that a record of the contribution (including all
|
|
personal information I submit with it, including my sign-off) is
|
|
maintained indefinitely and may be redistributed consistent with
|
|
this project or the open source license(s) involved.
|
|
|
|
then you just add a line saying
|
|
|
|
Signed-off-by: Random J Developer <random@developer.example.org>
|
|
|
|
Note that git has support for adding such a message in the end of the commit
|
|
log message.
|