LAMBDADELTA README

  LambdaDelta is an emulator of the LMI Lambda Lisp Machine. Its goal is to
  simulate the hardware sufficiently to run original microcode and binaries
  unmodified, with performance and capability comparable to the original
  hardware.

  LambdaDelta is written in C. It is intended to be portable to any reasonably
  Unix-like operating system, but is developed primarily on Linux. The initial
  versions will most likely fail to compile elsewhere, but attempts will be
  made to rectify this as soon as practical.

  SDL Version 1 or 2 is used for console IO, the Linux tuntap driver or
  Berkeley Packet Filter is used for network IO, and standard Unix file
  operations are used for disk and tape IO. LambdaDelta includes code from the
  Fake86 project by Mike Chambers in its SDU implementation.

  LambdaDelta is licensed under the GNU GPL Version 2 or later at your option.
  Please see the file COPYING for details.

PREREQUISITES

  LambdaDelta requires a set of ROM images from a physical Lambda, and
  either a disk image of an installed system or images of the installation
  and source tapes. At the time of release, these items are available from
  Bitsavers. See http://www.bitsavers.org/ for more information.

  A prototype Release 5.0 system software distribution is available at 
  https://s3.us-east-2.amazonaws.com/ds.storage.0000/Lambda-Release5.tar.gz
  A Github repository has been set up to track issues and changes for this
  release, see https://github.com/dseagrav/Lambda-system-software

CONTACT

  Questions, ideas, problems, solutions, praise, complaints, or baseless
  accusations may be directed to the LispM mailing list on tunes.org.
  See http://lists.tunes.org/mailman/listinfo/lispm/ for more information.

  All contributors to this project are listed in the AUTHORS file.

ABOUT THE LAMBDA

  The LMI Lambda is a NuBus-based machine consisting of at least one Lambda
  processor, a System Diagnostic Unit, and various NuBus and Multibus
  peripherals. The System Diagnostic Unit has an Intel 8088 processor, and is
  responsible for bootstrapping the Lambda processor. The Lambda processor is
  made up of four cards in a specially wired area of the NuBus backplane.
  The standard Multibus peripherals are a 3Com ethernet interface, an
  Interphase SMD disk controller, a Tapemaster 9-track tape controller,
  and a Quarterback QIC tape controller (not emulated). The SDU software 
  mediates sharing of Multibus peripherals. The SDU hardware provides a
  DMA path between Multibus space and NuBus space with mapping hardware
  for routing pages between targets on both busses.

  The NuBus peripherals are memory and the VCMEM console controller. There
  must be one VCMEM for each Lambda processor. The standard configuration
  has one pair. An optional configuration called LAMBDA-2x2 has two pairs.
  This enables two simultaneous and separate Lisp environments to share one
  backplane, memory, disk, and network interface. The result was a
  considerable cost savings over buying a second machine. The 2x2 machine
  was also used for operating system development.

  There was also an optional 68000-based Unix processor which could run
  V7 or SVR4. No attempt was made to emulate this. A configuration with a
  Unix processor was given the suffix "plus", making a "LAMBDA-PLUS"
  (or "LAMBDA+") a single-user Lambda with a Unix processor and a 
  "LAMBDA-2X2-PLUS" a two-user Lambda with a Unix processor.

