Add divby0 fault handler and abstract things better
[akaros.git] / GETTING_STARTED
1 GETTING_STARTED
2 Barret Rhoden
3
4 Last thorough update: 2013-02-07
5
6
7 1. Overview
8 ---------------------
9 In this document, I outline what steps I go through to set up my development
10 environment.  Some devs use other setups, and they can put sections farther
11 down in this document describing their steps.
12
13 Due to the nature of different workflows and different Linux distros, you'll
14 need to do some configuration of your environment.  Things won't magically work
15 out of the box.
16
17
18 2. Need help?
19 ---------------------
20 First off, if you get stuck, email someone.  You can join our mailing list by
21 sending an email to akaros-request@lists.eecs.berkeley.edu.  Send your messages
22 to akaros@lists.eecs.berkeley.edu.  Or just email me (brho@cs), though the
23 mailing list is a more scalable method in the long run.
24
25 Alternatively, you can poke your head in #akaros on irc.freenode.net.  I'm
26 usually idling in there (alone), and if I'm at my computer, I'll respond.
27
28
29 3. From Download to Hello World
30 ---------------------
31 I'll describe how to get x86 working.  RISCV is similar.
32
33 The first step is to configure the kernel.  config, menuconfig, and some of the
34 other KBuild targets work.  Defconfig gives you a default configuration.  For
35 example, to config for 64-bit x86:
36
37 $ make ARCH=x86 defconfig
38
39 Alternatively, you can run menuconfig to customize what settings you want:
40
41 $ make ARCH=x86 menuconfig
42
43 For x86, you can choose between 32 and 64 bit when you make menuconfig.  This
44 selection must match your cross compiler make command.  The default is 64 bit.
45
46 There are a lot of other settings when you make config, and you should browse
47 through to decide what you want to enable/disable.
48
49 Most everyone wants KFS turned on (Filesystems --> KFS filesystem).  This is
50 the in-memory filesystem that the kernel uses.  The kernel build scripts will
51 look at the "KFS/Initramfs paths" string and take any of those directories and
52 add them to a CPIO archive that will eventually become the root filesystem when
53 Akaros runs. These settings are set by default when you do a 'make defconfig'.
54
55 There are also settings for ext2.  If you turn on ext2 support, you need to
56 point to an img file that has been formatted with ext2 and has files in it.  If
57 you aren't messing with filesystems at all, feel free to ignore this.  It's an
58 in-memory filesystem, like KFS (linked to the end of the kernel), so you won't
59 gain much by using it for now.
60
61 3.1 Cross compiler (and glibc)
62 ----------
63 The second step is to build the cross compiler, which lives in
64 tools/compilers/gcc-glibc
65
66 $ cd tools/compilers/gcc-glibc
67
68 In this directory, you first need to set up your Makelocal file.  There is a
69 template to work from.
70
71 $ cp Makelocal.template Makelocal
72
73 You need to set your INSTDIRS to some place where you want the cross compiler
74 installed.  I have a directory named ros-gcc-glibc for this.
75
76 You also need to add bin directories to your PATH where the cross compiler will
77 be installed.  This will vary based on your value for INSTDIRS.  For instance,
78 my path contains:
79
80 /home/brho/classes/ros/ros-gcc-glibc/install-x86_64-ros-gcc/bin
81
82         and
83
84 /home/brho/classes/ros/ros-gcc-glibc/install-i686-ros-gcc/bin
85
86 You can also set up MAKE_JOBS, so you don't over or under load your system when
87 building.  I have a 2 core laptop, so I use MAKE_JOBS := 3
88
89 At this point, you can build (for example):
90
91 $ make x86_64
92
93 This might take a while (10-20 minutes for me on a 2007 era laptop).
94
95 Just to double check everything installed correctly, you should be able to run
96 x86_64-ros-gcc from your shell.
97
98 Now, you have a cross compiler ready, and you can start to build Akaros.
99
100 3.2 Kernel
101 ----------
102 cd back into the repo root.
103
104 Like the cross compiler, the kernel has its own Makelocal.
105
106 $ cp Makelocal.template Makelocal
107
108 This file is used to set up custom make targets that are not part of the
109 default Makefile, but fit nicely into your personal workflow. This file is not
110 under version control and can me made to contain just about anything.
111
112 Now you're ready to build the kernel:
113
114 $ make
115
116 So the kernel built, but you can't do much with it, and you probably have no
117 programs.
118
119 Notice that we didn't have to set the ARCH variable this time.  The make system
120 knows what architecture we are set up for and will always build for that
121 architecture until a new ARCh is selected (i.e. via 'make ARCH=xxx defconfig'
122 etc.)
123
124 3.3 Userspace
125 ---------
126 To build userspace and test programs:
127
128 $ make tests
129
130 You now have programs and libraries, and need to put them in KFS.  To do this,
131 we provide a 'fill-kfs' make target. 
132
133 $ make fill-kfs
134
135 The 'fill-kfs' target copies your cross compiler's shared libraries and all
136 test binaries into the first "KFS/Initramfs path" you set during configuration
137 (or kern/kfs/lib if you just kept the default).
138
139 Now that you've changed the contents of KFS's source, remake the kernel.  You
140 should see something like
141         Building initramfs:
142                 Adding kern/kfs to initramfs...
143 before the kernel links.  If you don't see this, then you probably didn't
144 actually fill KFS properly.
145
146 3.4 Busybox
147 ---------
148 If you don't care about busybox or just want to get started immediately, skip
149 this section.
150
151 Other userspace programs, like busybox need to be compiled with the cross
152 compiler and then have their binaries copied to kern/kfs/bin (I do this
153 manually).
154
155 I'm running busybox 1.17.3, and the config file I use is in
156 tools/patches/busybox.  Copy that to your busybox directory (once you download
157 and untar it, etc) and name it ".config".  This config file assumes you want
158 x86_64-ros-gcc.  If you are builidng for 32 bit x86 or riscv, you will need to
159 edit the config file.
160
161 You can get busybox from http://www.busybox.net/downloads/.  Eventually I'll
162 upgrade, though it hasn't been a big deal yet.
163
164 $ cd BUSYBOXDIR/..
165 $ wget http://www.busybox.net/downloads/busybox-1.17.3.tar.bz2
166 $ tar -jxvf busybox-1.17.3.tar.bz2
167 $ cd AKAROS-ROOT
168 $ cp tools/patches/busybox/busybox-1.17.3.config BUSYBOXDIR/.config
169
170 $ cd BUSYBOXDIR
171
172 You'll also want to apply any patches for busybox.  From the busybox directory:
173
174 $ patch -p1 < AKAROS-ROOT/tools/patches/busybox/EACH_PATCH_FILE.patch
175 $ make
176
177 Then I copy the unstripped binary to KFS.
178
179 $ cp busybox_unstripped AKAROS-ROOT/kern/kfs/bin/busybox
180
181 Note I change the name to busybox (dropping the unstripped).  I want the
182 unstripped binary for debugging reasons.
183
184 Busybox can do core commands like ls and rm, as well as run a shell (ash), all
185 from within one binary.  It can tell which command it should execute based on
186 the name of the binary (or symlink to it).  I have a bunch of symlinks for
187 whatever 'busybox' programs I want to run inside kern/kfs/bin.
188
189 For instance, from my AKAROS-ROOT:
190 $ ls -l kern/kfs/bin/ | grep busybox
191 lrwxrwxrwx 1 brho brho      7 Aug 24  2010 ash -> busybox
192 -rwxr-xr-x 1 brho brho 337917 Dec 19 17:39 busybox
193 lrwxrwxrwx 1 brho brho      7 Sep 29  2010 cat -> busybox
194 lrwxrwxrwx 1 brho brho      7 Sep  1  2010 cp -> busybox
195 lrwxrwxrwx 1 brho brho      7 Oct 18 13:12 kill -> busybox
196 lrwxrwxrwx 1 brho brho      7 Sep  5  2010 ln -> busybox
197 lrwxrwxrwx 1 brho brho      7 Aug 23  2010 ls -> busybox
198 lrwxrwxrwx 1 brho brho      7 Sep  5  2010 mkdir -> busybox
199 lrwxrwxrwx 1 brho brho      7 Sep  5  2010 rmdir -> busybox
200 lrwxrwxrwx 1 brho brho      7 Apr  9  2012 stty -> busybox
201 lrwxrwxrwx 1 brho brho      7 Apr  9  2012 tty -> busybox
202
203 Note I don't need to update the symlinks (almost ever...).  I just recopy the
204 busybox binary whenever I update it.
205
206 I think some of the other devs build busybox so that it spits out the links
207 into an install directory.  Feel free to do whatever.  I'll probably just add a
208 bunch of symlinks to the repos default KFS contents one of these days.
209 Incidentally, kern/kfs/* is ignored by git.
210
211 Now that you've changed KFS, don't forget to remake the kernel.
212
213 3.5 Building and Loading a Virtual Machine Image
214 ---------
215 At this point, you probably have a runnable kernel with programs in KFS.  It
216 should be sitting at obj/kernel/akaros-kernel.  When running in a VM, you can
217 either run the kernel directly from qemu, or put it in a virtual machine image
218 file. 
219
220 If you don't want to bother with the image, skip this section.  I tend to run
221 my images off an image file, since qemu acts more like hardware (as far as
222 multiboot goes).  The downside is the boot up is slower, especially if you have
223 a large kernel (>100MB).  It also takes some effort to set up the VM image.
224
225 If you are still reading, you'll need an image file that looks like a hard disk
226 to boot qemu off of.  I put one similar to mine at:
227 http://akaros.cs.berkeley.edu/files/hdd268mb.img
228
229 It's around 268MB (256MiB, or whatever).  If you want to make your own, check
230 out Documentation/howtos/make-bootable-grub-hdd.txt.  That's actually the
231 original document I made back when I first figured it out back in 2009, which
232 has been updated again in 2013.    In between, I wrote it up online at
233 http://www.omninerd.com/articles/Installing_GRUB_on_a_Hard_Disk_Image_File,
234 which has some other tidbits in the comments.  Both methods still use grub1.
235
236 Anyway, I put that img in AKAROS-ROOT/mnt/, and make a folder next to it:
237 AKAROS-ROOT/mnt/hdd.  mnt/hdd is the mount point where I mount hdd.img (Note I
238 don't call it hdd64mb.img on my dev machine).
239
240 Personally, I always have hdd.img mounted.  Some of the other devs have make
241 targets that mount and umount it.  Whenever I reboot my development machine, I
242 run a script (as root) that mounts the image file and sets up a few things for
243 networking.  I put a script I use for this in scripts/kvm-up.sh.  You'll likely
244 want to copy it to the directory *above* the akaros root directory and edit it
245 accordingly. Feel free to comment out the networking stuff.  That's for using
246 networking in qemu.
247
248 Now that your image file is mounted at mnt/hdd, you'll want to copy your
249 freshly built kernel to the root of the image.  I have a make target in my
250 makelocal for this, so that whenever I do a make kvm, it builds the kernel and
251 copies it to my hdd.img.
252
253 I added edited versions of my KVM (and USB) make targets to the
254 Makelocal.template.  Uncomment the KVM one (at least).
255
256 Incidentally, I also have the following in my Makelocal, so that make (and make
257 all) also make kvm:
258
259 all: kvm
260
261 Now, make kvm.  You should be able to see the new kernel in mnt/hdd/ (do an ls
262 -l and check the timestamp).
263
264 3.6 Running Qemu
265 ---------
266 Here is the command I use to run qemu/kvm.  It's evolved over the years, and it
267 will vary based on your linux distribution.  Don't run it just yet:
268
269 $ qemu-system-i386 -s -enable-kvm -cpu phenom -smp 8 -m 2048 -nographic -monitor /dev/pts/3 -net nic,model=e1000 -net tap,ifname=tap0,script=no mnt/hdd.img
270
271 If you skipped making a virtual machine image, replace "mnt/hdd.img" with
272 "-kernel obj/kern/akaros-kernel".
273
274 The -monitor is the qemu monitor, which is a CLI for qemu.  Pick a
275 tab/terminal/pty in Linux that you will only use for qemu monitoring, and enter
276 'tty'.  Whatever it tells you, put in place of /dev/pts/3.  I've been using the
277 same tab for about 4 years now.  In that tab, enter 'sleep 999999999'.  Qemu
278 will still access it, but you won't have to worry about bash trying to handle
279 your inputs.
280
281 -nographic allows qemu to work in the terminal you run qemu from, instead of
282 spawning off a fake cpu crt/monitor.
283
284 If you don't have networking set up (including the tun/tap stuff from
285 kvm-up.sh), remove the -net commands/options.
286
287 Fell free to pick different values for the number of cpus and RAM (8 and 1024
288 in the example).
289
290 Once you finally run it, you can stop the VM by entering 'q' to the qemu
291 monitor (or just killing the process)..  Other help commands from the monitor
292 include 'info cpus', 'info registers', 'x', and 'help'.
293
294
295 3.7 Running on Hardware
296 ---------
297 I have a few bootable USB sticks with grub set up to run Akaros.  The make usb
298 target (example in Makelocal.template) will copy freshly made kernels to your
299 USB device.  You'll need to adjust those paths according to your distro.  My
300 usb sticks are usually /dev/sdc, for instance (some odd USB device in the last
301 couple of years has taken over /dev/sdb.  Probably something to do with udev
302 changing over the years).
303
304 Anyway, you'll need to mess around a bit to get that working.  Or I can dd one
305 for you (I have 4GB disks in my office that I use).  If you make your own, the
306 critical part is getting grub to pick the right device (from what I remember),
307 and its fairly similar to installing grub on any old hard drive (since it's
308 just a bloc device).  Much easier than a hard disk image file.
309
310
311 3.8 Hello World
312 ---------
313 So now you can run the kernel.  It's time to edit a program (or make your own).
314 In this, I'll go through my workflow for making changes.
315
316 $ vi tests/hello.c
317 (edit, save)
318
319 $ make tests
320 (new version in obj/tests/hello)
321
322 $ make fill-kfs
323 (updates kfs)
324
325 $ make
326 (rebuilds kernel with the new KFS)
327
328 $ qemu...
329
330 (following commands are in Akaros)
331 Shift-G (to get to the kernel monitor)
332
333 ROS(Core 0)> bb (to run busybox)
334
335 / $ hello
336 (Should print your message)
337
338
339 3.9 Other Dev Workflow stuff
340 ---------
341 One thing to note is that while we use dynamic linking for libc, parlib
342 libraries are statically linked with applications.  In fact, nowadays *all*
343 Akaros programs need to be linked againt parlib (used to be that single-core
344 processes (SCPs) didn't need it).
345
346 The makefiles won't notice if you change a file in parlib and then remake a
347 binary.  So if you edit user/parlib/uthread.c for example, tests/pthread_test
348 won't get rebuilt.  Here's what I do:
349
350 $ vi user/parlib/uthread.c (make awesome change)
351
352 $ touch tests/pthread_test.c ; make tests
353
354 This will force the rebuild of pthread_test.  Older, untouched binaries (e.g.
355 block_test), won't get rebuilt.  I actually want this in some cases (different
356 versions of parlib when I'm running certain tests).  Anyway, just pay attention
357 to what you're building.  There's not much output in the console, so you should
358 be able to see what's going on all the time.  (unlike when building glibc...).
359
360 Oh, and don't forget to:
361
362 $ make fill-kfs
363
364 to make sure you run the new pthread_test. 
365
366 Additionally, when switching between 32 and 64 bit x86, make objclean before
367 filling KFS.  This is the easiest way to make sure you get the appropriate
368 libraries loaded in KFS.
369
370 Early on as a dev, there are lots of times where you accidentally don't run the
371 right program (or kernel) and won't understand why your change isn't happening.
372 A few printk("WTF\n")'s later, you realize you didn't have the hdd.img mounted,
373 or you didn't fill KFS, or you didn't relink your binaries, or you forgot to
374 save all files in vi (and not just the current buffer).  But after doing a
375 couple hello worlds, you're set. 
376
377 Alternatively, you could have a make target to run qemu, which also touches all
378 binaries (or otherwise enforces a rebuild), auto-fills KFS, remakes the kernel,
379 and mounts/copies/unmounts your hdd.img.  Kevin's sim repo has stuff like this,
380 so check it out if that's what you're into.  (I think it is at
381 http://akaros.cs.berkeley.edu/ros-sim.tar.gz).  Personally, I'm not that into
382 it, since I like to keep track of what is going on under the hood, esp if I
383 want to do something a little differently (like with testing ext2, having
384 different versions of parlib with some binaries, or being picky about my
385 mount/umounts).
386
387
388 4. RISCV
389 ---------------------
390 TODO.
391
392 For now, you need a 64 bit distro to build the RISCV stuff, so I don't do it
393 very often.  I'll eventually sync up with Andrew and we'll get this part sorted
394 out.
395
396
397 5. Other Developer's Stuff
398 ---------------------