Software Design Notes                         Other Subprimitives






                           SECTION 16

          Other Subprimitives, Variables, and Counters



16.1  INTRODUCTION



                              NOTE
          Unless   indicated   otherwise,    all    the
          subprimitive  and  variable  names  listed in
          this section are in the SYSTEM package.



This section covers the  Explorer  subprimitives  that  are  non-
storage-related.   They,  like other subprimitives should be used
with caution, since they may ruin the Lisp  environment  if  used
incorrectly.


                              NOTE

          Because  they are used at the lowest level of
          the Explorer virtual machine  implementation,
          the  subprimitives  and  variables  described
          here may change in the way they  function  or
          even  be  removed  entirely  from  the system
          without   notice.    Most   programs   should
          generally not refer to them directly.





16.2  ARRAY SUBPRIMITIVES

The  subprimitives  described  below  are  special-purpose  array
manipulating functions.

%string-equal (string1 start1 string2 start2 count)
     %STRING-EQUAL is the microcode  primitive  used  by  STRING-
     EQUAL.   It  returns  T  if  the COUNT characters of STRING1
     starting at START1 are char-equal to the count characters of
     STRING2 starting at START2, or NIL if the characters are not
     equal or if COUNT runs off the length of either array.


                             16-1

Other Subprimitives                         Software Design Notes



     Instead of a FIXNUM, COUNT may also be NIL.  In  this  case,
     %STRING-EQUAL compares the substring from START1 to (STRING-
     LENGTH  <string1>)  against  the  substring  from  START2 to
     (STRING-LENGTH  <string2>).   If  the   lengths   of   these
     substrings  differ,  then  they  are  not  equal  and NIL is
     returned.

     Note that STRING1 and STRING2 must really  be  strings,  the
     usual  coercion  of  symbols  and  FIXNUMs to strings is not
     performed.  This  function  is  documented  because  certain
     programs  which  require  high efficiency and are willing to
     pay the price of less generality may want  to  use  %STRING-
     EQUAL in place of STRING-EQUAL.

     Examples:

       To compare the two strings foo and bar:
       (%STRING-EQUAL foo 0 bar 0 nil)
       To see if the string foo starts with the characters "bar":
       (%STRING-EQUAL foo 0 "bar" 0 3)

alphabetic-case-affects-string-comparison             Variable
     If  this  variable  is  T,  the  function  %STRING-EQUAL and
     %STRING-SEARCH-CHAR consider case (and font) significant  in
     comparing  characters.   Normally  this  variable is NIL and
     those primitives ignore differences of case.

     This variable may be bound by user programs around calls  to
     %STRING-EQUAL  and  %STRING-SEARCH-CHAR,  but  do not set it
     globally,  for  that  may  cause  the  higher  level  string
     comparisons not to function as desired.

%string-search-char (char string from to)
     %STRING-SEARCH-CHAR  is  the  microcode  primitive called by
     STRING-SEARCH-CHAR and other functions.  STRING must  be  an
     array  and CHAR, FROM and TO must be FIXNUMs.  The arguments
     are all required.  Case-sensetivity  is  controlled  by  the
     value    of   the   variable ALPHABETIC-CASE-AFFECTS-STRING-
     COMPARISON rather than by an  argument.   Except  for  these
     differences,  %STRING-SEARCH-CHAR  is  the  same  as STRING-
     SEARCH-CHAR.  This function is documented for the benefit of
     those who require  maximum  possible  efficiency  in  string
     searching.

ar-1 (array i)

ar-2 (array i j)

ar-3 (array i j k)

as-1 (array i)

as-2 (array i j)


                             16-2

Software Design Notes                         Other Subprimitives




as-3 (array i j k)

ap-1 (array i)

ap-2 (array i j)

ap-3 (array i j k)

     These are obsolete versions of AREF, ASET and ALOC that only
     work   for   one-,   two-,   or   three-dimensional  arrays,
     respectively.

     The compiler turns AREF into AR-1, AR-2, etc.  according  to
     the  number  of  subscripts specified, turns ASET into AS-1,
     AS-2, etc., and turns ALOC into AP-1, AP-2, etc.  For arrays
     with more  than  three  dimensions  the  compiler  uses  the
     slightly less efficient form since the special routines only
     exist for one, two and three dimensions.  There is no reason
     for  any program to call AR-1, AS-1, AR-s, etc.  explicitly;
     they are documented because there used to be such a  reason,
     and  many  old  programs  use these functions.  New programs
     should use AREF, ASET, and ALOC.

