libnet: ARP resending more robust with periodic events
[barrelfish] / README
1 ##########################################################################
2 Copyright (c) 2009-2016, 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, Universitaetsstrasse 6, 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, 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)
22
23  * ARM CPUs, specifically ARMv7 and ARMv5. The following platforms are known to work:
24
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
31
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).
35
36 You can either generate the latest documentation from this source-code
37 (instructions at end of this file), or visit the Barrelfish_ website
38 to download them.
39
40 .. _Barrelfish: http://www.barrelfish.org/
41
42 Supported PC hardware
43 --------------------------------
44
45 Barrelfish supports following PC hardware :
46
47  * x86 CPUs in either IA-32 or AMD64 mode. The following are known to work:
48
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.
54
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:
58
59  * Intel x5000XVN
60  * Tyan n6650W and S4985
61  * Supermicro H8QM3-2
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
67
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).
71
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.
74
75 Required Tools
76 --------------------------------
77
78 Our toolchain tracks Ubuntu LTS releases, and this is what we use to
79 run our nightly tests.  If you are running Ubuntu LTS (16.04.1 at time
80 of writing), this means the following:
81
82  * GCC 5.4.0 for x86_64, ARMv7 and ARMv8
83    - Install packages gcc-arm-linux-gnueabi, g++-arm-linux-gnueabi,
84      gcc-aarch64-linux-gnu and g++-aarch64-linux-gnu on Ubuntu LTS
85  * GNU binutils (2.24 and 2.26 are known to work)
86  * GNU make
87  * GHC v7.10.3 and Parsec 3.1
88    - older versions of the tree supported v6.10 or v6.12.2 with Parsec
89      2.1 or v7.4 with Parsec 3.1, or v7.6.3 with Parsec 3.1; GHC v6.12.1 has a
90      known bug and is unable to build our tools, but now earlier versions of
91      GHC are unsupported.
92    - On Ubuntu LTS, install the following packages: 
93      libghc-mtl-dev libghc-ghc-mtl-dev cabal-install libghc-src-exts-dev
94      libghc-async-dev libghc-ghc-paths-dev libghc-parsec3-dev
95      libghc-random-dev
96    - Then, run cabal-install bytestring-trie
97  * FreeBSD's libelf:
98    - On Ubuntu install the following packages:
99      libelf-freebsd-dev freebsd-glue
100  * LibUSB 1.0 (for the usbboot tool):
101    - On Ubuntu install libusb-1.0-0-dev
102
103 Building
104 --------------------------------
105
106 1. Assuming you have already unpacked the sources, create a build directory ::
107
108     $ mkdir build && cd build
109
110 1. Run ``hake.sh``, giving it the path to the source directory and target
111 architecture(s) ::
112
113     $ ../hake/hake.sh -s ../ -a x86_64
114
115 This will configure the build directory and use GHC to compile and then run
116 hake, a tool used to generate the ``Makefile``.
117
118 3. Optionally, edit the configuration parameters in ``hake/Config.hs`` and
119 run ``make rehake`` to apply them.
120
121 4. Run make, and wait ::
122
123     $ make X86_64_Basic
124
125 5. If everything worked, you should now be able to run Barrelfish inside QEMU ::
126
127     $ make qemu_x86_64
128
129 Installing and Booting
130 --------------------------------
131
132 Barrelfish requires a Multiboot-compliant bootloader that is capable of loading
133 an ELF64 image. At the time of writing, this doesn't include the default GRUB.
134 Your options are either:
135
136  * use the pre-loader "elver" that can be found in the tools directory
137  * patch GRUB to support a 64-bit kernel image, using this patch_.
138
139 .. _patch: http://savannah.gnu.org/bugs/?17963
140
141 "Installing" Barrelfish currently consists of copying the ELF files for the CPU
142 driver and user programs to a location that the target machine can boot from,
143 and writing a suitable menu.lst file that instructs the bootloader (GRUB) which
144 programs to load and the arguments to pass them.
145
146 If you specify an appropriate INSTALL_PREFIX, ``make install`` will copy the
147 binaries to the right place for you, eg ::
148
149     $ make install INSTALL_PREFIX=/tftpboot/barrelfish
150
151 We usually boot Barrelfish via PXE/TFTP, although loading from a local disk
152 also works. Instructions for setting up GRUB to do this are beyond the scope of
153 this document. Assuming you have such a setup, here is a sample menu.lst file
154 for a basic diskless boot that doesn't do anything useful beyond probing the
155 PCI buses and starting a basic shell ::
156
157     title   Barrelfish
158     root    (nd)
159     kernel /barrelfish/x86_64/sbin/elver
160     module /barrelfish/x86_64/sbin/cpu
161     module /barrelfish/x86_64/sbin/init
162     module /barrelfish/x86_64/sbin/mem_serv
163     module /barrelfish/x86_64/sbin/monitor
164     module /barrelfish/x86_64/sbin/ramfsd boot
165     module /barrelfish/x86_64/sbin/skb boot
166     modulenounzip /barrelfish/skb_ramfs.cpio.gz nospawn
167     module /barrelfish/x86_64/sbin/acpi boot
168     module /barrelfish/x86_64/sbin/pci boot
169     module /barrelfish/x86_64/sbin/spawnd boot
170     module /barrelfish/x86_64/sbin/serial
171     module /barrelfish/x86_64/sbin/fish
172
173 There are many other programs you can load (take a look around the usr tree for
174 examples). To start a program on a core other than the BSP core, pass
175 ``core=N`` as its first argument.
176
177 If things work, you should see output on both the VGA console and COM1.
178
179 Generating Documentation
180 --------------------------------
181
182 Barrelfish documentation can be found on Barrelfish website
183 (http://www.barrelfish.org/). And it can be also generated from the code tree.
184 For documentation generation, you will need ``latex`` packages installed,
185 including support for ``pdflatex``.  Following are the instructions for
186 generating the documentation assuming you have already unpacked the sources ::
187
188     $ mkdir build && cd build
189     $ ../hake/hake.sh -s ../
190     $ make docs
191
192 You will find all the technotes in ``docs/`` directory.
193
194 Known Issues
195 --------------------------------
196
197 There are many. Those you're likely to encounter include:
198
199  * The documentation is incomplete and out of date.
200  * Some drivers and user programs are known not to build, and are
201    not included in the default set of targets (MODULES) in the Makefile.
202
203 Likely FAQs
204 --------------------------------
205
206 Q: How do I run a program?
207 A: Add it to the boot sequence by specifying the module in your menu.lst file.
208    For example, to run the memtest program, add the line:
209        module /PATH/x86_64/sbin/memtest
210    to the end of menu.lst, where PATH is relative either to your TFTP
211    server's root directory (when booting on hardware) or to your build
212    directory (when using a simulator such as QEMU).
213    If memtest runs, you should see it output "memtest passed successfully!".
214
215 Q: Where's the CPU driver?
216 A: It's in the directory named kernel :) But don't worry, it really does run
217    independently on each core.
218
219 Q: Where is the source for the SPLASH2 benchmarks? It seems to be missing.
220 A: The license for these prevents redistribution, so we were forced to ship our
221    changes as a patch. See usr/splash2/README for further instructions.
222
223 Q: Can I use a debugger?
224 A: Maybe. There are two options at the moment:
225     * On a simulator, using whatever debug interfaces it supports.
226       For QEMU, you could try the "debugsim" target.
227     * On hardware, using the kernel-mode remote GDB stubs that operate on the
228       primary serial port and are entered in response to a kernel trap or
229       exception. However, these are not well maintained, and may not be usable
230       beyond reading/writing memory locations and inspecting the stack.
231    When debugging the kernel, beware that it is relocated to an address
232    determined at core boot time. Look for output such as:
233    "Kernel starting at address 0xffffffffc072b000".
234
235 Q: Where can I find more information, including papers and new releases?
236 A: http://www.barrelfish.org/
237    http://wiki.barrelfish.org/
238
239 Q: Can I contribute?
240 A: We'd certainly like to hear from you. Feel free to send patches (or even
241    git merge requests) to the Barrelfish mailing list.
242
243    To keep track of contributions to Barrelfish, we use a sign-off procedure
244    similar to the Linux kernel:
245
246    The sign-off is a simple line at the end of the explanation for the patch,
247    which certifies that you wrote it or otherwise have the right to pass it on
248    as an open-source patch.  The rules are pretty simple: if you can certify
249    the below:
250
251         Developer's Certificate of Origin 1.1
252
253         By making a contribution to this project, I certify that:
254
255         (a) The contribution was created in whole or in part by me and I
256             have the right to submit it under the open source license
257             indicated in the file; or
258
259         (b) The contribution is based upon previous work that, to the best
260             of my knowledge, is covered under an appropriate open source
261             license and I have the right under that license to submit that
262             work with modifications, whether created in whole or in part
263             by me, under the same open source license (unless I am
264             permitted to submit under a different license), as indicated
265             in the file; or
266
267         (c) The contribution was provided directly to me by some other
268             person who certified (a), (b) or (c) and I have not modified
269             it.
270
271         (d) I understand and agree that this project and the contribution
272             are public and that a record of the contribution (including all
273             personal information I submit with it, including my sign-off) is
274             maintained indefinitely and may be redistributed consistent with
275             this project or the open source license(s) involved.
276
277    then you just add a line saying
278
279         Signed-off-by: Random J Developer <random@developer.example.org>
280
281    Note that git has support for adding such a message in the end of the commit
282    log message.