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