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

Project 4: Semaphore - SUFiX -

Assignment Day October 20, 2016 (Friday - midnight)
Due Date November 03, 2016.

* NOTE: Grading Criteria will change (e.g., the system call component will be worth less since it has an overlap with the OTHER project(s), the evaluation component will absorb those points).

Collaboration Policy - Read Carefully

You may work on this project with a partner, and you are encourage to discuss the assignment with other students or teams on the email list. You may consult (but not copy) any outside resources you including books, papers, web sites and people (but no penguins or sea urchins).

Note (as before) if you work on a team you are required to include a statement to specify the contributions of each team member. The statement can be up to several sentences long, describing the tasks of each individual [see examples here of contribution statements here - note this is in the context of a research article but it still a real world example (starting at 2nd paragraph) here ].

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, of-course.

If you work on your own - you will get a 5% bonus provided that your base grade is above 60%). As this will require more effort.

Lessons to date: 1) Participate on the google MINIX group, it is a fantastic resource, 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 server to MINIX", I posted on the google MINIX but I did not get a reply 4) MISC - IF you do work on a team - and get stuck - try to use your partner's set-up, backup frequently - your kernel will crash - and it will crash often.

Objective:

The main objectives for this project are:

The latest version of this project is borrowed from Prof. Christopher Kruegel's CS 170 Course at UC, Santa Barbara. I have also noted that there are helpful hints on this project on the MINIX google group - so you might want to check that out as well.

Tutorial / References

How to implement a system call (you have done this already)

http://www.phien.org/ucdavis/ta/ecs150-f03/syscall.html http://www.cis.syr.edu/~wedu/seed/Documentation/Minix3/How_to_add_system_call.pdfhttp://fixunix.com/minix/255067-add-system-call.html

How to implement a semaphore service:

http://www.usenix.org/publications/login/2006-04/openpdfs/herder.pd

If you find other resources please post links on the mailing list for the class.

Background:

And it doesn't hurt to mention this again:

As previously mentioned this project will teach you how to experiment with a real operating system kernel(s)- and as a consequence you will learn to work in such a way that deals with a computer crashes (well not quite since we are working in a virtual machine) and / or end up with an OS that doesn't work.

We suggest that you manage multiple kernels, and always have access to at least one working kernel. Back up your work frequently and work in small incremental steps. Incremental steps is very important. A step could be as small as one line of code, or changing the value of an assignement.

Basics:

The center piece of this project is to add a new synchronization "service" to MINIX. This service provides synchronization using semaphores and isimplemented as a "system service", similar to the process manager (PM) or the file system server. There are three tasks (one is completed in the previous project) in the project and TWO of the taks can be completed independently. The three tasks are:

  1. Implement a system call in MINIX (you have done this already in the previous project but you will do it again here - you could add a twist to the earlier project if you like, be sure to mention that during the demo).
  2. Add a semaphore "service" to MINIX (this uses system calls
    so it builds on the first task).
  3. Write a C program that use the semaphore service above (for partial credit you may complete a pre-curser of this program using semaphores on atlas or nike).

This project is worth 100% - but we will use 150 point to make grading easier.

Details:

Task 1 (Prelude): Provide System Calls (assume this is already completed from the previous scheudling project)

Here are some pointers for task one:
http://www.phien.org/ucdavis/ta/ecs150-f03/syscall.html
http://www.cis.syr.edu/~wedu/seed/Documentation/Minix3/How_to_add_system_call.pdf
http://fixunix.com/minix/255067-add-system-call.html.

You need to make sure that you port it to your version of MINIX, i.e., version 3.1.7 or higher.

Task 2 (the Real Project): Provide a semaphore synchronization service

Task TWO builds on the prelude task as it requires system calls. Here is the real challenge, and it is two fold:

(1) is to add another 'service' to MINIX (like the file or process "services") that is part of the boot image and starts up during booting and

(2) is process management that wakes and put processes to sleep. The semaphore service includes implementing appropriate semaphore messages such as SEMA_UP, SEMA_DOWN, SEMA_INIT and SEMA_RELEASE (more on this in details below).

