Description

Before you begin:

• Install VirtualBox and load Reptilian VM (see Ex-0).

Assignment:

1. Create a new system call.
2. Create procedure calls to access system call; install into the system library
3. Create a man page accessible through the man command to document the new library calls, so man get_tag or man set_tag should display a man page for these system library calls (in section 2).
4. Write a short report describing what you did, any challenges you encountered, how you got past them, how you tested your code, any known bugs/limitations
5. Produce a patch file to apply updates and submit this.

I have provided gettag.c and settag.c programs for basic testing; these should compile without any special compiler directives or additional .o files or libraries.

That is, a line like

$ cc gettag.c -o gettag

should produce gettag, which can be run from the shell and allows the root user to get the tag value of an existing process (say, PID 123) using

$ ./gettag 123

0

Likewise, settag should compile as easily and if run by the root user should allow the tag value of an existing process to be changed (the new tag value is returned), e.g.,

$ ./gettag 123

0

$ ./settag 123 5

5

$ ./gettag 123

5

$

If a non-root user tries to do either, the call should fail. You will have to write some additional test code to check all cases required, but this should get you started.

If you have not modified the unistd.h file or the unix standard library, yet, then you can still test the calls by including your own .h file and adding your own .o file to the compile command (but DO fix this before submitting!). So if your .h file is p1.h and library file is p1.o, then

cc gettag.o p1.o -o gettag

after modifying gettag.c to have #include “p1.h” in it should also produce the command program gettag.

Only include text entry with submission if necessary.

Further details in project 1 description.

P1 – System Call Project

 

 

 

Overview

You will implement a system call in your OS along with two library functions in the system library API that allow the system call to be invoked from a C program. We will provide a program that exercises and demonstrates the new call. You will then create a short video to demonstrate your code and submit the project via Canvas.

NOTE: Take Snapshots in VirtualBox! You will most likely brick your machine at some point during this or other projects, and you will not want to start from scratch. No, seriously – take snapshots!

 

Structure

The project is broken into four main parts:

 

• Create system calls that allow a process to “get” or “set” a tag for a process.
• Create system library wrapper functions that allow the system calls to be invoked from a C program.
• Add manual page entries for the system calls and the C library calls. 4) Create a report and a short screencast to explain what you did.

 

While exact implementation may vary the system library functions must match the signatures laid out in this document, and the system calls must get and set tags properly.

 

System Call

Each process in the modified system will have a 32-bit tag. A tag has a structure of two bits of level (the two LSBs) and 29 bits of bitmap (bits 2 through 30). The MSB shall be set to 0 always. Level ranges from zero (low) to three (high). Treated as an unsigned integer, tags can take values between 0 and 2³¹-1. Tags for this system will behave as follows:

 

• Any process that does not have a parent shall have a tag of 0x00000000.
• All child processes shall inherit the tag of their parent process (all 32 bits of it).
• A process running as the superuser may read and write the tag of any process (all 32 bits of it, but it still cannot set the MSB to 1).
• A user process has read-only access to the tag of any process.
• A user process may decrease its own level, but not increase it.
• A user process may reset a bit in its tag’s bitmap to zero but not set a bit.

 

The tag for each process must be stored in the process table. There must also be corresponding kernel system calls named get_tag and set_tag. Other aspects of their signatures may vary. The system calls are invoked from user space via syscall(call_number, param1, param2). Your system call must be limited to no more than two parameters!

 

Static Library

You will create a static library that provides and API to invoke the system calls in a directory named tags. This will be composed of a header with name tags.h and a static library file named libtags.a. You will also need to provide a Makefile for this library in the tags directory. All other sources must be contained within the tags directory. Please note, these names of the files must match exactly!

 

You will create a tarred gzip file of the tags directory with name tags.tar.gz. When testing your code, we will decompress the archive, enter the tags directory, and build. All functions enumerated below must be made available by including “tags.h”. See Submission for details.

 

In addition to the standard library functions, you will implement testing harness functions. The testing harness functions are used to verify the system calls from the system library (and are required for full credit on this assignment). We will call these functions to retrieve the information needed to make a system call. We will then call the system call within our own program. This ensures that the implementation is not being done in the user-level library.

Library Functions

These functions provide primary functionality to user programs. They should be made available by including <tags.h>.

 int set_tag(int pid, int new_tag)

