(ae68723)

SPI Host Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/dif/autogen/dif_spi_host_autogen.h"

Data Structures
struct	dif_spi_host_config
	Runtime configuration for SPI Host. More...

struct	dif_spi_host_segment
	Segment descriptor for each segment in a transaction. More...

struct	dif_spi_host_status

struct	dif_spi_host_config.chip_select

union	dif_spi_host_segment.__unnamed__

struct	dif_spi_host_segment.__unnamed__.opcode

struct	dif_spi_host_segment.__unnamed__.address

struct	dif_spi_host_segment.__unnamed__.dummy

struct	dif_spi_host_segment.__unnamed__.tx

struct	dif_spi_host_segment.__unnamed__.rx

struct	dif_spi_host_segment.__unnamed__.bidir

Typedefs
typedef struct dif_spi_host_config	dif_spi_host_config_t
	Runtime configuration for SPI Host. More...

typedef enum dif_spi_host_width	dif_spi_host_width_t
	Width of SPI operations.

typedef enum dif_spi_host_direction	dif_spi_host_direction_t
	Direction of SPI operations. More...

typedef enum dif_spi_host_segment_type	dif_spi_host_segment_type_t
	Segment types for segments in a transaction.

typedef enum dif_spi_host_addr_mode	dif_spi_host_addr_mode_t
	Address mode for the address segment in a transaction.

typedef struct dif_spi_host_segment	dif_spi_host_segment_t
	Segment descriptor for each segment in a transaction. More...

typedef enum dif_spi_host_events	dif_spi_host_events_code_t

typedef uint32_t	dif_spi_host_events_t
	Bitmask with the `dif_spi_host_events_code_t` values.

typedef struct dif_spi_host_status	dif_spi_host_status_t

typedef enum dif_spi_host_error_code	dif_spi_host_error_code_t

typedef uint32_t	dif_spi_host_errors_t
	Bitmask with the `dif_spi_host_error_code_t` values.

Enumerations
enum	dif_spi_host_width { kDifSpiHostWidthStandard = 0, kDifSpiHostWidthDual = 1, kDifSpiHostWidthQuad = 2 }
	Width of SPI operations. More...

enum	dif_spi_host_direction { kDifSpiHostDirectionDummy = 0, kDifSpiHostDirectionRx = 1, kDifSpiHostDirectionTx = 2, kDifSpiHostDirectionBidirectional = 3 }
	Direction of SPI operations. More...

enum	dif_spi_host_segment_type { kDifSpiHostSegmentTypeOpcode, kDifSpiHostSegmentTypeAddress, kDifSpiHostSegmentTypeDummy, kDifSpiHostSegmentTypeTx, kDifSpiHostSegmentTypeRx, kDifSpiHostSegmentTypeBidirectional }
	Segment types for segments in a transaction. More...

enum	dif_spi_host_addr_mode { kDifSpiHostAddrMode3b, kDifSpiHostAddrMode4b }
	Address mode for the address segment in a transaction. More...

enum	dif_spi_host_events { kDifSpiHostEvtRxFull = 1 << 0, kDifSpiHostEvtTxEmpty = 1 << 1, kDifSpiHostEvtRxWm = 1 << 2, kDifSpiHostEvtTxWm = 1 << 3, kDifSpiHostEvtReady = 1 << 4, kDifSpiHostEvtIdle = 1 << 5, kDifSpiHostEvtAll = (1 << 6) - 1 }

enum	dif_spi_host_error_code { kDifSpiHostErrorCmdBusy = 1 << 0, kDifSpiHostErrorOverflow = 1 << 1, kDifSpiHostErrorUnderflow = 1 << 2, kDifSpiHostErrorCmdInval = 1 << 3, kDifSpiHostErrorCsIdIval = 1 << 4, kDifSpiHostErrorAccessIval = 1 << 5, kDifSpiHostIrqErrorAll = (1 << 5) - 1, kDifSpiHostErrorAll = (1 << 6) - 1 }

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_configure (const dif_spi_host_t *spi_host, dif_spi_host_config_t config)
	Configures SPI Host with runtime information. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_output_set_enabled (const dif_spi_host_t *spi_host, bool enabled)
	Sets the enablement of the SPI host output buffers. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_fifo_write (const dif_spi_host_t spi_host, const void src, uint16_t len)
	Write to the SPI Host transmit FIFO. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_fifo_read (const dif_spi_host_t spi_host, void dst, uint16_t len)
	Read from the SPI Host receive FIFO. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_transaction (const dif_spi_host_t spi_host, uint32_t csid, dif_spi_host_segment_t segments, size_t length)
	Begins a SPI Host transaction. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_event_set_enabled (const dif_spi_host_t *spi_host, dif_spi_host_events_t events, bool enable)
	Set the enable state of the spi host events. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_event_get_enabled (const dif_spi_host_t spi_host, dif_spi_host_events_t events)
	Get the enabled events. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_get_status (const dif_spi_host_t spi_host, dif_spi_host_status_t status)
	Read the current status of the spi host. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_write_command (const dif_spi_host_t *spi_host, uint16_t length, dif_spi_host_width_t speed, dif_spi_host_direction_t direction, bool last_segment)
	Issues a command segment to a spi_host. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_error_set_enabled (const dif_spi_host_t *spi_host, dif_spi_host_errors_t errors, bool enable)
	Set the enable state of the spi host errors. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_error_get_enabled (const dif_spi_host_t spi_host, dif_spi_host_errors_t errors)
	Get the enabled errors. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_get_error (const dif_spi_host_t spi_host, dif_spi_host_errors_t errors)
	Read the current error status of the spi host. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_host_wait_until_idle (const dif_spi_host_t *spi_host)
	Wait until the SPI Host is idle. More...

