HP OpenVMS Systems Documentation

Content starts here VMS DECwindows Device Driver Manual

VMS DECwindows Device Driver Manual

June 1990

This manual describes the DECwindows device driver software on workstations that run VMS. It may be used when you write a DECwindows driver for a device connected to a VAX workstation. It describes the DECwindows driver/server architecture, the various drivers, driver components, their routines, macros, and data structures. It also describes the driver/server interface and methods by which a driver and server call routines and pass information.

Revision/Update Information: This manual supersedes the VMS DECwindows Device Driver Manual
Version 5.3.

Software Version: VMS Version 5.4 June 1990

© 1990.
The following are trademarks of Digital Equipment Corporation:
DDIF Desktop--VMS PrintServer 40 VAXserver
DEC DIGITAL Q-bus VAXstation
DECwindows LN03 VAX  
DECwriter MASSBUS VAXcluster

The following are third-party trademarks:

PostScript is a registered trademark of Adobe Systems Incorporated.

X Window System, Version 11 and its derivations (X, X11, X Version 11, X Window System) are trademarks of the Massachusetts Institute of Technology.

Contents Index


The VMS DECwindows Device Driver Manual provides information needed to understand the driver software and workstation system, and to write a DECwindows driver for an input device. The DECwindows software described in this document is designed to run with VMS Version 5.0 or later and is associated with the family of workstations specified in this manual. The manual provides DECwindows driver data structures, routines, and code examples for the programmer.

Intended Audience

This manual is intended for system programmers who are already familiar with VAX processors and the VMS operating system. Although the discussion of the device driver architecture and components applies specifically to DECwindows workstations with keyboard and mouse, the information also applies to other serial input devices. The driver design described is based on Q22-bus CPU/controller type (VCB01/VCB02) hardware.

Structure of This Document

The manual presents the DECwindows architecture and its main components and functions and then describes the driver/server interface, driver entry points, driver services and routines, and other information needed to write a driver. The appendixes contain reference material such as the DECwindows data structures and macros.

If you are coding a server, Chapter 2 and Chapter 6 provide required information concerning $QIO calls for programming devices. The manual contains the following chapters:

  • Chapter 1 presents the X Window System concept and introduces the components of the DECwindows architecture. It describes the main software components and their functions, hardware relationships, and DECwindows requirements.
  • Chapter 2 describes the common driver queue and server interface. It describes the data format of the serial line interface, queue management and communication protocols. It also describes the $QIO common interface and $QIO calls made from the server.
  • Chapters 3 and 4 describe the port and class input drivers. Both chapters provide program entry points and information required to write a DECwindows input driver. Chapter 4 describes how to write a port driver and presents the input driver routines that process input data and manage the devices. These driver routines handle interrupts and manage the controller ports. Chapter 3 describes how to write a class driver and presents the routines that process input data and manipulate the input queue.
  • Chapter 5 presents common driver program information and routines that provide common DECwindows services. It provides information concerning management of the queue interface to the server, calls for service in other drivers, and $QIO preprocessing. It also describes the FDT routines, organization, and preprocessing services provided.
  • Chapter 6 presents output driver program information and the vectored output routines that provide video and cursor image control, operator window control, and device-dependent $QIO services.
  • Appendix A describes the data structures that make up the DECwindows I/O subsystem database. Each data structure is shown in a figure and has an accompanying table that defines each field.
  • Appendix B presents the macros for all the common and input driver module software. It describes general driver macros, input queue and packet processing macros, and vector generation macros.

Associated Documents

Because the DECwindows software is integrated with VMS, this manual often refers to the VMS driver software or I/O subsystem that is described in the OpenVMS VAX Device Support Manual. If you are writing a DECwindows device driver, refer to both this manual and the VMS Device Support Volume for basic driver design. Before reading the VMS DECwindows Device Driver Manual, you should have an understanding of the material discussed in the following documents:

  • OpenVMS VAX Device Support Manual
  • OpenVMS VAX Device Support Reference Manual
  • I/O-related portions ($QIO) of the OpenVMS System Services Reference Manual
  • Terminal driver section of the VMS I/O User's Reference Manual: Part I

You may also find useful some of the material in your workstation's technical manual. Other related information may be found in the following books:

  • VAX/VMS Internals and Data Structures
  • Guide to Setting Up a VMS System
  • VMS System Dump Analyzer Utility Manual
  • VMS DECwindows Guide to Xlib Programming: VAX Binding
  • VMS DECwindows Xlib Routines Reference Manual


The following conventions are used in this manual:

