DUE: Friday, September 30th 11:59 PM

By the end of this lab students will be able to:

• Understand how a process's status changes its scheduled behavior when the Xinu scheduler runs
• Extend the process table to allow waiting processes to be suspended.

In XINU, a process has a state set in for its entry in the process table that consists of only one of several values. XINU uses these values during scheduling, signaling, etc. in order for the processes in the system to execute correctly. The list of process states is defined in include/process.h and are as follows:

#define	PR_FREE		0	/* Process table entry is unused	*/
#define	PR_CURR		1	/* Process is currently running		*/
#define	PR_READY	2	/* Process is on ready queue		*/
#define	PR_RECV		3	/* Process waiting for message		*/
#define	PR_SLEEP	4	/* Process is sleeping			*/
#define	PR_SUSP		5	/* Process is suspended			*/
#define	PR_WAIT		6	/* Process is on semaphore queue	*/
#define	PR_RECTIM	7	/* Process is receiving with timeout	*/

NOTE: the PR_FREE state is not an actual process state, but is used to indicate that the corresponding entry in the process table is not used.

Consider, for example, the wait system call in system/wait.c which decrements the counter on a semaphore and if the count is less than zero, it sets the process state to PR_WAIT. Since the process is not ready to run, the XINU scheduler will never allow it to run via a context switch. Now consider what happens when another process calls the suspend system call giving the process ID for this waiting process. If you look in system/suspend.c you'll notice that a process can only be suspended if it has a state of PR_CURR or PR_READY. In this example, the suspend system call will return SYSERR. Similarly a process that is waiting for a message from calling the receive system call can also not be suspended.

However, what if you wanted a waiting process to immediately go into a process state of suspended as soon as it becomes ready (for example, once another process signals the semaphore)? Using the suspend system call as it is implemented today does not allow this behavior.

For this lab, your job in this lab is to create a new system call that will perform this behavior. You will be doing this by implementing the following system call:

/* Suspend a process, even if its current status is waiting or receiving */
syscall mysuspend(pid32 pid);

In /homes/cs503/xinu there is a file called xinu-fall2016-lab3.tar.gz that contains a start to the code. Unpack:

tar zxvf /u/u3/cs503/xinu/xinu-fall2016-lab3.tar.gz

This will create a directory called xinu-fall2016-lab3.

Along with the main code for XINU, this tarball contains the following files (additional explanation of the contents of the files are in the following sections).

• system/mysuspend.c - function declarations for the mysuspend system call.
• include/prototypes.h - prototypes for the new system call.

For this lab, you are required to implement the function declared in system/mysuspend.c. The details of the function are as follows:

The file mysuspend.c file contains the function declaration for the mysuspend function that you must implement:

• syscall mysuspend(pid32 pid) - System call for mysuspend.
  • For a process that has a state of PR_CUR, PR_READY or PR_SUSP, this system call behaves exactly the same as the suspend system call does today.
  • For a process that has a state of PR_WAIT, PR_SLEEP, PR_RECV, or PR_RECTIM, your new system call will set a flag in the process table which will cause XINU to suspend the process as soon as it becomes ready.

NOTE: if a process is currently in a waiting state PR_WAIT, PR_RECV, PR_SLEEP, or PR_RECVTIM, the mysuspend system call does not change the process's state. Instead it should merely set a delayed suspend flag in the process table entry for the process to indicate that the process should be suspend when it becomes ready.

Today when the ps command is run from the XINU shell the processes status is shown, for example:

xsh $ ps
Pid Name             State Prio Ppid Stack Base Stack Ptr  Stack Size
--- ---------------- ----- ---- ---- ---------- ---------- ----------
  0 prnull           ready    0    0 0x0EFDEFFC 0x0EFDEEB0     8192
  1 rdsproc          wait   200    0 0x0EFDCFFC 0x0EFDCA9C    16384
  2 ipout            wait   500    0 0x0EFD8FFC 0x0EFD8F40     8192
  3 netin            wait   500    0 0x0EFD6FFC 0x0EFD6EE0     8192
  4 Main process     recv    20    0 0x0EFD4FFC 0x0EFD4F64    65536
  5 shell            recv    50    4 0x0EFC4FFC 0x0EFC4C7C     8192
  6 ps               curr    20    5 0x0EFC2FFC 0x0EFC2DC8     8192

With the addition of the delayed suspend caused by mysuspend, the output from the ps command needs to be modified to indicate which processes are set to a delayed suspend. For example, let's assume a call was made to mysuspend to suspend process 1 (rdsproc). Currently, process 1 is waiting with the call to mysuspend it should now have a status of waiting with delayed suspend. This status should be indicated by adding an asterisk to the ps command output. So in this case the output would look as follows:

xsh $ ps
Pid Name             State Prio Ppid Stack Base Stack Ptr  Stack Size
--- ---------------- ----- ---- ---- ---------- ---------- ----------
  0 prnull           ready    0    0 0x0EFDEFFC 0x0EFDEEB0     8192
  1 rdsproc         *wait   200    0 0x0EFDCFFC 0x0EFDCA9C    16384
  2 ipout            wait   500    0 0x0EFD8FFC 0x0EFD8F40     8192
  3 netin            wait   500    0 0x0EFD6FFC 0x0EFD6EE0     8192
  4 Main process     recv    20    0 0x0EFD4FFC 0x0EFD4F64    65536
  5 shell            recv    50    4 0x0EFC4FFC 0x0EFC4C7C     8192
  6 ps               curr    20    5 0x0EFC2FFC 0x0EFC2DC8     8192

