System/161

System/161 2.x Software and Hardware Manual
David A. Holland
August 19, 2010

Copyright 2000, 2001, 2002, 2009, 2010
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:

- Getting and Installing System/161
- System/161 Virtual Hardware
- Running System/161 (below)
- Remote debugging with `gdb`
- Network connectivity with `hub161`
- Programming specs: MIPS processor LAMEbus Hardware devices

### 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.