Detailed Description

SPI Host Device Interface Functions

Definition in file dif_spi_host.h.

Data Structure Documentation

◆ dif_spi_host_config

struct dif_spi_host_config

Runtime configuration for SPI Host.

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

Definition at line 26 of file dif_spi_host.h.

Data Fields
struct dif_spi_host_config	chip_select
bool	cpha	SPI clock phase.
bool	cpol	SPI clock polarity.
bool	full_cycle	Full-cycle sampling mode.
uint32_t	peripheral_clock_freq_hz	Peripheral clock frequency (ie: kClockFreqPeripheralHz).
size_t	rx_watermark	If `EVENT_ENABLE.RXWM` is set, an interrupt will fire when the depth of the RX FIFO drops below `RX_WATERMARK` words (32b each).
uint32_t	spi_clock	Desired SPI clock frequency (SCK).
size_t	tx_watermark	If `EVENT_ENABLE.TXWM` is set, an interrupt will fire when the depth of the TX FIFO drops below `TX_WATERMARK` words (32b each).

◆ dif_spi_host_segment

struct dif_spi_host_segment

Segment descriptor for each segment in a transaction.

This struct is a tagged union: the type field determines which field of the union is relevant.

Definition at line 115 of file dif_spi_host.h.

Data Fields
union dif_spi_host_segment	__unnamed__
dif_spi_host_segment_type_t	type	The segment type for this segment.

◆ dif_spi_host_status

struct dif_spi_host_status

Definition at line 278 of file dif_spi_host.h.

Data Fields
bool	active	Indicates the SPI host is processing a previously issued command.
uint32_t	cmd_queue_depth	Indicates how many unread 32-bit words are currently in the command segment queue.
bool	least_significant_first	If true the least significant bits will be transmitted first.
bool	ready	Indicates the SPI host is ready to receive commands.
bool	rx_empty	Indicates that the receive fifo is empty. Any reads from `RX FIFO` will cause an error interrupt.
bool	rx_full	Indicates that the receive fifo is full. Any ongoing transactions will stall until firmware reads some data from `RXDATA`.
uint32_t	rx_queue_depth	Indicates how many unread 32-bit words are currently in the `RX FIFO`. When active, this result may an underestimate due to synchronization delays.
bool	rx_stall	If true, signifies that an ongoing transaction has stalled due to lack of available space in the `RX FIFO`.
bool	rx_water_mark	If true, the number of 32-bits in the `RX FIFO` now exceeds the `CONTROL.RX_WATERMARK`entries (32b each).
bool	tx_empty	Indicates that the transmit data fifo is empty.
bool	tx_full	Indicates that the transmit data fifo is full.
uint32_t	tx_queue_depth	Indicates how many unsent 32-bit words are currently in the`TX FIFO`.
bool	tx_stall	If true, signifies that an ongoing transaction has stalled due to lack of data in the`TX FIFO`.
bool	tx_water_mark	If true, the amount of data in the `TX FIFO` has fallen below the level of `CONTROL.TX_WATERMARK`words (32b each).

◆ dif_spi_host_config.chip_select

struct dif_spi_host_config.chip_select

Definition at line 31 of file dif_spi_host.h.

Data Fields
uint8_t	idle	Minimum idle time between commands in SCK half-cycles.
uint8_t	lead	Chip-select leading time in SCK half-cycles.
uint8_t	trail	Chip-select trailing time in SCK half-cycles.

◆ dif_spi_host_segment.unnamed

