Hints for A2

Quick Topic Links

general hints
write
_exit
argument passing
open,lseek,close,read,write
fork
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.11/kern/conf
% ./config ASST2
% cd ../compile/ASST2
% make depend
% make
% make 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 we don't want to see mountains of output when we run your kernel. OS/161 provides a 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. 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.

write

As your very first step, you should try writing a quick-and-dirty implementation of write. The goal of this is just to teach yourself how to get control from a user program into a kernel system call handler and back again. You can test this using the testbin/palin program, which only uses console (standard output) writes and _exit.
You can design your quick-and-dirty write system call so that it only handles writes to standard output, which are indicated by fd = 1 (see the manual page for the write system call). The kernel should direct writes to standard output to the console device, and a quick-and-dirty way for the kernel to do that is to use the kprintf function. You can use a simple kprintf-based implementation of write to test that control is actually getting to the system call handler, and that the handler is able to get the characters that the application wants to print.
Your final implementation of write should not be based on kprintf. One problem with the kprintf implementation of write is that kprintf assumes that its argument is a null-terminated character string. However, in general, the data that an application passes to a write system call may not consist of printable characters and will not, in general, be null-terminated. The kprintf-based write implementatin is just a way to get an initial system call working quickly.

_exit

Initially, you don't need to worry about what to do with the status code parameter to _exit. Store it away somewhere, or just ignore it, and focus on getting the process that called _exit cleaned up. Later, when you start working on fork and waitpid you can come back and worry about what to do with the status code.
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?

passing arguments

To pass arguments (argv) to a user program, you will have to load the arguments into the program's address space. In addition to the argument strings themselves, you have to create the argv array in the user program's address space - argv is an array of pointers to the actual argument strings.

Whenever you are loading date into an address space, you must ensure that it is properly aligned. Otherwise, the application will cause addressing exceptions when it tries to access the data. 4-byte items, like character pointers, must start at an address that is divisible by 4. So, it would be OK to start your argv array at an address like 0x7fffff08, but your application will run in to alignment problems if argv starts at an address like 0x7fffff09 or 0x7fffff0a, since those addresses are not divisible by 4. Characters are only 1 byte long, so there are no alignment issues. Your argument strings, which are character arrays, can start at any address.
A related constraint is that the stack pointer should always start at an address that is 8-byte aligned (evenly divisible by 8). This is because the largest data types that require alignment (and which might be pushed onto a stack) are 8 bytes long, e.g., a double-precision floating point value.
Make sure that you understand how argv and argc are supposed to work before you try implementing argument passing. As an example, consider the testbin/tail application, which expects two arguments. The main() function of tail looks like this:
```
int
main(int argc, char **argv)
{
	int file;

	if (argc < 3) {
		errx(1, "Usage: tail  ");
	}
	file = open(argv[1], O_RDONLY);
	if (file < 0) {
		err(1, "%s", argv[1]);
	}
	tail(file, atoi(argv[2]), argv[1]);
	close(file);
	return 0;
}
```
argv is a character pointer pointer - it points to an array of character pointers, each of which points to one of the arguments. For example, if the tail program is invoked from the kernel command line like this:
```
OS/161 kernel [? for menu]: p testbin/sort foo 100
```
Then the argv and argc variables should be set up as illustrated in the following illustration:

A detailed description of the expected set up of argv and argc can be found in the man page for the execv system call.

open, lseek, close, read, write

A call like this:
```
result = vfs_open("string", mode, &2vn);
```
is incorrect and should bring a warning from the compiler. The problem is that vfs_open may modify its first argument, but "string" is an unmodifiable literal. So if, for example, you want to open the console, you need to do something like this instead:
```
char *console = NULL;
console = kstrdup("con:");
result = vfs_open(console,mode,&vn);
kfree(console);
```
VOP_WRITE, VOP_READ, and other operations on vnodes want a uio structure as a parameter. kern/userprog/loadelf.c contains some useful examples of uio structures being setup and used for vnode operations.

fork

