.TITLE FERMI_SYS_DISP Fermilab System Service Dispatchers .IDENT /V01.01/ ; ;**************************************************************************** ;* * ;* COPYRIGHT (c) 1980 * ;* BY DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. * ;* * ;* THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED * ;* ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE * ;* INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER * ;* COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY * ;* OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY * ;* TRANSFERRED. * ;* * ;* THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE * ;* AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT * ;* CORPORATION. * ;* * ;* DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS * ;* SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. * ;* * ;**************************************************************************** ; ;++FERMIDISP.MAR ; ; Facility: ; Fermilab Accelerator Control System - ACNET. ; General user-written system services image (FERMIUSS). ; ; Abstract: ; This module contains the dispatcher for user-written system services. ; ; Overview: ; User written system services are contained in privileged shareable ; images that are linked into user program images in exactly the ; same fashion as any shareable image. The creation and installation ; of a privileged, shareable image is slightly different from that ; of an ordinary shareable image. These differences are: ; ; 1. A vector defining the entry points and providing other ; control information to the image activator. This vector ; is a the lowest address in an image section with the VEC ; attribute. ; ; 2. The shareable image is linked with the /PROTECT option ; that marks all of the image sections so that they will ; protected and given EXEC mode ownership by the image ; activator. ; ; 3. The shareable image MUST be installed /SHARE /PROTECT ; with the INSTALL utility in order for the image activator ; to connect the privileged shareable image to the change mode ; dispatchers. ; ; A privileged shareable image implementing user written system services ; is comprised of the following major components: ; ; 1. A transfer vector containing all of the entry points and ; collecting them at the lowest virtual address in the ; shareable image. This formalism enables revision of the ; shareable image without necessitating the relinking of ; images that use it. ; ; 2. A Privileged Library Vector in a PSECT with the VEC ; attribute that describes the entry points for dispatching ; EXEC and KERNEL mode services along with validation ; information. ; ; 3. A dispatcher for kernel mode services. This code will ; be called by the VMS change mode dispatcher when it ; fails to recognize a kernel mode service request. ; ; 4. A dispatcher for executive mode services. This code will ; be called by the VMS change mode dispatcher when it fails ; to recognize an executive mode service request. ; ; 5. Service routines to perform the various services. ; ; The first four components are contained in this module and are ; most easily implemented in MACRO, while the service routines can ; be implemented in BLISS or MACRO. Other languages may be usable ; but are not recommended -- particularly if they require runtime ; support routines or are extravagant in their use of stack or are ; unable to generate PIC code. ; ;-- ; ; Link Command File Example: ; ; $! ; $! Command file to link User System Service example. ; $! ; $ LINK/PROTECT/NOSYSSHR/SHARE=USS/MAP=USS/FULL SYS$INPUT/OPTIONS ; ! ; ! Options file for the link of User System Service example. ; ! ; service-files,... ; SYS$SYSTEM:SYS.STB/SELECTIVE ; ! ; ! Create a separate cluster for the transfer vector. ; ! ; CLUSTER=TRANSFER_VECTOR,,,SYS$DISK:[]USSDISP ; ! ; GSMATCH=LEQUAL,4,1 ; ; ; Modification History: ; ; This dispatcher originally came from the example provided by DEC in ; [SYSHLP.EXAMPLES] along with sample system service routines. ; ; V01.00 14-May-83 FJN Created from ACNETUSS to provide general ; (non-network) system services. ; V01.01 16-May-83 FJN Changes from May'83 VAX System Dispatch so ; HLL's which think (SP)=(FP) will function ; .PAGE .SUBTITLE Declarations and Equates ; ; Include Files ; .LIBRARY "SYS$LIBRARY:LIB.MLB" ; Macro library for system structure ; definitions .LIBRARY "SYS$LIBRARY:FERMILIB.MLB" ;Fermilab macro library ; ; Macro Definitions ; ; DEFINE_SERVICE - A macro to make the appropriate entries in several ; different PSECTs required to define an EXEC or KERNEL ; mode service. These include the transfer vector, ; the case table for dispatching, and a table containing ; the number of required arguments. ; ; DEFINE_SERVICE Name,Number_of_Arguments,Mode ; .MACRO DEFINE_SERVICE,NAME,NARG=0,MODE=KERNEL .PSECT $$$TRANSFER_VECTOR,PAGE,NOWRT,EXE,PIC,SHR .ALIGN QUAD ;Align entry points for speed and style .TRANSFER NAME ;Define name as universal symbol for ; entry point. .MASK NAME ;Use entry mask defined in main routine .IF IDN MODE,KERNEL CHMK # ;Change to kernel mode and execute RET ;Return KERNEL_COUNTER=KERNEL_COUNTER+1 ;Advance counter .PSECT KERNEL_NARG,BYTE,NOWRT,EXE,PIC,SHR .BYTE NARG ;Define number of required arguments .PSECT USER_KERNEL_DISP1,BYTE,NOWRT,EXE,PIC,SHR .WORD 2+NAME-KCASE_BASE ;Make entry in kernel mode CASE table .IFF CHME # ;Change to executive mode and execute RET ;Return EXEC_COUNTER=EXEC_COUNTER+1 ;Advance counter .PSECT EXEC_NARG,BYTE,NOWRT,EXE,PIC,SHR .BYTE NARG ;Define number of required arguments .PSECT USER_EXEC_DISP1,BYTE,NOWRT,EXE,PIC,SHR .WORD 2+NAME-ECASE_BASE ;Make entry in exec mode CASE table .ENDC ; .ENDM DEFINE_SERVICE ; ; ; Equated Symbols ; .NOCROSS $PHDDEF ; Define process header offsets $PLVDEF ; Define PLV offsets and values $PRDEF ; Define processor register numbers $SSDEF ; System service completion codes $PCBDEF ; Process control block offsets $XSC_DEF ; Extended System Common block - ; allocated in VMS pool by XSCINIT ; at system startup $RHB_DEF ; Rundown Block offsets .CROSS ; ; Initialize counters for change mode dispatching codes ; KERNEL_COUNTER=0 ; Kernel code counter EXEC_COUNTER=0 ; Exec code counter ; ; Own Storage ; .PSECT KERNEL_NARG,BYTE,NOWRT,EXE,PIC,SHR KERNEL_NARG: ; Base of byte table containing the ; number of required arguments. .PSECT EXEC_NARG,BYTE,NOWRT,EXE,PIC,SHR EXEC_NARG: ; Base of byte table containing the ; number of required arguments. .PAGE .SUBTITLE Transfer Vector and Service Definitions ;+0Transfer_Vectors ; ; The use of transfer vectors to effect entry to the user written system ; services enables some updating of the shareable image containing them without ; necessitating a re-link of all programs that call them. The PSECT containing ; the transfer vector will be positioned at the lowest virtual address in the ; shareable image and so long as the transfer vector is not re-ordered, ; programs linked with one version of the shareable image will continue to work ; with the next. ; ; Thus as additional services are added to a privileged shareable image, their ; definitions should be added to the end of the following list to ensure that ; programs using previous versions of it will not need to be re-linked. ; To completely avoid relinking existing programs the size of the privileged ; shareable image must not change so some padding will be required to provide ; the opportunity for future growth. ;- .PSECT $$$TRANSFER_VECTOR,PAGE,NOWRT,EXE,PIC,SHR FERMI_TRANSFER: ;Start of transfer vectors ; ; Return contents of the interval timer count processor register. ; DEFINE_SERVICE USER_GETICR,1,KERNEL ; ; Return contents of the time of day processor register ; DEFINE_SERVICE USER_GETODR,1,KERNEL ; ; Declare an AST in another process (external process AST) ; DEFINE_SERVICE USER_DXPAST,5,KERNEL ; ; Declare an image rundown handler for a process. ; DEFINE_SERVICE USER_DCLRDH,1,KERNEL ;============================================================================== ; ; Null executive mode service (until first "real" one is defined) ; DEFINE_SERVICE USER_NULL,0,EXEC ; ; The base values used to generate the dispatching codes should be negative for ; user services and must be chosen to avoid overlap with any other privileged ; shareable images that will be used concurrently. Their definition is ; deferred to this point in the assembly to cause their use in the preceding ; macro calls to be forward references that guarantee the size of the change ; mode instructions to be four bytes. This satisfies an assumption that is ; made by for services that have to wait and be retried. The PC for retrying ; the change mode instruction that invokes the service is assumed to be 4 bytes ; less than that saved in the change mode exception frame. Of course, the ; particular service routine determines whether this is possible. ; KCODE_BASE=-512 ; Base CHMK code value for services ECODE_BASE=-512 ; Base CHME code value for services .PAGE .SUBTITLE Change Mode Dispatcher Vector Block ;+0Change_Mode_Vectors ; ; This vector is used by the image activator to connect the privileged ; shareable image to the VMS change mode dispatcher. The offsets in the vector ; are self-relative to enable the construction of position independent images. ; The system version number will be used by the image activator to verify that ; this shareable image was linked with the symbol table for the current system. ; ; Change Mode Vector Format ; ; +------------------------------------------+ ; ! Vector Type Code ! PLV$L_TYPE ; ! (PLV$C_TYP_CMOD) ! ; +------------------------------------------+ ; ! System Version Number ! PLV$L_VERSION ; ! (SYS$K_VERSION) ! ; +------------------------------------------+ ; ! Kernel Mode Dispatcher Offset ! PLV$L_KERNEL ; ! ! ; +------------------------------------------+ ; ! Exec Mode Entry Offset ! PLV$L_EXEC ; ! ! ; +------------------------------------------+ ; ! User Rundown Service Offset ! PLV$L_USRUNDWN ; ! ! ; +------------------------------------------+ ; ! Reserved ! ; ! ! ; +------------------------------------------+ ; ! RMS Dispatcher Offset ! PLV$L_RMS ; ! ! ; +------------------------------------------+ ; ! Address Check ! PLV$L_CHECK ; ! ! ; +------------------------------------------+ ; ;- .PSECT USER_SERVICE_VECTORS,PAGE,VEC,PIC,NOWRT,EXE,SHR .LONG PLV$C_TYP_CMOD ; Set type of vector to change mode ; dispatcher .LONG SYS$K_VERSION ; Identify system version .LONG KERNEL_DISPATCH-. ; Offset to kernel mode dispatcher .LONG EXEC_DISPATCH-. ; Offset to executive mode dispatcher .LONG USER_RUNDOWN-. ; Offset to rundown handler dispatcher .LONG 0 ; Reserved. .LONG 0 ; No RMS dispatcher .LONG 0 ; Address check - PIC image .PAGE .SUBTITLE Kernel Mode Dispatcher ;+0KERNEL_DISPATCH ; ; Functional Description: ; This routine attempts to handle negative CHMK codes (defined by the ; VMS System kernel mode dispatcher to be user codes). ; ; Input Parameters: ; ; (SP) - Return address if bad change mode value ; ; R0 - Change mode argument value. ; ; R4 - Current PCB Address. (Therefore R4 must be specified in all ; register save masks for kernel routines.) ; ; AP - Argument pointer existing when the change ; mode instruction was executed. ; ; FP - Address of minimal call frame to exit ; the change mode dispatcher and return to ; the original mode. ;- .PSECT USER_KERNEL_DISP0,BYTE,NOWRT,EXE,PIC,SHR KACCVIO: ; Kernel access violation MOVZWL #SS$_ACCVIO,R0 ; Set access violation status code RET ; and return KINSFARG: ; Kernel insufficient arguments. MOVZWL #SS$_INSFARG,R0 ; Set status code and RET ; return KNOTME: RSB ; RSB to forward request KERNEL_DISPATCH:: ; Entry to dispatcher MOVAB W^-KCODE_BASE(R0),R1 ; Normalize dispatch code value BLSS KNOTME ; Branch if code value too low CMPW R1,#KERNEL_COUNTER ; Check high limit BGEQU KNOTME ; Branch if out of range ; ; The dispatch code has now been verified as being handled by this dispatcher, ; now the argument list will be probed and the required number of arguments ; verified. ; MOVZBL W^KERNEL_NARG[R1],R1 ; Get required argument count MOVAL @#4[R1],R1 ; Compute byte count including arg count IFNORD R1,(AP),KACCVIO ; Branch if arglist not readable CMPB (AP),W^[R0] ; Check for required number BLSSU KINSFARG ; of arguments MOVL FP,SP ; Toss unneeded JSB return locations CASEW R0,- ; Case on change mode - ; argument value #KCODE_BASE,- ; Base value # ; Limit value (number of entries) KCASE_BASE: ; Case table base address for ; DEFINE_SERVICE ; ; Case table entries are made in the PSECT USER_KERNEL_DISP1 by ; invocations of the DEFINE_SERVICE macro. The three PSECTS, ; USER_KERNEL_DISP0,1,2 will be abutted in lexical order at link-time. ; .PSECT USER_KERNEL_DISP2,BYTE,NOWRT,EXE,PIC,SHR BUG_CHECK IVSSRVRQST,FATAL ; This should not happen! .PAGE .SUBTITLE Executive Mode Dispatcher ;+0EXEC_DISPATCH ; ; Functional Description: ; This routine attempts to handle negative CHME codes (defined by the ; VMS System executive mode dispatcher to be user codes). ; ; Input Parameters: ; ; (SP) - Return address if bad change mode value ; ; R0 - Change mode argument value. ; ; AP - Argument pointer existing when the change ; mode instruction was executed. ; ; FP - Address of minimal call frame to exit ; the change mode dispatcher and return to ; the original mode. ;- .PSECT USER_EXEC_DISP0,BYTE,NOWRT,EXE,PIC,SHR EACCVIO: ; Exec access violation MOVZWL #SS$_ACCVIO,R0 ; Set access violation status code RET ; and return EINSFARG: ; Exec insufficient arguments. MOVZWL #SS$_INSFARG,R0 ; Set status code and RET ; return ENOTME: RSB ; RSB to forward request EXEC_DISPATCH:: ; Entry to dispatcher MOVAB W^-ECODE_BASE(R0),R1 ; Normalize dispatch code value BLSS ENOTME ; Branch if code value too low CMPW R1,#EXEC_COUNTER ; Check high limit BGEQU ENOTME ; Branch if out of range ; ; The dispatch code has now been verified as being handled by this dispatcher, ; now the argument list will be probed and the required number of arguments ; verified. ; MOVZBL W^EXEC_NARG[R1],R1 ; Get required argument count MOVAL @#4[R1],R1 ; Compute byte count including arg count IFNORD R1,(AP),EACCVIO ; Branch if arglist not readable CMPB (AP),W^[R0] ; Check for required number BLSSU EINSFARG ; of arguments MOVL FP,SP ; Toss unneeded JSB return locations CASEW R0,- ; Case on change mode - ; argument value #ECODE_BASE,- ; Base value # ; Limit value (number of entries) ECASE_BASE: ; Case table base address for ; DEFINE_SERVICE ; ; Case table entries are made in the PSECT USER_EXEC_DISP1 by ; invocations of the DEFINE_SERVICE macro. The three PSECTS, ; USER_EXEC_DISP0,1,2 will be abutted in lexical order at link-time. ; .PSECT USER_EXEC_DISP2,BYTE,NOWRT,EXE,PIC,SHR BUG_CHECK IVSSRVRQST,FATAL ; This should not happen! .PAGE .SUBTITLE Image Rundown Handler "Dispatcher" ;+0USER_RUNDOWN ; ; Function Description: ; This service is invoked from within the kernel mode system service ; that performs image rundown (SYS$RUNDWN). It is invoked before any ; system rundown functions (i.e. deassign channels, release memory) are ; performed. User code should not invoked any RMS services or RTL ; routines, must not signal any exceptions. User code can invoke ; most system services execpt those that use RMS (e.g. $PUTMSG). ; ; This image rundown handler uses some ACNET network features. The ; eXtended System Common block (in VMS nonpaged pool) contains the ; address of a longword array which contains the head of the linked ; list of the rundown blocks declared by USER_DCLRDH for each process. ; If this address is non-zero, the list is unlinked (zero is stored ; in the array) block by block and the individual rundown routines ; called. Note that the blocks are processed in opposite order to ; the DCLRDH calls (LIFO queue). ; ; Calling sequence: ; JSB USER_RUNDOWN ; Entered at IPL=0 and must leave at IPL=0. ; ; Input Parameters: ; R4 - Current PCB Address. (Therefore R4 must be specified in all ; register save masks for kernel routines.) ; R7 - Access mode parameter to $RUNDWN maximized with previous mode ; AP - Argument pointer existing when the $RUNDWN system ; service was invoked. ; 4(AP) - Access mode parameter to $RUNDWN ; ;- .PSECT USER_RUNDOWN_HANDLER,BYTE,NOWRT,EXE,PIC,SHR USER_RUNDOWN:: MOVL G^EXE$GL_SITESPEC,R0 ;Get address of XSC block BEQL 29$ ;Is there an XSC block? MOVZWL PCB$L_PID(R4),R1 ;Get process index from pid in PCB PUSHL R2 ;Save register (use as list head) MOVAL @ACN_L_RUNDWNLST(R0)[R1],R0 ;Address of list head in array MOVL (R0),R2 ;Get address of 1st block in list BEQL 19$ ;If no list, exit CLRL (R0) ;Clear array entry and process list ; ; R2 now points to block at top of rundown block list. ; 10$: MOVL R2,R1 ;Get address of rundown block MOVL RHB_L_LINK(R1),R2 ;Advance list pointer to next block MOVL RHB_L_ENTRY(R1),R0 ;Get address of rundown routine BEQL 15$ ;If none, ignore this block CALLG RHB_L_ARGLST(R1),(R0) ;Call rundown routine with arguments 15$: TSTL R2 ;Check for another block on list BNEQ 10$ ;If more, continue processing 19$: POPREG R2 ;Restore register 29$: RSB ;And return to VMS rundown handler .END