HP OpenVMS Systems Documentation

This chapter describes the function, routines, and program entry of the DECwindows common driver. The chapter also describes the routines that service the $QIO interface. The $QIO calls are described in Chapter 2 and Chapter 6. More information concerning the data structures referenced in this chapter may be found in Appendix A.

5.1 Overview of the Common Driver

The DECwindows common device driver (INDRIVER) is the DECwindows server interface to the input and output drivers and performs the device-independent functions of a workstation. The common device interface comprises routines, an input queue for the primary server interface, and a $QIO interface.

The common driver contains a set of DECwindows routines called by output drivers and class input drivers. It also contains routines required by VMS for all device drivers to communicate with the VMS system. Function decision table (FDT) routines within the driver service the $QIO interface.

DECwindows output and class drivers locate and call common driver service routines directly, through the common vector table, or indirectly, by invoking macros. For example, moving the mouse may necessitate moving the cursor. Because cursor movement is controlled by the graphics controller, class drivers access this function in the output driver by way of the common driver.

The common driver services and macros provided are listed in Table 5-1. As outlined in the table, the common driver routine descriptions that follow in this chapter are grouped according to type of service.

DECwindows routines in the common driver for class and output services are entered by means of a vector table. The common vector table is a data structure that allows a driver to find the appropriate service routine. Each entry name is a specific vector table offset (relative to the beginning of the common driver) that points to the common routine. Therefore, each name may be used as a symbolic offset into the table. The service routine symbolic addresses appear in the table as follows:

• COMMON_DDT
• COMMON_POS_CURSOR
• COMMON_SETUP_INPUT_UCB
• COMMON_SETUP_OUTPUT_UCB
• COMMON_VSYNC
• COMMON_FLAGS

The common driver builds the vector table by invoking the $VECINI macro, the $VEC macro for each table entry, and the $VECEND macro that terminates the structure. A macro within the controller initialization routine relocates the table. The routines are described in this chapter and the macros in Appendix B.

Driver calls to these common vectored routines refer to symbolic offsets in the common vector table. When INDRIVER is loaded, DECW$GL_VECTOR is a global location that contains the address of the common vector table. A common routine call example follows:

MOVL  G^DECW$GL_VECTOR,R0 ;get global pointer to vector table
JSB   @COMMON_VSYNC(R0)   ;call the COMMON_VSYNC routine

The common driver module contains class service routines that are required by class drivers. This section presents the common driver class service routines in alphabetical order. The class service routines are as follows:

• COMMON_POS_CURSOR
• COMMON_SETUP_INPUT_UCB

The COMMON_POS_CURSOR routine positions the cursor (pointer) according to the location specified in the UCB (UCB$W_DECW_CURSOR_X and UCB$W_DECW_CURSOR_Y). The cursor position adjusts to the hotspot and is clipped to the physical screen boundaries.

The COMMON_SETUP_INPUT_UCB routine clears most fields of the class input UCB and sets the system defaults where required. It is called by the port driver's unit initialization routine.

5.4 Common Driver Routines for Output Service

• COMMON_SETUP_OUTPUT_UCB
• COMMON_VSYNC

The COMMON_SETUP_OUTPUT_UCB routine clears most fields of the output UCB and sets the system defaults where required (screen saver and starting cursor position). This routine is called by an output driver's unit initialization routine. COMMON_SETUP_OUTPUT_UCB allocates and initializes a device information block (DVI) and then calls the OUTPUT_SET_DVI routine, which loads device-specific values into the DVI fields.

The COMMON_VSYNC routine performs time-sensitive processing during the vertical synchronization (VSYNC) interval. Because most output drivers receive a vertical SYNC interrupt to perform the necessary hardware functions, the output driver also calls the COMMON_VSYNC routine from its interrupt service routine. Because this call is inherently timer based, the COMMON_VSYNC routine periodically checks whether the screen saver function should be enabled or disabled. It also checks the input queue at this interval and determines whether the server needs to be notified of new input.

5.5 Common Driver Vectored Data

