path: root/drivers/staging/csr/csr_sdio.h

#ifndef CSR_SDIO_H__
#define CSR_SDIO_H__
/*****************************************************************************

            (c) Cambridge Silicon Radio Limited 2010
            All rights reserved and confidential information of CSR

            Refer to LICENSE.txt included with this source for details
            on the license terms.

*****************************************************************************/

#include "csr_result.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Result Codes */
#define CSR_SDIO_RESULT_INVALID_VALUE   ((CsrResult) 1) /* Invalid argument value */
#define CSR_SDIO_RESULT_NO_DEVICE       ((CsrResult) 2) /* The specified device is no longer present */
#define CSR_SDIO_RESULT_CRC_ERROR       ((CsrResult) 3) /* The transmitted/received data or command response contained a CRC error */
#define CSR_SDIO_RESULT_TIMEOUT         ((CsrResult) 4) /* No command response or data received from device, or function enable/disable did not succeed within timeout period */
#define CSR_SDIO_RESULT_NOT_RESET       ((CsrResult) 5) /* The device was not reset */

/* Features (for use in features member of CsrSdioFunction) */
#define CSR_SDIO_FEATURE_BYTE_MODE                   0x00000001 /* Transfer sizes do not have to be a multiple of block size */
#define CSR_SDIO_FEATURE_DMA_CAPABLE_MEM_REQUIRED    0x00000002 /* Bulk operations require DMA friendly memory */

/* CsrSdioFunctionId wildcards (for use in CsrSdioFunctionId members) */
#define CSR_SDIO_ANY_MANF_ID        0xFFFF
#define CSR_SDIO_ANY_CARD_ID        0xFFFF
#define CSR_SDIO_ANY_SDIO_FUNCTION  0xFF
#define CSR_SDIO_ANY_SDIO_INTERFACE 0xFF

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioFunctionId
 *
 *  DESCRIPTION
 *      This structure describes one or more functions of a device, based on
 *      four qualitative measures. The CsrSdioFunctionId wildcard defines can be
 *      used for making the CsrSdioFunctionId match more than one function.
 *
 *  MEMBERS
 *      manfId - Vendor ID (or CSR_SDIO_ANY_MANF_ID).
 *      cardId - Device ID (or CSR_SDIO_ANY_CARD_ID).
 *      sdioFunction - SDIO Function number (or CSR_SDIO_ANY_SDIO_FUNCTION).
 *      sdioInterface - SDIO Standard Interface Code (or CSR_SDIO_ANY_SDIO_INTERFACE)
 *
 *----------------------------------------------------------------------------*/
typedef struct
{
    u16 manfId;       /* Vendor ID to match or CSR_SDIO_ANY_MANF_ID */
    u16 cardId;       /* Device ID to match or CSR_SDIO_ANY_CARD_ID */
    u8  sdioFunction; /* SDIO Function number to match or CSR_SDIO_ANY_SDIO_FUNCTION */
    u8  sdioInterface; /* SDIO Standard Interface Code to match or CSR_SDIO_ANY_SDIO_INTERFACE */
} CsrSdioFunctionId;

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioFunction
 *
 *  DESCRIPTION
 *      This structure represents a single function on a device.
 *
 *  MEMBERS
 *      sdioId - A CsrSdioFunctionId describing this particular function. The
 *               subfield shall not contain any CsrSdioFunctionId wildcards. The
 *               subfields shall describe the specific single function
 *               represented by this structure.
 *      blockSize - Actual configured block size, or 0 if unconfigured.
 *      features - Bit mask with any of CSR_SDIO_FEATURE_* set.
 *      device - Handle of device containing the function. If two functions have
 *               the same device handle, they reside on the same device.
 *      driverData - For use by the Function Driver. The SDIO Driver shall not
 *                   attempt to dereference the pointer.
 *      priv - For use by the SDIO Driver. The Function Driver shall not attempt
 *             to dereference the pointer.
 *
 *
 *----------------------------------------------------------------------------*/