union dif_spi_host_segment.__unnamed__

Definition at line 118 of file dif_spi_host.h.

Data Fields
__unnamed__	address
__unnamed__	bidir
__unnamed__	dummy
__unnamed__	opcode
__unnamed__	rx
__unnamed__	tx

◆ dif_spi_host_segment.unnamed.opcode

struct dif_spi_host_segment.__unnamed__.opcode

Definition at line 119 of file dif_spi_host.h.

Data Fields
uint8_t	opcode
dif_spi_host_width_t	width

◆ dif_spi_host_segment.unnamed.address

struct dif_spi_host_segment.__unnamed__.address

Definition at line 123 of file dif_spi_host.h.

Data Fields
uint32_t	address
dif_spi_host_addr_mode_t	mode
dif_spi_host_width_t	width

◆ dif_spi_host_segment.unnamed.dummy

struct dif_spi_host_segment.__unnamed__.dummy

Definition at line 128 of file dif_spi_host.h.

Data Fields
size_t	length
dif_spi_host_width_t	width

◆ dif_spi_host_segment.unnamed.tx

struct dif_spi_host_segment.__unnamed__.tx

Definition at line 132 of file dif_spi_host.h.

Data Fields
const void *	buf
size_t	length
dif_spi_host_width_t	width

◆ dif_spi_host_segment.unnamed.rx

struct dif_spi_host_segment.__unnamed__.rx

Definition at line 137 of file dif_spi_host.h.

Data Fields
void *	buf
size_t	length
dif_spi_host_width_t	width

◆ dif_spi_host_segment.unnamed.bidir

struct dif_spi_host_segment.__unnamed__.bidir

Definition at line 142 of file dif_spi_host.h.

Data Fields
size_t	length
void *	rxbuf
const void *	txbuf
dif_spi_host_width_t	width

Typedef Documentation

◆ dif_spi_host_config_t

typedef struct dif_spi_host_config dif_spi_host_config_t

Runtime configuration for SPI Host.

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

◆ dif_spi_host_direction_t

typedef enum dif_spi_host_direction dif_spi_host_direction_t

Direction of SPI operations.

This describes which direction a given SPI operation will use.

◆ dif_spi_host_segment_t

typedef struct dif_spi_host_segment dif_spi_host_segment_t

Segment descriptor for each segment in a transaction.

This struct is a tagged union: the type field determines which field of the union is relevant.

Enumeration Type Documentation

◆ dif_spi_host_addr_mode

enum dif_spi_host_addr_mode

Address mode for the address segment in a transaction.

Enumerator
kDifSpiHostAddrMode3b	The address is a 3-byte address.
kDifSpiHostAddrMode4b	The address is a 4-byte address.

Definition at line 102 of file dif_spi_host.h.

◆ dif_spi_host_direction

enum dif_spi_host_direction

Direction of SPI operations.

This describes which direction a given SPI operation will use.

Enumerator
kDifSpiHostDirectionDummy	The SPI host neither transmits or receives.
kDifSpiHostDirectionRx	The SPI host receives data.
kDifSpiHostDirectionTx	The SPI host transmits data.
kDifSpiHostDirectionBidirectional	The SPI host transmits and receives data.

Definition at line 70 of file dif_spi_host.h.

◆ dif_spi_host_error_code

enum dif_spi_host_error_code

Enumerator
kDifSpiHostErrorCmdBusy	Indicates a write to `COMMAND` when `STATUS.READY = 0`.
kDifSpiHostErrorOverflow	Indicates that firmware has overflowed the `TX FIFO`.
kDifSpiHostErrorUnderflow	Indicates that firmware has attempted to read from `RXDATA` when the `RX FIFO` is empty.
kDifSpiHostErrorCmdInval	Indicates an invalid command segment, meaning either an invalid value of `COMMAND.SPEED` or a request for bidirectional data transfer at dual or quad speed.
kDifSpiHostErrorCsIdIval	Indicates a command was attempted with an invalid value for `CSID`.
kDifSpiHostErrorAccessIval	Indicates that TL-UL attempted to write to `TXDATA` with no bytes enabled. Such ‘zero byte’ writes are not supported. Note: This error does not generate IRQ.
kDifSpiHostIrqErrorAll	All the errors that can generate an IRQ.
kDifSpiHostErrorAll	All the errors above together.

Definition at line 376 of file dif_spi_host.h.

◆ dif_spi_host_events

enum dif_spi_host_events

Enumerator
kDifSpiHostEvtRxFull	Enable IRQ to be fired when `STATUS.RXFULL` goes high.
kDifSpiHostEvtTxEmpty	Enable IRQ to be fired when `STATUS.TXEMPTY` goes high.
kDifSpiHostEvtRxWm	Enable IRQ to be fired when the number of 32-bit words in the RX FIFO is greater than `CONTROL.RX_WATERMARK`.
kDifSpiHostEvtTxWm	Enable IRQ to be fired when the number of 32-bit words in the TX FIFO is greater than `CONTROL.TX_WATERMARK`.
kDifSpiHostEvtReady	Enable IRQ to be fired when `STATUS.READY` goes high.
kDifSpiHostEvtIdle	Enable IRQ to be fired when `STATUS.ACTIVE` goes low.
kDifSpiHostEvtAll	All above together.

Definition at line 215 of file dif_spi_host.h.

◆ dif_spi_host_segment_type

enum dif_spi_host_segment_type

Segment types for segments in a transaction.

Enumerator
kDifSpiHostSegmentTypeOpcode	The segment is a SPI opcode.
kDifSpiHostSegmentTypeAddress	The segment is a SPI address.
kDifSpiHostSegmentTypeDummy	The segment is a SPI dummy cycle.
kDifSpiHostSegmentTypeTx	The segment is a SPI transmit (from a memory buffer).
kDifSpiHostSegmentTypeRx	The segment is a SPI receive (into a memory buffer).
kDifSpiHostSegmentTypeBidirectional	The segment is a simultaneous transmit and receieve.

Definition at line 84 of file dif_spi_host.h.

◆ dif_spi_host_width

enum dif_spi_host_width

Width of SPI operations.

Enumerator
kDifSpiHostWidthStandard	Standard SPI mode (single lanes for send and recv).
kDifSpiHostWidthDual	Dual SPI mode (use two lanes for send and recv).
kDifSpiHostWidthQuad	Quad SPI mode (use four lanes for send and recv).

Definition at line 56 of file dif_spi_host.h.

Function Documentation

◆ dif_spi_host_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_configure	(	const dif_spi_host_t *	spi_host,
		dif_spi_host_config_t	config
	)

Configures SPI Host with runtime information.

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

Parameters

spi_host	A SPI Host handle.
config	Runtime configuration parameters.

Returns: The result of the operation.

Definition at line 69 of file dif_spi_host.c.

◆ dif_spi_host_error_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_error_get_enabled	(	const dif_spi_host_t *	spi_host,
		dif_spi_host_errors_t *	errors
	)

Get the enabled errors.

Parameters

	spi_host	A SPI Host handle.
[out]	errors	A bitmask that will contain all the errors that are enabled.

Returns: The result of the operation.

Definition at line 521 of file dif_spi_host.c.

◆ dif_spi_host_error_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_error_set_enabled	(	const dif_spi_host_t *	spi_host,
		dif_spi_host_errors_t	errors,
		bool	enable
	)

Set the enable state of the spi host errors.

Parameters

spi_host	A SPI Host handle.
errors	A bitmask with the errors to be enabled or disabled.
enable	True to enable the `events` or false to disable.

Returns: The result of the operation.

Definition at line 502 of file dif_spi_host.c.

◆ dif_spi_host_event_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_event_get_enabled	(	const dif_spi_host_t *	spi_host,
		dif_spi_host_events_t *	events
	)

Get the enabled events.

Parameters

	spi_host	A SPI Host handle.
[out]	events	A bitmask that will contain all the events that are enabled.

Returns: The result of the operation.

Definition at line 448 of file dif_spi_host.c.

◆ dif_spi_host_event_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_event_set_enabled	(	const dif_spi_host_t *	spi_host,
		dif_spi_host_events_t	events,
		bool	enable
	)

Set the enable state of the spi host events.

Parameters

spi_host	A SPI Host handle.
events	A bitmask with the events to be enabled or disabled.
enable	True to enable the `events` or false to disable.

Returns: The result of the operation.

Definition at line 429 of file dif_spi_host.c.

◆ dif_spi_host_fifo_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_fifo_read	(	const dif_spi_host_t *	spi_host,
		void *	dst,
		uint16_t	len
	)

Read from the SPI Host receive FIFO.

Parameters

spi_host	A SPI Host handle.
dst	A pointer to the buffer to receive the data.
len	The length of the receive buffer.

Returns: The result of the operation.

Definition at line 234 of file dif_spi_host.c.

◆ dif_spi_host_fifo_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_fifo_write	(	const dif_spi_host_t *	spi_host,
		const void *	src,
		uint16_t	len
	)

Write to the SPI Host transmit FIFO.

Parameters

spi_host	A SPI Host handle.
src	A pointer to the buffer to transmit.
len	The length of the transmit buffer.

