Input/Output Device Driver Reference/Touch Display Device Driver

Input/Output Device Driver Reference

Advanced Power Management Architecture APM IOCtl Device Driver Test Tool Asynchronous (RS232-C) Communications Device Driver CLOCK$ Device Driver Joystick Device Driver Keyboard Device Driver Keyboard Inter-Device-Driver Communication Interfaces Keyboard Device Driver Test Tool Mouse Device Driver Mouse (DOS) Device Driver Test Tool Parallel Port Device Driver Physical Bidirectional Parallel Port Device Driver Parallel Port Device Driver Test Tool PCMCIA Architecture PCMCIA Socket Services Device Driver Test Tool Touch Display Device Driver Touch Inter-Device-Driver Communication Interfaces USB Device Driver Stack for OS/2 Warp Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

This chapter introduces and describes the OS/2 device driver for the IBM Touch Display pointing device.

Overview

The IBM Touch Display essentially is a PS/2 8515 Display. Besides the normal video cable connection to a VGA/XGA* port, the Touch Display has a touch data cable that attaches to the IBM PS/2 Mouse (pointing device) port on the system unit. In addition, the monitor itself has a socket to which the IBM PS/2 Mouse can optionally be attached.

Support for the IBM Touch Display for OS/2 protect-mode and DOS real-mode applications is provided by the following components:

• Touch device driver
• Touch device-independent subsystem
• Touch device-dependent subsystem
• Combined IBM PS/2 Mouse/Touch device-dependent device driver
• Touch virtual device driver (VDD)
• ABIOS RAM extension for both

IBM PS/2 Mouse and IBM Touch Display devices (not required for AT*-Bus machines)

Note

Support for the IBM Touch Display as a video device is provided by standard 8515 device drivers. As far as the system is concerned, there is no difference (video-wise) between the Touch Display monitor and a standard 8515.

OS/2, Versions 2.0 and 2.1, device-driver support for the Touch Display differs somewhat from the support provided in previous versions of OS/2, as follows:

• A revised Touch API, which is device independent.

  Programs written to the existing Touxxx API using device-dependent features (such as thresholds, filter type, and so forth), however, remain compatible by virtualizing some of the functions; others become no-ops.

• Device-dependent features (only) are accessed by the PM Touch control panel or device driver load-time parameters, using the common TOUCH.INI file.
• PM mouse-emulation support for windowed DOS sessions.
• The VDD provides support for the DOS Touch API (INT 7FH) for multiple full-screen DOS sessions.

Also, a DOS attribute is available that provides exclusive touch access for a windowed DOS session. This disables mouse emulation and gives the DOS application direct, full-screen X,Y,Z touch coordinates. If the DOS session is not maximized to cover the full screen, coordinate mapping by the application is required.

The arrangement of the Mouse and Touch device drivers is shown in the following figure.

   MouXXX ▲  Presentation Manager  ▲ TdiXXX        ▲ TouXXX
      API │         ▲   ▲          │ API           │ API
    ┌─────▼──────┐  │   │    ┌─────▼──────┐  ┌─────▼──────┐
    │MOUCALLS.DLL│  │   │    │TDICALLS.DLL│  │TOUCALLS.DLL│
    └─────▲──────┘  │   │    └─────▲──────┘  └────────────┘
          │         │   │          │
    ┌─────▼──────┐  │   │          │          DosDevIOCtl
    │BMSCALLS.DLL│  │   │          └───────────────────────┐
    └─────▲──────┘  │   │   INT33 DOS     INT7F DOS        │
   DosDev-│  ┌──────┘   │   ▲     API     ▲     API        │
    IOCtl │  │          │   │             │                │
    ┌─────▼──▼──┐   ┌───▼───▼────┐  ┌─────▼──────┐   ┌─────▼─────┐
    │           ├───►            │  │            ◄───┤           │
    │ MOUSE.SYS │   │ VMOUSE.SYS │  │ VTOUCH.SYS │   │ TOUCH.SYS │
    │           ◄───┤            │  │            ├───►           │
    └───▲───▲───┘   └────────────┘  └────────────┘   └─────▲─────┘
        │   │                                              │
        │   └───────────────────────┐   ┌──────────────────┘
        └─────────────┐ Emulated    │   │ Touch Data
        Mouse Data    │ mouse data  │   │
                    ┌─┼─────────────┼───┼──┐
   PDITOU02.SYS     │ │            ┌┴───┴┐ │    (device dependent)
   Combined         │ └───┐   ┌────┤  E  │ │   ┌────────────┐
   Mouse/Touch      │    ┌┴───┴┐   └─────┘ ◄───►TDDCALLS.DLL◄─────►
   Device-dependent │    │  I  │   PDITOU$ │   └────────────┘TDDxxx
   driver           │    └─────┘           │                 API
                    │    PDIMOU$           │
                    └──────────▲───────────┘
                               │
                         ┌─────┴─────┐
           TOUMOUSx.BIO  │   ABIOS   │
                         └─────▲─────┘
                               │
                   Mouse/Touch display hardware

