System/161

System/161 2.x Software and Hardware Manual
David A. Holland
September 29, 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:

- Getting and Installing System/161
- System/161 Virtual Hardware
- Running System/161 (below)
- Manipulating disk images (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.

### Manipulating disk images

The `disk161` tool can be used to manipulate disk images. It supports three actions: `create`, to create a new disk image; `info`, to print image information; and `resize`, to change the size of an image.

Create. Create a disk image like this:

       disk161 create LHD0.img 5M

This creates an image called `LHD0.img` capable of holding 5 megabytes of data. The size is given in bytes, but as above can given one of the suffixes `G`, `M`, `K`, or `s` for gigabytes, megabytes, kilobytes, sectors (512-byte units) respectively. The size must be a unit number of sectors.

Info. After creating `LHD0.img` as above,

       disk161 info LHD0.img

prints

       LHD0.img size 5242880 bytes (10240 sectors; 5120K; 5M)
       LHD0.img spaceused 8192 bytes (16 sectors; 8K; 0M)

meaning that the image holds up to 5M, but is currently only using 8K. (This is because the image is a sparse file by default; it only uses space for regions that have had data written to them. The only thing in a new image is the image header block, which is one sector rather than 8K; but here 8K is the host file system's block size.

Resize. Change the size of a disk image like this:

       disk161 resize LHD0.img 10M

which makes the image twice as big as before. You can also use + or - on the size argument to expand or shrink the image by a specified amount. Note that resizing the image will not resize any file system or other logical structure that may be stored on it. That must be done separately with other tools. Shrinking an image without doing this will destroy data.