0bb9f9b1c2e5444e20761e1dc45f3ce99ef98ebd
[akaros.git] / GETTING_STARTED.md
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 You can also set up MAKE_JOBS, so you don't over or under load your system when
83 building.  I have a 2 core laptop, so I use MAKE_JOBS := 3
84
85 At this point, you can build (for example):
86
87 $ make x86_64
88
89 This might take a while (10-20 minutes for me on a 2007 era laptop).
90
91 Just to double check everything installed correctly, you should be able to run
92 x86_64-ros-gcc from your shell.
93
94 Now, you have a cross compiler ready, and you can start to build Akaros.
95
96 3.2 Kernel
97 ----------
98 cd back into the repo root.
99
100 Like the cross compiler, the kernel has its own Makelocal.
101
102 $ cp Makelocal.template Makelocal
103
104 This file is used to set up custom make targets that are not part of the
105 default Makefile, but fit nicely into your personal workflow. This file is not
106 under version control and can me made to contain just about anything.
107
108 Now you're ready to build the kernel:
109
110 $ make
111
112 So the kernel built, but you can't do much with it, and you probably have no
113 programs.
114
115 Notice that we didn't have to set the ARCH variable this time.  The make system
116 knows what architecture we are set up for and will always build for that
117 architecture until a new ARCh is selected (i.e. via 'make ARCH=xxx defconfig'
118 etc.)
119
120 3.3 Userspace
121 ---------
122 To build userspace and test programs:
123
124 $ make tests
125
126 You now have programs and libraries, and need to put them in KFS.  To do this,
127 we provide a 'fill-kfs' make target. 
128
129 $ make fill-kfs
130
131 The 'fill-kfs' target copies your cross compiler's shared libraries and all
132 test binaries into the first "KFS/Initramfs path" you set during configuration
133 (or kern/kfs/lib if you just kept the default).
134
135 Now that you've changed the contents of KFS's source, remake the kernel.  You
136 should see something like
137         Building initramfs:
138                 Adding kern/kfs to initramfs...
139 before the kernel links.  If you don't see this, then you probably didn't
140 actually fill KFS properly.
141
142 3.4 Busybox
143 ---------
144 Busybox provides our shell and some basic utilities.  You almost certainly want
145 to build and install busybox.
146
147 Userspace programs like busybox need to be compiled with the cross compiler and
148 then have their binaries copied to kern/kfs/bin.  Since most everyone wants
149 busybox and we have a few patches of our own, we have support for automatically
150 building and installing it to KFS.
151
152 For the default build (x86_64):
153
154 $ cd tools/apps/busybox
155 $ make [x86_64|riscv]
156 $ cd -
157
158 And you should be set.  Check kfs to make sure everything installed.  You
159 should get sane results from:
160
161 $ ls -l kern/kfs/bin | grep cat
162 lrwxrwxrwx 1 brho brho       7 Jan 23 09:19 cat -> busybox
163
164 You can customize your busybox installation, including the install prefix, the
165 .config file, and make jobs.  Check out the makefile in tools/apps/busybox for
166 details.
167
168 Now that you've changed KFS, don't forget to remake the kernel.
169
170 3.5 Building and Loading a Virtual Machine Image
171 ---------
172 At this point, you probably have a runnable kernel with programs in KFS.  It
173 should be sitting at obj/kernel/akaros-kernel.  When running in a VM, you can
174 either run the kernel directly from qemu, or put it in a virtual machine image
175 file. 
176
177 If you don't want to bother with the image, skip this section.  I tend to run
178 my images off an image file, since qemu acts more like hardware (as far as
179 multiboot goes).  The downside is the boot up is slower, especially if you have
180 a large kernel (>100MB).  It also takes some effort to set up the VM image.
181
182 If you are still reading, you'll need an image file that looks like a hard disk
183 to boot qemu off of.  I put one similar to mine at:
184 http://akaros.cs.berkeley.edu/files/hdd268mb.img
185
186 It's around 268MB (256MiB, or whatever).  If you want to make your own, check
187 out Documentation/howtos/make-bootable-grub-hdd.txt.  That's actually the
188 original document I made back when I first figured it out back in 2009, which
189 has been updated again in 2013.    In between, I wrote it up online at
190 http://www.omninerd.com/articles/Installing_GRUB_on_a_Hard_Disk_Image_File,
191 which has some other tidbits in the comments.  Both methods still use grub1.
192
193 Anyway, I put that img in AKAROS-ROOT/mnt/, and make a folder next to it:
194 AKAROS-ROOT/mnt/hdd.  mnt/hdd is the mount point where I mount hdd.img (Note I
195 don't call it hdd64mb.img on my dev machine).
196
197 Personally, I always have hdd.img mounted.  Some of the other devs have make
198 targets that mount and umount it.  Whenever I reboot my development machine, I
199 run a script (as root) that mounts the image file and sets up a few things for
200 networking.  I put a script I use for this in scripts/kvm-up.sh.  You'll likely
201 want to copy it to the directory *above* the akaros root directory and edit it
202 accordingly. Feel free to comment out the networking stuff.  That's for using
203 networking in qemu.
204
205 Now that your image file is mounted at mnt/hdd, you'll want to copy your
206 freshly built kernel to the root of the image.  I have a make target in my
207 makelocal for this, so that whenever I do a make kvm, it builds the kernel and
208 copies it to my hdd.img.
209
210 I added edited versions of my KVM (and USB) make targets to the
211 Makelocal.template.  Uncomment the KVM one (at least).
212
213 Incidentally, I also have the following in my Makelocal, so that make (and make
214 all) also make kvm:
215
216 all: kvm
217
218 Now, make kvm.  You should be able to see the new kernel in mnt/hdd/ (do an ls
219 -l and check the timestamp).
220
221 3.6 Running Qemu
222 ---------
223 Here is the command I use to run qemu/kvm.  It's evolved over the years, and it
224 will vary based on your linux distribution.  Don't run it just yet:
225
226 $ 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-:23 -net dump,file=/tmp/vm.pcap -drive file=mnt/hdd.img,index=0,media=disk,format=raw
227
228 If you skipped making a virtual machine image or want to run the kernel
229 directly without emulating a disk, replace the "-drive" parameter (all the way
230 to format=raw) with "-kernel obj/kern/akaros-kernel".
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 The command as written uses QEMU's user networking.  It's emulated and a little
243 slow.  The example I have alo forwards port 5555 on the host to port 23 on the
244 guest.  Customize it according to your needs.
245
246 Another option for networking is to set up a tun/tap device.  I use this on
247 some machines, and the kvm-up script has some commands to set it up.  It's
248 tricky, and may vary for your distribution.  If you do use the tun/tap
249 networking, replace the "-net user" section with:
250
251         -net tap,ifname=tap0,script=no
252
253 The "-net dump" option saves a pcap trace of the network traffic.  This is very
254 useful for debugging, but probably not needed for most people.
255
256 Feel free to pick different values for the number of cpus and RAM (8 and 4096
257 in the example).
258
259 Once you finally run it, you can stop the VM by entering 'q' to the qemu
260 monitor (or just killing the process)..  Other help commands from the monitor
261 include 'info cpus', 'info registers', 'x', and 'help'.
262
263 In more recent versions of qemu, CTRL-C will not get sent to the guest; instead
264 it will kill the VM.  If this gets annoying, you can remap "interrupt" to
265 something other than CTRL-C in the terminal where you run qemu:
266
267 $ stty intr ^]
268
269 To change it back:
270
271 $ stty intr ^c
272
273 3.7 Running on Hardware
274 ---------
275 I have a few bootable USB sticks with grub set up to run Akaros.  The make usb
276 target (example in Makelocal.template) will copy freshly made kernels to your
277 USB device.  You'll need to adjust those paths according to your distro.  My
278 usb sticks are usually /dev/sdc, for instance (some odd USB device in the last
279 couple of years has taken over /dev/sdb.  Probably something to do with udev
280 changing over the years).
281
282 Anyway, you'll need to mess around a bit to get that working.  Or I can dd one
283 for you (I have 4GB disks in my office that I use).  If you make your own, the
284 critical part is getting grub to pick the right device (from what I remember),
285 and its fairly similar to installing grub on any old hard drive (since it's
286 just a bloc device).  Much easier than a hard disk image file.
287
288
289 3.8 Hello World
290 ---------
291 So now you can run the kernel.  It's time to edit a program (or make your own).
292 In this, I'll go through my workflow for making changes.
293
294 $ vi tests/hello.c
295 (edit, save)
296
297 $ make tests
298 (new version in obj/tests/hello)
299
300 $ make fill-kfs
301 (updates kfs)
302
303 $ make
304 (rebuilds kernel with the new KFS)
305
306 $ qemu...
307
308 (following commands are in Akaros)
309 Shift-G (to get to the kernel monitor)
310
311 ROS(Core 0)> bb (to run busybox)
312
313 / $ hello
314 (Should print your message)
315
316
317 3.9 Other Dev Workflow stuff
318 ---------
319 One thing to note is that while we use dynamic linking for libc, parlib
320 libraries are statically linked with applications.  In fact, nowadays *all*
321 Akaros programs need to be linked againt parlib (used to be that single-core
322 processes (SCPs) didn't need it).
323
324 The makefiles won't notice if you change a file in parlib and then remake a
325 binary.  So if you edit user/parlib/uthread.c for example, tests/pthread_test
326 won't get rebuilt.  Here's what I do:
327
328 $ vi user/parlib/uthread.c (make awesome change)
329
330 $ touch tests/pthread_test.c ; make tests
331
332 This will force the rebuild of pthread_test.  Older, untouched binaries (e.g.
333 block_test), won't get rebuilt.  I actually want this in some cases (different
334 versions of parlib when I'm running certain tests).  Anyway, just pay attention
335 to what you're building.  There's not much output in the console, so you should
336 be able to see what's going on all the time.  (unlike when building glibc...).
337
338 Oh, and don't forget to:
339
340 $ make fill-kfs
341
342 to make sure you run the new pthread_test. 
343
344 Additionally, when switching between 32 and 64 bit x86, make objclean before
345 filling KFS.  This is the easiest way to make sure you get the appropriate
346 libraries loaded in KFS.
347
348 Early on as a dev, there are lots of times where you accidentally don't run the
349 right program (or kernel) and won't understand why your change isn't happening.
350 A few printk("WTF\n")'s later, you realize you didn't have the hdd.img mounted,
351 or you didn't fill KFS, or you didn't relink your binaries, or you forgot to
352 save all files in vi (and not just the current buffer).  But after doing a
353 couple hello worlds, you're set. 
354
355 Alternatively, you could have a make target to run qemu, which also touches all
356 binaries (or otherwise enforces a rebuild), auto-fills KFS, remakes the kernel,
357 and mounts/copies/unmounts your hdd.img.  Kevin's sim repo has stuff like this,
358 so check it out if that's what you're into.  (I think it is at
359 http://akaros.cs.berkeley.edu/ros-sim.tar.gz).  Personally, I'm not that into
360 it, since I like to keep track of what is going on under the hood, esp if I
361 want to do something a little differently (like with testing ext2, having
362 different versions of parlib with some binaries, or being picky about my
363 mount/umounts).
364
365
366 4. RISCV
367 ---------------------
368 TODO.
369
370 For now, you need a 64 bit distro to build the RISCV stuff, so I don't do it
371 very often.  I'll eventually sync up with Andrew and we'll get this part sorted
372 out.
373
374
375 5. Other Developer's Stuff
376 ---------------------