Input/Output Device Driver Reference/PCMCIA Architecture

This chapter contains a description of the Personal Computer Memory Card International Association (PCMCIA) hardware and software architecture as it applies to the OS/2 operating system. Also included is a list of supported functions, and information on deviations from the PCMCIA standard. In addition, information regarding Card Services, COM Support, Socket Services, Socket Services Sample, Client Driver Sample, and Fax/Modem client services are discussed.

Overview
PCMCIA is an organization of computer hardware and software manufacturers that is developing industry standards for personal computer card architecture and design. The PCMCIA standards include specifications for both the hardware and software components of the technology.

PCMCIA Hardware
There are three major hardware components defined in the PCMCIA standard: 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: 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.
 * Cards
 * Sockets
 * Adapters
 * Connectivity devices, such as modems, local area networks (LANs), and terminal emulators
 * Secondary storage devices, such as mini rotating hard disks, solid state file disks, and flash
 * Random access memory, such as SRAM, DRAM, or NVRAM memory
 * Storage for software, such as applications, device drivers, and ROM extensions

Adapters are connected to the host system's bus. The adapters map the host system bus technology to the PCMCIA technology. According to PCMCIA standards, up to 256 adapters can exist on a host system, and each adapter can have a maximum of 16 sockets.

PCMCIA Software
There are three major software components defined in the PCMCIA architecture: Clients 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.
 * Clients
 * Card Services
 * Socket Services

The Card Services component is an operating-system-specific layer that provides the Card Services functions defined in the PCMCIA interface specification. The Card Services interface functions are provided according to the operating system's specifics for the client device driver model environment. Card Services rely on operating system and Socket Services interfaces to facilitate requests from PCMCIA clients. The functions, features, and availability of the Card Services component are the responsibilities of the operating system developer or manufacturer.

The Socket Services component is a hardware-specific layer that isolates the details of the adapter and socket logic from the other software components. The Socket Services component provides the functions defined in the PCMCIA interface specification. Ideally, this software layer is built as a BIOS extension so that a single implementation can service multiple operating systems. However, it is acceptable to have device driver versions, because several situations preclude the availability of ROM solutions (as would be the case when you are adding adapters into existing host systems). The functions, features, and availability of the Socket Services component are the responsibilities of the hardware (adapter option or system unit) developer or manufacturer.

PCMCIA Specifications
The PCMCIA General Committee publishes the following specifications for the software architecture components:
 * PCMCIA Card Services Release 2.00 Interface Specification
 * PCMCIA Socket Services Release 2.00 Interface Specification

These specifications contain a complete description of the Card Services and Socket Services functions described in this chapter. They can be ordered from: PCMCIA Office 1030G East Duane Avenue Sunnyvale, CA 94086 (408) 720-0107 Voice (408) 720-9416 FAX (408) 720-9388 BBS

OS/2 PCMCIA Environment
There are three separate PCMCIA client environments in the OS/2 operating system: the DOS environment, WIN-OS/2 environment, and OS/2 environment. Each of these client environments has a separate Card Services interface binding (or protocol) that encapsulates the Card Service functions into the native environment's characteristics. Although the OS/2 operating system supports these three application environments, it currently does not support the PCMCIA client interfaces in all environments.

The responsibilities and restrictions of providing support for these client environments is summarized as follows:
 * OS/2 Card Services is responsible for providing the client environment interfaces. Currently this support is limited to the native OS/2 device-driver environment for OS/2 physical device drivers. The OS/2 client environment support is provided by the OS/2 Card Services and the physical device driver contained in the file named PCMCIA.SYS. The interface bindings for this support are defined in Client Interfaces.  The architecture is designed such that the PCMCIA software components mask the hardware details from the OS/2 application environments. The concept of a PCMCIA-aware application does not apply in the OS/2 operating system.  The DOS client environment is not supported. This means that the DOS PCMCIA interfaces, INT 1Ah functions in the range of 80h - AFh, are intercepted and rejected with the Carry flag set (value = 1). The DOS client environment support is provided by the OS/2 Card Services and virtual device driver contained in the file named VPCMCIA.SYS.  The WIN-OS/2 client environment is not supported.  At this time, the industry has not defined an interface binding for the WIN -OS/2 client environment; therefore, there are no OS/2 files provided for this environment.
 * OS/2 PCMCIA clients are responsible for providing device-specific support in the desired application environments.
 * OS/2 PCMCIA clients can be written as stand-alone physical device drivers or as physical/virtual device driver pairs. If the desired client device support is limited to OS/2 application environments, the client can be a single physical device driver. If the desired application environments include a DOS or WIN-OS/2 environment, or both, then a virtual device driver also must be provided to emulate the device characteristics in those environments.

