Notes on the Lisp Machine

Table of Contents


1 Quick Debugging Tips

See the “Debugger Commands” in the manual for more details.

To enter debugger from an already running program hit M-BREAK (BREAK is bound to PgDn by default in usim).

C-b (and the more verbose M-b) show the back trace.

C-n and C-p can be used to navigate the back trace.

M-l will dump the current function in disassembled form.w

C-c and M-c will try and continue from the current frame.

C-e will open the file the function is associated with.

C-r will return a value from the current frame.

M-C-r will re-run the current frame with the same arguments.

1.1 Lisp Machine Debugger Cheat Sheet

 General information about using the debugger

   You are in the debugger.  If you don't want to debug this error, type <ABORT>.
   Otherwise you can evaluate expressions in the context of the error, examine
   the stack, and proceed//throw//return to recover.
     If you type in a Lisp form, it will be evaluated, and the results printed,
   using *READTABLE* and base *READ-BASE* in package *PACKAGE*. This
   evaluation uses the variable environment of the stack frame you are examining.
     Type <ABORT> or c-Z to get back to top level, or the previous debugger level.
   While in the debugger, c-G quits back to the debugger top level.
     If you think this error indicates a bug in the Lisp machine system, use the
   Control-M command.

 Various ways of obtaining information about the current stack frame

   c-L or <CLEAR SCREEN> clears screen and retypes error message.
   m-L clears screen and types args, locals and compiled code.
   c-B gives a backtrace of function names.
   c-m-B gives a backtrace of function names and argument names and values.
   m-B is line c-B but shows EVALs, PROGs, CONDs, etc.
   c-m-A prints an argument to the current function, and sets * to be that
      argument to let you do more complicated things with it.
      + is set to a locative to that argument, should you want to modify it.
      To specify which argument, type the argument number with Control
      or Meta held down before the c-m-A.
   c-m-L is like c-m-A but works on the function's locals rather than the args.
   c-m-V is like c-m-A but works on the values this frame is returning.
      (This is useful when you get a trap on exit from function).
   c-m-F does likewise for the function itself.
   c-A prints the arglist of the function in the current frame.
   m-S prints the value in this frame of a special variable you specify.
   c-m-S lists all special variable bindings in this frame.

   Use the functions (EH-ARG n), (EH-LOC n), (EH-VAL n) and (EH-FUN) to get the
   value of an arg, local, value or function-object respectively from an
   expression being evaluated. For args and locals, n can be a name or a number.
   EH-VAL allows numbers only. LOCF and SETF on those expressions are also allowed.

 Selecting Stack Frames to examine

   c-N or <LINE> goes down a frame, c-P or <RETURN> goes up.
   m-N and m-P are similar but show args, locals and compiled code.
   c-m-N and c-m-P are similar to c-N and c-P, but they show
      all the internal EVALs, PROGs, CONDs, etc. of interpreted code,
      and function calls whose args are still being computed.
   m-< and m-> go to the top and bottom of the stack, respectively.
   c-S reads a string and searches down the stack for a frame
      calling a function whose name contains that substring.

 Stepping though through the program

   c-X toggles the trap-on-exit flag for the current frame.
   m-X sets the trap-on-exit flag for the current frame and all outer frames.
   c-m-X clears this flag for the current frame and all outer frames.
   Trap on exit also occurs if the frame is thrown through.
   c-D proceeds like <resume>, but first sets the trap-on-next-function-call flag.
   m-D toggles the trap-on-next-function-call flag.
   Functions which get a trap on entry are automatically flagged for
   trap on exit as well.  You can un-flag them with c-X.

 Proceeding from this error and resuming execution

   c-Z aborts to previous debugger or other command loop, or to top level.
   c-R returns a value or values from the current frame.
   c-m-R offers to reinvoke the current frame with the same arguments
      originally supplied (as best as they can be determined).
   m-R offers to reinvoke the current frame, letting you alter
      some of the arguments, or use more or fewer arguments.
   c-T throws to a specific tag.

 Transferring to other systems: Edit, Bug report, Window-based Debugger

   c-E calls the editor to edit the current function.
   c-M enters the editor to send a bug message, and puts the error
     message and a backtrace into the message automatically.
     A numeric argument says how many stack frames to put in the backtrace.
   c-m-W switches to the window-based debugger.
  The 'Resume' (or 'Control-C') command is often synonymous with
'Super-A'.  But 'Resume' only proceeds, never aborts.  If there is no
way to proceed, just ways to abort, then 'Resume' does not do anything.

  'Meta-C' is similar to 'Control-C', but in the case of an unbound
