In this task, you will make changes to xv6 to add support for kernel threads to the OS. Once this part is done you will need to create the system calls that will allow the user to create and manage new threads. Kernel level threads (KLT) are implemented and managed by the kernel. A single process may execute multiple kernel threads, which may operate concurrently on a multi-core machine. Each process contains its own static array of threads. The maximum number of threads each process can hold is defined in `kthread.h`.

Please also read Chapter 1 of the xv6 book about the organization of xv6.

The xv6 code for this assignment (which is different from the code you started with in PA1) already includes some significant refactoring. However, the current thread implementation is missing some important functionality. Your job is to add additional thread management facilities and enforce correct thread semantics on existing system calls.

Supporting multiple threads per process means that you will have to think about handling shared resources. For example: growproc() is a function in `proc.c` which is responsible for retrieving more memory when the process asks for it. If not protected, 2 running threads of the same process calling this function may override the sz parameter and cause issues in the system. You need to synchronize all shared fields of the thread owner when they are accessed.

Make sure you watch the lecture that covers the PA2 slides.

To download the xv6 code base for PA2, please open a Terminal and type the following:

    cd
    cd cs350
    mkdir pa2
    cd pa2
    wget --user=USERNAME --password=PASSWORD http://bourbon.usc.edu/cs350-m25/programming/pa2/xv6-pa2-src.tar.gz

where USERNAME and PASSWORD are the username and password used to access protected content from our class web site.

After you have downloaded the xv6-pa2-src.tar.gz file, do:

    tar xvf xv6-pa2-src.tar.gz
    cd xv6-pa2-src

Now you are all set up!

Make sure you watch the lecture that covers the PA2 slides.

Here is an inexhaustive list of the expected behavior of existing system calls after you have finished this part (you may not have to make modifications to all of them):

fork()

should duplicate only the calling thread, if other threads exist in the process they will not exist in the new process.

exec()

should start running on a single thread of the new process. Note that in a multi-threaded environment a thread might be running while another thread of the same process is attempting to perform exec. The thread performing exec should “tell” other threads of the same process to destroy themselves and only then complete the exec task.

exit()

should kill the process and all of its threads, remember while a single thread is executing exit, others threads of the same process might still be running.

In this part of the assignment, you will add system calls that will allow applications to create KLTs. Use the file named kthread.h to contain the prototypes of the KLT API functions but implement them in `proc.c`.

The API for thread system calls is as follows: int kthread_create(void*(*start_func)(), void* stack, int stack_size);

Calling kthread_create() will create a new thread within the context of the calling process. The newly created thread state will be TRUNNABLE. The caller of kthread_create() must allocate a user stack for the new thread to use (it should be enough to allocate a single page i.e., 4K for the thread stack). This does not replace the kernel stack for the thread. start_func is a pointer to the entry function, which the thread will start executing. Upon success, the identifier of the newly created thread is returned. In case of an error, a non-positive value is returned. The kernel thread creation system call on real Linux does not receive a user stack pointer. In Linux the kernel allocates the memory for the new thread stack. You will need to create the stack in user mode and send its pointer to the system call in order to be consistent with current memory allocator of xv6.

int kthread_id();

Upon success, this function returns the caller thread's id. In case of error, a non-positive error identifier is returned. Remember, thread id and process id are not identical.

void kthread_exit();

This function terminates the execution of the calling thread. If called by a thread (even the main thread) while other threads exist within the same process, it shouldn’t terminate the whole process. If it is the last running thread, process should terminate. Each thread must explicitly call kthread_exit() in order to terminate normally.

int kthread_join(int thread_id);

This function suspends the execution of the calling thread until the target thread (of the same process), indicated by the argument thread_id, terminates. If the thread has already exited, execution should not be suspended. If successful, the function returns zero. Otherwise, -1 should be returned to indicate an error.

The code distribution contains 5 test files: `threadtest1.c`, `threadtest2.c`, and `threadtest3.c`. Most of the points on this assignment will be based on your code matching the expected outputs provided below.

threadtest1.c

    xv6...
    cpu0: starting
    sb: size 1000 nblocks 941 ninodes 200 nlog 30 logstart 2          inodestart 32 bmap start 58
    init: starting sh
    $ threadtest1
    thread in main 3,process 3
    Thread id is: 4
    Thread id is: 5
    Thread is exiting.
    Thread is exiting.
    Got id : 4 
    Got id : 5 
    Finished.
    $ 

