(def97ec)

DMA Controller Device Interface Functions More...

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

Data Structures
struct	dif_dma_transaction_address
	Define the transaction address space. More...

struct	dif_dma_transaction
	Parameters for a DMA Controller transaction. More...

struct	dif_dma_handshake
	Parameters for a handshake mode transaction. More...

Typedefs
typedef enum dif_dma_address_space_id	dif_dma_address_space_id_t

typedef enum dif_dma_transaction_width	dif_dma_transaction_width_t

typedef enum dif_dma_transaction_opcode	dif_dma_transaction_opcode_t

typedef struct dif_dma_transaction_address	dif_dma_transaction_address_t
	Define the transaction address space.

typedef struct dif_dma_transaction	dif_dma_transaction_t
	Parameters for a DMA Controller transaction.

typedef struct dif_dma_handshake	dif_dma_handshake_t
	Parameters for a handshake mode transaction.

typedef enum dif_dma_status_code	dif_dma_status_code_t

typedef uint32_t	dif_dma_status_t
	Bitmask with the `dif_dma_status_code_t` values.

typedef enum dif_dma_error_code	dif_dma_error_code_t

typedef enum dif_dma_intr_idx	dif_dma_intr_idx_t
	Address index for every interrupt. More...

Enumerations
enum	dif_dma_address_space_id { kDifDmaOpentitanInternalBus = 0x07, kDifDmaSoCControlRegisterBus = 0x0a, kDifDmaSoCSystemBus = 0x09 }

enum	dif_dma_transaction_width { kDifDmaTransWidth1Byte = 0x00, kDifDmaTransWidth2Bytes = 0x01, kDifDmaTransWidth4Bytes = 0x02 }

enum	dif_dma_transaction_opcode { kDifDmaCopyOpcode = 0x00, kDifDmaSha256Opcode = 0x01, kDifDmaSha384Opcode = 0x02, kDifDmaSha512Opcode = 0x03 }

enum	dif_dma_status_code { kDifDmaStatusBusy = 0x01 << DMA_STATUS_BUSY_BIT, kDifDmaStatusDone = 0x01 << DMA_STATUS_DONE_BIT, kDifDmaStatusAborted = 0x01 << DMA_STATUS_ABORTED_BIT, kDifDmaStatusError = 0x01 << DMA_STATUS_ERROR_BIT, kDifDmaStatusSha2DigestValid = 0x01 << DMA_STATUS_SHA2_DIGEST_VALID_BIT }

enum	dif_dma_error_code { kDifDmaErrorNone = 0x00, kDifDmaErrorSourceAddress = 0x01 << 0, kDifDmaErrorDestinationAddress = 0x01 << 1, kDifDmaErrorOpcode = 0x01 << 2, kDifDmaErrorSize = 0x01 << 3, kDifDmaErrorBus = 0x01 << 4, kDifDmaErrorEnableMemoryConfig = 0x01 << 5, kDifDmaErrorRangeValid = 0x01 << 6, kDifDmaErrorInvalidAsid = 0x01 << 7 }

enum	dif_dma_intr_idx { kDifDmaIntrClearIdx0 = 0x0, kDifDmaIntrClearIdx1 = 0x4, kDifDmaIntrClearIdx2 = 0x8, kDifDmaIntrClearIdx3 = 0xC, kDifDmaIntrClearIdx4 = 0x10, kDifDmaIntrClearIdx5 = 0x14, kDifDmaIntrClearIdx6 = 0x18, kDifDmaIntrClearIdx7 = 0x1C, kDifDmaIntrClearIdx8 = 0x20, kDifDmaIntrClearIdx9 = 0x24, kDifDmaIntrClearIdx10 = 0x28 }
	Address index for every interrupt. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_configure (const dif_dma_t *dma, dif_dma_transaction_t transaction)
	Configures DMA Controller for a transaction. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_handshake_enable (const dif_dma_t *dma, dif_dma_handshake_t handshake)
	Configures DMA Controller hardware handshake mode. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_handshake_disable (const dif_dma_t *dma)
	Disable DMA Controller hardware handshake mode. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_start (const dif_dma_t *dma, dif_dma_transaction_opcode_t opcode)
	Begins a DMA Controller transaction. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_abort (const dif_dma_t *dma)
	Abort the DMA Controller transaction in execution. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_memory_range_set (const dif_dma_t *dma, uint32_t address, size_t size)
	Set the DMA enabled memory range within the OT internal memory space. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_memory_range_get (const dif_dma_t dma, uint32_t address, size_t *size)
	Get the DMA enabled memory range within the OT internal memory space. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_memory_range_lock (const dif_dma_t *dma)
	Locks out the DMA memory range register. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_is_memory_range_locked (const dif_dma_t dma, bool is_locked)
	Checks whether the DMA memory range is locked. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_is_memory_range_valid (const dif_dma_t dma, bool is_valid)
	Checks whether the DMA memory range is valid. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_status_get (const dif_dma_t dma, dif_dma_status_t status)
	Reads the DMA status. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_status_write (const dif_dma_t *dma, dif_dma_status_t status)
	Writes the DMA status register and clears the corrsponding status bits. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_status_clear (const dif_dma_t *dma)
	Clear all status bits of the status register. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_status_poll (const dif_dma_t *dma, dif_dma_status_code_t flag)
	Poll the DMA status util a given flag in the register is set. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_error_code_get (const dif_dma_t dma, dif_dma_error_code_t error)
	Reads the DMA error code. More...