mouse The term mouse is used to refer to any pointing device, such as a mouse, a puck, or a stylus.
MB1, MB2, MB3 MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The buttons can be redefined by the user.)
PB1, PB2, PB3, PB4 PB1, PB2, PB3, and PB4 indicate buttons on the puck.
SB1, SB2 SB1 and SB2 indicate buttons on the stylus.
Ctrl/x A sequence such as Ctrl/x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1, then press and release another key or a pointing device button.
[Return] In examples, a key name is shown enclosed in a box to indicate that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
... In examples, a horizontal ellipsis indicates one of the following possibilities:
  • Additional optional arguments in a statement have been omitted.
  • The preceding item or items can be repeated one or more times.
  • Additional parameters, values, or other information can be entered.
A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
() In format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.
[] In format descriptions, brackets indicate that whatever is enclosed within the brackets is optional; you can select none, one, or all of the choices. (Brackets are not, however, optional in the syntax of a directory name in a file specification or in the syntax of a substring specification in an assignment statement.)
{} In format descriptions, braces surround a required choice of options; you must choose one of the options listed.
boldface text Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason.
italic text Italic text represents information that can vary in system messages (for example, Internal error number).
UPPERCASE TEXT Uppercase letters indicate that you must enter a command (for example, enter OPEN/READ), or they indicate the name of a routine, the name of a file, the name of a file protection code, or the abbreviation for a system privilege.
- Hyphens in coding examples indicate that additional arguments to the request are provided on the line that follows.
numbers Unless otherwise noted, all numbers in the text are assumed to be decimal. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1

The VMS DECwindows software provides a complete environment for developing and interacting with graphics-oriented applications. The DECwindows software presents a common network-transparent application programming environment for windowing, graphics, and user interface services. It is a single-appearance interface that is based upon the industry-standard X Window System, Version 11. The system comprises several components: a server, device drivers, the network protocol and transport mechanisms, and the DECwindows Xlib and Toolkit programming libraries.

1.1 About This Manual

This document focuses on the device driver software that provides the DECwindows device interface. The document provides the necessary information for writing either a class driver or a port driver and for understanding the DECwindows device driver contents and concepts. Accessing the hardware directly is beyond the scope of this manual. Refer to the hardware documentation for hardware information and to the OpenVMS VAX Device Support Manual and the OpenVMS VAX Device Support Reference Manual for VMS device driver information concerning class/port driver programming and the related VMS data structures. It may be necessary to refer to the DECwindows data structures described in Appendix A while you read the chapters of this manual.

A brief overview of the layers of DECwindows software that are above the device drivers is presented first. This chapter introduces the various drivers that make up the DECwindows device interface.

1.2 DECwindows Architecture

Figure 1-1 identifies and illustrates the hierarchical layers of the DECwindows software from high-level programs of the user/application layer to the low-level programs of the device driver layer. As the figure illustrates, applications do not program to or call the drivers directly. All driver functions are available to application programs through the use of Xlib routines or DECwindows toolkit routines.

Figure 1-1 DECwindows Architecture

Xlib is a library of medium-level routines for creating and managing a window environment. The routines define the mapping of the X11 network protocol to a procedure library. Xlib provides a way for client applications to communicate with the DECwindows server without having to deal explicitly with the network protocol or server. Client applications can directly call Xlib routines to manage DECwindows resources such as windows, color maps, input devices, and bitmap graphics services. Xlib routines then convert these calls into protocol requests that the transport module sends to the server.

The DECwindows Toolkit is built on top of Xlib and provides convenient access to the Xlib features. The toolkit allows a programmer to access the power of the Xlib routines from a higher level, streamlining the coding and saving time in the programming task.

The transport module is a general or transparent data transfer mechanism within DECnet; it does not interpret or need to recognize the particular format of the data that it transfers. The transport module operates symmetrically on both ends of the client/server connection in that it buffers and sends requests in the form of output data transfers to the server and sends input events, errors, and replies in the form of input data transfers to Xlib.

The server program is a lower-level component of the architecture that allows application interfaces to interact with all supported systems in the same way. The server converts the transport layer request to a command that can be executed by the appropriate device driver.

When the user of an application enters data, the server receives input from the device drivers and passes event packets back through the transport layers to Xlib and DECwindows Toolkit routines. The server supports asynchronous input to the application and asynchronous output from the application to the device.

1.3 DECwindows Device Drivers

Workstation device drivers are the lowest level of the DECwindows system, providing the device interface and support functions. The following are the family of VAX workstations that DECwindows currently supports:

  • VAXstation II
  • VAXstation II/GPX
  • VAXstation 2000/3100
  • VAXstation 2000/3100/GPX
  • VAXstation 3200/3500
  • VAXstation 3520/3540

The drivers support screens, keyboards, and system pointing devices. The server design and device driver support also allow nonstandard or "extension" input devices to be added. You can add nonstandard devices such as tablets and dial boxes1 that require you to add your own input driver module to the driver software. Table 1-1 shows the relationship of the driver software modules to the various workstation families and hardware units. The table includes the device name used for each device in the VMS I/O database.

