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

(7eb9436)

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"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_spi_device_autogen.h"

Go to the source code of this file.

Data Structures

struct  dif_spi_device_generic_mode_config
 
struct  dif_spi_device_config
 Runtime configuration for SPI. More...
 
struct  dif_spi_device_handle
 Struct containing the relevant run-time information for the DIF. More...
 
struct  dif_spi_device_generic_fifo_status
 Represents the status of the synchronous FIFOs in generic mode. More...
 
struct  dif_spi_device_flash_id
 
struct  dif_spi_device_passthrough_intercept_config
 Represents which optional hardware features may intercept commands in passthrough mode. More...
 
struct  dif_spi_device_flash_command
 
struct  dif_spi_device_tpm_caps
 
struct  dif_spi_device_tpm_config
 
struct  dif_spi_device_tpm_data_status
 
struct  dif_spi_device_tpm_id
 
union  dif_spi_device_config.mode_cfg
 

Typedefs

typedef enum dif_spi_device_mode dif_spi_device_mode_t
 The mode that the spi device operates in.
 
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 struct dif_spi_device_generic_mode_config dif_spi_device_generic_mode_config_t
 
typedef struct dif_spi_device_config dif_spi_device_config_t
 Runtime configuration for SPI. More...
 
typedef struct dif_spi_device_handle dif_spi_device_handle_t
 Struct containing the relevant run-time information for the DIF.
 
typedef struct dif_spi_device_generic_fifo_status dif_spi_device_generic_fifo_status_t
 Represents the status of the synchronous FIFOs in generic mode.
 
typedef struct dif_spi_device_flash_id dif_spi_device_flash_id_t
 
typedef struct dif_spi_device_passthrough_intercept_config dif_spi_device_passthrough_intercept_config_t
 Represents which optional hardware features may intercept commands in passthrough mode. More...
 
typedef enum dif_spi_device_flash_address_type dif_spi_device_flash_address_type_t
 
typedef enum dif_spi_device_payload_io dif_spi_device_payload_io_t
 An enum describing the type of I/O width used by a command's payload.
 
typedef struct dif_spi_device_flash_command dif_spi_device_flash_command_t
 
typedef enum dif_spi_device_flash_buffer_type dif_spi_device_flash_buffer_type_t
 
typedef struct dif_spi_device_tpm_caps dif_spi_device_tpm_caps_t
 
typedef enum dif_spi_device_tpm_interface dif_spi_device_tpm_interface_t
 
typedef struct dif_spi_device_tpm_config dif_spi_device_tpm_config_t
 
typedef struct dif_spi_device_tpm_data_status dif_spi_device_tpm_data_status_t
 
typedef struct dif_spi_device_tpm_id dif_spi_device_tpm_id_t
 

Enumerations

enum  dif_spi_device_mode {
  kDifSpiDeviceModeGeneric = 0,
  kDifSpiDeviceModeFlashEmulation = 1,
  kDifSpiDeviceModePassthrough = 2
}
 The mode that the spi device operates in. More...
 
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_flash_address_type {
  kDifSpiDeviceFlashAddrDisabled = 0,
  kDifSpiDeviceFlashAddrCfg,
  kDifSpiDeviceFlashAddr3Byte,
  kDifSpiDeviceFlashAddr4Byte,
  kDifSpiDeviceFlashAddrCount
}
 
enum  dif_spi_device_payload_io {
  kDifSpiDevicePayloadIoNone = 0x0,
  kDifSpiDevicePayloadIoSingle = 0x1,
  kDifSpiDevicePayloadIoDual = 0x3,
  kDifSpiDevicePayloadIoQuad = 0xf,
  kDifSpiDevicePayloadIoInvalid = 0x10
}
 An enum describing the type of I/O width used by a command's payload. More...
 
enum  dif_spi_device_flash_buffer_type {
  kDifSpiDeviceFlashBufferTypeEFlash = 0,
  kDifSpiDeviceFlashBufferTypeMailbox,
  kDifSpiDeviceFlashBufferTypeSfdp,
  kDifSpiDeviceFlashBufferTypePayload,
  kDifSpiDeviceFlashBufferTypes
}
 