common-lisp-ar-1 (array i)

common-lisp-ar-2 (array i j)

common-lisp-ar-3 (array i j k)

common-lisp-aref (array &rest subscripts)

     The first three of these functions are  identical  to  AR-1,
     AR-2  and  AR-3  except  that they return a character object
     rather than an integer when ARRAY is a string.  COMMON-LISP-
     AREF is  the  general  array  referencing  subprimitive  for
     Common Lisp.  It also returns a character object rather than
     an integer when ARRAY is a string.

array-types                                           Constant
     The  value  of  this  constant is a list of all of the array
     type symbols such as ART-Q, ART-4B, ART-STRING  and  so  on.
     The  values  of  these  symbols are internal array type code
     numbers for the corresponding type.

array-types (array-type-code)
     Given an  internal  numeric  array-type  code,  returns  the
     symbolic name of that type.

array-elements-per-q                                  Constant
     This is an association list which associates each array type
     symbol with the number of array elements stored in one word,
     for  an array of that type.  If the value is negative, it is


                             16-3

Other Subprimitives                         Software Design Notes



     instead the number of words per array  element,  for  arrays
     whose elements are more than one word long.

array-elements-per-q (array-type-code)
     Given  the  internal  array-type  code  number,  returns the
     number of array elements stored in one word, for an array of
     that type.  If the value is  negative,  it  is  instead  the
     number of words per array element, for arrays whose elements
     are more than one word long.

array-bits-per-element                                Constant
     The  value  of  this  constant  is an association list which
     associates each array type symbol with the number of bits of
     unsigned number it can hold, or NIL  if  it  can  hold  Lisp
     objects.  This can be used to tell whether an array can hold
     Lisp objects.

array-bits-per-element (array-type-code)
     Given  the  internal  array-type  code  numbers, returns the
     number of bits per cell for unsigned numeric arrays, or  NIL
     for a type of array that can contain Lisp objects.

array-element-size (array)
     Given  an  array,  returns the number of bits that fit in an
     element of that array.  For arrays  that  can  hold  general
     Lisp  objects,  the  result  is  25  (decimal), based on the
     assumption that you will be storing FIXNUMs in the array.



16.3  STACK LIST SUBPRIMITIVES

When you are creating a list that will not  be  needed  any  more
once  the function that creates it is finished, it is possible to
create the list on the stack instead  of  by  consing  it.   This
avoids   any  permanent  storage  allocation,  as  the  space  is
reclaimed as part of  exiting  the  function.   These  lists  are
called  temporary  lists  or  stack lists.   You  can create them
                              ___________
explicitly using the  special  forms  WITH-STACK-LIST  and  WITH-
STACK-LIST*.   &REST arguments also sometimes create stack lists.
See the Explorer Lisp Reference manual for  more  information  on
        _______________________
these   forms  and  there  usage.   Note  that  stack  lists  are
automatically copied out of the stack if you stoer a  pointer  to
them into normal virtual memory outside the stack.











                             16-4

Software Design Notes                         Other Subprimitives






16.4  FUNCTION-CALLING SUBPRIMITIVES

These  subprimitives  can  be  used  to  call a function with the
number  of  arguments  variable  at  run   time.    Since   these
subprimitives  act  as  a  signal  for  the  compiler to initiate
certain operations on the stack,  they  are  only  meaningful  in
compiled  code.   They are not callable from the interpreted Lisp
environment.


                              NOTE

          The  improper  use  of  these  functions  can
          irreparably  damage  the state of the runtime
          stack (PDL).  They should be used  only  with
          extreme  caution.  The preferred higher-level
          primitive is APPLY.



%push (value)
     Pushes  VALUE  onto  the  stack.   Use  this  to  push  each
     argument.

%call (function number-of-args &key lexper self-mapping-table)
     Call  FUNCTION,  passing  arguments  that  have already been
     pushed on the stack with %PUSH.   This  is  a  sub-primitive
     that only works in compiled code.

%pop
     Pops  the  top  value off of the stack and returns it as its
     value.

%assure-pdl-room (n-words)
     Call this before doing a sequence of %PUSH's that  will  add
     N-WORDS to the current frame.  This subprimitive checks that
     the  frame  will  not  exceed  the maximum legal frame size,
     which is 255 words including all overhead.   This  limit  is
     dictated  by  the  way stack frames are linked together.  If
     the frame is going to exceed the legal  limit,  %ASSURE-PDL-
     ROOM signals an error.











                             16-5

