## Input/Output Device Driver Reference

[prev][next][parent][TOC]

### Inter-Device-Driver Client Interfaces

The OS/2 PCMCIA architecture includes a special set of interfaces that allow transparent application support for PCMCIA COM devices. The OS/2 COM device driver (COM.SYS) provides an IDC interface that allows PCMCIA Clients to map their serial devices into the standard COM port declarations . This interface enables a wide-range of existing COM-based applications, without modification, to view and access the PCMCIA devices as if they were standard COM devices.

The OS/2 COM IDC support for PCMCIA devices is unique because the client device driver performs the installation (device setup) and deinstallation ( device removal) processing with Card Services. The OS/2 COM physical device driver assumes the responsibilities for application interaction with the device as well as the device manipulation for the data transfer. The arrangement can be viewed as COM.SYS containing a generic COM device engine while the client manages mapping the device characteristics into the system .

The COM IDC interface connection is established by the Client Device Driver by issuing the DevHelp_AttachDD function with a device name parameter value of "COM1 " (COM1 followed by 4 blanks). The Client device driver can call the AttachDD function during the INIT Command (00h) or INIT_COMPLETE ( 1Fh) Command processing and save the returned DevHelp_IDC entry point information for later use.

In a Far Call/return model, the COM IDC is defined as a register-based interface. This interface uses the following register-to-argument assignments:

Input:

    -------------------------------------------------------------------

      [DS]            = COM DS selector value
      [ES]:[BX]       = Request Packet pointer

    -------------------------------------------------------------------

All other registers are undefined.

Output:

    -------------------------------------------------------------------

             Carry Flag      = Completion flag

             IF CF = 1         If CF is set (value=1) then the
                               request failed. The error code is
                               stored in the ReturnCode field
                               of the request packet.

             IF CF = 0         If CF is reset (value=0) then the
                               request completed successfully.

    -------------------------------------------------------------------

Input register values remain unchanged, all other registers are reserved.

COM is invoked using the protect-mode IDC entry point information returned by the DevHlp_AttachDD function. The caller must do the following:

Operate in a Far Call/return model.

Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface.

Establish the COM DS register value (from the information returned by AttachDD) prior to issuing COM function requests.

The COM IDC interface consists of two functions: Install Device and Deinstall Device. These IDC functions use a common packet format for parameter passing. The parameter packet structure is defined as:

    -------------------------------------------------------------------

       Field Name    Type      Description
       ----------    ------    -----------------
       Function      USHORT    Function code
       PortNumber    USHORT    COM Port Number
       PortAddr      USHORT    COM Port Address
       PortIRQ       USHORT    COM Port IRQ
       ReturnCode    USHORT    Return code

    -------------------------------------------------------------------

The COM IDC packet field descriptions and values are defined as follows:

Function

Input parameter.

Contains the IDC Requested function code. Supported values are:

-0 - Deinstall COM port device

This function requests that the established COM device associations for the device owned by the calling client device driver be removed. Deinstall requests are typically made during the client's processing of a Card Services CARD_REMOVAL event. The client should call this function 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.

PortNumber

Input parameter.

Contains the COM port number associated with the device. Supported values are:

-1 - indicates COM1 port selection
-2 - indicates COM2 port selection
-3 - indicates COM3 port selection
-4 - indicates COM4 port selection
-All other values are reserved for future use.

PortAddr

Input parameter.

Contains the four-digit hexadecimal COM port address associated with the device. This parameter value is ignored in the Deinstall function request. However, it should always be provided for future compatibility. Examples of typical COM port address values are 03F8h and 02F8h.

PortIRQ

Input parameter.

Contains the interrupt request level (IRQ) value associated with the device . Supported values are within the range of 1 through 15 and represent the IRQ number requested. All other values are reserved for future use.

ReturnCode

Input/Output parameter.

Contains the return code for the IDC function request. On input, the parameter value should be set to zero. On output, the supported values are:

-ERROR_DEVICE_IN_USE

Indicates the requested COM port number is already in use.

-ERROR_INTERRUPT

Indicates the requested IRQ level is already in use.

-ERROR_INVALID_ADDRESS

Indicates the requested COM port address is already in use.

-ERROR_DEV_NOT_EXIST

Indicates the requested COM port number is not installed. Only returned on Deinstall function requests.

-ERROR_INVALID_FUNCTION

Indicates the requested function code is not supported.

-NO_ERROR

Indicates the requested function completed successfully without errors.

Notes

1.All packet values defined as input parameters are provided by the calling client device driver. All output packet values are returned by COM. SYS.

2.The COM IDC requests may not be used during the Interrupt context. All requests should be made only during Kernel and Init contexts.