enum  dif_spi_device_tpm_interface {
  kDifSpiDeviceTpmInterfaceFifo = 0,
  kDifSpiDeviceTpmInterfaceCrb,
  kDifSpiDeviceTpmInterfaceCount
}
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_init_handle (mmio_region_t base_addr, dif_spi_device_handle_t *spi)
 Initializes a SPI device handle for use. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure (dif_spi_device_handle_t *spi, dif_spi_device_config_t config)
 Configures SPI with runtime information. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_passthrough_mode (dif_spi_device_handle_t *spi, dif_toggle_t enable)
 Turn on/off passthrough without changing any other configuration. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_reset_generic_tx_fifo (dif_spi_device_handle_t *spi)
 Resets the asynchronous TX FIFO in generic mode. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_reset_generic_rx_fifo (dif_spi_device_handle_t *spi)
 Resets the asynchronous RX FIFO in generic mode. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_sram_clock_enable (dif_spi_device_handle_t *spi, dif_toggle_t enable)
 Enable or disable the clock for the SRAM backing all the various memory and FIFO-related functions. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_sram_clock_enable (dif_spi_device_handle_t *spi, dif_toggle_t *enabled)
 Get the current enablement state for the clock of the SRAM backing all the various memory and FIFO-related functions. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_abort (dif_spi_device_handle_t *spi)
 Issues an "abort" to the given SPI device, causing all in-progress IO to halt. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_irq_levels (dif_spi_device_handle_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_result_t dif_spi_device_rx_pending (const dif_spi_device_handle_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_result_t dif_spi_device_tx_pending (const dif_spi_device_handle_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_result_t dif_spi_device_get_async_fifo_levels (dif_spi_device_handle_t *spi, uint16_t *rx_fifo_level, uint16_t *tx_fifo_level)
 Get the current async FIFO occupancy levels. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_generic_fifo_status (dif_spi_device_handle_t *spi, dif_spi_device_generic_fifo_status_t *status)
 Get the current empty/full status for generic mode's synchronous FIFOs. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_csb_status (dif_spi_device_handle_t *spi, bool *csb)
 Get the current level of the CSB pin. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_recv (dif_spi_device_handle_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_result_t dif_spi_device_send (dif_spi_device_handle_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...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_send_polled (dif_spi_device_handle_t *spi, const void *buf, size_t buf_len)
 Writes buf_len bytes to the TX FIFO, blocking until all bytes can be written. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_enable_mailbox (dif_spi_device_handle_t *spi, uint32_t address)
 Enable the mailbox region for spi_device flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_disable_mailbox (dif_spi_device_handle_t *spi)
 Disable the mailbox region for spi_device flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_mailbox_configuration (dif_spi_device_handle_t *spi, dif_toggle_t *is_enabled, uint32_t *address)
 Get the active configuration for the mailbox region. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_4b_address_mode (dif_spi_device_handle_t *spi, dif_toggle_t addr_4b)
 Set the address mode of the SPI device in flash/passthrough mode. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_4b_address_mode (dif_spi_device_handle_t *spi, dif_toggle_t *addr_4b)
 Get the address mode of the SPI device in flash/passthrough mode. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_id (dif_spi_device_handle_t *spi, dif_spi_device_flash_id_t *id)
 Get the JEDEC ID presented when in flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_flash_id (dif_spi_device_handle_t *spi, dif_spi_device_flash_id_t id)
 Set the JEDEC ID presented when in flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_passthrough_intercept_config (dif_spi_device_handle_t *spi, dif_spi_device_passthrough_intercept_config_t config)
 Configure the optional hardware functions to intercept passthrough commands. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_last_read_address (dif_spi_device_handle_t *spi, uint32_t *address)
 Get the last address read from the flash memory that was not in the mailbox region. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_eflash_read_threshold (dif_spi_device_handle_t *spi, uint32_t address)
 Set the read threshold watermark for reporting to the corresponding interrupt status bit. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_flash_command_slot (dif_spi_device_handle_t *spi, uint8_t slot, dif_toggle_t enable, dif_spi_device_flash_command_t command_info)
 Set up the indicated command info slot for flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_command_slot (dif_spi_device_handle_t *spi, uint8_t slot, dif_toggle_t *enabled, dif_spi_device_flash_command_t *command_info)
 Get the current configuration of the indicated command info slot. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure_flash_en4b_command (dif_spi_device_handle_t *spi, dif_toggle_t enable, uint8_t opcode)
 Configure the command properties of the hardware's EN4B function. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure_flash_ex4b_command (dif_spi_device_handle_t *spi, dif_toggle_t enable, uint8_t opcode)
 Configure the command properties of the hardware's EX4B function. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure_flash_wren_command (dif_spi_device_handle_t *spi, dif_toggle_t enable, uint8_t opcode)
 Configure the command properties of the hardware's WREN function. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure_flash_wrdi_command (dif_spi_device_handle_t *spi, dif_toggle_t enable, uint8_t opcode)
 Configure the command properties of the hardware's WRDI function. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_flash_address_swap (dif_spi_device_handle_t *spi, uint32_t mask, uint32_t replacement)
 Set which address bits are swapped and their values for commands that have the address swap enabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_flash_payload_swap (dif_spi_device_handle_t *spi, uint32_t mask, uint32_t replacement)
 Set which bits are swapped and their values for commands that have the first-word payload swap function enabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_command_fifo_occupancy (dif_spi_device_handle_t *spi, uint8_t *occupancy)
 Get the current occupancy level of the command FIFO. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_address_fifo_occupancy (dif_spi_device_handle_t *spi, uint8_t *occupancy)
 Get the current occupancy level of the address FIFO. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_payload_fifo_occupancy (dif_spi_device_handle_t *spi, uint16_t *occupancy, uint32_t *start_offset)
 Get the current occupancy level of the payload FIFO. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_pop_flash_command_fifo (dif_spi_device_handle_t *spi, uint8_t *command)
 Pop the first command from the uploaded command FIFO. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_pop_flash_address_fifo (dif_spi_device_handle_t *spi, uint32_t *address)
 Pop the first address from the uploaded address FIFO. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_read_flash_buffer (dif_spi_device_handle_t *spi, dif_spi_device_flash_buffer_type_t buffer_type, uint32_t offset, size_t length, uint8_t *buf)
 Read data from one of the memories associated with flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_write_flash_buffer (dif_spi_device_handle_t *spi, dif_spi_device_flash_buffer_type_t buffer_type, uint32_t offset, size_t length, const uint8_t *buf)
 Write data to one of the memories associated with flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_passthrough_command_filter (dif_spi_device_handle_t *spi, uint8_t command, dif_toggle_t *enabled)
 Get whether the indicated command is filtered for passthrough. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_passthrough_command_filter (dif_spi_device_handle_t *spi, uint8_t command, dif_toggle_t enable)
 Set whether the indicated command is filtered for passthrough. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_all_passthrough_command_filters (dif_spi_device_handle_t *spi, dif_toggle_t enable)
 Set whether ALL commands are filtered for passthrough. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_clear_flash_busy_bit (dif_spi_device_handle_t *spi)
 Clear the busy bit and write-enable bit for flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_flash_status_registers (dif_spi_device_handle_t *spi, uint32_t value)
 Write the status registers for flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_status_registers (dif_spi_device_handle_t *spi, uint32_t *value)
 Get the values of the status registers for flash / passthrough modes. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_tpm_capabilities (dif_spi_device_handle_t *spi, dif_spi_device_tpm_caps_t *caps)
 Read the capabilities of the TPM hardware IP. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_configure (dif_spi_device_handle_t *spi, dif_toggle_t enable, dif_spi_device_tpm_config_t config)
 Configure the TPM within a SPI device. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_data_status (dif_spi_device_handle_t *spi, dif_spi_device_tpm_data_status_t *status)
 Get the current status of the TPM's data FIFOs and command / address register. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_access_reg (dif_spi_device_handle_t *spi, uint8_t locality, uint8_t value)
 Set the value for the TPM_ACCESS_x register, for use when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_access_reg (dif_spi_device_handle_t *spi, uint8_t locality, uint8_t *value)
 Get the value of the TPM_ACCESS_x register that is used when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_sts_reg (dif_spi_device_handle_t *spi, uint32_t value)
 Set the value for the TPM_STS register, for use when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_sts_reg (dif_spi_device_handle_t *spi, uint32_t *value)
 Get the value of the TPM_STS register that is used when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_intf_capability_reg (dif_spi_device_handle_t *spi, uint32_t value)
 Set the value for the TPM_INTF_CAPABILITY register, for use when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_intf_capability_reg (dif_spi_device_handle_t *spi, uint32_t *value)
 Get the value of the TPM_INTF_CAPABILITY register that is used when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_int_enable_reg (dif_spi_device_handle_t *spi, uint32_t value)
 Set the value for the TPM_INT_ENABLE register, for use when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_int_enable_reg (dif_spi_device_handle_t *spi, uint32_t *value)
 Get the value of the TPM_INT_ENABLE register that is used when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_int_vector_reg (dif_spi_device_handle_t *spi, uint32_t value)
 Set the value for the TPM_INT_VECTOR register, for use when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_int_vector_reg (dif_spi_device_handle_t *spi, uint32_t *value)
 Get the value of the TPM_INT_VECTOR register that is used when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_int_status_reg (dif_spi_device_handle_t *spi, uint32_t value)
 Set the value for the TPM_INT_STATUS register, for use when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_int_status_reg (dif_spi_device_handle_t *spi, uint32_t *value)
 Get the value of the TPM_INT_STATUS register that is used when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_id (dif_spi_device_handle_t *spi, dif_spi_device_tpm_id_t id)
 Set the values for the TPM_DID_VID and TPM_RID registers, for use when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_id (dif_spi_device_handle_t *spi, dif_spi_device_tpm_id_t *value)
 Get the values of the TPM_DID_VID and TPM_RID registers that are used when the return-by-hardware mode is active for this register type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_command (dif_spi_device_handle_t *spi, uint8_t *command, uint32_t *address)
 Retrieve the command and address of the current command. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_write_data (dif_spi_device_handle_t *spi, size_t length, uint8_t *buf)
 Write data to the TPM's ReadFIFO. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_read_data (dif_spi_device_handle_t *spi, size_t length, uint8_t *buf)
 Read data from the TPM's WriteFIFO. 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_generic_mode_config

struct dif_spi_device_generic_mode_config

Definition at line 78 of file dif_spi_device.h.

Data Fields
uint8_t rx_fifo_commit_wait The number of bus clock cycles that the RX FIFO waits before committing a sub-word data item to the SRAM.

Only used in Generic Mode.

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.

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_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 104 of file dif_spi_device.h.

Data Fields
dif_spi_device_edge_t clock_polarity
dif_spi_device_edge_t data_phase
dif_spi_device_mode_t device_mode
union dif_spi_device_config mode_cfg
dif_spi_device_bit_order_t rx_order
dif_spi_device_bit_order_t tx_order

◆ dif_spi_device_handle

struct dif_spi_device_handle

Struct containing the relevant run-time information for the DIF.

Definition at line 118 of file dif_spi_device.h.

Data Fields
dif_spi_device_config_t config Configuration information of the hardware.
dif_spi_device_t dev Device information of the hardware.

◆ dif_spi_device_generic_fifo_status

struct dif_spi_device_generic_fifo_status

Represents the status of the synchronous FIFOs in generic mode.

Definition at line 308 of file dif_spi_device.h.

Data Fields
bool rx_empty Whether the RX FIFO is empty.
bool rx_full Whether the RX FIFO is full.
bool tx_empty Whether the TX FIFO is empty.
bool tx_full Whether the TX FIFO is full.

◆ dif_spi_device_flash_id

struct dif_spi_device_flash_id

Definition at line 455 of file dif_spi_device.h.

Data Fields
uint8_t continuation_code The continuation code used before the manufacturer_id byte.
uint16_t device_id The device ID for the SPI flash.
uint8_t manufacturer_id The JEDEC manufacturer ID.
uint8_t num_continuation_code The number of continuation codes preceding the manufacturer_id.

◆ dif_spi_device_passthrough_intercept_config

struct dif_spi_device_passthrough_intercept_config

Represents which optional hardware features may intercept commands in passthrough mode.

If selected, the function will be handled internally and not passed to the downstream SPI flash (sometimes with conditions, such as the address matching the mailbox region when mailbox interception is selected).

Definition at line 494 of file dif_spi_device.h.

Data Fields
bool jedec_id Whether to intercept the ReadID command and respond with the JEDEC ID programmed via dif_spi_device_set_flash_id().
bool mailbox Whether to intercept read memory commands with data programmed in the mailbox buffer, when the address is inside the mailbox region.
bool sfdp Whether to intercept the ReadSFDP command with data programmed to the internal SFDP region.
bool status Whether to intercept commands to the status registers, such as WriteStatus and ReadStatus.

◆ dif_spi_device_flash_command

struct dif_spi_device_flash_command

Definition at line 584 of file dif_spi_device.h.

Data Fields
dif_spi_device_flash_address_type_t address_type
uint8_t dummy_cycles The number of dummy cycles between the address phase and the payload phase of a command.

Note that if payload_io_width is kDifSpiDevicePayloadIoNone, a nonzero value may cause undefined behavior, possibly including the device assuming dummy cycles are part of this payload-less command.

uint8_t opcode The opcode for this command.
bool passthrough_swap_address Whether to translate the address using the address swap mask and value provided to dif_spi_device_passthrough_set_swap_address().

Incompatible with a command with address_type that is kDifSpiDeviceFlashAddrDisabled.

bool payload_dir_to_host Whether the SPI host is receiving this command's payload phase.
dif_spi_device_payload_io_t payload_io_type The I/O width for the payload phase of this command.
bool payload_swap_enable Whether to swap up to the first 32 bits of the payload.
bool set_busy_status Whether to set the busy bit in the status register.
bool upload Whether to upload the command to the payload FIFO.

◆ dif_spi_device_tpm_caps

struct dif_spi_device_tpm_caps

Definition at line 933 of file dif_spi_device.h.

Data Fields
uint8_t max_read_size The maximum read size, in bytes, of the data phase of TPM transactions.

This represents the maximum amount of data the FIFO can accept.

uint8_t max_write_size The maximum write size, in bytes, of the data phase of TPM transactions.

This represents the maximum amount of data the FIFO can accept.

bool multi_locality True if the TPM supports 5 Locality.

Otherwise, only 1 Locality is supported.

uint8_t revision Hardware revision of the TPM submodule.

◆ dif_spi_device_tpm_config

struct dif_spi_device_tpm_config

Definition at line 974 of file dif_spi_device.h.

Data Fields
bool disable_address_prefix_check Disable address prefix check that matches the pattern 0xD4_XXXX before using the return-by-hardware logic.

When true, the upper 8 bits of the address are not required to be 0xD4 for the return-by-hardware logic to activate. When false, commands with non-matching addresses will be uploaded.

bool disable_locality_check Disable locality value check to be within the max value before using the return-by-hardware logic.

When true, the TPM will return 0xFF-valued data on reads and discard writes to registers in the TPM region (matching the 0xD4_XXXX address pattern) if the locality value is above the maximum. When false, commands with invalid locality will be uploaded, and software would be responsible for returning 0xFF to read requests.

bool disable_return_by_hardware Upload the commands that would ordinarily be targeted towards registers that automatically return by hardware.

This includes TPM_DID_VID_x, TPM_RID_x, TPM_STS_x, and TPM_ACCESS_x.

dif_spi_device_tpm_interface_t interface The register interface to implement for the TPM.

Note that in CRB mode, the return-by-hardware logic is disabled.

◆ dif_spi_device_tpm_data_status

struct dif_spi_device_tpm_data_status

Definition at line 1022 of file dif_spi_device.h.

Data Fields
bool cmd_addr_valid True if a command and address have been captured and are can be read.
uint8_t write_fifo_occupancy Current Write FIFO occupancy.

◆ dif_spi_device_tpm_id

struct dif_spi_device_tpm_id

Definition at line 1190 of file dif_spi_device.h.

Data Fields
uint16_t device_id The device ID found in the TPM_DID_VID register.
uint8_t revision The revision ID found in the TPM_RID register.
uint16_t vendor_id The vendor ID found in the TPM_DID_VID register.

◆ dif_spi_device_config.mode_cfg

union dif_spi_device_config.mode_cfg

Definition at line 110 of file dif_spi_device.h.

Data Fields
dif_spi_device_generic_mode_config_t generic

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_passthrough_intercept_config_t

Represents which optional hardware features may intercept commands in passthrough mode.

If selected, the function will be handled internally and not passed to the downstream SPI flash (sometimes with conditions, such as the address matching the mailbox region when mailbox interception is selected).

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 67 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 53 of file dif_spi_device.h.

◆ dif_spi_device_flash_address_type

Enumerator
kDifSpiDeviceFlashAddrDisabled 

No address for this command.

kDifSpiDeviceFlashAddrCfg 

Address size for this command is determined by the current address mode.

kDifSpiDeviceFlashAddr3Byte 

Address size for this command is fixed at 3 bytes.

kDifSpiDeviceFlashAddr4Byte 

Address size for this command is fixed at 4 bytes.

Definition at line 558 of file dif_spi_device.h.

◆ dif_spi_device_flash_buffer_type

Enumerator
kDifSpiDeviceFlashBufferTypeEFlash 

eFlash region

kDifSpiDeviceFlashBufferTypeMailbox 

Mailbox region.

kDifSpiDeviceFlashBufferTypeSfdp 

SFDP region.

kDifSpiDeviceFlashBufferTypePayload 

Payload for uploaded commands.

kDifSpiDeviceFlashBufferTypes 

Count of buffer types.

Definition at line 615 of file dif_spi_device.h.

◆ dif_spi_device_mode

The mode that the spi device operates in.

Enumerator
kDifSpiDeviceModeGeneric 

In the generic firmware mode, the hardware dumps incoming data to SRAM and outgoing data from the SRAM.

kDifSpiDeviceModeFlashEmulation 

In flash emulation mode, the hardware behaves like a SPI NOR flash device.

kDifSpiDeviceModePassthrough 

In pass-through mode, the hardware forwards commands to another SPI flash device, with various tables providing rules for filtering and forwarding.

The hardware may be configured to also behave like a SPI NOR flash device, with some commands and/or address regions targeting internal handling, instead of being passed through.

Definition at line 30 of file dif_spi_device.h.

◆ dif_spi_device_payload_io

An enum describing the type of I/O width used by a command's payload.

Enumerator
kDifSpiDevicePayloadIoNone 

Command does not have a payload.

kDifSpiDevicePayloadIoSingle 

Command's payload has an I/O channel width of 1.

kDifSpiDevicePayloadIoDual 

Command's payload has an I/O channel width of 2.

kDifSpiDevicePayloadIoQuad 

Command's payload has an I/O channel width of 4.

kDifSpiDevicePayloadIoInvalid 

The command info slot had an invalid setting for the payload I/O width.

Definition at line 571 of file dif_spi_device.h.

◆ dif_spi_device_tpm_interface

Enumerator
kDifSpiDeviceTpmInterfaceFifo 

Specifies the FIFO interface from the TPM specification.

kDifSpiDeviceTpmInterfaceCrb 

Specifies the CRB interface from the TPM specification.

Definition at line 966 of file dif_spi_device.h.

Function Documentation

◆ dif_spi_device_abort()

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

Applies only to generic mode.

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

Definition at line 230 of file dif_spi_device.c.

◆ dif_spi_device_clear_flash_busy_bit()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_clear_flash_busy_bit ( dif_spi_device_handle_t spi)

Clear the busy bit and write-enable bit for flash / passthrough modes.

Parameters
spiA handle to a spi device.
Returns
kDifBadArg if spi is NULL. kDifOk otherwise.

Definition at line 1297 of file dif_spi_device.c.

◆ dif_spi_device_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure ( dif_spi_device_handle_t spi,
dif_spi_device_config_t  config 
)

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 63 of file dif_spi_device.c.

◆ dif_spi_device_configure_flash_en4b_command()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure_flash_en4b_command ( dif_spi_device_handle_t spi,
dif_toggle_t  enable,
uint8_t  opcode 
)

Configure the command properties of the hardware's EN4B function.

EN4B is the command to activate 4-byte addressing for flash and passthrough modes.

Parameters
spiA handle to a spi_device.
enableWhether to enable the function.
opcodeWhich opcode activates the function.
Returns
The result of the operation.

Definition at line 1046 of file dif_spi_device.c.

◆ dif_spi_device_configure_flash_ex4b_command()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure_flash_ex4b_command ( dif_spi_device_handle_t spi,
dif_toggle_t  enable,
uint8_t  opcode 
)

Configure the command properties of the hardware's EX4B function.

EX4B is the command to deactivate 4-byte addressing for flash and passthrough modes. This would return the device to the 3-byte address mode.

Parameters
spiA handle to a spi_device.
enableWhether to enable the function.
opcodeWhich opcode activates the function.
Returns
The result of the operation.

Definition at line 1052 of file dif_spi_device.c.

◆ dif_spi_device_configure_flash_wrdi_command()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure_flash_wrdi_command ( dif_spi_device_handle_t spi,
dif_toggle_t  enable,
uint8_t  opcode 
)

Configure the command properties of the hardware's WRDI function.

WRDI is the command to disable writes and clear the WEL bit of the status register, for flash and passthrough modes.

Parameters
spiA handle to a spi_device.
enableWhether to enable the function.
opcodeWhich opcode activates the function.
Returns
The result of the operation.

Definition at line 1064 of file dif_spi_device.c.

◆ dif_spi_device_configure_flash_wren_command()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_configure_flash_wren_command ( dif_spi_device_handle_t spi,
dif_toggle_t  enable,
uint8_t  opcode 
)

Configure the command properties of the hardware's WREN function.

WREN is the command to enable writes and set the WEL bit of the status register, for flash and passthroug modes.

Parameters
spiA handle to a spi_device.
enableWhether to enable the function.
opcodeWhich opcode activates the function.
Returns
The result of the operation.

Definition at line 1058 of file dif_spi_device.c.

◆ dif_spi_device_disable_mailbox()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_disable_mailbox ( dif_spi_device_handle_t spi)

Disable the mailbox region for spi_device flash / passthrough modes.

Parameters
spiA SPI device.
Returns
kDifBadArg if spi is null, else kDifOk.

Definition at line 679 of file dif_spi_device.c.

◆ dif_spi_device_enable_mailbox()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_enable_mailbox ( dif_spi_device_handle_t spi,
uint32_t  address 
)

Enable the mailbox region for spi_device flash / passthrough modes.

Allocate 1 KiB for the mailbox, starting from the provided base address.

Parameters
spiA SPI device.
addressThe base address of the 1 KiB mailbox. The lower 10 bits are ignored.
Returns
kDifBadArg if spi is null, else kDifOk.

Definition at line 665 of file dif_spi_device.c.

◆ dif_spi_device_get_4b_address_mode()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_4b_address_mode ( dif_spi_device_handle_t spi,
dif_toggle_t addr_4b 
)

Get the address mode of the SPI device in flash/passthrough mode.

Parameters
spiA SPI device.
[out]addr_4bPoints to toggle that will be set to kDifToggleEnabled if the device is in 4-byte address mode, else kDifToggleDisabled.
Returns
kDifBadArg if spi or addr_4b are NULL. kDifOk otherwise.

Definition at line 723 of file dif_spi_device.c.

◆ dif_spi_device_get_async_fifo_levels()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_async_fifo_levels ( dif_spi_device_handle_t spi,
uint16_t *  rx_fifo_level,
uint16_t *  tx_fifo_level 
)

Get the current async FIFO occupancy levels.

Only used in generic mode.

Parameters
spiA SPI handle.
[out]rx_fifo_levelThe occupancy level of the RX FIFO.
[out]tx_fifo_levelThe occupancy level of the TX FIFO.
Returns
The result of the operation.

Definition at line 472 of file dif_spi_device.c.

◆ dif_spi_device_get_csb_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_csb_status ( dif_spi_device_handle_t spi,
bool *  csb 
)

Get the current level of the CSB pin.

This is available for the esoteric case where CSB is used like a slow GPIO. Note that for ordinary SPI operation, software sampling of the CSB pin cannot be used to determine whether it is safe to perform an operation where the host must be inactive.

Parameters
spiA SPI handle.
[out]csbThe current value of the chip-select pin (false for asserted, true for deasserted).
Returns
The result of the operation.

Definition at line 506 of file dif_spi_device.c.

◆ dif_spi_device_get_flash_address_fifo_occupancy()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_address_fifo_occupancy ( dif_spi_device_handle_t spi,
uint8_t *  occupancy 
)

Get the current occupancy level of the address FIFO.

Used in flash and passthrough modes.

Parameters
spiA SPI handle.
[out]occupancyThe number of address entries present in the command FIFO.
Returns
The result of the operation.

Definition at line 1108 of file dif_spi_device.c.

◆ dif_spi_device_get_flash_command_fifo_occupancy()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_command_fifo_occupancy ( dif_spi_device_handle_t spi,
uint8_t *  occupancy 
)

Get the current occupancy level of the command FIFO.

Used in flash and passthrough modes.

Parameters
spiA SPI handle.
[out]occupancyThe number of command entries present in the command FIFO.
Returns
The result of the operation.

Definition at line 1096 of file dif_spi_device.c.

◆ dif_spi_device_get_flash_command_slot()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_command_slot ( dif_spi_device_handle_t spi,
uint8_t  slot,
dif_toggle_t enabled,
dif_spi_device_flash_command_t command_info 
)

Get the current configuration of the indicated command info slot.

Parameters
spiA handle to a spi device.
slotA command info slot ID.
[out]enabledA pointer to where the current slot state can be stored.
[out]command_infoIf enabled, points to where the current command configuration can be stored.
Returns
kDifBadArg if any pointers are NULL or slot is larger than the number of command slots. kDifOk otherwise.

Definition at line 921 of file dif_spi_device.c.

◆ dif_spi_device_get_flash_id()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_id ( dif_spi_device_handle_t spi,
dif_spi_device_flash_id_t id 
)

Get the JEDEC ID presented when in flash / passthrough modes.

Parameters
spiA SPI device.
[out]idPoints to location that will be set to the current JEDEC ID.
Returns
kDifBadArg if spi or id are NULL. kDifOk otherwise.

Definition at line 738 of file dif_spi_device.c.

◆ dif_spi_device_get_flash_payload_fifo_occupancy()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_payload_fifo_occupancy ( dif_spi_device_handle_t spi,
uint16_t *  occupancy,
uint32_t *  start_offset 
)

Get the current occupancy level of the payload FIFO.

Used in flash and passthrough modes.

Also get the starting offset for the data that was captured. Only up to 256 bytes of payload may be captured by the SPI device, and if the SPI host sends more data, the SPI device wraps around to the beginning of the payload buffer and writes the newest data from there. The starting offset points to the oldest item in the payload buffer.

Parameters
spiA SPI handle.
[out]occupancyThe number of bytes present in the command FIFO.
[out]start_offsetThe starting offset in the payload buffer for the data, which may wrap around to the beginning.
Returns
The result of the operation.

Definition at line 1120 of file dif_spi_device.c.

◆ dif_spi_device_get_flash_status_registers()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_flash_status_registers ( dif_spi_device_handle_t spi,
uint32_t *  value 
)

Get the values of the status registers for flash / passthrough modes.

Note that the three registers are concatenated to make one 24-bit value, with the LSB being the busy bit.

Parameters
spiA handle to a spi device.
[out]valueA pointer to where to write the values of the registesr.
Returns
kDifBadArg if any pointer arguments are NULL. kDifOk otherwise.

Definition at line 1322 of file dif_spi_device.c.

◆ dif_spi_device_get_generic_fifo_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_generic_fifo_status ( dif_spi_device_handle_t spi,
dif_spi_device_generic_fifo_status_t status 
)

Get the current empty/full status for generic mode's synchronous FIFOs.

Parameters
spiA SPI handle.
[out]statusThe empty/full status for the FIFOs.
Returns
The result of the operation.

Definition at line 487 of file dif_spi_device.c.

◆ dif_spi_device_get_last_read_address()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_last_read_address ( dif_spi_device_handle_t spi,
uint32_t *  address 
)

Get the last address read from the flash memory that was not in the mailbox region.

Parameters
spiA SPI handle.
[out]addressThe last address read.
Returns
The result of the operation.

Definition at line 797 of file dif_spi_device.c.

◆ dif_spi_device_get_mailbox_configuration()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_mailbox_configuration ( dif_spi_device_handle_t spi,
dif_toggle_t is_enabled,
uint32_t *  address 
)

Get the active configuration for the mailbox region.

Parameters
spiA SPI device.
[out]is_enabledWhether the mailbox region is enabled.
[out]addressIf the mailbox is enabled, the base address of the mailbox region.
Returns
kDifBadArg if any argument is null, else kDifOk.

Definition at line 690 of file dif_spi_device.c.

◆ dif_spi_device_get_passthrough_command_filter()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_passthrough_command_filter ( dif_spi_device_handle_t spi,
uint8_t  command,
dif_toggle_t enabled 
)

Get whether the indicated command is filtered for passthrough.

Parameters
spiA handle to a spi device.
commandThe command to be queried.
[out]enabledA pointer to a location where the filter status can be stored. kDifEnabled means the command is filtered.
Returns
kDifBadArg if any pointers are NULL. kDifOk otherwise.

Definition at line 1250 of file dif_spi_device.c.

◆ dif_spi_device_get_sram_clock_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_sram_clock_enable ( dif_spi_device_handle_t spi,
dif_toggle_t enabled 
)

Get the current enablement state for the clock of the SRAM backing all the various memory and FIFO-related functions.

This function should only be called when the upstream spi host is held in reset or otherwise is inactive.

Parameters
spiA SPI handle.
[out]enabledWhether the clock is enabled or disabled.
Returns
The result of the operation.

Definition at line 218 of file dif_spi_device.c.

◆ dif_spi_device_get_tpm_capabilities()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_get_tpm_capabilities ( dif_spi_device_handle_t spi,
dif_spi_device_tpm_caps_t caps 
)

Read the capabilities of the TPM hardware IP.

Parameters
spiA handle to a spi device.
[out]capsThe TPM's hardware capabilities.
Returns
The result of the operation.

Definition at line 1332 of file dif_spi_device.c.

◆ dif_spi_device_init_handle()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_init_handle ( mmio_region_t  base_addr,
dif_spi_device_handle_t spi 
)

Initializes a SPI device handle for use.

Parameters
base_addrThe MMIO base address of the spi_device peripheral.
[out]Outparam for the initialized handle.
Returns
The result of the operation.

Definition at line 55 of file dif_spi_device.c.

◆ dif_spi_device_pop_flash_address_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_pop_flash_address_fifo ( dif_spi_device_handle_t spi,
uint32_t *  address 
)

Pop the first address from the uploaded address FIFO.

Parameters
spiA handle to a spi device.
[out]addressA pointer to where the address can be stored.
Returns
kDifBadArg if any pointers are NULL. kDifUnavailable if the FIFO was empty. kDifOk otherwise.

Definition at line 1153 of file dif_spi_device.c.

◆ dif_spi_device_pop_flash_command_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_pop_flash_command_fifo ( dif_spi_device_handle_t spi,
uint8_t *  command 
)

Pop the first command from the uploaded command FIFO.

Parameters
spiA handle to a spi device.
[out]commandA pointer to where the command can be stored.
Returns
kDifBadArg if any pointers are NULL. kDifUnavailable if the FIFO was empty. kDifOk otherwise.

Definition at line 1135 of file dif_spi_device.c.

◆ dif_spi_device_read_flash_buffer()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_read_flash_buffer ( dif_spi_device_handle_t spi,
dif_spi_device_flash_buffer_type_t  buffer_type,
uint32_t  offset,
size_t  length,
uint8_t *  buf 
)

Read data from one of the memories associated with flash / passthrough modes.

Parameters
spiA handle to a spi device.
buffer_typeAn identifier for which memory space to read from.
offsetThe starting offset for read data in the memory.
lengthThe length, in bytes, of the data to be copied.
[out]bufA pointer to the location where the data should be stored.
Returns
kDifBadArg is any pointers are NULL or the buffer_type does not exist. kDifOutOfRange if the requested offset and length go beyond the indicated buffer_type region. kDifOk otherwise.

Definition at line 1200 of file dif_spi_device.c.

◆ dif_spi_device_recv()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_recv ( dif_spi_device_handle_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.

Applies only to generic mode.

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 588 of file dif_spi_device.c.

◆ dif_spi_device_reset_generic_rx_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_reset_generic_rx_fifo ( dif_spi_device_handle_t spi)

Resets the asynchronous RX FIFO in generic mode.

This function should only be called when the upstream spi host is held in reset or otherwise is inactive.

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

Definition at line 185 of file dif_spi_device.c.

◆ dif_spi_device_reset_generic_tx_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_reset_generic_tx_fifo ( dif_spi_device_handle_t spi)

Resets the asynchronous TX FIFO in generic mode.

This function should only be called when the upstream spi host is held in reset or otherwise is inactive.

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

Definition at line 167 of file dif_spi_device.c.

◆ dif_spi_device_rx_pending()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_rx_pending ( const dif_spi_device_handle_t spi,
size_t *  bytes_pending 
)

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

Applies only to generic mode.

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

Definition at line 446 of file dif_spi_device.c.

◆ dif_spi_device_send()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_send ( dif_spi_device_handle_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.

Applies only to generic mode.

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 610 of file dif_spi_device.c.

◆ dif_spi_device_send_polled()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_send_polled ( dif_spi_device_handle_t spi,
const void *  buf,
size_t  buf_len 
)

Writes buf_len bytes to the TX FIFO, blocking until all bytes can be written.

Applies only to generic mode.

Parameters
spiA SPI device.
bufA pointer to bytes to be written.
buf_lenThe length of the buffer buf points to.
Returns
The result of the operation.

Definition at line 633 of file dif_spi_device.c.

◆ dif_spi_device_set_4b_address_mode()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_4b_address_mode ( dif_spi_device_handle_t spi,
dif_toggle_t  addr_4b 
)

Set the address mode of the SPI device in flash/passthrough mode.

Parameters
spiA SPI device.
addr_4bIf kDifToggleEnabled, set the address mode to 4 Bytes. Otherwise, set the address mode to 3 Bytes.
Returns
kDifBadArg if spi is NULL or addr_4b is not a valid toggle. kDifOk otherwise.

Definition at line 705 of file dif_spi_device.c.

◆ dif_spi_device_set_all_passthrough_command_filters()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_all_passthrough_command_filters ( dif_spi_device_handle_t spi,
dif_toggle_t  enable 
)

Set whether ALL commands are filtered for passthrough.

Can be used for a faster initial state before using dif_spi_device_set_passthrough_command_filter to set the filter status for individual commands.

Parameters
spiA handle to a spi device.
enableWhether to enable the command filter for all commands.
Returns
kDifBadArg if spi is NULL or enable is invalid. kDifOk otherwise.

Definition at line 1283 of file dif_spi_device.c.

◆ dif_spi_device_set_eflash_read_threshold()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_eflash_read_threshold ( dif_spi_device_handle_t spi,
uint32_t  address 
)

Set the read threshold watermark for reporting to the corresponding interrupt status bit.

This function is intended to be used in flash mode for devices that sequentially read from address 0 to the end of some initial block. A supplied address of 0 disables the watermark status bit and interrupt.

Parameters
spiA SPI handle.
addressThe watermark address that triggers reporting to the read threshold watermark's status bit, which can signal an interrupt.
Returns
The result of the operation.

Definition at line 807 of file dif_spi_device.c.

◆ dif_spi_device_set_flash_address_swap()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_flash_address_swap ( dif_spi_device_handle_t spi,
uint32_t  mask,
uint32_t  replacement 
)

Set which address bits are swapped and their values for commands that have the address swap enabled.

Parameters
spiA handle to a spi device.
maskA bitmask indicating which address bits should be replaced.
replacementThe values to swap in for the masked address bits.
Returns
kDifBadArg if spi is NULL, else kDifOk.

Definition at line 1070 of file dif_spi_device.c.

◆ dif_spi_device_set_flash_command_slot()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_flash_command_slot ( dif_spi_device_handle_t spi,
uint8_t  slot,
dif_toggle_t  enable,
dif_spi_device_flash_command_t  command_info 
)

Set up the indicated command info slot for flash / passthrough modes.

Parameters
spiA handle to a spi device.
slotA command info slot ID.
enableWhether to enable or disable the command slot.
command_infoIf enable is set, provides the configuration for the command.
Returns
kDifBadArg if spi is NULL or slot is larger than the number of command slots. kDifOk otherwise.

Definition at line 817 of file dif_spi_device.c.

◆ dif_spi_device_set_flash_id()

Set the JEDEC ID presented when in flash / passthrough modes.

Parameters
spiA SPI device.
idThe JEDEC ID to set.
Returns
kDifBadArg if spi is NULL. kDifOk otherwise.

Definition at line 758 of file dif_spi_device.c.

◆ dif_spi_device_set_flash_payload_swap()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_flash_payload_swap ( dif_spi_device_handle_t spi,
uint32_t  mask,
uint32_t  replacement 
)

Set which bits are swapped and their values for commands that have the first-word payload swap function enabled.

Parameters
spiA handle to a spi device.
maskA bitmask indicating which bits should be replaced.
replacementThe values to swap in for the masked bits.
Returns
kDifBadArg if spi is NULL, else kDifOk.

Definition at line 1083 of file dif_spi_device.c.

◆ dif_spi_device_set_flash_status_registers()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_flash_status_registers ( dif_spi_device_handle_t spi,
uint32_t  value 
)

Write the status registers for flash / passthrough modes.

Note that the three registers are concatenated to make one 24-bit value, with the LSB being the busy bit.

Parameters
spiA handle to a spi device.
valueThe value to write to the registers.
Returns
kDifBadArg if spi is NULL. kDifOk otherwise.

Definition at line 1312 of file dif_spi_device.c.

◆ dif_spi_device_set_irq_levels()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_irq_levels ( dif_spi_device_handle_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.

Applies only to generic mode.

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 250 of file dif_spi_device.c.

◆ dif_spi_device_set_passthrough_command_filter()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_passthrough_command_filter ( dif_spi_device_handle_t spi,
uint8_t  command,
dif_toggle_t  enable 
)

Set whether the indicated command is filtered for passthrough.

Parameters
spiA handle to a spi device.
commandThe command to have its filter status updated.
enableWhether to enable the command filter for the command.
Returns
kDifBadArg if spi is NULL or enable is invalid. kDifOk otherwise.

Definition at line 1268 of file dif_spi_device.c.

◆ dif_spi_device_set_passthrough_intercept_config()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_passthrough_intercept_config ( dif_spi_device_handle_t spi,
dif_spi_device_passthrough_intercept_config_t  config 
)

Configure the optional hardware functions to intercept passthrough commands.

Parameters
spiA SPI handle.
configThe passthrough interception configuration.
Returns
The result of the operation.

Definition at line 778 of file dif_spi_device.c.

◆ dif_spi_device_set_passthrough_mode()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_passthrough_mode ( dif_spi_device_handle_t spi,
dif_toggle_t  enable 
)

Turn on/off passthrough without changing any other configuration.

This changes the mode to one of flash mode or passthrough mode. The current mode must be one of those, else this function will fail.

Parameters
spiA SPI handle.
enableWhether to turn on passthrough mode.
Returns
The result of the operation.

Definition at line 143 of file dif_spi_device.c.

◆ dif_spi_device_set_sram_clock_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_set_sram_clock_enable ( dif_spi_device_handle_t spi,
dif_toggle_t  enable 
)

Enable or disable the clock for the SRAM backing all the various memory and FIFO-related functions.

This function should only be called when the upstream spi host is held in reset or otherwise is inactive.

Parameters
spiA SPI handle.
enableWhether to enable or disable the clock.
Returns
The result of the operation.

Definition at line 203 of file dif_spi_device.c.

◆ dif_spi_device_tpm_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_configure ( dif_spi_device_handle_t spi,
dif_toggle_t  enable,
dif_spi_device_tpm_config_t  config 
)

Configure the TPM within a SPI device.

The TPM circuit has a separate chip-select input but shares the clock and data pins of the rest of the spi_device. The TPM can be enabled alongside the other data path (for generic/flash/passthrough modes).

Parameters
spiA handle to a spi device.
enableWhether to enable the TPM block.
configThe TPM configuration.
Returns
The result of the operation.

Definition at line 1350 of file dif_spi_device.c.

◆ dif_spi_device_tpm_get_access_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_access_reg ( dif_spi_device_handle_t spi,
uint8_t  locality,
uint8_t *  value 
)

Get the value of the TPM_ACCESS_x register that is used when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
localityWhich TPM_ACCESS_x register to query, indexed by the locality.
[out]valueThe value of the TPM_ACCESS_x register.
Returns
The result of the operation.

Definition at line 1434 of file dif_spi_device.c.

◆ dif_spi_device_tpm_get_command()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_command ( dif_spi_device_handle_t spi,
uint8_t *  command,
uint32_t *  address 
)

Retrieve the command and address of the current command.

Parameters
spiA handle to a spi device.
[out]commandThe command opcode.
[out]addressThe address associated with the command.
Returns
The result of the operation.

Definition at line 1587 of file dif_spi_device.c.

◆ dif_spi_device_tpm_get_data_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_data_status ( dif_spi_device_handle_t spi,
dif_spi_device_tpm_data_status_t status 
)

Get the current status of the TPM's data FIFOs and command / address register.

Parameters
spiA handle to a spi device.
[out]statusThe status of the TPM.
Returns
The result of the operation.

Definition at line 1386 of file dif_spi_device.c.

◆ dif_spi_device_tpm_get_id()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_id ( dif_spi_device_handle_t spi,
dif_spi_device_tpm_id_t value 
)

Get the values of the TPM_DID_VID and TPM_RID registers that are used when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
[out]valueThe value of the registers.
Returns
The result of the operation.

Definition at line 1569 of file dif_spi_device.c.

◆ dif_spi_device_tpm_get_int_enable_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_int_enable_reg ( dif_spi_device_handle_t spi,
uint32_t *  value 
)

Get the value of the TPM_INT_ENABLE register that is used when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
[out]valueThe value of the TPM_INT_ENABLE register.
Returns
The result of the operation.

Definition at line 1527 of file dif_spi_device.c.

◆ dif_spi_device_tpm_get_int_status_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_int_status_reg ( dif_spi_device_handle_t spi,
uint32_t *  value 
)

Get the value of the TPM_INT_STATUS register that is used when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
value[out]The value of the TPM_INT_STATUS register.
Returns
The result of the operation.

Definition at line 1547 of file dif_spi_device.c.

◆ dif_spi_device_tpm_get_int_vector_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_int_vector_reg ( dif_spi_device_handle_t spi,
uint32_t *  value 
)

Get the value of the TPM_INT_VECTOR register that is used when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
[out]valueThe value of the TPM_INT_VECTOR register.
Returns
The result of the operation.

Definition at line 1537 of file dif_spi_device.c.

◆ dif_spi_device_tpm_get_intf_capability_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_intf_capability_reg ( dif_spi_device_handle_t spi,
uint32_t *  value 
)

Get the value of the TPM_INTF_CAPABILITY register that is used when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
[out]valueThe value of the TPM_INTF_CAPABILITY register.
Returns
The result of the operation.

Definition at line 1517 of file dif_spi_device.c.

◆ dif_spi_device_tpm_get_sts_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_get_sts_reg ( dif_spi_device_handle_t spi,
uint32_t *  value 
)

Get the value of the TPM_STS register that is used when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
[out]valueThe value of the TPM_STS register.
Returns
The result of the operation.

Definition at line 1507 of file dif_spi_device.c.

◆ dif_spi_device_tpm_read_data()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_read_data ( dif_spi_device_handle_t spi,
size_t  length,
uint8_t *  buf 
)

Read data from the TPM's WriteFIFO.

Parameters
spiA handle to a spi device.
lengthThe length, in bytes, of the data to be copied.
[out]bufA pointer to the location where the data should be stored.
Returns
The result of the operation.

Definition at line 1636 of file dif_spi_device.c.

◆ dif_spi_device_tpm_set_access_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_access_reg ( dif_spi_device_handle_t spi,
uint8_t  locality,
uint8_t  value 
)

Set the value for the TPM_ACCESS_x register, for use when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
localityWhich TPM_ACCESS_x register to target, indexed by the locality.
valueThe value to set the TPM_ACCESS_x register to.
Returns
The result of the operation.

Definition at line 1400 of file dif_spi_device.c.

◆ dif_spi_device_tpm_set_id()

Set the values for the TPM_DID_VID and TPM_RID registers, for use when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
idThe values to set the registers to.
Returns
The result of the operation.

Definition at line 1552 of file dif_spi_device.c.

◆ dif_spi_device_tpm_set_int_enable_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_int_enable_reg ( dif_spi_device_handle_t spi,
uint32_t  value 
)

Set the value for the TPM_INT_ENABLE register, for use when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
valueThe value to set the TPM_INT_ENABLE register to.
Returns
The result of the operation.

Definition at line 1522 of file dif_spi_device.c.

◆ dif_spi_device_tpm_set_int_status_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_int_status_reg ( dif_spi_device_handle_t spi,
uint32_t  value 
)

Set the value for the TPM_INT_STATUS register, for use when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
valueThe value to set the TPM_INT_STATUS register to.
Returns
The result of the operation.

Definition at line 1542 of file dif_spi_device.c.

◆ dif_spi_device_tpm_set_int_vector_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_int_vector_reg ( dif_spi_device_handle_t spi,
uint32_t  value 
)

Set the value for the TPM_INT_VECTOR register, for use when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
valueThe value to set the TPM_INT_VECTOR register to.
Returns
The result of the operation.

Definition at line 1532 of file dif_spi_device.c.

◆ dif_spi_device_tpm_set_intf_capability_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_intf_capability_reg ( dif_spi_device_handle_t spi,
uint32_t  value 
)

Set the value for the TPM_INTF_CAPABILITY register, for use when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
valueThe value to set the TPM_INTF_CAPABILITY register to.
Returns
The result of the operation.

Definition at line 1512 of file dif_spi_device.c.

◆ dif_spi_device_tpm_set_sts_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_set_sts_reg ( dif_spi_device_handle_t spi,
uint32_t  value 
)

Set the value for the TPM_STS register, for use when the return-by-hardware mode is active for this register type.

Parameters
spiA handle to a spi device.
valueThe value to set the TPM_STS register to.
Returns
The result of the operation.

Definition at line 1502 of file dif_spi_device.c.

◆ dif_spi_device_tpm_write_data()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_write_data ( dif_spi_device_handle_t spi,
size_t  length,
uint8_t *  buf 
)

Write data to the TPM's ReadFIFO.

Parameters
spiA handle to a spi device.
lengthThe length, in bytes, of the data to be copied.
bufA pointer to the location of the data to be copied.
Returns
The result of the operation.

Definition at line 1601 of file dif_spi_device.c.

◆ dif_spi_device_tx_pending()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tx_pending ( const dif_spi_device_handle_t spi,
size_t *  bytes_pending 
)

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

Applies only to generic mode.

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

Definition at line 459 of file dif_spi_device.c.

◆ dif_spi_device_write_flash_buffer()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_write_flash_buffer ( dif_spi_device_handle_t spi,
dif_spi_device_flash_buffer_type_t  buffer_type,
uint32_t  offset,
size_t  length,
const uint8_t *  buf 
)

Write data to one of the memories associated with flash / passthrough modes.

Parameters
spiA handle to a spi device.
buffer_typeAn identifier for which memory space to write to.
offsetThe starting offset for the write location of the data.
lengthThe length, in bytes, of the data to be copied.
bufA pointer to the location where the data can be copied from.
Returns
kDifBadArg is any pointers are NULL or the buffer_type does not exist. kDifOutOfRange if the requested offset and length go beyond the indicated buffer_type region. kDifOk otherwise.

Definition at line 1225 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 15 of file dif_spi_device.c.