HP OpenVMS Systems Documentation

This chapter describes the vectored output routines that process graphics requests from the server to the screen. The output driver operates on the video controller that manages output functions of the graphics hardware. Details for the standard VMS routines may be found in the VMS documentation. Macros called by the output routines are described in Appendix B. More information concerning data structures referenced in this chapter may be found in Appendix A.

6.1 Overview of the Output Driver

The current DECwindows output device drivers (GxxDRIVER modules) provide device-dependent driver support for monochrome and color graphics (GPX) controllers. The drivers and their associated workstations are shown in Table 1-1. The drivers provide services for DECwindows and VMS, as well as services for $QIO requests for output to screen displays. The output driver for a color (GPX) workstation interprets direct memory access (DMA) packets from the server and presents the packet data to the graphics hardware. The output driver for monochrome workstations uses a monochrome frame buffer (MFB) for issuing output data to the graphics hardware. The drivers may contain routines, macros, and services to execute draw requests, copy data between host memory and video memory, load template random-access memory (RAM), manipulate the cursor, modify the color map, and get or set device-specific information for $QIO requests.

6.2 Output Driver Program Entry

DECwindows routines of the output driver are entered by way of a vector table. The output vector table is a data structure that allows the common driver to find the appropriate service routine. Each entry name is an address (relative to the beginning of the output driver prologue table) of a service routine. Each name may be used as a symbolic offset into the table. The symbolic addresses in the table are listed in Table 6-1.

The output 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. The macro COMMON_CTRL_INIT within the controller initialization routine relocates the table. Macros are described in Appendix B and the routines are described in this chapter. A vectored output routine call example follows:

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.

6.4 Queue Processing of Output

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 (INSQTI).

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.

FORMAT

SYS$QIO [efn],chan,func,[iosb],[astadr],[astprm]

,p1,p2,p3[,p4][,p5][,p6]

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.

6.7 Output $QIO Calls

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.

The following VMS data structures are also used by DECwindows device driver modules:

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)

4735DVISTRUCT.TEX