-*- Mode:Text -*-
Started: 21-Feb-86 
Last updated: 21-Feb-86 by Pace

Here are some quick notes on the incremental micro assembler:

I know it works in system 110, and will probably do ok in previous
versions.

I think it will work without LAMBDA-DIAG, but I suggest you load that
first:

    (MAKE-SYSTEM 'LAMBDA-DIAG)

(I think this is in by default in release 3 bands.) Then,

    (MAKE-SYSTEM 'IMICRO).

Be careful not to let the MICRO package get created wrong (by reading in
the IMICRO files before loading the DEFSYSTEM, for example.)  To get
full use of the micro-printer, load the LAMBDA-DIAG symbol table:

    (when (null (lam:lam-select-symbols-for-version-if-possible
                  %microcode-version-number))
      (lam:lam-load-ucode-symbols-for-version
        %microcode-version-number))


If it gets errors when loading, don't try to use it.  It is very careful
about setting up the pointers that communicate with the microcode, and
is very conservative.  Try to debug things if you want to, or send me
mail (with a bug report header).

The file SYS:IMICRO;TEST has the functions I have been using to try the
thing out.  Maybe that will give you some ideas.

To use it, make a file in package MICRO, and write forms like this:

    (define-micro-function car-if-list (l)
      ((m-t) pdl-pop)
      (popj-data-type-not-equal m-t (a-constant (byte-value q-data-type dtp-list)))
      ((vma-start-read) m-t)
      (check-page-read)
      (dispatch transport md)
      ((m-t) md)
      (popj))

When you evaluate the form, it will assemble the instructions, allocate
slots in all of the right tables, and install the code.  If it returns
sucessfully, you are ready to call the function.  At this point, it is a
good idea to look at the code first (this only works if LAMBDA-DIAG is
loaded.)

    (micro-print 'car-if-list)

Then save you files and try it out:

    (car-if-list 5)
    (car-if-list '(a))

By the way, the name of the function could be in another package.

This kind of function is called a MISC instruction.  You can find
examples by looking for the string "MISC-INST-ENTRY" in the microcode
files (SYS:ULAMBDA;UC-*.LISP).  Briefly, MISC instructions take a fixed
number of arguments.  The DEFINE-MICRO-FUNCTION form has a normal
looking ARGLIST, but it is only used to see how many arguments you claim
you want (and to store for documentation purposes.)  The code is
REQUIRED to pop the stack (using the M source PDL-POP) that many times
before returning.

MISC instructions can clobber any number or lettered register (M-1 to
M-6, M-A to M-E, M-I, M-J, M-K, M-Q, M-R, M-S, M-T).  Numbered registers
can hold any 32 bit number, while lettered registers must have valid
data-types.

MISC instructions return their values in M-T.  You must store something
into M-T during the instruction.  If you have nothing better to do,
write:

    ((m-t) a-v-nil)

If you want to change to code, either to fix bugs, or to extend it,
please talk to me first.

Good luck,
Pace