 |
Software APIs
|
|
Software APIs
|
RRAM Controller Device Interface Functions More...
#include <stdbool.h>#include <stdint.h>#include "sw/device/lib/base/macros.h"#include "sw/device/lib/base/mmio.h"#include "sw/device/lib/base/multibits.h"#include "sw/device/lib/dif/dif_base.h"#include "sw/device/lib/dif/autogen/dif_rram_ctrl_autogen.h"Go to the source code of this file.
Data Structures | |
| struct | dif_rram_ctrl_state |
| Carries transaction state for a RRAM controller device. More... | |
| struct | dif_rram_ctrl_device_info |
| struct | dif_rram_ctrl_status |
| Status bits that can be queried. More... | |
| struct | dif_rram_ctrl_transaction |
| struct | dif_rram_ctrl_error_codes |
| struct | dif_rram_ctrl_error |
| Represents recoverable errors and synchronous errors caused by software. More... | |
| struct | dif_rram_ctrl_output |
| struct | dif_rram_ctrl_region_properties |
| Memory protection configuration options. More... | |
| struct | dif_rram_ctrl_data_region_properties |
| A composite of a data region and its memory properties. More... | |
| struct | dif_rram_ctrl_info_region |
| Representation of the memory protection regions for the info pages. More... | |
| struct | dif_rram_ctrl_faults |
| struct | dif_rram_ctrl_ecc_errors |
| struct | dif_rram_ctrl_phy_status |
Typedefs | |
| typedef struct dif_rram_ctrl_state | dif_rram_ctrl_state_t |
| Carries transaction state for a RRAM controller device. | |
| typedef struct dif_rram_ctrl_device_info | dif_rram_ctrl_device_info_t |
| typedef struct dif_rram_ctrl_status | dif_rram_ctrl_status_t |
| Status bits that can be queried. | |
| typedef enum dif_rram_ctrl_partition_type | dif_rram_ctrl_partition_type_t |
| Enum to represent the RRAM partition type (data or info). | |
| typedef enum dif_rram_ctrl_operation | dif_rram_ctrl_operation_t |
| typedef struct dif_rram_ctrl_transaction | dif_rram_ctrl_transaction_t |
| typedef struct dif_rram_ctrl_error_codes | dif_rram_ctrl_error_codes_t |
| typedef struct dif_rram_ctrl_error | dif_rram_ctrl_error_t |
| Represents recoverable errors and synchronous errors caused by software. | |
| typedef struct dif_rram_ctrl_output | dif_rram_ctrl_output_t |
| typedef struct dif_rram_ctrl_region_properties | dif_rram_ctrl_region_properties_t |
| Memory protection configuration options. | |
| typedef struct dif_rram_ctrl_data_region_properties | dif_rram_ctrl_data_region_properties_t |
| A composite of a data region and its memory properties. | |
| typedef struct dif_rram_ctrl_info_region | dif_rram_ctrl_info_region_t |
| Representation of the memory protection regions for the info pages. | |
| typedef struct dif_rram_ctrl_faults | dif_rram_ctrl_faults_t |
| typedef struct dif_rram_ctrl_ecc_errors | dif_rram_ctrl_ecc_errors_t |
| typedef struct dif_rram_ctrl_phy_status | dif_rram_ctrl_phy_status_t |
Enumerations | |
| enum | dif_rram_ctrl_partition_type { kDifRramCtrlPartitionTypeData = 0 , kDifRramCtrlPartitionTypeInfo = 1 } |
| Enum to represent the RRAM partition type (data or info). More... | |
| enum | dif_rram_ctrl_operation { kDifRramCtrlOpRead = 0 , kDifRramCtrlOpWrite = 1 , kDifRramCtrlOpRewrite = 2 } |
RRAM Controller Device Interface Functions
Definition in file dif_rram_ctrl.h.
| struct dif_rram_ctrl_state |
Carries transaction state for a RRAM controller device.
All members except dev should be considered private and should not be accessed directly outside of the DIF implementation.
Definition at line 34 of file dif_rram_ctrl.h.
| Data Fields | ||
|---|---|---|
| dif_rram_ctrl_t | dev | Contains autogenerated device information, like the base address for registers in the RRAM controller device. |
| bool | transaction_pending | Whether a transaction is pending completion. |
| uint32_t | words_remaining | Number of words remaining for the current transaction. |
| struct dif_rram_ctrl_device_info |
Definition at line 69 of file dif_rram_ctrl.h.
| struct dif_rram_ctrl_status |
Status bits that can be queried.
Definition at line 156 of file dif_rram_ctrl.h.
| struct dif_rram_ctrl_transaction |
Definition at line 216 of file dif_rram_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | byte_address |
Byte address (in the RRAM address space) to start the operation. For operations at a granularity of words, the RRAM controller will truncate to the closest, lower word aligned address. For example, if 0x13 is supplied for a read, the controller will perform a read at address 0x10. For write operations, the granularity is 4 words or 16 bytes. The RRAM controller and |
| dif_rram_ctrl_operation_t | op | |
| dif_rram_ctrl_partition_type_t | partition_type | The partition type for the transaction. |
| uint32_t | word_count |
Number of 32-bit words in the operation. Must be in the range [1,1024] (inclusive) for write or read operations. For write operations the number of 32-bit words must be a multiple of 4. |
| struct dif_rram_ctrl_error_codes |
Definition at line 400 of file dif_rram_ctrl.h.
| struct dif_rram_ctrl_error |
Represents recoverable errors and synchronous errors caused by software.
Definition at line 422 of file dif_rram_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | address | For errors associated with an address, the address where the error occurred. |
| dif_rram_ctrl_error_codes_t | codes | A set of error codes. |
| struct dif_rram_ctrl_output |
Definition at line 459 of file dif_rram_ctrl.h.
| Data Fields | ||
|---|---|---|
| dif_rram_ctrl_error_t | error_code |
The error code associated with an operation_error. This field is only valid if |
| bool | operation_done | RRAM operation done. |
| bool | operation_error | RRAM operation error. |
| struct dif_rram_ctrl_region_properties |
Memory protection configuration options.
Definition at line 496 of file dif_rram_ctrl.h.
| Data Fields | ||
|---|---|---|
| multi_bit_bool_t | ecc_en | ECC enable flag. |
| multi_bit_bool_t | rd_en | Read enable flag. |
| multi_bit_bool_t | scramble_en | Scramble enable flag. |
| multi_bit_bool_t | wr_en | Write enable flag. |
| struct dif_rram_ctrl_data_region_properties |
A composite of a data region and its memory properties.
Definition at line 510 of file dif_rram_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | base | Region base page index. |
| dif_rram_ctrl_region_properties_t | properties | Memory properties of the region. |
| uint32_t | size | Region config size (in number of pages). |
| struct dif_rram_ctrl_info_region |
Representation of the memory protection regions for the info pages.
Definition at line 522 of file dif_rram_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | page | Region page index. |
| struct dif_rram_ctrl_faults |
Definition at line 852 of file dif_rram_ctrl.h.
| struct dif_rram_ctrl_ecc_errors |
Definition at line 884 of file dif_rram_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | corr_error_count | Count of the number of correctable ECC errors. |
| uint32_t | last_error_address | The last address that produced a correctable ECC error. |
| dif_rram_ctrl_partition_type_t | last_error_partition | The last partition that produced a correctable ECC error. |
| struct dif_rram_ctrl_phy_status |
Definition at line 906 of file dif_rram_ctrl.h.
| Data Fields | ||
|---|---|---|
| bool | phy_init_done | RRAM phy controller initialization complete. |
| bool | phy_wr_busy | RRAM phy write operation in progress. |
| typedef struct dif_rram_ctrl_state dif_rram_ctrl_state_t |
Carries transaction state for a RRAM controller device.
All members except dev should be considered private and should not be accessed directly outside of the DIF implementation.
| Enumerator | |
|---|---|
| kDifRramCtrlOpRead | Read the specified number of words. |
| kDifRramCtrlOpWrite | Write the specified number of words. |
| kDifRramCtrlOpRewrite | Rewrite a specific word to repair it. |
Definition at line 207 of file dif_rram_ctrl.h.
Enum to represent the RRAM partition type (data or info).
Definition at line 202 of file dif_rram_ctrl.h.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_clear_error_codes | ( | dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_error_codes_t | codes ) |
Clear the error codes.
| handle | The RRAM controller DIF state. |
| codes | The error codes to clear. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 418 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_clear_rd_fifo | ( | dif_rram_ctrl_state_t * | handle | ) |
Clears the read FIFO.
This is useful in the event of an unexpected error as a means of reseting state.
Note that this does not reset the handle's internal words_remaining or transaction_pending tracking. After an aborted transaction, the handle must be reinitialized with dif_rram_ctrl_init_state() (which has no MMIO side effects) before starting a new one; otherwise dif_rram_ctrl_start() returns kDifUnavailable and dif_rram_ctrl_end() returns kDifIpFifoFull. See #30909 for adding a proper way to abort an ongoing transaction.
| handle | The RRAM controller DIF state. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 840 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_clear_wr_fifo | ( | dif_rram_ctrl_state_t * | handle | ) |
Clears the write FIFO.
This is useful in the event of an unexpected error as a means of reseting state.
Note that this does not reset the handle's internal words_remaining or transaction_pending tracking. After an aborted transaction, the handle must be reinitialized with dif_rram_ctrl_init_state() (which has no MMIO side effects) before starting a new one; otherwise dif_rram_ctrl_start() returns kDifUnavailable and dif_rram_ctrl_end() returns kDifIpFifoFull. See #30909 for adding a proper way to abort an ongoing transaction.
| handle | The RRAM controller DIF state. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 830 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_data_region_is_locked | ( | const dif_rram_ctrl_state_t * | handle, |
| uint32_t | region, | ||
| bool * | locked_out ) |
Query the state of the region configuration lock for the given data region entry's index.
This function checks if memory region configuration is still enabled or if it has been locked. Once locked, region configuration cannot be enabled again, and all calls to region configuration functions will return kDifLocked until the device is restarted.
| handle | The RRAM controller DIF state. | |
| region | The region in question. | |
| [out] | locked_out | Out-parameter, the current state of the region's configuration lock. |
kDifBadArg if handle or locked_out is null, or if region is invalid, kDifOk otherwise. Definition at line 762 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_end | ( | dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_output_t * | out ) |
Check that the transaction has completed and return any resulting error codes.
Does not clear the error codes, but does clear the operation status if the operation has terminated.
| handle | The RRAM controller DIF state. | |
| [out] | out | Out parameter. Contains the transaction status and error codes. |
kDifBadArg if handle or out are null, kDifError if no transaction was pending, kDifUnavailable if the controller is still processing the transaction, kDifIpFifoFull if there are still words remaining for the FIFOs, and kDifOk otherwise. Definition at line 437 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_data_region_enablement | ( | const dif_rram_ctrl_state_t * | handle, |
| uint32_t | region, | ||
| dif_toggle_t * | enabled_out ) |
Get the enabled/disabled state for the indicated data region.
| handle | The RRAM controller DIF state. | |
| region | The region in question. | |
| [out] | enabled_out | Out-parameter, the enabled/disabled state of this region. |
kDifBadArg if handle or enabled_out is null, or if region is invalid, kDifOk otherwise. Definition at line 499 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_data_region_properties | ( | const dif_rram_ctrl_state_t * | handle, |
| uint32_t | region, | ||
| dif_rram_ctrl_data_region_properties_t * | config_out ) |
Get the memory properties for the data region of RRAM indexed by region.
| handle | The RRAM controller DIF state. | |
| region | The index of the region entry in question. | |
| [out] | config_out | Out-parameter, a pointer to a dif_rram_ctrl_data_region_properties_t struct for writing the full entry showing the region configuration and its memory properties. |
kDifBadArg if handle or config_out is null or if region is invalid. kDifOk otherwise. Definition at line 645 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_default_region_properties | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_region_properties_t * | properties_out ) |
Get the default memory properties for data regions, when they are not overridden by a specific entry in the data region memory properties table.
| handle | The RRAM controller DIF state. | |
| [out] | properties_out | Out-parameter, a pointer to a dif_rram_ctrl_region_properties_t struct for writing the memory properties. |
kDifBadArg if handle or properties_out is null. kDifOk otherwise. Definition at line 584 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_rram_ctrl_device_info_t dif_rram_ctrl_get_device_info | ( | void | ) |
Get information on the RRAM controller sizes.
dif_rram_ctrl_device_info_t representing the feature sizes for various components of the RRAM. Definition at line 86 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_ecc_errors | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_ecc_errors_t * | errors_out ) |
Get the ECC error information of the RRAM.
| handle | The RRAM controller DIF state. | |
| [out] | errors_out | Out parameter, the ECC error information. |
kDifBadArg if handle or errors_out is null. kDifOk otherwise. Definition at line 879 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_error_codes | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_error_t * | error_code_out ) |
Get the error codes and address of the last associated error.
| handle | The RRAM controller DIF state. | |
| [out] | error_code_out | Output parameter. The location where the current status is to be stored. |
kDifBadArg if handle or error_code_out is null. kDifOk otherwise. Definition at line 389 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_exec_enablement | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_toggle_t * | enabled_out ) |
Get whether execution / fetch access is enabled.
| handle | The RRAM controller DIF state. | |
| [out] | enabled_out | Out parameter, whether execution / fetch access is allowed. |
kDifBadArg if handle or enabled_out is null. kDifOk otherwise. Definition at line 156 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_faults | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_faults_t * | faults_out ) |
Gets the unrecoverable or hardware faults.
| handle | The RRAM controller DIF state. | |
| [out] | faults_out | Out parameter, a pointer to the location to write the fault values. |
kDifBadArg if handle or faults_out is null. kDifOk otherwise. Definition at line 850 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_fifo_watermarks | ( | const dif_rram_ctrl_state_t * | handle, |
| uint32_t * | write_out, | ||
| uint32_t * | read_out ) |
Get the interrupt watermarks for the write and read FIFOs.
| handle | The RRAM controller DIF state. | |
| [out] | write_out | Out-parameter, the write FIFO watermark level. If the write FIFO empties to this level, a corresponding status bit and possibly an interrupt may be generated. May be null. |
| [out] | read_out | Out-parameter, the read FIFO watermark level. If the read FIFO fills to this level, a corresponding status bit and possibly an interrupt may be generated. May be null. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 813 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_info_region_enablement | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_info_region_t | region, | ||
| dif_toggle_t * | enabled_out ) |
Get the enabled/disabled state for the indicated info region.
| handle | The RRAM controller DIF state. | |
| region | The region in question. | |
| [out] | enabled_out | Out-parameter, the enabled/disabled state of this region. |
kDifBadArg if handle or enabled_out is null, or if region is invalid, kDifOk otherwise. Definition at line 547 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_info_region_properties | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_info_region_t | region, | ||
| dif_rram_ctrl_region_properties_t * | properties_out ) |
Get the memory properties for the info region of RRAM identified by region.
| handle | The RRAM controller DIF state. | |
| region | The index of the region entry in question. | |
| [out] | properties_out | Out-parameter, a pointer to a dif_rram_ctrl_region_properties_t struct for writing memory properties associated with the indicated region. |
kDifBadArg if handle or properties_out is null or if region is invalid. kDifOk otherwise. Definition at line 701 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_phy_status | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_phy_status_t * | status_out ) |
Query the status registers on the RRAM controller.
This function checks the various status bits as described in dif_rram_ctrl_phy_status_t.
| handle | The RRAM controller DIF state. | |
| [out] | status_out | Out-parameter, the current status of the RRAM phy. |
kDifBadArg if handle or status_out is null. kDifOk otherwise. Definition at line 901 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_rram_enablement | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_toggle_t * | enabled_out ) |
Get whether RRAM functionality is enabled.
| handle | The RRAM controller DIF state. | |
| [out] | enabled_out | Out parameter, where to store whether RRAM is enabled. |
kDifBadArg if handle or enabled_out is null. kDifOk otherwise. Definition at line 119 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_scratch | ( | const dif_rram_ctrl_state_t * | handle, |
| uint32_t * | value_out ) |
Get the value of the scratch register.
| handle | The RRAM controller DIF state. | |
| [out] | value_out | Out parameter. The location to write the scratch register's value to. |
kDifBadArg if handle or value_out is null. kDifOk otherwise. Definition at line 928 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_get_status | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_status_t * | status_out ) |
Query the status registers on the RRAM controller.
This function checks the various status bits as described in dif_rram_ctrl_status_t.
| handle | The RRAM controller DIF state. | |
| [out] | status_out | Out parameter. The current status of the RRAM controller. |
kDifBadArg if handle or status_out is null. kDifOk otherwise. Definition at line 187 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_info_region_is_locked | ( | const dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_info_region_t | region, | ||
| bool * | locked_out ) |
Query the state of the region configuration lock for the given info region.
This function checks if memory region configuration is still enabled or if it has been locked. Once locked, region configuration cannot be enabled again, and all calls to region configuration functions will return kDifLocked until the device is restarted.
| handle | The RRAM controller DIF state. | |
| region | The region in question. | |
| [out] | locked_out | Out-parameter, the current state of the region's configuration lock. |
kDifBadArg if handle or locked_out is null, or if region is invalid, kDifOk otherwise. Definition at line 774 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_init_state | ( | dif_rram_ctrl_state_t * | handle, |
| mmio_region_t | base_addr ) |
Initialize the DIF state for the RRAM controller.
| handle | The RRAM controller DIF state to initialize. |
| base_addr | The base address for the RRAM controller. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 69 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_init_state_from_dt | ( | dif_rram_ctrl_state_t * | handle, |
| dt_rram_ctrl_t | dt ) |
Initialize the DIF state for the RRAM controller from a device tree handle.
| handle | The RRAM controller DIF state to initialize. |
| dt | The RRAM controller device tree handle. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 80 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_lock_data_region_properties | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | region ) |
Lock data region memory properties configuration until the device is reset.
This will prevent any further configuration of region properties until device reset. Future calls to functions that set data region memory properties will return kDifLocked.
| handle | The RRAM controller DIF state. |
| region | The region to lock. |
kDifBadArg if handle is null or region is invalid, kDifLocked if configuration is already locked, kDifOk otherwise. Definition at line 724 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_lock_info_region_properties | ( | dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_info_region_t | region ) |
Lock info region memory properties configuration until the device is reset.
This will prevent any further configuration of region properties until device reset. Future calls to functions that set info region memory properties will return kDifLocked.
| handle | The RRAM controller DIF state. |
| region | The region to lock. |
kDifBadArg if handle is null or region is invalid, kDifLocked if configuration is already locked, kDifOk otherwise. Definition at line 743 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_read_fifo_pop | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | word_count, | ||
| uint32_t * | data_out ) |
Read data from the read FIFO.
Attempts to read word_count words from the read FIFO.
The following conditions are required:
data_out must reference a contiguous, allocated, writable region of at least word_count words, violation of this will produce undefined behavior.word_count must not exceed what was supplied at the start of the read transaction.word_count must not exceed word_count - words_received from the previous call. All deviations on the above will produce a kDifBadArg error unless otherwise specified.If the FIFO empties this function will cause the CPU to block until the RRAM controller fills the FIFO with more data.
It is up to the caller to call dif_rram_ctrl_end() to ensure the RRAM controller completed this transaction successfully.
| handle | The RRAM controller DIF state. | |
| word_count | The number of words to read. | |
| [out] | data_out | The region in memory to store the data read off the FIFO. |
kDifBadArg if handle or data_out are null, or if the value of word_count is illegal. kDifOk otherwise. Definition at line 368 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_read_fifo_pop_unsafe | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | word_count, | ||
| uint32_t * | data_out ) |
Read data from the read FIFO.
(unsafe version)
This function is primarily for testing hardware error responses. If you are not specifically trying to force an error, consider dif_rram_ctrl_read_fifo_pop() instead. This function does not check if a transaction is currently in progress, nor if this would cause a read beyond the number of words for the current operation.
Attempts to read word_count words from the read FIFO without consideration for the current controller state.
It is up to the caller to call dif_rram_ctrl_end() to ensure the RRAM controller completed this transaction successfully.
| handle | The RRAM controller DIF state. | |
| word_count | The number of words to read. | |
| [out] | data_out | The region in memory to store the data read off the FIFO. |
kDifBadArg if handle or data_out are null. kDifOk otherwise. Definition at line 353 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_data_region_enablement | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | region, | ||
| dif_toggle_t | enable ) |
Enable/disable the data region of RRAM indexed by region.
This may only be done if region configuration has not been locked.
| handle | The RRAM controller DIF state. |
| region | The region to operate on. |
| enable | Enable or disable this region. |
kDifBadArg if handle is null or region is invalid, kDifLocked if region configuration has been locked, and kDifOk otherwise. Definition at line 468 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_data_region_properties | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | region, | ||
| dif_rram_ctrl_data_region_properties_t | config ) |
Set memory properties for the data region of RRAM indexed by region.
This may only be done if region configuration has not been locked.
| handle | The RRAM controller DIF state. |
| region | The region to operate on. |
| config | The memory properties to control for this region. |
kDifBadArg if handle is null or region is invalid, kDifLocked if region configuration has been locked, and kDifOk otherwise. Definition at line 604 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_default_region_properties | ( | dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_region_properties_t | properties ) |
Set the default memory properties for data regions, when not overridden by a specific entry in the data region memory properties table.
| handle | The RRAM controller DIF state. |
| properties | The memory properties to control. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 564 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_exec_enablement | ( | dif_rram_ctrl_state_t * | handle, |
| dif_toggle_t | enable ) |
Set whether execution / fetch access is enabled.
| handle | The RRAM controller DIF state. |
| enable | Enable/disable execution / fetch access. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 136 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_info_region_enablement | ( | dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_info_region_t | region, | ||
| dif_toggle_t | enable ) |
Enable/disable the info region of RRAM identified by region.
This may only be done if region configuration has not been locked.
| handle | The RRAM controller DIF state. |
| region | The region to operate on. |
| enable | Enable or disable this region. |
kDifBadArg if handle is null or region is invalid, kDifLocked if region configuration has been locked, and kDifOk otherwise. Definition at line 516 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_info_region_properties | ( | dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_info_region_t | region, | ||
| dif_rram_ctrl_region_properties_t | properties ) |
Set memory properties for the info region of RRAM identified by region.
This may only be done if region configuration has not been locked.
| handle | The RRAM controller DIF state. |
| region | The region to operate on. |
| properties | The memory properties to control for this region. |
kDifBadArg if handle is null or region is invalid, kDifLocked if region configuration has been locked, and kDifOk otherwise. Definition at line 672 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_read_fifo_watermark | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | level ) |
Set the interrupt watermarks for the read FIFO.
The value of level defines the level the read FIFO must fill to before triggering a rd_lvl interrupt.
This interrupt will only trigger if enabled through the interrupt API.
| handle | The RRAM controller DIF state. |
| level | Trigger an interrupt when the read FIFO fills to this level. |
kDifBadArg if handle is null or the value of level is out of range, kDifOk otherwise. Definition at line 800 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_rram_enablement | ( | dif_rram_ctrl_state_t * | handle, |
| dif_toggle_t | enable ) |
Set whether the RRAM is enabled.
Generally, this is used to disable RRAM functionality in case of an emergency. RRAM functionality is ordinarily enabled.
| handle | The RRAM controller DIF state. |
| enable | Enable/disable RRAM functionality. |
kDifBadArg if handle is null. kDifOk on success. Definition at line 96 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_scratch | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | value ) |
Set the value of the scratch register.
| handle | The RRAM controller DIF state. |
| value | The value to set the scratch register to. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 918 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_set_wr_fifo_watermark | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | level ) |
Set the interrupt watermarks for the write FIFO.
The value of level defines the level the write FIFO must drain to before triggering a wr_lvl interrupt.
This interrupts will only trigger if enabled through the interrupt API.
| handle | The RRAM controller DIF state. |
| level | Trigger an interrupt when the write FIFO drains to this level. |
kDifBadArg if handle is null or the value level is out of range, kDifOk otherwise. Definition at line 787 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_start | ( | dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_transaction_t | transaction ) |
Start a RRAM controller operation.
| handle | The RRAM controller DIF state. |
| transaction | The parameters that constitute the operation to start. |
kDifBadArg if handle is null, if transaction contains an invalid or unsupported operation, if word_count is zero or out of range, if word_count is not a multiple of 4 for write operations, or if byte_address is not 16-byte aligned for write operations; kDifUnavailable if a RRAM transaction is in progress at the controller, kDifIpFifoFull if the FIFOs are not empty, and kDifOk otherwise. Definition at line 275 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_start_controller_init | ( | dif_rram_ctrl_state_t * | handle | ) |
Begins the RRAM controller's initialization sequence.
The RRAM controller will read out the root seeds before allowing other usage of the controller. This operation will only be performed once, and controller initialization cannot be requested again until after a reset.
| handle | The RRAM controller DIF state. |
kDifError if initialization has already been started, and kDifOk otherwise. Definition at line 171 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_start_unsafe | ( | dif_rram_ctrl_state_t * | handle, |
| dif_rram_ctrl_transaction_t | transaction ) |
Start a RRAM controller operation, with fewer safeguards.
(unsafe version)
Unlike dif_rram_ctrl_start(), this variant does not check whether the word count is valid, whether the write address is 16-byte aligned, or whether the FIFOs have been emptied. This function is intended to be used to trigger errors on purpose, for testing the hardware responses.
| handle | The RRAM controller DIF state. |
| transaction | The parameters that constitute the operation to start. |
kDifBadArg if handle is null, kDifUnavailable if a RRAM transaction is in progress, and kDifOk otherwise. Definition at line 210 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_wr_fifo_push | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | word_count, | ||
| const uint32_t * | data ) |
Push data to the write FIFO.
Attempts to write the contents of data to the write FIFO. It is required that a write transaction be started prior to calling this function, else the call will fail with kDifError.
The following conditions are also required:
data must reference a contiguous, allocated, readable region of at least word_count words, violation of this will produce undefined behavior.word_count must not exceed what was supplied at the start of the write transaction.word_count must not exceed word_count - words_sent_out from the previous call. All deviations on the above will produce a kDifBadArg error unless otherwise specified.If the FIFO fills up, this function will cause the CPU to block until the RRAM controller frees up more space.
It is up to the caller to call dif_rram_ctrl_end() to ensure the RRAM controller completed this transaction successfully.
| handle | The RRAM controller DIF state. |
| word_count | The number of words to write. |
| data | The data to write. |
kDifBadArg if handle or data are null or if the value of word_count is illegal. kDifError if a write transaction was not started. kDifOk otherwise. Definition at line 331 of file dif_rram_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_rram_ctrl_wr_fifo_push_unsafe | ( | dif_rram_ctrl_state_t * | handle, |
| uint32_t | word_count, | ||
| const uint32_t * | data ) |
Push data to the write FIFO.
(unsafe version)
This function is primarily for testing hardware error responses. If you are not specifically trying to force an error, consider dif_rram_ctrl_wr_fifo_push() instead. This function does not check if a write transaction has begun, nor if the number of words would exceed the size of the current transaction.
Attempts to write the contents of data to the write FIFO without consideration for the current controller state.
It is up to the caller to call dif_rram_ctrl_end() to ensure the RRAM controller completed this transaction successfully.
| handle | The RRAM controller DIF state. |
| word_count | The number of words to write. |
| data | The data to write. |
kDifBadArg if handle or data are null. kDifOk otherwise. Definition at line 316 of file dif_rram_ctrl.c.