BarrelfishOS/barrelfish

##########################################################################
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 <[email protected]>

   Note that git has support for adding such a message in the end of the commit
   log message.