• COMMON_DDT
• COMMON_FLAGS

This entry in the common driver vector table points to the driver dispatch table (DDT). It is simply an offset to the DDT and not a routine. The COMMON_UNIT_INIT macro uses the COMMON_DDT entry point when loading the address of the DDT into the UCB. The DDT is described in the VMS Device Support Manual.

This entry in the common driver vector table points to the driver common flags longword (COMMON_FLAG_BITS). It is simply an offset to the common flag bits or global flags and not a routine. The $DECW_COMMON_READY macro uses the flag bits to sense whether the drivers are loaded. The common bits in the flags longword are listed in Table 5-2.

Table 5-2 Common Flags Longword

Bits	Description
FLAGS$V_KB_DECODER	Bit 0 is set when the keyboard class driver is loaded.
FLAGS$V_PTR_DECODER	Bit 1 is set when the pointer class driver is loaded.

5.6 Common Driver FDT Routines for $QIO Service

When a user process calls the SYS$QIO system service, the system service uses the I/O function code specified in the request to scan the driver FDT and selects one or more of the FDT routines provided by the common driver. The common driver performs device-independent processing and then calls the output or input driver for any device-dependent processing. For example, during a cursor pattern $QIO service, the common driver validates the parameters and then calls the appropriate output driver to change the cursor.

To prepare for an I/O operation, FDT routines perform such tasks as allocating buffers in system space and validating the device-dependent arguments (p1 through p6) of the I/O request.

Before calling an FDT routine, the $QIO system service sets up the contents of certain registers, as listed in Table 5-3.

The common driver contains the preprocessor FDT routines and uses the FUNCTAB macro to build a function decision table that lists valid function codes for a given preprocessor. These function codes are entry points to the FDT routines that perform I/O processing for each function specified in the $QIO service call. A list of the common driver FDT function codes and functions is shown in Table 5-4.

The following sections describe the $QIO functions and modifiers processed by the device-dependent FDT routines that make up the $QIO common interface.

5.6.2 FDT Sense-Mode Routines

The sense-mode FDT routines service $QIO requests to retrieve device information or characteristics. The function modifier passed in the p1 argument selects the appropriate subroutine in the FDT sense-mode routine table for the specific sense-mode function. When the FDT routine exits, it either queues the I/O request, finishes processing the I/O, or aborts the I/O. The following are valid function services as listed in the FDT_SENSEM table that point to the appropriate sense-mode subroutine.

• DEVICE_INFO
• SENSE_KB_INFO
• SENSE_KB_LED
• SENSE_PMOUSE_KEY
• SENSE_PTR_ACCEL
• SENSE_OPWIN_KEY
• SENSE_MOTION_COMP
• SENSE_SCREEN_SAVER

The set-mode FDT routines service $QIO requests to set various device characteristics. The function modifier passed in the p1 parameter selects the appropriate subroutine in the FDT set-mode routine table for the specific set-mode function. When the FDT routine exits, it either queues the I/O request, calls the output driver to complete the request, finishes processing the I/O, or aborts the I/O. The following are valid function

services as listed in the FDT_SETM table that point to the appropriate set-mode subroutine.

• ENABLE_INPUT
• MOTION_BUFFER_INIT
• SET_ATTACH_SCREEN
• SET_CURSOR_PATTERN
• SET_CURSOR_POS
• SET_KB_INFO
• SET_KB_LED
• SET_MOTION_COMP
• SET_OPWIN_KEY
• SET_PMOUSE_KEY
• SET_PTR_ACCEL
• SET_SCREEN_SAVER
• RING_BELL

The FDT common driver output routines provide $QIO services that preprocess a $QIO output request. The output routines check whether the device being addressed is capable of providing output, then vectors the request to the appropriate FDT parsing routine in the output driver (using the output vector table). The routines preprocess both direct I/O and buffered I/O output requests.

• FDT_OUTPUT_B
• FDT_OUTPUT_D

The FDT common driver input routine (FDT_WRITEV) provides $QIO service that processes a $QIO input request. The nonported input event is processed like an X event.