Slightly refactors kthread sleeping
[akaros.git] / GETTING_STARTED
index 588c1bb..9704d46 100644 (file)
@@ -32,9 +32,31 @@ I'll describe how to get x86 working.  RISCV is similar.
 
 The first step is to configure the kernel.  config, menuconfig, and some of the
 other KBuild targets work.  Defconfig gives you a default configuration.  For
-example, to config for 32 bit x86:
+example, to config for 64-bit x86:
 
-$ make ARCH=i686 defconfig
+$ make ARCH=x86 defconfig
+
+Alternatively, you can run menuconfig to customize what settings you want:
+
+$ make ARCH=x86 menuconfig
+
+For x86, you can choose between 32 and 64 bit when you make menuconfig.  This
+selection must match your cross compiler make command.  The default is 64 bit.
+
+There are a lot of other settings when you make config, and you should browse
+through to decide what you want to enable/disable.
+
+Most everyone wants KFS turned on (Filesystems --> KFS filesystem).  This is
+the in-memory filesystem that the kernel uses.  The kernel build scripts will
+look at the "KFS/Initramfs paths" string and take any of those directories and
+add them to a CPIO archive that will eventually become the root filesystem when
+Akaros runs. These settings are set by default when you do a 'make defconfig'.
+
+There are also settings for ext2.  If you turn on ext2 support, you need to
+point to an img file that has been formatted with ext2 and has files in it.  If
+you aren't messing with filesystems at all, feel free to ignore this.  It's an
+in-memory filesystem, like KFS (linked to the end of the kernel), so you won't
+gain much by using it for now.
 
 3.1 Cross compiler (and glibc)
 ----------
@@ -51,25 +73,30 @@ $ cp Makelocal.template Makelocal
 You need to set your INSTDIRS to some place where you want the cross compiler
 installed.  I have a directory named ros-gcc-glibc for this.
 
+You also need to add bin directories to your PATH where the cross compiler will
+be installed.  This will vary based on your value for INSTDIRS.  For instance,
+my path contains:
+
+/home/brho/classes/ros/ros-gcc-glibc/install-x86_64-ros-gcc/bin
+
+       and
+
+/home/brho/classes/ros/ros-gcc-glibc/install-i686-ros-gcc/bin
+
 You can also set up MAKE_JOBS, so you don't over or under load your system when
 building.  I have a 2 core laptop, so I use MAKE_JOBS := 3
 
-At this point, you can build:
+At this point, you can build (for example):
 
-$ make x86
+$ make x86_64
 
 This might take a while (10-20 minutes for me on a 2007 era laptop).
 
-Finally, add the cross compiler's bin directories to your PATH.  This will vary
-based on where you installed things.  For instance, my path contains:
-
-/home/brho/classes/ros/ros-gcc-glibc/install-i386-ros-gcc/bin
-
-Just to double check, you should be able to run i686-ros-gcc from your shell.
+Just to double check everything installed correctly, you should be able to run
+x86_64-ros-gcc from your shell.
 
 Now, you have a cross compiler ready, and you can start to build Akaros.
 
-
 3.2 Kernel
 ----------
 cd back into the repo root.
@@ -78,30 +105,22 @@ Like the cross compiler, the kernel has its own Makelocal.
 
 $ cp Makelocal.template Makelocal
 
-There are a lot of settings in here, which you need to uncomment to turn on.
-
-Most everyone wants KFS turned on (CONFIG_KFS).  This is the in-memory
-filesystem that the kernel uses.  The kernel build scripts will look at
-INITRAMFS_PATHS and take any of those directories and add them to a CPIO
-archive that will eventually become the root filesystem when Akaros runs.  I
-set CONFIG_KFS and suggested a INITRAMFS_PATH in the Makelocal.template.
-
-There are also settings for ext2.  If you turn on ext2 support, you need to
-point to an img file that has been formatted with ext2 and has files in it.  If
-you aren't messing with filesystems at all, feel free to ignore this.  It's an
-in-memory filesystem, like KFS (linked to the end of the kernel), so you won't
-gain much by using it for now.
+This file is used to set up custom make targets that are not part of the
+default Makefile, but fit nicely into your personal workflow. This file is not
+under version control and can me made to contain just about anything.
 
 Now you're ready to build the kernel:
 
