drivers/staging/csr/sdioemb/sdio_api.h

   1 /*
   2  * SDIO device driver API.
   3  *
   4  * Copyright (C) 2007-2008 Cambridge Silicon Radio Ltd.
   5  *
   6  * Refer to LICENSE.txt included with this source code for details on
   7  * the license terms.
   8  */
   9 #ifndef _SDIO_API_H
  10 #define _SDIO_API_H
  11
  12 /**
  13  * @defgroup fdriver SDIO function driver API
  14  *
  15  * @brief The SDIO function driver API is used to implement drivers
  16  * for SDIO card functions.
  17  *
  18  * Function drivers register with the SDIO driver core
  19  * (sdio_register_driver()), listing which functions it supports and
  20  * providing callback functions for card inserts, removes and
  21  * interrupts.
  22  *
  23  * @par \anchor card_io_ops Card I/O operations:
  24  *
  25  * - \link sdioemb_read8(struct sdioemb_dev *, uint32_t, uint8_t *) sdioemb_read8()\endlink
  26  * - \link sdioemb_read16(struct sdioemb_dev *, uint32_t, uint16_t *) sdioemb_read16()\endlink
  27  * - \link sdioemb_write8(struct sdioemb_dev *, uint32_t, uint8_t) sdioemb_write8()\endlink
  28  * - \link sdioemb_write16(struct sdioemb_dev *, uint32_t, uint16_t) sdioemb_write16()\endlink
  29  * - \link sdioemb_f0_read8(struct sdioemb_dev *, uint32_t, uint8_t *) sdioemb_f0_read8()\endlink
  30  * - \link sdioemb_f0_write8(struct sdioemb_dev *, uint32_t, uint8_t) sdioemb_f0_write8()\endlink
  31  * - \link sdioemb_read(struct sdioemb_dev *, uint32_t, void *, size_t) sdioemb_read()\endlink
  32  * - \link sdioemb_write(struct sdioemb_dev *, uint32_t, const void *, size_t) sdioemb_write()\endlink
  33  */
  34
  35 struct sdioemb_func_driver;
  36 struct sdioemb_dev;
  37 struct sdioemb_dev_priv;
  38
  39 /**
  40  * An SDIO device.
  41  *
  42  * Each SDIO card will have an sdio_dev for each function.
  43  *
  44  * None of the fields (except for drv_data) should be written.
  45  *
  46  * @ingroup fdriver
  47  */
  48 struct sdioemb_dev {
  49     struct sdioemb_func_driver *driver;        /**< Function driver for this device. */
  50     uint16_t                 vendor_id;     /**< Vendor ID of the card. */
  51     uint16_t                 device_id;     /**< Device ID of the card. */
  52     int                      function;      /**< Function number of this device. */
  53     uint8_t                  interface;     /**< SDIO standard interface number. */
  54     uint16_t                 max_blocksize; /**< Maximum block size supported. */
  55     uint16_t                 blocksize;     /**< Blocksize in use. */
  56     int                      slot_id;       /**< ID of the slot this card is inserted into. */
  57     void *                   os_device;     /**< Pointer to an OS-specific device structure. */
  58     struct sdioemb_dev_priv *priv;          /**< Data private to the SDIO core. */
  59     void *                   drv_data;      /**< Data private to the function driver. */
  60 };
  61
  62 #define SDIOEMB_ANY_ID    0xffff
  63 #define SDIOEMB_UIF_FUNC  0
  64 #define SDIOEMB_ANY_FUNC  0xff
  65 #define SDIOEMB_ANY_IFACE 0xff
  66
  67 /**
  68  * An entry for an SDIO device ID table.
  69  *
  70  * Functions are matched to drivers using any combination of vendor
  71  * ID, device ID, function number or standard interface.
  72  *
  73  * Matching on #function == SDIOEMB_UIF_FUNC is reserved for the SDIO
  74  * Userspace Interface driver. Card management drivers can match on
  75  * #function == 0, these will be probed before any function drivers.
  76  *
  77  * @ingroup fdriver
  78  */
  79 struct sdioemb_id_table {
  80     uint16_t vendor_id; /**< Vendor ID to match or SDIOEMB_ANY_ID */
  81     uint16_t device_id; /**< Device ID to match or SDIOEMB_ANY_ID */
  82     int      function;  /**< Function number to match or SDIOEMB_ANY_FUNC */
  83     uint8_t  interface; /**< SDIO standard interface to match or SDIOEMB_ANY_IFACE */
  84 };
  85
  86 /**
  87  * A driver for an SDIO function.
  88  *
  89  * @ingroup fdriver
  90  */
  91 struct sdioemb_func_driver {
  92     /**
  93      * Driver name used in diagnostics.
  94      */
  95     const char *name;
  96
  97     /**
  98      * 0 terminated array of functions supported by this device.
  99      *
 100      * The driver may (for example) match on a number of vendor
 101      * ID/device ID/function number triplets or on an SDIO standard
 102      * interface.
 103      */
 104     struct sdioemb_id_table *id_table;
 105
 106     /**
 107      * Called by the core when an inserted card has functions which
 108      * match those listed in id_table.
 109      *
 110      * The driver's implementation should (if required):
 111      *
 112      *   - perform any additional probing
 113      *   - do function specific initialization
 114      *   - allocate and register any function/OS specific devices or interfaces.
 115      *
 116      * Called in: thread context.
 117      *
 118      * @param fdev the newly inserted device.
 119      *
 120      * @return 0 on success; -ve on error.
 121      */
 122     int (*probe)(struct sdioemb_dev *fdev);
 123
 124     /**
 125      * Called by the core when a card is removed.  This is only called
 126      * if the probe() call succeeded.
 127      *
 128      * The driver's implementation should (if required);
 129      *
 130      *   - do any function specific shutdown.
 131      *   - cleanup any data structures created/registers during probe().
 132      *
 133      * Called in: thread context.
 134      *
 135      * @param fdev the device being removed.
 136      */
 137     void (*remove)(struct sdioemb_dev *fdev);
 138
 139     /**
 140      * Called by the core to signal an SDIO interrupt for this card
 141      * occurs, if interrupts have been enabled with
 142      * sdioemb_interrupt_enable().
 143      *
 144      * The driver's implementation should signal a thread (or similar)
 145      * to actually handle the interrupt as no card I/O may be
 146      * performed whilst in interrupt context. When the interrupt is
 147      * handled, the driver should call sdioemb_interrupt_acknowledge() to
 148      * enable further interrupts to be signalled.
 149      *
 150      * Called in: interrupt context.
 151      *
 152      * @param fdev the device which may have raised the interrupt.
 153      */
 154     void (*card_int_handler)(struct sdioemb_dev *fdev);
 155
 156     /**
 157      * Called by the core to signal a suspend power management
 158      * event occured.
 159      *
 160      * The driver's implementation should (if required)
 161      * set the card to a low power mode and return as soon
 162      * as possible. After this function returns, the
 163      * driver should not start any SDIO commands.
 164      *
 165      * Called in: thread context.
 166      *
 167      * @param fdev the device handler.
 168      */
 169     void (*suspend)(struct sdioemb_dev *fdev);
 170
 171     /**
 172      * Called by the core to signal a resume power management
 173      * event occured.
 174      *
 175      * The driver's implementation should (if required)
 176      * initialise the card to an operational mode and return
 177      * as soon as possible. If the card has been powered off
 178      * during suspend, the driver would have to initialise
 179      * the card from scratch (f/w download, h/w initialisation, etc.).
 180      *
 181      * Called in: thread context.
 182      *
 183      * @param fdev the device handler.
 184      */
 185     void (*resume)(struct sdioemb_dev *fdev);
 186 };
 187
 188 int  sdioemb_driver_register(struct sdioemb_func_driver *fdriver);
 189 void sdioemb_driver_unregister(struct sdioemb_func_driver *fdriver);
 190
 191 int sdioemb_driver_probe(struct sdioemb_func_driver *fdriver, struct sdioemb_dev *fdev);
 192 void sdioemb_driver_remove(struct sdioemb_func_driver *fdriver, struct sdioemb_dev *fdev);
 193
 194 /* For backward compatibility. */
 195 #define sdio_register_driver sdioemb_driver_register
 196 #define sdio_unregister_driver sdioemb_driver_unregister
 197
 198 int sdioemb_set_block_size(struct sdioemb_dev *fdev, uint16_t blksz);
 199 void sdioemb_set_max_bus_freq(struct sdioemb_dev *fdev, int max_freq);
 200 int sdioemb_set_bus_width(struct sdioemb_dev *fdev, int bus_width);
 201
 202 int sdioemb_enable_function(struct sdioemb_dev *fdev);
 203 int sdioemb_disable_function(struct sdioemb_dev *fdev);
 204 int sdioemb_reenable_csr_function(struct sdioemb_dev *dev);
 205 void sdioemb_idle_function(struct sdioemb_dev *fdev);
 206
 207 int sdioemb_read8(struct sdioemb_dev *fdev, uint32_t addr, uint8_t *val);
 208 int sdioemb_read16(struct sdioemb_dev *fdev, uint32_t addr, uint16_t *val);
 209 int sdioemb_write8(struct sdioemb_dev *fdev, uint32_t addr, uint8_t val);
 210 int sdioemb_write16(struct sdioemb_dev *fdev, uint32_t addr, uint16_t val);
 211 int sdioemb_f0_read8(struct sdioemb_dev *fdev, uint32_t addr, uint8_t *val);
 212 int sdioemb_f0_write8(struct sdioemb_dev *fdev, uint32_t addr, uint8_t val);
 213 int sdioemb_read(struct sdioemb_dev *fdev, uint32_t addr, void *data, size_t len);
 214 int sdioemb_write(struct sdioemb_dev *fdev, uint32_t addr, const void *data, size_t len);
 215
 216 int sdioemb_hard_reset(struct sdioemb_dev *fdev);
 217
 218 void sdioemb_power_on(struct sdioemb_dev *fdev);
 219 void sdioemb_power_off(struct sdioemb_dev *fdev);
 220
 221 int sdioemb_interrupt_enable(struct sdioemb_dev *fdev);
 222 int sdioemb_interrupt_disable(struct sdioemb_dev *fdev);
 223 void sdioemb_interrupt_acknowledge(struct sdioemb_dev *fdev);
 224
 225 int sdioemb_cis_get_tuple(struct sdioemb_dev *fdev, uint8_t tuple,
 226                        void *buf, size_t len);
 227
 228 void sdioemb_suspend_function(struct sdioemb_dev *fdev);
 229 void sdioemb_resume_function(struct sdioemb_dev *fdev);
 230
 231 /**
 232  * SDIO command status.
 233  *
 234  * @ingroup fdriver
 235  */
 236 enum sdioemb_cmd_status {
 237     SDIOEMB_CMD_OK          = 0x00, /**< Command successful. */
 238
 239     SDIOEMB_CMD_ERR_CMD     = 0x01,
 240     SDIOEMB_CMD_ERR_DAT     = 0x02,
 241
 242     SDIOEMB_CMD_ERR_CRC     = 0x10,
 243     SDIOEMB_CMD_ERR_TIMEOUT = 0x20,
 244     SDIOEMB_CMD_ERR_OTHER   = 0x40,
 245
 246     SDIOEMB_CMD_ERR_CMD_CRC     = SDIOEMB_CMD_ERR_CMD | SDIOEMB_CMD_ERR_CRC,     /**< Response CRC error. */
 247     SDIOEMB_CMD_ERR_CMD_TIMEOUT = SDIOEMB_CMD_ERR_CMD | SDIOEMB_CMD_ERR_TIMEOUT, /**< Response time out. */
 248     SDIOEMB_CMD_ERR_CMD_OTHER   = SDIOEMB_CMD_ERR_CMD | SDIOEMB_CMD_ERR_OTHER,   /**< Other response error. */
 249     SDIOEMB_CMD_ERR_DAT_CRC     = SDIOEMB_CMD_ERR_DAT | SDIOEMB_CMD_ERR_CRC,     /**< Data CRC error. */
 250     SDIOEMB_CMD_ERR_DAT_TIMEOUT = SDIOEMB_CMD_ERR_DAT | SDIOEMB_CMD_ERR_TIMEOUT, /**< Data receive time out. */
 251     SDIOEMB_CMD_ERR_DAT_OTHER   = SDIOEMB_CMD_ERR_DAT | SDIOEMB_CMD_ERR_OTHER,   /**< Other data error. */
 252
 253     SDIOEMB_CMD_ERR_NO_CARD = 0x04, /**< No card present. */
 254
 255     SDIOEMB_CMD_IN_PROGRESS = 0xff, /**< Command still in progress. */
 256 };
 257
 258 /**
 259  * A response to an SDIO command.
 260  *
 261  * For R1, R4, R5, and R6 responses only the middle 32 bits of the
 262  * response are stored, the leading octet (start and direction bits
 263  * and command index) and trailing octet (CRC and stop bit) are
 264  * discarded.
 265  *
 266  * @bug R2 and R3 responses are not used by SDIO and are not
 267  * supported.
 268  *
 269  * @ingroup fdriver
 270  */
 271 union sdioemb_response {
 272     uint32_t r1;
 273     uint32_t r4;
 274     uint32_t r5;
 275     uint32_t r6;
 276 };
 277
 278 /**
 279  * SDIO command parameters and response.
 280  */
 281 struct sdioemb_cmd_resp {
 282     uint8_t  cmd;                 /**< Command index (0 to 63). */
 283     uint32_t arg;                 /**< Command argument. */
 284     union sdioemb_response response; /**< Response to the command. Valid
 285                                      iff the command has completed and
 286                                      (sdio_cmd::status & SDIOEMB_CMD_ERR_CMD) == 0.*/
 287 };
 288
 289 /**
 290  * CSPI command parameters and response.
 291  */
 292 struct cspi_cmd_resp {
 293     unsigned cmd : 8;  /**< Command octet (type, and function). */
 294     unsigned addr: 24; /**< 24 bit address. */
 295     uint16_t val;      /**< Word to write or read from the card (for non-burst commands). */
 296     uint8_t  response; /**< Response octet.  Valid iff the command has completed and
 297                           (sdio_cmd::status & SDIOEMB_CMD_ERR_CMD) == 0. */
 298 };
 299
 300
 301 /**
 302  * An SDIO command, its status and response.
 303  *
 304  * sdio_cmd is used to submit SDIO commands to a device and return its
 305  * status and any response or data.
 306  *
 307  * @ingroup fdriver
 308  */
 309 struct sdioemb_cmd {
 310     /**
 311      * The SDIO device which submitted the command.  Set by the
 312      * core.
 313      */
 314     struct sdioemb_dev *owner;
 315
 316     /**
 317      * Called by the core when the command has been completed.
 318      *
 319      * Called in: interrupt context.
 320      *
 321      * @param cmd the completed command.
 322      */
 323     void (*callback)(struct sdioemb_cmd *cmd);
 324
 325     /**
 326      * Set of flags specifying the response type, data transfer
 327      * direction and other parameters.
 328      *
 329      * For SDIO commands set at least one of the response types:
 330      *   - #SDIOEMB_CMD_FLAG_RESP_NONE
 331      *   - #SDIOEMB_CMD_FLAG_RESP_R1
 332      *   - #SDIOEMB_CMD_FLAG_RESP_R1B
 333      *   - #SDIOEMB_CMD_FLAG_RESP_R2
 334      *   - #SDIOEMB_CMD_FLAG_RESP_R3
 335      *   - #SDIOEMB_CMD_FLAG_RESP_R4
 336      *   - #SDIOEMB_CMD_FLAG_RESP_R5
 337      *   - #SDIOEMB_CMD_FLAG_RESP_R5B
 338      *   - #SDIOEMB_CMD_FLAG_RESP_R6
 339      *
 340      * and any of the additional flags:
 341      *   - #SDIOEMB_CMD_FLAG_READ
 342      *
 343      * For CSPI commands set:
 344      *   - #SDIOEMB_CMD_FLAG_CSPI
 345      */
 346     unsigned flags;
 347
 348     /**
 349      * SDIO command parameters and response.
 350      *
 351      * Valid only if #SDIOEMB_CMD_FLAG_CSPI is \e not set in #flags.
 352      */
 353     struct sdioemb_cmd_resp sdio;
 354
 355     /**
 356      * CSPI command parameters and response.
 357      *
 358      * Valid only if #SDIOEMB_CMD_FLAG_CSPI is set in #flags.
 359      */
 360     struct cspi_cmd_resp cspi;
 361
 362     /**
 363      * Buffer of data to read or write.
 364      *
 365      * Must be set to NULL if the command is not a data transfer.
 366      */
 367     uint8_t *data;
 368
 369     /**
 370      * Length of #data in octets.
 371      *
 372      * len must be either: less than the device's sdio_dev::blocksize;
 373      * or a multiple of the device's sdio_dev::blocksize.
 374      */
 375     size_t len;
 376
 377     /**
 378      * Status of the command after it has completed.
 379      */
 380     enum sdioemb_cmd_status status;
 381
 382     /**
 383      * Data private to caller of sdioemb_start_cmd().
 384      */
 385     void *priv;
 386 };
 387
 388 /** @addtogroup fdriver
 389  *@{*/
 390 #define SDIOEMB_CMD_FLAG_RESP_NONE 0x00 /**< No response. */
 391 #define SDIOEMB_CMD_FLAG_RESP_R1   0x01 /**< R1 response. */
 392 #define SDIOEMB_CMD_FLAG_RESP_R1B  0x02 /**< R1b response. */
 393 #define SDIOEMB_CMD_FLAG_RESP_R2   0x03 /**< R2 response. */
 394 #define SDIOEMB_CMD_FLAG_RESP_R3   0x04 /**< R3 response. */
 395 #define SDIOEMB_CMD_FLAG_RESP_R4   0x05 /**< R4 response. */
 396 #define SDIOEMB_CMD_FLAG_RESP_R5   0x06 /**< R5 response. */
 397 #define SDIOEMB_CMD_FLAG_RESP_R5B  0x07 /**< R5b response. */
 398 #define SDIOEMB_CMD_FLAG_RESP_R6   0x08 /**< R6 response. */
 399 #define SDIOEMB_CMD_FLAG_RESP_MASK 0xff /**< Mask for response type. */
 400 #define SDIOEMB_CMD_FLAG_RAW     0x0100 /**< @internal Bypass the command queues. */
 401 #define SDIOEMB_CMD_FLAG_READ    0x0200 /**< Data transfer is a read, not a write. */
 402 #define SDIOEMB_CMD_FLAG_CSPI    0x0400 /**< CSPI transfer, not SDIO or SDIO-SPI. */
 403 #define SDIOEMB_CMD_FLAG_ABORT   0x0800 /**< Data transfer abort command. */
 404 /*@}*/
 405
 406 int sdioemb_start_cmd(struct sdioemb_dev *fdev, struct sdioemb_cmd *cmd);
 407
 408 #endif /* #ifndef _SDIO_API_H */