1 ##########################################################################
2 Copyright (c) 2009-2014, ETH Zurich.
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 ##########################################################################
11 --------------------------------
13 Barrelfish currently runs on:
15 * x86 CPUs in either IA-32 or AMD64 mode. The following are known to work:
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 - QEMU simulator (2.0.0)
23 * ARM CPUs, specifically ARMv7 and ARMv5. The following platforms are known to work:
25 - The integratorcp ARMv5 machine as simulated by QEM
26 - The Texas Instruments OMAP4460 Pandaboard ES SoC
27 (Barrelfish runs on both the A9 and the M3 cores)
28 - The ARM VExpress EMM board as simulated by GEM5
29 - There is also limited support for the Netronome i8000 card, incorporating
30 a single Intel iXP2800 processor
32 This README file provides instructions for the x86 architecture. For other
33 architectures, please refer to the architecture-specific technical notes (e.g.,
34 see TN 06 for the SCC, and TN 17 for ARM).
36 You can either generate the latest documentation from this source-code
37 (instructions at end of this file), or visit the Barrelfish_ website
40 .. _Barrelfish: http://www.barrelfish.org/
43 --------------------------------
45 Barrelfish supports following PC hardware :
47 * x86 CPUs in either IA-32 or AMD64 mode. The following are known to work:
49 - Intel Xeon Clovertown, Gainestown, Beckton, Ivy Bridge, Haswell (X5355,
50 E5520, X7560, L5520, L7555, E5-2670v2, E3-1245v3)
51 - AMD Opteron Italy, Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
52 (275, 2220, 8350, 8374, 8380, 8431, 6174)
53 * Note: the Opteron 275 do not work in IA-32 mode.
55 The biggest compatibility problems are likely to be in the PCI/ACPI code. We
56 usually discover new quirks (or missing functionality in the ACPI glue code)
57 on each new machine we test. The following systems are known to work:
60 * Tyan n6650W and S4985
62 * Dell PowerEdge R610 and R905
63 * Sun Fire X2270 and X4440
64 * Intel/Quanta QSSC-S4R
65 * Lenovo X200 and X301 laptops
66 * ASUS Eee PC 1015PEM netbooks
68 The e1000n driver should work with most recent Intel gigabit ethernet
69 controllers (see the list in devices/e1000.dev). We've mostly used the
70 82572EI (PCI device ID 0x1082).
72 You should also be able to boot Barrelfish on a recent version of QEMU (0.14);
73 note that the e1000 device emulated by QEMU is not supported by our driver.
76 --------------------------------
78 We are making sure that Barrelfish and its tools can be built using the
81 * GCC 4.8.2 for x86_64 and x86_32
82 - cross-compiling between i386 and x86_64 works (install gcc-multilib on 64 bit Ubuntu LTS)
83 * GCC 4.7.3 for ARMv5 and ARMv7
84 - gcc-arm-linux-gnueabi and g++-arm-linux-gnueabi on Ubuntu LTS
85 * GNU binutils (2.24 is known to work)
87 * GHC v7.6.3 and Parsec 3.1
88 - older versions of the tree supported v6.10 or v6.12.2 with Parsec 2.1 or
90 - GHC v6.12.1 has a known bug and is unable to build our tools
91 - earlier versions of GHC are unsupported
92 - Install GHC packages libghc-mtl-dev libghc-ghc-mtl-dev cabal-install
93 haskell-src-exts libghc-async-dev
94 - Run cabal-install bytestring-trie
97 Our build system may not be very portable; if in doubt, try building on the
98 latest Ubuntu LTS system (14.04.1), as this is what we use to run nightly
103 --------------------------------
105 1. Assuming you have already unpacked the sources, create a build directory ::
107 $ mkdir build && cd build
109 1. Run ``hake.sh``, giving it the path to the source directory and target
112 $ ../hake/hake.sh -s ../ -a x86_64
114 This will configure the build directory and use GHC to compile and then run
115 hake, a tool used to generate the ``Makefile``.
117 3. Optionally, edit the configuration parameters in ``hake/Config.hs`` and
118 run ``make rehake`` to apply them.
120 4. Run make, and wait ::
124 5. If everything worked, you should now be able to run Barrelfish inside QEMU ::
128 Installing and Booting
129 --------------------------------
131 Barrelfish requires a Multiboot-compliant bootloader that is capable of loading
132 an ELF64 image. At the time of writing, this doesn't include the default GRUB.
133 Your options are either:
135 * use the pre-loader "elver" that can be found in the tools directory
136 * patch GRUB to support a 64-bit kernel image, using this patch_.
138 .. _patch: http://savannah.gnu.org/bugs/?17963
140 "Installing" Barrelfish currently consists of copying the ELF files for the CPU
141 driver and user programs to a location that the target machine can boot from,
142 and writing a suitable menu.lst file that instructs the bootloader (GRUB) which
143 programs to load and the arguments to pass them.
145 If you specify an appropriate INSTALL_PREFIX, ``make install`` will copy the
146 binaries to the right place for you, eg ::
148 $ make install INSTALL_PREFIX=/tftpboot/barrelfish
150 We usually boot Barrelfish via PXE/TFTP, although loading from a local disk
151 also works. Instructions for setting up GRUB to do this are beyond the scope of
152 this document. Assuming you have such a setup, here is a sample menu.lst file
153 for a basic diskless boot that doesn't do anything useful beyond probing the
154 PCI buses and starting a basic shell ::
158 kernel /barrelfish/x86_64/sbin/elver
159 module /barrelfish/x86_64/sbin/cpu
160 module /barrelfish/x86_64/sbin/init
161 module /barrelfish/x86_64/sbin/mem_serv
162 module /barrelfish/x86_64/sbin/monitor
163 module /barrelfish/x86_64/sbin/ramfsd boot
164 module /barrelfish/x86_64/sbin/skb boot
165 modulenounzip /barrelfish/skb_ramfs.cpio.gz nospawn
166 module /barrelfish/x86_64/sbin/acpi boot
167 module /barrelfish/x86_64/sbin/pci boot
168 module /barrelfish/x86_64/sbin/spawnd boot
169 module /barrelfish/x86_64/sbin/serial
170 module /barrelfish/x86_64/sbin/fish
172 There are many other programs you can load (take a look around the usr tree for
173 examples). To start a program on a core other than the BSP core, pass
174 ``core=N`` as its first argument.
176 If things work, you should see output on both the VGA console and COM1.
178 Generating Documentation
179 --------------------------------
181 Barrelfish documentation can be found on Barrelfish website
182 (http://www.barrelfish.org/). And it can be also generated from the code tree.
183 For documentation generation, you will need ``latex`` packages installed,
184 including support for ``pdflatex``. Following are the instructions for
185 generating the documentation assuming you have already unpacked the sources ::
187 $ mkdir build && cd build
188 $ ../hake/hake.sh -s ../
191 You will find all the technotes in ``docs/`` directory.
194 --------------------------------
196 There are many. Those you're likely to encounter include:
198 * The documentation is incomplete and out of date.
199 * Some drivers and user programs are known not to build, and are
200 not included in the default set of targets (MODULES) in the Makefile.
203 --------------------------------
205 Q: How do I run a program?
206 A: Add it to the boot sequence by specifying the module in your menu.lst file.
207 For example, to run the memtest program, add the line:
208 module /PATH/x86_64/sbin/memtest
209 to the end of menu.lst, where PATH is relative either to your TFTP
210 server's root directory (when booting on hardware) or to your build
211 directory (when using a simulator such as QEMU).
212 If memtest runs, you should see it output "memtest passed successfully!".
214 Q: Where's the CPU driver?
215 A: It's in the directory named kernel :) But don't worry, it really does run
216 independently on each core.
218 Q: Where is the source for the SPLASH2 benchmarks? It seems to be missing.
219 A: The license for these prevents redistribution, so we were forced to ship our
220 changes as a patch. See usr/splash2/README for further instructions.
222 Q: Can I use a debugger?
223 A: Maybe. There are two options at the moment:
224 * On a simulator, using whatever debug interfaces it supports.
225 For QEMU, you could try the "debugsim" target.
226 * On hardware, using the kernel-mode remote GDB stubs that operate on the
227 primary serial port and are entered in response to a kernel trap or
228 exception. However, these are not well maintained, and may not be usable
229 beyond reading/writing memory locations and inspecting the stack.
230 When debugging the kernel, beware that it is relocated to an address
231 determined at core boot time. Look for output such as:
232 "Kernel starting at address 0xffffffffc072b000".
234 Q: Where can I find more information, including papers and new releases?
235 A: http://www.barrelfish.org/
236 http://wiki.barrelfish.org/
239 A: We'd certainly like to hear from you. Feel free to send patches (or even
240 git merge requests) to the Barrelfish mailing list.
242 To keep track of contributions to Barrelfish, we use a sign-off procedure
243 similar to the Linux kernel:
245 The sign-off is a simple line at the end of the explanation for the patch,
246 which certifies that you wrote it or otherwise have the right to pass it on
247 as an open-source patch. The rules are pretty simple: if you can certify
250 Developer's Certificate of Origin 1.1
252 By making a contribution to this project, I certify that:
254 (a) The contribution was created in whole or in part by me and I
255 have the right to submit it under the open source license
256 indicated in the file; or
258 (b) The contribution is based upon previous work that, to the best
259 of my knowledge, is covered under an appropriate open source
260 license and I have the right under that license to submit that
261 work with modifications, whether created in whole or in part
262 by me, under the same open source license (unless I am
263 permitted to submit under a different license), as indicated
266 (c) The contribution was provided directly to me by some other
267 person who certified (a), (b) or (c) and I have not modified
270 (d) I understand and agree that this project and the contribution
271 are public and that a record of the contribution (including all
272 personal information I submit with it, including my sign-off) is
273 maintained indefinitely and may be redistributed consistent with
274 this project or the open source license(s) involved.
276 then you just add a line saying
278 Signed-off-by: Random J Developer <random@developer.example.org>
280 Note that git has support for adding such a message in the end of the commit