Remove PDX and NPDENTRIES
[akaros.git] / GETTING_STARTED
index cdd0cd2..7a3bab5 100644 (file)
@@ -32,7 +32,7 @@ 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=x86 defconfig
 
@@ -40,8 +40,11 @@ Alternatively, you can run menuconfig to customize what settings you want:
 
 $ make ARCH=x86 menuconfig
 
-There are a lot of settings in here, which you should browse through to decide
-what you want to enable/disable.
+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
@@ -74,19 +77,19 @@ 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-i386-ros-gcc/bin
+/home/brho/classes/ros/ros-gcc-glibc/install-x86_64-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).
 
 Just to double check everything installed correctly, you should be able to run
-i686-ros-gcc from your shell.
+x86_64-ros-gcc from your shell.
 
 Now, you have a cross compiler ready, and you can start to build Akaros.
 
@@ -138,71 +141,47 @@ actually fill KFS properly.
 
 3.4 Busybox
 ---------
-If you don't care about busybox or just want to get started immediately, skip
-this section.
-
-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.
-
-$ 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-1.17.3.config BUSYBOXDIR/.config
-
-$ cd BUSYBOXDIR ; make
-
-Then I copy the unstripped binary to KFS.
-
-$ 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.
-
-Busybox can do core commands like ls and rm, as well as run a shell (ash), all
-from within one binary.  It can tell which command it should execute based on
-the name of the binary (or symlink to it).  I have a bunch of symlinks for
-whatever 'busybox' programs I want to run inside kern/kfs/bin.
-
-For instance, from my AKAROS-ROOT:
-$ ls -l kern/kfs/bin/ | grep busybox
-lrwxrwxrwx 1 brho brho      7 Aug 24  2010 ash -> busybox
--rwxr-xr-x 1 brho brho 337917 Dec 19 17:39 busybox
-lrwxrwxrwx 1 brho brho      7 Sep 29  2010 cat -> busybox
-lrwxrwxrwx 1 brho brho      7 Sep  1  2010 cp -> busybox
-lrwxrwxrwx 1 brho brho      7 Oct 18 13:12 kill -> busybox
-lrwxrwxrwx 1 brho brho      7 Sep  5  2010 ln -> busybox
-lrwxrwxrwx 1 brho brho      7 Aug 23  2010 ls -> busybox
-lrwxrwxrwx 1 brho brho      7 Sep  5  2010 mkdir -> busybox
-lrwxrwxrwx 1 brho brho      7 Sep  5  2010 rmdir -> busybox
-lrwxrwxrwx 1 brho brho      7 Apr  9  2012 stty -> busybox
-lrwxrwxrwx 1 brho brho      7 Apr  9  2012 tty -> busybox
-
-Note I don't need to update the symlinks (almost ever...).  I just recopy the
-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 ignored by git.
+Busybox provides our shell and some basic utilities.  You almost certainly want
+to build and install busybox.
+
+Userspace programs like busybox need to be compiled with the cross compiler and
+then have their binaries copied to kern/kfs/bin.  Since most everyone wants
+busybox and we have a few patches of our own, we have support for automatically
+building and installing it to KFS.
+
+For the default build (x86_64):
+
+$ cd tools/apps/busybox
+$ make [x86_64|riscv]
+$ cd -
+
+And you should be set.  Check kfs to make sure everything installed.  You
+should get sane results from:
+
+$ ls -l kern/kfs/bin | grep cat
+lrwxrwxrwx 1 brho brho       7 Jan 23 09:19 cat -> busybox
+
+You can customize your busybox installation, including the install prefix, the
+.config file, and make jobs.  Check out the makefile in tools/apps/busybox for
+details.
 
 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
@@ -244,7 +223,10 @@ Now, make kvm.  You should be able to see the new kernel in mnt/hdd/ (do an ls
 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
@@ -338,6 +320,10 @@ $ 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,