Input/Output Device Driver Reference/PCMCIA Architecture

Input/Output Device Driver Reference

Advanced Power Management Architecture APM IOCtl Device Driver Test Tool Asynchronous (RS232-C) Communications Device Driver CLOCK$ Device Driver Joystick Device Driver Keyboard Device Driver Keyboard Inter-Device-Driver Communication Interfaces Keyboard Device Driver Test Tool Mouse Device Driver Mouse (DOS) Device Driver Test Tool Parallel Port Device Driver Physical Bidirectional Parallel Port Device Driver Parallel Port Device Driver Test Tool PCMCIA Architecture PCMCIA Socket Services Device Driver Test Tool Touch Display Device Driver Touch Inter-Device-Driver Communication Interfaces USB Device Driver Stack for OS/2 Warp Glossary

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

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

Overview

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

PCMCIA Hardware

There are three major hardware components defined in the PCMCIA standard:

• Cards
• Sockets
• Adapters

The cards come in several standardized sizes and shapes that are called form factors. The basic form factor is very similar to a credit card. There is a wide range of potential applications for PCMCIA cards, including:

• Connectivity devices, such as modems, local area networks (LANs), and terminal emulators
• Secondary storage devices, such as mini rotating hard disks, solid state file disks, and flash
• Random access memory, such as SRAM, DRAM, or NVRAM memory
• Storage for software, such as applications, device drivers, and ROM extensions

PCMCIA cards are treated in much the same way as standard removable media such as diskettes. The card slots, or sockets, are open bays into which the PCMCIA cards can be inserted without removing the system covers or turning off the system unit. Some PCMCIA Sockets contain mechanisms similar to those on diskette drives such as levers and locks.

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

PCMCIA Software

There are three major software components defined in the PCMCIA architecture:

• Clients
• Card Services
• Socket Services

Clients manage the device characteristics in an operating-system-specific environment and can be generalized as card-specific device drivers. Therefore, for any given card (device), there must be a specific device driver for each supported operating system. In addition, one client device driver can simultaneously manipulate several cards of the same type. Clients rely on the Card Services interfaces to set up and remove accessibility to the PCMCIA cards. The functions, features, and availability of client device drivers are the responsibilities of the PCMCIA card developer or the manufacturer.

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

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

PCMCIA Specifications

The PCMCIA General Committee publishes the following specifications for the software architecture components:

PCMCIA Card Services Release 2.00 Interface Specification

PCMCIA Socket Services Release 2.00 Interface Specification

These specifications contain a complete description of the Card Services and Socket Services functions described in this chapter. They can be ordered from:

 PCMCIA Office 
 1030G East Duane Avenue 
 Sunnyvale, CA 94086 
 
 (408) 720-0107 Voice 
 (408) 720-9416 FAX 
 (408) 720-9388 BBS

OS/2 PCMCIA Environment

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

The responsibilities and restrictions of providing support for these client environments is summarized as follows:

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

OS/2 Initialization Architecture

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

1. Card Services Initialization
   The Card Services component is implemented as an installable physical device driver. This component manages resources (I/O address space, IRQs, and memory) across the set of installed client device drivers and Socket Services. The Card Services component assumes that a default set of resources is available when it is initialized, and then adjusts the resource information (see Step 2) to limit or expand this resource base. The base set of resources that the Card Services component assumes are available to be managed, is defined as follows:
   • Non-system memory in the range C0000h - DFFFFh
   • IRQs in the range 2 through 15
   • I/O addresses in the range 0108h through FFFFh, with the following exceptions:
     • Addresses 3B4h, 3B5h, 3BAh, 3BBh, and 3C0h through 3DFh are reserved for video use.
     • Addresses 3F0h through 3F7h are reserved for diskette use.
2. Resource Map Initialization
   The Resource Map utility program is a special client device driver that determines the current system's hardware resource pool. This client is a hardware-specific device driver that performs the resource pool determination in a hardware-specific manner.
   The Resource Map utility program determines the system's resource information and informs Card Services by way of the AdjustResourceInfo (35h) function during BASEDEV INIT (1Bh) command processing. If an incorrect Resource Map utility program or no Resource Map utility program is loaded, Card Services continues to run, managing the default set of resources it assumed were present. (See Step 1).
   Because the Resource Map utility program is hardware-specific, it is provided by the hardware manufacturer on either the diskette that came with the computer or the diskette that came with the PCMCIA adapter.
3. Socket Services Initialization
   a. One or more Socket Services device drivers can be loaded into the operating system to support the adapters in the system unit. As each Socket Services device driver loads, it must verify the required hardware dependencies. During the BASEDEV INIT command (1Bh) processing, Socket Services device drivers must complete their inter-device-driver communication (IDC) initialization processing by calling the DevHlp_AttachDD function. If Card Services is loaded, the request for an IDC entry point for the device driver name "PCMCIA$ " (PCMCIA$, followed by a blank space) returns the 16:16 protect-mode information. The Socket Services device drivers then call the Card Services AddSocketServices (32h) function to establish the bidirectional IDC interface links. If the AttachDD request fails, the Socket Services device driver must free any allocated resources and permit itself to be swapped out of the active system memory as needed.
   b. Card Services processes the AddSocketServices (32h) function by:
   1. Identifying the Socket Services resources required.

      Card Services uses the following Socket Services functions to determine setup resources: GetAdapterCount (80h), GetSSInfo (83h), GetVendorInfo (9Dh), InquireAdapter (84h), GetAdapter (85h), InquireSocket (8Ch), and GetSocket (8Dh).

   2. Allocating resources from the resource map for Socket Services.

      Card Services assigns resources for the new Socket Services support, if available.

4. Installing interrupt handlers for the Socket Services hardware.
   Card Services uses the DevHlp_SetIRQ function to establish the adapter-specific interrupt handling routine for each adapter supported by the Socket Services currently initializing.
