(90f7989)

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_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_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

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_bit_order	dif_spi_device_bit_order_t
	A bit ordering within a byte.

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_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 enum dif_spi_device_read_pipeline_mode	dif_spi_device_read_pipeline_mode_t

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 { kDifSpiDeviceModeDisabled = 0, kDifSpiDeviceModeFlashEmulation = 1, kDifSpiDeviceModePassthrough = 2 }
	The mode that the spi device operates in. 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_read_pipeline_mode { kDifSpiDeviceReadPipelineModeZeroStages = 0, kDifSpiDeviceReadPipelineModeTwoStagesHalfCycle, kDifSpiDeviceReadPipelineModeTwoStagesFullCycle, kDifSpiDeviceReadPipelineModeCount }

enum	dif_spi_device_flash_buffer_type { kDifSpiDeviceFlashBufferTypeEFlash = 0, kDifSpiDeviceFlashBufferTypeMailbox, kDifSpiDeviceFlashBufferTypeSfdp, 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_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_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_clear_flash_status_request (dif_spi_device_handle_t *spi)
	Clear any pending software-originated flash status change requests. 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_reset_eflash_buffer (dif_spi_device_handle_t *spi)
	Clear eflash read buffer state. 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_payload_buffer (dif_spi_device_handle_t spi, uint32_t offset, size_t length, uint8_t buf)
	Read data from the payload buffer 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...

OT_WARN_UNUSED_RESULT dif_result_t	dif_spi_device_tpm_free_write_fifo (dif_spi_device_handle_t *spi)
	Release the TPM's WriteFIFO back to hardware. 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_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 69 of file dif_spi_device.h.

Data Fields
dif_spi_device_mode_t	device_mode
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 78 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_flash_id

struct dif_spi_device_flash_id

Definition at line 222 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 261 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 378 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.
dif_spi_device_read_pipeline_mode_t	read_pipeline_mode	The read payload pipeline mode to use for this command.
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 724 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 765 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 813 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.
bool	rdfifo_aborted	True if the last command targeted the Read FIFO and was aborted.
bool	wrfifo_acquired	True if the write FIFO is under software's exclusive use.

◆ dif_spi_device_tpm_id

struct dif_spi_device_tpm_id

Definition at line 983 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.

Typedef Documentation

◆ dif_spi_device_config_t

typedef struct dif_spi_device_config 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

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.

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

enum 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 52 of file dif_spi_device.h.

◆ dif_spi_device_flash_address_type

enum 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 336 of file dif_spi_device.h.

◆ dif_spi_device_flash_buffer_type

enum dif_spi_device_flash_buffer_type

Enumerator
kDifSpiDeviceFlashBufferTypeEFlash	eFlash region
kDifSpiDeviceFlashBufferTypeMailbox	Mailbox region.
kDifSpiDeviceFlashBufferTypeSfdp	SFDP region.
kDifSpiDeviceFlashBufferTypes	Count of buffer types.

Definition at line 411 of file dif_spi_device.h.

◆ dif_spi_device_mode

enum dif_spi_device_mode

The mode that the spi device operates in.

Enumerator

kDifSpiDeviceModeDisabled

spi_device will ignore all transactions in this mode configuration.

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

enum 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 349 of file dif_spi_device.h.

◆ dif_spi_device_read_pipeline_mode

enum dif_spi_device_read_pipeline_mode

Enumerator

kDifSpiDeviceReadPipelineModeZeroStages

No additional flash payload read pipeline stages.

kDifSpiDeviceReadPipelineModeTwoStagesHalfCycle

Add 2-stage pipeline to command read output.

Perform half-cycle sampling on the incoming data.

kDifSpiDeviceReadPipelineModeTwoStagesFullCycle

Add 2-stage pipeline to command read output.

Perform full-cycle sampling on the incoming data.

Definition at line 362 of file dif_spi_device.h.

◆ dif_spi_device_tpm_interface

enum 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 757 of file dif_spi_device.h.

Function Documentation

◆ 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

spi	A handle to a spi device.

Returns: kDifBadArg if spi is NULL. kDifOk otherwise.

Definition at line 832 of file dif_spi_device.c.

◆ dif_spi_device_clear_flash_status_request()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_clear_flash_status_request ( dif_spi_device_handle_t * spi )

Clear any pending software-originated flash status change requests.

Parameters

spi	A SPI device.

Returns: kDifBadArg if spi is NULL. kDifOk otherwise.

Definition at line 218 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

spi	A SPI handle.
config	Runtime configuration parameters.

Returns: The result of the operation.

Definition at line 83 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

spi	A handle to a spi_device.
enable	Whether to enable the function.
opcode	Which opcode activates the function.

Returns: The result of the operation.

Definition at line 588 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

spi	A handle to a spi_device.
enable	Whether to enable the function.
opcode	Which opcode activates the function.

Returns: The result of the operation.

Definition at line 594 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

spi	A handle to a spi_device.
enable	Whether to enable the function.
opcode	Which opcode activates the function.

Returns: The result of the operation.

Definition at line 606 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

spi	A handle to a spi_device.
enable	Whether to enable the function.
opcode	Which opcode activates the function.

Returns: The result of the operation.

Definition at line 600 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

spi	A SPI device.

Returns: kDifBadArg if spi is null, else kDifOk.

Definition at line 159 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

spi	A SPI device.
address	The base address of the 1 KiB mailbox. The lower 10 bits are ignored.

Returns: kDifBadArg if spi is null, else kDifOk.

Definition at line 145 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

