COSC 125 Operating Systems

Spring 2006

Homework Assignment #3

The Framebuffer Device Driver
Due: Wednesday, February 22, 1:00PM CST
Submit: E-mail tar-ball (see below) of operating system code to professor, with a subject header "COSC 125 HW#3, Team ???".
Work may be completed in pairs. Each team should submit only once. Be certain to put both team member names on work submitted. It would be courteous to carbon-copy your partner when e-mailing the final submission.
Preparation

You will have to familiarize yourself with several common UNIX tools for this assignment. The first of these is tar, a utility originally devised to create tape archives for the purpose of backing files up onto computer tapes.

While tar is still used to create tape backups of filesystems, it has become far more common to use tar to group files and/or directories together into a single entity, typically called a "tar-ball". (So common is the use of tar that it has been verbed in computer science terminology: We speak of "tarring" files, or files that have been "tarred up".) Tar syntax is somewhat arcane, as tar came into existence before modern standards for command-line options.

  • Login to Morbius, and change to your working directory.
  • Execute the the following command:
       tar xvzf ~brylow/cosc125/xinu-hw3.tar.gz
    • This untars the files into your working directory, in a subdirectory called xinu-hw3.

    For more information on tar, please see the UNIX man pages.
    Building

    While the gcc command-line options provide a great deal of flexibility when compiling programs, things quickly become unmanageable when the number of source files exceeds what you can conveniently type in a few seconds.

    The make utility can be thought of as a companion to the compiler infrastructure (preprocessor, compiler, assembler, and linker,) that allows the build rules for large projects to be explicitly encoded in Makefiles. A Makefile typically consists of common definitions, (such as, which compiler to use,) and a set of rules. Each rule has a target, such as the file that is to be built, and can be followed by a list of dependencies and a sequence of steps to perform in order to build that target. In addition, make has quite a few common rules built into it.

    You will not have to write your own Makefiles for this course, but you will have to use and possibly modify some for all of our remaining assignments. The Makefile is always human-readable, so feel free to open them up and look around.

    To build the XINU operating system, perform the following steps:

  • Change directory into the top level produced by the tar-ball, called xinu-hw3 for this assignment.
  • Change directory into the subdirectory "compile". This directory contains the XINU project Makefile, and is where all of the compiled ".o" files will go.
  • Execute the the following command:
       make clean
    By standard convention, almost all Makefiles include a target called "clean" that removes everything except the source code. The tar-ball you unpacked should already be clean, but it never hurts to make sure that you are starting from a clean slate. You may find yourself using this command often.
  • Execute the the following command:
       make
    This should produce about a page of output as each source file is compiled, and the resulting object files are linked together to form the operating system, a simple set of library functions, and the boot loader. If all goes as it should, you should find the directory full of .o files from all of the source code in the other subdirectories, and most importantly, a newly compiled operating system image called "xinu.boot".

    For more information on make, please see the UNIX man pages.
    Running

    Your XINU image is now ready to be run on a backend machine. To transfer it there, we have a special utility called xinu-console. Execute xinu-console in the compile directory where your xinu.boot file resides. Xinu-console will connect your terminal to the first available backend machine, and you should see a message like:
       connection 'sutekh', class 'ppc', host 'morbius.mscs.mu.edu'
    depending on which backend you get.

    The most important thing to remember about xinu-console is that it is modal, like vi. You start out in direct connection mode, in which (in theory) your terminal connects directly through special hardware to the serial console on your backend machine. We do not have that hardware hooked up yet, and your operating system is not far enough along to have a working serial console driver anyway, so this will be of surprisingly little use.

  • Get out of direct connect mode and into command mode by holding the control key and the hitting the space bar. From command mode, xinu-console can issue a number of commands to the backend, which you can see by typing '?'. The two options that are of interest to us are 'd' for "download", and 'q' for "quit".
  • Type 'd' to download your XINU kernel image to Morbius, which the backend will run as soon as it next reboots.
  • Enter the name of the file to be downloaded, "xinu.boot".
  • Xinu-console should indicate when the download is complete, and then automatically drops back into direct connect mode.

    • At this point, you are ready to reboot your backend machine with your new image. We don't have specialized rebooting hardware setup yet, so you must go to the front of the appropriate machine and hit the system reset button on the front panel. This is the smaller button marked with a triangle, just below and to the left of the power button. Please do not reboot other people's backends while they are working.

    Under normal traffic loads, the backend should take less than 10 seconds to reset, load your image, and begin executing the operating system.

    For more information on xinu-console and xinu-status, please see the UNIX man pages.
    Framebuffer Driver

    The source tar-ball we are starting with contains only two files for the operating system proper, in the subdirectory system. We will be adding files into this directory in every subsequent assignment.

    The other files in the XINU subdirectories break down as follows:

  • compile/ contains the compilation files for XINU.
  • include/ contains all of our local .h header files used throughout the rest of the source code files. At compile time, these are treated as being in a standard location, so they can be included with "#include<...>" rather than "#include"..."". Header files particularly important to this assignment are include/framebuffer.h and include/console-font.h.
  • lib/ contains a small library of standard C functions we can rely upon in the operating system, like strcmp() and atoi(), etc. Remember -- the UNIX system libraries are not available to our operating system running on the backend!
  • loader/ contains the files for the PowerPC XINU boot loader, the sort of "booster rocket" that is jettisoned once control is transferred to the operating system startup code in the system subdirectory.
  • framebuffer/ contains the driver files for the framebuffer. You will not need to create any new files for this assignment, merely add code into files within this directory.

    Within the framebuffer directory there are three files that comprise the brunt of the driver:

  • framebuffer/fbInit.c must setup all of the operating system variables for running the framebuffer, and sets the buffer into a known state.
  • framebuffer/fbPutChar.c puts a single character on the screen. Built on top of this, other operating system functions like kputc() and kprintf() present a logical view of the framebuffer that is no different from using the UNIX printf() to our client code.
  • framebuffer/fbControl.c implements control functions specific to the framebuffer device, like clearing the screen, moving the cursor around, or selecting colors.

    Each of these files contains skeleton functions that must be filled in. The major locations are marked with "// TODO...". Test your framebuffer driver by adding code to system/initialize.c's nulluser() function, which begins using kprintf() to report on the operating system's successful startup.

    When I test your driver, I will be putting different code into the nulluser() function to see if your driver follows the interface spelled out.

    Back