drivers/staging/csr/sdioemb/slot_api.h

   1 /*
   2  * Slot driver API.
   3  *
   4  * Copyright (C) 2007-2009 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 _SLOT_API_H
  10 #define _SLOT_API_H
  11
  12 #include <sdioemb/sdio_api.h>
  13
  14 struct sdioemb_slot;
  15
  16 /**
  17  * @defgroup sdriver SDIO slot driver API
  18  *
  19  * @brief The SDIO slot driver API provides an interface for the SDIO
  20  * layer to driver an SDIO slot (socket).
  21  *
  22  * Slot drivers register with the SDIO layer (sdioemb_slot_register()),
  23  * providing functions to starting commands, enabling/disable card
  24  * interrupts, card detection and bus power control.
  25  *
  26  * Functions are provided to notify the SDIO layer when a command has
  27  * completed (sdioemb_cmd_complete()) and when an SDIO card interrupt has
  28  * occurred (sdioemb_interrupt()).
  29  */
  30
  31 #define SDIOEMB_BUS_FREQ_OFF      0
  32 #define SDIOEMB_BUS_FREQ_DEFAULT -1
  33 #define SDIOEMB_BUS_FREQ_IDLE    -2
  34
  35 /**
  36  * Valid SDIO bus voltage levels.
  37  *
  38  * @ingroup sdriver
  39  */
  40 enum sdioemb_power {
  41     SDIOEMB_POWER_OFF  =   0, /**< Power switched off. */
  42     SDIOEMB_POWER_3V3  =  33, /**< Voltage set to 3.3V. */
  43 };
  44
  45 /**
  46  * SDIO slot capabilities.
  47  *
  48  * @ingroup sdriver
  49  */
  50 struct slot_caps {
  51     int max_bus_freq;  /**< Maximum bus frequency (Hz). */
  52     int max_bus_width; /**< Maximum bus width supported (1 or 4 data lines). */
  53     uint8_t cspi_mode; /**< CSPI_MODE register value (for CSPI capable slots). */
  54 };
  55
  56 /**
  57  * Controller hardware type.
  58  *
  59  * @ingroup sdriver
  60  */
  61 enum slot_controller_type {
  62     SDIOEMB_SLOT_TYPE_SD = 0,   /**< SD/SDIO controller. */
  63     SDIOEMB_SLOT_TYPE_SPI,      /**< SPI controller. */
  64     SDIOEMB_SLOT_TYPE_SPI_CSPI, /**< SPI controller capable of CSPI. */
  65 };
  66
  67 /**
  68  * Return values from the add_function() notifier.
  69  *
  70  * @ingroup sdriver
  71  */
  72 enum sdioemb_add_func_status {
  73     /**
  74      * The core will call sdioemb_add_function().
  75      */
  76     SDIOEMB_ADD_FUNC_NOW = 0,
  77     /**
  78      * The slot driver will call sdioemb_add_function() or the
  79      * function driver will call sdioemb_driver_probe() directly.
  80      */
  81     SDIOEMB_ADD_FUNC_DEFERRED = 1,
  82 };
  83
  84 /**
  85  * Slot/card event notifiers.
  86  *
  87  * A slot driver may be notified when certain slot or card events
  88  * occur.
  89  *
  90  * @ingroup sdriver
  91  */
  92 struct sdioemb_slot_notifiers {
  93     /**
  94      * This is called when a card function has been enumerated
  95      * and initialized but before can be bound to a function driver.
  96      *
  97      * A slot driver may use this to create an OS-specific object for
  98      * the function.  The slot driver must either (a) return
  99      * SDIOEMB_ADD_FUNC_NOW; (b) return SDIOEMB_ADD_FUNC_DEFERRED and
 100      * call sdioemb_add_function() later on; (c) return
 101      * SDIOEMB_ADD_FUNC_DEFERRED and pass the fdev to the function
 102      * driver for it to call sdioemb_driver_probe() directly; or (d)
 103      * return an error.
 104      *
 105      * The slot driver may need to get a reference to the fdev with
 106      * sdioemb_get_function() if the lifetime of the OS-specific
 107      * object extends beyond the subsequent return of the
 108      * del_function() callback.
 109      *
 110      * If this is non-NULL the slot driver must also provide
 111      * del_function().
 112      *
 113      * @param slot the SDIO slot producing the notification.
 114      * @param fdev the SDIO function being added.
 115      *
 116      * @return SDIOEMB_ADD_FUNC_NOW if the function is ready for use.
 117      * @return SDIOEMB_ADD_FUNC_DEFERRED if sdioemb_add_function() or
 118      *         sdioemb_driver_probe() will be called later.
 119      * @return -ve on a error.
 120      */
 121     int (*add_function)(struct sdioemb_slot *slot, struct sdioemb_dev *fdev);
 122
 123     /**
 124      * This is called when a card function is being removed and after
 125      * any function driver has been unbound.
 126      *
 127      * A slot driver may use this to delete any OS-specific object
 128      * created by the add_function() notifier.
 129      *
 130      * @param slot the SDIO slot producing the notification.
 131      * @param fdev the SDIO function being deleted.
 132      */
 133     void (*del_function)(struct sdioemb_slot *slot, struct sdioemb_dev *fdev);
 134 };
 135
 136 struct sdioemb_slot_priv;
 137
 138 /**
 139  * An SDIO slot driver.
 140  *
 141  * Allocate and free with sdioemb_slot_alloc() and sdioemb_slot_free().
 142  *
 143  * @ingroup sdriver
 144  */
 145 struct sdioemb_slot {
 146     /**
 147      * Name of the slot used in diagnostic messages.
 148      *
 149      * This would typically include the name of the SDIO controller
 150      * and the slot number if the controller has multiple slots.
 151      *
 152      * This will be set by sdioemb_slot_register() if it is left as an
 153      * empty string.
 154      */
 155     char name[64];
 156
 157     /**
 158      * Controller hardware type.
 159      */
 160     enum slot_controller_type type;
 161
 162     /**
 163      * Set the SD bus clock frequency.
 164      *
 165      * The driver's implementation should set the SD bus clock to not
 166      * more than \a clk Hz (unless \a clk is equal to
 167      * #SDIOEMB_BUS_FREQ_OFF or #SDIOEMB_BUS_FREQ_IDLE).
 168      *
 169      * If \a clk == SDIOEMB_BUS_FREQ_OFF the clock should be stopped.
 170      *
 171      * \a clk == SDIOEMB_BUS_FREQ_IDLE indicates that the bus is idle
 172      * (currently unused) and the host controller may slow (or stop)
 173      * the SD bus clock to save power on the card.  During this idle
 174      * state the host controller must be capable of receiving SDIO
 175      * interrupts (for certain host controllers this may require
 176      * leaving the clock running).
 177      *
 178      * If \a clk is greater than #SDIO_CLOCK_FREQ_NORMAL_SPD (25 MHz)
 179      * subsequent commands should be done with the controller in high
 180      * speed mode.
 181      *
 182      * Called from: interrupt context.
 183      *
 184      * @param slot  the slot to configure.
 185      * @param clk   new SD bus clock frequency in Hz, SDIOEMB_BUS_FREQ_OFF
 186      *              or SDIOEMB_BUS_FREQ_IDLE.
 187      *
 188      * @return The bus frequency actually configured in Hz.
 189      */
 190     int (*set_bus_freq)(struct sdioemb_slot *slot, int clk);
 191
 192     /**
 193      * Set the SD bus width.
 194      *
 195      * The driver's implementation should set the width of the SD bus
 196      * for all subsequent data transfers to the specified value.
 197      *
 198      * This may be NULL if the driver sets the bus width when starting
 199      * a command, or the driver is for an SDIO-SPI or CSPI controller.
 200      *
 201      * Called from: thread context.
 202      *
 203      * @param slot      the slot to configure.
 204      * @param bus_width new SD bus width (either 1 or 4).
 205      *
 206      * @return 0 on success.
 207      * @return -ve if a low-level error occured when setting the bus width.
 208      */
 209     int (*set_bus_width)(struct sdioemb_slot *slot, int bus_width);
 210
 211     /**
 212      * Start an SDIO command.
 213      *
 214      * The driver's implementation should:
 215      *
 216      *   - set the controller's bus width to #bus_width,
 217      *   - program the controller to start the command.
 218      *
 219      * Called from: interrupt context.
 220      *
 221      * @param slot  slot to perform the command.
 222      * @param cmd   SDIO command to start.
 223      */
 224     int (*start_cmd)(struct sdioemb_slot *slot, struct sdioemb_cmd *cmd);
 225
 226     /**
 227      * Detect if a card is inserted into the slot.
 228      *
 229      * Called from: thread context.
 230      *
 231      * @param slot slot to check.
 232      *
 233      * @return non-zero if a card is inserted; 0 otherwise.
 234      */
 235     int (*card_present)(struct sdioemb_slot *slot);
 236
 237     /**
 238      * Switch on/off the SDIO bus power and set the SDIO bus voltage.
 239      *
 240      * Called from: thread context.
 241      *
 242      * @param slot  the slot.
 243      * @param power the requested voltage.
 244      *
 245      * @return 0 on success; -ve on error: -EINVAL - requested voltage
 246      * is not supported.
 247      */
 248     int (*card_power)(struct sdioemb_slot *slot, enum sdioemb_power power);
 249
 250     /**
 251      * Enable (unmask) the SDIO card interrupt on the controller.
 252      *
 253      * Called from: interrupt context.
 254      *
 255      * @param slot the slot to enable the interrupt on..
 256      */
 257     void (*enable_card_int)(struct sdioemb_slot *slot);
 258
 259     /**
 260      * Disable (mask) the SDIO card interrupt on the controller.
 261      *
 262      * Called from: thread context.
 263      *
 264      * @param slot the slot to disable the interrupt on.
 265      */
 266     void (*disable_card_int)(struct sdioemb_slot *slot);
 267
 268     /**
 269      * Perform a hard reset of the card.
 270      *
 271      * Hard resets can be achieved in two ways:
 272      *
 273      * -# Power cycle (if the slot has power control).
 274      * -# Platform-specific assertion of a card/chip reset line.
 275      *
 276      * If hard resets are not supported, either return 0 or set
 277      * hard_reset to NULL.
 278      *
 279      * @param slot the slot for the card to reset.
 280      *
 281      * @return 0 if a hard reset was performed.
 282      * @return 1 if hard resets are not supported.
 283      */
 284     int (*hard_reset)(struct sdioemb_slot *slot);
 285
 286     struct slot_caps         caps;           /**< Slot capabilities. */
 287     int                      clock_freq;     /**< SD bus frequency requested by the SDIO layer. */
 288     int                      bus_width;      /**< Bus width requested by the SDIO layer. */
 289     struct sdioemb_slot_notifiers notifs;    /**< Slot event notifiers. */
 290     int                      cspi_reg_pad;   /**< Padding for CSPI register reads. */
 291     int                      cspi_burst_pad; /**< Padding for CSPI burst reads. */
 292     struct sdioemb_slot_priv *priv;          /**< Data private to the SDIO layer. */
 293     void *                   drv_data;       /**< Data private to the slot driver. */
 294 };
 295
 296 struct sdioemb_slot *sdioemb_slot_alloc(size_t drv_data_size);
 297 void sdioemb_slot_free(struct sdioemb_slot *slot);
 298 int sdioemb_slot_register(struct sdioemb_slot *slot);
 299 void sdioemb_slot_unregister(struct sdioemb_slot *slot);
 300 int sdioemb_card_inserted(struct sdioemb_slot *slot);
 301 void sdioemb_card_removed(struct sdioemb_slot *slot);
 302 void sdioemb_interrupt(struct sdioemb_slot *slot);
 303 void sdioemb_cmd_complete(struct sdioemb_slot *slot, struct sdioemb_cmd *cmd);
 304
 305 void sdioemb_suspend(struct sdioemb_slot *slot);
 306 void sdioemb_resume(struct sdioemb_slot *slot);
 307
 308 void sdioemb_add_function(struct sdioemb_dev *fdev);
 309 void sdioemb_del_function(struct sdioemb_dev *fdev);
 310 void sdioemb_get_function(struct sdioemb_dev *fdev);
 311 void sdioemb_put_function(struct sdioemb_dev *fdev);
 312
 313 #endif /* #ifndef _SLOT_API_H */