System/161 2.x Software and Hardware Manual

David A. Holland
January 23, 2014

Copyright 2000, 2001, 2002, 2009, 2010, 2014
The President and Fellows of Harvard College.


Introduction & Contents

System/161 is a synthetic (read: made up) hardware platform designed specifically for teaching operating systems and for experimental operating system hacking. It includes a simulated CPU, system bus, and bus devices that are realistic but simple and easy to work with.

New in System/161 2.x: support for multiprocessor and multicore system configurations.

The rest of this manual is divided into the following subsections:

Running System/161

There are two versions of System/161 that are built and installed: the normal one, sys161, and one compiled to be able to log information about what's happening and generally assist debugging, which is called trace161.

The general format for the command line for either of these is like this:

sys161 [ System/161 options ] kernel [ kernel options ]

The System/161 options are:

-c configfile
Specify alternate config file. Default is sys161.conf.
-D count
Enable the doom counter. After the specified number of disk writes, the machine halts abruptly. (This is useful for testing file systems.) Individual disks can be marked "nodoom" in the config file, in which case writes to those disks do not count. (This is useful for your swap disk.)
-p port
Listen for debugger connections on specified TCP port. The default is to use the Unix-domain socket ./.sockets/gdb for debugger connections.
Note: because the remote gdb protocol does not support authentication, use this option only with caution.
-s
Pass signal-generating characters (^C, ^Z, etc.) through to the running kernel instead of treating them as requests to sys161.
-w
Wait for a debugger connection immediately on startup.
-X
Do not hang waiting for the debugger; exit instead.
-Z secs
Check for progress and first warn, then drop to the debugger if no progress occurs in the specified amount of simulator time. Progress is defined as successfully retiring an instruction in user mode. Don't use this option with in-kernel test workloads.

The following additional options control trace161's tracing and are ignored by sys161:

-f tracefile
Set the file trace information is logged to. By default, stderr is used. Specifying -f- sends output to stdout instead of stderr.
-t traceflags
Tell System/161 what to trace. The following flags are available:
d Trace disk I/O
e Trace emufs I/O
j Trace jumps and branches
k Trace instructions in kernel mode
n Trace network I/O
t Trace TLB/MMU activity
u Trace instructions in user mode
x Trace exceptions
Caution: tracing instructions generates huge amounts of output that may overwhelm smaller host systems.

The following option is also only available in trace161:

-P
Collect a kernel profile and leave it in the file gmon.out for analysis by gprof.

The kernel is an operating system kernel to load and run. It should be an ELF-format executable for the same processor type as System/161 is compiled to support. For further information, see below.

Note that options found after the kernel name will be passed to the kernel and not interpreted by System/161.