Other Subprimitives                         Software Design Notes






16.5  SPECIAL-BINDING SUBPRIMITIVE


%bind (locative value)

bind (locative value)
     Binds  the  cell  pointed  to  by  LOCATIVE to VALUE, in the
     caller's environment.  This function is not defined  in  the
     interpreted  Lisp  environment;  it only works from compiled
     code.  Since it turns into  an  instruction,  the  "caller's
     environment"   really  means  "the  binding  block  for  the
     compiled function that executed the %BIND instruction".  The
     preferred higher-level primitived that turn  into  this  are
     LET, LET-IF, and PROGV.

     The  binding  is  in  effect  for the scope of the innermost
     binding construct,  such  as  prog  or  let,  even  if  that
     construct binds no variables itself.

     %BIND  is  the  preferred  name; BIND is an older name which
     will eventually be eliminated.



16.6  CLOSURE SUBPRIMITIVES

These functions are used to implement  dynamic  closures  on  the
Explorer system.  They deal with teh distinction between internal
and  external  value  cells  and control over how these different
kinds of value cells interact.

%using-binding-instances (instance-list)
     This function is the primitive operation that invocation  of
     closures  could  use.  It takes a list, and for each pair of
     elements in the list it "adds"  a  binding  to  the  current
     stack  frame,  in  the  same  manner that the %BIND function
     does.  These bindings  remain  in  effect  until  the  frame
     returns or is unwound.

     %USING-BINDING-INSTANCES  checks  for redundant bindings and
     ignores them.  (A binding is  redundant  if  the  symbol  is
     already  bound  to  the  desired external value cell.)  This
     check avoids excessive growth of the  special  PDL  in  some
     cases  and  is  also  made  by  the  microcode which invokes
     closures, entities, and instances.

     Given  a  closure,  closure-bindings  extract  its  list  of
     binding  instances,  which  you  can  then  pass  to %USING-
     BINDING-INSTANCES.



                             16-6

Software Design Notes                         Other Subprimitives



%external-value-cell (symbol)
     Returns a locative to whatever  the  value  cell  of  SYMBOL
     points  to.  If SYMBOL is bound by a closure, this will be a
     locative to the external value cell.  Does  not  check  that
     the  internal  value  cell  contains  an external value cell
     pointer.



16.7  LOCKING SUBPRIMITIVE


%store-conditional (pointer old new)
     This is the basic locking primitive.  POINTER is a  locative
     to  a cell which is read and written without interrupts.  If
     the contents of the cell is EQ to OLD, then it  is  replaced
     by  NEW  and  T is returned.  Otherwise, NIL is returned and
     the contents of the cell are not changed.  Normally programs
     should use the store-conditional function instead, since  it
     includes type checking.



16.8  EXPLORER I/O DEVICE SUBPRIMITIVES


%nubus-read (slot byte-address)
     Returns  the  contents  of  a  word  read  from  the  NuBus.
     Addresses on the NuBus are divided into an 8-bit slot number
     which identifies which physical board  is  being  referenced
     and  a  24-bit address within slot.  The address is measured
     in bytes and therefore should be a  multiple  of  4.   Which
     addresses  are  valid  depends  on the type of board plugged
     into the specified slot.  If, for example. the board is a  2
     Megabyte  main  memory  board,  then the valid address range
     from 0 to 4 *  (2MB  -  1).   (Of  course,  main  memory  is
     normally accessed through the virtual memory system.)

%nubus-write (slot byte-address word)
     Writes  WORD  into  a  word  of  the NuBus, whose address is
     specified by SLOT and BYTE-ADDRESS as described above.



16.9  SUBPRIMITIVES TO SHUT DOWN THE LISP ENVIRONMENT


%halt
     Stops the machine.

%crash (code object paws-up-p)
     Halts the machine after writing a crash record that includes
     CODE and OBJECT (each stored  as  one  word)  which  can  be


                             16-7

Other Subprimitives                         Software Design Notes



     reported  by  the crash analyzer.  If PAWS-UP-P is true, the
     monitor screen will invert its video characteristic.

%disk-restore (high-16-bits low-16-bits)
     Loads  virtual  memory  from  the  partition  named  by  the
     concatenation  of  the  two  16-bit  arguments,  and  starts
     executing it.  The name 0 refers to the  default  load  (the
     one  the  machine loads when it is started up).  This is the
     primitive used by the DISK-RESTORE function.



