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