dif_result_t	dif_dma_get_digest_length (dif_dma_transaction_opcode_t opcode, uint32_t *digest_len)
	Return the digest length given a DMA opcode. More...

dif_result_t	dif_dma_sha2_digest_get (const dif_dma_t *dma, dif_dma_transaction_opcode_t opcode, uint32_t digest[])
	Read out the SHA2 digest. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_handshake_irq_enable (const dif_dma_t *dma, uint32_t enable_state)
	Enable DMA controller handshake interrupt. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_handshake_clear_irq (const dif_dma_t *dma, uint32_t clear_state)
	Enable the corresponding DME handshake interrupt clearing mechanism. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_handshake_clear_irq_bus (const dif_dma_t *dma, uint32_t clear_irq_bus)
	Select the bus interface for the interrupt clearing mechanism. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_intr_src_addr (const dif_dma_t *dma, dif_dma_intr_idx_t idx, uint32_t intr_src_addr)
	Set the write address for the interrupt clearing mechanism. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_dma_intr_write_value (const dif_dma_t *dma, dif_dma_intr_idx_t idx, uint32_t intr_src_value)
	Set the write value for the interrupt clearing mechanism. More...

Detailed Description

DMA Controller Device Interface Functions

Definition in file dif_dma.h.

Data Structure Documentation

◆ dif_dma_transaction_address

struct dif_dma_transaction_address

Define the transaction address space.

Definition at line 61 of file dif_dma.h.

Data Fields
uint64_t	address
dif_dma_address_space_id_t	asid

◆ dif_dma_transaction

struct dif_dma_transaction

Parameters for a DMA Controller transaction.

Definition at line 69 of file dif_dma.h.

Data Fields
size_t	chunk_size
dif_dma_transaction_address_t	destination
dif_dma_transaction_address_t	source
size_t	total_size
dif_dma_transaction_width_t	width

◆ dif_dma_handshake

struct dif_dma_handshake

Parameters for a handshake mode transaction.

Definition at line 96 of file dif_dma.h.

Data Fields
bool	direction_from_mem_to_fifo
bool	fifo_auto_increment
bool	memory_auto_increment

Typedef Documentation

◆ dif_dma_intr_idx_t

typedef enum dif_dma_intr_idx dif_dma_intr_idx_t

Address index for every interrupt.

Used to configure the write address and write value for the interrupt clearing mechanism.

Enumeration Type Documentation

◆ dif_dma_intr_idx

enum dif_dma_intr_idx

Address index for every interrupt.

Used to configure the write address and write value for the interrupt clearing mechanism.

Definition at line 372 of file dif_dma.h.

Function Documentation

◆ dif_dma_abort()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_abort ( const dif_dma_t * dma )

Abort the DMA Controller transaction in execution.

Parameters

dma	A DMA Controller handle.

Returns: The result of the operation.

Definition at line 102 of file dif_dma.c.

◆ dif_dma_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_configure	(	const dif_dma_t *	dma,
		dif_dma_transaction_t	transaction
	)

Configures DMA Controller for a transaction.

This function should be called every time before dif_dma_start.

Parameters

dma	A DMA Controller handle.
config	Transaction configuration parameters.

Returns: The result of the operation.

Definition at line 22 of file dif_dma.c.

◆ dif_dma_error_code_get()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_error_code_get	(	const dif_dma_t *	dma,
		dif_dma_error_code_t *	error
	)

