Hints for A2a

Quick Topic Links

general hints
_exit
fork
kernel include files
proper use of kmalloc and kfree
testing

General

Don't forget to re-configure your kernel for Assignment 2, and to do all of your kernel builds in kern/compile/ASST2

% cd $HOME/cs350-os161/os161-1.99/kern/conf
% ./config ASST2
% cd ../compile/ASST2
% bmake depend
% bmake
% bmake install

Don't forget that if you add any new source files to the kernel code, you need to update the file kern/conf/conf.kern and you need to reconfigure your kernel. If you don't do this, the code in your new source file will not be included in the kernel build.

Don't worry about trying to reclaim physical frames in the kernel when they are no longer used. However, you should make sure that you kfree kernel memory that you've allocated using kmalloc but that the kernel no longer needs.

You may like to have lots of debugging information printing out from your kernel, but the kernel you submit to us must not do so. OS/161's DEBUG facility that can help with this problem - you can bury lots of debugging statements into your code, and you can turn them all off by just changing the value of a single variable. You can even turn them off conditionally by labeling them properly.

You encountered the DEBUG mechanism in A0, but as a reminder:

To use this facility, you just include DEBUG statements into your code instead of kprintf, like this:
```
DEBUG(DB_EXEC, "ELF: Loading %lu bytes to 0x%lx\n", 
     (unsigned long) filesize, (unsigned long) vaddr);
```
The DEBUG macro and the various flags (like DB_EXEC) are defined in kern/include/lib.h.
To control which DEBUG statements produce output, set the dbflags variable, which is found in kern/lib/kprintf.c. For example, setting
```
u_int32_t dbflags = 0;
```
will turn off all debugging output, while
```
u_int32_t dbflags = DB_EXEC|DB_THREADS;
```
will turn off everything except DEBUG statements that are labeled with DB_EXEC or DB_THREADS.

_exit

The partial implementation of _exit in the base OS/161 does not do anything with the exit status code provided by the the user program. Your complete implementation of _exit should properly handle the exit status code as described in the manual pages for _exit and waitpid.
Here is something to think about when you do start worrying about those exit status codes: a process's exit status code may be needed long after that process has exited. Where will you keep the code, and when will it be safe to forget it?

fork

To implement fork, you will need to copy the address space and trap frame from the parent process to use for the child process. When you do this, you need to watch out for potential synchronization problems. Specifically, you will need to make sure that the new thread goes not go to user mode until its address space and trap frame have been set up. In addition, you need to make sure that the parent process does not return to user mode until its address space and trap frame have been copied.

Kernel include files

If you create a new kernel source (.c) file, you will need to #include one or more kernel header files at the top. The kernel has some requirements about what you must include, and about the order in which things must be included. In particular, the kernel expects that
```
#include ‹types.h›
```
will always come first. For more details and rules about #include, see the comments at the top of kern/include/types.h. Symptoms of failure to observe the these rules include complaints about errors in header files during kernel compilation.
OS/161 kernel header files follow a convention designed to ensure that headers will not get included twice during any compilation. For example, the kern/include/lib.h includes the following preprocessor code at the top of the file
```
#ifndef _LIB_H_
#define _LIB_H_ 
```
as well as a corresponding
```
#endif /* _LIB_H_ */
```
at the end of the file. This ensures that lib.h will never be included more than once during a compilation. Every other kernel include file includes similar code, for the same reason. If you add a new header file to your kernel, you should follow a similar convention to ensure that your header will never be included twice. Failure to do so can lead to compilation errors, such as complaints about multiply-defined symbols or variables.

proper use of kmalloc and kfree

You will need to use kmalloc to dynamically allocate memory for your kernel to use. When that memory is no longer needed, you need to make it available for later reuse by calling kfree. For example:
```
kvaddr = kmalloc(size);  /* allocated some memory */

/* do some stuff */

kfree(kvaddr);           /* finished with the memory so free it */
```
Currently (for Assignment 2) kfree and the calls it relies on to actually free memory don't do anything, so memory will not actually be reused (yet). Assignment 3 often requires completeing the kfree implementation so that memory is actually freed and is available for reuse. This permits multiple programs (or kernel tests) to be executed over and over again without having to reboot the OS.
So when working on Assignment 2, be sure to use kfree to free memory when it is not longer needed, otherwise you may have to find these memory leaks when implementing Assignment 3.

testing

There are many OS/161 applications that you can use to test your kernel. The source code for many of these applications can be found under os161-1.99/user, in the testbin, uw-testbin, bin and sbin directories.
You build all of the OS/161 application programs when you run bmake in the directory cs350-os161/os161-1.99. When you do this, the application program executable files are copied into subdirectories under cs350-os161/root/.
Once your OS/161 kernel has booted, you can launch an application program using the p command from the kernel menu. For example, to run the palin program, which is located in testbin, use the following command
```
OS/161 kernel [? for menu]: p testbin/palin
```
As usual, you can pass commands to the kernel on sys161 command line, e.g.,
```
sys161 kernel "p testbin/palin"
```

The amount of memory in the default system is not very large. For some of the test applications, you may wish to increase the amount of memory by modifying the appropriate line in the sys161.conf file. Note that this must be a multiple of the page size (4096), and that the # symbol will comment out a line. For example:
```
# Old/default value
# 31  mainboard  ramsize=524288  cpus=1
# Changed to 4 MB.
31  mainboard  ramsize=4194304  cpus=1
```
In particular, you will probably have to do this for applications like forktest, farm and sty.
To evaluate the kernel you submit for Assignment 2a, we expect to use at least the following test programs, with single-processor and multi-processor configurations:

uw-testbin/onefork

this is the simplest test of fork, and also checks the PIDs returned to the parent and child processes

uw-testbin/pidcheck

this is also a very simple test that relies on fork and getpid. It can confirm that the child PID that the parent sees is the same as the child PID that the child sees.

uw-testbin/widefork

multiple forks, and can also test whether exit status values are being passed properly through _exit to waitpid

testbin/forktest

this also performs multiple forks. It relies on proper waitpid synchronization, but not on the exit statuses being returned by waitpid

If you'd like more details about what these test programs are doing and what kind of output they produce, please just have a look at the programs themselves. The programs are all short, and reviewing them is a good way to ensure that you understand how the system calls work.