;;; -*- Mode:GATE; Base:10; Fonts:(CPTFONT HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I) -*- =Node: system bookreports =Script: @ stack-groups @ stack-group-illustration @ stack-group-structure @ closure-illustration @ arrays @ investigation @ microcode investigation @ lambda main data paths @ interpreter closure illustration =Node: stack-groups =Text: A Stack Group is a LISP object used to generate control structures such as generators and coroutines. An important use is as the basis for Processes, which are a kind of coroutine. (See the Grey LISP Machine manual, section 13 for a general description and for the functional interface) A stack group is built from 3 arrays, the STACK-GROUP, the REGULAR-PDL, and the SPECIAL-PDL. The STACK-GROUP has a header (of type ART-STACK-GROUP-HEAD) and a leader but no data. The leader is long, and contains all of the state information about the stack group. (51 Q's in system 110). Much of this state information corresponds to the internal registers of the processor, such as "M-AP" (the Argument Pointer) or "A-IPMARK" (the pointer to the most recent open frame). When a Stack Group is "RESUMED", this means that the saved register state is restored to the processor and computation proceeds where it left off. When a Stack Group RESUMES another Stack Group ("SG", hereafter), it stores away its current state before the upcoming SG is restored. =Node: stack-group-structure =Text: The accessors to this leader are defined as a defstruct, (look at SYS:SYS2;SGDEFS) but the :CONSTRUCTOR argument is NIL and so no MAKE-STACK-GROUP function is defined. Instead, the function is defined manually so that it includes the construction of the two associated arrays, the REGULAR-PDL and the SPECIAL-PDL. (see SYS:SYS;SGFCTN). These arrays also have special array types, ART-REG-PDL and ART-SPECIAL-PDL respectively. They both have large data areas and leaders with only one element. In both cases, that element is a pointer back to the STACK-GROUP which owns them. Furthermore, these arrays are both consed in special areas, the REG-PDL-AREA and the SPECIAL-PDL-AREA (MAKE-STACK-GROUP takes arguments which purport to specify the areas for these structures to be consed, but at the moment, these arguments are ignored). The STACK-GROUP itself defaults to the DEFAULT-CONS-AREA, but the area may be specified at creation time. The two PDLs, or stacks, are for storing the call sequence and the binding environment for the SG. The REGULAR-PDL holds entries called CALL-BLOCKS, or frames, which control the call-return sequence for the SG. The SPECIAL-PDL stores special variable bindings which are lexically shadowed by functions called inside the SG. As those functions return, the SPECIAL-PDL is popped and the values are restored to the special variables. Some important keyword arguments to MAKE-STACK-GROUP are: :SG-AREA which defaults to default-cons-area :REGULAR-PDL-SIZE default is #o3000 :SPECIAL-PDL-SIZE default is #o2000 (which is apparently so large because of flavor objects.) :TRAP-ENABLE Causes machine to halt on error for values of nil or 0. Default is t, which means enter the error handler :SAFE nil or 0 allows stack group switching in any order, 1 or t, standard call-return sequence is imposed Some slots in the Stack Group Leader: SG-REGULAR-PDL Regular PDL array, 0=base of stack SG-REGULAR-PDL-LIMIT Max depth before trap - set to be 64 less than regular-pdl-size SG-SPECIAL-PDL Special PDL array, 0=base of stack SG-SPECIAL-PDL-LIMIT Max depth before trap - set to be 32 less than special-pdl-size SG-NAME The stack-group stores its name as a string SG-INITIAL-FUNCTION-INDEX A stack group always has an "Initial Function" at the base of the REGULAR-PDL. The leader has a slot to indicate the index into the Regular PDL of the initial Argument-Pointer (M-AP). This will usually be 3 because.... SG-PLIST SG-TRAP-TAG Symbolic tag corresponding to SG-TRAP-MICRO-PC. gotten via MICROCODE-ERROR-TABLE, etc. Properties of this symbol drive error recovery. SG-RECOVERY-HISTORY Available for hairy SG munging routines to attempt to leave tracks. SG-FOOTHOLD-DATA During error recovery, contains pointer to a stack frame which contains saved status of the main stack group. (Preventing it from being lost when the foothold is running.) SG-STATE (Stack group state field values from COLD;QCOM) SG-ST-CURRENT-STATE 0006 40----------------------------0 !-tag-!-------------------111111 SG-ST-PROCESSING-ERROR 0701 40----------------------------0 !-tag-!-----------------1------- SG-ST-SAFE 1101 (initialized by :safe keyword) 40----------------------------0 !-tag-!---------------1--------- SG-ST-INST-DISP 1202 40----------------------------0 !-tag-!-------------11---------- SG-ST-IN-SWAPPED-STATE 2601 40----------------------------0 !-tag-!--1---------------------- The next two flags control resumtion of another stack group at call time SG-ST-SWAP-SV-ON-CALL-OUT 2501 (initialized by keyword) 40----------------------------0 !-tag-!---1--------------------- SG-ST-SWAP-SV-OF-SG-THAT-CALLS-ME 2401 (initialized by keyword) 40----------------------------0 !-tag-!----1-------------------- ASSIGNED BUT NOT USED !! SG-ST-FOOTHOLD-EXECUTING 0601 40----------------------------0 !-tag-!------------------1------ SG-ST-PROCESSING-INTERRRUPT-REQUEST 1001 40----------------------------0 !-tag-!----------------1-------- UNUSED, UNASSIGNED 1410 40----------------------------0 !-tag-!-----11111111------------ =Node: stack-group-illustration =Function: (get-gi "lad:dexter.illos;stack-group") =Text: hyper-super-x to see diagram =Node: CLOSURE-ILLUSTRATION =Function: (get-gi "lad:dexter.illos;closure") =Text: hyper-super-x to get diagram =Node: investigation =Text: Knowledge about system internals is contained in a variety of places. The file SYS:COLD;QCOM.LISP defines most of the bit fields of the machines data structures and their values. describesou can read this file into ZMACS and search for substrings having to do with what you're looking for with the control-S editor command. If you know that the subject of your study is written in LISP then there are a number of useful editor funstions which can be used to find definitions. Meta-. (Meta period) will find definitions which were made using DEFUN, DEFFLAVOR, DESTRUCT, DEFVAR etc. There are a number of ZMACS extended commands which are used to find flavor method definitions. They are "Meta X Edit Combined Methods" Allows to to successively edit each of the methods which will execute when an instance of the type you specify receives a message which you specify. "Meta X Edit Flavor Methods" Allows you to sucessively edit all of the methods defined for a specific flavor. "Meta X Edit Methods" Edit the all methods for the specified message for all flavors which implement the message. =Node: microcode investigation =Text: If what you're looking for might be implemented in the microcode then the above editor commands will be of little use to you. You can do a string search of microcode by first setting up a tag table. To do this use the editor command "Meta-X Select System As Tag Table" for the system LAMBDA-UCODE. You can then use the command "Meta-X Tag Search" to find strings in the microcode. Some coding conventions: Symbol names beginning with a percent sign are usually part of the system internals. Many percent-named functions are implemented in microcode (eg %P-LDB-OFFSET). Symbol names which begin with two percent signs have a values which is a byte specifier. A byte specifier is a number which describes an arbitrary bit field in a number or a wrod of storage. The least significant six bits of the byte specifier determine the width of the bit field and the higher bits describe how many bits to the left from the least significant bit (bit 0) the least significant bit of the field is at. For example, the byte specifier %%Q-DATA-TYPE has the value #o3105 (as defined in the file QCOM). This field is 5 bits wide and starts at bit 25 (31 octal). This filed thus occupies bits 25 through 29. =Node: arrays =Text: The format of an array as stored on the LAMBDA has a large number of variations. Arrays can be considered to have three parts, the header, the leader and the data. The leader and data parts are optional. All arrays have a header (whos length varies) which describes how the array is structured and how to reference it. The first header word is of type DTP-ARRAY-HEADER. This header word has many fields which describe how the array is structured and how to interpret the rest of the header information. The fields in the first header word (and their definitions) are %%Q-DATA-TYPE 3105 ;;; contains DTP-ARRAY-HEADER what about bit 3001 %%ARRAY-TYPE-FIELD 2305 ;;; type of array %%ARRAY-LEADER-BIT 2101 ;;; set if array has a leader %%ARRAY-DISPLACED-BIT 2001 ;;; %%ARRAY-FLAG-BIT 1701 ;;; what's this for? %%ARRAY-NUMBER-DIMENSIONS 1403 ;;; %%ARRAY-LONG-LENGTH-FLAG 1301 ;;; %%ARRAY-NAMED-STRUCTURE-FLAG 1201 ;;; %%ARRAY-INDEX-LENGTH-IF-SHORT 0012 ;;; number of elements of array if ;;; fewer than %ARRAY-MAX-SHORT-INDEX-LENGTH 1777 The %%ARRAY-TYPE-FIELD describes the type of the array. It may be any one of ART-ERROR ART-1B ART-2B ART-4B ART-8B ART-16B ART-32B ART-Q ART-Q-LIST ART-STRING ART-STACK-GROUP-HEAD ART-SPECIAL-PDL ART-HALF-FIX ART-REG-PDL ART-FLOAT ART-FPS-FLOAT ART-FAT-STRING ART-COMPLEX-FLOAT ART-COMPLEX ART-COMPLEX-FPS-FLOAT. These describe how to interpret the data portion of the array. The %%ARRAY-LEADER-BIT is set if the array has a leader. If the array has a leader, the words of the leader immediately precede the header words of the array. The leader occupies two more words than the leader length. The very first word of the leader is the leader header word which is data type DTP-HEADER, has %%HEADER-TYPE-FIELD %HEADER-TYPE-ARRAY-HEADER and has the leader total size stored in the %%LEADER-LENGTH field. The leader total size is allways two more than the leader length. Then follow the actual leader data words. After the leader data words is a fixnum which contains the leader length. Immediately following this leader length fixnum is the array header. Elements of the leader are stored in last elemtnt first order. The last leader element is the one immediately following the leader header word. The %%ARRAY-DISPLACED-BIT is set if the array is a displaced array. A displaced array does not have its own data. It is used to refer to the data of another array, possibly imposing a different interpretation on the data that that of the array it is displaced to. The %%ARRAY-NUMBER-DIMENSIONS field contains the number of dimensions of the array. This number must be strictly less than ARRAY-RANK-LIMIT. Note that it is possible to have a zero dimensional array. A zero dimensional array has a single element. The %%ARRAY-LONG-LENGTH-FLAG bit is used in conjunction with the %%ARRAY-INDEX-LENGTH-IF-SHORT field. For a non-displaced array the index length (total number of elements) of the array is stored in the %%ARRAY-INDEX-LENGTH-IF-SHORT field unless it is strictly greater than %ARRAY-MAX-SHORT-INDEX-LENGTH. If this is the case then the index length is stored in the second header word and %%ARRAY-LONG-LENGTH-FLAG is set. For a displaced array,%%ARRAY-MAX-SHORT-INDEX-LENGTH contains the number of header words used to store the displacement information. this is 2 if the array does not have a displaced index offset. Otherwise it is 3. This is OK since there is no data portion allocated for displaced arrays. This indicates the number of header words used to describe where the array is displaced to. These words follow those where the dimensions are stored. Then follow the dimensions of the array, except for the first one which seems to be implicit from the index length. The dimensions are stored such that the last dimension of the dimension list passed to make-array is stored first. If the array is a displaced array then after the dimensions are two or three words, as indicated by the %%ARRAY-MAX-SHORT-INDEX-LENGTH field. The first is the place where the array is dislpaced to. The second is the index length describing how much of the data in the target array should be considered as part of this array. The third contains the displaced-index-offset, if there is one. If the array is a named structure then leader element 1 stores the named structure symbol. If the array has no leader then the named structure symbol is stored in element 0 of the array. A one dimensional array that has a leader can have a fill pointer. The fill pointer is stored as a fixnum in leader element zero. If leader element zero is a fixnum (for a one dimensional array) it is assumed to be the fill pointer. There is no other indication of whether the array has a fill pointer or not. =Node: lambda main data paths =Function: (get-gi "lad:dexter.illos;lambda-main-data-paths") =Text: hyper-super-x for diagram =Node: interpreter closure illustration =Function: (get-gi "lad:dexter.illos;interpreter-closures") =Text: hyper-super-x for diagram