SDIO function driver API

The SDIO function driver API is used to implement drivers for SDIO card functions. More...

Data Structures

struct  sdioemb_dev
struct  sdioemb_id_table
struct  sdioemb_func_driver
union  sdioemb_response
struct  sdioemb_cmd

Defines

#define SDIOEMB_CMD_FLAG_RESP_NONE   0x00
#define SDIOEMB_CMD_FLAG_RESP_R1   0x01
#define SDIOEMB_CMD_FLAG_RESP_R1B   0x02
#define SDIOEMB_CMD_FLAG_RESP_R2   0x03
#define SDIOEMB_CMD_FLAG_RESP_R3   0x04
#define SDIOEMB_CMD_FLAG_RESP_R4   0x05
#define SDIOEMB_CMD_FLAG_RESP_R5   0x06
#define SDIOEMB_CMD_FLAG_RESP_R5B   0x07
#define SDIOEMB_CMD_FLAG_RESP_R6   0x08
#define SDIOEMB_CMD_FLAG_RESP_MASK   0xff
#define SDIOEMB_CMD_FLAG_RAW   0x0100
#define SDIOEMB_CMD_FLAG_READ   0x0200
#define SDIOEMB_CMD_FLAG_CSPI   0x0400
#define SDIOEMB_CMD_FLAG_ABORT   0x0800

Enumerations

enum  sdioemb_cmd_status {
  SDIOEMB_CMD_OK = 0x00,
  SDIOEMB_CMD_ERR_CMD = 0x01,
  SDIOEMB_CMD_ERR_DAT = 0x02,
  SDIOEMB_CMD_ERR_CRC = 0x10,
  SDIOEMB_CMD_ERR_TIMEOUT = 0x20,
  SDIOEMB_CMD_ERR_OTHER = 0x40,
  SDIOEMB_CMD_ERR_CMD_CRC = SDIOEMB_CMD_ERR_CMD | SDIOEMB_CMD_ERR_CRC,
  SDIOEMB_CMD_ERR_CMD_TIMEOUT = SDIOEMB_CMD_ERR_CMD | SDIOEMB_CMD_ERR_TIMEOUT,
  SDIOEMB_CMD_ERR_CMD_OTHER = SDIOEMB_CMD_ERR_CMD | SDIOEMB_CMD_ERR_OTHER,
  SDIOEMB_CMD_ERR_DAT_CRC = SDIOEMB_CMD_ERR_DAT | SDIOEMB_CMD_ERR_CRC,
  SDIOEMB_CMD_ERR_DAT_TIMEOUT = SDIOEMB_CMD_ERR_DAT | SDIOEMB_CMD_ERR_TIMEOUT,
  SDIOEMB_CMD_ERR_DAT_OTHER = SDIOEMB_CMD_ERR_DAT | SDIOEMB_CMD_ERR_OTHER,
  SDIOEMB_CMD_ERR_NO_CARD = 0x04,
  SDIOEMB_CMD_IN_PROGRESS = 0xff
}

Functions

int sdioemb_hard_reset (struct sdioemb_dev *fdev)
int sdioemb_cis_get_tuple (struct sdioemb_dev *fdev, uint8_t tuple, void *buf, size_t len)
int sdioemb_start_cmd (struct sdioemb_dev *fdev, struct sdioemb_cmd *cmd)
int sdioemb_driver_register (struct sdioemb_func_driver *fdriver)
void sdioemb_driver_unregister (struct sdioemb_func_driver *fdriver)
int sdioemb_enable_function (struct sdioemb_dev *fdev)
int sdioemb_disable_function (struct sdioemb_dev *fdev)
int sdioemb_reenable_csr_function (struct sdioemb_dev *fdev)
int sdioemb_set_block_size (struct sdioemb_dev *fdev, uint16_t blksz)
void sdioemb_idle_function (struct sdioemb_dev *fdev)
void sdioemb_set_max_bus_freq (struct sdioemb_dev *fdev, int max_freq)
int sdioemb_set_bus_width (struct sdioemb_dev *fdev, int bus_width)
int sdioemb_interrupt_enable (struct sdioemb_dev *fdev)
int sdioemb_interrupt_disable (struct sdioemb_dev *fdev)
void sdioemb_interrupt_acknowledge (struct sdioemb_dev *fdev)
int sdioemb_read8 (struct sdioemb_dev *fdev, uint32_t addr, uint8_t *val)
int sdioemb_read16 (struct sdioemb_dev *fdev, uint32_t addr, uint16_t *val)
int sdioemb_write8 (struct sdioemb_dev *fdev, uint32_t addr, uint8_t val)
int sdioemb_write16 (struct sdioemb_dev *fdev, uint32_t addr, uint16_t val)
int sdioemb_f0_read8 (struct sdioemb_dev *fdev, uint32_t addr, uint8_t *val)
int sdioemb_f0_write8 (struct sdioemb_dev *fdev, uint32_t addr, uint8_t val)
int sdioemb_read (struct sdioemb_dev *fdev, uint32_t addr, void *data, size_t len)
int sdioemb_write (struct sdioemb_dev *fdev, uint32_t addr, const void *data, size_t len)
void sdioemb_power_on (struct sdioemb_dev *fdev)
void sdioemb_power_off (struct sdioemb_dev *fdev)
void sdioemb_suspend_function (struct sdioemb_dev *fdev)
void sdioemb_resume_function (struct sdioemb_dev *fdev)