Note

Box I is the interrupt handler, which decides whether the data packet is Mouse or Touch.

Box E is controlled by the state of mouse emulation. Data is passed to either the mouse device driver or the Touch device driver, depending on whether mouse emulation is ON or OFF, respectively.

Both the IBM PS/2 Mouse and IBM Touch Display devices share the same ABIOS and device-dependent driver. These components cannot be separated due to the access of both devices through the same physical I/O ports on the 8042, and sharing their physical hardware interrupt request, IRQ 12h. This implies a common device driver with a single interrupt handler that decides, by examination of the actual data, which device is responsible for the interrupt.

Using the Touch APIs

DOS-mode applications use the software interrupt 7FH (INT 7FH) interface to access the Touch display device. For details, refer to the OS/2 Virtual Device Driver Reference. OS/2-mode applications access the Touch display device using the TdixxxAPI, described fully in the OS/2 Virtual Device Driver Reference. Protect-mode applications cannot use the INT 7FH API nor can real-mode applications use the Tdixxx API.

The TouxxxAPI provided in previous versions of OS/2 also is available; but due to the fact that all of the hardware-dependent functions have been moved from the TOUCH.SYS driver into the PDITOU0x.SYS driver, the TOUCH.SYS driver truly is device-independent.

In addition to having touch-device capability, you also can have the Touch display emulate the IBM PS/2 Mouse, using the standard mouse INT 33H API (for real-mode) and the MOUxxx API (for OS/2 mode).

Programming a 32-Bit Touch Display Device

The APIs described previously are 16-bit; there are no 32-bit APIs available as yet for the Touch device. Programs compiled for the 32-bit flat model (CL386 -G3 switch) still can use the 16-bit API calls through the CL386 compiler's built-in 16->32-bit conversions. These conversions come into effect when pointer parameters and functions are declared with the _far16 keyword. The compiler then generates the necessary thunking code to perform the calls.

Accessing a Presentation Manager Touch Display Device

Within Presentation Manager, it is not possible to access the Touch device from the following locations:

• Presentation Manager program
• AVIO window
• DOS window (the default)

Under the Properties option on the System Menu, an option has been added called Touch: exclusive to a window, which disables mouse emulation under PM and gives the touch X,Y,Z data directly to the designated window. However, the window does receive full-screen touch coordinates; it will need to perform a mapping unless, for example, it is a graphics program, running maximized, which covers the full screen. In the previously mentioned cases, mouse-emulation mode must be used.

To learn what happens when a DOS program is started in a window and then switched to full screen, and whether a full-screen program can be switched to a window, refer to the OS/2 Physical Device Driver Reference.

Mouse Emulation

Mouse emulation is performed by the combined Touch/Mouse device-dependent driver; instead of reporting touch-event X,Y,Z data to the TOUCH.SYS driver, the touch event is converted to an equivalent mouse event and reported to MOUSE.SYS.

To facilitate mouse emulation, the MOUSE.SYS driver has two IDC entry points for reporting data:

• The conventional entry point, where real mouse events are reported
• An entry point where an absolute pointing device, such as the touch screen, can call directly, with absolute X,Y values instead of the normal DX,DY relative mouse movement values (in mickeys).

