git.barrelfish.org Git - barrelfish/blob - README

   1 ##########################################################################
   2 Copyright (c) 2009-2013, 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, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
   8 ##########################################################################
   9
  10 Barrelfish Overview
  11 --------------------------------
  12
  13 Barrelfish currently runs on:
  14
  15  * x86 CPUs in either IA-32 or AMD64 mode. The following are known to work:
  16
  17    - Intel Xeon Clovertown, Gainestown, Beckton (X5355, E5520, X7560, L5520,
  18      L7555)
  19    - AMD Opteron Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
  20      (2220, 8350, 8374, 8380, 8431, 6174)
  21    - QEMU simulator
  22  * Intel Single-Chip Cloud Computer (SCC), both Copper Ridge and Rocky Lake
  23    are known to work.
  24  * ARM Platform
  25    - ARMv7 and ARMv5 architectures
  26    - GEM5 simulator
  27    - Pandaboard System On Chip platform
  28
  29 This README file documents instructions for x86 architecture.  For other
  30 architectures, please refer to the corresponding technote documentations.
  31 You can either generate the latest documentation from this source-code
  32 (instructions at end of this file), or visit the Barrelfish_ website
  33 to download them.
  34
  35 .. _Barrelfish: http://www.barrelfish.org/
  36
  37 Supported PC hardware
  38 --------------------------------
  39
  40 Barrelfish supports following PC hardware :
  41
  42  * x86 CPUs in either IA-32 or AMD64 mode. The following are known to work:
  43
  44    - Intel Xeon Clovertown, Gainestown, Beckton (X5355, E5520, X7560, L5520,
  45      L7555)
  46    - AMD Opteron Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
  47      (2220, 8350, 8374, 8380, 8431, 6174)
  48
  49 The biggest compatibility problems are likely to be in the PCI/ACPI code. We
  50 usually discover new quirks (or missing functionality in the ACPI glue code)
  51 on each new machine we test. The following systems are known to work:
  52
  53  * Intel x5000XVN
  54  * Tyan n6650W and S4985
  55  * Supermicro H8QM3-2
  56  * Dell PowerEdge R610 and R905
  57  * Sun Fire X2270 and X4440
  58  * Intel/Quanta QSSC-S4R
  59  * Lenovo X200 and X301 laptops
  60  * ASUS Eee PC 1015PEM netbooks
  61
  62 The e1000n driver 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
  66 You should also be able to boot Barrelfish on a recent version of QEMU (0.14);
  67 note that the e1000 device emulated by QEMU is not supported by our driver.
  68
  69 Required Tools
  70 --------------------------------
  71
  72 The following are required to build Barrelfish and its tools:
  73
  74  * GCC 4.x
  75
  76    - 4.4.5, and 4.5.2 are known to work
  77    - cross-compiling between i386 and x86_64 works (requires libc6-dev-i386
  78      to build 32 bit on 64 bit machine)
  79    - for the ARM port, we recommend the EABI tools available from CodeSourcery_.
  80  * GNU binutils (2.19 is known to work)
  81  * GNU make
  82  * GHC v7.4 and Parsec 3.1
  83    - older versions of the tree supported v6.10 or v6.12.2 with Parsec 2.1
  84    - GHC v6.12.1 has a known bug and is unable to build our tools
  85    - earlier versions of GHC are unsupported
  86
  87 Our build system may not be very portable; if in doubt, try building on a
  88 recent Debian or Ubuntu system, as these are what we use.
  89
  90
  91 .. _CodeSourcery: http://www.codesourcery.com/sgpp/lite/arm
  92
  93 Building
  94 --------------------------------
  95
  96 1. Assuming you have already unpacked the sources, create a build directory ::
  97
  98     $ mkdir build && cd build
  99
 100 1. Run ``hake.sh``, giving it the path to the source directory and target
 101 architecture(s) ::
 102
 103     $ ../hake/hake.sh -s ../ -a x86_64
 104
 105 This will configure the build directory and use GHC to compile and then run
 106 hake, a tool used to generate the ``Makefile``.
 107
 108 3. Optionally, edit the configuration parameters in ``hake/Config.hs`` and
 109 run ``make rehake`` to apply them.
 110
 111 4. Run make, and wait ::
 112
 113     $ make
 114
 115 5. If everything worked, you should now be able to run Barrelfish inside QEMU ::
 116
 117     $ make sim
 118
 119
 120 Installing and Booting
 121 --------------------------------
 122
 123 Barrelfish requires a Multiboot-compliant bootloader that is capable of loading
 124 an ELF64 image. At the time of writing, this doesn't include the default GRUB.
 125 Your options are either:
 126
 127  * use the pre-loader "elver" that can be found in the tools directory
 128  * patch GRUB to support a 64-bit kernel image, using this patch_.
 129
 130 .. _patch: http://savannah.gnu.org/bugs/?17963
 131
 132 "Installing" Barrelfish currently consists of copying the ELF files for the CPU
 133 driver and user programs to a location that the target machine can boot from,
 134 and writing a suitable menu.lst file that instructs the bootloader (GRUB) which
 135 programs to load and the arguments to pass them.
 136
 137 If you specify an appropriate INSTALL_PREFIX, ``make install`` will copy the
 138 binaries to the right place for you, eg ::
 139
 140     $ make install INSTALL_PREFIX=/tftpboot/barrelfish
 141
 142 We usually boot Barrelfish via PXE/TFTP, although loading from a local disk
 143 also works. Instructions for setting up GRUB to do this are beyond the scope of
 144 this document. Assuming you have such a setup, here is a sample menu.lst file
 145 for a basic diskless boot that doesn't do anything useful beyond probing the
 146 PCI buses and starting a basic shell ::
 147
 148     title   Barrelfish
 149     root    (nd)
 150     kernel /barrelfish/x86_64/sbin/elver
 151     module /barrelfish/x86_64/sbin/cpu
 152     module /barrelfish/x86_64/sbin/init
 153     module /barrelfish/x86_64/sbin/mem_serv
 154     module /barrelfish/x86_64/sbin/monitor
 155     module /barrelfish/x86_64/sbin/ramfsd boot
 156     module /barrelfish/x86_64/sbin/skb boot
 157     modulenounzip /barrelfish/skb_ramfs.cpio.gz nospawn
 158     module /barrelfish/x86_64/sbin/acpi boot
 159     module /barrelfish/x86_64/sbin/pci boot
 160     module /barrelfish/x86_64/sbin/spawnd boot
 161     module /barrelfish/x86_64/sbin/serial
 162     module /barrelfish/x86_64/sbin/fish
 163
 164 There are many other programs you can load (take a look around the usr tree for
 165 examples). To start a program on a core other than the BSP core, pass
 166 ``core=N`` as its first argument.
 167
 168 If things work, you should see output on both the VGA console and COM1.
 169
 170 Generating Documentation
 171 --------------------------------
 172
 173 Barrelfish documentation can be found on Barrelfish website
 174 (http://www.barrelfish.org/). And it can be also generated from the code tree.
 175 For documentation generation, you will need ``latex`` packages installed,
 176 including support for ``pdflatex``.  Following are the instructions for
 177 generating the documentation assuming you have already unpacked the sources ::
 178
 179     $ mkdir build && cd build
 180     $ ../hake/hake.sh -s ../
 181     $ make docs
 182
 183 You will find all the technotes in ``docs/`` directory.
 184
 185 Known Issues
 186 --------------------------------
 187
 188 There are many. Those you're likely to encounter include:
 189
 190  * The documentation is incomplete and out of date.
 191  * Some drivers and user programs are known not to build, and are
 192    not included in the default set of targets (MODULES) in the Makefile.
 193
 194 Likely FAQs
 195 --------------------------------
 196
 197 Q: How do I run a program?
 198 A: Add it to the boot sequence by specifying the module in your menu.lst file.
 199    For example, to run the memtest program, add the line:
 200        module /PATH/x86_64/sbin/memtest
 201    to the end of menu.lst, where PATH is relative either to your TFTP
 202    server's root directory (when booting on hardware) or to your build
 203    directory (when using a simulator such as QEMU).
 204    If memtest runs, you should see it output "memtest passed successfully!".
 205
 206 Q: Where's the CPU driver?
 207 A: It's in the directory named kernel :) But don't worry, it really does run
 208    independently on each core.
 209
 210 Q: Where is the source for the SPLASH2 benchmarks? It seems to be missing.
 211 A: The license for these prevents redistribution, so we were forced to ship our
 212    changes as a patch. See usr/splash2/README for further instructions.
 213
 214 Q: Can I use a debugger?
 215 A: Maybe. There are two options at the moment:
 216     * On a simulator, using whatever debug interfaces it supports.
 217       For QEMU, you could try the "debugsim" target.
 218     * On hardware, using the kernel-mode remote GDB stubs that operate on the
 219       primary serial port and are entered in response to a kernel trap or
 220       exception. However, these are not well maintained, and may not be usable
 221       beyond reading/writing memory locations and inspecting the stack.
 222    When debugging the kernel, beware that it is relocated to an address
 223    determined at core boot time. Look for output such as:
 224    "Kernel starting at address 0xffffffffc072b000".
 225
 226 Q: Where can I find more information, including papers and new releases?
 227 A: http://www.barrelfish.org/
 228    http://wiki.barrelfish.org/
 229
 230 Q: Can I contribute?
 231 A: We'd certainly like to hear from you. Please send us mail.
 232