View source for Input/Output Device Driver Reference/Mouse Device Driver

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

Listed below are commonly-used terms and their definitions. These terms are frequently used throughout this chapter:
*MOUSE$. The OS/2 system-provided pointing device driver name, which is defined in the device header field of MOUSE.SYS.
*IDC. Inter-Device-Communication.
*Device-Independent-Device Driver. Another way of referring to MOUSE.SYS, which handles all the IDC interfaces defined on the following pages.
*Device-Dependent Device Driver. Hardware-specific device driver that communicates with MOUSE.SYS through the IDC for additional pointing device support. The OS/2 operating system provides pointing device support for the following:
:IBM Mouse
:IBM 8516 Touch Display
:Microsoft** Mouse
:Logitech** Mouse
:PC Mouse** Systems Mouse
:Any pointing device that is compatible with the above devices is supported.

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

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

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

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

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

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

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

==Physical Mouse Device Driver Considerations==
The OS/2 installation program ensures that physical mouse device driver initialization takes place prior to physical ASYNC device driver initialization. This allows the physical ASYNC device driver to determine that it is not responsible for servicing that port, ensuring that physical mouse device drivers are not preempted from the COM''n'' ports by the physical ASYNC device drivers.

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

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

==MOUSE.SYS IDC Interface==
The IDC provided by MOUSE.SYS supports the following:
*Process_Packet
*Disable_Support
*Process_Absolute
*Open_Mouse
*Close_Mouse
*Query_Activity

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

Input:
:'''AX'''= Process_Packet function code, 0001H.
:'''Common-event buffer initialized.''' The offset of the common-event buffer was passed on the Read_Enable request. This data buffer is used to pass both relative and absolute pointing-device events. When the physical device driver issues a Process_Packet request, the buffer has the following format:<br/><pre>
Event_Data   Struc

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

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

Output:
:No specific output for request.

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

;Note:Do not issue this request under normal circumstances.

Input:
:'''AX'''= Disable_Support function code, 0002H.

Output:
:No specific output for the request.

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

Input:
:'''AX'''= Process_Absolute function code, 0003H.
:'''Common-event buffer initialized.''' The offset of the common-event buffer was passed on the Read_Enable request. This data buffer is used to pass both relative and absolute pointing-device events. When issuing a Process_ Absolute request, the buffer has the following format:<br/><pre>
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</pre>
:MOUSE$ uses Row_Size and Col_Size to map the absolute event into the current display mode. These values should reflect the maximum allowed position that could be reported. All values are zero-based. The upper-left corner of the device should be reported as location 0,0.
:Initialize the buffer before making the request.

Output:
:No specific output for the request.

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

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

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

Error Return Codes: NO_HANDLES_AVAILABLE

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

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

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

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

Error Return Codes: INVALID_HANDLE

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

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

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

Output:
:'''AX'''= Error Return code if Carry is set; undefined if Carry is clear
:'''BX'''= Mouse Activity Status
:'''DS'''= MOUSE$ DD DS value
:'''ES'''= Calling DD DS value
:'''CX'''= Undefined
:'''DX'''= Undefined
:'''SI'''= Undefined
:'''DI'''= Undefined
:The Mouse Activity Status is a returned bit mask. A ''set'' bit is defined as having a value of 1. A set bit indicates that the description status or event occurred. The bit definitions for the Mouse Activity Status parameter are as follows:
:Bits 15-11 Reserved=0
:Bit 10 Button 5 usage, without motion
:Bit 9 Button 5 usage, with motion
:Bit 8 Button 4 usage, without motion
:Bit 7 Button 4 usage, with motion
:Bit 6 Button 3 usage, without motion
:Bit 5 Button 3 usage, with motion
:Bit 4 Button 2 usage, without motion
:Bit 3 Button 2 usage, with motion
:Bit 2 Button 1 usage, without motion
:Bit 1 Button 1 usage, with motion
:Bit 0 Pure motion was recorded.

;Note:The Mouse device-dependent IDC Interface allows a device with up to five buttons to be supported. The OS/2 operating system provides specific device support for only two-button and three-button pointing devices.

