 |
Software APIs
|
|
Software APIs
|
Flash Controller Device Interface Functions More...
#include "sw/device/lib/base/macros.h"#include "sw/device/lib/base/multibits.h"#include "sw/device/lib/dif/autogen/dif_flash_ctrl_autogen.h"Go to the source code of this file.
Data Structures | |
| struct | dif_flash_ctrl_state |
| Carries state for a flash controller device. More... | |
| struct | dif_flash_ctrl_device_info |
| struct | dif_flash_ctrl_status |
| Status bits that can be queried. More... | |
| struct | dif_flash_ctrl_prog_capabilities |
| Represents programming capabilities of the flash controller. More... | |
| struct | dif_flash_ctrl_transaction |
| struct | dif_flash_ctrl_error_codes |
| struct | dif_flash_ctrl_error |
| Represents recoverable errors and synchronous errors caused by software. More... | |
| struct | dif_flash_ctrl_output |
| struct | dif_flash_ctrl_region_properties |
| Memory protection configuration options. More... | |
| struct | dif_flash_ctrl_data_region_properties |
| A composite of a data region and its memory properties. More... | |
| struct | dif_flash_ctrl_info_region |
| Representation of the memory protection regions for the info pages. More... | |
| struct | dif_flash_ctrl_faults |
| struct | dif_flash_ctrl_ecc_errors |
| struct | dif_flash_ctrl_phy_status |
Typedefs | |
| typedef struct dif_flash_ctrl_state | dif_flash_ctrl_state_t |
| Carries state for a flash controller device. More... | |
| typedef struct dif_flash_ctrl_device_info | dif_flash_ctrl_device_info_t |
| typedef struct dif_flash_ctrl_status | dif_flash_ctrl_status_t |
| Status bits that can be queried. | |
| typedef struct dif_flash_ctrl_prog_capabilities | dif_flash_ctrl_prog_capabilities_t |
| Represents programming capabilities of the flash controller. More... | |
| typedef enum dif_flash_ctrl_partition_type | dif_flash_ctrl_partition_type_t |
| Enum to represent the flash partition type (data or info). | |
| typedef enum dif_flash_ctrl_operation | dif_flash_ctrl_operation_t |
| typedef struct dif_flash_ctrl_transaction | dif_flash_ctrl_transaction_t |
| typedef struct dif_flash_ctrl_error_codes | dif_flash_ctrl_error_codes_t |
| typedef struct dif_flash_ctrl_error | dif_flash_ctrl_error_t |
| Represents recoverable errors and synchronous errors caused by software. | |
| typedef struct dif_flash_ctrl_output | dif_flash_ctrl_output_t |
| typedef struct dif_flash_ctrl_region_properties | dif_flash_ctrl_region_properties_t |
| Memory protection configuration options. | |
| typedef struct dif_flash_ctrl_data_region_properties | dif_flash_ctrl_data_region_properties_t |
| A composite of a data region and its memory properties. | |
| typedef struct dif_flash_ctrl_info_region | dif_flash_ctrl_info_region_t |
| Representation of the memory protection regions for the info pages. | |
| typedef struct dif_flash_ctrl_faults | dif_flash_ctrl_faults_t |
| typedef struct dif_flash_ctrl_ecc_errors | dif_flash_ctrl_ecc_errors_t |
| typedef struct dif_flash_ctrl_phy_status | dif_flash_ctrl_phy_status_t |
Enumerations | |
| enum | dif_flash_ctrl_partition_type { kDifFlashCtrlPartitionTypeData = 0, kDifFlashCtrlPartitionTypeInfo = 1 } |
| Enum to represent the flash partition type (data or info). | |
| enum | dif_flash_ctrl_operation { kDifFlashCtrlOpRead = 0, kDifFlashCtrlOpProgram = 1, kDifFlashCtrlOpProgramRepair = 5, kDifFlashCtrlOpPageErase = 2, kDifFlashCtrlOpBankErase = 10 } |
Flash Controller Device Interface Functions
Definition in file dif_flash_ctrl.h.
| struct dif_flash_ctrl_state |
Carries state for a flash controller device.
All members except the dev should be considered private and should not be accessed directly outside of the DIF implementation.
Definition at line 29 of file dif_flash_ctrl.h.
| Data Fields | ||
|---|---|---|
| dif_flash_ctrl_t | dev | Contains autogenerated device information, like the base address for registers in the flash 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_flash_ctrl_device_info |
Definition at line 55 of file dif_flash_ctrl.h.
| struct dif_flash_ctrl_status |
Status bits that can be queried.
Definition at line 151 of file dif_flash_ctrl.h.
| struct dif_flash_ctrl_prog_capabilities |
Represents programming capabilities of the flash controller.
The meaning of the boolean values is context-sensitive. For the result of a query, they represent which types are allowed. As an argument to a function that disables capabilities, a true value indicates that the function should disable that type.
Definition at line 199 of file dif_flash_ctrl.h.
| Data Fields | ||
|---|---|---|
| bool | normal_prog_type: 1 | Normal programming type. |
| bool | repair_prog_type: 1 | Repair programming type. |
| struct dif_flash_ctrl_transaction |
Definition at line 265 of file dif_flash_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | byte_address |
Byte address (in the flash address space) to start the operation. For operations at a granularity of words, the flash 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. Similarly, for page erase and bank erase operations, the flash controller will truncate to the closest lower page-aligned or bank-aligned address, respectively. |
| dif_flash_ctrl_operation_t | op | |
| uint32_t | partition_id |
The index / ID of the info partition. Unused for data partitions, since there is only one in a given bank. |
| dif_flash_ctrl_partition_type_t | partition_type |
The partition type for the transaction. Note: For bank erase operations, the data partition is always erased, even when |
| uint32_t | word_count |
Number of 32-bit words in the operation. Must be in the range [1,4096] (inclusive) for program or read operations. Unused for erase operations. |
| struct dif_flash_ctrl_error_codes |
Definition at line 486 of file dif_flash_ctrl.h.
| struct dif_flash_ctrl_error |
Represents recoverable errors and synchronous errors caused by software.
Definition at line 514 of file dif_flash_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | address | For errors associated with an address, the address where the error occurred. |
| dif_flash_ctrl_error_codes_t | codes | A set of error codes. |
| struct dif_flash_ctrl_output |
Definition at line 551 of file dif_flash_ctrl.h.
| Data Fields | ||
|---|---|---|
| dif_flash_ctrl_error_t | error_code |
The error code associated with an operation_error. This field is only valid if |
| bool | operation_done: 1 | Flash operation done. |
| bool | operation_error: 1 | Flash operation error. |
| struct dif_flash_ctrl_region_properties |
Memory protection configuration options.
Definition at line 587 of file dif_flash_ctrl.h.
| struct dif_flash_ctrl_data_region_properties |
A composite of a data region and its memory properties.
Definition at line 605 of file dif_flash_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | base | Region base page index. |
| dif_flash_ctrl_region_properties_t | properties | Memory properties of the region. |
| uint32_t | size | Region config size (in number of pages). |
| struct dif_flash_ctrl_info_region |
Representation of the memory protection regions for the info pages.
Definition at line 617 of file dif_flash_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | bank | Region bank ID. |
| uint32_t | page | Region page index. |
| uint32_t | partition_id | Region info partition ID. |
| struct dif_flash_ctrl_faults |
Definition at line 974 of file dif_flash_ctrl.h.
| struct dif_flash_ctrl_ecc_errors |
Definition at line 1007 of file dif_flash_ctrl.h.
| Data Fields | ||
|---|---|---|
| uint32_t | last_error_address | The last address that produced a single-bit ECC error. |
| uint32_t | single_bit_error_count | Count of the number of single-bit ECC errors. |
| struct dif_flash_ctrl_phy_status |
Definition at line 1027 of file dif_flash_ctrl.h.
| Data Fields | ||
|---|---|---|
| bool | phy_init_wip: 1 | Flash phy controller is initializing. |
| bool | prog_normal_available: 1 | Normal programming is supported. |
| bool | prog_repair_available: 1 | Repair programming is supported. |
Represents programming capabilities of the flash controller.
The meaning of the boolean values is context-sensitive. For the result of a query, they represent which types are allowed. As an argument to a function that disables capabilities, a true value indicates that the function should disable that type.
| typedef struct dif_flash_ctrl_state dif_flash_ctrl_state_t |
Carries state for a flash controller device.
All members except the dev should be considered private and should not be accessed directly outside of the DIF implementation.
Definition at line 248 of file dif_flash_ctrl.h.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_bank_configuration_is_locked | ( | const dif_flash_ctrl_state_t * | handle, |
| bool * | locked_out | ||
| ) |
Query the state of the bank configuration lock.
This function checks if memory bank configuration is still enabled or if it has been locked. Once locked, bank configuration cannot be enabled again, and all calls to bank configuration functions will return kDifLocked until the device is restarted.
| handle | flash controller device to check the lock state for. |
| locked_out | Out-parameter, the current state of the bank configuration lock. |
kDifBadArg if handle or locked_out is null, kDifOk otherwise. Definition at line 1089 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_clear_error_codes | ( | dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_error_codes_t | codes | ||
| ) |
Clear the error codes.
| handle | flash controller device to set. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 579 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_data_region_is_locked | ( | const dif_flash_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 | flash controller device to check the lock state for. |
| region | The region in question. |
| 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 984 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_disallow_prog_types | ( | dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_prog_capabilities_t | types_to_disable | ||
| ) |
Disallow the indicated programming operations.
Note that this is a one-way operation. Programming types that are disabled cannot be enabled again without a reset.
| handle | The flash controller to operate on. |
| types_to_disallow | A programming type marked true indicates that the given type should be disabled. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 295 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_end | ( | dif_flash_ctrl_state_t * | handle, |
| dif_flash_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 | flash controller device for completing the transaction. |
| 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 601 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_allowed_prog_types | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_prog_capabilities_t * | allowed_types_out | ||
| ) |
Query the allowed programming types.
Note that this function is a check of a permission only. For checking whether the flash supports a given type, use dif_flash_ctrl_get_phy_status().
| handle | The flash controller to query. |
| allowed_types_out | Out parameter. Points to location where the allowed types should be written. |
kDifBadArg if handle or allowed_types_out are null. kDifOk otherwise. Definition at line 275 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_bank_erase_enablement | ( | const dif_flash_ctrl_state_t * | handle, |
| uint32_t | bank, | ||
| dif_toggle_t * | enabled_out | ||
| ) |
Query the erase permissions for a particular flash bank.
| handle | flash controller device to query. |
| bank | The bank to query. |
| enabled_out | Out-parameter, the erase permissions for this bank. |
kDifBadArg if handle or enabled_out is null and kDifOk otherwise. Definition at line 1048 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_data_region_enablement | ( | const dif_flash_ctrl_state_t * | handle, |
| uint32_t | region, | ||
| dif_toggle_t * | enabled_out | ||
| ) |
Get the enabled/disabled state for the indicated data region.
| handle | flash controller device to query. |
| region | The region in question. |
| 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 666 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_data_region_properties | ( | const dif_flash_ctrl_state_t * | handle, |
| uint32_t | region, | ||
| dif_flash_ctrl_data_region_properties_t * | config_out | ||
| ) |
Get the memory properties for the data region of flash indexed by region.
| handle | flash controller device to query. |
| region | The index of the region entry in question. |
| config_out | Out-parameter, a pointer to a dif_flash_ctrl_data_region_properties_t struct for writing the full entry showing the region configuration and its memory properties. |
kDifBadArg if handle or properties_out are null or if region is invalid. kDifOk otherwise. Definition at line 841 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_default_region_properties | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_flash_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 | flash controller device to query. |
| properties_out | Out-parameter, a pointer to a dif_flash_ctrl_region_properties_t struct for writing the memory properties. |
kDifBadArg if handle or properties_out are null. kDifOk otherwise. Definition at line 767 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_flash_ctrl_device_info_t dif_flash_ctrl_get_device_info | ( | void | ) |
Get information on the flash controller sizes.
dif_flash_ctrl_device_info_t representing the feature sizes for various components of the flash. Definition at line 136 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_ecc_errors | ( | const dif_flash_ctrl_state_t * | handle, |
| uint32_t | bank, | ||
| dif_flash_ctrl_ecc_errors_t * | errors_out | ||
| ) |
Get the ECC error information for the specified flash bank.
| handle | The flash controller device to query. |
| bank | The desired bank to look up errors for. |
kDifBadArg if handle or errors_out are null or if bank is invalid. kDifOk otherwise. Definition at line 1195 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_erase_suspend_status | ( | dif_flash_ctrl_state_t * | handle, |
| bool * | request_pending_out | ||
| ) |
Query the controller for any erase suspension requests pending.
| handle | The flash controller to query. |
| request_pending_out | Out parameter. The location to write whether an erase suspension request is pending. |
kDifBadArg if handle or request_pending_out are null. kDifOk otherwise. Definition at line 454 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_error_codes | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_error_t * | error_code_out | ||
| ) |
Get the error codes and address of the last associated error.
| handle | flash controller device to query. |
| error_code_out | Output parameter. The location where the current status is to be stored. |
kDifBadArg if handle or error_code_out are null. kDifOk otherwise. Definition at line 547 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_exec_enablement | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_toggle_t * | enabled_out | ||
| ) |
Get whether execution / fetch access is enabled.
| handle | The flash controller to operate on. |
| enabled_out | Out parameter, whether execution / fetch access is allowed. |
kDifBadArg if handle or enabled_out are null and kDifOk otherwise. Definition at line 217 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_faults | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_faults_t * | faults_out | ||
| ) |
Gets the unrecoverable or hardware faults.
| handle | flash controller device to query |
| faults_out | Out parameter, a pointer to the location to write the fault values. |
kDifBadArg if handle or fault_out are null. kDifOk otherwise. Definition at line 1162 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_fifo_watermarks | ( | const dif_flash_ctrl_state_t * | handle, |
| uint32_t * | prog_out, | ||
| uint32_t * | read_out | ||
| ) |
Get the interrupt watermarks for the program and read FIFOs.
| handle | flash controller to get FIFO level watermarks from. |
| prog_out | Out-parameter, the prog FIFO watermark level. If the prog FIFO empties to this level, a corresponding status bit and possibly an interrupt may be generated. May be null. |
| 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 1129 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_flash_enablement | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_toggle_t * | enabled_out | ||
| ) |
Get whether flash functionality is enabled.
| handle | The flash controller to operate on. |
| enabled_out | Out parameter, where to store whether flash is enabled. |
kDifBadArg if handle or enabled_out are null and kDifOk otherwise. Definition at line 175 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_info_region_enablement | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_info_region_t | region, | ||
| dif_toggle_t * | enabled_out | ||
| ) |
Get the enabled/disabled state for the indicated info region.
| handle | flash controller device to query. |
| region | The region in question. |
| 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 721 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_info_region_properties | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_info_region_t | region, | ||
| dif_flash_ctrl_region_properties_t * | properties_out | ||
| ) |
Get the memory properties for the info region of flash identified by region.
| handle | flash controller device to query. |
| region | The index of the region entry in question. |
| properties_out | Out-parameter, a pointer to a dif_flash_ctrl_region_properties_t struct for writing memory properties associated with the indicated region. |
kDifBadArg if handle or properties_out are null or if region is invalid. kDifOk otherwise. Definition at line 910 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_phy_status | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_phy_status_t * | status_out | ||
| ) |
Query the status registers on the flash controller.
This function checks the various status bits as described in dif_flash_ctrl_phy_status_t.
| handle | The flash controller device with the desired phy's status bit to check. |
| status_out | Out-parameter, the current status of the flash phy. |
kDifBadArg if handle or status_out is null, kDifOk otherwise. Definition at line 1227 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_scratch | ( | const dif_flash_ctrl_state_t * | handle, |
| uint32_t * | value_out | ||
| ) |
Get the value of the scratch register.
| handle | The flash controller device to query. |
| value_out | Out parameter. The location to write the scratch register's value to. |
kDifBadArg if handle or value_out are null. kDifOk otherwise. Definition at line 1259 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_get_status | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_status_t * | status_out | ||
| ) |
Query the status registers on the flash controller.
This function checks the various status bits as described in dif_flash_ctrl_status_t.
| handle | flash controller device to check the status bits for. |
| status_out | Out parameter. The current status of the flash controller. |
kDifBadArg if handle or status_out is null, kDifOk otherwise. Definition at line 250 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_info_region_is_locked | ( | const dif_flash_ctrl_state_t * | handle, |
| dif_flash_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 | flash controller device to check the lock state for. |
| region | The region in question. |
| 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 998 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_init_state | ( | dif_flash_ctrl_state_t * | handle, |
| mmio_region_t | base_addr | ||
| ) |
Initialize the DIF state for the flash controller.
| handle | The flash controller DIF state to initialize. |
| base_addr | The base address for the flash controller. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 121 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_lock_bank_configuration | ( | dif_flash_ctrl_state_t * | handle | ) |
Lock bank configuration until the device is reset.
This will prevent any further configuration of memory banks until device reset. Future calls to bank configuration functions will return kDifLocked.
| handle | flash controller device to lock region configuration on. |
kDifBadArg if handle is null, kDifLocked if already locked, and kDifOk otherwise. Definition at line 1068 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_lock_data_region_properties | ( | dif_flash_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 | flash controller device to lock region configuration on. |
| region | The region to lock. |
kDifBadArg if handle is null, or if region is invalid, kDifLocked if configuration is already locked, kDifOk otherwise. Definition at line 940 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_lock_info_region_properties | ( | dif_flash_ctrl_state_t * | handle, |
| dif_flash_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 | flash controller device to lock region configuration on. |
| region | The region to lock. |
kDifBadArg if handle is null, or if region is invalid, kDifLocked if configuration is already locked, kDifOk otherwise. Definition at line 961 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_prog_fifo_push | ( | dif_flash_ctrl_state_t * | handle, |
| uint32_t | word_count, | ||
| const uint32_t * | data | ||
| ) |
Push data to the program FIFO.
Attempts to write the contents of data to the program FIFO. It is required that a program 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 program 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 flash controller frees up more space.
It is up to the caller to call dif_flash_ctrl_end() to ensure the flash controller completed this transaction successfully.
| handle | flash controller device to push data to. |
| word_count | The number of words to write. |
| data | The data to write. program FIFO, will contain the number of words pushed. |
kDifBadArg if handle or data are null or if the value of word_count is illegal. kDifError if a program transaction was not started. kDifOk otherwise. Definition at line 485 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_prog_fifo_push_unsafe | ( | dif_flash_ctrl_state_t * | handle, |
| uint32_t | word_count, | ||
| const uint32_t * | data | ||
| ) |
Push data to the program FIFO.
(unsafe version)
This function is primarily for testing hardware error responses. If you are not specifically trying to force an error, consider dif_flash_ctrl_prog_fifo_push() instead. This function does not check if a program 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 program FIFO without consideration for the current controller state.
It is up to the caller to call dif_flash_ctrl_end() to ensure the flash controller completed this transaction successfully.
| handle | flash controller device to push data to. |
| 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 469 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_read_fifo_pop | ( | dif_flash_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 flash controller fills the FIFO with more data.
It is up to the caller to call dif_flash_ctrl_end() to ensure the flash controller completed this transaction successfully.
| handle | flash controller device to pull data from. |
| word_count | The number of words to read. |
| data_out | The region in memory to store the data read off the FIFO. |
| words_read_out | Out-parameter, the number of words read. |
kDifBadArg if handle or data_out are null, or if the value of word_count is illegal. kDifOk otherwise. Definition at line 525 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_read_fifo_pop_unsafe | ( | dif_flash_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_flash_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_flash_ctrl_end() to ensure the flash controller completed this transaction successfully.
| handle | flash controller device to push data to. |
| word_count | The number of words to read. |
| data_out | The region in memory to store the data read off the FIFO. |
kDifBadArg if handle or data are null. kDifOk otherwise. Definition at line 508 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_reset_fifos | ( | dif_flash_ctrl_state_t * | handle | ) |
Resets both the program and read FIFOs.
This is useful in the event of an unexpected error as a means of reseting state.
| handle | flash controller device to clear FIFOs on. |
kDifBadArg if handle is null, kDifOk otherwise. Definition at line 1148 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_bank_erase_enablement | ( | dif_flash_ctrl_state_t * | handle, |
| uint32_t | bank, | ||
| dif_toggle_t | enable | ||
| ) |
Enable/disable erase operations for a particular flash bank.
This may only be done if bank configuration is still enabled.
| handle | flash controller device to operate on. |
| bank | The bank to configure. |
| enable | Enable/disable erase access for this bank. |
kDifBadArg if handle is null or bank is invalid, kDifLocked if bank configuration is locked, and kDifOk otherwise. Definition at line 1016 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_data_region_enablement | ( | dif_flash_ctrl_state_t * | handle, |
| uint32_t | region, | ||
| dif_toggle_t | enable | ||
| ) |
Enable/disable the data region of flash indexed by region.
This may only be done if region configuration has not been locked.
| handle | flash controller device to configure. |
| 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 634 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_data_region_properties | ( | dif_flash_ctrl_state_t * | handle, |
| uint32_t | region, | ||
| dif_flash_ctrl_data_region_properties_t | config | ||
| ) |
Set memory properties for the data region of flash indexed by region.
This may only be done if region configuration has not been locked.
| handle | flash controller device to configure. |
| 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 794 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_default_region_properties | ( | dif_flash_ctrl_state_t * | handle, |
| dif_flash_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 | flash controller device to configure. |
| properties | The memory properties to control. |
kDifBadArg if handle is null, kDifOk otherwise. Definition at line 742 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_exec_enablement | ( | dif_flash_ctrl_state_t * | handle, |
| dif_toggle_t | enable | ||
| ) |
Set whether execution / fetch access is enabled.
| handle | The flash controller to operate on. |
| enable | Enable/disable execution / fetch access. |
kDifBadArg if handle or enabled_out are null and kDifOk otherwise. Definition at line 196 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_flash_enablement | ( | dif_flash_ctrl_state_t * | handle, |
| dif_toggle_t | enable | ||
| ) |
Set whether the flash is enabled.
Generally, this is used to disable flash functionality in case of an emergency. Flash functionality is ordinarily enabled.
| handle | The flash controller to operate on. |
| enable | Enable/disable flash functionality. |
kDifBadArg if handle is null. kDifOk otherwise. Definition at line 150 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_info_region_enablement | ( | dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_info_region_t | region, | ||
| dif_toggle_t | enable | ||
| ) |
Enable/disable the info region of flash identified by region.
This may only be done if region configuration has not been locked.
| handle | flash controller device to configure. |
| 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 685 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_info_region_properties | ( | dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_info_region_t | region, | ||
| dif_flash_ctrl_region_properties_t | properties | ||
| ) |
Set memory properties for the info region of flash identified by region.
This may only be done if region configuration has not been locked.
| handle | flash controller device to configure. |
| 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 874 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_prog_fifo_watermark | ( | dif_flash_ctrl_state_t * | handle, |
| uint32_t | level | ||
| ) |
Set the interrupt watermarks for the program FIFO.
The value of level defines the level the program FIFO must drain to before triggering a prog_lvl interrupt.
This interrupts will only trigger if enabled through the interrupt API.
| handle | flash controller to set FIFO level watermarks for. |
| prog | Trigger an interrupt when the program FIFO drains to this level. |
kDifBadArg if handle is null or if the value level is out of range, kDifOk otherwise. Definition at line 1101 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_read_fifo_watermark | ( | dif_flash_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 | flash controller to set FIFO level watermarks for. |
| level | Trigger an interrupt when the read FIFO fills to this level. |
kDifBadArg if flash_ctrl is null or if the value of prog is out of range, kDifOk otherwise. Definition at line 1115 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_set_scratch | ( | dif_flash_ctrl_state_t * | handle, |
| uint32_t | value | ||
| ) |
Set the value of the scratch register.
| handle | The flash controller device to operate on. |
| value | The value to set the scratch register to. |
kDifBadArg if handle is null, kDifOk otherwise. Definition at line 1248 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_start | ( | dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_transaction_t | transaction | ||
| ) |
Start a flash controller operation.
Note that not all underlying flash memory supports the kDifFlashCtrlOpProgramRepair operation. When specifying this in the op, dif_flash_ctrl_get_phy_status() can first be used to ensure the operation is supported.
| handle | The flash controller device to execute the transaction on. |
| transaction | The parameters that constitute the operation to start. |
kDifBadArg if handle is null or transaction contains an invalid or unsupported operation, kDifUnavailable if a flash transaction is in progress at the controller, kDifIpFifoFull if the FIFOs are not empty, and kDifOk otherwise. Definition at line 404 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_start_controller_init | ( | dif_flash_ctrl_state_t * | handle | ) |
Begins the flash controller's initialization sequence.
The flash 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 flash controller to operate on. |
kDifBadArg if handle is null, kDifError if initialization has already been started, and kDifOk otherwise. Definition at line 233 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_start_unsafe | ( | dif_flash_ctrl_state_t * | handle, |
| dif_flash_ctrl_transaction_t | transaction | ||
| ) |
Start a flash controller operation, with fewer safeguards.
(unsafe version)
Unlike dif_flash_ctrl_start(), this variant does not check whether the info partition id is valid, whether the word count is valid, or whether the FIFOs have been emptied. This function is intended to be used to trigger errors on purpose, for testing the hardware responses.
Note that not all underlying flash memory supports the kDifFlashCtrlOpProgramRepair operation. When specifying this in the op, dif_flash_ctrl_get_phy_status() can first be used to ensure the operation is supported.
| handle | The flash controller device to execute the transaction on. |
| transaction | The parameters that constitute the operation to start. |
kDifBadArg if handle is null, kDifUnavailable if a flash transaction is in progress, and kDifOk otherwise. Definition at line 319 of file dif_flash_ctrl.c.
| OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_suspend_erase | ( | dif_flash_ctrl_state_t * | handle | ) |
Suspend an ongoing erase transaction.
If no erase transaction is ongoing, returns with no effect.
| handle | flash controller device to operate on. |
kDifBadArg if handle is null. Otherwise, kDifOk. Definition at line 442 of file dif_flash_ctrl.c.