threadtest2.c

    xv6...
    cpu0: starting
    sb: size 1000 nblocks 941 ninodes 200 nlog 30 logstart 2          inodestart 32 bmap start 58
    init: starting sh
    $ threadtest2
    ~~~~~~~~~~~~~~~~~~ thread test ~~~~~~~~~~~~~~~~~~
    thread 1 says hello
    thread 2 says hello
    thread 3 says hello
    all threads exited
    $ 

threadtest3.c

    xv6...
    cpu0: starting
    sb: size 1000 nblocks 941 ninodes 200 nlog 30 logstart 2          inodestart 32 bmap start 58
    init: starting sh
    $ threadtest3
    Joining 4
    Thread 4 running !
    Thread 5 running !
    Thread 6 running !
    Joining 5
    Joining 6

    All threads done!
    $ 

The grading guidelines has been made available. Please run the commands in the grading guidelines on a standard 32-bit Ubuntu 16.04 system. It is possible that there are bugs in the guidelines. If you find bugs, please let the instructor know as soon as possible. (Note: if I change the grading guidelines, I will make an announcement in the class Piazza. Please remember that you are required to read my posts in the class Piazza.)

The grading guidelines is the only grading procedure we will use to grade your program. No other grading procedure will be used. Please note that the grader may use a different set of test programs and commandline arguments when grading your submission. (We may make minor changes if we discover bugs in the script or things that we forgot to test.) It is strongly recommended that you run your code through the commands in the grading guidelines.

Please read the general programming FAQ if you need a refresher on file I/O and bit/byte manipulications in C.

If you have made all your code changes in-place (which you are requied to do), it will be very easy to create a gzipped tarfile for submission using the Bistro system. To create your submission file, just do the following:

    make pa2-submit

and the following command should run:

    tar cvzf pa2-submit.tar.gz \
            Makefile \
            pa2-README.txt \
            proc.c \
            proc.h \
            syscall.c \
            sysproc.c \
            kthread.h \
            exec.c

Please note that you are not permitted to change any other existing files. If you submit another existing file, it will be deleted before grading. If you give instructions to the grader to modify another existing file (other than Config.mk), it will disregarded.

A pa2-README.txt template file is provided here. You must save it as your pa2-README.txt file and follow the instructions in it to fill it out with appropriate information and include it in your submission. You must not delete a single line from w1-README.txt. Please make sure that you satisfy all the README requirements.

To check the content of pa2-submit.tar.gz, you can use the following command:

    tar tvzf pa2-submit.tar.gz

Please read the output of the above command carefully to see what files were included in pa2-submit.tar.gz and what are their file sizes and make sure that they make sense.

Please enter your USC e-mail address and your submission PIN below. Then click on the Browse button and locate and select your submission file (i.e., pa2-submit.tar.gz). Then click on the Upload button to submit your pa2-submit.tar.gz. (Be careful what you click! Do NOT submit the wrong file!) If you see an error message, please read the dialogbox carefully and fix what needs to be fixed and repeat the procedure. If you don't know your submission PIN, please visit this web site to have your PIN e-mailed to your USC e-mail address.

When this web page was last loaded, the time at the submission server (merlot.usc.edu) was 28Nov2025-01:56:04. Reload this web page to see the current time on merlot.usc.edu.

USC Email:

 @usc.edu

Submission PIN:

Event ID (read-only):

Submission File Full Path:

 

 
If the command is executed successfully and if everything checks out, a ticket will be issued to you to let you know "what" and "when" your submission made it to the Bistro server. The next web page you see would display such a ticket and the ticket should look like the sample shown in the submission web page (of course, the actual text would be different, but the format should be similar). Make sure you follow the Verify Your Ticket instructions to verify the SHA1 hash of your submission to make sure what you did not accidentally submit the wrong file. Also, an e-mail (showing the ticket) will be sent to your USC e-mail address. Please read the ticket carefully to know exactly "what" and "when" your submission made it to the Bistro server. If there are problems, please contact the instructor.

It is extreme important that you also verify your submission after you have submitted pa2-submit.tar.gz electronically to make sure that every you have submitted is everything you wanted us to grade. If you don't verify your submission and you ended up submit the wrong files, please understand that due to our fairness policy, there's absolutely nothing we can do.

Finally, please be familiar with the Electronic Submission Guidelines and information on the bsubmit web page.