16.10  VIRTUAL MEMORY SYSTEM SUBPRIMITIVES

A number of virtual memory system subprimitives are  detailed  in
the last portion of the Paging and Disk Management section.



16.11  GARBAGE COLLECTION SUBPRIMITIVES

A  number  of  subprimitives  used  by  the garbage collector are
detailed  in  the  last  portion  of  the  section   on   Garbage
Collection.



16.12  MICROCODE VARIABLES

The   following   variables'   values   actually  reside  in  the
processor's  scratchpad  memory  register   blocks.    They   are
forwarded  there  by  DTP-ONE-Q-FORWARD invisible pointers in the
value cells of the symbols which name them.  These variables  are
used  by  the  microcode  and  by  the  low-level  Lisp system to
implement the virtual machine.  Thus, they are  highly  internal,
and  their  full  meanings  are  not necessarily documented here.
Changing their values  can  have  unpredictable  and  undesirable
results.

Although this variables can be set from Lisp code, since they are
actually aliases of processor registers their values are reset to
certain default values at boot time.  Even a warm boot will alter
some of them.


16.2.1   M-Memory  Variables.   These are the M-Memory variables.
A list of all of these variables can be found in the value of the
variable M-MEMORY-LOCATION-NAMES.  This variable will  always  be
up-to-date  even  if this documentation is not.  Current M-Memory
variable contents can be views with the function  DUMP-M-MEMORY-
Q-STORAGE or the function M-MEMORY.

%mode-flags                                          Variable


                             16-8

Software Design Notes                         Other Subprimitives



     The  MODE-FLAGS currently in effect.  Some flags are used as
     state flags  by  the  transporter  and  the  paging  system.
     Others are general modes honored on a per-stack-group basis,
     such as the meter-enable field.  Byte specifiers for each of
     the fields of this variable can be found in M-FLAGS-FIELDS.

%sequence-break-source-enable                         Variable
     Enables different sources of sequence breaks.  See SB-ON.

%meter-micro-enables                                  Variable
     Flags  for  enabling  the  different  metering events.  Byte
     descriptors can be found in the METER-ENABLES list.

self                                                  Variable
     The current value of the SELF instance.  It is  an  M-Memory
     register for efficiency.

self-mapping-table                                    Variable
     The  current  SELF-MAPPING-TABLE  array  used  for  instance
     variable  references.   It  is  an  M-Memory  register   for
     efficiency.


16.12.2   A-Memory  Variables.  These are the A-Memory variables.
A list of all of these variables can be found in the value of the
variable M-MEMORY-LOCATION-NAMES.  This variable will  always  be
up-to-date  even  if this documentation is not.  Current M-Memory
variable contents can be viewed with the function  DUMP-A-MEMORY-
Q-STORAGE or the function A-MEMORY.

%microcode-version-number                             Variable
     This   is   the   version  number  of  the  currently-loaded
     microcode, obtained from the version number  stored  in  the
     microcode partition loaded.

processor-type-code                                   Variable
     Code for the current processor's type.  Currently always 3.

microcode-type-code                                   Variable
     Code  number for the currently running microcode.  For legal
     values and the  microcode  types  they  represent,  see  the
     variable *MICROCODE-NAME-ALIST*.

microcode-debug-flags                                 Variable
     Microcode flags used for determining action to take on trap,
     sequence   break,  and  so  forth.   See  the  function SET-
     MICROCODE-DEBUG-FLAGS for information on  how  to  set  them
     from  Lisp.   The  list  MICROCODE-DEBUG-FLAGS-BITS contains
     byte specifiers for all the bits.

amem-evcp-vector                                      Variable
     A-Memory address of location where A-Memory dynamic variable
     closure bindings may be stored.


                             16-9

Other Subprimitives                         Software Design Notes



%number-of-micro-entries                              Variable
     The actual number of words used in the MICRO-CODE-ENTRY-AREA
     and the MICRO-CODE-ENTRY-DEBUG-INFO-AREA.

%counter-block-a-mem-address                          Variable
     The offset in A-Memory of the start of the Microcode Counter
     block.  See the following discussion of Microcode Counters.

%mar-low                                              Variable
     When the MAR is enabled, contains the lowest virtual address
     being monitored.

%mar-high                                             Variable
     When the  MAR  is  enabled,  contains  the  highest  virtual
     address being monitored.

%method-search-pointer                                Variable

%method-subroutine-pointer                            Variable
     Used by the flavor-support microcode.

