═══ 1. Notices ═══ Third Edition (September 1994) 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 authorized reseller or IBM marketing representative. ═══ 1.1. 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 1994. 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. ═══ 1.2. 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 IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectable rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. 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 the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A. ═══ 1.3. Trademarks ═══ The following terms are trademarks of the IBM Corporation in the United States or other countries: AT Common User Access CUA IBM Micro Channel OS/2 Personal System/2 Presentation Manager PS/2 SAA Systems Application Architecture Personal Computer AT WIN-OS/2 Workplace Shell XGA The following terms are trademarks of other companies: Borland Borland International, Inc. Intel Intel Corporation Logitech Logitech, Inc. Microsoft Microsoft Corporation PC Mouse Metagraphics/Mouse Systems PCMCIA Personal Computer Memory Card International Association RIPL CTA Inc. Windows Microsoft Corporation ═══ 2. About This Book ═══ The OS/2 Input/Output Device Driver Reference 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 OS/2 Physical Device Driver Reference and the Storage Device Driver Reference. ═══ 2.1. Summary of Changes ═══ The following are changes to the OS/2 Input/Output Device Driver Reference since the release of IBM Device Driver Source Kit for OS/2, Version 1.2. o All information for the virtual device drivers has been removed and can be found in the OS/2 Virtual Device Driver Reference. o Individual chapters on Device Driver Test Tools (DDTT's) have been added (Keyboard, Mouse, Parallel Port, and PCMCIA Socket Services). o A new chapter on the keyboard inter-device-driver (IDCs) communcations has been added. o Sample Socket Services has been added to PCMCIA. o The device driver chapters have been alphabetized for ease-of-use. Introduction describes the types of OS/2 device drivers. 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. 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. 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. 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. 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. ═══ 2.2. 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 Version 3 of the IBM Operating System/2. ═══ 2.3. Assistance ═══ Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS) known as the "DUDE." You are encouraged to use the DUDE 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 DUDE, dial 407-982-3217 (using a modem) to register and access the support system. For voice support in the United States, call 407-982-4239. Additional assistance is available through the IBM Developer Assistance Program. For membership information: Telephone: 407-982-6408 Fax: 407-988-7610 (U.S.A.) or Fax: 407-982-4259 (worldwide) ═══ 2.4. Ordering Information ═══ For an illustration of OS/2 Technical Publications and other related product documents, see the following figure. The IBM Developer Connection Device Driver Kit for OS/2 on CD-ROM contains actual source code for sample device drivers, as well as the complete text of the books in online form. To order any of the publications shown in the illustration, call: ┌────────────────────┬─────────────────────┬─────────────────────┐ │U.S.A.: │1-800-633-8266 │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Canada: │1-800-561-5293 │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Europe, Middle East,│ English language │(+45) 48101500 │ │Africa, and │ French language │(+45) 48101200 │ │Latin America: │ Italian language │(+45) 48101600 │ │ │ German language │(+45) 48101000 │ │ │ Spanish language │(+45) 48101100 │ │ │ Dutch language │(+45) 48101400 │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Asia/Pacific: │ All except Japan │(61) 2-354-7684 │ │ │ Japan │(81) 3-3495-2045(Fax)│ │ │ │Fax request to: │ │ │ │DAP-J, IBM Japan │ ├────────────────────┼─────────────────────┼─────────────────────┤ │SE Brazil: │(021) 800-6120(Voice)│ │ │ │(021) 800-6936(Fax) │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Mexico: │ Mexico City │627-2444 │ │ │ Country │91-800-00639 │ └────────────────────┴─────────────────────┴─────────────────────┘ ═══ 3. 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. ═══ 3.1. Types of OS/2 Device Drivers ═══ Three types of device drivers are used in OS/2 Version 3: o Physical device drivers o Virtual device drivers o Presentation drivers ═══ 3.1.1. 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: o Advanced Power Management o Asynchronous Communication (RS-232C) o CD-ROM o Hard Disk and Diskette o Keyboard o Mouse o Parallel Port Printer o PCMCIA o System Clock o Touch Screen o Video ═══ 3.1.2. 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. ═══ 3.1.3. 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. ═══ 4. 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. ═══ 4.1. 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 1.0 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 1.0 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.0 Architecture and includes functions specific to the OS/2 system components. ═══ 4.1.1. OS/2 APM Software Components ═══ There are four major software components defined in the OS/2 Power Management Architecture: o 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. o 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. o 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). o 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. ═══ 4.2. 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 2.1 (or later). 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.0 specifications and the OS/2 Power object adheres to the 1.0 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. ═══ 4.3. 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 2.1 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: o /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. o /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. 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 APM 1.0 Interface 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. ═══ 4.3.1. 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. The events reported by way of the Get Power Management Event function are equivalent to the power management event messages available from the OS/2 Power Management Services Layer. Message names containing the word Event are reported directly from the Advanced Power Management BIOS interface. ┌───────────────────────────┬─────────────────┬─────────────────┐ │OS/2 Power Management │ │ │ │Event Messages │ ulParm1 │ ulParm2 │ │ │ SubID │Reserved│ (msg-specific) │ ├───────────────────────────┼────────┼────────┼────────┬────────┤ │Enable Pwr Mgt Functions │ 0003h │ 0000h │ - - - │ - - - │ ├───────────────────────────┼────────┼────────┼────────┼────────┤ │Disable Pwr Mgt Functions │ 0004h │ 0000h │ - - - │ - - - │ ├───────────────────────────┼────────┼────────┼────────┼────────┤ │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 │ - - - │ - - - │ ├───────────────────────────┴────────┴────────┴────────┴────────┤ │ 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. o Enable Power Management Function Indicates that the Advanced Power Management BIOS request for power management assistance is being enabled. - Parameters ────────────────────────────────────────────────────────────────────────── SubId(USHORT) = 0003H ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(0,0) ────────────────────────────────────────────────────────────────────────── - Notification order 1. Device drivers 2. Application programs o Disable Power Management Function Indicates that the Advanced Power Management BIOS request for power management assistance is being disabled. - Parameters ────────────────────────────────────────────────────────────────────────── SubId(USHORT) = 0004H ulParm1 = MAKEULONG(SubId,0) ulParm2 = MAKEULONG(0,0) ────────────────────────────────────────────────────────────────────────── - Notification order 1. Application programs 2. Device drivers o 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 o 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 1.0 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 1.0 Specification is listed in Power Management States. - Notification order 1. Application programs 2. device drivers o 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 o 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 o 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 ═══ 4.3.1.1. 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. ═══ 4.3.2. 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.0 │OS/2 Power Management IDC │ │BIOS Functions │Functions │ ├──────────────────────────────┼──────────────────────────────┤ │Installation Check (00h) │QueryPowerInfo (0004h) │ ├──────────────────────────────┼──────────────────────────────┤ │Interface Connect (01h) │N/A │ ├──────────────────────────────┼──────────────────────────────┤ │Protect-Mode Connect 16-Bit │N/A │ │(02h) │ │ ├──────────────────────────────┼──────────────────────────────┤ │Protect-Mode Connect 32-Bit │N/A │ │(03h) │ │ ├──────────────────────────────┼──────────────────────────────┤ │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 │SendPowerEvent (0002h) │ │(08h) │ │ ├──────────────────────────────┼──────────────────────────────┤ │Restore BIOS Defaults (09h) │SendPowerEvent (0002h) │ ├──────────────────────────────┼──────────────────────────────┤ │Get Power Status (0Ah) │QueryPowerStatus (0003h) │ ├──────────────────────────────┼──────────────────────────────┤ │Get Pwr Mgt Event (0Bh) │RegisterDDRtn/DeregisterDDRtn │ │ │(0000h)/(0001h) │ └──────────────────────────────┴──────────────────────────────┘ 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. ═══ 4.3.2.1. 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 All other values are reserved. ────────────────────────────────────────────────────────────────────────── The OS/2 Power Management IDC functional descriptions are defined as follows: o 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: o 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. o EventHandler Input parameter. The calling device driver's Selector:Offset value of the calling device driver's Event Handler routine. o 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 All other bits are reserved. See Power Management Event Messages for more details on the Power Management Events previously described. o 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. o DeviceID Input parameter. The ID of the device. The set of device types supported by the Advanced Power Management 1.0 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. - Remarks 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: o Function Input parameter. Must be the following value: - Event Notification = 0000H. All other values are reserved. o ulParm1 Input parameter. See the previous figure "Power Management Event Messages and Parameter Values" and Power Management Event Messages for value descriptions. o ulParm2 Input 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. The OS/2 2.1 APM Subsystem only checks the AX return value for Suspend Event notification requests. If a device driver fails a Suspend Event request, 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. All other register values are preserved across the call by the Event Handler routine. o Power Management IDC Function 1 - DeregisterDDRtn The DeregisterDDRtn function is used by a power-management-sensitive 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: o 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. o Power Management IDC Function 2 - SendPowerEvent The SendPowerEvent function enables a power-management-sensitive 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. Refer to Category OCh, Function 40h, "Send Power Event" in the 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. o Power Management IDC Function 03h - QueryPowerStatus The QueryPowerStatus function is used by a power-management-sensitive 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 │ └────────────────────┴────────────┴────────────┘ - Remarks None. Refer to Category OCh, Function 60h, "Query Power Status" in the OS/2 Physical Device Driver Reference for more information. o Power Management IDC Function 04h - QueryPowerInformation The QueryPowerInfo function is used by a power-management-sensitive 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 │ └────────────────────┴────────────┴────────────┘ - Remarks None. Refer to Category OCh, Function 62h, "Query Power Information" in the the OS/2 Physical Device Driver Reference for more information. ═══ 4.3.2.2. 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.│ └───────────────┴─────────────────────────────────────────────┘ ═══ 4.3.3. 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: o Set/Send functions = 0100xxxxB o 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.0 │OS/2 Power Management IOCtls │ │BIOS Functions │ │ ├──────────────────────────────┼──────────────────────────────┤ │Installation Check (00h) │Query Power Info (Function │ │ │62h)*** │ ├──────────────────────────────┼──────────────────────────────┤ │Interface Connect (01h) │N/A │ ├──────────────────────────────┼──────────────────────────────┤ │Protect-Mode Connect 16-Bit │N/A │ │(02h) │ │ ├──────────────────────────────┼──────────────────────────────┤ │Protect-Mode Connect 32-Bit │N/A │ │(03h) │ │ ├──────────────────────────────┼──────────────────────────────┤ │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 │Send Power Event (Function │ │(08h) │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 Reference for descriptions of the IOCtls. ═══ 4.4. 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: o Queue up the request o Fail the request o 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. o If present, the driver sets up to support power management activities (such as locking power management code segments). o 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: o 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. o A Dynamic Link Library (DLL), which provides the Options page for the Power object utilizing the user-defined IOCtls. o 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 APM 1.0 Interface 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: o APM device IDs, which are defined by the APM 1.0 Interface Specification. o 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. o Effects of power management states on the device, (power supply and device capabilities). ═══ 4.4.1. Power Management Devices ═══ The device types supported by the Advanced Power Management 1.0 Specification are: o System BIOS (0000h) Device ID for Advanced Power Management BIOS o System BIOS-managed devices (0001h) Generic device ID for all devices managed by Advanced Power Management BIOS. o Display devices (01xxh) Generic device ID for display devices o Secondary storage devices (02xxh) Generic device ID for secondary storage devices o Parallel ports (03xxh) Generic device ID for parallel ports o Serial ports (04xxh) Generic device ID for serial ports Note: 1. XX indicates 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.4.2. Internal/External Power ═══ An internally powered device is 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 device is 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. ═══ 4.4.3. 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 1.0 Specification. o 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. o 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. o 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 1.0 BIOS Interface 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. o 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). All other power state values are reserved. ═══ 4.5. 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.0 Interface functions are used or required by the OS/2 APM subsystem. ┌──────────────────────────────┬──────────────────────────────┐ │APM 1.0 BIOS Functions │Required for OS/2 │ ├──────────────────────────────┼──────────────────────────────┤ │Installation Check (00h) │Yes │ ├──────────────────────────────┼──────────────────────────────┤ │Interface Connect (01h) │No │ ├──────────────────────────────┼──────────────────────────────┤ │Protect-Mode Connect 16-Bit │Yes** │ │(02h) │ │ ├──────────────────────────────┼──────────────────────────────┤ │Protect-Mode Connect 32-Bit │Yes** │ │(03h) │ │ ├──────────────────────────────┼──────────────────────────────┤ │Interface Disconnect (04h) │No │ ├──────────────────────────────┼──────────────────────────────┤ │CPU Idle (05h) │Yes │ ├──────────────────────────────┼──────────────────────────────┤ │CPU Busy (06h) │Yes │ ├──────────────────────────────┼──────────────────────────────┤ │Set Power State (07h) │Yes │ ├──────────────────────────────┼──────────────────────────────┤ │Enable/Disable Pwr Mgt Fcns │Yes │ │(08h) │ │ ├──────────────────────────────┼──────────────────────────────┤ │Restore BIOS Defaults (09h) │Yes │ ├──────────────────────────────┼──────────────────────────────┤ │Get Power Status (0Ah) │Yes │ ├──────────────────────────────┼──────────────────────────────┤ │Get Pwr Mgt Event (0Bh) │Yes │ └──────────────────────────────┴──────────────────────────────┘ Note: ** Only one of these functions is required per BIOS implementation. ═══ 4.5.1. 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. ═══ 4.5.2. 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: o Protect-mode 16-bit interface is the only mode supported. o 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. o 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 APM 1.0 Interface 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: o The APM BIOS device driver, which exports user-defined generic IOCtls for GUI/application level interactions and emulates the APM 1.0 BIOS interface (by way of IDC) for the APM subsystem interactions. o A dynamic link library (DLL), which provides the Options page for the Power object utilizing the user-defined IOCtls. o 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). ═══ 5. 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: o Services the RS232-C port in an interrupt-driven manner o Provides transmit and receive queues o Provides different automatic control modes for the modem control signals o 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. ═══ 5.1. Hardware Support ═══ The RS232-C ASYNC communications device driver supports any personal computer system based on an 80386SX (or higher) microprocessor. ═══ 5.1.1. 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. ═══ 5.1.2. 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: o 3F8H (must generate a level 4 interrupt) o 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: o IBM AT-bus serial/parallel adapter based on the NS 16450 Universal Asynchronous Receiver Transmitter (UART) device o Other compatible adapters based on the UART architecture (NS 16550, NS 16550A) ═══ 5.1.3. 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: o To allow an application program to support a special device not adequately supportable with this ASYNC device driver. o To allow additional COM ports (besides COM1-4 on IBM PS/2) to be supported. o To enhance the level of device driver function for a given COM port. (This might be required for certain subsystem support.) ═══ 5.1.4. 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: o Data Terminal Ready (DTR) o Request To Send (RTS) There are four separate modem control signals whose input values are available to the physical device driver: o Data Set Ready (DSR) o Clear To Send (CTS) o Data Carrier Detect (DCD), also known as Receive Line Signal Detect (RLSD) o Ring Indicator (RI) The receive and transmit data lines have the following hardware characteristics: o Logical 1 (Marking). More negative than -3 Volts. This state could mean no data. o Logical 0 (Spacing). More positive than +3 Volts. This state could mean break condition. The modem control signal lines have the following hardware characteristics: o Function ON, when more positive than +3 Volts. o Function OFF, when more negative than -3 Volts. ═══ 5.1.5. 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. ═══ 5.1.6. 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. ═══ 5.1.7. 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: o 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. o 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). o 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. o 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. ═══ 5.2. 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: o Query Number of Characters in Receive Queue (ASYNC_GETINQUECOUNT) o 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: o Controlling or monitoring those modem control signals o Monitoring the queue status o 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. ═══ 5.2.1. 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: o Open and Close processing of DTR and RTS o Disable/Enable DTR and RTS o RTS toggling on transmit o 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. ═══ 5.2.2. 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: o Output handshaking using CTS, DSR, DCD o 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. ═══ 5.2.3. Logical Flow Control (XON/XOFF) ═══ The application can attempt to manually control the flow of data by using the following IOCtls: o Transmit Immediate (ASYNC_TRANSMITIMM) o Stop Transmit Behave as if XOFF Received (ASYNC_STOPTRANSMIT) o 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). ═══ 5.2.4. 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. ═══ 5.2.5. 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. ═══ 5.2.6. 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. ═══ 5.2.7. 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. o Query COM Event Information (ASYNC_GETCOMMEVENT) o Query COM Status (ASYNC_GETCOMMSTATUS) o Query COM Error (ASYNC_GETCOMMERROR) ═══ 5.2.8. 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. ═══ 5.3. 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: o 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. o 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. o 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. o 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. ═══ 5.4. 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: o Automatic Receive Flow Control (XON/XOFF) o Automatic Transmit Flow Control (XON/XOFF) o Bit Rate o Break Replacement Character o Break Replacement Character Processing o COM Event WORD and COM Error WORD o Data Bits o DTR and RTS o DTR Control Mode o Error Replacement Character o Error Replacement Character Processing o Extended Hardware Buffering o Input Sensitivity Using DSR o Null Stripping o Output Handshaking Using CTS, DSR, DCD o Parity o RTS Control Mode o Read Timeout State o Read Timeout Value o Stop Bits o Transmit Immediate o Transmitting Break o Write Timeout State o Write Timeout Value o XON/XOFF Characters Each of the above states are covered as follows: o A brief description. o The initial (default) value. o 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. o 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. o 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. ═══ 5.4.1. 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. ═══ 5.4.2. 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). ═══ 5.4.3. 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 ═══ 5.4.4. 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 ═══ 5.4.5. 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. ═══ 5.4.6. 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 ═══ 5.4.7. 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 ═══ 5.4.8. 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. ═══ 5.4.9. DTR Control Mode ═══ The control modes for DTR are: o Enable o Disable o 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 ═══ 5.4.10. 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 ═══ 5.4.11. 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. ═══ 5.4.12. 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: o Enabled o Disabled o 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: o Enabled for Input Sensitivity Using DSR o Enabled for Output Handshaking Using CTS and DSR o Disabled for Output Handshaking Using DCD o 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: o 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. o 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 ═══ 5.4.13. 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. ═══ 5.4.14. 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. ═══ 5.4.15. 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. ═══ 5.4.16. 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 ═══ 5.4.17. RTS Control Mode ═══ The control modes for RTS are: o Enable o Disable o Input Handshaking o 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 ═══ 5.4.18. 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 Normal Timeout processing, if no data is received in the specified period of time, the request is completed. With No-Wait Timeout 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-Something Timeout 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 ═══ 5.4.19. 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 Timeout or Wait For Something Timeout processing is enabled. Initial Value 1 minute First Level Open Set to 1 minute Mode Utility No effect ═══ 5.4.20. 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 ═══ 5.4.21. 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. ═══ 5.4.22. 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. ═══ 5.4.23. 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 ═══ 5.4.24. 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 ═══ 5.4.25. 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 ═══ 5.5. 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. ═══ 5.5.1. 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. ═══ 5.6. 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. ═══ 5.6.1. 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: o The device driver must get an INIT request packet for the device name. o The 40: area that corresponds to the device name must have a valid I/O address. o 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: o Not allowing this physical device driver to receive an INIT request packet for a given device name o Putting an invalid I/O address in the corresponding 40: area (for example, 0) o 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: o The physical device driver must get an INIT request packet for the device name. o 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: o Not allowing this device driver to receive an INIT request packet for a given device name. o Claiming the appropriate ASYNC LID. ═══ 5.7. 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. ═══ 5.8. 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: o Break Processing o Device Control Block (DCB) Parameter Access o Device Driver I/O Queue Management o Line Characteristics o Manual XON/XOFF Processing o Polled Event Functions ═══ 5.8.1. 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 │ └──────────┴──────────────────────────────────────────────────┘ ═══ 5.8.1.1. 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. ═══ 5.8.1.2. 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: o Clears the receive and transmit queues o Turns break OFF, if it is currently transmitting a break o 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 o 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 o Waits until all the data in the transmit hardware has been physically transmitted o Relinquishes the interrupt level o Turns DTR and RTS OFF, if they are not already OFF. The physical device driver first waits the specified number of character times o Relinquishes the Logical ID for the device (on PS/2 machines) ═══ 5.8.1.3. 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. ═══ 5.8.1.4. 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. ═══ 5.9. 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. ═══ 5.10. 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: o Automatic Transmit Flow Control (start/stop transmit, when XON/XOFF received) o Automatic Receive Flow Control (transmit XON/XOFF, when receive buffer fills/empties) o XON/XOFF Characters o DTR Control Mode (enable/disable/input handshaking) o RTS Control Mode (enable/disable/input handshaking/toggling on transmit) o Output Handshaking Using CTS/DSR/DCD (control signal determines when to transmit) o Input Sensitivity Using DSR (reception of data controlled by DSR) o Error Replacement Character and Processing o Break Replacement Character and Processing o Null Stripping o Timeout Processing o 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. ═══ 5.11. 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. ═══ 5.12. 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. ═══ 5.13. 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. ═══ 5.13.1. 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: o If the user does not care if too many characters are transmitted after a modem connection is broken o 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. o If the system is connected to a modem or another system that is normally set up to always keep DSR ON. o 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. ═══ 6. CLOCK$ Device Driver ═══ This chapter discusses the physical CLOCK$ device driver. ═══ 6.1. 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. ═══ 6.2. 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: o RTREAD(4) o STREDY(5) o STCOMP(6,7) o RTWRIT(8,9) o RTIOCT(16) o RTINIT(27) o RTINIT2(0) o 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. ═══ 6.2.1. 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). ═══ 6.2.2. 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 ────────────────────────────────────────────────────────────────────────── ═══ 6.2.2.1. 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. ═══ 6.2.2.2. STREDY ═══ STREDY performs a non-destructive read operation with no-wait. ═══ 6.2.2.3. STCOMP ═══ STCOMP sets the status to "complete". ═══ 6.2.2.4. RTWRIT ═══ The Realtime Clock Write routine supports the device driver functions: o WRITE (function 8) o 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│CURRENT CENTURY│ │ YEAR - BCD │ YEAR - BINARY │ ├───────────────┼───────────────┤ BP+14 │ YEAR-BCD │ YEAR-BINARY │ ├───────────────┼───────────────┤ BP+12 │ MONTH-BCD │ MONTH-BINARY │ ├───────────────┼───────────────┤ BP+10 │ DAY OF MONTH │ DAY OF MONTH │ │ BCD │ BINARY │ ├───────────────┼───────────────┤ BP+8 │ DAY OF WEEK │ DAY OF WEEK │ │ BCD │ 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. ═══ 6.2.2.5. RTIOCT ═══ The Realtime Clock Generic IOCTL routine supports the category 0Dh generic IOCTL commands by calling the appropriate worker routine. ═══ 6.2.2.6. RTINIT ═══ RTINIT initializes data structures and the Realtime Clock device. ═══ 6.2.2.7. 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. ═══ 7. 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. ═══ 7.1. 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): o Translates the scan code to an ASCII character o Recognizes the key as a special key and signals the appropriate routine for processing o Passes the translated scan code's character data record to the monitor dispatcher for further custom processing by monitors o 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: o 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. o The code pages used are defined in CONFIG.SYS with the CODEPAGE and DEVINFO commands. o Using the KEYB command, the language layout of the keyboard can be changed. o 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. o 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. o 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. o KbdSetCustXt adds a custom code page option. o KbdXlate translates a scan code. o KbdSetCp, KbdGetCp, and KbdXlate can be replaced in the subsystem by the use of the KbdRegister function. o 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. 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. ═══ 7.2. 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. ═══ 7.3. 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. ═══ 7.3.1. 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 │ └────────────────────────┘ ═══ 7.3.1.1. 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. ═══ 7.3.1.2. 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. ═══ 7.3.1.3. 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. ═══ 7.3.1.4. 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: o Value for keys that are always placed in the KIB. Zero = no special action, always place in KIB. o 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. o 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 code field 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. o Values for packets not generated by a keystroke: 30h-37h RESERVED. 38h-3Eh RESERVED. Treated as undefined. See entry 3Fh. o 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. ═══ 7.3.2. 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│Value Placed in│ │ │ │or Signal │KIB │ │ │ │Handler Called │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │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 │Pressed twice means system dump │ │Ctrl+Alt+F10 │ │ ├────────────────────┼────────────────────────────────────────┤ │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. ═══ 7.4. 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: 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. ═══ 7.5. 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: o SRC\DEV\KBD\KBDBASE\MAKEFILE o SRC\DEV\KBD\IBMKBD\MAKEFILE For example: ────────────────────────────────────────────────────────────────────────── CD\DDK\SRC\DEV\KBD\KBDBASE\NMAKE ────────────────────────────────────────────────────────────────────────── ═══ 8. 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. ═══ 8.1. 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 ═══ 8.1.1. 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) ────────────────────────────────────────────────────────────────────────── ═══ 8.1.2. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.1.3. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.1.4. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.1.5. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2. 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) ═══ 8.2.1. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2.2. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2.3. 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) ────────────────────────────────────────────────────────────────────────── ═══ 8.2.4. 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 ────────────────────────────────────────────────────────────────────────── ═══ 8.2.5. 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 ────────────────────────────────────────────────────────────────────────── ═══ 8.2.6. 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 */ } ────────────────────────────────────────────────────────────────────────── ═══ 8.2.7. 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) ────────────────────────────────────────────────────────────────────────── ═══ 8.2.8. 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) ────────────────────────────────────────────────────────────────────────── ═══ 8.2.9. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2.10. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2.11. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2.12. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2.13. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2.14. 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) ────────────────────────────────────────────────────────────────────────── ═══ 8.2.15. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2.16. 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. ────────────────────────────────────────────────────────────────────────── ═══ 8.2.17. 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. ────────────────────────────────────────────────────────────────────────── ═══ 9. Keyboard Device Driver Test Tool ═══ This chapter explains how to use the keyboard Device Driver Test Tool. ═══ 9.1. 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. ═══ 9.1.1. 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: o DDTKBD.DLL o KBD.GRA. o 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: o DDTT.EXE o DDTT.DLL o GLOBAL.DLL o GLOBAL.GRA ═══ 9.1.2. 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. ═══ 9.1.3. 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. ═══ 9.1.4. KBDDD.SYS Test Grammar Function Calls ═══ The following is a list of the KBDDD.SYS Test Grammar Function Calls: o KBD_OPEN o KBD_CLOSE o KBD_QUERY_CAPS o KBD_QUERY_TYPEMATIC o KBD_QUERY_LEDS o KBD_QUERY_IDS o KBD_QUERY_DISABLED o KBD_SEND_CMD o KBD_FLUSH o KBD_SAVE_STATE o KBD_RESTORE_STATE o KBD_DISABLE and KBD_DISABLE_I o KBD_ENABLE and KBD_ENABLE_I o KBD_RESET and KBD_RESET_I o KBD_OPEN_DI o KBD_CLOSE_DI o KBD_PROCESS_KEY o KBD_PROCESS_REINIT o KBD_PRINT_LAST_IDC ═══ 9.1.4.1. KBD_OPEN ═══ This function opens the TESTKBD.SYS device driver and sends an open IDC to IBMKBD.SYS. ═══ 9.1.4.1.1. Input Parameter Keywords ═══ None. ═══ 9.1.4.1.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.1.3. Logged Data ═══ None. ═══ 9.1.4.2. KBD_CLOSE ═══ This function sends a close IDC to KBDDD.SYS and closes the TESTKBD.SYS device driver. ═══ 9.1.4.2.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.2.2. Output Parameter Keywords ═══ None. ═══ 9.1.4.2.3. Logged Data ═══ None. ═══ 9.1.4.3. KBD_QUERY_CAPS ═══ This function queries the capabilities of the keyboard. ═══ 9.1.4.3.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.3.2. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.3.3. 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 ═══ 9.1.4.4. KBD_QUERY_TYPEMATIC ═══ This function queries the current typematic rate and delay of the keyboard. ═══ 9.1.4.4.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.4.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │TYPASEL │NUM │Typematic rate │ │ │ │selector (0-31) │ ├────────────────────┼────────────────────┼────────────────────┤ │DELAYSEL │NUM │Delay value selector│ │ │ │(0-3) │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.4.3. Logged Data ═══ Typematic rate selector (0-31) Delay value selector (0-3) ═══ 9.1.4.5. KBD_QUERY_LEDS ═══ This function queries to determine which LEDs are lit. ═══ 9.1.4.5.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.5.2. Output Parameter Keywords ═══ None. ═══ 9.1.4.5.3. Logged Data ═══ Scroll Lock is ON/OFF Num Lock is ON/OFF Caps Lock is ON/OFF ═══ 9.1.4.6. KBD_QUERY_IDS ═══ This function queries the ID value and keycount of the keyboard. ═══ 9.1.4.6.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.6.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │KEYCOUNT │NUM │Number of keys │ ├────────────────────┼────────────────────┼────────────────────┤ │ID │NUM │ID code for keyboard│ │ │ │hardware │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.6.3. Logged Data ═══ Number of keys ID code for keyboard hardware ═══ 9.1.4.7. KBD_QUERY_DISABLED ═══ This function queries to determine if the keyboard has been disabled. ═══ 9.1.4.7.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.7.2. Output Parameter Keywords ═══ None. ═══ 9.1.4.7.3. Logged Data ═══ Keyboard enabled or disabled ═══ 9.1.4.8. KBD_QUERY_READY ═══ This function queries whether the keyboard is ready. ═══ 9.1.4.8.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.8.2. Output Parameter Keywords ═══ None. ═══ 9.1.4.8.3. Logged Data ═══ Keyboard ready or not ready ═══ 9.1.4.9. KBD_SEND_CMD ═══ This function sends a generic command to the keyboard. ═══ 9.1.4.9.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ ├────────────────────┼────────────────────┼────────────────────┤ │COMMAND │STRING │Command string │ ├────────────────────┼────────────────────┼────────────────────┤ │ACK │NUM │Nonzero if │ │ │ │acknowledgement is │ │ │ │required │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.9.2. Output Parameter Keywords ═══ None. ═══ 9.1.4.9.3. Logged Data ═══ None. ═══ 9.1.4.10. KBD_FLUSH ═══ This function flushes partial keystrokes and returns the keyboard to a start state. ═══ 9.1.4.10.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.10.2. Output Parameter Keywords ═══ None. ═══ 9.1.4.10.3. Logged Data ═══ None. ═══ 9.1.4.11. KBD_SAVE_STATE ═══ This function saves the keyboard state and is used by the Advanced Power Management System. ═══ 9.1.4.11.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.11.2. Output Parameter Keywords ═══ None. ═══ 9.1.4.11.3. Logged Data ═══ None. ═══ 9.1.4.12. KBD_RESTORE_STATE ═══ This function restores the keyboard's saved state. This function is used by the Advanced Power Management System. ═══ 9.1.4.12.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.4.12.2. Output Parameter Keywords ═══ None. ═══ 9.1.4.12.3. Logged Data ═══ None. ═══ 9.1.5. 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. ═══ 9.1.5.1. KBD_DISABLE and KBD_DISABLE_I ═══ These functions disable the keyboard. ═══ 9.1.5.1.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.5.1.2. Output Parameter Keywords ═══ None. ═══ 9.1.5.1.3. Logged Data ═══ None. ═══ 9.1.5.2. KBD_ENABLE and KBD_ENABLE_I ═══ These functions enable the keyboard. ═══ 9.1.5.2.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.5.2.2. Output Parameter Keywords ═══ None. ═══ 9.1.5.2.3. Logged Data ═══ None. ═══ 9.1.5.3. KBD_RESET and KBD_RESET_I ═══ These functions reset the keyboard. ═══ 9.1.5.3.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HANDLE │NUM │Handle for │ │ │ │TESTKBD.SYS │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.5.3.2. Output Parameter Keywords ═══ None. ═══ 9.1.5.3.3. Logged Data ═══ None. ═══ 9.1.5.4. KBD_SET_TYPEMATIC and KBD_SET_TYPEMATIC_I ═══ These functions set the typematic rate and delay of the keyboard. ═══ 9.1.5.4.1. 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) │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.5.4.2. Output Parameter Keywords ═══ None. ═══ 9.1.5.4.3. Logged Data ═══ None. ═══ 9.1.5.5. KBD_SET_LEDS and KBD_SET_LEDS_I ═══ These functions set the LEDs. ═══ 9.1.5.5.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.1.5.5.2. Output Parameter Keywords ═══ None. ═══ 9.1.5.5.3. Logged Data ═══ None. ═══ 9.2. 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. ═══ 10. 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: o MOUSE$. The OS/2 system-provided pointing device driver name, which is defined in the device header field of MOUSE.SYS. o IDC. Inter-Device-Communication. o Device-Independent-Device Driver. Another way of referring to MOUSE.SYS, which handles all the IDC interfaces defined on the following pages. o 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. ═══ 10.1. 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. ═══ 10.1.1. 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. ═══ 10.1.2. 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. ═══ 10.2. 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. ═══ 10.3. MOUSE.SYS IDC Interface ═══ The IDC provided by MOUSE.SYS supports the following: o Process_Packet o Disable_Support o Process_Absolute o Open_Mouse o Close_Mouse o Query_Activity ═══ 10.3.1. 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. ═══ 10.3.2. 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. ═══ 10.3.3. 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. ═══ 10.3.4. 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. ═══ 10.3.5. 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. ═══ 10.3.6. 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. ═══ 10.4. Device-Dependent Device Driver IDC Interface ═══ The IDC provided by the device-dependent device driver must support the following requests: o Query_Config o Read_Enable o Read_Disable o Disable_Device o Enable_Device ═══ 10.4.1. 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 Length field to 7 before issuing the request. The Num_Mics field 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. ═══ 10.4.2. 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. ═══ 10.4.3. 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. ═══ 10.4.4. 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. ═══ 10.4.5. 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. ═══ 10.5. 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: o Add the external declarations for the new global variables o Alter the execution path to enable the driver to run seamlessly o Include additional code to support the mouse running under OS/2 o Change the state_xlate table o Load ES with a driver code segment value o Call the virtual device driver interface o 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. ═══ 10.6. 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. ═══ 11. Mouse (DOS) Device Driver Test Tool ═══ This chapter explains how to use the mouse (DOS) Device Driver Test Tool. ═══ 11.1. 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. ═══ 11.1.1. 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: o DOSMOUSE.EXE o 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: o GLOBAL.GRA ═══ 11.1.2. 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/2 CD-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 ═══ 11.1.3. 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. ═══ 11.1.4. DDTT Mouse Test Grammar Function Calls ═══ The following is a list of the DDTT Parallel Port Test Grammar Function Calls: o MOUSE_RESETANDSTATUS o MOUSE_SHOWCURSOR o MOUSE_HIDECURSOR o MOUSE_GETBUTTONMPOS o MOUSE_SETCURPOS o MOUSE_GETBPRESS o MOUSE_GETBRELEASE o MOUSE_SETMINMAXHCPOS o MOUSE_SETMINMAXVCPOS o MOUSE_READMCOUNT o MOUSE_GETDRVVERTYPIRQ o MOUSE_GETGENINFO o MOUSE_GETMAXVCOOR o MOUSE_GETCURMSKMCNT o MOUSE_GETCURHSPT o MOUSE_HDWRESET o MOUSE_SETGETBPT o MOUSE_GETMINMAX o MOUSE_GETADVFCN o MOUSE_GETSWSET ═══ 11.1.4.1. MOUSE_RESETANDSTATUS ═══ Mouse Function 0 This function returns the current status of the mouse hardware and software. ═══ 11.1.4.1.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.1.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.1.3. Logged Data ═══ M1% Mouse status (found and reset = -1, otherwise = 0) M2% Number of buttons (if mouse found and reset = 2) ═══ 11.1.4.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. ═══ 11.1.4.2.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.2.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.2.3. Logged Data ═══ None. ═══ 11.1.4.3. 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. ═══ 11.1.4.3.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.3.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.3.3. Logged Data ═══ None. ═══ 11.1.4.4. 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. ═══ 11.1.4.4.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.4.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.4.3. Logged Data ═══ Button status Horizontal cursor coordinates Vertical cursor coordinates ═══ 11.1.4.5. MOUSE_SETCURPOS ═══ Mouse Function 4 This function sets the cursor position at the location of the specified horizontal vertical virtual coordinates. ═══ 11.1.4.5.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HORIZC │NUM │Horizontal cursor │ │ │ │coordinate │ ├────────────────────┼────────────────────┼────────────────────┤ │VERTC │NUM │Vertical cursor │ │ │ │coordinates │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 11.1.4.5.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.5.3. Logged Data ═══ None. ═══ 11.1.4.6. 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. ═══ 11.1.4.6.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │BUTTON │NUM │Left hand button=0 │ │ │ │or right hand button│ │ │ │=1 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 11.1.4.6.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.6.3. Logged Data ═══ Button status Number of button presses Horizontal coordinate Vertical coordinate ═══ 11.1.4.7. 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. ═══ 11.1.4.7.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │BUTTON │NUM │Left hand button=0 │ │ │ │or right hand button│ │ │ │=1 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 11.1.4.7.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.7.3. Logged Data ═══ Button status Button releases Horizontal coordinate Vertical coordinate ═══ 11.1.4.8. MOUSE_SETMINMAXHCPOS ═══ Mouse Function 7 This function sets the position of the minimum and maximum horizontal cursor coordinates on the screen. ═══ 11.1.4.8.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │HMIN │NUM │Horizontal minimum │ │ │ │position │ ├────────────────────┼────────────────────┼────────────────────┤ │HMAX │NUM │Horizontal maximum │ │ │ │position │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 11.1.4.8.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.8.3. Logged Data ═══ None. ═══ 11.1.4.9. MOUSE_SETMINMAXVCPOS ═══ Mouse Function 8 This function sets the position of the minimum and maximum vertical cursor coordinates on the screen. ═══ 11.1.4.9.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │VMIN │NUM │Vertical minimum │ │ │ │position │ ├────────────────────┼────────────────────┼────────────────────┤ │VMAX │NUM │Vertical maximum │ │ │ │position │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 11.1.4.9.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.9.3. Logged Data ═══ None. ═══ 11.1.4.10. MOUSE_READMCOUNT ═══ Mouse Function 11 This function returns the horizontal and vertical mickey counts since the last call of this function. ═══ 11.1.4.10.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.10.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.10.3. Logged Data ═══ Horizontal mickey count Vertical mickey count ═══ 11.1.4.11. 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). ═══ 11.1.4.11.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.11.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.11.3. Logged Data ═══ Major version Minor version Mouse type IRQ number ═══ 11.1.4.12. MOUSE_GETGENINFO ═══ Mouse Function 37 This function returns general information about the mouse. ═══ 11.1.4.12.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.12.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.12.3. Logged Data ═══ General information fCursorLock fInMouseCode fMouseBusy ═══ 11.1.4.13. MOUSE_GETMAXVCOOR ═══ Mouse Function 38 This function returns a flag indicating whether the mouse driver is disabled and indicates maximum virtual coordinates. ═══ 11.1.4.13.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.13.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.13.3. Logged Data ═══ Mouse-disabled flag Maximum virtual x Maximum virtual y ═══ 11.1.4.14. MOUSE_GETCURMSKMCNT ═══ Mouse Function 39 This function returns cursor information and accumulated raw mickey counts. ═══ 11.1.4.14.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.14.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.14.3. Logged Data ═══ Screen-mask or Scan-line start Cursor-mask or Scan-line stop Horizontal mickey count Vertical mickey count ═══ 11.1.4.15. 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. ═══ 11.1.4.15.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.15.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.15.3. Logged Data ═══ fCursor Horizontal cursor hot spot Vertical cursor hot spot Type of mouse ═══ 11.1.4.16. MOUSE_HDWRESET ═══ Mouse Function 47 This function returns cursor information and accumulated raw mickey counts ═══ 11.1.4.16.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.16.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.16.3. Logged Data ═══ Success flag ═══ 11.1.4.17. MOUSE_SETGETBPT ═══ Mouse Function 48 This function sets or returns cursor ballpoint-orientation and buttonmask information. ═══ 11.1.4.17.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │ROTANGLE │NUM │Rotation angle │ ├────────────────────┼────────────────────┼────────────────────┤ │CMDINFO │NUM │Command │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 11.1.4.17.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.17.3. Logged Data ═══ Status Rotation angle Button mask ═══ 11.1.4.18. MOUSE_GETMINMAX ═══ Mouse Function 49 This function returns the minimum and maximum horizontal and vertical coordinates for the current video mode. ═══ 11.1.4.18.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.18.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.18.3. Logged Data ═══ Status Virtual x minimum Virtual y minimum Virtual x maximum Virtual y maximum ═══ 11.1.4.19. MOUSE_GETADVFCN ═══ Mouse Function 50 This function returns the flags that indicate active advanced functions. ═══ 11.1.4.19.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.19.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.19.3. Logged Data ═══ Active function flags ═══ 11.1.4.20. MOUSE_GETSWSET ═══ Mouse Function 51 This function returns the current settings of switch values that can be passed to the mouse driver. ═══ 11.1.4.20.1. Input Parameter Keywords ═══ None. ═══ 11.1.4.20.2. Output Parameter Keywords ═══ None. ═══ 11.1.4.20.3. 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 ═══ 11.2. 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. ═══ 11.3. 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. ═══ 12. 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. ═══ 12.1. 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: o Initializing a parallel port device o Sending characters to a parallel port device o Returning the status of a parallel port device o 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: o Determines that the request is for the parallel port device driver (based on the specified device handle) o Creates a request packet o 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 Reference for more information. The INT 21h request is converted into a request packet and issued to the device driver strategy routine. ═══ 12.2. 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. ═══ 12.3. 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. ═══ 12.4. 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. ═══ 12.5. 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. ═══ 12.5.1. 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: o 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. o 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: o Receive all data and code page requests from the first monitor chain (see DosMonRead) o Return data requests to the first monitor chain (see DosMonWrite) o 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: o 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. o 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. o 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. ═══ 12.5.2. 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. ═══ 12.6. 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: o The first WORD consists of the length of the buffer (4). o 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. ═══ 12.7. 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: o 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. o 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. ═══ 12.8. Parallel Port Device Driver Interfaces ═══ The parallel port device driver has several interfaces: o Request Packet interface (referred to as the Strategy interface) o INT 21h interface o Generic IOCtl interface o Hardware Interrupt interface o Monitor Dispatcher Notification interface ═══ 12.8.1. 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. ═══ 12.8.1.1. 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. ═══ 12.8.1.2. 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. ═══ 12.8.1.3. 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. ═══ 12.8.2. 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. ═══ 12.8.3. 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. ═══ 12.8.3.1. 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 ═══ 12.8.3.2. 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: o Index=1 Registers a monitor with the data chain. o Index=2 Registers a monitor with the code page chain. ═══ 12.8.4. 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. ═══ 12.8.5. 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: o 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. o 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 │128 BYTES │ │(optional) │ │ └──────────────────────────────┴──────────────────────────────┘ 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. ═══ 12.8.6. 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 ═══ 12.8.6.1. 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 │ └──────────────────────────────┴──────────────────────────────┘ ═══ 12.8.6.2. 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 │ └──────────────────────────────┴──────────────────────────────┘ ═══ 12.8.6.3. 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 │ └──────────────────────────────┴──────────────────────────────┘ ═══ 12.8.6.4. 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). ═══ 12.8.6.5. 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. ═══ 12.8.6.6. 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. ═══ 12.8.7. 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. ═══ 12.8.8. Request Exclusive Access ═══ Request Exclusive Access grants the calling device driver sole ownership of the parallel port until a Release Exclusive Access is issued. ═══ 12.8.8.1. 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 ────────────────────────────────────────────────────────────────────────── ═══ 12.8.8.2. 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 ────────────────────────────────────────────────────────────────────────── ═══ 12.8.9. 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. ═══ 12.8.9.1. 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 ────────────────────────────────────────────────────────────────────────── ═══ 12.8.9.2. 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 ────────────────────────────────────────────────────────────────────────── ═══ 13. Parallel Port Device Driver Test Tool ═══ This chapter explains how to use the parallel port Device Driver Test Tool. ═══ 13.1. 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. ═══ 13.1.1. Parallel Port Test Architecture ═══ The DDTT provides a common front-end parser for test-case scripts. The following DDTT parallel-specific files are required: o DDTPARA.DLL o PARALLEL.GRA. o GEN.GRA - needed for test script file, REQEX.SCR o 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: o DDTT.EXE o DDTT.DLL o GLOBAL.DLL o GLOBAL.GRA * ================================================================== ═══ 13.1.2. 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. ═══ 13.1.3. 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 ═══ 13.1.4. DDTT Parallel Port Test Grammar Function Calls ═══ The following is a list of the DDTT Parallel Port Test Grammar Function Calls: o PARA_OPEN o PARA_CLOSE o PARA_SETRAMECTRL o PARA_SETRETRY o PARA_INIT o PARA_ACTIVATEFONT o PARA_SETTITLE o PARA_SETWRTTIMEOUT o PARA_QFRAMECTRL o PARA_QRETRY o PARA_QPORT o PARA_QACTIVEFONT o PARA_VERIFYFONT o PARA_QWRTTIMEOUT o PARA_READFILE o PARA_WRITEFILE ═══ 13.1.4.1. PARA_OPEN ═══ This function opens the given parallel port. ═══ 13.1.4.1.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DEVICENAME │STRING │Output port │ │ │ │identification, such│ │ │ │as LPT1 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.1.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.1.3. Logged Data ═══ None. ═══ 13.1.4.2. PARA_CLOSE ═══ This function closes the opened parallel port. ═══ 13.1.4.2.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.2.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.2.3. Logged Data ═══ None. ═══ 13.1.4.3. PARA_SETFRAMECTRL ═══ Category 05h - Function 42h This function sets frame control (characters-per-line, lines-per-inch). ═══ 13.1.4.3.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.3.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.3.3. Logged Data ═══ Frame Control Message with characters-per-line and lines-per-inch. ═══ 13.1.4.4. PARA_SETRETRY ═══ Category 05h - Function 44h This function sets infinite retry on/off (0=OFF, 1=ON). ═══ 13.1.4.4.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ ├────────────────────┼────────────────────┼────────────────────┤ │RETRY │NUM │ON or OFF setting │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.4.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.4.3. Logged Data ═══ Retry state Message with Infinite Retry Disabled/Enabled ═══ 13.1.4.5. PARA_INIT ═══ Category 05h - Function 46h This function initializes parallel port. ═══ 13.1.4.5.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.5.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.5.3. Logged Data ═══ None. ═══ 13.1.4.6. PARA_ACTIVATEFONT ═══ Category 05h - Function 48h This function activates a font. ═══ 13.1.4.6.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.6.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.6.3. Logged Data ═══ Font information Message with CODEPAGE and FONTID ═══ 13.1.4.7. PARA_SETTITLE ═══ Category 05h - Function 4Dh This function sets job title. ═══ 13.1.4.7.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ ├────────────────────┼────────────────────┼────────────────────┤ │JOBTITLE │STRING │Job title │ │ │ │identification │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.7.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.7.3. Logged Data ═══ Job title information Length and address with job title information. ═══ 13.1.4.8. PARA_SETWRTTIMEOUT ═══ Category 05h - Function 4Eh This function sets write timeout. ═══ 13.1.4.8.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ ├────────────────────┼────────────────────┼────────────────────┤ │PPWRTTIMEOUT │NUM │Seconds for write │ │ │ │timeout │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.8.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.8.3. Logged Data ═══ Write time out value Parallel Port Write Time Out Value in seconds ═══ 13.1.4.9. PARA_QFRAMECTRL ═══ Category 05h - Function 62h This function queries frame control (characters-per-line, lines-per-inch). ═══ 13.1.4.9.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.9.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.9.3. Logged Data ═══ Frame Control Message with characters-per-line and lines-per-inch. ═══ 13.1.4.10. PARA_QRETRY ═══ Category 05h - Function 64h This function queries infinite retry. ═══ 13.1.4.10.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.10.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.10.3. Logged Data ═══ Retry state Message with Infinite Retry Disabled/Enabled ═══ 13.1.4.11. PARA_QPORT ═══ Category 05h - Function 66h This function queries port. ═══ 13.1.4.11.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.11.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.11.3. Logged Data ═══ Data Value in data field ═══ 13.1.4.12. PARA_QACTIVEFONT ═══ Category 05h - Function 69h This function queries active font. ═══ 13.1.4.12.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.12.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.12.3. Logged Data ═══ Font information Message with CODEPAGE and FONTID ═══ 13.1.4.13. PARA_VERIFYFONT ═══ Category 05h - Function 6Ah This function verifies font. ═══ 13.1.4.13.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.13.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.13.3. Logged Data ═══ Font information Message with CODEPAGE and FONTID ═══ 13.1.4.14. PARA_QWRTTIMEOUT ═══ Category 05h - Function 6Eh This function queries write time out. ═══ 13.1.4.14.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.14.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.14.3. Logged Data ═══ Time out information Message with PP Write Time Out Value in seconds. ═══ 13.1.4.15. PARA_READFILE ═══ This function reads a file. ═══ 13.1.4.15.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.15.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.15.3. Logged Data ═══ None. ═══ 13.1.4.16. PARA_WRITEFILE ═══ This function writes a file. ═══ 13.1.4.16.1. Required Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Handle number of │ │ │ │output parallel port│ ├────────────────────┼────────────────────┼────────────────────┤ │FILENAME │STRING │Name of file to │ │ │ │write │ ├────────────────────┼────────────────────┼────────────────────┤ │$BUFFER │STRING │Buffer of write data│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 13.1.4.16.2. Output Parameter Keywords ═══ None. ═══ 13.1.4.16.3. Logged Data ═══ None. ═══ 13.2. 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: o 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: o 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. ═══ 13.3. 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". ═══ 14. 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. ═══ 14.1. 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. ═══ 14.1.1. PCMCIA Hardware ═══ There are three major hardware components defined in the PCMCIA standard: o Cards o Sockets o 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: o Connectivity devices, such as modems, local area networks (LANs), and terminal emulators o Secondary storage devices, such as mini rotating hard disks, solid state file disks, and flash o Random access memory, such as SRAM, DRAM, or NVRAM memory o 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. ═══ 14.1.2. PCMCIA Software ═══ There are three major software components defined in the PCMCIA architecture: o Clients o Card Services o 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. ═══ 14.1.3. 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: PCMCIAOffice 1030G East Duane Avenue Sunnyvale, CA 94086 (408) 720-0107 Voice (408) 720-9416 FAX (408) 720-9388 BBS ═══ 14.2. 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: o 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. o OS/2 PCMCIA clients are responsible for providing device-specific support in the desired application environments. o 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. ═══ 14.2.1. 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: o Non-system memory in the range C0000h - DFFFFh o IRQs in the range 2 through 15 o 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. 3. 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. 4. 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). 4. 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. 5. 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. ═══ 14.2.2. 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. ═══ 14.2.2.1. 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 CardState and SocketState field 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 CardState and SocketState field 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. ═══ 14.3. Card Services ═══ The following includes implementation limitations and restrictions and client interfaces. ═══ 14.3.1. 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: o A maximum of four adapters o A maximum of eight sockets o A maximum of 16 clients o A maximum of four Socket Services drivers o A maximum of 16 memory technology drivers o A maximum of 16 memory handles o A maximum of 16 erase queues o A maximum of 16 regions o A maximum of 16 partitions o 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: o Paged memory windows o ROM BIOS Socket Services o 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. o 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: o 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. o Multi-partitioned cards must have a drive letter assigned to each partition for the partition to be accessible. o All secondary storage cards are treated as removable media. This prohibits enhanced performance from file systems using cached support. ═══ 14.3.2. 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: o Functions o Callbacks o Events o Memory Technology Driver Helpers o Media Access Routines o 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. ═══ 14.3.2.1. 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: o Operate in a Far Call/return model. o Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface. o Ensure that an appropriate stack is used for the calling model (16-bit protect mode) with at least 512 bytes of available stack space. o 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. ═══ 14.3.2.2. 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: o Client Information o Ejection/Insertion Requests o Erase Completion o Exclusive o Insertion o MTD Request o Registration Completion o Reset o Socket Services Updates o 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 ─────────────────────────────────────────────────────────────────── ═══ 14.3.2.3. 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. ═══ 14.3.2.4. 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. ═══ 14.3.2.5. 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. ═══ 14.3.2.6. 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). ═══ 14.3.3. 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: o 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.) o AddSocketServices (32h) The Attributes field defines details for the new Socket Services entry point. Card Services accepts only bit 1 (16:16 protect mode) requests. The DataPointer field 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. o 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 IOAddrLines field is 0 or greater than 16. o 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. o 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. ─────────────────────────────────────────────────────────────────── o 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 Version field. It is recommended that the value be set to 0200h for future compatibility. Card Services currently disregards the Version field. 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. o 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. o 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. o 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. o RequestWindow (21h) Card Services supports the following Attributes field 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. o 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. ═══ 14.3.4. 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: o /W Wait line monitoring control. Refer to the Command Reference for a description of all the parameters defined for the Card Services device drivers. ═══ 14.4. 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. ═══ 14.4.1. 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: o Operate in a Far Call/return model. o Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface. o 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: o 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 before it 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 after it has received a resource configuration from Card Services. - All other values are reserved for future use. o 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. o 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. o 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. o 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. ═══ 14.5. 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. ═══ 14.5.1. 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: o Operate in a Far Call/return model. o Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface. o Ensure that an appropriate stack is used for the calling model (16-bit protect mode) with at least 512 bytes of available stack space. o 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. ═══ 14.5.2. 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). ═══ 14.5.3. 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: o GetAdapterCount (80h) OS/2 Socket Services returns the number of adapters supported by this driver for the TotalAdapters value. o GetSSInfo (0Bh) OS/2 Socket Services returns 0100 for the Compliance value. OS/2 Socket Services always returns zero for the FirstAdapter value. o 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. ═══ 14.5.4. 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. ═══ 14.6. 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. ═══ 14.6.1. 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: o /H The /H parameter causes the driver to print out the help information and then terminate. o /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. o /E The /E parameter enables initialization message output. If this parameter is not specified, messages will not be displayed. ═══ 14.6.2. Component Internal Structure ═══ The component internal structure is described below. ═══ 14.6.2.1. IDC Interface ═══ The IDC packet structure shared between the Socket Services driver and the Card Services driver is defined in Socket Services. ═══ 14.6.3. 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. 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│243 │ │ │dependent routines │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSPCICIN.ASM │Socket Services device driver │386 │ │ │initialization routines │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSPCIC.ASM │PCMCIA Socket Services Functions │623 │ │ │routines, except for window │ │ │ │management routines │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSPCICDP.ASM │Device driver internal function │212 │ │ │dispatcher │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSPCICVA.ASM │Request parameter validation │115 │ │ │routines │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSPCICWM.ASM │Window Management routines │569 │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSPCICUT.ASM │Utility routines used by the │218 │ │ │primary function routines of the │ │ │ │driver │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSMSG.ASM │The device driver's initialization│42 │ │ │messages │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSOS2.INC │OS/2 operating system related │39 │ │ │definitions │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSMSG.INC │Message file related definitions │22 │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSPCIC.INC │Intel 82365SL PCIC related │241 │ │ │definitions │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSDEFS.INC │PCMCIA Socket Services related │295 │ │ │definitions │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SS_SEGM.INC │Physical Device Driver data and │28 │ │ │code segment definitions │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSMAC.INC │Internally used macro definitions │18 │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SSPCIC.DEF │Linker definitions file │N/A │ ├─────────────┼──────────────────────────────────┼─────────────┤ │TOTAL │ │ 3051 │ └─────────────┴──────────────────────────────────┴─────────────┘ ═══ 14.6.4. 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: o co - (common) Indicates code that should be common to any implementation of this driver o 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. o 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 │ └───────────────┴──────────────────────────────┘ ═══ 14.7. 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. ═══ 14.7.1. 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. ═══ 14.7.2. Component Internal Structure ═══ The component internal structure is described below. ═══ 14.7.2.1. IDC Interface ═══ The IDC packet structure shared between the OS/2 COM.SYS driver and a modem client driver is defined in COM Support. ═══ 14.7.3. 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. The figure of Component Logic Flow - Enable Modem below details the high-level logic flow of the device driver design. The figure of Component Logic Flow - Callback Routine details the high-level logic flow of the device driver design. 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 │2 │ │ │prototype. │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CS_IDC.ASM │Contains the assembler code that │131 │ │ │attaches and interfaces to card │ │ │ │services │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CS_HELP.ASM │The callback handler function that│75 │ │ │card services will invoke when a │ │ │ │registered event occurs │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CS_HELP.H │Callback handler C function │1 │ │ │prototype │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │COMPORT.C │Contains the functions that │149 │ │ │acquire and release the COM port │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │COMPORT.H │Function prototypes for acquiring │3 │ │ │and releasing the COM port │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CS_UTIL.C │Contains the card services calls │734 │ │ │to allocate and deallocate │ │ │ │resources for the modem │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CS_UTIL.H │Contains the release and acquire │3 │ │ │resources function prototypes │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CS.C │Contains the routines to register │312 │ │ │with card services and to handle │ │ │ │the card present event │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CS.H │Declarations for the routines that│26 │ │ │interface with card services │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CARD_ID.C │Verifies the identity of the modem│29 │ │ │card │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CARD_ID.H │Declaration for the card_id │1 │ │ │function │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SHELL.ASM │Contains assembler shell that │77 │ │ │creates a device driver model to │ │ │ │which the C code can interface │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │DEVHLP.ASM │Contains routines help access │58 │ │ │DevHelp routines from the │ │ │ │operating system │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CS_HELP.ASM │The Callback handler that card │75 │ │ │services will invoke when a │ │ │ │registered event occurs │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CONFIG.C │Contains routines that process and│100 │ │ │store configuration info for the │ │ │ │system │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │CONFIG.H │Constant definitions and │15 │ │ │prototypes used by CONFIG.C │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │DEVHELP.H │Definitions and public functions │10 │ │ │for Device Driver help routines │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │STGY.C │Contains the strategy portion of │258 │ │ │the device driver │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │COM_IDC.ASM │Contains the code interfaces with │124 │ │ │OS/2 COM.SYS by way of the new IDC│ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │COM_IDC.H │Contains the declarations and │2 │ │ │prototypes for COM_IDC │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │SHELL.H │Device Driver prototypes │3 │ ├─────────────┼──────────────────────────────────┼─────────────┤ │TYPES.H │Contains constant definition and │7 │ │ │type definition for the system │ │ ├─────────────┼──────────────────────────────────┼─────────────┤ │TOTAL │ │ 2195 │ └─────────────┴──────────────────────────────────┴─────────────┘ ═══ 14.7.3.1. 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. The figure of OS/2 Client Driver Functional Logic Flow is a high level flow of the main functional portion of the client driver. ═══ 14.7.4. 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 │ └───────────────┴──────────────────────────────┘ ═══ 14.7.4.1. 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 ─────────────────────────────────────────────────────────────────── ═══ 14.7.5. Dependencies and Restrictions ═══ This device must be loaded in the CONFIG.SYS file after COM.SYS. ═══ 15. PCMCIA Socket Services Device Driver Test Tool ═══ This chapter explains explains how to use the Socket Services Device Driver Test Tool. ═══ 15.1. 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. ═══ 15.1.1. 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: o DDTPCMC.DLL o PCMC.GRA. o 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: o DDTT.EXE o DDTT.DLL o GLOBAL.DLL o GLOBAL.GRA ═══ 15.1.2. Installation ═══ There are two directory structures in the IBM Developer Connection Device Driver Kit for OS/2 that 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/2 CD-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/2 CD-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. ═══ 15.1.3. 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. ═══ 15.1.4. DDTT PCMCIA Socket Services Test Grammar Function Calls ═══ The following are the names of the PCMCIA Socket Services Test Grammar Function Calls: o PCMC_OPEN o PCMC_CLOSE o PCMC_GETADAPTERCOUNT o PCMC_ACKINTERRUPT o PCMC_PRIORHANDLER o PCMC_SSADDR o PCMC_ACCESSOFFSETS o PCMC_GETADAPTER o PCMC_GETSSINFO o PCMC_GETVENDORINFO o PCMC_INQADAPTER o PCMC_SETADAPTER o PCMC_VENDORSPECIFIC o PCMC_GETSOCKET o PCMC_GETSTATUS o PCMC_INQSOCKET o PCMC_RESETSOCKET o PCMC_SETSOCKET o PCMC_GETPAGE o PCMC_GETWINDOW o PCMC_INQWINDOW o PCMC_SETPAGE o PCMC_SETWINDOW o PCMC_GETEDC ═══ 15.1.4.1. PCMC_OPEN ═══ This function opens the PCMCIA$ test device driver. ═══ 15.1.4.1.1. Input Parameter Keywords ═══ None. ═══ 15.1.4.1.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.1.3. Logged Data ═══ None. ═══ 15.1.4.2. PCMC_CLOSE ═══ This function closes the PCMCIA$ test device driver. ═══ 15.1.4.2.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.2.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.2.3. Logged Data ═══ None. ═══ 15.1.4.3. PCMC_GETADAPTERCOUNT ═══ This function gets the number of adapters supported by Socket Services and the signature "SS". ═══ 15.1.4.3.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.3.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.3.3. Logged Data ═══ Total number of adapters Signature "SS" ═══ 15.1.4.4. PCMC_ACKINTERRUPT ═══ This function gets the oldest status change interrupt information from the PCMCIA$ test device driver. ═══ 15.1.4.4.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ ├────────────────────┼────────────────────┼────────────────────┤ │SOCKET │NUM │Socket number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.4.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.4.3. Logged Data ═══ Number of interrupts ═══ 15.1.4.5. PCMC_PRIORHANDLER ═══ This function gets or sets the prior Socket Services handler for the specified adapter. ═══ 15.1.4.5.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.5.2. Output Parameter Keywords ═══ ═══ 15.1.4.5.3. Logged Data ═══ Mode ( 0 = Get, 1 = Set ) ═══ 15.1.4.6. PCMC_SSADDR ═══ This function gets or sets mode and data area descriptors. ═══ 15.1.4.6.1. 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) │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.6.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.6.3. Logged Data ═══ Requested function Number of additional data segments to get or set ═══ 15.1.4.7. PCMC_ACCESSOFFSETS ═══ This function gets an array of offsets for low-level, adapter-specific optimized PC card-access routines. ═══ 15.1.4.7.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.7.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.7.3. Logged Data ═══ Number of offsets supported ═══ 15.1.4.8. PCMC_GETADAPTER ═══ This function gets the current configuration of the specified adapter. ═══ 15.1.4.8.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.8.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.8.3. Logged Data ═══ Adapter Attributes IRQ level for status change interrupts ═══ 15.1.4.9. PCMC_GETSSINFO ═══ This function gets the compliance level of the Socket Services interface supporting the specified adapter and identifies the adapters supported. ═══ 15.1.4.9.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.9.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.9.3. Logged Data ═══ Compliance Number of adapters First adapter ═══ 15.1.4.10. PCMC_GETVENDORINFO ═══ This function gets information about the vendor that implemented the Socket Services for the specified adapter. ═══ 15.1.4.10.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.10.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.10.3. Logged Data ═══ Release Number ASCII string describing the implementer ═══ 15.1.4.11. PCMC_INQADAPTER ═══ This function gets the capability information for the specified adapter. ═══ 15.1.4.11.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.11.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.11.3. 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. ═══ 15.1.4.12. PCMC_SETADAPTER ═══ This function sets the configuration of the specified adapter. ═══ 15.1.4.12.1. 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) │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.12.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.12.3. Logged Data ═══ None. ═══ 15.1.4.13. PCMC_VENDORSPECIFIC ═══ This function defines a vendor-specific function for implementing proprietary functions. ═══ 15.1.4.13.1. 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│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.13.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.13.3. Logged Data ═══ None. ═══ 15.1.4.14. PCMC_GETSOCKET ═══ This function gets the current configuration of the specified socket. ═══ 15.1.4.14.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ ├────────────────────┼────────────────────┼────────────────────┤ │SOCKET │NUM │Socket Number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.14.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.14.3. Logged Data ═══ Interrupt Mask Vcc Level Vpp Level Socket State variables Socket Control Variables IRQ level and status change interrupts ═══ 15.1.4.15. PCMC_GETSTATUS ═══ This function gets the status of the card in the specified socket on the specified adapter. ═══ 15.1.4.15.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ ├────────────────────┼────────────────────┼────────────────────┤ │SOCKET │NUM │Socket Number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.15.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.15.3. Logged Data ═══ Card Attributes Socket State Control and Indicator State IRQ level and status change interrupts ═══ 15.1.4.16. PCMC_INQSOCKET ═══ This function gets the capability information for the specified socket. ═══ 15.1.4.16.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ ├────────────────────┼────────────────────┼────────────────────┤ │SOCKET │NUM │Socket Number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.16.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.16.3. Logged Data ═══ Interrupt Capabilities Reporting Capabilities Control Capabilities Socket Characteristics ═══ 15.1.4.17. PCMC_RESETSOCKET ═══ This function resets the PC card in the specified socket. ═══ 15.1.4.17.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ ├────────────────────┼────────────────────┼────────────────────┤ │SOCKET │NUM │Socket Number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.17.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.17.3. Logged Data ═══ None. ═══ 15.1.4.18. PCMC_SETSOCKET ═══ This function sets the configuration for the specified socket. ═══ 15.1.4.18.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.18.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.18.3. Logged Data ═══ None. ═══ 15.1.4.19. PCMC_GETPAGE ═══ This function gets the current configuration of the specified page in the specified window. ═══ 15.1.4.19.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.19.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.19.3. Logged Data ═══ Page Attributes Offset ═══ 15.1.4.20. PCMC_GETWINDOW ═══ This function gets the current configuration of the specified window on the specified adapter. ═══ 15.1.4.20.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ ├────────────────────┼────────────────────┼────────────────────┤ │WINDOW │NUM │Window Number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.20.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.20.3. Logged Data ═══ Socket Window Size Window Attributes Access speed Window Base Address ═══ 15.1.4.21. PCMC_INQWINDOW ═══ This function gets the capability information for the specified window on the specified window. ═══ 15.1.4.21.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ ├────────────────────┼────────────────────┼────────────────────┤ │WINDOW │NUM │Window Number │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.21.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.21.3. Logged Data ═══ Capabilities Assignable Sockets ═══ 15.1.4.22. PCMC_SETPAGE ═══ This function sets the configuration for the specified page in the specified window. ═══ 15.1.4.22.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.22.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.22.3. Logged Data ═══ None. ═══ 15.1.4.23. PCMC_SETWINDOW ═══ This function sets the configuration for the specified window. ═══ 15.1.4.23.1. 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 │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.23.2. Output Parameter Keywords ═══ None. ═══ 15.1.4.23.3. Logged Data ═══ None. ═══ 15.1.4.24. PCMC_GETEDC ═══ This function gets the current configuration of the specified EDC generator. ═══ 15.1.4.24.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │PCMCIA device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │ADAPTER │NUM │Adapter number │ ├────────────────────┼────────────────────┼────────────────────┤ │EDC │NUM │EDC generator number│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 15.1.4.24.2. Output Parameter Keywords ═══ Socket State Type ═══ 15.2. 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. ═══ 16. Touch Display Device Driver ═══ This chapter introduces and describes the OS/2 device driver for the IBM Touch Display pointing device. ═══ 16.1. 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: o Touch device driver o Touch device-independent subsystem o Touch device-dependent subsystem o Combined IBM PS/2 Mouse/Touch device-dependent device driver o Touch virtual device driver (VDD) o 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: o 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. o Device-dependent features (only) are accessed by the PM Touch control panel or device driver load-time parameters, using the common TOUCH.INI file. o PM mouse-emulation support for windowed DOS sessions. o 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. ═══ 16.2. 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 Tdixxx API, 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 Touxxx API 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). ═══ 16.2.1. 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. ═══ 16.2.2. Accessing a Presentation Manager Touch Display Device ═══ Within Presentation Manager, it is not possible to access the Touch device from the following locations: o Presentation Manager program o AVIO window o 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. ═══ 16.3. 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: o The conventional entry point, where real mouse events are reported o 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, Mouxxx API, 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: o 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. o 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. ═══ 16.4. 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 │Valid file name│None │ │ │download into Touch │ │ │ │ │Display │ │ │ ├──────────┼────────────────────┼───────────────┼──────────┤ │INIT= │Parameter file to │Valid file name│None │ │ │override settings in│ │ │ │ │device driver │ │ │ └──────────┴────────────────────┴───────────────┴──────────┘ 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 │1 - 100 │10 │ │ │event queue size in │elements │ │ │ │elements │ │ │ ├──────────┼────────────────────┼───────────────┼──────────┤ │TYPE= │Indicates device │PDITOU$ for │None │ │ │dependent name. │Touch; PDIMOU$ │ │ │ │ │for Mouse │ │ └──────────┴────────────────────┴───────────────┴──────────┘ 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 │Selection type │0 │ │ │in protect mode and │0 - 5 │ │ │ │real mode │# of stable │ │ │ │ │points │ │ │ │ │0 - 40 │ │ │ │ │Tolerance value│ │ │ │ │0 - 4095 │ │ │ │ │Search Limit │ │ │ │ │0 - 40 │ │ └──────────┴────────────────────┴───────────────┴──────────┘ 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). ═══ 16.4.1. Format of TOUCH.INI Parameter File ═══ A TOUCH.INI parameter file is supplied containing the default device-driver settings for: o Force thresholds o Mouse emulation ON|OFF control o Mouse emulation beep feedback (on button down) ON|OFF control o Mouse emulation click-lock parameters o Mouse emulation XY finger-pointer offset o Data packet report rate o 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 */ ────────────────────────────────────────────────────────────────────────── ═══ 16.4.2. 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. ═══ 16.5. 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: o SRC\DEV\TOUCHDD\MAKEFILE o SRC\VDEV\VTOUCH\MAKEFILE ────────────────────────────────────────────────────────────────────────── Example: cd\ddk_x86\src\dev\TOUCHDD\nmake ────────────────────────────────────────────────────────────────────────── ═══ 17. 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. ═══ 17.1. Device-Independent to Device-Dependent IDC Interfaces ═══ The IDC interfaces provided by the device-independent-device driver are: o Process Packet o Disable Support ═══ 17.1.1. 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 ────────────────────────────────────────────────────────────────────────── ═══ 17.1.2. 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 ────────────────────────────────────────────────────────────────────────── ═══ 17.2. 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: o Query Configuration o Enable Read o Disable Write o Enable Device o Disable Device o Set Mouse Emulation State ═══ 17.2.1. 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 ────────────────────────────────────────────────────────────────────────── ═══ 17.2.2. 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 ────────────────────────────────────────────────────────────────────────── ═══ 17.2.3. 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 ────────────────────────────────────────────────────────────────────────── ═══ 17.2.4. 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 ────────────────────────────────────────────────────────────────────────── *================================================================== ═══ 17.2.5. 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 ────────────────────────────────────────────────────────────────────────── ═══ 17.2.6. 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,dy form, 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 ────────────────────────────────────────────────────────────────────────── ═══ 17.3. 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: ═══ 17.3.1. 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; ────────────────────────────────────────────────────────────────────────── ═══ 17.4. 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 ═══ 17.4.1. 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); ────────────────────────────────────────────────────────────────────────── ═══ 17.4.2. 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); ────────────────────────────────────────────────────────────────────────── ═══ 17.4.3. 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); ────────────────────────────────────────────────────────────────────────── ═══ 17.4.4. 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); ────────────────────────────────────────────────────────────────────────── ═══ 17.4.5. 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); ────────────────────────────────────────────────────────────────────────── ═══ 17.5. Virtual Touch Device Driver Architecture ═══ The following information describes the Virtual Touch Device Driver Architecture. ═══ 17.5.1. 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. REAL PROTECTED ARPL OS/2 Interrupt ┌──────────┐ Hook Proc 1 Vector Table │ │ │ ┌─────────────┐ ┌─────────────┐ │ ┌────────────┐ ┌────── │ │ │ │ │ │ ──────── ├──┘ ──┐ │ │ │ │ │ │ ──────── ├─────┐ │ │ │ │ │ │ │ │  ───┐ │ │ │ │ │ │ │ │  │ │ │ │ │ │ │ │ │ │ │  │ │ │ │ │ │ ├─────────────┤ │ │ ──────── │ │ │ │ │ │ INT 7F ┌──┤ Address B │ │ │ └─────────────┘ │ │ │ │ │ │ ├─────────────┤ │ List of │ │ └─┤ │ │ │ │ │ │ Installed │ │ └─────────────┘ Router │ └─────────────┘ │ IntHooks │ │ Hook Proc 2 │ │ │ │ │ ┌─────────────┐ │ ┌─────────────┐ │ │ └─── │ │ │ │ │ │ │ │ │ │ ├─────────────┤ │ │ │ │ │ │ Address A ├─────┤ │ │ │ │ │ ├─────────────┤ │ │ │ │ INT 7F │ │ ──┐ │ │ │ │ │ Handler │ ├─────────────┤ │ │ │ │ │ └── │ │ │ │ └─────┤ │ INT 7F │ ├──┼──┘ └─────────────┘ Jump ├─────────────┤ │ │ Table │ ──────── ├──┘ │ ──────── │ │ │ ──────── │ │  │ │ │  │ │  │ │ │ ──────── │ └─────────────┘ │ 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. REAL PROTECTED ARPL OS/2 Interrupt ┌──────────┐ Hook Proc 1 Vector Table │ │ │ ┌─────────────┐ ┌─────────────┐ │ ┌────────────┐ ┌────── │ │ │ │ │ │ ──────── ├──┘ ──┐ │ │ │ │ │ │ ──────── ├─────┐ │ │ │ │ │ │ │ │  ───┐ │ │ │ │ │ │ │ │  │ │ │ │ │ │ │ │ │ │ │  │ │ │ │ │ │ ├─────────────┤ │ │ ──────── │ │ │ │ │ │ INT 7F │ Address B ├─────┘ │ └─────────────┘ │ │ │ │ │ ├─────────────┤ List of │ │ └─┤ │ │ │ │ Installed │ │ └─────────────┘ └─────────────┘ IntHooks │ │ Hook Proc 2 │ │ │ ┌─────────────┐ │ └─── │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────┤ │ └─────────────┘ ═══ 17.6. 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). ═══ 17.6.1. 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 shared interrupt in the VDDs that simulate and service this interrupt. ═══ 17.7. 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: o Single-touch o 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. o 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. ═══ 17.7.1. 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: o 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. o 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. o 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. ═══ 17.8. 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 settled and 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. ═══ 17.8.1. 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. ────────────────────────────────────────────────────────────────────────── ═══ 17.9. 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 back into a circular buffer (a form of stack containing the N most 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 immune to 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 slide away 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). ═══ 17.9.1. 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 ────────────────────────────────────────────────────────────────────────── ═══ 17.9.2. 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: o Clicking on an icon to bring up the system menu o 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 ═══ 17.9.2.1. 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. ═══ 17.9.2.2. 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: o After the click-lock time has been exceeded o If the touch coordinate moves outside the click-lock area o If the touch is removed from the screen ═══ 17.9.2.3. Double Click Locking ═══ This option is the same as single click locking, except that the conditions for reporting X,Y data are: o After the click-lock time has been exceeded o If the touch coordinate moves outside the click-lock area o 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. ═══ 17.9.2.4. 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. ═══ 17.9.2.5. 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. ═══ 17.9.3. 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 ────────────────────────────────────────────────────────────────────────── ═══ 18. Glossary ═══ This glossary contains terms and definitions that are, for the most part, used for OS/2 products. This is not a complete dictionary of computer terms. ═══ 18.1. Introduction ═══ This glossary defines many of the terms used in this book. It includes terms and definitions from the IBM Dictionary of Computing, as well as terms specific to the Presentation Manager, but it is not a complete glossary for OS/2. Other primary sources for these definitions are: o The American National Standard Dictionary for Information Systems, ANSI X3.172-1990, copyrighted 1990 by the American National Standards Institute, 11 West 42nd Street, New York, New York 10036. These definitions are identified by the symbol (A) after the definition. o The Information Technology Vocabulary, developed by Subcommittee 1, Joint Technical Committee 1, of the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are identified by the symbol (I) after the definition; definitions taken from draft international standards, committee drafts, and working papers being developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the definition, indicating that final agreement has not yet been reached among the participating National Bodies of SC1. ═══ 18.2. Glossary Listing ═══ Select a starting letter of glossary terms: A N B O C P D Q E R F S G T H U I V J W K X L Y M Z ═══ Glossary - A ═══ A ABIOS - Advanced BIOS. See BIOS. accumulator - (1) A register in which one operand of an operation can be stored and subsequently replaced by the result of that operation. (T) (2) In the IBM 3800 Printing Subsystem Models 3 and 8, a feature that supplies a separate storage that can hold data in raster form. It can be used either for composing a sheet of data that combines a large amount of variable and constant data, or for storing an electronic overlay in raster form that will be merged with variable data as the sheet is printed. access permission - All access rights a user has regarding an object. (I) adapter - A piece of hardware that modifies the system unit to allow it to operate in a particular way, often by connecting the system unit to an external device such as a video monitor. adapter device driver - A device driver that provides hardware-dependent services for an OEM adapter. address space - (1) The range of addresses available to a program. (A) (2) The area of virtual storage available for a particular job. all points addressable (APA) - In computer graphics, pertaining to the ability to address and display or not display each picture element (pel) on a display surface. anchor block - An area of the internal resources of OS/2 Presentation Manager which is allocated to a process or thread that calls WinInitialize. anchor point - The position or choice from which selection or deselection is extended. APA - All points addressable. API - Application programming interface. application programming interface (API) - A functional interface supplied by the operating system, or by a separately-orderable licensed program, that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program. archive flag - In the OS/2 operating system, a flag of files and directories that the operating system uses to determine which files are new or modified. Files with this flag are included when a backup copy is made or when all the files are restored on a hard disk. See flag. area - In computer graphics, a filled shape such as a solid rectangle. ASCIIZ - A string of ASCII characters that is terminated with a byte containing the value 0. aspect ratio - (1) The ratio of the height of a rectangle to its width. A rectangle of width 10 inches and height 5 inches has an aspect ratio of 10/5 or 2. (2) On a display screen, the ratio of the maximum length of a display line to the maximum length of a display column. asynchronous (ASYNC) - (1) Pertaining to two or more processes that do not depend upon the occurrence of specific events such as common timing signals. (T) (2) Without regular time relationship; unexpected or unpredictable with respect to the execution of program instructions. atom - A constant that represents a string. Once a string has been defined as an atom, the atom can be used in place of the string to save space. Strings are associated with their respective atoms in an atom table. See integer atom. atom table - A table used to associate atoms with the strings that they represent. This table contains the mechanism by which the presence of a string can be verified. AVIO - Advanced Video Input/Output ═══ Glossary - B ═══ B background color - The color assigned to a background image. background mix - An attribute that determines how the background of a graphic primitive is combined with the existing color of the graphics presentation space. base device driver - An OS/2 device driver that performs I/O during the OS/2 kernel boot sequence to provide IPL support. Base device drivers are loaded by way of the CONFIG.SYS BASEDEV keyword, rather than the DEVICE keyword. See BASEDEV keyword, adapter device driver, and device manager. BASEDEV keyword - New CONFIG.SYS keyword; loads a base device driver into the operating system. Basic Input/Output System (BIOS) - Code that controls basic hardware operations, such as interactions with diskette drives, hard disk drives, and the keyboard. Bezier curve - A mathematical technique of specifying a smooth, continuous line or surface, requiring a starting point and an ending point, with several intermediate points that influence or control the path of the linking curve. BIOS - Basic Input/Output System. bit-block transfer (bitblt) - Transfer of a rectangular array of bit-map data. bitblt - Bit-block transfer. bit map - A representation of an image by an array of bits. block - (1) In programming languages, a compound statement that coincides with the scope of at least one of the declarations contained within it. A block may also specify storage allocation or segment programs for other purposes. (I) (2) A string of data elements recorded or transmitted as a unit. The elements may be characters, words or physical records. (T) (3) A collection of contiguous records recorded as a unit. Blocks are separated by interblock gaps and each block may contain one or more records. (A) Bit block transfer (bitblt) - The process of transferring one or more blocks of data. border - A visual indicator of a window's boundaries. BPB - BIOS Parameter Block. breakpoint - (1) A point in a computer program where execution may be halted. A breakpoint is usually at the beginning of an instruction where halts, caused by external intervention, are convenient for resuming execution. (T) (2) An instruction in a program for halting execution. Breakpoints are usually established at positions in a program where halts, caused by external intervention, are convenient for restarting. (T) (3) A place in a program, specified by a command or a condition, where the system halts execution and gives control to the workstation user or to a specified program. Bus Master adapter - An adapter capable of performing Reads and Writes to physical storage by communicating directly with the storage subsystem (memory) rather than depending on a host DMA channel or host CPU. Synonymous with first-party DMA adapter. ═══ Glossary - C ═══ C cached micro presentation space - A presentation space from a Presentation Manager owned store of micro presentation spaces. It can be used for drawing to a window only, and must be returned to the store when the task is complete. CDB - Command Descriptor Block. cell - See character cell. character box - (1) An imaginary parallelogram on a display surface that contains all parts of one graphic character. Synonymous with bounding box. (T) (2) The maximum area in which a symbol and all associated elements, such as a cursor, an underline, or space surrounding the symbol to separate it from other symbols, can be printed or displayed. Synonymous with character cell. (3) The imaginary parallelogram whose boundaries govern the size, orientation, and spacing of individual characters to be displayed on a graphics display device. character cell - (1) An addressable location on a display surface or printing medium. (2) The physical width and height in pels of a font. See also bounding box. (3) The imaginary box whose boundaries govern the size, orientation, and spacing of individual characters to be displayed on a workstation. character mode - A mode that, in conjunction with the font type, determines the extent to which graphics characters are affected by the character box, shear, and angle attributes. clipping - In computer graphics, removing those parts of display elements that lie outside of given boundary. clip limits - The area of the paper that can be reached by a printer or plotter. clipping path - A clipping boundary in world-coordinate space. code page - An assignment of graphic characters and control function meanings to all code points; for example, assignment of characters and meanings to 256 code points for an 8-bit code, assignment of characters and meanings to 128 code points for a 7-bit code. code point - A 1-byte code representing one of 256 potential characters. code segment - An executable section of programming code within a load module. color conversion - Changing one color format to another. Required, for example, when the source color format is different from the destination color format. When going from the monochrome color format to the color format, 1 (one) bits are converted to the image foreground color, and 0 (zero) bits are converted to the image background color. When going from color to monochrome, all pels that match the passed background color are converted to the image background color of the destination. All other pels are converted to the image foreground color of the destination. The color conversion takes place prior to any mix mode. color dithering - See dithering. command code - In this specification, refers to a group of related commands that an adapter device driver can receive. All command codes have a prefix of "IOCC_". For example, common I/O requests (such as Read, Write, etc.) are grouped under the command code IOCC_EXECUTE_IO. command data block - A data structure defined by the Small Computer System Interface standard to send commands to devices that conform to SCSI standards. command descriptor block (CDB) - The structure used to communicate commands from a source to a destination. command modifier - In this specification, a specific operation that an adapter device driver is to perform. All command modifiers have a prefix of "IOCM_". For example, an adapter device driver might receive an IOCC_EXECUTE_IO command with a command modifier of IOCM_READ. compatibility kernel - The portion of the OS/2 kernel that exists to support DOS INT 20, 21, 25, 26, and 27 functions. It acts as an interface to common kernel functionality such as the file system. CON - Character-device name reserved for the console keyboard and screen. conditional compilation - Processing by the preprocessor of certain specified code in the file, depending on the evaluation of a specified condition. context hook - Similar to a "force flag" in earlier versions of OS/2. These are events, signaled by a virtual device driver, that are processed at task time. Forcing an IRET, and simulating an NMI, can fall into this category. control program - A computer program designed to schedule and to supervise the execution of programs of a computer system. controller sector buffer - One or more buffers, managed by a hardware adapter, to improve I/O transfer rates by helping to match a device and software timing requirements. ═══ Glossary - D ═══ D DASD - Direct-access storage device. data bus - A bus used to communicate data internally and externally to and from a processing unit, storage, and peripheral devices. (A) See bus. data structure - The syntactic structure of symbolic expressions and their storage allocation characteristics. (T) DBCS - Double-byte character set. DC - Device context. DDB - Device-dependent bit map. deinstantiation - See instantiation. DevHlp - Device helper. device context (DC) - A logical description of a data destination such as memory, metafile, display, printer, or plotter. See also direct device context, information device context, memory device context, metafile device context, and screen device context. device driver - A file that contains the code needed to attach and use a device such as a display, printer, or plotter. device driver initialization (init) time - See initialization (init) time, device driver. device driver profile - A file with a "DDP" extension, containing a script that is interpreted by the OS/2 DDINSTAL utility. Among other things, it defines which files to copy from installation diskettes to target directories and specifies how the CONFIG.SYS file will be updated. device helper (DevHlp) - (1) A kernel service (memory, hardware interrupt, software interrupt, queuing, semaphore, and so forth) provided to physical device drivers. (2) A callable C-language or assembler-language routine that provides an operating system service for an OS/2 device driver. device object - A device that provides a means of communication between a computer and the outside world. A printer is an example of a device object. device table - A data structure containing a summary of the adapters an adapter device driver supports and a list of the I/O devices attached to each adapter. This data structure is built by the adapter device driver in response to an IOCC_CONFIGURATION IOCM_GET_DEVICE_TABLE request. direct access storage device (DASD) - A device in which access time is effectively independent of the location of the data. direct memory access (DMA) - (1) A technique for moving data directly between main storage and peripheral equipment without requiring processing of the data by the processing unit. (2) The transfer of data between memory and input/output units without processor intervention. display frame - (1) In computer graphics, an area in storage in which a display image can be recorded. (2) In computer micrographics, an area on a microform in which a display image can be recorded. dispatch table - (1) A block of memory, allocated by the graphics engine, for the containment of entry points for use by a display driver. (2) An array of pointers to function-handling routines. dithering - A technique for interleaving dark and light pels so that the resulting image looks smoothly shaded from a distance. DLL - Dynamic link library. DMA - Direct memory access. double-byte character set (DBCS) - A set of characters in which each character is represented by two bytes. Languages such as Japanese, Chinese, and Korean, which contain more characters than can be represented by 256 code points, require double-byte character sets. Because each character requires 2 bytes, the typing, display, and printing of DBCS characters requires hardware and programs that support DBCS. Contrast with single-byte character set. driver - (1) A program (and possibly data files) that contain information needed to run a particular unit, such as a plotter, printer, port, or mouse. See also device driver and printer driver. (2) A system or device that enables a functional unit to operate. dynamic link library (DLL) - A file containing executable code and data bound to a program at load time or run time, rather than during linking. The code and data in a dynamic link library can be shared by several applications simultaneously. ═══ Glossary - E ═══ E entry point - (1) In a database, the record that is first accessed upon entry into a database, caused by a user's command. (T) (2) The address or label of the first instruction executed on entering a computer program, routine, or subroutine. A computer program, routine, or subroutine may have a number of different entry points, each perhaps corresponding to a different function or purpose. (I) (A) Synonymous with entrance, entry. (3) In a routine, any place to which control can be passed. (A) (4) In the C, FORTRAN, and Pascal languages, the address or label of the first instruction processed or entered in a program, routine, or subroutine. A program, routine, or subroutine can have a number of different entry points, each corresponding to a different function or purpose. EOI - End Of Interrupt ═══ Glossary - F ═══ F Far call - Code that calls from one segment into another segment. fillet - An arc that is tangential to the end points of two adjacent lines. See also polyfillet. filter adapter device driver - A special class of adapter device drivers that do not manage the hardware directly, but monitor the stream of commands between a device manager and an adapter device driver. See Device Manager and adapter device driver. first-party DMA adapter - See bus master adapter. flag - A characteristic of a file or directory that enables it to be used in certain ways. See also archive flag, hidden flag, and read-only flag. flat address - See linear address. frame styles - Standard window layouts provided by the Presentation Manager. freeze and thaw services - Functions that prevent a DOS session from executing (VDHFreezeVDM) until the matching thaw function (VDHThawVDM) is called. The freeze occurs when the specified DOS session leaves kernel mode. ═══ Glossary - G ═══ G GDT - Global descriptor table. Global Descriptor Table (GDT) - A table that defines code and data segments available to all tasks in an application. glyph - A graphic symbol whose appearance conveys information; for example, the vertical and horizontal arrows on cursor keys that indicate the directions in which they control cursor movement, the sunburst symbol on the screen illumination control of a display device. GPI - Graphics programming interface graphic primitive - In computer graphics, a basic element, such as an arc or a line, that is not made up of smaller parts and that is used to create diagrams and pictures. graphics attributes - The attributes that apply to graphics primitives. Examples are color selection, line type, and shading pattern definition. Contrast with segment attributes. Graphics programming interface (GPI) - The formally-defined programming language that lies between an IBM graphics program and the user of the program. graphics segment - A sequence of related graphic primitives and graphics attributes. See also graphic primitive. GRE - Graphics engine. ═══ Glossary - H ═══ H handle - (1) An identifier that represents an object, such as a device or a window, to the Presentation Interface. (2) In the Advanced DOS and OS/2 operating systems, a binary value created by the system that identifies a drive, directory, and file so that the file can be found and opened. handshaking - A method by which two pieces of hardware, such as a personal computer and a plotter, can communicate. Depending upon the devices communicating, handshaking occurs either as a hardware function or through software, such as a device driver. hard error - An error condition on a network that requires that the network be reconfigured or that the source of the error be removed before the network can resume reliable operation. hardware palette - The array of RGBs that the physical device is displaying. heap - An area of free storage available for dynamic allocation by an application. Its size varies depending on the storage requirements of the application. hex - See hexadecimal hexadecimal - Pertaining to a system of numbers to the base 16; hexadecimal digits range from 0 through 9 and A through F, where A represents 10 and F represents 15. hook - A point in a system-defined function where an application can supply additional code that the system processes as though it were part of the function. hook chain - A sequence of hook procedures that are "chained" together so that each event is passed in turn to each procedure in the chain. ═══ Glossary - I ═══ I IDC - Inter-device-driver communication. in-memory buffer - A block of memory in the address space of the host machine, used for data transfer. init time - See initialization time, device driver. initialization time, device driver - After the OS/2 loads a device driver, it sends it an OS/2 request packet to initialize. During this initialization, certain DevHlp functions are not permitted. Also called init time. Input/Output Control (IOCtl) - A system service that provides a way for an application to send device-specific control commands to a device driver. Input/Output Privilege Level (IOPL) - Allows part of a Ring 3 application or device driver to execute at Ring 0. input router - OS/2 internal process that removes messages from the system queue. inter-device-driver communication (IDC) - A mechanism that enables a physical device driver to communicate with another physical device driver. interprocess communication - In the OS/2 operating system, the exchange of information between processes or threads through semaphores, queues, and shared memory. interrupt - An instruction that directs the microprocessor to suspend what it is doing and run a specified routine. When the routine is complete, the microprocessor resumes its original work. See also routine. interrupt request (IR) - Broadly, an "interrupt request level", referring to pending or in-service interrupt requests, or to a specific level (for example, IR 4). interrupt request flag - A bit in the 8259 PIC controller that indicates an interrupt is pending on particular level. The VPIC also maintains a virtual interrupt request flag for each interrupt level for each DOS session. interrupt service flag - A bit in the 8259 PIC controller that indicates an interrupt request is being serviced. It is cleared when the PIC is sent EOI. The VPIC maintains a virtual interrupt service flag indicating that a simulated interrupt is in-progress in a DOS session. interrupt time - When a device driver is run because of an interrupt rather than because of an application request. OS/2 device drivers receive interrupts either from the hardware they manage or from the system real-time clock. During interrupt time, certain DevHlp functions are not permitted. Also, addresses received directly from OS/2 applications might not be valid unless they are converted system addresses. IOCtl - Input/Output Control. IOPL - Input/Output Privilege Level. IORB - Input/Output Request Block. Input/Output Request Block (IORB) - A data structure defined by this specification that is passed as a parameter on all calls to an adapter device driver. It contains a fixed section, followed by a command-dependent section. IORBH - Input/Output Request Block Header IRET - Interrupt return. IRQ - Interrupt Request. ═══ Glossary - J ═══ J journal - A special-purpose file or data set that can be used to provide an audit trail of operator and system actions, or as a means of recovering superseded data. ═══ Glossary - K ═══ K kanji - A graphic character set consisting of symbols used in Japanese ideographic alphabets. Each character is represented by 2 bytes. kernel - (1) The part of an operating system that performs basic functions such as allocating hardware resources. (2) A program that can run under different operating system environments. kerning - The design of graphic characters so that their character boxes overlap. The toned picture elements (pels) of the character appear outside the character cell. Note: Kerning allows character boxes to overlap and characters to run together, so that characters can be designed for cursive languages, ligatures, or any other kind of character that requires more than one character box. It also allows for design of proportional-spaced fonts. By overlapping character boxes, characters can be placed closer together, or they can be placed farther apart by using overlapped blank character boxes. ═══ Glossary - L ═══ L LCT - logical color table. LDT - Local descriptor table. LIFO stack - A data structure from which data is retrieved in "Last-In, First-Out" order. linked list - A list in which the data elements may be dispersed, but in which each data element contains information for locating the next. Synonym for chained list. linear address - A unique value that identifies the memory object. Local Descriptor Table (LDT) - A table that defines code and data segments specific to a single task. logical palette - An array of RGB and mapping index pairs, created by the device driver when defining a palette (as a result of a GpqCreatePalette call). LVB - Logical Video Buffer. ═══ Glossary - M ═══ M memory device context - A logical description of a data destination that is a memory bit map. See also device context. metafile - A file containing a series of attributes that set color, shape, and size, usually of a picture or a drawing. Using a program that can interpret these attributes, a user can view the assembled image. metafile device context - A logical description of a data destination that is a metafile which is used for graphics interchange. See also device context. mickey - A unit of measurement for physical mouse motion whose value depends on the mouse device driver that is currently loaded. mixed character string - A string containing a mixture of one-byte and kanji or Hangeul (two-byte) characters. mutex semaphore - (Mutual exclusion semaphore). A semaphore that enables threads to serialize their access to resources. Only the thread that currently owns the mutex semaphore can gain access to the resource, thus preventing one thread from interrupting operations being performed by another. ═══ Glossary - N ═══ N named pipe - A named buffer that provides client-to-server, server-to-client or duplex communication between unrelated processes. Contrast with unnamed pipe. notification callout - The feature that provides for a routine to be called on completion of an input/output request. See also notification routine. notification routine - The routine indicated in an input/output request block to be called on completion of that request. See also notification callout. null-terminated string - A string of (n+1) characters where the (n+1)th character is the "null" character (X'00') and is used to represent an n-character string with implicit length. Also called a "zero-terminated" string or an "ASCIIZ". string. ═══ Glossary - O ═══ O ═══ Glossary - P ═══ P palette - A list of colors assigned to various areas on a panel. A user can change the color of these areas. PDD - Physical Device Driver. PDE - PageDirectoryEntry. pel - Picture element. permissible action - In a conceptual schema language, an action conforming to specified rules or constraints that changes a presumably consistent collection of sentences into a consistent one or makes known a consistent one present in the information base or conceptual schema. phase alignment - Aligning source bits with destination bits. Often required in a Bitblt function move operation where byte blocks are moved on bit boundaries. physical address - A 32-bit byte address giving the actual address in physical storage for a data item. physical device driver (PDD) - A system interface that handles hardware interrupts and supports a set of input and output functions. pipe - See named pipe, unnamed pipe. picture element (pel, pixel) - (1) In computer graphics, the smallest element of a display surface that can be independently assigned color and intensity. (T). (2) The area of the finest detail that can be reproduced effectively on the recording medium. (3) An element of a raster pattern about which a toned area on a photoconductor can appear. PIO - Programmed I/O. pixel - Picture element. polyfillet - A curve based on a sequence of lines. The curve is tangential to the end points of the first and last lines, and tangential also to the midpoints of all other lines. polyline - In computer graphics, a sequence of adjoining lines. pop - To remove an item from the top of a pushdown list. Contrast with push. prefetch - To locate and load a quantity of data in anticipation of a request. presence-check function - A Ring 3 (non-privileged) .EXE program that determines whether a given hardware interface is present on a workstation. PRESENCECHECK - A keyword, interpreted by the DDINSTAL utility, to determine whether to process the device driver profile file, based on the return code from PRESENCECHECK. printer driver - A file that describes the physical characteristics of a printer, plotter, or other peripheral device, and is used to convert graphics and text into device-specific data at the time of printing or plotting. Print Manager - In the Presentation Manager, the part of the spooler that manages the spooling process. It also allows the user to view print queues and to manipulate print jobs. privilege level - A method of protection that allows only certain program instructions to be used by certain programs. program group - Several programs that can be acted upon as a single entity. protect mode - A method of program operation that limits or prevents access to certain instructions or areas of storage. Contrast with real mode. push - To add an item to the top of a pushdown list. Contrast with pop. ═══ Glossary - Q ═══ Q queued device context - A logical description of a data destination (for example, a printer or plotter) where the output is to go through the spooler. See also device context. ═══ Glossary - R ═══ R read-only memory basic input/output system (ROM-BIOS) - Microcode in read-only memory that controls basic input/output operations such as interactions with cassettes, diskette drives, hard disk drives, and the keyboard. See also BIOS, NetBIOS. Note: ROM BIOS allows the user to write programs and add or remove devices without concern for characteristics such as device addresses. real mode - In the OS/2 operating system, a method of program operation that does not limit or prevent access to any instructions or areas of storage. The operating system loads the entire program into storage and gives the program access to all system resources. reentrant - The attribute of a program or routine that allows the same copy of the program or routine to be used concurrently by two or more tasks. removable-media indicator - A flag (bit) indicating that a device permits media removal. resource - The means of providing extra information used in the definition of a window. A resource can contain definitions of fonts, templates, accelerators and mnemonics; the definitions are held in a resource file. resurrection - The Presentation Manager event that occurs when switched back from a full-screen DOS or WIN-OS/2 session. RETF - Return far. reverse video - A form of highlighting a character, field, or cursor by reversing the color of the character, field, or cursor with its background; for example, changing a red character on a black background to a black character on a red background. ROM BIOS - Read-Only Memory Basic Input/Output System. ROP - Raster operation. RTC - Real-Time Clock. ═══ Glossary - S ═══ S SBCS - Single-byte character set SCB - See subsystem control block architecture. screen device context - A logical description of a data destination that is a particular window on the screen. See also device context. SCSI - Small Computer System Interface. seamless windows - An architecture contained within OS/2 which permits one or more applications to share windowed desktop graphical space and other resources, while executing concurrently. Application session windows managed by seamless windows can share border information, and pointing device transitions from session to session are handled smoothly and transparently. second-party DMA adapter - See DMA slave. semaphore - (1) A variable that is used to enforce mutual exclusion. (T) (2) An indicator used to control access to a file; for example, in a multiuser application, a flag that prevents simultaneous access to a file. (3) An entity used to control access to system resources. Processes can be locked to a resource with semaphores if the processes follow certain programming conventions. sense data - Data which describes an I/O error as defined by the ANSI SCSI specifications. single-byte character set (SBCS) - A character set in which each character is represented by a one-byte code. Contrast with double-byte character set. Small Computer System Interface (SCSI) - An input and output bus that provides a standard interface between the OS/2 multimedia system and peripheral devices. spline curve - In computer graphics, a shape created when a user specifies a series of points and the computer software draws a curve that smoothly approaches those points. spooler - A program that intercepts data going to a device driver and writes it to a disk. The data is later printed or plotted when the required device is available. A spooler prevents output from different sources from being intermixed. synchronous - Pertaining to two or more processes that depend upon the occurrence of specific events such as common timing signals. ═══ Glossary - T ═══ T text window - See VIO window. thread - The smallest unit of operation to be performed within a process. thunk - term used to describe the process of address conversion, stack, and structure realignment that is necessary when passing control between 16-bit and 32-bit modules. thunk layer - An interface that converts 32-bit parameters to 16-bit parameters, and maps linear addresses to segmented addresses. time slice - (1) The period of processing time allocated for running a program. (2) An interval of time on the processing unit allocated for use in performing a task. After the interval has expired, processing unit time is allocated to another task, so a task cannot monopolize processing unit time beyond a fixed limit. tuple - In a relational database, a part of a relation that uniquely describes an entity and its attribute. ═══ Glossary - U ═══ U unnamed pipe - A circular buffer created in memory; used by related processes to communicate with one another. Contrast with named pipe. ═══ Glossary - V ═══ V VBIOS - Virtual BIOS device driver VCMOS - Virtual CMOS device driver VDD - Virtual device driver VDH - Virtual video Device Handler VDM - Virtual DOS Machine; use DOS session. VDMA - Virtual Direct Memory Access device driver VDSK - Virtual hard DiSK device driver video graphics adapter (VGA) - A computer adapter that provides high-resolution graphics and a total of 256 colors. VIO - Virtual Input/Output VIRR - Virtual Interrupt Request Register Virtual Device Driver (VDD) - In the OS/2 operating system, a type of device driver used by DOS programs running in a DOS session to access devices, such as the screen or mouse, which must be shared with other processes in the system. The virtual device driver maps DOS device commands to the normal (physical) device driver under OS/2 2.0 and later versions of the operating system. virtual DevHlp (VDH) - Kernel (linear memory, paging, hardware interrupt, event control, port control) services provided to virtual device drivers. virtual I/O (VIO) - A facility that pages data into and out of external page storage. virtual memory - Synonym for virtual storage. Virtual Programmable Interrupt Controller - Virtualizes the 8259 Programmable Interrupt Controller (PIC). A special virtual device driver, in that it provides services to other virtual device drivers. virtual storage - Addressable space that is apparent to the user as the processor storage space, from which the instructions and the data are mapped into the processor storage locations. Synonymous with virtual memory. visible region - A window's presentation space clipped to the boundary of the window and the boundaries of any overlying window. VPIC - Virtual Programmable Interrupt Controller device driver. VRAM - Video Random-Access Memory. VTIMER - Virtual TIMER device driver. V86 mode - Virtual 8086 mode of the 80386 CPU. ═══ Glossary - W ═══ W window coordinates - A set of coordinates by which a window position or size is defined; measured in device units, or pels. ═══ Glossary - X ═══ X ═══ Glossary - Y ═══ Y There are no glossary terms for this initial letter. ═══ Glossary - Z ═══ Z