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