%current-stack-group-state                            Variable
     The sg-state of the currently-running stack group.

%current-stack-group-calling-args-pointer             Variable
     The argument list of the currently-running stack group.

%trap-micro-pc                                        Variable
     The microcode address of the most recent error trap.

%resumed-trap-ap-level                                Variable

%resumed-regular-pdl-pointer                          Variable

%resumed-special-pdl-pointer                          Variable

%resumed-saved-m-flags                                Variable
     Used by the error handler.

%initial-fef                                          Variable
     The  function  that  is  called  when the machine starts up.
     Normally this is the definition of LISP-TOP-LEVEL.

%initial-stack-group                                  Variable
     The stack group in which the machine  starts  up.   Normally
     this  is  the initial Lisp Listener window's process's stack
     group.

%error-handler-stack-group                            Constant
     The stack group that  receives  control  when  a  microcode-
     detected error occurs.  It is THE error handler stack group;
                                   ___
     that  is when invoked, it cleans up, signals the appropriate
     condition, then assigns a second-level error  handler  stack


                            16-10

Software Design Notes                         Other Subprimitives



     group  which  actually runs the debugger on the erring stack
     group.

%scheduler-stack-group                                Constant
     The stack group that receives control when a sequence  break
     occurs.

inhibit-scheduling-flag                           Variable
     When  true,  all sequence breaks are disabled.  This is used
     by the WITHOUT-INTERRUPTS macro.

%inhibit-read-only                                    Variable
     If true, you can write into read-only areas.  This  is  used
     by FASLOAD and the garbage collector.

inhibit-scavenging-flag                               Variable
     If  true, the scavenger is turned off.  The scavenger is the
     the quasi-asynchronous  portion  of  the  garbage  collector
     which  is invoked after consing operations if any generation
     is in a flipped state (undergoing collection).

default-cons-area                                     Variable
     The area number the default area in which to create objects.
     The default is WORKING-STORAGE-AREA.

background-cons-area                                  Variable
     The area number the default area in which to create  objects
     that  must  not  be  created in a temporary area (hence this
     must never be the area-number of a temporary area).  Used by
     the Extra-PDL dumper as the area for  copying  out  numbers.
     The default is WORKING-STORAGE-AREA.

number-cons-area                                      Variable
     The area number of the area where BIGNUMs, ratios, full-size
     floats  and  complexnums are consed.  Normally this variable
     contains  the  area  number  of  the  EXTRA-PDL-AREA.   This
     enables  number consing, the low-overhead garbage collection
              ______________
     of extended numbers.  To disable number  consing,  set  this
     variable to the number of another area.

%region-cons-alarm                                    Variable
     Increments whenever a new region is allocated.

%page-cons-alarm                                      Variable
     Increments whenever a new page is allocated.

%gc-flip-ready                                        Variable
     NIL  while  a garbage collection is in progress.  T when all
     scavenging is done (that is, when collection is complete and
     there are no more pointers to Oldspace).

%scavenger-ws-enable                                  Variable
     When  a   generation   collection   begins   scavenging   is


                            16-11

Other Subprimitives                         Software Design Notes



     temporarily  disabled  to  allow the mutator to move objects
     dynamically.  When this variable is true the scavenger is on
     hold.  When  NIL,  scavenging  can  occur   (when   INHIBIT-
     SCAVENGING FLAG is also NIL).

%gc-switches                                          Variable
     Currently unused.

%gc-generation-number                                 Variable
     A FIXNUM which is incremented whenever the garbage collector
     flips,  converting  one  or  more  regions  from Newspace to
     Oldspace.  If this number has changed,  the  address  of  an
     object  may have changed.  Comparing this number with a hash
     table's internal GC generation number is used  to  cause  EQ
     hash  tables  to  rehash  after  a  GC.   The  value cell is
     actually forwarded to a slot  in  the  System  Communication
     Area  so  that  the  changes  to its value can live across a
     DISK-SAVE.

load-unit                                             Variable
     The physical disk unit from which Lisp was loaded.

%disk-switches                                        Variable
     Controls various paging system  parameters.   Documented  in
     the paragraph on paging subprimitives.

number-of-page-devices                                Variable
     The current number of logical paging devices in the  system.
     Includes all PAGE bands and the LOD band.

%free-cluster-count                                   Variable
     A  FIXNUM  which  holds  the  current  number  of  PAGE band
     clusters available for allocation.

