drivers/staging/csr/sdioemb/libsdio.h

   1 /*
   2  * SDIO Userspace Interface library.
   3  *
   4  * Copyright (C) 2007 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 SDIOEMB_LIBSDIO_H
  10 #define SDIOEMB_LIBSDIO_H
  11
  12 /**
  13  * \defgroup libsdio Userspace SDIO library (libsdio)
  14  *
  15  * \brief \e libsdio is a Linux C library for accessing SDIO cards.
  16  *
  17  * Use of this library requires several \e sdioemb kernel modules to be
  18  * loaded:
  19  *   - \c sdio.
  20  *   - \c An SDIO slot driver (e.g., \c slot_shc for a standard PCI
  21  *     SDIO Host Controller).
  22  *   - \c sdio_uif which provides the required character devices
  23  *     (/dev/sdio_uif0 for the card in SDIO slot 0 etc.).
  24  */
  25 /*@{*/
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 #ifdef WIN32
  32 #  define LIBSDIOAPI __stdcall
  33 #else
  34 #  define LIBSDIOAPI
  35 #endif
  36
  37 struct sdio_uif;
  38
  39 /**
  40  * Handle to an opened SDIO Userspace Interface device.
  41  */
  42 typedef struct sdio_uif *sdio_uif_t;
  43
  44 enum sdio_status {
  45     SDIO_SUCCESS   = 0,
  46     SDIO_EAGAIN    = -1,
  47     SDIO_EINVAL    = -2,
  48     SDIO_EIO       = -3,
  49     SDIO_ENODEV    = -4,
  50     SDIO_ENOMEM    = -5,
  51     SDIO_ENOTSUPP  = -6,
  52     SDIO_ENXIO     = -7,
  53     SDIO_ETIMEDOUT = -8,
  54 };
  55
  56 /**
  57  * Card interrupt handler function.
  58  *
  59  * @param uif handle to the interrupting device.
  60  * @param arg data supplied by the caller of sdio_open().
  61  */
  62 typedef void (LIBSDIOAPI *sdio_int_handler_t)(sdio_uif_t uif, void *arg);
  63
  64 /**
  65  * Asynchronous IO completion callback function.
  66  *
  67  * @param uif    handle to the device that completed the IO operation.
  68  * @param arg    data supplied by the caller of the asynchronous IO operation.
  69  * @param status status of the IO operation. 0 is success; -EIO,
  70  *               -EINVAL, -ETIMEDOUT etc. on an error.
  71  */
  72 typedef void (LIBSDIOAPI *sdio_io_callback_t)(sdio_uif_t uif, void *arg, int status);
  73
  74 /**
  75  * Open a SDIO Userspace Interface device and (optionally) register a
  76  * card interrupt handler and enable card interrupts.
  77  *
  78  * Card interrupts are masked before calling int_handler and are
  79  * unmasked when int_handler returns (unless sdio_interrupt_mask() is
  80  * called).
  81  *
  82  * @param dev_filename  filename of the device to open.
  83  * @param int_handler   card interrupt handler; or NULL if no
  84  *                      interrupt handler is required.
  85  * @param arg           argument to be passed to the interrupt handler.
  86  *
  87  * @return handle to the opened device; or NULL on error with errno
  88  * set.
  89  */
  90 sdio_uif_t LIBSDIOAPI sdio_open(const char *dev_filename,
  91                                 sdio_int_handler_t int_handler, void *arg);
  92
  93 /**
  94  * Mask the SDIO interrupt.
  95  *
  96  * Call this in an interrupt handler to allow the processing of
  97  * interrupts to be deferred until after the interrupt handler has
  98  * returned.
  99  *
 100  * @note \e Must only be called from within the interrupt handler
 101  * registered with sdio_open().
 102  *
 103  * @param uif device handle.
 104  */
 105 void LIBSDIOAPI sdio_interrupt_mask(sdio_uif_t uif);
 106
 107 /**
 108  * Unmask the SDIO interrupt.
 109  *
 110  * Unmasks the SDIO interrupt if it had previously been masked with
 111  * sdio_interrupt_mask().
 112  *
 113  * @param uif device handle.
 114  */
 115 void LIBSDIOAPI sdio_interrupt_unmask(sdio_uif_t uif);
 116
 117 /**
 118  * Close an opened SDIO Userspace Interface device, freeing all
 119  * associated resources.
 120  *
 121  * @param uif handle to the device.
 122  */
 123 void LIBSDIOAPI sdio_close(sdio_uif_t uif);
 124
 125 /**
 126  * Return the number of functions the card has.
 127  *
 128  * @param uif device handle.
 129  *
 130  * @return number of card functions.
 131  */
 132 int LIBSDIOAPI sdio_num_functions(sdio_uif_t uif);
 133
 134 /**
 135  * Set an SDIO bus to 1 bit or 4 bit wide mode.
 136  *
 137  * The CCCR bus interface control register will be read and rewritten
 138  * with the new bus width.
 139  *
 140  * @param uif       device handle.
 141  * @param bus_width bus width (1 or 4).
 142  *
 143  * @return 0 on success; -ve on error with errno set.
 144  *
 145  * @note The card capabilities are \e not checked.  The user should
 146  * ensure 4 bit mode is not enabled on a card that does not support
 147  * it.
 148  */
 149 int LIBSDIOAPI sdio_set_bus_width(sdio_uif_t uif, int bus_width);
 150
 151 /**
 152  * Limit the frequency of (or stop) the SD bus clock.
 153  *
 154  * The frequency cannot be set greater than that supported by the card
 155  * or the controller.
 156  *
 157  * @note Stopping the bus clock while other device drivers are
 158  * executing commands may result in those commands not completing
 159  * until the bus clock is restarted.
 160  *
 161  * @param uif      device handle.
 162  * @param max_freq maximum frequency (Hz) or 0 to stop the bus clock
 163  *                 until the start of the next command.
 164  */
 165 void LIBSDIOAPI sdio_set_max_bus_freq(sdio_uif_t uif, int max_freq);
 166
 167 /**
 168  * Return the card's manufacturer (vendor) ID.
 169  *
 170  * @param uif device handle.
 171  *
 172  * @return manufacturer ID.
 173  */
 174 uint16_t LIBSDIOAPI sdio_manf_id(sdio_uif_t uif);
 175
 176 /**
 177  * Return the card's card (device) ID.
 178  *
 179  * @param uif device handle.
 180  *
 181  * @return card ID.
 182  */
 183 uint16_t LIBSDIOAPI sdio_card_id(sdio_uif_t uif);
 184
 185 /**
 186  * Return the standard interface code for a function.
 187  *
 188  * @param uif  device handle.
 189  * @param func card function to query.
 190  *
 191  * @return the standard interface.
 192  */
 193 uint8_t LIBSDIOAPI sdio_std_if(sdio_uif_t uif, int func);
 194
 195 /**
 196  * Return a function's maximum supported block size.
 197  *
 198  * @param uif  device handle.
 199  * @param func card function to query.
 200  *
 201  * @return maximum block size.
 202  */
 203 int LIBSDIOAPI sdio_max_block_size(sdio_uif_t uif, int func);
 204
 205 /**
 206  * Return a function's current block size.
 207  *
 208  * @note This returns the driver's view of the block size and not the
 209  * value in the function's block size register.
 210  *
 211  * @param uif  device handle.
 212  * @param func card function to query.
 213  *
 214  * @return the current block size.
 215  */
 216 int LIBSDIOAPI sdio_block_size(sdio_uif_t uif, int func);
 217
 218 /**
 219  * Set a function's block size.
 220  *
 221  * The function's block size registers will be written if necessary.
 222  *
 223  * @param uif   device handle.
 224  * @param func  function to modify.
 225  * @param blksz the new block size; or 0 for the default size.
 226  *
 227  * @return 0 on success; or -ve on error with errno set.
 228  */
 229 int LIBSDIOAPI sdio_set_block_size(sdio_uif_t uif, int func, int blksz);
 230
 231 /**
 232  * Read an 8 bit register.
 233  *
 234  * @param uif  device handle.
 235  * @param func card function.
 236  * @param addr register address.
 237  * @param data the data read.
 238  *
 239  * @return 0 on success; or -ve on error with errno set.
 240  */
 241 int LIBSDIOAPI sdio_read8(sdio_uif_t uif, int func, uint32_t addr, uint8_t *data);
 242
 243 /**
 244  * Write an 8 bit register.
 245  *
 246  * @param uif  device handle.
 247  * @param func card function.
 248  * @param addr register address.
 249  * @param data the data to write.
 250  *
 251  * @return 0 on success; or -ve on error with errno set.
 252  */
 253 int LIBSDIOAPI sdio_write8(sdio_uif_t uif, int func, uint32_t addr, uint8_t data);
 254
 255 /**
 256  * Read a buffer from a 8 bit wide register/FIFO.
 257  *
 258  * The buffer read uses a fixed (not incrementing) address.
 259  *
 260  * \a block_size \e must be set to the value writted into \a func's
 261  * I/O block size FBR register.
 262  *
 263  * If \a len % \a block_size == 0, a block mode transfer is used; a
 264  * byte mode transfer is used if \a len < \a block_size.
 265  *
 266  * @param uif        device handle.
 267  * @param func       card function.
 268  * @param addr       register/FIFO address.
 269  * @param data       buffer to store the data read.
 270  * @param len        length of data to read.
 271  * @param block_size block size to use for this transfer.
 272  *
 273  * @return 0 on success; or -ve on error with errno set.
 274  */
 275 int LIBSDIOAPI sdio_read(sdio_uif_t uif, int func, uint32_t addr, uint8_t *data,
 276                       size_t len, int block_size);
 277
 278 /**
 279  * Write a buffer to an 8 bit wide register/FIFO.
 280  *
 281  * The buffer write uses a fixed (not incrementing) address.
 282  *
 283  * \a block_size \e must be set to the value writted into \a func's
 284  * I/O block size FBR register.
 285  *
 286  * If \a len % \a block_size == 0, a block mode transfer is used; a
 287  * byte mode transfer is used if \a len < \a block_size.
 288  *
 289  * @param uif        device handle.
 290  * @param func       card function.
 291  * @param addr       register/FIFO address.
 292  * @param data       buffer of data to write.
 293  * @param len        length of the data to write.
 294  * @param block_size block size to use for this transfer.
 295  *
 296  * @return 0 on success; or -ve on error with errno set.
 297  */
 298 int LIBSDIOAPI sdio_write(sdio_uif_t uif, int func, uint32_t addr, const uint8_t *data,
 299                           size_t len, int block_size);
 300
 301 /**
 302  * Read an 8 bit register, without waiting for completion.
 303  *
 304  * @param uif      device handle.
 305  * @param func     card function.
 306  * @param addr     register address.
 307  * @param data     the data read.
 308  * @param callback function to be called when the read completes.
 309  * @param arg      argument to be passed to callback.
 310  *
 311  * @return 0 on success; or -ve on error with errno set.
 312  */
 313 int LIBSDIOAPI sdio_read8_async(sdio_uif_t uif, int func, uint32_t addr, uint8_t *data,
 314                                 sdio_io_callback_t callback, void *arg);
 315
 316 /**
 317  * Write an 8 bit register, without waiting for completion.
 318  *
 319  * @param uif      device handle.
 320  * @param func     card function.
 321  * @param addr     register address.
 322  * @param data     the data to write.
 323  * @param callback function to be called when the write completes.
 324  * @param arg      argument to be passed to callback.
 325  *
 326  * @return 0 on success; or -ve on error with errno set.
 327  */
 328 int LIBSDIOAPI sdio_write8_async(sdio_uif_t uif, int func, uint32_t addr, uint8_t data,
 329                                  sdio_io_callback_t callback, void *arg);
 330
 331 /**
 332  * Read a buffer from a 8 bit wide register/FIFO, without waiting for
 333  * completion.
 334  *
 335  * The buffer read uses a fixed (not incrementing) address.
 336  *
 337  * \a block_size \e must be set to the value writted into \a func's
 338  * I/O block size FBR register.
 339  *
 340  * If \a len % \a block_size == 0, a block mode transfer is used; a
 341  * byte mode transfer is used if \a len < \a block_size.
 342  *
 343  * @param uif        device handle.
 344  * @param func       card function.
 345  * @param addr       register/FIFO address.
 346  * @param data       buffer to store the data read.
 347  * @param len        length of data to read.
 348  * @param block_size block size to use for this transfer.
 349  * @param callback   function to be called when the read completes.
 350  * @param arg        argument to be passed to callback.
 351  *
 352  * @return 0 on success; or -ve on error with errno set.
 353  */
 354 int LIBSDIOAPI sdio_read_async(sdio_uif_t uif, int func, uint32_t addr, uint8_t *data,
 355                                size_t len, int block_size,
 356                                sdio_io_callback_t callback, void *arg);
 357
 358 /**
 359  * Write a buffer to an 8 bit wide register/FIFO, without waiting for
 360  * completion.
 361  *
 362  * The buffer write uses a fixed (not incrementing) address.
 363  *
 364  * \a block_size \e must be set to the value writted into \a func's
 365  * I/O block size FBR register.
 366  *
 367  * If \a len % \a block_size == 0, a block mode transfer is used; a
 368  * byte mode transfer is used if \a len < \a block_size.
 369  *
 370  * @param uif        device handle.
 371  * @param func       card function.
 372  * @param addr       register/FIFO address.
 373  * @param data       buffer of data to write.
 374  * @param len        length of the data to write.
 375  * @param block_size block size to use for this transfer.
 376  * @param callback   function to be called when the write completes.
 377  * @param arg        argument to be passed to callback.
 378  *
 379  * @return 0 on success; or -ve on error with errno set.
 380  */
 381 int LIBSDIOAPI sdio_write_async(sdio_uif_t uif, int func, uint32_t addr, const uint8_t *data,
 382                                 size_t len, int block_size,
 383                                 sdio_io_callback_t callback, void *arg);
 384 /**
 385  * Force a card removal and reinsertion.
 386  *
 387  * This will power cycle the card if the slot hardware supports power
 388  * control.
 389  *
 390  * @note The device handle will no longer be valid.
 391  *
 392  * @param uif device handle.
 393  *
 394  * @return 0 on success; or -ve on error with errno set.
 395  */
 396 int LIBSDIOAPI sdio_reinsert_card(sdio_uif_t uif);
 397
 398 #ifdef __cplusplus
 399 } /* extern "C" */
 400 #endif
 401
 402 /*@}*/
 403
 404 #endif /* #ifndef SDIOEMB_LIBSDIO_H */