Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_flash_ctrl.h File Reference

(2363bcd)

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
}
 

Functions

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. More...
 
dif_flash_ctrl_device_info_t dif_flash_ctrl_get_device_info (void)
 Get information on the flash controller sizes. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_flash_ctrl_suspend_erase (dif_flash_ctrl_state_t *handle)
 Suspend an ongoing erase transaction. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description

Flash Controller Device Interface Functions

Definition in file dif_flash_ctrl.h.


Data Structure Documentation

◆ dif_flash_ctrl_state

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.

◆ dif_flash_ctrl_device_info

struct dif_flash_ctrl_device_info

Definition at line 55 of file dif_flash_ctrl.h.

Data Fields
uint32_t bytes_per_page Number of bytes per flash page.
uint32_t bytes_per_word Number of bytes per flash word.
uint32_t data_pages Number of pages per bank in the data partition.
uint32_t info0_pages Number of pages per bank in the info partition, type 0.
uint32_t info1_pages Number of pages per bank in the info partition, type 1.
uint32_t info2_pages Number of pages per bank in the info partition, type 2.
uint32_t num_banks Number of banks under this flash controller.

◆ dif_flash_ctrl_status

struct dif_flash_ctrl_status

Status bits that can be queried.

Definition at line 150 of file dif_flash_ctrl.h.

Data Fields
bool controller_init_wip: 1 Flash controller undergoing init.
bool prog_fifo_empty: 1 Flash program FIFO empty, software must provide data.
bool prog_fifo_full: 1 Flash program FIFO full.
bool read_fifo_empty: 1 Flash read FIFO empty.
bool read_fifo_full: 1 Flash read FIFO full, software must consume data.

◆ dif_flash_ctrl_prog_capabilities

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 194 of file dif_flash_ctrl.h.

Data Fields
bool normal_prog_type: 1 Normal programming type.
bool repair_prog_type: 1 Repair programming type.

◆ dif_flash_ctrl_transaction

struct dif_flash_ctrl_transaction

Definition at line 260 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 partition_type is kFlashCtrlPartitionTypeInfo.

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.

◆ dif_flash_ctrl_error_codes

struct dif_flash_ctrl_error_codes

Definition at line 481 of file dif_flash_ctrl.h.

Data Fields
bool memory_properties_error: 1 Access permission error.
bool prog_type_error: 1 Flash program operation selected an unavailable type.

For example, the repair type of programming was selected, but the flash did not support it.

bool prog_window_error: 1 Flash program has a window resolution error.

In other words, the start of program and end of program are in different windows.

bool read_error: 1 Uncorrectable flash read data error.
bool shadow_register_error: 1 A shadow register encountered an update error.

◆ dif_flash_ctrl_error

struct dif_flash_ctrl_error

Represents recoverable errors and synchronous errors caused by software.

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

◆ dif_flash_ctrl_output

struct dif_flash_ctrl_output

Definition at line 546 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 operation_error is true.

bool operation_done: 1 Flash operation done.
bool operation_error: 1 Flash operation error.

◆ dif_flash_ctrl_region_properties

struct dif_flash_ctrl_region_properties

Memory protection configuration options.

Definition at line 582 of file dif_flash_ctrl.h.

Data Fields
multi_bit_bool_t ecc_en ECC enable flag.
multi_bit_bool_t erase_en Erase enable flag.
multi_bit_bool_t high_endurance_en High-endurance enable flag.
multi_bit_bool_t prog_en Program enable flag.
multi_bit_bool_t rd_en Read enable flag.
multi_bit_bool_t scramble_en Scramble enable flag.

◆ dif_flash_ctrl_data_region_properties

struct dif_flash_ctrl_data_region_properties

A composite of a data region and its memory properties.

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

◆ dif_flash_ctrl_info_region

struct dif_flash_ctrl_info_region

Representation of the memory protection regions for the info pages.

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

◆ dif_flash_ctrl_faults

struct dif_flash_ctrl_faults

Definition at line 969 of file dif_flash_ctrl.h.

Data Fields
bool host_gnt_error: 1 A host transaction was granted with illegal properties.
bool lifecycle_manager_error: 1 The lifecycle management interface encountered a fatal error.
bool memory_properties_error: 1 The flash hardware interface encountered a memory permission error.
bool phy_integrity_error: 1 The flash memory encountered a register integrity error.
bool prog_type_error: 1 The flash hardware interface encountered a program type error.
bool prog_window_error: 1 The flash hardware interface encountered a program resolution error.
bool read_error: 1 The flash hardware interface encountered a read data error.
bool register_integrity_error: 1 The flash controller encountered a register integrity error.
bool shadow_storage_error: 1 A shadow register encountered a storage fault.

◆ dif_flash_ctrl_ecc_errors

struct dif_flash_ctrl_ecc_errors

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

◆ dif_flash_ctrl_phy_status

struct dif_flash_ctrl_phy_status

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

Typedef Documentation

◆ dif_flash_ctrl_prog_capabilities_t

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.

◆ 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.

Enumeration Type Documentation

◆ dif_flash_ctrl_operation

Enumerator
kDifFlashCtrlOpRead 

Read the specified number of words.

kDifFlashCtrlOpProgram 

Program the specified number of words (normal mode).

kDifFlashCtrlOpProgramRepair 

Program the specified number of words in repair mode.

Support for this mode depends on the underlying flash technology. See dif_flash_ctrl_supports_repair_operation.

kDifFlashCtrlOpPageErase 

Erase the specified page.

kDifFlashCtrlOpBankErase 

Erase the specified bank.

Definition at line 243 of file dif_flash_ctrl.h.

Function Documentation

◆ dif_flash_ctrl_bank_configuration_is_locked()

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.

Parameters
handleflash controller device to check the lock state for.
locked_outOut-parameter, the current state of the bank configuration lock.
Returns
kDifBadArg if handle or locked_out is null, kDifOk otherwise.

Definition at line 1079 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_clear_error_codes()

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.

Parameters
handleflash controller device to set.
Returns
kDifBadArg if handle is null. kDifOk otherwise.

Definition at line 574 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_data_region_is_locked()

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.

Parameters
handleflash controller device to check the lock state for.
regionThe region in question.
locked_outOut-parameter, the current state of the region's configuration lock.
Returns
kDifBadArg if handle or locked_out is null, or if region is invalid, kDifOk otherwise.

Definition at line 974 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_disallow_prog_types()

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.

Parameters
handleThe flash controller to operate on.
types_to_disallowA programming type marked true indicates that the given type should be disabled.
Returns
kDifBadArg if handle is null. kDifOk otherwise.

Definition at line 290 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_end()

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.

Parameters
handleflash controller device for completing the transaction.
outOut parameter. Contains the transaction status and error codes.
Returns
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 596 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_allowed_prog_types()

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().

See also
dif_flash_ctrl_get_phy_status
Parameters
handleThe flash controller to query.
allowed_types_outOut parameter. Points to location where the allowed types should be written.
Returns
kDifBadArg if handle or allowed_types_out are null. kDifOk otherwise.

Definition at line 270 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_bank_erase_enablement()

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.

Parameters
handleflash controller device to query.
bankThe bank to query.
enabled_outOut-parameter, the erase permissions for this bank.
Returns
kDifBadArg if handle or enabled_out is null and kDifOk otherwise.

Definition at line 1038 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_data_region_enablement()

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.

Parameters
handleflash controller device to query.
regionThe region in question.
enabled_outOut-parameter, the enabled/disabled state of this region.
Returns
kDifBadArg if handle or enabled_out is null, or if region is invalid, kDifOk otherwise.

Definition at line 656 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_data_region_properties()

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.

Parameters
handleflash controller device to query.
regionThe index of the region entry in question.
config_outOut-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.
Returns
kDifBadArg if handle or properties_out are null or if region is invalid. kDifOk otherwise.

Definition at line 831 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_default_region_properties()

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.

Parameters
handleflash controller device to query.
properties_outOut-parameter, a pointer to a dif_flash_ctrl_region_properties_t struct for writing the memory properties.
Returns
kDifBadArg if handle or properties_out are null. kDifOk otherwise.

Definition at line 757 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_device_info()

dif_flash_ctrl_device_info_t dif_flash_ctrl_get_device_info ( void  )

Get information on the flash controller sizes.

Returns
A dif_flash_ctrl_device_info_t representing the feature sizes for various components of the flash.

Definition at line 133 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_ecc_errors()

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.

Parameters
handleThe flash controller device to query.
bankThe desired bank to look up errors for.
Returns
kDifBadArg if handle or errors_out are null or if bank is invalid. kDifOk otherwise.

Definition at line 1185 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_erase_suspend_status()

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.

Parameters
handleThe flash controller to query.
request_pending_outOut parameter. The location to write whether an erase suspension request is pending.
Returns
kDifBadArg if handle or request_pending_out are null. kDifOk otherwise.

Definition at line 449 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_error_codes()

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.