CONFIGURING LAMBDADELTA

  LambdaDelta uses the GNU auto* tools for configuration and compilation.
  Most features and libraries should be configured automatically.

  If your system has both SDL1 and SDL2, you will be required to disable
  the one you do not want. (use --without-SDLx). SDL1 seems to perform
  better over remote X11 connections, but SDL2 has better performance
  when running locally.

  If you wish to emulate the optional 2x2 configuration, run configure
  with the option "--enable-config-2x2=yes"

  After compilation, run-time options are controlled by a configuration
  file named "ld.conf". An example configuration is provided in the
  examples directory. Each line of the configuration file has a keyword
  followed by a number of parameters. The following are the supported
  keywords and their parameters:

  ether_iface IFACE
  Causes the ethernet interface to be bound to the specified interface.
  For tuntap, this is the name of the tuntap device to use.
  For BPF, this is the interface the BPF interface will be bound to.
  As this is used for the passing of raw frames, it must be a wired
  Ethernet interface (or something emulating one) - A wireless interface
  will not work. The default is "ldtap".

  ether_addr MAC-ADDRESS
  Sets the MAC address used by the Lambda. This must be unique on your
  LAN, so do not make it the same as the host! It is written in the
  canonical colon-separated hex format.
  The default is 00:02:9C:55:89:C6.

  disk N FNAME
  Sets the image file for disk unit N. The given FNAME must exist.
  The geometry of the disk is determined by settings in the SDU.
  The default is that unit 0 is disks/disk.img and all other units
  are absent.

  sdu_switch N
  Sets the position of the SDU's rotary switch. N is a single hex digit 0-F.
  Position 0 is used for initial software installation or recovery.
  Position 1 is the standard configuration. The other positions operate as
  determined by the SDU configuration. If the position is not 1, LambdaDelta
  will wait for a telnet connection on port 3637 after startup. This simulates
  a terminal connected to the SDU's serial port. 
  The default is 0.

  mouse_mode N
  Sets the operation mode of the mouse emulation. In mode 0, the mouse
  protocol is emulated directly using SDL relative mouse movement data.
  The lisp mouse pointer moves independently of the host mouse pointer,
  and movement may be difficult or unpredictable on some platforms.
  In mode 1, the position of the host's mouse pointer is written
  directly into the Lambda processor's memory, causing the mouse pointer
  to remain in sync with the host but requiring knowledge of the offsets
  at which the pointer data resides. For more information, see the usage
  instructions later in this document.
  The default is 1.

  mouse_x_loc_0 N
  mouse_y_loc_0 N
  mouse_wake_loc_0 N
  mouse_x_loc_1 N
  mouse_y_loc_1 N
  mouse_wake_loc_1 N
  Sets the memory offsets used for mouse operation mode 1. The 0 or 1
  indicates Lambda 0 or Lambda 1. N is an octal offset into A-memory. The
  offsets are for the X coordinate, the Y coordinate, and the mouse updation
  flag. You should only have to modify this if you modify the microcode.
  The defaults are 0156, 0157, and 0170 for both processors.

  pixel_on 0xVVVVVVVV
  pixel_off 0xVVVVVVVV
  Sets the pixel values used for on and off. The standard pixel format is
  AARRGGBB where AA is Alpha, RR is Red, GG is Green, BB is Blue. The default
  pixel values are 0xFFFFFFFF for on and 0x00000000 for off.

  sdl_quit STATE
  Enables or disables handling of the platform-specific SDL_QUIT event.
  (Alt-F4,Command-Q,etc.) STATE is one of on,off,yes,no,true,or false.
  The default is enabled.

  map_key HV LV
  Maps host key HV to Lambda key LV.
  HV is a decimal SDL key code, LV is an octal Lambda key code.
  See the KEYCODES file in the doc directory for a list of Lambda key codes.
  See the SDL documentation for your SDL version to find the SDL key codes.
  SDL1 codes start with SDLK_ and SDL2 codes start with SDL_SCANCODE_.
  The default keymap is described later in this document.

USING LAMBDADELTA

  While the program is running, the window title bar has the following form:

    LambdaDelta: VC N | Tape: FNAME | STATUS | DT X

  N is the number of the active console, either 0 or 1. N is always zero when
  the 2x2 configuration is not in use. FNAME is the name of the active tape
  image file. STATUS is a string describing the state of the Lambda processor
  associated with this console. The strings have the following meanings:

    Cold Halted	= The processor has been powered on and has no state.
    Cold Running = The halt flag is clear but the state is unknown.
    Cold Booting = The bootstrap is running.
    Lisp Boot Halted = The processor halted while Lisp was initializing.
    	      	       This is an error condition.
    Lisp Booting = Lisp is initializing or warm booting.
    Running = Lisp is running.
    Halted = Lisp has stopped running. The processor has valid state.
             If you did not halt lisp, this is an error condition.

  After the status string is the time offset. X is a number in deciseconds
  which indicates how far apart real time and the emulator's time are.
  The emulator will try to hold this number at 0, but if your computer is
  not fast enough to run the emulator in real time this number will become
  negative and decrease further as the times diverge. If the number becomes
  positive and increases, the throttle is not operating properly. This is a
  bug which should be reported.

  The following keys control emulator functions are cannot be remapped:

  F9 switches the active console if the 2x2 configuration is enabled.
    If the standard configuration is in use, F9 may be remapped.
  F10 changes mouse operation according to the configured mouse mode.
    In mode 0, F10 toggles capture and release of the mouse pointer. Clicking
    inside the LambdaDelta window while the mouse is not captured will
    recapture it.
    In mode 1, F10 toggles visibility of the host mouse pointer.

  F11 simulates the "return to newboot" keyboard chord, which terminates Lisp
    and recalls the Newboot interface. Limitations of the keyboard emulation
    make typing the actual chord fail, so this directly sends the expected
    sequence of bytes to make things happen.

  F12 causes the active tape image file to rotate to the next file in
    ASCIIbetical order. Pressing control and F12 at the same time causes
    the emulator to dump its state into a bunch of .DUMP files. These files
    are human-readable but not necessarily human-understandable. (Is is our
    understanding that whether or not the developers are classified as human
    is a subject of ongoing debate.)

  All other keys on the keyboard may be remapped using the map_key option
  described above. The standard mapping preserves the printed key label
  of the standard typewriter keys. The other keys are mapped as follows:

    HOST KEY	  LAMBDA KEY 	   NOTES
    [	 	  (	 	   [ is the shift state, ( is unshifted
    ]		  )		   ] is the shift state, ) is unshifted
    RETURN	  ENTER
    BACKSPACE	  RUBOUT
    UP		  HAND UP	   
    DOWN	  HAND DOWN
    LEFT	  HAND LEFT
    RIGHT	  HAND RIGHT

    PAGE UP	  ABORT
    PAGE DOWN	  RESUME

    F1	 	  SYSTEM
    F2		  NETWORK
    F3		  STATUS
    F4		  TERMINAL
    F5		  HELP
    F6		  CLEAR
    F7		  BREAK

    RIGHT CTRL	  LEFT GREEK
    RIGHT ALT	  LEFT SUPER
    LEFT ALT	  LEFT META
    
    RIGHT FLAG	  RIGHT SUPER	   Does not always work on some platforms
    LEFT FLAG	  LEFT SUPER	   Does not always work on some platforms
    MENU 	  RIGHT HYPER

  The default keymap is still under development and is subject to change. Feel
  free to make suggestions or comments.

