1 [Kernel, CS 235 Advanced Operating Systems, Fall 2010
5 You'll use two sets of tools in this class: an x86 emulator, QEMU, for running
6 your kernel; and a compiler toolchain, including assembler, linker, C compiler,
7 and debugger, for compiling and testing your kernel. Here's the information
8 you'll need to download and install your own copies. This class assumes
9 familiarity with Unix commands throughout.
13 A "compiler toolchain" is the set of programs, including C and C++ compilers,
14 assemblers, and linkers, that turn code into executable binaries. You'll need a
15 compiler toolchain that generates code for 32-bit Intel architectures ("x86"
16 architectures) in the ELF binary format. We recommend you configure one of your
17 machines (such as a laptop) with a working toolchain, but if you cannot do
18 this, the School of Engineering's SEASnet and a private class compute server
19 will be made available shortly.
21 Test Your Compiler Toolchain
23 Modern Linux and BSD UNIX distributions already provide a toolchain suitable
24 for CS 235. To test your distribution, try the following command:
28 If the second line is elf32-i386, you're all set, and don't need to compile
31 Using a Virtual Machine
33 Otherwise, the easiest way to get a compatible toolchain is to install a modern
34 Linux distribution on your computer. With platform virtualization, Linux can
35 cohabitate with your normal computing environment. Installing a Linux virtual
36 machine is a two step process. First, you download the virtualization platform.
38 • VirtualBox (free for Mac, Linux, Windows) — Download page
39 • VMware Player (free for Linux and Windows, registration required)
40 • VMware Fusion ($80 for Mac, $40 with academic discount)
42 VirtualBox is a little slower and less flexible, but free!
44 Once the virtualization platform is installed, download a boot disk image for
45 the Linux distribution of your choice.
47 • Ubuntu Desktop is what we use.
49 This will download a file named something like ubuntu-10.04.1-desktop-i386.iso.
50 Start up your virtualization platform and create a new (32-bit) virtual
51 machine. Use the downloaded Ubuntu image as a boot disk; the procedure differs
52 among VMs but is pretty simple. Type objdump -i, as above, to verify that your
53 toolchain is now set up. You will do your work inside the VM.
55 Building Your Own Toolchain
57 This will take longer to set up, but give slightly better performance than a
58 virtual machine, and lets you work in your own familiar environment. (Mac/Unix
61 We assume that you are installing the toolchain into /usr/local. You will need
62 a fair amount of disk space to compile the tools (around 1GiB). If you don't
63 have that much space, delete each directory after its make install step.
65 Download the following packages:
67 • ftp://ftp.gmplib.org/pub/gmp-5.0.1/gmp-5.0.1.tar.bz2
68 • http://www.mpfr.org/mpfr-current/mpfr-3.0.0.tar.bz2
69 • http://www.multiprecision.org/mpc/download/mpc-0.8.2.tar.gz
70 • http://ftpmirror.gnu.org/binutils/binutils-2.20.1.tar.bz2
71 • http://ftpmirror.gnu.org/gcc/gcc-4.5.1/gcc-core-4.5.1.tar.bz2
72 • http://ftpmirror.gnu.org/gcc/gcc-4.5.1/gcc-g++-4.5.1.tar.bz2
73 • http://ftpmirror.gnu.org/gdb/gdb-7.2.tar.bz2
75 Unpack and build the packages. The green bold text shows you how to install
76 into /usr/local, which is what we recommend. To install into a different
77 directory, $PFX, click herenote the differences in lighter type (hide). If you
78 have problems, see below.
80 export PATH=$PFX/bin:$PATH
81 export LD_LIBRARY_PATH=$PFX/lib:$LD_LIBRARY_PATH # On Mac OS X, use DYLD_LIBRARY_PATH
83 tar xjf gmp-5.0.1.tar.bz2
85 ./configure --prefix=/usr/local--prefix=$PFX
87 make install # This step may require privilege (sudo make install)
90 tar xjf mpfr-3.0.0.tar.bz2
92 ./configure --prefix=/usr/local--prefix=$PFX --with-gmp=$PFX
94 make install # This step may require privilege (sudo make install)
97 tar xzf mpc-0.8.2.tar.gz
99 ./configure --prefix=/usr/local--prefix=$PFX --with-gmp=$PFX --with-mpfr=$PFX
101 make install # This step may require privilege (sudo make install)
105 tar xjf binutils-2.20.1.tar.bz2
107 ./configure --prefix=/usr/local--prefix=$PFX --target=i386-jos-elf --disable-werror
109 make install # This step may require privilege (sudo make install)
112 i386-jos-elf-objdump -i
113 # Should produce output like:
114 # BFD header file version (GNU Binutils) 2.20.1.20100303
116 # (header little endian, data little endian)
120 tar xjf gcc-core-4.5.1.tar.bz2
121 tar xjf gcc-g++-4.5.1.tar.bz2
123 mkdir build # GCC will not compile correctly unless you build in a separate directory
125 ../configure --prefix=/usr/local--prefix=$PFX --with-gmp=$PFX --with-mpfr=$PFX --with-mpc=$PFX \
126 --target=i386-jos-elf --disable-werror \
127 --disable-libssp --disable-libmudflap --with-newlib \
128 --without-headers --enable-languages=c,c++
130 make install-gcc # This step may require privilege (sudo make install-gcc)
131 make all-target-libgcc
132 make install-target-libgcc # This step may require privilege (sudo make install-target-libgcc)
136 # Should produce output like:
137 # Using built-in specs.
138 # COLLECT_GCC=i386-jos-elf-gcc
139 # COLLECT_LTO_WRAPPER=/usr/local/libexec/gcc/i386-jos-elf/4.5.1/lto-wrapper
140 # Target: i386-jos-elf
143 tar xjf gdb-7.2.tar.bz2
145 ./configure --prefix=/usr/local--prefix=$PFX --target=i386-jos-elf --program-prefix=i386-jos-elf- \
148 make install # This step may require privilege (sudo make install)
153 Q. I can't run make install because I don't have root permission on this
155 A. Our instructions assume you are installing into the /usr/local
156 directory. However, this may not be allowed in your environment. If you can
157 only install code into your home directory, that's OK. In the instructions
158 above, replace --prefix=/usr/local with --prefix=$HOME (and click here to
159 update the instructions further). You will also need to change your PATH
160 and LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (Mac OS X) environment
161 variables, to inform your shell where to find the tools. For example:
163 export PATH=$HOME/bin:$PATH
164 export LD_LIBRARY_PATH=$HOME/lib:$LD_LIBRARY_PATH
166 Enter these lines in your ~/.bashrc file so you don't need to type them
167 every time you log in.
169 Q. My build fails with an inscrutable message about "library not found".
170 A. You need to set your LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (Mac
171 OS X) environment variable to include the libraries you built; see above.
172 The environment variable must include the PREFIX/lib directory (for
173 instance, /usr/local/lib).
177 We provide a patched version of the QEMU emulator with improved support for
178 debugging. (Credit to Kohler and Austin Clements and others at MIT 6.828.) We
179 recommend you compile QEMU from this source; if you use the version that came
180 installed on your Linux distribution, you will not be able to complete all the
183 First, download the source:
185 • http://www.cs.ucla.edu/~kohler/class/10f-aos/qemu-0.12.5-aos.tar.bz2
187 On a Linux machine, you will need to install the SDL graphics library to build
188 QEMU. On Ubuntu or Debian:
190 sudo aptitude install libsdl1.2-dev
192 Then unpack, compile, and install QEMU as follows.
194 tar xjf qemu-0.12.5-aos.tar.bz2
197 ./configure --prefix=/usr/local --disable-sdl --enable-cocoa \
198 --disable-docs --target-list="i386-softmmu x86_64-softmmu"
200 ./configure --prefix=/usr/local --target-list="i386-softmmu x86_64-softmmu"
202 make install # This step may require privilege (sudo make install)
204 The QEMU monitor is accessible by pressing Ctrl-Alt-2 inside the QEMU window.
205 Return to normal display with Ctrl-Alt-1. QEMU tends to take control of your
206 mouse. If you can't find a mouse pointer, check the QEMU title bar for text
207 like "Press Ctrl-Alt to exit grab" and, if so, press Ctrl-Alt to regain
212 You will do your work using a source code control system. This will help you
213 maintain two parallel branches—one with your changes, and one with the labs as
214 we release them. We will support two source code control systems: CVS and Git.
215 Git is by far the better system, and strongly preferred by your instructor for
216 his own work, but this is the first time we're trying it in CS 235, so it will
217 be more experimental.
219 You don't need to compile CVS or Git yourself. The packaged versions that come
220 with your OS will be good enough. You just need to install them.
222 • Ubuntu/Debian Linux: Run sudo aptitude install cvs git-core
223 • Mac OS X: Install MacPorts, then run sudo port install cvs git-core
224 • Windows: Versions are available; contact the instructor if you need help
226 Using Cygwin on a Windows Machine
228 If you have a Windows machine, but cannot run a Linux virtual machine or
229 install a dual-boot configuration, the easiest way to work on labs from home
230 will be to use a class compute server or SEASnet coupled with VNC remote
231 display. Let us know as soon as possible if you want this configuration to
234 Nevertheless, it should be possible to execute many of the above steps and get
235 a functional build environment running on Windows using Cygwin. Here's how to
236 install Cygwin on your Windows machine.
238 1. Install Cygwin/X. Follow this procedure. Make sure you select the
239 "xorg-x11-base" package and the "openssh" package. Also select the "flex"
240 and "bison" packages from the development header. This sets up a Unix-like
241 environment on your Windows machine, including an X server.
242 2. Start the Cygwin X server by running startxwin.bat. "Run /usr/X11R6/bin/
243 startxwin.bat by double-clicking it in Windows Explorer." http://
244 x.cygwin.com/docs/ug/using.html
246 You should also be able to compile the class tools and the labs on your Windows
247 machine, once Cygwin has been installed. Let us know if you have success with
250 Using the Class Compute Server
252 A compute server is available for your use. Request a login from your
253 instructor; your mail should include your preferred username and an SSH public
254 key (use PuTTY on Windows [PuTTY authentication notes]).
258 VNC is a compressed remote desktop viewing protocol that QEMU understands.
259 Using VNC will be faster; QEMU is very slow over a remote X connection. You
260 will need a VNC viewer on your local computer. Good, free viewers are available
261 for Linux, Mac OS X, and Windows.
263 When the instructor creates your account, you'll receive a VNC port allocation
264 (something like 5500). Remember this number; we call it VNCPORT below.
266 • Download a VNC viewer. On Linux, we have tested TightVNC (Ubuntu/Debian
267 package xtightvncviewer). On Mac OS X, try Chicken of the VNC (an installer
268 disk image is available). On Windows, TightVNC also works.
269 • Start your VNC viewer in “listening” mode, on port 5500 (display 0). On
270 Linux with TightVNC, try
272 vncviewer -listen 0 -encodings "copyrect zlib raw"
274 (You can leave off the -encodings argument, but display will be slower.) On
275 Mac OS X with Chicken, try "Connection > Listen for Server...", and enter
277 • Log on to the class server, forwarding the server's VNCPORT to your local
278 port 5500. This will let the server QEMU display into your local VNC
279 window. Sample command:
281 ssh -RVNCPORT:localhost:5500 seek.cs.ucla.edu
283 • When running QEMU on the server using make, supply the argument VNC=VNCPORT
290 This may be simpler if you have trouble finding a VNC viewer. Simply start up
293 ssh -Y seek.cs.ucla.edu
295 Do your work as usual. The -Y option will forward QEMU's window onto your local
296 display. Try make run-nox if you don't need the QEMU window.
298 Back to CS 235 Advanced Operating Systems