Personal tools

Milestone 0: Familiarisation

This is a simple exercise designed to get you started on L4. It contains very detailed instructions, together with the existing source code and the L4 manual you should have no problem doing it.

If you have a Slug without a serial connection, you will need to use your partner's Slug for this exercise (every group has at least one Slug with a serial adaptor). After completing this milestone, you will be able to use the new network console facility to perform some debugging, but will still need to use your partner's Slug if you want to use the kernel debugger (which only operates on the serial port).

Initial setup

If your lab machine is running Windows, first reboot it into Linux!

Most of the required binaries (eg. cross compilers, and a specific version of SCons) are installed under /net/fs.systems/export/groups/systems/p1/project/aos. You should modify your path with:

~ % arm5xdev=gcc-3.4.5-glibc-2.3.5/armv5b-softfloat-linux
~ % aos_path=/net/fs.systems/export/groups/systems/p1/project/aos
~ % export PATH=$PATH:%aos_path/bin:$aos_path/$arm5xdev/bin

... You should add the commands above (or something with the same effect) to your shell profile, so that you do not need to run them in every new terminal window.

Finally, for working on the lab machines, you will need to make yourself a copy of a VMware image containing a minimal Linux installation that we use to interact with the slug. You can do this by running the aos_copy_vm script from your terminal:

$ aos_copy_vm
Everything looks ok; copying /net/fs.systems/export/groups/systems/p1/project/aos/vm/aos to
 /nas/user/aos_vm and updating vmx file...
+ cp -r --preserve=mode /net/fs.systems/export/groups/systems/p1/project/aos/vm/aos /nas/user/aos_vm
+ cd /nas/user/aos_vm
+ cp aos.vmx aos.vmx.orig
+ sed 's/TFTPPATH/\/local\/user\/tftpboot/' aos.vmx.orig
+ rm aos.vmx.orig
+ set +x
Making sure you have a tftpboot directory on this machine...
Phew, nothing seems to have broken, so we are done!
To start your new VM, run: vmplayer /nas/user/aos_vm/aos.vmx

You need only do this once (although you can of course do it again if you break your VM image and need to recover a clean one).

Building SOS

  1. Get yourself a copy of the skeleton SOS, using Mercurial:
    $ hg clone http://hg.systems.ethz.ch/aos_project
  2. Build it:
    $ cd aos_project
    $ make
    ... you should see lots of output as it builds, followed by something like:
    scons: done building targets.
mkdir -p /local/user/tftpboot
cp build/bootimg.bin /local/user/tftpboot/bootimg.bin || true
nslu2 -p /dev/ttyUSB0 reset

Getting it Going

  1. Plug in the slug (USB and Ethernet) and power it on.
  2. In a terminal, launch minicom with minicom ttyUSB0.
    NB: Your minicom should default to 115200, 8N1, no hardware flow control. If it doesn't then you will have problems talking to your slug.
  3. Start your VM image with vmplayer ~/aos_vm/aos.vmx
    NB: The first time VMware Player starts, it will tell you that shared folders are disabled. However, you need to enable shared folders for your Slug to boot, so change this setting under preferences.
  4. Attach the USB-Ethernet device to your VM by clicking on the appropriate button at the top of the VMware window. Do not attach the USB-Serial dongle ("Future Devices Unslung") to the VM.
  5. Build, copy the sos image and reset your slug by just typing make (in your local terminal, not in the VM).
  6. You should see a successful boot of the sos skeleton in the minicom window. Now it is up to you to bring an entirely new operating system up, good luck.

Development cycle

We have developed a few tools to speed the development cycle along. The makefile can copy the sos operating system, known as a bootimage to your tftp directory and reset the slug. Below is a typical development cycle, assuming the path changes to your login script:

  1. Plug in the slug, don't forget the ethernet, and power it on.
  2. In a terminal, launch minicom, $ minicom ttyUSB0.
  3. Start VMware, $ vmplayer ~/aos_vm/aos.vmx, and attach the USB-Ethernet device to it.
  4. Once Linux has booted in the VM, click on its console to capture the keyboard and login as user (no password required).
  5. On the VM console, launch netcat (for libserial output), $ nc -lup 26706.
  6. To recover your focus (keyboard/mouse) from VMware, press Ctrl+Alt
  7. Make your changes, (hint: learn cscope).
  8. Build, copy the boot image and reset your slug from the host system with $ make.
  9. Test your changes.
  10. Repeat from step 7 above until satified, or you fall over for lack of sleep.
  11. Ending the minicom session: ^A q, and ^C will end the netcat session, or just shutdown/suspend your VM.

The Milestone

The example skeleton operating system includes an application tty_test which starts up, prints out its thread id, and then goes into a loop.

The example includes a printf implementation that outputs data to L4's debug console. In fact it uses the L4 debug API L4_KDB_PrintChar. This function should only be used for internal SOS debugging, not as a console for applications, so, your task is to modify the sos_write function to send data across the network to your netcat (nc) console.

The second part of milestone zero is to find a partner for the rest of the project. The project is to be completed in pairs.

Recommended procedure

  1. Read (and understand) the code in sos/main.c and the code in the tty_test application.
  2. Read the documentation on libserial.
  3. Design an IPC protocol to transfer data from the user program to your operating system.
  4. Write the client side implementation in sos_write.
  5. Change the syscall_loop in main.c to recognise your new protocol, and print out a debug message when you receive one of these messages.
  6. Edit tty_test.c so that it tests your sos_write function.
  7. Change the server side so that it now prints the data to libserial, which will send it onto the network.
  8. Test that all of tty_test's output now goes to the netcat console, not the console debugger.

Assessment

You will need to demonstrate user applications printing to the 2nd console via libserial, running on the slug hardware to the tutor during the demonstration period. You should be prepared to show your tutor which files you modified in your solution, and explain any design decisions you made. Your tutor will be particularly interested in the details of your IPC interface with different size blocks of data etc.

You will let the tutor know who your partner will be for future milestones.

Document Actions