Returns: The result of the operation.

Definition at line 167 of file dif_spi_host.c.

◆ dif_spi_host_get_error()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_get_error	(	const dif_spi_host_t *	spi_host,
		dif_spi_host_errors_t *	errors
	)

Read the current error status of the spi host.

Parameters

	spi_host	A SPI Host handle.
[out]	errors	The error status of the spi.

Returns: The result of the operation.

Definition at line 532 of file dif_spi_host.c.

◆ dif_spi_host_get_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_get_status	(	const dif_spi_host_t *	spi_host,
		dif_spi_host_status_t *	status
	)

Read the current status of the spi host.

Parameters

	spi_host	A SPI Host handle.
[out]	status	The status of the spi.

Returns: The result of the operation.

Definition at line 459 of file dif_spi_host.c.

◆ dif_spi_host_output_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_output_set_enabled	(	const dif_spi_host_t *	spi_host,
		bool	enabled
	)

Sets the enablement of the SPI host output buffers.

Parameters

spi_host	A SPI Host handle.
enabled	Enable or disable the output buffers.

Returns: The result of the operation.

Definition at line 111 of file dif_spi_host.c.

◆ dif_spi_host_transaction()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_transaction	(	const dif_spi_host_t *	spi_host,
		uint32_t	csid,
		dif_spi_host_segment_t *	segments,
		size_t	length
	)

Begins a SPI Host transaction.

Parameters

spi_host	A SPI Host handle.
csid	The chip-select ID of the SPI target.
segments	The SPI segments to send in this transaction.
length	The number of SPI segments in this transaction.

Returns: The result of the operation.

Definition at line 373 of file dif_spi_host.c.

◆ dif_spi_host_wait_until_idle()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_wait_until_idle ( const dif_spi_host_t * spi_host )

Wait until the SPI Host is idle.

Parameters

spi_host A SPI Host handle.

Returns: The result of the operation.

Definition at line 544 of file dif_spi_host.c.

◆ dif_spi_host_write_command()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_host_write_command	(	const dif_spi_host_t *	spi_host,
		uint16_t	length,
		dif_spi_host_width_t	speed,
		dif_spi_host_direction_t	direction,
		bool	last_segment
	)

Issues a command segment to a spi_host.

Parameters

spi_host	A SPI Host handle.
length	The number of 1-byte burst for read and write segments, or the number of cycles for dummy segments.
speed	Which speed the transmission should use.
direction	Which direction the operation should use.
last_segment	If true the chip select line is raised after the transmission, otherwise it is kept low.

Returns: The result of the operation.

Definition at line 490 of file dif_spi_host.c.

(ae68723)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_spi_host_config

◆ dif_spi_host_segment

◆ dif_spi_host_status

◆ dif_spi_host_config.chip_select

◆ dif_spi_host_segment.__unnamed__

◆ dif_spi_host_segment.__unnamed__.opcode

◆ dif_spi_host_segment.__unnamed__.address

◆ dif_spi_host_segment.__unnamed__.dummy

◆ dif_spi_host_segment.__unnamed__.tx

◆ dif_spi_host_segment.__unnamed__.rx

◆ dif_spi_host_segment.__unnamed__.bidir

Typedef Documentation

◆ dif_spi_host_config_t

◆ dif_spi_host_direction_t

◆ dif_spi_host_segment_t

Enumeration Type Documentation

◆ dif_spi_host_addr_mode

◆ dif_spi_host_direction

◆ dif_spi_host_error_code

◆ dif_spi_host_events

◆ dif_spi_host_segment_type

◆ dif_spi_host_width

Function Documentation

◆ dif_spi_host_configure()

◆ dif_spi_host_error_get_enabled()

◆ dif_spi_host_error_set_enabled()

◆ dif_spi_host_event_get_enabled()

◆ dif_spi_host_event_set_enabled()

◆ dif_spi_host_fifo_read()

◆ dif_spi_host_fifo_write()

◆ dif_spi_host_get_error()

◆ dif_spi_host_get_status()

◆ dif_spi_host_output_set_enabled()

◆ dif_spi_host_transaction()

◆ dif_spi_host_wait_until_idle()

◆ dif_spi_host_write_command()

◆ dif_spi_host_segment.unnamed

◆ dif_spi_host_segment.unnamed.opcode

◆ dif_spi_host_segment.unnamed.address

◆ dif_spi_host_segment.unnamed.dummy

◆ dif_spi_host_segment.unnamed.tx

◆ dif_spi_host_segment.unnamed.rx

◆ dif_spi_host_segment.unnamed.bidir