Error Return Codes: INVALID_HANDLE
:UNKNOWN_COMMAND

;Remarks:This function is valid only when OS/2 AIM Support is enabled. When Special Needs Support is inactive (AIM_Active = FALSE), IDC Query_Activity function requests are not allowed, and are returned to the caller with an UNKNOWN_COMMAND error code. For information on OS/2 AIM Support for physical device drivers, refer to Category 0Bh regarding System Notifications for Physical Device Drivers in the ''OS/2 Physical Device Driver Reference''.

==Device-Dependent Device Driver IDC Interface==
The IDC provided by the device-dependent device driver must support the following requests:
*Query_Config
*Read_Enable
*Read_Disable
*Disable_Device
*Enable_Device

===Query_Config===
This request is issued by MOUSE$ and determines the operating characteristics of the attached hardware. The format follows:

Input: '''AX'''= Query_Config function code, 0001H. <br />'''DI'''= Offset in mouse data segment of where to write the configuration data. <br />'''ES'''= Must be loaded with the MOUSE$ data segment/selector prior to the request. The configuration data has the following format:
<pre>
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
</pre>
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.

===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. <br />'''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|Process_Packet]], and [[#Process_Absolute|Process_Absolute]].

Output: No specific output for the request.

===Read_Disable===
This request is issued by MOUSE$ when it no longer accepts Process_Packet or Process_Absolute requests. References to the common-event buffer should be discontinued. However, MOUSE$ can enable the interface again by sending another Read_Enable request. Normally this request is not issued.

Input: '''AX'''= Read_Disable function code, 0003H

Output: No specific output for the request.

===Disable_Device===
This request is used by MOUSE$ when placing a pointing device in a disabled state. Upon completion of this request, no Process_Packet or Process_Absolute requests are to be made to MOUSE$ until an Enable_Device request is received. There is no requirement that the hardware itself be disabled, only that no Process_Packet or Process_Absolute requests be issued. Receipt of a Disable_Device request is not considered an error if the pointing device is already disabled.

Input: '''AX'''= Disable_Device function code, 0005H.

Output: No specific output for the request.

===Enable_Device===
This request is used by MOUSE$ when resetting a pointing device to an enabled state. Process_Packet and Process_Absolute requests are made to MOUSE$ when a pointing device is in an enabled state. Receipt of an Enable_ Device request is not considered an error if the pointing device is already enabled.

Input: '''AX'''= Enable_Device function code, 0004H.

Output: No specific output for the request.

==Building the WIN-OS/2 Mouse Device Driver==
WIN-OS/2* provides support for pointing devices using a generic mouse driver (MOUSE.DRV). Some devices may not work correctly with this driver. If this is the case, you should write a WIN-OS/2 mouse driver to support the new device type.

To write a WIN-OS/2 driver, examine the Windows** mouse driver example provided on the ''Microsoft Device Driver Kit''. Use the source code as a template for writing a WIN-OS/2 driver. In order for the driver to run correctly in the operating system, you must replace two files (MOUSE.ASM and INT33H.ASM) used in the Windows mouse driver. The source modifications (which are within the ifdef WINOS2 statements) support the WIN-OS/2 mouse driver. The replacement source files are available on the ''IBM Device Driver Source Kit for OS/2''.

The source code in the MOUSE.ASM file was modified to include global variables needed to support the device.

The source code in the INT33H.ASM file was modified to include the following:
*Add the external declarations for the new global variables
*Alter the execution path to enable the driver to run seamlessly
*Include additional code to support the mouse running under OS/2
*Change the state_xlate table
*Load ES with a driver code segment value
*Call the virtual device driver interface
*Add a routine that determines if the DOS session is running seamlessly
These modifications can be used with any device driver that is based on the Windows mouse device driver.

==Building the Physical Mouse Device Driver Code==
To build the physical mouse device drivers:
#Add the TOOLS directory in the ''IBM Device Driver Source Kit for OS/2'' to the current path.
#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.

[[Category:I/O Device Driver Reference]]