Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
SPI

SPI peripheral driver for Quark Microcontrollers. More...

Data Structures

struct  qm_spi_async_transfer_t
 SPI aynchronous transfer type. More...
 
struct  qm_spi_transfer_t
 SPI synchronous transfer type. More...
 

Enumerations

enum  qm_spi_frame_size_t {
  QM_SPI_FRAME_SIZE_4_BIT = 3, QM_SPI_FRAME_SIZE_5_BIT, QM_SPI_FRAME_SIZE_6_BIT, QM_SPI_FRAME_SIZE_7_BIT,
  QM_SPI_FRAME_SIZE_8_BIT, QM_SPI_FRAME_SIZE_9_BIT, QM_SPI_FRAME_SIZE_10_BIT, QM_SPI_FRAME_SIZE_11_BIT,
  QM_SPI_FRAME_SIZE_12_BIT, QM_SPI_FRAME_SIZE_13_BIT, QM_SPI_FRAME_SIZE_14_BIT, QM_SPI_FRAME_SIZE_15_BIT,
  QM_SPI_FRAME_SIZE_16_BIT, QM_SPI_FRAME_SIZE_17_BIT, QM_SPI_FRAME_SIZE_18_BIT, QM_SPI_FRAME_SIZE_19_BIT,
  QM_SPI_FRAME_SIZE_20_BIT, QM_SPI_FRAME_SIZE_21_BIT, QM_SPI_FRAME_SIZE_22_BIT, QM_SPI_FRAME_SIZE_23_BIT,
  QM_SPI_FRAME_SIZE_24_BIT, QM_SPI_FRAME_SIZE_25_BIT, QM_SPI_FRAME_SIZE_26_BIT, QM_SPI_FRAME_SIZE_27_BIT,
  QM_SPI_FRAME_SIZE_28_BIT, QM_SPI_FRAME_SIZE_29_BIT, QM_SPI_FRAME_SIZE_30_BIT, QM_SPI_FRAME_SIZE_31_BIT,
  QM_SPI_FRAME_SIZE_32_BIT
}
 QM SPI frame size type. More...
 
enum  qm_spi_tmode_t { QM_SPI_TMOD_TX_RX, QM_SPI_TMOD_TX, QM_SPI_TMOD_RX, QM_SPI_TMOD_EEPROM_READ }
 SPI transfer mode type. More...
 
enum  qm_spi_bmode_t { QM_SPI_BMODE_0, QM_SPI_BMODE_1, QM_SPI_BMODE_2, QM_SPI_BMODE_3 }
 SPI bus mode type. More...
 
enum  qm_spi_slave_select_t {
  QM_SPI_SS_DISABLED = 0, QM_SPI_SS_0 = BIT(0), QM_SPI_SS_1 = BIT(1), QM_SPI_SS_2 = BIT(2),
  QM_SPI_SS_3 = BIT(3)
}
 SPI slave select type. More...
 
enum  qm_spi_status_t {
  QM_SPI_IDLE, QM_SPI_BUSY, QM_SPI_RX_OVERFLOW, QM_SPI_RX_FULL,
  QM_SPI_TX_EMPTY
}
 SPI status. More...
 
enum  qm_spi_frame_format_t { QM_SPI_FRAME_FORMAT_STANDARD = 0x0 }
 QM SPI Frame Format. More...
 

Functions

int qm_spi_set_config (const qm_spi_t spi, const qm_spi_config_t *const cfg)
 Set SPI configuration. More...
 
int qm_spi_slave_select (const qm_spi_t spi, const qm_spi_slave_select_t ss)
 Select which slave to perform SPI transmissions on. More...
 
int qm_spi_get_status (const qm_spi_t spi, qm_spi_status_t *const status)
 Get SPI bus status. More...
 
int qm_spi_transfer (const qm_spi_t spi, const qm_spi_transfer_t *const xfer, qm_spi_status_t *const status)
 Multi-frame read / write on SPI. More...
 