OS/2 Initialization Architecture
The following steps describe the initialization flow of the PCMCIA software components in the OS/2 operating system. Card Services, the Resource Management Utility, and Socket Services are implemented as base devices (BASEDEV=). These BASEDEV drivers initialize in the order in which they occur in CONFIG.SYS, prior to any client drivers. Client drivers, unless they are ADDs, should be implemented as non-base device drivers (DEVICE=). After the BASEDEV drivers, the client drivers will then initialize in the order in which they occur in CONFIG.SYS.

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: 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. 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: 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. Card Services uses the following Socket Services functions to activate the adapter hardware: SetAdapter (86h), SetSocket (8Eh). 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. 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.
 * 1) Card Services Initialization
 * 1) *Non-system memory in the range C0000h - DFFFFh
 * 2) *IRQs in the range 2 through 15
 * 3) *I/O addresses in the range 0108h through FFFFh, with the following exceptions:
 * 4) **Addresses 3B4h, 3B5h, 3BAh, 3BBh, and 3C0h through 3DFh are reserved for video use.
 * 5) **Addresses 3F0h through 3F7h are reserved for diskette use.
 * 6) Resource Map Initialization
 * 1) Socket Services Initialization
 * 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).
 * 1) Allocating resources from the resource map for Socket Services.
 * Card Services assigns resources for the new Socket Services support, if available.
 * 1) Installing interrupt handlers for the Socket Services hardware.
 * 1) Programming the Socket Services hardware for the allocated resources.
 * 1) COM.SYS Physical Device Driver Initialization
 * 1) Client Device Driver Initialization

OS/2 PCMCIA Client Device Driver Model
The client device driver model is an important element of the OS/2 PCMCIA architecture. The PCMCIA client device driver model is a more restricted form of the general OS/2 device driver model. All OS/2 PCMCIA client device drivers are loaded during startup of the operating system. Therefore, before PCMCIA devices can be used, the user must determine the types of PCMCIA cards that might be used with the system, install the associated client device drivers, and add the appropriate statements to the CONFIG.SYS file. Client device drivers should be installed using the OS/2 DDINSTAL utility program because it simplifies device-driver installation for the user.

The OS/2 PCMCIA client device driver model utilizes the multisegment support available in the OS/2 operating system. Whenever a client device driver is not active (that is, no card is present), it should unlock its swappable/relocatable segments. The single, nonswappable/nonrelocatable base code segment must be organized so that it contains all the public entry points externalized by the client. In this way, all client public addresses are guaranteed to be valid. For example, the client device driver should ensure that the strategy, interrupt, Card Services callback, and other optional IDC entry point handling routines reside in the single, base code segment.

All worker routines should be placed in additional code segments and further organized for optimal paging. These additional code segments should be organized to contain routines that are used with approximately the same frequency intervals and conditions.

After all the needed unlocked segments have been reestablished in the system memory space, all resources required by a client must be requested from the operating system or Card Services after the notification of the card presence (through a CARD_INSERTION event).

Because it is possible to have numerous inactive client device drivers loaded in the operating system, the potential savings in unused system memory space is substantial.


 * Note:The previous information on the OS/2 multisegmented device driver model and DDINSTAL utility program also are applicable for device driver implementations of Socket Services.

For further details on the OS/2 multisegmented device driver model, refer to the OS/2 Physical Device Driver Reference.

Event Processing Flow
The following is a generalized event processing flow for the definition of responsibilities within the OS/2 PCMCIA environment. The following steps are provided for the CARD_INSERTION and CARD_REMOVAL events.