typedef struct
{
    CsrSdioFunctionId sdioId;
    u16         blockSize; /* Actual configured block size, or 0 if unconfigured */
    u32         features; /* Bit mask with any of CSR_SDIO_FEATURE_* set */
    void             *device; /* Handle of device containing the function */
    void             *driverData; /* For use by the Function Driver */
    void             *priv; /* For use by the SDIO Driver */
} CsrSdioFunction;

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioInsertedCallback, CsrSdioRemovedCallback
 *
 *  DESCRIPTION
 *      CsrSdioInsertedCallback is called when a function becomes available to
 *      a registered Function Driver that supports the function.
 *      CsrSdioRemovedCallback is called when a function is no longer available
 *      to a Function Driver, either because the device has been removed, or the
 *      Function Driver has been unregistered.
 *
 *      NOTE: These functions are implemented by the Function Driver, and are
 *            passed as function pointers in the CsrSdioFunctionDriver struct.
 *
 *  PARAMETERS
 *      function - Pointer to struct representing the function.
 *
 *----------------------------------------------------------------------------*/
typedef void (*CsrSdioInsertedCallback)(CsrSdioFunction *function);
typedef void (*CsrSdioRemovedCallback)(CsrSdioFunction *function);

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioInterruptDsrCallback, CsrSdioInterruptCallback
 *
 *  DESCRIPTION
 *      CsrSdioInterruptCallback is called when an interrupt occurs on the
 *      the device associated with the specified function.
 *
 *      NOTE: These functions are implemented by the Function Driver, and are
 *            passed as function pointers in the CsrSdioFunctionDriver struct.
 *
 *  PARAMETERS
 *      function - Pointer to struct representing the function.
 *
 *  RETURNS (only CsrSdioInterruptCallback)
 *      A pointer to a CsrSdioInterruptDsrCallback function.
 *
 *----------------------------------------------------------------------------*/
typedef void (*CsrSdioInterruptDsrCallback)(CsrSdioFunction *function);
typedef CsrSdioInterruptDsrCallback (*CsrSdioInterruptCallback)(CsrSdioFunction *function);

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioSuspendCallback, CsrSdioResumeCallback
 *
 *  DESCRIPTION
 *      CsrSdioSuspendCallback is called when the system is preparing to go
 *      into a suspended state. CsrSdioResumeCallback is called when the system
 *      has entered an active state again.
 *
 *      NOTE: These functions are implemented by the Function Driver, and are
 *            passed as function pointers in the CsrSdioFunctionDriver struct.
 *
 *  PARAMETERS
 *      function - Pointer to struct representing the function.
 *
 *----------------------------------------------------------------------------*/
typedef void (*CsrSdioSuspendCallback)(CsrSdioFunction *function);
typedef void (*CsrSdioResumeCallback)(CsrSdioFunction *function);

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioAsyncCallback, CsrSdioAsyncDsrCallback
 *
 *  DESCRIPTION
 *      CsrSdioAsyncCallback is called when an asynchronous operation completes.
 *
 *      NOTE: These functions are implemented by the Function Driver, and are
 *            passed as function pointers in the function calls that initiate
 *            the operation.
 *
 *  PARAMETERS
 *      function - Pointer to struct representing the function.
 *      result - The result of the operation that completed. See the description
 *               of the initiating function for possible result values.
 *
 *  RETURNS (only CsrSdioAsyncCallback)
 *      A pointer to a CsrSdioAsyncDsrCallback function.
 *
 *----------------------------------------------------------------------------*/