The emulation is performed at the junction of the device-dependent and - independent drivers, so that at the MOUSE.SYS interfaces available to everyone (IOCtl, MouxxxAPI, INT 33H API), no difference between the emulated mouse device and an actual mouse device is evident. The device-independent driver hides the differences between the various types of mouse devices that can attach to the system. These could be an actual mouse or, just as well, a tracker ball, tablet, touch screen, light pen, or even a voice recognition system.

This type of implementation is very flexible in that the mouse and touch screen can be used independently - the touch screen can be used to emulate the mouse alone (although without Button 2 capability), or it can be used to emulate the mouse with simultaneous use of the PS/2 Mouse itself.

Differences between...

OS/2, Versions 2.0 and 2.1, Mouse Support and That of Earlier Versions:

• Mouse emulation is no longer performed on a per-DOS session basis. Instead, it is now ON or OFF system wide; thus, turning mouse emulation OFF using the Touch control panel affects all sessions. However, DOS sessions do have individual mouse-emulation states, which means that even if mouse emulation is ON system wide, the DOS session can turn it ON or OFF in each individual session.

The DOS INT 7FH API has its own mouse emulation ON|OFF control function, so turning mouse emulation OFF in one DOS session does not affect the emulation state in any other.

• Opening of the Touch device turns off mouse emulation by default, but mouse emulation can be turned back ON while the device is still open as a Touch device. Each touch event then becomes two events: one touch and one emulated-mouse.

This facility was available in previous versions of OS/2, but it used an extra bit in the TouSetEmulOnOff() input parameter. This was further complicated by the fact that, for a given session, there were two independent sets of hardware parameters: touch and mouse emulation. Different touch thresholds could apply to a session, depending on whether mouse emulation was active.

OS/2, Versions 2.0 and 2.1, are much cleaner to implement and easier to understand with respect to mouse emulation.

Installing the Touch Display Device Driver

The Touch display shares the auxiliary device (mouse) port on the PS/2 with the IBM PS/2 Mouse by permitting the IBM PS/2 Mouse to connect to the Touch display, which is, itself, connected to the PS/2.

With the IBM PS/2 Mouse and Touch Display both connected to the auxiliary device port, existing IBM PS/2 Mouse ABIOS and device drivers continue to function normally, requiring no changes. However, to access the Touch display by way of the Touch display device driver, take the following steps:

1. Replace/extend the IBM PS/2 Mouse ABIOS by using an ABIOS RAM extension contained in TOUMOUSx.BIO. This ABIOS extension adds one function to the Mouse ABIOS interface to enable control of the Touch Display. Modify the system file, ABIOS.SYS, to include this file extension in its list of ABIOS extensions.
2. Replace the device-dependent IBM PS/2 Mouse device driver file, PDIMOU02 .SYS, with PDITOU02.SYS by modifying the CONFIG.SYS entry as shown in the following example.
3. Modify all CONFIG.SYS Mouse entries.

Make an entry for the combined Mouse/Touch device-dependent driver as follows:

Format: DEVICE=PDITOU0x.SYS CODE=TOUCO21D.BIN INIT=TOUCH.INI

where

TOUCO21D.BIN is the Touch display microcode binary file 
TOUCH.INI is a text file containing default parameter settings

The following table describes the CONFIG.SYS DEVICE= keyword parameters for the combined Mouse/Touch device-dependent driver.

Keyword	Description	Parameter Range	Default
CODE=	Microcode file to download into Touch Display	None
INIT=	Parameter file to override settings in device driver	None

Make an entry for the Touch device-independent driver as follows:

Format:       DEVICE=TOUCH.SYS TYPE=PDITOU$ [QSIZE=] [SEL=]

Example:      DEVICE=TOUCH.SYS TYPE=PDITOU$ QSIZE=15

Note: The device type must be PDITOU$.

An entry for the Mouse device-independent driver is made:

Format:       DEVICE=MOUSE.SYS TYPE=PDIMOU$ [QSIZE=]

Example:      DEVICE=MOUSE.SYS TYPE=PDIMOU$ QSIZE=15

Note: The device type must be PDIMOU$.

The entry for the device-dependent Mouse/Touch device driver must precede the other two entries, for which the order of appearance is not important.

The following table describes the common CONFIG.SYS DEVICE= keyword parameters for the device-independent Mouse and Touch drivers.