Detailed Description

The SDIO function driver API is used to implement drivers for SDIO card functions.

Function drivers register with the SDIO driver core (sdio_register_driver()), listing which functions it supports and providing callback functions for card inserts, removes and interrupts.

Card I/O operations:

Define Documentation

#define SDIOEMB_CMD_FLAG_ABORT   0x0800

Data transfer abort command.

#define SDIOEMB_CMD_FLAG_CSPI   0x0400

CSPI transfer, not SDIO or SDIO-SPI.

#define SDIOEMB_CMD_FLAG_READ   0x0200

Data transfer is a read, not a write.

#define SDIOEMB_CMD_FLAG_RESP_MASK   0xff

Mask for response type.

#define SDIOEMB_CMD_FLAG_RESP_NONE   0x00

No response.

#define SDIOEMB_CMD_FLAG_RESP_R1   0x01

R1 response.

#define SDIOEMB_CMD_FLAG_RESP_R1B   0x02

R1b response.

#define SDIOEMB_CMD_FLAG_RESP_R2   0x03

R2 response.

#define SDIOEMB_CMD_FLAG_RESP_R3   0x04

R3 response.

#define SDIOEMB_CMD_FLAG_RESP_R4   0x05

R4 response.

#define SDIOEMB_CMD_FLAG_RESP_R5   0x06

R5 response.

#define SDIOEMB_CMD_FLAG_RESP_R5B   0x07

R5b response.

#define SDIOEMB_CMD_FLAG_RESP_R6   0x08

R6 response.


Enumeration Type Documentation

SDIO command status.

Enumerator:
SDIOEMB_CMD_OK  Command successful.
SDIOEMB_CMD_ERR_CMD_CRC  Response CRC error.
SDIOEMB_CMD_ERR_CMD_TIMEOUT  Response time out.
SDIOEMB_CMD_ERR_CMD_OTHER  Other response error.
SDIOEMB_CMD_ERR_DAT_CRC  Data CRC error.
SDIOEMB_CMD_ERR_DAT_TIMEOUT  Data receive time out.
SDIOEMB_CMD_ERR_DAT_OTHER  Other data error.
SDIOEMB_CMD_ERR_NO_CARD  No card present.
SDIOEMB_CMD_IN_PROGRESS  Command still in progress.


Function Documentation

int sdioemb_cis_get_tuple ( struct sdioemb_dev fdev,
uint8_t  tuple,
void *  buf,
size_t  len 
)

Read a CIS tuple.

Copies the specified function's CIS tuple into a buffer. The tuple ID and link pointer are not copied.

Parameters:
fdev function to read CIS from.
tuple ID of tuple to find.
buf destination buffer for tuple data.
len length of buf.
Returns:
0 on success; -ve on error: -ENXIO - no such tuple found, -EINVAL - buffer is shorter than the tuple, -EIO,-ETIMEDOUT - I/O error while reading from card.

References sdioemb_dev::priv, and sdioemb_f0_read8().

int sdioemb_disable_function ( struct sdioemb_dev fdev  ) 

Disable the function.

The function's I/O Enable bit is cleared.

Callable from: thread context.

Parameters:
fdev the SDIO device to disable.
Returns:
0 on success; -ve on error: -EIO or -ETIMEDOUT - a register access failed.
Bug:
To permit a disable/enable sequence to be used as a per-function reset, disabling a function should wait for I/O Ready to be cleared.

References sdioemb_dev::function, sdioemb_dev::priv, sdioemb_f0_read8(), and sdioemb_f0_write8().

int sdioemb_driver_register ( struct sdioemb_func_driver fdriver  ) 

Register a function driver with the core.