5. Programming the Socket Services hardware for the allocated resources.
   Card Services uses the following Socket Services functions to activate the adapter hardware: SetAdapter (86h), SetSocket (8Eh).
6. COM.SYS Physical Device Driver Initialization
   The COM physical device driver provides a set of additional client device driver IDC interfaces for transparent application support. (See COM Support for more details).
   During initialization processing, the COM physical device driver determines if the special COM client device driver interface support is needed. It then loads or discards the support modules appropriately. The determination is made by issuing the DevHlp_AttachDD with the device driver name "PCMCIA$" (PCMCIA$, followed by a blank space) specified for the Card Services physical device driver.
7. Client Device Driver Initialization
   Several client device drivers can be loaded into the operating system to support the various cards that might be plugged into the system's PCMCIA sockets. The initialization processing for these PCMCIA client device drivers is minimal. The card must be initialized on an as-needed basis because a card can be inserted into a socket at any time. To be ready for events such as CARD_INSERTION, the client device driver must establish an IDC interface connection into Card Services. The IDC link is established during either the INIT command (00h) or the INIT_COMPLETE command (1Fh) processing, by using the DevHlp_AttachDD function. If Card Services is loaded, the request for an IDC entry point for the device driver name "PCMCIA$" returns the 16:16 protect-mode information. If the AttachDD request fails, the client device driver must enter a dormant state equivalent to the wait state that would be entered when a card is not present. As soon as the presence of Card Services is confirmed and the interface address is retrieved, the client device driver issues the RegisterClient request and enters the normal mode of event processing.

OS/2 PCMCIA Client Device Driver Model

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

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

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

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

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

Note

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

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

Event Processing Flow

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

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

1. Hardware Interrupt (Adapter)
   
   The user inserts a PCMCIA Card into a socket. The adapter raises a Status Change interrupt to Card Services. Card Services, which has installed interrupt handlers for each adapter, calls the Socket Services AcknowledgeInterrupt (9Eh) function to retrieve the socket ID that generated the interrupt. Card Services sets up a global context hook handler to process the interrupt, issues the EOI for the adapter IRQ, and returns from the interrupt.
2. CARD_INSERTION Events

   a. When the Card Services context hook handler gets control, it processes the pending interrupt information by calling the Socket Services GetStatus (8Fh), GetSocket (8Dh), and SetSocket (8Eh) functions to retrieve the specific interrupt meaning. In this scenario, the CardStateand SocketStatefield values indicate a card insertion. Therefore, the Card Services timer handler creates CARD_INSERTION events and sends them to all client device drivers registered for the affected socket.

   b. Each client device driver registered for the socket receives a CARD_INSERTION event notification. Client device drivers process the event by calling the Card Services GetConfigurationInfo (04h) function to determine if the card has been claimed by another client and to identify the card's attributes. The client might also query more card data from the Card Information Structure (CIS) tuples by using the Card Services GetFirstTuple (07h), GetNextTuple (0Ah), and GetTupleData (0Dh) functions.
   
   If the client determines that the card cannot be supported, it returns from the event notification. If the client determines that the card can be supported, it uses the Card Services RequestIO (1Fh), RequestIRQ (20h), and RequestConfiguration (30h) functions to allocate resources to manage the card. If the resources are not available, the client returns from the event notification. If the resources are available, the client issues a DevHlp_ SetIRQ request to hook its interrupt handler into the operating system's IRQ chain.
   
   Clients that use the COM IDC function should issue the Install function at this time, to map the device into the general COM application support. See COM Support for more details.

   Note

   Clients might receive two event notifications if the local and global event masks both have CARD_INSERTION events selected by way of the Card Services RegisterClient (10h) and SetEventMask (31h) functions.

   c. Card Services processes the RequestConfiguration function (30h) by calling Socket Services SetSocket (8Eh) to program the adapter/card to the configuration information that has been locked for that socket.

3. Normal Device Activity
   
   The client device driver uses the card-configured resources to perform normal device-specific manipulations, such as reading and writing data, processing device interrupts, and enacting device commands.
4. Hardware Interrupt (Adapter)
   
   The user removes a PCMCIA Card from a socket. The adapter raises a Status Change interrupt to Card Services. Card Services calls the Socket Services AcknowledgeInterrupt (9Eh) function to retrieve the socket ID that generated the interrupt. Card Services sets up the interrupt processing context hook handler, issues the EOI for the adapter IRQ, and returns from the interrupt.
5. CARD_REMOVAL Events

   a. When the Card Services timer handler gets control, it processes the pending interrupt information by calling the Socket Services GetStatus (8Fh ), GetSocket (8Dh), and SetSocket (8Eh) functions to retrieve the specific interrupt meaning. In this scenario, the CardStateand SocketStatefield values indicate a card removal. Therefore, the Card Services timer handler creates CARD_REMOVAL events and sends them to all client device drivers registered for the affected socket.

   b. Each client device driver registered for the socket receives a CARD_REMOVAL event notification. Client device drivers process the event by releasing Card Services resources (for example, by calling the Card Services ReleaseConfiguration (1Eh), ReleaseIO (1Bh), and ReleaseIRQ (1Ch) functions). In addition, the client device driver releases system resources (for example, by calling the DevHlp_UnsetIRQ function).
   
   Clients that use the COM IDC functions should issue the Deinstall function at this time to map the device into the general COM application support. The COM IDC client should issue the Deinstall function prior to releasing the Card Services resources or system resources associated with the device. See COM Support for more details.

6. 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.
7. d. Card Services processes the ReleaseIO (1Bh) and ReleaseIRQ (1Ch) functions by returning the referenced resources to the resource map. This makes them available for subsequent request function calls.

Card Services

The following includes implementation limitations and restrictions and client interfaces.

Implementation Limitations and Restrictions

There are some restrictions on OS/2 PCMCIA client device drivers. These restrictions define Card Services support. The following can be supported by Card Services:

• A maximum of four adapters
• A maximum of eight sockets
• A maximum of 16 clients
• A maximum of four Socket Services drivers
• A maximum of 16 memory technology drivers
• A maximum of 16 memory handles
• A maximum of 16 erase queues
• A maximum of 16 regions
• A maximum of 16 partitions
• A maximum of seven windows per socket

The maximum window count is further defined such that five are memory windows (four for clients and one for Card Services), and two are I/O windows.

The following are not supported or provided by Card Services:

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

The following additional restrictions apply to client device drivers that manage PCMCIA cards with secondary storage devices:

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

Client Interfaces

The PCMCIA Card Services architecture consists of several basic interface elements. These interface elements are necessary for generating a composite binding for client device driver developers. The binding itself provides bidirectional validation of the PCMCIA architecture and the operating system implementation. The basic interface elements are:

• Functions
• Callbacks
• Events
• Memory Technology Driver Helpers
• Media Access Routines
• Return Codes

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

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

Functions

OS/2 supports the following PCMCIA Card Services functions:

AddSocketServices         (32h)    AdjustResourceInfo        (35h)
CheckEraseQueue           (26h)    CloseMemory               (00h)
CopyMemory                (01h)    DeregisterClient          (02h)
DeregisterEraseQueue      (25h)    GetCardServicesInfo       (0Bh)
GetClientInfo             (03h)    GetConfigurationInfo      (04h)
GetEventMask              (2Eh)    GetFirstClient            (0Eh)
GetFirstPartition         (05h)    GetFirstRegion            (06h)
GetFirstTuple             (07h)    GetNextClient             (2Ah)
GetNextPartition          (08h)    GetNextRegion             (09h)
GetNextTuple              (0Ah)    GetStatus                 (0Ch)
GetTupleData              (0Dh)    MapLogSocket              (12h)
MapLogWindow              (13h)    MapMemPage                (14h)
MapPhySocket              (15h)    MapPhyWindow              (16h)
ModifyConfiguration       (27h)    ModifyWindow              (17h)
OpenMemory                (18h)    RegisterClient            (10h)
ReadMemory                (19h)    RegisterEraseQueue        (0Fh)
RegisterMTD               (1Ah)    ReleaseConfiguration      (1Eh)
ReleaseExclusive          (2Dh)    ReleaseIO                 (1Bh)
ReleaseIRQ                (1Ch)    ReleaseSocketMask         (2Fh)
ReleaseWindow             (1Dh)    ReplaceSocketServices     (33h)
RequestConfiguration      (30h)    RequestExclusive          (2Ch)
RequestIO                 (1Fh)    RequestIRQ                (20h)
RequestSocketMask         (22h)    RequestWindow             (21h)
ResetCard                 (11h)    ReturnSSEntry             (23h)
SetEventMask              (31h)    SetRegion                 (29h)
ValidateCIS               (2Bh)    WriteMemory               (24h)

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

Input:

 [AL]             = Function argument
 [AH]             = Static AFh value
 [DX]             = Handle argument
 [DI]:[SI]        = Pointer argument
 [CX]             = ArgLength argument
 [ES]:[BX]        = ArgPointer argument

All other registers are undefined.

Output:

[AX]            = Status argument
Carry Flag      = Completion flag

All other registers are reserved.

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

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

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

Callbacks

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

The OS/2 operating system supports the following PCMCIA Card Services call-back types:

• Client Information
• Ejection/Insertion Requests
• Erase Completion
• Exclusive
• Insertion
• MTD Request
• Registration Completion
• Reset
• Socket Services Updates
• Status Change

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

Input:

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

All other registers are undefined.

Output:

         [AX]            = Status argument
         Carry Flag      = Completion flag

         All other registers are preserved.

The ClientData structure is used in the RegisterClient function and has the following format.

 Field Name    Type      Description
 ----------    ------    --------------------------------
 ClientVal     USHORT    Client-specific data value
 ClientDS      USHORT    Client's data segment selector
 ClientOff     USHORT    Client's call-back data offset
 Reserved      USHORT    Reserved field

Events

The OS/2 operating system supports the following PCMCIA Card Services events:

BATTERY_DEAD               (01h)
BATTERY_LOW                (02h)

Note:These events can be generated at CARD_INSERTION time if hardware detection capabilities are available.

 CARD_INSERTION             (40h)
 CARD_READY                 (04h)
 CARD_REMOVAL               (05h)
 CARD_RESET                 (11h)
 CARD_LOCK                  (03h)
 CARD_UNLOCK                (06h)
 CLIENT_INFO                (14h)
 EJECTION_REQUEST           (08h)
 EJECTION_COMPLETE          (07h)
 ERASE_COMPLETE             (81h)
 EXCLUSIVE_REQUEST          (0Eh)
 EXCLUSIVE_COMPLETE         (0Dh)
 INSERTION_REQUEST          (0Ah)
 INSERTION_COMPLETE         (09h)
 MTD_REQUEST                (12h)
 REGISTRATION_COMPLETE      (82h)
 RESET_COMPLETE             (80h)
 RESET_PHYSICAL             (0Fh)
 RESET_REQUEST              (10h)
 SS_UPDATED                 (16h)

The events received by a client device driver depend on the functions the device driver uses.

Memory Technology Driver Helpers

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

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

Media Access Routines

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

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

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

Return Codes

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

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

Deviations from Card Services Release 2.00

There are some deviations from the PCMCIA Card Services Release 2.00 Interface Specification in the PCMCIA support. These deviations are as follows:

• General
  The following return codes are available on all Card Services functions supported by the OS/2 operating system.
  Return Codes:

  BUSY Unable to process request at this time; retry later.
  The calling client is expected to retry the failed operation at a later time.

  OUT_OF_RESOURCE Out of internal or system resources necessary to process the request.
  The calling client is expected to either retry the operation later or cancel the current operation.
  (See Implementation Limitations and Restrictions for more details.)