Parameters
handleflash controller device to query.
error_code_outOutput parameter. The location where the current status is to be stored.
Returns
kDifBadArg if handle or error_code_out are null. kDifOk otherwise.

Definition at line 542 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_exec_enablement()

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.

Parameters
handleThe flash controller to operate on.
enabled_outOut parameter, whether execution / fetch access is allowed.
Returns
kDifBadArg if handle or enabled_out are null and kDifOk otherwise.

Definition at line 214 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_faults()

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.

Parameters
handleflash controller device to query
faults_outOut parameter, a pointer to the location to write the fault values.
Returns
kDifBadArg if handle or fault_out are null. kDifOk otherwise.

Definition at line 1152 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_fifo_watermarks()

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.

Parameters
handleflash controller to get FIFO level watermarks from.
prog_outOut-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_outOut-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.
Returns
kDifBadArg if handle is null, kDifOk otherwise.

Definition at line 1119 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_flash_enablement()

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.

Parameters
handleThe flash controller to operate on.
enabled_outOut parameter, where to store whether flash is enabled.
Returns
kDifBadArg if handle or enabled_out are null and kDifOk otherwise.

Definition at line 172 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_info_region_enablement()

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.

Parameters
handleflash controller device to query.
regionThe region in question.
enabled_outOut-parameter, the enabled/disabled state of this region.
Returns
kDifBadArg if handle or enabled_out is null, or if region is invalid, kDifOk otherwise.

Definition at line 711 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_info_region_properties()

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.

Parameters
handleflash controller device to query.
regionThe index of the region entry in question.
properties_outOut-parameter, a pointer to a dif_flash_ctrl_region_properties_t struct for writing memory properties associated with the indicated region.
Returns
kDifBadArg if handle or properties_out are null or if region is invalid. kDifOk otherwise.

Definition at line 900 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_phy_status()

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.

Parameters
handleThe flash controller device with the desired phy's status bit to check.
status_outOut-parameter, the current status of the flash phy.
Returns
kDifBadArg if handle or status_out is null, kDifOk otherwise.

Definition at line 1217 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_scratch()

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.

Parameters
handleThe flash controller device to query.
value_outOut parameter. The location to write the scratch register's value to.
Returns
kDifBadArg if handle or value_out are null. kDifOk otherwise.

Definition at line 1249 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_get_status()

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.

Parameters
handleflash controller device to check the status bits for.
status_outOut parameter. The current status of the flash controller.
Returns
kDifBadArg if handle or status_out is null, kDifOk otherwise.

Definition at line 247 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_info_region_is_locked()

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.

Parameters
handleflash controller device to check the lock state for.
regionThe region in question.
locked_outOut-parameter, the current state of the region's configuration lock.
Returns
kDifBadArg if handle or locked_out is null, or if region is invalid, kDifOk otherwise.

Definition at line 988 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_init_state()

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.

Parameters
handleThe flash controller DIF state to initialize.
base_addrThe base address for the flash controller.
Returns
kDifBadArg if handle is null. kDifOk otherwise.

Definition at line 118 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_lock_bank_configuration()

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.

Parameters
handleflash controller device to lock region configuration on.
Returns
kDifBadArg if handle is null, kDifLocked if already locked, and kDifOk otherwise.

Definition at line 1058 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_lock_data_region_properties()

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.

Parameters
handleflash controller device to lock region configuration on.
regionThe region to lock.
Returns
kDifBadArg if handle is null, or if region is invalid, kDifLocked if configuration is already locked, kDifOk otherwise.

Definition at line 930 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_lock_info_region_properties()

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.

Parameters
handleflash controller device to lock region configuration on.
regionThe region to lock.
Returns
kDifBadArg if handle is null, or if region is invalid, kDifLocked if configuration is already locked, kDifOk otherwise.

Definition at line 951 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_prog_fifo_push()

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.
  • The first call to this function after starting the program transaction the same word_count must not exceed what was supplied at the start of the program transaction.
  • Each subsequent call the new 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.

Parameters
handleflash controller device to push data to.
word_countThe number of words to write.
dataThe data to write. program FIFO, will contain the number of words pushed.
Returns
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 480 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_prog_fifo_push_unsafe()

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.

Parameters
handleflash controller device to push data to.
word_countThe number of words to write.
dataThe data to write.
Returns
kDifBadArg if handle or data are null. kDifOk otherwise.

Definition at line 464 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_read_fifo_pop()

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.
  • The first call to this function after starting the program transaction the same word_count must not exceed what was supplied at the start of the read transaction.
  • Each subsequent call the new 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.