If any inserted cards that have functions that match fdriver's list of supported functions then fdriver's probe() function will be called for those functions.

Parameters:
fdriver the function driver to register.
Returns:
0 on success; -ve on error: -ENOMEM - maximum number of function drivers are already registered.

References sdioemb_func_driver::name, SDIOEMB_FDEVS_MAX, and SDIOEMB_FDRIVERS_MAX.

void sdioemb_driver_unregister ( struct sdioemb_func_driver fdriver  ) 

Unregister a function driver from the core.

fdriver's remove() will be called for any SDIO devices currently attached to the driver.

Parameters:
fdriver the function driver to unregister.

References sdioemb_dev::driver, sdioemb_func_driver::name, SDIOEMB_FDEVS_MAX, and SDIOEMB_FDRIVERS_MAX.

int sdioemb_enable_function ( struct sdioemb_dev fdev  ) 

Enable the function.

The function's I/O Enable bit is set and I/O Ready is polled until it is set.

Callable from: thread context.

Parameters:
fdev the SDIO device to enable.
Returns:
0 on success; -ve on error: -ETIMEDOUT - time out waiting for I/O Ready to be set, -EIO or -ETIMEDOUT - a register access failed.

References sdioemb_dev::function, sdioemb_dev::priv, sdioemb_f0_read8(), and sdioemb_f0_write8().

int sdioemb_f0_read8 ( struct sdioemb_dev fdev,
uint32_t  addr,
uint8_t *  val 
)

Read an 8 bit wide function 0 register.

Parameters:
fdev an SDIO function of the card.
addr register address.
val returns the value read.
Returns:
0 on success.

-EIO if a low-level transport error occurred (e.g., CRC error),

-ETIMEDOUT if no response was received.

References sdioemb_dev::priv.

Referenced by sdioemb_cis_get_tuple(), sdioemb_disable_function(), sdioemb_enable_function(), and sdioemb_reenable_csr_function().

int sdioemb_f0_write8 ( struct sdioemb_dev fdev,
uint32_t  addr,
uint8_t  val 
)

Write an 8 bit wide function 0 register.

Parameters:
fdev an SDIO function of the card.
addr register address.
val value to write.
Returns:
0 on success.

-EIO if a low-level transport error occurred (e.g., CRC error),

-ETIMEDOUT if no response was received.

References sdioemb_dev::priv.

Referenced by sdioemb_disable_function(), sdioemb_enable_function(), and sdioemb_reenable_csr_function().

int sdioemb_hard_reset ( struct sdioemb_dev fdev  ) 

Perform a hard reset of the card (if the slot is capable) and reinitialize the card.

Parameters:
fdev an SDIO device of the card.
Returns:
0 if a hard reset was performed and the card successfully reinitialized.

1 if the slot is not capable of hard resets.

-ve if the reinitialization failed.

References sdioemb_slot::hard_reset, sdioemb_slot::priv, and sdioemb_dev::priv.

void sdioemb_idle_function ( struct sdioemb_dev fdev  ) 

Set the function as idle.

When all functions are idle the SD bus will be idled.

Functions are set as active (non-idle) when a command is started.

Parameters:
fdev the SDIO device to set as idle.
See also:
slot_driver::idle_bus.

References sdioemb_dev::function, sdioemb_slot::priv, and sdioemb_dev::priv.

void sdioemb_interrupt_acknowledge ( struct sdioemb_dev fdev  ) 

Acknowledge an SDIO interrupt.

Function drivers should acknowledge interrupts when they have either:

1. Cleared the interrupt source.

2. Disabled interrupts with sdioemb_interrupt_disable().

3. Determined that the interrupt was for a different function.

Callable from: thread context.

Parameters:
fdev the function acknowledging the interrupt.

References sdioemb_slot::enable_card_int, sdioemb_dev::function, sdioemb_slot::priv, and sdioemb_dev::priv.

Referenced by sdioemb_power_off().

int sdioemb_interrupt_disable ( struct sdioemb_dev fdev  ) 

Disable SDIO interrupts for a function.

Interrupts are disable by clearing the function's enable bit in the Int Enable CCCR register.

Callable from: thread context.

Parameters:
fdev the SDIO function to disable interrupts for.
Returns:
0 on success.

-ETIMEDOUT or -EIO if the Int Enable register write failed.

See also:
sdioemb_interrupt_enable().

References sdioemb_dev::function, sdioemb_slot::priv, and sdioemb_dev::priv.

Referenced by sdioemb_power_off().

int sdioemb_interrupt_enable ( struct sdioemb_dev fdev  ) 

