System Call Simulation

The User Side

Let's start with the user side of things. We'll write a program that uses a few system calls, but rather than using the standard system-call wrappers (from the C library), we'll use a generic function, system_call, that can make any system call provided by our simulated kernel. (We'll also include a uprintf function (that's similar to printf), so we can print debugging messages and see what's happening.)

#include "user.h"

int
main(void)
{
        long ret;
        int exit_code = 0;

        uprintf("User process started up.\n");

        ret = system_call(SYS_PRINT, (intptr_t) "Hello, Kernel!\n", 0, 0, 0);
        uprintf("SYS_PRINT returned: %ld\n", ret);

        ret = system_call(SYS_PRINT, 0, 0, 0, 0);
        uprintf("Errorneous SYS_PRINT returned: %ld (%s)\n", ret,
                strerror(errno));

        ret = system_call(SYS_GET_PID, 0, 0, 0, 0);
        uprintf("SYS_GET_PID returned: %ld\n", ret);

        uprintf("Calling SYS_EXIT\n");
        system_call(SYS_EXIT, exit_code, 0, 0, 0);

        uprintf("This should not be printed\n");
        return 0; /* This should never be reached */
}

Our system_call function takes a system-call number and up to four arguments. It returns the return value of the system call (which may also set the global errno variable). All the arguments are intptr_t values, which are integers that are the same size as pointers on the system, allowing us to cast pointers to integers and back again.

The Kernel Side

Here's code on the kernel side of the divide that implements the system calls.

#include "kernel.h"

#define SIMULATED_PID 42
#define SYS_PRINT_LIMIT 4096 /* Maximum number of characters to print */

int
sys_print(const_userptr_t str, int *len_printed)
{
        char kernel_buf[SYS_PRINT_LIMIT];
        int err;

        err = copyinstr(str, kernel_buf, sizeof(kernel_buf), NULL);
        if (err == 0) {
                fputs(kernel_buf, stdout);
                *len_printed = strlen(kernel_buf);
                return 0;
        } else {
                return err;
        }
}

int
sys_get_pid(int *pid)
{
        *pid = SIMULATED_PID;
        return 0;
}

int
sys_exit(int code)
{
        kprintf("User process exited with code %d\n", code);
        /* Terminate the user process */
        kill(user_pid, SIGTERM);
        return 0;
}

void
handle_syscall(struct syscall_args *args, struct syscall_result *result)
{
        int err, retval;

        kprintf("Handling syscall %d\n", args->num);

        switch (args->num) {
        case SYS_PRINT:
                err =
                    sys_print((const_userptr_t) args->args[0], (int *) &retval);
                break;
        case SYS_GET_PID:
                err = sys_get_pid((int *) &retval);
                break;
        case SYS_EXIT:
                err = sys_exit(args->args[0]);
                user_connected = false;
                return;
        default:
                kprintf("Unknown syscall number: %d\n", args->num);
                err = ENOSYS;
                retval = -1;
        }

        result->err = err;
        result->ret_val = err ? -1 : retval;

        kprintf("Syscall %d returning %d, err=%d\n", args->num, retval, err);
}

Here, we've written a helper function for each system call, and a handle_syscall function that dispatches to the appropriate helper function based on the system-call number. The handle_syscall function also sets the return value and error code in the syscall_result structure the kernel will return to the user process.

As in the user code, the kernel needs to use a cast to convert the intptr_t arguments to the appropriate types.

Accessing User Memory

User memory is in a separate address space from the kernel, so the kernel can't directly access it. Instead, some kind of mechanism is needed to copy data between user and kernel memory. In OS/161, this is done with the copyin and copyout functions, which are defined as,

int copyin(const_userptr_t usersrc, void *dest, size_t len);
int copyout(const void *src, userptr_t userdest, size_t len);
int copyinstr(const_userptr_t usersrc, char *dest, size_t len, size_t *got);
int copyoutstr(const char *src, userptr_t userdest, size_t len, size_t *got);

where

• copyin copies len bytes from the user-space address usersrc to the kernel-space address dest.
• copyout copies len bytes from the kernel-space address src to the user-space address userdest.
• copyinstr is like copyin, but it copies a null-terminated string; it writes the total number of bytes copied to got.
• copyoutstr is like copyout, but it copies a null-terminated string; it writes the total number of bytes copied to got.

All of these functions return an error code, with zero indicating success. Possible errors are

• EFAULT if the memory access is invalid.
• ENAMETOOLONG if the string is too long.

Error Handling

It's vitally important that the kernel never crash, even if the user provides bad input. One very nice thing about the memory-copy functions is that they will return an error code if the memory access is invalid, rather than crashing the kernel. Catching the problem allows the kernel to return an error code to the user process, which can then take appropriate action.