As shown in Table 1-1, IKDRIVER and IMDRIVER are class input drivers. IKDRIVER supports LK201 keyboard byte-stream processing and IMDRIVER supports mouse data input processing.

Table 1-1 Driver Software/Hardware Relationship
Class Input Driver Hardware Unit Device Name Device
IKDRIVER Pseudodevice IKA0 LK201 keyboard
IMDRIVER Pseudodevice IMA0 VSXXX mouse or tablet
(Your driver) Pseudodevice Uxxx (Your device)
Port Input Driver Hardware Unit/Controller Device Name System Type
YEDRIVER Serial line 0
Serial line 1
VAXstation 2000 (monochrome and color)
VAXstation 3100, 3520, 3540
GAADRIVER Serial line 0
Serial line 1
VAXstation 3200, 3500, and II/GPX
GCADRIVER Serial line 0
Serial line 1
VAXstation II monochrome
DZ11, DZ32
VAXstation II, MicroVAX II
Large VAX systems
Output Driver Hardware Unit/Controller Device Name Workstation Type with VR2xx Monitor
GABDRIVER Busless CPU and GPX video controller GAA0 VAXstation 2000/GPX, VAXstation 3100/GPX
GCBDRIVER Busless CPU and B/W video controller GCA0 VAXstation 2000 (monochrome), VAXstation 3100 (monochrome)
GAADRIVER 1 Q22-bus CPU and VCB02 video controller GAA0 VAXstation II/GPX,
VAXstation 3200, 3500
GCADRIVER 1 Q22-bus CPU and VCB01 video controller GCA0 VAXstation II (monochrome)
GBBDRIVER M-bus CPU and LEGSS video controller GBA0 VAXstation 3520, 3540
Common Driver Hardware Unit/Controller Device Name System Type
INDRIVER All DECwindows driver/server interfaces INA0 All DECwindows systems

1The output driver also contains the port input driver software.

The GABDRIVER and GCBDRIVER are output drivers for the VAXstations 2000 and 3100. GABDRIVER supports output data processing on the graphics processor extension (GPX) to VAXstation 2000 and 3100 color monitors; GCBDRIVER supports output to a VAXstation 2000/3100 monochrome monitor.

The GxADRIVERs are output drivers for the VAXstation II and the VAXstations 3200 and 3500. GAADRIVER supports output data processing to a GPX VAXstation color monitor; GCADRIVER supports output to a VAXstation II monochrome monitor. Note that the port input driver component is built into these output drivers.

GBBDRIVER is an output driver for the VAXstations 3520 and 3540 low end graphics subsystem (LEGSS) color monitors.

INDRIVER is the common DECwindows driver required for each workstation server interface.

YEDRIVER is the port input driver required for the VAXstation 2000 input devices. DZDRIVER and YFDRIVER are only used for nonstandard workstation input devices. These port drivers are not described in this manual.

The modular DECwindows architecture allows for expansion, utilizing other device-specific driver extensions, including ones not furnished by Digital. However, you cannot add a driver for input devices other than a keyboard or system pointing device without a server extension. Because server and Xlib extensions are not implemented in this release, such a driver cannot be added. You can replace an existing driver with a new one. For example, you can replace a class input mouse driver with one for a tablet.

1.3.1 Features Supported by the Device Drivers

VMS drivers supplied with DECwindows software provide the following functionality:

  • Keyboard, pointer, and button input
  • Color services
  • Monochrome frame buffer system
  • Cursor services
  • Device characteristics information
  • Input queue
  • Tablet input (as a system pointing device)
  • Graphics output
  • Multiscreen support
  • Pointer acceleration control
  • Mouse motion event prebuffering and compression
  • Keyboard pseudomouse

All window management is performed by the server, therefore there are no window services within the driver. The drivers treat the physical screen as a single rectangular bitmap.

Keyboard input is supplied in the form of raw LK201 scan codes. According to the X11 standard protocol, translation services are available using Xlib routines. Key autorepeat is simulated by the keyboard drivers. The LK201 keys are set in up/down transition detection mode. Keyboard drivers support the pseudomouse feature in which the keyboard can simulate the mouse functions in the event of mouse failure.

Pointer acceleration can be controlled by a server with calls to a $QIO system service and X11 type acceleration table in the mouse driver. The mouse driver provides mouse motion event prebuffering and compression for improved motion event system response. These features are selectable by the server using the $QIO interface.

The drivers also provide multiscreen support, interfacing a single input device with multiple output devices. Screens of multiple DECwindows workstations can be attached to a single pointing device. The pointer can move off the top of one screen into the bottom of another, or off screen to the right or left into another. After a screen saver timeout, all screens come alive with any mouse movement or keystroke.


1 A dial box is an analog control device having a set of knobs for variable adjustment to various graphic images and movements on the screen.

Next Contents Index