	spi	A SPI device.
[out]	addr_4b	Points 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 203 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

	spi	A SPI handle.
[out]	csb	The current value of the chip-select pin (false for asserted, true for deasserted).

Returns: The result of the operation.

Definition at line 134 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

	spi	A SPI handle.
[out]	occupancy	The number of address entries present in the command FIFO.

Returns: The result of the operation.

Definition at line 650 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

	spi	A SPI handle.
[out]	occupancy	The number of command entries present in the command FIFO.

Returns: The result of the operation.

Definition at line 638 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

	spi	A handle to a spi device.
	slot	A command info slot ID.
[out]	enabled	A pointer to where the current slot state can be stored.
[out]	command_info	If `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 463 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

	spi	A SPI device.
[out]	id	Points to location that will be set to the current JEDEC ID.

Returns: kDifBadArg if spi or id are NULL. kDifOk otherwise.

Definition at line 239 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

	spi	A SPI handle.
[out]	occupancy	The number of bytes present in the command FIFO.
[out]	start_offset	The 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 662 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

	spi	A handle to a spi device.
[out]	value	A pointer to where to write the values of the registesr.

Returns: kDifBadArg if any pointer arguments are NULL. kDifOk otherwise.

Definition at line 857 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

	spi	A SPI handle.
[out]	address	The last address read.

Returns: The result of the operation.

Definition at line 298 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

	spi	A SPI device.
[out]	is_enabled	Whether the mailbox region is enabled.
[out]	address	If the mailbox is enabled, the base address of the mailbox region.

Returns: kDifBadArg if any argument is null, else kDifOk.

Definition at line 170 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

	spi	A handle to a spi device.
	command	The command to be queried.
[out]	enabled	A 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 785 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

	spi	A handle to a spi device.
[out]	caps	The TPM's hardware capabilities.

Returns: The result of the operation.

Definition at line 867 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_addr	The MMIO base address of the spi_device peripheral.
[out]	Out	param for the initialized handle.

Returns: The result of the operation.

Definition at line 75 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

	spi	A handle to a spi device.
[out]	address	A 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 695 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

	spi	A handle to a spi device.
[out]	command	A 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 677 of file dif_spi_device.c.

◆ dif_spi_device_read_flash_payload_buffer()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_read_flash_payload_buffer	(	dif_spi_device_handle_t *	spi,
		uint32_t	offset,
		size_t	length,
		uint8_t *	buf
	)

Read data from the payload buffer associated with flash / passthrough modes.

Parameters

	spi	A handle to a spi device.
	offset	The starting offset for read data in the memory.
	length	The length, in bytes, of the data to be copied.
[out]	buf	A 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 payload buffer region. kDifOk otherwise.

Definition at line 738 of file dif_spi_device.c.

◆ dif_spi_device_reset_eflash_buffer()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_reset_eflash_buffer ( dif_spi_device_handle_t * spi )

Clear eflash read buffer state.

Reinitialize the eflash read buffer to initial state.

Parameters

spi	A SPI device.

Returns: kDifBadArg if spi is NULL. kDifOk otherwise.

Definition at line 318 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

spi	A SPI device.
addr_4b	If 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 185 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

spi	A handle to a spi device.
enable	Whether to enable the command filter for all commands.

Returns: kDifBadArg if spi is NULL or enable is invalid. kDifOk otherwise.

Definition at line 818 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

spi	A SPI handle.
address	The 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 308 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

spi	A handle to a spi device.
mask	A bitmask indicating which address bits should be replaced.
replacement	The values to swap in for the masked address bits.

Returns: kDifBadArg if spi is NULL, else kDifOk.

Definition at line 612 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

spi	A handle to a spi device.
slot	A command info slot ID.
enable	Whether to enable or disable the command slot.
command_info	If `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 338 of file dif_spi_device.c.

◆ dif_spi_device_set_flash_id()

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.

Parameters

spi	A SPI device.
id	The JEDEC ID to set.

Returns: kDifBadArg if spi is NULL. kDifOk otherwise.

Definition at line 259 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

spi	A handle to a spi device.
mask	A bitmask indicating which bits should be replaced.
replacement	The values to swap in for the masked bits.

Returns: kDifBadArg if spi is NULL, else kDifOk.

Definition at line 625 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

spi	A handle to a spi device.
value	The value to write to the registers.

Returns: kDifBadArg if spi is NULL. kDifOk otherwise.

Definition at line 847 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

spi	A handle to a spi device.
command	The command to have its filter status updated.
enable	Whether to enable the command filter for the `command`.

Returns: kDifBadArg if spi is NULL or enable is invalid. kDifOk otherwise.

Definition at line 803 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

spi	A SPI handle.
config	The passthrough interception configuration.

Returns: The result of the operation.

Definition at line 279 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

spi	A SPI handle.
enable	Whether to turn on passthrough mode.

Returns: The result of the operation.

Definition at line 110 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

spi	A handle to a spi device.
enable	Whether to enable the TPM block.
config	The TPM configuration.

Returns: The result of the operation.

Definition at line 885 of file dif_spi_device.c.

◆ dif_spi_device_tpm_free_write_fifo()

OT_WARN_UNUSED_RESULT dif_result_t dif_spi_device_tpm_free_write_fifo ( dif_spi_device_handle_t * spi )

Release the TPM's WriteFIFO back to hardware.

Parameters

spi	A handle to a spi device.

Returns: The result of the operation.

Definition at line 1193 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