But it also means that in kernel code, we have to be fastidious about both checking the return values of functions that might return an error code, and taking appropriate action if an error occurs.

Putting It All Together

To make our user-space / kernel-space simulator work, we need some support code. For the most part, you can ignore the details, but how it's actually implemented is

• A Unix process for the “kernel”, which handles the system calls.
• A Unix process for the “user process”, which makes the system calls.
• A communications channel between the two processes, which is used to pass system-call numbers and arguments from the user process to the kernel process, and to pass return values and error codes back.
  • The communications protocol also handles requests from the kernel to read and write user memory.

• Try the simulator in Online GDB

Alternatively, you can download the code and run it on your own machine. You can compile it with cc -g -Wall -o kern-sim *.c and run it with ./kern-sim.

In either case, the two most important files to look at are user.c and kernel.c.

Run it and take a look at the output. If you look at the code, you'll see we added a little bit of extra code to the user program compared to the code we showed above.

When you run the code, you should see output like

- kern: Kernel-space booting.
- user: User process started up.
- kern: Handling syscall 1
Hello, Kernel!
- kern: Syscall 1 returning 15, err=0
- user: SYS_PRINT returned: 15
- kern: Handling syscall 1
ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOP
- kern: Syscall 1 returning 1499, err=0
- user: SYS_PRINT returned: 1499 (Success)
- kern: Handling syscall 1
- kern: Syscall 1 returning 1499, err=14
- user: Errorneous SYS_PRINT returned: -1 (Bad address)
- kern: Handling syscall 2
- kern: Syscall 2 returning 42, err=0
- user: SYS_GET_PID returned: 42
- user: Calling SYS_EXIT
- kern: Handling syscall 3
- kern: User process exited with code 0
- kern: Kernel-space shutting down.

Going Further, Part 1

Let's fork this code, and add another system call, SYS_GET_TIME. You have two choices for how to implement this:

• Return the time as the syscall's return value, much like SYS_GET_PID returns a fixed value.
• Take a pointer to a long value in user memory, and return the time in that location. This option will give you practice with copyout.

You can use the time function from the standard C library to get the current time, and then return it to the user process.

You'll need to

• Edit common.h to add a new system-call number. Find the line that says

  enum syscall_num { SYS_PRINT = 1, SYS_GET_PID, SYS_EXIT };
  

  and add a new entry for SYS_GET_TIME to the end of the list.

• Edit kernel.c to add a new function sys_get_time that takes a userptr_t argument for a place in user-space memory that points to a long value, and returns the current time in seconds since the Unix epoch. The function should return 0 on success, and an error code on failure.

  • You'll need to #include <time.h> to use the time function.

• Edit kernel.c to add a case for SYS_GET_TIME to the handle_syscall function, which calls sys_get_time and sets the return value and error code in the syscall_result structure.

• Edit user.c to add a call to SYS_GET_TIME and print the result with uprintf (use the %ld format specifier to print a long value).

Try running the code with your new system call. You should see the current time in seconds since the Unix epoch printed out, looking something like this:

- kern: Handling syscall 4
- kern: Syscall 4 returning 0, err=0
- user: SYS_GET_TIME returned: 0, time: 1727739692

Except that instead of 1727739692, it'll probably be closer to 1727739692, since that's the actual number of seconds since the Unix epoch right now.

The change to kernel.c might look something like

int
sys_get_time(userptr_t timeptr)
{
        long now = time(NULL);
        return copyout(&now, timeptr, sizeof(now));
}

and adding this case to handle_syscall

        case SYS_GET_TIME:
                err = sys_get_time((userptr_t) args->args[0]);
                retval = 0;
                break;

The change to user.c might look something like

        long now;
        ret = system_call(SYS_GET_TIME, (intptr_t) &now, 0, 0, 0);
        uprintf("SYS_GET_TIME returned: %ld, time: %ld\n", ret, now);

If you want to see the full working code, you can download the completed code.

Going Further, Part 2

If you want to go even further, you could implement a SYS_INPUT system call that reads a line of input from the user and returns it to the user process. You could use the getline function from the standard C library to read a line of input from the user, which allows arbitrary-length inputs. Be sure to free the memory that getline allocates after you're done with copying the string to user memory.

Implemented, a run might look something like

- kern: Handling syscall 1
Enter your name:
- kern: Syscall 1 returning 17, err=0
- user: SYS_PRINT returned: 17
- kern: Handling syscall 5
Melissa         <-- User types this and presses Enter
- kern: Syscall 5 returning 8, err=0
- user: SYS_INPUT returned: 8, 'Melissa'

Give it a try!

You can check out the completed code if you want to see a working implementation.

(When logged in, completion status appears here.)