%disk-run-light                                       Constant
     A FIXNUM.  This is the virtual  address  of  the  TV  buffer
     location  of  the run-light which lights up when the disk is
     active.  This plus 2 is the address of the run-light for the
     processor.  This minus 2 is the address of the run-light for
     the scavenger.

%disk-blocks-per-track                                Variable

%disk-blocks-per-cylinder                             Variable
     Configuration of the disk.

%clipping-rectangle-left-edge                         Variable

%clipping-rectangle-right-edge                        Variable


                            16-12

Software Design Notes                         Other Subprimitives



%clipping-rectangle-top-edge                          Variable

%clipping-rectangle-bottom-edge                       Variable

%current-sheet                                        Variable

%currently-prepared-sheet                             Variable
     Used for communication between the  window  system  and  the
     microcoded graphics primitives.

%mouse-cursor-state                                   Variable

%mouse-x                                              Variable

%mouse-y                                              Variable

%mouse-cursor-x-offset                                Variable

%mouse-cursor-y-offset                                Variable

%mouse-cursor-width                                   Variable

%mouse-cursor-height                                  Variable

%mouse-x-speed                                        Variable

%mouse-y-speed                                        Variable

%mouse-buttons-buffer-in-index                        Variable

%mouse-buttons-buffer-out-index                       Variable

%mouse-wakeup                                         Variable

%mouse-h3                                             Variable
     Used by the mouse tracking microcode.

%meter-global-enable                                  Variable
     T if the metering system is turned on for all stack-groups.

%meter-buffer-pointer                                 Variable
     A I/O buffer (RQB data buffer) used by the metering system.

%meter-first-address                                  Variable
     Where  the  metering system writes its next block of results
     on the disk.

%meter-disk-count                                     Variable
     The  number  of  disk  blocks  remaining  for  recording  of
     metering information.

meter-unit                                            Variable
     The disk unit being used for metering.


                            16-13

Other Subprimitives                         Software Design Notes



lexical-environment                                   Variable
     This  is  the  static  chain  used  in the implementation of
     lexical scoping of variable bindings in compiled code.

%mc-code-exit-vector                                  Variable
     Unused.

%inhibit-stack-list-copy                              Variable
     Unused.

alphabetic-case-affects-string-comparison             Variable
     If this  variable  is  T,  the  function  %string-equal  and
     %string-search-char  consider case (and font) significant in
     comparing characters.  Normally this  variable  is  NIL  and
     those primitives ignore differences of case.

%underflow                                            Variable
     When  this  variable  is  true  floating  point underflow or
     divide-by-zero has occurred.

array-index-order                                     Variable
     When true (the  default)  arrays  are  stored  in  row-major
     order.   This should not be changed, since no other ordering
     is supported by some of the array primitives.

ar-1-array-pointer-1                                  Variable

ar-1-array-pointer-2                                  Variable
     Used by the array microcode as a cache of information on the
     last array decoded.



16.13  MICROCODE COUNTERS