PREPARING ROM IMAGES

  The ROM images go in the "roms" subdirectory. The necessary files are:

  SDU.ROM - The SDU's 8088 program ROM. 64K, merged from two chips on the
  	  board. Bitsavers has one with a MD5 checksum of 
	  4795bf46168808d32012213c0b370f30

  MEM.ROM - The nubus-space configuration ROM for a memory card. 2K.
  	  Bitsavers has two, their MD5 checksums are
	  21089f3b4082548865f8cda6017f302e or 1f898d018a2e2ab29279ecf00c7a4c82.
	  Either one may be used, but the same one will be used for both cards
	  simulated.

  VCMEM.ROM - The VCMEM's nubus-space configuration ROM. 2K. This contains 8088
  	  program code that will be run by the SDU. The one on Bitsavers has
	  a MD5 checksum of 0e53416a49294f02c7fd925c9de47f5a.

  These can be found in zip files on the PDFs side of Bitsavers.

MICROCODE SYMBOL FILES

  In the lisp source tree there are files named bootstrap.lam-uload and 
  ulambda.lmc-sym which correspond to the Lambda bootstrap code downloaded
  by the SDU and the Lisp microcode. Place these in the LambdaDelta directory
  to provide symbols for debugging. These are optional.

INSTALLING A NEW MACHINE

  1) Prepare your config file, ROM images, tape images, and create the disk
     image file. Ensure the SDU switch setting is zero in your configuration.

  2) Start the emulator. Telnet to port 3637 on the host. The emulator should
     start, and you should have a SDU prompt in your telnet session.

     Ignore the graphical console for the now - It is inoperative until
     the SDU firmware partition is loaded and the CMOS contents are valid.

  3) Type "init" and push enter to initialize the busses and SDU. The SDU will
     reboot.

  4) Ensure the install tape is the active tape.

  5) Give the SDU command "/tar/setup clear eagle sp shell". Your CMOS should
     be initialized.

  6) Give the SDU command "/tar/load" and follow the prompts.

  7) When the "load >" prompt appears, give the command "install" and follow
     the prompts.

  8) Give the command "q" to return to the SDU

  9) Close the emulator by closing its window

  10) Edit your ld.conf file, change the SDU switch setting to 1

  11) Restart the emulator. You should get a SDU prompt on the console.

  12) Give the "config" command to initialize the Lambda configuration.
      When asked if you want to change anything, type y and press enter.

  13) At the cmd: prompt, give the command "lambda".

  14) At the "lambda cmd:" prompt, give the command "switches"

  15) At the "->" prompt, give the command "set use_multiplier"

  16) Push enter to return to the lambda command level.

  17) Give the command "x" until config reboots the SDU.

  18) At this point your machine is configured and you can save backups of your
      ld.conf, disk image, and CMOS image file.

  19) At the SDU prompt, give the command "newboot" to bring up the
      bootstrap program.

  20) At the "Command:" prompt, give the command "boot" to start lisp.

  21) When the REPL arrives, evaluate (si:set-pack-name "LAMBDA-A") to set
      the host name.

  22) Evaluate (si:%halt) to halt Lisp.

  23) When Lisp halts, press F11 to summon Newboot again

  24) At the "Command:" prompt, give the boot command to cold-boot Lisp.

  25) When the REPL arrives, evaluate (fs:initialize-file-system) to 
      format the LMFS. Answer "Yes" when prompted for confirmation.

  26) Push F12 to switch tapes to your distribution tape, if you have one.

  27) Type System-B to summon the Backup activity.

  At this point you can follow the instructions included with the
  distribution tape. If it is a backup tape, simply restore it. If it is
  an actual distribution tape, it may have special loading procedures.