-$ make x86
-
-On future makes, you can just 'make'.  The initial make x86 is to pick a target
-architecture.
+$ make
 
 So the kernel built, but you can't do much with it, and you probably have no
 programs.
 
+Notice that we didn't have to set the ARCH variable this time.  The make system
+knows what architecture we are set up for and will always build for that
+architecture until a new ARCh is selected (i.e. via 'make ARCH=xxx defconfig'
+etc.)
+
 3.3 Userspace
 ---------
 To build userspace and test programs:
@@ -109,12 +128,13 @@ To build userspace and test programs:
 $ make tests
 
 You now have programs and libraries, and need to put them in KFS.  To do this,
-I have a script called 'fill_kfs.sh'.  I usually have it in the directory above
-my repo root.  I put a copy of it in scripts/fill_kfs.sh in the repo.  You will
-need to edit it for your own setup.  Or you can do everything manually.  Either
-way, you need to make sure shared libraries are copied into kern/kfs/lib (given
-kern/kfs as your INITRAMFS_PATH) and you want your programs copied to
-kern/kfs/bin.
+we provide a 'fill-kfs' make target. 
+
+$ make fill-kfs
+
+The 'fill-kfs' target copies your cross compiler's shared libraries and all
+test binaries into the first "KFS/Initramfs path" you set during configuration
+(or kern/kfs/lib if you just kept the default).
 
 Now that you've changed the contents of KFS's source, remake the kernel.  You
 should see something like
@@ -132,18 +152,31 @@ Other userspace programs, like busybox need to be compiled with the cross
 compiler and then have their binaries copied to kern/kfs/bin (I do this
 manually).
 
-I'm running busybox 1.17.3, and the config file I use is in tools/patches.
-Copy that to your busybox directory (once you download and untar it, etc) and
-name it ".config".  You can get busybox from http://www.busybox.net/downloads/.
-Eventually I'll upgrade, though it hasn't been a big deal yet.
+I'm running busybox 1.17.3, and the config file I use is in
+tools/patches/busybox.  Copy that to your busybox directory (once you download
+and untar it, etc) and name it ".config".  This config file assumes you want
+x86_64-ros-gcc.  If you are builidng for 32 bit x86 or riscv, you will need to
+edit the config file.
+
+You can get busybox from http://www.busybox.net/downloads/.  Eventually I'll
+upgrade, though it hasn't been a big deal yet.
 
-$ cp tools/patches/busybox-1.17.3.config BUSYBOXDIR/.config
+$ cd BUSYBOXDIR/..
+$ wget http://www.busybox.net/downloads/busybox-1.17.3.tar.bz2
+$ tar -jxvf busybox-1.17.3.tar.bz2
+$ cd AKAROS-ROOT
+$ cp tools/patches/busybox/busybox-1.17.3.config BUSYBOXDIR/.config
 
-$ cd BUSYBOXDIR ; make
+$ cd BUSYBOXDIR
+
+You'll also want to apply any patches for busybox.  From the busybox directory:
+
+$ patch -p1 < AKAROS-ROOT/tools/patches/busybox/EACH_PATCH_FILE.patch
+$ make
 
 Then I copy the unstripped binary to KFS.
 
-$ cp busybox_unstripped AKAROS-REPO/kern/kfs/bin/busybox
+$ cp busybox_unstripped AKAROS-ROOT/kern/kfs/bin/busybox
 
 Note I change the name to busybox (dropping the unstripped).  I want the
 unstripped binary for debugging reasons.
@@ -173,19 +206,25 @@ busybox binary whenever I update it.
 I think some of the other devs build busybox so that it spits out the links
 into an install directory.  Feel free to do whatever.  I'll probably just add a
 bunch of symlinks to the repos default KFS contents one of these days.
