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