Updated the README and Practical guide so that they have instructions
[barrelfish] / doc / 018-Practical-guide / readme.tex
1 \section{Barrelfish Overview%
2   \label{barrelfish-overview}%
3 }
4
5 Barrelfish currently runs on:
6 %
7 \begin{quote}
8 %
9 \begin{itemize}
10
11 \item x86 CPUs in either IA-32 or AMD64 mode. The following are known to work:
12 %
13 \begin{itemize}
14
15 \item Intel Xeon Clovertown, Gainestown, Beckton (X5355, E5520, X7560, L5520,
16 L7555)
17
18 \item AMD Opteron Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
19 (2220, 8350, 8374, 8380, 8431, 6174)
20
21 \item QEMU simulator
22
23 \end{itemize}
24
25 \item Intel Single-Chip Cloud Computer (SCC), both Copper Ridge and Rocky Lake
26 are known to work.
27
28 \item ARM Platform
29 - ARMv7 and ARMv5 architectures
30 - GEM5 simulator
31 - Pandaboard System On Chip platform
32
33 \end{itemize}
34
35 \end{quote}
36
37 This README file documents instructions for x86 architecture.  For other
38 architectures, please refer to the corresponding technote documentations.
39 You can either generate the latest documentation from this source-code
40 (instructions at end of this file), or visit the \href{http://www.barrelfish.org/}{Barrelfish} website
41 to download them.
42
43
44 \section{Supported PC hardware%
45   \label{supported-pc-hardware}%
46 }
47
48 Barrelfish supports following PC hardware :
49 %
50 \begin{quote}
51 %
52 \begin{itemize}
53
54 \item x86 CPUs in either IA-32 or AMD64 mode. The following are known to work:
55 %
56 \begin{itemize}
57
58 \item Intel Xeon Clovertown, Gainestown, Beckton (X5355, E5520, X7560, L5520,
59 L7555)
60
61 \item AMD Opteron Santa Rosa, Barcelona, Shanghai, Istanbul, Magny Cours
62 (2220, 8350, 8374, 8380, 8431, 6174)
63
64 \end{itemize}
65
66 \end{itemize}
67
68 \end{quote}
69
70 The biggest compatibility problems are likely to be in the PCI/ACPI code. We
71 usually discover new quirks (or missing functionality in the ACPI glue code)
72 on each new machine we test. The following systems are known to work:
73 %
74 \begin{quote}
75 %
76 \begin{itemize}
77
78 \item Intel x5000XVN
79
80 \item Tyan n6650W and S4985
81
82 \item Supermicro H8QM3-2
83
84 \item Dell PowerEdge R610 and R905
85
86 \item Sun Fire X2270 and X4440
87
88 \item Intel/Quanta QSSC-S4R
89
90 \item Lenovo X200 and X301 laptops
91
92 \item ASUS Eee PC 1015PEM netbooks
93
94 \end{itemize}
95
96 \end{quote}
97
98 The e1000n driver should work with most recent Intel gigabit ethernet
99 controllers (see the list in devices/e1000.dev). We've mostly used the
100 82572EI (PCI device ID 0x1082).
101
102 You should also be able to boot Barrelfish on a recent version of QEMU (0.14);
103 note that the e1000 device emulated by QEMU is not supported by our driver.
104
105
106 \section{Required Tools%
107   \label{required-tools}%
108 }
109
110 The following are required to build Barrelfish and its tools:
111 %
112 \begin{quote}
113 %
114 \begin{itemize}
115
116 \item GCC 4.x
117 %
118 \begin{itemize}
119
120 \item 4.4.5, and 4.5.2 are known to work
121
122 \item cross-compiling between i386 and x86\_64 works (requires libc6-dev-i386
123 to build 32 bit on 64 bit machine)
124
125 \item for the ARM port, we recommend the EABI tools available from \href{http://www.codesourcery.com/sgpp/lite/arm}{CodeSourcery}.
126
127 \end{itemize}
128
129 \item GNU binutils (2.19 is known to work)
130
131 \item GNU make
132
133 \item GHC v7.4 and Parsec 3.1
134 - older versions of the tree supported v6.10 or v6.12.2 with Parsec 2.1
135 - GHC v6.12.1 has a known bug and is unable to build our tools
136 - earlier versions of GHC are unsupported
137
138 \end{itemize}
139
140 \end{quote}
141
142 Our build system may not be very portable; if in doubt, try building on a
143 recent Debian or Ubuntu system, as these are what we use.
144
145
146 \section{Building%
147   \label{building}%
148 }
149 \newcounter{listcnt0}
150 \begin{list}{\arabic{listcnt0}.}
151 {
152 \usecounter{listcnt0}
153 \setlength{\rightmargin}{\leftmargin}
154 }
155
156 \item Assuming you have already unpacked the sources, create a build directory
157 %
158 \begin{quote}{\ttfamily \raggedright \noindent
159 \$~mkdir~build~\&\&~cd~build
160 }
161 \end{quote}
162 \end{list}
163
164 1. Run \texttt{hake.sh}, giving it the path to the source directory and target
165 architecture(s)
166 %
167 \begin{quote}{\ttfamily \raggedright \noindent
168 \$~../hake/hake.sh~-s~../~-a~x86\_64
169 }
170 \end{quote}
171
172 This will configure the build directory and use GHC to compile and then run
173 hake, a tool used to generate the \texttt{Makefile}.
174
175 3. Optionally, edit the configuration parameters in \texttt{hake/Config.hs} and
176 run \texttt{make rehake} to apply them.
177 \setcounter{listcnt0}{0}
178 \begin{list}{\arabic{listcnt0}.}
179 {
180 \usecounter{listcnt0}
181 \addtocounter{listcnt0}{3}
182 \setlength{\rightmargin}{\leftmargin}
183 }
184
185 \item Run make, and wait
186 %
187 \begin{quote}{\ttfamily \raggedright \noindent
188 \$~make
189 }
190 \end{quote}
191
192 \item If everything worked, you should now be able to run Barrelfish inside QEMU
193 %
194 \begin{quote}{\ttfamily \raggedright \noindent
195 \$~make~sim
196 }
197 \end{quote}
198 \end{list}
199
200
201 \section{Installing and Booting%
202   \label{installing-and-booting}%
203 }
204
205 Barrelfish requires a Multiboot-compliant bootloader that is capable of loading
206 an ELF64 image. At the time of writing, this doesn't include the default GRUB.
207 Your options are either:
208 %
209 \begin{quote}
210 %
211 \begin{itemize}
212
213 \item use the pre-loader ``elver'' that can be found in the tools directory
214
215 \item patch GRUB to support a 64-bit kernel image, using this \href{http://savannah.gnu.org/bugs/?17963}{patch}.
216
217 \end{itemize}
218
219 \end{quote}
220
221 ``Installing'' Barrelfish currently consists of copying the ELF files for the CPU
222 driver and user programs to a location that the target machine can boot from,
223 and writing a suitable menu.lst file that instructs the bootloader (GRUB) which
224 programs to load and the arguments to pass them.
225
226 If you specify an appropriate INSTALL\_PREFIX, \texttt{make install} will copy the
227 binaries to the right place for you, eg
228 %
229 \begin{quote}{\ttfamily \raggedright \noindent
230 \$~make~install~INSTALL\_PREFIX=/tftpboot/barrelfish
231 }
232 \end{quote}
233
234 We usually boot Barrelfish via PXE/TFTP, although loading from a local disk
235 also works. Instructions for setting up GRUB to do this are beyond the scope of
236 this document. Assuming you have such a setup, here is a sample menu.lst file
237 for a basic diskless boot that doesn't do anything useful beyond probing the
238 PCI buses and starting a basic shell
239 %
240 \begin{quote}{\ttfamily \raggedright \noindent
241 title~~~Barrelfish\\
242 root~~~~(nd)\\
243 kernel~/barrelfish/x86\_64/sbin/elver\\
244 module~/barrelfish/x86\_64/sbin/cpu\\
245 module~/barrelfish/x86\_64/sbin/init\\
246 module~/barrelfish/x86\_64/sbin/mem\_serv\\
247 module~/barrelfish/x86\_64/sbin/monitor\\
248 module~/barrelfish/x86\_64/sbin/ramfsd~boot\\
249 module~/barrelfish/x86\_64/sbin/skb~boot\\
250 modulenounzip~/barrelfish/skb\_ramfs.cpio.gz~nospawn\\
251 module~/barrelfish/x86\_64/sbin/acpi~boot\\
252 module~/barrelfish/x86\_64/sbin/pci~boot\\
253 module~/barrelfish/x86\_64/sbin/spawnd~boot\\
254 module~/barrelfish/x86\_64/sbin/serial\\
255 module~/barrelfish/x86\_64/sbin/fish
256 }
257 \end{quote}
258
259 There are many other programs you can load (take a look around the usr tree for
260 examples). To start a program on a core other than the BSP core, pass
261 \texttt{core=N} as its first argument.
262
263 If things work, you should see output on both the VGA console and COM1.
264
265