OpenVMS VAX Device Support Reference Manual Order Number: AA–PWC9A–TE March 1994 This manual provides the reference material for the OpenVMS VAX Device Support Manual, which describes how to write a driver for a device connected to a VAX processor. This manual describes the data structures, macros, and routines used in device driver programming. Revision/Update Information: This manual supersedes the OpenVMS VAX Device Support Reference Manual, Version 6.0. Software Version: OpenVMS VAX Version 6.
March 1994 Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.
Send Us Your Comments We welcome your comments on this or any other OpenVMS manual. If you have suggestions for improving a particular section or find any errors, please indicate the title, order number, chapter, section, and page number (if available). We also welcome more general comments. Your input is valuable in improving future releases of our documentation. You can send comments to us in the following ways: OPENVMSDOC@ZKO.MTS.DEC.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii 1 Data Structures 1.1 1.2 1.3 1.4 1.5 1.5.1 1.6 1.7 1.7.1 1.8 1.9 1.10 1.11 1.12 1.13 1.14 1.15 1.16 1.17 1.18 1.19 Configuration Control Block (ACF) . . . . . . . . . . . . Adapter Control Block (ADP) . . . . . . . . . . . . . . . . . Channel Control Block (CCB) . . . . . . . . . . . . . . . . Per-CPU Database (CPU) . . . . . . . . . . . . . . . . . . .
DSBINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . ENBINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . $EQULST . . . . . . . . . . . . . . . . . . . . . . . . . . FIND_CPU_DATA . . . . . . . . . . . . . . . . . . . . FORK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FORKLOCK . . . . . . . . . . . . . . . . . . . . . . . . . FORKUNLOCK . . . . . . . . . . . . . . . . . . . . . . FUNCTAB . . . . . . . . . . . . . . . . . . . . . . . . . . IFNORD, IFNOWRT, IFRD, IFWRT . .
SPI$SEND_COMMAND . . . . . . . SPI$SENSE_PHASE . . . . . . . . . . SPI$SET_CONNECTION_CHAR . SPI$SET_PHASE . . . . . . . . . . . . . SPI$UNMAP_BUFFER . . . . . . . . SWAPLONG . . . . . . . . . . . . . . . . . SWAPWORD . . . . . . . . . . . . . . . . TIMEDWAIT . . . . . . . . . . . . . . . . TIMEWAIT . . . . . . . . . . . . . . . . . UNLOCK . . . . . . . . . . . . . . . . . . . UNLOCK_SYSTEM_PAGES . . . . $VEC . . . . . . . . . . . . . . . . . . . . . . $VECEND . . . . . . . . . . . . . . . . . . $VECINI . .
EXE$QIODRVPKT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXE$QIORETURN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXE$READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXE$READCHK, EXE$READCHKR . . . . . . . . . . . . . . . . . . . . . . EXE$READLOCK, EXE$READLOCKR . . . . . . . . . . . . . . . . . . . . EXE$RMVTIMQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXE$SENSEMODE . . . . . . .
IOC$RELXBIMAP . . . . . . . . . . . . . . . . . . IOC$REQALTMA . . . . . . . . . . . . . . . . . . . IOC$REQCOM . . . . . . . . . . . . . . . . . . . . . IOC$REQDATAP, IOC$REQDATAPNW . . IOC$REQMAPREG . . . . . . . . . . . . . . . . . IOC$REQPCHANH, IOC$REQPCHANL, IOC$REQXBIMAP . . . . . . . . . . . . . . . . . . IOC$RETURN . . . . . . . . . . . . . . . . . . . . . IOC$VERIFYCHAN . . . . . . . . . . . . . . . . . IOC$WFIKPCH, IOC$WFIRLCH . . . . . . . LDR$ALLOC_PT . . . . . . . . . . . . . . . . . . .
1–7 1–8 1–9 1–10 1–11 1–12 1–13 1–14 1–15 1–16 1–17 1–18 1–19 1–20 1–21 1–22 1–23 1–24 1–25 1–26 1–27 2–1 2–2 3–1 3–2 Hardware Mailbox Structure . . . . . . . . . . . . . . . . . . . . . . . . . . Control Register Access Mailbox Header (CRAMH) . . . . . . . . . Channel Request Block (CRB) . . . . . . . . . . . . . . . . . . . . . . . . . Interrupt Transfer Vector Block (VEC) . . . . . . . . . . . . . . . . . . . Device Data Block (DDB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1–20 1–21 1–22 1–23 1–24 1–25 1–26 2–1 2–2 2–3 2–4 2–5 2–6 2–7 2–8 2–9 2–10 2–11 2–12 4–1 Contents of the Spinlock Data Structure . . . . . . . . . . . . . . . . . . . UCB Extensions and Sizes Defined in $UCBDEF . . . . . . . . . . . . Contents of Unit Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . UCB Error-Log Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UCB Local Tape Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preface The OpenVMS VAX Device Support Reference Manual provides the reference material for the OpenVMS VAX Device Support Manual, which describes how to write a driver for a device connected to a VAX processor. This manual describes the data structures, macros, and routines used in driver programming. This manual provides information you need to write a device driver that runs under OpenVMS VAX Version 6.1 and to load the driver into the operating system.
• The section on operating system naming conventions in the Guide to Creating OpenVMS Modular Procedures • OpenVMS I/O User’s Reference Manual Other useful information can be found in your processor’s hardware documentation, as well as that in the following documents: • OpenVMS VAX System Dump Analyzer Utility Manual • OpenVMS System Manager’s Manual • VAX/VMS Internals and Data Structures • OpenVMS Delta/XDelta Debugger Manual Conventions In this manual, every use of OpenVMS VAX means the OpenV
boldface text Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason (user action that triggers a callback). Boldface text is also used to show user input in Bookreader versions of the manual. italic text Italic text emphasizes important information and indicates complete titles of manuals and variables.
1 Data Structures This chapter provides a condensed description of those data structures referenced by driver code. It lists their fields in the order in which they appear in the structures. All data structures discussed in this chapter—with the exception of the channel control block (CCB)—exist in nonpaged system memory.
Data Structures Notes Driver code must consider fields marked by asterisks ( * ) to be read-only fields. Fields marked ‘‘Reserved’’ or ‘‘Unused’’ are reserved for future use by Digital unless otherwise specified. When referring to locations within a data structure, a driver should use symbolic offsets, never numeric offsets, from the beginning of the structure. Numeric offsets are likely to change with each new release of the operating system.
Data Structures 1.1 Configuration Control Block (ACF) 1.1 Configuration Control Block (ACF) The configuration control block (ACF) is used by the System Generation utility (SYSGEN) autoconfiguration facility to describe the device it is adding to the system. Device drivers can gain access to this data structure only if they have specified a unit delivery routine in the DPT and only when that routine is executing.
Data Structures 1.1 Configuration Control Block (ACF) Table 1–1 Contents of Configuration Control Block Field Name Contents ACF$L_ADAPTER* Address of ADP for adapter currently being configured. ACF$L_CONFIGREG* Address of configuration register for adapter currently being configured. ACF$W_AVECTOR* Offset from base of SCB to interrupt vector of adapter currently being configured. ACF$B_AUNIT* Adapter unit number of device or controller currently being configured.
Data Structures 1.2 Adapter Control Block (ADP) 1.2 Adapter Control Block (ADP) Each MASSBUS adapter, UNIBUS adapter, Q22–bus, and VAXBI node configured in a VAX system is represented to the operating system and driver routines by an adapter control block (ADP). The ADP stores adapter-specific static and dynamic data such as the adapter CSR address and map-register wait queues.
Data Structures 1.
Data Structures 1.2 Adapter Control Block (ADP) Table 1–2 Contents of Adapter Control Block Field Name Contents ADP$L_CSR* Virtual address of adapter configuration register. For a generic VAXBI adapter, this field contains the address of the base of the adapter’s node space. The system adapter initialization routine writes this field.
Data Structures 1.2 Adapter Control Block (ADP) Table 1–2 (Cont.) Contents of Adapter Control Block Field Name Contents For both types of VAX processor, adapter dispatch table entries that correspond to unused vectors contain the address of the adapter’s unexpected-interrupt service routine. ADP$L_DPQFL* Data path wait queue forward link. IOC$REQDATAP and IOC$RELDATAP read and write this field.
Data Structures 1.2 Adapter Control Block (ADP) Table 1–2 (Cont.
Data Structures 1.2 Adapter Control Block (ADP) Table 1–2 (Cont.) Contents of Adapter Control Block Field Name Contents UNIBUS Adapter Extension ADP$L_MRACTMDRS* Number of active standard map register descriptors in arrays to which ADP$W_MRNREGARY and ADP$W_MRFREGARY point. IOC$REQMAPREG and IOC$RELMAPREG use these fields when allocating and deallocating standard map registers. ADP$W_DPBITMAP* Data path allocation bit map. IOC$REQDATAP and IOC$RELDATAP read and write this field.
Data Structures 1.2 Adapter Control Block (ADP) Table 1–2 (Cont.) Contents of Adapter Control Block Field Name Contents UNIBUS Adapter Extension ADP$L_MR2QBL* Alternate-map-register wait queue’s backward link. IOC$ALOALTMAP, IOC$REQALTMAP, and IOC$RELALTMAP read and write this field when allocating and deallocating from the set of Q22–bus alternate map registers. ADP$L_MR2ACTMDR* Number of active map register descriptors in arrays to which ADP$W_ MR2NREGAR and ADP$W_MR2FREGAR point.
Data Structures 1.3 Channel Control Block (CCB) 1.3 Channel Control Block (CCB) When a process assigns an I/O channel to a device unit with the $ASSIGN system service, EXE$ASSIGN locates a free block among the preallocated channel control blocks (CCBs) of the process. EXE$ASSIGN then writes into the CCB a description of the device attached to the CCB’s channel. The channel control block is the only data structure described in this chapter that exists in the control (P1) region of a process address space.
Data Structures 1.4 Per-CPU Database (CPU) 1.4 Per-CPU Database (CPU) A per-CPU database structure exists for each processor in a multiprocessing environment. The per-CPU database records processor-specific information such as the current process control block (PCB), the priority of the current process, and the physical processor identifier. It points to the processor’s interrupt stack and contains the list heads for the processor’s fork queues and I/O postprocessing queue.
Data Structures 1.
Data Structures 1.
Data Structures 1.4 Per-CPU Database (CPU) Table 1–4 Contents of Per-CPU Database Field Name Contents CPU$L_CURPCB* Address of current PCB. The scheduler writes this field. CPU$L_REALSTACK* Physical address of boot stack. CPU$W_SIZE* Size of the per-CPU database, including the size of the boot stack but not the interrupt stack or the interrupt stack’s guard pages. CPU$B_TYPE* Type of data structure.
Data Structures 1.4 Per-CPU Database (CPU) Table 1–4 (Cont.
Data Structures 1.4 Per-CPU Database (CPU) Table 1–4 (Cont.) Contents of Per-CPU Database Field Name Contents CPU$Q_WORK_FQFL* Work packet queue. This field is also called CPU$Q_WORK_IFQ. CPU$L_QLOST_FQFL* Quorum loss fork queue forward link. CPU$L_QLOST_FQBL* Quorum loss fork queue blink link. CPU$W_QLOST_SIZE* Quorum loss fork block size. CPU$B_QLOST_TYPE* Quorum loss fork block type. CPU$B_QLOST_FLCK* Quorum loss fork lock. CPU$L_QLOST_FPC* Quorum loss fork PC.
Data Structures 1.4 Per-CPU Database (CPU) Table 1–4 (Cont.) Contents of Per-CPU Database Field Name Contents CPU$L_IPL_VEC* Vector recording, in inverse order, the IPLs of all spinlocks currently held by the processor (that is, bit 0 represents IPL 31). CPU$L_IPL_ARRAY* Array of 32 longwords, corresponding in inverse order to the 32 IPLs (that is, the first longword represents IPL 31).
Data Structures 1.5 Control Register Access Mailbox (CRAM) 1.5 Control Register Access Mailbox (CRAM) The control register access mailbox (CRAM) holds information that describes a mailbox I/O access of a control and status register of a device attached to a remote bus. The CRAM contains information required by the software as well as the hardware itself.
Data Structures 1.
Data Structures 1.5 Control Register Access Mailbox (CRAM) Table 1–5 Contents of Control Register Access Mailbox Field Name Contents CRAM$L_FLINK Forward link. Reserved for driver use. CRAM$L_BLINK Backward link. Reserved for driver use. CRAM$W_SIZE* CRAM structure size in bytes. CRAM$B_TYPE* Structure type. Set to DYN$C_MISC when the CRAM is allocated. CRAM$B_SUBTYPE* Structure subtype. Set to DYN$C_CRAM when the CRAM is allocated. CRAM$L_MBPR* Address of mailbox pointer register (MBPR).
Data Structures 1.
Data Structures 1.5 Control Register Access Mailbox (CRAM) Table 1–6 Contents of the Hardware Mailbox Structure Field Name Contents HW_CRAM$L_COMMAND Bus command to the remote I/O interconnect. Specifies either a read or write transaction. The local I/O adapter delivers this command to the remote interconnect to which the target device is connected. The command may also include fields such as address width and data width.
Data Structures 1.6 Control Register Access Mailbox Header (CRAMH) Figure 1–8 Control Register Access Mailbox Header (CRAMH) CRAMH$B_SUBTYPE CRAMH$L_FLINK 0 CRAMH$L_BLINK 4 CRAMH$B_TYPE CRAMH$W_SIZE 8 CRAMH$L_MAX 12 CRAMH$Q_PA_BASE 16 CRAMH$L_AVAIL 24 CRAMH$B_MAP (64 bytes) 28 Unused (36 bytes) 92 *A read-only field Table 1–7 Contents of the Control Register Access Mailbox Header Field Name Contents CRAMH$L_FLINK Forward link.
Data Structures 1.7 Channel Request Block (CRB) 1.7 Channel Request Block (CRB) The activity of each controller in a configuration is described in a channel request block (CRB). This data structure contains pointers to the wait queue of drivers ready to gain access to a device through the controller. The CRB also stores the entry points to the driver’s interrupt service routines and the unit or controller initialization routine.
Data Structures 1.7 Channel Request Block (CRB) CRB$L_BUGCHECK2* 120 CRB$L_RTINTD2* (12 bytes) 124 CRB$L_INTD2* (40 bytes) 136 *A read-only field Table 1–8 Contents of Channel Request Block Field Name Contents CRB$L_FQFL Fork queue forward link. The link points to the next entry in the fork queue. Controller initialization routines write this field when they must drop IPL to utilize certain executive routines, such as those that allocate memory, that must be called at a lower IPL.
Data Structures 1.7 Channel Request Block (CRB) Table 1–8 (Cont.) Contents of Channel Request Block Field Name Contents CRB$L_WQBL* Controller channel wait queue backward link. IOC$REQxCHANy and IOC$RELxCHAN read and write this field. CRB$B_TT_TYPE* Type of controller (for instance, DZ11 or DZ32) for terminals. A terminal port driver fills in this field. CRB$W_REFC* UCB reference count.
Data Structures 1.7 Channel Request Block (CRB) Table 1–8 (Cont.) Contents of Channel Request Block Field Name Contents CRB$L_RTINTD* Portion of interrupt transfer vector created at system initialization when a MicroVAX system implements multilevel device interrupt dispatching. The code stored in this 12-byte field implements a conditional lowering to device IPL. See Section 1.7.1 for a description of the contents of the interrupt transfer vector.
Data Structures 1.
Data Structures 1.7 Channel Request Block (CRB) Table 1–9 (Cont.) Contents of Interrupt Transfer Vector Block (VEC) Field Name Contents VEC$L_INTD* Interrupt dispatching code, written by the driver-loading procedure as follows: PUSHR JSB #^M @# The destination of the JSB instruction is the driver’s interrupt service routine, as indicated at offset VEC$L_ISR.
Data Structures 1.7 Channel Request Block (CRB) Table 1–9 (Cont.) Contents of Interrupt Transfer Vector Block (VEC) Field Name Contents VEC$B_DATAPATH Data path specifier. The bits that make up this field are used as follows: VEC$V_DATAPATH Number of data path used in DMA transfer. The routine IOC$REQDATAP writes this 5-bit field when a buffered data path is allocated and clears the field when the data path is released.
Data Structures 1.7 Channel Request Block (CRB) Table 1–9 (Cont.) Contents of Interrupt Transfer Vector Block (VEC) Field Name Contents VEC$W_MAPALT The following bits are defined within VEC$W_MAPALT: VEC$V_MAPALT Number of first Q22–bus alternate map register allocated to driver that owns controller data channel. IOC$REQALTMAP writes this field when the routine allocates a set of Q22–bus alternate map registers to a driver fork process for a DMA transfer.
Data Structures 1.8 Device Data Block (DDB) 1.8 Device Data Block (DDB) The device data block (DDB) is a block that identifies the generic device-controller name and driver name for a set of devices attached to a single controller. System routines and device drivers refer to the DDB.
Data Structures 1.8 Device Data Block (DDB) Table 1–10 Contents of Device Data Block Field Name Contents DDB$L_LINK* Address of next DDB. A zero indicates that this is the last DDB in the DDB chain. DDB$L_UCB* Address of UCB for first unit attached to controller. DDB$W_SIZE* Size of DDB. DDB$B_TYPE* Type of data structure. The driver-loading procedure writes the constant DYN$C_DDB into this field when the procedure creates the DDB. DDB$L_DDT Address of DDT.
Data Structures 1.
Data Structures 1.9 Driver Dispatch Table (DDT) Table 1–11 Contents of Driver Dispatch Table Field Name Contents DDT$L_START Entry point to the driver’s start-I/O routine. Every driver must specify this address in the start argument to the DDTAB macro. When a device unit is idle and an I/O request is pending for that unit, IOC$INITIATE transfers control to the address contained in this field. DDT$L_UNSOLINT Entry point to a MASSBUS driver’s unsolicited-interrupt service routine.
Data Structures 1.9 Driver Dispatch Table (DDT) Table 1–11 (Cont.) Contents of Driver Dispatch Table Field Name Contents DDT$L_MNTVER Address of the system routine (IOC$MNTVER) called at the beginning and end of mount verification operation. The mntver argument to the DPTAB macro defaults to this routine. Use of the mntver argument to call any routine other than IOC$MNTVER is reserved to Digital. DDT$L_CLONEDUCB Address of routine to call when UCB is cloned. DDT$W_FDTSIZE* Number of bytes in FDT.
Data Structures 1.
Data Structures 1.10 Driver Prologue Table (DPT) Table 1–12 Contents of Driver Prologue Table Field Name Contents DPT$L_FLINK* Forward link to next DPT. The driver-loading procedure writes this field. The procedure links all DPTs in the system in a doubly linked list. DPT$L_BLINK* Backward link to previous DPT. The driver-loading procedure writes this field. DPT$W_SIZE Size in bytes of the driver.
Data Structures 1.10 Driver Prologue Table (DPT) Table 1–12 (Cont.) Contents of Driver Prologue Table Field Name DPT$W_INITTAB Contents DPT$V_TPALLOC Select the tape allocation class parameter. DPT$V_SNAPSHOT Driver is certified for system snapshot. DPT$V_NO_IDB_DISPATCH Do not select IDB$L_UCBLST for UCB vectors. DPT$V_EXTENDED_DDT Do not allocate an extended DDT. DPT$V_XPAMOD Driver is compliant with extended addressing (XA). DPT$V_VERSION_SAFE Driver is exempt from version checks.
Data Structures 1.10 Driver Prologue Table (DPT) Table 1–12 (Cont.) Contents of Driver Prologue Table Field Name Contents The driver-loading procedure compares the name of a driver to be loaded with the values in this field in all DPTs already loaded into system memory to ensure that it loads only one copy of a driver at a time. DPT$Q_LINKTIME* Time and date at which driver was linked, taken from its image header. DPT$L_ECOLEVEL* ECO level of driver, taken from its image header.
Data Structures 1.11 Interrupt Dispatch Block (IDB) Table 1–13 Contents of Interrupt Dispatch Block Field Name Contents IDB$L_CSR* Address of CSR. The SYSGEN command CONNECT specifies the address of a device’s CSR. The driver-loading procedure writes the system virtual equivalent of this address into the IDB$L_CSR field. Device drivers set and clear bits in device registers by referencing all device registers at fixed offsets from the CSR address.
Data Structures 1.11 Interrupt Dispatch Block (IDB) Table 1–13 (Cont.) Contents of Interrupt Dispatch Block Field Name Contents IDB$L_ADP* Address of the adapter’s ADP. The SYSGEN CONNECT command must specify the nexus number of the I/O adapter used by a device. The driverloading procedure writes the address of the ADP for the specified I/O adapter into the IDB$L_ADP field. IDB$L_UCBLST* List of UCB addresses.
Data Structures 1.12 I/O Request Packet (IRP) ! IRP$L_BCNT 48 IRP$W_STS2 .. . 52 , IRP$L_BCNT IRP$L_IOST1 56 IRP$L_IOST2 60 IRP$L_ABCNT 64 IRP$L_OBCNT 68 IRP$L_SEGVBN 72 IRP$L_DIAGBUF* 76 IRP$L_SEQNUM* 80 IRP$L_EXTEND 84 IRP$L_ARB* 88 IRP$L_KEYDESC* 92 Reserved (72 bytes) 96 *A read-only field Table 1–14 Contents of an I/O Request Packet Field Name Contents IRP$L_IOQFL I/O queue forward link.
Data Structures 1.12 I/O Request Packet (IRP) Table 1–14 (Cont.) Contents of an I/O Request Packet Field Name Contents IRP$L_AST* Address of AST routine, if specified by the process in the I/O request. (This field is otherwise clear.) If the process specifies an AST routine address in the $QIO call, EXE$QIO writes the address in this field. During I/O postprocessing, the special kernel-mode AST routine queues a user mode AST to the requesting process if this field contains the address of an AST routine.
Data Structures 1.12 I/O Request Packet (IRP) Table 1–14 (Cont.) Contents of an I/O Request Packet Field Name Contents IRP$W_STS Status of I/O request. EXE$QIO initializes this field to 0. EXE$QIO, FDT routines, and driver fork processes modify this field according to the current status of the I/O request. I/O postprocessing reads this field to determine what sort of postprocessing is necessary (for example, deallocate system buffers and adjust quota usage).
Data Structures 1.12 I/O Request Packet (IRP) Table 1–14 (Cont.) Contents of an I/O Request Packet Field Name Contents IRP$L_BCNT Byte count of the I/O transfer. FDT routines calculate the count value and write the field. IOC$INITIATE copies the low-order word of this field into UCB$W_BCNT before calling a device driver’s start-I/O routine. For a buffered-I/O-read function, I/O postprocessing uses IRP$L_BCNT to determine how many bytes of data to write to the user’s buffer.
Data Structures 1.12 I/O Request Packet (IRP) Table 1–14 (Cont.) Contents of an I/O Request Packet Field Name Contents IRP$L_SEGVBN Virtual block number of the current segment of a virtual I/O transfer. IOC$IOPOST writes this field after a partial virtual transfer. IRP$L_DIAGBUF* Address of a diagnostic buffer in system address space.
Data Structures 1.13 I/O Request Packet Extension (IRPE) IOC$IOPOST automatically unlocks the pages in region 1 (if defined) and region 2 (if defined) for all the IRPEs linked to the IRP undergoing completion processing. IOC$IOPOST also deallocates all the IRPEs. The I/O request packet extension is illustrated in Figure 1–16 and described in Table 1–15.
Data Structures 1.13 I/O Request Packet Extension (IRPE) Table 1–15 Contents of the I/O Request Packet Extension Field Name Contents IRPE$W_SIZE* Size of IRPE. EXE$ALLOCIRP writes the constant IRP$C_LENGTH to this field. IRPE$B_TYPE* Type of data structure. EXE$ALLOCIRP writes the constant DYN$C_IRP to this field. IRPE$W_STS IRPE status field. If bit IRPE$V_EXTEND is set, it indicates that another IRPE is linked to this one.
Data Structures 1.14 Object Rights Block (ORB) Figure 1–17 Object Rights Block (ORB) ! , ORB$W_FLAGS ORB$L_OWNER 0 ORB$L_ACL_MUTEX 4 ORB$B_TYPE* ORB$W_SIZE* ORB$W_REFCOUNT Unused ORB$W_FLAGS 8 .. .
Data Structures 1.14 Object Rights Block (ORB) Table 1–16 Contents of Object Rights Block Field Name Contents ORB$L_OWNER UIC of the object’s owner. ORB$L_ACL_MUTEX Mutex for the object’s ACL, used to control access to the ACL for reading and writing. The driver-loading procedure initializes this field with 0000FFFF16 . ORB$W_SIZE* Size in bytes of ORB. The driver-loading procedure writes the symbolic constant ORB$K_LENGTH into this field when it creates an ORB. ORB$B_TYPE* Type of data structure.
Data Structures 1.14 Object Rights Block (ORB) Table 1–16 (Cont.) Contents of Object Rights Block Field Name Contents ORB$R_MIN_CLASS Minimum classification mask. ORB$R_MAX_CLASS Maximum classification mask. ORB$W_NAME_LENGTH Length of object name. ORB$L_NAME_POINTER Pointer to object name. ORB$L_OCB Pointer to object class block. ORB$L_TEMPLATE_ORB Pointer to template ORB. ORB$L_OBJECT_ SPECIFIC Object class specific usage cell. ORB$L_ORIGINAL_ORB Pointer to another ORB.
Data Structures 1.
Data Structures 1.
Data Structures 1.15 SCSI Class Driver Request Packet (SCDRP) SCDRP$L_PO_STK* (24 bytes) SCDRP$L_TAG* 340 364 368 Reserved (44 bytes) Note that the SCSI-2 data fields begin here.
Data Structures 1.15 SCSI Class Driver Request Packet (SCDRP) Table 1–17 Contents of SCSI Class Driver Request Packet Field Name Contents SCDRP$L_FQFL Fork queue forward link. This field points to the next entry in the SCSI adapter’s command buffer wait queue (ADP$L_BVPWAITFL), map register wait queue (ADP$L_MRQFL), port wait queue (SPDT$L_PORT_WQFL), or system fork queue. SCDRP$L_FQBL Fork queue backward link.
Data Structures 1.15 SCSI Class Driver Request Packet (SCDRP) Table 1–17 (Cont.
Data Structures 1.15 SCSI Class Driver Request Packet (SCDRP) Table 1–17 (Cont.) Contents of SCSI Class Driver Request Packet Field Name Contents SCDRP$L_CMD_BUF_LEN Length of SCSI command buffer. SCDRP$L_CMD_PTR Address of the SCSI command descriptor block (its length byte) in the SCSI command buffer allocated by the SCSI port driver. The SCSI class driver initializes this field. SCDRP$L_STS_PTR Address of SCSI status byte in the port command buffer. The SCSI class driver initializes this field.
Data Structures 1.15 SCSI Class Driver Request Packet (SCDRP) Table 1–17 (Cont.) Contents of SCSI Class Driver Request Packet Field Name Contents SCDRP$W_PAD_BCNT Pad byte count. This field contains the number of bytes required to make the size of the user buffer equal to the data length value required by a specific SCSI command.
Data Structures 1.15 SCSI Class Driver Request Packet (SCDRP) Table 1–17 (Cont.) Contents of SCSI Class Driver Request Packet Field Name Contents SCDRP$L_MSGO_ PENDING* Output message pending flags.
Data Structures 1.15 SCSI Class Driver Request Packet (SCDRP) Table 1–17 (Cont.) Contents of SCSI Class Driver Request Packet Field Name Contents SCDRP$L_SAVER3* Reserved to Digital. SCDRP$L_SAVER6* Reserved to Digital. SCDRP$L_SAVER7* Reserved to Digital. SCDRP$L_SAVER3CL* Reserved to Digital. SCDRP$L_SAVEPCCL* Reserved to Digital. SCDRP$L_ABORTPCCL* Reserved to Digital. SCDRP$L_PO_STK_PTR* Stack pointer of the port driver’s return address stack.
Data Structures 1.15 SCSI Class Driver Request Packet (SCDRP) Table 1–17 (Cont.) Contents of SCSI Class Driver Request Packet Field Name Contents SCDRP$L_BUS_PHASE* Current SCSI bus phase.
Data Structures 1.15 SCSI Class Driver Request Packet (SCDRP) Table 1–17 (Cont.) Contents of SCSI Class Driver Request Packet Field Name SCDRP$L_CNX_STS Contents Longword bit mask for the connection status.
Data Structures 1.16 SCSI Connection Descriptor Table (SCDT) 1.16 SCSI Connection Descriptor Table (SCDT) The SCSI connection descriptor table (SCDT) contains information specific to a connection established between a SCSI class driver and the port, such as phase records, timeout values, and error counters. The SCSI port driver creates an SCDT each time a SCSI class driver, by invoking the SPI$CONNECT macro, connects to a device on the SCSI bus.
Data Structures 1.
Data Structures 1.16 SCSI Connection Descriptor Table (SCDT) SCDT$L_QUEUE_FLAGS* 260 SCDT$Q_TAG_MAP* 264 SCDT$W_PORT_IO_COUNT* SCDT$W_DEV_IO_COUNT* 272 SCDT$W_MAX_TAG_USED* SCDT$W_WAIT_TAG* 276 Reserved SCDT$W_MAX_QUEUE_DEPTH* 280 SCDT$L_SEQUENCE* 284 SCDT$L_NEXT_SEQUENCE* 288 SCDT$L_SCDRP_MAP* 292 *A read-only field from a class driver point of view Table 1–18 Contents of SCSI Connection Descriptor Table Field Name Contents SCDT$L_FLINK* SCDT forward link.
Data Structures 1.16 SCSI Connection Descriptor Table (SCDT) Table 1–18 (Cont.) Contents of SCSI Connection Descriptor Table Field Name Contents SCDT$L_STS* Connection status. This field is a bit map, maintained by the port driver. The following bits are defined: SCDT$V_BSY Connection busy. SCDT$V_ABORT_PND Abort pending on connection. SCDT$V_ABORT_CMPL Abort completed on connection. SCDT$V_ABORT_INPROG Abort is in progess. SCDT$V_ABORT_RESEL Port was reselected while abort was in progress.
Data Structures 1.16 SCSI Connection Descriptor Table (SCDT) Table 1–18 (Cont.) Contents of SCSI Connection Descriptor Table Field Name Contents SCDT$L_BUS_PHASE* Current SCSI bus phase.
Data Structures 1.16 SCSI Connection Descriptor Table (SCDT) Table 1–18 (Cont.) Contents of SCSI Connection Descriptor Table Field Name Contents SCDT$L_BADPHS_CNT* Count of bad phase errors. SCDT$L_RETRY_CNT* Count of retries. SCDT$L_RST_CNT* Count of bus resets. SCDT$L_CTLERR_CNT* Count of controller errors. SCDT$L_BUSERR_CNT* Count of bus errors. SCDT$L_CMDSENT* Number of commands sent on this connection. SCDT$L_MSGSENT* Number of messages sent on this connection.
Data Structures 1.16 SCSI Connection Descriptor Table (SCDT) Table 1–18 (Cont.) Contents of SCSI Connection Descriptor Table Field Name Contents SCDT$L_DMA_TIMEOUT* Timeout value (in seconds) for a target to change the SCSI bus phase or complete a data transfer. The SCSI port driver initially writes this field according to information the SCSI class driver supplies to the SPI$SET_ CONNECTION_CHAR macro. SCDT$L_DISCON_ TIMEOUT* Disconnect timeout.
Data Structures 1.16 SCSI Connection Descriptor Table (SCDT) Table 1–18 (Cont.) Contents of SCSI Connection Descriptor Table Field Name Contents SCDT$W$_TAG_MAP Quadword bitmap of allocated tags. A bit set in this map indicates a tag value in use. Tag values in the map can be from 0 to 63 allowing 64 outstanding I/Os in a device. SCDT$W_DEV_IO_COUNT Number of I/Os currently outstanding on the in-device queue. SCDT$W_PORT_IO_COUNT Number of I/Os currently outstanding on the incoming port queue.
Data Structures 1.
Data Structures 1.
Data Structures 1.
Data Structures 1.17 SCSI Port Descriptor Table (SPDT) Table 1–19 Contents of SCSI Port Descriptor Table Field Name Contents SPDT$L_FLINK* SPDT forward link. This field points to the next SPDT in the system SPDT list. The SCSI port driver initializes this field when it creates the SPDT. SPDT$W_SIZE* Size of SPDT. The SCSI port driver initializes this field to SPDT$C_ PKNLENGTH or SPDT$C_PKSLENGTH when creating the SPDT. SPDT$B_TYPE Structure type. SPDT$B_SUBTYP Structure subtype.
Data Structures 1.17 SCSI Port Descriptor Table (SPDT) Table 1–19 (Cont.) Contents of SCSI Port Descriptor Table Field Name Contents SPDT$L_SPTE_BASE* System virtual address of the system page-table entry mapping the first page of the port’s DMA buffer. SPDT$L_SPTE_SVAPTE* System virtual address of the system page-table entry that double-maps the data transfer buffer. SPDT$L_ADP* Address of the adapter control block managing port resources.
Data Structures 1.17 SCSI Port Descriptor Table (SPDT) Table 1–19 (Cont.) Contents of SCSI Port Descriptor Table Field Name Contents SPDT$L_DEALLOC_ COMMAND_BUFFER* Address of the port driver routine that executes in response to a class driver’s SPI$DEALLOCATE_COMMAND_BUFFER macro call. The port driver initializes this field. SPDT$L_ABORT* Address of the port driver routine that executes in response to a class driver’s SPI$ABORT_COMMAND macro call. The port driver initializes this field.
Data Structures 1.17 SCSI Port Descriptor Table (SPDT) Table 1–19 (Cont.) Contents of SCSI Port Descriptor Table Field Name SPDT$L_PORT_FLAGS* Contents Port-specific flags. The following bits are defined: SPDT$V_SYNCH Port supports synchronous mode data transfers. SPDT$V_ASYNCH Port supports asynchronous mode data transfers. SPDT$V_MAPPING_ REG Port supports map registers. SPDT$V_BUF_DMA Port supports buffered DMA transfers. SPDT$V_DIR_DMA Port supports direct DMA transfers.
Data Structures 1.18 Spinlock Data Structure (SPL) 1.18 Spinlock Data Structure (SPL) The spinlock data structure (SPL) records all information necessary to properly grant, release, and record the ownership of a spinlock. Each static system spinlock (including the fork locks) and device lock uses an SPL to record the IPL required for spinlock acquisition, its rank, and its owner. The spinlock structure also maintains a history of spinlock use and a variety of counters used in accounting and debugging.
Data Structures 1.18 Spinlock Data Structure (SPL) Table 1–20 Contents of the Spinlock Data Structure Field Contents SPL$B_SPINLOCK* The following fields are defined within SPL$B_SPINLOCK: SPL$V_INTERLOCK Spinlock access interlock. When set, this bit signifies that the spinlock is owned. <7:1> Reserved to Digital. SPL$B_IPL* IPL required for spinlock acquisition. SPL$B_RANK* Spinlock rank.
Data Structures 1.19 Unit Control Block (UCB) 1.19 Unit Control Block (UCB) The unit control block (UCB) is a variable-length block that describes a single device unit. Each device unit on the system has its own UCB. The UCB describes or provides pointers to the device type, controller, driver, device status, and current I/O activity. During autoconfiguration, the driver-loading procedure creates one UCB for each device unit in the system.
Data Structures 1.19 Unit Control Block (UCB) The driver-loading procedure initializes some static UCB fields when it creates the block. The operating system and the device drivers can read and modify all nonstatic fields of the UCB. The UCB fields that are present for all devices are illustrated in Figure 1–23 and described in Table 1–22. The length of the basic UCB is defined by the symbol UCB$K_LENGTH.
Data Structures 1.19 Unit Control Block (UCB) In this case, too, the driver must ensure that it specifies the length of the extended UCB in the ucbsize argument of the DPTAB macro: DPTAB -, . . . UCBSIZE=UCB$K_XX_LENGTH,. . .
Data Structures 1.
Data Structures 1.19 Unit Control Block (UCB) Table 1–22 Contents of Unit Control Block Field Name Contents UCB$L_FQFL* Fork queue forward link. The link points to the next entry in the fork queue. EXE$IOFORK and system resource management routines write this field. The queue contains addresses of UCBs that contain driver fork process context of drivers waiting to continue I/O processing. UCB$L_FQBL* Fork queue backward link. The link points to the previous entry in the fork queue.
Data Structures 1.19 Unit Control Block (UCB) Table 1–22 (Cont.) Contents of Unit Control Block Field Name Contents UCB$L_ORB* Address of ORB associated with the UCB. SYSGEN places the address in this field when you use SYSGEN’s CONNECT command. UCB$L_LOCKID* Lock management lock ID of device allocation lock. A lock management lock is used for device allocation so that device allocation functions properly for cluster-accessible devices in a VAXcluster (DEV$V_CLU set within UCB$L_ DEVCHAR2).
Data Structures 1.19 Unit Control Block (UCB) Table 1–22 (Cont.
Data Structures 1.19 Unit Control Block (UCB) Table 1–22 (Cont.
Data Structures 1.19 Unit Control Block (UCB) Table 1–22 (Cont.) Contents of Unit Control Block Field Name Contents DC$_WORKSTATION Workstation DC$_REALTIME Real time DC$_BUS Bus DC$_MAILBOX Mailbox DC$_DECVOICE DECVoice DC$_AUDIO General audio DC$_REMCSL_ STORAGE Remote console storage DC$_MISC Miscellaneous Note that the definition of a device as a real-time device (DC$_REALTIME) is somewhat subjective; it implies no special treatment by the operating system. UCB$B_DEVTYPE Device type.
Data Structures 1.19 Unit Control Block (UCB) Table 1–22 (Cont.) Contents of Unit Control Block Field Name Contents UCB$L_IRP Address of IRP currently being processed on the device unit by the driver fork process. IOC$INITIATE writes the address of an IRP into this field before the routine creates a driver fork process to handle an I/O request. From this field, a driver fork process obtains the address of the IRP being processed.
Data Structures 1.19 Unit Control Block (UCB) Table 1–22 (Cont.) Contents of Unit Control Block Field Name UCB$W_DEVSTS Contents UCB$V_UNLOAD Unload volume at dismount. UCB$V_TEMPLATE Template UCB from which other UCBs for this device are made. The $ASSIGN system service checks this bit in the requested UCB and, if the bit is set, creates a UCB from the template. The new UCB is assigned instead. UCB$V_MNTVERIP Mount verification in progress.
Data Structures 1.19 Unit Control Block (UCB) Table 1–22 (Cont.) Contents of Unit Control Block Field Name Contents UCB$L_DUETIM* Due time for I/O completion. Stored as the low-order 32-bit absolute time (time in seconds since the operating system was booted) at which the device will time out. IOC$WFIKPCH and IOC$WFIRLCH write this value when they suspend a driver to wait for an interrupt or timeout. EXE$TIMEOUT examines this field in each UCB in the I/O database once per second.
Data Structures 1.19 Unit Control Block (UCB) Table 1–22 (Cont.) Contents of Unit Control Block Field Name Contents UCB$W_ERRCNT Number of errors that have occurred on the device since the system was booted. The driver-loading procedure initializes the field to zero when the procedure creates the UCB. ERL$DEVICERR and ERL$DEVICTMO increment the value in the field and copy the value into an error message buffer.
Data Structures 1.19 Unit Control Block (UCB) Table 1–23 (Cont.) UCB Error-Log Extension Field Name Contents UCB$B_CEX Device-specific field. This field is reserved for driver use. Certain system disk drivers (such as DLDRIVER in one of the appendixes to the OpenVMS VAX Device Support Manual) use this field to store an index into a software function case table. UCB$L_EMB* Address of error message buffer.
Data Structures 1.19 Unit Control Block (UCB) Table 1–24 UCB Local Tape Extension Field Name Contents UCB$W_DIRSEQ Directory sequence number. If the high-order bit of this word, UCB$V_ AST_ARMED, is set, it indicates that the requesting process is blocking ASTs. UCB$B_ONLCNT Number of times the device has been placed on line since the system was last bootstrapped. UCB$B_PREV_RECORD Tape position prior to the start of the last I/O operation. UCB$L_RECORD Current tape position or frame counter.
Data Structures 1.19 Unit Control Block (UCB) Unused UCB$L_DX_BUF 228 UCB$L_DX_BFPNT 232 UCB$L_DX_RXDB 236 UCB$B_DX_SCTCNT UCB$W_DX_BCR 240 Table 1–25 UCB Local Disk Extension Field Name Contents UCB$W_DIRSEQ Directory sequence number. If the high-order bit of this word, UCB$V_AST_ ARMED, is set, it indicates that the requesting process is blocking ASTs. UCB$B_ONLCNT Number of times device has been placed on line since the system was last bootstrapped.
Data Structures 1.
Data Structures 1.
Data Structures 1.19 Unit Control Block (UCB) Table 1–26 UCB Terminal Extension Field Name Contents UCB$L_TL_CTRLY* Listhead of CTRL/Y AST control blocks (ACBs). UCB$L_TL_CTRLC* Listhead of CTRL/C ACBs. UCB$L_TL_OUTBAND* Out-of-band character mask. UCB$L_TL_BANDQUE* Listhead of out-of-band ACBs. UCB$L_TL_PHYUCB* Address of physical UCB. UCB$L_TL_CTLPID* Process ID of controlling process (used with SPAWN). UCB$Q_TL_BRKTHRU* Facility broadcast bit mask.
Data Structures 1.19 Unit Control Block (UCB) Table 1–26 (Cont.
Data Structures 1.19 Unit Control Block (UCB) Table 1–26 (Cont.) UCB Terminal Extension Field Name Contents UCB$B_TT_DELFF* Default line-feed fill. UCB$B_TT_DEPARI* Default parity/character size. UCB$B_TT_DETYPE* Default terminal type. UCB$W_TT_DESIZE* Default line size. UCB$W_TT_SPEED* Terminal line speed. This field is read and written by the class driver, and read by the port driver.
Data Structures 1.19 Unit Control Block (UCB) Table 1–26 (Cont.) UCB Terminal Extension Field Name Contents UCB$W_TT_HOLD Port driver’s internal flags and unit holding tank. This is read and written by the port driver, and is not accessed by the class driver. It contains the following subfields: TTY$B_TANK_CHAR Character. TTY$V_TANK_PREMPT Send preempt character. TTY$V_TANK_STOP Stop output. TTY$V_TANK_HOLD Character stored in TTY$B_TANK_CHAR. TTY$V_TANK_BURST Burst is active.
Data Structures 1.19 Unit Control Block (UCB) Table 1–26 (Cont.) UCB Terminal Extension Field Name Contents TTY$V_PC_XOFAVL Auto XOFF supported. If set, auto XOFF is supported for this port. TTY$V_PC_XOFENA Auto XOFF enabled. If set, auto XOFF is currently enabled on this port. TTY$V_PC_NOCRLF No auto line feed. If set, a line feed is not generated following a carriage return. TTY$V_PC_BREAK Break.
Data Structures 1.19 Unit Control Block (UCB) Table 1–26 (Cont.) UCB Terminal Extension Field Name Contents UCB$L_TT_FBK* Address of fallback block. UCB$L_TT_RDVERIFY* Address of read/verify table. Reserved for future use. UCB$L_TT_CLASS1* First class driver longword. UCB$L_TT_CLASS2* Second class driver longword. UCB$L_TT_ACCPORNAM Address of counted string. UCB$L_TP_MAP* UNIBUS/Q22–bus map registers. UCB$B_TP_STAT DMA port-specific status.
2 System Macros Invoked by Drivers This chapter describes system macros that are the most frequently used by device drivers. When referring to these macro descriptions note the following conventions: • If an argument is enclosed in brackets, you can choose to include that argument or omit it. • The operating system assigns values by default to certain arguments. If you omit one of these arguments, the macro behaves as if you specified the argument with its default value.
System Macros Invoked by Drivers ADPDISP ADPDISP Causes a branch to a specified address given the existence of a selected adapter characteristic. Format ADPDISP select ,addrlist [,adpaddr] [,crbaddr] [,ucbaddr] [,ecrbaddr] [,scratch=R0] Parameters select Determines which ADP field or bit field is the basis for dispatching and, by implication, which adapter characteristic. See the Description section that follows for a list of legal values for select.
System Macros Invoked by Drivers ADPDISP Table 2–1 Selectable Adapter Characteristics Select Argument Possible Value of flag in addrlist Definition ADAP_TYPE UBA, MBA, GENBI, DR, or NULL. (See those symbols prefixed with AT$ defined by the $DCDEF macro in SYS$LIBRARY:STARLET.MLB.) Adapter type. ADDR_BITS 18 or 22 Number of adapter address bits.
System Macros Invoked by Drivers ADPDISP UCB address specified in R5. In doing so, it destroys the contents of scratch register R1. 3. ADPDISP SELECT=ADDR_BITS,ADDRLIST=<<18,10$>,<22,20$>>,ADPADDR=R3 ADPDISP transfers control to 10$ for all adapters using an 18-bit address and 20$ for all using a 22-bit address. The ADP address is supplied in R3.
System Macros Invoked by Drivers BI_NODE_RESET BI_NODE_RESET Initiates BIIC self-test on the specified VAXBI node. Format BI_NODE_RESET csr Parameters csr General purpose register that contains the address of the VAXBI node’s control and status register (CSR). Description The BI_NODE_RESET macro uses the recommended instruction sequence to disable arbitration on the specified VAXBI node, and sets the node reset and self-test status bits in the BIIC CSR.
System Macros Invoked by Drivers CASE CASE Generates a CASE instruction and its associated table. Format CASE src ,displist [,type=W] [,limit=#0] [,nmode=S^#] Parameters src Source of the index value to be used with the CASE instruction. displist List of destinations to which control is to be dispatched, depending on the value of the index. [type=W] Data type of src (B, W, or L). [limit=#0] Lower limit of the value of src.
System Macros Invoked by Drivers CLASS_CTRL_INIT CLASS_CTRL_INIT Generates the common code that must be executed by the controller initialization routine of all terminal port drivers. Format CLASS_CTRL_INIT dpt, vector Parameters dpt Symbolic name of the port driver’s driver prologue table. vector Address of the port driver vector table.
System Macros Invoked by Drivers CLASS_UNIT_INIT CLASS_UNIT_INIT Generates the common code that must be executed by the unit initialization routine of all terminal port drivers. Format CLASS_UNIT_INIT Description A terminal port driver’s unit initialization routine invokes the CLASS_UNIT_ INIT macro to perform initialization tasks common to all port drivers. To use the CLASS_UNIT_INIT macro, the driver must include an invocation of the $TTYMACS definition macro (from SYS$LIBRARY:LIB.MLB).
System Macros Invoked by Drivers CPUDISP CPUDISP Causes a branch to a specified address according to the CPU type of the VAX processor executing the macro code. Format CPUDISP addrlist ,[environ=VMS] ,continue=NO Parameters addrlist List containing one or more pairs of arguments in the following format: The CPU-type parameter identifies the type or subtype of a VAX processor for which the macro is to generate a case table entry.
System Macros Invoked by Drivers CPUDISP Table 2–2 (Cont.) VAX Systems and Their CPU Type CPU Type VAX System 420 410 60 46 UV2 VAXstation 3100/MicroVAX 3100 VAXstation 2000/MicroVAX 2000 VAXstation 3520/3540 VAXstation 4000-60 MicroVAX II The CPUDISP macro identifies the VAX system by type and subtype as listed in Table 2–3.
System Macros Invoked by Drivers CPUDISP The destination parameter contains the address to which the code generated by the invocation of the CPUDISP macro passes control to continue with CPUspecific processing. [environ=VMS] Identification of the run-time environment of the code generated by the CPUDISP macro. There is no need to change the default value of this argument.
System Macros Invoked by Drivers DDTAB DDTAB Generates a driver dispatch table (DDT) labeled devnam$DDT. Format DDTAB devnam ,[start=+IOC$RETURN] ,[unsolic=+IOC$RETURN] ,functb [,cancel=+IOC$RETURN] [,regdmp=+IOC$RETURN] [,diagbf=0] [,erlgbf=0] [,unitinit=+IOC$RETURN] [,altstart=+IOC$RETURN] [,mntver=+IOC$MNTVER] [,cloneducb=+IOC$RETURN] Parameters devnam Generic name of the device. [start=+IOC$RETURN] Address of start-I/O routine.
System Macros Invoked by Drivers DDTAB [cloneducb=+IOC$RETURN] Address of routine called when a UCB is cloned by the $ASSIGN system service. Description The DDTAB macro creates a driver dispatch table (DDT). The table has a label of devnam$DDT. Just preceding the table, DDTAB generates the driver code program section with the following statement: .
System Macros Invoked by Drivers $DEF $DEF Defines a data-structure field within the context of a $DEFINI macro. Format $DEF sym [,alloc] [,siz] Parameters sym Name of the symbol to access the field. [alloc] Block-storage-allocation directives, one of the following: .BLKB, .BLKW, .BLKL, .BLKQ, or .BLKO. [siz] Number of block storage units to allocate.
System Macros Invoked by Drivers $DEFEND $DEFEND Ends the scope of the $DEFINI macro, thereby completing the definition of fields within a data structure. Format $DEFEND struc Parameters struc Name of the structure that is being defined. Description See the descriptions of the $DEFINI, _VIELD, and $EQULST macros for additional information on defining symbols for data structure fields.
System Macros Invoked by Drivers $DEFINI $DEFINI Begins the definition of a data structure. Format $DEFINI struc [,gbl=LOCAL] [,dot=0] Parameters struc Name of the data structure that is being defined. [gbl=LOCAL] Specifies whether the symbols defined for this data structure are to be local or global symbols. The default is to make them local. To make the definitions of symbols global, you must specify GLOBAL for the value of the gbl argument.
System Macros Invoked by Drivers DEVICELOCK DEVICELOCK Achieves synchronized access to a device’s database as appropriate to the processing environment. Format DEVICELOCK [lockaddr] [,lockipl] [,savipl] [,condition] [,preserve=YES] Parameters [lockaddr] Address of the device lock to be obtained. If lockaddr is not present, DEVICELOCK presumes that R5 contains the address of the UCB and uses the value at UCB$L_DLCK(R5) as the lock address.
System Macros Invoked by Drivers DEVICELOCK • Calls either SMP$ACQUIREL or SMP$ACQNOIPL, depending upon the presence of condition=NOSETIPL. SMP$ACQUIREL raises IPL to device IPL prior to obtaining the lock, determining appropriate IPL from the device lock’s data structure (SPL$B_IPL).
System Macros Invoked by Drivers DEVICEUNLOCK DEVICEUNLOCK Relinquishes synchronized access to a device’s database as appropriate to the processing environment. Format DEVICEUNLOCK [lockaddr] [,newipl] [,condition] [,preserve=YES] Parameters [lockaddr] Address of the device lock to be released or restored. If lockaddr is not present, DEVICEUNLOCK presumes that R5 contains the address of the UCB and uses the value at UCB$L_DLCK(R5) as the lock address.
System Macros Invoked by Drivers DEVICEUNLOCK Example DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),- ;Lock device access CONDITION=NOSETIPL,;Do not set IPL PRESERVE=NO ;Do not preserve R0 . . .
System Macros Invoked by Drivers DPTAB DPTAB Generates a driver prologue table (DPT) in a program section called $$$105_ PROLOGUE. Format DPTAB end ,adapter ,[flags=0] ,ucbsize ,[unload] ,[maxunits=8] ,[defunits=1] ,[deliver] ,[vector] ,name [,psect=$$$105_PROLOGUE] [,smp=NO] [,decode] Parameters end Address of the end of the driver. adapter Type of adapter (as indicated by the symbols prefixed by AT$ defined by the $DCDEF macro in SYS$LIBRARY:STARLET.MLB).
System Macros Invoked by Drivers DPTAB DPT$M_SMPMOD DPT$M_XPAMOD DPT$M_XVAMOD Indicates that the driver has been designed to execute within a multiprocessing environment. Use of any of the multiprocessing synchronization macros (DEVICELOCK/DEVICEUNLOCK, FORKLOCK /FORKUNLOCK, or LOCK/UNLOCK) automatically sets this flag, as long as the code using the macro resides in the same module as the invocation of DPTAB. Indicates that the driver can operate on a system with extended physical addressing.
System Macros Invoked by Drivers DPTAB [vector] Address of a driver-specific transfer vector. A terminal port driver specifies the address of its vector table in this argument. name Name of the device driver. The driver-loading procedure will permit the loading of only one copy of the driver associated with this name. A driver name can be up to 11 alphabetic characters and, by convention, is formed by appending the string DRIVER to the 2-alphabetic-character generic device name, for example, QBDRIVER.
System Macros Invoked by Drivers DPTAB DPT_STORE UCB,UCB$B_DEVCLASS,B,DC$_REALTIME ;Device class DPT_STORE UCB,UCB$B_DEVTYPE,B,DT$_DR11W ;Device type DPT_STORE UCB,UCB$W_DEVBUFSIZ,W,XA_DEF_BUFSIZ ;Default buffer size DPT_STORE REINIT ;Start of reload initialization table DPT_STORE DDB,DDB$L_DDT,D,XA$DDT ;Address of DDT DPT_STORE CRB,CRB$L_INTD+VEC$L_ISR,D,XA_INTERRUPT ;Address of interrupt service routine DPT_STORE CRB,CRB$L_INTD+VEC$L_INITIAL,D,XA_CONTROL_INIT ;Address of controller init routine DPT_STORE
System Macros Invoked by Drivers DPT_STORE DPT_STORE Instructs the system driver-loading procedure to store values in a table or data structure. Format DPT_STORE str_type ,str_off ,oper ,exp [,pos] [,size] Parameters str_type Type of data structure (CRB, DDB, IDB, ORB, or UCB) into which the driverloading procedure is to store the specified data, or a label denoting a table marker.
System Macros Invoked by Drivers DPT_STORE [pos] Starting bit position within the specified field; used only if oper=V. [size] Number of bits to be written; used only if oper=V. Description The DPT_STORE macro places information in the DPT that the driver-loading procedure uses to load specified values into specified fields.
System Macros Invoked by Drivers DPT_STORE Drivers use the DPT_STORE macro with the REINIT table marker label to begin a list of DPT_STORE invocations that supply initialization and reinitialization data for the following fields: DDB$L_DDT CRB$L_INTD+ VEC$L_ISR CRB$L_INTD2+ VEC$L_ISR CRB$L_INTD+ VEC$L_INITIAL CRB$L_INTD+ VEC$L_UNITINIT Driver dispatch table. Every driver must specify a value for this field. Interrupt service routine. Interrupt service routine for second interrupt vector.
System Macros Invoked by Drivers DSBINT DSBINT Blocks interrupts from occurring on the local processor at or below a specified IPL. Format DSBINT [ipl=31] [,dst=–(SP)] [,environ=MULTIPROCESSOR] Parameters [ipl=31] IPL at which to block interrupts. If no ipl is specified, the default is IPL 31, which blocks all interrupts. [dst=–(SP)] Location in which to save the current IPL. If no destination is specified, the current IPL is pushed onto the stack.
System Macros Invoked by Drivers ENBINT ENBINT Lowers the local processor’s IPL to a specified value, thus permitting interrupts to occur at or beneath the current IPL. Format ENBINT [src=(SP)+] Parameters [src=(SP)+] Location containing the IPL to be restored to the processor IPL register (PR$_ IPL) of the local processor. If you do not specify a value in src, ENBINT moves the value on the top of the stack into PR$_IPL.
System Macros Invoked by Drivers $EQULST $EQULST Defines a list of symbols and assigns values to the symbols. Format $EQULST prefix ,[gbl=LOCAL] ,init ,[incr=1] ,list Parameters prefix Prefix to be used in forming the names of the symbols. [gbl=LOCAL] Scope of the definition of the symbol, either LOCAL, the default, or GLOBAL. init Value to be assigned to the first symbol in the list. [incr=1] Increment by which to increase the value of each succeeding symbol in the list. The default is 1.
System Macros Invoked by Drivers $EQULST This code excerpt produces the following symbols: XA_K_FNCT1 XA_K_FNCT2 XA_K_FNCT3 XA_K_STATUSA XA_K_STATUSB XA_K_STATUSC = = = = = = 00000002 00000004 00000008 00000800 00000400 00000200 2–31
System Macros Invoked by Drivers FIND_CPU_DATA FIND_CPU_DATA Locates the start of the per-CPU database area (CPU) for the current process. Format FIND_CPU_DATA reg [,amod=G^] [,istack=NO] Parameters reg Register to receive the base virtual address of the current processor’s per-CPU database structure (CPU)). [amod=G^] Addressing mode. [istack=NO] Mechanism to calculate the base address of the per-CPU database structure.
System Macros Invoked by Drivers FORK FORK Creates a fork process for the context of the code to execute that follows this macro invocation. Format FORK Description The FORK macro calls EXE$FORK to create a fork process.
System Macros Invoked by Drivers FORKLOCK FORKLOCK Achieves synchronized access to a device driver’s fork database as appropriate to the processing environment. Format FORKLOCK [lock] [,lockipl] [,savipl] [,preserve=YES] [,fipl=NO] Parameters [lock] Index of the fork lock to be obtained. If the lock argument is not present in the macro invocation, FORKLOCK presumes that R5 contains the address of the fork block and uses the value at FKB$B_FLCK(R5) as the lock index.
System Macros Invoked by Drivers FORKLOCK In a multiprocessing environment, the FORKLOCK macro stores the fork lock index in R0 and calls SMP$ACQUIRE. SMP$ACQUIRE uses the value in R0 to locate the fork lock structure in the system spinlock database (a pointer to which is located at SMP$AR_SPNLKVEC). Prior to securing the fork lock, SMP$ACQUIRE raises IPL to its associated IPL (SPL$B_IPL).
System Macros Invoked by Drivers FORKUNLOCK FORKUNLOCK Relinquishes synchronized access to a device driver’s fork database as appropriate to the processing environment. Format FORKUNLOCK [lock] [,newipl] [,condition] [,preserve=YES] Parameters [lock] Index of the fork lock to be released or restored. If lock is not present, FORKUNLOCK assumes that R5 contains the address of the fork block and uses the value at FKB$B_FLCK(R5) as the fork lock index. [newipl] Location containing the IPL to which to lower.
System Macros Invoked by Drivers FUNCTAB FUNCTAB Creates a driver’s function decision table (FDT) and generates FDT entries. Format FUNCTAB [action] ,codes Parameters [action] Address of an FDT routine that the operating system calls when preprocessing an I/O request whose function code matches a function indicated in the codes argument. A plus sign ( + ) precedes the address of any specified FDT routine that is part of the operating system.
System Macros Invoked by Drivers FUNCTAB Example XX_FUNCTABLE: FUNCTAB , FUNCTAB , FUNCTAB XX_READ, FUNCTAB +EXE$SETMODE, FUNCTAB +EXE$SENSEMODE, ;Function decision table ;Valid functions ;Read logical block ;Read physical block ;Read virtual block ;Sense reader mode ;Sense reader characteristics ;Set reader mo
System Macros Invoked by Drivers IFNORD, IFNOWRT, IFRD, IFWRT IFNORD, IFNOWRT, IFRD, IFWRT Determines the read or write accessibility of a range of memory locations. Format 8 IFNORD > < IFNOWRT > IFRD : IFWRT 9 > = > ; siz ,adr ,dest [,mode=#0] Parameters siz Offset of the last byte to check from the first byte to check, a number less than or equal to 512. adr Address of first byte to check.
System Macros Invoked by Drivers IFNORD, IFNOWRT, IFRD, IFWRT Example MOVZWL MOVL IFRD BRW $SS_ACCVIO,R0 ENTRY_LIST(AP),R11 #4*4,(R11),50$ ERROR ;Assume read access failure ;Get address of entry point list ;Branch forward if process ; has read access ;Otherwise stop with error . . . The connect-to-interrupt driver uses the IFRD macro to verify that the process has read access to the four longwords that make up the entry point list.
System Macros Invoked by Drivers INVALIDATE_TB INVALIDATE_TB Allows a single page-table entry (PTE) to be modified while any translation buffer entry that maps it is invalidated, or invalidates the entire translation buffer. Format INVALIDATE_TB [addr, inst1 [,inst2] [,inst3] [,inst4] [,inst5] [,inst6] [,save_r2=YES] [,checks=YES]] Parameters [addr] Virtual address mapped by the PTE for which invalidation is required. If addr is blank, then the macro invalidates all PTEs in the translation buffer.
System Macros Invoked by Drivers INVALIDATE_TB preventing all other processors in the system from referencing the page it maps. Because the INVALIDATE_TB macro calls system routines that rely on the stack contents and use R2, none of the specified instruction arguments should reference the stack or use R2. To invalidate the entire translation buffer (without modifying PTEs), invoke the INVALIDATE_TB macro with no addr and instruction arguments.
System Macros Invoked by Drivers IOFORK IOFORK Disables timeouts from a target device and creates a fork process for the context of the code to execute that follows this macro invocation. Format IOFORK Description The IOFORK macro calls EXE$IOFORK to disable timeouts from a target device (by clearing UCB$V_TIM in UCB$L_STS) and to create a fork process for a device driver.
System Macros Invoked by Drivers LOADALT LOADALT Loads a set of Q22–bus alternate map registers. Format LOADALT Description The LOADALT macro calls IOC$LOADALTMAP to load a set of Q22–bus alternate map registers (registers 496 to 8191). Map registers must already be allocated before the LOADALT macro can be invoked. When the LOADALT macro is invoked, register R5 must contain the address of the UCB. LOADALT destroys the contents of R0 through R2.
System Macros Invoked by Drivers LOADMBA LOADMBA Loads MASSBUS map registers. Format LOADMBA Description The LOADMBA macro calls IOC$LOADMBAMAP to load MASSBUS map registers. The driver must own the MASSBUS adapter, and thus the map registers, before it can invoke LOADMBA.
System Macros Invoked by Drivers LOADUBA LOADUBA Loads a set of UNIBUS map registers or a set of the first 496 Q22–bus map registers. Format LOADUBA Description The LOADUBA macro calls IOC$LOADUBAMAP to load a set of UNIBUS map registers or a set of the first 496 Q22–bus map registers. Map registers must already be allocated before the LOADUBA macro can be invoked. When the LOADUBA macro is invoked, register R5 must contain the address of the UCB. LOADUBA destroys the contents of R0 through R2.
System Macros Invoked by Drivers LOCK LOCK Achieves synchronized access to a system resource as appropriate to the processing environment. Format LOCK lockname [,lockipl] [,savipl] [,condition] [,preserve=YES] Parameters lockname Name of the resource to lock. [lockipl] Location containing the IPL at which the resource is synchronized. Although the value of this argument is ignored by the macro, Digital recommends that you specify a lockipl value to facilitate debugging.
System Macros Invoked by Drivers LOCK_SYSTEM_PAGES LOCK_SYSTEM_PAGES Locks a paged code segment in system memory. Format LOCK_SYSTEM_PAGES [startva] ,endva [,ipl] Parameters [startva] System virtual address in the first page to be locked. If the startva argument is omitted, the starting virtual address defaults to the current PC. endva System virtual address in the last page to be locked. [ipl] IPL at which the locked code segment is to execute.
System Macros Invoked by Drivers LOCK_SYSTEM_PAGES • If it specified the ipl argument to the LOCK_SYSTEM_PAGES macro, the code segment must restore the previous IPL, either explicitly, through the use of the ipl argument to the UNLOCK_SYSTEM_PAGES macro, or through the use of one of the system synchronization macros. Example 30$: TSTB (R0) LOCK_SYSTEM_PAGES,END=100$ LOCK LOCKNAME=MMG,SAVIPL=-(SP) MOVL W^MMG$GL_SYSPHD,R3 . . .
System Macros Invoked by Drivers PURDPR PURDPR Purges a UNIBUS adapter buffered data path. Format PURDPR Description The PURDPR macro calls IOC$PURGDATAP to purge a UNIBUS adapter buffered data path. A driver within an I/O subsystem configuration that does not provide buffered data paths may use the PURDPR macro because the purge operation detects memory parity errors that may have occurred during the transfer. When the PURDPR macro is invoked, R5 must contain the address of the UCB.
System Macros Invoked by Drivers READ_CSR READ_CSR Reads the contents of a device control and status register. Format READ_CSR src, dest [,length=LONGWORD] [,error=BUGCHECK] [,environ=GENERIC] [,vme=pio_reg] Parameters src System virtual address or pseudo CSR address of the register in I/O space. dest Location to which the register data is to be returned. [length=LONGWORD] Size of the CSR access: BYTE, WORD, or LONGWORD. Default is LONGWORD. [error=BUGCHECK] Proper disposition on error.
System Macros Invoked by Drivers READ_SYSTIME READ_SYSTIME Reads the current system time. Format READ_SYSTIME dst Parameter dst Quadword into which the macro inserts the system time. Description The READ_SYSTIME macro generates the code required to obtain a consistent copy of the system time from EXE$GQ_SYSTIME. Use of the READ_SYSTIME macro is subject to the following restrictions: • IPL must be less than 23. • The processor must be executing in kernel mode.
System Macros Invoked by Drivers RELALT RELALT Releases a set of Q22–bus alternate map registers allocated to the driver. Format RELALT Description The RELALT macro calls IOC$RELALTMAP to release a set of Q22–bus alternate map registers (registers 496 to 8191) allocated to the driver. When the RELALT macro is invoked, R5 must contain the address of the UCB. RELALT destroys the contents of R0 through R2.
System Macros Invoked by Drivers RELCHAN RELCHAN Releases all controller data channels allocated to a device. Format RELCHAN Description The RELCHAN macro calls IOC$RELCHAN to release all controller data channels allocated to a device. When the RELCHAN macro is invoked, R5 must contain the address of the UCB. RELCHAN destroys the contents of R0 through R2.
System Macros Invoked by Drivers RELDPR RELDPR Releases a UNIBUS adapter data path register allocated to the driver. Format RELDPR Description The RELDPR macro calls IOC$RELDATAP to release a UNIBUS adapter buffered data path allocated to the driver. When the RELDPR macro is invoked, R5 must contain the address of the UCB. RELDPR destroys the contents of R0 through R2.
System Macros Invoked by Drivers RELMPR RELMPR Releases a set of UNIBUS map registers or a set of the first 496 Q22–bus map registers allocated to the driver. Format RELMPR Description The RELMPR macro calls IOC$RELMAPREG to release a set of map registers allocated to the driver. When the RELMPR macro is invoked, R5 must contain the address of the UCB. RELMPR destroys the contents of R0 through R2.
System Macros Invoked by Drivers RELSCHAN RELSCHAN Releases all secondary channels allocated to the driver. Format RELSCHAN Description The RELSCHAN macro calls IOC$RELSCHAN to release all secondary data channels (for example, the MASSBUS adapter’s controller data channel) allocated to the driver. When the RELSCHAN macro is invoked, R5 must contain the address of the UCB. RELSCHAN destroys the contents of R0 through R2.
System Macros Invoked by Drivers REQALT REQALT Obtains a set of Q22–bus alternate map registers. Format REQALT Description The REQALT macro calls IOC$REQALTMAP to obtain a set of Q22–bus alternate map registers (registers 496 to 8191). When the REQALT macro is invoked, the following registers must contain the following values: Register Contents R5 00(SP) Address of UCB Address of caller’s caller The REQALT macro destroys the contents of R0 through R2.
System Macros Invoked by Drivers REQCOM REQCOM Invokes system device-independent I/O postprocessing. Format REQCOM Description The REQCOM macro calls IOC$REQCOM to complete the processing of an I/O request after the driver has finished its portion of the processing.
System Macros Invoked by Drivers REQDPR REQDPR Requests a UNIBUS adapter buffered data path. Format REQDPR Description The REQDPR macro calls IOC$REQDATAP to request a UNIBUS adapter buffered data path. When the REQDPR macro is invoked, the following registers must contain the following values: Register Contents R5 00(SP) Address of UCB Address of caller’s caller The REQDPR macro destroys the contents of R0 through R2.
System Macros Invoked by Drivers REQMPR REQMPR Obtains a set of UNIBUS map registers or a set of the first 496 Q22–bus map registers. Format REQMPR Description The REQMPR macro calls IOC$REQMAPREG to obtain a set of map registers. When the REQMPR macro is invoked, the following registers must contain the following values: Register Contents R5 00(SP) Address of UCB Address of caller’s caller The REQMPR macro destroys the contents of R0 through R2.
System Macros Invoked by Drivers REQPCHAN REQPCHAN Obtains a controller’s data channel. Format REQPCHAN [pri] Parameters [pri] Priority of request. If the priority is HIGH, REQPCHAN calls IOC$REQPCHANH; otherwise it calls IOC$REQPCHANL. Description The REQPCHAN macro calls IOC$REQPCHANH or IOC$REQPCHANL, depending on the priority specified, to obtain a controller’s data channel.
System Macros Invoked by Drivers REQSCHAN REQSCHAN Obtains a secondary MASSBUS data channel. Format REQSCHAN [pri] Parameter [pri] Priority of request. If the priority is HIGH, REQSCHAN calls IOC$REQSCHANH; otherwise it calls IOC$REQSCHANL. Description The REQSCHAN macro calls IOC$REQSCHANH or IOC$REQSCHANL, depending on the priority specified, to obtain a secondary MASSBUS data channel.
System Macros Invoked by Drivers SAVIPL SAVIPL Saves the current IPL of the local processor. Format SAVIPL [dst=–(SP)] Parameter [dst=–(SP)] Address of longword in which to save the current IPL. Description The SAVIPL macro stores the current IPL of the local processor, as recorded in the processor IPL register (PR$_IPL), in the specified location.
System Macros Invoked by Drivers SETIPL SETIPL Sets the current IPL of the local processor. Format SETIPL [ipl=31] [environ=MULTIPROCESSOR] Parameters [ipl=31] Level at which to set the current IPL. The default value sets IPL to 31, blocking all interrupts on the local processor. [environ=MULTIPROCESSOR] Processing environment in which the SETIPL synchronization macro is to be assembled.
System Macros Invoked by Drivers SETIPL Example DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),SAVIPL=-(SP) SETIPL #IPL$_POWER,ENVIRON=UNIPROCESSOR BBC #UCB$V_POWER, UCB$W_STS(R5),30$ ;Service power failure ;Secure device lock ;(also raises IPL to device lock’s IPL) ;Save current IPL on stack ;Raise IPL to 31 ;Avoid assembly-time warning DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),NEWIPL=(SP)+ ;Release device lock ;If clear, no power failure . . . ;Restore old IPL from stack . . . ;Branch 30$: ;Start device . . .
System Macros Invoked by Drivers SOFTINT SOFTINT Requests a software interrupt from the local processor at a specified IPL. Format SOFTINT ipl Parameter ipl IPL at which the software interrupt is being requested. Description The SOFTINT macro moves the specified ipl into the local processor’s Software Interrupt Request Register (PR$_SIRR), thus requesting a software interrupt at that IPL on the processor.
System Macros Invoked by Drivers SPI$ABORT_COMMAND SPI$ABORT_COMMAND Aborts execution of the outstanding SCSI command on a given connection. Format SPI$ABORT_COMMAND Description The SPI$ABORT_COMMAND macro aborts the outstanding SCSI command on the connection specified in SCDRP$L_CDT. The SCSI port driver’s abort routine sends the SCSI ABORT command to the target device. Note VAXstation 3520/3540 systems do not implement the abort-SCSIcommand function.
System Macros Invoked by Drivers SPI$ALLOCATE_COMMAND_BUFFER SPI$ALLOCATE_COMMAND_BUFFER Allocates a port command buffer for a SCSI command descriptor block. Format SPI$ALLOCATE_COMMAND_BUFFER Description The SPI$ALLOCATE_COMMAND_BUFFER macro allocates a port command buffer for a SCSI command descriptor block.
System Macros Invoked by Drivers SPI$CONNECT SPI$CONNECT Creates a connection from a class driver to a SCSI device. Format SPI$CONNECT [select_callback [,select_context]] Parameters select_callback Address of a routine in the class driver that executes in response to asynchronous event notification from the target device.
System Macros Invoked by Drivers SPI$CONNECT Table 2–4 lists the port driver return values to the class driver. Table 2–4 Values Returned by the SPI$CONNECT Macro Location Contents R0 Port status. The port driver returns one of the following values: SS$_DEVALLOC Connection already open for this target. SS$_DEVOFFLINE Port is off line and allows no connections. SS$_INSFMEM Insufficient memory to allocate SCDT. SS$_NORMAL Connection formed. SS$_NOSUCHDEV Port not found.
System Macros Invoked by Drivers SPI$CONNECT The port driver returns the maximum allowed value (SPDT$L_MAXBYTECNT) in R1 to the class driver in response to the class driver’s invocation of the SPI$CONNECT macro. Some devices, typically tape drives, need to utilize the full value of SPDT$L_MAXBYTECNT. Most devices, such as disk drives, can better utilize resources with a smaller (suggested) byte count per DMA transfer.
System Macros Invoked by Drivers SPI$DEALLOCATE_COMMAND_BUFFER SPI$DEALLOCATE_COMMAND_BUFFER Deallocates a port command buffer. Format SPI$DEALLOCATE_COMMAND_BUFFER Description The SPI$DEALLOCATE_COMMAND_BUFFER macro deallocates a port command buffer. Inputs to the SPI$DEALLOCATE_COMMAND_BUFFER macro include the following: Location Contents R4 R5 SCDRP$L_CDT SCDRP$W_CMD_ MAPREG SCDRP$W_CMD_ NUMREG Address of the SPDT. Address of the SCDRP. Address of the SCDT.
System Macros Invoked by Drivers SPI$DISCONNECT SPI$DISCONNECT Breaks a connection between a class driver and a SCSI port. Format SPI$DISCONNECT Description The SPI$DISCONNECT macro breaks a connection between a class driver and a SCSI device unit and deallocates the associated SCDT. The connection must not be busy when it is being disconnected. Normally a connection between a class driver and a SCSI device unit lasts throughout the runtime life of a system.
System Macros Invoked by Drivers SPI$FINISH_COMMAND SPI$FINISH_COMMAND Completes an I/O operation initiated with asynchronous event notification. Format SPI$FINISH_COMMAND Description The SPI$FINISH_COMMAND macro allows the host acting as a target to send a status byte, return the COMMAND COMPLETE message, and drive the SCSI bus to BUS FREE. The class driver’s callback routine should invoke SPI$FINISH_COMMAND or SPI$RELEASE_BUS, but not both, before exiting.
System Macros Invoked by Drivers SPI$GET_CONNECTION_CHAR SPI$GET_CONNECTION_CHAR Returns characteristics of an existing connection to a specified buffer. Format SPI$GET_CONNECTION_CHAR Description The SPI$GET_CONNECTION_CHAR macro returns characteristics of an existing connection to a specified buffer. The buffer format has the characteristics listed in Table 2–5.
System Macros Invoked by Drivers SPI$GET_CONNECTION_CHAR Table 2–5 (Cont.) SPI$GET_CONNECTION_CHAR Macro Buffer Characteristics Longword Contents 9 Command retry count. Maximum number of retries allowed on this connection to successfully send a command to the target device. Phase change timeout. Default timeout value (in seconds) for a target to change the SCSI bus phase or complete a data transfer. This value is also known as the DMA timeout.
System Macros Invoked by Drivers SPI$GET_CONNECTION_CHAR 2–78 Location Contents R2 Address of the connection characteristics buffer in which device characteristics are returned.
System Macros Invoked by Drivers SPI$MAP_BUFFER SPI$MAP_BUFFER Makes the process buffer involved in a data transfer available to the port driver. Format SPI$MAP_BUFFER [prio=HIGH] Parameters prio=HIGH If prio=HIGH is specified, deadlocks (that can be incurred when several devices are mapping buffers) are avoided. If the argument is not specified, the macro defaults to LOW priority. Description The SPI$MAP_BUFFER macro makes the process buffer involved in a data transfer accessible to the port driver.
System Macros Invoked by Drivers SPI$MAP_BUFFER Table 2–6 (Cont.) Inputs to the SPI$MAP_BUFFER Macro Location Contents SCDRP$L_SVA_USER SCDRP$L_SVAPTE SCDRP$L_SCSI_ FLAGS SCDRP$W_STS For direct DMA buffering, system virtual address of the process buffer to map in system space (S0 space) System virtual address of the pagetable entry that maps the first byte of the user buffer. SCSI mapping flags. If SCDRP$V_ S0BUF is set, SPI$MAP_BUFFER does not double-map the buffer into system space.
System Macros Invoked by Drivers SPI$QUEUE_COMMAND SPI$QUEUE_COMMAND Initiates a new I/O to the port driver for queued SCSI-2 command tagged requests. Format SPI$QUEUE_COMMAND Description The SPI$QUEUE_COMMAND initiates a new I/O to the port driver for queued SCSI-2 command tagged requests. This macro is similar to the SPI$SEND_ COMMAND, but SPI$QUEUE_COMMAND does not wait for command completion in the device before returning to the class driver.
System Macros Invoked by Drivers SPI$QUEUE_COMMAND Table 2–8 (Cont.) Inputs to the SPI$QUEUE_COMMAND Macro Location Contents SCDRP$L_SVA_USER SCDRP$L_STS_PTR SCDRP$W_FUNC SCDRP$L_SCDT System virtual address of the process buffer as mapped in system space (S0 space). Address of the status longword. The port driver copies the SCSI status byte it receives in the bus STATUS phase into the low-order byte of this buffer. Read or write operation. Address of the SCDT.
System Macros Invoked by Drivers SPI$RECEIVE_BYTES SPI$RECEIVE_BYTES Receives command, message, and data bytes from a device acting as an initiator on the SCSI bus. Format SPI$RECEIVE_BYTES Description The SPI$RECEIVE_BYTES macro allows the host to receive information from the device acting as an initiator. A class driver uses SPI$RECEIVE_BYTES to receive command, message, and data bytes. This macro uses DMA operations for the transfer of large segments of data where appropriate.
System Macros Invoked by Drivers SPI$RELEASE_BUS SPI$RELEASE_BUS Releases the SCSI bus. Format SPI$RELEASE_BUS Description The SPI$RELEASE_BUS macro allows the host acting as a target to release the SCSI bus. The class driver’s callback routine should invoke either SPI$RELEASE_BUS or SPI$FINISH_COMMAND, but not both, before exiting.
System Macros Invoked by Drivers SPI$RELEASE_QUEUE SPI$RELEASE_QUEUE Clears the frozen state of the SCSI-2 port driver queues. Format SPI$RELEASE_QUEUE Description The SPI$RELEASE_QUEUE macro clears the frozen state of the port driver queues allowing queue processing to resume and new I/O to be processed. The entry point routine in the port driver clears the SCDT$V_QUEUE_FROZEN bit in the SCDT$L_QUEUE_FLAGS longword mask. This bit is checked by the queue manager to signal when to resume queue processing.
System Macros Invoked by Drivers SPI$RESET SPI$RESET Resets the SCSI bus and SCSI port hardware. Format SPI$RESET Description The SPI$RESET macro first resets the SCSI bus and then resets the port hardware. A SCSI class driver should rarely invoke this macro; those class drivers that do use it should be aware of the impact of a reset operation on other devices on the same bus. The SCSI port driver logs an error when a class driver invokes the SPI$RESET macro.
System Macros Invoked by Drivers SPI$SEND_BYTES SPI$SEND_BYTES Sends command, message, and data bytes to a device acting as an initiator on the SCSI bus. Format SPI$SEND_BYTES Description The SPI$SEND_BYTES macro allows the host to send information to the device acting as an initiator. A class driver uses SPI$SEND_BYTES to send command, message, and data bytes. This macro uses DMA operations for the transfer of large segments of data where appropriate.
System Macros Invoked by Drivers SPI$SEND_COMMAND SPI$SEND_COMMAND Sends a command to a SCSI device. Format SPI$SEND_COMMAND Description The SPI$SEND_COMMAND macro sends a command to a SCSI device. A class driver invokes this macro, after calling SPI$ALLOCATE_COMMAND_BUFFER to allocate a port command buffer and formatting a SCSI command descriptor block in it.
System Macros Invoked by Drivers SPI$SEND_COMMAND Table 2–10 (Cont.) Inputs to the SPI$SEND_COMMAND Macro Location Contents SCDRP$L_SVA_USER SCDRP$L_STS_PTR SCDRP$L_CDT SCDRP$W_FUNC Address of the SCDT. System virtual address of the process buffer as mapped in system space (S0 space). Address of the status longword. The port driver copies the SCSI status byte it receives in the bus STATUS phase into the low-order byte of this buffer. Read or write operation.
System Macros Invoked by Drivers SPI$SENSE_PHASE SPI$SENSE_PHASE Returns the current phase of the SCSI bus. Format SPI$SENSE_PHASE Description The SPI$SENSE_PHASE macro allows the host to read the current SCSI bus phase, and the state of the ATN signal, while using the asynchronous event notification feature. A class driver must supply the address of the SPDT in R4 as input to the SPI$SENSE_PHASE macro.
System Macros Invoked by Drivers SPI$SET_CONNECTION_CHAR SPI$SET_CONNECTION_CHAR Sets characteristics of an existing connection. Format SPI$SET_CONNECTION_CHAR Description The SPI$SET_CONNECTION_CHAR macro sets characteristics of an existing SCSI connection. Prior to altering the characteristics of a connection, a SCSI class driver should read and examine the current connection characteristics using the SPI$GET_CONNECTION_CHAR macro.
System Macros Invoked by Drivers SPI$SET_CONNECTION_CHAR Table 2–12 (Cont.) SPI$SET_CONNECTION_CHAR Macro Settable Characteristics Longword Contents 8 Select retry count. Maximum number of retries allowed on this connection while waiting for the port to be selected by the target device. Command retry count. Maximum number of retries allowed on this connection to successfully send a command to the target device. Phase change timeout.
System Macros Invoked by Drivers SPI$SET_CONNECTION_CHAR Location Contents R0 Port status.
System Macros Invoked by Drivers SPI$SET_PHASE SPI$SET_PHASE Sets the bus to a new phase. Format SPI$SET_PHASE Description The SPI$SET_PHASE macro allows the host to set the SCSI bus to a new phase. A class driver uses this macro to drive the phase transitions of the SCSI bus while using the asynchronous event notification feature. Inputs to the SPI$SET_PHASE macro include the following: Location Contents R0 New SCSI bus phase. This SCSI-defined longword has the format shown in Figure 2–2.
System Macros Invoked by Drivers SPI$UNMAP_BUFFER SPI$UNMAP_BUFFER Releases port mapping resources and deallocates port DMA buffer space, as required to unmap a process buffer. Format SPI$UNMAP_BUFFER Description The SPI$UNMAP_BUFFER macro releases mapping resources and deallocates port DMA buffer space, as required to unmap a process buffer. Inputs to the SPI$UNMAP_BUFFER macro include the following: Location Contents R4 R5 Address of the SPDT. Address of the SCDRP.
System Macros Invoked by Drivers SWAPLONG SWAPLONG Swaps the bytes within each longword supplied. Format SWAPLONG longword Parameters longword The address of the longword data that requires the bytes to be swapped. Description When a data word is passed between a host CPU and a device with a differing byte-order pattern (big-endian and little-endian devices), the byte positions must be swapped.
System Macros Invoked by Drivers SWAPWORD SWAPWORD Swaps the bytes within each word supplied. Format SWAPWORD word Parameters word The address of the data (2 bytes) that requires the bytes to be swapped. Description When a data word is passed between a host CPU and a device with a differing byte-order pattern (big-endian and little-endian devices), the byte positions must be swapped. The SWAPWORD macro reads the location of the 2-byte data supplied in the word argument and swaps the byte positions.
System Macros Invoked by Drivers TIMEDWAIT TIMEDWAIT Waits a specified interval of time for an event or condition to occur. Format TIMEDWAIT time [,ins1] [,ins2] [,ins3] [,ins4] [,ins5] [,ins6] [,donelbl] [,imbedlbl] [,ublbl] Parameters time Number of 10-microsecond intervals to wait. The operating system multiplies this value by a processor-specific value in order to calculate the interval to wait.
System Macros Invoked by Drivers TIMEDWAIT [ublbl] Label placed at the instruction that performs the processor-specific delay after each execution of the loop of embedded instructions; embedded instructions can pass control here in order to skip the execution of the rest of the embedded instructions in a given execution of the embedded loop. Description The TIMEDWAIT macro waits for a period of time for an event or condition to occur.
System Macros Invoked by Drivers TIMEWAIT TIMEWAIT Waits for a specified bit to be cleared or set within a specified length of time. Format TIMEWAIT time ,bitval ,source ,context [,sense=.TRUE.] Parameters time Number of 10-microsecond intervals to wait. The operating system multiplies this value by a processor-specific value in order to calculate the interval to wait. The processor-specific value is inversely proportional to the speed of the processor, but is never less than 1.
System Macros Invoked by Drivers UNLOCK UNLOCK Relinquishes synchronized access to a system resource as appropriate to the processing environment. Format UNLOCK lockname [,newipl] [,condition] [,preserve=YES] Parameters lockname Name of the system resource to be released or restored. [newipl] Location containing the IPL to which to lower. A prior invocation of the LOCK macro may have stored this IPL value. [condition] Indication of a special use of the macro.
System Macros Invoked by Drivers UNLOCK_SYSTEM_PAGES UNLOCK_SYSTEM_PAGES Terminates a request to lock down a series of system pages. Format UNLOCK_SYSTEM_PAGES [ipl] Parameters [ipl] IPL at which to continue execution. Description The UNLOCK_SYSTEM_PAGES macro terminates a request to lock down a series of contiguous system pages. In a code segment that uses this locking technique, there must be exactly one UNLOCK_SYSTEM_PAGES macro call per LOCK_SYSTEM_PAGES macro call.
System Macros Invoked by Drivers $VEC $VEC Defines an entry in a port driver vector table within the context of a $VECINI macro. Format $VEC entry, routine Parameters entry Name of the vector table entry, specified without the PORT_ prefix. routine Name of the service routine within the driver that corresponds to the entry point. Description A terminal port driver uses the $VEC macro to validate and generate a vector table entry.
System Macros Invoked by Drivers $VECEND $VECEND Ends the scope of the $VECINI macro, thereby completing the definition of a port driver vector table. Format $VECEND [end] Parameter [end] Flag controlling the generation of the end of the vector table. This argument is generally omitted so that the $VECEND macro can generate the end of the vector table. Otherwise, the $VECEND macro does not generate the end of the table.
System Macros Invoked by Drivers $VECINI $VECINI Begins the definition of a port vector table. Format $VECINI drivername, null_routine [,prefix=PORT_] [,size=_LENGTH] Parameters drivername Prefix (usually two letters) of the driver name (for example, DZ). null_routine Address of the driver’s null entry point, usually specified in the format drivername$NULL. This address contains an RSB instruction. [,prefix=PORT_] Prefix to be added to the symbols defined in subsequent invocations of the $VEC macro.
System Macros Invoked by Drivers $VIELD, _VIELD $VIELD, _VIELD Defines symbolic offsets and masks for bit fields. Format $VIELD _VIELD mod ,inibit ,fields Parameters mod Module in which this bit field is defined; the prefix portion of the name of the symbol to be defined. inibit Bit within the field on which the positions of the bits to be defined are based.
System Macros Invoked by Drivers $VIELD, _VIELD Example $EQULST XA_K_,,0,1,<_VIELD XX_CSR,0,<,,,,,,> ;Define CSR bit values ;Control/status register ;Start device ;Function bits ;Extended address bits ;Enable interrupts ;Maintenance bit ;Status from other processors This code excerpt produces the following symbols: . . .
System Macros Invoked by Drivers WFIKPCH, WFIRLCH WFIKPCH, WFIRLCH Suspends a driver fork thread and folds its context into a fork block in anticipation of a device interrupt or timeout. When WFIKPCH is invoked, the fork thread keeps ownership of the controller channel while waiting; when WFIRLCH is invoked, the fork thread releases ownership of the controller channel.
System Macros Invoked by Drivers WFIKPCH, WFIRLCH The suspended code thread is resumed by the occurrence of an interrupt signaling the successful completion of a device operation. When an interrupt occurs, control returns to the instruction following the macro. If a device timeout occurs before an interrupt can be posted, the timeout handling routine specified in excpt is called. In both instances, subsequent code can assume that only R3 and R4 have been preserved across the suspension.
System Macros Invoked by Drivers WRITE_CSR WRITE_CSR Writes data to a device control and status register. Format WRITE_CSR src, dest [,length=LONGWORD] [,error=BUGCHECK] [,environ=GENERIC] [,vme=pio_reg] Parameters src Location containing the data to be written to the register. dest System virtual address or pseudo CSR address of the register in I/O space. [length=LONGWORD] Size of the CSR access: BYTE, WORD, or LONGWORD. Default is LONGWORD. [error=BUGCHECK] Proper disposition on error.
3 Operating System Routines This chapter describes the operating system routines that are used by device drivers and employs the following conventions: • Most routines reside in modules within the [SYS] facility of the operating system. A routine description provides a facility name (in brackets) only if the module is not located in the [SYS] facility. • Many routines are not directly called by device drivers.
Operating System Routines BYTE_SWAP_LONG BYTE_SWAP_LONG Swaps the bytes within each longword in a given data transfer buffer. Module [DRIVER]VME_SUPPORT Input Location R0 Contents Length of the data transfer buffer in bytes. This number should fall on a longword boundary. Address of the data transfer buffer. R1 Output Location R0, R1 Contents Destroyed (All other registers preserved) Synchronization A driver calls BYTE_SWAP_LONG in kernel mode at or above IPL$_ASTDEL.
Operating System Routines BYTE_SWAP_WORD BYTE_SWAP_WORD Swaps the bytes within each word in a given data transfer buffer. Module [DRIVER]VME_SUPPORT Input Location R0 Contents Length of the data transfer buffer in bytes. This number should fall on a word boundary. Address of the data transfer buffer. R1 Output Location R0, R1 Contents Destroyed (All other registers preserved) Synchronization A driver calls BYTE_SWAP_WORD in kernel mode at or above IPL$_ASTDEL.
Operating System Routines COM$DELATTNAST COM$DELATTNAST Delivers all attention ASTs linked in the specified list. Module COMDRVSUB Input Location R4 R5 Contents Address of listhead of AST control blocks Address of UCB Location Specified listhead R0 through R11 Contents Empty Preserved Output Synchronization COM$DELATTNAST executes and exits at the caller’s IPL, and acquires no spinlocks. However, the caller must be executing at IPL3 or higher to avoid certain race conditions.
Operating System Routines COM$DRVDEALMEM COM$DRVDEALMEM Deallocates system dynamic memory. Module COMDRVSUB Input Location R0 IRP$W_SIZE Contents Address of block to be deallocated Size of block in bytes (must be at least 24 bytes long) Location R0 through R11 Contents Preserved Output Synchronization Drivers can call COM$DRVDEALMEM from any IPL. COM$DRVDEALMEM executes at the caller’s IPL and returns control at that IPL. The caller retains any spinlocks it held at the time of the call.
Operating System Routines COM$FLUSHATTNS COM$FLUSHATTNS Flushes an attention AST list.
Operating System Routines COM$POST, COM$POST_NOCNT COM$POST, COM$POST_NOCNT Initiates device-independent postprocessing of an I/O request independent of the status of the device unit.
Operating System Routines COM$SETATTNAST COM$SETATTNAST Enables or disables attention ASTs.
Operating System Routines COM$SETATTNAST Description A driver FDT routine calls COM$SETATTNAST to service a $QIO request that specifies a set-attention-AST function. If the p1 argument of the request contains a zero, COM$SETATTNAST transfers control to COM$FLUSHATTNS, which disables all ASTs indicated by the PID and I/O channel number (IRP$W_CHAN). COM$FLUSHATTNS searches through the AST control block (ACB) list, extracts each identified ACB, deallocates, and returns to the caller of COM$SETATTNAST.
Operating System Routines ERL$DEVICERR, ERL$DEVICTMO, ERL$DEVICEATTN ERL$DEVICERR, ERL$DEVICTMO, ERL$DEVICEATTN Allocate an error message buffer and record in it information concerning the error.
Operating System Routines ERL$DEVICERR, ERL$DEVICTMO, ERL$DEVICEATTN • Initializes the buffer with the current system time, error log sequence number, and error type code. These routines use the following error type codes: ERL$DEVICERR ERL$DEVICTMO ERL$DEVICEATTN Device error (EMB$C_DE) Device timeout (EMB$C_DT) Device attention (EMB$C_DA) • Places the address of the error message buffer in UCB$L_EMB. • Sets UCB$V_ERLOGIP in UCB$L_STS.
Operating System Routines EXE$ABORTIO EXE$ABORTIO Completes the servicing of an I/O request without returning status to the I/O status block specified in the request.
Operating System Routines EXE$ABORTIO This interrupt causes I/O postprocessing to occur before the remaining instructions in EXE$ABORTIO are executed.
Operating System Routines EXE$ALLOCBUF, EXE$ALLOCIRP EXE$ALLOCBUF, EXE$ALLOCIRP Allocates a buffer from nonpaged pool for a buffered-I/O operation. Module MEMORYALC Input Location R1 PCB$L_STS Contents Size of requested buffer in bytes (EXE$ALLOCBUF only). This value should include the 12 bytes required to store header information. PCB$V_SSRWAIT clear if the process should wait if no memory is available for requested buffer; set if resource wait mode is disabled.
Operating System Routines EXE$ALLOCBUF, EXE$ALLOCIRP The caller must check and adjust process quotas (JIB$L_BYTCNT or JIB$L_ BYTLM, or both) by calling EXE$DEBIT_BYTCNT or EXE$DEBIT_BYTCNT_ BYTLM. (Note that you can perform this task and allocate a buffer of the requested size by using the routines EXE$DEBIT_BYTCNT_ALO and EXE$DEBIT_BYTCNT_BYTLM_ALO. These routines invoke EXE$ALLOCBUF.
Operating System Routines EXE$ALONONPAGED EXE$ALONONPAGED Allocates a block of memory from nonpaged pool. Module MEMORYALC Input Location R1 Contents Size of requested block in bytes Location R0 R1 Contents SS$_NORMAL or SS$_INSFMEM Size of the allocated block, which may be larger than the requested size Address of allocated block Output R2 Synchronization EXE$ALONONPAGED executes at its caller’s IPL and at IPL$_POOL, obtaining the POOL spinlock in a multiprocessing environment.
Operating System Routines EXE$ALOPHYCNTG EXE$ALOPHYCNTG Allocates a physically contiguous block of memory. Module MEMORYALC Input Location R1 Contents Number of physically contiguous pages to allocate Location R0 R2 Contents SS$_NORMAL, SS$_INSFMEM, or SS$_INSFSPTS System virtual address of allocated block, if the allocation succeeds Output Synchronization EXE$ALOPHYCNTG raises IPL to IPL$_SYNCH and obtains the MMG spinlock.
Operating System Routines EXE$ALTQUEPKT EXE$ALTQUEPKT Delivers an IRP to a driver’s alternate start-I/O routine without regard for the status of the device. Module SYSQIOREQ Input Location R3 R5 DDT$L_ALTSTART UCB$B_FLCK UCB$L_DDB DDB$L_DDT Contents Address of IRP Address of UCB Address of alternate start-I/O routine Fork lock index Address of unit’s DDB Address of DDT Location R0 through R5 Contents Destroyed Output Synchronization A driver FDT routine calls EXE$ALTQUEPKT at IPL$_ASTDEL.
Operating System Routines EXE$CRAM_CMD EXE$CRAM_CMD Processes a CSR read or write to a device connected to a remote bus.
Operating System Routines EXE$CRAM_CMD When the operation completes, EXE$CRAM_CMD checks the status return and processes any errors in accordance with the error argument of the READ_CSR or WRITE_CSR macro. If the operation was a successful read, the returned data is stored on the stack. If a CRAM was allocated at the start of the routine, the CRAM is deallocated via a call to routine IOC$DEALLOCATE_CRAM. EXE$CRAM_CMD then returns to the caller. Digital does not recommend calling this routine directly.
Operating System Routines EXE$CREDIT_BYTCNT, EXE$CREDIT_BYTCNT_BYTLM EXE$CREDIT_BYTCNT, EXE$CREDIT_BYTCNT_BYTLM Return credit to a job’s buffered-I/O byte count quota and byte limit.
Operating System Routines EXE$CREDIT_BYTCNT, EXE$CREDIT_BYTCNT_BYTLM Description EXE$CREDIT_BYTCNT provides a synchronized method of crediting a job’s byte count quota to JIB$L_BYTCNT. EXE$CREDIT_BYTCNT_BYTLM also credits a job’s byte limit to JIB$L_BYTLM. Both routines round the value specified in R0 up to the nearest 16-byte boundary before applying it to the JIB. Both check JIB$V_BYTCNT_WAITERS to determine if any process is waiting for the return of nonpaged pool quota for this JIB.
Operating System Routines EXE$DEANONPAGED, EXE$DEANONPGDSIZ EXE$DEANONPAGED, EXE$DEANONPGDSIZ Deallocates a block of memory and returns it to nonpaged pool.
Operating System Routines EXE$DEBIT_BYTCNT(_NW), EXE$DEBIT_BYTCNT_BYTLM(_NW) EXE$DEBIT_BYTCNT(_NW), EXE$DEBIT_BYTCNT_BYTLM(_NW) Determine whether a job’s buffered I/O byte count quota usage permits the process to be granted additional buffered I/O and, if so, adjust the job’s byte count quota and byte limit.
Operating System Routines EXE$DEBIT_BYTCNT(_NW), EXE$DEBIT_BYTCNT_BYTLM(_NW) Description EXE$DEBIT_BYTCNT and EXE$DEBIT_BYTCNT_NW check whether a process has sufficient quota for a buffer of the specified size and, if so, deduct the corresponding number of bytes from the job’s byte count quota. EXE$DEBIT_ BYTCNT_BYTLM and EXE$DEBIT_BYTCNT_BYTLM_NW also adjust the job’s byte limit. All routines round the value specified in R1 up to the nearest 16-byte boundary before applying it to the JIB.
Operating System Routines EXE$DEBIT_BYTCNT_ALO, EXE$DEBIT_BYTCNT_BYTLM_ALO EXE$DEBIT_BYTCNT_ALO, EXE$DEBIT_BYTCNT_BYTLM_ALO Determine whether a job’s buffered I/O byte count quota usage permits the process to be granted additional buffered I/O and, if so, allocates the requested amount of nonpaged pool and adjust the job’s byte count quota and byte limit.
Operating System Routines EXE$DEBIT_BYTCNT_ALO, EXE$DEBIT_BYTCNT_BYTLM_ALO Synchronization EXE$DEBIT_BYTCNT_ALO and EXE$DEBIT_BYTCNT_BYTLM_ALO raise IPL to IPL$_SYNCH and obtain the JIB spinlock in a multiprocessing environment. Their callers cannot be executing above IPL$_SYNCH or hold any spinlock. EXE$DEBIT_BYTCNT_ALO and EXE$DEBIT_BYTCNT_BYTLM_ALO return control to their callers at IPL$_ASTDEL.
Operating System Routines EXE$FINISHIO, EXE$FINISHIOC EXE$FINISHIO, EXE$FINISHIOC Complete the servicing of an I/O request and return status to the I/O status block specified in the request.
Operating System Routines EXE$FINISHIO, EXE$FINISHIOC • Inserts the IRP in the local processor’s I/O postprocessing queue. • If the queue is empty, requests a software interrupt from the local processor at IPL$_IOPOST. This interrupt causes postprocessing to occur before the remaining instructions in EXE$FINISHIO or EXE$FINISHIOC are executed.
Operating System Routines EXE$FORK EXE$FORK Creates a fork process on the local processor. Module FORKCNTRL Macro FORK Input Location R5 00(SP) 04(SP) FKB$B_FLCK Contents Address of fork block Return PC of caller Return PC of caller’s caller Fork lock index or fork IPL Location R3 R4 FKB$L_FR3 (UCB$L_ FR3) FKB$L_FR4 (UCB$L_ FR4) FKB$L_FPC (UCB$L_ FPC) Contents Destroyed Fork IPL R3 of caller Output R4 of caller 00(SP) Synchronization EXE$FORK acquires no spinlocks and leaves IPL unchanged.
Operating System Routines EXE$INSERTIRP EXE$INSERTIRP Inserts an IRP into the specified queue of IRPs according to the base priority of the process that issued the I/O request.
Operating System Routines EXE$INSIOQ, EXE$INSIOQC EXE$INSIOQ, EXE$INSIOQC Insert an IRP in a device’s pending-I/O queue and call the driver’s start-I/O routine if the device is not busy.
Operating System Routines EXE$INSIOQ, EXE$INSIOQC Description EXE$INSIOQ and EXE$INSIOQC increment UCB$W_QLEN and proceed according to the status of the device (as indicated by UCB$V_BSY in UCB$W_ STS) as follows: • If the device is busy, call EXE$INSERTIRP to place the IRP on the device’s pending-I/O queue. • If the device is idle, call IOC$INITIATE to begin device processing of the I/O request immediately. IOC$INITIATE transfers control to the driver’s start-I/O routine.
Operating System Routines EXE$INSTIMQ EXE$INSTIMQ Inserts a timer queue element (TQE) into the timer queue.
Operating System Routines EXE$IOFORK EXE$IOFORK Creates a fork process on the local processor for a device driver, disabling timeouts from the associated device.
Operating System Routines EXE$IOFORK If FKB$B_FLCK contains a fork lock index, EXE$IOFORK determines the fork IPL by using this value as an index into the spinlock IPL vector (SMP$AR_ IPLVEC). EXE$IOFORK inserts the fork block into the fork queue on the local processor (headed by CPU$Q_SWIQFL) corresponding to this IPL. If the queue is empty, EXE$IOFORK issues a SOFTINT macro, requesting a software interrupt from the local processor at that fork IPL.
Operating System Routines EXE$MODIFY EXE$MODIFY Translates a logical read or write function into a physical read or write function, transfers $QIO system service parameters to the IRP, validates and prepares a user buffer, and proceeds with or aborts a direct-I/O, DMA read/write operation. Module SYSQIOFDT Input Location R3 R4 R5 R6 R7 R8 00(AP) 04(AP) 12(AP) IRP$W_FUNC Contents Address of IRP. Address of current PCB. Address of UCB. Address of CCB. Bit number of the I/O function code.
Operating System Routines EXE$MODIFY Description A driver uses EXE$MODIFY as an FDT routine when the driver must both read from and write to the user-specified buffer. Because EXE$MODIFY transfers control to EXE$QIODRVPKT if its operations are successful or EXE$ABORTIO if they are not, it must be the last FDT routine called to perform the preprocessing of I/O read/write requests. A driver cannot use EXE$MODIFY for buffered I/O operations.
Operating System Routines EXE$MODIFY • If MMG$IOLOCK fails, it returns SS$_ACCVIO, SS$_INSFWSL, or page fault status to EXE$MODIFYLOCKR. If either EXE$READCHKR or MMG$IOLOCK returns an error status other than a page fault condition, EXE$MODIFYLOCKR calls EXE$ABORTIO. In the event of a page fault, EXE$MODIFYLOCKR adjusts direct I/O count and AST count to the values they held before the I/O request, deallocates the IRP, and restarts the I/O request at the $QIO system service.
Operating System Routines EXE$MODIFYLOCK, EXE$MODIFYLOCKR EXE$MODIFYLOCK, EXE$MODIFYLOCKR Validate and prepare a user buffer for a direct-I/O, DMA read/write operation.
Operating System Routines EXE$MODIFYLOCK, EXE$MODIFYLOCKR EXE$MODIFYLOCK calls EXE$MODIFYLOCKR. EXE$MODIFYLOCKR calls EXE$READCHKR, which performs the following tasks: • Moves the transfer byte count into IRP$L_BCNT. If the byte count is negative, it returns SS$_BADPARAM status to EXE$MODIFYLOCKR.
Operating System Routines EXE$MODIFYLOCK, EXE$MODIFYLOCKR A driver FDT routine that calls EXE$MODIFYLOCKR must distinguish between successful and unsuccessful status when it resumes, as shown in the following example: JSB G^EXE$MODIFYLOCKR BLBS BUF_LOCK_OK BUF_LOCK_FAIL: ; ; clean up this $QIO bookkeeping ; RSB BUF_LOCK_OK: . . .
Operating System Routines EXE$ONEPARM EXE$ONEPARM Copies a single $QIO parameter into the IRP and delivers the IRP to a driver’s start-I/O routine.
Operating System Routines EXE$QIODRVPKT EXE$QIODRVPKT Delivers an IRP to the driver’s start-I/O routine or pending-I/O queue, returns success status in R0, lowers IPL to 0, and returns to the system service dispatcher.
Operating System Routines EXE$QIODRVPKT When EXE$INSIOQ returns to EXE$QIODRVPKT at IPL$_ASTDEL, EXE$QIODRVPKT returns control to the system service dispatcher in the following steps: 1. Loads SS$_NORMAL into R0 2. Lowers IPL to zero 3.
Operating System Routines EXE$QIORETURN EXE$QIORETURN Sets a success status code in R0, lowers IPL to 0, and returns to the system service dispatcher. Module SYSQIOREQ Input Location R5 UCB$B_FLCK Contents Address of UCB Fork lock index or fork IPL Location R0 Contents SS$_NORMAL Output Synchronization EXE$QIORETURN is typically called by a driver FDT routine at IPL$_ASTDEL. Its caller cannot be executing above fork IPL or hold any spinlocks other than the appropriate fork lock.
Operating System Routines EXE$READ EXE$READ Translates a logical read function into a physical read function, transfers $QIO system service parameters to the IRP, validates and prepares a user buffer, and proceeds with or aborts a direct-I/O, DMA read/write operation. Module SYSQIOFDT Input Location R3 R4 R5 R6 R7 R8 00(AP) 04(AP) 12(AP) IRP$W_FUNC Contents Address of IRP. Address of current PCB. Address of UCB. Address of CCB. Bit number of the I/O function code. Address of FDT entry for this routine.
Operating System Routines EXE$READ Description A driver uses EXE$READ as an FDT routine when the driver must write to the user-specified buffer. Because EXE$READ transfers control to EXE$QIODRVPKT if its operations are successful or EXE$ABORTIO if they are not, it must be the last FDT routine called to perform the preprocessing of read I/O requests. A driver cannot use EXE$READ for buffered-I/O operations.
Operating System Routines EXE$READ • If MMG$IOLOCK fails, it returns SS$_ACCVIO, SS$_INSFWSL, or page fault status to EXE$READLOCKR. If either EXE$READCHKR or MMG$IOLOCK returns an error status other than a page fault condition, EXE$READLOCKR transfers control to EXE$ABORTIO. In the event of a page fault, EXE$READLOCKR adjusts direct I/O count and AST count to the values they held before the I/O request, deallocates the IRP, and restarts the I/O request at the $QIO system service.
Operating System Routines EXE$READCHK, EXE$READCHKR EXE$READCHK, EXE$READCHKR Verify that a process has write access to the pages in the buffer specified in a $QIO request.
Operating System Routines EXE$READCHK, EXE$READCHKR • Determines whether the specified buffer is write accessible for a read I/O function, with one of the following results: If the buffer allows write access, EXE$READCHKR sets IRP$V_FUNC in IRP$W_STS and returns SS$_NORMAL to its caller. If the buffer does not allow write access, EXE$READCHKR returns SS$_ ACCVIO status to its caller.
Operating System Routines EXE$READLOCK, EXE$READLOCKR EXE$READLOCK, EXE$READLOCKR Validate and prepare a user buffer for a direct-I/O, DMA read operation.
Operating System Routines EXE$READLOCK, EXE$READLOCKR EXE$READLOCK calls EXE$READLOCKR. EXE$READLOCKR calls EXE$READCHKR, which performs the following tasks: • Moves the transfer byte count into IRP$L_BCNT. If the byte count is negative, it returns SS$_BADPARAM status to EXE$READLOCKR.
Operating System Routines EXE$READLOCK, EXE$READLOCKR A driver FDT routine that calls EXE$READLOCKR must distinguish between successful and unsuccessful status when it resumes, as shown in the following example: JSB G^EXE$READLOCKR BLBS BUF_LOCK_OK BUF_LOCK_FAIL: ; ; clean up this $QIO bookkeeping ; RSB BUF_LOCK_OK: . . .
Operating System Routines EXE$RMVTIMQ EXE$RMVTIMQ Removes timer queue elements (TQEs) from the timer queue. Module EXSUBROUT Input Location R2 R3 R4 R5 Contents Access mode (unused by system subroutine) Request identification (unused by system subroutine) Type of TQE entry (TQE$B_RQTYPE) to remove from queue (TQE$C_ SSNGL) if bit 31 is zero. If bit 31 is set, then R4 contains the address of the TQE. Process ID (TQE$L_PID) Output Location R0 R1 Contents If R0=1, then at least one TQE was removed.
Operating System Routines EXE$SENSEMODE EXE$SENSEMODE Copies device-dependent characteristics from the device’s UCB into R1, writes a success code into R0, and completes the I/O operation.
Operating System Routines EXE$SETCHAR, EXE$SETMODE EXE$SETCHAR, EXE$SETMODE Write device-specific status and control information into the device’s UCB and complete the I/O request (EXE$SETCHAR); or write the information into the IRP and deliver the IRP to the driver’s start-I/O routine (EXE$SETMODE).
Operating System Routines EXE$SETCHAR, EXE$SETMODE Description A driver uses EXE$SETCHAR or EXE$SETMODE as an FDT routine to process the set-device-mode (IO$_SETMODE) and set-device-characteristics (IO$_ SETCHAR) functions. If setting device characteristics requires device activity or synchronization with fork processing, the driver’s FDT entry must specify EXE$SETMODE. Otherwise, it can specify EXE$SETCHAR.
Operating System Routines EXE$SNDEVMSG EXE$SNDEVMSG Builds and sends a device-specific message to the mailbox of a system process, such as the job controller or OPCOM. Module MBDRIVER Input Location R3 Contents Address of mailbox UCB. (SYS$AR_JOBCTLMB contains the address of the job controller’s mailbox; SYS$AR_OPRMBX contains the address of OPCOM’s mailbox.
Operating System Routines EXE$SNDEVMSG EXE$SNDEVMSG then calls EXE$WRTMAILBOX to send the message to a mailbox. EXE$SNDEVMSG can fail for any of the following reasons: 3–60 • The message is too large for the mailbox (SS$_MBTOOSML). • The message mailbox is full of messages (SS$_MBFULL). • The system is unable to allocate memory for the message (SS$_INSFMEM). • The caller lacks privilege to write to the mailbox (SS$_NOPRIV).
Operating System Routines EXE$WRITE EXE$WRITE Translates a logical write function into a physical write function, transfers $QIO system service parameters to the IRP, validates and prepares a user buffer, and proceeds with or aborts a direct-I/O, DMA read/write operation. Module SYSQIOFDT Input Location R3 R4 R5 R6 R7 R8 00(AP) 04(AP) 12(AP) IRP$W_FUNC Contents Address of IRP. Address of current PCB. Address of UCB. Address of CCB. Bit number of the I/O function code.
Operating System Routines EXE$WRITE Description A driver uses EXE$WRITE as an FDT routine when the driver must read from the user-specified buffer. Because EXE$WRITE transfers control to EXE$QIODRVPKT if its operations are successful or EXE$ABORTIO if they are not, it must be the last FDT routine called to perform the preprocessing of write I/O requests. A driver cannot use EXE$WRITE for buffered I/O operations.
Operating System Routines EXE$WRITECHK, EXE$WRITECHKR EXE$WRITECHK, EXE$WRITECHKR Verify that a process has read access to the pages in the buffer specified in a $QIO request.
Operating System Routines EXE$WRITECHK, EXE$WRITECHKR If the buffer does not allow read access, EXE$WRITECHKR returns SS$_ACCVIO status to its caller. If the initial call was to EXE$WRITECHK, and EXE$WRITECHKR returns error status, EXE$WRITECHK transfers control to EXE$ABORTIO to terminate the I/O request. If the initial call was to EXE$WRITECHKR, and an error occurs, EXE$WRITECHKR returns control to the driver. Otherwise, these routines return success status to their callers.
Operating System Routines EXE$WRITELOCK, EXE$WRITELOCKR EXE$WRITELOCK, EXE$WRITELOCKR Validate and prepare a user buffer for a direct-I/O, DMA write operation.
Operating System Routines EXE$WRITELOCK, EXE$WRITELOCKR EXE$WRITELOCK calls EXE$WRITELOCKR. EXE$WRITELOCKR calls EXE$WRITECHKR, which performs the following tasks: • Moves the transfer byte count into IRP$L_BCNT. If the byte count is negative, it returns SS$_BADPARAM status to EXE$WRITELOCKR. • Determines if the specified buffer is write accessible for a write I/O function, with one of the following results: If the buffer allows read access, EXE$WRITECHKR returns SS$_ NORMAL to EXE$WRITELOCKR.
Operating System Routines EXE$WRITELOCK, EXE$WRITELOCKR A driver FDT routine that calls EXE$WRITELOCKR must distinguish between successful and unsuccessful status when it resumes, as shown in the following example: JSB G^EXE$WRITELOCKR BLBS BUF_LOCK_OK BUF_LOCK_FAIL: ; ; clean up this $QIO bookkeeping ; RSB BUF_LOCK_OK: . . .
Operating System Routines EXE$WRTMAILBOX EXE$WRTMAILBOX Sends a message to a mailbox. Module MBDRIVER Input Location R3 R4 R5 Mailbox UCB fields Contents Message size Message address Address of mailbox UCB Location R0 Contents SS$_NORMAL, SS$_MBTOOSML, SS$_MBFULL, SS$_INSFMEM, or SS$_NOPRIV Destroyed Output R1 and R2 Synchronization Because EXE$WRTMAILBOX raises IPL to IPL$_MAILBOX and obtains the MAILBOX spinlock in a multiprocessing environment, its caller cannot be executing above IPL$_MAILBOX.
Operating System Routines EXE$ZEROPARM EXE$ZEROPARM Processes an I/O function code that requires no parameters. Module SYSQIOFDT Input Location R3 R4 R5 R6 R7 R8 Contents Address of IRP Address of current PCB Address of UCB Address of CCB Bit number of the I/O function code Address of FDT entry for this routine Location IRP$L_MEDIA Contents 0 Output Synchronization EXE$ZEROPARM is called as a driver FDT routine at IPL$_ASTDEL.
Operating System Routines IOC$ALLOCATE_CRAM IOC$ALLOCATE_CRAM Allocates a control register access mailbox (CRAM). Module [SYSLOA]CRAM_ROUTINES_LSB Input Location 04(SP) Contents Reserved for returned address of CRAM Location 04(SP) R0 Contents Address of CRAM Status of operation Output Synchronization During normal processing, IOC$ALLOCATE_CRAM uses no spinlocks.
Operating System Routines IOC$ALOALTMAP, IOC$ALOALTMAPN, IOC$ALOALTMAPSP IOC$ALOALTMAP, IOC$ALOALTMAPN, IOC$ALOALTMAPSP Allocate a set of Q22–bus alternate map registers. Module [SYSLOA]MAPSUBxxx Input Location R3 R4 R5 UCB$W_BCNT UCB$W_BOFF UCB$L_CRB CRB$L_INTD+ VEC$L_ADP CRB$L_INTD+ VEC$W_MAPALT ADP$W_MR2NREGAR, ADP$W_MR2FREGAR, ADP$L_MR2ACTMDR Contents Number of alternate map registers to allocate (IOC$ALOALTMAPN and IOC$ALOALTMAPSP only).
Operating System Routines IOC$ALOALTMAP, IOC$ALOALTMAPN, IOC$ALOALTMAPSP Synchronization Callers of IOC$ALOALTMAP, IOC$ALOALTMAPN, or IOC$ALOALTMAPSP may be executing at fork IPL or above and must hold the corresponding fork lock in a multiprocessing environment. Each routine returns control to its caller at the caller’s IPL. The caller retains any spinlocks it held at the time of the call.
Operating System Routines IOC$ALOTCMAP_DMA, IOC$ALOTCMAP_DMAN IOC$ALOTCMAP_DMA, IOC$ALOTCMAP_DMAN Allocate a set of TURBOchannel DMA map registers.
Operating System Routines IOC$ALOTCMAP_DMA, IOC$ALOTCMAP_DMAN Synchronization The caller of IOC$ALOTCMAP_DMA or IOC$ALOTCMAP_DMAN must be executing at fork IPL or above and must hold the corresponding fork lock (typically IOLOCK8) in a multiprocessing environment. Either routine returns control to its caller at the caller’s IPL. The caller retains any spinlocks it held at the time of the call. Description IOC$ALOTCMAP_DMA and IOC$ALOTCMAP_DMAN allocate a contiguous set of TURBOchannel DMA map registers.
Operating System Routines IOC$ALOUBAMAP, IOC$ALOUBAMAPN IOC$ALOUBAMAP, IOC$ALOUBAMAPN Allocate a set of UNIBUS map registers or a set of the first 496 Q22–bus map registers. Module IOSUBNPAG Input Location R3 R5 UCB$W_BCNT UCB$W_BOFF UCB$L_CRB CRB$L_INTD+ VEC$L_ADP CRB$L_INTD+ VEC$W_MAPREG ADP$W_MRNREGARY, ADP$W_MRFREGARY, ADP$L_MRACTMDRS Contents Number of map registers to allocate (IOC$ALOUBAMAPN only). The value should account for one extra register needed to prevent a transfer overrun.
Operating System Routines IOC$ALOUBAMAP, IOC$ALOUBAMAPN Description IOC$ALOUBAMAP and IOC$ALOUBAMAPN allocate a contiguous set of UNIBUS map registers or a set of the first 496 Q22–bus map registers and record the allocation in the ADP and CRB. These routines differ in the way in which they determine the number of the map registers they allocate: • IOC$ALOUBAMAP calculates the number of needed map registers using the values contained in UCB$W_BCNT and UCB$W_BOFF.
Operating System Routines IOC$ALOVMEMAP_DMA, IOC$ALOVMEMAP_DMAN IOC$ALOVMEMAP_DMA, IOC$ALOVMEMAP_DMAN Allocate a set of VME DMA map registers.
Operating System Routines IOC$ALOVMEMAP_DMA, IOC$ALOVMEMAP_DMAN Synchronization The caller of IOC$ALOVMEMAP_DMA or IOC$ALOVMEMAP_DMAN must be executing at fork IPL or above and must hold the corresponding fork lock (typically IOLOCK8) in a multiprocessing environment. Either routine returns control to its caller and the caller’s IPL. The caller retains any spinlocks it held at the time of the call. Description IOC$ALOVMEMAP_DMA and IOC$ALOVMEMAP_DMAN allocate a contiguous set of VME DMA map registers.
Operating System Routines IOC$ALOVMEMAP_PIO IOC$ALOVMEMAP_PIO Alocates a set of VME PIO map registers. Module [DRIVER]VMEPIO_XMI, VMEPIO_TC Input Location R3 UCB$L_CRB CRB$L_INTD+ VEC$L_ADP ADP$W_MR2NREGAR, ADP$W_MR2FREGAR, ADP$L_MR2ACTMDR Contents Number of map registers to allocate Address of CRB Address of ADP Location R0 R1 R2 CRB$L_INTD+ VEC$B_NUMALT ADP$W_MR2NREGAR, ADP$W_MR2FREGAR, ADP$L_MR2ACTMDR Contents SS$_NORMAL or SS$_INSFMAPREG Destroyed Address of ADP Number of map registers allocated.
Operating System Routines IOC$ALOVMEMAP_PIO Note that if there are not enough map registers available, your driver can put a fork block onto the map register allocation wait queue in the ADP (ADP$L_ MRQFL). When registers are released, the release routine checks for waiting fork threads. If any threads are waiting, the routine attempts to complete the allocation at that time.
Operating System Routines IOC$ALOXBIMAP, IOC$ALOXBIMAPN IOC$ALOXBIMAP, IOC$ALOXBIMAPN Allocate a set of XBI+ map registers.
Operating System Routines IOC$ALOXBIMAP, IOC$ALOXBIMAPN Description IOC$ALOXBIMAP and IOC$ALOXBIMAPN allocate a contiguous set of XBI+ map registers and record the allocation in the ADP and CRB. These routines differ in the way in which they determine the number and location of the map registers they allocate: • IOC$ALOXBIMAP calculates the number of map registers required using the values contained in UCB$W_BCNT and UCB$W_BOFF. • IOC$ALOXBIMAPN uses the value in R3 as the number of required registers.
Operating System Routines IOC$ALOXBIMAPRM, IOC$ALOXBIMAPRMN IOC$ALOXBIMAPRM, IOC$ALOXBIMAPRMN Permanently allocate a set of XBI+ map registers.
Operating System Routines IOC$ALOXBIMAPRM, IOC$ALOXBIMAPRMN Description IOC$ALOXBIMAPRM and IOC$ALOXBIMAPRMN permanently allocate a contiguous set of XBI+ map registers and record the allocation in the ADP and CRB. These routines differ in the way in which they determine the number and location of the map registers they allocate: • IOC$ALOXBIMAPRM calculates the number of map registers required using the values contained in UCB$W_BCNT and UCB$W_BOFF.
Operating System Routines IOC$APPLYECC IOC$APPLYECC Applies an ECC correction to data transferred from a disk device into memory.
Operating System Routines IOC$CANCELIO IOC$CANCELIO Conditionally marks a UCB so that its current I/O request will be canceled.
Operating System Routines IOC$CANCELIO Description IOC$CANCELIO cancels I/O to a device in the following device-independent manner: 1. It confirms that the device is busy by examining the device-busy bit in the UCB status longword (UCB$V_BSY in UCB$L_STS). 2. It confirms that the IRP in progress on the device originates from the current process (that is, the contents of IRP$L_PID and PCB$L_PID are identical). 3.
Operating System Routines IOC$CRAM_IO IOC$CRAM_IO Initiates an I/O operation to a device on a remote bus and waits for the operation to complete. Module [SYSLOA]CRAM_ROUTINES_LSB Input Location 04(SP) Contents Address of CRAM Location R0 Contents Status indicating success or failure of the operation Output Synchronization IOC$CRAM_IO executes at the IPL necessary to read and write CSRs. Description IOC$CRAM_IO is called by routine EXE$CRAM_CMD.
Operating System Routines IOC$CRAM_IO • If the operation does not complete within the timeout interval (found at location CRAM$Q_WAIT_TIME), the routine returns a status of SS$_ TIMEOUT. Bit CRAM$V_CRAM_IN_USE is left set. If IOC$CRAM_IO returns a status of SS$_NORMAL for a read operation, the requested data is stored in HW_CRAM$Q_RDATA of the hardware I/O mailbox.
Operating System Routines IOC$DEALLOCATE_CRAM IOC$DEALLOCATE_CRAM Deallocates a control register access mailbox (CRAM). Module [SYSLOA]CRAM_ROUTINES_LSB Input Location 04(SP) Contents Address of CRAM Location R0 Contents Status of operation Output Synchronization IOC$DEALLOCATE_CRAM uses no spinlocks. Description IOC$DEALLOCATE_CRAM deallocates the CRAM by marking it available for use.
Operating System Routines IOC$DIAGBUFILL IOC$DIAGBUFILL Fills a diagnostic buffer if the original $QIO request specified such a buffer.
Operating System Routines IOC$INITIATE IOC$INITIATE Initiates the processing of the next I/O request for a device unit.
Operating System Routines IOC$INITIATE Description IOC$INITIATE creates the context in which a driver fork process services an I/O request. IOC$INITIATE creates this context and activates the driver’s start-I/O routine in the following steps: • Checks the CPU ID of the local processor against the device’s affinity mask to determine whether the local processor can initiate the I/O operation on the device.
Operating System Routines IOC$IOPOST IOC$IOPOST Performs device-independent I/O postprocessing and delivers the results of an I/O request to a process.
Operating System Routines IOC$IOPOST Output Location UCB$W_QLEN PCB$W_DIOCNT PCB$W_BIOCNT JIB$L_BYTCNT CCB$W_IOC CCB$L_DIRP Contents Decremented Incremented for a direct-I/O request Incremented for a buffered I/O request Updated for buffered I/O request Decremented Cleared if channel is idle Synchronization IOC$IOPOST executes in response to an interrupt granted at IPL$_IOPOST. It performs some of its functions in a special kernel-mode AST that executes within process context at IPL$_ASTDEL.
Operating System Routines IOC$LOADALTMAP IOC$LOADALTMAP Loads a set of Q22–bus alternate map registers.
Operating System Routines IOC$LOADALTMAP Description A driver fork process calls IOC$LOADALTMAP to load a previously allocated set of alternate map registers with page-frame numbers (PFNs). This enables a device DMA transfer to or from the buffer indicated by the contents of UCB$L_ SVAPTE, UCB$W_BCNT, and UCB$W_BOFF. IOC$LOADALTMAP confirms that sufficient alternate map registers have been previously allocated. If not, it issues a UBMAPEXCED bugcheck.
Operating System Routines IOC$LOADMBAMAP IOC$LOADMBAMAP Loads MASSBUS map registers.
Operating System Routines IOC$LOADTCMAP_DMA, IOC$LOADTCMAP_DMAN IOC$LOADTCMAP_DMA, IOC$LOADTCMAP_DMAN Load a set of TURBOchannel map registers for DMA.
Operating System Routines IOC$LOADTCMAP_DMA, IOC$LOADTCMAP_DMAN Description A driver fork process calls IOC$LOADTCMAP_DMA or IOC$LOADTCMAP_ DMAN to load a previously allocated set of DMA map registers with pageframe numbers (PFNs). This enables a device to perform DMA transfers to or from the buffer indicated by the contents of UCB$L_SVAPTE, UCB$W_ BCNT, and UCB$W_BOFF (or the contents of R3, R4, and R5 when using IOC$LOADTCMAP_DMAN).
Operating System Routines IOC$LOADUBAMAP, IOC$LOADUBAMAPA IOC$LOADUBAMAP, IOC$LOADUBAMAPA Load a set of UNIBUS map registers or a set of the first 496 Q22–bus map registers.
Operating System Routines IOC$LOADUBAMAP, IOC$LOADUBAMAPA Description A driver fork process calls IOC$LOADUBAMAP or IOC$LOADUBAMAPA to load a previously allocated set of map registers with page-frame numbers (PFNs). This enables a device DMA transfer to or from the buffer indicated by the contents of UCB$L_SVAPTE, UCB$W_BCNT, and UCB$W_BOFF. Either IOC$LOADUBAMAP or IOC$LOADUBAMAPA confirms that sufficient map registers have been previously allocated. If not, it issues a UBMAPEXCED bugcheck.
Operating System Routines IOC$LOADVMEMAP_DMA, IOC$LOADVMEMAP_DMAN IOC$LOADVMEMAP_DMA, IOC$LOADVMEMAP_DMAN Load a set of VME map registers for DMA. Module [DRIVER]VMEDMA_XMI Input Location R0 Contents VMEbus control flags: VME$M_RMWMODE—Translate VME readmodify-write into XMI interlocked accesses VME$K_WORDSWAP—Enables hardwareassisted byte swapping within words. VME$K_LONGSWAP—Enables hardwareassisted byte swapping within longwords.
Operating System Routines IOC$LOADVMEMAP_DMA, IOC$LOADVMEMAP_DMAN Output Location R0, R1, R2 Contents Destroyed Synchronization A driver fork process calls IOC$LOADVMEMAP_DMA or IOC$LOADVMEMAP_ DMAN at fork IPL, holding the corresponding fork lock (typically IOLOCK8) in a multiprocessing environment. Either routine returns control to its caller at the caller’s IPL. The caller retains any spinlocks it held at the time of the call.
Operating System Routines IOC$LOADVMEMAP_PIO IOC$LOADVMEMAP_PIO Loads a set of VME PIO map registers.
Operating System Routines IOC$LOADVMEMAP_PIO Synchronization A driver fork process calls IOC$LOADVMEMAP_PIO at fork IPL, holding the corresponding fork lock in a multiprocessing environment. IOC$LOADVMEMAP_ PIO returns control to its caller at the caller’s IPL. The caller retains any spinlocks it held at the time of the call. Description A driver fork process calls IOC$LOADVMEMAP_PIO to load a previously allocated set of map registers with VME PFNs.
Operating System Routines IOC$LOADXBIMAP IOC$LOADXBIMAP Loads a set of XBI+ map registers.
Operating System Routines IOC$MOVFRUSER, IOC$MOVFRUSER2 IOC$MOVFRUSER, IOC$MOVFRUSER2 Move data from a user buffer to a device.
Operating System Routines IOC$MOVFRUSER, IOC$MOVFRUSER2 IOC$MOVFRUSER2 is useful for moving blocks of data in several pieces, each piece beginning within a page rather than on a page boundary. To begin, the driver calls IOC$MOVFRUSER. For each subsequent piece, the driver calls IOC$MOVFRUSER2.
Operating System Routines IOC$MOVTOUSER, IOC$MOVTOUSER2 IOC$MOVTOUSER, IOC$MOVTOUSER2 Move data from a device to a user buffer.
Operating System Routines IOC$MOVTOUSER, IOC$MOVTOUSER2 IOC$MOVTOUSER2 is useful for moving blocks of data in several pieces, each piece beginning within a page rather than on a page boundary. It handles as many pages as you need. To begin, the driver calls IOC$MOVTOUSER. For each subsequent buffer to move, the driver calls IOC$MOVTOUSER2.
Operating System Routines IOC$PURGDATAP IOC$PURGDATAP Purges the buffered data path and logs memory errors that may have occurred during an I/O transfer.
Operating System Routines IOC$PURGDATAP • Stores the contents of the data path register in R1. The driver’s registerdumping routine writes this value to the error message buffer. • Clears any purge errors in the data path register. • Places the appropriate return status in R0. • Determines the base of UNIBUS or Q22–bus map registers and writes the value into R2. The driver’s register-dumping routine writes this value to the error message buffer.
Operating System Routines IOC$RELALTMAP IOC$RELALTMAP Releases a set of Q22–bus alternate map registers.
Operating System Routines IOC$RELALTMAP Description A driver fork process calls IOC$RELALTMAP to release a previously allocated set of Q22–bus alternate map registers (registers 496 to 8191) and update the alternate map register descriptor arrays in the ADP. IOC$RELMAPREG assumes that its caller is the current owner of the controller data channel. IOC$RELALTMAP obtains the location and number of the allocated map registers from CRB$L_INTD+VEC$W_MAPALT and CRB$L_INTD+VEC$W_NUMALT, respectively.
Operating System Routines IOC$RELCHAN IOC$RELCHAN Releases device ownership of all controller data channels.
Operating System Routines IOC$RELDATAP IOC$RELDATAP Releases a UNIBUS adapter’s buffered data path.
Operating System Routines IOC$RELDATAP If the data path wait queue contains waiting fork processes, IOC$RELDATAP dequeues the first process, allocates the data path to it, restores R3 through R5, and reactivates it. Otherwise, it marks the path available by setting the corresponding bit in the data path bit map (ADP$W_DPBITMAP), and returns to its caller. If the bit map has been corrupted, IOC$RELDATAP issues an INCONSTATE bugcheck.
Operating System Routines IOC$RELMAPREG IOC$RELMAPREG Releases a set of UNIBUS map registers or a set of the first 496 Q22–bus map registers.
Operating System Routines IOC$RELMAPREG Description A driver fork process calls IOC$RELMAPREG to release a previously allocated set of UNIBUS map registers or a set of the first 496 Q22–bus map registers. IOC$RELMAPREG updates the alternate map register descriptor arrays in the ADP. IOC$RELMAPREG assumes that its caller is the current owner of the controller data channel.
Operating System Routines IOC$RELSCHAN IOC$RELSCHAN Releases device ownership of only the secondary controller’s data channel.
Operating System Routines IOC$RELTCMAP_DMA, IOC$RELTCMAP_DMAN IOC$RELTCMAP_DMA, IOC$RELTCMAP_DMAN Release a set of TURBOchannel DMA map registers.
Operating System Routines IOC$RELTCMAP_DMA, IOC$RELTCMAP_DMAN Description A driver fork process calls IOC$RELTCMAP_DMA or IOC$RELTCMAP_DMAN to release a previously allocated set of the TURBOchannel DMA map registers. IOC$RELTCMAP_DMA obtains the location and number of the allocated map registers from CRB$L_INTED+VEC$W_MAPREG and CRB$L_INTED+VEC$B_ NUMREG, respectively, while IOC$RELTCMAP_DMAN obtains this same information from the map register descriptor (TC_MD).
Operating System Routines IOC$RELVMEMAP_DMA, IOC$RELVMEMAP_DMAN IOC$RELVMEMAP_DMA, IOC$RELVMEMAP_DMAN Release a set of VME DMA map registers.
Operating System Routines IOC$RELVMEMAP_DMA, IOC$RELVMEMAP_DMAN Description A driver fork process calls IOC$RELVMEMAP_DMA or IOC$RELVMEMAP_ DMAN to release a previously allocated set of VME DMA map registers. IOC$RELVMEMAP_DMA obtains the location and number of the allocated map registers from CRB$L_INTED+VEC$W_MAPREG and CRB$L_INTED+VEC$B_ NUMREG, respectively, while IOC$RELVMEMAP_DMAN obtains this same information from the map register descriptor (VME_MD).
Operating System Routines IOC$RELVMEMAP_PIO IOC$RELVMEMAP_PIO Releases a set of VME PIO map registers.
Operating System Routines IOC$RELVMEMAP_PIO After adjusting the PIO map register descriptor arrays, IOC$RELVMEMAP_ PIO examines the VME PIO map register wait queue. If the queue is empty, IOC$RELVMEMAP_PIO returns successfully to its caller. If the queue contains waiting fork processes, IOC$RELVMEMAP_PIO dequeues the first process and calls IOC$ALOVMEMAP_PIO to attempt to allocate the set of map registers it requires.
Operating System Routines IOC$RELXBIMAP IOC$RELXBIMAP Releases a set of XBI+ map registers.
Operating System Routines IOC$REQALTMA IOC$REQALTMA Allocates sufficient Q22–bus alternate map registers to accommodate a DMA transfer and, if unavailable, places the requesting fork process in an alternatemap-register wait queue.
Operating System Routines IOC$REQALTMA ADP$W_MR2NREGAR, ADP$W_MR2FREGAR, ADP$L_MR2ACTMDR ADP$L_MR2QBL UCB$L_FR3 UCB$L_FR4 UCB$L_FPC Updated Updated R3 of caller R4 of caller 00(SP) Synchronization A driver fork process calls IOC$REQALTMAP at fork IPL, holding the corresponding fork lock in a multiprocessing environment.
Operating System Routines IOC$REQCOM IOC$REQCOM Completes an I/O operation on a device unit, requests I/O postprocessing of the current request, and starts the next I/O request waiting for the device. Module IOSUBNPAG Macro REQCOM Input Location R0 R1 R5 UCB$L_STS UCB$B_ERTCNT UCB$B_ERTMAX UCB$L_EMB UCB$L_IRP UCB$B_DEVCLASS UCB$L_IOQFL Contents First longword of I/O status. Second longword of I/O status. Address of UCB. UCB$V_ERLOGIP set if error logging is in progress. Final error count.
Operating System Routines IOC$REQCOM Synchronization A driver fork process calls IOC$REQCOM at fork IPL, holding the corresponding fork lock in a multiprocessing environment. IOC$REQCOM transfers control to IOC$RELCHAN. If the fork process calls IOC$REQCOM by means of the REQCOM macro (or a JMP instruction), IOC$RELCHAN returns control to the caller of the driver fork process (for instance, the fork dispatcher).
Operating System Routines IOC$REQDATAP, IOC$REQDATAPNW IOC$REQDATAP, IOC$REQDATAPNW Request a UNIBUS adapter buffered data path and, optionally, if no path is available, place process in data-path wait queue.
Operating System Routines IOC$REQDATAP, IOC$REQDATAPNW If IOC$REQDATAP or IOC$REQDATAPNW locates a free data path, it writes the data path number into CRB$L_INTD+VEC$B_DATAPATH, updates the data path bit map (ADP$W_DPBITMAP), and returns successfully to its caller. If the bit map has been corrupted, the routine issues an INCONSTATE bugcheck.
Operating System Routines IOC$REQMAPREG IOC$REQMAPREG Allocates sufficient UNIBUS map registers or a sufficient number of the first 496 Q22–bus map registers to accommodate a DMA transfer and, if unavailable, places process in standard-map-register wait queue.
Operating System Routines IOC$REQMAPREG ADP$L_MRQBL UCB$L_FR3 UCB$L_FR4 UCB$L_FPC Updated R3 of caller R4 of caller 00(SP) Synchronization A driver fork process calls IOC$REQMAPREG at fork IPL, holding the corresponding fork lock in a multiprocessing environment. Description A driver fork process calls IOC$REQMAPREG to allocate a contiguous set of UNIBUS map registers or a set of the first 496 Q22–bus map registers to service the DMA transfer described by UCB$W_BCNT and UCB$W_BOFF.
Operating System Routines IOC$REQPCHANH, IOC$REQPCHANL, IOC$REQSCHANH, IOC$REQSCHANL IOC$REQPCHANH, IOC$REQPCHANL, IOC$REQSCHANH, IOC$REQSCHANL Request a controller’s primary or secondary data channel and, if unavailable, place process in channel wait queue.
Operating System Routines IOC$REQPCHANH, IOC$REQPCHANL, IOC$REQSCHANH, IOC$REQSCHANL Description A driver fork process calls IOC$REQPCHANH or IOC$REQPCHANL to acquire ownership of the primary controller’s data channel; it calls IOC$REQSCHANH or IOC$REQSCHANL to request the secondary controller’s data channel (for instance, the MASSBUS adapter’s controller data channel). Each routine examines CRB$V_BSY in CRB$B_MASK.
Operating System Routines IOC$REQXBIMAP IOC$REQXBIMAP Requests a set of XBI+ map registers, and if unavailable, places the requesting fork process in the XBI+ map register wait queue.
Operating System Routines IOC$REQXBIMAP If XBI+ map registers have been permanently allocated to the controller, IOC$REQXBIMAP returns a success status indicator (SS$_NORMAL) without allocating the requested map registers. Otherwise, the routine searches for the required number of map registers, returning SS$_NORMAL when they are found.
Operating System Routines IOC$RETURN IOC$RETURN Returns to its caller. Module None. Input None. Output None. Synchronization IOC$RETURN executes at its caller’s IPL and returns control to the caller at that IPL. Description IOC$RETURN is a universal executive routine vector in the fixed portion of the system executive. It contains a single RSB instruction.
Operating System Routines IOC$VERIFYCHAN IOC$VERIFYCHAN Verifies an I/O channel number and translates it to a CCB address.
Operating System Routines IOC$WFIKPCH, IOC$WFIRLCH IOC$WFIKPCH, IOC$WFIRLCH Suspend a driver fork thread and fold its context into a fork block in anticipation of a device interrupt or timeout.
Operating System Routines IOC$WFIKPCH, IOC$WFIRLCH Synchronization When it is called, IOC$WFIKPCH or IOC$WFIRLCH assumes that the local processor has obtained the appropriate synchronization with the device database: • In a uniprocessing environment, the processor must be executing at device IPL or above. • In a multiprocessing environment, the processor must own the appropriate device lock, as recorded in the unit control block (UCB$L_DLCK) of the device unit from which the interrupt is expected.
Operating System Routines IOC$WFIKPCH, IOC$WFIRLCH • In a multiprocessing environment, issues a DEVICEUNLOCK to conditionally release the device lock associated with the device unit and to lower IPL to the IPL saved on the stack. These actions presume that the DEVICELOCK macro has been issued prior to the wait-for-interrupt invocation. • Returns to the caller of the driver fork thread (that is, its caller’s caller) whose address is now at the top of the stack.
Operating System Routines LDR$ALLOC_PT LDR$ALLOC_PT Allocates the specified number of system page-table entries (SPTEs).
Operating System Routines LDR$DEALLOC_PT LDR$DEALLOC_PT Deallocates the specified system page-table entries (SPTEs).
Operating System Routines MMG$UNLOCK MMG$UNLOCK Unlocks process pages previously locked for a direct-I/O operation. Module IOLOCK Input Location R1 R3 Contents Number of buffer pages to unlock System virtual address of PTE for the first buffer page Output None. Synchronization Because MMG$UNLOCK raises IPL to IPL$_SYNCH, and obtains the MMG spinlock in a multiprocessing environment, its caller cannot be executing above IPL$_SYNCH or hold any higher ranked spinlocks.
Operating System Routines SMP$ACQNOIPL SMP$ACQNOIPL Acquires a device lock, assuming the local processor is already running at the IPL appropriate for acquisition of the lock. Module SPINLOCKS Macro DEVICELOCK Input Location R0 Contents Address of device lock Location R0 Contents Address of device lock Output Synchronization Upon entry, the local processor must be executing at the synchronization IPL of the device lock, as it is, for instance, when responding to a device interrupt.
Operating System Routines SMP$ACQUIRE SMP$ACQUIRE Acquires a fork lock or spinlock and enforces the appropriate IPL synchronization on the local processor. Module SPINLOCKS Macro FORKLOCK, LOCK Input Location R0 Contents Fork lock or spinlock index Location R0 Contents Fork lock or spinlock index Output Synchronization When calling SMP$ACQUIRE, the local processor should be executing at an IPL less than or equal to the synchronization IPL of the lock.
Operating System Routines SMP$ACQUIRE Otherwise SMP$ACQUIRE attempts to acquire the requested lock, allowing the acquisition to succeed if the local processor already holds the lock or if the lock is unowned. If the lock is unowned, the routine increments by 1 a counter that records the acquisition level. Each additional (or nested) acquisition of this lock by the owning processor again increments this counter.
Operating System Routines SMP$ACQUIREL SMP$ACQUIREL Acquires a device lock and enforces the appropriate IPL synchronization on the local processor. Module SPINLOCKS Macro DEVICELOCK Input Location R0 Contents Address of device lock Location R0 Contents Address of device lock Output Synchronization When calling SMP$ACQUIREL, the local processor should be executing at an IPL less than or equal to the synchronization IPL of the device lock.
Operating System Routines SMP$RELEASE SMP$RELEASE Releases all acquisitions of a fork lock or spinlock by the local processor and makes the lock available for acquisition by other processors. Module SPINLOCKS Macro FORKUNLOCK, UNLOCK Input Location R0 Contents Fork lock or spinlock index Location R0 Contents Fork lock or spinlock index Output Synchronization Upon entry, the local processor must be executing at or above the IPL at which the lock was originally obtained.
Operating System Routines SMP$RELEASEL SMP$RELEASEL Releases all acquisitions of a device lock by the local processor and makes the lock available for acquisition by other processors. Module SPINLOCKS Macro DEVICEUNLOCK Input Location R0 Contents Address of device lock Location R0 Contents Address of device lock Output Synchronization Upon entry, the local processor must be executing at or above the IPL at which the device lock was originally obtained. This IPL must be greater than IPL$_ ASTDEL.
Operating System Routines SMP$RESTORE SMP$RESTORE Releases a single acquisition of a fork lock or spinlock held by the local processor. Module SPINLOCKS Macro FORKUNLOCK, UNLOCK Input Location R0 Contents Fork lock or spinlock index Location R0 Contents Fork lock or spinlock index Output Synchronization Upon entry, the local processor must be executing at or above the IPL at which the lock was originally obtained. This IPL must be greater than IPL$_ASTDEL.
Operating System Routines SMP$RESTOREL SMP$RESTOREL Releases a single acquisition of a device lock held by the local processor. Module SPINLOCKS Macro DEVICEUNLOCK Input Location R0 Contents Address of device lock Location R0 Contents Address of device lock Output Synchronization Upon entry, the local processor must be executing at or above the IPL at which the device lock was originally obtained. This IPL must be greater than IPL$_ ASTDEL.
4 Device Driver Entry Points This chapter describes the standard driver routines and their environment that the operating system uses as entry points in a device driver program.
Device Driver Entry Points Alternate Start-I/O Routine Alternate Start-I/O Routine Initiates activity on a device that can support multiple, concurrent I/O operations and synchronizes access to its UCB. Specified in Specify the address of the alternate start-I/O routine in the altstart argument to the DDTAB macro. This macro places the address into DDT$L_ALTSTART. Called by Called by routine EXE$ALTQUEPKT in module SYSQIOREQ. A driver FDT routine generally is the caller of EXE$ALTQUEPKT.
Device Driver Entry Points Alternate Start-I/O Routine Description An alternate start-I/O routine initiates requests for activity on a device that can process two or more I/O requests simultaneously. Because the method by which the alternate start-I/O routine is invoked bypasses the unit’s pending-I/O queue (UCB$L_IOQFL) and the device busy flag (UCB$V_BSY in UCB$L_STS), the routine is activated regardless of whether the device unit is busy with another request.
Device Driver Entry Points Cancel-I/O Routine Cancel-I/O Routine Prevents further device-specific processing of the I/O request currently being processed on a device. Specified in Supply the address of the cancel-I/O routine in the cancel argument of the DDTAB macro. The macro places this address into DDT$L_CANCEL. Many drivers specify the system routine IOC$CANCELIO as their cancel-I/O routine.
Device Driver Entry Points Cancel-I/O Routine R8 Reason for cancellation, one of the following: CAN$C_CANCEL Called by $CANCEL system service CAN$C_DASSGN Called by $DASSGN or $DALLOC system service Exit The cancel-I/O routine issues an RSB instruction to return to its caller. Description A driver’s cancel-I/O routine must perform the following tasks: 1. Confirm that the device is busy by examining the device-busy bit in the UCB status longword (UCB$V_BSY in UCB$L_STS). 2.
Device Driver Entry Points Cloned UCB Routine Cloned UCB Routine Performs device-specific initialization and verification of a cloned UCB. Specified in Specify the address of a cloned UCB routine in the cloneducb argument of the DDTAB macro. The macro places this address into DDT$L_CLONEDUCB. Only drivers for template devices, such as mailboxes, specify a cloned UCB routine.
Device Driver Entry Points Cloned UCB Routine UCB$W_CHARGE(R2) UCB$W_REFC(R2) UCB$L_STS(R2) UCB$W_DEVSTS(R2) UCB$L_OPCNT(R2) UCB$L_SVAPTE(R2) UCB$W_BOFF(R2) UCB$W_BCNT(R2) UCB$L_ORB(R2) ORB$L_OWNER of template ORB ORB$L_ACL_MUTEX of template ORB ORB$W_FLAGS of template ORB ORB$W_PROT of template ORB ORB$L_ACL_COUNT of template ORB ORB$L_ACL_DESC of template ORB ORB$R_MIN_CLASS of template ORB Mailbox byte quota charge (UCB$W_SIZE) 0 UCB$V_DELETEUCB set, UCB$V_ONLINE set UCB$V_DELMBX set if DEV$V_MBX is set
Device Driver Entry Points Controller Initialization Routine Controller Initialization Routine Prepares a controller for operation. Specified in Use the DPT_STORE macro to place the address of the controller initialization routine into CRB$L_INTD+VEC$L_INITIAL. Called by The System Generation utility (SYSGEN) calls a driver’s controller initialization routine when processing a CONNECT command.
Device Driver Entry Points Controller Initialization Routine Exit The controller initialization routine returns control to its caller with an RSB instruction. Description Some controllers require initialization when the system’s driver-loading routine loads the driver and when the system is recovering from a power failure.
Device Driver Entry Points Driver Unloading Routine Driver Unloading Routine A driver specifies a driver unloading routine if there is any device-specific work to do when the driver is unloaded and reloaded. Specified in Specify the address of the driver unloading routine in the unload argument of the DPTAB macro. The driver-loading procedure puts the relative address of this routine in DPT$W_UNLOAD.
Device Driver Entry Points FDT Routines FDT Routines Perform any device-dependent activities needed to prepare the I/O database to process an I/O request. Specified in Use the FUNCTAB macro to specify the set of FDT routines that preprocess requests for I/O activity of a given type. Specify the names of the routines in the order in which you want them to execute for each type of I/O operation. Called by The $QIO system service calls a driver’s FDT routines from the module SYSQIOREQ.
Device Driver Entry Points FDT Routines Exit In a set of FDT routines associated with an I/O function, each, except the last, must return control to its caller by means of an RSB instruction. The last routine must exit using one of the mechanisms listed in Table 4–1. Table 4–1 Last FDT Routine Exit Mechanisms Exit Mechanism Function JMP EXE$ABORTIO Aborts an I/O request and returns status to the caller of the $QIO system service in R0.
Device Driver Entry Points Interrupt Service Routine Interrupt Service Routine Processes interrupts generated by a device. Specified in UNIBUS, Q22–bus, and generic VAXBI devices require an interrupt service routine for each interrupt vector the device has. Use the DPT_STORE macro to place the address of the interrupt service routine into CRB$L_INTD+VEC$L_ISR.
Device Driver Entry Points Interrupt Service Routine Input Location 00(SP) 04(SP) to 24(SP) 28(SP) 32(SP) 04(SP) to 16(SP) 20(SP) 24(SP) Contents Address of longword that contains the address of the IDB For UNIBUS, Q22–bus, and generic VAXBI devices, the contents of R0 through R5 at the time of the interrupt For UNIBUS, Q22–bus, and generic VAXBI devices, PC at the time of the interrupt For UNIBUS, Q22–bus, and generic VAXBI devices, PSL at the time of the interrupt For MASSBUS devices, the contents of R2
Device Driver Entry Points Register-Dumping Routine Register-Dumping Routine Copies the contents of a device’s registers to an error message buffer or a diagnostic buffer. Specified in Specify the name of the register-dumping routine in the regdmp argument of the DDTAB macro. This macro places the address of the routine into DDT$L_ REGDUMP.
Device Driver Entry Points Register-Dumping Routine Description A register-dumping routine fills the indicated buffer as follows: 1. Writes a longword value representing the number of device registers to be written into the buffer 2.
Device Driver Entry Points Start-I/O Routine Start-I/O Routine Activates a device to process a requested I/O function. Specified in Specify the name of the start-I/O routine in the start argument of the DDTAB macro. This macro places the address of the routine into DDT$L_START. Called by The start-I/O routine is called by IOC$INITIATE and IOC$REQCOM in module IOSUBNPAG.
Device Driver Entry Points Start-I/O Routine UCB$L_SVAPTE For a direct-I/O transfer, virtual address of first page-table entry (PTE) of I/O-transfer buffer; for buffered-I/O transfer, address of buffer in system address space Exit The start-I/O routine suspends itself whenever it must wait for a required resource, such as a controller data channel or UNIBUS or Q22–bus map registers.
Device Driver Entry Points Timeout Handling Routine Timeout Handling Routine Takes whatever action is necessary when a device has not yet responded to a request for device activity and the time allowed for a response has expired. Specified in Specify the address of the timeout handling routine in the excpt argument to the WFIKPCH or the WFIRLCH macro. Called by The WFIKPCH and WFIRLCH macros use this entry point, but only when the name of a timeout handling routine is provided in their excpt argument.
Device Driver Entry Points Timeout Handling Routine Input Location R3 R4 R5 UCB$L_STS Contents Contents of R3 when the last invocation of WFIKPCH or WFIRLCH took place Contents of R4 when the last invocation of WFIKPCH or WFIRLCH took place Address of UCB of the device UCB$V_INT and UCB$V_TIM clear; UCB$V_ TIMOUT set Exit The timeout handling routine issues an RSB instruction to return to its caller.
Device Driver Entry Points Unit Delivery Routine Unit Delivery Routine For controllers that can control a variable number of device units, determines which specific devices are present and available for inclusion in the system’s configuration. Specified in Specify the name of the unit delivery routine in the deliver argument to the DPTAB macro. The macro puts the relative address of this routine in DPT$W_ DELIVER.
Device Driver Entry Points Unit Delivery Routine Exit A unit delivery routine issues an RSB instruction to return control to the SYSGEN autoconfiguration facility. If the routine returns error status in R0, SYSGEN does not configure the unit. Description The unit delivery routine determines which units on a controller should be configured. For instance, a unit delivery routine can prevent the creation of UCBs for devices that do not respond to a test for their presence.
Device Driver Entry Points Unit Initialization Routine Unit Initialization Routine Prepares a device for operation and, in the case of a device on a dedicated controller, initializes the controller. Specified in You can specify a unit initialization routine in two ways, either of which will suffice for all but a few specific devices. • Specify the address of the unit initialization routine unitinit argument of the DDTAB macro. This macro places the address of the routine into DDT$L_ UNITINIT.
Device Driver Entry Points Unit Initialization Routine Input Location R3 R4 R5 Contents Address of primary CSR. Address of secondary CSR, if it exists. (If it does not, the contents of R4 are the same as those of R3.) Address of UCB. Exit The unit initialization routine returns control to its caller with an RSB instruction. Description Depending on the device, a unit initialization routine performs any or all of the following tasks: 1.
Device Driver Entry Points Unsolicited Interrupt Service Routine Unsolicited Interrupt Service Routine Services an interrupt from a MASSBUS disk that is not the result of a driver’s request. Specified in Specify the name of the unsolicited interrupt service routine in the unsolic argument to the DDTAB macro. This macro places the address of the routine into DDT$L_UNSOLINT.
Index A ACB$V_QUOTA, 3–9, 3–12 ACB (AST control block), 1–45, 1–101, 3–4, 3–6 contents, 3–8 Accessibility of memory See Buffer Access violation See SS$_ACCVIO ACF (configuration control block), 1–3 to 1–4 ACL (access rights list), 1–53 ACP (ancillary control process), 1–12, 1–46, 1–47, 1–88 See also XQP class, 1–35 default, 1–35 ACP_MULTIPLE parameter, 1–35 Adapter dispatch table, 1–7 address, 1–7 ADP$L_CSR, 3–112 ADP$L_DPQFL, 3–117 ADP$L_MBASCB, 1–8 ADP$L_MBASPTE, 1–8 ADP$W_ADPTYPE, 2–3 ADP$W_DPBITMAP, 3–1
B BADDALRQSZ bugcheck, 3–5, 3–23 Big-endian byte handling, 2–96, 2–97, 3–2, 3–3 BIIC (backplane interconnect interface chip) self test, 2–5 BIOLM (buffered I/O limit) quota for mailbox, 1–87 BI_NODE_RESET macro, 2–5 BOOTED processor state, 1–16 Boot stack, 1–16 BOOT_REJECTED processor state, 1–16 BR level relation to SCB vectors, 1–9 Buffer allocating, 3–14, 3–16, 3–26 allocating a physically contiguous, 3–17 deallocating, 3–5, 3–23 locking, 1–49, 3–37, 3–40, 3–47, 3–52, 3–61, 3–65 locking multiple areas, 3
COM$DRVDEALMEM routine, 3–5 COM$FLUSHATTNS routine, 3–6, 3–9 COM$POST routine, 3–7, 4–2 COM$POST_NOCNT routine, 3–7 COM$SETATTNAST routine, 3–8 Connection breaking, 2–74 obtaining characteristics of, 2–76 to 2–78 requesting, 2–70 to 2–72 setting characteristics of, 2–91 to 2–93 Connection characteristics buffer, 2–91 Controller initialization routine, 4–8 address, 1–31, 2–27, 4–8 context, 4–8 entry point, 4–8 exit method, 4–9 forking, 1–27 for terminal port driver, 2–7 functions, 4–9 input, 4–8 register usa
Device (cont’d) cluster available, 1–89 directory structured, 1–88 disk, 1–90, 3–58, 3–132 dual ported, 1–89 file structured, 1–35, 1–89 input, 1–89 line printer, 1–90 mailbox, 1–89, 1–91 mounted, 1–89, 1–92 mounted foreign, 1–89 network, 1–89 output, 1–89 random access, 1–89 real time, 1–89, 1–91 record oriented, 1–88 reference count, 1–94 sequential block-oriented, 1–88 shareable, 1–89 spooled, 1–88 synchronous communications, 1–90 tape, 1–90, 3–132 terminal, 1–88, 1–90 timed out, 1–92 workstation, 1–90 D
Direct data path odd transfer, 1–9 Direct I/O, 1–47, 1–94 additional buffer regions for, 1–49 to 1–51 checking accessibility of process buffer for, 3–50, 3–63 locking a process buffer for, 3–37, 3–40, 3–47, 3–52, 3–61, 3–65 postprocessing, 3–94 unlocking process buffer, 3–148 Directory sequence number, 1–97, 1–98 Direct-vector interrupt, 1–7, 1–8, 1–31, 2–3 Disconnect feature determining setting of, 2–76 enabling, 2–91 Disk driver, 1–93, 1–94 See also MBA, MASSBUS ECC correction routine for, 3–85 using loca
EXE$CANCEL routine, 3–86 EXE$CRAM_CMD routine, 3–19, 3–88 EXE$CREDIT_BYTCNT routine, 3–21 EXE$CREDIT_BYTCNT_BYTLM routine, 3–21 EXE$DASSGN routine, 1–12 EXE$DEANONPAGED routine, 3–5, 3–15, 3–23 EXE$DEBIT_BYTCNT routine, 3–24 EXE$DEBIT_BYTCNT_ALO routine, 3–26 EXE$DEBIT_BYTCNT_BYTLM routine, 3–24 EXE$DEBIT_BYTCNT_BYTLM_ALO routine, 3–26 EXE$DEBIT_BYTCNT_BYTLM_NW routine, 3–24 EXE$DEBIT_BYTCNT_NW routine, 3–24 EXE$FINISHIOC routine, 1–48, 3–28, 4–12 EXE$FINISHIO routine, 1–48, 3–28, 3–56, 3–57, 3–58, 4–12 EXE
Fork queue, 1–17, 1–87, 3–30, 3–36 FORKUNLOCK macro, 2–36, 3–153, 3–155 example, 2–35 Full duplex device driver, 4–3 I/O completion for, 3–7 FUNCTAB macro, 2–37 to 2–38 example, 2–38 H Hardware I/O mailbox, 1–22 to 1–24, 3–19 HWCLK spinlock, 3–34, 3–55 I I/O adapter configuration register, 1–7 data path register, 2–50 number of address bits, 1–9, 2–3 type, 1–7, 1–40, 2–3, 2–21 I/O database, 1–1, 1–2 creation, 1–40, 2–26 I/O function code, 1–46 I/O postprocessing, 1–47 device-independent, 3–94 for aborted
IOC$CRAM_IO routine, 3–19, 3–88 IOC$DEALLOCATE_CRAM routine, 1–20, 3–90 IOC$DIAGBUFILL routine, 1–37, 1–49, 3–91 IOC$GL_CRBTMOUT, 1–28 IOC$GL_DEVLIST, 1–34 IOC$GL_MUTEX, 4–6 IOC$GW_MAXBUF, 3–24, 3–26 IOC$INITIATE routine, 1–37, 1–47, 1–91, 1–92, 1–94, 3–33, 3–45, 3–91, 3–92, 3–132, 4–17 IOC$IOPOST routine, 1–48, 1–49, 1–50, 3–94 unlocking process buffers, 3–148 IOC$LOADALTMAP routine, 2–44, 3–96 IOC$LOADMBAMAP routine, 2–45, 3–98 IOC$LOADTCMAP_DMAN routine, 3–99 IOC$LOADTCMAP_DMA routine, 3–99 IOC$LOADUBAMA
IRP (I/O request packet) (cont’d) unlocking buffers specified in, 3–148 IRPE (I/O request packet extension), 1–47, 1–49 to 1–51, 3–94 address, 1–49 allocating, 1–49 deallocation, 1–50, 3–95, 3–148 unlocking buffers specified in, 3–95, 3–148 J JIB$L_BYTCNT, 3–15, 3–21, 3–24, 3–26 JIB$L_BYTLM, 3–15, 3–21, 3–24, 3–26 JIB$V_BYTCNT_WAITERS, 3–21 JIB spinlock, 3–21, 3–24, 3–27 Job controller, 1–93 sending a message to, 3–60, 3–68 Job quota byte count, 3–15, 3–21, 3–24, 3–26 byte limit, 3–15, 3–21, 3–24, 3–26 L
N Network device, 1–89 Nexus ID, 1–7 Node ID, 1–7 Non-direct-vector interrupt, 1–7, 1–31 Nonpaged pool, 1–20, 1–24, 3–16, 3–70 allocating, 3–14, 3–16, 3–26 deallocating, 3–5, 3–23 lookaside list, 3–15 O Object protection, 1–53 OPCOM process sending a message to, 3–60, 3–68 Operator device, 1–88 ORB (object rights block), 1–51 to 1–54 address, 1–87 cloned, 4–7 Output device, 1–89 P Page table entry allocating, 3–146 deallocating, 3–147 modifying, 2–41 Paging I/O function, 1–47 PCA (pseudo CSR address), 1–7
READ_SYSTIME macro, 2–52 example, 2–52 Real time device, 1–89, 1–91 Record oriented device, 1–88 Register-dumping routine, 1–37, 1–98, 2–50, 3–11, 3–91, 3–112, 3–113, 4–15 address, 4–15 context, 4–15 entry point, 4–15 exit method, 4–15 functions, 4–16 input, 4–15 register usage, 4–15 synchronization requirements, 4–15 Reinitialization table, 1–41, 2–26 RELALT macro, 2–53, 3–114 RELCHAN macro, 2–54, 3–116 RELDPR macro, 2–55, 3–117 RELMPR macro, 2–56, 3–119 RELSCHAN macro, 2–57, 3–121 Remote terminal UCB exte
Set device mode function, 1–90, 1–91 SETIPL macro, 2–65 example, 2–66 Set mode function, 1–91 Shareable device, 1–89 SHOW DEVICE command, 1–95 SMP$ACQNOIPL routine, 2–17, 3–149 SMP$ACQUIREL routine, 2–17, 3–152 SMP$ACQUIRE routine, 2–35, 2–47, 3–150 SMP$AR_IPLVEC, 2–34, 3–30, 3–36 SMP$AR_SPNLKVEC, 1–81, 2–35, 2–47, 2–101 SMP$RELEASEL routine, 2–19, 3–154 SMP$RELEASE routine, 2–36, 2–101, 3–153 SMP$RESTOREL routine, 2–19, 3–156 SMP$RESTORE routine, 2–36, 2–101, 3–155 SOFTINT macro, 2–67, 3–30, 3–36 SPDT (SCS
SYS$ALLOC routine, 1–88, 1–92 SYS$ASSIGN routine, 1–12, 1–92, 1–93 for template device, 4–6 SYS$CANCEL routine, 1–37, 4–4 SYS$DALLOC routine, 1–37, 1–92, 4–4 SYS$DASSGN routine, 1–37, 1–92, 4–4 SYS$QIO routine, 1–44 device-dependent arguments of, 1–48 SYS$QIOW routine, 1–44 System buffer See Nonpaged pool System Generation utility (SYSGEN) AUTOCONFIGURE command, 1–3, 1–41, 1–83, 2–22, 4–21 CONNECT command, 1–7, 1–32, 1–43, 1–51, 1–83, 2–22, 4–8, 4–23 /NUMVEC qualifier, 1–29 RELOAD command, 4–10 System page-
UCB$L_IRP, 3–93 UCB$L_OPCNT, 3–7, 3–28, 3–131 adjusted by IOC$REQCOM, 3–132 UCB$L_ORB, 1–51 UCB$L_SVAPTE, 1–47, 3–93, 3–108 UCB$L_SVPN, 2–21, 3–85, 3–108 UCB$L_TT_CLASS, 2–8 UCB$L_TT_PORT, 2–8 UCB$Q_DEVDEPEND, 3–56, 3–58 UCB$V_BSY, 3–32, 3–87, 4–5 UCB$V_CANCEL, 3–86, 3–87, 3–93, 4–5 UCB$V_ECC, 3–85 UCB$V_ERLOGIP, 3–10, 3–132 UCB$V_ONLINE, 1–43 UCB$V_TEMPLATE, 4–6 UCB$V_TIM, 2–43, 3–35, 3–143 UCB$V_TIMOUT, 3–93, 3–143 UCB$W_BCNT, 1–48, 1–94, 3–72, 3–76, 3–82, 3–84, 3–93, 3–139 UCB$W_BOFF, 1–47, 1–94, 3–72, 3
Workstation device, 1–90 Write check enabling, 1–89 WRITE_CSR macro, 2–110, 3–19 example, 2–110 X XBI+ adapter map registers, 3–81, 3–83, 3–107, 3–128, 3–139 XQP (extended QIO processor), 1–12, 1–88 default, 1–35 Index–15
