pcmcia-prog

pcmcia source code

  every last bit.

  The ValidateCIS call checks to see if a card has a reasonable CIS.
  The GetFirstTuple and GetNextTuple calls are used to step through CIS
  tuple lists.  GetTupleData extracts data bytes from a tuple.  And
  ParseTuple unpacks most tuple types into more easily used forms.
  Finally, the ReplaceCIS call allows a client to provide Card Services
  with a substitute for the CIS found on the card.

  33..44..11..  GGeettFFiirrssttTTuuppllee,, GGeettNNeexxttTTuuppllee

       #include "cistpl.h"

       int CardServices(GetFirstTuple, client_handle_t client, tuple_t *tuple);
       int CardServices(GetNextTuple, client_handle_t client, tuple_t *tuple);

  The tuple_t data structure is given by:

       typedef struct tuple_t {
               u_int           Attributes;
               cis_data_t      DesiredTuple;
               u_int           Flags;
               cisdata_t       TupleCode;
               u_int           TupleLink;
               cisdata_t       TupleOffset;
               cisdata_t       TupleDataMax;
               cisdata_t       TupleDataLen;
               cisdata_t       *TupleData;
       } tuple_t;

  GetFirstTuple searches a card's CIS for the first tuple code matching
  DesiredTuple.  The special code RETURN_FIRST_TUPLE will match the
  first tuple of any kind.  If successful, TupleCode is set to the code
  of the first matching tuple found, and TupleLink is the address of
  this tuple in attribute memory.

  GetNextTuple is like GetFirstTuple, except that given a tuple_t
  structure returned by a previous call to GetFirstTuple or
  GetNextTuple, it will return the next tuple matching DesiredTuple.

  These functions will automatically traverse any link tuples found in
  the CIS.  For multifunction cards having a CISTPL_LONGLINK_MFC tuple,
  these functions will automatically follow just the CIS chain specific
  to a client driver's assigned function.  If a client was bound to
  BIND_FN_ALL, then all tuples will be returned.

  The following flags can be specified in Attributes:

     TUPLE_RETURN_LINK
        Indicates that link tuples (CISTPL_LONGLINK_A,
        CISTPL_LONGLINK_C, CISTPL_LONGLINK_MFC, CISTPL_NOLINK,
        CISTPL_LINKTARGET) should be returned.  Normally these tuples
        are processed silently.

     TUPLE_RETURN_COMMON
        Indicates that tuples in the ``common'' CIS section of a
        multifunction CIS should be returned.  In the absence of this
        flag, normally, Card Services will only return tuples specific
        to the function bound to the client.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_OUT_OF_RESOURCE
        Card Services was unable to set up a memory window to map the
        card's CIS.

     CS_NO_MORE_ITEMS
        There were no tuples matching DesiredTuple.

  33..44..22..  GGeettTTuupplleeDDaattaa

       #include "cistpl.h"

       int CardServices(GetTupleData, client_handle_t client, tuple_t *tuple);

  GetTupleData extracts a series of data bytes from the specified tuple,
  which must have been returned by a previous call to GetFirstTuple or
  GetNextTuple.  A maximum of TupleDataMax bytes will be copied into the
  TupleData buffer, starting at an offset of TupleOffset bytes.  The
  number of bytes copied is returned in TupleDataLen.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_OUT_OF_RESOURCE
        Card Services was unable to set up a memory window to map the
        card's CIS.

     CS_NO_MORE_ITEMS
        The tuple does not contain any more data.  TuppleOffset is
        greater than or equal to the length of the tuple.

  33..44..33..  PPaarrsseeTTuuppllee

       #include "cistpl.h"

       int CardServices(ParseTuple, client_handle_t client, tuple_t *tuple, cisparse_t *parse);

  The cisparse_t data structure is given by:

  typedef union cisparse_t {
          cistpl_device_t         device;
          cistpl_checksum_t       checksum;
          cistpl_longlink_t       longlink;
          cistpl_longlink_mfc_t   longlink_mfc;
          cistpl_vers_1_t         version_1;
          cistpl_altstr_t         altstr;
          cistpl_jedec_t          jedec;
          cistpl_manfid_t         manfid;
          cistpl_funcid_t         funcid;
          cistpl_config_t         config;
          cistpl_cftable_entry_t  cftable_entry;
          cistpl_device_geo_t     device_geo;
          cistpl_vers_2_t         version_2;
          cistpl_org_t            org;
          cistpl_format_t         format;
  } cisparse_t;

  ParseTuple interprets tuple data returned by a previous call to
  GetTupleData.  The structure returned depends on the type of the
  parsed tuple.  See the cistpl.h file for these structure definitions;
  some of them are quite complex.

  Return codes:

     CS_BAD_TUPLE
        An error was encounted during parsing of this tuple.  The tuple
        may be incomplete, or may be formatted incorrectly.

     CS_UNSUPPORTED_FUNCTION
        ParseTuple cannot parse the specified tuple type.

  33..44..44..  VVaalliiddaatteeCCIISS

       int CardServices(ValidateCIS, client_handle_t client, cisinfo_t *cisinfo);

  The cisinfo_t structure is given by:

       typedef struct cisinfo_t {
               u_int           Chains;
       } cisinfo_t;

  ValidateCIS attempts to verify that a card has a reasonable Card
  Information Structure.  It returns the number of tuples found in
  Chains.  If the CIS appears to be uninterpretable, Chains will be set
  to 0.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_OUT_OF_RESOURCE
        Card Services was unable to set up a memory window to map the
        card's CIS.

  33..44..55..  RReeppllaacceeCCIISS

       int CardServices(ReplaceCIS, client_handle_t client, cisdump_t *cisinfo);

  The cisdump_t structure is given by:

       typedef struct cisdump_t {
               u_int           Length;
               cisdata_t       Data[CISTPL_MAX_CIS_SIZE];
       } cisinfo_t;

  ReplaceCIS allows a client to pass Card Services a replacement for the
  CIS found on a card.  Its intended application is for cards with
  incomplete or inaccurate CIS information.  If a correct CIS can be
  deduced from other information available for the card, this allows
  that information to be provided to clients in a clean fashion.  The
  alternative is to pollute client source code with fixes targeted for
  each card with a CIS error.  The replacement CIS remains in effect
  until the card is ejected, and all tuple-related services will use the
  replacement instead of the card's actual CIS.

  The Length field gives the number of bytes of CIS data in the Data
  array.  The Data array can be considered to be just the even bytes of
  a card's attribute memory.  It should contain all required features of
  a normal CIS, including an initial CISTPL_DEVICE tuple and a final
  CISTPL_END tuple.  Long links (including CISTPL_LONGLINK_MFC) may be
  used: all target addresses are interpreted in the replacement CIS
  space.  In general, a replacement CIS should also contain the same
  basic identification tuples (CISTPL_MANFID, CISTPL_VERS_1) as the
  original card.

  This service was added in release 3.0.1.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_OUT_OF_RESOURCE
        Card Services was unable to allocate memory to hold the
        replacement CIS.

  33..55..  MMeemmoorryy wwiinnddooww ccoonnttrrooll

  Each socket can have up to four active memory windows, mapping
  portions of card memory into the host system address space.  A PC Card
  device can address at most 16MB of both common and attribute memory.
  Windows should typically be sized to a power of two.  Depending on
  socket capabilities, they may need to be aligned on a boundary that is
  a multiple of the window size in both the host and card address
  spaces.

  A memory window is initialized by a call to RequestWindow.  Some
  window attributes can be modified using ModifyWindow.  The segment of
  card memory mapped to the window can be modified using MapMemPage.
  And windows are released with ReleaseWindow.  Unlike almost all other
  Card Services subfunctions, the memory window functions normally act
  on window_handle_t handles, rather than client_handle_t handles.

  33..55..11..  RReeqquueessttWWiinnddooww

       int CardServices(RequestWindow, client_handle_t *handle, win_req_t *req);

  The win_req_t structure is given by:

       typedef struct win_req_t {
               u_int           Attributes;
               u_long          Base;
               u_int           Size;
               u_int           AccessSpeed;
       } win_req_t;

  RequestWindow maps a window of card memory into system memory.  On
  entry, the handle parameter should point to a valid client handle.  On
  return, this will be replaced by a window_handle_t handle that should
  be used in subsequent calls to ModifyWindow, MapMemPage, and
  ReleaseWindow.

  The following flags can be specified in Attributes:

     WIN_MEMORY_TYPE
        This field can be either WIN_MEMORY_TYPE_CM for common memory,
        or WIN_MEMORY_TYPE_AM for attribute memory.

     WIN_DATA_WIDTH
        Either WIN_DATA_WIDTH_16 for 16-bit accesses, or
        WIN_DATA_WIDTH_8 for 8-bit access.

     WIN_ENABLE
        If this is set, the window is turned on.

     WIN_USE_WAIT
        Specifies that the controller should observe the card's MWAIT
        signal.

     WIN_MAP_BELOW_1MB
        Requests that the window be mapped below the 1MB address
        boundary.  This may not be possible on some platforms.

     WIN_STRICT_ALIGN
        Requests that the window base be aligned to a multiple of the
        window size.  Added in release 3.1.2.

  Base specifies the base physical address of the window in system
  memory.  If zero, Card Services will set Base to the first available
  window address.  Size specifies the window size in bytes.  If zero,
  Card Services will set Size to the smallest window size supported by
  the host controller.  AccessSpeed specifies the memory access speed,
  in nanoseconds.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_NO_CARD
        The socket assigned to this client is currently vacant.

     CS_BAD_ATTRIBUTE
        An unsupported window attribute was requested.

     CS_OUT_OF_RESOURCE
        The maximum number of memory windows for this socket are already
        being used.

     CS_IN_USE
        RequestWindow was unable to find a free window of system memory.

     CS_BAD_SIZE
        ,

     CS_BAD_BASE
        Either Base or Size does not satisfy the alignment rules for
        this socket.

  33..55..22..  MMooddiiffyyWWiinnddooww

       int CardServices(ModifyWindow, window_handle_t handle, modwin_t *mod);

  The modwin_t structure is given by:

       typedef struct modwin_t {
               u_int           Attributes;
               u_int           AccessSpeed;
       } modwin_t;

  ModifyWindow modifies the attributes of a window handle returned by a
  previous call to RequestWindow.  The following attributes can be
  changed:

     WIN_MEMORY_TYPE
        This field can be either WIN_MEMORY_TYPE_CM for common memory,
        or WIN_MEMORY_TYPE_AM for attribute memory.

     WIN_DATA_WIDTH
        Either WIN_DATA_WIDTH_16 for 16-bit accesses, or
        WIN_DATA_WIDTH_8 for 8-bit access.

     WIN_ENABLE
        If this is set, the window is turned on.

  AccessSpeed gives the new memory access speed, in nanoseconds.

  Return codes:

     CS_BAD_HANDLE
        The window handle is invalid.

  33..55..33..  RReelleeaasseeWWiinnddooww

       int CardServices(ReleaseWindow, window_handle_t handle);

  ReleaseWindow releases a memory window previously allocated with
  RequestWindow.

  Return codes:

     CS_BAD_HANDLE
        The window handle is invalid.

  33..55..44..  GGeettFFiirrssttWWiinnddooww,, GGeettNNeexxttWWiinnddooww

       int CardServices(GetFirstWindow, client_handle_t *client, win_req_t *req);
       int CardServices(GetNextWindow, window_handle_t *handle, win_req_t *req);

  These calls sequentially retrieve window configuration information for
  all of a socket's memory windows.  GetFirstWindow replaces the client
  window handle with a memory window handle, which will in turn be
  updated by calls to GetNextWindow.

  These services were added in release 3.1.0.

  Return codes: