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