variable or undefined function, actually 'setq's the variable or defines
the function, so that the error will not happen again.  'Control-C' (or
'Resume') provides a replacement value but does not actually change the
variable.  'Meta-C' proceeds using the proceed type ':store-new-value',
and is available only if that proceed type is provided.

2 Site Creation Notes

The System 78.48 distribution band has the following site configuration:

    ;;; -*- Mode: LISP; Package: SI; Base: 8 -*-
    
    (DEFCONST LISPM-SYS-PATHNAME-TRANSLATIONS
      '(("CC" ">LMCONS>")
        ("CHAOS" ">CHAOS>")
        ("DEMO" ">LMDEMO>")
        ("DISTRIBUTION" ">DISTRIBUTION>")
        ("FONTS" ">LMFONTS>")
        ("IO" ">LMIO>")
        ("IO1" ">LMIO1>")
        ("LMFS" ">LMFS>")
        ("LMSYM" ">LMSYM>")
        ("LMTAPE" ">LMTAPE>")
        ("PATCH" ">LMPAT>")
        ("PRESS-FONTS" ">FONTS>")
        ("SITE" ">LMSITE>")
        ("SYS" ">LISPM>")
        ("SYS2" ">LISPM2>")
        ("UBIN" ">LISPM1>")
        ("UCADR" ">LCADR>")
        ("WINDOW" ">LMWIN>")
        ("ZMAIL" ">ZMAIL>")
        ("ZWEI" ">ZWEI>")))
     
    (DEFSITE :DISTRIBUTION
      (:SITE-PRETTY-NAME "Distribution")
      (:SYS-HOST "DISTRIBUTION-LM1")
      (:SYS-DIRECTORY-TRANSLATIONS LISPM-SYS-PATHNAME-TRANSLATIONS)
      (:CHAOS T)
      (:TIMEZONE 5)
      (:ESC-F-ARG-ALIST '((NIL . :LOGIN)
    		          (1 . :LISP-MACHINES)
    		          (0 . :READ)))
      )