The service you are providing is to add semaphore support to MINIX. Currently, MINIX lacks a mechanism to synchronize different processes. The goal for this task is to change this limitation and write a semaphore service. This semaphore service should be implemented as a system service, similar to the process manager (PM) or the file system. That is, your semaphore service should be a service that is part of the boot image and automatically start when the system is booted. This semaphore service should understand four different messages: SEMA_INIT, SEMA_RELEASE, SEMA_DOWN, and SEMA_UP.

Task 1 Extension (System Calls)

Of course, user programs are not supposed to build these messages directly. Instead, and similar to task 1, you are supposed to write POSIX library wrapper functions that create the appropriate messages with the right number of parameters.

You'll also have to declare the functions in an appropriate header file (e.g. /usr/src/include/unistd.h) and provide the wrapper functions (take a look at /usr/src/lib/syslib). Note that you need to rebuild the libraries by doing a "make libraries" inside /usr/src/tools.

In the following, the semantics of these four library functions (and the corresponding messages that they create) are described below:

For the first challenge, which is to make a system service that is included into the boot image of Minix, it makes sense to look at the code of a simple system service such as DS (which can be found under /usr/src/servers/ds). You can, for example, copy the files that are in this directory into a new directory (such as /usr/src/servers/ss). Then, update the makefiles appropriately to make sure that your new server is compiled. Finally, look at the code that you just copied. You will see that in main.c, there are routines to initialize and exit the server, routines to get and process messages (the loop in the main function), and code to dispatch different messages to different routines. Many of the functions that do the actual work are in store.c. You will probably want to adapt this code so that you keep the main loop that processes messages, but you invoke different semaphore routines, depending on which message is sent by a user program.

The four messages that can be sent to the semaphore service can be defined in /usr/src/include/minix/com.h. Just check out how other messages such as those to the data store server (DS) are defined. Also, you might want to add your service to the list of system services (check for DS_PROC_NR).

Another step to become a full-fledged system service is to inform the kernel that the boot image has now one additional process. To this end, check out the image[] array in /usr/src/kernel/table.c. Moreover, make sure that the permissions are set so that user processes can send messages to your new semaphore service.

Finally, you have to update the makefile that is responsible for creating the boot image and make sure that your new server is properly included. As you probably know by now, this makefile is located under /usr/src/tools.

At this point, you should check whether you have all the things in place to be able to send messages to your new service. That is, check whether a user program can use your new library wrapper functions (such as sema_init) to send messages to the new semaphore service, which hopefully is started during boot time as part of the boot image.

Once you are sure that you can send messages to your system service, it is time to implement the actual semaphore functionality. Recall that you need to be able to support 10 semaphores, each of which needs its own counter and queue for processes that sleep. For a nice discussion of how a semaphore service can be implemented, see the case study section of this article.

Once you your semaphore service in place, play around with user processes that initialize semaphores, call sema_down on them to sleep, and have them woken up by other processes that call sema_up.

Task 3: Provide a user application program

Now that we have semaphores available, we would like to use them to solve a simple synchronization problem. The problem is as follows:

You have been hired by the CS Division to write code to help synchronize a professor and his/her students during office hours. The professor waits until there are students around to ask questions; if there are students who want to ask questions, they must synchronize with each other and with the professor so that (i) only one person is speaking at any one time, (ii) each student question is answered by the professor, and (iii) no student asks another question before the professor is done answering the previous one. Each student asks a single question.

To solve this problem, you have to write two C programs, one called prof.c, which implements the actions of the professor, the other one called student.c, which implements the actions of the student. Note that there can be only one prof process, but multiple student processes running at the same time. You can assume that the prof process is started first, so you can add all (semaphore) initialization code there. Whenever it is the turn of a student to ask a question, print out "student: ask question\n" to standard output. Once a question is asked, the professor process should respond by printing out "prof: answer question\n". After that, the student is (hopefully) happy and leaves, printing "student: leaving room\n".

The prof and student processes must be synchronized such that the order requirements introduced above are met. That is, once a student prints out "student: ask question\n", the next printout must come from the professor process. That is, no other student process is allowed to "ask a question", and the student process that asked is not allowed to "leave the room" before the professor task has "answered the question". Make sure that the professor process sleeps for a few seconds (using the call sleep(n)) before "answering a question" to add some delay.

