This program was originally written by Brad Parker brad@heeltoe.com, and is designed to emulate the MIT CADR microprocessor and hardware peripherals. The CADR is a second generation MIT Lisp Machine, and a good description can be found at https://tumbleweed.nu/r/lm-3/uv/cadr.html.

There is sufficient hardware support for the disk and network to provide a reasonably functional Lisp Machine experience.

Getting started (quickly)

Please see the README in the l project for how to quickly get up and running.

Configuration of usim (usim.ini)

When usim starts, it tries to read usim.ini which is a INI style configuration file consisting of sections, and key/value pairs.

usim section

• state_filename: Specifies a state file that is saved either when a user sends SIGINFO/SIGUSR1, or on halt if the -d option was passed to usim.

• sys_directory: Specifies a directory where all System sources live, by mapping the /tree prefix in the FILE server to this directory. Note that all other files and directories, outside /tree are also available through the local FILE server. Better: use the fs_root_directory option below.

• fs_root_directory: Specifies where the root of the files served by the local FILE server is. This provides a better "sandbox" for the FILE server than the sys_directory option. If your sources were previously in your sys subdirectory, if you move them to a tree subdirectory of the fs_root_directory, everything will work fine. You can use links in the fs_root_directory if you want to use directories outside it, e.g. /tmp or /home.

• kbd: Specify what keyboard type to use. This affects what type of a keyboard the CADR sees, not the actual keyboard layout from the host. Possible values are:

  • knight: Send Knight (old) keyboard scancodes. Keyboard layout
  • cadet: Send Space-Cadet (new) keyboard scancodes. Keyboard Layout, Front keys.

• grab_keyboard: If set to true, try to grab the keyboard.

• scale: Sets the scaling factor for the CADR display. NOTE: only works with the SDL2 backend. (default: 1.0)

• scale_filter: Sets the scaling filter for the CADR display. Avaliable values are nearest and linear. If you set the scaling factor to an integer value, the recommended scaling filter is nearest. NOTE: only works with the SDL2 backend. (default: linear)

• allow_resize: If set to true, allow the CADR window to be resized. NOTE: only works with the SDL2 backend. (default: false)

• icon_file: File to use for the application window. It must be a 32x32 pixel 256-color BMP image. RGB 255,0,255 is used for transparency. NOTE: only works with the SDL2 backend. (default: icon.bmp)

ucode section

• prommcr_filename: Specifies the boot PROM microcode load.

• promsym_filename: Specifies the symbol table for the boot PROM.

• mcrsym_filename: Specifies the symbol table for the microcode.

chaos section

• backend: Specifies which back-end to use; possible values are:

  • daemon: Tries to connect to the chaosd daemon.
  • local: Uses the embedded Chaosnet NCP.
  • udp: Uses Chaos-over-UDP to a Chaosnet bridge.
  • hybrid: Use a hybrid of "local" and "udp" - see udp_local_hybrid below.

• myname: Specifies the name of the simulated machine; this is used to figure out which Chaosnet address we have.

• servername: Specifies the name of the NCP; this is only used when the Chaosnet backend is local (or udp with the udp_local_hybrid option, see below).

• bridgeip: IP or host name of the Chaosnet bridge to use for Chaos-over-UDP.

• bridgeport: UDP port of the Chaosnet bridge (default 42042)

• bridgeport_local: Local UDP port to use for Chaos-over-UDP (default 42042).

• bridgechaos: Chaosnet address of the Chaosnet bridge (octal).

• udp_local_hybrid: Use a hybrid of "local" and "udp", where the address of servername is treated locally, but all others are handled over UDP. Requires udp backend and configuration of servername (and hosts).

• hosts: Hosts table containing hostname to Chaosnet address mappings. The format of this file is the same as for the Lisp Machine.

disk section

• disk0_filename, disk1_filename, disk2_filename, disk3_filename, disk4_filename, disk5_filename, disk6_filename, disk7_filename: Specify which disks drives are available.

trace section

• level: Specify trace level. See utrace.h for possible levels

• facilities: Specify what facilities to trace. See utrace.h for possible values.

idle section

• cycles: amount of cycles since last work to consider idle

• quantum: cycles to wait until sleep call

• timeout: timeout for each sleep cycle

kbd section

This maps X11 keys to a corresponding key in the simulator. The left-hand side is an X11 key name, the right-hand side is a Lisp Machine character name that will get inserted.

For example, to map a few host Fn-functions keys to provide access to keys that are not available on PC keyboards:

[kbd]
F1 = system
F2 = network
F3 = status
F4 = terminal
F5 = help
F6 = clear
F7 = break
F10 = hold_output
F11 = abort
F12 = resume

To insert the alpha character when pressing a key that is mapped to Alpha in X11:

Greek_alpha = alpha

kbd.modifiers section

This maps X11 modifiers to the corresponding bucky key in the simulator. The left-hand side is an X11 modifier name (Mod1, Mod2, ...), the right-hand side is a corresponding to a Lisp Machine bucky key.

Not all bucky keys are supported by all keyboard types. There is also no support currently to differentiate between left and right bucky keys.

Available modifier masks from X11 are: Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, Mod5.

Available bucky keys: Shift, Top, Control, Meta, ShiftLock.

Cadet specific bucky keys: ModeLock, Greek, Repeat, AltLock, Hyper, Super.

Simulator keyboard bindings

All keys have been mapped so that they should work mostly as advertised. Not all keys have been mapped to the host; e.g., Call or Altmode on the Knight.

X11 Modifier have been mapped as follows, depending on the type of Lisp Machine keyboard currently in use:

Some additional keys that are hard to type, or do not have a corresponding key on a normal PC keyboard have been mapped as well.

What programs are here?

• usim: MIT CADR simulator
• diskmaker: utility for managing disk packs

Debugging utilities:

• readmcr: microcode disassembler

Release History

v0.10 - TBD

v0.9 - Minor speedups. Mac OSX (little endian) fixes. Warm start support (usim.state). Mouse/microcode synchronisation (thanks to Devon for the idea)

v0.8 - Speedups and bug fixes. chaosd/FILE server supports rebuilding sources from server. Can now resize screen.

v0.7 - Added raw X11 support. Bjorn Victor's new keyboard configuration code. Diskmaker now takes a template file and will show info on existing disk images.

v0.6 - Better network support.

Standing on the shoulders of giants

I (Brad Parker) would like to thanks the following people for helping me on this, er, project:

• Tom Knight (TK)
• Howard Shrobe
• Richard Greenblatt (RG)
• Daniel Weinreb
• Al Kossow
• George Carrette
• Steve Krueger
• Alastair Bridgewater
• John Wroclawski
• Bjorn Victor
• Devon Sean McCullough

Without their support or encouragement I would probably not have done this. Certainly if Al had not sent me the PROM images I would never have started. And without Daniel's box-of-tapes I could never have succeeded. RG offered some good explanations when I was confused. TK and Howard were extremely supportive at the just right moment (and answered a lot of email). George offered many good suggestions and answered lots of questions. Steve helped me locate missing pages from "memo 528". Alastair did some amazing work on several Explorer emulators. Bjorn has used the code, offered many suggestions, fixes and improvements. And John's office is where I first saw a 3600 console and said, "what's that?".