Kernel hacking primer for SPINThis page is intended to get first-time SPIN hackers off the ground. At the end of this page, you will have checked out the SPIN kernel, built it, created a hello world extension, and downloaded it into the kernel. From there, you should go on to building more interesting and useful extensions. Before you can do any of this, you need to overcome some basic logistical problems. Logistics for UWTo build a spin kernel, you will need at a minimum:
All of this will likely take more than a day to acquire, so please make sure that you have these down early on. Let me know if you have a problem at this stage. Logging inTo compile the kernel you will need to select a machine for your platform, choose one from the list below.
Once logged on, you may have to acquire an AFS token to access your files. /usr/afsws/bin/tokens lists your active tokens and /usr/afsws/bin/klog lets you get a new one. Check out the AFS FAQ when you want to know more about AFS, but AFS sufficiently like NFS that it probably doesn't matter now.
Setting up your environmentYou need to tell CVS where the kernel source tree is by setting an environment variable in one of your startup scripts (e.g. .login):Your path needs to contain Make sure that you DO NOT use the cvs in /uns/cvs. If you want to see a typical path on our systems, check out mine in /homes/gws/egs/.rcrc. Checking out SPIN***PLEASE NOTE***CVS checkout does not work properly when done on a PC. If you are going to build on the iX86 platform, do your CVS operations on one of the alpha machines, then build on the PC. We have weekly releases of the kernel. Each week, the release is tested to make sure that it passes all of the obvious tests. These releases are compiled and kept for archival in /afs/cs/project/spin/build. As of today, the most recent release is spin-29. You should go into the build directory and make sure that spin-29 is still current. If not, modify all subsequent commands with the name of the most recent release. cd /afs/cs/project/spin/YOU mkdir s29 cd s29 cvs co -r spin-29 -l spin cvs co -r spin-29 spin/kernel cvs co -r spin-29 spin/user #go grab some coffee... the checkout will take 5 minutes cd /afs/cs/project/spin/YOU ln -s s29/spin ln -s s29/spin/kernel/sal/ALPHA_SPIN/SPIN/spin.boot cd ~ && ln -s /afs/cs/project/spin/YOU/spin spinAt this point if you are planning on building for the iX86, you want to switch to that platform if you haven't already done so. The build command on the PC is "make" rather than "gmake". cd spin gmake #go and grab some more coffee You are wired from the coffee at this point, and the kernel is hopefully built. Since a tested release should build out of the box without problems, you should not encounter any. It is best to ask someone if you do, since that indicates that something serious is broken. Booting the kernelYou have a copy of the SPIN kernel and all of the extensions. Now you need to find a crash machine, connect to it, and boot it with the kernel you have just built. The more detailed alpha, or iX86 boot page, and loading extensions page are here in case you need it.All of the crash machines are accessible over the net. They have been configured to use a serial line instead of a console (keyboard and/or monitor). At the other end of the serial line, there is a host that acts as a remote console (rconsole). What you'll end up doing is sending network packets to that host, which will relay them to the crash box for you. To do this, just type rconsole machinename, where machine name is the name of some crash box. Here's the list of crash boxes. All except www-spin are fair game. If someone else is using a crash box, rconsole will let you know. You need to type in an rconsole password. I, or anyone else in SPIN, can tell this to you when you get to this stage. When you connect to a machine, hopefully it will be in some decent state. If it is at the PROM prompt, ">>>", you are set. Otherwise, type halt. If it doesn't respond to that, try connecting with the debugger and halting via gdb. If that doesn't work, someone has to press a button on the machine. The rconsole page shows where the machines are. To boot your kernel, type b -filename "/spin/YOU/spin.boot" ez0 or b -filename "/spin/YOU/spin.boot" ewa0 The TurboChannel alphas refer to their network interface as ez0, and the PCI alphas call it ewa0. To determine whether you are on a PCI box or a TurboChannel alpha, press return at the PROM prompt (i.e. ">>>"). PCIs will print another prompt on the next line, whereas TurboChannel alphas will print an empty line before the next prompt. Once booted, your kernel should come up to the kernel shell prompt. You can type help and go on from there. Building and downloading an extensionThis stage involves making some changes to a hello world extension and downloading it. The hello world extension, like all other SPIN extensions, is written in Modula-3. The Harbison Modula-3 book is a good primer for the language, and to become familiar with it, it helps to go through the motions of learning a new language. There is a useful online tutorial for Modula-3 provided by Columbia University that you should definitely check out.The hello world extension can be found in user/hello. Compile it with gmake. Once you have changed it to your liking, you can download it by typing script ~/spin/user/hello/ALPHA_SPIN/hello.rc at the shell. Once it is pulled into the kernel over the network, it should get initialized and do whatever you asked it to do. The EndCongrats. You have built and compiled the kernel, as well as an extension. The gruntwork is over - there are no more obstacles to building interesting, high-performance and complex subsystems within the kernel. Good luck.Where to go from hereThere are other extensions that are more interesting than the hello world one. Check out httpd (web server), fs/wfs (http based file system), sync/rwlock (synchronization), net/udp (UDP networking protocol), threat (thread operations), vm/mach (virtual memory), shell/version (shell commands). |
Emin Gün Sirer
egs@cs.washington.edu