Program 1: Compile! Load! Run!
CS 3210 Design of Operating Systems
Spring 2000 * Hutto
Georgia Tech College of Computing
DUE: 1:35 pm (class time) Tuesday 25 January 2000
For your first "programming" assignment, you will compile, download and run a new kernel on your team's Skiff board. To do this, you will need to setup your development environment. If you will work in the Skiff Lab, that just means copying the source tree to your account. If you are working at home, it will be a bit more involved. There are lots of little problems that you might encounter. Learning how to recognize and overcome such obstacles is part of the assignment! Welcome to the bleeding edge.
After scanning over the steps outlined below, check out Jason's suggestions and advice for this assignment.
Step 1: Exercise the Serial Console
The boards as handed out are pre-configured with a working bootloader, kernel and root filesystem. In addition, we have saved five network parameters in the flash memory. Without these parameters, your board will look for configuration information via the BOOTP protocol. If you happen to see these BOOTP request messages, they will timeout after 5 minutes and the board will boot with default values. You can manually set the network configuration from Linux if necessary. Also, it is relatively easy to run the Dynamic Host Control Protocol Daemon (dhcpd) under Linux. dhcpd speaks BOOTP (an earlier version of the DHCP protocol) and can supply the initial network configuration.
The five required parameters are:
The nfs_server_address parameter is used only when booting using a remote root filesystem but you must supply a non-zero value anyway to avoid the BOOTP timeout. The team Skiff boards have names like skiff112 and are known to the College Domain Name System so you can telnet into your boards form other College machines. The hostnames are written in red ink on a label on the Skiff board. The number is the final "octet" of the ip address. The Skiff subnet is 130.207.98.0 so the ip address for skiff112 is 130.207.98.112. A second name is written on the label on each Skiff board in blue or black ink. skiff112 also has the name skiff30. The number in this first name encodes the final byte of the MAC or ethernet address of the board. All boards have MAC addresses that begin 08:00:2B:00:01 in hex. Since 30 in hex is 0x1E, the MAC address of skiff112 (skiff30) is 08:00:2B:00:01:1E.
To communicate with your board you will need to use the 9-pin DB serial port. You will connect your board via a serial cable (a so called "null-modem cable") to a similar port on one of the following six machines in the Intel Lab:
These machines are the six closest to the Skiff Lab table. Each has a serial cable run to the Skiff Lab. You should use these pre-existing cables in the lab. (It is possible to simply plug your board into any machine if you don't need the ethernet connection but the lab staff would prefer you not to fiddle around with the connections on the back of the machines.)
Once you are cabled-up, you need to run a communications or "terminal emulation" program on the host. You have two options. You can either use Hyperterminal under Windows NT or minicom under Linux. Configure the program to communicate at 38400 baud 8-1-none with no flow control. You should try both options. Be aware that only the six machines listed above have minicom installed under Linux.
Warning: Hyperterminal is a bit flaky under NT. Every time I have tried to start Hyperterminal it hangs and must be killed using the Task Manager. The second time I start it, it seems to work properly :-(. It is possible to save a Hyperterminal configuration file so that you don't need to reconfigure each time you startup.
Once you have your console up and running, power-up your board and watch the boot messages fly by! If things go well, you will eventually see a login: prompt. Login as root. There is no password.
Warning: minicom creates a lockfile in /tmp. Be sure to exit minicom cleanly so that the lockfile is properly removed. If not, the next team to use your workstation may not be able to start minicom! Also, on two occasions I've ended up with another minicom running in the background! This causes random corruption of the console output. I'm not sure exactly what causes this. Beware.
Step 2: Exercise the Bootloader
When you press the reboot button on the back of the Skiff board (near the status and power lights) or powerup the board, the standard boot sequence begins. You can interrupt this sequence by pressing the space bar when you see the following:
10000000
20000000
40000000
80000000
ENDM
***
This should produce a bootloader command prompt. Do this and look around a bit. Notice how the saved boot parameters mentioned above are "evaluated" before the command prompt. Type help to review the commands available. Type show to see the current parameter values. Notice the linuxargs parameter. These are the commandline parameters provided to the kernel when it boots. Linux supports a very large number of commandline boot parameters. Try changing the hostname parameter by typing:
set hostname foobar
If you reboot or repower the system at this point, the value will be lost. For parameter changes to persist you must "flash" the parameters into flash memory. You do this with the command:
params save
Reboot your system and then return to the boot loader. If you are in the Skiff Lab you will need to RUN back to your console to get there in time or have another team member walk over to the table and reboot for you. Notice how your change to the hostname has survived the reboot.
Now change the hostname back to the name printed in red on the board label and be sure to flash your change into memory.
Step 3: Download a Good Kernel Using Hyperterminal (load kernel)
Before you do any damage, go ahead and load a good working kernel into your board to become familiar with the process. We will maintain a working "recovery" kernel on the class Web page in the file
Copy this file to a Windows machine or to your College account and make sure you can access it under Windows NT in the Intel Lab.
Serial downloads to the Skiff board use the XMODEM protocol. Unfortunately, the Skiff boards currently do not talk properly to the XMODEM used by minicom (sx) under Linux. That means, sadly, that we can only do serial downloads using Hyperterminal under Windows. We hope to have a fix for this in the future but for now we need to use Windows. (If someone wants to experiment, you might try looking for another XMODEM implementation for Linux and see if it has the same problem.)
There is a way to load the kernel over the ethernet using the "flash write" (fw) command but that, also, is not currently working properly. Stay tuned.
To download a new kernel, simply type:
load kernel
at the bootloader prompt and (quickly) select Transfer > Send File under Hyperterminal. Be sure to select the XMODEM protocol.
Step 4: Get the Source Tree
Next copy and unpack the source tree wherever you intend on compiling. Recall only one team member will have sufficient disk allocation to compile using your College account. Follow the detailed instructions on the main class webpage.
We need to update one configuration file in the source tree before you compile. Once you have the source tree unpacked, replace the .config file in the root of the source tree (linux-2.2.12-rmk1-crl3) with this updated version
Step 5: Compile! Compile! Compile!
Compiling the kernel is simple (in theory). Simply cd into the source root directory then type, in sequence:
make clean
make depend
make zImage
If everything works properly, you should end up with a compressed, bootable kernel in the file:
linux-2.2.12-rmk1-crl3/arch/arm/boot/skiffzImage
Step 6: Download Your Kernel Using Hyperterminal (load altkernel)
The Skiff board has an ability to store two kernel images in flash. The normal image boots by default and when you issue the bootloader command:
boot flash
You can load and boot the "alternate" kernel using the commands (remember, currently, you can only user Hyperterminal under Windows to do serial downloads using XMODEM):
load altkernel
boot altkernel
You should always keep a good "working" kernel as the primary kernel. If you damage both kernels, but still have a working bootloader, you can download a good standard kernel as described in Step 3.
Step 7: Schedule a Demo Time with Jason
Any time prior to the due date, get in touch with the TA Jason Lunz (j@cc.gatech.edu) to schedule a brief demo to showoff your shiny new Linux kernel! For the demo, you simply need to demonstrate that you have correctly loaded the standard "good" kernel (load kernel) and your newly compiled kernel as altkernel. We will check the compile date printed on boot.
Step 8: EXTRA CREDIT: Add a printk() Statement
If you'd like to do a bit of extra credit related to the class reading, insert one or two printk() statements in appropriate places to demonstrate that you really have compiled and loaded your own kernel.
In general, you may do extra credit work on any programming assignment. Check with Phil or Jason in advanced to get approval for your extra credit idea. Also, get the basic assignment working FIRST and only then start on extra work.
Odds and Ends
The standard late policy allows you to turn in assignments up to one week late for a modest 10% penalty. Beyond that, you need a REALLY good excuse. Having said that, I expect there to be lots of unexpected problems that will require extensions and postponements. Stay tuned to the newsgroup for late-breaking details.
I'm going to have a very open collaboration policy this semester. Feel free to discuss things with anyone but you must ensure that everyone in the team understands everything submitted for grading and that each team member can explain and reproduce any part of the assignment solution (given enough time) if asked! Grading assignments will usually involve a live demo. Expect us to ask some questions
What should you do when things go wrong? Read the assignment, review the relevant reading in the texts and handouts, ask your teammates for help, post to the newsgroup, involve other class members, come to office hours, use resources on the Web, find a local Linux guru who will share some hard-earned wisdom. Remember, your mother loves you...
-- Good luck!