• AddSocketServices (32h)
  The Attributesfield defines details for the new Socket Services entry point. Card Services accepts only bit 1 (16:16 protect mode) requests.
  The DataPointerfield is used to establish data addressability for Socket Services when called by Card Services. Card Services accepts only 16-bit, protect-mode, GDT Level 0, data selector values.
  Return Codes:
  OS/2 Card Services returns the following error codes in addition to the error codes defined in the PCMCIA specification:

  BAD_ARG_LENGTH ArgLength value is not equal to 4.

  UNSUPPORTED_MODE Requested processor mode is not 16:16 protect mode.

• AdjustResourceInfo (35h)
  Return Codes:
  OS/2 Card Services returns the following error code in addition to the error codes defined in the PCMCIA specification:

  BAD_ARGS The IOAddrLinesfield is 0 or greater than 16.

• DeregisterClient (02h)
  To use the DeregisterClient function, the client must release all the resources allocated using the following functions:
  • RequestConfiguration
  • RequestIO
  • RequestIRQ
  • RequestWindow
  • RegisterEraseQueue
  • OpenMemory

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

  IN_USE A resource has not been released by the requesting client.

• GetCardServicesInfo (0Bh)
  The following OS/2 Card Services returns the following:

  0100 for the Revision value.

  0200h for the CSLevel value.

  Text for the VendorStrings value:

 IBM OS/2 PCMCIA Card Services Device Driver.
 [c]  Copyright IBM Corporation 1992, 1993, 1994.
 All Rights Reserved.

• RegisterClient (10h)
  Card Services does not support the power management change bit in the EventMask field. Set bit 8 to 0 for future compatibility. Card Services currently disregards the bit 8 value.
  
  Card Services does not support the write-protect change bit in the EventMask field. Bit 0 should be set to 0 for future compatibility. Card Services currently disregards the bit 0 value.
  
  Card Services does not support the Versionfield. It is recommended that the value be set to 0200h for future compatibility. Card Services currently disregards the Versionfield.

Return Codes:

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

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

• ReplaceSocketServices (33h)
  One Socket Services device driver can replace another only if it takes ownership of the exact adapter resources previously claimed by the existing Socket Services device driver. If this does not occur, the request is rejected with a BAD_SOCKET error return code.
• RequestIRQ (20h)
  Card Services supports the following Attributes field bit definitions.

 Bit 0 - 1   IRQ type
             0 - Exclusive
             1 - Time-Multiplexed Sharing
             2 - Dynamic Sharing
             3 - Reserved
 Bit 2       Force Pulse (Not supported, must = 0)
 Bit 3       First Shared
 Bit 4 - 7   Reserved (Must = 0)
 Bit 8       Pulse IRQ Allocated
             (not supported, always returned as 0)
 Bit 9 - 15  Reserved (Must = 0)

If any of the unsupported Attributes field bits are set, the request fails with a BAD_ATTRIBUTE return code.

• RequestSocketMask (22h)
  Card Services does not support the power management change or the write-protect change bits in the EventMask field. Set these bits to 0 for future compatibility. Card Services currently disregards these bit values.
• RequestWindow (21h)
  Card Services supports the following Attributesfield bit definitions.

 Bit 0      Reset to 0.
 Bit 1      Memory type (Set = attribute)
 Bit 2      Enabled (Set = true, reset = disabled)
 Bit 3      Data path width (Reset = 8-bit, set = 16-bit)
 
 Bit 4      Paged (Set = true)
            (not supported, must be 0)
 Bit 5      Shared (Set = true)
 Bit 6      First Shared (Set = true)
 Bit 7 - 15 RESERVED (reset to 0)

If any of the unsupported Attributes field bits are set, the request fails with a BAD_ATTRIBUTE return code.

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

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

Card Services Device Driver Parameters

OS/2 Card Services supports the following BASEDEV= parameters in the CONFIG.SYS file:

  .
  .
 BASEDEV=[drive][:pathname]\PCMCIA.SYS /W
  .
  .

Parameter descriptions are defined as follows:

• /W
  Wait line monitoring control.
  Refer to the Command Reference for a description of all the parameters defined for the Card Services device drivers.

COM Support

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

Inter-Device-Driver Client Interfaces

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

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

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

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

Input:

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

All other registers are undefined.

Output:

 Carry Flag      = Completion flag
 
 IF CF = 1         If CF is set (value=1) then the
                   request failed. The error code is
                   stored in the ReturnCode field
                   of the request packet.
 
 IF CF = 0         If CF is reset (value=0) then the
                   request completed successfully.

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

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

• Operate in a Far Call/return model.
• Use only Global Descriptor Table (GDT) Level 0, 16:16 (Selector:Offset) addresses in all pointer or address fields referenced across the interface.
• Establish the COM DS register value (from the information returned by AttachDD) prior to issuing COM function requests.

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

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

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

• Function
  Input parameter.
  
  Contains the IDC Requested function code. Supported values are:

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

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

  -All other values are reserved for future use.

• PortNumber
  Input parameter.
  
  Contains the COM port number associated with the device. Supported values are:

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

• PortAddr
  Input parameter.
  
  Contains the four-digit hexadecimal COM port address associated with the device. This parameter value is ignored in the Deinstall function request. However, it should always be provided for future compatibility. Examples of typical COM port address values are 03F8h and 02F8h.
• PortIRQ
  Input parameter.
  
  Contains the interrupt request level (IRQ) value associated with the device. Supported values are within the range of 1 through 15 and represent the IRQ number requested. All other values are reserved for future use.
• ReturnCode
  Input/Output parameter.

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

