![Content starts here](http://welcome.hp-ww.com/img/s.gif) |
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:
CDA
|
DEQNA
|
MicroVAX
|
VAX RMS
|
DDIF
|
Desktop--VMS
|
PrintServer 40
|
VAXserver
|
DEC
|
DIGITAL
|
Q-bus
|
VAXstation
|
DECdtm
|
GIGI
|
ReGIS
|
VMS
|
DECnet
|
HSC
|
ULTRIX
|
VT
|
DECUS
|
LiveLink
|
UNIBUS
|
XUI
|
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.
Preface
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:
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 Introduction
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
|
TTA0
TTA1
|
VAXstation 2000 (monochrome and color)
VAXstation 3100, 3520, 3540
|
GAADRIVER
|
Serial line 0
Serial line 1
|
GAA1
GAA2
|
VAXstation 3200, 3500, and II/GPX
|
GCADRIVER
|
Serial line 0
Serial line 1
|
GCA1
GCA2
|
VAXstation II monochrome
|
DZDRIVER
|
DZQ11, DZV11
DZ11, DZ32
|
TT
TT
|
VAXstation II, MicroVAX II
Large VAX systems
|
YFDRIVER
|
DHV11, DHU11
|
TX
|
MicroVAX II
|
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.
Note
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.
|
|