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

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Enumerations | Functions
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

enum qm_spi_bmode_t

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.

enum qm_spi_frame_format_t

QM SPI Frame Format.

Enumerator
QM_SPI_FRAME_FORMAT_STANDARD | Standard SPI mode.

Definition at line 103 of file qm_spi.h.

enum qm_spi_frame_size_t

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.

enum qm_spi_slave_select_t

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.

enum qm_spi_status_t

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.

enum qm_spi_tmode_t

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] | spi | SPI controller identifier.
  [in] | dma_ctrl_id | DMA controller identifier.
  [in] | dma_channel_id | DMA channel identifier.
  [in] | dma_channel_direction | DMA 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

  0 | on success.
  Negative | errno 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] | spi | SPI controller identifier.
  [in] | xfer | Structure 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

  0 | on success.
  Negative | errno 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] | spi | SPI controller identifier.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | spi | Which SPI to read the status of.
  [out] | status | Current SPI status. This must not be null.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | spi | Which SPI to transfer to / from.
  [in] | xfer | Transfer 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

  0 | on success.
  Negative | errno 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] | spi | Which SPI to cancel the current transfer.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | spi | Which SPI to transfer to / from.
  [in] | xfer | Transfer 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] | update | Specify if only RX has to be updated, or only TX or both.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | spi | SPI controller identifier.
  [in] | ctx | SPI context structure. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | spi | SPI controller identifier.
  [out] | ctx | SPI context structure. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | spi | Which SPI module to configure.
  [in] | cfg | New configuration for SPI. This must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | spi | Which SPI module to configure.
  [in] | ss | Which slave select line to enable when doing transmissions.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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] | spi | Which SPI to read/write on.
  [in] | xfer | Structure containing pre-allocated write and read data buffers. This must not be NULL.
  [out] | status | Get spi status.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno 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.