Home Schedule Reading Projects People
Mac Logo Windows Logo Minix Logo Sun Solaris Logo Linux Logo

Project 3: GIMIX - MINIX Setup

Assignment Day September 26, 2016 (Monday)
Due Date Check PT1 October 06, 2016 (Thursday) Setup and Patch (part 1 and part 2)
Due Date Check PT2 October 10, 2016 (Monday). Demo System Call (part 2 and part 3) on Tue Oct 11, 2016

Collaboration Policy - Read Carefully

You must work on this project individually, but you may discuss this assignment with other students in the class and ask and provide help in useful ways, preferable over our email list (piazza) so we can all benefit from your great ideas. You may consult (but not copy) any outside resources you including books, papers, web sites and people (but no penguins or sea urchins).

If you use resources other than the class materials, indicate what you used along with your answer.

You have probably guessed it by now - every project will have a similar paragraph to the one above but with slight variations, or not.

Objective:

The main objectives for this assignment are:

A variation of this tutorial/project is drawn from Darrel Long's class and is used by permission.

Lessons from other students taking this course in the past:

1) Participate on the google Minix group, this is a fantastic resource (see here). Follow the group protocol if you post questions (e.g., search and see if your question has already been answered).
2) Use google - you won't get penalized - it is a win-win tool
3) Use the class list, but to get a reply - be courteuous and outline what resources you have tried before posting, e.g., I tried searching on google for "add a sysstem call to MINIX", and I posted on the google Minix group, but I did not get a reply
4) backup frequently - your kernel will crash - and it will crash often, and
5) have fun! you can if you want to, you are all in the same boat (:

Tutorial / References

MINIX resources programming/tutorials:

There are several MINIX resources that I found useful.

http://en.wikipedia.org/wiki/MINIX_3 (see great links at bottom).

MINIX Wiki Installation Guide (outlines the process nicely, be sure to follow the links).

MINIX Wike Installation Guide detailed (newer and above, but the first listed is still useful).

Minix Setup (insights on running MINIX on WMware you can get 30 days for free, you can use other free Virtual Machines, people from this class have used Virtual Box successfully).

http://www.minix3.org/manpages/index.html (Minix man pages)

How to implement a system call:

http://www.phien.org/ucdavis/ta/ecs150-f03/syscall.html
Syracuse University - How_to_add_system_call.pdf
http://fixunix.com/minix/255067-add-system-call.html

VMWare resources programming/tutorials:

http://www.vmware.com/products/player/ (free VMware player)
http://www.vmware.com/products/fusion/ (WMWare for mac and it links to 30-day trial - $79.99 after 30 days.
If you find other resources please post links on the mailing list for the class.

Background:


The Minix operating system comes with a complete set of tools, including C compiler and linker as well as debugger (this is not true of latest version of Minix - which you will not be using). If you want the less wordy description skip to the bottom of this page and just do each bullet point.

Install VMware:

Before you install Minix you need to install a platform where Minix runs. Minix runs (and have been tested) on both actual hardware and machine emulators (or virtual machines as we called them in class). Maintaining a uniform machine for a large class is close to impossible we will use an emulator for the class.

Hardware emulators that I have tried (that also runs on a mac) include Bochs, QEMU (Q for mac), Virtual Box, VMware, Virtual Box and Parallels. We recommend, VMware for this project for the following reasons - we had the least problem with VMware, it has a nice interface, it performs well, and it has a large user base, including MINIX developers (and MINIX users). It is free if it runs on top of Window, it costs $79.99 on top of OS X (mac OS).

For the obsessed shopper of emulators - here is a nice comparison chart from Wikipedia.

Install Minix:

After you installed your 'platform', you need to download and Install Minix. Minix is distributed as a [compressed] CD image file (.iso file) - which are easily installed on VMware. An 'image file' is simple an archive of an optical disk, a single file containg lots of smaller files.

It is '.iso' because the archive file format is a standard defined by the International Organization of Standards. ISO actually have a double meaning: the acronym (ISO) and isos which in Greek means equal - It was a deliberate double meanin and itsignifies the aim of the organization which is to equalize and standardize across different cultures.

You may have heard of other ISO standards from the organization, for example the ISO standard for speed of photographic film (ISO 5800), but in addition to file ISO and CD image file ISO, there are 17,500 other standards including the grading standard of Saffron (the world's most expensive spice) and the size of paper (A4 - european paper size). The CD image file is ISO 9660.

Back to business (if you use windows - a button may be in a slightly different location (bottom vs. top)) in getting started with Minix. Note there is lots of available documentation online (in addition to the one in the red box on how to install Minix. For installs on physical machines, take a look at the Minix install docs here. For installation on Qemu, there is a nice set of instructions here. Note : You can chose your platform (virtual machine) because your implementation of projects will graded according to how you perform you demo in class, and by inspecting your code. So, be sure it works on your laptop that you will bring to class when demo your project (and future projects). Having it work on your workstation at home (only) will give you a 0.

Installing Minix is fairly straightforward, and involves several key steps:

1. Download Minix (minix_R3.2.1-972156d.iso.bz2), and decompress it.
2. Configure your Virtual Machine to boot from the downloaded CD (ISO).
3. Run the setup script (pgin)
4. Reboot from the installed Minix on disk (and not the ISO image).

Use sftp to easily transfer files to/from Minix and your host OS:

Using Putty (see here - similar project look for sub heading).

 

MINIX Familiarization

Once the network is active, you might want to install a few other applications to make your life easier (unless, of-course, you used the install all option above). For example, you might want an editor (such as vim), openssh (to exchange files between Minix and the outside world using scp), a new shell (such as bash), or a version control system (such as svn). Also, check out the source code of Minix that is located in /usr/src and get a feeling for which parts of the OS are located under which directories.

Once you have played around a little bit and have become more familiar with Minix, answer the following questions (you may use the Minix Wiki to answer these)

  1. Provide a brief description of your installation, including whether you installed MINIX on a simulator (and if so, which one) or on what hardware, and if on actual hardware, whether you have a dedicated machine or a machine that multi-boots Minix and other operating systems. Also (whether on real hardware or on a simulator), the size of your disk and the amount of memory available to the OS.
  2. What is the name of the application (utility) that you used to install new software in Minix?
  3. What is the command that you need to issue to rebuild the kernel and install it?
  4. What is the kernel source file that holds the Minix banner string (i.e., "MINIX 3.2.1 ...") that is shown when Minix boots up?
  5. What is the name of the Minix system call with the number 33 (decimal), and how did you determine this information?
  6. Why does a new installation of Minix come with an existing user called "ast"?


    The answers to these questions have to be written in a plain ASCII file called discussion.txt, which you will need to submit as part of this project (see below for instructions).

     

Part 2: Simple Kernel Hack & Create a Patch

At this point, it is time to rebuild the kernel.

 

Check the page for hints on rebuilding the kernel:

http://wiki.minix3.org/doku.php?id=developersguide:rebuildingsystem

 

Go to (this may be different from later kernels this is for (3.1.x) so double check the above page, essentially;

/usr/src/tools and invoke make.

 

Check the options to see how a kernel can be rebuilt and installed. Make sure you select the third option "Start custom kernel" in the start screen so you run your new and freshly built and improved kernel.

When you are able to build a new kernel, it is finally time to make a small OS modification (and enter the realm of kernel hacking). First, however, you have to make a clean copy of the kernel source tree.

This is necessary for two reasons. First, when you later make changes that do not work and you want to have a reference that you can look at, the source is already there. Second, and more importantly, you need such a clean reference to create patches (see below).

So, just issue a cp -r /usr/src /usr/src.clean, and you are good to continue. Of course, you can additionally store (backup) your modified and clean source trees on a remote machine (using rsync or scp, for example) or using version control system.  At this point, you should not be modifying any code directly on Minix. Run the following on your developement machine:

rsync -rptOv minix:/usr/src/ minix_src_clean
Note that rsync may fail occasionally. If that happens, just continue to re-run rsync until you receive no errors.

 

For the kernel modification itself, you need to print out the name of every file that is being executed by the OS.

You should locate the kernel source file that implements the exec system call. Then, at the right point, you should insert a printf statement that outputs the string "executing ... " followed by the name of the file that is being executed. That is, when you type "ls" in the shell, you should see the string "executing ... " being printed to the console. More precisly, if a process executes /bin/ls, your code should print to the console "executing /bin/ls".

This should actually require only a single line to be added, but it provides you with some (very basic) debugging facilities. Once you have done your modification, rebuilt the kernel, install it, and reboot the system. When you were successful, you should now see a series of output statements that show you which programs the operating systems launches.

Your last task of part 2 is to submit your changes to us. When dealing with large software systems (e.g., operating systems such as Linux), it does not make sense to send around the complete source code tree for every small change. For this, people invented patches. A patch captures the changes between two different files (oldfile and newfile). Given the oldfile and the patch, one can use the patch program to create the newfile. This is exactly what we want. So, when you have finished your kernel modification (including recompiling, installing, and testing everything), you switch to the /usr directory and produce a patch for each file that you have changed. For this, you invoke

diff -ruNp (path/to/oldfile) (path/to/newfile) and store the output in a file named mypatch (so redirect standard output to a file).

For example, when making a patch of the file /usr/src/servers/inet/clock.c, you would first change into the /usr directory (containting both src.clean and src) and then do

diff -ruNp src.clean/servers/inet/clock.c src/servers/inet/clock.c. > mypatch

You can test whether your patch has worked by creating another copy of the source tree (e.g., /usr/test), change to /usr/test and run patch -p1 < mypatch. This should modify the clock.c file in the /usr/test tree accordingly. Also, note that this is how we test your patches, and we expect that they can be applied cleanly (without any warnings or errors).

Part 3: A Simple System Call

You are to write a system call, numberprocs(), that returns the number of processes currently running in the system. Use the below tutorial for this.

https://github.com/rhiguita/lab-minix/blob/master/eng_us/Seen2-Creating_a_System_Call-English.txt (your kernel)

http://www.phien.org/ucdavis/ta/ecs150-f03/syscall.html (older MINIX kernel but may contain useful instructions).

Submitting:

Submitting:

  1. Create a file named discussion.txt with the answers to the questions listed above.
  2. Create a file named mypatch that contains the patch to the Minix kernel to print the requested debug information (as described above). Please note that this patch must cleanly apply to a fresh source tree.
  3. Your files must be in a directory named project3.
  4. Put all the materials needed discussed above in the above directory (including your README.txt file)
  5. Submit via the 'submit' command (while on nike.cs.uga.edu)

    {nike:maria} submit project3 csx730

Optional:

Install your shell that you created in project 1 in the proper place and test it out and debug if needed for 5 pt extra credit.