Operating Systems

System/161

System/161 is a synthetic (read: made up) hardware platform designed specifically for use in this coure. It includes a simulated system bus and bus devices, and any of several possible simulated CPUs.

This document includes the following other documents:

LAMEbus programming info
System/161 LAMEbus devices
LAMEbus on MIPS

Running System/161

There are two versions of System/161 that can be built: 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.

-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 kernel instead of treating them as requests to sys161.

-w

Wait for a debugger connection immediately on startup.

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.

System/161 Config Files

System/161 reads a config file to determine what hardware it should simulate. The default config file is ./sys161.conf. A different one can be specified with the -c option.

The config file is composed of lines in the following form:

slot-number device-name [args...]

Slots may be 0-31. You must place the bus controller card in slot 31, or the system will not run.

Single-line comments are introduced with #.

The devices available, and the arguments they support, are:

busctl		LAMEbus bus controller
	ramsize=bytes		Specify size of physical RAM. Required.
timer		CS161 timer device
	(no arguments)
disk		CS161 disk device
	rpm=cycles		Specify rotation speed. Must be multiple of 60. Default is 3600.
	sectors=sectors		Specify number of 512-byte sectors on disk. Required.
	file=filename		Filename to use for disk storage. Required.
	paranoid		If set, call fsync() on every disk write to hopefully ensure data is not lost if the host system crashes. Slow and not recommended for normal operation.
serial		CS161 serial console
	(no arguments)
screen		CS161 full-screen console
	(no arguments)
	Note: not available yet.
nic		CS161 network interface
	hwaddr=addr		Set the hardware address for this network card. The hardware address is a 16-bit integer. (Note that 0 and 65535 (0xffff) are reserved for special purposes.) Required.
	hub=path		Set the path to the socket for the network hub, hub161. The default is .sockets/hub.
emufs		CS161/OS161 emulator pass-through filesystem
	dir=directory		Directory to use as root of emufs filesystem. Default is ..
trace		System/161 trace controller
	(no arguments)
random		CS161 random number generator
	seed=number		Set seed for pseudo-random-number generator. Default is 0.
	autoseed		Set seed for pseudo-random-number generator based on the system clock.
	Note: if you have multiple random devices, they all share the same randomizer state.

System/161 Programming Information

At present, System/161 can be compiled to simulate only one fully supported processor type: the MIPS r2000/r3000. There is partial support for the Ant-32 processor as well, but this is incomplete and not supported. It may not be present in the release tarfiles.

This page does not document MIPS r2000/r3000 programming.

The system bus used in System/161 is a simplified architecture made up for the purpose; it is fittingly called LAMEbus. There are also a half dozen or so simulated devices available.

LAMEbus programming info
System/161 LAMEbus devices

The kernel loaded by System/161 is (at present) loaded by the simulator, not a boot ROM within the simulator. Thus, at present, any of the memory regions described as being boot ROMs are in fact unmapped and accesses to them will cause bus errors.

The kernel will be loaded into physical memory at an address chosen so that it appears in kernel virtual memory at the virtual address it was linked to be run at. (The desired address should be passed to the linker at kernel build time.) Precisely what this means depends on the processor and MMU in use. See the processor-specific pages listed at the top of the LAMEbus programming page.

Control will be transferred to the entry point of the kernel specified in the ELF file. The entry point will be called as if it were a C function taking one argument: a string. This string contains the kernel arguments passed on the System/161 command line, concatenated with spaces.

Both the argument string and a small bootup stack, and possibly other machine-dependent data, are located in the top few pages of physical memory. The precise location is not specified and should not be assumed. The kernel should establish its own stack, copy the string to a known location elsewhere, and handle any other machine-dependent data appropriately; then it can reuse the top of physical memory for its own purposes.