int qm_spi_irq_transfer (const qm_spi_t spi, volatile const qm_spi_async_transfer_t *const xfer)
 Interrupt based transfer on SPI. More...
 
int qm_spi_irq_update (const qm_spi_t spi, volatile const qm_spi_async_transfer_t *const xfer, const qm_spi_update_t update)
 Update parameters of Interrupt based transfer on SPI. More...
 
int qm_spi_dma_channel_config (const qm_spi_t spi, const qm_dma_t dma_ctrl_id, const qm_dma_channel_id_t dma_channel_id, const qm_dma_channel_direction_t dma_channel_direction)
 Configure a DMA channel with a specific transfer direction. More...
 
int qm_spi_dma_transfer (const qm_spi_t spi, const qm_spi_async_transfer_t *const xfer)
 Perform a DMA-based transfer on the SPI bus. More...
 
int qm_spi_irq_transfer_terminate (const qm_spi_t spi)
 Terminate SPI IRQ transfer. More...
 
int qm_spi_dma_transfer_terminate (const qm_spi_t spi)
 Terminate the current DMA transfer on the SPI bus. More...
 
int qm_spi_save_context (const qm_spi_t spi, qm_spi_context_t *const ctx)
 Save SPI context. More...
 
int qm_spi_restore_context (const qm_spi_t spi, const qm_spi_context_t *const ctx)
 Restore SPI context. More...
 

Detailed Description

SPI peripheral driver for Quark Microcontrollers.

Enumeration Type Documentation

SPI bus mode type.

Enumerator
QM_SPI_BMODE_0 

Clock Polarity = 0, Clock Phase = 0.

QM_SPI_BMODE_1 

Clock Polarity = 0, Clock Phase = 1.

QM_SPI_BMODE_2 

Clock Polarity = 1, Clock Phase = 0.

QM_SPI_BMODE_3 

Clock Polarity = 1, Clock Phase = 1.

Definition at line 67 of file qm_spi.h.

QM SPI Frame Format.

Enumerator
QM_SPI_FRAME_FORMAT_STANDARD 

Standard SPI mode.

Definition at line 103 of file qm_spi.h.

QM SPI frame size type.

Enumerator
QM_SPI_FRAME_SIZE_4_BIT 

4 bit frame.

QM_SPI_FRAME_SIZE_5_BIT 

5 bit frame.

QM_SPI_FRAME_SIZE_6_BIT 

6 bit frame.

QM_SPI_FRAME_SIZE_7_BIT 

7 bit frame.

QM_SPI_FRAME_SIZE_8_BIT 

8 bit frame.

QM_SPI_FRAME_SIZE_9_BIT 

9 bit frame.

QM_SPI_FRAME_SIZE_10_BIT 

10 bit frame.

QM_SPI_FRAME_SIZE_11_BIT 

11 bit frame.

QM_SPI_FRAME_SIZE_12_BIT 

12 bit frame.

QM_SPI_FRAME_SIZE_13_BIT 

13 bit frame.

QM_SPI_FRAME_SIZE_14_BIT 

14 bit frame.

QM_SPI_FRAME_SIZE_15_BIT 

15 bit frame.

QM_SPI_FRAME_SIZE_16_BIT 

16 bit frame.

QM_SPI_FRAME_SIZE_17_BIT 

17 bit frame.

QM_SPI_FRAME_SIZE_18_BIT 

18 bit frame.

QM_SPI_FRAME_SIZE_19_BIT 

19 bit frame.

QM_SPI_FRAME_SIZE_20_BIT 

20 bit frame.

QM_SPI_FRAME_SIZE_21_BIT 

21 bit frame.

QM_SPI_FRAME_SIZE_22_BIT 

22 bit frame.

QM_SPI_FRAME_SIZE_23_BIT 

23 bit frame.

QM_SPI_FRAME_SIZE_24_BIT 

