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.