.title Entrap .ident *03.00* ;+ ; TITLE: ENTRAP - AST / SST INTERFACE AND AUTOLOAD ; CONTEXT PRESERVATION ROUTINE ; VERSION: 03.00 ; SYSTEM: COMMON DEC ; SUBSYSTEM: SYSTEM LIBRARIES ; ENTRY POINT: ENTRAP ; SOURCE FILE: ENTRAP.MAC ; SOFTWARE TREE: ZSYSLB.STS ; PROGRAMMER: Wayne E. Baisley ; DATE: April 13, 1982 ; ; REVISION DATE PROGRAMMER DESCRIPTION ; -------- -------- -------------- ----------------------------- ; ; 1) WB100 02/02/83 W. E. Baisley To fix OVMAP to work if the ; calling task isn't overlaid ; ; 2) WB120 06/05/84 W. E. Baisley Completely new release based on ; RSX-11M V4.1 / M-Plus V2.1, which ; uses the Autoload Cluster Library ; support code. ; ; NOTES: ; ; Entrap performs two functions on behalf of AST and SST service routines : ; ; 1) It provides a subroutine interface for trap service routines written ; in C. This means that it preserves registers 0 and 1 (C routines are ; expected to preserve the remainder), calls the routine, cleans up the ; stack, and returns in the manner appropriate for the type of trap. ; Entrap sets up the calling stack frame for the service routine as ; though it had been called directly with the following argument list : ; ; ast_serv (r0, r1, code, [ast-specific parameters,] dsw, pc, psw, efmw); ; ; sst_serv (r0, r1, code, [sst-specific parameters,] pc, psw); ; ; The "code" argument is copied from the AST / SST transfer vector ; discussed below. See Section 2.3 of the RSX-11M/M-Plus Executive ; Reference Manual for information on the trap-specific parameters. ; ; The r0, r1, dsw, pc, psw, and efmw (event flag mask word) parameters ; are the actual saved values of those items from just prior to the ; trap. Don't even think about modifying these arguments. ; ------------------------------------------------ ; ; 2) It preserves the overlay context for tasks which are overlaid. This ; allows the trap service routine to be overlaid and/or to call routines ; which are overlaid (in a memory-resident overlaid library, for example). ; .page ; ; Entrap is called from an AST or SST transfer vector set up by the ; calling program. The transfer vector has the following format: ; ; +-------------------------------+ ; 0 | | ; +-- JSR R1,@#ENTRAP --+ ; 2 | | ; +-------------------------------+ ; 4 | Number Of Items On Trap Stack | * (See Note, Below) ; +-------------------------------+ ; 6 | AST/SST Routine Entry Address | ; +-------------------------------+ ; ; For tasks with separate I-(nstruction) and D-(ata) Spaces, the format is : ; ; +-------------------------------+ ; 0 | MOV R1,-(SP) | ; +-------------------------------+ ; 2 | MOV (PC)+,R1 | ; +-------------------------------+ ; 4 | Address of D-Space Portion | I-Space Portion ; +-------------------------------+ ; 6 | | ; +-- JMP @#ENTRAP --+ ; 10 | | ; +-------------------------------+ ; ; +-------------------------------+ ; 0 | Number Of Items On Trap Stack | * ; +-------------------------------+ D-Space Portion ; 2 | AST/SST Routine Entry Address | ; +-------------------------------+ ; ; Inputs: ; ; r1 =Address of the data portion of the trap vector ; 0(sp)=Saved r1 contents ; 2(sp)=Remainder of AST / SST stack (depends on the type of trap) ; ; Outputs: ; ; Sets the AST / SST clustering flag and transfers to the specified AST / SST ; service routine. Upon re-entry it cleans up the stack and effects an AST ; or SST exit. ; ; * - Note: ; ; The "Number Of Items On Trap Stack" element (1st word in the data portion) ; must be initialized with care. For an AST, it is the number of excess ; trap-specific parameters. That is, the number does not include the 4 ; common AST stack words ($DSW, PC, PS, Event Flag Mask Word). For an SST, ; the value is the negative of the total number of words on the stack, ; including the 2 common SST stack words (PC, PS). See Section 2.3 of the ; RSX-11M/M-Plus Executive Reference Manual. ; .page ; ; For programs without I- and D-Space separation, the transfer vector ; can be expressed in a C structure as follows : ; ; typedef struct { ; int JSR_R1; /* the actual command to call routine */ ; int (*entrap)(); /* the routine to be called */ ; int count; /* the number of "active" arguments */ ; int (*srvrtn)(); /* user defined subroutine */ ; } TRAP_VECTOR; ; ; A QIOW AST vector is then initialized as follows : ; ; static TRAP_VECTOR qiow_ast = { 04137, &entrap, 1, &ast_routine }; ; ; Alternatively, the vector can be set up in MACRO-11. This example can handle ; tasks with separate I- and D-Spaces. ; ; .MACRO TRPVEC SRVRTN,COUNT,DSECT ; .IF B ; jsr r1,@#entrap ;transfer to entrap ; .IFF ; .save ;save the current psect settings ; .psect DSECT,d ; $$$ = . ;address of the data portion ; .IFTF ; .word COUNT ;system trap stack code word ; .word SRVRTN ;trap service routine addr ; .IFF ; .restore ;restore psect settings ; mov r1,-(sp) ;save R1's contents ; mov #$$$,r1 ;load address of the data portion ; jmp @#entrap ;transfer to entrap ; .ENDC ; .ENDM TRPVEC ; ; The examples which follow show the macro's use in setting up a memory-protect SST ; vector, and an FPP Exception AST vector for a task with separate I- and D-Spaces. ; ; V$MPRO: TRPVEC MEMSST,-5 ;SET UP THE MEMORY-PROTECT SST ROUTINE VECTOR ; JSR R1,@#ENTRAP ; .WORD -5 ; .WORD MEMSST ; ; V$FPPX: TRPVEC FPXAST,2,DATA ;SET UP THE FPP EXCEPTION AST ROUTINE VECTOR ; .SAVE ; .PSECT DATA,D ; $$$ = . ; .WORD 2 ; .WORD FPXAST ; .RESTORE ; MOV R1,-(SP) ; MOV #$$$,R1 ; JMP @#ENTRAP ; .page ; ; Entrap and the autoload overlay routines accomplish their overlay context ; maintenance operations by means of a push-down stack which is an extension ; to the overlay work area. The Segment Stack area, located in the $$STCK ; psect, has the structure : ; ; +-------------------------------+ <- .nstlm ; | Empty | ; +-------------------------------+ ; . ; . ; . ; +-------------------------------+ ; | Nth Pair Of Words Of | <- .nstpt, while running ; +--- Saved Segment ---+ ; | Descriptor & Return Addrs | ; +-------------------------------+ ; . ; . ; . ; +-------------------------------+ ; | 1st Pair Of Words Of | ; +--- Saved Segment ---+ ; | Descriptor & Return Addrs | ; +-------------------------------+ <- .nstpt, initially ; ; As each AST or SST transfers to Entrap, the N.CAST flag in the Overlay Impure ; Data Area is set, which causes any overlay operations incurred by the AST or SST ; routine (and any subroutines they call) to revert to the original state when the ; routine(s) return. The N.CAST flag is then reset. The mechanism used is the same ; as that used by the Cluster Library facility. The effect is to make the AST / SST ; action invisible to the task as far as overlays are concerned. Two exceptions to ; this otherwise happy arrangement should be noted. The more serious of the two is ; that Entrap cannot restore impure data which occupies disk-resident overlays; it ; can merely cause the overlay to be reloaded, so avoid overlay arrangements where ; AST and SST routines can preempt such segments. The less serious side-effect of ; Entrap's action is that any overlay segments mapped by the AST / SST service ; routine which are higher than but along the same path as the original mapping are ; not unmapped when the service routine exits. This should cause no problems, but ; is a "visible" difference. ; ; The Segment Stack area is allocated at assembly time by Exdat, with a default size ; of 12. words. This is sufficient for Cluster Library and overlaid AST/SST calls 6 ; levels deep. Note well that if the Stack overflows your program will be killed via ; an IOT instruction! The Segment Stack area may be enlarged, as in this example : ; ; TKB>extsct=$$stck:20 !make the Segment Stack 16. words long ; .page ; ; The work area is located in the $$OVDT psect and is structured as follows : ; ; +-------------------------------+ ; 0 | Overlay Load LUN | .novly, n.ovly * ; +-------------------------------+ ; 2 | Address of First Segment Desc | .nstbl, n.stbl + ; +-------------------------------+ ; 4 | Overlay Load | .niost, n.iost ; +--- I/O ---+ ; 6 | Status Block | ; +-------------------------------+ ; 10 | Overlay Load Error Subroutine | .naler, n.aler + ; +---------------+---------------+ ; 13, 12 | AST Interlock | Seg Desc Size | .nfast, n.fast @ .nszsg, n.szsg * ; +---------------+---------------+ ; 14 | Load and Map Segment Routine | .nrdsg, n.rdsg + ; +-------------------------------+ ; 16 | Unmap Segment(s) Routine | .nmrks, n.mrks + ; +-------------------------------+ ; 20 | Displaced Seg Desc Tmp Storage| .ndtds, n.dtds ; +-------------------------------+ ; 22 | Autoload Routine | .nauto, n.auto + ; +---------------+---------------+ ; 25, 24 | Unused |AST Cluster Flg| .ncast, n.cast ! ; +---------------+---------------+ ; 26 | Top Address Of Segment Stack | .nstlm, n.stlm ! ; +-------------------------------+ ; 30 | Segment Stack Pointer | .nstpt, n.stpt ! ; +-------------------------------+ ; ; * - The Overlay Load LUN and the Segment Descriptor Size words are filled ; in by the Task Builder. The Segment Descriptor size is 6, 8, or 9 ; words long, depending on whether manual loading and memory-resident ; overlays are used. The Task Builder Automatically allocates a Logical ; Unit, assigns the load device to it, and fills in the number. ; ; + - The address of the first Segment Descriptor, and the addresses of ; the Overlay Load Failure, Load and Map Segment, Unmap Conflicting ; Segment(s), and Autoload Routines are filled in at assembly time ; by the Ovdat module. ; ; @ - The AST Interlock flag byte is initialized by the Exdat module since ; AST interlocking is required (Task-Builder Manual V4.1, Section 4.5). ; ; ! - The Top Address of Segment Stack and Segment Stack Pointer are filled ; in and the Segment Stack area is allocated at assembly time by the ; module Exdat. These optional words are present only if the module ; Exdat is included in your task, either implicitly because of Entrap's ; references, or explicitly in the Task-Build command file ; (I.e., lb:[1,1]syslib/lb:exdat). ;- .nlist toc .page .sbttl \in-'trap\ vt : to lure into a compromising statement or act .enabl mcl alodf$ ; Define the segment descriptor symbols exddf$ ; Define the extended overlay work area symbols .globl $marke ; Force the Autoload AST/SST support code to load .globl .ndtds ; Force the data area extensions to load .list meb .psect $$resl ro Entrap:: mov r0,-(sp) ; Save r0 (r1 has already been saved) mov (r1)+,-(sp) ; Set up the stack code word mov (r1),-(sp) ; Obtain the service routine address mov @#n.ovpt,r1 ; Get the overlay work area address beq 20$ ; If eq we aren't overlaid ! incb n.cast(r1) ; Set the AST/SST "cluster" flag 20$: call @(sp)+ ; Call the user's service routine mov @#n.ovpt,r1 ; Get the overlay work area address again beq 40$ ; If eq we aren't overlaid ! decb n.cast(r1) ; Reset the AST/SST "cluster" flag 40$: mov 2(sp),r0 ; Restore r0 mov 4(sp),r1 ; Restore r1 asl (sp) ; Convert the code word to a byte count bge 60$ ; If ge the byte count is non-negative, do an AST exit sub (sp),sp ; Fix the SST stack tst (sp)+ ; Finish the clean-up rti ; Exit the SST (or, failing that, make an existential leap) 60$: add (sp),sp ; Fix the AST stack add #6,sp ; Finish the clean-up astx$s ; Exit from the AST ; ; Otherwise, all hell breaks loose ; iot .end