Input/Output Device Driver Reference

From EDM2
Revision as of 22:47, 27 May 2018 by Ak120 (Talk | contribs)

Jump to: navigation, search

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

Contents

About This Book

The Input/Output Device Driver Reference for OS/2 contains specific character device drivers that are shipped with OS/2. A generic discussion of character and block device drivers can be found in the Physical Device Driver Reference for OS/2 and the Storage Device Driver Reference for OS/2.

How This Book is Organized

#Advanced Power Management Architecture describes the Advanced Power Management specification, a component of the OS/2 operating system that is used to manage power (AC/DC) consumption and utilization for PC systems.

#APM IOCtl Device Driver Test Tool explains the test tool and its various test cases.

#Asynchronous (RS232-C) Communications Device Driver presents the physical asynchronous (RS232-C) communications device driver and describes how it enables OS/2 applications to utilize the RS232-C device hardware.

#CLOCK$ Device Driver describes the physical clock device driver.

#Joystick Device Driver describes the Advanced OS/2 Joystick Device Driver.

#Keyboard Device Driver describes the KBD$ (device-independent) driver.

#Keyboard Inter-Device-Driver Communication Interfaces describes the IBMKBD (device-dependent) driver.

#Keyboard Device Driver Test Tool describes how to use the keyboard Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of keyboard device drivers.

#Mouse Device Driver describes a physical mouse device driver (MOUSE.SYS) whose job it is to detect the types of pointing devices currently installed on the OS/2 operating system. When a pointing device is identified, support for it is set up dynamically.

#Mouse (DOS) Device Driver Test Tool describes how to use the mouse Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of mouse device drivers.

#Parallel Port Device Driver describes the parallel port device driver, which supports the parallel port device interface for OS/2, Versions 2.0 and later.

#Physical Bidirectional Parallel Port Device Driver describes the function the new PAR1284.SYS device driver provides.

#Parallel Port Device Driver Test Tool describes how to use the parallel port Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of parallel port device drivers.

#PCMCIA Architecture contains a description of the PCMCIA architecture as it applies to the OS/2 operating system. Also included is a list of the supported functions and information on deviations from the PCMCIA standard.

#PCMCIA Socket Services Device Driver Test Tool describes how to use the PCMCIA Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of PCMCIA device drivers.

#Touch Display Device Driver introduces and describes the IBM Touch Display device driver, which, in addition to the video cable connection to a VGA/ XGA port, has a touch data cable that attaches to the IBM PS/2 Mouse ( pointing device) port on the system unit. OS/2 protect-mode and DOS real- mode applications are supported by the touch component.

#Touch Inter-Device-Driver Communication Interfaces describes the IBM interfaces for the Touch Display device driver.

USB Device Driver Stack for OS/2 Warp briefly describes OS/2 USB stack implementation and gives guidelines for host controller driver and class/client driver implementation together with stack driver communication API specification.

#Notices contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies.

A glossary and an index are included at the back of this book.

Conventions

Double-Byte Character Set

Throughout this publication, there are references to specific values for character strings. These values are for the Single-Byte Character Set (SBCS). When using the Double-Byte Character Set, note that one DBCS character equals two SBCS characters.

Version

Unless otherwise stated, "OS/2" as used in this book refers to the Warp Version of the IBM Operating System/2.

Assistance

Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS). You are encouraged to use the DDSC to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.

To access the DDSC BBS, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.

Additional assistance is available through the IBM Solution Developer Program. For membership information:

Internet: ibmsdp@vnet.ibm.com

US/Canada: 800-627-8363

International: 770-835-9902

International Fax: 770-835-9444

Ordering Information

In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, it also includes the following DDK reference books in online format.

  • The Physical Device Driver Reference
  • The Storage Device Driver Reference
  • The Input/Output Device Driver Reference
  • The Pen for OS/2 Device Driver Reference
  • The Virtual Device Driver Reference
  • The Presentation Device Driver Reference
  • The Display Device Driver Reference
  • The Printer Device Driver Reference
  • The Graphics Adapter Device Driver Reference
  • The MMPM/2 Device Driver Reference (Multimedia)

What's New

A new chapter, #APM IOCtl Device Driver Test Tool is provided. This chapter explains the Advanced Power Management test tool.

A new chapter, #Physical Bidirectional Parallel Port Device Driver was added which describes the PAR1284.SYS device driver.

For information on any items discussed in this reference that have been added to OS/2 beginning with OS/2 Warp Version 3.0 and their compatibility with different versions of OS/2, see #OS/2 Version Compatibility Considerations.

Introduction

Device drivers are software modules that act as an interface between OS/2* (or its applications) and physical devices. In DOS, applications are responsible for knowing and managing all the differences between different devices of like types. The device drivers of OS/2 enable applications to focus on the logic of the actual application and treat devices in a device-independent way.

This device-independence is a fundamental benefit of the OS/2 programming environment. For example, drawing a circle on the screen or on a printer is as easy as opening a device context for the correct output device and performing the drawing operations. By placing the drawing operation into the device context, the programmer does not have to be concerned about whether the device is a printer or a display.

Types of OS/2 Device Drivers

Three types of device drivers are used in OS/2 Version 3:

  • Physical device drivers
  • Virtual device drivers
  • Presentation drivers

Physical Device Drivers

Physical device drivers, in most cases, resolve device-independent input and output (I/O) requests from the operating system and its applications with the device-dependent physical attributes of the device. The physical device drivers shipped with OS/2 Version 3 include support for the following:

  • Advanced Power Management
  • Asynchronous Communication (RS-232C)
  • CD-ROM
  • Hard Disk and Diskette
  • Keyboard
  • Mouse
  • Parallel Port Printer
  • PCMCIA
  • System Clock
  • Touch Screen
  • Video

Virtual Device Drivers

The virtual device driver is an installable module that virtualizes a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers that operate at Ring 0. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware.

Further information on virtual device drivers, virtual device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Virtual Device Driver Reference.

Presentation Drivers

The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API call interface, which uses the program stack to communicate with, or pass parameters to, the presentation drivers. These drivers are special purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware.

Presentation drivers are dynamic link library modules that are supplied as files and identified by the extension DRV. When the Presentation Manager interface is initialized, the display presentation driver is loaded and enabled automatically. Other presentation drivers (for example, the hardcopy presentation drivers) are loaded and enabled when an application calls the DevOpenDC function to open the device.

Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack.

Header and include files are shipped with OS/2 to provide support for building presentation drivers that are written in C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions. Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Presentation Device Driver Reference.

Advanced Power Management Architecture

This chapter contains a brief description of the Advanced Power Management (APM) hardware and software architecture as it applies to the OS/2 operating system. Also included is a list of supported functions.

Refer to #APM IOCtl Device Driver Test Tool for information on testing APM hardware.

Overview

Advanced Power Management is an industry standard that covers the division of responsibilities for power management between hardware and software. The Advanced Power Management Specification defines the Advanced Power Management BIOS Extension interfaces available to the operating system software layers. The OS/2 Power Management Subsystem supports and extends the Advanced Power Management Specification. The OS/2 operating system runs on and exploits the wide range of manufacturers' hardware that provides industry-standard Advanced Power Management BIOS Extensions.

The OS/2 Power Management Architecture is based on the APM 1.1 Architecture and includes functions specific to the OS/2 system components.

OS/2 APM Software Components

There are four major software components defined in the OS/2 Power Management Architecture:

  • Power Object manages and tracks power consumption in battery-powered computers that support the APM standard. This component is provided in OS/ 2 but might be extended by APM-aware device drivers or APM BIOS vendors.
  • APM Subsystem interacts with the APM BIOS, APM-aware device drivers, and the Power object to process power management state changes. This component is provided in OS/2.
  • APM-Aware Device Drivers manage specific device details across power management state changes. There are numerous device drivers that can fit into this component category. Some of the OS/2-provided device drivers are APM-aware (such as MOUSE.SYS). Other OS/2 APM-aware device drivers are provided by OEM hardware manufacturers that produce power managed add-on devices (such as data/fax modems).
  • APM BIOS encapsulates the underlying hardware characteristics and provides a consistent industry-wide function base for higher layers of software (such as OS/2). The APM BIOS component is provided by the Personal Computer Manufacturer (PCM) if the system is meant to provide power management capabilities. A machine's APM BIOS will support a given version of the APM Specification. OS/2 currently supports the Advanced Power Management Specification. Older machines may only support APM 1.0. Older versions of the APM Specification will not support all of the features of newer versions, and the following discussion makes note of these cases.

Power Object

As previously mentioned, the OS/2 Power object provides the GUI for power management actions. The complete explanation of the Power object GUI details are documented in the OS/2 V2.1 Update Redbook. In addition, the Power object provides a set of Workplace Shell* methods as an application programming interface (API). The complete explanation of the Power object methods are documented in the Presentation Manager Programming Reference for OS/2.

The Power object is located in the System Setup folder, which is located inside the OS/2 System Folder. The Power object is automatically installed on systems containing the APM BIOS interfaces. In addition, the user can selectively install the Power object (and subsystem) by way of the OS/2 Selective Installation procedures.

A useful tool to customize the Power Object Notebook is the OEM extensions. Some OEM computer vendors add additional power savings capabilities outside the 1.1 specifications and the OS/2 Power object adheres to the 1.1 specification. To provide the OEM extensions, replace the WPPower class and use the wpAddSettingsPages and wpInsertSettingsPage methods with a tab label of "Options".

The ability to perform an immediate conservation of power is controlled by way of selections in the object's pop-up menu. Any Power object extensions can be added in device-specific power state controls by subclassing the pop-up menu and adding or replacing specific menu selections. Furthermore, the conditional cascade menu control (right pointing arrow) should be used to provide the conditional cascade submenu with its additional suboptions. One of the cascaded submenu suboptions should be an "All" option that acts as a replacement for the existing system-wide menu option. A device specific option for the customized device support should also be added to the cascade submenu. The cascaded submenu option that is currently active (defined by check box control) is the option which will be executed when the pop-up menu option is selected.

Pop-up menu options are added by way of the wpModifyPopupMenu method. The OEM extension DLL code maps wpMenuItemSelected notifications for the "All" condition to the original pop-up menu option value. The extension passes the notification on to the OS/2 Power object for normal processing.

The following figure depicts the user's view of the topics previously discussed.

Ioddr-01.gif

APM Subsystem

The OS/2 APM Subsystem provides the support hub for the OS/2 Power Management Architecture. The APM Subsystem provides both Category OCh Generic IOCtl interfaces for specialized applications (such as Power object) and an inter-device-driver communication (IDC) programming interface for APM-aware device drivers. Both the generic IOCtl and IDC interfaces are defined later in this section of the document.

The OS/2 APM Subsystem is contained in two separate files, APM.SYS and VAPM.SYS. The APM.SYS file is a physical device driver (PDD) and contains the key OS/2 APM Subsystem support (BIOS interactions, IDC and IOCtl interface support, and so on). The VAPM.SYS file is a virtual device driver (VDD) and contains power management support for the DOS and WIN-OS/2 application environments. The real DOS and Windows environments utilize the APM BIOS INT 15h, Ah=53h interfaces as well as the INT 2Fh broadcast interface for power state change notifications. These DOS and Windows interfaces are not supported in the DOS and WIN-OS/2 environments by the OS/2 VAPM.SYS device driver. The VAPM.SYS support simply rejects requests made to INT 15h, Ah= 53h by setting the returned AH value to 86h, indicating power management support functions are not available.

Because the APM Subsystem (APM.SYS) is the hub of the OS/2 Power Management support, it must be specified in the CONFIG.SYS file before the other power management components. If the APM BIOS is being implemented as an OS/2 device driver, then it must appear in the CONFIG.SYS file before the APM device driver. (See #APM BIOS for more details.) In addition, the APM Subsystem provides the following DEVICE= command line switches:

  • /B
    This switch directs APM.SYS to first locate and connect to the APM ROM BIOS. If the APM ROM BIOS support is not available, then the APM Subsystem will attempt to locate and connect to a device driver implementation of the BIOS support.
  • /D
    This switch directs APM.SYS to first locate and connect to a device driver implementation of the BIOS support. If the device driver support is not available then the APM Subsystem will attempt to locate and connect to the APM ROM BIOS support.
  • /V version
    This switch specifies the version of APM the OS/2 APM Subsystem should support. The default is to support the highest version of APM supported by both BIOS and the APM driver. This switch allows the APM Subsystem to run at a lower APM version, perhaps for compatibility reasons.
    The version parameter is specified in the form d.d , where d is a digit. The following example specifies APM version 1.0: /V 1.0

Note: If no DEVICE= command line switch is specified then the /B option is used as the APM.SYS default switch setting.

The APM Subsystem IDC and IOCtl programming interfaces utilize the values defined by the Advanced Power Management Specification for the Power Management Device IDs and the Power Management States. (see #APM-Aware Device Drivers). Furthermore, Power Management Event Messages are utilized in the APM Subsystem IDC and IOCtl programming interfaces.

Power Management Event Messages

The OS/2 Power Management Subsystem uses a messaging, event-driven interface. The OS/2 Power Management event messages are summarized in the following figure, with message-specific parameter values. A client registers with the APM Subsystem to receive notification of power management events. IDC clients register a callback function to be invoked when a power management event occurs. Clients using the IOCtl programming interface are notified of power management events through a registered semaphore, and subsequent use of the Query Power Event function. Message names containing the word Event are reported directly from the Advanced Power Management BIOS interface. The other events are generated programatically through use of the Send Power Event function. Only a subset of the listed events can be generated by Send Power Event. Specifically, only event SubIds 0003h through 0006h, and 000Bh through 000Ch can be generated by Send Power Event.

Event SubIds 000Ah through 0010h are only available on systems running APM version 1.1 or higher. They are not available under APM version 1.0. An attempt to send an event which is not supported under the current APM version will return a PowerNotSupported error.

OS/2 Power Management Event Messages ulParm1 ulParm2
SubId Reserved (msg-specific)
Enable Pwr Mgt Functions 0003h 0000h DevId - - -
Disable Pwr Mgt Functions 0004h 0000h DevId - - -
Restore BIOS Defaults 0005h 0000h - - - - - -
Set Power State 0006h 0000h DevId PwrState
Battery Low Event 0007h 0000h - - - - - -
Normal Resume Event 0008h 0000h - - - - - -
Critical Resume Event 0009h 0000h - - - - - -
Standby Resume Event 000Ah 0000h - - - - - -
Engage Pwr Mgt Functions 000Bh 0000h DevId - - -
Disengage Pwr Mgt Functions 000Ch 0000h DevId - - -
Power Status Change Event 000Dh 0000h - - - - - -
Update Time Event 000Eh 0000h - - - - - -
OEM Defined APM Event 000Fh 0000h EvtCode - - -
Query Power State 0010h 0000h DevId PwrState
Note: All other values are reserved.

The general descriptions for each of the Power Management event message values follow.

Note: Many of the descriptions that follow use a C-language macro called MAKEULONG in the definition of the parameters. A description of MAKEULONG is included at the end of this section.

  • Enable Power Management Function
    Indicates that the Advanced Power Management BIOS request for power management assistance is being enabled, either for the entire system or a particular device or device class.
    • Parameters
 SubId(USHORT) = 0003H
 DevId(USHORT) = (See below)
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(DevId,0)

DevId is the ID of the device whose power management assistance is being enabled. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.

Note: When running with APM version 1.0, DevId must be 0 or 1 (specifying all devices managed by APM), otherwise the error PowerNotSupported is returned.

-Notification Order

  1. Device Drivers
  2. Application Programs
  • Disable Power Management Function

Indicates that the Advanced Power Management BIOS request for power management assistance is being disabled, either for the entire system or a particular device or device class.

-Parameters

 SubId(USHORT) = 0004H
 DevId(USHORT) = (See below)
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(DevId,0)

DevId is the ID of the device whose power management assistance is being disabled. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.

Note: When running with APM version 1.0, DevId must be 0 or 1 (specifying all devices managed by APM), otherwise the error PowerNotSupported is returned.

-Notification Order

  1. Application Programs
  2. Device Drivers
  • Restore BIOS Defaults

Indicates that the Advanced Power Management BIOS Restore BIOS Power-On Defaults request is being processed.

-Parameters

 SubId(USHORT) = 0005H
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(0,0)

-Notification Order

  1. Application Programs
  2. Device Drivers
  • Set Power State

Indicates that an Advanced Power Management BIOS Set Power State function request is being processed.

-Parameters

 SubId(USHORT) = 0006H
 DevId(USHORT) = (See below)
 PwrState(USHORT) = (See below)
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(DevId,PwrState)

DevId is the ID of the device whose power state is being set. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.

PwrState is the state to which the device is to be set. The set of power states supported by the Advanced Power Management Specification is listed in #Power Management States.

-Notification Order

  1. Application Programs
  2. Device Drivers
  • Battery Low Event

Indicates that the Advanced Power Management BIOS has detected and notified the operating system that a Battery Low situation is occurring.

-Parameters

 SubId(USHORT) = 0007H
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(0,0)

-Notification Order

  1. Application Programs
  2. Device Drivers
  • Normal Resume Event

Indicates that the Advanced Power Management BIOS has entered and exited a normal System Suspend situation and is notifying the operating system on the suspend exit.

-Parameters

 SubId(USHORT) = 0008H
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(0,0)

-Notification Order

  1. Device Drivers
  2. Application Programs
  • Critical Resume Event

Indicates that the Advanced Power Management BIOS has entered and exited a critical System Suspend situation and is notifying the operating system on the suspend exit.

-Parameters

 SubId(USHORT) = 0009H
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(0,0)

-Notification Order

  1. Device Drivers
  2. Application Programs
  • Standby Resume Event

Indicates that the Advanced Power Management BIOS has entered and exited a System Standby state and is notifying the operating system on the standby exit.

-Parameters

 SubId(USHORT) = 000AH
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(0,0)

-Notification Order

  1. Device Drivers
  2. Application Programs
  • Engage Power Management Function

Indicates that cooperative power management between BIOS and the operating system has been requested, either for the entire system or a particular device or device class.

-Parameters

 SubId(USHORT) = 000BH
 DevId(USHORT) = (See below)
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(DevId,0)

DevId is the ID of the device whose cooperative power management is being engaged. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.

-Notification Order

  1. Device Drivers
  2. Application Programs
  • Disengage Power Management Function

Indicates that BIOS will be automatically performing power management without operating system cooperation, either for the entire system or a particular device or device class.

-Parameters

 SubId(USHORT) = 000CH
 DevId(USHORT) = (See below)
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(DevId,0)

DevId is the ID of the device whose cooperative power management is being disengaged. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.

-Notification Order

  1. Application Programs
  2. Device Drivers
  • Power Status Change Event

Indicates that the system's power status has changed. A query power status call can be issued to obtain the system's current power status.

-Parameters

 SubId(USHORT) = 000DH
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(0,0)

-Notification Order

  1. Device Drivers
  2. Application Programs
  • Update Time Event

Indicates that the operating system may need to update its time by reading the hardware clock. This event is issued in cases where APM BIOS actions may have prevented the timer tick from being serviced.

-Parameters

 SubId(USHORT) = 000EH
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(0,0)

-Notification Order

  1. Device Drivers
  2. Application Programs
  • OEM Defined APM Event

Indicates that the APM BIOS has raised an OEM defined event which is specific to the system currently being used.

-Parameters

 SubId(USHORT) = 000FH
 EvtCode(USHORT) = (See below)
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(EvtCode,0)

EvtCode is the OEM defined event code. The Advanced Power Management Specification defines the range of OEM defined events to be 0200H - 02FFH.

-Notification Order

  1. Device Drivers
  2. Application Programs
  • Query Power State

Issued to query the power state of a device. This message is only sent to ring 0 device drivers who have registered to receive it through the IDC interface. It is not supported for ring 3 tasks using the IOCTL interface. It is generated by the APM Subsystem in order to determine the power state of a device from its device driver. This is particularly useful for devices which are not directly power managed by the machine's BIOS. Refer to the RegisterDDRtn function under #Power Management IDC Functions for more details on this event.

-Parameters

 SubId(USHORT) = 0010H
 DevId(USHORT) = (See below)
 PwrState(USHORT) = (See below)
 ulParm1 = MAKEULONG(SubId,0)
 ulParm2 = MAKEULONG(DevId,PwrState)

DevId is the ID of the device whose power state is being queried. The set of device types supported by the Advanced Power Management Specification is listed in #Power Management Devices.

PwrState is the power state of the specified device. This field is an output parameter filled in by the device driver receiving the event. The set of power states supported by the Advanced Power Management Specification is listed in #Power Management States.

-Notification Order

  1. Device Drivers
MAKEULONG

In the previous descriptions, a C language-defined macro called MAKEULONG is sometimes used in the definition of the parameters. MAKEULONG is defined in OS2DEF.H and has the following syntax:

MAKEULONG(Low, High)

/* Low and High are both 16-bit parameters. */

Leaving out the type-casting for simplicity, MAKEULONG translates to:

( (Low) | (High) << 16 )

An example is:

ULONG ulParm;

ulParm = MAKEULONG(0x5678, 0x1234);
/* The statement above sets ulParm equal to 0x12345678 */

The first parameter to MAKEULONG becomes the low-order word, and the second parameter becomes the high-order word in the resulting 32-bit value.

Power Management IDC Interfaces

In the OS/2 operating system, there is an interface layer between the low-level subsystems and device driver clients. The mechanism for achieving this interface is based on IDC. For the OS/2 Power Management Services Layer, there are five IDC functions. The IDC functional interfaces and how they map to the Advanced Power Management BIOS Interfaces are defined in the following table:

Advanced Power Management 1.1 BIOS Functions OS/2 Power Management IDC Functions
Installation Check (00h) QueryPowerInfo (0004h)
Interface Connect (01h) N/A
Protect-Mode Connect 16-Bit (02h) N/A
Protect-Mode Connect 32-Bit (03h) N/A
Interface Disconnect (04h) N/A
CPU Idle (05h) N/A
CPU Busy (06H) N/A
Set Power State (07h) SendPowerEvent (0002h)
Enable/Disable Pwr Mgt Fcns (08h) SendPowerEvent (0002h)
Restore BIOS Defaults (09h) SendPowerEvent (0002h)
Get Power Status (0Ah) QueryPowerStatus (0003h)
Get Pwr Mgt Event (0Bh) RegisterDDRtn/DeregisterDDRtn (0000h)/(0001h)
Get Power State (0Ch) QueryPowerState (0006h)
Enable/Disable Device Pwr Mgt (0Dh) SendPowerEvent (0002h)
APM Driver Version (0Eh) N/A
Engage/Disengage Pwr Mgt (0Fh) SendPowerEvent (0002h)
OEM APM Function (80h) OEMAPMFunction (0007h)

An OS/2 physical device driver (PDD) accesses the power management services by calling the power management device driver's IDC entry point. This address is obtained using the DevHlp_AttachDD interface. The name "APM$", (APM$, followed by four blank characters) is passed to AttachDD as the power management device driver name.

Before calling the power management device driver, the client device driver must create a data structure and fill in the appropriate parameters. The first member of the structure is a WORD that identifies the function being requested. The rest of the data structure contains the parameters for that function.

The client then loads a Selector:Offset pointer to the structure into ES:BX and calls the Power Management IDC interface. There is no need to set the Power Management Data Selector before the call.

On entry to the Power Management IDC routine, ES:BX points to a data structure of the following format:

Function      WORD        ; IDC function code, as defined below.
Parameters    BYTE(?)     ; Parameter packet, as defined below.
                          ; A different parameter packet is defined
                          ; for each IDC service.

These IDC interfaces are only available at task time. They are not available at initialization or interrupt time. The Power Management device driver processes the call and returns the Return Code in AX. AX is set to 0 and the Carry flag is cleared on a successful call. On error, AX is guaranteed to be nonzero and the Carry flag is set.

Power Management IDC functions are callable only in kernel-context mode.

Power Management IDC Functions

The OS/2 Power Management IDC function codes are the values in the first WORD of the data structures submitted to the Power Management device driver. The codes are defined as follows:

Length Value Function
WORD 0 RegisterDDRtn
1 DeregisterDDRtn
2 SendPowerEvent
3 QueryPowerStatus
4 QueryPowerInfo
6 QueryPowerState
7 OEMAPMFunction
All other values are reserved.

The OS/2 Power Management IDC functional descriptions are defined as follows:

Power Management IDC Function 0 - RegisterDDRtn

The RegisterDDRtn function is used by a Power-Management-sensitive device driver so that it will be notified of Power Management events. These Power Management events are synchronous messages. The caller provides the following parameter information:

-Parameters

Field Type Length
Handle USHORT WORD
EventHandler PRM DWORD
NotificationMask ULONG DWORD
ClientDS SEL WORD
DeviceID USHORT WORD

Where the fields are interpreted as follows:

--Handle

Output parameter. The unique handle value for the registered event-handler routine information. When registered, a device driver is required to perform a DeregisterDDRtn request to disconnect the registered routine.

--EventHandler

Input parameter. The calling device driver's Selector:Offset value of the calling device driver's Event Handler routine.

--NotificationMask

Input parameter. The bit mask indicating the power management events on which the calling device driver is to receive notifications. A set bit ( value = 1) indicates power management event notification selection. The Notification Mask bit definitions are as follows:

BIT # MEANING

3 Enable Power Management
4 Disable Power Management
5 Restore BIOS defaults
6 Set power state
7 Battery Low event
8 Normal Resume event
9 Critical Resume event
10 Standby Resume event
11 Engage Power Management
12 Disengage Power Management
13 Power Status Change event
14 Update Time event
15 OEM Defined APM event
16 Query Power State
All other bits are reserved.

Events associated with bits 10 through 16 are supported by APM version 1.1, but not APM version 1.0. Selecting to receive notification for events not supported under the current version of APM will not cause an error. See Power Management Event Messages for more details on the Power Management Events previously described.

--ClientDS

Input parameter. The calling device driver's Data Segment Selector value. This value is loaded into the DS register when the Event Handler Routine is invoked.

--DeviceID

Input parameter. The ID of the device. The set of device types supported by the Advanced Power Management Specification is listed in Power Management Devices. This parameter can be used to restrict the notification of power state changes. The parameter normally is set to 0001H, which selects all BIOS-managed devices. However, if the parameter is set to some other value that selects a particular device type, the client receives notification on power transitions only on that particular device. For example, the driver registers with DeviceID set to 02FF (all disk devices). The Event Handler routine is called at the following times:

-When the entire system is entering or exiting Standby or Suspend mode
-When only a disk is entering or exiting Standby or Suspend modes.

The Event Handler routine is not invoked, however, when, for example, only a display is entering Standby.

-Event Handler Calling Conventions

When a Power Management Event is triggered, the Power Management device driver formats an Event Handler Packet (as defined below), stores a 16:16 pointer to the packet in ES:BX, sets the client's DS selector, then calls the client device driver.

Registered device-driver Event Handler routines are called with the following power management event-related information and conditions:

Field Type Length
Function USHORT WORD
ulParm1 ULONG DWORD
ulParm2 ULONG DWORD

Where the fields are interpreted as follows:

--Function

Input parameter. Must be the following value:

-Event Notification = 0000H. All other values are reserved.

--ulParm1

Input parameter. See

the previous figure "Power Management Event Messages and Parameter Values" and Power Management Event Messages for value descriptions.

--ulParm2

Input/Output parameter. See the previous figure "Power Management Event Messages and Parameter Values" and Power Management Event Messages for value descriptions.

The Power Management device driver loads the DS register and calls the Event Handler routine address with the values established using the RegisterDDRtn function.

The Event Handler routine is guaranteed to be called only in kernel-context mode by the Power Management device driver.

On return from the Event Handler routine, the AX register is used to indicate whether or not the notification request was accepted or rejected. An accepted request is noted by an AX register value of zero. A rejected request is noted by a nonzero AX register value. If a notification request cannot be supported due to pending device activity or an indeterminate device state it is valid for the device driver to fail the request.

All other register values are preserved across the call by the Event Handler routine.

The OS/2 APM Subsystem performs special processing of the return values for the following events.

--Set Power State to Suspend

If a device driver fails a Suspend Event request (indicated by returning a nonzero value in AX), the APM Subsystem will generate an artificial Resume Event to reset the device drivers that have already processed, and accepted , the failed Suspend Event request. Those registered device drivers that did not see the Suspend Event would also not see the Resume Event.

--Query Power State

When this event is received, the device driver should determine whether or not it supports the device specified by the DevId parameter. If so, and the power state of the device is known, it should report the power state by updating the PwrState field in the event message packet, and return success by setting AX to 0. Otherwise, it should fail the query by setting AX to a nonzero return code.

Power Management IDC Function 1 - DeregisterDDRtn

The DeregisterDDRtn function is used by an APM-aware device driver to disconnect a registered event-handler routine. Disconnection is necessary for proper cleanup in cases where a device driver de-installs itself after registration has occurred.

-Parameters

Field Type Length
Handle USHORT WORD

Where the field is interpreted as follows:

--Handle

Input parameter. The unique handle value for the device driver's registered event-handler routine. This value is returned from a successful request to the RegisterDDRtn function.

-Remarks

None.

Power Management IDC Function 2 - SendPowerEvent

The SendPowerEvent function enables an APM-aware device driver to send a power management event message to Power Management Services. Power Management Services process power management event messages sent by the device driver in the same manner as power management BIOS and user interface requests. This function might not return to the caller until the request and associated activities are completed.

The caller provides the following parameter information:

-Parameters

Field Type Length
ulParm1 ULONG DWORD
ulParm2 ULONG DWORD

See the previous figure "Power Management Event Messages and Parameter Values" for the parameter values. All unused parameter fields should be set to a value of 0. Refer to Category OCh, Function 40h, "Send Power Event" in the OS/2 Physical Device Driver Reference for more information.

This function must not be called if the caller is running under the context of the IDC-registered device driver event-handler routine. In addition, this function must not be called when running in an interrupt context.

Power Management IDC Function 03h - QueryPowerStatus

The QueryPowerStatus function is used by an APM-aware device driver to determine the current power source status.

-Parameters

Field Type Length
ParmLength USHORT WORD
PowerFlags USHORT WORD
ACStatus BIT 8 BYTE
BatteryStatus BIT 8 BYTE
BatteryLife BIT 8 BYTE
BatteryTimeForm BIT 8 BYTE
BatteryTime USHORT WORD
BatteryFlags BIT 8 BYTE

-Remarks

None.

Refer to Category OCh, Function 60h, "Query Power Status" in the OS/2 Physical Device Driver Referencefor more information.

Power Management IDC Function 04h - QueryPowerInformation

The QueryPowerInfo function is used by an APM-aware device driver to determine the power configuration and revision-level information.

-Parameters

Field Type Length
ParmLength USHORT WORD
BIOSFlags USHORT WORD
BIOSVersion USHORT WORD
SubsysVersion USHORT WORD
APMVersion USHORT WORD

-Remarks

None.

Power Management IDC Function 06h - QueryPowerState

The QueryPowerState function is used by an APM-aware device driver to determine the current power state of a device, class of devices, or the entire system.

-Parameters

Field Type Length
ParmLength USHORT WORD
DeviceId USHORT WORD
PowerState USHORT WORD

-Remarks

This function is not supported under APM version 1.0.

Refer to Category OCh, Function 63h, "Query Power State" in the OS/2 Physical Device Driver Referencefor more information.

This function must not be called if the caller is running under the context of the IDC-registered device driver event-handler routine. In addition, this function must not be called when running in an interrupt context.

Power Management IDC Function 07h - OEMAPMFunction

The OEMAPMFunction provides access to hardware dependant OEM defined APM functions. Since BIOS APM functions use a register passing interface, the parameter packet structure for this function facilitates general purpose register passing.

-Parameters

Field Type Length
ParmLength USHORT WORD
Flags USHORT WORD
EAX ULONG DWORD
EBX ULONG DWORD
ECX ULONG DWORD
EDX ULONG DWORD
ESI ULONG DWORD
EDI ULONG DWORD
DS USHORT WORD
ES USHORT WORD
FS USHORT WORD
GS USHORT

-Remarks

This function is not supported under APM version 1.0.

Refer to Category OCh, Function 45h, "OEM APM Function" in the OS/2 Physical Device Driver Reference for more information.

IDC Error Codes

In addition to the error codes listed under the IOCtl return errors (see Power Management IOCtl Interfaces), the following error codes pertain to IDC functions:

Decimal Value Name (Hex Value) and Description
128 PowerIDC_InvalidFunction (0080h). IDC function code out of range.
129 PowerIDC_InvalidHandle (0081h). IDC handle invalid.
130 PowerIDC_TooManyClients (0082h). Maximum number of IDC clients exceeded.
131 PowerIDC_Busy (0083h). The request cannot be serviced at this time due to pending activity that must be completed. The caller must determine whether to wait and reissue the request, proceed anyway, or end the activity.

Power Management IOCtl Interfaces

The OS/2 operating system contains an interface layer between the low-level subsystems and the user interface environment. A typical mechanism for bridging these layers when device drivers are involved is the generic IOCtl interface. For the OS/2 Power Management Services Layer, the generic IOCtl category value of OCh (12) is used for this interface. The function codes supported are defined with the following common descriptions:

  • Set/Send functions = 0100xxxxB
  • Get/Query functions = 0110xxxxB

The generic IOCtl interfaces and how they are mapped to the Advanced Power Management BIOS Interfaces are defined in the following table:

Advanced Power Management 1.1 BIOS Functions OS/2 Power Management IOCtls
Installation Check (00h) Query Power Info (Function 62h)***
Interface Connect (01h) N/A
Protect-Mode Connect 16-Bit (02h) N/A
Protect-Mode Connect 32-Bit (03h) N/A
Interface Disconnect (04h) N/A
CPU Idle (05h) N/A
CPU Busy (06h) N/A
Set Power State (07h) Send Power Event (Function 40h)
Enable/Disable Pwr Mgt Fcns (08h) Send Power Event (Function 40h)
Restore BIOS Defaults (09h) Send Power Event (Function 40h)
Get Power Status (0Ah) Query Power Status (Function 60h)
Get Pwr Mgt Event (0Bh) Query Power Event (Function 61h)
N/A Set Power Event Resources (Function 41h)

Note:

      • Some of the information available in the Installation Check function is made available in the Query Power Information IOCtl. Refer to the OS/2 Physical Device Driver Referencefor descriptions of the IOCtls.

The possible error codes returned by the Power Management IOCtl Interfaces are defined in the following table:

Decimal Value Name Description
0 PowerNoError No error.
1 PowerBadSubId Invalid SubId specified for Send Power Event.
2 PowerBadReserved Reserved field not set to 0.
3 PowerBadDevId Invalid or unsupported device ID.
4 PowerBadPwrState Invalid power state specified.
5 PowerSemAlreadySetup Set Power Event semaphore already set up.
6 PowerBadFlags Invalid Set Power Event request flags.
7 PowerBadSemHandle Semaphore doesn't match the one used to setup event queue.
8 PowerBadLength Invalid ParmLength field value.
9 PowerDisabled Power management is disabled.
10 PowerNoEventQueue Attempt to query event with no event queue.
11 PowerTooManyQueues Unable to create event queue (reached limit).
12 PowerBiosError BIOS returned an error.
13 PowerBadSemaphore Set Power Event invalid semaphore.
14 PowerQueueOverflow Event queue overflow occurred.
15 PowerStateChangeReject The requested power state cannot be entered.
16 PowerNotSupported Attempt to use a function not supported by current APM version.
17 PowerDisengaged Power management is disengaged.

APM-Aware Device Drivers

APM-aware device drivers provide the device-specific knowledge for managing power management events for their device. Typically, device drivers understand what activities are pending in their device queues and know what effects a given power state has on their device. An APM-aware device driver can choose among several schemes to manage the device. The following are some of the most common device management schemes for access requests (read/write) when the device is powered-off:

  • Queue up the request
  • Fail the request
  • Change the current power state and process the request

An OS/2 APM-aware device driver must be written as an OS/2 physical device driver (PDD). The PDD can be defined as a level-3 device driver by setting Bit 4 (value=1) in the Capabilities Bit Strip of the device driver header. By using the level-3 PDD support APM-aware device drivers can simplify CONFIG.SYS ordering problems and utilize the INIT_COMPLETE (1Fh) command. All OS/2 APM-aware device drivers must form an IDC interface link with the OS/2 APM Subsystem in order to get notifications of power events. (See #Power Management IDC Functions for more details.)

There are numerous ways an APM-aware device driver can be optimized for size, speed, maintenance, and so on, which also applies to the driver initialization phase. For instance, a common initialization scenario for APM-aware device drivers is:

  1. During the INIT command (00h) processing, the driver issues the DevHelp_ AttachDD call to determine if the APM System is present.
    • If present, the driver sets up to support power management activities ( such as locking power management code segments).
    • If not present, the driver may streamline itself (such as discarding power management code/data areas) for non-power managed environments.
  2. During the INIT_COMPLETE command (1Fh) processing the driver issues a Far Call to the APM Subsystem IDC entry point to register itself as an APM- aware device driver. (See #Power Management IDC Functions for more details.)

Note:The above scenario has a driver ordering dependency in the CONFIG. SYS file such that the APM Subsystem (APM.SYS) must be loaded first.

An APM-aware device driver can have accompanying user interface requirements for the device specific functions and features. The typical OEM APM-Aware device driver scenario includes:

  • The APM-aware device driver, which exports user-defined generic IOCtls for GUI/application level interactions and utilizes the APM Subsystem IDC interface for power event interactions.
  • A Dynamic Link Library (DLL), which provides the Options page for the Power object utilizing the user-defined IOCtls.
  • An installation program to copy the files into an OS/2 environment and form the execution linkages (such as device driver, Power object DLL subclassing, and so on).

Be sure to note that not all devices can be or should be managed by an APM-aware device driver. For example, device IDs not supported by the Advanced Power Management Specification are also not supported in OS/2 as being power manageable. In addition, some common devices (internally powered) are completely managed by the vast majority of available APM BIOS implementations so that APM-aware device drivers are not needed. There are three key elements that help define whether an APM-aware device driver should be developed for a given device. These three elements are:

  • APM device IDs, which are defined by the Advanced Power Management Specification.
  • Power supply, which is defined by the device environment and determines if the APM BIOS is aware of the device existence. It also determines whether the device draws current internally or externally.
  • Effects of power management states on the device, (power supply and device capabilities).

Power Management Devices

The device types supported by the Advanced Power Management Specification are:

  • System BIOS (0000h)
    Device ID for Advanced Power Management BIOS
  • System BIOS-managed devices (0001h)
    Generic device ID for all devices managed by Advanced Power Management BIOS.
  • Display devices (01xxh)
    Generic device ID for display devices
  • Secondary storage devices (02xxh)
    Generic device ID for secondary storage devices
  • Parallel ports (03xxh)
    Generic device ID for parallel ports
  • Serial ports (04xxh)
    Generic device ID for serial ports
  • Network adapters (05xxh)
    Generic device ID for network adapters
  • PCMCIA sockets (06xxh)
    Generic device ID for PCMCIA sockets
  • OEM defined power device IDs (E000h - EFFFh)
    Range of IDs to be used by OEM devices

Note:

  1. XXindicates the physical device number (0-based)
  2. All other device-type values are reserved
  3. Devices powered with external system unit power supplies are not supported
  4. Device IDs 05xxh and higher are only supported by version 1.1 or higher of APM

Internal/External Power

An internally powered deviceis one that draws current from the system unit 's power supply and has a direct line from the power supply that can be independently and uniquely controlled. An externally powered deviceis one that draws current from either a power supply outside the system unit's power supply or from an internal device that has no independent or unique control over the power line. For example, an asynchronous serial port (COM) is an internally powered device, whereas the mouse connected to a COM port is considered an externally powered device because the current supply is not unique to the mouse.

Power Management States

OS/2 device drivers should support, with appropriate device actions, the following set of power states supported by the Advanced Power Management Specification.

  • Ready (0000h)
    This state indicates that the system or device is operating at full power. Ready state responsibilities include:
    • Enter State
      Actions to enter this state are more accurately defined by the prior state involved in the state transition, particularly for externally powered devices.
    • State Operations
      Operates at maximum throughput for device performance.
    • Exit State
      Actions to exit this state are more accurately defined by the next state involved in the state transition, particularly for externally powered devices.
  • Standby (0001h)
    This state indicates that the system or device is operating at a partial power level that permits energy conservation without noticeable delays in restoring power for reestablished operation.
    Standby state responsibilities include:
    • Enter State
      The current device state can be saved in RAM for most devices (both internal and external).
    • State Operations
      The device is isolated from unnecessary commands and status activities that would consume power by bringing the device out of Standby. Useful commands can be processed by changing the state saved in RAM rather than programming the device immediately.
    • Exit State
      If a RAM-saved state is available and the saved information is modified during the Standby period, the saved values can be activated as delayed commands. As a rule, internally powered devices need not have additional support for this state. However, externally powered devices (for example, those that draw power from a port) must have device-state Save and Restore support.
      Note: There is no explicit Resume notification for the Standby state. The implicit Standby Resume is based on the next time the associated code is invoked.
  • Suspend (0002h)
    This state indicates that the system or device is operating at a partial power level that permits substantial energy conservation with accepted noticeable delays in restoring power for reestablished operation.
    The Advanced Power Management Specification defines the Suspend power state as system-wide and does not currently support it as device-specific. The OS/2 architecture supports both system and device levels of usage as a desired deviation from the public standard. Suspend state responsibilities include:
    • Enter State
      All externally powered devices must have their device-state information saved in a RAM data area. Similarly, all internally powered devices must have their device-state information saved when the Suspend is on a device level rather than on a system/BIOS level. Because no processing is permitted in the System Suspended state, internally powered devices can be saved by the Advanced Power Management BIOS.
    • State Operations
      Because processing is not performed during this state, there are no in-state operation requirements for system/BIOS requests. However, for a Device Suspend (versus a system/BIOS Suspend), the device driver must provide the isolation layer between the device and the applications.
    • Exit State
      All externally powered devices that had their former state information saved are reconfigured to bring them back to the pre-Suspend operating mode. Internally powered devices are also brought back to the pre-Suspend operating mode when a device-level Suspend exits.
  • Off (0003H)
    This state indicates that the system or device is not operating or receiving any amount of power. OFF state responsibilities include:
    • Enter State
      Actions to enter this state include complete device shutdown and disconnection from application environments. Because the device is not recoverable when this state is entered, all parameters used for reconnection must be saved to disk if needed and applicable.
    • State Operations
      The device is now completely unavailable, and there is no operational activity.
    • Exit State
      Actions to exit this state are currently defined only as a restart of the entire system environment (both hardware and software).
  • OEM Defined System State (0020h - 03Fh)
    This range of states may be used to define OEM system states.
  • OEM Defined Device State (0040h - 07Fh)
    This range of states may be used to define OEM device states.

All other power state values are reserved.

APM BIOS

The APM BIOS is the single most important piece of the OS/2 Power Management Architecture because all higher layers of software components are dependent upon its presence and function. The APM BIOS interfaces are significant because they define basic parameters values utilized in the higher software layers as well as the ability for the APM Subsystem to locate and connect to the APM BIOS support. There are two basic parameters (Power Management Device IDs and Power Management States) defined by the APM BIOS interfaces which are utilized within the APM Subsystem IDC and IOCtl interfaces. The details for both the Power Management Device IDs and Power Management States are defined in APM-Aware Device Drivers.

The OS/2 Power Management Architecture allows the traditional APM ROM BIOS support to be built as an OS/2 physical device driver (PDD). This construction facilitates a field upgrade capability for computer manufacturers which may have the desire to supplement existing support or even the ability to add APM BIOS to systems which were not built with it initially. Details for the APM Subsystem interactions and dependencies on these two APM BIOS implementation options are defined later in this document.

The following table defines whether or not the Industry Standard APM BIOS 1.1 Interface functions are used or required by the OS/2 APM Subsystem.

APM 1.1 BIOS Functions Required for OS/2
Installation Check (00h) Yes
Interface Connect (01h) No
Protect-Mode Connect 16-Bit (02h) Yes**
Protect-Mode Connect 32-Bit (03h) Yes**
Interface Disconnect (04h) No
CPU Idle (05h) Yes
CPU Busy (06h) Yes
Set Power State (07h) Yes
Enable/Disable Pwr Mgt Fcns (08h) Yes
Restore BIOS Defaults (09h) Yes
Get Power Status (0Ah) Yes
Get Pwr Mgt Event (0Bh) Yes
Get Power State (0Ch) Yes
Enable/Disable Device Pwr Mgmt (0Dh) Yes
APM Driver Version (0Eh) Yes
Engage/Disengage Pwr Mgmt (0Fh) Yes
OEM APM Function (80h) Yes

Note:** Only one of these functions is required per BIOS implementation.

ROM BIOS

During OS/2 system initialization processing, the APM ROM BIOS support is queried. The BIOS query is performed using the INT 15h, APM Installation Check Function (AH=53h AL=00h). The returned information is saved and made available to device drivers by way of the DevHelp_GetDOSVar function call (index parameter value = 16). The returned data is checked (if an APM BIOS is present) for the types of interface connections supported (real mode, protect-mode 16 bit, or protect-mode 32 bit). OS/2 will attempt to connect to the APM BIOS using the protect-mode 16-bit interface, if available. If the protect-mode 16-bit interface is not available then OS/2 will try to connect to the APM BIOS using the protect-mode 32-bit interface. If neither of the protect-mode options are available then OS/2 will end the connection processing.

When the APM Subsystem (APM.SYS PDD) loads (with either a /B option or a failed /D option) it issues the DevHelp_GetDOSVar (index = 16) request to determine if the APM ROM BIOS is available. If so, APM.SYS will check which interface connection mechanism was established with the APM BIOS and begin using it to setup the OS/2 environment variables. See the OS/2 Required APM BIOS functions defined in the previous table.

BIOS Device Driver

When the APM Subsystem (APM.SYS PDD) loads (with either a /D option or a failed /B option) it attempts to locate and connect to a device driver implementation of APM BIOS. This connection is performed by issuing a DevHelp_AttachDD function call specifying a device name of "APMBIOS$". A successful function return provides APM.SYS with the protect-mode 16-bit IDC interface, which APM.SYS will treat as the standard APM BIOS protect- mode 16-bit connected interface. (See the OS/2 Required APM BIOS Functions defined in APM BIOS). An APM BIOS Device Driver must be an OS/2 physical device driver (PDD) with a device name of "APMBIOS$" defined in the Device Driver Header.

There are some differences between the APM BIOS Device Driver implementation and the APM ROM BIOS implementation for supported APM BIOS interfaces. These differences are:

  • Protect-mode 16-bit interface is the only mode supported.
  • No protect-mode 16-bit connection request needed. It is the default interface mode as opposed to the real mode default of ROM BIOS implementations.
  • The Installation Check function will be issued in protect-mode 16-bit to determine BIOS driver capabilities. (As opposed to the real-mode definition for ROM BIOS implementations.)

All other calling conventions, register usage, and parameter definitions are preserved as defined by the Advanced Power Management Specification. The APM BIOS device driver interfaces are based upon the BIOS conventions rather than OS/2 IDC conventions. For instance, the APM BIOS device driver must set up its own DS register value when invoked rather than assuming it is done by the caller. All register values, except those identified as having return values, must be preserved across function request as is normal practice with BIOS requests.

It is quite probable that APM BIOS extensions implemented as device drivers will have accompanying user interface requirements for the added functions and features. The typical OEM APM BIOS Extension scenario includes:

  • The APM BIOS device driver, which exports user-defined generic IOCtls for GUI/application level interactions and emulates the APM 1.1 BIOS interface (by way of IDC) for the APM Subsystem interactions.
  • A dynamic link library (DLL), which provides the Options page for the Power object utilizing the user-defined IOCtls.
  • An installation program to copy the pieces into an OS/2 environment and form the execution linkages (such as device driver, Power object DLL subclassing, and so on).

APM IOCtl Device Driver Test Tool

This chapter explains the APM IOCtl Device Driver Test Tool.

Overview

The APM IOCtl Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of the APM device driver. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate APM function and performance. Errors are reported and are easily isolated to a specific test sequence and API.

User input and output from each thread of the APM tests is by way of a separate Presentation Manager window. Multi-threaded test cases log all information to a single log file, clearly indicating the actual execution sequence in the event of errors.

APM IOCtl Test Architecture

The DDTT provides a common front-parser for test case scripts and also tests several devices and APIs. The following DDTT APM IOCtl-specific stub code and grammar files are required:

  • DDTAPM.DLL
  • APM.GRA

The VisualAge C++ source code DDTAPM.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2. The following required, common components of DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:

  • DDTT.EXE
  • DDTT.DLL
  • GLOBAL.DLL
  • GLOBAL.GRA

Installation

There are two directory structures in IBM Developer Connection Device Driver Kit for OS/2 that utilize test suites. The TESTCERT substructure contains the executables and test cases.

The following procedure describes the installation steps for running test cases:

1. Copy the executable and APM IOCtl test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TSTAPM. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TSTAPM and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM, then use the following commands to copy the APM IOCtl test suite:

 [C:\]md tstapm
 [C:\]cd tstapm
 [C:\tstapm]copy e:\ddk\testcert\apm\function\*
 [C:\tstapm]copy e:\ddk\testcert\general\ddtt\*

2. Make sure the statement BASEDEV=APM.SYS is in the CONFIG.SYS file and the driver is installed correctly.

Test-Case Execution

There are two different ways to run APM tests. One way is to run the program from a command file. To run the command file, first make sure you are in the directory in which the files were installed and then type TEST. The command file will run all of the script files. However, if you would like to test certain parts of the driver, then you need to execute the corresponding test script. For instance, in order to test the function 61 you need to type, 61.CMD.

Another way to run APM IOCtl tests is to run each script file individually. To run one script file at a time, see #Description of Test Cases for a description of each script file. After deciding on a script file to run, type in DDTT followed by the script file name:

[C:\tstapm]DDTT ENABLE01.SCR

After the script has finished executing, control will transfer back to the OS/2 window.

APM IOCtl Test Grammar Function Calls

The following is a list of APM IOCtl Test Grammar Function Calls:

  • APM_OPEN
  • APM_CLOSE
  • APM_0C40
  • APM_0C41
  • APM10_0C60
  • APM_0C60
  • APM_0C61
  • APM_0C62
  • APM_0C63
  • APM_SEM
  • APM_ENDSEM
  • APM_CREATETHREAD
  • APM_POLLQUEUE
  • DATA_COMPARE
APM_OPEN

This function opens the advanced power management driver.

Input Parameter Keywords
Keyword Type Description
DEVICENAME STRING Power management device driver name.
Output Parameter Keywords
Keyword Type Description
APMHANDLE NUM Drive handle for APM device being tested.
Logged Data

None.

APM_CLOSE

This function closes the advanced power management driver.

Input Parameter Keywords
Keyword Type Description
APMHANDLE NUM Drive handle for APM driver.
Output Parameter Keywords

None.

Logged Data

None.

APM_0C40

Category 0Ch Function 40h - Send Power Event

This function enables the caller to initiate a power management event through the power management services subsystem and system clients.

Input Parameter Keywords
Keyword Type Description
APMHANDLE NUM Drive handle for APM driver
SUBID ALNUM Event message id
DEVID NUM Device id
PWRSTATE NUM Power State
Output Parameter Keywords

None.

Logged Data

None.

APM_0C41

Category 0Ch Function 41h - Set Power Event Resource

This function enables the caller to manipulate the resource set used to communicate with the power management subsystem. The parameter fields enable the caller to customize the resource set to fit the communication protocol desired.

Input Parameter Keywords
Keyword Type Description
APMHANDLE NUM Drive handle for APM driver
REQUESTFLAG NUM Request flag
SEMHANDLE NUM Semaphore handle
EVENTMASK NUM Event mask
Output Parameter Keywords

None.

Logged Data

None.

APM_0C60

Category 0Ch Function 60h - Query Power Status

This function returns the current power state information for the system and system devices.

Input Parameter Keywords
Keyword Type Description
APMHANDLE NUM Drive handle for APM driver
Output Parameter Keywords

None.

Logged Data
Power Flags
AC Status
Battery Life
Battery Time
Battery Time Form
Battery Status
APM10_0C60

Category 0Ch Function 60h - Query Power Status APM Version 1.0

This function returns the current power state information for the system and system devices.

Input Parameter Keywords
Keyword Type Description
APMHANDLE NUM Drive handle for APM driver
Output Parameter Keywords

None.

Logged Data
Power Flags
AC Status
Battery Life
Battery Status
APM_0C61

Category 0Ch Function 61h - Query Power Event

This function returns power management event information queued in the power management services subsystem.

Input Parameter Keywords
Keyword Type Description
APMHANDLE NUM Drive handle for APM driver
Output Parameter Keywords

None.

Logged Data
Data Packet Format
Message Count
SubID
DevID
Power State
APM_0C62

Category 0Ch Function 62h - Query Power Information

This function returns the power management subsystem and bios configuration information.

Input Parameter Keywords
Keyword Type Description
APMHANDLE NUM Drive handle for APM driver
Output Parameter Keywords

None.

Logged Data
BIOS Flags
BIOS Version
SubSystem Version
APM_0C63

Category 0Ch Function 63h - Query Power State

This function allows the current power state of device, class of device, or the entire system to be queried.

Input Parameter Keywords
Keyword Type Description
APMHANDLE NUM Drive handle for APM driver
DEVID NUM Device ID
Output Parameter Keywords

None.

Logged Data
Power State
APM_SEM

This function creates a semaphore handle.

Input Parameter Keywords

None.

Output Parameter Keywords
Keyword Type Description
SEMHANDLE NUM Semaphore handle
Logged Data

None.

APM_ENDSEM

This function deletes a semaphore handle.

Input Parameter Keywords
Keyword Type Description
SEMHANDLE NUM Semaphore handle
Output Parameter Keywords

None.

Logged Data

None.

APM_CREATETHREAD

This function is designed to test function 61 using semaphore notification. Two threads are created for this purpose. The main thread generates the event (by a function 40 call) then goes idle for 100 milliseconds and then checks if the event is picked up by the child thread. If the event is not picked up by the child thread, the main thread goes back into idle again and repeats the same process. In the mean time, the child thread waits on a semaphore. It is notified when the event is created. Then the child thread picks up the event (by a function 61 call). This cycle is repeated for max_count times. In general, max_count does not need to be greater than 1. When the main thread finishes its work, it waits for the child thread to complete its execution and then it terminates.

Input Parameter Keywords
Keyword Type Description
MAXCOUNT NUM Number of times a power management event is generated.
Output Parameter Keywords

None.

Logged Data

None.

APM_POLLQUEUE

This function is designed to test function 61 without using semaphore notification. Two threads are created for this purpose. The main thread generates the event (function 40) and goes idle for 100 milliseconds and then checks if the event is picked up by the child running in parallel. If it is not picked up by the child thread then the main thread goes back to idle end repeats the same process. The child thread continuously polls the queue and when it retrieves an event from the queue, it notifies the main thread. The main thread repeats this cycle for max_count times. In general, max_count does not need to be greater than 1. When the main thread is done, it waits for the child thread to complete its execution and it terminates.

Input Parameter Keywords
Keyword Type Description
MAXCOUNT NUM Number of times a power management event is generated.
Output Parameter Keywords

None.

Logged Data

None.

DATA_COMPARE

This function is to compare the actual result to the expected result.

Input Parameter Keywords
Keyword Type Description
DATA_FORMAT NUM Actual result
EXPECTED_VALUE NUM Expected result
Output Parameter Keywords

None.

Logged Data

SUCCESS or ERROR

Description of Test Cases

Each of the APM IOCtl test cases can be executed individually as previously described. The corresponding test scripts are described below. The user can create additional tests or combine tests into logically organized test groups to test certain aspects of the driver, after becoming familiar with the DDTT and the APM IOCtl grammar files.

All of the APM IOCtl test cases use the DDTT @IMPORT command to include APM_RET.SCR which contains the return codes from the IOCtl calls.

All test scripts close the APM device driver and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name and a file name extension, .LOG. The same information is also written to DDTT's output windows. Log files can be examined after the test case has completed.

APM_RET.SCR
A common script included by all scripts that contains the error codes returned by the IOCtl calls.
ENABLE01.SCR
Enables power management functions for BIOS-managed devices.
ENABLE0.SCR
Enables power management functions for system BIOS.
ENABLE1.SCR
Enables power management functions for display devices.
ENABLE2.SCR
Enables power management functions for secondary storage devices.
ENABLE3.SCR
Enables power management functions for parallel ports.
ENABLE4.SCR
Enables power management functions for serial ports.
ENABLE6.SCR
Enables power management functions for PCMCIA sockets.
DISABL01.SCR
Disables power management functions for BIOS-managed devices.
DISABLE0.SCR
Disables power management functions for system BIOS.
DISABLE1.SCR
Disables power management functions for display devices.
DISABLE2.SCR
Disables power management functions for secondary storage devices.
DISABLE3.SCR
Disables power management functions for parallel ports.
DISABLE4.SCR
Disables power management functions for serial ports.
DISABLE6.SCR
Disables power management functions for PCMCIA sockets.
ENGAGE01.SCR
Engages power management functions so that cooperative power management between BIOS and the operating system takes place for the BIOS-managed devices.
ENGAGE0.SCR
Engages power management functions so that cooperative power management between BIOS and the operating system takes place for the system BIOS.
ENGAGE1.SCR
Engages power management functions so that cooperative power management between BIOS and the operating system takes place for the display devices.
ENGAGE2.SCR
Engages power management functions so that cooperative power management between BIOS and the operating system takes place for the secondary storage devices.
ENGAGE3.SCR
Engages power management functions so that cooperative power management between BIOS and the operating system takes place for parallel ports.
ENGAGE4.SCR
Engages power management functions so that cooperative power management between BIOS and the operating system takes place for serial ports.
ENGAGE6.SCR
Engages power management functions so that cooperative power management between BIOS and the operating system takes place for the PCMCIA sockets.
DISENG01.SCR
Disengages power management functions therefore BIOS will be automatically performing power management without operating system cooperation for all BIOS-managed devices.
DISENG0.SCR
Disengages power management functions therefore BIOS will be automatically performing power management without operating system cooperation for itself.
DISENG1.SCR
Disengages power management functions therefore BIOS will be automatically performing power management without operating system cooperation for display devices.
DISENG2.SCR
Disengages power management functions therefore BIOS will be automatically performing power management without operating system cooperation for secondary storage devices.
DISENG3.SCR
Disengages power management functions therefore BIOS will be automatically performing power management without operating system cooperation for parallel ports.
DISENG4.SCR
Disengages power management functions therefore BIOS will be automatically performing power management without operating system cooperation for serial ports.
DISENG6.SCR
Disengages power management functions therefore BIOS will be automatically performing power management without operating system cooperation for PCMCIA sockets.
RESTORE.SCR
Restores the BIOS defaults.
SBMDOFF.SCR
Sets the power of system BIOS-managed devices to off.
SBMDRDY.SCR
Sets the power of system BIOS-managed devices to ready.
SBMDSBY.SCR
Sets the power of system BIOS-managed devices to standby.
SBMDSPD.SCR
Sets the power of system BIOS-managed devices to suspend.
SBIOSOFF.SCR
Sets the power of the system BIOS to off.
SBIOSRDY.SCR
Sets the power of the system BIOS to ready.
SBIOSSBY.SCR
Sets the power of the system BIOS to standby.
SBIOSSPD.SCR
Sets the power of the system BIOS to suspend.
SDSPLOFF.SCR
Sets the power of display devices to off.
SDSPLRDY.SCR
Sets the power of display devices to ready.
SDSPLSBY.SCR
Sets the power of display devices to standby.
SDSPLSPD.SCR
Sets the power of Display Devices to suspend.
SSTGOFF.SCR
Sets the power of secondary storage devices to off.
SSTGRDY.SCR
Sets the power of secondary storage devices to ready.
SSTGSBY.SCR
Sets the power of secondary storage devices to standby.
SSTGSPD.SCR
Sets the power of secondary storage devices to suspend.
SPPRTOFF.SCR
Sets the power of parallel ports to off.
SPPRTRDY.SCR
Sets the power of parallel ports to ready.
SPPRTSBY.SCR
Sets the power of parallel ports to standby.
SPPRTSPD.SCR
Sets the power of parallel ports to suspend.
SSPRTOFF.SCR
Sets the power of serial ports to off.
SSPRTRDY.SCR
Sets the power of serial ports to ready.
SSPRTSBY.SCR
Sets the power of serial ports to standby.
SSPRTSPD.SCR
Sets the power of serial ports to suspend.
SPCMCOFF.SCR
Sets the power of PCMCIA sockets to off.
SPCMCRDY.SCR
Sets the power of PCMCIA sockets to ready.
SPCMCSBY.SCR
Sets the power of PCMCIA sockets to standby.
SPCMCSPD.SCR
Sets the power of PCMCIA sockets to suspend.
41ERROR1.SCR
Error case. Attempts to set up a semaphore without providing a semaphore type.
41ERROR2.SCR
Error case. Requests a semaphore setup and removal at the same time.
41ERROR3.SCR
Error case. Attempts to set up both a 32-bit and 16-bit semaphore at the same time.
41ERROR4.SCR
Error case. Attempts to set up a semaphore while NoSemFlag is set.
41ERROR5.SCR
Error case. Attempts to set up a semaphore despite the case that there already exists one.
41ERROR6.SCR
Error case. Bad semaphore handle.
41ERROR7.SCR
Error case. Attempts to remove a semaphore which was not set up.
41ERROR8.SCR
Error case. An invalid event mask is used while setting the resource set.
41SEMREM.SCR
Removes an already set up semaphore.
QPOWEN01.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for system BIOS-managed devices (semaphore implementation).
QPOWEEN0.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for system BIOS (semaphore implementation).
QPOWEEN1.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for display devices (semaphore implementation).
QPOWEEN2.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for secondary storage devices (semaphore implementation).
QPOWEEN3.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for parallel ports (semaphore implementation).
QPOWEEN4.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for serial ports (semaphore implementation).
QPOWEEN6.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for PCMCIA Sockets (semaphore implementation).
QPWDIS01.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for system BIOS-managed device drivers (semaphore implementation).
QPOWDIS0.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for system BIOS (semaphore implementation).
QPOWDIS1.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for display devices (semaphore implementation).
QPOWDIS2.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for secondary storage devices ( semaphore implementation).
QPOWDIS3.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for parallel ports (semaphore implementation).
QPOWDIS4.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for serial ports (semaphore implementation).
QPOWDIS6.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for PCMCIA sockets (semaphore implementation).
QPWENG01.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for System BIOS-managed devices (semaphore implementation).
QPOWENG0.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for system BIOS (semaphore implementation).
QPOWENG1.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for display devices (semaphore implementation).
QPOWENG2.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for secondary storage devices (semaphore implementation).
QPOWENG3.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for parallel ports (semaphore implementation).
QPOWENG4.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for serial ports (semaphore implementation).
QPOWENG6.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for PCMCIA sockets (semaphore implementation).
QPWDSE01.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for system BIOS-managed devices (semaphore implementation).
QPWDSEN0.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for system BIOS (semaphore implementation).
QPWDSEN1.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for display devices (semaphore implementation).
QPWDSEN2.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for secondary storage devices (semaphore implementation).
QPWDSEN3.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for parallel ports (semaphore implementation).
QPWDSEN4.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for serial ports (semaphore implementation).
QPWDSEN6.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for PCMCIA sockets (semaphore implementation).
QPWENS01.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for system BIOS-managed devices (non-semaphore implementation).
QPWENNS0.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for system BIOS (non-semaphore implementation).
QPWENNS1.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for display devices (non-semaphore implementation).
QPWENNS2.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for secondary storage devices (non-semaphore implementation).
QPWENNS3.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for parallel ports (non-semaphore implementation).
QPWENNS4.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for serial ports (non-semaphore implementation).
QPWENNS6.SCR
Returns the enable power management event information queued in the Power Management Services subsystem for PCMCIA sockets (non-semaphore implementation).
QPDSNS01.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for system BIOS-managed devices (non-semaphore implementation).
QPWDSNS0.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for system BIOS (non-semaphore implementation).
QPWDSNS1.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for display devices (non-semaphore implementation).
QPWDSNS2.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for secondary storage devices (non-semaphore implementation).
QPWDSNS3.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for parallel ports (non-semaphore implementation).
QPWDSNS4.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for serial ports (non-semaphore implementation).
QPWDSNS6.SCR
Returns the disable power management event information queued in the Power Management Services subsystem for PCMCIA sockets (non-semaphore implementation).
QPEGNS01.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for system BIOS-managed devices (non-semaphore implementation).
QPENGNS0.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for system BIOS (non-semaphore implememtation).
QPENGNS1.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for display devices (non-semaphore implementation).
QPENGNS2.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for secondary storage devices (non-semaphore implementation)
QPENGNS3.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for parallel ports (non-semaphore implementation).
QPENGNS4.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for serial ports (non-semaphore implementation)
QPENGNS6.SCR
Returns the engage power management event information queued in the Power Management Services subsystem for PCMCIA sockets (non-semaphore implementation).
QPDGNS01.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for system BIOS-managed devices (non-semaphore implementation).
QPDSGNS0.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for system BIOS (non-semaphore implementation).
QPDSGNS1.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for system BIOS-managed devices (non-semaphore implementation).
QPDSGNS2.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for secondary storage devices (non-semaphore implementation).
QPDSGNS3.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for parallel ports (non-semaphore implementation).
QPDSGNS4.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for serial ports (non-semaphore implementation).
QPDSGNS6.SCR
Returns the disengage power management event information queued in the Power Management Services subsystem for PCMCIA sockets (non-semaphore implementation).
QP01SE.SCR
Queries the power state of system BIOS-managed devices using semaphores for event notification.
QP0SE.SCR
Queries the power state of system BIOS using semaphores for event notification.
QP1SE.SCR
Queries the power state of display devices using semaphores for event notification.
QP2SE.SCR
Queries the power state of secondary storage devices using semaphores for event notification.
QP3SE.SCR
Queries the power state of parallel ports using semaphores for event notification.
QP4SE.SCR
Queries the power state of serial ports using semaphores for event notification.
QP6SE.SCR
Queries the power state of PCMCIA sockets using semaphores for event notification.
QP01NS.SCR
Queries the power state of system BIOS-managed devices without using semaphores.
QP0NS.SCR
Queries the power state of system BIOS without using semaphores.
QP1NS.SCR
Queries the power state of display devices devices without using semaphores.
QP2NS.SCR
Queries the power state of secondary storage devices without using semaphores.
QP3NS.SCR
Queries the power state of parallel ports without using semaphores.
QP4NS.SCR
Queries the power state of serial ports without using semaphores.
QP6NS.SCR
Queries the power state of PCMCIA sockets without using semaphores.
QPOWINFO.SCR
Returns the Power Management subsystem and BIOS configuration information.
QPOWSTAT.SCR
Returns the current power state information for the system and system devices.
QPWSTE01.SCR
Returns the current power state of system BIOS-managed devices.
QPOWSTE0.SCR
Returns the current power state of system BIOS.
QPOWSTE1.SCR
Returns the current power state of display devices.
QPOWSTE2.SCR
Returns the current power state of secondary storage devices.
QPOWSTE3.SCR
Returns the current power state of parallel ports.
QPOWSTE4.SCR
Returns the current power state of serial ports.
QPOWSTE6.SCR
Returns the current power state of PCMCIA sockets.
RBIOSDNS.SCR
Returns the Restore BIOS defaults event information queued in the Power Management Services Subsystem (non-semaphore implementation).
RBIOSDSE.SCR
Returns the Restore BIOS defaults event information queued in the Power Management Services Subsystem (semaphore implementation).
SINIDOFF.SCR
Handles the error case in which the power of an invalid device is attempted to be set to off.
SINSTAT1.SCR
Attempts to set the power of a valid device to an invalid power state.
SINVSTAT.SCR
Attempts to set the power of an invalid device to an invalid power state.

Evaluation of Test Case Results

The script files test all of the different APM IOCtl functions for the Advanced Power Management device driver. After each script file has finished executing, it will log all of the test information to a log file. Unless otherwise stated in the test case-description, all test cases are expected to succeed. If a test case fails in a mode detectable by the DDTT, then the token "ERROR" will be written to the corresponding file. On the other hand, if the test case is designed in such a manner that "ERROR" is expected, a "SUCCESS" is logged to the log file indicating that the test case is successful.

When the all of the script file has finished executing, the command file will search all of the log files for any errors that have occurred. The results from this search are stored in the RESULTS.TXT. The command file is searching only for the word "ERROR". If the script is testing an error situation, the user should also check a following "SUCCESS" to determine the real outcome of the test.

Asynchronous (RS232-C) Communications Device Driver

The Asynchronous Communications (ASYNC) device driver enables OS/2 applications to utilize the Serial Communications (RS232-C) device hardware. The physical device driver allows an application program in OS/2 session to support duplex communications while the device driver:

  • Services the RS232-C port in an interrupt-driven manner
  • Provides transmit and receive queues
  • Provides different automatic control modes for the modem control signals
  • Provides logical data stream flow control (XON/XOFF) for transmit and receive operations

The user will normally want to use the physical ASYNC device driver either in conjunction with the spooler (for serial printers only) or with an application program that uses the RS232-enabling capabilities of the physical ASYNC device driver coupled with a serial device attached to the system.

The user installs the physical ASYNC device driver by adding a DEVICE= statement to the CONFIG.SYS file.

Hardware Support

The RS232-C ASYNC communications device driver supports any personal computer system based on an 80386SX (or higher) microprocessor.

IBM PS/2 Micro Channel Adapter Support

The physical device driver supports a maximum of four ASYNC ports on a maximum of two different interrupt levels. The interrupt levels must have ABIOS support, with one unit per Logical ID (LID) for the ASYNC Device ID. The only ASYNC devices supported on IBM PS/2 and the Extended Industry Standard Architecture (EISA) machines are COM1, COM2, COM3, and COM4. These devices correspond to the first four LIDs in the ABIOS common data area that have the architected ASYNC Device ID. These devices also correspond to the first four ASYNC addresses in the ROM BIOS 40: data area.

If a device has capabilities other than ASYNC that cannot be utilized independently of the ASYNC capabilities (for example, as in the Advanced BIOS separate LID architecture), and if Advanced BIOS assigns the device the ASYNC Device ID, then that device can be used only for ASYNC in that power-on session.

If the device is assigned the ASYNC Device ID, and it has additional capabilities beyond supporting the RS232-C port (for example, a built-in modem), the physical device driver does not recognize those additional capabilities (and potential limitations). Also, the physical device driver does not inform any application program of those additional capabilities or limitations. In addition, it does not limit the control of the RS232-C interface or the device to only those modes that are acceptable to the extended hardware capabilities of that RS232-C port.

If the device is not assigned the ASYNC Device ID, it is not supported by this physical device driver. If an ASYNC device is not supported by the OS/2 operating system, but is recognized by Advanced BIOS as an ASYNC Device ID, the physical device driver can recognize and try to use that unsupported device, if it is COM1, COM2, COM3, or COM4.

AT Bus Adapter Support

The physical device driver for the IBM AT bus machines by default, supports two ASYNC ports, COM1 and COM2, each on separate levels. ASYNC ports with the following base I/O addresses are recognized by the physical device driver:

  • 3F8H (must generate a level 4 interrupt)
  • 2F8H (must generate a level 3 interrupt)

COM3 and COM4 are supported by the command line parameters for COM.SYS. COM3 and COM4 are supported through parameters on the DEVICE= statement in the CONFIG.SYS file. These parameters specify the desired base I/O address and interrupt levels. The physical ASYNC device driver for the AT-bus machine interfaces directly to the hardware and supports:

  • IBM AT-bus serial/parallel adapter based on the NS 16450 Universal Asynchronous Receiver Transmitter (UART) device
  • Other compatible adapters based on the UART architecture (NS 16550, NS 16550A)

Attachment Support

The ASYNC physical device driver does not provide any support for devices attached to the RS232-C port. The physical device driver provides enabling support for the RS232-C interface itself. Application programs, subsystems, and systems programs provide the support needed to use devices attached to the RS232-C port.

The ability to support a device can be determined by understanding the level of RS232-C interface enabling support the physical device driver provides, along with the characteristics of the attachment hardware in question and the required functions to be supported.

The OS/2 operating system provides a mechanism where one or more additional drivers can be installed to support specific COM ports. This feature might be required for the following reasons:

  • To allow an application program to support a special device not adequately supportable with this ASYNC device driver.
  • To allow additional COM ports (besides COM1-4 on IBM PS/2) to be supported.
  • To enhance the level of device driver function for a given COM port. (This might be required for certain subsystem support.)

RS232-C Interface

The ASYNC interface consists of separate read and transmit lines. There are two separate modem control signals whose output values can be controlled by the physical device driver:

  • Data Terminal Ready (DTR)
  • Request To Send (RTS)

There are four separate modem control signals whose input values are available to the physical device driver:

  • Data Set Ready (DSR)
  • Clear To Send (CTS)
  • Data Carrier Detect (DCD), also known as Receive Line Signal Detect (RLSD)
  • Ring Indicator (RI)

The receive and transmit data lines have the following hardware characteristics:

  • Logical 1 (Marking). More negative than -3 Volts. This state could mean no data.
  • Logical 0 (Spacing). More positive than +3 Volts. This state could mean break condition.

The modem control signal lines have the following hardware characteristics:

  • Function ON, when more positive than +3 Volts.
  • Function OFF, when more negative than -3 Volts.

Hardware Support for Extended Hardware Buffering

This capability is a feature of the asynchronous communications port's serial controller device. Serial controllers that support this capability, such as the NS-16550A UART, are present in many IBM PS/2 systems and on a variety of IBM and non-IBM asynchronous communications adapters.

INS 8250, INS 8250-B Considerations

The following hardware defects cannot be compensated for in the physical device driver and can cause indeterminate function when used with the OS/2 physical ASYNC device driver:

Line Control Configurations
These devices are known to transmit bad data when configured for 5 data bits and 1.5 stop bits.
Receive Character Overrun Errors
These devices are known to occasionally drop received characters without posting the RECEIVE_OVERRUN error flag. Undetected data loss can result from this hardware deficiency. Application error-correction routines can be implemented to ensure accurate data transmission when these devices are being used.
Spurious Characters at Power-On
These devices can transmit a single random character at power-on. The connected device must not be expecting valid data to be received until after the physical device driver initialization routine has been run.

Supported Bit Rates on 16450 and Compatibles

The NS 16450 and other compatible UART devices (including the 8250- and 16550-Series UARTs) incorporate a Programmable Baud Generator feature that is driven as a function of the following constants:

CLOCK     = 1843200    ; crystal frequency
CLOCK/16  = 115200     ; after divider

Given these constants, the algorithm for determining which rates are supported is explained in the following examples:

  • If 900 bps is specified, the bit rate is exactly 900 because it divides evenly into 115200 (115200/900 = 128). Bit rate, returned by IOCtl ASYNC_ GETBAUDRATE, is 900.
  • If 901 bps is specified, the bit rate does not change, and the IOCtl fails with an invalid parameter error because it cannot be supported within .01% (115200/901 = 128, 115200/128 = 900, which gives a .1111% error).
  • If 907 bps is specified, the bit rate is 907.0866 because it can be supported within .01% (115200/907 = 127, 115200/127 = 907.0866, which gives a .0095% error). Bit rate, returned by ASYNC_GETBAUDRATE, is 907.
  • If 110 bps is specified, the bit rate is 110.0287, even though the error is over .01% (115200/110 = 1047, 115200/1047 = 110.0287, which gives a . 0260% error). Bit rate, returned by ASYNC_GETBAUDRATE, is 110.

Note: Where division is performed and the quotient is not a whole integer, an integer result is obtained by rounding off the fractional part of the quotient.

ASYNC (RS232-C) Device Driver Features

The device driver supports the ASYNC interface in an interrupt-driven manner. This allows the multitasking capabilities of the OS/2 operating system to be supported while ASYNC data reception and transmission are taking place.

Warning: With any supported hardware, the physical device driver cannot absolutely guarantee accurate function, as there is a dependency on the hardware being driven. It is known, for example, that INS 8250 and INS 8250-B UART devices exhibit a number of deviations from their hardware specifications. In some cases, these deviations have been compensated for in the physical device driver design. Some of these deviations, however, cannot be resolved in software. The user must be familiar with the limitations and restrictions associated with such hardware.

When data is given to the transmit hardware, it has not yet been physically transmitted (at the RS232 interface). The data is considered completely transmitted by the transmit hardware at the physical RS232 interface when the transmit shift register of the UART is empty. The IOCtl, ASYNC_GETLINESTATUS, which can be found in the OS/2 Physical Device Driver Reference, can be used to determine this information.

The device driver transmit queue is a memory buffer between the operating system and the transmit hardware. The device driver receive queue is a memory buffer between the operating system and the receive hardware. Both are considered to be owned by the physical device driver because the physical device driver controls the data movement in and out of the transmit and receive queues. Algorithms for this data movement can change between releases of the physical device driver. Changes in the ASYNC hardware can cause changes in the data movement algorithms and external interfaces.

Data that applications send (made available by Write requests) is placed in the physical device driver transmit queue. When an interrupt occurs to tell the physical device driver that the hardware is ready for more data, the driver gives the transmit hardware more data from the transmit queue.

When an interrupt occurs to tell the physical device driver that the hardware has received data, that data is placed in the physical device driver receive queue. When the physical device driver gets a Read request (READ request packet) from the application, it fills the Read request from the receive queue.

At high bit rates, such as 19200 bits-per-second, a serial device supporting full-duplex asynchronous I/O can generate an interrupt every 260 microseconds (at 10 bits-per-character and one interrupt-per-character transmitted and received). This leads to excessive interrupt-time overhead in the multitasking, interrupt-driven, device driver.

To address this problem, serial devices with Extended Hardware Buffering capabilities (FIFO or First-In-First-Out buffers) have been developed. However, many serially-attached devices that support the RS232-C interface, have been designed to operate with specific protocols that assume the system processes all data I/O one character at a time. The ASYNC physical device driver employs a software mechanism that automatically controls parameters to utilize the Extended Hardware Buffering capability, while compatibly supporting devices that use existing ASYNC device driver protocols.

The Automatic Protocol Override (system default) mode for Extended Hardware Buffering support partially utilizes only these performance advantages, while remaining fully compatible with the behavior of existing ASYNC device driver protocols (for example, Input Sensitivity using DSR). Applications and subsystems can disable certain device driver default settings in order to fully use the Extended Hardware Buffering capabilities. This results in a significant reduction of serial device interrupt processing overhead, and greatly increases the aggregate bit rates that can be supported across multiple active COM ports.

The size of the receive and transmit queues are available from the following IOCtls:

  • Query Number of Characters in Receive Queue (ASYNC_GETINQUECOUNT)
  • Query Number of Characters in Transmit Queue (ASYNC_GETOUTQUECOUNT)

The physical device driver services each communications port independently. Requests issued to a given port have no effect on any other communications ports that the physical device driver might be servicing. The physical device driver processes READ and WRITE request packets independently for a given port. An application can be written to support simultaneous reception and transmission of data. In addition, the device driver can process an IOCtl request simultaneously with outstanding Read and Write requests.

The physical device driver does not schedule the processing of IOCtl requests. It processes the IOCtl request when received, regardless of what else it is doing. This can cause unexpected results if, for instance, the bit rate is modified while data reception or transmission is taking place. The application should issue only one IOCtl request at a time. If it issues another IOCtl request before the first IOCtl request is completed, the results are UNDEFINED.

The device driver queues multiple READ and WRITE request packets independently and always begins processing the READ request packets in the order they are received. It also begins processing the WRITE request packets in the order they are received.

Note: The operating system does not guarantee that file system requests will be delivered to a device driver in the order in which they are issued by an application. This means that a request by one thread can get blocked in the operating system, thus allowing a subsequent request by a different thread for the same function (for example, DosWrite) to pass through and arrive ahead of the first thread at the physical device driver. This is true for synchronous operations performed by multiple threads or asynchronous operations performed by the same thread.

Because of thread-priority considerations and the system dynamics, the order observed by the application of completing requests of the same type might not be the order in which they were received by the device driver. The physical device driver always keeps the data in the same order in which the READ and WRITE request packets (of the same type) were received. There is no ordering or timing between different types of request packets.

The concept of a First Level Open is described in the section on #States of the ASYNC Device Driver. A First Level Open occurs when the device driver receives an OPEN request packet for the port and the port is not already open (from a previous open without a matching close). A CLOSE request packet causing the physical device driver to process the next OPEN request packet as a First Level Open is called a Last Level Close. Because the requests that an application issues sometimes get out of order before they reach the device driver, an application cannot consider a close a Last Level Close until the CLOSE completes. If the application issues an Open request to the COM port before a previously issued Close request is completed, then the results are UNDEFINED.

A Flush request can be completed before all the appropriate request packets (which have been queued by the device driver) have been flushed. The appropriate request packets eventually are flushed and return to the caller, based on their priority and the system dynamics. Once the Flush request has been processed, the appropriate request packets do not cause data to be incorrectly transmitted (or received data to be moved).

The device driver supports different timeout processing characteristics and timeout settings for the Read and Write requests. Only the physical device driver is informed of when a given character is being transmitted or received at the hardware interface. Therefore, an application cannot expect to provide real-time flow control of data (in the middle of data transmission or reception) based on logical characters (XON/XOFF), or based on the state of the modem control signals by manually:

  • Controlling or monitoring those modem control signals
  • Monitoring the queue status
  • Monitoring data moving across the link

Alternatively, the physical device driver provides optional modes of operation to control the data flow through the RS232-C port automatically. OS/2 applications use IOCtls to select which protocols are to be made active.

Output Modem Control Signals

In addition to allowing the application to directly control RTS and DTR, the physical device driver has different automatic control modes to control the value of the output modem control signals:

  • Open and Close processing of DTR and RTS
  • Disable/Enable DTR and RTS
  • RTStoggling on transmit
  • Input handshaking using DTR and RTS

These control modes are described in the section on #States of the ASYNC Device Driver, and in the IOCtls description.

Note: The level of support provided by this device driver requires that DTR and RTS are turned on at least once, even if this puts the physical device driver in a mode where they will never be turned on again.

Input Modem Control Signals

Besides allowing the application to read directly the current state of DSR, CTS, DCD, and RI, the physical device driver has automatic modes that cause it to respond to the value that some input modem control signals can have:

  • Output handshaking using CTS, DSR, DCD
  • Input sensitivity using DSR

These control modes are described in the section on #States of the ASYNC Device Driver and in the IOCtls description. Additional information on the state of the input modem control signals is available by using the IOCtl ASYNC_GETCOMMEVENT.

Logical Flow Control (XON/XOFF)

The application can attempt to manually control the flow of data by using the following IOCtls:

  • Transmit Immediate (ASYNC_TRANSMITIMM)
  • Stop Transmit Behave as if XOFF Received (ASYNC_STOPTRANSMIT)
  • Start Transmit Behave as if XON Received (ASYNC_STARTTRANSMIT)

The physical device driver automatically controls the flow of transmitted data based upon the reception of XON/XOFF characters. This is referred to as Automatic Transmit Flow Control (XON/XOFF). The physical device driver also attempts to control the flow of data that is received by automatically transmitting XON/XOFF characters to the system it is communicating with, based on the amount of space left in the receive queue. This is referred to as Automatic Receive Flow Control (XON/XOFF).

Support for Extended Hardware Buffering

Another significant feature of this device driver is its exploitation of the Extended Hardware Buffering capabilities of the serial communications devices in many IBM systems and option adapters. Extended Hardware Buffering refers to the ability of the serial device servicing a COM port to buffer in hardware several characters, and to release them all at one time on the occurrence of a single transmit or receive hardware interrupt. This capability significantly reduces the interrupt-driven I/O processing overhead required to service Transmit and Receive requests on a given COM port. On the devices that support the Extended Hardware Buffering capability, this significantly improves COM I/O throughput and improves data integrity for higher data-transfer rates.

The Extended Hardware Buffering capabilities are automatically controlled under the default modes of the physical ASYNC device driver. Automatic Protocol Override is a feature of the OS/2 ASYNC device driver that automatically controls parameters relating to Extended Hardware Buffering. Systems and Adapters that incorporate the FIFO-mode hardware feature in a manner fully compatible with the NS-16550A UART are automatically enabled to run in Automatic Protocol Override mode.

Line Characteristics

IOCtls can be used to control and read the bit rate, number of stop-bits per character, number of data bits per character, and the parity characteristics of the line. See #States of the ASYNC Device Driver.

Break and Error Processing

The device driver can be commanded to transmit a Break with an IOCtl (ASYNC_SETBREAKON and ASYNC_SETBREAKOFF). An application can detect where an error or break occurred in the input data stream by using Break Replacement Character Processing and Error Replacement Character Processing. This requires that certain binary byte combinations be reserved for this purpose.

State of the COM Port

The following IOCtls can be used to determine the state of the COM port or if a given event happened. However, the exact timing relationship between this information and the specific data being received or transmitted at the time of the event is not available.

  • Query COM Event Information (ASYNC_GETCOMMEVENT)
  • Query COM Status (ASYNC_GETCOMMSTATUS)
  • Query COM Error (ASYNC_GETCOMMERROR)

Event Notification

The device driver does not provide any capabilities of event notification. For example, the only way for an application to know that RI changed state or that a Break condition occurred is to poll that status with the IOCtl ASYNC_GETCOMMEVENT. This should not be a problem for those applications that can use the automatic control modes of the physical device driver during the course of a communications dialog (for time-critical control functions). Polling could be adequate for non-time-critical event monitoring.

Error Alert Generation

The ASYNC physical device driver supports SNA Generic Alerts by generating Error Alerts, as defined under the OS/2 Logging Facility. Alerts are generated by the ASYNC driver whenever the OS/2 Logging Facility is enabled by the user at system initialization time.

Alerts may be generated only while the COM port is open and is processing a Write request (transmitting data). Write Timeout mode must be normal. (If Infinite Timeout mode is enabled, timeouts do not occur.) Error Alerts can be generated only when a Write Timeout occurs while waiting for:

  • CTS to be asserted, when Transmit is disabled because CTS is inactive. The Output Handshaking Using CTS mode must be enabled for this alert-generating condition to occur. This mode is enabled by default in the physical ASYNC device driver.
  • DSR to be asserted, when Transmit is disabled because DSR is inactive. The Output Handshaking Using DSR mode must be enabled for this alert-generating condition to occur. This mode is enabled by default in the physical ASYNC device driver.
  • DCD to be asserted, when Transmit is disabled because DCD is inactive. The Output Handshaking Using DCD mode must be enabled for this alert-generating condition to occur. This mode must be enabled by an application. It is not enabled by default in the ASYNC device driver.
  • An XON to be received, when Transmit is disabled because an XOFF is received. Automatic Transmit Flow Control mode must be enabled for this alert-generating condition to occur. This mode must be enabled by an application. It is not enabled by default in the ASYNC device driver.

Refer to the Set Device Control Block (DCB) Parameters Note on the IOCtl ASYNC_SETDCBINFO which can be found in the OS/2 Physical Device Driver Reference.

States of the ASYNC Device Driver

The different processing states of the physical ASYNC device driver, the ASYNC hardware, and the ASYNC control signals are listed below:

  • Automatic Receive Flow Control (XON/XOFF)
  • Automatic Transmit Flow Control (XON/XOFF)
  • Bit Rate
  • Break Replacement Character
  • Break Replacement Character Processing
  • COM Event WORD and COM Error WORD
  • Data Bits
  • DTR and RTS
  • DTR Control Mode
  • Error Replacement Character
  • Error Replacement Character Processing
  • Extended Hardware Buffering
  • Input Sensitivity Using DSR
  • Null Stripping
  • Output Handshaking Using CTS, DSR, DCD
  • Parity
  • RTS Control Mode
  • Read Timeout State
  • Read Timeout Value
  • Stop Bits
  • Transmit Immediate
  • Transmitting Break
  • Write Timeout State
  • Write Timeout Value
  • XON/XOFF Characters

Each of the above states are covered as follows:

  • A brief description.
  • The initial (default) value.
  • The effect on the physical device driver when the physical device driver receives an OPEN request packet for the port and the port is not already open (from a previous OPEN without a matching CLOSE). This is called a First Level Open. If applicable, the way the state of the physical device driver is affected by a CLOSE request packet.
  • How the MODE utility can be used to alter the state of this item or how the MODE utility will alter the state of this item.
  • The effect on the physical device driver of the state of Extended Hardware Buffering. In particular, special considerations relating to Automatic Protocol Override are given where the protocol being described is affected by this feature of the physical ASYNC device driver.

Automatic Receive Flow Control (XON/XOFF)

When the physical device driver is enabled for this mode of operation, it transmits an XOFF when its receive queue gets close to full, and an XON when its receive queue is about half full.

The normal mode of Automatic Receive Flow Control causes the ASYNC device driver to stop transmitting all data after it sends an XOFF character until its receive queue lowers to about half full, when it sends the XON character. This behavior is suitable for most devices, but reduces transmit throughput significantly in Full-Duplex (Transmit and Receive) communications scenarios. By setting the Full-Duplex mode of Automatic Receive Flow Control, the physical ASYNC device driver continues to send application data after it sends the XOFF character. See IOCtl ASYNC_ SENTDCBINFO which can be found in the OS/2 Physical Device Driver Reference.

Initial Value Automatic Receive Flow Control is disabled.
First Level Open There is no effect on whether the physical device driver is enabled or disabled for this mode of operation. The state of the physical device driver is reset to show that the last flow control character automatically transmitted was an XON, if it is enabled for this mode of operation.
Close Considerations If the last character automatically transmitted by the physical device driver was an XOFF and a CLOSE request packet is received, the physical device driver automatically transmits an XON, if possible. After processing this close request, the port is not open any more from another open without a close.
Mode Utility Always disables Automatic Receive Flow Control.

Automatic Transmit Flow Control (XON/XOFF)

When the physical device driver is enabled for this mode of operation, it stops sending data to the transmit hardware when an XOFF is received, and resumes sending data to the transmit hardware when an XON is received.

If this mode is enabled, Error Alerts can be generated when the OS/2 Logging Facility is enabled. If an external device sends an XOFF, but does not send an XON, transmission of data is blocked because the device driver is waiting for the XON to be received. If the XON is not received before the Write Timeout period expires, an Error Alert is generated.

Initial Value Automatic Transmit Flow Control is disabled.
First Level Open There is no effect on whether the physical device driver is enabled or disabled for this mode of operation. The state of the physical device driver is reset to show that it has not received an XOFF, so it can transmit (due to automatic transmit flow control), if it is enabled for this mode of operation.
Mode Utility User interface to enable/disable this mode of the physical device driver.
Automatic Override When Automatic Transmit Flow Control is enabled, the physical device driver responds to receiving the XOFF within a single character time. That is, Automatic Protocol Override controls the Extended Hardware Buffering capability so that only one character is buffered for transmit at a time, and the device generates an interrupt for every character received (Receive Trigger Level is set to 1).

Bit Rate

The bit rate determines the hardware setting for the data transfer rate, specified in bits per second, and is the speed for which the hardware is configured. See IOCtls ASYNC_SETBAUDRATE and ASYNC_GETBAUDRATE, which can be found in the OS/2 Physical Device Driver Reference.

Initial Value 1200 bps
First Level Open No effect
Mode Utility User interface to change the bit rate

Break Replacement Character

The device driver uses this character value if Break Replacement Character Processing is enabled. See IOCtl ASYNC_SETDCBINFO, which can be found in the OS/2 Physical Device Driver Reference.

Initial Value 00h
First Level Open Reset to 00h
Mode Utility No effect

Break Replacement Character Processing

If Break Replacement Character Processing is enabled and the device driver detects a break condition, it places the break replacement character in the physical device driver receive queue. If Break Replacement Character Processing is disabled, the physical device driver does not place any character in the physical device driver receive queue when it detects a break condition.

Initial Value Break replacement character processing is disabled.
First Level Open Break replacement character processing is disabled.
Mode Utility No effect.

COM Event WORD and COM Error WORD

These two WORDs have bits that show the status of the COM port. When an event occurs, the appropriate bits are turned on. The bits are cleared when the WORD is read with the appropriate IOCtl. See IOCtls ASYNC_GETCOMMEVENT and ASYNC_GETCOMMERROR, which can be found in the OS/2 Physical Device Driver Reference.

Initial Value All defined bits are 0
First Level Open All defined bits are 0
Mode Utility Not applicable

Data Bits

This is the number of bits contained in each character transmitted or received by way of the communications hardware. See IOCtls ASYNC_SETLINECTRL and ASYNC_GETLINECTRL, which can be found in the OS/2 Physical Device Driver Reference.

Initial Value 7 data bits
First Level Open No effect
Mode Utility User interface to change the number of data bits

DTR and RTS

This is the value of the modem control signals Data Terminal Ready (DTR) and Request To Send (RTS) put out by the communications hardware. Each signal is controlled independently and can be either ON or OFF. See IOCtls ASYNC_SETMODEMCTRL and ASYNC_GETMODEMOUTPUT, which can be found in the OS/2 Physical Device Driver Reference.

Initial Value When the physical device driver starts the port during device driver initialization, their values are turned OFF.
First Level Open The signals are normally turned ON, but there are many conditions that can cause the signals to be affected differently. See IOCtls ASYNC_SETMODEMCTRL and ASYNC_SETDCBINFO, which can be found in the OS/2 Physical Device Driver Reference, for a complete explanation.
Close Considerations A Close request packet causes DTR and RTS to be turned OFF after the transmit hardware has completely transmitted all the data sent by the physical device driver. After processing this Close request, the port is no longer open from another OPEN without a CLOSE. In addition, at least 10 additional character times must have elapsed (or one second, whichever is less).
Mode Utility Not applicable for direct control. Indirect effects through altering processing modes of the physical device driver are possible.

DTR Control Mode

The control modes for DTR are:

  • Enable
  • Disable
  • Input Handshaking

The Enable and Disable control modes of DTR affect DTR processing during a First Level Open. When these control modes are set through the ASYNC_SETDCBINFO, the value of the DTR signal can be modified immediately by the physical device driver. The action depends on the previous control mode of DTR and the current value of the DTR modem control signal. If the control mode of DTR is Input Handshaking, then the device driver controls the DTR signal, depending on how full the receive queue is. The bits that control these states of the device driver are in the device control block.

Initial Value Enable
First Level Open No effect
Mode Utility User interface to change the DTR Control Mode of the physical device driver

Error Replacement Character

The character value that the physical device driver uses, if Error Replacement Character Processing is enabled.

Initial Value 00h
First Level Open Reset to 00h
Mode Utility No effect

Error Replacement Character Processing

The processing that the physical device driver performs when a received character has an error (parity, framing, overrun, or lack of receive queue space) is determined by whether Error Replacement Character Processing is enabled (active).

Initial Value Error replacement character processing is disabled.
First Level Open Error replacement character processing is disabled.
Mode Utility No effect.

Extended Hardware Buffering

The extended hardware buffering (FIFO-mode) capabilities available in supported systems apply to the NS-16550A UART device and other fully compatible devices. These serial devices are installed on many IBM PS/2 system boards, and on various ASYNC communications adapter options. Refer to #Hardware Support for Extended Hardware Buffering.

On those systems that incorporate serial devices that fully and compatibly support Extended Hardware Buffering, the OS/2 ASYNC device driver provides three modes for exploiting this feature:

  • Enabled
  • Disabled
  • Automatic Protocol Override

The default is to enable Automatic Protocol Override on that COM port. Automatic Protocol Override is an asynchronous device driver mode of operation that automatically controls various parameters of Extended Hardware Buffering, such as Receive Trigger Level and Transmit Buffer Load Count.

Automatic Protocol Override causes the Receive Trigger Level and Transmit Buffer Load Count to be adjusted according to the device driver handshaking protocols in effect. When Automatic Protocol Override mode is ON and the handshaking protocols are set to their default settings, the physical device driver partially exploits only the performance advantages of Extended Hardware Buffering. The default handshaking protocols are:

  • Enabled for Input Sensitivity Using DSR
  • Enabled for Output Handshaking Using CTS and DSR
  • Disabled for Output Handshaking Using DCD
  • Disabled for Automatic Transmit Flow Control

If both Input Sensitivity Using DSR and Output Handshaking Using CTS and DSR are disabled, the Automatic Protocol Override causes the asynchronous device driver to automatically reset internal parameters (fully exploiting the Extended Hardware Buffering capabilities to the maximum extent possible).

The physical device driver's initialization default is to set Extended Hardware Buffering capabilities to the Automatic Protocol Override mode. An application or subsystem can alternatively set Extended Hardware Buffering to DISABLED, which causes the hardware to service transmit and receive interrupts one character at a time. It can also set Extended Hardware Buffering to ENABLED, which causes the physical device driver to set certain Extended Hardware Buffering parameters to specified levels, so the serial device fully exploits its Extended Hardware Buffering capabilities to the maximum extent possible.

When Extended Hardware Buffering is set to ENABLED, the following serial device hardware capabilities are exploited for maximum performance benefit and increased receive data integrity:

  • By setting the Transmit Buffer Load Count to 16, up to 16 characters are placed in the transmit hardware buffer (FIFO) during the processing of one Transmit Holding Register Empty (THRE) interrupt.
  • A 16-character receive hardware buffer (FIFO) is available with the Receive Trigger Level set to 1, 4, 8, or 14 characters. The Receive Trigger Level determines when the receive hardware generates a Receive Data Available hardware interrupt.

If the physical device driver receives an Open request for a COM port that is not already open, it does not alter the Extended Hardware Buffering setting that is in effect at the time. The ASYNC physical device driver preserves this state across multiple Open and Close requests.

Initial Value Automatic Protocol Override mode is on
First Level Open No effect
Mode Utility User interface to set the Extended Hardware Buffering mode to ENABLED, DISABLED, or to Automatic Protocol Override

Input Sensitivity Using DSR

When the physical device driver is enabled for this mode of operation and DSR is OFF, the physical device driver discards receive data.

Initial Value Input Sensitivity using DSR is enabled
First Level Open No effect
Mode Utility User interface to enable/disable this mode of the physical device driver
Automatic Override When Input Sensitivity Using DSR is enabled, the physical device driver responds to the lowering of the DSR line within a single character time. That is, the Extended Hardware Buffering (Receive Trigger Level) is adjusted so the device generates an interrupt for each character received. The full 16-character receive buffer is still available to help avoid any receive hardware overruns. The Transmit FIFO feature is also still enabled so that only one transmit interrupt occurs for every 16 characters transmitted.

Note: In situations where DSR can naturally drop from O to OFF at the end of a communications session, but is not normally toggled during the session, it is most advantageous to disable Input Sensitivity Using DSR after the communications data transfer has begun. This achieves a significant performance benefit (under the control of Automatic Protocol Override), without the risk of losing valid data upon termination of the session. If, however, the DSR signal is expected to toggle frequently during a communications session, Input Sensitivity Using DSR should not be disabled, or potential data loss can result.

Null Stripping

If the physical device driver is enabled for null stripping, characters read in from the receive hardware (nonerror or nonbreak) with a value of 00h are thrown away. These null characters are stripped (not checked for Automatic Transmit Flow Control), even if the XON or XOFF character has been set to 00h, and are not placed in the physical device driver receive queue.

Initial Value Null stripping is disabled.
First Level Open Null stripping is disabled.
Mode Utility No effect.

Output Handshaking Using CTS, DSR, DCD

This mode of the physical device driver can be controlled independently for each modem control signal. When this mode is enabled, the physical device driver does not give data to the transmit hardware if the modem control signals are OFF (disabled). Data is not transmitted unless all the lines enabled for output handshaking are up.

If one of these modes is enabled, Error Alerts might be generated when the OS/2 Logging Facility is enabled. If an external device causes CTS, DCD, or DSR to become inactive, transmission is blocked while the device driver waits for the respective line to become active again. If the line does not become active before the Write Timeout period expires, an Error Alert is generated.

Initial Value Output handshaking using CTS and DSR is enabled. Output handshaking using DCD is disabled.
First Level Open No effect.
Mode Utility User interface to enable/disable this mode of the physical device driver for CTS and DSR (independently). Mode always disables this mode of operation of the physical device driver for DCD.
Automatic Override When Output Handshaking using DSR, CTS, or DCD is enabled, the physical device driver responds to the dropping modem line within a single character time. That is, Automatic Protocol Override controls the Extended Hardware Buffering capability so that only one character at a time is given to the transmit hardware (Transmit Buffer Load Count is set to 1). The Receive Trigger Level is unaffected.

Parity

Determines whether a parity bit exists and, if appropriate, what algorithm determines its value. See ASYNC_SETLINECTRL and ASYNC_GETLINECTRL, which can be found in the OS/2 Physical Device Driver Reference.

Initial Value Even parity
First Level Open No effect
Mode Utility User interface to change the parity characteristics

RTS Control Mode

The control modes for RTS are:

  • Enable
  • Disable
  • Input Handshaking
  • Toggling on Transmit

The Enable and Disable control modes affect RTS processing during a First Level Open. When these control modes are set using the ASYNC_SETDCBINFO, the value of the RTS signal can be immediately modified by the physical device driver. The action depends on the previous control mode of RTS and the current value of the RTS modem control signal. If the control mode of RTS is Input Handshaking, the device driver controls the RTS signal, depending on how full the receive queue is. If the control mode of RTS is Toggling on Transmit, then the physical device driver controls the RTS signal, depending on whether it is transmitting data. The bits that control these states of the physical device driver are in the device control block.

Initial Value Enable
First Level Open No effect
Mode Utility User interface to change the RTS Control Mode of the physical device driver

Read Timeout State

When the physical device driver processes a READ request packet, it can be with Normal, No-Wait, or Wait-For-Something Timeout processing. With NormalTimeout processing, if no data is received in the specified period of time, the request is completed. With No-WaitTimeout processing, the request obtains whatever data is available in the physical device driver receive queue (at the time the request is processed by the device driver) and returns. With Wait-For-SomethingTimeout processing, the request acts like No-Wait Timeout processing. However, if no data is available when the device driver processes the request, the physical device driver waits until some data is available or until the request times out due to Normal Timeout processing.

Initial Value Normal Read Timeout processing
First Level Open The device driver is set to Normal Read Timeout processing
Mode Utility No effect

Read Timeout Value

The user-specific value, in .01 seconds units (based on 0, where 0 = .01 seconds), is used for the Read Timeout processing, if Normal Read Timeoutor Wait For SomethingTimeout processing is enabled.

Initial Value 1 minute
First Level Open Set to 1 minute
Mode Utility No effect

Stop Bits

Determines the number of stop bits associated with each character transmitted or received by way of the communications hardware.

Initial Value 1 stop bit
First Level Open No effect
Mode Utility User interface to change the number of stop bits

Transmit Immediate

The device driver can be told to transmit a byte immediately, bypassing the normal file system Write requests (bypassing the data to be transmitted in the transmit queue). Only one character at a time can be waiting to be transmitted immediately.

Initial Value There is no character waiting to be transmitted immediately.

First Level Open There is no character waiting to be transmitted immediately.

Close Considerations A CLOSE request packet, when after processing this close request the port is not open any more (from another open without a close), causes the device driver to attempt to transmit the character waiting to be transmitted immediately. If the physical device driver cannot transmit the character waiting to be transmitted immediately (see IOCtl Category 01h ASYNC_TRANSMITIMM), which can be found in the OS/2 Physical Device Driver Reference, it does not try to transmit the character and proceeds with the close processing.

Mode Utility Not applicable.

Transmitting Break

The device driver can be transmitting a break. See IOCtls ASYNC_SETBREAKON and ASYNC_SETBREAKOFF, which can be found in the OS/2 Physical Device Driver Reference.

Initial Value Not transmitting a break.

Close Considerations A CLOSE request packet, when after processing this close request the port is not open any more (from another open without a close), causes the device driver to tell the hardware not to transmit a break any more.

Mode Utility Not applicable.

Write Timeout State

When the physical device driver processes a WRITE request packet, it can be with Normal or Infinite Timeout processing. With Normal Timeout processing if no data is given to the transmit hardware within a specified amount of time, the request is completed. With Infinite Timeout processing, the request is completed only when all the data from the request has been given to the transmit hardware.

Error Alerts can be generated on the occurrence of Write Timeout, if the OS /2 Logging Facility is enabled. In order for an error alert to be generated by the physical ASYNC device driver, the appropriate mode of operation must be enabled.

Initial Value Normal Write Timeout processing
First Level Open No effect on Write Timeout processing
Mode Utility User interface to set Infinite or Normal Write Timeout processing

Write Timeout Value

The user-specific value, in .01 seconds units (based on 0, where 0 = .01 seconds), is used for the Write Timeout processing, if Normal Write Timeout processing is enabled.

Initial Value 1 minute
First Level Open Set to 1 minute
Mode Utility No effect

XON/XOFF Characters

The characters used for automatic transmit and automatic receive flow control.

Initial Value XON is 11h, and XOFF is 13h
First Level Open The XON and XOFF characters are reset to their initial values
Mode Utility No effect

Reserved Device Names (COM1-n)

The device name AUX does not appear in the device header of the ASYNC device driver. The ASYNC physical device driver does not support the reserved name AUX for either DOS applications or OS/2 applications.

IBM PS/2 (with Micro Channel) Considerations for COM1-4

The IBM PS/2 ASYNC device driver has device names COM1, COM2, COM3, and COM4 in its device driver header. Device name COM1 corresponds to the first LID in the ABIOS common data area with the ASYNC Device ID. Device name COM2 corresponds to the second LID. Device name COM3 corresponds to the third LID. Device name COM4 corresponds to the fourth LID in the ABIOS common data area with the ASYNC Device ID.

The Advanced BIOS architecture ensures that the ordering in the ROM BIOS 40 : data area matches the ordering of the LIDs in the common data area. Compatibility BIOS supports up to four ASYNC devices on the IBM PS/2 system, and the physical device driver assumes that the order of the Logical IDs matches the order of the addresses of these devices in the ROM BIOS 40: data area. Additional ASYNC devices can be supported by additional device drivers.

The mapping of the ASYNC Logical ID ordering to COMn must be consistent across all device drivers that support the ASYNC hardware in the IBM PS/2 hardware environment.

Initialization/Resource Management

The device driver is loaded and initialized with a DEVICE= statement in the CONFIG.SYS file. They physical device driver processes parameters on the CONFIG.SYS to support COM ports with nonstandard address and IRQ's. Type help com.sys and read about the parameters.

During initialization, the physical device driver attempts to free memory from its data segment for ports it does not need and that do not get initialized. The physical device driver does not remove device names from its device driver header for ports that do not get initialized.

The device driver does not deinstall a device if the system requests it. If another device driver wishes to support a port already supported by this device driver, it needs to be initialized before this ASYNC device driver.

Shared ownership of a given serial device between multiple device drivers in a single session of the OS/2 operating system is supported, subject to certain restrictions. Each driver that installs sharing a serial device obtains exclusive access to that device when it processes an Open request, rather than claiming the device during initialization. Each driver also fully relinquishes control of that device, when it processes a matching Close request.

When the physical device driver is initialized, it is enabled by default for Output Handshaking Using CTS and DSR. This is for compatibility with existing systems (IBM PC and PS/2 BIOS INT 14H) and the requirements of supporting an RS232 port. It is also enabled by default for Input Sensitivity to DSR. This allows a remote device to indicate whether data being received is valid and is enabled to help ensure compatibility with existing systems. The initialization default for Extended Hardware Buffering on serial devices that fully support FIFO mode operations is Automatic Protocol Override.

Note: The ASYNC device driver default protocols provide an upwardly compatible RS232-C interface for communication with most devices. New communication applications and devices might not require the default protocols to be enabled. The user should evaluate these alternatives and consider which protocols to enable or disable in order to provide the highest possible performance for support of a given serial device.

Initialization Considerations

The device driver does not attempt to initialize or support a port if it does not get the INIT request packet for the port's corresponding device name. If the physical device driver gets the INIT request packet for a given device name, it checks to see if a valid I/O address is in the BIOS 40: data area that corresponds to that device name. COM1 is in 40:0 and COM2 is in 40:2. If the 40: area does not have a valid I/O address, the physical device driver fails the port and will not support the port. Otherwise, the device driver attempts to get exclusively the interrupt level that corresponds to the I/O address for the port. If the interrupt level is not available, the physical device driver fails to initialize the port and will not support the port.

If the interrupt level is available, the physical device driver relinquishes the interrupt level. The physical device driver also initializes the port and sets up support for the port during this startup of the operating system.

In summary, in order for the physical device driver to support a port, the following must be TRUE:

  • The device driver must get an INIT request packet for the device name.
  • The 40: area that corresponds to the device name must have a valid I/O address.
  • The appropriate interrupt level must be available for exclusive use, even though the physical device driver will not claim the interrupt level for exclusive use during initialization.

The physical device driver claims ownership of the port by not deinstalling the corresponding device name. Another device driver can cause this device driver not to claim a port by initializing before this device driver, and by doing at least one of the following:

  • Not allowing this physical device driver to receive an INIT request packet for a given device name
  • Putting an invalid I/O address in the corresponding 40: area (for example, 0)
  • Exclusively owning the appropriate interrupt level at initialization time

The device driver does not attempt to initialize or support a port if it does not get the INIT request packet for the port's corresponding device name. If the physical device driver gets the INIT request packet for a given device name, it attempts to claim ownership of the specific LID position for the ASYNC Device ID that corresponds to the device name being initialized.

For Micro Channel bus machines, if the LID is not available, the physical device driver fails to initialize the port and does not support the port. If the LID is available, the physical device driver initializes the port and sets up support for the port during this startup of the operating system. The LID for the port is relinquished; it is reclaimed during Open processing.

For the AT-bus machine, COM.SYS still installs even though the LID is not present.

In summary, for the physical device driver to support a port on an IBM PS/2 computer, the following must be TRUE:

  • The physical device driver must get an INIT request packet for the device name.
  • The ASYNC LID corresponding to the device name must be available.

The physical device driver claims ownership of the port by not deinstalling the corresponding device name. Another device driver can cause this device driver not to claim a port by initializing before this device driver and doing at least one of the following:

  • Not allowing this device driver to receive an INIT request packet for a given device name.
  • Claiming the appropriate ASYNC LID.

Data Translation/Monitor Support/Spooler Support

The physical device driver provides no data translation, code page, or monitor support. It is the responsibility of the application or subsystem to provide any function required in these areas.

Spooling from LPT to COM is supported by the spooler, but spooling from COM to LPT, or COM to COM, is not supported. When spooling from COM to LPT, code page support is provided by the spooler.

Any requests for registering or opening a monitor chain to COMn are rejected by the physical device driver. The physical device driver deals with binary data and provides no special processing of binary or ASCII data streams.

ASYNC Communication Device Driver Interfaces

The physical ASYNC device driver supports a large set of generic IOCtl functions (Category 01h), which are organized into the following groups:

  • Break Processing
  • Device Control Block (DCB) Parameter Access
  • Device Driver I/O Queue Management
  • Line Characteristics
  • Manual XON/XOFF Processing
  • Polled Event Functions

File System Requests

The physical ASYNC device driver supports the File System requests as shown in the following table.

Request Description
INIT Initialize the device
Open Open the device
Close Close the device
Read Read from the device (Normal, Non-Destructive, No-Wait)
Write Write to the device
Status Input or output status
Flush Flush or terminate all pending requests
Open Processing

The physical device driver does not claim the interrupt level the port is on until the port is open. If the interrupt level is not available, the OPEN request packet fails. The interrupt level is claimed exclusively on the ISA bus machines. The interrupt level is claimed shareable on the Micro Channel architecture machines.

On PS/2 machines, a First Level Open causes the physical device driver to attempt to obtain a Logical ID. If this fails (which indicates another physical device driver might be using the device), a general failure is returned. If the Logical ID is obtained, but the open fails for some other reason, the Logical ID is freed. Other physical device drivers that coexist with the OS/2 physical ASYNC device driver perform similar processing.

If a timer tick handler is not available during First Level Open processing, the Open request can fail. If the physical device driver receives an OPEN request packet and the COM device is not already open (from a previous open without a close), this is called a First Level Open, and the physical device driver does special processing. See #States of the ASYNC Device Driver. If a subsequent Open request is issued before a previous First Level Open request has completed, the device driver might process the OPEN request packets in an order different from the one in which they were issued. This could cause the First Level Open to take effect at a time different from what the application expected.

An Open request should never be issued until a previous Last Level Close request has completed. Otherwise, the function performed by a Last Level Close and a First Level Open might not occur. If the port is not already open (First Level Open), the physical device driver attempts to clear out any data in the receive hardware. On the IBM PS/2 system, if the port is not already open (First Level Open), the physical device driver relies on the Reset/Initialize Advanced BIOS function to reset and clear the UART receive hardware.

Close Processing

An application should never close an open handle to a COM port while there are requests still pending for that handle. If a request has not completed, it might be waiting for timeout processing. IOCtls are used to determine, and change, the current timeout processing.

A Last Level Close occurs when the port is no longer open (from another open without a close). When a Last Level Close occurs, the physical device driver does some special processing:

  • Clears the receive and transmit queues
  • Turns break OFF, if it is currently transmitting a break
  • Clears any character waiting to be transmitted immediately, if it cannot be transmitted If it can be transmitted, the physical device driver makes sure that it is given to the transmit hardware
  • Attempts to automatically transmit an XON (if possible), if currently enabled for Automatic Receive Flow Control (XON/XOFF), and the last character that the physical device driver automatically transmitted was an XOFF
  • Waits until all the data in the transmit hardware has been physically transmitted
  • Relinquishes the interrupt level
  • Turns DTR and RTS OFF, if they are not already OFF. The physical device driver first waits the specified number of character times
  • Relinquishes the Logical ID for the device (on PS/2 machines)
Read Processing

The physical device driver begins processing Read requests in the order it received them. Notice that this might not be the same order in which the requests were issued by the application. If the physical device driver receives more than one Read request, the request is queued on the Read request queue for later processing. Applications might not see Read requests completed in the order in which they were issued. The order of the data placed in the Read requests reflects the order in which the requests were received by the physical device driver.

The data for the Read requests comes from the physical device driver receive queue. Because of timeout processing, it is normal for the total number of Read characters requested not to be read. This is not considered an error. The request is completed when timeout is completed or when the amount of data requested is placed in the Read buffer. The various kinds of Read Timeout processing are discussed in the #States of the ASYNC Device Driver. To reduce the probability of a device driver receive queue buffer overrun, the communications protocol takes into account the size of the physical device driver receive queue.

Write Processing

The physical device driver begins processing Write requests in the order it received them. Notice that this might not be the same order that the requests were issued by the application. If the physical device driver receives more than one Write request, the request is queued on the Write request queue for later processing. Applications might not see Write requests complete in the order they were issued. The order of the data transmitted due to the Write requests reflects the order that the requests were received by the physical device driver.

The data from the Write requests is placed in the physical device driver transmit queue. The number of characters written is considered to be the number of characters given to the transmit hardware, and not the number of characters placed in the physical device driver transmit queue. Because of timeout processing, it is possible that the total number of Write characters requested will not be transmitted. This is not considered an error. The request is completed when it times out or when the amount of data requested is given to the transmit hardware (but not actually transmitted at the physical RS232-C interface). Write Timeout processing is discussed in #States of the ASYNC Device Driver.

If infinite Write Timeout processing is enabled, it is the responsibility of the application to monitor the status of the Write requests. The application might have to issue an IOCtl to disable infinite Write Timeout processing to cause the Write request to be completed (without all the data being transmitted). If an application does not check that all the data is given to the transmit hardware on each Write request, use the infinite timeout processing mode of the physical device driver to ensure that all the data has been given to the transmit hardware before the request is completed. To increase the throughput (ratio of number of characters transmitted per second to the bit rate), the application should keep the Write requests as large as possible.

Access Authorization

The physical ASYNC device driver does not prevent multiple processes from concurrently opening the same device name. The physical device driver uses standard file system contention control. An application or subsystem that needs exclusive access to the COM device will open it with access rights set to DENY_ANY. Inheritance of open handles, and sharing of the device among multiple opens, works in a manner similar to regular files.

ASYNC (RS232-C) Generic IOCtl Command Summary

The following table lists each function and its description:

Function Category 01h IOCtls
Line Characteristics
41h Set Bit Rate
42h Set Line Characteristics (stop, parity, data bits)
43h Extended Set Bit Rate
46h Set Modem Control Signals
61h Query Current Bit Rate
62h Query Line Characteristics
63h Extended Query Bit Rate
66h Query Modem Control Output Signals
67h Query Current Modem Input Signals
Manual XON/XOFF (Flow Control) Processing
44h Transmit Byte Immediate
47h Behave as if XOFF Received (stop transmit)
48h Behave as if XON Received (start transmit)
Break Processing
45h Set Break OFF
4Bh Set Break ON
Device Driver I/O Queue Management
68h Query Number of Characters in Receive Queue
69h Query Number of Characters in Transmit Queue
Polled Events
64h Query COM Status
65h Query Transmit Data Status
6Dh Query COM Error
72h Query COM Event Information
Enhanced Parameters
54h Set Enhanced Mode Parameters
74h Query Enhanced Mode Parameters
Device Control Block (DCB) Parameter Access
53h Set Device Control Block Parameters
73h Query Device Control Block Parameters

Note: Device Control Block parameters determine:

  • Automatic Transmit Flow Control (start/stop transmit, when XON/XOFF received)
  • Automatic Receive Flow Control (transmit XON/XOFF, when receive buffer fills/empties)
  • XON/XOFF Characters
  • DTR Control Mode (enable/disable/input handshaking)
  • RTS Control Mode (enable/disable/input handshaking/toggling on transmit)
  • Output Handshaking Using CTS/DSR/DCD (control signal determines when to transmit)
  • Input Sensitivity Using DSR (reception of data controlled by DSR)
  • Error Replacement Character and Processing
  • Break Replacement Character and Processing
  • Null Stripping
  • Timeout Processing
  • Extended Hardware Buffering (DISABLED/ENABLED/Automatic Protocol Override)

See "Generic IOCtl Commands", which can be found in the OS/2 Physical Device Driver Reference, for detailed descriptions of the asynchronous Category 01h IOCtl functions.

DOS Session Considerations/Restrictions

Applications using a serial printer from a DOS session must spool print data to the spooler through the appropriate LPT handles.

The physical device driver makes no attempt to restrict or mold the function of file system requests because they might have come from a DOS session. To achieve the full capabilities of the file system access to COM, the application needs access to the full range of Category 01h IOCtls. The design and externals of the physical asynchronous device driver are based on the requirements of OS/2-mode applications that use the RS232-C port of the system.

Spooler Considerations

When setting up a serial printer in the Serial Port Settings, the user can choose between two handshaking protocols. If the user selects None, the serial printer card switches must be set for XON/XOFF handshaking. If the user chooses Hardware, the serial printer card switches must be set for DTR Pacing.

Performance

The achievable performance is very sensitive to the environment. The type and amount of other system activity determine the achievable performance. On the IBM PS/2 system, the number of COM ports or other devices on the same interrupt level significantly affects the achievable performance level.

Trying to receive data at too high a bit rate could cause hardware overrun errors or receive queue overrun errors. Receive queue overrun errors are easily solved by adjusting the communications protocol to the size of the physical device driver receive queue. Trying to transmit data at too high a bit rate could also cause the performance of the operating system to be severely reduced.

The bit rate can be set with the MODE command or with an IOCtl. The bit rate should not be set to values that might cause receive overruns or adverse OS/2 system performance effects.

Enabling Extended Hardware Buffering

In most transmit-only situations (for example, serial printers), there is always a requirement for flow control (using Output Handshaking or Automatic Transmit Flow Control). If the attached hardware can receive a significant number of characters after the modem control (pacing) signal is changed, then setting Extended Hardware Buffering to enabled (ASYNC_SETDCBINFO) can be an acceptable way to significantly improve the transmit throughput and the operating system performance. This allows the Extended Hardware Buffering to yield maximum serial I/O performance while still providing the required Output Handshaking or Automatic Transmit Flow Control protocols required by the attached serial device. Testing with Extended Hardware Buffering enabled must be performed at the attached device when the physical asynchronous device driver is placed in this mode.

In many Receive and Transmit (half- or full-duplex) scenarios, disabling Input Sensitivity Using DSR has no negative effects. Many communications devices have switches that cause DSR to be constantly ON. Disabling Input Sensitivity Using DSR significantly improves the ability of the serial port hardware to handle receive data without receive hardware overrun errors. Another possible approach is to set Extended Hardware Buffering enabled by using IOCtl ASYNC_SETDCBINFO or the OS/2 MODE command.

In some other Transmit and Receive scenarios, disabling Output Handshaking Using CTS and DSR after a communications link has been established has no adverse effects under normal operating conditions. Again,the achievable performance benefits can be significant. Another possible approach is to set Extended Hardware Buffering enabled by using IOCtl ASYNC_SETDCBINFO.

The potential negative effects of disabling a default control mode of the physical device driver should be thoroughly understood. The potential performance benefits, however, can far outweigh the added complexity of usage and any other potential problems. Such problems can usually be resolved either by reverting to the Automatic Protocol Override mode or by using IOCtl ASYNC_SETDCBINFO to set Extended Hardware Buffering to disabled.

The per-character processing requirements must be addressed when deciding whether to override one of the default protocols of the physical device driver. Possible data integrity problems, such as receive overrun errors, loss of data at the beginning or end of a communications session, or receipt of invalid data on a noisy communications connection can occur. Such problems must be considered before using the potential performance benefits associated with Extended Hardware Buffering.

For ports operating at a given data-transfer rate, the system has less than 20% interrupt-driven device driver overhead when running with Extended Hardware Buffering enabled (both transmit and receive FIFO buffering active), as compared with running those ports on devices where Extended Hardware Buffering is disabled.

Also of equal importance are the operational characteristics of the device driver. By setting Extended Hardware Buffering enabled, the physical device driver can transmit with the full 16-character FIFO buffer active (essentially transmitting 16 characters at a time), and the Receive Data Available interrupts can provide 4, 8, or 14 characters each to the physical device driver receive queue. This is true no matter what device driver protocols are enabled. Examples of scenarios where setting the FIFO Enabled mode of the physical device driver might be acceptable are:

  • If the user does not care if too many characters are transmitted after a modem connection is broken.
  • If the printer or plotter connected to the system does not lose data when it tells the system (with a modem control signal), to stop transmitting, and the system continues to transmit a significant number (up to 16) of characters.
  • If the system is connected to a modem or another system that is normally set up to always keep DSR ON.
  • If the communications protocol with the remote device does not require the system to respond on a character-by-character basis to input data (for example, when the remote device sends data in blocks and provides error retry capability on a block basis rather than a per-character basis).

Note: VCOM.SYS does not currently support buffering.

CLOCK$ Device Driver

This chapter discusses the physical CLOCK$ device driver.

Physical CLOCK$ Device Driver

The OS/2 operating system assumes that a CMOS real-time clock is available in the system. The CLOCK$ device defines and performs functions like any other character device, except that it is identified by a bit in the attribute WORD. The operating system uses this bit to identify the device driver; therefore, this device can take any name. The device has been named CLOCK$ to avoid possible conflicts with any files named CLOCK.

The CLOCK$ device is unique because the OS/2 operating system reads or writes a 6-byte sequence, which encodes the date and time. Writing to this device sets the date and time; reading from it gets the date and time. The following figure illustrates the binary time format used by the CLOCK$ device:

  Byte 0     Byte 1     Byte 2     Byte 3     Byte 4     Byte 5
┌─────────────────────┬──────────┬──────────┬──────────┬──────────┐
│ Days since 01-01-80 │ Minutes  │ Hours    │ Sec/100  │ Seconds  │
│ Low-byte Hi-byte    │          │          │          │          │
└─────────────────────┴──────────┴──────────┴──────────┴──────────┘

The physical CLOCK$ device driver sets and maintains the following fields in the global InfoSeg:

TIME
Time, from 1-1-1980, in seconds
Milliseconds
Hours
Minutes
Seconds
Hundredths
Timer interval
DATE
Day
Month
Year
Day of week

The physical CLOCK$ device driver ensures that the date, time in seconds (from 1-1-1980), and time of day (hours, minutes, seconds) fields remain synchronized with the CMOS clock and that the hundredths of seconds field is correctly synchronized with the seconds field.

CMOS Clock

CLOCK$ is the device driver for the CMOS clock. The RTENTR routine is the task-time entry point to the Clock device driver. The requested functions are dispatched to worker routines.

RTENTR provides eight functions:

  • RTREAD(4)
  • STREDY(5)
  • STCOMP(6,7)
  • RTWRIT(8,9)
  • RTIOCT(16)
  • RTINIT(27)
  • RTINIT2(0)
  • BADCMD (all other functions)

A case control structure is used because a command table has only 8 valid entries of 28 options. Functions 6,7 and functions 8,9 have the same effect.

All Other Functions

Input: ES:BX= Address of Device Driver Request Packet

DS:= Points to Clock Device Driver Data Segment

Note: Parameter checking on input data to RTWRIT through this routine must be performed by the caller.

Output: Device Driver Request Packet filled in (for example, Status word set, date/time fields).

Equivalent Command Dispatch Table (Highest legal function is 27):

 ClkSwap:RTINIT2         ; 0 Initialize (2nd stage, special for clock)
 ClkSwap:BADCMD          ; 1 Media Check  these are unsupported
 ClkSwap:BADCMD          ; 2 Build BPB    functions.
 ClkSwap:BADCMD          ; 3 IOCTL input
 ClkSwap:RTREAD          ; 4 Input (Read)
 ClkSwap:STREDY          ; 5 Non-destructive read, no wait
 ClkSwap:STCOMP          ; 6 Input status
 ClkSwap:STCOMP          ; 7 Input flush
 ClkSwap:RTWRIT          ; 8 Output (Write)
 ClkSwap:RTWRIT          ; 9 Output with verify
 ClkSwap:BADCMD          ; 10 BADCMD
 ClkSwap:BADCMD          ; 11 BADCMD
 ClkSwap:BADCMD          ; 12 BADCMD
 ClkSwap:BADCMD          ; 13 BADCMD
 ClkSwap:BADCMD          ; 14 BADCMD
 ClkSwap:BADCMD          ; 15 BADCMD
 ClkSwap:RTIOCT          ; 16 Generic IOCTL
 ClkSwap:BADCMD          ; 17 BADCMD
 ClkSwap:BADCMD          ; 18 BADCMD
 ClkSwap:BADCMD          ; 19 BADCMD
 ClkSwap:BADCMD          ; 20 BADCMD
 ClkSwap:BADCMD          ; 21 BADCMD
 ClkSwap:BADCMD          ; 22 BADCMD
 ClkSwap:BADCMD          ; 23 BADCMD
 ClkSwap:BADCMD          ; 24 BADCMD
 ClkSwap:BADCMD          ; 25 BADCMD
 ClkSwap:BADCMD          ; 26 BADCMD
 ClkCode:RTINIT          ; 27 Initialize
 ClkSwap:BADCMD          ; 28 BADCMD here at table end
RTREAD

The Realtime Clock Read routine returns six bytes of date and time information in the form Date(word), Min, Hrs, Sec/100, Sec.

DevHlp_PhysToVirt converts the real address of the data buffer in the Device Driver Request Block (PktData) to a virtual address. DevHlp_UnPhysToVirt later restores the physical memory address.

RTREAD does not actually read the clock, but instead retrieves the data from the Global InfoSeg date/time data area.

STREDY

STREDY performs a non-destructive read operation with no-wait.

STCOMP

STCOMP sets the status to "complete".

RTWRIT

The Realtime Clock Write routine supports the device driver functions:

  • WRITE (function 8)
  • WRITE WITH VERIFY (function 9)

Set the Realtime Clock device with the date/time information and update the Global InfoSeg date/time variables accordingly. Set the stack frame to reserve the clock information as follows:

OLD BP
BP+16 CURRENT CENTURY YEAR - BCD CURRENT CENTURY YEAR - BINARY
BP+14 YEAR - BCD YEAR-BINARY
BP+12 MONTH - BCD MONTH-BINARY
BP+10 DAY OF MONTH BCD DAY OF MONTH BINARY
BP+8 DAY OF WEEK BCD DAY OF WEEK BINARY
BP+6 HOUR - BCD HOUR - BINARY
BP+4 MINUTE - BCD MINUTE - BINARY
BP+2 SECOND - BCD SECOND - BINARY
BP CENTURY-BINARY HUNDREDTH of SECOND-BINARY

DevHlp_PhysToVirt converts the real address of the data buffer in the Device Driver Request Block (PktData) to a virtual address. DevHlp_UnPhysToVirt later restores the physical memory address.

RTIOCT
The Realtime Clock Generic IOCTL routine supports the category 0Dh generic IOCTL commands by calling the appropriate worker routine.
RTINIT
RTINIT initializes data structures and the Realtime Clock device.
RTINIT2
There must be a delay hooking IRQ0 until after loadable device drivers/IFS are installed, because RIPL with ETHERNET/PC-NET uses IRQ0. The kernel calls the loadable device driver init with command 0, which then hooks the IRQ0. The RTINIT2 routine is then invoked.

Joystick Device Driver

The Advanced OS/2 Joystick Device Driver has two main purposes:

  • To provide a reliable joystick device driver for DOS games running under OS/2.
  • To provide a standard device driver for OS/2 game programmers that they can use as an interface between the PC game adapter port and their products.

Understanding How the IBM PC Game-Port Adapter Works

The IBM PC game-port adapter provides a simple interface to joysticks and other similar analog devices. The status of up to four analog and four digital signals is read through I/O port address 201h. Two analog and two digital signals are commonly grouped together in the form of a dual-axis joystick with two "fire" buttons. Some modern joysticks use two axes for movement and an additional axis for throttle.

Each analog and digital signal is assigned one bit in the game adapter port. A low (binary zero) value for a bit connected to a joystick button is returned when that button is depressed. Bits representing analog signals are implemented as one-shot outputs. All one-shots are fired when the I/O port is written to and remain high until an RC timing circuit decays. The variable position of each joystick axis provides the necessary resistance for this delay circuit. If a joystick axis is not connected, the infinite resistance across that signal holds the one-shot high indefinitely.

Determining the position of each joystick axis is done by measuring the duration of the high state for each one-shot. Two methods are commonly used to measure this duration: counting loop iterations and reading the hardware timer. Although the iterative method is dependant on the speed of the processor, this limitation becomes irrelevant with proper calibration of each axis. This is the method chosen to sample the game-port adapter in this device driver.

Understanding How the Joystick Device Driver Works

The pre-emptive multi-tasking nature of OS/2 can cause DOS applications reading the game adapter port to deduce incorrect positions for the joysticks connected. The solution implemented in this device driver to fix this is to regularly sample the game adapter port inside the Physical Device Driver (PDD) and then return fabricated values to the DOS application that reflect that state. With the logic for regularly sampling the port already in the PDD, all that must be done in that regard is to activate that procedure.

Before any of this can be initiated, the first thing that must be done is to trap any access to the game port by the DOS application. Any time I/O ports are to be trapped or emulated, an OS/2 Virtual Device Driver (VDD) is required. The VDD works in conjunction with the PDD to provide the device emulation by capturing port reads and returning values that reflect the current state as determined by the PDD. The VDD is also responsible for determining whether or not a given virtual DOS machine (VDM) is to have direct access to the port and, if so, for obtaining ownership of it.

At device initialization, the VDD first opens the PDD and then retrieves a pointer to the data area that will be used to store the current state of the device. The next job for the VDD comes when a DOS session is started - at which time, it hooks the I/O port for the game adapter. Knowing that the device must be written to by the CPU to fire the one-shots before the read sequence can begin, the hook handler for the write operation is the function where device ownership or emulation is resolved.

If the GAME_DIRECT_ACCESS DOS property is ON for that session, this specifies that the device is to be directly accessed by the VDM. In this case, the VDD must first obtain ownership of the device before allowing this operation to proceed. Device ownership is one of the more complex issues handled by this device driver. It first involves getting permission from the PDD, which can only be granted if the device is presently unused either by an OS/2 application or by another VDM through the emulation system. If not available, the user is given the choice to kill the session, wait for the device to become free, or ignore that error and use the device in emulation mode. If the user chooses to wait for the device to become free, the DOS session process will be blocked on an event semaphore to be posted when the device is available.

Once the VDD is granted ownership of the device by the PDD, it then must arbitrate final ownership amongst all VDMs competing for it. A mutual exclusion (MUTEX) semaphore is used as the final decision maker in this process and the VDM that is granted ownership of it is given the same status with game adapter port. When the DOS application that owns the device terminates, this MUTEX is released-allowing any other VDMs waiting for it to compete for ownership once again. If no VDMs are waiting, the ownership of the device is returned to none through a call to the PDD.

When the GAME_DIRECT_ACCESS property for a VDM is in its default state of OFF and the game adapter port is written to, the emulation system is activated. First the VDD informs the PDD that it wishes to become a client of the sampling procedure. If no other clients are already active, this request forces an initial sampling so that valid data is immediately available to the VDD. Next the VDD copies the game-port data from the PDD space to its own VDM instance data area using the pointer retrieved at initialization. This copy of the data will be used when the DOS application reads the game port.

Next, the emulation system uses the other DOS property registered at initialization: GAME_DIGITAL_RESPONSE If set to ON, the joysticks connected are emulated as fixed-resistance style joysticks. In this case, the values for each axis are selected from a field in the PDD data area that corresponds to the range the actual value is presently within. That is, if the current value for an axis is less than the upper limit for the lower range, a given fixed value for the lower range is chosen.

With the given value for each axis in hand, the VDD is ready to emulate the game-port adapter when read by the DOS application. First the count on the number of reads is zeroed as the last operation in the port write handler. When the port read handler is called, the value for each axis is compared against the number of reads by this VDM and if greater, a one for that bit is generated. The state of each position bit mirrors the value returned by the actual hardware when the PDD last sampled it on that iteration. The bits for each of the buttons is retrieved from the PDD data area and used in generating the byte returned. This information is transferred on each read to maintain a "freshness" in the button data.

Adjusting the Device Driver's Settings

This section describes how to adjust the device driver's settings.

DOS-Settings Adjustment

The joystick device-driver installation adds two options to your DOS-Settings notebook. To change these options, simply bring up the settings notebook for a particular DOS-session icon, choose the Session tab, and click on the DOS-Settings button.

GAME_DIRECT_ACCESS
ON
This setting essentially disables the device driver by giving the DOS program direct access to the game port. You should only enable this setting if you are having problems with control of a DOS game and suspect that the joystick device driver may be at fault. This is also useful for testing the difference between having the device driver enabled and disabled for a particular game.
OFF
The default setting. This prevents the DOS program from talking directly to the game port and thus allows the joystick device driver to do its work.
GAME_DIGITAL_RESPONSE
ON
The default setting. When this option is enabled, the device driver reports information back to the DOS program in such a way as to make your joystick look digital even if it is analog.
OFF
Analog joysticks will look like analog joysticks.

Manual Response-Settings Adjustment

The values that the device driver returns to the application using it can be manually adjusted in case of unusual behavior. For example, some games may act as if the joystick is being held constantly toward one direction. If this happens, switch out of the running DOS application (e.g., by using CTRL+ESC) and execute the JOYTUNE.EXE program found in the MPCA subdirectory.

The program displays the values that the joystick device driver currently responds with when in Digital-Response mode. If you choose to change these values, you are prompted first for X-axis values then for Y-axis values. Enter three numbers for each axis representing the values that should be returned to the game or application.

Modifying these values may improve or resolve odd joystick-response problems. For example, if your program acts as if the joystick is being held constantly towards the upper left, then values the joystick device driver is returning for the centered position are too low for each axis. Try raising the middle value for each axis using JOYTUNE. You will probably need to adjust the other values as well. In most cases, you will be able to simply switch back and forth between the game that you are trying to use and the JOYTUNE program until the adjustment is refined.

Limitations

There seems to be a limitation in the number of option settings that can be added to the DOS-Settings notebook. If nothing happens when you click on the DOS-Settings button, then you have most likely run into this limitation. Our only suggestion at this point is that you remove other virtual device drivers that add options to this notebook from your CONFIG.SYS.

Using the Interface

Defining and implementing an API for OS/2 applications is one of the two primary functions of this device driver. After opening the device, applications communicate with the device driver via the OS/2 device IOCtl interface. Functions are provided for getting and setting device parameters, reading the state of the devices connected, and calibrating those devices.

The device driver samples the game-port adapter inside the realtime clock timer handler. This handler is registered with the operating system at device initialization and is called every 32 milliseconds thereafter. It determines whether or not the game-adapter port requires sampling based on client demand and the current sampling rate. Client demand for the sampling procedure only exists if an OS/2 application has the device open or if a VDM is emulating the port.

The joysticks connected are determined and calibrated as part of the device initialization. These parameters can be modified by an OS/2 application or refreshed through a calibration IOCtl request.

In addition to the standard device-read function, functions are also defined for returning the state of the device connected at the next button press or at the next timed read. These functions block the calling process until the given event occurs when the process is run from inside the timer handler.

Usage Examples

Interfacing with the device driver is accomplished rather straightforwardly through IOCtl functions after opening the new GAME$ device.

Note: Versions of the joystick device driver prior to 0.2a only have stub open, read, and close routines enabled. Do your testing with device driver version 0.2a or later.

1.Open the device:

HFILE   hGame;
ULONG   action;
APIRET  rc;

rc = DosOpen( GAMEPDDNAME,                        // "GAME$"
              &hGame,
              &action,
              0,
              FILE_READONLY,
              FILE_OPEN,
              OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE,
              NULL );

if( rc != 0 )
{
  // ERROR opening device: result code in rc
}

2.Get the version number of the device driver:

HFILE   hGame;
ULONG   version;
ULONG   dataLen;
APIRET  rc;

dataLen = sizeof( version );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_GET_VERSION,                // 0x80, 0x01
                  NULL,
                  0,
                  NULL,
                  &version,
                  dataLen,
                  &dataLen );

if( rc != 0 )
{
  // ERROR in IOCtl:  result code in rc
}

3.Get device-driver parameters:

// Below defined in JOYOS2.H
// In use bitmasks originating in 1.0
#define  GAME_USE_BOTH_OLDMASK    0x01   // For backward compatibility with Boolean
#define  GAME_USE_X_NEWMASK       0x02
#define  GAME_USE_Y_NEWMASK       0x04
#define  GAME_USE_X_EITHERMASK    ( GAME_USE_X_NEWMASK | GAME_USE_BOTH_OLDMASK )
#define  GAME_USE_Y_EITHERMASK    ( GAME_USE_Y_NEWMASK | GAME_USE_BOTH_OLDMASK )
#define  GAME_USE_BOTH_NEWMASK    ( GAME_USE_X_NEWMASK | GAME_USE_Y_NEWMASK )

// Only timed sampling implemented in version 1.0
#define  GAME_MODE_TIMED          1                // Timed sampling
#define  GAME_MODE_REQUEST        2                // Request-driven sampling

// Only raw implemented in version 1.0
#define  GAME_DATA_FORMAT_RAW     1                // [l,c,r]
#define  GAME_DATA_FORMAT_SIGNED  2                // [-l,0,+r]
#define  GAME_DATA_FORMAT_BINARY  3                // {-1,0,+1}
#define  GAME_DATA_FORMAT_SCALED  4                // [-10,+10]

// Parameters defining the operation of the device driver
typedef struct
              {
                USHORT  useA;                      // New bitmasks:  see above
                USHORT  useB;
                USHORT  mode;                      // See constructs above
                USHORT  format;                    // See constructs above
                USHORT  sampDiv;                   // Sample frequency = 32 / n
                USHORT  scale;                     // Scaling factor
                USHORT  res1;                      // Must be 0
                USHORT  res2;                      // Must be 0
              }
              GAME_PARM_STRUCT;

//----------------------------------------------------------
HFILE             hGame;
GAME_PARM_STRUCT  gameParms;
ULONG             dataLen;
APIRET            rc;

dataLen = sizeof( gameParms );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_GET_PARMS,                 // 0x80, 0x02
                  NULL,
                  0,
                  NULL,
                  &gameParms,
                  dataLen,
                  &dataLen);

if( rc != 0 )
{
  // ERROR in IOCtl: result code in rc
}

4.Set device-driver parameters:

// See section above from JOYOS2.H
HFILE             hGame;
GAME_PARM_STRUCT  gameParms;
ULONG             parmLen;
APIRET            rc;

parmLen = sizeof( gameParms );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_SET_PARMS,                 // 0x80, 0x03
                  &gameParms,
                  parmLen,
                  &parmLen,
                  NULL,
                  0,
                  NULL );

if( rc != 0 )
{
  // ERROR in IOCtl: result code in rc
}

5.Get calibration values for joystick(s):

// Below defined in JOYOS2.H
// 1-D position struct used for each axis
typedef SHORT  GAME_POS;                // Some data formats require signed values

// Struct to be used for calibration and digital response on each axis
typedef struct
              {
                GAME_POS  lower;
                GAME_POS  centre;
                GAME_POS  upper;
              }
              GAME_3POS_STRUCT;

// Calibration values for each axis:
//     upper limit on value to be considered in lower range
//     centre value
//     lower limit on value to be considered in upper range
typedef struct
              {
                GAME_3POS_STRUCT  Ax;
                GAME_3POS_STRUCT  Ay;
                GAME_3POS_STRUCT  Bx;
                GAME_3POS_STRUCT  By;
              }
              GAME_CALIB_STRUCT;

//----------------------------------------------------------
HFILE              hGame;
GAME_CALIB_STRUCT  gameCalib;
ULONG              dataLen;
APIRET             rc;

dataLen = sizeof( gameCalib );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_GET_CALIB,                 // 0x80, 0x04
                  NULL,
                  0,
                  NULL,
                  &gameCalib,
                  dataLen,
                  &dataLen);

if( rc != 0 )
{
  // ERROR in IOCtl:  result code in rc
}

6.Calibrate joystick(s)-set calibration values:

// See section above from JOYOS2.H

// For each stick:
//    tell user to centre joystick and press button
//    call get status with wait
//    tell user to move to upper left and press button
//    call get status with wait
//    tell user to move to lower right and press button
//    call get status with wait
// Then call set calibration IOCTL with these values

HFILE              hGame;
GAME_CALIB_STRUCT  gameCalib;
ULONG              parmLen;
APIRET             rc;

parmLen = sizeof( gameCalib );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_SET_CALIB,                     // 0x80, 0x05
                  &gameCalib,
                  parmLen,
                  &parmLen,
                  NULL,
                  0,
                  NULL );

if( rc != 0 )
{
  // ERROR in IOCtl:  result code in rc
}

7.Get VDM digital response values for joystick(s):

// Below defined in JOYOS2.H

// 1-D position struct used for each axis
typedef SHORT  GAME_POS;                 // Some data formats require signed values

// Struct to be used for calibration and digital response on each axis
typedef struct
              {
                GAME_POS  lower;
                GAME_POS  centre;
                GAME_POS  upper;
              }
              GAME_3POS_STRUCT;

// Struct defining the digital response values for all axes 
typedef   struct 
                { 
                  GAME_3POS_STRUCT    Ax ; 
                  GAME_3POS_STRUCT    Ay ; 
                  GAME_3POS_STRUCT    Bx ; 
                  GAME_3POS_STRUCT    By ; 
                } 
                GAME_DIGSET_STRUCT ;

//----------------------------------------------------------
HFILE               hGame;
GAME_DIGSET_STRUCT  gameDigset;
ULONG               dataLen;
APIRET              rc;

dataLen = sizeof( gameDigset );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_GET_DIGSET,                // 0x80, 0x06
                  NULL,
                  0,
                  NULL,
                  &gameDigset,
                  dataLen,
                  &dataLen );

if( rc != 0 )
{
  // ERROR in IOCtl:  result code in rc
}

8.Set VDM digital response values for joystick(s):

// See section above from JOYOS2.H

HFILE               hGame;
GAME_DIGSET_STRUCT  gameDigset;
ULONG               parmLen;
APIRET              rc;

parmLen = sizeof( gameDigset );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_SET_DIGSET,                // 0x80, 0x07
                  &gameDigset,
                  parmLen,
                  &parmLen,
                  NULL,
                  0,
                  NULL );

if( rc != 0 )
{
  // ERROR in IOCtl:  result code in rc
}

9.Get the status of the joystick(s):

// Below defined in JOYOS2.H
// 1-D position struct used for each axis

typedef SHORT  GAME_POS;                   // Some data formats require signed values

// Simple 2-D position for each joystick

typedef struct
              {
                GAME_POS  x;
                GAME_POS  y;
              }
              GAME_2DPOS_STRUCT;

// Struct defining the instantaneous state of both sticks and all buttons

typedef struct
              {
                GAME_2DPOS_STRUCT  A;
                GAME_2DPOS_STRUCT  B;
                USHORT             butMask;
              }
              GAME_DATA_STRUCT;

// Status struct returned to OS/2 applications:
// Current data for all sticks as well as button counts since last read

typedef struct
              {
                GAME_DATA_STRUCT  curdata;
                USHORT            b1cnt;
                USHORT            b2cnt;
                USHORT            b3cnt;
                USHORT            b4cnt;
              }
              GAME_STATUS_STRUCT;

//----------------------------------------------------------

HFILE               hGame;
GAME_STATUS_STRUCT  gameStatus;
ULONG               dataLen;
APIRET              rc;

dataLen = sizeof( gameStatus );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_GET_STATUS,                // 0x80, 0x10
                  NULL,
                  0,
                  NULL,
                  &gameStatus,
                  dataLen,
                  &dataLen );

if( rc != 0 )
{
  // ERROR in IOCtl:  result code in rc
}

10.Get the status of the joystick(s) at next button press:

// See section above from JOYOS2.H
// NOTE: this call will block

HFILE               hGame;
GAME_STATUS_STRUCT  gameStatus;
ULONG               dataLen;
APIRET              rc;

dataLen = sizeof( gameStatus );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_GET_STATUS_BUTWAIT,        // 0x80, 0x11
                  NULL,
                  0,
                  NULL,
                  &gameStatus,
                  dataLen,
                  &dataLen );

if( rc != 0 )
{
  // ERROR in IOCtl:  result code in rc
}

11.Get the status of the joystick(s) at next sample (depends on mode):

// See section above from JOYOS2.H
// NOTE: this call will block

HFILE               hGame;
GAME_STATUS_STRUCT  gameStatus;
ULONG               dataLen;
APIRET              rc;

dataLen = sizeof( gameStatus );
rc = DosDevIOCtl( hGame,
                  IOCTL_CAT_USER,
                  GAME_GET_STATUS_SAMPWAIT,       // 0x80, 0x12
                  NULL,
                  0,
                  NULL,
                  &gameStatus,
                  dataLen,
                  &dataLen );

if( rc != 0 )
{
  // ERROR in IOCtl:  result code in rc
}

Close the device:

HFILE   hGame;
APIRET  rc;

rc = DosClose( hGame );

if( rc != 0 )
{
  // ERROR closing device:  result code in rc
}

Keyboard Device Driver

The keyboard physical device driver is separated into two separate drivers: the device-independent driver (KBDBASE.SYS) and the device-dependent driver (IBMKBD.SYS).

The device-independent driver (DI) is OS/2-specific. It handles the monitors, screen groups, code paging, translation, and special needs processing. It also communicates hardware changes with the device-dependent driver through an inter-device-driver communication (IDC) interface.

The device-dependent (DD) driver handles the hardware interrupts and keyboard hardware commands. It also passes scan codes and notifications of a hot plug to the device-independent driver IDC. These drivers function on ISA/EISA or Micro Channel machines.

Overview

The physical keyboard device-dependent driver receives the make-and-break keystroke scan codes along with special keyboard hardware codes. The scan codes are stored until a completed key stroke is received. A key packet is then passed to the device-independent driver which performs one or more of the following operations: (see the following figure):

  • Translates the scan code to an ASCII character
  • Recognizes the key as a special key and signals the appropriate routine for processing
  • Passes the translated scan code's character data record to the monitor dispatcher for further custom processing by monitors
  • Places the translated scan code's character record into the appropriate session's keyboard input buffer

In addition, the physical keyboard device driver supports code page switching. The following is a result of this support:

  • Each handle can use one of two system-wide code pages. One code page is current and the other code page can be switched to. Each handle can also use the PC US 437 code page.
  • The code pages used are defined in CONFIG.SYS with the CODEPAGE and DEVINFO commands.
  • Using the KEYB command, the language layout of the keyboard can be changed.
  • Code pages specified with the CODEPAGE command in CONFIG.SYS are for one language only. However, it is possible that code page support for different languages can result if default code pages are not accepted during execution of the KEYB command. This can occur when attempting to load translation tables in a non-supported code page for that language.
  • The user can control, by the KbdSetCp subsystem function or the CHCP command, which of the two code pages is used in the translation of scan codes.
  • Two subsystem functions support code page switching:
    • KbdSetCp - Set to an installed code page, which is loaded if necessary.
    • KbdGetCp - Get the current in-use code page.
  • KbdSetCustXt adds a custom code page option.
  • KbdXlate translates a scan code.
  • KbdSetCp, KbdGetCp, and KbdXlate can be replaced in the subsystem by the use of the KbdRegister function.
  • Code page number, Language ID of the translation table, Subcountry ID, language default table indicator, and keyboard type indicator can all be found in the Translation table header of each country's keyboard layout. For more information, refer to "Set Code Page" (Function 50h), which can be found in the OS/2 Physical Device Driver Reference.

Ioddr-02.gif

The physical keyboard device driver is the interface between the physical keyboard and applications as shown in the following figure.

(1) is part of the physical device driver interrupt handler.

(2) is part of the physical device driver strategy routine.

(3) is part of the base subsystem/router.

Keyboard Initialization

The device-independent driver (KBDBASE.SYS) loads prior to CONFIG.SYS, and the device-dependent driver (IBMKBD.SYS) is loaded as a BASEDEV= in CONFIG. SYS. IBMKBD.SYS uses a DEVHELP_ATTACHDD call to get the address of KBDBASE.SYS. The device-dependent driver then registers with the device-independent driver so that the appropriate inter-device-driver communication (IDC) can occur.

Keyboard Run-Time Operation

When a session is started, a default logical keyboard already exists. This keyboard is identified to the subsystem by a zero handle. Any program can share the keyboard by using Handle 0. If multiple programs use the default keyboard they must coordinate their access to it. The default keyboard logically terminates when the session terminates.

If a program wants a logical keyboard separate from the default logical keyboard, it issues a KbdOpen. This open creates a new logical keyboard, but does not make the physical-to-logical bond. As a result of an open, a handle unique within a process is returned to the caller, which is later used to identify the logical keyboard. The handle ownership is tied to the process; handles are not inherited. Use of KbdOpen does not prohibit the process from using the default keyboard.

To make the physical-to-logical bond, the process issues the KbdGetFocus using the handle which identifies the logical keyboard. When the bond is made, the logical keyboard can receive keystrokes. Note that type-ahead keystrokes are not possible before the bond is made. The keyboard API can be used only when the bond is made, or with Handle 0 when no other handle has the bond.

The bond represents a foreground keyboard (one physical-to-logical bond exists for each session). This is the default or a created logical keyboard. To break the bond, issue a KbdFreeFocus call. If other threads have a KbdGetFocus outstanding, the thread having the highest priority gets the bond. If there are no KbdGetFocus calls outstanding, the physical keyboard reverts to the default keyboard.

A logical keyboard is destroyed with a KbdClose. The close frees the focus, flushes the buffer, and deallocates the KCB and related memory. The close is done by the process kill mechanism, if it is not performed by the program.

Keystroke Monitors

Some applications need to view the raw keystrokes as they arrive from the keyboard at interrupt time. These applications might consume, modify, or replace keystrokes. This is made possible by the keystroke monitor function.

An application operating with the OS/2 system cannot register a keyboard monitor for a Presentation Manager session. When DosMonReg is issued with keyboard devices, the INDEX parameter indicates which OS/2 session, requested by the caller, is to register the monitor. The INDEX parameter indicates an OS/2 session from 0-15. (For more information on DevHlp_ DosGetInfoSeg, refer to the OS/2 Physical Device Driver Reference.)

An INDEX parameter value of -1 indicates that the session of the calling thread is being requested. If the caller requests either the Presentation Manager session or a DOS session, a MONITORS_NOT_SUPPORTED error is returned. For both of these sessions, the error return code is generated, regardless of the caller's specific usage of the INDEX parameter (explicit/ implicit).

The size of the physical keyboard device driver's monitor chain buffer is 16 bytes. This is the value to be used in calculating the sizes of the input/output buffers required for the DosMonReg function. The physical keyboard device driver supports device monitors. This physical device driver passes its information to the monitors in packets.

The following figure describes the content and format of keystroke monitor data packets.

 /------------------------\
 | MonFlagWord:      Word |
 |------------------------|
 | C |XlatedChar:    Byte |
 | h |--------------------|
 | a |XlatedScan:    Byte |
 | r |--------------------|
 | D |DBCS Status:   Byte |
 | a |--------------------|
 | t |DBCS Shift:    Byte |
 | a |--------------------|
 |   |Shift State:   Word |
 | R |--------------------|
 | e |Milliseconds: DWord |
 | c |--------------------|
 | o |                    |
 | r |                    |
 | d |                    |
 |------------------------|
 | KbdDDFlagWord     Word |
 \------------------------/
MonFlagWord (Lower Byte)

Monitor Dispatcher Flags.

Bits 7-3 RESERVED. Must be passed untouched for packets that are passed on. Must be set to 0 on packets that are inserted by a monitor.

Bit 2 FLUSH. This is a flush packet. No other information in the packet has meaning. Monitor must flush its internal buffers and pass the packet quickly.

Bit 1 CLOSE. Not used by keystroke monitors.

Bit 0 OPEN. Not used by keystroke monitors.

MonFlagWord (Upper Byte)

Original Scan code, as read from the hardware. If 0, this packet was inserted for other reasons. See #KbdDDFlagWord. Monitors pass this field untouched or put 0 here if they insert a packet.

CharData Record

For information regarding the Read Character Data Records IOCtl, refer to Function 74h, Category 04h in the OS/2 Physical Device Driver Reference.

KbdDDFlagWord

Has the following bits:

Bits 15-14 Available. These bits are available for communication between monitors; they are not used by the physical device driver. The monitor applications coordinate the use of these flags.

Bits 13-10 RESERVED=0. Monitors must pass these flags as is. They must set these flags to 0 in packets they create.

Bit 9 ACCENTED. This key is translated using the previous key passed, which is an accent key. Where an accent key is pressed, and the following key does not use the accent, a packet containing the accent character itself is first passed with this bit set. The scan code field of MonFlagWord (see above) would be 0, indicating a non-key generated record. A valid packet containing that following keystroke is then passed without this bit set.

Bit 8 MULTIMAKE. The translation process sees this scan code as a typematic repeat of a toggle key or a shift key. Because toggle and shift keys only change state on the first make after each key-break, no state information is changed. For example, the NumLock toggle bit in the shift status WORD is not changed, even though this can be the NumLock key. If this key is a valid character, it does not go into the Keyboard Input Buffer (KIB) once this bit is set.

Bit 7 SECONDARY. The scan code prior to the one in this packet was the Secondary Key Prefix (see below).

Bit 6 KEY BREAK. This record is generated by the release (the break) of the key involved.

Bits 5-0 KEY TYPE. This numeric field flags the physical device driver and reports that this is a key that requires action. The number in this field is filled in during the translation of the scan code. The value allows the driver to act on keystrokes without regard for what scan codes the keyboard uses or character codes that the current translation process may be using. The following values are currently defined:

  • Value for keys that are always placed in the KIB. Zero = no special action, always place in KIB.
  • Values acted on prior to passing packet to monitors. Except for the final keystroke of the DUMP key sequences, all of these values are passed on to the monitors. They are not placed in the KIB. The XlatedChar and XlatedScan fields are undefined for these values:

01h ACK. This scan code is a keyboard acknowledge. Personal Computer IBM* AT* attached keyboards set this value on an FAh scan code.

02h SECONDARY KEY PREFIX. This scan code is a prefix generated by the Enhanced Keyboard. It indicates that the next scan code coming is one of the secondary keys that exists on that keyboard. Usually set on an E0h scan code or an E1h scan code.

03h KBD OVERRUN. This scan code is an overrun indication from the keyboard. On an IBM Personal Computer AT-attached keyboard, this value would be set on an FFh scan code.

04h RESEND. This scan code is a resend request from the keyboard. On an IBM Personal Computer AT-attached keyboard, this value would be set on an FEh scan code.

05h REBOOT KEY. This scan code completes the multi-key restart sequence. On an IBM Personal Computer AT attached-keyboard, this value would be used when the Ctrl+Alt+Delete sequence is used.

06h DUMP KEY. This scan code completes the multi-key Stand Alone Dump request sequence. On an IBM Personal Computer AT-attached keyboard, this value would be used on completion of the second consecutive press of Ctrl+Alt+NumLock or Ctrl+Alt+F10 without other keystrokes between the two presses.

07h-0Ah See entries below.

0Bh INVALID ACCENT COMBINATION. This scan code follows an accent scan code but the combination is not valid, and neither key is put in the KIB.

Note:This is set if the Canadian-French code pages are in use.

0Ch SYSTEM-DEFINED HOT KEYS.

0D-0Fh RESERVED. Treated as undefined. See entry 3Fh.

  • Values acted on after passing packet to monitors. Except where noted, these values are placed in the KIB when the physical device driver is in binary mode; they are not placed in the KIB when the physical device driver is in ASCII mode. (Also listed are those that never get placed in the KIB.)

07h SHIFT KEY. This scan code translates as a shift key and affects the shift status fields of the CharData record, but does not generate a defined character. It is not placed in the KIB. The XlatedChar field is undefined. The scan codefield is 0.

08h PAUSE KEY. This scan code is translated as the key sequence meaning pause. On an IBM Personal Computer AT-attached keyboard, this value is used when the Ctrl+NumLock sequence is used. The key itself is not placed in the KIB.

09h PSEUDO-PAUSE KEY. This scan code is translated into the value that is treated as the Pause key when the physical device driver is in ASCII mode. On most keyboards, this would be when the Ctrl+S combination is used. The key itself is not placed in the KIB.

0Ah WAKE-UP KEY. This scan code follows a Pause key or Pseudo-Pause key, which causes the Pause state to end. The key itself is not placed in the KIB.

10h ACCENT KEY. This scan code is translated and used as a key to alter the translation of the next key to come in.

The packet containing this value is passed when the accent key is pressed, but it is not put into the KIB, unless the Accented bit is ON. The next key determines this decision. If the next key is one that can be accented, then it is passed by itself with the Accented bit ON. If that next key cannot be accented by this accent, then two packets are passed. The first contains the character to print for the accent itself. It has the Accent key value and the Accented flag (which allows the packet to be put in the KIB). The second packet contains a regular translation of that following key.

Note
The two packets get passed for every language except Canadian-French. See entry 0Bh.

11h BREAK KEY. This scan code is translated as the key sequence meaning break. On the IBM Personal Computer AT-attached keyboard, this value is used where the Ctrl+Break sequence is used.

12h PSEUDO-BREAK KEY. This scan code is translated into the value that is treated as the Break key when the physical device driver is in ASCII mode. On most keyboards, this would be when the Ctrl+C combination is used. Notice that the event generated by this key is separate from the one generated by the Break key when in the binary mode.

13h PRINT SCREEN KEY. This scan code is translated as the key sequence meaning Print Screen. On an IBM Personal Computer AT-attached keyboard, this value is used where the Shift+PrtSc sequence is used.

14h PRINT ECHO KEY. This scan code is translated as the key sequence meaning Print Echo. This value is used where the Ctrl+PrtSc sequence is used.

15h PSEUDO-PRINT ECHO KEY. This scan code is translated into the value that is treated as the Print Echo key when the physical device driver is in ASCII mode. On most keyboards, this would show as the Ctrl+P combination.

16h PRINT-FLUSH KEY. This scan code is translated into the key sequence Print-Flush. This value is used where the Ctrl+Alt+PrtSc sequence is used.

17h-2Fh RESERVED=0. Treated as undefined. See entry 3Fh.

  • Values for packets not generated by a keystroke:

30h-37h RESERVED.

38h-3Eh RESERVED. Treated as undefined. See entry 3Fh.

  • Value for keys the translation process does not recognize:

3Fh UNDEFINED. This scan code, or its combination with the current shift state, is not recognized in the translation process.

Special Key Processing

The operating system examines each incoming keyboard character to determine if it should cause an asynchronous signal to be sent to some process (for example, Ctrl+C). The physical keyboard device driver responds to the keystrokes as shown in the following table:

Keys Mode Event Signalled or Signal Handler Called Value Placed in KIB
Ctrl+C Binary Nothing 03h
Ctrl+C ASCII SIGINTR Nothing
Ctrl+S Binary Nothing 13h
Ctrl+S ASCII Event_CtrlScrLk Nothing
Ctrl+P Binary Nothing 10h
Ctrl+P ASCII Event_CtrlPrtSc Nothing
Ctrl+Break Binary SIGBREAK 00:00h
Ctrl+Break ASCII SIGINTR Nothing
Ctrl+NumLock Binary Event_CtrlScrLk Nothing
Ctrl+NumLock ASCII Event_CtrlScrLk Nothing
Ctrl+PrtSc Binary Event_CtrlPrtSc Nothing
Ctrl+PrtSc ASCII Event_CtrlPrtSc Nothing
PrtSc Binary Event_ShftPrtSc Nothing
PrtSc ASCII Event_ShftPrtSc Nothing
  1. The value xxh represents the translated ASCII field in the character data record.
  2. The value xx:yyh represents the translated ASCII (that is, translated scan code fields of the character data record).
  3. Ctrl+NumLock has no effect on an IBM Enhanced keyboard; the Pause key provides this function.

Other special keys are shown in the following table:

Key Meaning
Hot Key Change sessions
Ctrl+Alt+Del System IPL (restart)
Ctrl+Alt+NumLock
Ctrl+Alt+F10
Pressed twice means system dump
PrtScr Print the current display screen. (Print Screen on an IBM Enhanced keyboard)

In addition to passing individual characters, the physical device driver must specifically recognize the character (or character sequence, or other special action) that indicates the special signal, or hot key, to the Session Manager. When this event is recognized, the SendEvent Device Helper service is started.

The "System Hot Key" is defined by IOCtl Category 04h, Function 56h in the OS/2 Physical Device Driver Reference.

The Device-Dependent Driver

The device-dependent driver uses a state machine to control the hardware interrupts. The following is a diagram of the state machine:

Ioddr-03.gif

NOCMDIPG (No Command In Progress (*))
This is the base state. It accepts scan codes as keystrokes and it passes them in a key packet to the DI driver. It also checks for an override (FFh) scan code. This is usually the start of a hot plug sequence; therefore, move to the [HOTPLGPG] state.
RCVDE0SC (Received E0h Scan Code (*))
If [NOCMDIPG] receives an E0h scan code, it jumps to this state to await the remaining keystroke scan byte. These two bytes are then passed to the DI driver in a key packet. Upon completion, return to the state [NOCMDIPG].
HOTPLGPG (Notify Hot-Plug in Progress)
If [NOCMDIPG] receives FFh, it jumps to this state and waits for the next scan code. If the next scan code is an AAh, it starts the hot plug sequence. If not, then it beeps the keyboard and returns to [NOCMDIPG] state to pass the scan code to the DI driver.
SENTLEDC (Sent LED Command (!))
The change LEDs command has been sent to the keyboard and is now awaiting an ACK from the keyboard. When one is received, send the new LED data byte to the keyboard and go to [SENTLEDD] to wait for an ACK.
SENTLEDD (Sent LED Data (!))
The LED byte is sent to the keyboard and is awaiting an ACK. When one is received, go to [NOCMDIPG] and wait for the next scan code.
SENTTYPC (Sent Typematic Command (!))
The change type rate/delay command has been sent to the keyboard, and is now awaiting an ACK from the keyboard. When one is received, send the new type rate/delay data byte to the keyboard and go to [SENTTYPD] to wait for an ACK.
SENTTYPD (Sent Typematic Rate (!))
The new type rate/delay byte has been sent to the keyboard and is awaiting an ACK. When one is received, go to [NOCMDIPG] and wait for the next scan code.
SENTIDCM (Sent Read ID Command)
The Read ID command has been sent to the keyboard, and is now awaiting an ACK from the keyboard. When one is received, start a timer and go to [WAITIDB1] to await the first ID byte (go to [GTKBDCMD] upon timeout).
WAITIDB1 (Wait for First ID Byte)
The Read ID command has been sent and ACK has been received. The device driver is waiting for the first ID byte. When one is received, go to [WAITIDB2] to await the second ID byte.
WAITIDB2 (Wait for Second ID Byte)
The first ID byte has been received, and the driver is now waiting for the second ID byte. When the byte has been received, request the controller command byte and go to [GTKBDCMD].
GTKBDCMD (Get Controller Command Byte(!))
The device driver waits for the command byte from the keyboard controller. If the Scan-Code Set is set to 1 , then the driver makes the request to change the Scan-Code Set. If the Scan-Code Set is set to 2, then the driver goes to [SENTSCSC].
SENTSCSC (Sent Out Scan-Code Set Change(!))
When the device driver receives an ACK, it sends out the correct Scan-Code Set to the keyboard and then goes to [SENTSCSD] to wait for an ACK.
SENTSCSD (Sent Out Correct Scan-Code Set(!))
The device driver is waiting for an ACK from the keyboard to acknowledge that it has completed the request. To ensure that the type rate/delay is correct, send off the change type rate/delay command and go to [SENTTYPC].

Note:The state sequence from SENTIDCM to SENTSCSD should only occur during init and after every Hot Plug as it is part of the setup routine.

(*) This state generates a keystroke packet.
(!) This state starts a timer that resets the state machine and flags an error, if time runs out.

Building the Physical Keyboard Device Driver

To build the physical keyboard device driver, you must do the following:

  1. Ensure that the TOOLS directory in the IBM Device Driver Source Kit for OS/2 is part of the current path.
  2. Create NMAKE using the following Make files provided in the device driver:
    • SRC\DEV\KBD\KBDBASE\MAKEFILE
    • SRC\DEV\KBD\IBMKBD\MAKEFILE
    For example:CD:\DDK\SRC\DEV\KBD\KBDBASE\NMAKE

Keyboard Inter-Device-Driver Communication Interfaces

This chapter describes the inter-device-driver communication (IDC) interfaces for the IBM keyboard device drivers provided by the OS/2 operating system - both device-independent to device-dependent and device-dependent to device-independent.

The division of the keyboard device driver has allowed new functions to be included that were not previously available. These functions are found in the following IDC functions.

Note: If an independent-device driver changes the state of one of the drivers by making an IDC call, it is not always reflected in the other driver. For example, if a driver changes the state of the LEDs in the device-dependent (DD) driver, the change will not be reflected in the device-independent (DI) driver and the device-independent driver might change the LEDs to another state at any time.

Device-Independent Supplied IDC's

The following are the device-independent IDC functions.

Note: For compatibility purposes, the data segment should not be changed by the dependent-device driver. The device-independent driver will load up the correct data segment required.

The following are the device-independent IDC functions that are currently available.

00 Open
01 Close
02 Process Keystroke
03 Process Reinit
04 Pen Functions

Open

This function registers the device-dependent driver with the device-independent driver. The independent-device driver will use this registry to notify device-dependent drivers of updates (such as LED, type rate/delay, and so on). If a driver does not want to be notified of updates, then it sends in a 0000h Code Segment value.

Input:

 Func: Open_IDC code (0000h)
 Var1: Code Offset of DD IDC routine
 Var2: Data Segment of DD Driver
 Var3: Code Segment of DD IDC routine

Output:

AX = Handle (0FFFFh=error, could not open)

Close

This function deletes the driver from the registry.

Input:

 Func: Close_IDC code (0001h)
 Var1: NULL
 Var2: Data Segment of DD Driver
 Var3: Handle from Open Call

Output:

If the handle or data segment are incorrect, AX=0FFFFh is returned.

Process Keystroke

This function is called by the device-dependent driver when it has a complete keystroke to report to the device-independent driver. The buffer may be reused immediately after this call.

Input:

 Func: Process_Keystroke code (0002h)
 Var1: Data Offset of keystroke buffer
 Var2: Data Segment of keystroke buffer and DD Driver
 Var3: Handle from Open Call

Output:

If the handle or data segment are incorrect, AX=0FFFFh is returned.

Process Reinit

This IDC informs the device-independent driver that a reinit/hot-plug condition has occurred. The device-independent driver now checks the attached keyboard type (and all that a keyboard change entails), and resends the appropriate LED state to the device-dependent driver.

Input:

 Func: Process_Reinit Code (0003h)
 Var1: NULL
 Var2: Data Segment of DD Driver
 Var3: Handle from Open call

Output:

If the handle or data segment are incorrect, AX=0FFFFh is returned.

Pen Functions

This function allows the keyboard device driver to create system keyboard events on behalf of the Pen for OS/2 subsystem.

Input:

 Func: Pen_Functions code (04XXh)
 Var1: Index to SINFO data structure
 Var2: Data Segment
 Var3: Internal Pen function variable

Output:

Carry set if error occurs.

Device-Dependent Supplied IDC's

The following are the device-dependent IDC functions.

00 Open
01 Close
02 Query Capabilities
03 Query Typematic & Delay
04 Query LEDs
05 Query ID codes
06 Query Disabled
07 Disable Keyboard
08 Enable Keyboard
09 Reset Hardware
0A Set Typematic & Delay
0B Set LEDs
0E Send Generic Command
0F Query Keyboard Ready
10 Flush Partial Keys
12 Save State
13 Restore State
87 Disable Keyboard (Interrupt Time)
88 Enable Keyboard (Interrupt Time)
89 Reset Hardware (Interrupt Time)
8A Set Typematic & Delay (Interrupt Time)
8B Set LEDs (Interrupt Time)

Open

The open function is not a prerequisite for implementing other functions within this device driver.

Input:

     Func: Open Device Driver code (0000h)
     Var1: NULL
     Var2: NULL

Output:

     AX = 0:  Keyboard is ready for any command.
     0FFFFh:  Keyboard is busy.  OK to query, but thread will be
                    blocked or unexecuted (if interrupt time) if an
                    attempt is made to send a command to the keyboard
                    hardware.

Close

This function is null and is used for compatibility purposes only.

Input:

     Func: Close Device Driver code (0001h)
     Var1: NULL
     Var2: NULL

Output:

None.

Query Capabilities

This request is issued by the device-independent driver to find out what capabilities the attached driver has.

Input:

     Func: Query_Capabilities code (0002h)
     Var1: CapStruc buffer address offset
     Var2: CapStruc buffer address segment

Output:

     AX = 0 (and structure is filled in)

struct CapStruc {
     USHORT  DevFlags;
     USHORT  KeyCount;
     USHORT  MaxTypa;
     USHORT  MinTypa;
     USHORT  MaxDelay;
     USHORT  MinDelay;
}

     Device Flags:  0000 0000 0ccc 00ba
                                 │   ││
                                 │   │└─ True Keyboard
                                 │   └── Hotplug Detection
                                 └───── Number of LEDs (0-7)
     Device Flags:  0000 0000 0ccc 00ba
                                 │   ││
                                 │   │└─ True Keyboard
                                 │   └── Hotplug Detection
                                 └───── Number of LEDs (0-7)

Query Typematic Rate and Delay

This function queries the current type rate and delay of the keyboard hardware.

Input:

     Func: Query_Typematic code (0003h)
     Var1: NULL
     Var2: NULL

Output:

     AX = Bits 15-7 -> Reserved
          Bits 6-5  -> Delay value in milliseconds
                        (values in binary)
                        00 - 250
                        01 - 500
                        10 - 750
                        11 - 1000
          Bits 4-0  -> Rate value in characters per second
                          (values in binary)
                          00000 - 30.0         10000 - 7.5
                          00001 - 26.7         10001 - 6.7
                          00010 - 24.0         10010 - 6.0
                          00011 - 21.8         10011 - 5.5
                          00100 - 20.0         10100 - 5.0
                          00101 - 18.5         10101 - 4.6
                          00110 - 17.1         10110 - 4.3
                          00111 - 16.0         10111 - 4.0
                          01000 - 15.0         11000 - 3.7
                          01001 - 13.3         11001 - 3.3
                          01010 - 12.0         11010 - 3.0
                          01011 - 10.9         11011 - 2.7
                          01100 - 10.0         11100 - 2.5
                          01101 - 9.2          11101 - 2.3
                          01110 - 8.6          11110 - 2.1
                          01111 - 8.0          11111 - 2.0

Query LEDs

This function queries the current LED state of the keyboard hardware.

Input:

     Func: Query_LEDs code (0004h)
     Var1: NULL
     Var2: NULL

Output:

     AX = Bits 15 to  3 - Reserved
          Bit 2         - CapsLock
          Bit 1         - NumLock
          Bit 0         - ScrollLock

Query ID Codes

This function queries the current ID of the keyboard hardware.

Input:

     Func: Query_ID (0005h)
     Var1: IDstruc buffer address offset
     Var2: IDstruc buffer address segment

Output:

     AX = key count (88/101/122/etc), 0=undetermined (IDstruc buffer is
filled in, also).

struc IDstruc {
     USHORT idlen;          /* length of returned ID code        */
     UCHAR idbytes[8];      /* buffer for ID bytes               */
 }

Query Disabled

This function queries if the keyboard hardware is disabled.

Input:

     Func: Query_Disabled (0006h)
     Var1: NULL
     Var2: NULL

Output:

     AX = Disabled Flag (0 enabled, 0FFFFh disabled)

Disable Keyboard

This function disables the keyboard and does not allow keystrokes to be accepted.

Input:

     Func: Disable_Keyboard (0007h)+[Interrupt Time +80h]

     Var1: NULL
     Var2: NULL

Output:

     AX = Disable Function (0 was already disabled, 1 disabled)

Enable Keyboard

This function enables the keyboard and allows keystrokes to be accepted.

Input:

     Func: Enable_Keyboard (0008h)+[Interrupt Time +80h]
     Var1: NULL
     Var2: NULL

Output:

     AX=0FFFFh if error occurs.

Reset Hardware

This function is issued when the device-independent portion wants to place the physical hardware into a known, reset state. This call should reset the physical keyboard and the attaching device (Kbd section of 8042).

Input:

     Func: Reset_Hardware (0009h)+[Interrupt Time +80h]
     Var1: NULL
     Var2: NULL

Output:

     AX=0FFFFh if error occurs.

Set Typematic Rate and Delay

This function sets the keyboard hardware to a specified type rate and delay.

Input:

     Func: Set_Typematic code (000Ah)+[Interrupt Time +80h]
     Var1: Parameter word
     Var2: NULL

Parameter word:
     AX = Bits 15-7 -> Reserved (must be set to zero)
          Bits 6-5  -> Delay value in milliseconds
                        (values in binary)
                        00 - 250
                        01 - 500
                        10 - 750
                        11 - 1000
          Bits 4-0  -> Rate value in characters per second
                          (values in binary)
                          00000 - 30.0         10000 - 7.5
                          00001 - 26.7         10001 - 6.7
                          00010 - 24.0         10010 - 6.0
                          00011 - 21.8         10011 - 5.5
                          00100 - 20.0         10100 - 5.0
                          00101 - 18.5         10101 - 4.6
                          00110 - 17.1         10110 - 4.3
                          00111 - 16.0         10111 - 4.0
                          01000 - 15.0         11000 - 3.7
                          01001 - 13.3         11001 - 3.3
                          01010 - 12.0         11010 - 3.0
                          01011 - 10.9         11011 - 2.7
                          01100 - 10.0         11100 - 2.5
                          01101 - 9.2          11101 - 2.3
                          01110 - 8.6          11110 - 2.1
                          01111 - 8.0          11111 - 2.0

Output:

     AX=0FFFFh if error occurs.

Set LEDs

This function sets the state of the keyboard LEDs. Bits 0-2 must set the LEDs labeled below. The other bits of BL are reserved for future support of keyboards with greater LED counts.

Input:

     Func: Set_LEDs code (000Bh)+[Interrupt Time +80h]
     Var1: Parameter word
     Var2: NULL

Parameter word:
          bit 15 - bit  3 - Reserved
                   bit  2 - CapsLock
                   bit  1 - NumLock
                   bit  0 - ScrollLock

Output:

     AX=0FFFFh if error occurs.

Send Generic Command

This function will send any command to the keyboard.

Input:

     Func: Send_Generic code (000Eh)
     Var1: CmdStruc buffer address offset
     Var2: CmdStruc buffer address segment

struc CmdStruc {
     USHORT wait;             /* 1 wait for ACK between bytes, 0 no wait   */
     USHORT strlen;           /* length of following string                */
     UCHAR bytes[strlen];     /* string of bytes to send to keyboard       */
}

Output:

     AX=0FFFFh if error occurs.

Query Keyboard Ready

This function determines if the keyboard is currently executing a command or ready for input.

Input:

     Func: Query_Kbd_Rdy code (000Fh)
     Var1: NULL
     Var2: NULL

Output:

     AX = Ready Flag (0=No, 0FFFFh=Yes)

Flush Partial Keys

This request instructs the device-dependent keyboard driver to flush any partial keys it has accumulated and return to a quiescent state. Because most physical drivers will be implemented using a finite state machine, this is a forced transition to the start state.

Input:

     Func: Flush_Partial code (0010h)
     Var1: NULL
     Var2: NULL

Output:

     AX=0.

Save State

This function informs device-dependent drivers to save all hardware state information for a later time. This function is used for Advanced Power Management (APM) support.

Input:

     Func: Save_State code (0012h)
     Var1: NULL
     Var2: NULL

Output:

     AX=0FFFFh if error occurs.

Restore State

This function restores all hardware state information from the last save. If a Save State has not receded this call, the keyboard defaults to no LEDs lit, and a 0 type rate and delay. This function is used for Advanced Power Management (APM) support.

Input:

     Func: Save_State code (0013h)
     Var1: NULL
     Var2: NULL

Output:

AX=0FFFFh if error occurs. 

Keyboard Device Driver Test Tool

This chapter explains how to use the keyboard Device Driver Test Tool.

Overview

The keyboard Functional Verification Tests (FVTs) exercise the Inter-Device-Driver Communication (IDC)interfaces defined for the keyboard device drivers. The tests are implemented with the Device Driver Test Tool (DDTT) and a test device driver (TEST KBD.SYS). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate keyboard function and performance. Errors are reported and isolated to a specific test sequence and API.

User input and output from each keyboard test is performed by way of a separate Presentation Manager window. Test cases log all information to a log files, clearly indicating the actual execution sequence in the event of errors.

Keyboard Test Architecture

The DDTT provides a common front-end parser for test-case scripts and also tests several devices and APIs. The following DDTT keyboard-specific files are required:

  • DDTKBD.DLL
  • KBD.GRA.
  • TESTKBD.SYS

The C++ source code for DDTKWD.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc.

The following required, common components of the DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:

  • DDTT.EXE
  • DDTT.DLL
  • GLOBAL.DLL
  • GLOBAL.GRA

Ioddr-04.gif

Installation

There are two directory structures utilizing test suites in the IBM Developer Connection Device Driver Kit for OS/2. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL.

The following procedure describes installation for running test cases.

1. Copy the executable and parallel port test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TESTKBD. Test case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TESTKBD and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the parallel port test suite:

 [C:\]md testkbd
 [C:\]cd testkbd
 [C:\testkbd]copy e:\ddk_x86\testcert\inputout\function\keyboard\*
 [C:\testkbd]copy e:\ddk_x86\testcert\general\ddtt\*

2. Add C:\TESTKBD to the LIBPATH and PATH in the CONFIG.SYS file.

3. To install the device driver, edit your system's CONFIG.SYS file and add the following line:

 DEVICE=c:\testkbd\testkbd.sys

4. Reboot your machine so the new LIBPATH entry and DEVICE statement take effect.

Test Case-Execution

To run one script file at a time, refer to #Description of Test Cases for a description of each script file. Then, after determining which script file to run, type in DDTT followed by the script file name:

 [C:\TESTKBD]DDTT QUERY.SCR

After the script has finished executing, CONTROL will transfer back to the OS/2 Window.

KBDDD.SYS Test Grammar Function Calls

The following is a list of the KBDDD.SYS Test Grammar Function Calls:

  • KBD_OPEN
  • KBD_CLOSE
  • KBD_QUERY_CAPS
  • KBD_QUERY_TYPEMATIC
  • KBD_QUERY_LEDS
  • KBD_QUERY_IDS
  • KBD_QUERY_DISABLED
  • KBD_SEND_CMD
  • KBD_FLUSH
  • KBD_SAVE_STATE
  • KBD_RESTORE_STATE
  • KBD_DISABLE and KBD_DISABLE_I
  • KBD_ENABLE and KBD_ENABLE_I
  • KBD_RESET and KBD_RESET_I
  • KBD_OPEN_DI
  • KBD_CLOSE_DI
  • KBD_PROCESS_KEY
  • KBD_PROCESS_REINIT
  • KBD_PRINT_LAST_IDC

KBD_OPEN

This function opens the TESTKBD.SYS device driver and sends an open IDC to IBMKBD.SYS.

Input Parameter Keywords

None.

Output Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Logged Data

None.

KBD_CLOSE

This function sends a close IDC to KBDDD.SYS and closes the TESTKBD.SYS device driver.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data

None.

KBD_QUERY_CAPS

This function queries the capabilities of the keyboard.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords
Keyword Type Description
MAXTYPA NUM Max typematic rate selector (0-31)
MINTYPA NUM Min typematic rate selector (0-31)
MAXDELAY NUM Max delay value selector (0-3)
MINDELAY NUM Min delay value selector (0-3)
KEYCOUNT NUM Number of keys
NUMLEDS NUM Number of LEDs
Logged Data
Max typematic rate selector (0-31)
Min typematic rate selector (0-31)
Max delay value selector (0-3)
Min delay value selector (0-3)
Number of keys
Number of LEDs
(No) Hotplug Detection
(Not) True keyboard

KBD_QUERY_TYPEMATIC

This function queries the current typematic rate and delay of the keyboard.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords
Keyword Type Description
TYPASEL NUM Typematic rate selector (0-31)
DELAYSEL NUM Delay value selector (0-3)
Logged Data
Typematic rate selector (0-31)
Delay value selector (0-3)

KBD_QUERY_LEDS

This function queries to determine which LEDs are lit.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data
Scroll Lock is ON/OFF
Num Lock is ON/OFF
Caps Lock is ON/OFF

KBD_QUERY_IDS

This function queries the ID value and keycount of the keyboard.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords
Keyword Type Description
KEYCOUNT NUM Number of keys
ID NUM ID code for keyboard hardware
Logged Data
Number of keys
ID code for keyboard hardware

KBD_QUERY_DISABLED

This function queries to determine if the keyboard has been disabled.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data

Keyboard enabled or disabled

KBD_QUERY_READY

This function queries whether the keyboard is ready.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data

Keyboard ready or not ready

KBD_SEND_CMD

This function sends a generic command to the keyboard.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
COMMAND STRING Command string
ACK NUM Nonzero if acknowledgement is required
Output Parameter Keywords

None.

Logged Data

None.

KBD_FLUSH

This function flushes partial keystrokes and returns the keyboard to a start state.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data

None.

KBD_SAVE_STATE

This function saves the keyboard state and is used by the Advanced Power Management System.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data

None.

KBD_RESTORE_STATE

This function restores the keyboard's saved state. This function is used by the Advanced Power Management System.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data

None.

Paired Functions

The following functions are paired according to interrupt-mode processing and non-interrupt mode processing. If the function is an interrupt-mode function, it has a _I suffix. The functionality of the pairs of functions is identical whether the _I suffix is there or not.

KBD_DISABLE and KBD_DISABLE_I

These functions disable the keyboard.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data

None.

KBD_ENABLE and KBD_ENABLE_I

These functions enable the keyboard.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data

None.

KBD_RESET and KBD_RESET_I

These functions reset the keyboard.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
Output Parameter Keywords

None.

Logged Data

None.

KBD_SET_TYPEMATIC and KBD_SET_TYPEMATIC_I

These functions set the typematic rate and delay of the keyboard.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
TYPASEL NUM Typematic rate selector (0-31)
DELAYSEL NUM Delay value selector (0-3)
Output Parameter Keywords

None.

Logged Data

None.

KBD_SET_LEDS and KBD_SET_LEDS_I

These functions set the LEDs.

Input Parameter Keywords
Keyword Type Description
HANDLE NUM Handle for TESTKBD.SYS
LEDS NUM THE LEDS KEYWORD IS A 3-BIT BINARY NUMBER, where:

Bit 0 = Scroll Lock Bit 1 = Num Lock Bit 2 = Caps Lock

Output Parameter Keywords

None.

Logged Data

None.

Description of Test Cases

Each of the keyboard test cases can be executed individually as previously described. The corresponding test scripts are described below. The user can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the keyboard grammar files.

All test scripts close the channels opened to the keyboard device and verify successful status returns from every exercised API. All test scripts log information to a log file with the same file name and a file name extension .LOG. When current status is queried (for example, track, channel, or drive), this data is written to the DDTT's output windows and to the log file. Log files can be examined after the test case has been completed.

INTERACT.SCR Human interaction script - This script tests the enable/ disable feature of the keyboard driver. When the keyboard is disabled, the user is asked to type at a prompt. If the disable is successful, the keyboard re-enables after a timeout of five seconds.

SET.SCR LED and Typematic selection script - This script sets the typematic rate and delay, as well as playing with the LEDs. It allows the user to verify that the rate and delay have been changed by allowing typing at the prompt. If no input is received, the prompt times out after 10 seconds.

QUERY.SCR This is a multi-threaded test that attempts to run some IDCs in parallel.

Mouse Device Driver

OS/2 2.0 (and later) supports two classes of pointing devices - relative and absolute. A relative pointing device reports relative motion (that is, how far it has moved). An example of a relative pointing device is a mouse or a track ball. An absolute pointing device reports absolute positions within some predefined work space; there is no real concept of relative motion. An example of an absolute pointing device is a touch-sensitive screen.

Listed below are commonly-used terms and their definitions. These terms are frequently used throughout this chapter:

  • MOUSE$. The OS/2 system-provided pointing device driver name, which is defined in the device header field of MOUSE.SYS.
  • IDC. Inter-Device-Communication.
  • Device-Independent-Device Driver. Another way of referring to MOUSE.SYS, which handles all the IDC interfaces defined on the following pages.
  • Device-Dependent Device Driver. Hardware-specific device driver that communicates with MOUSE.SYS through the IDC for additional pointing device support. The OS/2 operating system provides pointing device support for the following:
IBM Mouse
IBM 8516 Touch Display
Microsoft** Mouse
Logitech** Mouse
PC Mouse** Systems Mouse

Any pointing device that is compatible with the above devices is supported.

Generic Pointing Device Support

The OS/2 operating system provides a physical mouse device driver called MOUSE.SYS that tries to detect the type of pointing device currently installed on the system. Once it detects the existence of a particular pointing device, it dynamically sets up support for that device.

If the physical mouse device driver is unable to detect the presence of a pointing device, the installation program prompts the user for pointing device information. The installation program then sets the appropriate statements for pointing device support in the CONFIG.SYS file. The physical mouse driver will set up to support the first pointing device that it finds.

High-Level Design

During device driver initialization time, the physical mouse device driver first checks to see if the TYPE= overrider has been used. If the DEVICE=C:\OS2\MOUSE.SYS line in the CONFIG.SYS file contains a TYPE= overrider, then pointing device support is established through an IDC interface with the device-dependent device driver name following TYPE=. The device-dependent device driver must be loaded before MOUSE.SYS.

If a TYPE= overrider has not been specified, it is assumed that generic pointing device support is desired. The generic pointing device driver detects if the system is a EIA/EISA (non-ABIOS) system or a Micro Channel (ABIOS) system.

Application Level Interface

An IOCtl is provided to get the device type. The installation program calls the IOCtl sometime during the installation process to find out if a pointing device has been found. If no pointing device is found, the installation program prompts the user for the pointing device that is installed. The installation program can also give the user a chance to override the pointing device found by MOUSE.SYS.

Note: It is unlikely that a situation where the user would override the pointing device support set up by the generic pointing device driver. (Multiple pointing devices would be necessary in order for this situation to occur.)

In some cases, the generic pointing device driver might not be able to detect the pointing device, even though it is plugged into the system. The installation program prompts the user for the pointing device type and updates the CONFIG.SYS file with a TYPE= overrider, if a hardware-dependent device driver is currently provided for the specified device.

Physical Mouse Device Driver Considerations

The OS/2 installation program ensures that physical mouse device driver initialization takes place prior to physical ASYNC device driver initialization. This allows the physical ASYNC device driver to determine that it is not responsible for servicing that port, ensuring that physical mouse device drivers are not preempted from the COMn ports by the physical ASYNC device drivers.

Note: When manually changing CONFIG.SYS, the user must place the mouse DEVICE= statements before ASYNC DEVICE= statements.

OS/2 provides a method for supporting additional pointing devices. Pointing device support can be obtained by writing a device-dependent device driver for the device. This physical device driver will communicate directly with the OS/2-provided device driver MOUSE.SYS (the device-independent device driver) through the IDC interfaces that follow.

MOUSE.SYS IDC Interface

The IDC provided by MOUSE.SYS supports the following:

  • Process_Packet
  • Disable_Support
  • Process_Absolute
  • Open_Mouse
  • Close_Mouse
  • Query_Activity

Process_Packet

This request is issued by the device-dependent device driver to pass a relative-pointing-device event to MOUSE.SYS. Process_Packet is nonreentrant. The device-dependent device driver ensures that calls to Process_Packet are never nested. Process_Packet must be issued only when the pointing device is enabled.

Input: AX= Process_Packet function code, 0001H.

Common-event buffer initialized. The offset of the common-event buffer was passed on the Read_Enable request. This data buffer is used to pass both relative and absolute pointing-device events. When the physical device driver issues a Process_Packet request, the buffer has the following format:

Event_Data   Struc

Event        dw     ?   ; Description of event
Col_Motion   dw     ?   ; Relative column motion
Row_Motion   dw     ?   ; Relative row motion

Event_Data   Ends

Before the physical device driver makes the request, initialize the buffer. Notice that positive motion is up and to the right. Up can also be viewed as moving a mouse device away from the user. Negative motion is the opposite of positive.

Output: No specific output for request.

Disable_Support

This request is used by the device-dependent device driver to inform MOUSE$ that it has uninstalled. When the request is received, MOUSE$ enters a disabled state. It returns the error DEVICE NOT READY for subsequent requests from the system.

Note: Do not issue this request under normal circumstances.

Input: AX= Disable_Support function code, 0002H.

Output: No specific output for the request.

Process_Absolute

This request is issued by the device-dependent device driver to pass an absolute-pointing device event, usually from a touch-sensitive screen, to MOUSE.SYS. Process_Absolute is nonreentrant. It is the responsibility of the device-dependent device driver to ensure that calls to Process_Absolute are never nested. Process_Absolute should be issued only when the pointing device is enabled. The reported event is mapped into the current display mode and appears to the system to be a mouse event.

Input: AX= Process_Absolute function code, 0003H.

Common-event buffer initialized. The offset of the common-event buffer was passed on the Read_Enable request. This data buffer is used to pass both relative and absolute pointing-device events. When issuing a Process_ Absolute request, the buffer has the following format:

Event_Data   Struc

Event        dw     ?   ; Description of event
Row_Pos      dw     ?   ; Row position of event
Col_Pos      dw     ?   ; Col position of event
Row_Size     dw     ?   ; Number of row units
Col_Size     dw     ?   ; Number of column units

Event_Data   Ends

MOUSE$ uses Row_Size and Col_Size to map the absolute event into the current display mode. These values should reflect the maximum allowed position that could be reported. All values are zero-based. The upper-left corner of the device should be reported as location 0,0.

Initialize the buffer before making the request.

Output: No specific output for the request.

Open_Mouse

This function is started by another Input Device Driver to get a Mouse IDC Interface handle. This handle is a required parameter for the Close_Mouse and Query_Activity functions. This function supports a maximum of five open Mouse IDC handles at any given point in time. Attempts to open a sixth Mouse IDC handle are returned with a NO_HANDLES_AVAILABLE error code.

Input: AX= Open_Mouse function request code, 0004H
DS= MOUSE$ DD DS value
ES= Calling DD DS value
BX= Undefined
CX= Undefined
DX= Undefined
SI= Undefined
DI= Undefined

Output: AX= Error Return code if Carry is set; undefined if Carry is clear
BX= Mouse IDC handle
DS= MOUSE$ DD DS value
ES= Calling DD DS value
CX= Undefined
DX= Undefined
SI= Undefined
DI= Undefined

Error Return Codes: NO_HANDLES_AVAILABLE

Remarks: This function is valid any time after device driver initialization.

Close_Mouse

This function is started by another physical device driver to free a mouse IDC Interface handle. The input handle value must have been generated using the Mouse IDC Function 0004H, Open_Mouse. If the input Mouse IDC handle is invalid, then an INVALID_HANDLE error code is returned.

Input: AX= Close_Mouse function request code, 0005H
BX= Mouse IDC handle
DS= MOUSE$ DD DS value
ES= Calling DD DS value
CX= Undefined
DX= Undefined
SI= Undefined
DI= Undefined

Output: AX= Error Return code if Carry is set; undefined if Carry is clear
DS= MOUSE$ DD DS value
ES= Calling DD DS value
BX= Undefined
CX= Undefined
DX= Undefined
SI= Undefined
DI= Undefined

Error Return Codes: INVALID_HANDLE

Remarks: This function is valid any time after device driver initialization.

Query_Activity

This function is started by another physical device driver to get the current Mouse Activity Status, in relation to the last time this function was called or because the caller's handle was opened. This function does not provide the caller with the current Mouse State. It provides only the data from a last-call perspective. A return value of 0 in the BX register ( without an error condition) indicates that no mouse device activity has been recorded since the last call. In addition, the return status is on a system-wide basis (that is, there is no evaluation for a particular session's activity). If the input Mouse IDC handle is invalid, then an INVALID_ HANDLE error code is returned.

Input: AX= Query_Activity function request code, 0006H
BX= Mouse IDC handle
DS= MOUSE$ DD DS value
ES= Calling DD DS value
CX= Undefined
DX= Undefined
SI= Undefined
DI= Undefined

Output: AX= Error Return code if Carry is set; undefined if Carry is clear
BX= Mouse Activity Status
DS= MOUSE$ DD DS value
ES= Calling DD DS value
CX= Undefined
DX= Undefined
SI= Undefined
DI= Undefined

The Mouse Activity Status is a returned bit mask. A set bit is defined as having a value of 1. A set bit indicates that the description status or event occurred. The bit definitions for the Mouse Activity Status parameter are as follows:

Bits 15-11 Reserved=0
Bit 10 Button 5 usage, without motion
Bit 9 Button 5 usage, with motion
Bit 8 Button 4 usage, without motion
Bit 7 Button 4 usage, with motion
Bit 6 Button 3 usage, without motion
Bit 5 Button 3 usage, with motion
Bit 4 Button 2 usage, without motion
Bit 3 Button 2 usage, with motion
Bit 2 Button 1 usage, without motion
Bit 1 Button 1 usage, with motion
Bit 0 Pure motion was recorded.

Note: The Mouse device-dependent IDC Interface allows a device with up to five buttons to be supported. The OS/2 operating system provides specific device support for only two-button and three-button pointing devices.

Error Return Codes: INVALID_HANDLE

UNKNOWN_COMMAND

Remarks
This function is valid only when OS/2 AIM Support is enabled. When Special Needs Support is inactive (AIM_Active = FALSE), IDC Query_Activity function requests are not allowed, and are returned to the caller with an UNKNOWN_COMMAND error code. For information on OS/2 AIM Support for physical device drivers, refer to Category 0Bh regarding System Notifications for Physical Device Drivers in the OS/2 Physical Device Driver Reference.

Device-Dependent Device Driver IDC Interface

The IDC provided by the device-dependent device driver must support the following requests:

  • Query_Config
  • Read_Enable
  • Read_Disable
  • Disable_Device
  • Enable_Device

Query_Config

This request is issued by MOUSE$ and determines the operating characteristics of the attached hardware. The format follows:

Input: AX= Query_Config function code, 0001H.
DI= Offset in mouse data segment of where to write the configuration data.
ES= Must be loaded with the MOUSE$ data segment/selector prior to the request. The configuration data has the following format:

Config_Data  Struc

Length       dw    ?  ; Total length in bytes (7)
Num_Mics     db    ?  ; Device resolution in mickeys/centimeter
Num_Butt     db    ?  ; Number of buttons (up to 7 supported)
Dev_IRQ      db    ?  ; Device IRQ level
Mouse_Type   db    ?  ; Type of mouse attached:
                      ;      0 = Unknown
                      ;      1 = Bus mouse
                      ;      2 = Serial mouse
                      ;      3 = InPort mouse
                      ;      4 = Pointing Device Port Mouse
                      ;      5 = IBM 8516 Touch Display
                      ;  6-255 = Reserved
Com_Num      db    ?  ; Com port number of the attached pointing device
                      ; 0 - If non-serial device
Config_Data  Ends

Initialize the Lengthfield to 7 before issuing the request. The Num_Micsfield for an absolute device should reflect some reasonable measure of the number of device units per centimeter.

Output: Configuration data structure filled if no errors.

Read_Enable

This request serves two purposes. It gives the offset of the common-event buffer in the MOUSE$ data segment. (This offset should be saved.) It also informs the device-dependent device driver that it can start sending event data to MOUSE$, using the Process_Packet and Process_Absolute requests. The device-dependent device driver also should attach itself to MOUSE$, using DevHelp_ AttachDD, when it receives this request.

Input: AX= Read_Enable function code, 0002H.
DI= Offset to common-event buffer.This buffer resides in the MOUSE$data segment. To address it, use the MOUSE$ data segment/selector value ( depending on the processor mode) returned on the AttachDD call. The common- event buffer has enough space to format either a relative or absolute event. For the two common-event buffer formats, see Process_Packet, and Process_Absolute.

Output: No specific output for the request.

Read_Disable

This request is issued by MOUSE$ when it no longer accepts Process_Packet or Process_Absolute requests. References to the common-event buffer should be discontinued. However, MOUSE$ can enable the interface again by sending another Read_Enable request. Normally this request is not issued.

Input: AX= Read_Disable function code, 0003H

Output: No specific output for the request.

Disable_Device

This request is used by MOUSE$ when placing a pointing device in a disabled state. Upon completion of this request, no Process_Packet or Process_Absolute requests are to be made to MOUSE$ until an Enable_Device request is received. There is no requirement that the hardware itself be disabled, only that no Process_Packet or Process_Absolute requests be issued. Receipt of a Disable_Device request is not considered an error if the pointing device is already disabled.

Input: AX= Disable_Device function code, 0005H.

Output: No specific output for the request.

Enable_Device

This request is used by MOUSE$ when resetting a pointing device to an enabled state. Process_Packet and Process_Absolute requests are made to MOUSE$ when a pointing device is in an enabled state. Receipt of an Enable_ Device request is not considered an error if the pointing device is already enabled.

Input: AX= Enable_Device function code, 0004H.

Output: No specific output for the request.

Building the WIN-OS/2 Mouse Device Driver

WIN-OS/2* provides support for pointing devices using a generic mouse driver (MOUSE.DRV). Some devices may not work correctly with this driver. If this is the case, you should write a WIN-OS/2 mouse driver to support the new device type.

To write a WIN-OS/2 driver, examine the Windows** mouse driver example provided on the Microsoft Device Driver Kit. Use the source code as a template for writing a WIN-OS/2 driver. In order for the driver to run correctly in the operating system, you must replace two files (MOUSE.ASM and INT33H.ASM) used in the Windows mouse driver. The source modifications (which are within the ifdef WINOS2 statements) support the WIN-OS/2 mouse driver. The replacement source files are available on the IBM Device Driver Source Kit for OS/2.

The source code in the MOUSE.ASM file was modified to include global variables needed to support the device.

The source code in the INT33H.ASM file was modified to include the following:

  • Add the external declarations for the new global variables
  • Alter the execution path to enable the driver to run seamlessly
  • Include additional code to support the mouse running under OS/2
  • Change the state_xlate table
  • Load ES with a driver code segment value
  • Call the virtual device driver interface
  • Add a routine that determines if the DOS session is running seamlessly

These modifications can be used with any device driver that is based on the Windows mouse device driver.

Building the Physical Mouse Device Driver Code

To build the physical mouse device drivers:

  1. Add the TOOLS directory in the IBM Device Driver Source Kit for OS/2 to the current path.
  2. NMAKE the corresponding Make file provided in the device driver.

For example:

CD \DDK_x86\SRC\DEV\MOUSE (where the mouse code resides)
NMAKE

This will build MOUSE.SUS, which is language-dependent (US). You must copy this driver to C:\OS2\MOUSE.SYS and reboot the system in order for the newly-built driver to be loaded. This is the generic physical mouse device driver provided by OS/2.

The directory \ddk_x86\src\dev\mouse\familyg (which can be found on the IBM Developer Connection Device Driver Kit for OS/2) contains the device-dependent device driver.

To build the WIN-OS/2 mouse device driver, you must have the tools necessary to build the Windows mouse driver. In addition, replace the Windows files with the WIN-OS/2 MOUSE.ASM and INT33H.ASM files. Run 'nmake WINOS2=1'. The output file is MOUSE>DRV. Use this file to replace the existing WIN-OS/2 MOUSE.DRV file.

Mouse (DOS) Device Driver Test Tool

This chapter explains how to use the mouse (DOS) Device Driver Test Tool.

Overview

The mouse Functional Verification Tests (FVTs) exercise the Int86() DOS interface for mouse functions. The tests are implemented with a special variation of the Device Driver Test Tool (called DOSMOUSE), which uses much of the Device Driver Test Tool code; however, DOSMOUSE does not use the multithread capability. Specific mouse function code is included in the DOSMOUSE.EXE, not in a DLL, as is it done for the DDTT running in OS/2.

These tests run in a DOS window. Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate mouse functions.

Test cases log all information to a log file, clearly indicating the actual execution sequence.

Mouse Test Architecture

DOSMOUSE uses the DDTT common front-end parser code for test case scripts. DOSMOUSE is specific to test mouse functions. The mouse grammar file is required:

  • DOSMOUSE.EXE
  • MOUSE.GRA.

The following required, common component of the DDTT allows use of the DDTT's common test functions such as SET, LOOP, and PAUSE:

  • GLOBAL.GRA

Installation

The mouse test files reside on the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc. These files utilize the test suites in the TESTCERT substructure, which also contain the executables and test cases.

The following procedure describes the installation process for running test cases:

1. Copy the executable and mouse test case files from the IBM Developer Connection Device Driver Kit for OS/2CD-ROM disc to the hard drive. The executable (DOSMOUSE.EXE) files can reside in one directory (for example, \MOUSE). Test case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\MOUSE and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the mouse test suite:

 [C:\]md mouse
 [C:\]cd mouse
 [C:\mouse]copy e:\ddk_x86\testcert\inputout\function\mouse\*
 [C:\mouse]copy e:\ddk_x86\testcert\general\ddtt\GLOBAL.GRA

Test Case Execution

To run one script file at a time, refer to #Description of Test Cases for a description of each script file. Then, after determining which script file to run, type in DOSMOUSE followed by the script file name:

[C:\MOUSE]DOSMOUSE ALL.SCR

After the script has finished executing, control will transfer back to the DOS window. Results are logged in the file identified following the @THREAD line.

DDTT Mouse Test Grammar Function Calls

The following is a list of the DDTT Parallel Port Test Grammar Function Calls:

  • MOUSE_RESETANDSTATUS
  • MOUSE_SHOWCURSOR
  • MOUSE_HIDECURSOR
  • MOUSE_GETBUTTONMPOS
  • MOUSE_SETCURPOS
  • MOUSE_GETBPRESS
  • MOUSE_GETBRELEASE
  • MOUSE_SETMINMAXHCPOS
  • MOUSE_SETMINMAXVCPOS
  • MOUSE_READMCOUNT
  • MOUSE_GETDRVVERTYPIRQ
  • MOUSE_GETGENINFO
  • MOUSE_GETMAXVCOOR
  • MOUSE_GETCURMSKMCNT
  • MOUSE_GETCURHSPT
  • MOUSE_HDWRESET
  • MOUSE_SETGETBPT
  • MOUSE_GETMINMAX
  • MOUSE_GETADVFCN
  • MOUSE_GETSWSET
MOUSE_RESETANDSTATUS

Mouse Function 0

This function returns the current status of the mouse hardware and software.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
M1% Mouse status (found and reset = -1, otherwise = 0)
M2% Number of buttons (if mouse found and reset = 2)
MOUSE_SHOWCURSOR

Mouse Function 1

This function increments the internal cursor flag and if the value of the flag is 0, displays the cursor on the screen.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
None.
MOUSE_HIDECURSOR

Mouse Function 2

This function removes the cursor from the screen, decrements the internal cursor flag, and hides the cursor. The mouse driver continues to track the motion of the mouse, changing the cursor's position as the mouse changes position.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
None.
MOUSE_GETBUTTONMPOS

Mouse Function 3

This function returns the state of the left-hand and right-hand mouse buttons and also returns the state of the cursor's horizontal and vertical virtual screen coordinates.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
Button status
Horizontal cursor coordinates
Vertical cursor coordinates
MOUSE_SETCURPOS

Mouse Function 4

This function sets the cursor position at the location of the specified horizontal vertical virtual coordinates.

Input Parameter Keywords
Keyword Type Description
HORIZC NUM Horizontal cursor coordinate
VERTC NUM Vertical cursor coordinates
Output Parameter Keywords
None.
Logged Data
None.
MOUSE_GETBPRESS

Mouse Function 5

This function returns the current status of both buttons, counts the number of times the specified button was pressed since the last call to this function, and reports the cursor's horizontal and vertical coordinates the last time the specified button was pressed.

Input Parameter Keywords
Keyword Type Description
BUTTON NUM Left hand button=0 or right hand button =1
Output Parameter Keywords
None.
Logged Data
Button status
Number of button presses
Horizontal coordinate
Vertical coordinate
MOUSE_GETBRELEASE

Mouse Function 6

This function returns the current status of both buttons, counts the number of times the specified button was released since the last call to this function, and reports the cursor's horizontal and vertical coordinates the last time the specified button was released.

Input Parameter Keywords
Keyword Type Description
BUTTON NUM Left hand button=0 or right hand button =1
Output Parameter Keywords
None.
Logged Data
Button status Button releases
Horizontal coordinate
Vertical coordinate
MOUSE_SETMINMAXHCPOS

Mouse Function 7

This function sets the position of the minimum and maximum horizontal cursor coordinates on the screen.

Input Parameter Keywords
Keyword Type Description
HMIN NUM Horizontal minimum position
HMAX NUM Horizontal maximum position
Output Parameter Keywords
None.
Logged Data
None.
MOUSE_SETMINMAXVCPOS

Mouse Function 8

This function sets the position of the minimum and maximum vertical cursor coordinates on the screen.

Input Parameter Keywords
Keyword Type Description
VMIN NUM Vertical minimum position
VMAX NUM Vertical maximum position
Output Parameter Keywords
None.
Logged Data
None.
MOUSE_READMCOUNT

Mouse Function 11

This function returns the horizontal and vertical mickey counts since the last call of this function.

Input Parameter Keywords

None.

Output Parameter Keywords
None.
Logged Data
Horizontal mickey count
Vertical mickey count
MOUSE_GETDRVVERTYPIRQ

Mouse Function 36

This function returns the version number of the mouse driver, reports the type of mouse the driver requires, and returns the number of the interrupt request type (IRQ).

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
Major version
Minor version
Mouse type
IRQ number
MOUSE_GETGENINFO

Mouse Function 37

This function returns general information about the mouse.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
General information
fCursorLock
fInMouseCode
fMouseBusy
MOUSE_GETMAXVCOOR

Mouse Function 38

This function returns a flag indicating whether the mouse driver is disabled and indicates maximum virtual coordinates.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
Mouse-disabled flag
Maximum virtual x
Maximum virtual y
MOUSE_GETCURMSKMCNT

Mouse Function 39

This function returns cursor information and accumulated raw mickey counts.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
Screen-mask or Scan-line start
Cursor-mask or Scan-line stop
Horizontal mickey count
Vertical mickey count
MOUSE_GETCURHSPT

Mouse Function 42

This function returns the cursor hot-spot location, reports the type of mouse in use, and returns the internal counter that controls cursor visibility.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
fCursor
Horizontal cursor hot spot
Vertical cursor hot spot
Type of mouse
MOUSE_HDWRESET

Mouse Function 47

This function returns cursor information and accumulated raw mickey counts

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
Success flag
MOUSE_SETGETBPT

Mouse Function 48

This function sets or returns cursor ballpoint-orientation and buttonmask information.

Input Parameter Keywords
Keyword Type Description
ROTANGLE NUM Rotation angle
CMDINFO NUM Command
Output Parameter Keywords
None.
Logged Data
Status
Rotation angle
Button mask
MOUSE_GETMINMAX

Mouse Function 49

This function returns the minimum and maximum horizontal and vertical coordinates for the current video mode.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
Status
Virtual xminimum
Virtual yminimum
Virtual xmaximum
Virtual ymaximum
MOUSE_GETADVFCN

Mouse Function 50

This function returns the flags that indicate active advanced functions.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
Active function flags
MOUSE_GETSWSET

Mouse Function 51

This function returns the current settings of switch values that can be passed to the mouse driver.

Input Parameter Keywords
None.
Output Parameter Keywords
None.
Logged Data
Mouse type
Mouse port
Language
Horizontal sensitivity
Vertical sensitivity
Double threshold
Ballistic curve
Interrupt rate
Cursor Override Mask
Laptop adjustment
Memory type
Super VGA support
Rotation angle
Primary button
Secondary button
Clip lock enabled
Acceleration curve data

Description of Test Cases

Each of the mouse test cases can be executed individually as previously described. The test scripts are described below. The user can create additional tests or combine tests into test cases after becoming familiar with DOSMOUSE and the MOUSE grammar file.

ALL.SCR
This runs all the mouse functions.
BUTTON.SCR
This tests button press and release functions.

Evaluation of Test Case Results

Unless otherwise stated in the test case descriptions, all test cases are expected to succeed. If a test case fails in a mode detectable by DOSMOUSE, then the token "ERROR" will be written to the corresponding log file.

Parallel Port Device Driver

The OS/2 parallel port device driver is a base physical device driver that supports the parallel port device interface for OS/2. There are two distinct versions of the parallel port device driver:

PRINT01.SYS
Supporting parallel port adapters on ISA/EISA bus machines
PRINT02.SYS
Supporting parallel port adapters on Micro Channel machines (machines containing Micro Channel architecture).

PRINT01.SYS manipulates the hardware ports through I/O instructions. The Micro Channel parallel port device driver does not access the hardware ports. Advanced BIOS (ABIOS), which executes on Micro Channel machines, replaces the hardware port manipulation done on the ISA/EISA bus machines.

Only one of these physical device drivers will be resident for each machine running in OS/2. Because the parallel port device driver is a base physical device driver, OS/2 determines the system's hardware configuration and automatically installs and initializes the appropriate physical device driver. OS/2 adds a BASEDEV= statement for the device driver to the CONFIG. SYS file.

Overview

The parallel port device drivers service parallel port requests from DOS, WIN-OS/2, and OS/2 applications (including those running under the Presentation Manager). Requests are serialized by the spooler so that mixed printer output will not occur. Printer requests include:

  • Initializing a parallel port device
  • Sending characters to a parallel port device
  • Returning the status of a parallel port device
  • Handling IOCtl function calls, including the setting of the parallel port device's frame control (characters per line and lines per inch)

In addition, the parallel port device drivers include character device monitor support. The parallel port device driver sends data to a character device monitor, if one is installed.

The primary method of communicating with the parallel port device driver is through a request packet. When the parallel port device driver receives a request packet, it determines which device the request is for. If a request is not already in progress, the physical device driver calls an appropriate routine to handle the request. If a request is in progress, the physical device driver blocks the caller's thread until the in-progress request has completed. Once the in-progress request has been serviced, the physical device driver will run the caller's thread and process the waiting request.

To make a request of the printer, an OS/2 application pushes parameters ( for example, the address of characters to be written) onto its stack, and calls the file system API (for example, DosWrite). The file system:

  • Determines that the request is for the parallel port device driver (based on the specified device handle)
  • Creates a request packet
  • Issues a call to the parallel port device driver strategy routine

To make a request of the printer from a DOS session, an application moves the parameters into predefined registers and issues an INT 17h or INT 21h. The INT 17h is intercepted by the virtual parallel port device driver. Refer to OS/2 Virtual Device Driver Referencefor more information. The INT 21h request is converted into a request packet and issued to the device driver strategy routine.

Replacing the Parallel Port Device Driver

The parallel port device drivers contain four device headers in their data segments with the reserved device names PRN, LPT1, LPT2, and LPT3. These device names correspond to the three physical devices supported by this physical device driver. Notice that the names PRN and LPT1, although logically appearing different, correspond to the same physical device.

The parallel port device driver is replaceable. It is uninstalled by creating another parallel port device driver with the device name in the device header identical as the one listed above. It can then be reinstalled by specifying the new parallel port device driver in a DEVICE= statement in CONFIG.SYS.

Note: Installation of the files associated with the new device driver, and the addition of the corresponding DEVICE= statement in the CONFIG.SYS file, is accomplished through the DDINSTAL utility and the Device Driver Profile (DDP) for the new device driver.

When the DEVICE= statement for the new parallel port device driver is encountered in CONFIG.SYS during system initialization, the system generates a DEINSTALL request packet and sends it to the parallel port device driver. The OS/2 parallel port device driver receives the DEINSTALL request packet and releases its resources. Refer to the strategy command, "14h / DEINSTALL" in the OS/2 Physical Device Driver Reference for more information.

If the parallel port device driver successfully releases its resources, it returns a successful completion on the Deinstallation request. When the parallel port device driver has been deinstalled, the system then generates an INSTALL request packet and sends it to the new device driver. Refer to the strategy command, "0h /INIT" in the OS/2 Physical Device Driver Reference for more information.

Parallel Port IRQ Performance

The Programmable Interrupt Controller (PIC) under OS/2 2.1, IRQ3 (serial port) has the highest priority in the system. This has given IRQ7 (parallel port) a much higher priority than it would otherwise have. It is now higher in priority than the keyboard or the mouse. A system unit running multiple parallel port devices, that can receive data quickly on a combination of serial/parallel port devices at a high rate of speed (for example, a laser printer with several megabytes of memory) can experience slow user input performance from the mouse and keyboard.

Several alternatives exist to improve user input performance. One alternative, for attended print servers, is to ensure the system unit supports a direct memory access (DMA) parallel or serial port. The parallel port device driver takes advantage of DMA, which reduces the number of hardware interrupts in the system. Fewer high priority interrupts in the system allow the processor to spend more time processing lower priority interrupts.

Another alternative is to convert a parallel port device to run using the serial port and to reduce the bit rate to the serial device. The ASYNC adapter must support extended hardware buffering. For more information on this approach, refer to the Physical ASYNC Communications Device Driver in the OS/2 Physical Device Driver Reference.

A last alternative for those situations where user responsiveness is extremely important is to reduce the number of print files being sent to the print server by moving some of the devices to other system units (thus balancing the workload among several system units available) or to reduce the user installable memory within the device.

DMA Parallel Port Support

The OS/2 2.1 (and later) parallel port device driver for PS/2 systems supports DMA parallel ports using the ABIOS parallel port functions found on those system units.

Using the parallel port in a Programmed I/O (PIO) methodology causes the processor to be involved on each byte transmitted. This prevents the processor from performing other operations.

Using the parallel port in a DMA methodology causes the processor to be involved on each buffer transmitted. The larger the buffer, the fewer interrupts to the CPU, and the more time the CPU can spend doing other useful work.

Code Page Support

The parallel port device driver provides code page support through the OS/2 character device monitor mechanism (for example, the spooler). In addition, three printer IOCtl commands support code page and font switching so that an application has the ability to change the active code page and font in the middle of its print job.

Because the spooler is no longer a character monitor, code page and font switching is handled before the parallel port device driver receives the data. This section remains for compatibility.

Parallel Port (Printer) Monitors

The parallel port device driver defines a data stream for each parallel port device. In addition, each printer data stream can be monitored by parallel port device monitor applications, registered with one of two monitor chains. Character device monitor support is provided by the parallel port device driver, therefore, for each parallel port device.

To register a monitor for one of the parallel port devices, an application issues the DosMonOpen and DosMonReg monitor function calls. DosMonReg generates an IOCtl request for the application to the parallel port device driver to register a monitor on one of the two monitor chains associated with the device. See Category 0Ah, "Register Monitor" (Function 40h), which can be found in the OS/2 Physical Device Driver Reference. When the parallel port device driver receives this request, it:

  • Creates a monitor chain for that device by calling the DevHlp_MonitorCreate, if none was previously created as the result of another register monitor IOCtl request.
  • Registers the monitor with the monitor chain by calling the DevHlp_Register.

By setting the DosMonReg index parameter appropriately, the application specifies on which of the two monitor chains its monitors are registered. The first monitor chain (specified by the application by setting Index=1) is considered to be the data chain, and is used by the parallel port device driver to send data to a monitor. The second monitor chain (specified by the application by setting Index=2) is considered to be the code page chain.

To ensure that printer requests are processed in order, the parallel port device driver places all data and code page requests into only the first monitor chain (referred to as the data chain). That is, the parallel port device driver issues MonWrite calls only to the data chain. The parallel port device driver does not place data into the code page chain by calling MonWrite.

To improve performance, the second monitor chain (code page chain) is used by the parallel port device driver primarily to receive the results of a code page request. Processes that issue code page requests are blocked until they receive an indication that their request is valid. Since the number of code page requests is negligible compared to the number of data requests, parallel port monitors can respond more quickly and efficiently to the physical device driver through the code page chain.

In summary, parallel port monitors:

  • Receive all data and code page requests from the first monitor chain (see DosMonRead)
  • Return data requests to the first monitor chain (see DosMonWrite)
  • Return code page requests to the first or the second monitor chain (see DosMonWrite), depending on the position of the monitor when other monitors are registered with the chain (see below)

Note: The parallel port device driver expects to receive the monitor responses to code page requests on the code page chain. If monitor responses to code page requests are not received from any monitor on the code page chain, unpredictable results can occur.
The spooler is an example of an application that registers a parallel port monitor with both the data chain and the code page chain for a parallel port device. When the spooler registers the monitor with the second chain (see DosMonReg, with Index=2) the monitor input buffer specified is not used because no requests are placed into the second monitor chain by the parallel port device driver.

Parallel port monitors must be designed with extreme care. They must be positioned carefully when other parallel port monitors, in particular the spooler, are registered:

  • If an application monitor wishes only to process character data, it registers a parallel port monitor only on the data chain (Index=1) when:
    1. It is the only monitor in the monitor chain (for example, the spooler is not loaded).
    2. It is registered in a position to process the data after the spooler. This monitor never sees code page requests from the spooler, because the spooler automatically sends these requests back to the physical device driver through the code page chain.
  • If an application wishes to process both character data and code page requests, it registers a parallel port monitor on the data chain (Index=1) and a parallel port monitor on the code page chain (Index=2) when:
    1. It is the only monitor in the monitor chain. It must expect to receive both data and code page requests on the data chain. It must respond to the code page requests on the code page chain as quickly as possible.
    2. It is registered in a position to process data after the spooler. It must expect to receive character data from the spooler on the data chain and the code page requests from the spooler on the code page chain.

Because the spooler passes the code page results along the code page chain before all the data has been spooled and released to be printed, a parallel port monitor cannot easily synchronize the code page requests with the data requests.

  • If a parallel port monitor wishes to process character data and code page requests, and it is registered in a position to process data before the spooler, it registers on the data chain (Index=1) only.

All data and code page requests are sent to the first (nonspooler) monitor on the data chain. Because the spooler receives data and code page requests from the data chain only, this monitor must pass on to the spooler through the data chain all the information it receives in the order that it is received.

IOCtl Support of Code Page and Font Switching

The parallel port device driver has three printer-specific IOCtl commands to support the code page and font switching provided in OS/2 2.1 (and later). In order to support these IOCtl calls, there are Font Monitor Buffer command/responses in the monitor interface between the parallel port device driver and the spooler.

All of the actual code page and font switching functions for printers are provided by the code page switcher or OS/2 printer drivers. When the spooler is started, it checks to see if code page support is required. If it is, the spooler causes the code page switcher to be loaded and initialized. The spooler interfaces with the code page switcher through the DosPFSxxx API functions. If a DEVINFO= statement is not specified in the CONFIG.SYS file, the spooler redirects code page requests to the Presentation Manager device drivers.

The following illustrates the dialog between the parallel port device driver and the spooler when the parallel port device driver receives one of these special IOCtl requests from an application:

  1. The parallel port device driver receives an IOCtl request from an application to activate a code page.
  2. If the spooler is loaded, the parallel port device driver sends a Font Monitor Buffer command to the spooler in the form of a special monitor record placed into the data monitor chain (refer to MonWrite in the OS/2 Physical Device Driver Reference).
  3. The spooler calls DosMonRead to receive this special monitor record from its monitor input buffer registered with the data monitor chain.
  4. When the spooler receives this special monitor record, it either calls DosPFSActivate to get information from the Define Code Page (DCP) system files, or it calls the appropriate Presentation Manager routines to get the code page information pertaining to the particular printer. This information is placed into a temporary spooler file.
  5. The spooler sends a return code back to the parallel port device driver by calling DosMonWrite to place a special monitor record (that is, a Font Monitor Buffer response) into its monitor output buffer registered with the code page chain.

The three printer specific IOCtl commands to support code page and font switching are:

Activate Font: When an application issues a DosOpen for a printer (that is, PRN, LPT1, LPT2, or LPT3), the file system issues an Activate Font IOCtl to the parallel port device driver to set the active code page and font, according to the active code page of the process making the Open request. At any time, an application can also issue the IOCtl, "Activate Font" (Function 48h), to the parallel port device driver by using the handle returned from the DosOpen call to open the device. This allows the application to change the active code page and font in the middle of its print job.

If the parallel port device driver receives the Activate Font IOCtl, and the spooler or another monitor is registered, the parallel port device driver sends a Font Monitor Buffer command (in this case, an Activate Font command) to the monitor on the data chain. The monitor calls DosMonRead to receive this special monitor record from its monitor input buffer registered on the data chain. The monitor sends a Font Monitor Buffer response to this command and to the parallel port device driver by calling DosMonWrite. The monitor then places a special monitor record into its monitor output buffer registered on the code page chain. If the spooler or another monitor is not registered, the parallel port device driver returns the appropriate return code to the caller of the Activate Font IOCtl.

Query Active Font: When the parallel port device driver receives the Query Active Font IOCtl request, and if the spooler or another monitor is registered, the parallel port device driver sends a Font Monitor Buffer command (in this case, a "Query Active Font", Function 69h) to the monitor on the data chain. The monitor calls DosMonRead to receive this special monitor record from its monitor input buffer registered on the data chain. The monitor calls DosMonWrite to send a Font Monitor Buffer response to this command to the parallel port device driver. This places a special monitor record into its monitor output buffer registered on the code page chain. The parallel port device driver then returns the active code page and font information to the caller of the Query Active Font IOCtl. If the spooler or another monitor is not registered, the parallel port device driver returns the appropriate return code to the caller of the Query Active Font IOCtl.

Verify Font: If the parallel port device driver receives the Verify Font IOCtl request, and if the spooler or another monitor is registered, the parallel port device driver sends a Font Monitor Buffer command (in this case, "Verify Font", Function 6Ah, which can be found in the OS/2 Physical Device Driver Reference) to the monitor on the data chain. The monitor receives this special monitor record, from its monitor input buffer registered on the data chain, by calling DosMonRead. The monitor sends a Font Monitor Buffer response to this command to the parallel port device driver by calling DosMonWrite. This places a special monitor record into its monitor output buffer registered on the code page chain. The parallel port device driver then returns the return code to the caller of the Verify Font IOCtl. If the spooler or another monitor is not registered, the parallel port device driver returns the appropriate return code to the caller of the Verify Font IOCtl.

Refer to "Generic IOCtl Interface" and "Monitor Dispatcher Notification Interface", which can be found in the OS/2 Physical Device Driver Reference for specific interface parameters.

Character Monitor Performance

The character monitor buffer of the parallel port device driver has a size of 134 bytes. The PRINTMONBUFSIZE= command, within CONFIG.SYS, provides a method for character monitors to increase this size, and thereby increase performance of data to devices connected to the parallel port. The parallel port device driver allocates and registers its monitor chain buffer based upon the value specified.

The format of this command is:

 PRINTMONBUFSIZE=xxxx,xxxx,xxxx

 Where:
        xxxx corresponds to LPT1, LPT2, and LPT3 character monitor
        buffer size, respectively.

The minimum value allowed for compatibility with existing character monitors is 134 bytes. The maximum value is 2048 bytes. If a value that is out of the valid range is specified, a default value of 134 bytes is used.

Character monitors can dynamically determine the size of a device driver's monitor buffer by issuing a DosMonReg call with a 2-WORD buffer:

  • The first WORD consists of the length of the buffer (4).
  • The second WORD (on return from the call) contains the size of the device driver's monitor chain buffer.

DosMonReg returns with the return code ERROR_MON_BUFFER_TOO_SMALL. The character monitor then allocates the monitor buffer to the correct size and reissues the call to DosMonReg.

Parallel Port IRQ Timeout Processing

The parallel port device driver sets a 120-second timer after receiving a Write request and sending the first byte to the parallel port. If a hardware interrupt is not generated after 120 seconds, the timer expires and a timeout occurs.

There are two different mechanisms for processing timeouts:

  • If infinite retry is enabled, the parallel port device driver does not terminate the request and indefinitely continues to try to send the data to the printer.
  • If infinite retry is disabled, the parallel port device driver terminates the Write request, returning the number of actual bytes sent to the device.

When a monitor is registered, infinite retry is always enabled. The parallel port device driver sends a status monitor packet through the data chain (Index=1) when a timeout error occurs. This activity alerts all monitors of the error.

If a hardware interrupt does occur, the parallel port device driver resets the timer to 120 seconds and sends the next byte to the device. This activity continues until all data has been sent to the device. Once the parallel port device driver determines that all characters have been sent, it turns the timer OFF.

Parallel Port Device Driver Interfaces

The parallel port device driver has several interfaces:

  • Request Packet interface (referred to as the Strategy interface)
  • INT 21h interface
  • Generic IOCtl interface
  • Hardware Interrupt interface
  • Monitor Dispatcher Notification interface

Request Packet Interface

The file system is the primary component that interfaces with the parallel port device driver. In response to a function call, the file system creates a request packet containing the information required by the parallel port device driver to process the request. The file system then calls the parallel port device driver's strategy entry point, with the registers ES: BX containing the address of the request packet.

The Strategy interface uses the Call/Far return model and must preserve the caller's registers. The strategy entry point routes all IOCtl requests and all Open, Read, Write, Close, and Status requests to the appropriate internal parallel port device driver routines to handle the requests. For a description and format of a request packet, refer to the physical device driver strategy commands, which can be found in the OS/2 Physical Device Driver Reference.

Request Packet Command Summary

The command code field of a request packet contains the function requested of the physical device driver. The parallel port device driver is a character device driver and supports all character device driver functions.

A detailed description of these commands can be found in the OS/2 Physical Device Driver Reference.

Request Packet Status Description

On the call to the parallel port device driver, the status code is set to 0. On return from the physical device driver, the status code contains the results of the request (for example, done or error). The parallel port device driver sets the error bit, busy bit, done bit, and error code, when necessary.

Return Codes

The error codes that the parallel port device driver returns are listed below:

8102h Device not ready
8103h Unknown command
8109h Printer out of paper
810Ah Write fault
810Ch General failure
8111h Character I/O call interrupted
8113h Invalid parameter

If the parallel port device driver does not support a request, a status of 8103h (unknown command) is returned.

INT 21h Interface

An application running in a DOS session can access the parallel port device driver through INT 21h. The file system creates a request packet from the parameters and calls the parallel port device driver at its strategy entry point. This interface maintains compatibility with DOS applications. As in the Request Packet interface, the parallel port device driver preserves the caller's registers ES:BX and points to the request packet. The strategy entry point follows the Call/Far return model.

Generic IOCtl Interface

The parallel port device driver supports a set of generic IOCtl functions. Refer to the parallel port control IOCtl commands in the OS/2 Physical Device Driver Reference for a list and detailed description of these functions.

Note: From the command line, a user can start the MODE command to perform the parallel port control functions Set/Query Frame Control and Set/Query Infinite Retry. See the description of the MODE command in the OS/2 Command Reference.

Parallel Port Device Driver Support

All the Category 05h IOCtl commands are supported by the parallel port device driver. Additionally, the following IOCtls are also supported by the parallel port device driver:

Category 0Ah Character Monitor Control. Supported by the physical keyboard, mouse, and parallel port device drivers.

Function 40h Register (A character monitor)

Category 0Bh General Device Control. Supported by all the character device drivers.

Function 01h Flush input buffer

Function 02h Flush output buffer

Function 60h Query monitor support

Character Monitor Control

The IOCtl Category 0Ah "Register Monitor" (Function 40h), which can be found in the OS/2 Physical Device Driver Reference, is supported by the physical keyboard and mouse device drivers, as well as by the parallel port device driver. The index field of the data packet received on this call is device specific. That is, it is defined differently for each physical device driver. The index field generally indicates on which monitor chain an application wishes to register a monitor.

As previously discussed, the parallel port device driver creates two monitor chains for each parallel port device - a data chain and a code page chain. An application issuing this IOCtl function call to a specified parallel port device sets the index parameter as follows:

  • Index=1Registers a monitor with the data chain.
  • Index=2Registers a monitor with the code page chain.

Hardware Interrupt (8259) Interface

When a hardware interrupt is pending on an interrupt level owned by the parallel port device driver, the hardware interrupt manager calls the parallel port device driver's hardware interrupt entry point for that interrupt level. PRINT01.SYS runs parallel port devices using hardware interrupt levels IRQ 7 and IRQ 5. PRINT02.SYS runs parallel port devices on hardware interrupt level IRQ 7. The parallel port device driver for Micro Channel machines shares the hardware interrupt level IRQ 7.

Each of the parallel port device driver's hardware entry points call a parallel port device driver general interrupt routine. This routine sends the next character to the port, issues an EOI (End-Of-Interrupt), and completes a strategy request when the last character has been received by the device.

The hardware interrupt manager saves all registers before calling the parallel port device driver interrupt entry points. On return to the hardware interrupt manager, the parallel port device driver's general interrupt routine clears the carry flag, signalling the interrupt manager that the parallel port device driver owns the interrupt. If the parallel port device driver does not own the hardware interrupt, it sets the carry flag. The parallel port device driver's hardware interrupt routine follows the Call/Return Far model and does not handle nested interrupts.

Monitor Dispatcher Notification Interface

The OS/2 parallel port device driver supports character device monitors. For a description of how that support is provided, see #Parallel Port (Printer) Monitors.

Data sent to each parallel port device can be monitored before reaching the device by parallel port monitor applications registered with one of two monitor chains. When a parallel port monitor is registered, the parallel port device driver calls the MonWrite device helper runtime to place all requests (in the form of monitor records or packets) into its monitor chains. Each parallel port monitor registered on the monitor chain can monitor the data destined for the parallel port. Parallel port data that has passed through all monitors registered on the monitor chain is placed into a parallel port device driver monitor chain buffer by the OS/2 monitor dispatcher.

A monitor chain for a parallel port device is created when the parallel port device driver calls MonitorCreate. For each monitor chain, the parallel port device driver must provide:

  • A device driver monitor chain buffer, into which the monitor dispatcher places the filtered parallel port data after it has passed through all the parallel port monitors in the monitor chain.

The length of the parallel port device driver's monitor chain buffer is 134 bytes. This length is specified by the parallel port device driver in the first WORD of the buffer when MonitorCreate is called. The length of parallel port monitor input and output buffers, registered with a parallel port monitor chain, must be greater than or equal to 134 bytes plus 20 bytes.

  • The address of a notification routine that is called by the monitor dispatcher when it has placed filtered data into the monitor chain buffer.

Before the monitor dispatcher calls the parallel port device driver's notification routine, it:

1.Places a data record in the parallel port device driver's monitor chain buffer starting at the second WORD of the buffer

2.Places the length of the data record (in bytes) in the first WORD of the parallel port device driver's monitor chain buffer

3.Sets the register pair ES:SI to point to the parallel port device driver 's monitor chain buffer

The general monitor packet format for code page processing is described in the following table.

Field Length
Monitor Flags WORD
System File Number WORD
Command Byte BYTE
Reserved. Set to 0. BYTE
Reserved. Set to 0. BYTE
Reserved. Set to 0. BYTE
Return Code WORD
Code Page WORD
Font ID WORD

The general monitor packet format for Open, Write, Close, Status, and Print -Job-Title monitor requests is described in the following table.

Field Length
Monitor Flags WORD
System File Number WORD
Data to be Monitored (optional) 128 BYTES

Data items included in these data structures are defined in the descriptions of the corresponding request packet data structures. The parallel port device driver communicates with parallel port monitors using the monitor protocol.

Parallel Port Monitor Buffer Command

Each monitor record can be of variable length and contain a WORD of flags defining the type of monitor packet.

Note:Monitor packets that parallel port monitors do not understand should be returned to the parallel port device driver on the monitor chains from which they were received.

  Monitor Flags       Device-Driver Dependent

  Byte 0               Byte 1
 /---------------\    /---------------\
 |7|6|5|4|3|2|1|0|    |7|6|5|4|3|2|1|0|
 \---------------/    \---------------/
  | | | | | | | |      | | | | | | | |
  | | | | | | | \-Open | | | | | | | \-Printer Font Monitor
  | | | | | | \-Close  | | | | | | |    Buffer Command Response
  | | | | | \-Flush    | | | | | | \-Code Page Command Response
  | | | | \-Reserved   | | | | | \-INT 17H Code Page Request
  | | | \-Reserved     | | | | \-Status
  | | \-Reserved       | | | \-Reserved
  | \-Reserved         | | \-Job Title
  \-Reserved           | \-Reserved
                       \-Reserved

Monitor Open Packet

When the Open bit (byte 0, bit 0) is set to 1, the monitor buffer contains an open packet from the parallel port device driver. In this case, the next two bytes are:

Field Length
System File Number WORD

Monitor Close Packet

When the Close bit (byte 0, bit 1) is set to 1, the monitor buffer is a close packet from the parallel port device driver. In this case, the next two bytes are:

Field Length
System File Number WORD

Monitor Write Packet

When the Close bit (byte 0, bit 1) is set to 0, and the Open bit (byte 0, bit 0) is set to 0, the monitor buffer is a write data packet from the parallel port device driver. In this case, the next bytes are:

Field Length
System File Number WORD
Data to be Monitored 128 BYTES

Font Monitor Packet

When the Font Monitor Buffer Command/Response bit (byte 1, bit 0) is set to 1, the monitor buffer is a Font Monitor Buffer command. In this case, the next six bytes are:

Field Length
System File Number WORD
Command Byte BYTE
Reserved. Set to 0. BYTE
Reserved. Set to 0. BYTE
Reserved. Set to 0. BYTE

Byte 2-3 System File Number

Byte 4 Font Monitor Buffer Command byte, which indicates the type of command or response

Byte 5 Reserved. Must be set to 0

Byte 6-7 Reserved. Must be set to 0

When the Code Page Command Processed bit (byte 1, bit 1) is set to 1, the Font Monitor Buffer command has been processed by the spooler.

The parallel port device driver sends Font Monitor Buffer commands to its monitors through the data monitor chain (Index=1). A parallel port monitor, which services the Font Monitor Buffer command, sets the Code Page command processed bit and uses DosMonWrite to place the Font Monitor Buffer response into the code page monitor chain (Index=2). Data to be printed continues to flow on the data monitor chain. The code page monitor chain is used only for the Font Monitor Buffer responses, so the parallel port device driver does not block a program issuing a code page and font IOCtl request when print data monitor buffers are already queued ahead of the IOCtl request.

Font Monitor Buffer Commands:The valid Font Monitor Buffer commands, along with the remainder of the buffer contents for the responses, are as follows:

Byte 4 = 01h Activate Font. Command data, starting at byte 8:

Field Length
Return Code WORD
Code Page WORD
Font ID WORD

Return Code A value returned, starting at byte 8, which includes the following values:

0000h Successful completion
0002h Code page is not available
0003h No code page function, because spooler not started
0004h Font ID is not available (verify)
0009h Error caused by switcher error, not by input parameters
000Ah Error caused by invalid printer name as input
000Dh Received code page request, when code page switcher not initialized
000Fh SFN table full cannot activate another entry
0013h DASD error reading font file
0015h DASD error reading font file definition block
0017h DASD error, while writing to temporary spool file
0018h Disk full error, while writing to temporary spool file
0019h Spool file handle was bad Code Page. The value to assign to the currently active code page.
0000h If the Code Page value and Font ID are specified as 0, set printer to hardware default code page and font.
0001h-FFFFh Valid code page numbers.

Font ID The ID value of the font to make currently active.

0000h If the Code Page value and Font ID are specified as 0, set printer to hardware default code page and font.

If only the Font ID is 0 and the Code Page is a valid nonzero, then any font within the specified code page is acceptable.

0001h-FFFFh Valid Font ID numbers, which are font types defined by the font file definitions as fonts that can be downloaded. For cartridge fonts, Font IDs are the numbers on the cartridge label. They are also entered in the DEVINFO statement for the printer.

The parallel port device driver passes the Font Monitor Buffer command to the monitor on the data monitor chain (Index=1). The monitor returns the Font Monitor Buffer response to the parallel port device driver on the code page monitor chain (Index=2).

Byte 4 = 02h Query Active Font. There is no additional command data. Data returned from this function call includes:

Field Length
Return Code WORD
Code Page WORD
Font ID WORD

Return Code A value returned, starting at byte 8, which includes the following values:

0000h Successful completion
0003h No code page function, because spooler not started
0009h Error caused by switcher error, not by input parameters
000Ah Error caused by invalid printer name as input
000Dh Received code page request, when code page switcher not initialized
0010H Received request for SFN not in SFN table.

Code Page On return, is set to currently active code page:

0000h If the Code Page value and Font ID are returned as zero, the printer is set to the hardware default code page and font.
0001h-FFFFh Valid code page numbers.

Font ID On return, is the ID value of the Font, which is currently active:

0000h If the Code Page value and Font ID are specified as zero, the printer is set to the hardware default code page and font. A Font ID value of zero can indicate the default font of a particular code page.
0001h-FFFFh Valid Font ID numbers, which are font types defined by the font file definitions as fonts that can be downloaded. For cartridge fonts, Font IDs are the numbers on the cartridge label. They are also entered in the DEVINFO statement for the printer.

The parallel port device driver passes the Font Monitor Buffer command to the monitor on the data monitor chain (Index=1). The monitor returns the Font Monitor Buffer response to the parallel port device driver on the code page monitor chain (Index=2).

Byte 4 = 03h Verify Font. Command Data, starting at byte 8:

Field Length
Return Code WORD
Code Page WORD
Font ID WORD

Return Code A value returned, starting at byte 8, which includes the following values:

0000h Successful completion
0002h Code page is not available
0003h No code page function, because spooler not started
0004h Font ID is not available (verify)
000Ah Error caused by invalid printer name as input
000Dh Received code page request, when code page switcher not initialized.

Code Page The Code Page number to validate.

0000h-FFFFh Valid code page numbers.

Font ID The Font ID value to validate.

0000h-FFFFh Valid Font ID numbers.

The parallel port device driver passes the Font Monitor Buffer command to the monitor on the data monitor chain (Index=1). The monitor returns the Font Monitor Buffer response to the parallel port device driver on the code page monitor chain (Index=2).

Monitor Status Packet

When the Status bit (byte 1, bit 3) is set to 1, this indicates that the monitor buffer is a status packet from the parallel port device driver. In this case, the next four bytes are:

Field Length
System File Number WORD
Error Code BYTE
Reserved BYTE

The parallel port device driver sends either device not ready (02h), printer out of paper (09h), or write fault (0Ah) as the error code.

Monitor-Job Title Packet

A print-monitor job title packet passes the name of the file being printed to all monitors registered with the parallel port device driver.

When the job title bit (byte 1, bit 5) is set to 1, it indicates the monitor buffer is a job title packet from the parallel port device driver. In this case, the next bytes are:

Field Length
System File Number WORD
Job Title Length WORD
Job Title Buffer BYTES

The Job Title Length field includes the null character. The Job Title Buffer is terminated with the null character. The Job Title Buffer field contains bytes 6-131.

Sharing the Parallel Port With Other Device Drivers

The OS/2 parallel port device driver provides two functions in its physical device driver to physical device driver inter-device-driver communication ( PDD-PDD IDC) interface - request exclusive access and release exclusive access to the parallel port. The request exclusive access IDC function is used by device drivers to request sole ownership of the parallel port. The release exclusive access IDC function is used by device drivers to release sole ownership of the parallel port. Parameter passing is register-based and not stack-based.

Client device drivers use the DevHlp_AttachDD to obtain the OS/2 parallel port device driver IDC entry point. The client device driver requests sole ownership of the parallel port once it has work to perform and should release ownership of the parallel port once the work has completed. Client device drivers obtain and release sole ownership to the parallel port by loading the general purpose registers with the appropriate parameters and calling the OS/2 parallel port device driver.

After obtaining sole ownership of the parallel port, the client device driver should then obtain the resources it needs to perform the request ( including the hardware interrupt levels, DMA channels, and other shareable system resources). Prior to releasing ownership of the parallel port, the client device driver should release these other sharable system resources so that other client device drivers can obtain them. At a minimum, the client device driver should release ownership of the parallel port at the completion of a kernel write request packet. The process of sharing the parallel port only works when client device drivers cooperate with each other.

Exclusive port access can be overridden with the share access option in the parallel port settings dialog box of a print object. When this option is selected, all client device drivers requesting sole access to the parallel port are granted access. The parallel port device driver does not perform the serialization of access to the port. Users must perform the serialization by not trying to access two devices connected to the parallel port simultaneously. Otherwise, unpredictable results will occur.

The parallel port sharing feature is not available in the OS/2 2.1 (or later) product. It is available through the OS/2 Driver Development Support group and the IBM Developer Connection Device Driver Kit for OS/2.

Request Exclusive Access

Request Exclusive Access grants the calling device driver sole ownership of the parallel port until a Release Exclusive Access is issued.

Parameters
 AX = Function Code           ; 0 = Request Exclusive Access
 BX = Request Flags           ; Bit 0 = 0 Do not block
                              ; Bit 0 = 1 Block until available
 CX = Port ID                 ; LPT1 = 0, LPT2 = 1, LPT3 = 2
 DS = Data Selector           ; OS/2 PPDD Data Selector
 ES = Data Selector of caller ; DS of caller
Returns

No error

Carry Flag clear
AX = 0

Error

Carry Flag set
AX = Error code

Possible errors:

ERROR_I24_INVALID_PARAMETER
ERROR_I24_DEVICE_IN_USE
ERROR_I24_CHAR_CALL_INTERRUPTED

Release Exclusive Access

Release Exclusive Access releases the calling device driver from sole ownership to the parallel port. Sole ownership was granted when a Request Exclusive Access was issued.

Parameters

 AX = Function Code           ; 1 = Release Exclusive Access
 CX = Port ID                 ; LPT1 = 0, LPT2 = 1, LPT3 = 2
 DS = Data Selector           ; OS/2 PPDD Data Selector
 ES = Data Selector of caller ; DS of caller

Results

        No error
           Carry Flag clear
           AX = 0

        Error
           Carry Flag set
           AX = Error code
                Possible errors:
                ERROR_I24_INVALID_PARAMETER
                ERROR_I24_DEVICE_IN_USE

Physical Bidirectional Parallel Port Device Driver

The OS/2 base device driver, PAR1284.SYS, is a bus-independent device driver that supports bidirectional communication across the parallel port to bidirectional capable peripherals. The protocol is described as half-duplex (either the host or peripheral can transmit at a given point in time) in a master-slave relationship (the host determines who can transmit and when).

Overview

The OS/2 bidirectional parallel port device driver supports the Standard Parallel Port (SPP) in compatible, FIFO, and extended mode and supports the Extended Capabilities Port (ECP) in standard, PS/2, FIFO and ECP FIFO modes.

The enhanced parallel port modes, while maintaining compatibility with the "classic" IBM PC parallel port, also provide FIFO buffer capability for improved performance, several modes which enable bidirectional data transfer (nibble mode, byte mode, and ECP mode), and a mode that enables hardware controlled handshaking of multiple data bytes in both directions ( ECP FIFO mode). The FIFO mode generates the lowest CPU overhead thus providing improved system response for the user while data is being transfered to/from the peripheral.

ECP mode also includes a method for addressing multiple devices attached to the same ECP capable port. This feature enables other software to be written to control multifunction office devices such as a FAX/scanner/ printer/copier machine attached with a single cable to an ECP parallel port on the computer.

The bidirectional parallel port device driver conforms to the Standard Signaling Method for a Bidirectional Parallel Peripheral Interface for Personal Computers (IEEE 1284-1994) for bidirectional communications. Bidirectional communication enables the host system (IBM PC compatible) to communicate with the peripheral and the peripheral to communicate with the host. The bidirectional communication protocols supported are nibble, byte , and ECP modes.

Typically, the host communicates with the peripheral for identification, configuration, and status information. The identification data can be used to auto configure the system with the correct device drivers for the specific device. Configuration data can be returned to the device driver so that the user can make decisions based upon actual configuration rather than possible configuration. Status data can be used to present real time information to the user by way of an interactive graphical application. A remote operator panel is an example of an interactive graphical application for a printer. The application can display a window in the likeness of the operator panel found on the front of a printer. The user is able to make menu selections from a remote system without having to be physically next to the printer.

Installation

The bidirectional parallel port device driver should be installed to the \OS2\BOOT directory of the OS/2 partition on your disk. The BASEDEV=PAR1284.SYS statement must exist in the CONFIG.SYS file. The BASEDEV=PRINT0?.SYS statement (where ? can be 1 or 2 as appropriate) must be removed from the CONFIG.SYS file. The OS/2 operating system must be shutdown and restarted for the bidirectional parallel port device driver to become active.

Functional Support

The bidirectional parallel port device driver is a functional replacement for the OS/2 parallel port device drivers (PRINT01.SYS and PRINT02.SYS). The bidirectional parallel port device driver supports the following strategy commands:

  • open
  • read
  • write
  • close
  • ioctl
  • input flush
  • output flush
  • initialize device driver
  • initialization complete

For more information on the IOCtl commands supported, refer to the Category 05h Parallel Port Control IOCtl Commands found in the Physical Device Driver Reference.

Character Monitors

The bidirectional parallel port device driver does not support character monitors and therefore does not support the category 0Ah and 0Bh monitor IOCtl commands. It also does not support the following category 05h Parallel Port Control IOCtl commands related to code page and font switching (previously performed by a character monitor).

  • Activate Font
  • Query Active Font
  • Verify Font

The PRINTMONBUFSIZE=CONFIG.SYS statement is not used by the bidirectional parallel port device driver.

Parallel Port Timeout Processing

The bidirectional parallel port device driver supports timeout processing on an inter-character and a request packet basis for both read and write requests. For more information on the timeout IOCtl commands supported, refer to the Category 05h Parallel Port Control IOCtl commands found in the Physical Device Driver Reference.

Sharing the Parallel Port With Other Device Drivers

Refer to #Sharing the Parallel Port With Other Device Drivers for details on how this function works. The bidirectional parallel port device driver provides this capability.

Parallel Port Device Driver Test Tool

This chapter explains how to use the parallel port Device Driver Test Tool.

Overview

The parallel port Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of parallel port device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate parallel port function and performance. Errors are reported and are isolated to a specific test sequence and API.

User input and output from each thread of the parallel port tests is performed by way of a separate Presentation Manager window. Test cases log all information to a log files, clearly indicating the actual execution sequence in the event of errors.

Parallel Port Test Architecture

The DDTT provides a common front-end parser for test-case scripts. The following DDTT parallel-specific files are required:

  • DDTPARA.DLL
  • PARALLEL.GRA
  • GEN.GRA - needed for test script file, REQEX.SCR
  • GENDRV.SYS - needed for test script file, REQEX.SCR

The C++ source code for DDTPARA.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2.

The following required, common components of the DDTT implement the DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:

  • DDTT.EXE
  • DDTT.DLL
  • GLOBAL.DLL
  • GLOBAL.GRA

Ioddr-05.gif

Installation

There are two directory structures that utilize test suites in the IBM Developer Connection Device Driver Kit for OS/2. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL.

The following procedure describes installation for running test cases:

1. Copy the executable and parallel port test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TESTPARA. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TESTPARA and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the parallel port test suite:

   [C:\]md testpara
   [C:\]cd testpara
   [C:\testpara]copy e:\ddk_x86\testcert\inputout\function\parallel\*
   [C:\testpara]copy e:\ddk_x86\testcert\general\ddtt\*

2. Add the C:\TESTPARA to the LIBPATH and PATH in the CONFIG.SYS file.

3. For script testcase REQEX.SCR, which requests and releases exclusive access, a generic driver named GENDRV.SYS must be installed. Edit your system's CONFIG.SYS file and add the following line:
 DEVICE=c:\testpara\gendrv.sys

4. Reboot your machine so the new LIBPATH entry and DEVICE statement take effect.

Test-Case Execution

The DDTT parallel port tests must be executed on a directly-attached printer device. These tests will not work when executed against a printer device accessed by way of a network connection.

There are two ways to run parallel port tests. To run the program from a command file, be sure the files are installed in the current directory. Then, execute the TESTFONT or TESTPARA command files. The command file will run a set of script files. The TESTFONT executes scripts related to font testing and requires the spooler to be enabled. The TESTPARA executes scripts using other printer functions that require the spooler to be disabled.

To run one script file at a time, see #Description of Test Cases of the file to get a description of each script file. Then, after determining which script file to run, type in DDTT followed by the script file name:

 [C:\TESTPARA]DDTT QFONT.SCR

After the script has finished executing, control will transfer back to the OS/2 Window. If the script files are run individually, and a TESTxxx command file has not been run first, then run SETINFO to set up your printer device.

There are three different sets of script files in the DDTT parallel port package. The first set is the font script files, the second set is the general printer script files, and the third is only one script file, REQEX. SCR, which requests and releases exclusive access. When TESTFONT or TESTPARA is run, it will ask for the printer device (such as LPT1 or LPT2).

The SETINFO command file will set up the necessary information that is needed for the parallel port script files. The command file will ask the following question:

 PLEASE ENTER THE OUTPUT PORT OF YOUR PRINTER, SUCH AS LPT1

After this information is entered, the command file will store this information in the SYSINFO.TXT file. The contents of the file is

PARA SET DEVICENAME=LPT1

DDTT Parallel Port Test Grammar Function Calls

The following is a list of the DDTT Parallel Port Test Grammar Function Calls:

  • PARA_OPEN
  • PARA_CLOSE
  • PARA_SETRAMECTRL
  • PARA_SETRETRY
  • PARA_INIT
  • PARA_ACTIVATEFONT
  • PARA_SETTITLE
  • PARA_SETWRTTIMEOUT
  • PARA_QFRAMECTRL
  • PARA_QRETRY
  • PARA_QPORT
  • PARA_QACTIVEFONT
  • PARA_VERIFYFONT
  • PARA_QWRTTIMEOUT
  • PARA_READFILE
  • PARA_WRITEFILE

PARA_OPEN

This function opens the given parallel port.

Input Parameter Keywords
Keyword Type Description
DEVICENAME STRING Output port identification, such as LPT1
Output Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
Logged Data

None.

PARA_CLOSE

This function closes the opened parallel port.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
Output Parameter Keywords

None.

Logged Data

None.

PARA_SETFRAMECTRL

Category 05h - Function 42h

This function sets frame control (characters-per-line, lines-per-inch).

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
CPL NUM Characters-per-line
LPI NUM Lines-per-inch
Output Parameter Keywords

None.

Logged Data

Frame Control Message with characters-per-line and lines-per-inch.

PARA_SETRETRY

Category 05h - Function 44h

This function sets infinite retry on/off (0=OFF, 1=ON).

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
RETRY NUM ON or OFF setting
Output Parameter Keywords

None.

Logged Data

Retry state Message with Infinite Retry Disabled/Enabled

PARA_INIT

Category 05h - Function 46h

This function initializes parallel port.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
Output Parameter Keywords

None.

Logged Data

None.

PARA_ACTIVATEFONT

Category 05h - Function 48h

This function activates a font.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
CODEPAGE NUM Number of code page
FONTID NUM Number of font
Output Parameter Keywords

None.

Logged Data

Font information Message with CODEPAGE and FONTID

PARA_SETTITLE

Category 05h - Function 4Dh

This function sets job title.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
JOBTITLE STRING Job title identification
Output Parameter Keywords

None.

Logged Data

Job title information Length and address with job title information.

PARA_SETWRTTIMEOUT

Category 05h - Function 4Eh

This function sets write timeout.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
PPWRTTIMEOUT NUM Seconds for write timeout
Output Parameter Keywords

None.

Logged Data

Write time out value Parallel Port Write Time Out Value in seconds

PARA_QFRAMECTRL

Category 05h - Function 62h

This function queries frame control (characters-per-line, lines-per-inch).

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
Output Parameter Keywords

None.

Logged Data

Frame Control Message with characters-per-line and lines-per-inch.

PARA_QRETRY

Category 05h - Function 64h

This function queries infinite retry.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
Output Parameter Keywords

None.

Logged Data

Retry state Message with Infinite Retry Disabled/Enabled

PARA_QPORT

Category 05h - Function 66h

This function queries port.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
Output Parameter Keywords

None.

Logged Data

Data Value in data field

PARA_QACTIVEFONT

Category 05h - Function 69h

This function queries active font.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
Output Parameter Keywords

None.

Logged Data

Font information Message with CODEPAGE and FONTID

PARA_VERIFYFONT

Category 05h - Function 6Ah

This function verifies font.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
CODEPAGE NUM Number of code page
FONTID NUM Number of font id
Output Parameter Keywords

None.

Logged Data

Font information Message with CODEPAGE and FONTID

PARA_QWRTTIMEOUT

Category 05h - Function 6Eh

This function queries write time out.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
Output Parameter Keywords
None.
Logged Data

Time out information Message with PP Write Time Out Value in seconds.

PARA_READFILE

This function reads a file.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
FILENAME STRING File to be read
BYTECOUNT NUM Number of bytes to read
$BUFFER STRING Buffer to hold data
Output Parameter Keywords
None.
Logged Data
None.

PARA_WRITEFILE

This function writes a file.

Required Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Handle number of output parallel port
FILENAME STRING Name of file to write
$BUFFER STRING
Output Parameter Keywords
None.
Logged Data
None.

Description of Test Cases

Each of the parallel port test cases can be executed individually as previously described. The corresponding test scripts are described below. The user can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the parallel grammar file.

All of the parallel port test cases use the DDTT @IMPORT command to include one script file:

  • SYSINFO.TXT
    The content of the SYSINFO.TXT files is set by the SETINFO.CMD command file. SETINFO.CMD should be executed once to establish values for the following DDTT parameter keywords:
  • DEVICENAME - drive name of the parallel port device under test, such as LPT1.

All test scripts open and close the parallel port device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name and a file name extension .LOG. When current status is queried (for example, the font, timeout, or port), this data is written to DDTT's output windows and to the log file. Log files can be examined after the test case has completed.

ACTFONT.SCR
Activates and logs the font identified by the CODEPAGE and FONTID.
FRAMES.SCR
Sets and queries the frame controls for four combinations of characters-per-line and lines-per-inch.
INITPAR.SCR
Initializes the parallel port.
QFONT.SCR
Queries the activefont, logging, CODEPAGE, and FONTID.
QFRAME.SCR
Queries frame control, logging characters-per-line, and lines-per-inch settings.
QPARPORT.SCR
Queries the parallel port and logs the value in the data field.
QPPWTOUT.SCR
Queries write time out and logs time, in seconds.
QRETRY.SCR
Queries to determine if infinite retry is enabled.
REQEX.SCR
Requests exclusive access of LPT1 and displays Have exclusive access, pauses for two minutes, and then releases exclusive access. This process requires installation of the generic device driver, GENDRV.SYS.
RETRY.SCR
Enables infinite retry, queries retry, disables infinite retry, and queries retry, again.
SETFRAME.SCR
Sets frame control of 80 characters-per-line and 6 lines-per-inch.
SPPWTOUT.SCR
Sets parallel port write time out value to 10 seconds.
SRETRY.SCR
Sets infinite retry enabled.
TITLERD.SCR
Sets jobtitle to BIDI TEST JOB-TITLE, reads file READ.SCR, and writes file.
VFONT.SCR
Verifies font with CODEPAGE=34000 and FONTID=34000.

Evaluation of Test Case Results

Unless otherwise stated in the test-case descriptions, all test cases are expected to succeed. If a test case fails in a mode detectable by DDTT, then the token "ERROR" will be written to the corresponding log file.

The script files test all of the different parallel port functions. After each script file has finished executing, it will log all of the test information out to a log file. When all of the script files have finished executing, the command file will search all of the log files for any errors that have occurred. The results from this search are stored in the RESULTS.TXT file.

When the command file has completed searching the log files, it also displays the results on the screen. The command file is searching only for the word "ERROR".

PCMCIA Architecture

This chapter contains a description of the Personal Computer Memory Card International Association (PCMCIA) hardware and software architecture as it applies to the OS/2 operating system. Also included is a list of supported functions, and information on deviations from the PCMCIA standard. In addition, information regarding Card Services, COM Support, Socket Services , Socket Services Sample, Client Driver Sample, and Fax/Modem client services are discussed.

Overview

PCMCIA is an organization of computer hardware and software manufacturers that is developing industry standards for personal computer card architecture and design. The PCMCIA standards include specifications for both the hardware and software components of the technology.

PCMCIA Hardware

There are three major hardware components defined in the PCMCIA standard:

  • Cards
  • Sockets
  • Adapters

The cards come in several standardized sizes and shapes that are called form factors. The basic form factor is very similar to a credit card. There is a wide range of potential applications for PCMCIA cards, including:

  • Connectivity devices, such as modems, local area networks (LANs), and terminal emulators
  • Secondary storage devices, such as mini rotating hard disks, solid state file disks, and flash
  • Random access memory, such as SRAM, DRAM, or NVRAM memory
  • Storage for software, such as applications, device drivers, and ROM extensions

PCMCIA cards are treated in much the same way as standard removable media such as diskettes. The card slots, or sockets, are open bays into which the PCMCIA cards can be inserted without removing the system covers or turning off the system unit. Some PCMCIA Sockets contain mechanisms similar to those on diskette drives such as levers and locks.

Adapters are connected to the host system's bus. The adapters map the host system bus technology to the PCMCIA technology. According to PCMCIA standards, up to 256 adapters can exist on a host system, and each adapter can have a maximum of 16 sockets.

PCMCIA Software

There are three major software components defined in the PCMCIA architecture:

  • Clients
  • Card Services
  • Socket Services

Clients manage the device characteristics in an operating-system-specific environment and can be generalized as card-specific device drivers. Therefore, for any given card (device), there must be a specific device driver for each supported operating system. In addition, one client device driver can simultaneously manipulate several cards of the same type. Clients rely on the Card Services interfaces to set up and remove accessibility to the PCMCIA cards. The functions, features, and availability of client device drivers are the responsibilities of the PCMCIA card developer or the manufacturer.

The Card Services component is an operating-system-specific layer that provides the Card Services functions defined in the PCMCIA interface specification. The Card Services interface functions are provided according to the operating system's specifics for the client device driver model environment. Card Services rely on operating system and Socket Services interfaces to facilitate requests from PCMCIA clients. The functions, features, and availability of the Card Services component are the responsibilities of the operating system developer or manufacturer.

The Socket Services component is a hardware-specific layer that isolates the details of the adapter and socket logic from the other software components. The Socket Services component provides the functions defined in the PCMCIA interface specification. Ideally, this software layer is built as a BIOS extension so that a single implementation can service multiple operating systems. However, it is acceptable to have device driver versions , because several situations preclude the availability of ROM solutions (as would be the case when you are adding adapters into existing host systems). The functions, features, and availability of the Socket Services component are the responsibilities of the hardware (adapter option or system unit) developer or manufacturer.

PCMCIA Specifications

The PCMCIA General Committee publishes the following specifications for the software architecture components:

PCMCIA Card Services Release 2.00 Interface Specification

PCMCIA Socket Services Release 2.00 Interface Specification

These specifications contain a complete description of the Card Services and Socket Services functions described in this chapter. They can be ordered from:

 PCMCIA Office 
 1030G East Duane Avenue 
 Sunnyvale, CA 94086 
 
 (408) 720-0107 Voice 
 (408) 720-9416 FAX 
 (408) 720-9388 BBS

OS/2 PCMCIA Environment

There are three separate PCMCIA client environments in the OS/2 operating system: the DOS environment, WIN-OS/2 environment, and OS/2 environment. Each of these client environments has a separate Card Services interface binding (or protocol) that encapsulates the Card Service functions into the native environment's characteristics. Although the OS/2 operating system supports these three application environments, it currently does not support the PCMCIA client interfaces in all environments.

The responsibilities and restrictions of providing support for these client environments is summarized as follows:

  • OS/2 Card Services is responsible for providing the client environment interfaces.

Currently this support is limited to the native OS/2 device-driver environment for OS/2 physical device drivers. The OS/2 client environment support is provided by the OS/2 Card Services and the physical device driver contained in the file named PCMCIA.SYS. The interface bindings for this support are defined in Client Interfaces.

The architecture is designed such that the PCMCIA software components mask the hardware details from the OS/2 application environments. The concept of a PCMCIA-aware application does not apply in the OS/2 operating system.

The DOS client environment is not supported. This means that the DOS PCMCIA interfaces, INT 1Ah functions in the range of 80h - AFh, are intercepted and rejected with the Carry flag set (value = 1). The DOS client environment support is provided by the OS/2 Card Services and virtual device driver contained in the file named VPCMCIA.SYS.

The WIN-OS/2 client environment is not supported.

At this time, the industry has not defined an interface binding for the WIN -OS/2 client environment; therefore, there are no OS/2 files provided for this environment.

  • OS/2 PCMCIA clients are responsible for providing device-specific support in the desired application environments.
  • OS/2 PCMCIA clients can be written as stand-alone physical device drivers or as physical/virtual device driver pairs. If the desired client device support is limited to OS/2 application environments, the client can be a single physical device driver. If the desired application environments include a DOS or WIN-OS/2 environment, or both, then a virtual device driver also must be provided to emulate the device characteristics in those environments.

OS/2 Initialization Architecture

The following steps describe the initialization flow of the PCMCIA software components in the OS/2 operating system. Card Services, the Resource Management Utility, and Socket Services are implemented as base devices (BASEDEV=). These BASEDEV drivers initialize in the order in which they occur in CONFIG.SYS, prior to any client drivers. Client drivers, unless they are ADDs, should be implemented as non-base device drivers (DEVICE=). After the BASEDEV drivers, the client drivers will then initialize in the order in which they occur in CONFIG.SYS.

  1. Card Services Initialization
    The Card Services component is implemented as an installable physical device driver. This component manages resources (I/O address space, IRQs, and memory) across the set of installed client device drivers and Socket Services. The Card Services component assumes that a default set of resources is available when it is initialized, and then adjusts the resource information (see Step 2) to limit or expand this resource base. The base set of resources that the Card Services component assumes are available to be managed, is defined as follows:
    • Non-system memory in the range C0000h - DFFFFh
    • IRQs in the range 2 through 15
    • I/O addresses in the range 0108h through FFFFh, with the following exceptions:
      • Addresses 3B4h, 3B5h, 3BAh, 3BBh, and 3C0h through 3DFh are reserved for video use.
      • Addresses 3F0h through 3F7h are reserved for diskette use.
  2. Resource Map Initialization
    The Resource Map utility program is a special client device driver that determines the current system's hardware resource pool. This client is a hardware-specific device driver that performs the resource pool determination in a hardware-specific manner.
    The Resource Map utility program determines the system's resource information and informs Card Services by way of the AdjustResourceInfo (35h) function during BASEDEV INIT (1Bh) command processing. If an incorrect Resource Map utility program or no Resource Map utility program is loaded, Card Services continues to run, managing the default set of resources it assumed were present. (See Step 1).
    Because the Resource Map utility program is hardware-specific, it is provided by the hardware manufacturer on either the diskette that came with the computer or the diskette that came with the PCMCIA adapter.
  3. Socket Services Initialization
    a. One or more Socket Services device drivers can be loaded into the operating system to support the adapters in the system unit. As each Socket Services device driver loads, it must verify the required hardware dependencies. During the BASEDEV INIT command (1Bh) processing, Socket Services device drivers must complete their inter-device-driver communication (IDC) initialization processing by calling the DevHlp_ AttachDD function. If Card Services is loaded, the request for an IDC entry point for the device driver name "PCMCIA$ " (PCMCIA$, followed by a blank space) returns the 16:16 protect-mode information. The Socket Services device drivers then call the Card Services AddSocketServices (32h) function to establish the bidirectional IDC interface links. If the AttachDD request fails, the Socket Services device driver must free any allocated resources and permit itself to be swapped out of the active system memory as needed.
    b. Card Services processes the AddSocketServices (32h) function by:
    1. Identifying the Socket Services resources required.
      Card Services uses the following Socket Services functions to determine setup resources: GetAdapterCount (80h), GetSSInfo (83h), GetVendorInfo (9Dh), InquireAdapter (84h), GetAdapter (85h), InquireSocket (8Ch), and GetSocket (8Dh).
    2. Allocating resources from the resource map for Socket Services.
      Card Services assigns resources for the new Socket Services support, if available.
  4. Installing interrupt handlers for the Socket Services hardware.
    Card Services uses the DevHlp_SetIRQ function to establish the adapter-specific interrupt handling routine for each adapter supported by the Socket Services currently initializing.
  5. Programming the Socket Services hardware for the allocated resources.
    Card Services uses the following Socket Services functions to activate the adapter hardware: SetAdapter (86h), SetSocket (8Eh).
  6. COM.SYS Physical Device Driver Initialization
    The COM physical device driver provides a set of additional client device driver IDC interfaces for transparent application support. (See COM Support for more details).
    During initialization processing, the COM physical device driver determines if the special COM client device driver interface support is needed. It then loads or discards the support modules appropriately. The determination is made by issuing the DevHlp_AttachDD with the device driver name "PCMCIA$" (PCMCIA$, followed by a blank space) specified for the Card Services physical device driver.
  7. Client Device Driver Initialization
    Several client device drivers can be loaded into the operating system to support the various cards that might be plugged into the system's PCMCIA sockets. The initialization processing for these PCMCIA client device drivers is minimal. The card must be initialized on an as-needed basis because a card can be inserted into a socket at any time. To be ready for events such as CARD_INSERTION, the client device driver must establish an IDC interface connection into Card Services. The IDC link is established during either the INIT command (00h) or the INIT_COMPLETE command (1Fh) processing, by using the DevHlp_AttachDD function. If Card Services is loaded, the request for an IDC entry point for the device driver name "PCMCIA$" returns the 16:16 protect-mode information. If the AttachDD request fails, the client device driver must enter a dormant state equivalent to the wait state that would be entered when a card is not present. As soon as the presence of Card Services is confirmed and the interface address is retrieved, the client device driver issues the RegisterClient request and enters the normal mode of event processing.

OS/2 PCMCIA Client Device Driver Model

The client device driver model is an important element of the OS/2 PCMCIA architecture. The PCMCIA client device driver model is a more restricted form of the general OS/2 device driver model. All OS/2 PCMCIA client device drivers are loaded during startup of the operating system. Therefore, before PCMCIA devices can be used, the user must determine the types of PCMCIA cards that might be used with the system, install the associated client device drivers, and add the appropriate statements to the CONFIG.SYS file. Client device drivers should be installed using the OS/2 DDINSTAL utility program because it simplifies device-driver installation for the user.

The OS/2 PCMCIA client device driver model utilizes the multisegment support available in the OS/2 operating system. Whenever a client device driver is not active (that is, no card is present), it should unlock its swappable/relocatable segments. The single, nonswappable/nonrelocatable base code segment must be organized so that it contains all the public entry points externalized by the client. In this way, all client public addresses are guaranteed to be valid. For example, the client device driver should ensure that the strategy, interrupt, Card Services callback, and other optional IDC entry point handling routines reside in the single, base code segment.

All worker routines should be placed in additional code segments and further organized for optimal paging. These additional code segments should be organized to contain routines that are used with approximately the same frequency intervals and conditions.

After all the needed unlocked segments have been reestablished in the system memory space, all resources required by a client must be requested from the operating system or Card Services after the notification of the card presence (through a CARD_INSERTION event).

Because it is possible to have numerous inactive client device drivers loaded in the operating system, the potential savings in unused system memory space is substantial.

Note: The previous information on the OS/2 multisegmented device driver model and DDINSTAL utility program also are applicable for device driver implementations of Socket Services.

For further details on the OS/2 multisegmented device driver model, refer to the OS/2 Physical Device Driver Reference.

Event Processing Flow

The following is a generalized event processing flow for the definition of responsibilities within the OS/2 PCMCIA environment. The following steps are provided for the CARD_INSERTION and CARD_REMOVAL events.

Note:The following scenario has been simplified for descriptive purposes. In addition, the defined scenario represents only the actions used to manage I/O card support. There are numerous combinations of Card Services and Socket Services functions, as well as ordering differences, when this scenario is broadened to include other events.

1.Hardware Interrupt (Adapter)

The user inserts a PCMCIA Card into a socket. The adapter raises a Status Change interrupt to Card Services. Card Services, which has installed interrupt handlers for each adapter, calls the Socket Services AcknowledgeInterrupt (9Eh) function to retrieve the socket ID that generated the interrupt. Card Services sets up a global context hook handler to process the interrupt, issues the EOI for the adapter IRQ, and returns from the interrupt.

2.CARD_INSERTION Events

a.When the Card Services context hook handler gets control, it processes the pending interrupt information by calling the Socket Services GetStatus (8Fh), GetSocket (8Dh), and SetSocket (8Eh) functions to retrieve the specific interrupt meaning. In this scenario, the CardStateand SocketStatefield values indicate a card insertion. Therefore, the Card Services timer handler creates CARD_INSERTION events and sends them to all client device drivers registered for the affected socket.

b.Each client device driver registered for the socket receives a CARD_ INSERTION event notification. Client device drivers process the event by calling the Card Services GetConfigurationInfo (04h) function to determine if the card has been claimed by another client and to identify the card's attributes. The client might also query more card data from the Card Information Structure (CIS) tuples by using the Card Services GetFirstTuple (07h), GetNextTuple (0Ah), and GetTupleData (0Dh) functions.

If the client determines that the card cannot be supported, it returns from the event notification. If the client determines that the card can be supported, it uses the Card Services RequestIO (1Fh), RequestIRQ (20h), and RequestConfiguration (30h) functions to allocate resources to manage the card. If the resources are not available, the client returns from the event notification. If the resources are available, the client issues a DevHlp_ SetIRQ request to hook its interrupt handler into the operating system's IRQ chain.

Clients that use the COM IDC function should issue the Install function at this time, to map the device into the general COM application support. See COM Support for more details.

Note:Clients might receive two event notifications if the local and global event masks both have CARD_INSERTION events selected by way of the Card Services RegisterClient (10h) and SetEventMask (31h) functions.

c.Card Services processes the RequestConfiguration function (30h) by calling Socket Services SetSocket (8Eh) to program the adapter/card to the configuration information that has been locked for that socket.

3.Normal Device Activity

The client device driver uses the card-configured resources to perform normal device-specific manipulations, such as reading and writing data, processing device interrupts, and enacting device commands.

4.Hardware Interrupt (Adapter)

The user removes a PCMCIA Card from a socket. The adapter raises a Status Change interrupt to Card Services. Card Services calls the Socket Services AcknowledgeInterrupt (9Eh) function to retrieve the socket ID that generated the interrupt. Card Services sets up the interrupt processing context hook handler, issues the EOI for the adapter IRQ, and returns from the interrupt.

5.CARD_REMOVAL Events

a.When the Card Services timer handler gets control, it processes the pending interrupt information by calling the Socket Services GetStatus (8Fh ), GetSocket (8Dh), and SetSocket (8Eh) functions to retrieve the specific interrupt meaning. In this scenario, the CardStateand SocketStatefield values indicate a card removal. Therefore, the Card Services timer handler creates CARD_REMOVAL events and sends them to all client device drivers registered for the affected socket.

b.Each client device driver registered for the socket receives a CARD_ REMOVAL event notification. Client device drivers process the event by releasing Card Services resources (for example, by calling the Card Services ReleaseConfiguration (1Eh), ReleaseIO (1Bh), and ReleaseIRQ (1Ch) functions). In addition, the client device driver releases system resources (for example, by calling the DevHlp_UnsetIRQ function).

Clients that use the COM IDC functions should issue the Deinstall function at this time to map the device into the general COM application support. The COM IDC client should issue the Deinstall function prior to releasing the Card Services resources or system resources associated with the device. See COM Support for more details.

c.Card Services processes the ReleaseConfiguration request by calling Socket Services Set Socket (8Eh) to reprogram the socket so that it stops generating interrupts and cannot be accessed through the previously configured I/O addresses.

d.Card Services processes the ReleaseIO (1Bh) and ReleaseIRQ (1Ch) functions by returning the referenced resources to the resource map. This makes them available for subsequent request function calls.

Card Services

The following includes implementation limitations and restrictions and client interfaces.

Implementation Limitations and Restrictions

There are some restrictions on OS/2 PCMCIA client device drivers. These restrictions define Card Services support. The following can be supported by Card Services:

  • A maximum of four adapters
  • A maximum of eight sockets
  • A maximum of 16 clients
  • A maximum of four Socket Services drivers
  • A maximum of 16 memory technology drivers
  • A maximum of 16 memory handles
  • A maximum of 16 erase queues
  • A maximum of 16 regions
  • A maximum of 16 partitions
  • A maximum of seven windows per socket

The maximum window count is further defined such that five are memory windows (four for clients and one for Card Services), and two are I/O windows.

The following are not supported or provided by Card Services:

  • Paged memory windows
  • ROM BIOS Socket Services
  • Power management support. Even though some of the interfaces have power management definitions, the values are ignored by Card Services. For future compatibility, the power management bit always should be reset to 0.
  • Write protection. Even though some of the interfaces have write-protect definitions, the values are ignored by Card Services. For future compatibility, the write-protect bit always should be reset to 0.

The following additional restrictions apply to client device drivers that manage PCMCIA cards with secondary storage devices:

  • During device-driver initialization, the PCMCIA secondary storage card might not be present, but the device driver must still claim the required number of drive letters that it supports.
  • Multi-partitioned cards must have a drive letter assigned to each partition for the partition to be accessible.
  • All secondary storage cards are treated as removable media. This prohibits enhanced performance from file systems using cached support.

Client Interfaces

The PCMCIA Card Services architecture consists of several basic interface elements. These interface elements are necessary for generating a composite binding for client device driver developers. The binding itself provides bidirectional validation of the PCMCIA architecture and the operating system implementation. The basic interface elements are:

  • Functions
  • Callbacks
  • Events
  • Memory Technology Driver Helpers
  • Media Access Routines
  • Return Codes

OS/2-specific descriptions for each of these elements are in the following sections.

In addition to the PCMCIA-architected interface elements listed previously, the OS/2 Card Services support has reserved Generic IOCtl - Category 0Dh for future use as a PCMCIA application programming interface.

Functions

OS/2 supports the following PCMCIA Card Services functions:

AddSocketServices         (32h)    AdjustResourceInfo        (35h)
CheckEraseQueue           (26h)    CloseMemory               (00h)
CopyMemory                (01h)    DeregisterClient          (02h)
DeregisterEraseQueue      (25h)    GetCardServicesInfo       (0Bh)
GetClientInfo             (03h)    GetConfigurationInfo      (04h)
GetEventMask              (2Eh)    GetFirstClient            (0Eh)
GetFirstPartition         (05h)    GetFirstRegion            (06h)
GetFirstTuple             (07h)    GetNextClient             (2Ah)
GetNextPartition          (08h)    GetNextRegion             (09h)
GetNextTuple              (0Ah)    GetStatus                 (0Ch)
GetTupleData              (0Dh)    MapLogSocket              (12h)
MapLogWindow              (13h)    MapMemPage                (14h)
MapPhySocket              (15h)    MapPhyWindow              (16h)
ModifyConfiguration       (27h)    ModifyWindow              (17h)
OpenMemory                (18h)    RegisterClient            (10h)
ReadMemory                (19h)    RegisterEraseQueue        (0Fh)
RegisterMTD               (1Ah)    ReleaseConfiguration      (1Eh)
ReleaseExclusive          (2Dh)    ReleaseIO                 (1Bh)
ReleaseIRQ                (1Ch)    ReleaseSocketMask         (2Fh)
ReleaseWindow             (1Dh)    ReplaceSocketServices     (33h)
RequestConfiguration      (30h)    RequestExclusive          (2Ch)
RequestIO                 (1Fh)    RequestIRQ                (20h)
RequestSocketMask         (22h)    RequestWindow             (21h)
ResetCard                 (11h)    ReturnSSEntry             (23h)
SetEventMask              (31h)    SetRegion                 (29h)
ValidateCIS               (2Bh)    WriteMemory               (24h)

The PCMCIA Card Services function notation is defined for the OS/2 operating system as a register-based interface with the following register- to-argument assignments:

Input:

 [AL]             = Function argument
 [AH]             = Static AFh value
 [DX]             = Handle argument
 [DI]:[SI]        = Pointer argument
 [CX]             = ArgLength argument
 [ES]:[BX]        = ArgPointer argument

All other registers are undefined.

Output:

[AX]            = Status argument
Carry Flag      = Completion flag

All other registers are reserved.

Card Services is invoked using the protect-mode IDC entry point information returned by the DevHlp_AttachDD function. Card Services IDC entry point functions are callable only in kernel-context mode. The caller must do the following:

  • Operate in a Far Call/return model.
  • Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface.
  • Ensure that an appropriate stack is used for the calling model (16-bit protect mode) with at least 512 bytes of available stack space.
  • Establish the Card Services DS register value (from the information returned by AttachDD) prior to issuing Card Services function requests.

Card Services performs parameter-range checking on items directly managed and numbered. Card Services does not check each parameter on entry, but checks only those with values specified for the requested function. For example, Card Services determines if the logical socket number is valid or if a card is present in the socket being addressed. Card Services does not check if the card offset address is valid or if the unused input parameters contain null or zero values. For compatibility purposes, define all input values according to the guidelines outlined in the PCMCIA Interface Specification.

Callbacks

Card Services callbacks are events grouped into logical subsets, which include a general description and common call-based argument usage conventions. The call-back types received by a client device driver depend on the functions it uses.

The OS/2 operating system supports the following PCMCIA Card Services call-back types:

  • Client Information
  • Ejection/Insertion Requests
  • Erase Completion
  • Exclusive
  • Insertion
  • MTD Request
  • Registration Completion
  • Reset
  • Socket Services Updates
  • Status Change

In a Far Call/return model, the PCMCIA Card Services call-back invocation notation is defined for the OS/2 operating system as a register-based interface. All callback routines are guaranteed to be called only in kernel-context mode by the Card Services device driver. This callback interface uses the following register-to-argument assignments:

Input:

  [AL]            = Function argument
  [CX]            = Socket argument
  [DH]            = Information, socket status
  [DL]            = Information, card status
  [DI]            = ClientVal field from ClientData structure
  [DS]            = ClientDS field from ClientData structure
  [SI]            = ClientOff field from ClientData structure
  [SS]:[BP]       = MTD Request
  [ES]:[BX]       = Buffer argument
  [BX]            = Miscellaneous Argument, when no buffer argument

All other registers are undefined.

Output:

         [AX]            = Status argument
         Carry Flag      = Completion flag

         All other registers are preserved.

The ClientData structure is used in the RegisterClient function and has the following format.

 Field Name    Type      Description
 ----------    ------    --------------------------------
 ClientVal     USHORT    Client-specific data value
 ClientDS      USHORT    Client's data segment selector
 ClientOff     USHORT    Client's call-back data offset
 Reserved      USHORT    Reserved field
Events

The OS/2 operating system supports the following PCMCIA Card Services events:

BATTERY_DEAD               (01h)
BATTERY_LOW                (02h)

Note:These events can be generated at CARD_INSERTION time if hardware detection capabilities are available.

 CARD_INSERTION             (40h)
 CARD_READY                 (04h)
 CARD_REMOVAL               (05h)
 CARD_RESET                 (11h)
 CARD_LOCK                  (03h)
 CARD_UNLOCK                (06h)
 CLIENT_INFO                (14h)
 EJECTION_REQUEST           (08h)
 EJECTION_COMPLETE          (07h)
 ERASE_COMPLETE             (81h)
 EXCLUSIVE_REQUEST          (0Eh)
 EXCLUSIVE_COMPLETE         (0Dh)
 INSERTION_REQUEST          (0Ah)
 INSERTION_COMPLETE         (09h)
 MTD_REQUEST                (12h)
 REGISTRATION_COMPLETE      (82h)
 RESET_COMPLETE             (80h)
 RESET_PHYSICAL             (0Fh)
 RESET_REQUEST              (10h)
 SS_UPDATED                 (16h)

The events received by a client device driver depend on the functions the device driver uses.

Memory Technology Driver Helpers

The Memory Technology Driver (MTD) Helper routines provide Card Services assistance to MTDs during Read, Write, and Erase operations.

Card Services provides default MTD support. The default SRAM MTD supports Read, Write, and Erase (= write FFh) operations. A non-SRAM default MTD supports Read and Write operations as basic bus cycle byte presentations to the card (with no special algorithms). The Erase operation is not supported by the non-SRAM default MTD.

Media Access Routines

The media access routines are the common worker routines used by MTDs to perform the low-level primitive functions underlying the basic Read, Write, and Erase operations.

Card Services builds the Media Access Table (MAT) using the Socket Services function GetAccessOffsets for register-based sockets. If Socket Services does not support the function, the MAT is provided by Card Services itself.

All pointers in the MAT consist of Selector:Offset (16:16), level 0, GDT addresses.

Return Codes

All return codes are used and returned in the manner defined in the PCMCIA Card Services Release 2.00 Interface Specification unless explicitly noted in this document. Function compatibility determines which of the return codes (equate names and numeric values) will actually be returned for each function.

Functions that are not supported will be returned with the standard Card Services UNSUPPORTED_FUNCTION error code (15h).

Deviations from Card Services Release 2.00

There are some deviations from the PCMCIA Card Services Release 2.00 Interface Specification in the PCMCIA support. These deviations are as follows:

  • General
    The following return codes are available on all Card Services functions supported by the OS/2 operating system.
    Return Codes:
    BUSY Unable to process request at this time; retry later.
    The calling client is expected to retry the failed operation at a later time.
    OUT_OF_RESOURCE Out of internal or system resources necessary to process the request.
    The calling client is expected to either retry the operation later or cancel the current operation.
    (See Implementation Limitations and Restrictions for more details.)
  • AddSocketServices (32h)
    The Attributesfield defines details for the new Socket Services entry point. Card Services accepts only bit 1 (16:16 protect mode) requests.
    The DataPointerfield is used to establish data addressability for Socket Services when called by Card Services. Card Services accepts only 16-bit, protect-mode, GDT Level 0, data selector values.
    Return Codes:
    OS/2 Card Services returns the following error codes in addition to the error codes defined in the PCMCIA specification:
    BAD_ARG_LENGTH ArgLength value is not equal to 4.
    UNSUPPORTED_MODE Requested processor mode is not 16:16 protect mode.
  • AdjustResourceInfo (35h)
    Return Codes:
    OS/2 Card Services returns the following error code in addition to the error codes defined in the PCMCIA specification:
    BAD_ARGS The IOAddrLinesfield is 0 or greater than 16.
  • DeregisterClient (02h)
    To use the DeregisterClient function, the client must release all the resources allocated using the following functions:
    • RequestConfiguration
    • RequestIO
    • RequestIRQ
    • RequestWindow
    • RegisterEraseQueue
    • OpenMemory
    Return Codes:
    OS/2 Card Services returns the following error code in addition to the error codes defined in the PCMCIA specification:
    IN_USE A resource has not been released by the requesting client.
  • GetCardServicesInfo (0Bh)

The following OS/2 Card Services returns the following:

0100 for the Revision value.

0200h for the CSLevel value.

Text for the VendorStrings value:

 IBM OS/2 PCMCIA Card Services Device Driver.
 [c]  Copyright IBM Corporation 1992, 1993, 1994.
 All Rights Reserved.
  • RegisterClient (10h)

Card Services does not support the power management change bit in the EventMask field. Set bit 8 to 0 for future compatibility. Card Services currently disregards the bit 8 value.

Card Services does not support the write-protect change bit in the EventMask field. Bit 0 should be set to 0 for future compatibility. Card Services currently disregards the bit 0 value.

Card Services does not support the Versionfield. It is recommended that the value be set to 0200h for future compatibility. Card Services currently disregards the Versionfield.

Return Codes:

OS/2 Card Services returns the following error code in addition to the error codes defined in the PCMCIA specification.

BAD_ATTRIBUTE No client type or more than one client type specified.

  • ReplaceSocketServices (33h)

One Socket Services device driver can replace another only if it takes ownership of the exact adapter resources previously claimed by the existing Socket Services device driver. If this does not occur, the request is rejected with a BAD_SOCKET error return code.

  • RequestIRQ (20h)

Card Services supports the following Attributes field bit definitions.

 Bit 0 - 1   IRQ type
             0 - Exclusive
             1 - Time-Multiplexed Sharing
             2 - Dynamic Sharing
             3 - Reserved
 Bit 2       Force Pulse (Not supported, must = 0)
 Bit 3       First Shared
 Bit 4 - 7   Reserved (Must = 0)
 Bit 8       Pulse IRQ Allocated
             (not supported, always returned as 0)
 Bit 9 - 15  Reserved (Must = 0)

If any of the unsupported Attributes field bits are set, the request fails with a BAD_ATTRIBUTE return code.

  • RequestSocketMask (22h)

Card Services does not support the power management change or the write-protect change bits in the EventMask field. Set these bits to 0 for future compatibility. Card Services currently disregards these bit values.

  • RequestWindow (21h)

Card Services supports the following Attributesfield bit definitions.

         Bit 0      Reset to 0.
         Bit 1      Memory type (Set = attribute)
         Bit 2      Enabled (Set = true, reset = disabled)
         Bit 3      Data path width (Reset = 8-bit, set = 16-bit)

         Bit 4      Paged (Set = true)
                    (not supported, must be 0)
         Bit 5      Shared (Set = true)
         Bit 6      First Shared (Set = true)
         Bit 7 - 15 RESERVED (reset to 0)

If any of the unsupported Attributes field bits are set, the request fails with a BAD_ATTRIBUTE return code.

Card Services sets the PCMCIA card memory offset for the window to 0. A client can change a PCMCIA card memory offset for the window by using the MapMemPage function.

  • SetEventMask (31h)

Card Services does not support the power-management change or the write- protect change bits in the EventMask field. Set these bits to 0 for future compatibility. Card Services currently disregards these bit values.

Card Services Device Driver Parameters

OS/2 Card Services supports the following BASEDEV= parameters in the CONFIG.SYS file:

  .
  .
 BASEDEV=[drive][:pathname]\PCMCIA.SYS /W
  .
  .

Parameter descriptions are defined as follows:

  • /W
    Wait line monitoring control.
    Refer to the Command Reference for a description of all the parameters defined for the Card Services device drivers.

COM Support

The OS/2 COM driver provides generic hardware support for ASYNC COM ports present in the system unit. COM provides this generalized support to the application layers in OS/2 by way of Category 01h Generic IOCtl functions. Please see the OS/2 Physical Device Driver Reference for more details.

Inter-Device-Driver Client Interfaces

The OS/2 PCMCIA architecture includes a special set of interfaces that allow transparent application support for PCMCIA COM devices. The OS/2 COM device driver (COM.SYS) provides an IDC interface that allows PCMCIA Clients to map their serial devices into the standard COM port declarations. This interface enables a wide-range of existing COM-based applications, without modification, to view and access the PCMCIA devices as if they were standard COM devices.

The OS/2 COM IDC support for PCMCIA devices is unique because the client device driver performs the installation (device setup) and deinstallation (device removal) processing with Card Services. The OS/2 COM physical device driver assumes the responsibilities for application interaction with the device as well as the device manipulation for the data transfer. The arrangement can be viewed as COM.SYS containing a generic COM device engine while the client manages mapping the device characteristics into the system.

The COM IDC interface connection is established by the Client Device Driver by issuing the DevHelp_AttachDD function with a device name parameter value of "COM1" (COM1 followed by 4 blanks). The Client device driver can call the AttachDD function during the INIT Command (00h) or INIT_COMPLETE (1Fh) Command processing and save the returned DevHelp_IDC entry point information for later use.

In a Far Call/return model, the COM IDC is defined as a register-based interface. This interface uses the following register-to-argument assignments:

Input:

[DS]            = COM DS selector value
[ES]:[BX]       = Request Packet pointer

All other registers are undefined.

Output:

 Carry Flag      = Completion flag
 
 IF CF = 1         If CF is set (value=1) then the
                   request failed. The error code is
                   stored in the ReturnCode field
                   of the request packet.
 
 IF CF = 0         If CF is reset (value=0) then the
                   request completed successfully.

Input register values remain unchanged, all other registers are reserved.

COM is invoked using the protect-mode IDC entry point information returned by the DevHlp_AttachDD function. The caller must do the following:

  • Operate in a Far Call/return model.
  • Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface.
  • Establish the COM DS register value (from the information returned by AttachDD) prior to issuing COM function requests.

The COM IDC interface consists of two functions: Install Device and Deinstall Device. These IDC functions use a common packet format for parameter passing. The parameter packet structure is defined as:

 Field Name    Type      Description
 ----------    ------    -----------------
 Function      USHORT    Function code
 PortNumber    USHORT    COM Port Number
 PortAddr      USHORT    COM Port Address
 PortIRQ       USHORT    COM Port IRQ
 ReturnCode    USHORT    Return code

The COM IDC packet field descriptions and values are defined as follows:

  • Function

Input parameter.

Contains the IDC Requested function code. Supported values are:

-0 - Deinstall COM port device

This function requests that the established COM device associations for the device owned by the calling client device driver be removed. Deinstall requests are typically made during the client's processing of a Card Services CARD_REMOVAL event. The client should call this function beforeit has released the resource configuration from Card Services.

-1 - Install COM port device

This function requests that the specific COM device associations for the device owned by the calling client device driver be established. Installation requests are typically made during the client's processing of a Card Services CARD_INSERTION event. The client should call this function afterit has received a resource configuration from Card Services.

-All other values are reserved for future use.

  • PortNumber

Input parameter.

Contains the COM port number associated with the device. Supported values are:

-1 - indicates COM1 port selection
-2 - indicates COM2 port selection
-3 - indicates COM3 port selection
-4 - indicates COM4 port selection
-All other values are reserved for future use.

  • PortAddr

Input parameter.

Contains the four-digit hexadecimal COM port address associated with the device. This parameter value is ignored in the Deinstall function request. However, it should always be provided for future compatibility. Examples of typical COM port address values are 03F8h and 02F8h.

  • PortIRQ

Input parameter.

Contains the interrupt request level (IRQ) value associated with the device. Supported values are within the range of 1 through 15 and represent the IRQ number requested. All other values are reserved for future use.

  • ReturnCode

Input/Output parameter.

Contains the return code for the IDC function request. On input, the parameter value should be set to zero. On output, the supported values are:

-ERROR_DEVICE_IN_USE

Indicates the requested COM port number is already in use.

-ERROR_INTERRUPT

Indicates the requested IRQ level is already in use.

-ERROR_INVALID_ADDRESS

Indicates the requested COM port address is already in use.

-ERROR_DEV_NOT_EXIST

Indicates the requested COM port number is not installed. Only returned on Deinstall function requests.

-ERROR_INVALID_FUNCTION

Indicates the requested function code is not supported.

-NO_ERROR

Indicates the requested function completed successfully without errors.

Notes
  1. All packet values defined as input parameters are provided by the calling client device driver. All output packet values are returned by COM.SYS.
  2. The COM IDC requests may not be used during the Interrupt context. All requests should be made only during Kernel and Init contexts.

Socket Services

The PCMCIA Socket Services architecture allows for both device driver and ROM BIOS implementations of the Socket Services support layer. Both implementation models follow a standard presence detection and interface setup methodology. This common methodology is defined as follows:

Presence Detection

Performed by issuing the real mode INT 1Ah - GetAdapterCount function request. If the function returns SUCCESS and "SS" in the Signature field, then at least one Socket Services handler exists.

Interface Setup

When Card Services completes the presence detection step it must:

1.Issue the real mode INT 1Ah - GetSSInfo function request to identify the mapping between Socket Services handlers and the adapters located in the system.

2.Issue the real mode INT 1Ah - GetSetSSAddr function request (w/subfunc = 0) to determine supporting interface modes and interface interaction dependencies. In addition, more GetSetSSAddr function requests (w/subfunc = 1 and 2) are needed for implementations requiring additional data areas.

3.All subsequent interface function requests do not use the INT 1Ah convention but rather use one of the supported interface modes returned in the previous step.

OS/2 Card Services does not currently support ROM BIOS implementations of Socket Services. This is primarily a test statement based upon the lack of ROM BIOS systems for OS/2 Card Services on which it is to be verified. The OS/2 Socket Services device driver model does not require all of the defined PCMCIA architecture interface setup steps previously listed. Therefore, the OS/2 Socket Services presence detection and interface setup methodology for device driver implementations follow the logic defined earlier in this document see Step 3 of the #OS/2 Initialization Architecture.

Functions

OS/2 supports the following PCMCIA Socket Services functions in device driver implementations:

AcknowledgeInterrupt      (9Eh)    GetAdapter                (85h)
GetAdapterCount           (80h)    GetPage                   (8Ah)
GetSocket                 (8Dh)    GetSSInfo                 (83h)
GetStatus                 (8Fh)    GetVendorInfo             (9Dh)
GetWindow                 (88h)    InquireAdapter            (84h)
InquireSocket             (8Ch)    InquireWindow             (87h)
ResetSocket               (90h)    SetAdapter                (86h)
SetPage                   (8Bh)    SetSocket                 (8Eh)
SetWindow                 (89h)

All Socket Services IDC functions are callable in kernel-context mode. In addition, the AcknowledgeInterrupt (9Eh) function is callable in interrupt-context mode. Card Services is responsible for managing the PCMCIA adapter interrupt state and issues the EOI upon return from the AcknowledgeInterrupt request.

The PCMCIA Socket Services function notation is defined for the OS/2 operating system as a register-based interface with the following register-to-argument assignments:

Input:

 [AH]             = Function argument
 [AL]             = Adapter argument
 [BH]             = Window argument
 [BL]             = Page or Socket argument
 [CX]             = Count argument
 [DX]             = Attributes argument
 [DS]:[SI]        = Data pointer argument
 [ES]:[DI]        = Buffer pointer argument
 [DI]             = Offset or Base argument

All other registers are undefined.

Output:

[AX]            = Return Code argument
Carry Flag      = Status Indicator

All other registers are reserved.

Socket Services is invoked using the protect-mode IDC entry point information, which is provided to Card Services in the AddSocketServices function request. Card Services is the sole client of Socket Services and provides the following interface requirements:

  • Operate in a Far Call/return model.
  • Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface.
  • Ensure that an appropriate stack is used for the calling model (16-bit protect mode) with at least 512 bytes of available stack space.
  • Establish the Socket Services DS register value (from the information provided by the AddSocketServices request) prior to issuing Socket Services function requests.

Socket Services performs parameter-range checking on items directly managed and numbered. Socket Services does not check each parameter on entry, but checks only those with values specified for the requested function. Socket Services does not check if the unused input parameters contain null or zero values. For compatibility purposes, define all input values according to the guidelines outlined in the PCMCIA Interface Specification.

Return Codes

All return codes are used and returned in the manner defined in the PCMCIA Socket Services Release 2.00 Interface Specification unless explicitly noted in this document. Function compatibility determines which of the return codes (equate names and numeric values) will actually be returned for each function.

Functions that are not supported will be returned with the standard Socket Services UNSUPPORTED_FUNCTION error code (15h).

Deviations from Socket Services Release 2.00

There are some deviations from the PCMCIA Socket Services Release 2.00 Interface Specification in the OS/2 operating systems PCMCIA support, as shown in the following list:

  • GetAdapterCount (80h)

OS/2 Socket Services returns the number of adapters supported by this driver for the TotalAdapters value.

  • GetSSInfo (0Bh)

OS/2 Socket Services returns 0100 for the Compliance value.

OS/2 Socket Services always returns zero for the FirstAdapter value.

  • GetVendorInfo (9Dh)

OS/2 Socket Services returns the following text for the pBuffer pointer:

 IBM OS/2 PCMCIA Socket Services Device Driver.
   [c]  Copyright IBM Corporation 1992, 1993, 1994.
 All Rights Reserved.

OS/2 Socket Services returns 0100 for the Release value.

Device Driver Parameters

OS/2 Socket Services supports the following BASEDEV= parameters in the CONFIG.SYS file:

BASEDEV=drive:pathname\???xSS0n.SYS /C0=10 /C1=11 /S0=2 /S1=1

Refer to the Command Reference for a description of all the parameters defined for the Socket Services device drivers.

Sample Socket Services Device Driver

The sample Socket Services device driver, which supports the 82365SL B-Step PC Card Interface Controller (PCIC), is Intel** written to the PCMCIA Socket Services Interface 2.0 specification level. As of OS/2 2.1, Card Services is included with the base operating system. The Socket Services sample driver will fail to load if the OS/2 Card Services device driver is not already present.

At device driver load time, the Socket Services driver performs a DevHlp_ATTACHDD to Card Services. If this ATTACHDD fails, the Socket Services driver will set a return code in the request packet to indicate its failure to install. If the Socket Services driver successfully attaches to Card Services, it will interface to this driver by way of an IDC call to perform the AddSocketServices function.

The sample driver is written in assembler, and relies on the Microsoft** MASM Assembler Version 6.00.

Invoking the Sample Socket Services Device Driver

The Socket Services driver is an OS/2 physical device driver and is invoked at system IPL time. Since the driver is a BASEDEV, it resides in the \OS2 directory of the IPL volume, and no path information is specified on the command line in CONFIG.SYS. The syntax is as follows:

BASEDEV=SSPCIC.SYS /H /A:nnnn /E

Note that the parameters used by the driver are not the same as those used by the drivers shipped with OS/2. The sample driver will auto-detect the number of sockets present, and does not permit the manual specification of the IRQ. The driver will usually initialize properly with no parameters specified, but the following parameters may be used to direct its initialization:

  • /H
The /H parameter causes the driver to print out the help information and then terminate.
  • /A:nnnn
The /A:nnnn parameter allows the user to specify an adapter I/O address within the range 100h and 3F0h. If not specified, the default value 03E0h is used.
  • /E
The /E parameter enables initialization message output. If this parameter is not specified, messages will not be displayed.

Component Internal Structure

The component internal structure is described below.

IDC Interface

The IDC packet structure shared between the Socket Services driver and the Card Services driver is defined in Socket Services.

Component Logic Flow

The Socket Services driver is divided into two main parts: Initialization and Socket Services Interface Request Processing. The Socket Services Interface routines are straightforward procedures that perform the PCMCIA Socket Services functions defined in Socket Services. The device driver initialization routine is depicted in the following figure.

Ioddr-06.gif

The sample Socket Services device driver consists of the modules shown in the following table:

Module Module Description Line-of-Code Estimates
MAKEFILE Makefile source N/A
SSOS2DRV.ASM Contains the OS/2 operating system dependent routines 243
SSPCICIN.ASM Socket Services device driver initialization routines 386
SSPCIC.ASM PCMCIA Socket Services Functions routines, except for window management routines 623
SSPCICDP.ASM Device driver internal function dispatcher 212
SSPCICVA.ASM Request parameter validation routines 115
SSPCICWM.ASM Window Management routines 569
SSPCICUT.ASM Utility routines used by the primary function routines of the driver 218
SSMSG.ASM The device driver's initialization messages 42
SSOS2.INC OS/2 operating system related definitions 39
SSMSG.INC Message file related definitions 22
SSPCIC.INC Intel 82365SL PCIC related definitions 241
SSDEFS.INC PCMCIA Socket Services related definitions 295
SS_SEGM.INC Physical Device Driver data and code segment definitions 28
SSMAC.INC Internally used macro definitions 18
SSPCIC.DEF Linker definitions file N/A
TOTAL 3051

Module to Function Map

The following table lists the modules and the function or routines they contain. Note the use of the following prefixes on some of the module names:

  • co - (common) Indicates code that should be common to any implementation of this driver
  • as - (adapter specific) These routines contain the code that would likely need to be changed if this driver is modified to support a different socket controller chip.
  • os - (operating system) Indicates a routine that is highly operating system specific.
Modules Routines
SSOS2DRV.ASM
Strategy
GetSegmPars
GetSetSSAddr
osAddSS
osOKtoLoad
osPrintString
osPrintChar
SSPCICIN.ASM
coiInitAdapter
coiInitSocket
coiInitWindow
coiInitAll
coiScanCommand
asDetectAdapter
asResetHardware
coiInitSS
SSPCIC.ASM
GetReg
SetReg
asSetSktIRQ
asSetSktInterface
asSetSktMask
GetPower
SetVcc
SetVpp
SoftReset
GetSktChanges
GetAdapterCnt
GetSSInfo
GetVendorInfo
AckInterrupt
InquireAdapter
InquireSocket
SetSktPower
GetSocket
GetStatus
SetSocket
ResetSocket
GetInstSktState
GetAdapter
SetAdapter
SSPCICDP.ASM
IsCardIn
ValidateArgs
codCommon16
codRM_Entry
SSPCICVA.ASM
covValidateIRQ
CheckPowerLevel
covValidatePw
covValidateIFt
SSPCICWM.ASM
cowDisableWindow
cowEnableWindow
cowIsWindowEnabled
cowValWinPars
GetWndReg
SetWndReg
CalcWndIndex
asGetWindowCtrl
InquireWindow
GetWindow
SetupMemWin
SetupIOWin
SetWindow
GetPage
SetPage
SSPCICUT.ASM
couDelay
couIsValidSpeed
couGetSpeedComp
couCompSpeed
couCopyInfo
couGetHex
couGetToken
couStrlen

IBM Data/FAX Modem Client Driver Sample

The OS/2 client driver for the IBM PCMCIA Data/FAX Modem is a device driver written to the PCMCIA Card Services Interface 2.0 specification level. In OS/2 2.1, Card Services is included with the base operating system. IBM PCMCIA Data/FAX Modem support for OS/2 will fail to install if Card Services, Socket Services, and the OS/2 COM.SYS device driver are not present. This is similar to the DOS support with the additional dependency of the COM.SYS driver. IBM PCMCIA Data/FAX Modem support is dependent upon COM.SYS because it interfaces to this driver through an IDC interface created specifically for PCMCIA support.

At device driver load time, the IBM PCMCIA Data/FAX Modem driver performs an ATTACHDD to COM.SYS. If this ATTACHDD fails, the IBM PCMCIA Data/FAX Modem will set a return code in the request pack back to OS/2 to indicate its failure to install.

If the IBM PCMCIA Data/FAX Modem driver successfully attaches to COM.SYS, it will interface to this driver by way of an IDC each time a PCMCIA modem is inserted or ejected from the system. When a modem is inserted, IBM PCMCIA Data/FAX Modem will call the COM.SYS IDC with a request packet indicating which new COM port was created. Likewise, when the modem is ejected, IBM PCMCIA Data/FAX Modem calls the COM.SYS IDC with a request packet indicating which COM port has been removed.

All but the essential device driver shell is written in C using the Microsoft C Compiler for OS/2, Version 6.0. The assembler pieces rely on the Microsoft MASM Assembler for OS/2, Version 5.10.

Invoking the Client Driver

The client driver is an OS/2 physical device driver and is invoked at system IPL time. The syntax for the client driver is as follows:

DEVICE=C:\ESTDFM.OS2 SxCy,...,SxCy

SxCy where:S denotes PCMCIA Slot # and x = {1,2,3,4,5,6,7,8}

C denotes COM port # and y = {1,2,3,4}

This parameter is used to denote which COM port should be assigned to a modem present in a particular socket.

Up to four (4) of these parameters may be specified.

The following base address and IRQ values are assigned currently regardless of the target system bus.

 COM1:        03F8h   IRQ4
 COM2:        02F8h   IRQ3
 COM3:        03E8h   IRQ4
 COM4:        02E8h   IRQ3

At this time, the enabling software will support a maximum of four IBM PCMCIA Data/FAX Modem. However, the absolute maximum is system dependent. A system with less than eight PCMCIA sockets could not utilize eight IBM PCMCIA Data/FAX Modem simultaneously. Likewise, a system that already has a COM port allocated to the planar reduces the maximum number modems that can be used simultaneously by one.

Component Internal Structure

The component internal structure is described below.

IDC Interface

The IDC packet structure shared between the OS/2 COM.SYS driver and a modem client driver is defined in COM Support.

Component Logic Flow

The client driver is divided into the following areas: Initialization, Card Services Interface, and Callback Notification.

The figure of Component Logic Flow - Driver Initialization details the high -level logic flow of the device driver design.

Ioddr-07.gif

The figure of Component Logic Flow - Enable Modem below details the high-level logic flow of the device driver design.

Ioddr-08.gif

The figure of Component Logic Flow - Callback Routine details the high- level logic flow of the device driver design.

Ioddr-09.gif

The OS/2 client driver for the IBM PCMCIA Data/FAX Modem consists of the modules shown in the following table.

Module Module Description Line-of-Code Estimates
MAKEFILE C makefile source N/A
CS_IDC.H Contains CS_IDC.ASM function prototype. 2
CS_IDC.ASM Contains the assembler code that attaches and interfaces to card services 131
CS_HELP.ASM The callback handler function that card services will invoke when a registered event occurs 75
CS_HELP.H Callback handler C function prototype 1
COMPORT.C Contains the functions that acquire and release the COM port 149
COMPORT.H Function prototypes for acquiring and releasing the COM port 3
CS_UTIL.C Contains the card services calls to allocate and deallocate resources for the modem 734
CS_UTIL.H Contains the release and acquire resources function prototypes 3
CS.C Contains the routines to register with card services and to handle the card present event 312
CS.H Declarations for the routines that interface with card services 26
CARD_ID.C Verifies the identity of the modem card 29
CARD_ID.H Declaration for the card_id function 1
SHELL.ASM Contains assembler shell that creates a device driver model to which the C code can interface 77
DEVHLP.ASM Contains routines help access DevHelp routines from the operating system 58
CS_HELP.ASM The Callback handler that card services will invoke when a registered event occurs 75
CONFIG.C Contains routines that process and store configuration info for the system 100
CONFIG.H Constant definitions and prototypes used by CONFIG.C 15
DEVHELP.H Definitions and public functions for Device Driver help routines 10
STGY.C Contains the strategy portion of the device driver 258
COM_IDC.ASM Contains the code interfaces with OS/2 COM.SYS by way of the new IDC 124
COM_IDC.H Contains the declarations and prototypes for COM_IDC 2
SHELL.H Device Driver prototypes 3
TYPES.H Contains constant definition and type definition for the system 7
TOTAL 2195
Module Tree

The figure of OS/2 Client Driver Initialization Routine depicts the logic flow of the initialization portion of the OS/2 client driver.

Ioddr-10.gif

The figure of OS/2 Client Driver Functional Logic Flow is a high level flow of the main functional portion of the client driver.

Ioddr-11.gif

Module to Function Map

The following table lists the modules and the function or routines they contain.

Modules Routines
CARD_ID.C
correct_card_id
COMPORT.C
acquire_com_port
release_com_port
CONFIG.C
store_config_info
store_socket_assignments
CS.C
cs_services_present
cs_card_present
cs_register_client
service_callback
cs_get_num_of_sockets
CS_UTIL.C
cs_acquire_resource
cs_request_irq
cs_request_io
cs_request_configuration
cs_is_modem_card
cs_release_resource
cs_release_configuration
cs_release_irq
cs_release_io
STGY.C
do_strat
get_parameters
COM_IDC.ASM
com_idc_init
set_com_port
CS_HELP.ASM
callback_handler
CS_IDC.ASM
cs_idc_init
do_card_services
DEVHLP.ASM
devhlp_init
SHELL.ASM
strategy
OS/2 Device Driver Routine Descriptions
do_strat
This function is the device driver strategy routine. The parameter 'rpP' is a pointer to a block of information from the operating system called the request packet.
void do_strat(REQPACKET far *rpP)
begin
       switch(request pkt cmd)
         case (initialization)
           if driver already installed
            set status to error
           else
            save pointer to DevHlp routines
            if (cs_idc_init fails)
             set status to error
            if (com_idc_init fails)
             set status to error
            parse and save device= parms
            set status to success
         case (init complete)
            if card services present
             get number of sockets machine supports
             store configuration information
             if (registered with card services failed)
              set error status
             else
              set status to success
         end switch
       return
end

com_idc_init This function retrieves the inter-device-driver communications entry point from COM.SYS. The function returns the value -1, if successful. Otherwise, the value 0 is returned.

public com_idc_init
begin
            if (attach to COM.SYS o.k.)
             save pointer to IDC entry point
            else
             set error code
end
cs_idc_init
This function retrieves the inter-device-driver communications entry point from Card Services. The function returns the value -1 if successful. Otherwise, the value 0 is returned.
public cs_idc_init
begin
            if (attach to Card Service ok)
             save pointer to IDC entry point
            else
             set error code
end
devhlp_init
This function stores the OS/2 device driver help services entry point. The function returns the value -1, if successful. Otherwise, the value 0 is returned.
public devhlp_init
begin
            advance to area in request pkt containing DevHlp
            address save pointer to DevHlp entry point
end
set_com_port
This function passes a request to COM.SYS through the IDC.
public set_com_port
begin
    copy parms off of stack and into IDC packet
    (IDC command,comport #, comport address, comport IRQ)
    call COM.SYS by way of IDC
    get COM.SYS return code back from IDC pkt
end
get_parameters
This function retrieves the parameters from the DEVICE= statement in the CONFIG.SYS file.
void get_parameters(ULONG argP, short far *argc,
 char far * far *argv);
service_callback
This function services callback events for card insertion and card removal from Card services.
void service_callback (USHORT socket_num, USHORT event_num)
begin
    switch(event_number)
      case (card inserted)
       if (card is an IBM modem)
         call cs_acquire_resource
         return if unsuccessful
         call set_com_port(INSTALL_CMD)
         call cs_release_resource and return if unsuccessful
         call acquired_com_port
         call cs_release_resource.  Set_com-Port (DEINSTALL_CMD)
           and return if unsuccessful
       endif
      case (card removed)
       if (card removed is ours)
         call cs_release_resource
         return if unsuccessful
         call set_com_port(DEINSTALL_CMD)
         call release_com_port
       endif
      end switch
end
callback_handler
This assembler language entry point is invoked by card services when a registered event occurs. It sets up the data segment and calls the C routine to service the callback.
public callback_handler
begin
    get event number and socket number
    call service_callback
end
correct_card_id
This routine passes the tuple data to determine if the card in question is one of the IBM PCMCIA Data/FAX Modem cards.
BOOL correct_card_id(UCHAR far *dataP)
release_com_port
This function removes the I/O address from the BIOS data area.
void release_com_port(USHORT ioaddress)
begin
    point to BIOS data area
    remove IO address that was in use
    decrement number of RS232 devices in BIOS data area
end
store_config_info
This function checks the syntax of the command line arguments and stores configuration information. The parameter 'argc' contains the number of arguments on the command line. The parameter 'argv' contains a pointer to an array of pointers to null terminated ASCII strings containing the arguments. The function returns 0 if successful. Otherwise, a value less than 0 is returned, indicating the error condition.
short store_config_info(short argc, char far * far *argv)
begin
    initialize default settings for modem (Intel compatible,
    ISA bus) parse command line and determine COM port
    settings if error parsing arguments
      fail to install
end
store_socket_assignments
This function stores the I/O address, the IRQ number, and the COM port number. This information is found in the socket assignment string. The parameter 'strP' contains a pointer to a null terminated string containing the socket assignment information. The parameter 'io_addressP' is the address of an array containing i/o addresses for the present configuration. The parameter 'irq_numP' is the address of an array containing the IRQ numbers for the present configuration. The parameter ' num_of_io_addresses' contains the number of I/O addresses for the present configuration. The function returns 0 if successful. Otherwise, a value less than 0 is returned, indicating the error condition.
static short store_socket_assignments
                 (char far *strP,
                 USHORT far *io_addressP,
                 USHORT far *irq_numP,
                 USHORT num_of_io_addresses)
make_flat_address
This function makes a flat address out of a segmented address. The parameters 'segment' and 'offset' contain the segmented address. The function returns the flat address.
static ULONG make_flat_address(USHORT segment, USHORT offset)
do_card_services
This function enables sockets and cards using Card Services.
static void short do_card_services(void)
begin
       get the number of sockets
       go through sockets - if there's an assignment for a
       socket and no card present, then report the error
       register as client
       return
end
cs_is_modem_card
This function determines if a modem card is present in a particular socket. The parameter 'socket_num' contains the number of the socket to check. The function returns the value TRUE if a modem card is present. Otherwise, the value FALSE is returned if a modem card is not present or if an error occurred.
static BOOL cs_is_modem_card(USHORT socket_num)
begin
        set up socket number
        set up attributes
        set up to look for  first tuple
        get segment and offset of packet
        get size of packet
        set up codes for get first tuple
        set up segment and offset of packet
        set up size of packet
        set up client handle
        make the call
        return value for false if carry flag set
        set up socket number
        set up attributes
        set up desired tuple code value
        set up data flags
        set up link state information
        set up cis state information
        set up offset into tuple from link byte
        set up maximum size of tuple data area
        get segment and offset of packet
        get size of packet
        set up codes for get tuple data
        set up segment and offset of packet
        set up size of packet
        set up client handle
        make the call
        return value for false if carry flag set
        return value for false if unexpected tuple contents
        return value for true
end
cs_acquire_resource
This function acquires resources and performs initialization activities on both the PCIC and the PCMCIA card. The parameter 'socket_num' contains the socket to initialize. The parameters 'io_address' and 'irq_num' contain the I/O address and the interrupt request number to assign to the socket. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.
static short cs_acquire_resource(USHORT socket_num,
                                 USHORT io_address,
                                 USHORT irq_num)
begin
       request the interrupt request number
       return error code if unsuccessful
       request io address
       release irq and return error code if unsuccessful
       request configuration
       release irq and io address and return error code
         if unsuccessful
       return successful code
end
cs_request_io
This function requests from card services that a particular I/O address be assigned to a socket. The parameters 'socket_num' and 'io_ address' contain the socket number and I/O address. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.
static short cs_request_io(USHORT socket_num, USHORT io_address)
begin
       set up logical socket
       set up base address for ports
       set up range for ports
       set up attributes
       specify that the addresses are not shared with another
          client
       set up additional port info - no additional ports
          specified
       set up addr line info - specify no additional addresses
          need to marked as used
       set up access speed - specify access speed of 100 nsec
          for ports
       get segment and offset for packet
       get size of packet
       set up codes for request io
       set up segment and offset for packet
       set up size of packet
       set up client handle
       make the call
       return error code if carry flag set
       return successful code
end
cs_request_irq
This function requests from card services that a particular interrupt be assigned to a socket. The parameter 'socket_num' is the socket number, and the parameter 'irq_num' is the interrupt number. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.
static short cs_request_irq(USHORT socket_num, USHORT irq_num)
begin
       set up logical socket number
       set up attributes - prefer exclusive irq
       set up for level interrupt and make second info
          field valid
       designate desired irq number
       get segment and offset for packet
       get size of packet
       set codes for request irq
       set segment and offset for packet
       set size of packet
       set client handle
       make the call
       return error code if carry flag set
       return error code if irq number was not assigned
       return successful code
end
cs_request_configuration
This function requests from card services that a particular I/O address be assigned to a socket. The parameter 'socket_num' is the socket number and the parameter 'io_address' is the I/O address. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.
static short cs_request_configuration(USHORT socket_num,
                                      USHORT io_address)
begin
      set up socket number
      set up exclusive use and enable irq
      set up for 5.0 volts (50 x 0.1)
      set vpp - no requirements
      set up option configuration register for normal operation,
          card enable, and designated com port
      set option register value
      set pin register value
      set copy register value
      set status register value - enable audio and ring indicate
      set which registers are present - option & status regs are
          present
      set up base address of config registers in attribute
          memory
      set up interface type - memory and I/O
      get segment and offset for packet
      get size of packet
      set code for request configuration
      set segment and offset for request configuration
      set size of packet
      set client handle
      make the call
      return error code if carry flag
      return successful code
end
cs_release_resource
This function requests from Card Services that resources be released for a particular socket. The parameter 'socket_num' is the socket number of the socket from which resources are to be released. The parameter 'io_address' and 'irq_num' are the I/O address and interrupt number to release. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.
static short cs_release_resource(USHORT socket_num,
                                 USHORT io_address,
                                 USHORT irq_num)
begin
      release configuration
      return error code if unsuccessful
      release interrupt
      return error code if unsuccessful
      release io address
      return error code if unsuccessful
      return successful code
end
cs_release_irq
This function requests from card services that an interrupt number be released for a particular socket. The parameters 'socket_num' and 'irq_num' are the socket number and interrupt number. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.
static short cs_release_irq(USHORT socket_num, USHORT irq_num)
begin
      set up logical socket number
      set attributes - prefer exclusive irq
      set up info - level interrupt and make second info field
         valid
      set up additional info - designate desired irq number
      set up irq number - designate previously established irq
      get segment and offset for packet
      get size of packet
      set code for release irq
      set segment and offset for packet
      set size of packet
      set client handle
      make the call
      return error code if carry flag
      return successful code
end
cs_release_io
This function requests from card services that an I/O address be released for a socket. The parameters 'socket_num' and 'io_address' are the socket number and I/O address. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.
static short cs_release_io(USHORT socket_num, USHORT io_address)
begin
      set up logical socket
      set up base address for ports
      set up range for ports
      set attributes - specify addr not shared with other
         clients
      set additional port info - no additional ports
         specified
      set addr line info - no additional addr need to
         marked in use
      set access speed - specify that access speed for
         ports is 100 nsec
      get segment and offset for packet
      get size of packet
      set codes for release io
      set segment and offset for packet
      set size of packet
      set client handle
      make the call
      return successful code
end
cs_release_configuration
This function requests from card services that a configuration be released for a socket. The parameter 'socket_num' is the socket number. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.
static short cs_release_configuration(USHORT socket_num)
begin
      set up logical socket
      get segment and offset for packet
      get size of packet
      set codes for release configuration
      set segment and offset for packet
      set size of packet
      set client handle
      make the call
      return error code if carry flag
      return successful flag
end
cs_services_present
This function determines if card services is present on the system. The function returns the value TRUE if card services is present. Otherwise, the value FALSE is returned.
BOOL cs_services_present(void)
begin
        init signature field
        set max length for vendor string 
         get   PCMCIA Card Services for OS/2 info
         get   segment and offset of packet
         get   size of packet
         set   up codes for get PCMCIA Card Services for OS/2 information 
         set   up segment and offset of packet
         set   up size of packet
         make  the call 
         return  false value if carry flag
         store   number of sockets
         if   PCMCIA Card Services for OS/2 are present then return
           true value 
         return false value
end 
cs_register_client
This function registers as a client with card services. It returns an error code in parameter 'statusP' if an error occurs. In addition, as a return value, the function returns the value 0 if successful. Otherwise, the function returns the value -1.
short cs_register_client(USHORT *status)
begin
        set up attributes - memory client device driver -
            generate artificial insertion events
        set up event mask - global notification of insertion
            & ejection events
        set up data client receives on callback
        set up segment and offset of client data area
        set up reserved field
        get segment and offset of packet
        get segment and offset of callback handler routine
        set up size of packet
        set up codes for register client
        set up segment and offset of packet
        set up size of packet
        set up segment and offset of callback handler routine
        make the call
        return error code if carry flag
        store client handle
        return successful code
end
cs_card_present
This function determines if a card is present in a particular socket. The parameter 'socket_num' contains the socket to check for a card. It returns the value TRUE if a card is present. Otherwise, it returns the value FALSE.
BOOL cs_card_present(USHORT socket_num)
begin
        set up socket number
        get segment and offset
        get size of packet
        set up codes for get status
        set up segment and offset for packet
        set up size of packet
        make the call
        check carry flag for error
        return true if card present bit is set or false
          if clear
        return false value if error occurred
end
cs_get_num_of_sockets
This function reports the number of sockets present in the system. The function returns the number of sockets.
USHORT cs_get_num_of_sockets(void)
begin
        return the number of sockets
end

Dependencies and Restrictions

This device must be loaded in the CONFIG.SYS file after COM.SYS.

PCMCIA Socket Services Device Driver Test Tool

This chapter explains explains how to use the Socket Services Device Driver Test Tool.

Overview

PCMCIA Socket Services Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of PCMCIA Socket Services device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate PCMCIA Socket Services function and performance. Errors are reported and are easily isolated to a specific test sequence and API.

User input and output from each thread of the PCMCIA Socket Services tests is performed by way of a separate Presentation Manager window. Multi- threaded test cases log all information to a single log file, clearly indicating the actual execution sequence in the event of errors.

PCMCIA Socket Services Test Architecture

The DDTT provides a common front-end parser for test case scripts. The following DDTT PCMCIA-specific files are required:

  • DDTPCMC.DLL
  • PCMC.GRA.
  • PCMCIATS.SYS

The C++ source code for DDTPCMC.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2.

The following required, common components of DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:

  • DDTT.EXE
  • DDTT.DLL
  • GLOBAL.DLL
  • GLOBAL.GRA

Ioddr-12.gif

Installation

There are two directory structures in the IBM Developer Connection Device Driver Kit for OS/2that utilize test suites. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL.

The following procedure describes installation for running test cases:

1.Copy the executable and PCMCIA socket services test case files from the IBM Developer Connection Device Driver Kit for OS/2CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TESTPCMC. Test case script and command files can also be placed in this directory on the hard disk. If the target directory is C: \TESTPCMC and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2CD-ROM disc, then use the following commands to copy the PCMCIA socket services test suite:

[C:\]md testpcmc
[C:\]cd testkpcmc
[C:\testpcmc]copy e:\ddk_x86\testcert\storage\function\pcmcia\socket\*
[C:\testpcmc]copy e:\ddk_x86\testcert\general\ddtt\*

2.Copy the PCMCIATS.SYS file to your root system directory. If your system drive is C, execute the following:

[C:\testpcmc]copy PCMCIATS.SYS c:\

1.To install the test device driver, add BASEDEV=PCMCIATS.SYS immediately before the following two lines (which are used for a Think Pad system). Other systems use different names for the PCMCIA socket services and Resource Map Utility device drivers. These lines load the system's Resource Map Utility device driver and Socket Services device driver. The PCMCIATS. SYS test device driver enables an IOCtl interface for calling Socket Services from the DDTT script files.

BASEDEV=ICRMU01.SYS
BASEDEV=IBM2SS01.SYS

2.Next, make sure the following lines are commented out of the CONFIG.SYS file.

rem BASEDEV=PCMCIA.SYS
rem DEVICE=VPCMCIA.SYS
rem DEVICE=AUTODRV2.SYS AUTODRV2.INI
rem DEVICE=$ICPMOS2.SYS

Loading any of the above PCMCIA support drivers will interfere with Socket Services testing.

3.Add C:\TESTPCMC\BIN to the LIBPATH and PATH in CONFIG.SYS.

4.Reboot your machine so the new LIBPATH entry and CONFIG.SYS changes take effect.

Test-Case Execution

1.Change to the directory where the socket services test script files were copied, for example C:\TESTPCMC.

2.For machines with one socket, start SSSCR1.CMD. For machines with two sockets, start SSSCR2.CMD.

3.The output is written to the corresponding filenames with a .LOG extension. After executing the command file, all the log files are concatenated and written into the file SSLOG1.

DDTT PCMCIA Socket Services Test Grammar Function Calls

The following are the names of the PCMCIA Socket Services Test Grammar Function Calls:

  • PCMC_OPEN
  • PCMC_CLOSE
  • PCMC_GETADAPTERCOUNT
  • PCMC_ACKINTERRUPT
  • PCMC_PRIORHANDLER
  • PCMC_SSADDR
  • PCMC_ACCESSOFFSETS
  • PCMC_GETADAPTER
  • PCMC_GETSSINFO
  • PCMC_GETVENDORINFO
  • PCMC_INQADAPTER
  • PCMC_SETADAPTER
  • PCMC_VENDORSPECIFIC
  • PCMC_GETSOCKET
  • PCMC_GETSTATUS
  • PCMC_INQSOCKET
  • PCMC_RESETSOCKET
  • PCMC_SETSOCKET
  • PCMC_GETPAGE
  • PCMC_GETWINDOW
  • PCMC_INQWINDOW
  • PCMC_SETPAGE
  • PCMC_SETWINDOW
  • PCMC_GETEDC

PCMC_OPEN

This function opens the PCMCIA$ test device driver.

Input Parameter Keywords
None.
Output Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
Logged Data
None.

PCMC_CLOSE

This function closes the PCMCIA$ test device driver.

Input Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE         |NUM                 |Drive handle for    |
|                    |                    |PCMCIA device under |
|                    |                    |test                |
Output Parameter Keywords
None.
Logged Data
None.

PCMC_GETADAPTERCOUNT

This function gets the number of adapters supported by Socket Services and the signature "SS".

Input Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE         |NUM                 |Drive handle for    |
|                    |                    |PCMCIA device under |
|                    |                    |test                |
Output Parameter Keywords
None.
Logged Data
Total number of adapters
Signature "SS"

PCMC_ACKINTERRUPT

This function gets the oldest status change interrupt information from the PCMCIA$ test device driver.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
SOCKET NUM Socket number
Output Parameter Keywords
None.
Logged Data
Number of interrupts

PCMC_PRIORHANDLER

This function gets or sets the prior Socket Services handler for the specified adapter.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
MODE NUM Function mode where
0 = function performs a GET
1 = function performs a SET
Output Parameter Keywords
Logged Data
Mode ( 0 = Get, 1 = Set )

PCMC_SSADDR

This function gets or sets mode and data area descriptors.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
PROCMODE NUM Processor mode where:
00 = Real Mode
01 = 16:16 Protect
02 = 16:32 Protect
03 = 00:32 Protect
FUNCTION NUM Requested function where:
0 = Get code and main data segments
1 = Get additional data segments
2 = Set additional data segments (NEEDED FOR SET ONLY)
NUM_SEGS NUM Number of additional data segments to GET or SET (NEEDED FOR SET ONLY)
Output Parameter Keywords
None.
Logged Data
Requested function
Number of additional data segments to get or set

PCMC_ACCESSOFFSETS

This function gets an array of offsets for low-level, adapter-specific optimized PC card-access routines.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
PROCMODE NUM Processor mode where:
00 = Real Mode
01 = 16:16 Protect
02 = 16:32 Protect
03 = 00:32 Protect
FUNCTION NUM Requested function where:
0 = Get code and main data segments
1 = Get additional data segments
2 = Set additional data segments (NEEDED FOR SET ONLY)
NUM_DESIRED NUM Number of offsets to be reported, a value between 0 and 18
Output Parameter Keywords
None.
Logged Data
Number of offsets supported

PCMC_GETADAPTER

This function gets the current configuration of the specified adapter.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
Output Parameter Keywords
None.
Logged Data
Adapter Attributes
IRQ level for status change interrupts

PCMC_GETSSINFO

This function gets the compliance level of the Socket Services interface supporting the specified adapter and identifies the adapters supported.

Input Parameter Keywords:
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
Output Parameter Keywords
None.
Logged Data
Compliance
Number of adapters
First adapter

PCMC_GETVENDORINFO

This function gets information about the vendor that implemented the Socket Services for the specified adapter.

Input Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE         |NUM                 |Drive handle for    |
|                    |                    |PCMCIA device under |
|                    |                    |test                |
|--------------------+--------------------+--------------------|
|ADAPTER             |NUM                 |Adapter number      |
Output Parameter Keywords
None.
Logged Data
Release Number
ASCII string describing the implementer

PCMC_INQADAPTER

This function gets the capability information for the specified adapter.

Input Parameter Keywords
|Keyword         |Type     |Description
|----------------+---------+-------------------
|DRIVEHANDLE     |NUM      |Drive handle for
|                |         |PCMCIA device under
|                |         |test
|----------------+---------+-------------------
|ADAPTER         |NUM      |Adapter number
Output Parameter Keywords
None.
Logged Data
Number of sockets
Number of windows
Number of EDCS
Contains the information on the adapter capabilities, the IRQ state and level, and the power management specifications.

PCMC_SETADAPTER

This function sets the configuration of the specified adapter.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
ADPSTATE NUM Adapter attributes where:
Bit 0 = Reduce power consumption (1 = True)
Bit 2 = Preserve State Information (1 = Preserve)

All other bits are reserved and must be zero.

IRQ ALNUM IRQ level to use for status change interrupts (if bit 7 is enabled)
Output Parameter Keywords
None.
Logged Data
None.

PCMC_VENDORSPECIFIC

This function defines a vendor-specific function for implementing proprietary functions.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
SUBFUNCTION NUM Subfunction codes where:
1 = InquireBootSocket
2 = UnlockBootSocket
Output Parameter Keywords
None.
Logged Data
None.

PCMC_GETSOCKET

This function gets the current configuration of the specified socket.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
SOCKET NUM Socket Number
Output Parameter Keywords
None.
Logged Data
Interrupt Mask
Vcc Level
Vpp Level
Socket State variables
Socket Control Variables
IRQ level and status change interrupts

PCMC_GETSTATUS

This function gets the status of the card in the specified socket on the specified adapter.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
SOCKET NUM Socket Number
Output Parameter Keywords
None.
Logged Data
Card Attributes
Socket State
Control and Indicator State
IRQ level and status change interrupts

PCMC_INQSOCKET

This function gets the capability information for the specified socket.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
SOCKET NUM Socket Number
Output Parameter Keywords
None.
Logged Data
Interrupt Capabilities
Reporting Capabilities
Control Capabilities
Socket Characteristics

PCMC_RESETSOCKET

This function resets the PC card in the specified socket.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
SOCKET NUM Socket Number
Output Parameter Keywords
None.
Logged Data
None.

PCMC_SETSOCKET

This function sets the configuration for the specified socket.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
SOCKET NUM Socket Number
INTERRUPTMASK ALNUM Status change interrupt mask where:
Bit 0 = Write Protect Change (must be zero)
Bit 1 = Card Lock Change (must be zero)
Bit 2 = Ejection Request (set = enable for PS/2-E)
Bit 3 = Insertion Request (must be zero)
Bit 4 = Battery Dead Change (set = enabled)
Bit 5 = Battery Warning Change (set = enabled)
Bit 6 = Ready Change (set = enabled)
Bit 7 = Card Detect Change (set = enabled)
VCCLEVEL NUM Lower nibble - Vcc Level
VPPLEVEL NUM Upper Nibble - Vpp Level, Lower Nibble - Vpp2 Level
SOCKETSTATE NUM Socket state where:
Bit 0 = Write Protect Change
Bit 1 = Card Lock Change
Bit 2 = Ejection Request(For PS/2-E)
Bit 3 = Insertion Request(must be zero)
Bit 4 = Battery Dead Change
Bit 5 = Battery Warning Change
Bit 6 = Ready Change
Bit 7 = Card Detect Change
SOCKETCONTROL NUM Socket Control where:
Bit 4 = Lock Control(PS/2-e only)
Bit 6 = Busy Status

All other bits are reserved and are set to zero

IFIRQ ALNUM IRQ Steering and Interface Type Control where:
Bit 0..3 = IRQ Level (0..15) (16..19 must be zero)
Bit 4 = Reserved (always zero)
Bit 5 = Reserved (always zero)
Bit 6 = IRQ Inverter enabled (set to one = enable)
Bit 7 = IRQ Steering enabled (set to one = enable)
Bit 8 = Memory only interface (mutually exclusive of I/O and Memory interface)
Bit 9 = I/O and Memory interface (mutually exclusive of Memory only interface)

All other bits are reserved and are set to zero

Output Parameter Keywords
None.
Logged Data
None.

PCMC_GETPAGE

This function gets the current configuration of the specified page in the specified window.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
WINDOW NUM Window Number
PAGE NUM Page number
Output Parameter Keywords
None.
Logged Data
Page Attributes
Offset

PCMC_GETWINDOW

This function gets the current configuration of the specified window on the specified adapter.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
WINDOW NUM Window Number
Output Parameter Keywords
None.
Logged Data
Socket
Window Size
Window Attributes
Access speed
Window Base Address

PCMC_INQWINDOW

This function gets the capability information for the specified window on the specified window.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
WINDOW NUM Window Number
Output Parameter Keywords
None.
Logged Data
Capabilities
Assignable Sockets

PCMC_SETPAGE

This function sets the configuration for the specified page in the specified window.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
WINDOW NUM Window Number
PGSTATE NUM Page Attributes where.
Bit 0 set = Attribute Memory, reset = Common Memory
Bit 1 set = Enable, reset = Disable
All other bits are reserved and must be set to zero
OFFSET NUM 4KB units
Output Parameter Keywords
None.
Logged Data
None.

PCMC_SETWINDOW

This function sets the configuration for the specified window.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
WINDOW NUM Window Number
SOCKET NUM Socket number
SIZE ALNUM Number of bytes for I/O, number of 4KB units for memory
WINSTATE NUM Window State where:
Bit 0 set = Memory, reset = I/O
Bit 1 set = Enabled, reset = Disabled
Bit 2 set = 16-bit, reset = 8-bit

All other bits are set to zero

SPEED NUM Actual access speed 1 = 250nSec Only speed supported
BASE ALNUM Base address where:
0x00A0 - First Byte addressable
0x00FF - Last Byte addressable
Output Parameter Keywords
None.
Logged Data
None.

PCMC_GETEDC

This function gets the current configuration of the specified EDC generator.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for PCMCIA device under test
ADAPTER NUM Adapter number
EDC NUM EDC generator number
Output Parameter Keywords
Socket
State
Type

Description of Test Cases

Each of the PCMCIA Socket Services test cases can be executed individually as previously described. The corresponding test scripts are described below. You can create additional tests or combine tests into multi- threaded test cases after becoming familiar with the DDTT and the PCMCIA grammar files.

All test scripts close the channels opened to the PCMCIA device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name and a file name extension .LOG. When current status is queried (for example, track, channel, or drive), this data is written to the DDTT's output windows and to the log file. Log files can be examined after the test case has completed.

ACKINT.SCR Gets the number of Status Change Interrupts from the test device driver since the last time ACKINT was called. The count is reset to zero.

ADAPTER.SCR Calls the SetAdapter function with different values for State and IRQ. SetAdapter sets the configuration for the specified adapter. Each time the SetAdapter function is called, the GetAdapter function is also called to verify the configuration.

GETAOFS.SCR Gets an array of offsets for low-level, adapter-specific, optimized PC-card access routines. Can return UNSUPPORTED FUNCTION.

GETADP.SCR Gets the current configuration of the specified adapter,

GTADPCT.SCR Gets the number of adapters supported by Socket Services and the Signature "SS".

GETEDC.SCR Gets the current configuration of the specified EDC generator. Can return UNSUPPORTED FUNCTION.

GETPAGE.SCR Gets the current configuration of the specified memory page in the specified window.

GETSOC.SCR Formats the information and sends it to the log file.

GTSSINF.SCR Gets the compliance level of the Socket Services interface supporting the specified adapter and identifies the adapters supported.

GETSTAT.SCR Gets the status of the card in the specified socket on a specified adapter.

GTVNINF.SCR Gets information about the vendor that implemented the Socket Services for the specified PCMCIA adapter.

GETWIN.SCR Gets the current configuration of the specified memory window on the specified adapter.

GSPRHND.SCR Gets the prior Socket Services handler for the specified socket . Can return UNSUPPORTED FUNCTION.

GSSSADR.SCR Gets or sets mode and data area descriptors.

INQADP.SCR Gets the capability information for the specified adapter.

INQSOC.SCR Gets the capability information for the specified socket.

INQWIN.SCR Gets the capability information for the specified window on the specified adapter.

INTRUPT.SCR Calls the AckInterrupts function after various combinations of insert and remove operations on the socket. The AckInterrupts function gets the oldest Status Change Interrupt information from the test version of the PCMCIA$ device driver.

Note:Each call to AckInterrupts from the test IOCtl resets the current count of interrupts. This count is kept and reported for diagnostic purposes only.

MAXPAGE.SCR Calls the GetPage function with different values for the Window number. GetPage gets the current configuration for the specified Page.

MAXWIN.SCR Calls the GetWindow function with different values for the Window number. GetWindow gets the current configuration for the specified Window.

RSETSOC.SCR Resets the PC card in the specified socket.

Note:There must be a card in the socket to call this function successfully.

SETADP.SCR Sets the configuration of the specified adapter.

SETPAGE.SCR Sets the configuration for the specified page in the specified window.

SETSOC.SCR Sets the configuration for the specified socket.

SETWIN.SCR Sets the configuration for the specified memory window.

SETWP.SCR Calls the SetWindow and SetPage functions with different values. After setting the values it calls GetWindow and GetPage to verify configuration.

VNSPEC.SCR Defines a vendor-specific function for implementing proprietary functions. Can return UNSUPPORTED FUNCTION.

WINDOW.SCR Calls the SetWindow function with different combinations of values for Base, Window and Size. SetWindow sets the configuration for the specified Window. Each time the SetWindow function is called, GetWindow function is called before and after the SetWindow to compare the configuration.

Touch Display Device Driver

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

Touch Inter-Device-Driver Communication Interfaces

This chapter describes the inter-device-driver communication (IDC) interfaces for the IBM Touch Display device driver provided by the OS/2 operating system - both device-independent to device-dependent and device-dependent to device-independent.

Device-Independent to Device-Dependent IDC Interfaces

The IDC interfaces provided by the device-independent-device driver are:

  • Process Packet
  • Disable Support

Process Packet

This interface is called by the device-dependent-driver when it completes receiving and formatting Touch device data into the shared data buffer address, so that the data can be processed by the device-independent driver.

Input:

AX = Function Request Code = 0001H
SI = Shared data buffer offset
DS = Device-independent driver's DS value
ES = Device-dependent driver's DS value (caller)
BX,CX,DX, and DI register contents are undefined

Output:

AX = Error return code (if  Carry Set;
     undefined if Carry Clear)
DS = Device-independent driver's DS value
ES = Device-dependent driver's DS value (caller)
BX,CX,DX,SI and DI register contents are undefined

Disable Support

This interface is used by the device-dependent-device driver to inform the device-independent driver that it has received a Deinstall request and wants to release its system resources. The device-independent driver cannot uninstall itself at this point, but it can disable the API interfaces.

Input:

AX = Function Request Code = 0002H
DS = Device-independent driver's DS value
ES = Device-dependent driver's DS value (caller)
BX,CX,DX,SI and DI register contents are undefined

Output:

AX = Error Return Code (if Carry Set;
     undefined if Carry Clear)
DS = Device-independent-driver's DS value
ES = Device-dependent-driver's DS value (caller)
BX,CX,DX,SI and DI register contents are undefined

Device-Dependent to Device-Independent IDC Interface

The IDC interface provided by the Touch component of the device-dependent-device driver is identical to that provided by a PS/2 Mouse device-dependent-driver, with two exceptions: Enable and Disable device functions do not enable or disable the device at the IRQ level, which would cause the Touch device to be enabled or disabled simultaneously. The Enable and Disable device functions simply stop and start reporting of data to the device-independent driver.

The IDC interface provided by the Touch component of the device-dependent device driver consists of the following functions:

  • Query Configuration
  • Enable Read
  • Disable Write
  • Enable Device
  • Disable Device
  • Set Mouse Emulation State

Query Configuration

Input:

 AX = Function Request Code = 0001H
 DI = Configuration data buffer offset
 DS = Device-dependent driver's DS value
 ES = Device-independent driver's DS value (caller)
 BX,CX,DX, and SI register contents are undefined

ES:DI points to a data structure that is filled in by the device-dependent driver to convey configuration information back to the device-independent driver, according to the following format:

    config_data struc

               length    dw ?  ; length (inclusive) of structure in bytes
               irq_num   db ?  ; interrupt request level for device
               mou_stat  dw ?  ; mouse device status flags
                               ; bit 0 =1 Physical PS/2 mouse attached
                               ; bit 1 =1 Device independent driver attached
                               ; bit 2 =1 Protected mode emulation enabled
                               ; bit 3 =1 Real mode emulation enabled
               tou_stat  dw ?  ; touch device status flags
                               ; bit 0 =1 Touch device calibrated

        config_data ends

Output:

     AX = Error return code (if Carry Set, undefined if Carry Clear)
     DI = Configuration data buffer offset
     ES = Device-independent driver's DS value (caller)
     BX,CX,DX,SI and DS register contents are undefined

Enable Read

This function is issued by the device-independent driver to indicate that data packet processing has been set up and data transfer can begin.

Input:

 AX = Function Request code = 0002H
 DI = Shared interrupt data buffer offset
 DS = Device-dependent driver's DS value
 ES = Device-independent driver's DS value (caller)
 BX,CX,DX, and SI register contents are undefined

ES:DI points to the interrupt data packet structure in which the called device driver will write/return the touch data packet when a complete packet has been accumulated.

        touch_data struc

                    status    dw ?  ; touch display status
                    x_coord   dw ?  ; x coordinate of touch
                    y_coord   dw ?  ; y coordinate of touch
                    z_coord   dw ?  ; z coordinate of touch
                    x_range   dw ?  ; Xmax - Xmin
                    y_range   dw ?  ; Ymax - Ymin
                    z_range   dw ?  ; Zmax - Zmin

        touch_data ends

Note: X,Y,Z coordinates are reported in fixed 4096x4096x255 coordinate space. X increases left to right; Y increases top to bottom.

Output:

 AX = Error return code (if Carry Set, undefined if Carry Clear)
 ES = Device-independent driver's DS value (caller)
 BX,CX,DX,SI,DI and DS register contents are undefined

Disable Write

This function is called by the device-independent driver to indicate that data packet processing is no longer supported and that data transfers by way of Process Packet should be stopped until an Enable Read request is processed. Following this call, no further references should be made to the shared interrupt data buffer address previously provided by way of the last Enable Read request.

Input:

 AX = Function Request code = 0003H
 DS = Device-dependent driver's DS value
 ES = Device-independent driver's DS value (caller)
 BX,CX,DX,SI and DI register contents are undefined

Output:

 AX = Error return code (if Carry Set, undefined if Carry Clear)
 ES = Device-independent driver's DS value (caller)
 BX,CX,DX,SI,DI and DS register contents are undefined

Enable Device

This function is used to enable touch data event reporting from the device-dependent driver to the device-independent driver. It does not affect interrupt data processing at the IRQ level (which is shared between PS/2 Mouse and Touch devices); therefore, mouse data event processing and reporting is not affected.

Input:

 AX = Function Request code = 0004H
 DS = Device-dependent driver's DS value
 ES = Device-independent driver's DS value (caller)
 BX,CX,DX,SI and DI register contents are undefined

Output:

 AX = Error return code (if carry set, undefined if carry clear)
 ES = device independent driver's DS value (caller)
 BX,CX,DX,SI,DI and DS register contents are undefined

Disable Device

This function is used to disable Touch data event reporting from the device-dependent driver to the device-independent driver. It does not affect interrupt data processing at the IRQ level (which is shared between PS/2 Mouse and Touch devices); therefore, mouse data event processing and reporting is not affected.

Input:

 AX = Function Request code = 0004H
 DS = Device-dependent driver's DS value
 ES = Device-independent driver's DS value (caller)
 BX,CX,DX,SI and DI register contents are undefined

Output:

 AX = Error return code (if Carry Set, undefined if Carry Clear)
 ES = Device-independent driver's DS value (caller)
 BX,CX,DX,SI,DI and DS register contents are undefined

Set Mouse Emulation State

This function is used to control the way touch data packets are handled by the device-dependent driver. When emulation mode is set to Off, touch data packets are reported to the Touch device-independent driver only as direct X,Y,Z data packets. When mouse emulation mode is set to absolute, the touch data packet is additionally converted into a mouse data packet of absolute X,Y form, and reported to the mouse device-independent driver by way of its Process Packet Absolute IDC entry point. When mouse emulation mode is set to relative, the touch data packet is additionally converted into a mouse data packet of relative dx,dyform, and reported to the mouse device-independent driver by way of its standard Process Packet IDC entry point.

Input:

 AX = Function Request code = 0006H
 BX = Emulation mode (0=off 1=absolute 2=relative)
 DS = Device-dependent driver's DS value
 ES = Device-independent driver's DS value (caller)
 CX,DX,DI and SI register contents are undefined

Output:

 AX = Error return code (if Carry Set, undefined if Carry Clear)
 ES = Device-independent driver's DS value (caller)
 BX,CX,DX,DI,SI and DS register contents are undefined

Communications from Physical Device Driver to Virtual Device Driver

The physical device driver (PDD) uses touch data packets to communicate with the virtual device driver (VDD). While the virtual mouse device driver can receive mouse data from the Presentation Manager that is correctly adjusted for DOS window sizes and positions, the same is not true for touch data. Normally, therefore, a DOS session receives touch data only when it is running full screen (that is, a non-PM foreground session). In a PM session, all touch data is used to form emulated mouse packets and is reported to the physical mouse device driver. The virtual mouse device driver then receives the emulated mouse data by way of the normal PM route (or physical driver route if exclusive mouse access in On).

The exclusive touch access DOS property, however, permits a DOS window to receive all touch data when running in a PM session. The DOS window must be running maximized (except for text-mode applications where maximizing a window does not cover the full screen) in order to run without modification. Otherwise, the application has to perform the coordinate conversions itself, an impossible task for a DOS program because it has no knowledge of or access to window position and size information.

The VDD entry point is passed to the PDD when the VDD calls VDHOpenPDD with the 16:16 address of VTEventProc as a parameter, as shown in the following code:

VTEventProc Function 1 - Process Packet/Event
/*     VTEventProc - Process event packets from PDD.
 *
 *  ENTRY
 *     ulFunc == function code (VTDCMD_REPORT_EVENT)
 *     f16p1 -> MONREC
 *     f16p2 -  Not used.
 *
 *  EXIT
 *     None.
 *
 *  USES
 *     32-bit small-model PASCAL calling/register conventions
 *
 *  CONTEXT
 *     Interrupt time
 *
 *  PSEUDOCODE
 *     If handle and pointer are valid and touch is enabled,
 *         add the event to the VDE's buffer.
 */

 VOID     VDDENTRY VTEventProc(ULONG ulFunc, F16PVOID f16p1, F16PVOID f16p2;

The MONREC pointer points to a structure, as shown in the following example:

/*    + PTD-to-VTD communication structures
 *
 */

typdef struct {                                // VTDCMD_REPORT_EVENT
       USHORT            Status;
       ULONG             TimeStamp;
       USHORT            x;
       USHORT            y;
       USHORT            z;
    }  QEVENT, * PQEVENT, * *  PPQEVENT;

typedef struct {
            USHORT       SGId;
            QEVENT       Qevent;
    } MONREC, * PMONREC;

Virtual Device Driver to Physical Device Driver Communication

The primary function of this interface is to register the VDD with the PDD so that, later, the VDD can call the PDD back with data, establish the configuration setup (for example, physical mouse is attached or not, Touch display is calibrated or not, and so forth), and device control (such as emulation On or Off, DOS property exclusive access On or Off, and so forth).

The following functions are supported:

Register VDD
Query configuration
Set emulation state
Disable
Set exclusive access

Function 0: Register VDD - PddRegister

Establishes the VDD entry point for the PDD to call the VDD.

/*      PddRegisterVdd - Called when Vdd calls VDHOpenPDD()
 *
 *  Input:
 *       USHORT  pIBuff.off        VDD's CS
 *       USHORT  pIBuff.sel        Zero
 *       USHORT  pOBuff.off        Low 16 bits of EIP for VDD entry point
 *       USHORT  pOBuff.sel        High 16 bits of EIP for VDD entry point
 *
 *  Return:
 *       BOOL success (AX)
 *
 *  Usage:
 *       Success = PddEntry( 0, VddEntrySelector, VddEntryOffset);
 *
 *  Called from:
 *       PddEntry (seg3) via VdhOpenPdd()
 *
 */

STATIC VDMFUNC PddQueryConfig( PUSHORT pOFubb);

Function 1: Query Configuration - PddQueryConfig

Returns device configuration information, including device interrupt request (IRQ) level, mouse status (physical mouse present, MOUSE.SYS driver attached and emulation state) and touch status (calibrated or not).

/*      PddQueryConfig - Copy device config data to a vdd 16:16 ptr
 *
 *  Input:
 *       None.
 *
 *  Return:
 *       Configuration data:
 *               USHORT  size = 7
 *               UCHAR   irq
 *               USHORT  mouse status
 *               USHORT  touch status
 *       BOOL success (AX)
 *
 *  Usage:
 *       Success = PddEntry( 1, NULL, &ParmsAddr);
 *
 *  Called from:
 *       PddEntry (seg3) [QueryType(&TouHardware)]
 */

STATIC VDMFUNC PddQueryConfig( PUSHORT pOBuff);

Function 2: Set Emulation State - PddSetEmul

Used to switch mouse emulation in the DOS virtual machine Off or On (relative/glass mouse or absolute).

/*      PddSetEmul - Set emulation state
 *
 *  Input:
 *       Emulation data:
 *              USHORT  size = 3
 *              UCHAR   emul state (0 - off, 1 - absolute, 2 - glass)
 *
 *  Return:
 *       BOOL success (AX)
 *
 *  Usage:
 *       Success = PddEntry( 2, &DataAddr, NULL);
 *
 *  Called from:
 *       PddEntry (seg3)
 */

STATIC VDMFUNC PddSetEmul( PUSHORT pIBuff);

Function 3: Disable - PddDisable

Used to get information from the VDD that it is unable to load or get from the PDD.

/*      PddDisable -
 *  Input:
 *       None.
 *
 *  Return:
 *       BOOL success (AX)
 *
 *  Usage:
 *       Success = PddEntry( 3, NULL, NULL);
 *
 *  Called from:
 *       PddEntry (seg3)
 */

STATIC VDMFUNC PddDisable(VOID);

Function 4: Set exclusive access On/Off - PddSetExclAcc

Enables a DOS window to receive full-screen touch data. (Valid for the PM session only.) Mouse emulation is effectively turned Off when exclusive access is on.

/*      PddSetExclAcc - Set exclusive access On/Off
 *
 *  Input:
 *       Exclusive Access Data:
 *               USHORT  size = 3
 *               UCHAR   exclusive access flag (0 - off, 1 - on)
 *
 *  Return:
 *       BOOL success (AX)
 *
 *  Usage:
 *       Success = PddEntry( 4,&DataAddr, NULL);
 *
 *  Called from:
 */

STATIC VDMFUNC PddSetExclAcc( PUSHORT pIBuff);

Virtual Touch Device Driver Architecture

The following information describes the Virtual Touch Device Driver Architecture.

INT 7Fh Software Interrupt and Function Table Call Handling

Following is the sequence of events when a real-mode program issues a software interrupt that has been hooked by a VDD:

  1. At create time, VDD installs an interrupt vector hook (InstallHookVect()).
  2. The interrupt vector table gets patched with Address A.
  3. Address A points to an illegal real-mode instruction (ARPL).
  4. The software interrupt causes transfer to Address A.
  5. The execution of the ARPL located there causes a trap.
  6. The OS/2 operating system fields the trap.
  7. OS/2 hooks into the list of procedures registered for this trap by way of InstallHookVect and calls each one in turn.
  8. The hook procedures get passed a pointer to Client Register Frame (CRF).
  9. The hook procedures process the call, based on registers passed in the CRF.
  10. If the hook procedures interrupt, they call VDHPopInt(), which fills in the return CS:IP in the CRF.
  11. The hook procedures return TRUE if they are interrupted; else, FALSE.
  12. OS/2 calls the next procedure in the chain if FALSE; else, it returns to CS:IP as filled in the CRF.

See the following figure for the route from a real-mode application to the protect-mode VDD handler.

[Artwork not shown]

With the IBM Touch Display, the interface to the device driver is by way of a call table, the address of which the application obtains by issuing INT 7F with AX=ABCDH and BX=0H. When it has obtained the call table address ( CTA), it then calls the individual function it requires by calling the address at (CTA) + 4*(FN-1), where FN is the required device driver function number. This cannot be done in the previous sequence, however, because calls cannot be made directly from the DOS (real-mode) application to the OS/2 (protect-mode) VDD.

The mouse INT 33 driver has a related problem in that it has a BASIC entry point located 2 bytes forward of the actual INT 33 vector address. (The first instruction of the INT 33 handler is a jump over the BASIC entry point code.) Therefore, a BASIC application would obtain Address A and then call (Address A + 2), which could be anything.

To resolve this, the VDD must have a real-mode portion that has a software interrupt handler similar to that provided by the DOS driver. Address A, then, is replaced by the address of this handler (Address B) by the VDD at create time, as well as saving Address A in real-mode.

For the particular case of the IBM Touch Display driver, the call table also must be part of the real-mode portion, enabling calls to its entries to be made directly by real-mode applications, with the interrupt handler setting the address of the table in ES:BX as in the real DOS driver, before calling Address A. If the handler received a call that did not belong to it (AX !=ABCDH), then it would call Address A directly.

The entries in the call table then consist of a common call into a router. The router determines the function number from the address from which it was called, then sets up the registers appropriately before calling Address A, as shown in the following figure.

[Artwork not shown]

Physical Touch Device Driver - Virtual Touch Device Driver Interface

The physical Touch device driver - virtual Touch device driver interface is very similar to the physical Mouse device driver - virtual Mouse device driver interface, except that it passes absolute Touch X,Y,Z status data instead of Mouse row,column,status data.

The physical Touch device driver is aware at all times of which session owns the Touch device: When it is a foreground DOS session, it notifies the virtual Touch device driver of the touch events, which are immediately buffered in the virtual driver. The virtual driver then processes the event by updating the INT 7h data structures for the foreground DOS session, as well as handling the touch event user subroutine, if one is registered.

Notice that the specific-case Presentation Manager session is handled differently in the case of the mouse, where the event is sent to the PM single queue by the physical mouse driver. From there, PM notifies the DOS session whenever the mouse pointer is over a windowed DOS session, and performs coordinate conversion on behalf of the windowed session. Also, if an alternate mouse coordinate system is set up in the DOS session, the session must discard any events posted by PM that fall outside the coordinate system but, otherwise, are within the session window.

The Touch Display and its virtual Touch device driver do not have any such relationship between the device and PM, nor is there any architected mechanism for it to do so, because the single queue supports only keyboard and mouse events. This prevents the virtual Touch driver from providing full touch data for windowed DOS sessions or for supporting the Tdixxx API properly for VIO windows.

When a touch event is received while in a PM session, the physical device driver can handle the event only as though it were a normal full-screen OS/ 2 session; in other words, the event passes through the device monitor chain before being buffered in the physical device driver queue. This is because the physical device driver has no information regarding the arrangement of the PM Desktop, location and size of windowed DOS sessions, and so forth, to enable it to directly inform the virtual device driver of the event (correctly tagged, with the target DOS session handle and coordinates converted).

Event Notification

Each time the virtual Touch device driver is notified of a touch event, it might have to notify a DOS session user subroutine. This depends on whether the DOS session has a user subroutine registered by way of INT 7Fh, and whether the call mask conditions match the event.

The user subroutine is called by simulating an interrupt into the DOS session. An interrupt service routine (in the virtual Touch driver) is loaded into each DOS session at create time. This routine services an interrupt (PopInt, ClearIRR, issues SendVEOI, PushRegs), sets up a CRF containing the appropriate values of the registers, and then performs a VDHPushFarCall to the user subroutine. The routine also arms a return hook procedure to gain control after the user subroutine has completed. When the context of the DOS session next becomes current, it executes the user subroutine. When the return hook procedure gains control again, it performs only a PopRegs.

The interrupt number chosen for simulation is the hardware interrupt being used by the physical device driver. For 8516, this is IRQ 12, the same as for the PS/2 Mouse, depending on the ability to choose an interrupt number that will not conflict with another virtual device driver.

The 8516 Touch device and the PS/2 Mouse can simulate and service their own interrupts separately while using the same IRQ 12h, INT 74h. The virtual PIC driver will be able to handle interrupt simulations separately on the same interrupt (function 74h) for both the DOS session and the virtual Touch driver, but it will require that IRQ 12h, INT 74h is handled as a sharedinterrupt in the VDDs that simulate and service this interrupt.

Algorithms to Improve Touch Selection

In addition to the straightforward way of setting the selection-detection flag on Push Harder or Lift Off (where the snapshot X,Y value when crossing a given Z threshold is used directly), the X,Y,Z packets can be further processed to enhance the repeatability and accuracy of the X,Y report. Following is a list of these data processing algorithms:

  • Single-touch
  • Stable region (also called Back-in-the-Stack algorithm)
    The algorithms are activated by setting the appropriate bit in the selection-detection mechanism Type parameter of Function 6 "Set Selection Mechanism". Only one algorithm can be active at any given time, in either Push Harder or Lift Off modes.
  • Click locking
    Click locking was introduced primarily to facilitate the Presentation Manager's mouse-emulation mode, but it was found equally useful in the DOS environment.

Accuracy of the X,Y Report

Touch accuracy (or lack of it) is a primary reason for the need to improve Touch selection. There are many factors that affect Touch accuracy, including:

  • Style of touch

As the screen is touched, from the point of touch down to lift off, there can be appreciable movement of the reported X,Y position, even though the intent is to keep the contact point stationary. This can depend on the way the screen is touched; for example, a rapid stab at the screen ordinarily produces more variation than a slower, lighter touch.

  • On-screen touch threshold

Lowering the on-screen touch threshold makes the system not only more sensitive to touch but also to external unwanted noise, such as mechanical vibration.

  • Filter cut-off frequency

Increasing the system's low pass cut-off frequency can increase the system' s responsiveness to fast touches, but it does so at the expense of not being able to filter out unwanted noise, variation, and movement.

Single-Touch Algorithm

The single touch algorithm is designed to provide more consistent touch-down X,Y coordinates over a wide range of applied touch speed and pressure.

The single-touch algorithm prevents the snapshot X,Y data (taken at the first point of contact) being used when the subsequent data reports are moving away rapidly from the initial position. Rather, it ensures that the data reports have settled within a consistent area for a given number of reports. The size of the area and number of reports are determined by additional (optional) parameters.

The algorithm checks each point against the subsequent point; if the second differs from the first by an amount within the defined tolerance, a count is incremented. If not, the count is set to 0. Only when the count reaches the defined minimum is the data considered settledand the X,Y report given with the status of selection detected.

As the number of reports and tolerance parameters are tightened, so is the requirement for more controlled, slow, and deliberate touches. Lightly tapping or quickly stabbing the screen are less likely to trigger the algorithm, because of either insufficient data or too much variation within the data. For this reason, this algorithm is less likely to be of use in an untrained user or public kiosk type of environment where user frustration could result. Applications designed for such environments generally can avoid the effects of inaccuracy and repeatability by having more simply designed screens with large, widely spaced targets.

Pseudocode for the Single-Touch Algorithm

  If     status == touch-down
         single_touch X,Y = current X,Y
         touch_detected = single_touch_sent = FALSE
         count = RESET_VALUE
         return()

  If     status == on_screen
         if     selection_method == lift_off
                return()

         update_single_touch_xy()

         if     signal_touch_sent == FALSE && touch_detected = TRUE
                current X,Y = single_touch X,Y
                signal_touch_sent = TRUE
                return()

  If     status == lift_off
         if     selection_method == lift_off
                update_single_touch X,Y
                current X,Y = single_touch X,Y
                return()

Procedure update_single_touch_xy()

  if     absolute(current X,Y - single_touch X,Y) < tolerance
         single_touch X,Y = ( single_touch X,Y + current X,Y) / 2
         count --
         if  (count==0)
              set touch_detected

  else
         single_touch X,Y = current X,Y
         count = RESET_VALUE
  endif
endproc.

Back-in-the-Stack Algorithm

The Back-in-the-Stack (BIST) algorithm provides for detailed selection of an item (down to pel level at 640 x 480 resolution), even in the presence of varying X,Y data packets when the selection needs to be made.

For example, it might be relatively easy to adjust the touch contact so that the required (small) item is identified, but then much more difficult to actually perform the selection, either by lifting off or pressing harder, without involuntarily moving the X,Y position and thereby selecting the wrong item.

The BIST algorithm gets around this potential problem by exploiting the natural way in which such a selection would be made: usually the touch contact position is adjusted until the required item is identified, held momentarily, then the selection gesture made. Thus, instead of taking the snapshot X,Y position at the time the gesture is recognized (the time that the Z value exceeds the push-harder threshold or a lift-off event status is reported), it looks backinto a circularbuffer (a form of stack containing the Nmost recent X,Y,Z reports, where the oldest contents are continually being overwritten by the newest) to find the plateau region where the touch was held on the required item.

After having found a plateau region of sufficient length, the X,Y values of the data report containing the selection-detected status are taken from the average of the X,Y values of the reports in the stable region. In this way, the X,Y value reported is relatively immuneto any variations that take place in X,Y between the actual finding of the item and trying to select it. The following figure illustrates this technique:

    |   *
 C  |    **       *
 o  |      *       *    *           *
 o  |      *     *  **** ***** * *** *
 r  |        *  *             * *     *
 d  |          *                       *
 i  |         *                         *
 n  |                                    * *
 a  |                                       *
 t  |                                        *
 e  |                                         *  <----  Lift off
    |
    \----------------------------------------------------------------

        |          |               |                              Time --->
         Manipulation   Hold on item  Select item by
         to identify    to select     lift off
         item

Notice the typical way in which the X,Y position tends to slideaway from the required selection point (thereby making selection of the required item impossible by normal means) as the selection gesture is made by releasing the touch force.

Without the BIST algorithm, the smallest size a selection item can be is restricted to approximately twice the anticipated X,Y movement, from selection to lift off.

What the BIST algorithm provides, therefore, is the ability to track back through a short history of the data to determine that a selection point was, indeed, being held just prior to lift off. In this way, the selection item size is limited by the amount of X,Y jitter while a touch is being held steady.

An alternative use for the BIST algorithm is cancelling a selection when, otherwise, cancellation would be inevitable: this is the case where the selection method is lift off, and there is no dead area on the screen for the user to move to and lift off without selecting anything. Wherever the user decides to lift off, something will be selected. What, then, does the user do if the screen is touched by accident, or touched, followed by a decision to cancel the operation?

In either case, all the user must do is lift off in a long, exaggerated swiping motion. This fills up the stack (circular buffer) with continually varying data so that there is no plateau region for the algorithm to find. Detailed selection in the manner described, and/or the method of not- selecting, of course, is restricted to experienced users. Both are operations that require some degree of practice, and in the case of the ability to not-select, the knowledge that the facility even exists (since a full-screen select-sensitive application screen, presumably, would leave no room for help instructions).

Pseudocode for the Back-in-the-Stack Algorithm

Main Routine

        If status == on-screen
           put X,Y into circular buffer
           If selection method == Lift Off
              Return()
           Else     /* Must be push harder */
              If ( z < Push Harder Threshold )
                 Return()
              Else
                 Call Send_Stable_Data
              Endif
           Endif
        Else
           If status == touch-down
              flush circular buffer
              clear flags
           Else     /* lift-off */
              If selection method == Lift Off
                 Call Send_Stable_Data()
              Endif
        Endif

Send_stable_data

        Procedure Send_Stable_Data
           If already sent
              Return()
           Else
              Call Check_Buffer_For_Stable_Region()
              If Stable Region Detect flag
                 Current X,Y = Stable X,Y
                 Set flags
                 Return()
              Else
                 Return()
              Endif
           Endif
        EndProc

Check_Buffer_For_Stable_Region

        Procedure Check_Buffer_For_Stable_Region
           Stable Ref Point X,Y = Buffer Head X,Y
           Reset count, buffer index
           While points left in buffer
              Get buffer X,Y
              If ( Modulus( buffer X,Y - Stable Ref Point X,Y ) < Tolerance
                 count ++
                 If count >= Stable Region Size
                    Stable Region X,Y = Average X,Y over stable region
                    Set Stable Region Detect flag
                    Return()
                 Endif
              Else
                 Stable Ref Point X,Y = current X,Y
                 Reset count, buffer index
              Endif
           EndWhile
        Endproc

Click Locking

Click locking is the process by which the touch (X,Y) coordinate locks onto a value before being sent to the system as emulated mouse data.

Note: Click locking affects touch data only when it is sent as emulated mouse data and does not interfere with the normal use of an IBM PS/2 Mouse, if one is attached to the IBM Touch Display, or the data is sent in full touch pointing mode.

Click locking is performed because some actions with a clicked mouse button require that little movement of the mouse pointer itself take place. Click locking makes double clicking using the Touch display easier, because there is no need to maintain the touch position at exactly the same point between clicks.

The following examples of this can be found in the OS/2 Presentation Manager:

  • Clicking on an icon to bring up the system menu
  • Double clicking to activate the window

Clicking on an icon, when attempted with the Touch display's emulating the mouse, occasionally can result in the icon's moving a few pels, because the PM Desktop misinterprets the click down with associated movement as a drag operation to move the icon. PM decides that if the movement is more than a few pels, it must be a click with drag rather than a simple click. Thus, even a single click action sometimes can be unsuccessful.

The double-click action is more difficult: even if the first click can be made without moving the icon, the second click must be done at the same position. PM permits a small movement of 6 pels in the X direction and 8 pels in the Y direction. With a great deal of practice, this condition can be satisfied, but perhaps with only a 20% success rate.

Tip: For the least X,Y movement, keep the force variation to a minimum. In other words, do not press harder than necessary to achieve the button-down threshold; and do not lift off completely between clicks; rather, just release sufficiently to go below the button-up threshold. The usual outcome will be that the icon will move and/or the system menu will appear.

Click locking attempts to minimize the difficulty of maintaining the X,Y position while button clicking. While mainly applicable to PM, the click- locking technique is useful also in the DOS 4.0 shell and any application (usually in graphics mode) that uses a mouse.

The following click-lock options can be chosen:

  • No click locking
  • Single click locking
  • Double click locking
No Click Locking

Using this option, click locking can be turned off altogether, in which case, the system sees the touch coordinates directly as mouse coordinates.

Single Click Locking

This option locks the X,Y coordinates as soon as the button-down threshold has been exceeded. All subsequent touch coordinates are then reported to the system with this X,Y value when sent as emulated mouse data.

Normal reporting of X,Y coordinates resumes:

  • After the click-lock time has been exceeded
  • If the touch coordinate moves outside the click-lock area
  • If the touch is removed from the screen
Double Click Locking

This option is the same as single click locking, except that the conditions for reporting X,Y data are:

  • After the click-lock time has been exceeded
  • If the touch coordinate moves outside the click-lock area
  • If the button-down threshold is exceeded for a second time, the touch having been taken below the button-up threshold in the interim.

The third condition enables the X,Y coordinates of two successive touches to be locked at the same value. The touch need not be removed from the screen completely; it is sufficient just to go below the button-up threshold.

Click-Lock Area

This value determines the size of one side of a square that defines the click-lock area. The center of the square is located at the X,Y position at which the coordinates become locked. When the touch coordinates move outside the click-lock area, normal X,Y reporting is resumed.

The click-lock value is in pels, and, therefore, varies with screen resolution if a click-lock area of a given physical dimension is required. A large value makes double clicking at a point very easy, but it also makes immediate minor adjustment and close manipulation by dragging slightly more cumbersome.

Click-Lock Time

This value determines the time that is permitted to elapse between the time the coordinates first become locked and when normal X,Y reporting is resumed.

A large value makes double clicking a less hurried process but also makes immediate minor adjustments and close manipulation by dragging slightly more cumbersome.

Pseudocode for Click Locking

        Constants:
                   X_limit  = limit of allowed movement in X direction
                   Y_limit  = limit of allowed movement in Y direction
                   timeout  = limit of time between successive clicks
                   click_type = number of successive clicks to lock over

        Variables:
                   sd_count = number of successive clicks being locked over
                   sd_time  = system time at which timeout will occur
                   sd_X     = initial button down X position
                   sd_Y     = initial button down Y position
                   X        = current reported X position
                   Y        = current reported Y position

        Initial state:
                   sd_count = 0


        On entry to the procedure, the X,Y values are set to the current
        X,Y coordinate report.  A bit in a status word (selection
        detection bit) reflects the binary state of the emulated mouse
        button (1= button down 0= button up).

        /* Check if click locking active and still valid:
           if so, lock the coordinate,
           else reset the process
        */

        If sd_count != 0

           /* If click locking currently active */

           If sd_time > current time
              && modulus(x - sd_x) < x_limit
              && modulus(y - sd_x) < y_limit

              /* If not timed out and within lock area, */
              /* force current X,Y position to first click position */
              X = sd_X
              Y = sd_Y

              If button going up
                 && (sd_count >= click_type)

                 /* If the 'button' is being released and required */
                 /* number of clicks reached */
                 sd_count = 0       /* Reset the click locking process */
              Endif

           Else

              /* Timed out or moved outside lock area: reset click locking */
              sd_count = 0
           Endif
        Endif

        /* Check if button going down to increment sd_count,
           thereby starting click locking if it was previously 0,
           or incrementing towards the required number of clicks if not
        */

        If button going down

           /* Reinitialise timeout time on each button down */

           sd_time = current time + timeout

           If sd_count == 0

              /* If this is the first button down, set the lock coordinates
                 to the current X,Y values */

              sd_X = X
              sd_Y = Y

           Endif

           sd_count++         /* Increment click count */

        Endif

OS/2 Version Compatibility Considerations=

The following table lists any items discussed in this reference that have been added to OS/2 since OS/2 Warp Version 3.0 and discusses their compatibility with different versions of OS/2.

Item Added or Changed Date Item Added or Changed Compatibility of Addition or Change
Joystick Driver November 1995 OS/2 Warp, Version 3.0 and Later

Notices

IBM Developer Connection Device Driver Kit for OS/2, Version 4.02 Edition ( September 1997)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

Copyright Notices

COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."

(C) Copyright International Business Machines Corporation 1997. All rights reserved.
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products , except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.

Trademarks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

IBM
Multimedia Presentation Manager/2
OS/2
Ultimotion

The following terms are trademarks of other companies:

Helvetica Linotype Company
MASM Microsoft Corporation
Mitsumi Mitsumi Denki Kabushki Kaisha
Panasonic Matsushita Electric Industrial Co., Ltd.
OPTi OPTi, Inc.
Pioneer Pioneer Electric Corporation
ProAudio Spectrum Media Vision, Inc.
ProAudio Spectrum 16 Media Vision, Inc.
QuickVia Jovian Logic Corp.
ReelMagic Sigma Designs, Inc.
Sound Blaster Creative Technology Ltd.
SuperVia Jovian Logic Corp.
Super VideoWindows New Media Graphics Corporation
Video Blaster Creative Technology, Inc.
Yamaha Yamaha Corporation

Windows is a trademark of Microsoft Corporation.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.

Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.

Glossary