Note:The following scenario has been simplified for descriptive purposes. In addition, the defined scenario represents only the actions used to manage I/O card support. There are numerous combinations of Card Services and Socket Services functions, as well as ordering differences, when this scenario is broadened to include other events.


 * 1) Hardware Interrupt (Adapter)  The user inserts a PCMCIA Card into a socket. The adapter raises a Status Change interrupt to Card Services. Card Services, which has installed interrupt handlers for each adapter, calls the Socket Services AcknowledgeInterrupt (9Eh) function to retrieve the socket ID that generated the interrupt. Card Services sets up a global context hook handler to process the interrupt, issues the EOI for the adapter IRQ, and returns from the interrupt.
 * 2) CARD_INSERTION Events
 * a. When the Card Services context hook handler gets control, it processes the pending interrupt information by calling the Socket Services GetStatus (8Fh), GetSocket (8Dh), and SetSocket (8Eh) functions to retrieve the specific interrupt meaning. In this scenario, the CardStateand SocketStatefield values indicate a card insertion. Therefore, the Card Services timer handler creates CARD_INSERTION events and sends them to all client device drivers registered for the affected socket.
 * b. Each client device driver registered for the socket receives a CARD_ INSERTION event notification. Client device drivers process the event by calling the Card Services GetConfigurationInfo (04h) function to determine if the card has been claimed by another client and to identify the card's attributes. The client might also query more card data from the Card Information Structure (CIS) tuples by using the Card Services GetFirstTuple (07h), GetNextTuple (0Ah), and GetTupleData (0Dh) functions. If the client determines that the card cannot be supported, it returns from the event notification. If the client determines that the card can be supported, it uses the Card Services RequestIO (1Fh), RequestIRQ (20h), and RequestConfiguration (30h) functions to allocate resources to manage the card. If the resources are not available, the client returns from the event notification. If the resources are available, the client issues a DevHlp_ SetIRQ request to hook its interrupt handler into the operating system's IRQ chain.  Clients that use the COM IDC function should issue the Install function at this time, to map the device into the general COM application support. See COM Support for more details.
 * Note:Clients might receive two event notifications if the local and global event masks both have CARD_INSERTION events selected by way of the Card Services RegisterClient (10h) and SetEventMask (31h) functions.
 * c. Card Services processes the RequestConfiguration function (30h) by calling Socket Services SetSocket (8Eh) to program the adapter/card to the configuration information that has been locked for that socket.
 * 1) 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.
 * 2) 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.
 * 3) CARD_REMOVAL Events
 * a. When the Card Services timer handler gets control, it processes the pending interrupt information by calling the Socket Services GetStatus (8Fh ), GetSocket (8Dh), and SetSocket (8Eh) functions to retrieve the specific interrupt meaning. In this scenario, the CardStateand SocketStatefield values indicate a card removal. Therefore, the Card Services timer handler creates CARD_REMOVAL events and sends them to all client device drivers registered for the affected socket.
 * b. Each client device driver registered for the socket receives a CARD_ REMOVAL event notification. Client device drivers process the event by releasing Card Services resources (for example, by calling the Card Services ReleaseConfiguration (1Eh), ReleaseIO (1Bh), and ReleaseIRQ (1Ch) functions). In addition, the client device driver releases system resources (for example, by calling the DevHlp_UnsetIRQ function). Clients that use the COM IDC functions should issue the Deinstall function at this time to map the device into the general COM application support. The COM IDC client should issue the Deinstall function prior to releasing the Card Services resources or system resources associated with the device. See COM Support for more details.
 * 1) 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.
 * 2) d. Card Services processes the ReleaseIO (1Bh) and ReleaseIRQ (1Ch) functions by returning the referenced resources to the resource map. This makes them available for subsequent request function calls.

Card Services
The following includes implementation limitations and restrictions and client interfaces.

Implementation Limitations and Restrictions
There are some restrictions on OS/2 PCMCIA client device drivers. These restrictions define Card Services support. The following can be supported by Card Services: 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.
 * A maximum of four adapters
 * A maximum of eight sockets
 * A maximum of 16 clients
 * A maximum of four Socket Services drivers
 * A maximum of 16 memory technology drivers
 * A maximum of 16 memory handles
 * A maximum of 16 erase queues
 * A maximum of 16 regions
 * A maximum of 16 partitions
 * A maximum of seven windows per socket

The following are not supported or provided by Card Services:
 * Paged memory windows
 * ROM BIOS Socket Services
 * Power management support. Even though some of the interfaces have power management definitions, the values are ignored by Card Services. For future compatibility, the power management bit always should be reset to 0.
 * Write protection. Even though some of the interfaces have write-protect definitions, the values are ignored by Card Services. For future compatibility, the write-protect bit always should be reset to 0.

The following additional restrictions apply to client device drivers that manage PCMCIA cards with secondary storage devices:
 * During device-driver initialization, the PCMCIA secondary storage card might not be present, but the device driver must still claim the required number of drive letters that it supports.
 * Multi-partitioned cards must have a drive letter assigned to each partition for the partition to be accessible.
 * All secondary storage cards are treated as removable media. This prohibits enhanced performance from file systems using cached support.

Client Interfaces
The PCMCIA Card Services architecture consists of several basic interface elements. These interface elements are necessary for generating a composite binding for client device driver developers. The binding itself provides bidirectional validation of the PCMCIA architecture and the operating system implementation. The basic interface elements are:
 * Functions
 * Callbacks
 * Events
 * Memory Technology Driver Helpers
 * Media Access Routines
 * Return Codes

OS/2-specific descriptions for each of these elements are in the following sections.

In addition to the PCMCIA-architected interface elements listed previously, the OS/2 Card Services support has reserved Generic IOCtl - Category 0Dh for future use as a PCMCIA application programming interface.

Functions
OS/2 supports the following PCMCIA Card Services functions: AddSocketServices        (32h)    AdjustResourceInfo        (35h) CheckEraseQueue          (26h)    CloseMemory               (00h) CopyMemory               (01h)    DeregisterClient          (02h) DeregisterEraseQueue     (25h)    GetCardServicesInfo       (0Bh) GetClientInfo            (03h)    GetConfigurationInfo      (04h) GetEventMask             (2Eh)    GetFirstClient            (0Eh) GetFirstPartition        (05h)    GetFirstRegion            (06h) GetFirstTuple            (07h)    GetNextClient             (2Ah) GetNextPartition         (08h)    GetNextRegion             (09h) GetNextTuple             (0Ah)    GetStatus                 (0Ch) GetTupleData             (0Dh)    MapLogSocket              (12h) MapLogWindow             (13h)    MapMemPage                (14h) MapPhySocket             (15h)    MapPhyWindow              (16h) ModifyConfiguration      (27h)    ModifyWindow              (17h) OpenMemory               (18h)    RegisterClient            (10h) ReadMemory               (19h)    RegisterEraseQueue        (0Fh) RegisterMTD              (1Ah)    ReleaseConfiguration      (1Eh) ReleaseExclusive         (2Dh)    ReleaseIO                 (1Bh) ReleaseIRQ               (1Ch)    ReleaseSocketMask         (2Fh) ReleaseWindow            (1Dh)    ReplaceSocketServices     (33h) RequestConfiguration     (30h)    RequestExclusive          (2Ch) RequestIO                (1Fh)    RequestIRQ                (20h) RequestSocketMask        (22h)    RequestWindow             (21h) ResetCard                (11h)    ReturnSSEntry             (23h) SetEventMask             (31h)    SetRegion                 (29h) ValidateCIS              (2Bh)    WriteMemory               (24h) The PCMCIA Card Services function notation is defined for the OS/2 operating system as a register-based interface with the following register- to-argument assignments:

Input: [AL]            = Function argument [AH]            = Static AFh value [DX]            = Handle argument [DI]:[SI]       = Pointer argument [CX]            = ArgLength argument [ES]:[BX]       = ArgPointer argument All other registers are undefined.

Output: [AX]           = Status argument Carry Flag     = Completion flag All other registers are reserved.

Card Services is invoked using the protect-mode IDC entry point information returned by the DevHlp_AttachDD function. Card Services IDC entry point functions are callable only in kernel-context mode. The caller must do the following:


 * Operate in a Far Call/return model.
 * Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface.
 * Ensure that an appropriate stack is used for the calling model (16-bit protect mode) with at least 512 bytes of available stack space.
 * Establish the Card Services DS register value (from the information returned by AttachDD) prior to issuing Card Services function requests.

Card Services performs parameter-range checking on items directly managed and numbered. Card Services does not check each parameter on entry, but checks only those with values specified for the requested function. For example, Card Services determines if the logical socket number is valid or if a card is present in the socket being addressed. Card Services does not check if the card offset address is valid or if the unused input parameters contain null or zero values. For compatibility purposes, define all input values according to the guidelines outlined in the PCMCIA Interface Specification.

Callbacks
Card Services callbacks are events grouped into logical subsets, which include a general description and common call-based argument usage conventions. The call-back types received by a client device driver depend on the functions it uses.

The OS/2 operating system supports the following PCMCIA Card Services call-back types:
 * Client Information
 * Ejection/Insertion Requests
 * Erase Completion
 * Exclusive
 * Insertion
 * MTD Request
 * Registration Completion
 * Reset
 * Socket Services Updates
 * Status Change

In a Far Call/return model, the PCMCIA Card Services call-back invocation notation is defined for the OS/2 operating system as a register-based interface. All callback routines are guaranteed to be called only in kernel-context mode by the Card Services device driver. This callback interface uses the following register-to-argument assignments:

Input: [AL]           = Function argument [CX]           = Socket argument [DH]           = Information, socket status [DL]           = Information, card status [DI]           = ClientVal field from ClientData structure [DS]           = ClientDS field from ClientData structure [SI]           = ClientOff field from ClientData structure [SS]:[BP]      = MTD Request [ES]:[BX]      = Buffer argument [BX]           = Miscellaneous Argument, when no buffer argument All other registers are undefined.

Output: [AX]           = Status argument Carry Flag     = Completion flag

All other registers are preserved. The ClientData structure is used in the RegisterClient function and has the following format. Field Name   Type      Description --   --     ClientVal     USHORT    Client-specific data value ClientDS     USHORT    Client's data segment selector ClientOff    USHORT    Client's call-back data offset Reserved     USHORT    Reserved field

Events
The OS/2 operating system supports the following PCMCIA Card Services events: BATTERY_DEAD              (01h) BATTERY_LOW               (02h)

Note:These events can be generated at CARD_INSERTION time if hardware detection capabilities are available. CARD_INSERTION            (40h) CARD_READY                (04h) CARD_REMOVAL              (05h) CARD_RESET                (11h) CARD_LOCK                 (03h) CARD_UNLOCK               (06h) CLIENT_INFO               (14h) EJECTION_REQUEST          (08h) EJECTION_COMPLETE         (07h) ERASE_COMPLETE            (81h) EXCLUSIVE_REQUEST         (0Eh) EXCLUSIVE_COMPLETE        (0Dh) INSERTION_REQUEST         (0Ah) INSERTION_COMPLETE        (09h) MTD_REQUEST               (12h) REGISTRATION_COMPLETE     (82h) RESET_COMPLETE            (80h) RESET_PHYSICAL            (0Fh) RESET_REQUEST             (10h) SS_UPDATED                (16h) The events received by a client device driver depend on the functions the device driver uses.

Memory Technology Driver Helpers
The Memory Technology Driver (MTD) Helper routines provide Card Services assistance to MTDs during Read, Write, and Erase operations.

Card Services provides default MTD support. The default SRAM MTD supports Read, Write, and Erase (= write FFh) operations. A non-SRAM default MTD supports Read and Write operations as basic bus cycle byte presentations to the card (with no special algorithms). The Erase operation is not supported by the non-SRAM default MTD.