• ERROR_DEVICE_IN_USE - Indicates the requested COM port number is already in use.
• ERROR_INTERRUPT - Indicates the requested IRQ level is already in use.
• ERROR_INVALID_ADDRESS - Indicates the requested COM port address is already in use.
• ERROR_DEV_NOT_EXIST - Indicates the requested COM port number is not installed. Only returned on Deinstall function requests.
• ERROR_INVALID_FUNCTION - Indicates the requested function code is not supported.
• NO_ERROR - Indicates the requested function completed successfully without errors.

Notes

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

Socket Services

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

Presence Detection

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

Interface Setup

When Card Services completes the presence detection step it must:

1. Issue the real mode INT 1Ah - GetSSInfo function request to identify the mapping between Socket Services handlers and the adapters located in the system.
2. Issue the real mode INT 1Ah - GetSetSSAddr function request (w/subfunc = 0) to determine supporting interface modes and interface interaction dependencies. In addition, more GetSetSSAddr function requests (w/subfunc = 1 and 2) are needed for implementations requiring additional data areas.
3. All subsequent interface function requests do not use the INT 1Ah convention but rather use one of the supported interface modes returned in the previous step.

OS/2 Card Services does not currently support ROM BIOS implementations of Socket Services. This is primarily a test statement based upon the lack of ROM BIOS systems for OS/2 Card Services on which it is to be verified. The OS/2 Socket Services device driver model does not require all of the defined PCMCIA architecture interface setup steps previously listed. Therefore, the OS/2 Socket Services presence detection and interface setup methodology for device driver implementations follow the logic defined earlier in this document see Step 3 of the #OS/2 Initialization Architecture.

Functions

OS/2 supports the following PCMCIA Socket Services functions in device driver implementations:

AcknowledgeInterrupt      (9Eh)    GetAdapter                (85h)
GetAdapterCount           (80h)    GetPage                   (8Ah)
GetSocket                 (8Dh)    GetSSInfo                 (83h)
GetStatus                 (8Fh)    GetVendorInfo             (9Dh)
GetWindow                 (88h)    InquireAdapter            (84h)
InquireSocket             (8Ch)    InquireWindow             (87h)
ResetSocket               (90h)    SetAdapter                (86h)
SetPage                   (8Bh)    SetSocket                 (8Eh)
SetWindow                 (89h)

All Socket Services IDC functions are callable in kernel-context mode. In addition, the AcknowledgeInterrupt (9Eh) function is callable in interrupt-context mode. Card Services is responsible for managing the PCMCIA adapter interrupt state and issues the EOI upon return from the AcknowledgeInterrupt request.

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

Input:

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

All other registers are undefined.

Output:

[AX]            = Return Code argument
Carry Flag      = Status Indicator

All other registers are reserved.

Socket Services is invoked using the protect-mode IDC entry point information, which is provided to Card Services in the AddSocketServices function request. Card Services is the sole client of Socket Services and provides the following interface requirements:

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

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

Return Codes

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

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

Deviations from Socket Services Release 2.00

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

• GetAdapterCount (80h)

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

• GetSSInfo (0Bh)

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

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

• GetVendorInfo (9Dh)

OS/2 Socket Services returns the following text for the pBuffer pointer:

 IBM OS/2 PCMCIA Socket Services Device Driver.
   [c]  Copyright IBM Corporation 1992, 1993, 1994.
 All Rights Reserved.

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

Device Driver Parameters

OS/2 Socket Services supports the following BASEDEV= parameters in the CONFIG.SYS file:

BASEDEV=drive:pathname\???xSS0n.SYS /C0=10 /C1=11 /S0=2 /S1=1

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

Sample Socket Services Device Driver

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

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

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

Invoking the Sample Socket Services Device Driver

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

BASEDEV=SSPCIC.SYS /H /A:nnnn /E

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

• /H

The /H parameter causes the driver to print out the help information and then terminate.

• /A:nnnn

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

• /E

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

Component Internal Structure

The component internal structure is described below.

IDC Interface

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

Component Logic Flow

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

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

Module	Module Description	Line-of-Code Estimates
MAKEFILE	Makefile source	N/A
SSOS2DRV.ASM	Contains the OS/2 operating system dependent routines	243
SSPCICIN.ASM	Socket Services device driver initialization routines	386
SSPCIC.ASM	PCMCIA Socket Services Functions routines, except for window management routines	623
SSPCICDP.ASM	Device driver internal function dispatcher	212
SSPCICVA.ASM	Request parameter validation routines	115
SSPCICWM.ASM	Window Management routines	569
SSPCICUT.ASM	Utility routines used by the primary function routines of the driver	218
SSMSG.ASM	The device driver's initialization messages	42
SSOS2.INC	OS/2 operating system related definitions	39
SSMSG.INC	Message file related definitions	22
SSPCIC.INC	Intel 82365SL PCIC related definitions	241
SSDEFS.INC	PCMCIA Socket Services related definitions	295
SS_SEGM.INC	Physical Device Driver data and code segment definitions	28
SSMAC.INC	Internally used macro definitions	18
SSPCIC.DEF	Linker definitions file	N/A
TOTAL		3051

Module to Function Map

The following table lists the modules and the function or routines they contain. Note the use of the following prefixes on some of the module names:

• co - (common) Indicates code that should be common to any implementation of this driver
• as - (adapter specific) These routines contain the code that would likely need to be changed if this driver is modified to support a different socket controller chip.
• os - (operating system) Indicates a routine that is highly operating system specific.