Invokes system call which attempts to change the tag of the process identified by _pid to the new tag value new_tag. Returns new_level on success, and -1 otherwise.

 

int get_tag(int pid)

Invokes system call which reads the tag of the process identified by _pid. Returns the access level on success, and _-1 otherwise.

 

Harness Functions

These functions serve as a testing harness to verify the system calls and are required for full credit on this assignment. They shall be made available by including _<harness.h>.

 

System call parameter retrieval data shall be returned as a pointer to an _int array of 2-4 values that can be used to make the system call. The array has this format:

 

{ call_number, num_parameters [, parameter1] [, parameter2] }

 

e.g.: { 42, 2, 867, 5309 } → syscall(42, 867, 5309)

 

int* retrieve_set_tag_params(int pid, int new_tag)

Returns an _int array of 2-4 values that can be used to make the set-tag system call.

 

int* retrieve_get_tag_params(int pid)

Returns an _int array of 2-4 values that can be used to make the get-tag system call.

 

int interpret_set_tag_result(int ret_value)

After making the system call, we will pass the syscall return value to this function call. It should return set_tag’s interpretation of the system call completing with return value ret_value (i.e., what the library call should return to the user program).

 

int interpret_get_tag_result(int ret_value)

After making the system call, we will pass the syscall return value to this function call. It should return get_tag’s interpretation of the system call completing with return value ret_value (i.e., what the library call should return to the user program).

 

Revised Extra Credit

The system library is the means by which a process may invoke the system call in a program. For five points extra credit you may discover where the default library path and the default include path is. Make an addition to the makefile that when executed with `sudo make install` will install the project files (headers & library) files into the proper paths. If done correctly, you should be able to compile the get_tag and set_tag sources to executables without any -I or -L flags in gcc.

(This is in lieu of the much more challenging former extra credit of adding system library functions to the standard C library for your system.)

 

Manual Pages

You are required to create manual pages detailing the two system calls and the four library function calls. These manual pages shall be in man page format and in the appropriate manual section; you may copy and modify an existing man page for this purpose.

You may also “double up” on the man pages by creating a single man page that handles a pair of calls (e.g., the library calls for both get_tag and set_tag). This can be accomplished by including both calls in the page, saving with the name of one of the calls, then making a hard link for the second call’s man page (e.g., if you created get_tag.2, then ln get_tag.2 set_tag.2 will allow that file to be accessed as either get_tag.2 or set_tag.2 – see for example fopen(3)). This way, you can create three manual pages instead of six (as long as each man page addresses two calls).

You must place each new man page in the proper location so that entering the command man <S> set_tag or man <S> get_tag will return the man page for these calls in section <S>. You may check the manual path using the manpath(1) command to see where the man pages are, and type “man man” to see how the sections are arranged. At a minimum, the man page must have proper header/footer, name, synopsis, description, errors, notes, see also, and author.

 

Testing

You should test your code for all behavioral cases. You will include this information in your report and demonstrate the tests in your screencast video. You must also test that all your man pages display properly.

Submissions

You will submit the following at the end of this project:

 

• Report (txt) in man page format on Canvas, including link to unlisted screencast video
• Kernel Patch File (diff) on Canvas that includes sourcecode, makefile(s), and man pages
• Compressed tar archive (tar.gz) for tags library on Canvas

 

Report

Your report will explain how you implemented the new system calls, including what changes were made to which files and why each change was made.  It will include description of how testing was performed along with any known bugs. The report must be created using man format and be named p1.txt. The report should be no more than two pages and should cover all relevant aspects of the project. It must also include a link to an unlisted screencast video. The report must be organized and formatted professionally – this is not a memo!

 

Screencast

In addition to the written text report, you should submit a screencast (with audio) walking through the changes you make to the operating system to enable the system calls. Additionally, the screencast should include you showing/demonstrating your changes in action using your tests. (It should take no more than 5 minutes).

 

Patch File

The patch file will include all changes to all files in a single patch. Applying the patches and remaking the necessary parts of the OS, then rebooting and then building the test code (which we will also copy over) should compile the test program and link in the new library object code. Typing “man <S> set_tag” shall display the man page for set_tag in section <S>, and typing “man <S> get_tag” shall display the man page for get_tag in section <S>.