pcmcia-prog

pcmcia source code

  Linux PCMCIA Programmer's Guide
  David Hinds, [e-mail].
  v2.32, 19 July 2002

  This document describes how to write kernel device drivers for the
  Linux PCMCIA Card Services interface.  It also describes how to write
  user-mode utilities for communicating with Card Services.  The latest
  version of this document can always be found at <http://pcmcia-
  cs.sourceforge.net>.
  ______________________________________________________________________

  Table of Contents

  1. Introduction

     1.1 Copyright notice and disclaimer
     1.2 Acknowledgements

  2. Basic Concepts

     2.1 The socket interface
     2.2 The socket controller

  3. Card Services Subfunction Descriptions

     3.1 Client management functions
        3.1.1 RegisterClient
        3.1.2 DeregisterClient
        3.1.3 SetEventMask
        3.1.4 BindDevice
     3.2 Socket state control
        3.2.1 GetStatus
        3.2.2 ResetCard
        3.2.3 SuspendCard
        3.2.4 ResumeCard
        3.2.5 EjectCard
        3.2.6 InsertCard
     3.3 IO card configuration calls
        3.3.1 RequestIO
        3.3.2 ReleaseIO
        3.3.3 RequestIRQ
        3.3.4 ReleaseIRQ
        3.3.5 RequestConfiguration
        3.3.6 ModifyConfiguration
        3.3.7 ReleaseConfiguration
        3.3.8 GetConfigurationInfo
     3.4 Card Information Structure (CIS) calls
        3.4.1 GetFirstTuple, GetNextTuple
        3.4.2 GetTupleData
        3.4.3 ParseTuple
        3.4.4 ValidateCIS
        3.4.5 ReplaceCIS
     3.5 Memory window control
        3.5.1 RequestWindow
        3.5.2 ModifyWindow
        3.5.3 ReleaseWindow
        3.5.4 GetFirstWindow, GetNextWindow
        3.5.5 MapMemPage, GetMemPage
     3.6 Bulk Memory Services
        3.6.1 RegisterMTD
        3.6.2 GetFirstRegion, GetNextRegion
        3.6.3 OpenMemory
        3.6.4 CloseMemory
        3.6.5 ReadMemory, WriteMemory
        3.6.6 RegisterEraseQueue
        3.6.7 DeregisterEraseQueue
        3.6.8 CheckEraseQueue
     3.7 Miscellaneous calls
        3.7.1 GetCardServicesInfo
        3.7.2 AccessConfigurationRegister
        3.7.3 AdjustResourceInfo
        3.7.4 ReportError

  4. Card Information Structure Definitions

     4.1 CIS Tuple Definitions
        4.1.1 CISTPL_CHECKSUM
        4.1.2 CISTPL_LONGLINK_A, CISTPL_LONGLINK_C, CISTPL_LINKTARGET, CISTPL_NOLINK
        4.1.3 CISTPL_LONGLINK_MFC
        4.1.4 CISTPL_DEVICE, CISTPL_DEVICE_A
        4.1.5 CISTPL_VERS_1
        4.1.6 CISTPL_ALTSTR
        4.1.7 CISTPL_JEDEC_C, CISTPL_JEDEC_A
        4.1.8 CISTPL_CONFIG, CISTPL_CONFIG_CB
        4.1.9 CISTPL_BAR
        4.1.10 CISTPL_CFTABLE_ENTRY
        4.1.11 CISTPL_CFTABLE_ENTRY_CB
        4.1.12 CISTPL_MANFID
        4.1.13 CISTPL_FUNCID
        4.1.14 CISTPL_DEVICE_GEO
        4.1.15 CISTPL_VERS_2
        4.1.16 CISTPL_ORG
        4.1.17 CISTPL_FORMAT
     4.2 CIS configuration register definitions
        4.2.1 Configuration Option Register
        4.2.2 Card Configuration and Status Register
        4.2.3 Pin Replacement Register
        4.2.4 Socket and Copy Register
        4.2.5 Extended Status Register
        4.2.6 IO Base and Size Registers

  5. Card Services Event Handling

     5.1 Event handler operations
     5.2 Event descriptions
     5.3 Client driver event handling responsibilities

  6. Memory Technology Drivers

     6.1 MTD request handling
     6.2 MTD helper functions
        6.2.1 MTDRequestWindow, MTDReleaseWindow
        6.2.2 MTDModifyWindow
        6.2.3 MTDSetVpp
        6.2.4 MTDRDYMask

  7. Driver Services Interface

     7.1 Interface to other client drivers
        7.1.1 The dev_link_t structure
        7.1.2 register_pccard_driver
        7.1.3 unregister_pccard_driver
     7.2 The CardBus client interface
        7.2.1 register_driver
        7.2.2 unregister_driver
        7.2.3 The driver_operations entry points
     7.3 Interface to user mode utilities
        7.3.1 Card Services event notifications
        7.3.2 Ioctl descriptions

  8. Anatomy of a Card Services Client Driver

     8.1 Module initialization and cleanup
     8.2 The *_attach() and *_detach() functions
     8.3 The *_config() and *_release() functions
     8.4 The client event handler
     8.5 Locking and synchronization issues
     8.6 Using existing Linux drivers to access PC Card devices

  9. The Socket Driver Layer

     9.1 Card Services entry points for socket drivers
     9.2 Services provided by the socket driver
        9.2.1 SS_InquireSocket
        9.2.2 SS_RegisterCallback
        9.2.3 SS_GetStatus
        9.2.4 SS_GetSocket, SS_SetSocket
        9.2.5 SS_GetIOMap, SS_SetIOMap
        9.2.6 SS_GetMemMap, SS_SetMemMap
        9.2.7 SS_GetBridge, SS_SetBridge
        9.2.8 SS_ProcSetup
     9.3 Supporting unusual socket architectures

  10. Where to Go for More Information

  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  The Linux kernel PCMCIA system has three main components.  At the
  lowest level are the socket drivers.  Next is the Card Services
  module.  Drivers for specific cards are layered on top of Card
  Services.  One special Card Services client, called Driver Services,
  provides a link betweek user level utility programs and the kernel
  facilities.

  The socket driver layer is loosely based on the Socket Services API.
  There are two socket driver modules.  The tcic module supports the
  Databook TCIC-2 family of host controllers.  The i82365 module
  supports the Intel i82365sl family and various Intel-compatible
  controllers, including Cirrus, VLSI, Ricoh, and Vadem chips.  In
  addition, the i82365 module implements support for CardBus controllers
  that follow the ``Yenta'' register-level specification.

  Card Services is the largest single component of the package.  It
  provides an API somewhat similar to DOS Card Services, adapted to a
  Unix environment.  The Linux implementation was based in part on the
  Solaris interface specification.  It is implemented in the pcmcia_core
  module.  Most version 2.1 features are implemented, with some PC Card
  95 features.

  The Driver Services layer implements a user mode pseudo-device for
  accessing some Card Services functions from utility programs.  It is
  responsible for keeping track of all client drivers, and for matching
  up drivers with physical sockets.  It is implemented in the ds module.

  This document describes the kernel interface to the Card Services and
  Driver Services modules, and the user interface to Driver Services.
  It is intended for use by client device driver developers.  The Linux
  PCMCIA-HOWTO describes how to install and use Linux PCMCIA support.
  It is available from  <http://pcmcia-cs.sourceforge.net>.

  11..11..  CCooppyyrriigghhtt nnoottiiccee aanndd ddiissccllaaiimmeerr

  Copyright (c) 1996-2002 David A. Hinds

  This document may be reproduced or distributed in any form without my
  prior permission.  Modified versions of this document, including
  translations into other languages, may be freely distributed, provided
  that they are clearly identified as such, and this copyright is
  included intact.

  This document may be included in commercial distributions without my
  prior consent.  While it is not required, I would like to be informed
  of such usage.  If you intend to incorporate this document in a
  published work, please contact me to make sure you have the latest
  available version.
  This document is provided ``AS IS'', with no express or implied
  warranties.  Use the information in this document at your own risk.

  11..22..  AAcckknnoowwlleeddggeemmeennttss

  I'd like to thank all the Linux users who have helped test and debug
  this software, and who have helped with driver development.  I should
  also thank Linus Torvalds, Donald Becker, Alan Cox, and Bjorn Ekwall
  for Linux kernel development help.  I'm especially grateful to Michael
  Bender for many helpful discussions about the Solaris implementation.

  22..  BBaassiicc CCoonncceeppttss

  22..11..  TThhee ssoocckkeett iinntteerrffaaccee

  The PC Card bus has two basic operating modes: ``memory-only'' and
  ``memory and IO''.  The first mode was defined by the original Version
  1.0 specification and only supports simple memory cards.  The second
  mode, defined in Version 2.0, redefines a few of the memory card
  control signals to support IO port addressing and IO interrupt
  signalling.

  PC Card devices have two memory spaces: ``attribute memory'' and
  ``common memory''.  The interface can address up to 16MB of each type
  of memory.  Attribute memory is typically used for holding descriptive
  information and configuration registers.  Common memory may include
  the bulk storage of a memory card, or device buffers in the case of IO
  cards.  All cards that are compliant with the version 2.0 PC Card
  specification should have a Card Information Structure (or ``CIS'') in
  attribute memory, which describes the card and how it should be
  configured.

  Separate control signals allow cards to signal their operating status
  to the host.  These signals include card detect, ready/busy, write
  protect, battery low, and battery dead.

  The ``memory and IO'' interface mode allows cards to address up to 64K
  of IO ports.  It also allows cards to signal IO interrupts, and routes
  one card output to the host system's speaker.  In this mode, several
  of the memory card control signals are unavailable because those pins
  are used to carry the extra IO card signals.  On some cards, these
  signals can instead be read from a special configuration register in
  attribute memory, the ``Pin Replacement Register''.

  22..22..  TThhee ssoocckkeett ccoonnttrroolllleerr

  The socket controller serves as a bridge between PC Card devices and
  the system bus.  There are several varieties of controllers, but all
  share the same basic functionality.  The Socket Services software
  layer takes care of all the details of how to program the host
  controller.

  The socket controller has the job of mapping windows of addresses in
  the host memory and IO spaces to windows of addresses in card space.
  All supported controllers support at least four independent memory
  windows and two IO windows per socket.

  Each memory window is defined by a base address in the host address
  space, a base address in the card address space, and a window size.
  Some controllers differ in their alignment rules for memory windows,
  but all controllers will support windows whose size is at least 4K and
  also a power of two, and where the base address is a multiple of the
  window size.  Each window can be programmed to point to either
  attribute or common memory.

  IO windows differ from memory windows in that host addresses that fall
  within an IO window are not modified before they are passed on to an
  IO card.  Effectively, the base addresses of the window in the host
  and card address spaces are always equal.  IO windows also have no
  alignment or size restrictions; an IO window can start and end on any
  byte boundary in the 64K IO address space.

  The PC Card bus defines a single interrupt signal from the card to the
  controller.  The controller then has the responsibility of steering
  this interrupt to an appropriate interrupt request (``irq'') line.
  All controllers support steering card IO interrupts to essentially any
  free interrupt line.  Because steering happens in the controller, the
  card itself is unaware of which interrupt it uses.

  All PC Card controllers can generate interrupts in response to card
  status changes.  These interrupts are distinct from the IO interrupts
  generated by an IO card, and use a separate interrupt line.  Signals
  that can generate interrupts include card detect, ready/busy, write
  protect, battery low, and battery dead.

  33..  CCaarrdd SSeerrvviicceess SSuubbffuunnccttiioonn DDeessccrriippttiioonnss

  Card Services calls have the general form:

       #include "cs_types.h"
       #include "cs.h"

       int CardServices(int subfunc, void *arg1, void *arg2, ...);

  Some Card Services functions require additional #include statements.
  The particular subfunction determines the number of expected
  arguments.  A return code of CS_SUCCESS indicates that a call
  succeeded.  Other return codes indicate errors.

  33..11..  CClliieenntt mmaannaaggeemmeenntt ffuunnccttiioonnss

  Device drivers that use Card Services functions are called
  ``clients''.  A device driver should use the RegisterClient call to
  get a client handle before using other services.  Most Card Services
  functions will take this client handle as an argument.  Before
  unloading, drivers should also unregister with DeregisterClient.

  33..11..11..  RReeggiisstteerrCClliieenntt

  int CardServices(RegisterClient, client_handle_t *client, client_reg_t *reg);

  The client_reg_t data structure is given by:

       typedef struct client_reg_t {
               dev_info_t      *dev_info;
               u_int           Attributes;
               u_int           EventMask;
               int             (*event_handler)(event_t event, int priority,
                                                event_callback_args_t *args);
               event_callback_args_t   event_callback_args;
               u_int           Version;
       } client_reg_t;

  RegisterClient establishes a link between a client driver and Card
  Services, and connects the client with an appropriate socket.  The
  dev_info parameter is used by Card Services to match the client with a
  socket and function; this correspondence is normally established by
  Driver Services via a call to BindDevice.  If successful, a client
  handle will be returned in client.

  The following flags can be specified in Attributes:

     INFO_MASTER_CLIENT
        For use only by the Driver Services client.  Among other things,
        specifies that this client should not be automatically unbound
        when a card is ejected from this socket.

     INFO_IO_CLIENT
        Specifies that this client is an IO card driver.

     INFO_MTD_CLIENT
        Specifies that this client is a Memory Technology Driver.

     INFO_MEM_CLIENT
        Specifies that this client is a memory card driver.

     INFO_CARD_SHARE