Modules	Routines
SSOS2DRV.ASM	Strategy GetSegmPars GetSetSSAddr osAddSS osOKtoLoad osPrintString osPrintChar
SSPCICIN.ASM	coiInitAdapter coiInitSocket coiInitWindow coiInitAll coiScanCommand asDetectAdapter asResetHardware coiInitSS
SSPCIC.ASM	GetReg SetReg asSetSktIRQ asSetSktInterface asSetSktMask GetPower SetVcc SetVpp SoftReset GetSktChanges GetAdapterCnt GetSSInfo GetVendorInfo AckInterrupt InquireAdapter InquireSocket SetSktPower GetSocket GetStatus SetSocket ResetSocket GetInstSktState GetAdapter SetAdapter
SSPCICDP.ASM	IsCardIn ValidateArgs codCommon16 codRM_Entry
SSPCICVA.ASM	covValidateIRQ CheckPowerLevel covValidatePw covValidateIFt
SSPCICWM.ASM	cowDisableWindow cowEnableWindow cowIsWindowEnabled cowValWinPars GetWndReg SetWndReg CalcWndIndex asGetWindowCtrl InquireWindow GetWindow SetupMemWin SetupIOWin SetWindow GetPage SetPage
SSPCICUT.ASM	couDelay couIsValidSpeed couGetSpeedComp couCompSpeed couCopyInfo couGetHex couGetToken couStrlen

IBM Data/FAX Modem Client Driver Sample

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

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

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

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

Invoking the Client Driver

The client driver is an OS/2 physical device driver and is invoked at system IPL time. The syntax for the client driver is as follows:

DEVICE=C:\ESTDFM.OS2 SxCy,...,SxCy

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

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

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

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

The following base address and IRQ values are assigned currently regardless of the target system bus.

 COM1:        03F8h   IRQ4
 COM2:        02F8h   IRQ3
 COM3:        03E8h   IRQ4
 COM4:        02E8h   IRQ3

At this time, the enabling software will support a maximum of four IBM PCMCIA Data/FAX Modem. However, the absolute maximum is system dependent. A system with less than eight PCMCIA sockets could not utilize eight IBM PCMCIA Data/FAX Modem simultaneously. Likewise, a system that already has a COM port allocated to the planar reduces the maximum number modems that can be used simultaneously by one.

Component Internal Structure

The component internal structure is described below.

IDC Interface

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

Component Logic Flow

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

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

The figure of Component Logic Flow - Enable Modem below details the high-level logic flow of the device driver design.

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

The OS/2 client driver for the IBM PCMCIA Data/FAX Modem consists of the modules shown in the following table.

Module	Module Description	Line-of-Code Estimates
MAKEFILE	C makefile source	N/A
CS_IDC.H	Contains CS_IDC.ASM function prototype.	2
CS_IDC.ASM	Contains the assembler code that attaches and interfaces to card services	131
CS_HELP.ASM	The callback handler function that card services will invoke when a registered event occurs	75
CS_HELP.H	Callback handler C function prototype	1
COMPORT.C	Contains the functions that acquire and release the COM port	149
COMPORT.H	Function prototypes for acquiring and releasing the COM port	3
CS_UTIL.C	Contains the card services calls to allocate and deallocate resources for the modem	734
CS_UTIL.H	Contains the release and acquire resources function prototypes	3
CS.C	Contains the routines to register with card services and to handle the card present event	312
CS.H	Declarations for the routines that interface with card services	26
CARD_ID.C	Verifies the identity of the modem card	29
CARD_ID.H	Declaration for the card_id function	1
SHELL.ASM	Contains assembler shell that creates a device driver model to which the C code can interface	77
DEVHLP.ASM	Contains routines help access DevHelp routines from the operating system	58
CS_HELP.ASM	The Callback handler that card services will invoke when a registered event occurs	75
CONFIG.C	Contains routines that process and store configuration info for the system	100
CONFIG.H	Constant definitions and prototypes used by CONFIG.C	15
DEVHELP.H	Definitions and public functions for Device Driver help routines	10
STGY.C	Contains the strategy portion of the device driver	258
COM_IDC.ASM	Contains the code interfaces with OS/2 COM.SYS by way of the new IDC	124
COM_IDC.H	Contains the declarations and prototypes for COM_IDC	2
SHELL.H	Device Driver prototypes	3
TYPES.H	Contains constant definition and type definition for the system	7
TOTAL		2195

Module Tree

The figure of OS/2 Client Driver Initialization Routine depicts the logic flow of the initialization portion of the OS/2 client driver.

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.

Modules	Routines
CARD_ID.C	correct_card_id
COMPORT.C	acquire_com_port release_com_port
CONFIG.C	store_config_info store_socket_assignments
CS.C	cs_services_present cs_card_present cs_register_client service_callback cs_get_num_of_sockets
CS_UTIL.C	cs_acquire_resource cs_request_irq cs_request_io cs_request_configuration cs_is_modem_card cs_release_resource cs_release_configuration cs_release_irq cs_release_io
STGY.C	do_strat get_parameters
COM_IDC.ASM	com_idc_init set_com_port
CS_HELP.ASM	callback_handler
CS_IDC.ASM	cs_idc_init do_card_services
DEVHLP.ASM	devhlp_init
SHELL.ASM	strategy

OS/2 Device Driver Routine Descriptions

do_strat

This function is the device driver strategy routine. The parameter 'rpP' is a pointer to a block of information from the operating system called the request packet.

void do_strat(REQPACKET far *rpP)
begin
       switch(request pkt cmd)
         case (initialization)
           if driver already installed
            set status to error
           else
            save pointer to DevHlp routines
            if (cs_idc_init fails)
             set status to error
            if (com_idc_init fails)
             set status to error
            parse and save device= parms
            set status to success
         case (init complete)
            if card services present
             get number of sockets machine supports
             store configuration information
             if (registered with card services failed)
              set error status
             else
              set status to success
         end switch
       return
end

com_idc_init This function retrieves the inter-device-driver communications entry point from COM.SYS. The function returns the value -1, if successful. Otherwise, the value 0 is returned.

public com_idc_init
begin
            if (attach to COM.SYS o.k.)
             save pointer to IDC entry point
            else
             set error code
end

cs_idc_init

This function retrieves the inter-device-driver communications entry point from Card Services. The function returns the value -1 if successful. Otherwise, the value 0 is returned.

public cs_idc_init
begin
            if (attach to Card Service ok)
             save pointer to IDC entry point
            else
             set error code
end

