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

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