pcmcia-prog

pcmcia source code

        Included for compatibility, has no effect.

     INFO_CARD_EXCL
        Included for compatibility, has no effect.

  EventMask specifies what events this client should be notified of.
  The event_handler entry point will be called by Card Services when an
  event in EventMask is processed.  The event_handler_args structure is
  a template for the structure that will be passed to the event handler.
  The Version parameter identifies the Card Services version level that
  this driver expects; it is currently ignored.

  A driver should be prepared to handle Card Services events before
  calling RegisterClient.  This call will always generate a
  CS_REGISTRATION_COMPLETE event, and may also generate an artificial
  CS_CARD_INSERTION event if the socket is currently occupied.

  Return codes:

     CS_OUT_OF_RESOURCE
        An appropriate socket could not be found for this driver.
  33..11..22..  DDeerreeggiisstteerrCClliieenntt

       int CardServices(DeregisterClient, client_handle_t client);

  DeregisterClient severs the connection between a client and Card
  Services.  It should be called after the client has freed any
  resources it has allocated.  Once a connection is broken, it cannot be
  reestablished until after another call to BindDevice.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_IN_USE
        The client still has allocated resources, such as IO port
        windows or an interrupt, or the socket configuration is locked.

  33..11..33..  SSeettEEvveennttMMaasskk

       int CardServices(SetEventMask, client_handle_t client, eventmask_t *mask);

  The eventmask_t structure is given by:

       typedef struct eventmask_t {
               u_int           Attributes;
               u_int           EventMask;
       } eventmask_t;

  SetEventMask updates the mask that determines which events this client
  will be notified of.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

  33..11..44..  BBiinnddDDeevviiccee

       int CardServices(BindDevice, bind_req_t *req);

  The bind_req structure is given by:

  typedef struct bind_req_t {
          socket_t        Socket;
          u_char          Function;
          dev_info_t      *dev_info;
  } bind_req_t;

  BindDevice associates a device driver with a particular socket.  It is
  normally called by Driver Services after a newly inserted card has
  been identified.  Once a driver has been bound to a socket, it will be
  eligible to register as a client of that socket.  Note that this call
  does not take a client handle as an argument.  This is the only Card
  Services call that takes a socket number as an argument.

  The Function field specifies which function(s) of a multifunction card
  are to be bound to this driver.  Function numbers correspond to
  entries in the card's CISTPL_LONGLINK_MFC tuple.  If Function is set
  to BIND_FN_ALL, the driver will be bound to all card functions.  A
  driver will only be able to access CIS tuples corresponding to
  functions for which it is bound.

  Return codes:

     CS_BAD_SOCKET
        The specified socket number is invalid.

  33..22..  SSoocckkeett ssttaattee ccoonnttrrooll

  These functions are more or less concerned with getting and setting
  the current operating state of a socket.  GetStatus returns the
  current socket state.  ResetCard is used to send a hard reset signal
  to a socket.  SuspendCard and ResumeCard can be used to power down and
  power up a socket without releasing the drivers currently bound to
  that socket.  EjectCard and InsertCard essentially mimic real card
  ejection and insertion events.

  33..22..11..  GGeettSSttaattuuss

       int CardServices(GetStatus, client_handle_t client, cs_status_t *status);

  The cs_status_t data structure is given by:

       typedef struct cs_status_t {
               u_char          Function;
               u_int           CardState;
               u_int           SocketState;
       } cs_status_t;

  GetStatus returns the current status of a client's socket.  For cards
  that are configured in IO mode, GetStatus uses the Pin Replacement
  Register and Extended Status Register to determine the card status.
  For normal clients, the Function field is ignored, but for clients
  bound with BIND_FN_ALL, this field specifies the function whose
  configuration registers should be used to determine the socket state,
  if the socket is currently configured.  The following flags are
  defined in CardState:

     CS_EVENT_CARD_DETECT
        Specifies that the socket is occupied.

     CS_EVENT_CB_DETECT
        Specifies that the socket is occupied by a CardBus device.

     CS_EVENT_WRITE_PROTECT
        Specifies that the card is currently write protected.

     CS_EVENT_BATTERY_LOW
        Specifies that the card battery is low.

     CS_EVENT_BATTERY_DEAD
        Specifies that the card battery is dead.

     CS_EVENT_READY_CHANGE
        Specifies that the card is ready.

     CS_EVENT_PM_SUSPEND
        Specifies that the socket is suspended.

     CS_EVENT_REQUEST_ATTENTION
        Specifies that the request attention bit in the extended status
        register is set.

     CS_EVENT_CARD_INSERTION
        Specifies that a card insertion event is in progress.  An
        insertion event will be sent to the client when socket setup is
        complete.

     CS_EVENT_3VCARD
        Indicates that the card supports 3.3V operation.

     CS_EVENT_XVCARD
        Indicates that the card supports ``X.X''V operation.  The actual
        voltage is currently undefined in the specification.

  SocketState is currently unused, but in theory, it should latch
  changes in the state of the fields in CardState.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

  33..22..22..  RReesseettCCaarrdd

       int CardServices(ResetCard, client_handle_t client);

  ResetCard requests that a client's socket be reset.  When this call is
  made, Card Services sends all clients a CS_EVENT_RESET_REQUEST event.
  If any client rejects the request, Card Services sends the initiating
  client a CS_EVENT_RESET_COMPLETE event with event_callback_args.info
  set to the return code of the client that rejected the request.

  If all clients agree to the request, Card Services sends a
  CS_EVENT_RESET_PHYSICAL event, then resets the socket.  When the
  socket signals that it is ready, a CS_EVENT_CARD_RESET event is
  generated.  Finally, a CS_EVENT_RESET_COMPLETE event is sent to the
  initiating client, with event_callback_args.info set to zero.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_NO_CARD
        The socket assigned to this client is currently vacant.

     CS_IN_USE
        This socket is currently being reset.

  33..22..33..  SSuussppeennddCCaarrdd

       int CardServices(SuspendCard, client_handle_t client);

  Card Services sends all clients CS_EVENT_PM_SUSPEND events, then shuts
  down and turns off power to the socket.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_NO_CARD
        The socket assigned to this client is currently vacant.

     CS_IN_USE
        This socket is already suspended.

  33..22..44..  RReessuummeeCCaarrdd

       int CardServices(ResumeCard, client_handle_t client);

  After restoring power to the socket, Card Services will notify all
  clients with CS_EVENT_PM_RESUME events.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_NO_CARD
        The socket assigned to this client is currently vacant.

     CS_IN_USE
        This socket is not currently suspended.

  33..22..55..  EEjjeeccttCCaarrdd

       int CardServices(EjectCard, client_handle_t client);

  Card Services sends eject events to all clients, then shuts down and
  turns off power to the socket.  All clients except for Driver Services
  will be unlinked from the socket.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_NO_CARD
        The socket assigned to this client is currently vacant.

  33..22..66..  IInnsseerrttCCaarrdd

       int CardServices(InsertCard, client_handle_t client);

  Card Services sends insertion events to all clients of this socket
  (normally, only Driver Services).

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_NO_CARD
        The socket assigned to this client is currently vacant.

     CS_IN_USE
        The socket has already been configured.

  33..33..  IIOO ccaarrdd ccoonnffiigguurraattiioonn ccaallllss

  The normal order of events is for a driver to reserve IO ports and an
  interrupt line with calls to RequestIO and RequestIRQ, then to call
  RequestConfiguration to actually configure the socket.  If any of
  these calls fails, a driver should be sure to release any resources it
  successfully reserved.

  Multifunction cards can have separate configurations for each card
  function.  However, the configurations do need to be consistent with
  one another.  While each card function has its own set of
  configuration registers, each socket has only a single interrupt line
  and can only map two contiguous ranges of IO ports.

  CardBus cards are configured somewhat differently.  The RequestIO and
  RequestConfiguration calls have similar roles, however, Card Services
  takes responsibility for most of the configuration details, and the
  contents of the request structures are ignored.

  33..33..11..  RReeqquueessttIIOO

       int CardServices(RequestIO, client_handle_t client, io_req_t *req);

  The io_req_t data structure is given by:

       typedef struct io_req_t {
               ioaddr_t        BasePort1;
               ioaddr_t        NumPorts1;
               u_int           Attributes1;
               ioaddr_t        BasePort2;
               ioaddr_t        NumPorts2;
               u_int           Attributes2;
               u_int           IOAddrLines;
       } io_req_t;

  RequestIO reserves IO port windows for a card.  BasePort1 specifies
  the base IO port address of the window to be reserved.  If NumPorts2
  is non-zero, a second IO port window will also be reserved.
  IOAddrLines specifies the number of address lines that are actually
  decoded by the card.  The IO port allocation algorithm assumes that
  any alias of the requested address(es) that preserves the lower
  IOAddrLines bits will be acceptable, and will update BasePort1 and
  BasePort2 to reflect the address range(s) actually assigned.

  Prior to release 3.1.4, the IOAddrLines field was ignored.  The
  allocator always tried to assign the exact address range requested,
  unless the base address was zero; in that case, it would assign any
  available window aligned to the nearest power of two larger than the
  window size.  The new allocator verifies that the IOAddrLines
  parameter agrees with the requested window parameters, and defaults to
  the pre-3.1.4 behavior if an inconsistency is found.

  With multifunction cards, this call will allocate IO ports for each
  card function in such a way that all a card's ports can be mapped by
  the two low-level IO port windows associated with each physical
  socket.  For example, if the drivers for a hypothetical four-function
  card each attempt to allocate one IO window of 8 ports, Card Services
  will consolidate these into a single contiguous 32-port block.

  When this function is invoked by a CardBus client, the IO request
  structure is ignored.  Instead, Card Services examines the card and
  allocates any necessary system resources: this includes IO and memory
  space, as well as an interrupt, if needed.  One call will reserve all
  resources needed for all card functions, not just the function of the
  client making the call.

  This call does not actually configure a socket's IO windows: this is
  done by a subsequent call to RequestConfiguration.

  The following flags can be specified in Attributes1 and Attributes2:

     IO_DATA_PATH_WIDTH
        This field may either be IO_DATA_PATH_WIDTH_16 for 16-bit
        access, or IO_DATA_PATH_WIDTH_8 for 8-bit access, or
        IO_DATA_PATH_WIDTH_AUTO to dynamically size the bus based on the
        access size.

  Return codes:

     CS_BAD_HANDLE
        The client handle is invalid.

     CS_NO_CARD
        The socket assigned to this client is currently vacant.

     CS_IN_USE
        This socket's IO windows have already been reserved.

     CS_CONFIGURATION_LOCKED
        This socket's configuration has been locked by a call to
        RequestConfiguration.