devhlp_init

This function stores the OS/2 device driver help services entry point. The function returns the value -1, if successful. Otherwise, the value 0 is returned.

public devhlp_init
begin
            advance to area in request pkt containing DevHlp
            address save pointer to DevHlp entry point
end

set_com_port

This function passes a request to COM.SYS through the IDC.

public set_com_port
begin
    copy parms off of stack and into IDC packet
    (IDC command,comport #, comport address, comport IRQ)
    call COM.SYS by way of IDC
    get COM.SYS return code back from IDC pkt
end

get_parameters

This function retrieves the parameters from the DEVICE= statement in the CONFIG.SYS file.

void get_parameters(ULONG argP, short far *argc,
 char far * far *argv);

service_callback

This function services callback events for card insertion and card removal from Card services.

void service_callback (USHORT socket_num, USHORT event_num)
begin
    switch(event_number)
      case (card inserted)
       if (card is an IBM modem)
         call cs_acquire_resource
         return if unsuccessful
         call set_com_port(INSTALL_CMD)
         call cs_release_resource and return if unsuccessful
         call acquired_com_port
         call cs_release_resource.  Set_com-Port (DEINSTALL_CMD)
           and return if unsuccessful
       endif
      case (card removed)
       if (card removed is ours)
         call cs_release_resource
         return if unsuccessful
         call set_com_port(DEINSTALL_CMD)
         call release_com_port
       endif
      end switch
end

callback_handler

This assembler language entry point is invoked by card services when a registered event occurs. It sets up the data segment and calls the C routine to service the callback.

public callback_handler
begin
    get event number and socket number
    call service_callback
end

correct_card_id

This routine passes the tuple data to determine if the card in question is one of the IBM PCMCIA Data/FAX Modem cards.

BOOL correct_card_id(UCHAR far *dataP)

release_com_port

This function removes the I/O address from the BIOS data area.

void release_com_port(USHORT ioaddress)
begin
    point to BIOS data area
    remove IO address that was in use
    decrement number of RS232 devices in BIOS data area
end

store_config_info

This function checks the syntax of the command line arguments and stores configuration information. The parameter 'argc' contains the number of arguments on the command line. The parameter 'argv' contains a pointer to an array of pointers to null terminated ASCII strings containing the arguments. The function returns 0 if successful. Otherwise, a value less than 0 is returned, indicating the error condition.

short store_config_info(short argc, char far * far *argv)
begin
    initialize default settings for modem (Intel compatible,
    ISA bus) parse command line and determine COM port
    settings if error parsing arguments
      fail to install
end

store_socket_assignments

This function stores the I/O address, the IRQ number, and the COM port number. This information is found in the socket assignment string. The parameter 'strP' contains a pointer to a null terminated string containing the socket assignment information. The parameter 'io_addressP' is the address of an array containing i/o addresses for the present configuration. The parameter 'irq_numP' is the address of an array containing the IRQ numbers for the present configuration. The parameter ' num_of_io_addresses' contains the number of I/O addresses for the present configuration. The function returns 0 if successful. Otherwise, a value less than 0 is returned, indicating the error condition.

static short store_socket_assignments
                 (char far *strP,
                 USHORT far *io_addressP,
                 USHORT far *irq_numP,
                 USHORT num_of_io_addresses)

make_flat_address

This function makes a flat address out of a segmented address. The parameters 'segment' and 'offset' contain the segmented address. The function returns the flat address.

static ULONG make_flat_address(USHORT segment, USHORT offset)

do_card_services

This function enables sockets and cards using Card Services.

static void short do_card_services(void)
begin
       get the number of sockets
       go through sockets - if there's an assignment for a
       socket and no card present, then report the error
       register as client
       return
end

cs_is_modem_card

This function determines if a modem card is present in a particular socket. The parameter 'socket_num' contains the number of the socket to check. The function returns the value TRUE if a modem card is present. Otherwise, the value FALSE is returned if a modem card is not present or if an error occurred.

static BOOL cs_is_modem_card(USHORT socket_num)
begin
        set up socket number
        set up attributes
        set up to look for  first tuple
        get segment and offset of packet
        get size of packet
        set up codes for get first tuple
        set up segment and offset of packet
        set up size of packet
        set up client handle
        make the call
        return value for false if carry flag set
        set up socket number
        set up attributes
        set up desired tuple code value
        set up data flags
        set up link state information
        set up cis state information
        set up offset into tuple from link byte
        set up maximum size of tuple data area
        get segment and offset of packet
        get size of packet
        set up codes for get tuple data
        set up segment and offset of packet
        set up size of packet
        set up client handle
        make the call
        return value for false if carry flag set
        return value for false if unexpected tuple contents
        return value for true
end

cs_acquire_resource

This function acquires resources and performs initialization activities on both the PCIC and the PCMCIA card. The parameter 'socket_num' contains the socket to initialize. The parameters 'io_address' and 'irq_num' contain the I/O address and the interrupt request number to assign to the socket. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.

static short cs_acquire_resource(USHORT socket_num,
                                 USHORT io_address,
                                 USHORT irq_num)
begin
       request the interrupt request number
       return error code if unsuccessful
       request io address
       release irq and return error code if unsuccessful
       request configuration
       release irq and io address and return error code
         if unsuccessful
       return successful code
end

cs_request_io

This function requests from card services that a particular I/O address be assigned to a socket. The parameters 'socket_num' and 'io_ address' contain the socket number and I/O address. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.

static short cs_request_io(USHORT socket_num, USHORT io_address)
begin
       set up logical socket
       set up base address for ports
       set up range for ports
       set up attributes
       specify that the addresses are not shared with another
          client
       set up additional port info - no additional ports
          specified
       set up addr line info - specify no additional addresses
          need to marked as used
       set up access speed - specify access speed of 100 nsec
          for ports
       get segment and offset for packet
       get size of packet
       set up codes for request io
       set up segment and offset for packet
       set up size of packet
       set up client handle
       make the call
       return error code if carry flag set
       return successful code
end

cs_request_irq

This function requests from card services that a particular interrupt be assigned to a socket. The parameter 'socket_num' is the socket number, and the parameter 'irq_num' is the interrupt number. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.

static short cs_request_irq(USHORT socket_num, USHORT irq_num)
begin
       set up logical socket number
       set up attributes - prefer exclusive irq
       set up for level interrupt and make second info
          field valid
       designate desired irq number
       get segment and offset for packet
       get size of packet
       set codes for request irq
       set segment and offset for packet
       set size of packet
       set client handle
       make the call
       return error code if carry flag set
       return error code if irq number was not assigned
       return successful code
end

cs_request_configuration

This function requests from card services that a particular I/O address be assigned to a socket. The parameter 'socket_num' is the socket number and the parameter 'io_address' is the I/O address. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.

static short cs_request_configuration(USHORT socket_num,
                                      USHORT io_address)
begin
      set up socket number
      set up exclusive use and enable irq
      set up for 5.0 volts (50 x 0.1)
      set vpp - no requirements
      set up option configuration register for normal operation,
          card enable, and designated com port
      set option register value
      set pin register value
      set copy register value
      set status register value - enable audio and ring indicate
      set which registers are present - option & status regs are
          present
      set up base address of config registers in attribute
          memory
      set up interface type - memory and I/O
      get segment and offset for packet
      get size of packet
      set code for request configuration
      set segment and offset for request configuration
      set size of packet
      set client handle
      make the call
      return error code if carry flag
      return successful code
end

cs_release_resource

This function requests from Card Services that resources be released for a particular socket. The parameter 'socket_num' is the socket number of the socket from which resources are to be released. The parameter 'io_address' and 'irq_num' are the I/O address and interrupt number to release. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.

static short cs_release_resource(USHORT socket_num,
                                 USHORT io_address,
                                 USHORT irq_num)
begin
      release configuration
      return error code if unsuccessful
      release interrupt
      return error code if unsuccessful
      release io address
      return error code if unsuccessful
      return successful code
end

cs_release_irq

This function requests from card services that an interrupt number be released for a particular socket. The parameters 'socket_num' and 'irq_num' are the socket number and interrupt number. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.

static short cs_release_irq(USHORT socket_num, USHORT irq_num)
begin
      set up logical socket number
      set attributes - prefer exclusive irq
      set up info - level interrupt and make second info field
         valid
      set up additional info - designate desired irq number
      set up irq number - designate previously established irq
      get segment and offset for packet
      get size of packet
      set code for release irq
      set segment and offset for packet
      set size of packet
      set client handle
      make the call
      return error code if carry flag
      return successful code
end

cs_release_io

This function requests from card services that an I/O address be released for a socket. The parameters 'socket_num' and 'io_address' are the socket number and I/O address. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.

static short cs_release_io(USHORT socket_num, USHORT io_address)
begin
      set up logical socket
      set up base address for ports
      set up range for ports
      set attributes - specify addr not shared with other
         clients
      set additional port info - no additional ports
         specified
      set addr line info - no additional addr need to
         marked in use
      set access speed - specify that access speed for
         ports is 100 nsec
      get segment and offset for packet
      get size of packet
      set codes for release io
      set segment and offset for packet
      set size of packet
      set client handle
      make the call
      return successful code
end

cs_release_configuration

This function requests from card services that a configuration be released for a socket. The parameter 'socket_num' is the socket number. The function returns the value -1 if an error occurred. Otherwise, the value 0 is returned.

static short cs_release_configuration(USHORT socket_num)
begin
      set up logical socket
      get segment and offset for packet
      get size of packet
      set codes for release configuration
      set segment and offset for packet
      set size of packet
      set client handle
      make the call
      return error code if carry flag
      return successful flag
end

cs_services_present

This function determines if card services is present on the system. The function returns the value TRUE if card services is present. Otherwise, the value FALSE is returned.

BOOL cs_services_present(void)
begin
        init signature field
        set max length for vendor string 
         get   PCMCIA Card Services for OS/2 info
         get   segment and offset of packet
         get   size of packet
         set   up codes for get PCMCIA Card Services for OS/2 information 
         set   up segment and offset of packet
         set   up size of packet
         make  the call 
         return  false value if carry flag
         store   number of sockets
         if   PCMCIA Card Services for OS/2 are present then return
           true value 
         return false value
end 

cs_register_client

This function registers as a client with card services. It returns an error code in parameter 'statusP' if an error occurs. In addition, as a return value, the function returns the value 0 if successful. Otherwise, the function returns the value -1.

short cs_register_client(USHORT *status)
begin
        set up attributes - memory client device driver -
            generate artificial insertion events
        set up event mask - global notification of insertion
            & ejection events
        set up data client receives on callback
        set up segment and offset of client data area
        set up reserved field
        get segment and offset of packet
        get segment and offset of callback handler routine
        set up size of packet
        set up codes for register client
        set up segment and offset of packet
        set up size of packet
        set up segment and offset of callback handler routine
        make the call
        return error code if carry flag
        store client handle
        return successful code
end

cs_card_present

This function determines if a card is present in a particular socket. The parameter 'socket_num' contains the socket to check for a card. It returns the value TRUE if a card is present. Otherwise, it returns the value FALSE.

BOOL cs_card_present(USHORT socket_num)
begin
        set up socket number
        get segment and offset
        get size of packet
        set up codes for get status
        set up segment and offset for packet
        set up size of packet
        make the call
        check carry flag for error
        return true if card present bit is set or false
          if clear
        return false value if error occurred
end

cs_get_num_of_sockets

This function reports the number of sockets present in the system. The function returns the number of sockets.

USHORT cs_get_num_of_sockets(void)
begin
        return the number of sockets
end

Dependencies and Restrictions

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