Software Design Notes                                Stack Groups






                           SECTION 14

                          Stack Groups



14.1  INTRODUCTION

This chapter  explains  stack  groups,  the  building  blocks  of
multiprocessing.

A  stack  group  is  the  fundamental  unit of computation in the
Explorer.   It  is   the   main   data   structure   behind   the
implementation  of  a  process.  Interrupt context-switching, co-
routines, and generators are facilitated  by  the  use  of  stack
groups.

At  all  times,  there  is  exactly one active stack group, which
corresponds to the process currently being run on a  time-sharing
system.   Although  there is no time-sharing between users on the
Explorer, it is still useful to support multiple processes.   For
example,  when a message is recieved from the network, some other
stack group is activated to handle it.



14.2  THE STACK GROUP DATA STRUCTURE

The term stack group refers to the fact that  each  process  must
have  its  own control stack for remembering function call/return
data and arguments and local data, and each process must  have  a
Linear  Binding stack to save the values of special variables.  A
stack group is  a  pointer  of  datatype  DTP-STACK-GROUP,  which
points  to  an  arrat geader word the same way a DTP-ARRAY would.
The reason for using  an  additional  datatype  is  so  that  any
routine  will  always  be able to distinguish a stack-group array
from all other arrays.  The array also has its  own  array  type,
ART-STACK-GROUP-HEAD, for the same reason.

The  stack  group  structure  is  an  array  with no body, only a
leader.  The array leader holds many relevant  data  including  a
pointer to the regular push down list, a pointer to another array
holding  the  Linear  Binding  PDL  for  the stack group, the PDL
pointer, for both PDLs, and  various  saved  microcode  registers
(the  Linear  Binding  PDL  is  also  called  the  Special PDL or
SPECPDL; see description below).

A  useful  feature  is  that  by  binding   appropriate   special
variables,   such   as   the  default  cons  area  and  debugging


                             14-1

Stack Groups                                Software Design Notes



information, an error handler can be made  a  function  of  which
stack  group  is  active; each may have its own.  This is because
each stack group has a separate Linear Binding PDL.

The array leader contains miscellaneous data related  to  running
and  maintaining  a  stack  group  in  the  system.  This data is
divided up into sections according to how the data is used.   The
static  section  contains  data such as the stack group name, and
size and limits on the PDLs.  This data is set up when the  stack
group is created and doesn't normally change during the course of
system  operation.   This  information  is  loaded when the stack
group is entered; but since it doesn't change, the  data  needn't
be saved when the stack group is left.  The debugging section has
information  that the error handler needs to determine what error
has occured and how to restart the stack group.  This information
is read directly by the error handler as needed and will  not  be
loaded  or  saved on stack group entry or exit.  The next section
of the stack group contains information used to  determine  which
operations  are valid on this stack group.  A layout of the stack
group data structure follows:


14.2.0  Static Section.

     SG-NAME                    Name of stack group for
                                conversing with user.

     SG-REGULAR-PDL             The array serving as the
                                regular PDL of this
                                stack group.  It must be
                                an ART-REG-PDL array.

     SG-REGULAR-PDL-LIMIT       Max PDL pointer value
                                before overflow.

     SG-SPECIAL-PDL             Special PDL for stack group.
                                It must be an
                                ART-SPECIAL-PDL array.

     SG-SPECIAL-PDL-LIMIT       Max special PDL pointer
                                value before overflow.

     SG-INITIAL-FUNCTION-INDEX  Position in regular PDL
                                of the topmost function
                                pointer cell (normally 3).


14.2.2  Debugging Section.

     SG-TRAP-TAG                Symbolic tag corresponding
                                to SG-TRAP-MICRO-PC.
                                Determined by looking up
                                the trap PC in the


                             14-2

Software Design Notes                                Stack Groups



                                microcode error table.
                                Properties of this
                                symbol drive error
                                reporting and recovery.

     SG-RECOVERY-HISTORY        Available for complex SG
                                debugging routines to
                                leave tracks in for debugging
                                purposes.  (This
                                may be done away with
                                in the future.)

     SG-FOOTHOLD-DATA           Structure which saves
                                dynamic section of "real"
                                SG when executing in
                                the error handler foothold.


14.2.3  High Level Section.

     SG-STATE                   The stack-group state.
                                This has fields
                                describing the high-level
                                state of this stack
                                group.  Stack group states
                               are listed in Table 14-1.

     SG-PREVIOUS-STACK-GROUP    SG which caused resumption
                                of this one.

     SG-CALLING-ARGS-POINTER    Pointer to argument-block
                                which last called
                                this SG.

     SG-CALLING-ARGS-NUMBER     Number of args in last
                                call to this SG.

     SG-TRAP-AP-LEVEL           Used for stepping.  When
                                stepping compiled
                                functions, will cause a
                                STEP-BREAK trap when
                                PDL pointer is below this
                                virtual address.


14.2.4  Dynamic Section.

     SG-REGULAR-PDL-POINTER     Saved PDL pointer, stored
                                as fixnum index into
                                SG-REGULAR-PDL.

     SG-SPECIAL-PDL-POINTER     Saved special PDL pointer,
                                stored as fixnum index


                             14-3

Stack Groups                                Software Design Notes



                                into SG-SPECIAL-PDL.

     SG-TRAP-MICRO-PC           Micro-address from which a
                                trap was signalled.
                                Used as a key to lookup the
                                TRAP-TAG in the
                                microcode error table.

     SG-SAVED-M-FLAGS           Saved processor flags as fixnum.
                               The flags are shown in Table 14-2.

     SG-PDL-PHASE               The index into the hardware
                                PDL buffer cache of
                                the Q at the top of the PDL.
                                This preserves
                                index-phasing of the pdl buffer
                                across SG switches.

     SG-SAVED-VMA               VMA register in a locative.
                                The data type is
                                stored in SG-VMA-M1-M2-TAGS.

     SG-VMA-M1-M2-TAGS          Tags of VMA, M-1, and M-2
                                packed into a fixnum.

     SG-M3-M4-TAGS              Tags of M-3 and M-4 packed
                                into a fixnum.

     SG-AC-1                    Pointer fields of "raw"
                                accumulators packed into
                                fixnums.  Tags are in one
                                of previous packed-tag regs.

     SG-AC-2

     SG-AC-3

     SG-AC-4

     SG-AC-A                    Accumulators ...

     SG-AC-B

     SG-AC-C

     SG-AC-D

     SG-AC-E

     SG-AC-F

     SG-AC-G



                             14-4

Software Design Notes                                Stack Groups



     SG-AC-H

     SG-AC-I

     SG-AC-J

     SG-AC-K

     SG-AC-L


     SG-AC-Q

     SG-AC-R

     SG-AC-S

     SG-AC-ZR

     SG-AC-T                    Result register, pseudo
                                indicators.

     SG-CATCH-POINTER           Typed pointer to catch
                                block.































                             14-5

Stack Groups                                Software Design Notes




                 Table 14-1  Stack Group States


    Value   Name                Meaning
    -----   ----                ------------------
      0     SG-STATE-ERROR      Should never get this.
      1     SG-STATE-ACTIVE     Actually executing on
                                  the machine.
      2     SG-STATE-RESUMABLE  Reached by interrupt
                                  or error recovery
                                  completed.  Just
                                  restore state and
                                  continue.
      3     SG-STATE-AWAITING-RETURN
                                After doing a "legitimate"
                                  sg-call.  To resume this,
                                  release sg, then return
                                  a value.
      4     SG-STATE-INVOKE-CALL-ON-RETURN
                                To resume this, reload sg,
                                  then simulate a store in
                                  destination-last.  The error
                                  system can produce this state
                                  when it wants to activate the
                                  foothold or perform a retry.
      5     SG-STATE-INTERRUPTED-DIRTY
                                Get this if forced to take an
                                  interrupt at an inopportune
                                  time.
      6     SG-STATE-AWAITING-ERROR-RECOVERY
                                Immediately after error, before
                                  recovery.
      7     SG-STATE-AWAITING-CALL
                                The SG is ready to be called.
      8     SG-STATE-AWAITING-INITIAL-CALL
                                Initial state of the SG, before
                                  it has been called.
      9     SG-STATE-EXHAUSTED  State when the SG has finished
                                  running.















                             14-6