Parameters
handleflash controller device to pull data from.
word_countThe number of words to read.
data_outThe region in memory to store the data read off the FIFO.
words_read_outOut-parameter, the number of words read.
Returns
kDifBadArg if handle or data_out are null, or if the value of word_count is illegal. kDifOk otherwise.

Definition at line 520 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_read_fifo_pop_unsafe()

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.

Parameters
handleflash controller device to push data to.
word_countThe number of words to read.
data_outThe region in memory to store the data read off the FIFO.
Returns
kDifBadArg if handle or data are null. kDifOk otherwise.

Definition at line 503 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_reset_fifos()

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.

Parameters
handleflash controller device to clear FIFOs on.
Returns
kDifBadArg if handle is null, kDifOk otherwise.

Definition at line 1138 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_bank_erase_enablement()

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.

Parameters
handleflash controller device to operate on.
bankThe bank to configure.
enableEnable/disable erase access for this bank.
Returns
kDifBadArg if handle is null or bank is invalid, kDifLocked if bank configuration is locked, and kDifOk otherwise.

Definition at line 1006 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_data_region_enablement()

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.

Parameters
handleflash controller device to configure.
regionThe region to operate on.
enableEnable or disable this region.
Returns
kDifBadArg if handle is null or region is invalid, kDifLocked if region configuration has been locked, and kDifOk otherwise.

Definition at line 624 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_data_region_properties()

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.

Parameters
handleflash controller device to configure.
regionThe region to operate on.
configThe memory properties to control for this region.
Returns
kDifBadArg if handle is null or region is invalid, kDifLocked if region configuration has been locked, and kDifOk otherwise.

Definition at line 784 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_default_region_properties()

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.

Parameters
handleflash controller device to configure.
propertiesThe memory properties to control.
Returns
kDifBadArg if handle is null, kDifOk otherwise.

Definition at line 732 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_exec_enablement()

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.

Parameters
handleThe flash controller to operate on.
enableEnable/disable execution / fetch access.
Returns
kDifBadArg if handle or enabled_out are null and kDifOk otherwise.

Definition at line 193 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_flash_enablement()

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.

Parameters
handleThe flash controller to operate on.
enableEnable/disable flash functionality.
Returns
kDifBadArg if handle is null. kDifOk otherwise.

Definition at line 147 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_info_region_enablement()

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.

Parameters
handleflash controller device to configure.
regionThe region to operate on.
enableEnable or disable this region.
Returns
kDifBadArg if handle is null or region is invalid, kDifLocked if region configuration has been locked, and kDifOk otherwise.

Definition at line 675 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_info_region_properties()

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.

Parameters
handleflash controller device to configure.
regionThe region to operate on.
propertiesThe memory properties to control for this region.
Returns
kDifBadArg if handle is null or region is invalid, kDifLocked if region configuration has been locked, and kDifOk otherwise.

Definition at line 864 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_prog_fifo_watermark()

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.

Parameters
handleflash controller to set FIFO level watermarks for.
progTrigger an interrupt when the program FIFO drains to this level.
Returns
kDifBadArg if handle is null or if the value level is out of range, kDifOk otherwise.

Definition at line 1091 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_read_fifo_watermark()

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.

Parameters
handleflash controller to set FIFO level watermarks for.
levelTrigger an interrupt when the read FIFO fills to this level.
Returns
kDifBadArg if flash_ctrl is null or if the value of prog is out of range, kDifOk otherwise.

Definition at line 1105 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_set_scratch()

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.

Parameters
handleThe flash controller device to operate on.
valueThe value to set the scratch register to.
Returns
kDifBadArg if handle is null, kDifOk otherwise.

Definition at line 1238 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_start()

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.

Parameters
handleThe flash controller device to execute the transaction on.
transactionThe parameters that constitute the operation to start.
Returns
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 399 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_start_controller_init()

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.

Parameters
handleThe flash controller to operate on.
Returns
kDifBadArg if handle is null, kDifError if initialization has already been started, and kDifOk otherwise.

Definition at line 230 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_start_unsafe()

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.

Parameters
handleThe flash controller device to execute the transaction on.
transactionThe parameters that constitute the operation to start.
Returns
kDifBadArg if handle is null, kDifUnavailable if a flash transaction is in progress, and kDifOk otherwise.

Definition at line 314 of file dif_flash_ctrl.c.

◆ dif_flash_ctrl_suspend_erase()

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.

Parameters
handleflash controller device to operate on.
Returns
kDifBadArg if handle is null. Otherwise, kDifOk.

Definition at line 437 of file dif_flash_ctrl.c.