Reads the DMA error code.

Parameters

	dma	A DMA Controller handle.
[out]	error	Out-param for the error code.

Returns: The result of the operation.

Definition at line 220 of file dif_dma.c.

◆ dif_dma_get_digest_length()

dif_result_t dif_dma_get_digest_length	(	dif_dma_transaction_opcode_t	opcode,
		uint32_t *	digest_len
	)

Return the digest length given a DMA opcode.

Parameters

opcode	A DMA opcode.
digest_len	The digest length.

Returns: The result of the operation.

Definition at line 230 of file dif_dma.c.

◆ dif_dma_handshake_clear_irq()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_handshake_clear_irq	(	const dif_dma_t *	dma,
		uint32_t	clear_state
	)

Enable the corresponding DME handshake interrupt clearing mechanism.

Parameters

dma	A DMA Controller handle.
clear_state	Enable interrupt clearing mechanism. The bit position corresponds to the IRQ index.

Returns: The result of the operation.

Definition at line 281 of file dif_dma.c.

◆ dif_dma_handshake_clear_irq_bus()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_handshake_clear_irq_bus	(	const dif_dma_t *	dma,
		uint32_t	clear_irq_bus
	)

Select the bus interface for the interrupt clearing mechanism.

0: CTN/System fabric 1: OT-internal crossbar

Parameters

dma	A DMA Controller handle.
clear_irq_bus	Bus selection for the clearing mechanism. The bit position corresponds to the IRQ index.

Returns: The result of the operation.

Definition at line 292 of file dif_dma.c.

◆ dif_dma_handshake_disable()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_handshake_disable ( const dif_dma_t * dma )

Disable DMA Controller hardware handshake mode.

Parameters

dma	A DMA Controller handle.

Returns: The result of the operation.

Definition at line 76 of file dif_dma.c.

◆ dif_dma_handshake_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_handshake_enable	(	const dif_dma_t *	dma,
		dif_dma_handshake_t	handshake
	)

Configures DMA Controller hardware handshake mode.

This function should be called before dif_dma_start.

Hardware handshake mode is used to push / pop FIFOs to / from low speed IO peripherals receiving data e.g. I3C receive buffer.

Parameters

dma	A DMA Controller handle.
handshake	Hardware handshake configuration parameters.

Returns: The result of the operation.

Definition at line 56 of file dif_dma.c.

◆ dif_dma_handshake_irq_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_handshake_irq_enable	(	const dif_dma_t *	dma,
		uint32_t	enable_state
	)

Enable DMA controller handshake interrupt.

Parameters

dma	A DMA Controller handle.
enable_state	Enable state. The bit position corresponds to the IRQ index.

Returns: The result of the operation.

Definition at line 271 of file dif_dma.c.

◆ dif_dma_intr_src_addr()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_intr_src_addr	(	const dif_dma_t *	dma,
		dif_dma_intr_idx_t	idx,
		uint32_t	intr_src_addr
	)

Set the write address for the interrupt clearing mechanism.

Parameters

dma	A DMA Controller handle.
idx	Index of the selected interrupt.
intr_src_addr	Address to write the interrupt clearing value to.

Returns: The result of the operation.

Definition at line 303 of file dif_dma.c.

◆ dif_dma_intr_write_value()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_intr_write_value	(	const dif_dma_t *	dma,
		dif_dma_intr_idx_t	idx,
		uint32_t	intr_src_value
	)

Set the write value for the interrupt clearing mechanism.

Parameters

dma	A DMA Controller handle.
idx	Index of the selected interrupt.
intr_src_value	Value to write the interrupt clearing value to.

Returns: The result of the operation.

Definition at line 314 of file dif_dma.c.

◆ dif_dma_is_memory_range_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_is_memory_range_locked	(	const dif_dma_t *	dma,
		bool *	is_locked
	)

Checks whether the DMA memory range is locked.

Parameters

	dma	A DMA Controller handle.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 158 of file dif_dma.c.

◆ dif_dma_is_memory_range_valid()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_is_memory_range_valid	(	const dif_dma_t *	dma,
		bool *	is_valid
	)

Checks whether the DMA memory range is valid.

Parameters

	dma	A DMA Controller handle.
[out]	is_valid	Out-param for the valid state.

Returns: The result of the operation.

Definition at line 169 of file dif_dma.c.

◆ dif_dma_memory_range_get()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_memory_range_get	(	const dif_dma_t *	dma,
		uint32_t *	address,
		size_t *	size
	)

