HP OpenVMS Systems Documentation
VMS DECwindows Device Driver Manual
MOVL UCB$L_DECW_OUTPUT_VECTOR(R5),R1 ;get vector table address JSB @OUTPUT_CURSOR_PATTERN(R1) ;load the cursor pattern
The vectored output routines provide video and cursor image control, operator window control, start and cancel I/O, and device-dependent $QIO service. Table 6-1 lists and briefly describes the vectored routines that are part of the code of the output driver. When called, all routines assume that R5 contains the output unit control block (UCB) starting address. The OPWIN (operator window) routines in the table are only valid for workstations that are the active system console.
|Vector Name||Routine Function|
|OUTPUT_CLEAR_CURSOR||The clear-cursor routine redraws the cursor with all zeros (nulls the cursor). (Not used in the GPX drivers.)|
|OUTPUT_CURSOR_PATTERN||The cursor-pattern routine sets or loads the cursor pattern in UCB$L_DECW_CURSOR_PATTERN of the UCB output extension.|
|OUTPUT_DISABLE_VIDEO||The disable-video routine and macro disable the video display output (for example, in the screen-save function).|
|OUTPUT_ENABLE_VIDEO||The enable-video routine and macro enable the video display output.|
|OUTPUT_BUFFERED_FDT||The buffered-FDT routine parses $QIO calls from the common driver that specify the buffered output mode of $QIO processing in the function code. The routine also checks the validity of the function code in the p1 parameter being passed in the call.|
|OUTPUT_POS_CURSOR||The position-cursor routine positions the cursor on the screen according to the x- and y-coordinates defined in fields UCB$W_QD_CURSOR_X and UCB$W_QD_CURSOR_Y.|
|OUTPUT_CANCEL||The FDT cancel routine is called by the common driver to cancel all I/O request packets (IRPs) in the wait queue. The routine cancels or aborts all outstanding I/O requests.|
|OUTPUT_DIRECT_FDT||The direct-FDT routine parses $QIO calls from the common driver that specify the direct output mode of $QIO processing. The routine also validates the function code in the p1 parameter being passed in the call.|
|OUTPUT_SET_DVI||The routine sets or initializes fields in the device information block (DVI).|
|OUTPUT_OPWIN_VISIBLE||This check-for-operator-window-mode-capability routine is located in the output driver subroutine module.|
|OUTPUT_OPWIN_UP||This display-operator-window routine is located in the output driver subroutine module.|
|OUTPUT_OPWIN_DOWN||The remove-operator-window routine is located in the output driver subroutine module.|
|OUTPUT_OPWIN_RESIZE||The resize-operator-window routine is located in the output driver subroutine module. (Reduces the operator window to fit the window system.)|
6.4 Queue Processing of Output
The mechanism for passing data between server and output driver is an
output queue. The output queue is a pair of interlocked queues
consisting of a command queue, or GPX packet buffer (GPB), and a GPB
free queue. The queues consist of GPB packet buffers and their
associated control blocks. The GPB buffers contain various command
packets generated to hold the server output data. These structures
exist in nonpaged memory and are accessed by the server by mapping page
frame numbers (PFNs) into P0 process space.
Like the common driver and input queue, the server and output driver
use interlocked queue instructions to remove data packet buffers from
the command queue (REMQHI) and to insert packets on the free queue
6.5 $QIO Output Interface
The GADRIVER module contains function decision table (FDT) routines
that provide a $QIO output interface. (The $QIO interface is for
color/DMA drivers only.) A main FDT parsing routine and its FDT
subroutines handle all incoming $QIO calls from the server/common
driver interface. The output driver does not maintain a separate FDT
table. Specific FDT routines are accessed through the vectored routines
that initialize and manipulate the output packet data structures.
6.6 $QIO Calls to the Output Driver
This section presents the output $QIO calls used in a server that are supported by routines within the DECwindows output driver. The $QIO system service format is presented first.
$QIO calls must be issued to a physical device. Initially, using the $ASSIGN system service, the appropriate device name is assigned to an I/O channel (see the OpenVMS System Services Reference Manual). The channel number entry is required for chan in the $QIO system service call. Physical device names on a GPX workstation are GAA0 for output to the screen, GAA1 for the keyboard, and GAA2 for the mouse (see Table 1-1). Note that the DECwindows environment provides logical names (DECW$WORKSTATION, DECW$KEYBOARD, and DECW$POINTER) to point to physical devices.
The Queue I/O Request service queues an I/O request to a channel associated with a device. The SYS$QIO format described next applies to all the $QIO calls presented in this chapter. For more information on SYS$QIO, refer to the OpenVMS System Services Reference Manual.
SYS$QIO [efn],chan,func,[iosb],[astadr],[astprm]arguments efn is the event flag number of the I/O operation. The efn argument is a longword containing the number of the event flag.
chan is the I/O channel assigned ($ASSIGN) to the device name to which the request is directed. The chan argument is a longword containing the number of the I/O channel; however, $QIO uses only the low-order word.
func is the device-specific function code specifying the operation to be performed. The func argument is a longword containing the function code.
iosb is the I/O status block that holds the completion status of the I/O operation. The iosb argument is the address of the quadword I/O status block.
astadr is the asynchronous trap (AST) service routine to be executed when the I/O completes. The astadr argument is the address of a longword that is the entry mask to the AST routine.
astprm is the AST parameter to be passed to the AST service routine. The astprm argument is a longword containing the AST parameter.
p1 is the function modifier specifying the specific service being called within the basic function code.
p2 to p6 are the function-specific parameters being passed.
The $QIO interface is for color/DMA drivers only. With $QIO calls from the server, DMA packet data passes directly to the output driver using a set of packet data structures in an output queue that is created by the output driver. The following $QIO calls that create the output queue interface are supported by the DECwindows output driver:
- Create GPD
- Queue GPB
- Packet Wait
This section defines the specific argument information required for the various $QIO calls serviced by the output driver. The calls use the IO$_DECW_OUTPUT_DIRECT_FDT or the IO$_DECW_OUTPUT_BUFFERED_FDT function codes.
The create GPX physical data (Create GPD) $QIO function routine creates a GPX shared memory data block. A $QIO call to this service allocates and maps a contiguous region of memory from nonpaged pool for the entire output queue holding all GPX packet buffers (GPBs). The region is mapped so it is accessible by the hardware and VMS. The block size in pages must be specified in p2. If a GPD already exists, the GPD block is reinitialized. Table 6-2 provides the required argument information for the Create GPD $QIO call. The function routine returns p2 and p3 parameters defining the existing block size and starting PFN, and the function routine also updates the I/O status block (IOSB) with the same information.
Table 6-2 Argument Data for Create GPD$QIO Call $QIO Argument Required Data func IO$_DECW_OUTPUT_DIRECT_FDT or IO$_DECW_OUTPUT_BUFFERED_FDT function code. p1 IO$K_DECW_CREATE_GPD function modifier. p2 Size of the GPX physical data block in pages. p3 Page frame number (PFN) of the first page of the data block. (A return parameter only. Within the first page is a table listing the remaining PFNs that make up the GPD.)
The queue GPX packet buffer (Queue GPB) $QIO function routine inserts a newly written GPB in the command queue. This service is also known as INSQTI GPB, because of its insert-on-queue function. Table 6-3 provides the required argument information for the Queue GPB $QIO call.
Table 6-3 Argument Data for Queue GPB$QIO Call $QIO Argument Required Data func IO$_DECW_OUTPUT_DIRECT_FDT or IO$_DECW_OUTPUT_BUFFERED_FDT function code p1 IO$K_DECW_INSQTI_GPB function modifier p2 Offset of the new GPB within the GPD data block p3 Start of user buffer (optional) p4 Length of user buffer (optional)
The packet wait $QIO function routine suspends the I/O request when there are no free GPX packet buffers (GPBs), or when there are no free packets in the LEGSS common area. The $QIO completes when there are one or more GPBs or LEGSS packets on the free queue. Table 6-4 provides the required argument information for the Packet Wait $QIO call.
Table 6-4 Argument Data for the Packet Wait$QIO Call $QIO Argument Required Data func IO$_DECW_OUTPUT_DIRECT_FDT or IO$_DECW_OUTPUT_BUFFERED_FDT function code p1 IO$K_DECW_GPBWAIT function modifier for GPX packet buffers, or GB$K_LEGSS_WAIT_FOR_PKT modifier for LEGSS packets
The DECwindows device driver software requires an I/O database that contains both the standard VMS data structures and data structures specific to DECwindows. The data structures provide information to the VMS operating system and to drivers that monitor status of and control the functions of the I/O subsystem. All of the data structures are allocated space in nonpaged system memory. DECwindows common and input driver structures are defined by the DECwindows global macro $DECWGBL. The following data structures are described in this appendix. These are the specific sources of data for the DECwindows device drivers.
|DVI||Device information block|
|INB||Input buffer control block|
|INP||Input packet structure|
|KIB||Keyboard information block|
|MHB||Motion history buffer|
|UCB/DWI/DECW||Unit control block, DECwindows common input extension|
|UCB/DWI/KB||Unit control block, DECwindows keyboard input extension|
|UCB/DWI/PTR||Unit control block, DECwindows pointer input extension|
|UCB/DECW||Unit control block, DECwindows common output extension|
|Vector Tables||For class, common, port, and output drivers|
The following VMS data structures are also used by DECwindows device driver modules:
|ACB||Asynchronous system trap (AST) control block|
|CRB||Channel request block|
|DDB||Device data block|
|DDT||Driver dispatch table|
|DPT||Driver prologue table|
|FDT||Function decision table|
|IDB||Interrupt dispatch block|
|IRP||I/O request packet|
|ORB||Object rights block|
|UCB||Unit control block (main system portion)|
|UCBx||Unit control block (class/port terminal extensions)|
These data structures are described in the OpenVMS VAX Device Support Reference Manual and the
VAX/VMS Internals and Data Structures book.
A.1 Device Information Block (DVI)
The device information block (DVI) in the I/O database provides DECwindows device-specific information, primarily concerning the color graphics (GPX) workstation. The fields define system defaults and static device information and are read-only access (see Figure A-1). Table A-1 lists and defines the fields of the block. The length of the data structure is defined by the constant DVI$K_LENGTH.
Figure A-1 Device Information Block (DVI)
|DVI$L_FLINK||The forward link to the next DVI structure (not implemented).|
|DVI$L_BLINK||The backward link to the previous DVI structure (not implemented).|
|DVI$W_SIZE||Total size in bytes of the device information block.|
|DVI$B_TYPE||Defines the system or major type of data structure (DECwindows) that is read by the System Dump Analyzer (SDA). When the common driver creates the DVI, the common driver writes the symbolic constant DYN$C_DECW in this field when the common driver creates the DVI.|
|DVI$B_SUB_TYPE||Defines the specific (subtype) data structure (DVI) within the major type that is read by the SDA. When the common driver creates the DVI, the common driver writes the symbolic constant DYN$C_DECW_DVI in this field.|
A 32-bit field containing screen status bits. Mask bits in this field
correspond to two possible states:
|DVI$B_WS_TYPE||The code for the workstation type.|
An 8-bit field containing status bits concerning device compression
characteristics. Mask bits in this field correspond to two possible
|DVI$B_VSYNC_INTERVAL||The vertical synchronization (VSYNC) interval in milliseconds.|
|DVI$L_SRCSAV_TIMEOUT||The screen saver timeout in seconds.|
|DVI$B_SYSTEM_COLOR_MAPS||The default number of the system color map.|
|DVI$B_COLOR_MAPS||The number of color maps.|
|DVI$W_COLOR_MAP_ENTRIES||The maximum number of colormap entries.|
|DVI$B_BITS_PER_RGB||The number of bits for every red/green/blue (RGB) pixel.|
|DVI$B_SYSTEM_CURSOR||The default system cursor number.|
|DVI$B_CURSORS||The number of hardware cursors.|
|DVI$B_CURSOR_PLANES||The address of the array (MAX16_CURSOR) for planes in the hardware cursor. (The last 15 bytes of MAX16_CURSOR are reserved.)|
|DVI$B_CURSOR_WIDTH||The address of the array (MAX16_CURSOR) for the width of the cursor pattern. (The last 15 bytes are reserved.)|
|DVI$B_CURSOR_HEIGHT||The address of the array (MAX16_CURSOR) for the height of the cursor pattern. (The last 15 bytes are reserved.)|
|DVI$B_CURSOR_TYPE||The address of the array (MAX16_CURSOR) for the cursor type in the hardware cursor. Contains the DVI$V_COLOR_CURSOR bit, which is set if the cursor has color or is clear if the cursor is monochrome.|
|DVI$L_VIDEO_STARTING_PFN||A signed longword specifying the starting page frame number.|
|DVI$W_VIDEO_PAGE_COUNT||A signed word indicating the number of pages in the monochrome frame buffer.|
|DVI$B_BITS_PER_PIXEL||The number of bits for every pixel in the monochrome frame buffer.|
|DVI$B_BITS_PER_PIX_BTP||The number of bits for every pixel in the bitmap-to-processor (BTP) operation.|
|DVI$W_VIDEO_MEM_WIDTH||Screen width in pixels.|
|DVI$W_VIDEO_MEM_HEIGHT||Screen height in pixels.|
|DVI$W_ONSCREEN_X_ORIGIN||Defines the left screen margin (offset) in pixels to the visible screen point (visible 0).|
|DVI$W_ONSCREEN_Y_ORIGIN||Defines the top screen margin (offset) in pixels to the visible screen point (visible 0).|
|DVI$W_ONSCREEN_WIDTH||Defines the width in pixels of the visible screen (frame buffer width).|
|DVI$W_ONSCREEN_HEIGHT||Defines the height in pixels of the visible screen (frame buffer height).|
|DVI$W_OPWIN_X_ORIGIN||Defines the left screen margin (offset) in pixels to the start of the operator window.|
|DVI$W_OPWIN_Y_ORIGIN||Defines the top screen margin (offset) in pixels to the start of the operator window.|
|DVI$W_OPWIN_WIDTH||Defines the width in pixels of the operator window.|
|DVI$W_OPWIN_HEIGHT||Defines the height in pixels of the operator window.|
|DVI$W_TABLET_WIDTH||Defines the width of the tablet.|
|DVI$W_TABLET_HEIGHT||Defines the height of the tablet.|