Media Access Routines
The media access routines are the common worker routines used by MTDs to perform the low-level primitive functions underlying the basic Read, Write, and Erase operations.

Card Services builds the Media Access Table (MAT) using the Socket Services function GetAccessOffsets for register-based sockets. If Socket Services does not support the function, the MAT is provided by Card Services itself.

All pointers in the MAT consist of Selector:Offset (16:16), level 0, GDT addresses.

Return Codes
All return codes are used and returned in the manner defined in the PCMCIA Card Services Release 2.00 Interface Specification unless explicitly noted in this document. Function compatibility determines which of the return codes (equate names and numeric values) will actually be returned for each function.

Functions that are not supported will be returned with the standard Card Services UNSUPPORTED_FUNCTION error code (15h).

Deviations from Card Services Release 2.00
There are some deviations from the PCMCIA Card Services Release 2.00 Interface Specification in the PCMCIA support. These deviations are as follows: The following return codes are available on all Card Services functions supported by the OS/2 operating system. Return Codes: The calling client is expected to retry the failed operation at a later time. The calling client is expected to either retry the operation later or cancel the current operation. (See Implementation Limitations and Restrictions for more details.) The Attributesfield defines details for the new Socket Services entry point. Card Services accepts only bit 1 (16:16 protect mode) requests. The DataPointerfield is used to establish data addressability for Socket Services when called by Card Services. Card Services accepts only 16-bit, protect-mode, GDT Level 0, data selector values. Return Codes: OS/2 Card Services returns the following error codes in addition to the error codes defined in the PCMCIA specification: Return Codes: OS/2 Card Services returns the following error code in addition to the error codes defined in the PCMCIA specification: To use the DeregisterClient function, the client must release all the resources allocated using the following functions: OS/2 Card Services returns the following error code in addition to the error codes defined in the PCMCIA specification: IBM OS/2 PCMCIA Card Services Device Driver. [c] Copyright IBM Corporation 1992, 1993, 1994. All Rights Reserved.
 * General
 * BUSY Unable to process request at this time; retry later.
 * OUT_OF_RESOURCE Out of internal or system resources necessary to process the request.
 * AddSocketServices (32h)
 * BAD_ARG_LENGTH ArgLength value is not equal to 4.
 * UNSUPPORTED_MODE Requested processor mode is not 16:16 protect mode.
 * AdjustResourceInfo (35h)
 * BAD_ARGS The IOAddrLinesfield is 0 or greater than 16.
 * DeregisterClient (02h)
 * RequestConfiguration
 * RequestIO
 * RequestIRQ
 * RequestWindow
 * RegisterEraseQueue
 * OpenMemory
 * Return Codes:
 * IN_USE A resource has not been released by the requesting client.
 * GetCardServicesInfo (0Bh) The following OS/2 Card Services returns the following:
 * 0100 for the Revision value.
 * 0200h for the CSLevel value.
 * Text for the VendorStrings value:
 * RegisterClient (10h)

Card Services does not support the power management change bit in the EventMask field. Set bit 8 to 0 for future compatibility. Card Services currently disregards the bit 8 value.

Card Services does not support the write-protect change bit in the EventMask field. Bit 0 should be set to 0 for future compatibility. Card Services currently disregards the bit 0 value.

Card Services does not support the Versionfield. It is recommended that the value be set to 0200h for future compatibility. Card Services currently disregards the Versionfield.

Return Codes:

OS/2 Card Services returns the following error code in addition to the error codes defined in the PCMCIA specification.

BAD_ATTRIBUTE No client type or more than one client type specified.


 * ReplaceSocketServices (33h)

One Socket Services device driver can replace another only if it takes ownership of the exact adapter resources previously claimed by the existing Socket Services device driver. If this does not occur, the request is rejected with a BAD_SOCKET error return code.


 * RequestIRQ (20h)

Card Services supports the following Attributes field bit definitions. Bit 0 - 1  IRQ type 0 - Exclusive 1 - Time-Multiplexed Sharing 2 - Dynamic Sharing 3 - Reserved Bit 2      Force Pulse (Not supported, must = 0) Bit 3      First Shared Bit 4 - 7  Reserved (Must = 0) Bit 8      Pulse IRQ Allocated (not supported, always returned as 0) Bit 9 - 15 Reserved (Must = 0) If any of the unsupported Attributes field bits are set, the request fails with a BAD_ATTRIBUTE return code.


 * RequestSocketMask (22h)

Card Services does not support the power management change or the write-protect change bits in the EventMask field. Set these bits to 0 for future compatibility. Card Services currently disregards these bit values.


 * RequestWindow (21h)

Card Services supports the following Attributesfield bit definitions. Bit 0     Reset to 0. Bit 1     Memory type (Set = attribute) Bit 2     Enabled (Set = true, reset = disabled) Bit 3     Data path width (Reset = 8-bit, set = 16-bit)