-Incidentally, kern/kfs/* is now ignored by git.
+Incidentally, kern/kfs/* is ignored by git.
 
 Now that you've changed KFS, don't forget to remake the kernel.
 
 3.5 Building and Loading a Virtual Machine Image
 ---------
 At this point, you probably have a runnable kernel with programs in KFS.  It
-should be sitting at obj/kernel/kernel.  However, you need a place to run it.
+should be sitting at obj/kernel/akaros-kernel.  When running in a VM, you can
+either run the kernel directly from qemu, or put it in a virtual machine image
+file. 
 
-I run my kernels either in KVM (Qemu) or off a bootable USB stick.
+If you don't want to bother with the image, skip this section.  I tend to run
+my images off an image file, since qemu acts more like hardware (as far as
+multiboot goes).  The downside is the boot up is slower, especially if you have
+a large kernel (>100MB).  It also takes some effort to set up the VM image.
 
-You'll need an image file that looks like a hard disk to boot qemu off of.  I
-put one similar to mine at: http://akaros.cs.berkeley.edu/files/hdd268mb.img
+If you are still reading, you'll need an image file that looks like a hard disk
+to boot qemu off of.  I put one similar to mine at:
+http://akaros.cs.berkeley.edu/files/hdd268mb.img
 
 It's around 268MB (256MiB, or whatever).  If you want to make your own, check
 out Documentation/howtos/make-bootable-grub-hdd.txt.  That's actually the
@@ -201,9 +240,10 @@ don't call it hdd64mb.img on my dev machine).
 Personally, I always have hdd.img mounted.  Some of the other devs have make
 targets that mount and umount it.  Whenever I reboot my development machine, I
 run a script (as root) that mounts the image file and sets up a few things for
-networking.  I put a script I use for this in scripts/kvm-up.sh.  You'll need
-to edit this to use it, and feel free to comment out the networking stuff.
-That's for using networking in qemu.
+networking.  I put a script I use for this in scripts/kvm-up.sh.  You'll likely
+want to copy it to the directory *above* the akaros root directory and edit it
+accordingly. Feel free to comment out the networking stuff.  That's for using
+networking in qemu.
 
 Now that your image file is mounted at mnt/hdd, you'll want to copy your
 freshly built kernel to the root of the image.  I have a make target in my
@@ -221,13 +261,15 @@ all: kvm
 Now, make kvm.  You should be able to see the new kernel in mnt/hdd/ (do an ls
 -l and check the timestamp).
 
-
 3.6 Running Qemu
 ---------
 Here is the command I use to run qemu/kvm.  It's evolved over the years, and it
 will vary based on your linux distribution.  Don't run it just yet:
 
-$ 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
+$ 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
+
+If you skipped making a virtual machine image, replace "mnt/hdd.img" with
+"-kernel obj/kern/akaros-kernel".
 
 The -monitor is the qemu monitor, which is a CLI for qemu.  Pick a
 tab/terminal/pty in Linux that you will only use for qemu monitoring, and enter
@@ -277,7 +319,7 @@ $ vi tests/hello.c
 $ make tests
 (new version in obj/tests/hello)
 
-$ ../fill-kfs.sh
+$ make fill-kfs
 (updates kfs)
 
 $ make
@@ -317,10 +359,14 @@ be able to see what's going on all the time.  (unlike when building glibc...).
 
 Oh, and don't forget to:
 
-$ ../fill-kfs.sh (or whatever you do)
+$ make fill-kfs
 
 to make sure you run the new pthread_test. 
 
+Additionally, when switching between 32 and 64 bit x86, make objclean before
+filling KFS.  This is the easiest way to make sure you get the appropriate
+libraries loaded in KFS.
+
 Early on as a dev, there are lots of times where you accidentally don't run the
 right program (or kernel) and won't understand why your change isn't happening.
 A few printk("WTF\n")'s later, you realize you didn't have the hdd.img mounted,