24 bit frame.

QM_SPI_FRAME_SIZE_25_BIT 

25 bit frame.

QM_SPI_FRAME_SIZE_26_BIT 

26 bit frame.

QM_SPI_FRAME_SIZE_27_BIT 

27 bit frame.

QM_SPI_FRAME_SIZE_28_BIT 

28 bit frame.

QM_SPI_FRAME_SIZE_29_BIT 

29 bit frame.

QM_SPI_FRAME_SIZE_30_BIT 

30 bit frame.

QM_SPI_FRAME_SIZE_31_BIT 

31 bit frame.

QM_SPI_FRAME_SIZE_32_BIT 

32 bit frame.

Definition at line 22 of file qm_spi.h.

SPI slave select type.

Slave selects can combined by logical OR if multiple slaves are selected during one transfer. Setting only QM_SPI_SS_DISABLED prevents the controller from starting the transfer.

Enumerator
QM_SPI_SS_DISABLED 

Slave select disable.

QM_SPI_SS_0 

Slave Select 0.

QM_SPI_SS_1 

Slave Select 1.

QM_SPI_SS_2 

Slave Select 2.

QM_SPI_SS_3 

Slave Select 3.

Definition at line 81 of file qm_spi.h.

SPI status.

Enumerator
QM_SPI_IDLE 

SPI device is not in use.

QM_SPI_BUSY 

SPI device is busy.

QM_SPI_RX_OVERFLOW 

RX transfer has overflown.

QM_SPI_RX_FULL 

Appl.

Rx buffer full (slave only).

QM_SPI_TX_EMPTY 

Appl.

Tx buffer empty (slave only) .

Definition at line 92 of file qm_spi.h.

SPI transfer mode type.

Enumerator
QM_SPI_TMOD_TX_RX 

Transmit & Receive.

QM_SPI_TMOD_TX 

Transmit Only.

QM_SPI_TMOD_RX 

Receive Only.

QM_SPI_TMOD_EEPROM_READ 

EEPROM Read.

Definition at line 57 of file qm_spi.h.

Function Documentation

int qm_spi_dma_channel_config ( const qm_spi_t  spi,
const qm_dma_t  dma_ctrl_id,
const qm_dma_channel_id_t  dma_channel_id,
const qm_dma_channel_direction_t  dma_channel_direction 
)

Configure a DMA channel with a specific transfer direction.

The user is responsible for managing the allocation of the pool of DMA channels provided by each DMA core to the different peripheral drivers that require them.

Note that a SPI controller cannot use different DMA cores to manage transfers in different directions.

This function configures DMA channel parameters that are unlikely to change between transfers, like transaction width, burst size, and handshake interface parameters. The user will likely only call this function once for the lifetime of an application unless the channel needs to be repurposed.

This function configures the DMA source transfer width according to the currently set SPI frame size. Therefore, whenever the SPI frame is updated (using qm_spi_set_config) this function needs to be called again as the previous source transfer width configuration is no longer valid. Note that if the current frame size lies between 17 and 24 bits, this function fails (returning -EINVAL) as the DMA core cannot handle 3-byte source width transfers with buffers containing 1 padding byte between consecutive frames.

Note that qm_dma_init() must first be called before configuring a channel.

Parameters
[in]spiSPI controller identifier.
[in]dma_ctrl_idDMA controller identifier.
[in]dma_channel_idDMA channel identifier.
[in]dma_channel_directionDMA channel direction, either QM_DMA_MEMORY_TO_PERIPHERAL (TX transfer) or QM_DMA_PERIPHERAL_TO_MEMORY (RX transfer).
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 851 of file qm_spi.c.