Bit 4     Paged (Set = true) (not supported, must be 0) Bit 5     Shared (Set = true) Bit 6     First Shared (Set = true) Bit 7 - 15 RESERVED (reset to 0) If any of the unsupported Attributes field bits are set, the request fails with a BAD_ATTRIBUTE return code.

Card Services sets the PCMCIA card memory offset for the window to 0. A client can change a PCMCIA card memory offset for the window by using the MapMemPage function.


 * SetEventMask (31h)

Card Services does not support the power-management change or the write- protect change bits in the EventMask field. Set these bits to 0 for future compatibility. Card Services currently disregards these bit values.

Card Services Device Driver Parameters
OS/2 Card Services supports the following BASEDEV= parameters in the CONFIG.SYS file: . . BASEDEV=[drive][:pathname]\PCMCIA.SYS /W . . Parameter descriptions are defined as follows: Wait line monitoring control. Refer to the Command Reference for a description of all the parameters defined for the Card Services device drivers.
 * /W

COM Support
The OS/2 COM driver provides generic hardware support for ASYNC COM ports present in the system unit. COM provides this generalized support to the application layers in OS/2 by way of Category 01h Generic IOCtl functions. Please see the OS/2 Physical Device Driver Reference for more details.

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

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

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

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

Input: [DS]           = COM DS selector value [ES]:[BX]      = Request Packet pointer All other registers are undefined.

Output: Carry Flag     = Completion flag IF CF = 1        If CF is set (value=1) then the request failed. The error code is                  stored in the ReturnCode field of the request packet. IF CF = 0        If CF is reset (value=0) then the request completed successfully. Input register values remain unchanged, all other registers are reserved.

COM is invoked using the protect-mode IDC entry point information returned by the DevHlp_AttachDD function. The caller must do the following:
 * Operate in a Far Call/return model.
 * Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface.
 * Establish the COM DS register value (from the information returned by AttachDD) prior to issuing COM function requests.

The COM IDC interface consists of two functions: Install Device and Deinstall Device. These IDC functions use a common packet format for parameter passing. The parameter packet structure is defined as: Field Name   Type      Description --   --    - Function      USHORT    Function code PortNumber   USHORT    COM Port Number PortAddr     USHORT    COM Port Address PortIRQ      USHORT    COM Port IRQ ReturnCode   USHORT    Return code The COM IDC packet field descriptions and values are defined as follows:


 * Function

Input parameter.

Contains the IDC Requested function code. Supported values are:

-0 - Deinstall COM port device

This function requests that the established COM device associations for the device owned by the calling client device driver be removed. Deinstall requests are typically made during the client's processing of a Card Services CARD_REMOVAL event. The client should call this function beforeit has released the resource configuration from Card Services.

-1 - Install COM port device

This function requests that the specific COM device associations for the device owned by the calling client device driver be established. Installation requests are typically made during the client's processing of a Card Services CARD_INSERTION event. The client should call this function afterit has received a resource configuration from Card Services.

-All other values are reserved for future use.


 * PortNumber

Input parameter.

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

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


 * PortAddr

Input parameter.

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


 * PortIRQ

Input parameter.

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


 * ReturnCode

Input/Output parameter.

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

-ERROR_DEVICE_IN_USE

Indicates the requested COM port number is already in use.

-ERROR_INTERRUPT

Indicates the requested IRQ level is already in use.

-ERROR_INVALID_ADDRESS

Indicates the requested COM port address is already in use.

-ERROR_DEV_NOT_EXIST

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

-ERROR_INVALID_FUNCTION

Indicates the requested function code is not supported.

-NO_ERROR

Indicates the requested function completed successfully without errors.


 * Notes
 * 1) All packet values defined as input parameters are provided by the calling client device driver. All output packet values are returned by COM.SYS.
 * 2) The COM IDC requests may not be used during the Interrupt context. All requests should be made only during Kernel and Init contexts.

Socket Services
The PCMCIA Socket Services architecture allows for both device driver and ROM BIOS implementations of the Socket Services support layer. Both implementation models follow a standard presence detection and interface setup methodology. This common methodology is defined as follows:

Presence Detection

Performed by issuing the real mode INT 1Ah - GetAdapterCount function request. If the function returns SUCCESS and "SS" in the Signature field, then at least one Socket Services handler exists.

Interface Setup

When Card Services completes the presence detection step it must: 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.
 * 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.

Functions
OS/2 supports the following PCMCIA Socket Services functions in device driver implementations: AcknowledgeInterrupt     (9Eh)    GetAdapter                (85h) GetAdapterCount          (80h)    GetPage                   (8Ah) GetSocket                (8Dh)    GetSSInfo                 (83h) GetStatus                (8Fh)    GetVendorInfo             (9Dh) GetWindow                (88h)    InquireAdapter            (84h) InquireSocket            (8Ch)    InquireWindow             (87h) ResetSocket              (90h)    SetAdapter                (86h) SetPage                  (8Bh)    SetSocket                 (8Eh) SetWindow                (89h) All Socket Services IDC functions are callable in kernel-context mode. In addition, the AcknowledgeInterrupt (9Eh) function is callable in interrupt-context mode. Card Services is responsible for managing the PCMCIA adapter interrupt state and issues the EOI upon return from the AcknowledgeInterrupt request.

