Read the whole document before you begin, or you may miss points on some requirements (for example, the bug log).
In this machine problem, you will work in teams to develop the core of an operating system. We will provide you with code that boots you into protected mode, sets up the GDT, LDT, and initial TSS, and maps a read-only file system image into physical memory for you. You must set up the interrupt descriptor table (IDT), basic paging support for tasks, separate 4 MB pages for the kernel and applications, initialize a few devices, write the system call interface along with ten system calls, provide support for six tasks from program images in the file system which interface with the kernel via system calls, multiple terminals and basic scheduling.
The goal for the assignment is to provide you with hands-on experience in developing the software used to interface between devices and applications, i.e., operating systems. We have deliberately simplified many of the interfaces to reduce the level of effort necessary to complete the project, but we hope that you will leave the class with the skills necessary to extend the implementation that you develop here along whatever direction you choose by incrementally improving various aspects of your system.
2 Using the Group Repository
You should be receiving an invite to your group repository within the next two days or so. Your repo can be found at:
https://gitlab.engr.illinois.edu/ece391 sp22/mp3 group XX
where XX is your assigned group number. Please check the course website Assignment page to know what is your group number.
To use Git on a lab computer, you’ll have to use Git Bash. You are free to download other Git tools as you wish,but this documentation assumes you are using Git Bash. To launch Git Bash, click the Start button in Windows,type in git bash, then click on the search result that says Git Bash.
Run the following commands to make sure the line endings are set to LF (Unix style):
git config –global core.autocrlf input
git config –global core.eol lf
Switch the path in git-bash into your Z: drive by running the command: cd /z.
If you do NOT have a ssh-key configured, clone your git repo in Z: drive by running the command, it will ask for your
NETID and AD password:
git clone https://gitlab.engr.illinois.edu/ece391 sp22/mp3 group XX.git mp3
If you do have a ssh-key configured, clone your git repo in Z: drive by running the command:
git clone firstname.lastname@example.org:ece391 sp22/mp3 group XX.git mp3
Inside a newly created MP3 directory. You can add/delete files to/from the repository with git add [file list] and git rm [file list] respectively. Remember to git pull each time you sit down to work on the project and git commit and git push when you are done. Doing so will ensure that all members are working on the most current version of the sources. As a final note, it is bad practice to commit broken sources. You should make sure that your sources compile correctly before committing them to the repository. As with previous MPs, please do not modify the Makefile as we will be grading using the vanilla Makefile initially provided.
As you work on MP3 with your teammates, you may find it useful to create additional branches to avoid conflicts while editing source files. Remember to merge your changes back into the master branch by each checkpoint deadline,as this is the only branch we will use for grading.
3 Getting Started: Booting and GRUB
For this project, you will make use of GRUB (GRand Unified Bootloader) to boot your OS image file. GRUB implements the Multiboot specification, the details of which can be found online at
http://www.gnu.org/software/grub/manual/multiboot/multiboot.html. You will need to read
through at least the chunk of this documentation entitled ”Boot information format” to understand the information that GRUB provides to your operating system upon bootup. Various boot parameters are stored in a multiboot info t data structure, whose address is passed in via EBX to the entry point of the OS image. The multiboot.h file contains this and other structure definitions that you should use when accessing the boot information.
GRUB drops you into protected mode, but with paging turned off and all the descriptor tables (GDT, LDT, IDT, TSS)in an undefined state. The first thing to do is set up a GDT, LDT, and TSS. The given code in boot.S does this for you,and then calls entry() in kernel.c, passing the address of the multiboot info t to it. GRUB has loaded the file system image at some place in physical memory, as a module; there is a section in the multiboot info t structure which describes how to access the module information, including physical addresses and size information. You will need to keep the base address of this file system module around, since many operations will need to interact with the file system. You may need to extract other boot information as well, such as the physical memory map provided to you by the BIOS (and also passed in as part of the boot information structure).
To get started, read the INSTALL file given in the MP distribution for instructions on booting the OS image file. Once you have the skeleton OS booting, you are ready to begin designing and implementing features. Necessary references for this project are the x86 ISA manuals, which can be found in the “Tools, References, and Links” section of the class website. Volume 3: System Programming details things like segmentation, virtual memory, interrupts and exceptions,and task support in all of their gory detail. The other volumes provide invaluable resources such as x86 instruction specifications. You will need to reference these manuals early and often; familiarize yourself with their contents before beginning. To debug your MP, you will take advantage of QEMU, which by now, you should be comfortable with.
One final note: GRUB depends on seeing the Multiboot header within the first 8 kB of the OS image file. This header is located in the boot.S file of your sources, and boot.o is passed as the first object file to the linker to ensure that it falls within the first 8 kB of the OS image. Don’t move boot.o to a different position in the link order given in the Makefile, or GRUB may not be able to boot your OS image.
4 The Pieces
The materials provided to you will launch your machine into protected mode, set up the GDT and LDT as well as a TSS. A file system image with a shell, a few utilities, a single directory entry, and a real-time clock (RTC) device file will also be mapped into physical memory for you. We will also provide you with the tools necessary to develop your own test applications, including the compilation infrastructure used to produce the shell and utilities and the file system image itself (the createfs). For simplicity, we will stick to text-mode graphics, but your OS will in the end support operation of a user-level animation package from MP1. Some basic printf support is also provided to aid in debugging, but eventually you will need to write your own output support for the terminal.
Work plan:: Although we are not explicitly requiring that you tell us how you plan to split up the work for this project,we do expect that you will want to do so to allow independent progress by all team members. A suggested split of the work (after getting the devices initialized) is to have each person work on one of the subgoals of Checkpoint 2 with one person concentrating on how these functions will eventually integrate with system calls in Checkpoint 3 and 4 , which connects all previous pieces using the system calls as glue. Checkpoint 5 also requires the group to work together on terminal drivers, RTC interrupts, and everything learned in Checkpoint 3 and 4.
Setting up a clean testing interface will also help with partitioning the work, since group members can finish and test parts of the project without other members having finished the other parts (yet).
For this project, we require you to demonstrate unit tests with adequate coverage of your source code.
As your operating system components are dependent on one another, you may find it useful to unit test each component individually to isolate any design or coding bugs.
We have provided you with a starter test suite in the tests.c file. As you add more components to your operating system, we encourage you to add corresponding tests that verify the functionality of each component at the interface level. Minimum test coverage for each checkpoint is detailed in the following sections.
You may launch tests individually from each of your source files, but all your tests should be defined in tests.c.
This will be especially useful when passing in state variables from your modules to test functions. Remember to use the RUN TESTS macro to exclude test launches when compiling your code for handin.
Keep in mind that passing all of your unit tests does not guarantee bug free code. However, the test suite provides a conven