Software APIs
Data Structures | Typedefs | Enumerations | Functions | Variables
dif_spi_device.h File Reference

(915ba13)

SPI Device Device Interface Functions More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"

Go to the source code of this file.

Data Structures

struct  dif_spi_device_params
 Hardware instantiation parameters for SPI. More...
 
struct  dif_spi_device_config
 Runtime configuration for SPI. More...
 
struct  dif_spi_device
 A handle to a SPI device. More...
 

Typedefs

typedef enum dif_spi_device_edge dif_spi_device_edge_t
 A signal edge type: positive or negative.
 
typedef enum dif_spi_device_bit_order dif_spi_device_bit_order_t
 A bit ordering within a byte.
 
typedef enum dif_spi_device_toggle dif_spi_device_toggle_t
 A toggle state: enabled, or disabled. More...
 
typedef struct dif_spi_device_params dif_spi_device_params_t
 Hardware instantiation parameters for SPI. More...
 
typedef struct dif_spi_device_config dif_spi_device_config_t
 Runtime configuration for SPI. More...
 
typedef struct dif_spi_device dif_spi_device_t
 A handle to a SPI device. More...
 
typedef enum dif_spi_device_result dif_spi_device_result_t
 The result of a SPI operation.
 
typedef enum dif_spi_device_irq dif_spi_device_irq_t
 A SPI interrupt request type.
 
typedef uint32_t dif_spi_device_irq_snapshot_t
 A snapshot of the enablement state of the interrupts for SPI. More...
 

Enumerations

enum  dif_spi_device_edge {
  kDifSpiDeviceEdgePositive,
  kDifSpiDeviceEdgeNegative
}
 A signal edge type: positive or negative. More...
 
enum  dif_spi_device_bit_order {
  kDifSpiDeviceBitOrderMsbToLsb,
  kDifSpiDeviceBitOrderLsbToMsb
}
 A bit ordering within a byte. More...
 
enum  dif_spi_device_toggle {
  kDifSpiDeviceToggleEnabled,
  kDifSpiDeviceToggleDisabled
}
 A toggle state: enabled, or disabled. More...
 
enum  dif_spi_device_result {
  kDifSpiDeviceOk = 0,
  kDifSpiDeviceError = 1,
  kDifSpiDeviceBadArg = 2
}
 The result of a SPI operation. More...
 
enum  dif_spi_device_irq {
  kDifSpiDeviceIrqRxFull,
  kDifSpiDeviceIrqRxAboveLevel,
  kDifSpiDeviceIrqTxBelowLevel,
  kDifSpiDeviceIrqRxError,
  kDifSpiDeviceIrqRxOverflow,
  kDifSpiDeviceIrqTxUnderflow
}
 A SPI interrupt request type. More...
 

Functions

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_init (dif_spi_device_params_t params, dif_spi_device_t *spi)
 Creates a new handle for SPI. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_configure (dif_spi_device_t *spi, dif_spi_device_config_t config)
 Configures SPI with runtime information. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_abort (const dif_spi_device_t *spi)
 Issues an "abort" to the given SPI device, causing all in-progress IO to halt. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_is_pending (const dif_spi_device_t *spi, dif_spi_device_irq_t irq, bool *is_pending)
 Returns whether a particular interrupt is currently pending. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_acknowledge (const dif_spi_device_t *spi, dif_spi_device_irq_t irq)
 Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_get_enabled (const dif_spi_device_t *spi, dif_spi_device_irq_t irq, dif_spi_device_toggle_t *state)
 Checks whether a particular interrupt is currently enabled or disabled. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_set_enabled (const dif_spi_device_t *spi, dif_spi_device_irq_t irq, dif_spi_device_toggle_t state)
 Sets whether a particular interrupt is currently enabled or disabled. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_force (const dif_spi_device_t *spi, dif_spi_device_irq_t irq)
 Forces a particular interrupt, causing it to be serviced as if hardware had asserted it. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_disable_all (const dif_spi_device_t *spi, dif_spi_device_irq_snapshot_t *snapshot)
 Disables all interrupts, optionally snapshotting all toggle state for later restoration. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_restore_all (const dif_spi_device_t *spi, const dif_spi_device_irq_snapshot_t *snapshot)
 Restores interrupts from the given snapshot. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_set_irq_levels (const dif_spi_device_t *spi, uint16_t rx_level, uint16_t tx_level)
 Sets up the "FIFO level" (that is, number of bytes present in a particular FIFO) at which the TxLevel and RxLevel IRQs will fire. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_rx_pending (const dif_spi_device_t *spi, size_t *bytes_pending)
 Returns the number of bytes still pending receipt by software in the RX FIFO. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_tx_pending (const dif_spi_device_t *spi, size_t *bytes_pending)
 Returns the number of bytes still pending transmission by hardware in the TX FIFO. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_recv (const dif_spi_device_t *spi, void *buf, size_t buf_len, size_t *bytes_received)
 Reads at most buf_len bytes from the RX FIFO; the number of bytes read will be written to bytes_received. More...
 
OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_send (const dif_spi_device_t *spi, const void *buf, size_t buf_len, size_t *bytes_sent)
 Writes at most buf_len bytes to the TX FIFO; the number of bytes actually written will be written to bytes_sent. More...
 

Variables

const uint16_t kDifSpiDeviceBufferLen
 The length of the SPI device FIFO buffer, in bytes. More...
 

Detailed Description

SPI Device Device Interface Functions

Definition in file dif_spi_device.h.


Data Structure Documentation

◆ dif_spi_device_params

struct dif_spi_device_params

Hardware instantiation parameters for SPI.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

Definition at line 76 of file dif_spi_device.h.

Data Fields
mmio_region_t base_addr The base address for the SPI hardware registers.

◆ dif_spi_device_config

struct dif_spi_device_config

Runtime configuration for SPI.

This struct describes runtime information for one-time configuration of the hardware.

Definition at line 89 of file dif_spi_device.h.

Data Fields
dif_spi_device_edge_t clock_polarity
dif_spi_device_edge_t data_phase
uint16_t rx_fifo_len The length, in bytes, that should be reserved for the RX FIFO.

kDifSpiDeviceBufferLen / 2 is a good default for this value.

uint8_t rx_fifo_timeout
dif_spi_device_bit_order_t rx_order
uint16_t tx_fifo_len The length, in bytes, that should be reserved for the TX FIFO.

kDifSpiDeviceBufferLen / 2 is a good default for this value.

dif_spi_device_bit_order_t tx_order

◆ dif_spi_device

struct dif_spi_device

A handle to a SPI device.

This type should be treated as opaque by users.

Definition at line 114 of file dif_spi_device.h.

Data Fields
dif_spi_device_params_t params
uint16_t rx_fifo_len
uint16_t tx_fifo_len

Typedef Documentation

◆ dif_spi_device_config_t

Runtime configuration for SPI.

This struct describes runtime information for one-time configuration of the hardware.

◆ dif_spi_device_irq_snapshot_t

A snapshot of the enablement state of the interrupts for SPI.

This is an opaque type, to be used with the dif_spi_device_irq_disable_all() and dif_spi_device_irq_restore_all() functions.

Definition at line 178 of file dif_spi_device.h.

◆ dif_spi_device_params_t

Hardware instantiation parameters for SPI.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

◆ dif_spi_device_t

A handle to a SPI device.

This type should be treated as opaque by users.

◆ dif_spi_device_toggle_t

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

Enumeration Type Documentation

◆ dif_spi_device_bit_order

A bit ordering within a byte.

Enumerator
kDifSpiDeviceBitOrderMsbToLsb 

Represents the most-significant-bit to least-significant-bit order.

kDifSpiDeviceBitOrderLsbToMsb 

Represents the least-significant-bit to most-significant-bit order.

Definition at line 41 of file dif_spi_device.h.

◆ dif_spi_device_edge

A signal edge type: positive or negative.

Enumerator
kDifSpiDeviceEdgePositive 

Represents a positive edge (i.e., from low to high).

kDifSpiDeviceEdgeNegative 

Represents a negative edge (i.e., from high to low).

Definition at line 27 of file dif_spi_device.h.