The PCMCIA Socket Services function notation is defined for the OS/2 operating system as a register-based interface with the following register-to-argument assignments:

Input: [AH]            = Function argument [AL]            = Adapter argument [BH]            = Window argument [BL]            = Page or Socket argument [CX]            = Count argument [DX]            = Attributes argument [DS]:[SI]       = Data pointer argument [ES]:[DI]       = Buffer pointer argument [DI]            = Offset or Base argument All other registers are undefined.

Output: [AX]           = Return Code argument Carry Flag     = Status Indicator All other registers are reserved.

Socket Services is invoked using the protect-mode IDC entry point information, which is provided to Card Services in the AddSocketServices function request. Card Services is the sole client of Socket Services and provides the following interface requirements:
 * Operate in a Far Call/return model.
 * Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface.
 * Ensure that an appropriate stack is used for the calling model (16-bit protect mode) with at least 512 bytes of available stack space.
 * Establish the Socket Services DS register value (from the information provided by the AddSocketServices request) prior to issuing Socket Services function requests.

Socket Services performs parameter-range checking on items directly managed and numbered. Socket Services does not check each parameter on entry, but checks only those with values specified for the requested function. Socket Services does not check if the unused input parameters contain null or zero values. For compatibility purposes, define all input values according to the guidelines outlined in the PCMCIA Interface Specification.

Return Codes
All return codes are used and returned in the manner defined in the PCMCIA Socket Services Release 2.00 Interface Specification unless explicitly noted in this document. Function compatibility determines which of the return codes (equate names and numeric values) will actually be returned for each function.

Functions that are not supported will be returned with the standard Socket Services UNSUPPORTED_FUNCTION error code (15h).

Deviations from Socket Services Release 2.00
There are some deviations from the PCMCIA Socket Services Release 2.00 Interface Specification in the OS/2 operating systems PCMCIA support, as shown in the following list:


 * GetAdapterCount (80h)

OS/2 Socket Services returns the number of adapters supported by this driver for the TotalAdapters value.


 * GetSSInfo (0Bh)

OS/2 Socket Services returns 0100 for the Compliance value.

OS/2 Socket Services always returns zero for the FirstAdapter value.


 * GetVendorInfo (9Dh)

OS/2 Socket Services returns the following text for the pBuffer pointer: IBM OS/2 PCMCIA Socket Services Device Driver. [c] Copyright IBM Corporation 1992, 1993, 1994. All Rights Reserved. OS/2 Socket Services returns 0100 for the Release value.

Device Driver Parameters
OS/2 Socket Services supports the following BASEDEV= parameters in the CONFIG.SYS file: BASEDEV=drive:pathname\???xSS0n.SYS /C0=10 /C1=11 /S0=2 /S1=1

Refer to the Command Reference for a description of all the parameters defined for the Socket Services device drivers.

Sample Socket Services Device Driver
The sample Socket Services device driver, which supports the 82365SL B-Step PC Card Interface Controller (PCIC), is Intel** written to the PCMCIA Socket Services Interface 2.0 specification level. As of OS/2 2.1, Card Services is included with the base operating system. The Socket Services sample driver will fail to load if the OS/2 Card Services device driver is not already present.

At device driver load time, the Socket Services driver performs a DevHlp_ATTACHDD to Card Services. If this ATTACHDD fails, the Socket Services driver will set a return code in the request packet to indicate its failure to install. If the Socket Services driver successfully attaches to Card Services, it will interface to this driver by way of an IDC call to perform the AddSocketServices function.

The sample driver is written in assembler, and relies on the Microsoft MASM Assembler Version 6.00.

Invoking the Sample Socket Services Device Driver
The Socket Services driver is an OS/2 physical device driver and is invoked at system IPL time. Since the driver is a BASEDEV, it resides in the \OS2 directory of the IPL volume, and no path information is specified on the command line in CONFIG.SYS. The syntax is as follows: BASEDEV=SSPCIC.SYS /H /A:nnnn /E

Note that the parameters used by the driver are not the same as those used by the drivers shipped with OS/2. The sample driver will auto-detect the number of sockets present, and does not permit the manual specification of the IRQ. The driver will usually initialize properly with no parameters specified, but the following parameters may be used to direct its initialization:
 * /H
 * The /H parameter causes the driver to print out the help information and then terminate.


 * /A:nnnn
 * The /A:nnnn parameter allows the user to specify an adapter I/O address within the range 100h and 3F0h. If not specified, the default value 03E0h is used.


 * /E
 * The /E parameter enables initialization message output. If this parameter is not specified, messages will not be displayed.

Component Internal Structure
The component internal structure is described below.

IDC Interface
The IDC packet structure shared between the Socket Services driver and the Card Services driver is defined in Socket Services.

Component Logic Flow
The Socket Services driver is divided into two main parts: Initialization and Socket Services Interface Request Processing. The Socket Services Interface routines are straightforward procedures that perform the PCMCIA Socket Services functions defined in Socket Services. The device driver initialization routine is depicted in the following figure.