typedef void (*CsrSdioAsyncDsrCallback)(CsrSdioFunction *function, CsrResult result);
typedef CsrSdioAsyncDsrCallback (*CsrSdioAsyncCallback)(CsrSdioFunction *function, CsrResult result);

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioFunctionDriver
 *
 *  DESCRIPTION
 *      Structure representing a Function Driver.
 *
 *  MEMBERS
 *      inserted - Callback, see description of CsrSdioInsertedCallback.
 *      removed - Callback, see description of CsrSdioRemovedCallback.
 *      intr - Callback, see description of CsrSdioInterruptCallback.
 *      suspend - Callback, see description of CsrSdioSuspendCallback.
 *      resume - Callback, see description of CsrSdioResumeCallback.
 *      ids - Array of CsrSdioFunctionId describing one or more functions that
 *            are supported by the Function Driver.
 *      idsCount - Length of the ids array.
 *      priv - For use by the SDIO Driver. The Function Driver may initialise
 *             it to NULL, but shall otherwise not access the pointer or attempt
 *             to dereference it.
 *
 *----------------------------------------------------------------------------*/
typedef struct
{
    CsrSdioInsertedCallback  inserted;
    CsrSdioRemovedCallback   removed;
    CsrSdioInterruptCallback intr;
    CsrSdioSuspendCallback   suspend;
    CsrSdioResumeCallback    resume;
    CsrSdioFunctionId       *ids;
    u8                 idsCount;
    void                    *priv;          /* For use by the SDIO Driver */
} CsrSdioFunctionDriver;

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioFunctionDriverRegister
 *
 *  DESCRIPTION
 *      Register a Function Driver.
 *
 *  PARAMETERS
 *      functionDriver - Pointer to struct describing the Function Driver.
 *
 *  RETURNS
 *      CSR_RESULT_SUCCESS - The Function Driver was successfully
 *                           registered.
 *      CSR_RESULT_FAILURE - Unable to register the function driver,
 *                                because of an unspecified/unknown error. The
 *                                Function Driver has not been registered.
 *      CSR_SDIO_RESULT_INVALID_VALUE - The specified Function Driver pointer
 *                                      does not point at a valid Function
 *                                      Driver structure, or some of the members
 *                                      contain invalid entries.
 *
 *----------------------------------------------------------------------------*/
CsrResult CsrSdioFunctionDriverRegister(CsrSdioFunctionDriver *functionDriver);

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioFunctionDriverUnregister
 *
 *  DESCRIPTION
 *      Unregister a previously registered Function Driver.
 *
 *  PARAMETERS
 *      functionDriver - pointer to struct describing the Function Driver.
 *
 *----------------------------------------------------------------------------*/
void CsrSdioFunctionDriverUnregister(CsrSdioFunctionDriver *functionDriver);

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioFunctionEnable, CsrSdioFunctionDisable
 *
 *  DESCRIPTION
 *      Enable/disable the specified function by setting/clearing the
 *      corresponding bit in the I/O Enable register in function 0, and then
 *      periodically reading the related bit in the I/O Ready register until it
 *      is set/clear, limited by an implementation defined timeout.
 *
 *  PARAMETERS
 *      function - Pointer to struct representing the function.
 *
 *  RETURNS
 *      CSR_RESULT_SUCCESS - The specified function was enabled/disabled.
 *      CSR_RESULT_FAILURE - Unspecified/unknown error.
 *      CSR_SDIO_RESULT_NO_DEVICE - The device does not exist anymore.
 *      CSR_SDIO_RESULT_CRC_ERROR - A CRC error occured. The state of the
 *                                  related bit in the I/O Enable register is
 *                                  undefined.
 *      CSR_SDIO_RESULT_TIMEOUT - No response from the device, or the related
 *                                bit in the I/O ready register was not
 *                                set/cleared within the timeout period.
 *
 *      NOTE: If the SDIO R5 response is available, and either of the
 *            FUNCTION_NUMBER or OUT_OF_RANGE bits are set,
 *            CSR_SDIO_RESULT_INVALID_VALUE shall be returned. If the ERROR bit
 *            is set (but none of FUNCTION_NUMBER or OUT_OF_RANGE),
 *            CSR_RESULT_FAILURE shall be returned. The ILLEGAL_COMMAND and
 *            COM_CRC_ERROR bits shall be ignored.
 *
 *            If the CSPI response is available, and any of the
 *            FUNCTION_DISABLED or CLOCK_DISABLED bits are set,
 *            CSR_SDIO_RESULT_INVALID_VALUE will be returned.
 *
 *----------------------------------------------------------------------------*/