References qm_dma_channel_config_t::callback_context, qm_dma_channel_config_t::channel_direction, qm_dma_channel_config_t::client_callback, qm_dma_channel_config_t::destination_burst_length, qm_dma_channel_config_t::destination_transfer_width, DMA_HW_IF_SPI_MASTER_0_RX, DMA_HW_IF_SPI_MASTER_0_TX, DMA_HW_IF_SPI_MASTER_1_RX, DMA_HW_IF_SPI_MASTER_1_TX, qm_dma_channel_config_t::handshake_interface, qm_dma_channel_config_t::handshake_polarity, QM_DMA_CHANNEL_NUM, qm_dma_channel_set_config(), QM_DMA_HANDSHAKE_POLARITY_HIGH, QM_DMA_MEMORY_TO_PERIPHERAL, QM_DMA_NUM, QM_DMA_PERIPHERAL_TO_MEMORY, QM_DMA_TRANS_WIDTH_16, QM_DMA_TRANS_WIDTH_32, QM_DMA_TRANS_WIDTH_8, QM_DMA_TYPE_SINGLE, qm_dma_channel_config_t::source_burst_length, qm_dma_channel_config_t::source_transfer_width, and qm_dma_channel_config_t::transfer_type.

int qm_spi_dma_transfer ( const qm_spi_t  spi,
const qm_spi_async_transfer_t *const  xfer 
)

Perform a DMA-based transfer on the SPI bus.

If transfer mode is full duplex (QM_SPI_TMOD_TX_RX), then tx_len and rx_len must be equal. Similarly, for transmit-only transfers (QM_SPI_TMOD_TX) rx_len must be 0 while for receive-only transfers (QM_SPI_TMOD_RX) tx_len must be 0. Transfer length is limited to 4KB.

For starting a transfer, this controller demands at least one slave select line (SS) to be enabled. Thus, a call to qm_spi_slave_select() with one of the four SS valid lines is mandatory. This is true even if the native slave select line is not used (i.e. when a GPIO is used to drive the SS signal manually).

Note that qm_spi_dma_channel_config() must first be called in order to configure all DMA channels needed for a transfer.

Parameters
[in]spiSPI controller identifier.
[in]xferStructure containing pre-allocated write and read data buffers and callback functions. This must not be NULL and must be kept valid until the transfer is complete.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 955 of file qm_spi.c.

References qm_dma_transfer_t::block_size, qm_spi_reg_t::ctrlr1, qm_dma_transfer_t::destination_address, qm_spi_reg_t::dmacr, qm_spi_reg_t::dmardlr, qm_spi_reg_t::dmatdlr, qm_spi_reg_t::dr, qm_spi_reg_t::imr, QM_DMA_CHANNEL_NUM, QM_DMA_NUM, qm_dma_transfer_set_config(), qm_dma_transfer_start(), qm_spi_dma_transfer_terminate(), QM_SPI_TMOD_EEPROM_READ, QM_SPI_TMOD_RX, QM_SPI_TMOD_TX, QM_SPI_TMOD_TX_RX, qm_spi_async_transfer_t::rx, qm_spi_async_transfer_t::rx_len, qm_dma_transfer_t::source_address, qm_spi_reg_t::ssienr, qm_spi_async_transfer_t::tx, and qm_spi_async_transfer_t::tx_len.

int qm_spi_dma_transfer_terminate ( const qm_spi_t  spi)

Terminate the current DMA transfer on the SPI bus.

Terminate the current DMA transfer on the SPI bus. This will cause the relevant callbacks to be invoked.

Parameters
[in]spiSPI controller identifier.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 1094 of file qm_spi.c.

References QM_DMA_CHANNEL_NUM, and qm_dma_transfer_terminate().

Referenced by qm_spi_dma_transfer().

int qm_spi_get_status ( const qm_spi_t  spi,
qm_spi_status_t *const  status 
)

Get SPI bus status.

Retrieve SPI bus status. Return QM_SPI_BUSY if transmitting data or SPI TX FIFO not empty; QM_SPI_IDLE is available for transfer; QM_SPI_RX_OVERFLOW if an RX overflow has occurred.

The user may call this function before performing an SPI transfer in order to guarantee that the SPI interface is available.