Get the DMA enabled memory range within the OT internal memory space.

Parameters

	dma	A DMA Controller handle.
[out]	address	Out-param for the base address.
[out]	size	Out-param for the range size.

Returns: The result of the operation.

Definition at line 131 of file dif_dma.c.

◆ dif_dma_memory_range_lock()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_memory_range_lock ( const dif_dma_t * dma )

Locks out the DMA memory range register.

This function is reentrant: calling it while functionality is locked will have no effect and return kDifOk.

Parameters

dma	A DMA Controller handle.

Returns: The result of the operation.

Definition at line 148 of file dif_dma.c.

◆ dif_dma_memory_range_set()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_memory_range_set	(	const dif_dma_t *	dma,
		uint32_t	address,
		size_t	size
	)

Set the DMA enabled memory range within the OT internal memory space.

Parameters

dma	A DMA Controller handle.
address	Base address.
size	The range size.

Returns: The result of the operation.

Definition at line 113 of file dif_dma.c.

◆ dif_dma_sha2_digest_get()

dif_result_t dif_dma_sha2_digest_get	(	const dif_dma_t *	dma,
		dif_dma_transaction_opcode_t	opcode,
		uint32_t	digest[]
	)

Read out the SHA2 digest.

Parameters

	dma	A DMA Controller handle.
	opcode	The opcode to select the length of the read digest.
[out]	digest	Pointer to the digest, to store the read values.

Returns: The result of the operation.

Definition at line 252 of file dif_dma.c.

◆ dif_dma_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_start	(	const dif_dma_t *	dma,
		dif_dma_transaction_opcode_t	opcode
	)

Begins a DMA Controller transaction.

Before this function the DMA transaction shall be configured by calling the function dif_dma_configure and optionally dif_dma_handshake_enable can be called.

Parameters

dma	A DMA Controller handle.
opcode	Transaction opcode.

Returns: The result of the operation.

Definition at line 88 of file dif_dma.c.

◆ dif_dma_status_clear()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_status_clear ( const dif_dma_t * dma )

Clear all status bits of the status register.

Parameters

dma	A DMA Controller handle.

Returns: The result of the operation.

Definition at line 199 of file dif_dma.c.

◆ dif_dma_status_get()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_status_get	(	const dif_dma_t *	dma,
		dif_dma_status_t *	status
	)

Reads the DMA status.

Parameters

	dma	A DMA Controller handle.
[out]	status	Out-param for the status.

Returns: The result of the operation.

Definition at line 179 of file dif_dma.c.

◆ dif_dma_status_poll()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_status_poll	(	const dif_dma_t *	dma,
		dif_dma_status_code_t	flag
	)

Poll the DMA status util a given flag in the register is set.

Parameters

dma	A DMA Controller handle.
flag	The status that needs to bet set.

Returns: The result of the operation.

Definition at line 204 of file dif_dma.c.

◆ dif_dma_status_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_dma_status_write	(	const dif_dma_t *	dma,
		dif_dma_status_t	status
	)

Writes the DMA status register and clears the corrsponding status bits.

Parameters

dma	A DMA Controller handle.
status	Status bits to be cleared.

Returns: The result of the operation.

Definition at line 189 of file dif_dma.c.

(def97ec)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_dma_transaction_address

◆ dif_dma_transaction

◆ dif_dma_handshake

Typedef Documentation

◆ dif_dma_intr_idx_t

Enumeration Type Documentation

◆ dif_dma_intr_idx

Function Documentation

◆ dif_dma_abort()

◆ dif_dma_configure()

◆ dif_dma_error_code_get()

◆ dif_dma_get_digest_length()

◆ dif_dma_handshake_clear_irq()

◆ dif_dma_handshake_clear_irq_bus()

◆ dif_dma_handshake_disable()

◆ dif_dma_handshake_enable()

◆ dif_dma_handshake_irq_enable()

◆ dif_dma_intr_src_addr()

◆ dif_dma_intr_write_value()

◆ dif_dma_is_memory_range_locked()

◆ dif_dma_is_memory_range_valid()

◆ dif_dma_memory_range_get()

◆ dif_dma_memory_range_lock()

◆ dif_dma_memory_range_set()

◆ dif_dma_sha2_digest_get()

◆ dif_dma_start()

◆ dif_dma_status_clear()

◆ dif_dma_status_get()

◆ dif_dma_status_poll()

◆ dif_dma_status_write()