To implement fork, you will need to copy the address space, open file information, 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, open file information, 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, trap frame, and open file information have been copied.

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.11/testbin. Some other applications live under os161-1.11/bin and os161-1.11/sbin.
You build all of the OS/161 application programs when you run make in the directory cs350-os161/os161-1.11. When you do this, the application program executable files are copied into cs350-os161/root/testbin (or root/bin or root/sbin).
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"
```
Be sure to see the next note, about modifying your kernel

We would like to be able to autotest your submissions by scripting and running commands like this (and like the others shown above):
```
% sys161 kernel "p testbin/palin;q"
```
The idea is that this should first launch the palin application from testbin, and then, when palin is finished, shutdown the kernel using the q command. Unfortunately, these kinds of commands will not work in OS/161 as it is provided to you. The problem is that after creating a new thread to run the palin program, the main kernel thread will immediately read the next command without waiting for the palin application to finish running. In this case, the next command is q, which means that the kernel will shut down immediately, probably before palin has finished running. This is not the behaviour we want.
For this reason, you need to modify the way the kernel launches programs when it receives a p command. After the main kernel thread gets the p command and launches a new thread to run the application program, the main thread should wait for the new thread to finish before continuing to read and process the next kernel menu command. A good place to make this change is in the common_prog function in kern/main/menu.c, since that is where the main kernel thread launches a new thread to run the application.
Once you have implemented the kernel changes needed for waitpid, it should be relatively easy for you to modify common_prog so that the main thread will wait for the newly-created thread. In the meantime, here is a simple (but not very elegant) way to change your kernel so that the main kernel thread will wait for launched application programs to finish. Two changes are needed. In the common_prog function, just before the function returns, add the following code:
```
#if OPT_A2
	while (!one_thread_only()) {
	  clocksleep(1);
	}
#endif /* OPT_A2 */
```
Also, don't forget to add #include "opt-A2.h" to the top of kern/main/menu.c so that this change will take effect. The second change is to add the one_thread_only function to kern/thread/thread.c, like this:
```
#if OPT_A2
/*
 * returns true (1) if the number of threads in the system is
 * equal to 1, otherwise returns fals (0).
 *
 * See the usage note in thread.h
 */
int
one_thread_only() {
  int s;
  int n;
  /* numthreads is a shared variable, so turn interrupts
     off to ensure that we can inspect its value atomically */
  s = splhigh();
  n = numthreads;
  splx(s);
  return(n==1);
}
#endif /* OPT_A2 */
```
and a corresponding function prototype in kern/include/thread.h:
```
#if OPT_A2
/*
 * returns true (1) if the number of threads in the system is
 * equal to 1, otherwise returns fals (0).
 * 
 * Usage Note: if this function returns 0 (false), the actual thread
 * count in the system may have changed by the time the calling 
 * function is able to use the returned value.  Thus, a return value
 * of 0 provides little information to the caller.
 * However, if the return value is 1 (true), then the calling thread
 * is the only thread in the system.  Unless the caller itself
 * creates new threads (or unless the kernel spontaneously lauches
 * new threads, e.g., in response to interrupts), the caller will
 * know that it is the only thread in the system.
 */
int one_thread_only(void);
#endif /* OPT_A2 */
```
Again, don't forget to include opt-A2.h in both thread.c and thread.h.
After making these changes, rebuild your kernel (make depend, make, make install). When you run the new kernel and launch an application program from the kernel menu with the p command, you should find that the kernel does not prompt for new command until the launched application has finished.
Again, this implementation is just intended to be a stopgap until you have made enough progress on your kernel to allow you to make the main thread wait specifically for the new application thread that it launches. You're not required to use this implementation. However, you must ensure somehow that the main kernel thread waits. Doing so will make your own testing easier, and without that change we will not be able to autotest your code.

Tim Brecht has prepared a handy chart that shows which system calls are used by each of the programs in testbin.

The following list summarizes the applications that we plan to use to test the various parts of your assignment. All of the applications are in testbin unless othewise specified.
- Console:palin,sink,conman,tictac
- Arg Passing:argtest,add
- File Access:hash,bigfile,tail,bin/cat
- Fork/Exit/Waitpid/Getpid:forktest,forkbomb
- Execv:farm,sty
- Exception Handling:crash

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). For example:
```
# Old/default value
# 31      busctl  ramsize=524288
# Changed to 2 MB.
31      busctl  ramsize=2097152
```
In particular, you will probably have to do this for applications like forktest, farm and sty.