Software Design Notes                                Stack Groups




                   Table 14-2  Processor Flags


   Bit(s)      Name             Meaning
   ------      ----             -----------------------
       0       QBBFL            This flag is no longer
                                  used.
     1-2       CAR-SYM-MODE     CAR of symbol mode:
                                  0: error
                                  1: error except
                                     (CAR NIL) is NIL
                                  2: NIL
                                  3: error
     3-4       CAR-NUM-MODE     CAR of number mode:
                                  0: error
                                  1: NIL
                                  2: error
                                  3: error
     5-6       CDR-SYM-MODE     CDR of symbol mode:
                                  0: error
                                  1: error except
                                     (CDR NIL) is NIL
                                  2: NIL
                                  3: error
     7-8       CDR-NUM-MODE     CDR of number mode:
                                  0: error
                                  1: NIL
                                  2: error
                                  3: error
       9       DONT-SWAP-IN     Flag for creating fresh
                                  pages.
      10       TRAP-ENABLE      When set, enable error
                                  trapping.
   11-12       MAR-MODE         1-bit = read-trap,
                                2-bit = write-trap
      13       PGF-WRITE        Flag used by page fault
                                  routine.
      14       INTERRUPT-FLAG   In a microcode interrupt.
      15       SCAVENGE-FLAG    In scavenger.
      16       TRANSPORT-FLAG   In transporter.
      17       STACK-GROUP-SWITCH-FLAG
                                Switching stack groups.
      18       DEVERRED-SEQUENCE-BREAK-FLAG
                                Sequence break pending
                                  but inhibited.
      19       METER-ENABLE     Metering enabled for
                                  this stack group.
      20       TRAP-ON-CALL     Trap on attempting to
                                  activate new frame.





                             14-7

Stack Groups                                Software Design Notes



14.3  SPECIAL PDL

The Special PDL, also known as the Linear Binding PDL, is used to
hold saved bindings of  special  variables.   The  Explorer  uses
shallow  binding,  so  the  current value of any symbol is always
found in the symbol's value cell.  When a symbol  is  bound,  its
previous  value is saved on the Special PDL, and the new value is
placed  in  the  value  cell.   When  a  stack  group  switch  is
performed,  the  current  process's  Special  PDL is saved in the
stack group.

The Special PDL also serves some other functions.  When a  micro-
to-macro  call  is  made, the processor micro-stack (UPCS) of the
machine is stored there (this is needed because the hardware UPCS
is of a small fixed size).

The Special PDL is block oriented.  The blocks are  delimited  by
setting the SPECPDL-BLOCK-START-FLAG in the first binding made in
a  block.  The data type of the top word (last pushed) of a block
determines what kind of block this is, as shown in Table 14-3.

SPECPDL-BLOCK-START-FLAG and SPECPDL-CLOSURE-BINDING  are  stored
in the CDR-Code field of Q's on the Special PDL.  The CDR-Code is
not  otherwise  used on the Special PDL.  SPECPDL-CLOSURE-BINDING
(bit 31) indicates that this binding was made  "before"  entering
the function (i.e., by closure binding, or by the binding of SELF
for a method).  SPECPDL-BLOCK-START-FLAG is bit 30.

A  normal  binding  block  is  stored  as  a pair of Q's for each
binding, the first Q is a locative pointer to the bound location,
and the second is the saved contents of the location.  Note  that
any  location  can  be bound; usually these locations will be the
value cells of symbols, but they can also be array elements, etc.
(only of arrays of type ART-Q or ART-Q-LIST).

The processor micro-stack (UPCS) blocks are  always  pushed  onto
the  Special  PDL all at once, and so are never "open."  However,
the normal binding blocks are created one pair  at  a  time.   To
keep track of this, when a macrocompiled function is running, the
binding-block-pushed  bit  is  set  in  the  call-info-word  if a
binding block has been opened on the Special PDL.   This  assures
that  when  a  compiled function is done, the call-info-word will
correctly reflect whether it has done any bindings that  must  be
popped  off  the  Special  PDL.   If  the  bit is set, all of the
bindings of the top-most block of the Special PDL must be undone.
If not set, it means that no pairs have yet been pushed.

Micro-to-micro calls can also cause bindings,  and  in  order  to
keep  that  straight, a bit on the UPCS is set it indicate that a
block was bound.

The Special PDL is pointed to  by  the  location  SG-SPECIAL-PDL-
POINTER  in  the stack group and by A-GLBNDP when the stack group


                             14-8

Software Design Notes                                Stack Groups



is executing on processor.  There is an area devoted  to  storing
both  Special  PDLs  and stack groups called the SG-AND-BIND-PDL-
AREA.

               Table 14-3  Special PDL Block Type


          DATATYPE       USE
          --------       -------------------------

          LOCATIVE       The block is a normal binding block.
          FIXNUM         This is a block transferred from the
                         processor micro-stack (UPCS).  Each
                         word in the block should be a fixnum
                         containing the old contents of the
                         UPCS.  Only the active part of the stack
                         stack is transferred.






































                             14-9