	spi	A handle to a spi device.
	locality	Which TPM_ACCESS_x register to query, indexed by the locality.
[out]	value	The value of the TPM_ACCESS_x register.

Returns: The result of the operation.

Definition at line 971 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

	spi	A handle to a spi device.
[out]	command	The command opcode.
[out]	address	The address associated with the command.

Returns: The result of the operation.

Definition at line 1124 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

	spi	A handle to a spi device.
[out]	status	The status of the TPM.

Returns: The result of the operation.

Definition at line 921 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

	spi	A handle to a spi device.
[out]	value	The value of the registers.

Returns: The result of the operation.

Definition at line 1106 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

	spi	A handle to a spi device.
[out]	value	The value of the TPM_INT_ENABLE register.

Returns: The result of the operation.

Definition at line 1064 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

spi	A handle to a spi device.
value[out]	The value of the TPM_INT_STATUS register.

Returns: The result of the operation.

Definition at line 1084 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

	spi	A handle to a spi device.
[out]	value	The value of the TPM_INT_VECTOR register.

Returns: The result of the operation.

Definition at line 1074 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

	spi	A handle to a spi device.
[out]	value	The value of the TPM_INTF_CAPABILITY register.

Returns: The result of the operation.

Definition at line 1054 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

	spi	A handle to a spi device.
[out]	value	The value of the TPM_STS register.

Returns: The result of the operation.

Definition at line 1044 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

