dif_dma.h File Reference

(5184668f82)

DMA Controller Device Interface Functions More...

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

Go to the source code of this file.

Data Structures
struct	dif_dma_transaction_address
	Define the transaction address space. More...
struct	dif_dma_address_config
	Addressing configuration. More...
struct	dif_dma_transaction
	Parameters for a DMA Controller 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_address_config	dif_dma_address_config_t
	Addressing configuration.
typedef struct dif_dma_transaction	dif_dma_transaction_t
	Parameters for a DMA Controller 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 ,   kDifDmaStatusChunkDone = 0x01 << DMA_STATUS_CHUNK_DONE_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)
	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_address_config

struct dif_dma_address_config

Addressing configuration.

Definition at line 69 of file dif_dma.h.

Data Fields
bool	increment
bool	wrap

dif_dma_transaction

struct dif_dma_transaction

Parameters for a DMA Controller transaction.

Definition at line 79 of file dif_dma.h.

Data Fields
size_t	chunk_size
dif_dma_transaction_address_t	destination
dif_dma_address_config_t	dst_config
dif_dma_transaction_address_t	source
dif_dma_address_config_t	src_config
size_t	total_size
dif_dma_transaction_width_t	width

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 367 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 114 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 232 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 242 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 293 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 304 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 88 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

)

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.

Returns

The result of the operation.

Definition at line 76 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 283 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 315 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 326 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 170 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 181 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 143 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 160 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 125 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 264 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 100 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 211 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 191 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 216 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 201 of file dif_dma.c.