An Introduction to the Linux-based Assignments

Note: Please use the class discussion board (you can find it on your blackboard) as a communication and Q&A tool.  Should you still need to send an e-mail inquiry, address it to the TAs and cc the instructor. 

In the QEMU/Linux assignments, you are required to use QDGL to modify and test a Linux kernel. You will be using your personal cs/csug accounts for development.

First you need to copy QDGL to your directory. You will need ~562MB just to grab QDGL, and another ~400M as soon as you untar and compile the kernel, so make sure you have at least 1GB of free disk space in your account (the instructor and system administrators have made sure you have the appropriate allocation). We will be using a stock kernel from the kernel repository, version 2.6.26.5 (pre-configured).

Below is the list of the contents of QDGL:

• linux-3.18.77 : The Linux kernel. You will have to untar it and compile it with any modifications suggested per assignment.
  
• hda.img : Debian's virtual disk image. Your disk is  seen by the linux kernel as device /dev/hda - more about this below. Do not touch this file.
• qemu : This directory holds the binaries of your emulator, QEMU, plus other files QEMU needs to work properly (virtual PC bios, video device, etc.). Do not touch anything in this directory.

• Undergrads* : Copy QDGL to your home directory using the following instruction: cp -r ~cs256/QDGL ~
• Grads** : Copy QDGL to your home directory using the following instruction: cp -r ~cs456/QDGL ~
  

• ./qemu/bin/qemu : execute the emulator binary
  
• -m 64M : tell the emulator that the emulated system will have a physical memory of 64 MB. Feel free to increase this number if your host can accept a larger value
• -L ./qemu/share/qemu : tell the emulator where to find the virtual pc bios and other necessary files for the system emulation
• -hda hda.img : tell the emulator which file will act as the virtual hard disk image - this file should appear as device /dev/hda in the guest GNU/Linux OS
• -nographic : tell the emulator to use the ncurses library to draw its interface on your terminal
  

• -append "root=/dev/hda1 console=ttyS0,115200n8 console=tty0": passes the parameter in quotes to the kernel. The kernel needs to know where the root directory will be to mount it and boot properly. The kernel also needs to know it is displayed on a serial console along with the console parameters if you choose to use a serial display.
  
• -kernel linux-2.6.26.5/arch/i386/boot/bzImage: tells the emulator where the external (to the image) kernel to boot lies (full or relative path)
  

• SDL : To use the SDL interface, simply neglect the parameter -nographic and try running QEMU as
• ./qemu/bin/qemu -m 64M -L ./qemu/share/qemu/ -hda hda.img for the default case
• ./qemu/bin/qemu -m 64M -L ./qemu/share/qemu/ -hda hda.img -append "root=/dev/hda1" -kernel linux-2.6.26.5/arch/i386/boot/bzImage
  if you want to boot your own kernel
• Networking : QEMU will automatically try to bridge its virtual network device to the host's network device. Should that not work, explicitely adding -net nic,vlan=1 -net user,vlan=1 to QEMU should get it right (we define how this bridging should work). That should safely bring your guest OS to the outside world and give you access to the internet.
• Your Debian installation comes with an ssh server/client. If your host has an ssh-server also running on port 22, then there would be a port-clash. You could avoid this problem by passing the parameters -redir tcp:2222::22 to QEMU. Then, connecting on port 2222 on the host OS (localhost) would get you to the ssh server port of the guest OS (port 22, Debian in our case).
• Generalize the usage of the above instruction to accommodate other port clashes that might appear, for example if you share your host OS with someone else, pick a random 4-5 digit port as the bridge port to your regular server port.
  
• Kernel config : The procedure to build a kernel is actually first making the configuration ( for example make menuconfig ) and then building it (make). To save disk space, the provided kernel has been stripped of unnecessary modules and is being compiled as a static binary (the Linux kernel, though monolithic, is also for the most part modular, with external loadable modules, but we are compiling it as a big binary). You can change the configuration to fit your needs if you have to. One interesting option that will increase the disk space you will need is the kernel hacking options. By turning them on you should get useful runtime debugging information. Make sure you have enough disk space for this purpose (we estimated an extra 500M in our attempts).
• Debugging: QEMU can be attached to GDB, the GNU debugger, to allow you to step through your kernel. Simple printk (the analogue of printf inside the kernel) should also work. However, it's always nice to have extra functionality that can speed up your compile-test cycle. If you want to try using the debugger, here is one of the ways you can do it:
  
• Compile the kernel enabling the "kernel hacking" options, more specifically, enabling the debugging information. To do so, go to the kernel directory, run make menuconfig navigate to the "kernel hacking" option and enable at least the "Compile the kernel with debug info" option, plus all the options that you will find useful according to your target. Recompile as discussed, and then start your kernel adding the following two parameters, "-s [port] -S" (port will default to 1234 if not provided - it is optional), resulting in something like the example below:
  
./qemu/bin/qemu -s -S -m 64M -L ./qemu/share/qemu/ -hda hda.img -append "root=/dev/hda1" -kernel linux-2.6.26.5/arch/i386/boot/bzImage

  Those parameters tell QEMU to open a port (1234 by default) for gdb to connect to, and then freeze CPU until it gets the signal to continue.
• Start gdb giving it as the executable to be debugged vmlinux which is the linux kernel binary (bzImage is the bz-compressed kernel image). vmlinux is in the topmost linux kernel source directory, linux-2.6.26.5 as assumed here, so you can start as
  
  gdb linux-2.6.26.5/vmlinux

  
• Connect gdb to qemu by the following instruction

target remote localhost:1234
  
  (or port instead of 1234 if you specified it - and you should uniquely if you share your host OS).
  
• Start debugging by setting your breakpoints etc.
• Code browsing : The Linux kernel is huge, so you might want to always use a code browser. You will find one at LXR. Another option is using Eclipse with the C/C++ plugins (CDT) for code browsing and editing.
• Debian : Find out how to use apt utilities if you want to add extra software to your disk image. For starters, open-ssh is installed, so you can transfer files to and from your disk image.
• Host OS : QEMU runs on Windows, GNU/Linux, and Mac OS X. We don't care if you use your desktop and what kind of software you have, but you should be able to compile your kernel there. There is no other limitiation: you can take QDGL home and work with it. There are many reasons why you would prefer a GNU/Linux host, however. For example, the virtual disk image is just a virtual disk you can mount using a loopback device and add/delete files from; all you need to know is which sector the first partition starts at and find the exact offset to mount (offset=32256 in our case).
  

• QEMU : You can visit their website. Read the manuals, read the options, explore them - you will make your development cycle a lot faster.
  
• Debian  : Again, you can visit their website. Use the man pages. Search the internet.
• Eclipse  : Extra Information about Linux kernel debugging using Eclipse and QEMU can be found here (but please don't spend more time on setting up your environment rather than coding for your assignments).
  
• QDGL  : As you can see from links like that, we are not the only ones who are using this setup to teach/hack/develop OS. Dr. Tia Newhall 's QEMU guide is meant for her OS class. Try searching the internet for "QEMU and Linux kernel development" - you will see it is a very successful combination .