Keyword	Description	Parameter Range	Default
QSIZE=	OS/2-mode support event queue size in elements	1 - 100 elements	10
TYPE=	Indicates device dependent name.	PDITOU$ for Touch; PDIMOU$ for Mouse	None

The following table describes the unique CONFIG.SYS DEVICE= keyword parameters for the Touch device-independent driver.

Keyword	Description	Parameter Range	Default
SEL=	Selection mechanism in protect mode and real mode	Selection type 0 - 5 # of stable points 0 - 40 Tolerance value 0 - 4095 Search Limit 0 - 40	0

An entry for the Touch virtual device driver is made:

Format:       DEVICE=VTOUCH.SYS

Example:      DEVICE=VTOUCH.SYS

There are no keyword parameters for the Touch VDD.

An entry for the mouse virtual device driver is made:

Format:       DEVICE=VMOUSE.SYS

Example:      DEVICE=VMOUSE.SYS

Note

The handling of threshold parameter changes, filter frequencies and click-locking parameters is done either through the PM Touch control panel (refer to the OS/2 Physical Device Driver Reference) or the TOUCH.INI parameter file (see the following).

Format of TOUCH.INI Parameter File

A TOUCH.INI parameter file is supplied containing the default device-driver settings for:

• Force thresholds
• Mouse emulation ON|OFF control
• Mouse emulation beep feedback (on button down) ON|OFF control
• Mouse emulation click-lock parameters
• Mouse emulation XY finger-pointer offset
• Data packet report rate
• Low-pass filter setting

The file contents override the built-in device-dependent driver settings by using the INIT=filename keyword in the DEVICE= config.sys entry for the device driver.

Any file can be used if it conforms to the TOUCH.INI syntax; the Touch Control panel uses and updates the file referred to by the config.sys entry.

The following code fragment shows the format of the TOUCH.INI file containing the default settings:

/*
 * TOUCH.INI - 8516 Touch Display Device-Dependent Driver Initialization File
 *
 */

/* The format of this file is as follows:
 *
 * One Keyword per line, followed by an equal sign (=), then the arguments,
 * no duplicate tokens allowed.
 *
 * All spaces and tabs are ignored.
 * Arguments are delimited by commas.
 *
 * To set an option OFF, use 0.
 * To set an option ON, use 1.
 *
 * Two types of comments are supported. They conform to
 the 'C' programming language syntax. Nested comments, in any form,
 are not supported.
 *
 */

THRESH  = 46, 80, 96    // Thresholds [on-screen, push-hyst, push-thresh]
CLICK   = 2, 300, 500   // Click Locking [type, size, time]
XYOFF   = 0, 0          // XY Offset [x-off, y-off]
RATE    = 3             // Report Rate [rate]
EMUL    = 1             // Mouse Emulation [on/off]
BEEP    = 1             // Emulation Beep on selection [on/off]
FILT    = 0, 0          // Low pass filter type, speed

/* end-of-file */

Calibration Utility Installation

The Calibration utility performs the dual function of downloading calibration constant data to the Touch display every time the system unit is powered on and permitting re-calibration of the Touch display (on initial setup, when the display is moved to a new location, and so forth). For this reason, the Calibration utility should be inserted into the config.sys file where it will run automatically every time the system unit is powered on (or warm booted, although this is not necessary).

An entry in config.sys is made as follows:

run=c:\touchos2\calibrat.exe -c calibrat.dat

If the calibrat.dat file is not found (when the display is initially installed for instance), the operator is prompted to re-calibrate the display; and if successful, a new calibrat.dat file will be created.

The calibration utility can be run from the OS/2 command line at any time, for example, to re-calibrate the display:

c:
cd \touchos2
calibrat -u

Note

The use of the -u option enables an existing calibrat.dat file to be updated with new calibration data.

Building the OS/2 Touch Device Driver

The OS/2 Device Driver code is required to successfully build the OS/2 Touch device drivers.

To build the Touch device drivers:

1. Ensure that the TOOLS directory in the IBM Developer Connection Device Driver Kit for OS/2 is part of the current path.
2. Create NMAKE using the following Make files in the device driver:
   • SRC\DEV\TOUCHDD\MAKEFILE
   • SRC\VDEV\VTOUCH\MAKEFILE

Example:

cd \ddk_x86\src\dev\TOUCHDD\nmake