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