CsrResult CsrSdioFunctionEnable(CsrSdioFunction *function);
CsrResult CsrSdioFunctionDisable(CsrSdioFunction *function);

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioInterruptEnable, CsrSdioInterruptDisable
 *
 *  DESCRIPTION
 *      Enable/disable the interrupt for the specified function by
 *      setting/clearing the corresponding bit in the INT Enable register in
 *      function 0.
 *
 *  PARAMETERS
 *      function - Pointer to struct representing the function.
 *
 *  RETURNS
 *      CSR_RESULT_SUCCESS - The specified function was enabled/disabled.
 *      CSR_RESULT_FAILURE - Unspecified/unknown error.
 *      CSR_SDIO_RESULT_NO_DEVICE - The device does not exist anymore.
 *      CSR_SDIO_RESULT_CRC_ERROR - A CRC error occured. The state of the
 *                                  related bit in the INT Enable register is
 *                                  unchanged.
 *      CSR_SDIO_RESULT_INVALID_VALUE - The specified function cannot be
 *                                      enabled/disabled, because it either
 *                                      does not exist or it is not possible to
 *                                      individually enable/disable functions.
 *      CSR_SDIO_RESULT_TIMEOUT - No response from the device.
 *
 *      NOTE: If the SDIO R5 response is available, and either of the
 *            FUNCTION_NUMBER or OUT_OF_RANGE bits are set,
 *            CSR_SDIO_RESULT_INVALID_VALUE shall be returned. If the ERROR bit
 *            is set (but none of FUNCTION_NUMBER or OUT_OF_RANGE),
 *            CSR_RESULT_FAILURE shall be returned. The ILLEGAL_COMMAND and
 *            COM_CRC_ERROR bits shall be ignored.
 *
 *            If the CSPI response is available, and any of the
 *            FUNCTION_DISABLED or CLOCK_DISABLED bits are set,
 *            CSR_SDIO_RESULT_INVALID_VALUE will be returned.
 *
 *----------------------------------------------------------------------------*/
CsrResult CsrSdioInterruptEnable(CsrSdioFunction *function);
CsrResult CsrSdioInterruptDisable(CsrSdioFunction *function);

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioInterruptAcknowledge
 *
 *  DESCRIPTION
 *      Acknowledge that a signalled interrupt has been handled. Shall only
 *      be called once, and exactly once for each signalled interrupt to the
 *      corresponding function.
 *
 *  PARAMETERS
 *      function - Pointer to struct representing the function to which the
 *                 event was signalled.
 *
 *----------------------------------------------------------------------------*/
void CsrSdioInterruptAcknowledge(CsrSdioFunction *function);

/*----------------------------------------------------------------------------*
 *  NAME
 *      CsrSdioInsertedAcknowledge, CsrSdioRemovedAcknowledge
 *
 *  DESCRIPTION
 *      Acknowledge that a signalled inserted/removed event has been handled.
 *      Shall only be called once, and exactly once for each signalled event to
 *      the corresponding function.
 *
 *  PARAMETERS
 *      function - Pointer to struct representing the function to which the
 *                 inserted was signalled.
 *      result (CsrSdioInsertedAcknowledge only)
 *          CSR_RESULT_SUCCESS - The Function Driver has accepted the
 *                                    function, and the function is attached to
 *                                    the Function Driver until the
 *                                    CsrSdioRemovedCallback is called and
 *                                    acknowledged.
 *          CSR_RESULT_FAILURE - Unable to accept the function. The
 *                                    function is not attached to the Function
 *                                    Driver, and it may be passed to another
 *                                    Function Driver which supports the
 *                                    function.
 *
 *----------------------------------------------------------------------------*/
void CsrSdioInsertedAcknowledge(CsrSdioFunction *fun