◆ dif_spi_device_irq

A SPI interrupt request type.

Enumerator
kDifSpiDeviceIrqRxFull 

Indicates that the RX FIFO is full.

kDifSpiDeviceIrqRxAboveLevel 

Indicates that the RX FIFO is above the configured level.

kDifSpiDeviceIrqTxBelowLevel 

Indicates that the TX FIFO is below the configured level.

kDifSpiDeviceIrqRxError 

Indicates an error in the RX FIFO.

kDifSpiDeviceIrqRxOverflow 

Indicates that overflow has occurred in the RX FIFO.

kDifSpiDeviceIrqTxUnderflow 

Indicates that underflow has occurred in the RX FIFO.

Definition at line 144 of file dif_spi_device.h.

◆ dif_spi_device_result

The result of a SPI operation.

Enumerator
kDifSpiDeviceOk 

Indicates that the operation succeeded.

kDifSpiDeviceError 

Indicates some unspecified failure.

kDifSpiDeviceBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 123 of file dif_spi_device.h.

◆ dif_spi_device_toggle

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

Enumerator
kDifSpiDeviceToggleDisabled 

The "disabled" state.

Definition at line 58 of file dif_spi_device.h.

Function Documentation

◆ dif_spi_device_abort()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_abort ( const dif_spi_device_t spi)

Issues an "abort" to the given SPI device, causing all in-progress IO to halt.

Parameters
spiA SPI handle.
Returns
The result of the operation.

Definition at line 93 of file dif_spi_device.c.

◆ dif_spi_device_configure()

Configures SPI with runtime information.

This function should need to be called once for the lifetime of handle.

Parameters
spiA SPI handle.
configRuntime configuration parameters.
Returns
The result of the operation.

Definition at line 48 of file dif_spi_device.c.

◆ dif_spi_device_init()

Creates a new handle for SPI.

This function does not actuate the hardware.

Parameters
paramsHardware instantiation parameters.
[out]spiOut param for the initialized handle.
Returns
The result of the operation.

Definition at line 14 of file dif_spi_device.c.

◆ dif_spi_device_irq_acknowledge()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_acknowledge ( const dif_spi_device_t spi,
dif_spi_device_irq_t  irq 
)

Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced.

Parameters
spiA SPI handle.
irqAn interrupt type.
Returns
The result of the operation.

Definition at line 159 of file dif_spi_device.c.

◆ dif_spi_device_irq_disable_all()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_disable_all ( const dif_spi_device_t spi,
dif_spi_device_irq_snapshot_t snapshot 
)

Disables all interrupts, optionally snapshotting all toggle state for later restoration.

Parameters
spiA SPI handle.
[out]snapshotOut-param for the snapshot; may be NULL.
Returns
The result of the operation.

Definition at line 248 of file dif_spi_device.c.

◆ dif_spi_device_irq_force()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_force ( const dif_spi_device_t spi,
dif_spi_device_irq_t  irq 
)

Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.

Parameters
spiA SPI handle.
irqAn interrupt type.
Returns
The result of the operation.

Definition at line 230 of file dif_spi_device.c.

◆ dif_spi_device_irq_get_enabled()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_get_enabled ( const dif_spi_device_t spi,
dif_spi_device_irq_t  irq,
dif_spi_device_toggle_t state 
)

Checks whether a particular interrupt is currently enabled or disabled.

Parameters
spiA SPI handle.
irqAn interrupt type.
[out]stateOut-param toggle state of the interrupt.
Returns
The result of the operation.

Definition at line 177 of file dif_spi_device.c.

◆ dif_spi_device_irq_is_pending()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_is_pending ( const dif_spi_device_t spi,
dif_spi_device_irq_t  irq,
bool *  is_pending 
)

Returns whether a particular interrupt is currently pending.

Parameters
spiA SPI handle.
irqAn interrupt type.
[out]is_pendingOut-param for whether the interrupt is pending.
Returns
The result of the operation.

Definition at line 141 of file dif_spi_device.c.

◆ dif_spi_device_irq_restore_all()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_restore_all ( const dif_spi_device_t spi,
const dif_spi_device_irq_snapshot_t snapshot 
)