Enable SDIO interrupts for a function.

Interrupts are enabled by writing the function's enable bit in the Int Enable CCCR register.

Callable from: thread context.

Parameters:
fdev the SDIO function to enable interrupts for.
Returns:
0 on success.

-ETIMEDOUT or -EIO if the Int Enable register write failed.

References sdioemb_dev::function, sdioemb_slot::priv, and sdioemb_dev::priv.

void sdioemb_power_off ( struct sdioemb_dev fdev  ) 

Allow the card to be powered off.

If no other function is requesting power, the card is powered off. The driver must call sdioemb_power_on() before performing any more I/O to the card.

Interrupts are disabled by calling sdioemb_interrupt_disable() as the DAT1/INT line may no longer be pulled high when power is removed. If there is an unhandled interrupt it is acknowledged with sdioemb_interrupt_acknowledge() as it may have been for this function.

This is called by the core after calling a function driver's remove() method.

Parameters:
fdev the SDIO device not requiring power.

References sdioemb_dev::function, sdioemb_slot::priv, sdioemb_dev::priv, sdioemb_interrupt_acknowledge(), and sdioemb_interrupt_disable().

void sdioemb_power_on ( struct sdioemb_dev fdev  ) 

Request power to the card.

If the card is not powered, apply power and re-initialize the card. No per-function state of the card is restored and the driver should re-enable the function and perform any other function specific initialization.

This is called by the core before calling a function driver's probe() method.

Parameters:
fdev the SDIO device requesting power.

References sdioemb_dev::function, sdioemb_slot::priv, and sdioemb_dev::priv.

int sdioemb_read ( struct sdioemb_dev fdev,
uint32_t  addr,
void *  data,
size_t  len 
)

Read a buffer from an 8 bit wide card register/FIFO.

Parameters:
fdev SDIO function to read from.
addr register/FIFO address.
data buffer to store the data read.
len length of the buffer.
Returns:
0 on success.

-EIO if a low-level transport error occurred (e.g., CRC error).

-ETIMEDOUT if no response or data was received.

References sdioemb_dev::function, and sdioemb_dev::priv.

int sdioemb_read16 ( struct sdioemb_dev fdev,
uint32_t  addr,
uint16_t *  val 
)

Read a 16 bit wide register.

If the physical transport supports native 16 bit accesses (i.e., CSPI) these are used. Otherwise, the lower octet is read from addr and the the upper octet is read from addr + 1.

Parameters:
fdev SDIO function to read from.
addr register address.
val returns the value read.
Returns:
0 on success.

-EIO if a low-level transport error occurred (e.g., CRC error),

-ETIMEDOUT if no response was received.

References sdioemb_dev::function, and sdioemb_dev::priv.

int sdioemb_read8 ( struct sdioemb_dev fdev,
uint32_t  addr,
uint8_t *  val 
)

Read an 8 bit wide register.

Parameters:
fdev SDIO function to read from.
addr register address.
val returns the value read.
Returns:
0 on success.

-EIO if a low-level transport error occurred (e.g., CRC error),

-ETIMEDOUT if no response was received.

References sdioemb_dev::function, and sdioemb_dev::priv.

int sdioemb_reenable_csr_function ( struct sdioemb_dev fdev  ) 

Reenable a function on a CSR card.

This reenables a function that was disabled due to a watchdog (or similar) reset.

Parameters:
fdev the SDIO function to reenable.
See also:
[CS-122272-SP] CSPI Specification, section 6.

References sdioemb_dev::function, SDIO_CSR_EXT_IO_EN, sdioemb_f0_read8(), and sdioemb_f0_write8().

void sdioemb_resume_function ( struct sdioemb_dev fdev  ) 

Resume an SDIO function.

This puts an SDIO Function into an operational (D0) power state. The function driver's resume() callback will be called.

If the function driver doesn't provide a resume callback, the function is powered on with sdioemb_power_on().

See sdioemb_suspend_function() for notes on when this is required.

Parameters:
fdev the function to resume.

int sdioemb_set_block_size ( struct sdioemb_dev fdev,
uint16_t  blksz 
)

Set a function's block size.

The default block size is the largest supported by both the function and the host, with a maximum of 512 to ensure that arbitrarily sized data transfers use the optimal (least) number of commands.

A driver may call this to override the default block size set by the core. This can be used to set a block size greater than the maximum that reported by the card; it is the driver's responsibility to ensure it uses a value that the card supports.

Callable from: thread context.