Parameters
[in]spiWhich SPI to read the status of.
[out]statusCurrent SPI status. This must not be null.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 479 of file qm_spi.c.

References QM_SPI_BUSY, QM_SPI_IDLE, QM_SPI_RX_OVERFLOW, qm_spi_reg_t::risr, and qm_spi_reg_t::sr.

int qm_spi_irq_transfer ( const qm_spi_t  spi,
volatile const qm_spi_async_transfer_t *const  xfer 
)

Interrupt based transfer on SPI.

Perform an interrupt based transfer on the SPI bus. The function will replenish/empty TX/RX FIFOs on SPI empty/full interrupts. If transfer mode is full duplex (QM_SPI_TMOD_TX_RX), then tx_len and rx_len must be equal. For transmit-only transfers (QM_SPI_TMOD_TX) rx_len must be 0 while for receive-only transfers (QM_SPI_TMOD_RX) tx_len must be 0.

For starting a transfer, this controller demands at least one slave select line (SS) to be enabled. Thus, a call to qm_spi_slave_select() with one of the four SS valid lines is mandatory. This is true even if the native slave select line is not used (i.e. when a GPIO is used to drive the SS signal manually).

Parameters
[in]spiWhich SPI to transfer to / from.
[in]xferTransfer structure includes write / read buffers, length, user callback function and the callback context data. The structure must not be NULL and must be kept valid until the transfer is complete.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 639 of file qm_spi.c.

References qm_spi_reg_t::ctrlr0, qm_spi_reg_t::ctrlr1, QM_SPI_FRAME_FORMAT_STANDARD, qm_spi_irq_update(), QM_SPI_TMOD_EEPROM_READ, QM_SPI_TMOD_RX, QM_SPI_TMOD_TX, QM_SPI_TMOD_TX_RX, qm_spi_async_transfer_t::rx_len, qm_spi_reg_t::rxftlr, qm_spi_reg_t::ssienr, qm_spi_async_transfer_t::tx_len, and qm_spi_reg_t::txftlr.

int qm_spi_irq_transfer_terminate ( const qm_spi_t  spi)

Terminate SPI IRQ transfer.

Terminate the current IRQ transfer on the SPI bus. This will cause the user callback to be called with error code set to -ECANCELED.

Parameters
[in]spiWhich SPI to cancel the current transfer.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 736 of file qm_spi.c.

References qm_spi_async_transfer_t::callback, qm_spi_async_transfer_t::callback_data, qm_spi_reg_t::imr, QM_SPI_IDLE, QM_SPI_TMOD_TX, qm_spi_reg_t::ssienr, and qm_spi_reg_t::txflr.

int qm_spi_irq_update ( const qm_spi_t  spi,
volatile const qm_spi_async_transfer_t *const  xfer,
const qm_spi_update_t  update 
)

Update parameters of Interrupt based transfer on SPI.

Allow the application to transmit and/or receive more data over the current SPI communication. The application is supposed to call this function only inside the registered callback, once notified from the driver. It is strongly recommended to use this function for slave-based applications only, as slave controllers usually do not know how many frames an external master will send or request before starting the communication. Master controllers should not use this function as it will most likely corrupt the transaction.

Parameters
[in]spiWhich SPI to transfer to / from.
[in]xferTransfer structure includes write / read buffers, length, user callback function and the callback context data. The structure must not be NULL and must be kept valid until the transfer is complete.
[in]updateSpecify if only RX has to be updated, or only TX or both.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 584 of file qm_spi.c.

References qm_spi_reg_t::imr, QM_SPI_FRAME_FORMAT_STANDARD, QM_SPI_TMOD_EEPROM_READ, QM_SPI_TMOD_RX, QM_SPI_TMOD_TX, qm_spi_async_transfer_t::rx_len, and qm_spi_async_transfer_t::tx_len.

Referenced by qm_spi_irq_transfer().