Restores interrupts from the given snapshot.

This function can be used with dif_spi_device_irq_disable_all() to temporary interrupt save-and-restore.

Parameters
spiA SPI handle.
snapshotA snapshot to restore from.
Returns
The result of the operation.

Definition at line 265 of file dif_spi_device.c.

◆ dif_spi_device_irq_set_enabled()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_irq_set_enabled ( const dif_spi_device_t spi,
dif_spi_device_irq_t  irq,
dif_spi_device_toggle_t  state 
)

Sets whether a particular interrupt is currently enabled or disabled.

Parameters
spiA SPI handle.
irqAn interrupt type.
stateThe new toggle state for the interrupt.
Returns
The result of the operation.

Definition at line 197 of file dif_spi_device.c.

◆ dif_spi_device_recv()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_recv ( const dif_spi_device_t spi,
void *  buf,
size_t  buf_len,
size_t *  bytes_received 
)

Reads at most buf_len bytes from the RX FIFO; the number of bytes read will be written to bytes_received.

Parameters
spiA SPI device.
[out]bufA pointer to valid memory.
buf_lenThe length of the buffer buf points to.
[out]bytes_receivedThe number of bytes successfully read; may be null.
Returns
The result of the operation.

Definition at line 568 of file dif_spi_device.c.

◆ dif_spi_device_rx_pending()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_rx_pending ( const dif_spi_device_t spi,
size_t *  bytes_pending 
)

Returns the number of bytes still pending receipt by software in the RX FIFO.

Parameters
spiA SPI handle.
[out]bytes_pendingThe number of bytes pending
Returns
The result of the operation.

Definition at line 473 of file dif_spi_device.c.

◆ dif_spi_device_send()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_send ( const dif_spi_device_t spi,
const void *  buf,
size_t  buf_len,
size_t *  bytes_sent 
)

Writes at most buf_len bytes to the TX FIFO; the number of bytes actually written will be written to bytes_sent.

Parameters
spiA SPI device.
bufA pointer to bytes to be written.
buf_lenThe length of the buffer buf points to.
[out]bytes_sentThe number of bytes successfully written; may be null.
Returns
The result of the operation.

Definition at line 591 of file dif_spi_device.c.

◆ dif_spi_device_set_irq_levels()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_set_irq_levels ( const dif_spi_device_t spi,
uint16_t  rx_level,
uint16_t  tx_level 
)

Sets up the "FIFO level" (that is, number of bytes present in a particular FIFO) at which the TxLevel and RxLevel IRQs will fire.

For the reciept side, when the FIFO overflows rx_level (i.e., goes over the set level), an interrupt is fired. This can be used to detect that more data should be read from the RX FIFO. This is the Spi Buffer -> Main Memory case.

Conversely, for the transmission side, when the FIFO underflows tx_level (i.e., goes below the set level), an interrupt is fired. This can be used to detect that there is free space to write more data to the TX FIFO. This is the Main Memory -> Spi Buffer case.

Parameters
spiA SPI handle.
rx_levelThe new RX level, as described above.
tx_levelThe new TX level, as described above.
Returns
The result of the operation.

Definition at line 278 of file dif_spi_device.c.

◆ dif_spi_device_tx_pending()

OT_WARN_UNUSED_RESULT dif_spi_device_result_t dif_spi_device_tx_pending ( const dif_spi_device_t spi,
size_t *  bytes_pending 
)

Returns the number of bytes still pending transmission by hardware in the TX FIFO.

Parameters
spiA SPI handle.
[out]bytes_pendingThe number of bytes pending
Returns
The result of the operation.

Definition at line 485 of file dif_spi_device.c.

Variable Documentation

◆ kDifSpiDeviceBufferLen

const uint16_t kDifSpiDeviceBufferLen

The length of the SPI device FIFO buffer, in bytes.

Useful for initializing FIFO lengths: for example, for equally-sized FIFOs, rx_fifo_len and tx_fifo_len would be set to kDifSpiDeviceBufferLen / 2.

Definition at line 12 of file dif_spi_device.c.