HP OpenVMS Systems Documentation

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 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.

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

Conventions

The following conventions are used in this manual:

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 boxes¹ 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.

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.