SYS161(1)

NAME
sys161, trace161 - System/161 machine simulator

SYNOPSIS
sys161 [-c config] [-D doom] [-p port] [-swX] [-Z timeout] kernel [kernel-arguments ...]
trace161 [-c config] [-D doom] [-p port] [-swX] [-Z timeout] [-f tracefile] [-P] [-t traceflags] kernel [kernel-arguments ...]

DESCRIPTION
The System/161 machine simulator provides up to 32 32-bit MIPS processors in a simplified hardware environment suitable for teaching or low-level experimentation. (Please see the full manual for programming and configuration information.) Use sys161 for regular operation, including debugging with gdb(1). The trace161 program should be run instead when accessing certain expensive functionality that makes the CPU code run slower.

OPTIONS
The first argument not beginning with a dash is treated as the kernel image to load and execute. Anything following the kernel name on the command line is concatenated together and provided to the kernel as the boot argument string. With suitable kernel support it is therefore possible to choose tests or programs to run directly from the System/161 command line.

The supported options (coming before the kernel name) are:

-c config
    Specify the config file to read. The default is sys161.conf.

-D doom
    Set the “doom counter”. After the selected number of writes to non-exempted disk devices, the machine shuts itself off. This is useful for testing file systems.

-f tracefile
    This option is accepted only when running trace161 and chooses the destination for trace output. Note that when tracing to a file the the trace output is slightly different in order to better allow cross-referencing trace output and regular machine output.

-p port
    Listen on the selected TCP port for connections from gdb(1). Note that unless firewalled or otherwise filtered, this allows anyone anywhere to connect a debugger to your System/161 process and do virtually anything with it; it is not safe except in a carefully controlled environment. By default, System/161 listens on the local socket .sockets/gdb instead. (This, however, requires corresponding patches to gdb(1) to teach it to talk to local filesystem sockets.)

-P  This option is accepted only when running trace161 and enables kernel profiling. At shutdown time, a profile dump is written to the file gmon.out suitable for use with the gprof(1) utility. Note that because the profile collector is integrated with the CPU model, its timings are much more precise than gprof(1) expects; you can safely tell gprof to use several more significant figures than it normally does.

-s  Do not allow keyboard/terminal signals (such as control-C) to affect System/161 itself; instead send the corresponding keystrokes to the guest kernel running inside System/161. Since System/161 is intended for teaching and experimentation, not production use, and it is much more common to want to interrupt a broken guest kernel than to interrupt a program running on the guest kernel, the default is to allow these key combinations to kill System/161.

-t traceflags
    This option is accepted only when running trace161 and sets the trace flags to use. Each flag enables a different set of trace points. The trace flags are:

    k   Trace kernel instructions.

    u   Trace user instructions.

    j   Trace jumps.

    t   Trace TLB / MMU operations.

    x   Trace exceptions.

    i   Trace interrupts.

    d   Trace disk activity.

    n   Trace network activity.

    e   Trace emufs operations.
    Note that tracing instructions both is slow and generates extremely voluminous output. Sometimes, however, it is the best way to hunt a bizarre bug...

-w  Wait for a debugger connection before beginning to execute the kernel.

-X  By default, System/161 drops to the debugger (waiting for a debugger connection if no debugger is already connected) on various adverse conditions. If the -X option is given, it exits with an error message instead of dropping to the debugger. This is useful for unattended testing runs.

-Z timeout
    Monitor kernel execution and check for progress. Progress is defined as successfully retiring at least one instruction in user mode. The timeout is measured in seconds. If this much (virtual) time elapses with no progress, a warning is printed; if the same amount of time then elapses again with still no progress, System/161 drops to the debugger. (Or, if the -X option is in effect, exits with an error message.) This is useful for unattended testing runs.

    Note that while this mode is intended to catch unwanted deadlock, livelock, and infinite loop states, it will equally also trigger if the guest system is sitting at a prompt waiting for input. Furthermore, because execution within the kernel is not counted as progress, it should not be used in connection with purely in-kernel tests.

FILES
sys161.conf
    The default configuration file.
gmon.out
    The file name used when generating a kernel execution profile.
.sockets/gdb
    The socket used by default for communicating with the debugger.
.sockets/meter
    The socket used to communicate with stat161(1).
.sockets/hub
    The socket used by default by the network device to communicate with hub161(1).
.sockets/net-ABCD
    The source address socket used to send to hub161(1), where ABCD is the network device's hardware address.

SEE ALSO
disk161(1), hub161(1), stat161(1)

BUGS
The sys161 and trace161 programs differ only by compile-time conditionals in the MIPS CPU code. It would be better to have one executable that chooses which of two compiled copies of that code to run based on the command-line options.