int qm_spi_restore_context ( const qm_spi_t  spi,
const qm_spi_context_t *const  ctx 
)

Restore SPI context.

Restore the configuration of the specified SPI peripheral after exiting sleep.

Parameters
[in]spiSPI controller identifier.
[in]ctxSPI context structure. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 1165 of file qm_spi.c.

References qm_spi_reg_t::baudr, qm_spi_context_t::baudr, qm_spi_reg_t::ctrlr0, qm_spi_context_t::ctrlr0, qm_spi_reg_t::ser, and qm_spi_context_t::ser.

int qm_spi_save_context ( const qm_spi_t  spi,
qm_spi_context_t *const  ctx 
)

Save SPI context.

Saves the configuration of the specified SPI peripheral before entering sleep.

Parameters
[in]spiSPI controller identifier.
[out]ctxSPI context structure. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 1157 of file qm_spi.c.

References qm_spi_reg_t::baudr, qm_spi_context_t::baudr, qm_spi_reg_t::ctrlr0, qm_spi_context_t::ctrlr0, qm_spi_reg_t::ser, and qm_spi_context_t::ser.

int qm_spi_set_config ( const qm_spi_t  spi,
const qm_spi_config_t *const  cfg 
)

Set SPI configuration.

Change the configuration of a SPI module. This includes transfer mode, bus mode, clock divider and data frame size.

Parameters
[in]spiWhich SPI module to configure.
[in]cfgNew configuration for SPI. This must not be NULL.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 423 of file qm_spi.c.

References qm_spi_reg_t::baudr, qm_spi_reg_t::ctrlr0, and QM_SPI_TMOD_EEPROM_READ.

int qm_spi_slave_select ( const qm_spi_t  spi,
const qm_spi_slave_select_t  ss 
)

Select which slave to perform SPI transmissions on.

Parameters
[in]spiWhich SPI module to configure.
[in]ssWhich slave select line to enable when doing transmissions.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 465 of file qm_spi.c.

int qm_spi_transfer ( const qm_spi_t  spi,
const qm_spi_transfer_t *const  xfer,
qm_spi_status_t *const  status 
)

Multi-frame read / write on SPI.

Perform a multi-frame read/write on the SPI bus. This is a blocking synchronous call. If the SPI is currently in use, the function will wait until the SPI is free before beginning the transfer. If transfer mode is full duplex (QM_SPI_TMOD_TX_RX), then tx_len and rx_len must be equal. Similarly, for transmit-only transfers (QM_SPI_TMOD_TX) rx_len must be 0, while for receive-only transfers (QM_SPI_TMOD_RX) tx_len must be 0.

For starting a transfer, this controller demands at least one slave select line (SS) to be enabled. Thus, a call to qm_spi_slave_select() with one of the four SS valid lines is mandatory. This is true even if the native slave select line is not used (i.e. when a GPIO is used to drive the SS signal manually).

Parameters
[in]spiWhich SPI to read/write on.
[in]xferStructure containing pre-allocated write and read data buffers. This must not be NULL.
[out]statusGet spi status.
Returns
Standard errno return type for QMSI.
Return values
0on success.
Negativeerrno for possible error codes.

Definition at line 499 of file qm_spi.c.

References qm_spi_reg_t::ctrlr1, qm_spi_reg_t::imr, QM_SPI_FRAME_FORMAT_STANDARD, QM_SPI_RX_OVERFLOW, QM_SPI_TMOD_EEPROM_READ, QM_SPI_TMOD_RX, QM_SPI_TMOD_TX, QM_SPI_TMOD_TX_RX, qm_spi_reg_t::risr, qm_spi_transfer_t::rx, qm_spi_transfer_t::rx_len, qm_spi_reg_t::rxoicr, qm_spi_reg_t::sr, qm_spi_reg_t::ssienr, qm_spi_transfer_t::tx, and qm_spi_transfer_t::tx_len.