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