As an example, assume that there is one professor process running. Then, three student processes are started simultaneously. The output to the console should be:

student: ask question
prof: answer question
student: leave room
student: ask question
prof: answer question
student: leave room
student: ask question
prof: answer question
student: leave room


Write the code for the prof and the student programs, making sure that the necessary synchronization code is in place to ensure the required order of interaction.

Hints

We assume that you are already familiar with makefiles and debugging techniques from your earlier project in this class or from courses such as CS 1730 or the UNIX tutorials held the first week of class by the department. If not (which is unlikely), this will be a considerably more difficult project because you will have to learn to use these tools as well.

You should do your design first, before writing your code. To do this, experiment by inserting debugging print statements if it'll help. It may be more fun to just start cnikeg without a design, but it'll also result in spending more time than you need to on the project.

IMPORTANT: As with all of the projects this semester, the key to success is starting early. You can always take a break if you finish early, but it's impossible to complete a 20 hour project in the remaining 12 hours before it's due....

Submitting:

Submitting:

  1. You must include a design document for this project (note this is a substantial portion of your grade).
  2. NEW: Please include a description in the README.txt file on what works, what works well, and what has not been implemented (if you run out of time). Also write a paragraph on lessons learned for this project.
  3. INCLUDE a file called partner.txt - indicating the name of you partner or 'none' if you are working independently and its partners contribution (see above for more details on this).
  4. Create a file named that contains the applicable patches to the Minix kernel (as described above). Please note that this patch must cleanly apply to a fresh source tree. The patch will be used as a time stamp and also as a reference 'as a freeze' when demoing the project to the instructor (the patch will strictly used as a reference, and not be used to 'recompile' your project).
  5. Provide the prof.c and student.c C programs.
  6. Your files must be in a directory named project5.
  7. Put all the materials needed discussed above in the above directory (including your README.txt file)
  8. Submit via the 'submit' command (while on nike.cs.uga.edu)

    {nike:maria} submit project4 csx730

 

Design Document:

Your design document should describe the design of your assignment in enough detail that a knowledgeable programmer could duplicate your work. This includes descriptions of the data structures you use, all non-trivial algorithms and formulas, and a description of each function including its purpose, inputs, outputs, and assumptions it makes about the inputs or outputs. A sample design document is available here.

 

Grading Criteria (subjected to some change)

* NOTE: The Grading Criteria will change (e.g., the system call component will be worth less since it has an overlap with the scheduling project), we will also put more emphasis on evaluating whether the service works and it has been thouroughly tested (see the scientific method here). The "think! try again" block is especially important.

 

150
Total
  Component Subcomponent
90 60 Design 20
System Calls
Data Structures modified, added (detailed)
Pseudo Code (include where: file/function name added/extended)
20
Semaphore Service
 
 
20
User Programs
 
 
30 Compile/Run As proof of concept demonstrates that “something” for each component compiles and runs (system call, semaphore service and prof.c/student.c apps). This is not expected to be a full fledge system (but enourages incremental development)
20   Full Fledge:
System Call
10 Data structures – works!
10 Functionality
20   Full Fledge:
Semaphore Service
10  
10  
20   Full Fledge:
User Programs
10  
10  

Grading criteria:

A+ (95-100) Extraordinary, goes beyond minimum criteria both in depth and breath. Design is thourough and well thought out, code base and implementation is beautiful- modularized, complete, clear and concise. A well thought out debugging strategy is appearant. Well documented code. The evaluation plan is welll executed and well thought out, goes beyond the simple cases and illustrates strong problem solving skills.

A (90-94) Superior (somewhat less than an A+, almost perfect code, beautiful, concise, minimum criteria met, not as much depth and forethought as an A+ but it is superb), goes beyound meeting the minimum critera demonstrates depth, can apply solution to a variation of similar problems.

B (80-89) Good, minimum criteria well executed and well done, shows some depth and understanding, meets most testcases but not as much forethought as an A;

C (70-79) Fair, minimum criteria met, but could have been executed with more depth and forethought.