The sample Socket Services device driver consists of the modules shown in the following table:

Module to Function Map
The following table lists the modules and the function or routines they contain. Note the use of the following prefixes on some of the module names:
 * co - (common) Indicates code that should be common to any implementation of this driver
 * as - (adapter specific) These routines contain the code that would likely need to be changed if this driver is modified to support a different socket controller chip.
 * os - (operating system) Indicates a routine that is highly operating system specific.

IBM Data/FAX Modem Client Driver Sample
The OS/2 client driver for the IBM PCMCIA Data/FAX Modem is a device driver written to the PCMCIA Card Services Interface 2.0 specification level. In OS/2 2.1, Card Services is included with the base operating system. IBM PCMCIA Data/FAX Modem support for OS/2 will fail to install if Card Services, Socket Services, and the OS/2 COM.SYS device driver are not present. This is similar to the DOS support with the additional dependency of the COM.SYS driver. IBM PCMCIA Data/FAX Modem support is dependent upon COM.SYS because it interfaces to this driver through an IDC interface created specifically for PCMCIA support.

At device driver load time, the IBM PCMCIA Data/FAX Modem driver performs an ATTACHDD to COM.SYS. If this ATTACHDD fails, the IBM PCMCIA Data/FAX Modem will set a return code in the request pack back to OS/2 to indicate its failure to install.

If the IBM PCMCIA Data/FAX Modem driver successfully attaches to COM.SYS, it will interface to this driver by way of an IDC each time a PCMCIA modem is inserted or ejected from the system. When a modem is inserted, IBM PCMCIA Data/FAX Modem will call the COM.SYS IDC with a request packet indicating which new COM port was created. Likewise, when the modem is ejected, IBM PCMCIA Data/FAX Modem calls the COM.SYS IDC with a request packet indicating which COM port has been removed.

All but the essential device driver shell is written in C using the Microsoft C Compiler for OS/2, Version 6.0. The assembler pieces rely on the Microsoft MASM Assembler for OS/2, Version 5.10.

Invoking the Client Driver
The client driver is an OS/2 physical device driver and is invoked at system IPL time. The syntax for the client driver is as follows: DEVICE=C:\ESTDFM.OS2 SxCy,...,SxCy

SxCy where:S denotes PCMCIA Slot # and x = {1,2,3,4,5,6,7,8}

C denotes COM port # and y = {1,2,3,4}

This parameter is used to denote which COM port should be assigned to a modem present in a particular socket.

Up to four (4) of these parameters may be specified.

The following base address and IRQ values are assigned currently regardless of the target system bus. COM1:       03F8h   IRQ4 COM2:       02F8h   IRQ3 COM3:       03E8h   IRQ4 COM4:       02E8h   IRQ3 At this time, the enabling software will support a maximum of four IBM PCMCIA Data/FAX Modem. However, the absolute maximum is system dependent. A system with less than eight PCMCIA sockets could not utilize eight IBM PCMCIA Data/FAX Modem simultaneously. Likewise, a system that already has a COM port allocated to the planar reduces the maximum number modems that can be used simultaneously by one.

Component Internal Structure
The component internal structure is described below.

IDC Interface
The IDC packet structure shared between the OS/2 COM.SYS driver and a modem client driver is defined in COM Support.

Component Logic Flow
The client driver is divided into the following areas: Initialization, Card Services Interface, and Callback Notification.

The figure of Component Logic Flow - Driver Initialization details the high -level logic flow of the device driver design.



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 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.



Module to Function Map
The following table lists the modules and the function or routines they contain.

OS/2 Device Driver Routine Descriptions
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
 * 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.

public cs_idc_init begin if (attach to Card Service ok) 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 devhlp_init begin advance to area in request pkt containing DevHlp address save pointer to DevHlp entry point 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 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
 * set_com_port:This function passes a request to COM.SYS through the IDC.

void get_parameters(ULONG argP, short far *argc, char far * far *argv);
 * get_parameters:This function retrieves the parameters from the DEVICE= statement in the CONFIG.SYS file.

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
 * service_callback:This function services callback events for card insertion and card removal from Card services.

public callback_handler begin get event number and socket number call service_callback 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.

BOOL correct_card_id(UCHAR far *dataP)
 * 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.

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
 * release_com_port:This function removes the I/O address from the BIOS data area.

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_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.

static short store_socket_assignments (char far *strP,                USHORT far *io_addressP,                 USHORT far *irq_numP,                 USHORT num_of_io_addresses)
 * 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 ULONG make_flat_address(USHORT segment, USHORT offset)
 * 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 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
 * do_card_services:This function enables sockets and cards using Card Services.

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_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 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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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.

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_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.

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_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.

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_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.

USHORT cs_get_num_of_sockets(void) begin return the number of sockets end
 * cs_get_num_of_sockets:This function reports the number of sockets present in the system. The function returns the number of sockets.

Dependencies and Restrictions
This device must be loaded in the CONFIG.SYS file after COM.SYS.