You will need to add the asterisk output for each process that has the delayed suspend flag set. This change should be made in shell/xsh_ps.c

• When calling mysuspend, the process identifier (pid) must be the identifier for a valid process. If a process identifier is passed to mysuspend that is not valid, SYSERR should be returned. See an example of how to do this by looking at the suspend system call in suspend.c
• The null process must always be ready to run and therefore cannot be suspended. If the caller attempts to suspend the null process with mysuspend, SYSERR should be returned.
• The suspend system call when called with a process ID for a process that is already in a state of PR_SUSP returns SYSERR. The same behavior should be implemented for mysuspend including the case where a process already has its delayed suspend flag set. For example, the first time mysuspend is called with a process ID for a process waiting on a semaphore (state of PR_WAIT), mysuspend should return OK (assuming all other conditions for mysuspend are correct). However, if the delayed suspend flag is already set for the process, then further calls to mysuspend should return SYSERR.
• Do not change the way that the existing suspend system call works. You will be required to change the process table entry for the new system call, but do not change it in away that causes existing system calls to no longer work. A call to suspend should function in the same way it does today.
• Provide a set of test cases to ensure that your code works as required. Put these test cases in main.c
  • Make sure your test cases not only test the new functionality of the new system call, but that existing system calls still function correctly.
• The TAs will be replacing main.c with their own test cases after running your submitted test cases. Make sure you do not define any dependent variables in main.c. You are free to modify any other file(s) to implement the lab requirements.
  • Make sure that there are no dependent declarations in main.c.
• If your submitted code does not compile (either the exact submitted code or the code after the TA's replace any test case files), you will receive zero (0) points for code execution. If this happens, you will be allowed to resubmit for half credit only.
• Please run “make clean” prior to submission so that you don't submit object files
• NOTE: When you make xinu for this lab the make file will generate a binary file in the compile directory called xinu. This is the file you will need to download to your backend.
• Please make sure you remove all debug print statements prior to submitting.

Implement function mysleepms to provides a 3rd-party sleep capability. The idea is to guarantee a minimum sleep time independent of the current activity of a process. For example, if the process is waiting on a semaphore, mysleepms can be used to guarantee a minimum sleep delay after the semaphore wait completes. The functionality of mysleepms is similar to the sleepms system call with differences described below:

syscall	mysleepms(pid32 pid, int32 delay);

The mysleepms system call function puts the process with process identifier pid to sleep for the the given number of milliseconds.

If the process identifier given is the currently executing process, then mysleepms works exactly the same as sleepms.

If the process identifier given is not the currently executing process then, the process with process identifier given is put to sleep for the specified number of milliseconds as soon as it becomes eligible to run. To understand how to handle this it might be helpful to think of all the states that the process with the given process identifier could be in when mysleepms is called.

A couple other situations to consider:

• Process 'A' is not eligible to run and another process calls mysleems, using the process identifier for 'A' and a delay greater than zero, multiple times before 'A' becomes eligible to run.
• Process 'A' is currently sleeping and another process calls mysleepms using the process identifier for 'A' and a delay of 0 milliseconds.
• Process 'A' is not eligible to run, but mysleepms was called causing it to sleep for a time greater than 0 when it becomes ready. Before it gets a chance to sleep, another process calls mysleepms using the process identifier for 'A' and a delay of 0 milliseconds.

The choice of how these situations are handled is up to you. Make sure you document the choices you made when you write down the semantics of your version, and be sure to describe why you made those decisions in your lab analysis report.

Submit using the turnin command (see below) your complete source code (all of XINU) including the any files you added to complete the lab. In the system directory include a PDF file called lab3_analysis.pdf with a report discussing:

• The details behind your implementation (including a discussion of the extra credit if attempted). As part of this discussion write answers to the following questions:
  • Although deferred suspension is straightforward, the semantics of deferred actions can become troublesome. For example, suppose a process is current waiting, but has the deferred suspension flag set, and the process is resumed.
    • Should the resume cancel the deferred suspension, or should the process first be moved to the suspended state and later resumed?
    • What should we do if some action is valid when a process is in the suspended state, should the the action happen when the process has deferred suspension?
    • Should the operating system keep a list of all the actions to be performed once the process is out the deferred situation?
  • Think about how such things could be handled, and assess the tradeoffs.

NOTE: Make sure you put your name on your report, that the file is named exactly as specified, and the file located in the directory specified.

NOTE: Please make sure you remove all debug print statements prior to submitting.

To turn in your lab use the following command

turnin -c cs503 -p lab3 xinu-fall2016-lab3

assuming xinu-fall2016-lab3 is the name of the directory containing your code.

If you wish to, you can verify your submission by typing the following command:

turnin -v -c cs503 -p lab3

Do not forget the -v above, as otherwise your earlier submission will be erased (it is overwritten by a blank submission).

Note that resubmitting overwrites any earlier submission and erases any record of the date/time of any such earlier submission.

We will check that the submission time stamp is before the due date; Any submission past the due date will be deducted the appropriate number of grace days. If submission is beyond your remaining number of grace days, your work will not be accepted.

NOTE: Please make sure you remove all debug print statements prior to submitting.