Hints for A2

This file may be updated during the term, so check back periodically

Quick Topic Links

general hints
console write and read
_exit
argument passing
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.

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 in your code, but 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 in 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. 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 be based on VFS, not 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.
vfs_open() is used to create a vnode to represent a file or a device. The name of the console device is "con:" - that's what you need to open to get a vnode that represents the console. Note, though, that a call like this:
```
struct vnode *vn;
result = vfs_open("con:", mode, &vn);
```
is incorrect and should bring a warning from the compiler. The problem is that vfs_open may modify its first argument, but "con:" is an unmodifiable literal. So instead you need to do something like this:
```
char *console = NULL;
console = kstrdup("con:");
result = vfs_open(console, mode, &vn);
kfree(console);
```
Once you have a vnode to represent the console, you can use VOP_WRITE and VOP_READ to write and read data. Both of these operations expect a uio structure pointer as a parameter. A uio structure essentially describes a data transfer between the console (or some other file or device) and a buffer in the kernel or user part of the address space. You need to create and initialize the uio structure prior to calling VOP_WRITE or VOP_READ. In a nutshell:
- uio_iovec describes the location and length of the buffer that is being transferred to or from. This buffer can be in the application part of the kernel address space or in the kernel's part.
- uio_resid describes the amount of data to transfer
- uio_rw identifies whether the transfer is from the file/device or to the file/device,
- uio_segflag indicates whether the buffer is in the user (application) part of the address space or the kernel's part of the address space.
- uio_space points to the addrspace object of the process that is doing the VOP_WRITE or VOP_READ. This is only used if the buffer is is in the user part of the address space - otherwise, it should be set to NULL.
See the comments in kern/include/uio.h for more information. kern/userprog/loadelf.c contains some useful examples of the creation, initialization, and use of uio structures for vnode operations.

_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> <location>");
	}
	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 shown in the following illustration:

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

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.

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"
```

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 Read/Write: palin, sink, conman, tictac
- Fork/Exit/Waitpid/Getpid: forktest, forkbomb
- Exception Handling: crash
- Execv: sty (no arg passing needed)
- Runprogram Arg Passing: argtest, add

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.