Parameters:
fdev the SDIO device.
blksz new block size or 0 to use the default.
Returns:
0 on success; -ve on error: -EIO or -ETIMEDOUT - a register access failed.

References sdioemb_dev::priv.

int sdioemb_set_bus_width ( struct sdioemb_dev fdev,
int  bus_width 
)

Set the SDIO bus to 1 bit or 4 bit mode.

Callable from: thread context.

Parameters:
fdev the SDIO device.
bus_width the bus width (1 or 4).
Returns:
0 on success (or if the slot is in SPI mode).

-EINVAL if the slot doesn't support the requested mode.

-EIO, -ETIMEDOUT if an I/O error occured when writing the mode to the card.

References sdioemb_slot::caps, slot_caps::max_bus_width, sdioemb_slot::priv, sdioemb_dev::priv, SDIOEMB_SLOT_TYPE_SD, and sdioemb_slot::type.

void sdioemb_set_max_bus_freq ( struct sdioemb_dev fdev,
int  max_freq 
)

Limit the bus frequency supported by a function.

The bus frequency used will be the minimum of:

  • the speed reported by the card,
  • the maximum the slot can support,
  • the value set by this function for any of the card's functions.

If the frequency to be used is high speed (> 25 MHz), high speed mode will be enabled on the card.

Callable from: thread context.

Parameters:
fdev the SDIO device.
max_freq maximum frequency in Hz, or 0 for the maximum reported by the card.

References sdioemb_slot::priv, and sdioemb_dev::priv.

int sdioemb_start_cmd ( struct sdioemb_dev fdev,
struct sdioemb_cmd cmd 
)

Submit an SDIO command to a device.

The command will be started if the slot is not busy with another command, otherwise it is queued and will be executed later.

The queue has enough space for 2 commands per SDIO function.

Parameters:
fdev the SDIO device submitting the command.
cmd the command to submit.
Returns:
0 if the command was queued.

-EAGAIN if the command queue is full.

-EINVAL if the data transfer is invalid (unsupported buffer alignment or the length is not a valid byte or block mode transfer).

See also:
sdio_dev::io

References sdioemb_dev::blocksize, sdioemb_cmd::data, sdioemb_dev::function, sdioemb_cmd::len, sdioemb_slot::name, sdioemb_cmd::owner, and sdioemb_dev::priv.

void sdioemb_suspend_function ( struct sdioemb_dev fdev  ) 

Suspend an SDIO function.

This puts an SDIO Function into a low power (D1/D2) state. The function driver's suspend() callback will be called.

If the function driver doesn't provide a suspend callback, the function is powered off with sdioemb_power_off().

A suspended function may be resumed by calling sdioemb_resume_function().

Note:
This is useful on some platforms (e.g., Windows) where the power management events are sent to child devices (the function) before the parent device (the slot). On platforms where power management events are sent to parent devices first (e.g., Linux) then calling this function is not required.
Parameters:
fdev the function to suspend.

int sdioemb_write ( struct sdioemb_dev fdev,
uint32_t  addr,
const void *  data,
size_t  len 
)

Writes a buffer to an 8 bit wide card register/FIFO.

Parameters:
fdev SDIO function to write to.
addr register/FIFO address.
data buffer of data to write.
len length of the buffer.
Returns:
0 on success.

-EIO if a low-level transport error occurred (e.g., CRC error).

-ETIMEDOUT if no response was received.

References sdioemb_dev::function, and sdioemb_dev::priv.

int sdioemb_write16 ( struct sdioemb_dev fdev,
uint32_t  addr,
uint16_t  val 
)

Write a 16 bit wide register.

If the physical transport supports native 16 bit accesses (i.e., CSPI) these are used. Otherwise, the upper octet is written to addr + 1 and then the lower octet is written to addr.

Parameters:
fdev SDIO function to write to.
addr register address.
val value to write.
Returns:
0 on success.

-EIO if a low-level transport error occurred (e.g., CRC error),

-ETIMEDOUT if no response was received.

References sdioemb_dev::function, and sdioemb_dev::priv.

int sdioemb_write8 ( struct sdioemb_dev fdev,
uint32_t  addr,
uint8_t  val 
)

Write an 8 bit wide register.

Parameters:
fdev SDIO function to write to.
addr register address.
val value to write.
Returns:
0 on success.

-EIO if a low-level transport error occurred (e.g., CRC error),

-ETIMEDOUT if no response was received.

References sdioemb_dev::function, and sdioemb_dev::priv.


Generated on Wed Oct 27 15:18:12 2010 for sdioemb by  doxygen 1.5.5