	spi	A handle to a spi device.
	length	The length, in bytes, of the data to be copied.
[out]	buf	A pointer to the location where the data should be stored.

Returns: The result of the operation.

Definition at line 1171 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

spi	A handle to a spi device.
locality	Which TPM_ACCESS_x register to target, indexed by the locality.
value	The value to set the TPM_ACCESS_x register to.

Returns: The result of the operation.

Definition at line 937 of file dif_spi_device.c.

◆ dif_spi_device_tpm_set_id()

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.

Parameters

spi	A handle to a spi device.
id	The values to set the registers to.

Returns: The result of the operation.

Definition at line 1089 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

spi	A handle to a spi device.
value	The value to set the TPM_INT_ENABLE register to.

Returns: The result of the operation.

Definition at line 1059 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

spi	A handle to a spi device.
value	The value to set the TPM_INT_STATUS register to.

Returns: The result of the operation.

Definition at line 1079 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

spi	A handle to a spi device.
value	The value to set the TPM_INT_VECTOR register to.

Returns: The result of the operation.

Definition at line 1069 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

spi	A handle to a spi device.
value	The value to set the TPM_INTF_CAPABILITY register to.

Returns: The result of the operation.

Definition at line 1049 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

spi	A handle to a spi device.
value	The value to set the TPM_STS register to.

Returns: The result of the operation.

Definition at line 1039 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

spi	A handle to a spi device.
length	The length, in bytes, of the data to be copied.
buf	A pointer to the location of the data to be copied.

Returns: The result of the operation.

Definition at line 1138 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

spi	A handle to a spi device.
buffer_type	An identifier for which memory space to write to.
offset	The starting offset for the write location of the data.
length	The length, in bytes, of the data to be copied.
buf	A 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 760 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.

(90f7989)

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ dif_spi_device_config

◆ dif_spi_device_handle

◆ dif_spi_device_flash_id

◆ dif_spi_device_passthrough_intercept_config

◆ dif_spi_device_flash_command

◆ dif_spi_device_tpm_caps

◆ dif_spi_device_tpm_config

◆ dif_spi_device_tpm_data_status

◆ dif_spi_device_tpm_id

Typedef Documentation

◆ dif_spi_device_config_t

◆ dif_spi_device_passthrough_intercept_config_t

Enumeration Type Documentation

◆ dif_spi_device_bit_order

◆ dif_spi_device_flash_address_type

◆ dif_spi_device_flash_buffer_type

◆ dif_spi_device_mode

◆ dif_spi_device_payload_io

◆ dif_spi_device_read_pipeline_mode

◆ dif_spi_device_tpm_interface

Function Documentation

◆ dif_spi_device_clear_flash_busy_bit()

◆ dif_spi_device_clear_flash_status_request()

◆ dif_spi_device_configure()

◆ dif_spi_device_configure_flash_en4b_command()

◆ dif_spi_device_configure_flash_ex4b_command()

◆ dif_spi_device_configure_flash_wrdi_command()

◆ dif_spi_device_configure_flash_wren_command()

◆ dif_spi_device_disable_mailbox()

◆ dif_spi_device_enable_mailbox()

◆ dif_spi_device_get_4b_address_mode()

◆ dif_spi_device_get_csb_status()

◆ dif_spi_device_get_flash_address_fifo_occupancy()

◆ dif_spi_device_get_flash_command_fifo_occupancy()

◆ dif_spi_device_get_flash_command_slot()

◆ dif_spi_device_get_flash_id()

◆ dif_spi_device_get_flash_payload_fifo_occupancy()

◆ dif_spi_device_get_flash_status_registers()

◆ dif_spi_device_get_last_read_address()

◆ dif_spi_device_get_mailbox_configuration()

◆ dif_spi_device_get_passthrough_command_filter()

◆ dif_spi_device_get_tpm_capabilities()

◆ dif_spi_device_init_handle()

◆ dif_spi_device_pop_flash_address_fifo()

◆ dif_spi_device_pop_flash_command_fifo()

◆ dif_spi_device_read_flash_payload_buffer()

◆ dif_spi_device_reset_eflash_buffer()

◆ dif_spi_device_set_4b_address_mode()

◆ dif_spi_device_set_all_passthrough_command_filters()

◆ dif_spi_device_set_eflash_read_threshold()

◆ dif_spi_device_set_flash_address_swap()

◆ dif_spi_device_set_flash_command_slot()

◆ dif_spi_device_set_flash_id()

◆ dif_spi_device_set_flash_payload_swap()

◆ dif_spi_device_set_flash_status_registers()

◆ dif_spi_device_set_passthrough_command_filter()

◆ dif_spi_device_set_passthrough_intercept_config()

◆ dif_spi_device_set_passthrough_mode()

◆ dif_spi_device_tpm_configure()

◆ dif_spi_device_tpm_free_write_fifo()

◆ dif_spi_device_tpm_get_access_reg()

◆ dif_spi_device_tpm_get_command()

◆ dif_spi_device_tpm_get_data_status()

◆ dif_spi_device_tpm_get_id()

◆ dif_spi_device_tpm_get_int_enable_reg()

◆ dif_spi_device_tpm_get_int_status_reg()

◆ dif_spi_device_tpm_get_int_vector_reg()

◆ dif_spi_device_tpm_get_intf_capability_reg()

◆ dif_spi_device_tpm_get_sts_reg()

◆ dif_spi_device_tpm_read_data()

◆ dif_spi_device_tpm_set_access_reg()

◆ dif_spi_device_tpm_set_id()