There seems to be no host table configured (SI:MACHINE-LOCATION-ALIST is NIL). When doing SETUP-MY-ADDRESS, if we fail to get a host address from GET-HOST-FROM-ADDRESS we will make a unnamed host and put it into SI:HOST-ALIST. At that point, SI:HOST-ALIST will contain:

    (("UNKNOWN" #<LISPM-CHAOS-HOST UNKNOWN> NIL LISPM DISTRIBUTION CHAOS (401)))

The function PRESET-FOR-DISTRIBUTION (see DISTRIBUTION; DIST LISP – Slimebolix) is used to setup a cold loaded system for distribution. This NILs HOST-ALIST, initailizes MACHINE-LOCATION-ALIST and cleans up some extra things. It also creates a new HOSTS TEXT file that contains DISTRIBUTION-LM1, copies LOCAL:>DISTRIBUTION>DISTRIBUTION>SITE.LISP etc to SITE; SITE LISP, etc. The function assumes that the following files exists, it also overwrites whatever is in LOCAL:>LMSITE:

  LOCAL:>DISTRIBUTION>DISTRIBUTION>SITE.LISP
  LOCAL:>DISTRIBUTION>DISTRIBUTION>HOSTS.TEXT ;This is created by the fucntion.
  LOCAL:>DISTRIBUTION>DISTRIBUTION>LMLOCS.LISP

CANON that is being refered in the Slimebolix DIST LISP is a system for "Canon LBP software".

In System 222 the scheme is slightly different, and handled during COLD initialization. The function SI:SAVE-FOR-DISTRIBUTION is called which sets up so that the band will clear any site specific information on COLD initialization.

SI:SAVE-FOR-DISTRIBUTION  
     Saves the current environment as a distribution world load; this is
     how distribution world loads are created.  It prints the disk label,
     prompts you for the name of partition, and does a DISK-SAVE into that
     partition.  As is usual with DISK-SAVE, when it is finished, the saved
     environment is restored, and so when SI:SAVE-FOR-DISTRIBUTION is
     finished, the machine is in a distribution world load environment.

3 Lisp Machine Glossary


4 Random Compiler Notes

Overal working of QC:


5 Serial SPY protocol notes

Serial SPY protocol (values are octal, as usual):

<ADDRESS>/		Read from address ADDRESS, used by DBG-READ.
<ADDRESS>:<VALUE>:	Write value VALUE to address ADDRESS, used by DBG-WRITE.
R			Read status, returns a octal number.
<N>S			Manipulates some kind of high serial bit.
<N>A			Set the baud rate of the UART, where N is one of:

	0: 50. baud
	1: 75. baud
	2: 110. baud
	4: 150. baud
	5: 300. baud
	6: 600. baud
	7: 1200. baud
	10: 1800. baud
	11: 2000. baud
	12: 2400. baud
	13: 3600. baud
	14: 4800. baud
	15: 7200. baud
	16: 9600. baud
	17: 19200. baud

<LOW>L<MIDDLE>M<HIGH>H0I	CC-EXECUTE-LOAD-DEBUG-IR
<LOW>L<MIDDLE>M<HIGH>H1I	CC-EXECUTE-R
<LOW>L<MIDDLE>M<HIGH>H7I	CC-EXECUTE-W

Error code:

#o7	ERRONEOUS COMMAND RECEIVED BY DEBUGGER
#o10	DEBUGGER GOT PARITY ERROR, RESETTING DEBUGGER; when getting this we type out #o33
#o15	Nothing.
;;; The following are the active locations:
;;; 766100  Reads or writes the debuggee-Unibus location addressed by the registers below.
;;; 766114  (Write only) Contains bits 1-16 of the debuggee-Unibus address
;;;	    to be accessed.  Bit 0 of the address is always zero.
;;; 766110  (Write only) Contains additional modifier bits, as follows.
;;;	    These bits are reset to zero when the debuggee's Unibus is reset.
;;;	    1  Bit 17 of the debuggee-Unibus address.
;;;	    2  Resets the debuggee's Unibus and bus interface.  Write a 1 here then write a 0.
;;;	    4  Timeout inhibit.  This turns off the NXM timeout for all Xbus and Unibus cycles
;;;	       done by the debuggee's bus interface (not just those by the debugger).
;;; 766104  (Read only) These contain the status for bus cycles executed on the debuggee's
;;;	    busses.  These bits are cleared by writing into location 766044 (Error Status)
;;;	    on the debuggee's Unibus.  They are not cleared by power up.
;;;	    1  Xbus NXM Error.  Set when an Xbus cycle times out for lack of response.
;;;	    2  Xbus Parity Error.  Set when an Xbus read receives a word with bad parity,
;;;	       and the Xbus ignore-parity line was not asserted.  Parity Error is also set
;;;	       by Xbus NXM Error.
;;;	    4  CADR Address Parity Error.  Set when an address received from the processor
;;;	       has bad parity.
;;;	   10  Unibus NXM Error.  Set when a Unibus cycle times out for lack of response.
;;;	   20  CADR Parity Error.  Set when data received from the processor has bad parity.
;;;	   40  Unibus Map Error.  Set when an attempt to perform an Xbus cycle through the
;;;	       Unibus map is refused because the map specifies invalid or write-protected.
;;;	   The remaining bits are random (not necessarily zero).

6 Notes on debugging in usim

6.1 Macrocode debug tracing

When tracing, the macro disassembler prints out the PC, this can be used to figure out where in the LOD:

        00012140044 054010 BR-NOT-NIL 12140055
        00012140046 040206 CALL D-PDL FEF|134
        00012140050 076060 PUSH-NUMBER 48
        00012140052 042143 MOVE D-PDL FEF|99
        00012140054 055324 (MISC) LENGTH D-PDL

E.g, for a load band from System 99:

   $ ~/l/usim/lod -p 00012140052 LOD
   %SYS-COM-AREA-ORIGIN-PNTR: 00000000400 03200004000 (0x1a000800)
   %SYS-COM-BAND-FORMAT: 00000000410 01200000000 (0x0a000000)
   %SYS-COM-POINTER-WIDTH: 00000000432 01200000031 (0x0a000019)
   %SYS-COM-MAJOR-VERSION: 00000000427 00600000000 (0x06000000)
   %SYS-COM-DESIRED-MICROCODE-VERSION: 00000000430 00600000000 (0x06000000)

   fef @ 12140052:

   pc 12140052, addr 2430012
[...]
    30602143675 31001656007 (0xc8075c07) 'LISP-REINITIALIZE'
   00002427411 31200400001 (0xca020001)
   00002427412 31220000000 (0xca400000)
[...]
   00002427771 23401056520 (0x9c045d50)

   00002427772 042401 MOVE D-PDL '401
   00002427772 173010 POP FEF|8
   00002427773 042160 MOVE D-PDL FEF|112
   00002427773 072403 EQ '403
   00002427774 034004 BR-NIL 2430001
   00002427774 073157 SET-NIL FEF|111
   00002427775 073156 SET-NIL FEF|110
   00002427775 073155 SET-NIL FEF|109
   00002427776 014011 BR 2430010
   00002427776 042160 MOVE D-PDL FEF|112
   00002427777 072404 EQ '404
   00002427777 034006 BR-NIL 2430006
   00002430000 075113 (MISC) %lambda-tv-quad-slot D-PDL
   00002430000 173157 POP FEF|111
   00002430001 075112 (MISC) %lambda-rg-quad-slot D-PDL
   00002430001 173156 POP FEF|110
   00002430002 075116 (MISC) %lambda-sdu-quad-slot D-PDL
   00002430002 173155 POP FEF|109
   00002430003 073154 SET-NIL FEF|108
   00002430003 073153 SET-NIL FEF|107
   00002430004 073152 SET-NIL FEF|106
   00002430004 073151 SET-NIL FEF|105
   00002430005 073150 SET-NIL FEF|104
   00002430005 073147 SET-NIL FEF|103
   00002430006 073146 SET-NIL FEF|102
   00002430006 073145 SET-NIL FEF|101
   00002430007 042205 MOVE D-PDL FEF|133
   00002430007 015576 (MISC) BOUNDP D-IGNORE
   00002430010 034002 BR-NIL 2430013
   00002430010 002144 MOVE D-IGNORE FEF|100
   00002430011 054010 BR-NOT-NIL 2430022
   00002430011 040206 CALL D-PDL FEF|134
   00002430012 076060 PUSH-NUMBER 48
   00002430012 042143 MOVE D-PDL FEF|99
   00002430013 055324 (MISC) LENGTH D-PDL
   00002430013 031777 + PDL|511 (undefined)
   00002430014 042207 MOVE D-PDL FEF|135
   00002430014 142142 MOVE D-LAST FEF|98
   00002430015 173144 POP FEF|100
[...]

7 Notes on Clock Domains in the MIT CADR (FPGA)

Notes based on the Pipistrello implementation


8 Notes on the inner Lisp Machine System (version 99 / MIT CADR)

These variables are defined in SYS: SYS; SYSDCL LISP.

File loaded into the cold load are defined by COLD-LOAD-FILE-LIST:

        SYS: FONTS; CPTFON QFASL
        SYS: SYS; QRAND QFASL
        SYS: SYS; FSPEC QFASL
        SYS: IO; QIO QFASL
        SYS: IO; RDTBL QFASL	-- done specially
        SYS: IO; CRDTBL QFASL	-- done specially
        SYS: IO; READ QFASL
        SYS: IO; PRINT QFASL
        SYS: WINDOW; COLD QFASL
        SYS: SYS; SGFCTN QFASL
        SYS: SYS; EVAL QFASL
        SYS: SYS; TYPES QFASL
        SYS: SYS; LTOP QFASL
        SYS: SYS; QFASL QFASL
        SYS: IO; MINI QFASL
        SYS: SYS; QFCTNS QFASL
        SYS: SYS2; STRING QFASL
        SYS: SYS2; CHARACTER QFASL
        SYS: SYS; CLPACK QFASL
        SYS: COLD; GLOBAL QFASL
        SYS: COLD; SYSTEM QFASL
        SYS: COLD; LISP QFASL

When booting (cold, or warm) we call LISP-TOP-LEVEL.

When doing QLD files listed in MINI-FILE-ALIST-LIST get loaded into the running system over MINI:

        INNER-SYSTEM-FILE-ALIST
                SYS: SYS2; DEFSEL QFASL		-- By (resource named-structure-invoke)
                SYS: SYS2; RESOUR QFASL		-- By FILLARRAY
                SYS: SYS; QMISC QFASL
                SYS: SYS; SORT QFASL		-- Needed by FLAVOR
                SYS: IO; FORMAT QFASL		-- ditto
                SYS: IO1; FQUERY QFASL		-- Needed by everything in sight
                SYS: SYS2; HASH QFASL		-- Needed by FLAVOR,PATHNM
                SYS: SYS2; FLAVOR QFASL		-- Needed by PROCES
                SYS: SYS2; HASHFL QFASL		-- Make flavors really work.
                SYS: SYS2; PRODEF QFASL		-- Definitions for PROCES
                SYS: SYS2; PROCES QFASL
                SYS: SYS2; NUMER QFASL		-- SI:EXPT-HARD needed by PROCES
                SYS: EH; EH QFASL
                SYS: EH; EHF QFASL
                SYS: EH; EHC QFASL
                SYS: EH; EHBPT QFASL
                SYS: SYS2; DISASS QFASL		-- EH calls subroutines in DISASS
                SYS: SYS2; DESCRIBE QFASL	-- For hack value
                SYS: IO; DISK QFASL
                SYS: SYS2; LOGIN QFASL		-- ditto
                SYS: IO; RDDEFS QFASL		-- Load this before trying to read any #\'s
                SYS: NETWORK; HOST QFASL
                SYS: NETWORK; PACKAGE QFASL
                SYS: IO; FILE; ACCESS QFASL
                SYS: IO; STREAM QFASL		-- Probably needed by any file system
                -- PATHNM must be the last file in this list.  It
                -- breaks things while cold loading that QLD knows how
                -- to fix after this alist is loaded.
                SYS: IO; FILE; PATHNM QFASL

        REST-OF-PATHNAMES-FILE-ALIST
                SYS: IO; FILE; PATHST QFASL
                SYS: IO; FILE; LOGICAL QFASL
                SYS: FILE2; PATHNM QFASL
                SYS: FILE; LMPARS QFASL
                SYS: IO; FILE; OPEN QFASL
                SYS: NETWORK; CHAOS; CHSNCP QFASL
                SYS: NETWORK; CHAOS; CHUSE QFASL
                SYS: NETWORK; CHAOS; QFILE QFASL

        ETHERNET-FILE-ALIST
                SYS: IO; SIMPLE-ETHER QFASL
                SYS: IO; ADDR-RES QFASL

        SITE-FILE-ALIST
                SYS: SITE; SITE QFASL

        HOST-TABLE-FILE-ALIST
                SYS: SITE; HSTTBL QFASL
                SYS: SITE; LMLOCS QFASL

Then, SYSTEM-SYSTEM-FILE-ALIST is loaded:

        SYS: SYS2; MAKSYS QFASL
        SYS: SYS2; PATCH QFASL
        SYS: SYS; SYSDCL QFASL

At this point, QLD will do MAKE-SYSTEM on SYSTEM to load the rest of the Lisp Machine system. And we are done.


9 Notes on confusion or discrepancies in MIT AI Memo 528

This was written by Brad Parker, around 10/17/04.

While writing a CADR emulator I ran into some issues and/or discrepancies in the available documentation. I’ve tried to list them here.

[These are my conclusions; If you read them and disagree, please send me email and set me straight. I do not have a functional hardware description (i.e. verilog) yet, so some things are assuptions based on quick scans of the schematics]

First, let me quote from "lmdocs: popj.2", a document which I found illuminating.

POPJ-AFTER-NEXT in combination with JUMP and DISPATCH			[CONTRL]

Dispatch	R	P	N	PC	SPC	NOP
                0	0	0	jump	pop	no
                0	0	1	jump	pop	yes
                0	1	0	jump	push	no
                0	1	1	jump	push	yes
                1	0	0	popj	pop	no
                1	0	1	popj	pop	yes
                1	1	0	popj	pop	no
                1	1	1	popj	pop	yes

Jump		R	P	N	PC	SPC	NOP
(cond		0	0	0	jump	pop	no
 satisfied)	0	0	1	jump	pop	yes
                0	1	0	jump	push	no
                0	1	1	jump	push	yes
                1	0	0	popj	pop	no
                1	0	1	popj	pop	yes
                1	1	0	iwrite
                1	1	1	iwrite

Jump with condition not satisfied is similar to ALU and BYTE instructions.

Possible mods to increase usefulness:

A dispatch-call or jump-call in combination with popj-after-next should neither popj nor pushj but just jump. If it’s xct-next the right thing happens. If the next instruction is inhibited, well that’s OK. However, if the next instruction is not inhibited, and it’s a CALL, normally (without the previous call) would be like tail recursive, but here will end up with two return addresses on pdl, however, the top one is the address of the place called in the first instruction and the one under that is the original return so that’s right too.

Dispatch example - POPJ+DISPATCH, enumerating cases

001 LABEL	(CHECK-PAGE-READ)
002	(POPJ-AFTER-NEXT DISPATCH TRANSPORT READ-MEMORY-DATA) ;FOLLOW ALL INVZ
003       ((M-T) Q-TYPED-POINTER READ-MEMORY-DATA)	;RETURN C(E) IN M-T
004
005
dispatch yields N=0,P=0,R=0

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/alu
   new pc<- dispatch address
   (disable popj)
- exec alu                              fetch new pc (dispatch address)

dispatch yields N=0,P=0,R=1

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/alu
   new pc <- spc[spc-ptr--]
   (disable popj)
- exec alu                              fetch new pc (from stack)

dispatch yields N=0,P=1,R=0

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/alu
   spc[++spc-ptr] <- 004
   new pc <- dispatch address
   (disable popj)
- exec alu                              fetch new pc (dispatch address)

dispatch yields N=0,P=1,R=1

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/alu
   ignore dispatch, do popj
   new pc <- spc[spc-ptr--]
   if pc14, advance-lc
- exec alu                              fetch new pc

dispatch yields N=1,P=0,R=0

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/alu
   new pc<- dispatch address
   (disable popj)
- (nop - pipe flush)                    fetch new pc

dispatch yields N=1,P=0,R=1

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/alu
   new pc <- spc[spc-ptr--]
   if pc14, advance-lc
   (disable popj)
- (nop - pipe flush)                    fetch new pc

dispatch yields N=1,P=1,R=0

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/alu
   spc[++spc-ptr] <- 005
   new pc <- dispatch address
   (disable popj)
- exec alu                              fetch new pc

Another Dispatch example - POPJ+DISPATCH with CALL, enumerating cases

001 LABEL	(CHECK-PAGE-READ)
002	(POPJ-AFTER-NEXT DISPATCH TRANSPORT READ-MEMORY-DATA) ;FOLLOW ALL INVZ
003     (CALL-XCT-NEXT FUNC)
004
005
dispatch yields N=0,P=0,R=0

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/call
   new pc<- dispatch address
   (disable popj)
- exec call                             fetch new pc (dispatch address)
   spc[++spc-ptr] <- new pc+1
   new pc<- call address
- exec 1st inst @ dispatch address	fetch call address
- exec 1st inst @ call address

[help! I'm confused here. I don't think the action above is correct.
When the call returns it will return to new pc + 1...]

dispatch yields N=0,P=0,R=1

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/call
   new pc <- spc[spc-ptr--]
   (disable popj)
- exec call                             fetch new pc (from stack)
   spc[++spc-ptr] <- new pc+1
   new pc<- call address
- exec 1st inst @ new pc		fetch call address
- exec 1st inst @ call address

[again; I don't think the action above is correct.  When the call
returns it will return to new pc + 1...]

dispatch yields N=0,P=1,R=0a

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/call
   spc[++spc-ptr] <- 004
   new pc <- dispatch address
   (disable popj)
- exec call                             fetch new pc (dispatch address)
   spc[++spc-ptr] <- new pc+1
   new pc<- call address
- exec 1st inst @ dispatch address	fetch call address
- exec 1st inst @ call address

dispatch yields N=0,P=1,R=1

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/call
   ignore dispatch, do popj
   new pc <- spc[spc-ptr--]
   if pc14, advance-lc
- exec call                             fetch new pc (from stack)
   spc[++spc-ptr] <- new pc+1
   new pc<- call address
- exec 1st inst @ new pc		fetch call address
- exec 1st inst @ call address

dispatch yields N=1,P=0,R=0

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/call
   new pc<- dispatch address
   (disable popj)
- (nop - pipe flush)                    fetch new pc (dispatch address)
- exec 1st inst @ new pc		fetch new pc+1

dispatch yields N=1,P=0,R=1

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/call
   new pc <- spc[spc-ptr--]
   if pc14, advance-lc
   (disable popj)
- (nop - pipe flush)                    fetch new pc (from stack)
- exec 1st inst @ new pc		fetch new pc+1

dispatch yields N=1,P=1,R=0

- exec check-page-read jump		fetch 002/popj
- exec popj + dispatch			fetch 003/call
   spc[++spc-ptr] <- 005
   new pc <- dispatch address
   (disable popj)
- exec call                             fetch new pc (dispatch address)
   spc[++spc-ptr] <- dispatch address+1
   new pc<- call address
- exec 1st inst @ new pc		fetch call address
- exec 1st inst @ call address

Another Dispatch example - with CALL, enumerating cases

001	(NOP)
002	(DISPATCH TRANSPORT READ-MEMORY-DATA) ;FOLLOW ALL INVZ
003     (CALL FUNC)
004
005
dispatch yields N=0,P=0,R=0

- exec check-page-read jump		fetch 002/dispatch
- exec dispatch				fetch 003/call
   new pc <- dispatch address
- exec call w/n-bit			fetch new pc (dispatch address)
   spc[++spc-ptr] <- new pc+1
   new pc<- call address
- (nop - pipe flush)			fetch call address
- exec 1nd inst @ call address

The call pushes the dispatch address + 1 and the pipe stalls because the call has the N bit set, followed by the 1st instruction at the call address.


10 TAGS database

For creating a TAGS database that also contains DEFMETHOD mixins for :BEFORE or :AFTER, one can pass the following to etags:

    -r "/(defmethod ([A-Z-_ \t(]+\(:BEFORE\|:AFTER\)?[ \t]+:\([A-Z-]+\)/\2/i"

11 CADR HDL Internals

*** TO BE WRITTEN ***

12 Internal Implementation Stuff (Lisp Machine chapter)

The following chapters are intended to be merged into the Lisp Machine Manual when they have been written.

12.1 Bootstrap loading

*** TO BE WRITTEN ***

12.2 Lisp Machine Storage

This section describes the format in which objects are stored in the Lisp Machine.

*** TO BE WRITTEN ***
	----------------------------------------------------------------
	| 2 |1|    5    |                    24                        |
	----------------------------------------------------------------
          |  |       |                          |
CDR CODE--|  |       |                          |
USER CONTROL-|       |                          |
                     |                          |
DATA TYPE------------|                          |
POINTER-----------------------------------------|

12.2.1 DTP-TRAP

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.2 DTP-NULL

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.3 DTP-FREE

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.4 DTP-SYMBOL

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.5 DTP-SYMBOL-HEADER

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.6 DTP-FIX

	----------------------------------------------------------------
	|                              24                              |
	----------------------------------------------------------------
                                        |
                                        |
                                        |
                                        |
                                        |
VALUE OF FIXNUM-------------------------|

12.2.7 DTP-EXTENDED-NUMBER

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.8 DTP-HEADER

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.9 DTP-GC-FORWARD

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.10 DTP-EXTERNAL-VALUE-CELL-POINTER

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.11 DTP-ONE-Q-FORWARD

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.12 DTP-HEADER-FORWARD

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.13 DTP-BODY-FORWARD

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.14 DTP-LOCATIVE

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.15 DTP-LIST

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.16 DTP-U-ENTRY

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.17 DTP-FEF-POINTER

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.18 DTP-ARRAY-POINTER

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.19 DTP-ARRAY-HEADER

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.20 DTP-STACK-GROUP

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.21 DTP-CLOSURE

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.22 DTP-SMALL-FLONUM

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.23 DTP-SELECT-METHOD

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.24 DTP-INSTANCE

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.25 DTP-INSTANCE-HEADER

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.26 DTP-ENTITY

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.2.27 DTP-STACK-CLOSURE

	----------------------------------------------------------------
	|                                                              |
	----------------------------------------------------------------

12.3 Areas and Regions

12.4 The Lisp Machine Macro-instruction Set

This section describes the Lisp Machine’s interpreted order code, referred to below as "macrocode." The macrocode is designed to be highly bit-efficient, and well-suited to Lisp. The compilation of Lisp into macrocode is very straightforward, as will be shown in examples below.

*** TO BE WRITTEN ***

12.5 QFASL format

*** TO BE WRITTEN ***
[When written, move this under “Analyzing QFASL Files”]

12.6 Paging internals

*** TO BE WRITTEN ***
[When written, move this under “The Paging System”]

13 Right way to create a clean load band

29-Oct-83 11:21:24-CDT,1900;000000000000
Return-Path: <@MIT-MC:rsl@SPA-NIMBUS>
Received: from MIT-MC by UTEXAS-20.ARPA with TCP; Tue 25 Oct 83 15:19:04-CDT
Received: from SPA-RUSSIAN by SPA-Nimbus with CHAOS; Tue 25-Oct-83 13:24:02-PST
Date: Tuesday, 25 October 1983, 13:23-PST
From: Richard Lamson <rsl at SPA-NIMBUS>
Subject: pathname defaulting
To: Jonathan Slocum <LRC.Slocum at UTEXAS-20 at mc>,
    cmp.cohen at UTEXAS-20 at mc, HOSS at SCRC-TENEX
Cc: slug at UTEXAS-20 at mc
In-reply-to: The message of 25 Oct 83 07:42-PST from Jonathan Slocum <LRC.Slocum at UTEXAS-20>

    Date: Tue 25 Oct 83 10:42:44-CDT
    From: Jonathan Slocum <LRC.Slocum@UTEXAS-20.ARPA>
 ....
    What do you think -- is this a bug, or a feature?  The way things are arranged
    now, it is not safe to reconfigure a configured band that one has used the
    editor in [for example], since all sorts of old pathnames start getting saved
    away for future use.  Beware...

As documented in the Lisp Machine manual on page 424, the "right" way to
create a world is to do as little as possible in it before saving it.
That is, you should not use the editor, the File System Editor, Peek,
etc.  Please read the last paragraph on that page for (slightly)
incorrect information but sound advice.

You should do something which looks like this:

   <cold boot>
   (login "whoever" T)	; don't load an init file -- makes your world dirtier
   (make-system ...)	; load whatever things you want in your world
or (load ...)		; repeat for each file you want loaded
   (si:update-site-configuration-info)
                        ; only if the site information has changed
   (si:full-gc)		; optional -- makes the world somewhat smaller.
   (disk-save ...)	; save it away

Although it says to use the function PRINT-DISK-LABEL, I try to do that
before cold booting, so even the little garbage that function generates
is not present in the saved world.

14 Notes on using LOCAL-FILE

Load the local file system:

	(MAKE-SYSTEM 'LOCAL-FILE)

If doing this is the first time (this only needs to be done once):

Good idea to do DISK-SAVE at this point.

To create a directory, e.g., your home directory:

(CREATE-DIRECTORY "LM:AMS;")

To edit your Lisp Machine login file:

(ed "LM:AMS;LISPM.INIT"

Start DIRED in the root directory:

(dired "LM:<>")		  ; 

See the Lisp Machine Manual for more file system operations.

The file SYS:FILE;FSDOC TEXT documents some aspects of the local file system.

14.1 Lisp Machine file name syntax

Lisp Machine file name syntax (from FSDOC.TEXT):

HOST: DEVICE: DIRECTORY; FILENAME.TYPE#VERSION

The DEVICE field has no meaning. The DIRECTORY field is actually

  [DIRECTORY[.SUBDIRECTORY[.SUBDIRECTORY[...]]]]

The order of the fields is not important:

"LM: DLA; FOO.LISP"
"LM: DLA; FOO#<"
"DLA;.LISP"
"#4"
".LISP FOO DLA;#4 LM:"

The host LM always refers to the Local Machine.

VERSION can be one of the following tokens:

  >          Newest.  Same meaning as ITS.
  <          Oldest.  Same meaning as ITS.
  0          Newest.  On output, this will not create a new file if one already
             exists, rather, it will overwrite the existing newest version.
  *          Wild.  Same meaning as ITS.
  (absent)   Unspecific.  This is the same as > unless there are wildcard characters
             elsewhere in the name and type.  In that case, it is identical to *.
  n or +n    Refers to a specific version, as on ITS.
  -n         Refers to the version NEWEST minus n.

14.2 Copying files to and from Lisp Machine

To copy files use the COPY-FILE function.

;; Copy lispm.init from host to LispM.
(copy-file "oz://home//ams//lispm.init" "lm:ams;lispm.init")

;; Copies all files in LM:AMS; to OZ:/tmp.
(copy-file "lm:ams;*.*#*" "oz://tmp") 


15 Working with gore...

If modifying the following (anything under DEFS in SYSTEM-INTERNALS):

  1. SYS: SYS2; PRODEF
  2. SYS: IO; RDDEFS
  3. SYS: SYS2; SGDEFS
  4. SYS: SYS2; NUMDEF

Recompile everything. To incrementally test this do:

(RECOMPILE-COLD-LOAD-FILES)

Make a new COLD load band, and check that everything works.

(RECOMPILE-MINI-FILES)

See if the system loads.

(NEW-SYSTEM T)

And then MAKE-COLD, QLD, DISK-SAVE.

If just modifying some of the cold load files, or MINI file

(CHECK-COLD-LOAD-FILES)

or

(CHECK-MINI-FILES)

as suitable.


16 Lisp Machine Hackers

GAB
AKR	Alex Krymm
ALR	Andrew L. Ressler
DULCEY	Mark J. Dulcey
ELISHA	Elisha Sacks
FILECOMPUTER
HDT	Howard D. Trachtman
JGB	Jonathan G. Bliss
LISPM	A Default User
LMFILE	Use by @code{FILE-COMPUTER} as a default user.
MLY	Richard Mlynarik
MUSE	Tom Cloney
PGS	Patrick G. Sobalvarro
RAMESH	Ramesh S. Patil
RLK	Robert L. Krawitz
RMS	Richard M. Stallman
RPK	Robert P. Krajewski
STRAZ	Steve Strassmann
SUNDAR	Sundar Narasimhan
TIM	Tim McNerney
ADS	Sathya D.Narayanan
KAB	Kim A. Barrett
PHILIP	Philippe Brou
RG	Richard Greenblatt
SAZ	David M. J. Saslav