The Microcode Counters (also called Meters are locations  in  the
              ________              ______
processor's  scratchpad A-Memory register block which contain 32-
bit numbers (they have nothing  to  do  with  the  Lisp  metering
system per se).

Most  of  the  meters  are used to count events of various sorts.
Others exist simply  so  that  the  value  of  certain  microcode
registers can be read and written from Lisp.  They are accessible
through  the functions READ-METER and WRITE-METER.  Their current
values are displayed by the PEEK COUNTERS display and by invoking
the function DUMP-A-MEMORY-COUNTERS or A-COUNTERS.

All the counters  are  described  below.   They  are  grouped  by
general  use,  although  they  do not appear in that order in the
PEEK display.





                            16-14

Software Design Notes                         Other Subprimitives



16.13.1  Accessing Counters.

read-meter (name)
     Returns the contents of  the  microcode  meter  named  NAME.
     NAME  name  must  be  one  of  the  symbols  in  the counter
     descriptions below.  Warning:  since the meters can  be  32-
     bit values, either a FIXNUM or a BIGNUM may be returned.

write-meter (name value)
     Writes value, a FIXNUM or a BIGNUM, into the microcode meter
     named name.  Name must be one of the symbols listed below.

a-memory-counter-block-names                   Constant
     A  list  of all the symbols listed below.  The value of each
     symbol is the counter's offset from the start of the counter
     block.


16.13.2  Page Exception Handling Counters.

%count-first-level-map-reloads                    Meter
     The number of times the second-level  map  handling  had  to
     take place in order to set up a first level map.

%count-second-level-map-reloads                   Meter
     The  number of times the second-level virtual-memory map was
     invalid and had to be reloaded from the Page Hash Table.

%count-meta-bits-map-reloads                      Meter
     The number of times the memory maps  have  been  set  up  to
     contain  only  "meta bits" for the garbage collector without
     physical address mapping information.

%count-pdl-buffer-read-faults                     Meter
     The number of read references to the PDL  buffer  that  were
     virtual memory references that trapped.

%count-pdl-buffer-write-faults                    Meter
     The  number  of write references to the PDL buffer that were
     virtual memory references that trapped.

%count-pdl-buffer-memory-faults                   Meter
     The number of virtual memory references that trapped in case
     they might have been in the PDL buffer, but turned out to be
     real virtual memory references after all (and therefore were
     needlessly slowed down).


16.13.3  Page Fault Handling Counters.

%count-disk-page-reads                            Meter
     The total number of disk  page  read  operations  performed.
     This  is  equal  to  the  total number of disk pages read if


                            16-15

Other Subprimitives                         Software Design Notes



     prepaging is disabled.  If prepaging is enabled,  the  total
     number  of  disk pages read is this number plus the value of
     the %COUNT-PRE-PAGES-READ counter.

     This number can also be considered a count of the number  of
     times  the  page-fault  logic  was invoked because of a hard
     fault on a demanded page.

%count-fresh-pages                                Meter
     The number of fresh (newly-consed) pages  created  in  core.
     Since  a  fresh  page  request  is  considered  a page fault
     (because they cause another page to be evicted), this number
     plus the %COUNT-DISK-PAGE-READS is  a  count  of  the  total
     number of times the hard page-fault routine has been called.

%count-disk-page-writes                           Meter
     The total number of pages written to the disk.

%count-disk-page-write-operations                 Meter
     The  total  number  of  paging  write  operations.   This is
     usually  smaller  than  the  %COUNT-DISK-PAGE-WRITES   value
     because every attempt is made to swap out more than one page
     at a time.

%count-disk-page-wrote-appends                    Meter
     The  number  of  pages appended in multi-swapout operations.
     This number  plus  %COUNT-DISK-PAGE-WRITE-OPERATIONS  should
     add up to %COUNT-DISK-PAGE-WRITES.

%count-pre-pages-read                             Meter
     The number of page was read in due to pre-paging.

%count-pre-pages-used                             Meter
     The  number  of read pre-pages that have actually been used.
     The ratio of this number to  %COUNT-PRE-PAGES-READ  gives  a
     measure of pre-paging efficiency.

%disk-wait-time                                   Meter
     The  total time spent waiting for the disk, in microseconds.
     Since swapouts  are  overlapped  with  processing  and  with
     swapins  whenever  possible,  this  number cannot be used in
     conjunction with the total  number  of  disk  operations  in
     order  to  measure  the  disk hardware's processing time per
     page.  However, it could  be  used  to  measure  the  paging
     system's  average  disk  wait  time  per read operation, for
     example, if divided by the %COUNT-PAGE-READS number.

%total-page-fault-time                            Meter
     Contains the total  amount  of  time  spent  in  page  fault
     processing (when tracking this time is enabled by the %DISK-
     SWITCHES  flag).   This  time  includes  all  the time spent
     waiting on the disk  (%DISK-WAIT-TIME)  plus  any  microcode
     processing  time  not done during disk-I/O.  Subtract %DISK-


                            16-16

Software Design Notes                         Other Subprimitives



     WAIT-TIME from this number to get the amount of time take by
     the page fault processing routime.  This  does  NOT  include
     time  spent  handling page exceptions which did not turn out
     to be hard faults.  Such page exception processing  time  is
     very  small  in  any case, and can be considered part of the
     cost of computation.

%count-disk-page-write-waits                      Meter
     The number of times the page write routine had to wait for a
     page to finish being written out before being able to  start
     its I/O.

%count-disk-page-write-busys                      Meter
     The total number of times any paging routine had to wait for
     a  page to finish being written out in order to do something
     else with the disk.

%aborted-swapouts                                 Meter
     The number of pages  referenced  while  a  swapout  to  disk
     operation for them was still in progress.

%count-swapout-page-count-reached                 Meter
     The  number  of  multipage  swapouts  stopped because of the
     DISK-SWITCHES limit.

%swapout-sized-by-rqb-or-page-count               Meter
     The number of page writes limited by the size of the swapout
     RQB scatter list.

%count-disk-page-read-resubmissions               Meter
     The number of read operations restarted due to  disk  error.
     Since  page  read resubmissions are currently not supported,
     this number should always be 0.

%count-sb-from-swapper                            Meter
     Unused.

%swapout-sequence-breaks-in-progress              Meter
     Unused.


16.13.4  Page Replacement Algorithm Counters.

%count-clean-page-requests                        Meter
     The number of times FINDCORE (the page replacement  routine)
     has been requested to return a clean memory page rather than
     just the least recently used page.

%count-clean-page-request-failed                  Meter
     The number of times FINDCORE could not find a clean page.

%count-findcore-clear-pages                       Meter
     The number of already flushed pages found by FINDCODE


                            16-17

Other Subprimitives                         Software Design Notes



%count-findcore-steps                             Meter
     The  number  of  pages  inspected  by  the  page replacement
     algorithm.

%count-findcode-emergencies                       Meter
     The number of times no evictable page was  found  and  extra
     aging had to be done.

%least-used-page                                  Meter
     The  PHT  byte  index  of  the  least recently used physical
     memory page.

%most-recently-referenced-page                    Meter
     The PHT byte index page frame number of  the  most  recently
     referenced physical memory page.


16.13.5  PHT and PPD Information Counters.

%page-hash-table-address                          Meter
     The starting physical address of the PHT.

%physical-page-data-address                       Meter
     The starting physical address of the PPD.

%pht-index-limit                                  Meter
     Maximum byte offset in the PHT.

%physical-page-data-end                           Meter
     Maximum byte offset in the PPD.

%pht-index-size                                   Meter
     Number  of  bits  of  the  virtual  page  number  to  use in
     computing an address' PHT hash value.

%pht-search-depth                                 Meter
     Longest collision bucket so far in the Page Hash Table.

%page-table-search-count                          Meter
     Unused.


16.13.6  GC Counters.

%count-cons-work                                  Meter
     The number of words consed times 16.  This is used to  drive
     scavenging.

%count-scavenger-work                             Meter
     Scavenger work done.  Value is usually less than or equal to
     %COUNT-CONS-WORK,   but  can  be  slightly  greater  if  the
     scavenger gets a bit ahead of consing.



                            16-18

Software Design Notes                         Other Subprimitives



%tgc-counter                                      Meter
     General purpose TGC counter.  Currently unused.

%max-generation-0-object-size                     Meter
     Size of the largest object (in words) allowed to be  created
     in   generation  0.   Larger  objects  will  be  created  in
     generation 1.


16.13.7  Hardware Fault Detection Counters.

%count-nubus-gacbl-retries                        Meter
     The number  of  times  the  system  had  to  retry  a  NuBus
     operation due to receiving a Go Away Come Back Later (GACBL)
     response from the NuBus.

%count-nubus-parity-retries                       Meter
     The  number  of  times  the  system  had  to  retry  a NuBus
     operation due to receiving a Parity Error response from  the
     NuBus.


16.13.8  Miscellaneous Counters.

%lowest-direct-virtual-address                    Meter
     The  virtual  address  corresponding  to  the  start  of the
     processor's internal A-Memory.  Same address as the constant
     A-MEMORY-VIRTUAL-ADDRESS,  except  that  READ-METER  on  the
     meter will give you a BIGNUM.

%io-space-virtual-address                         Meter
     Lowest virtual address for TV screen memory.

%crash-record-physical-address                    Meter
     Physical  address  in NVRAM of the currently allocated crash
     record, or 0 if none allocated.

%tv-clock-rate                                    Meter
     The number of TV  frames  per  clock  sequence  break.   The
     default  value  is  67 which causes clock sequence breaks to
     happen about once per second.

%meter-wait-time                                  Meter
     The amount of time spent in metering.

%slots-i-own                                      Meter
     Bit map for ownership  of  the  hardware  boards.   Used  in
     multiprocessing environment to determine which boards belong
     to the Explorer processor.

%cnfg-partition-slot-unit                         Meter
     Slot  and  unit  for reading the configuration partition, or
     all ones if none used.


                            16-19

Other Subprimitives                         Software Design Notes



%cnfg-partition-name                              Meter
     ASCII name of the configuration partition.

%count-tail-recursions-ignored                    Meter
     The number of times we have to ignore the D-TAIL-REC  return
     type  (tail recursion) generated by the compiler and just do
     a D-RETURN instead.
















































                            16-20
