ADuCM4x50 Device Drivers API Reference Manual  Release 4.0.0.0
Flash Driver

Flash (FEE) Driver More...

Modules

 Static Configuration
 

Data Structures

struct  ADI_FEE_TRANSACTION
 

Macros

#define ADI_FEE_MEMORY_SIZE   (44u + ADI_SEM_SIZE)
 
#define ADI_FEE_NUM_INSTANCES   (1u)
 
#define FEE_FLASH_SIZE   (0x80000u)
 
#define FEE_BLOCK_SHIFT   (14u)
 
#define FEE_PAGE_SHIFT   (11u)
 
#define FEE_MAX_NUM_PAGES   (FEE_FLASH_SIZE >> FEE_PAGE_SHIFT)
 
#define FEE_MAX_NUM_BLOCKS   (FEE_FLASH_SIZE >> FEE_BLOCK_SHIFT)
 

Typedefs

typedef struct __ADI_FEE_DEV_DATA_TYPE * ADI_FEE_HANDLE
 

Enumerations

enum  ADI_FEE_RESULT {
  ADI_FEE_SUCCESS = 0,
  ADI_FEE_ERR_ALIGNMENT,
  ADI_FEE_ERR_ALREADY_INITIALIZED,
  ADI_FEE_ERR_BAD_DEVICE_NUM,
  ADI_FEE_ERR_BUFFER_ERR,
  ADI_FEE_ERR_DEVICE_BUSY,
  ADI_FEE_ERR_DMA_BUS_FAULT,
  ADI_FEE_ERR_DMA_INVALID_DESCR,
  ADI_FEE_ERR_DMA_REGISTER,
  ADI_FEE_ERR_DMA_UNKNOWN_ERROR,
  ADI_FEE_ERR_HW_ERROR_DETECTED,
  ADI_FEE_ERR_INSUFFICIENT_MEM,
  ADI_FEE_ERR_INVALID_HANDLE,
  ADI_FEE_ERR_INVALID_PARAM,
  ADI_FEE_ERR_NO_DATA_TO_TRANSFER,
  ADI_FEE_ERR_TRANSFER_IN_PROGRESS,
  ADI_FEE_ERR_UNMATCHED_SUBMIT_QUERY,
  ADI_FEE_ERR_SEMAPHORE_FAILED
}
 
enum  ADI_FEE_CALLBACK_EVENT {
  ADI_FEE_CALLBACK_EVENT_BUFFER_PROCESSED,
  ADI_FEE_CALLBACK_EVENT_DEVICE_ERROR
}
 
enum  ADI_FEE_ECC_EVENT_TYPE {
  ADI_FEE_ECC_EVENT_TYPE_ERROR,
  ADI_FEE_ECC_EVENT_TYPE_CORRECT
}
 
enum  ADI_FEE_ECC_RESPONSE {
  ADI_FEE_ECC_RESPONSE_NONE = 0x0,
  ADI_FEE_ECC_RESPONSE_BUS_ERROR = 0x1,
  ADI_FEE_ECC_RESPONSE_IRQ = 0x2
}
 

Functions

ADI_FEE_RESULT adi_fee_Open (uint32_t const nDeviceNum, void *const pMemory, uint32_t const nMemorySize, ADI_FEE_HANDLE *const phDevice)
 Open the flash controller. More...
 
ADI_FEE_RESULT adi_fee_Close (ADI_FEE_HANDLE const hDevice)
 Close the flash controller. More...
 
ADI_FEE_RESULT adi_fee_RegisterCallback (ADI_FEE_HANDLE const hDevice, ADI_CALLBACK const pfCallback, void *const pCBParam)
 Register an application-defined callback function. More...
 
ADI_FEE_RESULT adi_fee_PageErase (ADI_FEE_HANDLE const hDevice, uint32_t const nPageNumStart, uint32_t const nPageNumEnd, uint32_t *const pHwErrors)
 Erase the given range of (2kB) page(s) within the flash user space memory. This is a blocking call. More...
 
ADI_FEE_RESULT adi_fee_MassErase (ADI_FEE_HANDLE const hDevice, uint32_t *const pHwErrors)
 Erase the entire flash user space memory. This is a blocking call. More...
 
ADI_FEE_RESULT adi_fee_Write (ADI_FEE_HANDLE const hDevice, ADI_FEE_TRANSACTION *const pTransaction, uint32_t *const pHwErrors)
 Perform a blocking flash data write operation. More...
 
ADI_FEE_RESULT adi_fee_SubmitBuffer (ADI_FEE_HANDLE const hDevice, ADI_FEE_TRANSACTION *const pTransaction)
 Submit a non-blocking flash data write operation for background processing. More...
 
ADI_FEE_RESULT adi_fee_IsBufferAvailable (ADI_FEE_HANDLE const hDevice, bool *const pbCompletionState)
 Non-blocking check if a write transaction complete. More...
 
ADI_FEE_RESULT adi_fee_GetBuffer (ADI_FEE_HANDLE const hDevice, uint32_t *const pHwErrors)
 Blocking mode call to await transaction completion. More...
 
ADI_FEE_RESULT adi_fee_GetPageNumber (ADI_FEE_HANDLE const hDevice, uint32_t const nAddress, uint32_t *const pnPageNum)
 Get the zero-based (2kB) page number within which a flash address resides. More...
 
ADI_FEE_RESULT adi_fee_GetBlockNumber (ADI_FEE_HANDLE const hDevice, uint32_t const nAddress, uint32_t *const pnBlockNum)
 Get the zero-based (16kB) block number within which a flash address resides. More...
 
ADI_FEE_RESULT adi_fee_VerifySignature (ADI_FEE_HANDLE const hDevice, uint32_t const nStartPage, uint32_t const nEndPage, uint32_t *const pSigResult, uint32_t *const pHwErrors)
 Generate the CRC signature for a range of flash data page(s). This is a blocking call. More...
 
ADI_FEE_RESULT adi_fee_WriteProtectBlock (ADI_FEE_HANDLE const hDevice, uint32_t const nBlockNum)
 Set write protection on an (16kB) block. More...
 
ADI_FEE_RESULT adi_fee_Sleep (ADI_FEE_HANDLE const hDevice, bool const bSleep)
 Sleep or awake the flash controller. This is a blocking call. More...
 
ADI_FEE_RESULT adi_fee_Abort (ADI_FEE_HANDLE const hDevice)
 Forcefully ABORT an ongoing flash operation. This is a blocking call. More...
 
ADI_FEE_RESULT adi_fee_GetAbortAddr (ADI_FEE_HANDLE const hDevice, uint32_t *const pnAddress)
 Get the address of recently aborted write command. More...
 
ADI_FEE_RESULT adi_fee_ConfigECC (ADI_FEE_HANDLE const hDevice, uint32_t const nStartPage, bool const bInfoECCEnable)
 Configure ECC start page and enablement. More...
 
ADI_FEE_RESULT adi_fee_EnableECC (ADI_FEE_HANDLE const hDevice, bool const bEnable)
 Enable/Disable user space ECC for the device. More...
 
ADI_FEE_RESULT adi_fee_ConfigECCEvents (ADI_FEE_HANDLE const hDevice, ADI_FEE_ECC_EVENT_TYPE const eEvent, ADI_FEE_ECC_RESPONSE const eResponse)
 Confifure ECC event response. More...
 
ADI_FEE_RESULT adi_fee_GetECCErrAddr (ADI_FEE_HANDLE const hDevice, uint32_t *const pnAddress)
 Get the address for which the ECC event is detected. More...
 
ADI_FEE_RESULT adi_fee_GetECCCorrections (ADI_FEE_HANDLE const hDevice, uint32_t *const pnNumCorrections)
 Get the number of 1-bit error corrections. More...
 
ADI_FEE_RESULT adi_fee_ConfigureWaitStates (ADI_FEE_HANDLE const hDevice, uint8_t numWaitStates)
 Configure the flash wait states. More...
 

Detailed Description

Flash (FEE) Driver

The flash controller provides access to the embedded flash memory. The embedded flash has a 72-bit wide data bus providing for two 32-bit words of data and one corresponding 8-bit ECC byte per access.

Flash Driver Hardware Errors

Many of the Flash Controller APIs can result in hardware errors. Each such API has a a hardware error parameter (pHwErrors), which is a pointer to an application-defined variable into which the failing API will store the failing hardware error status.
APIs failing with hardware errors are flagged with the ADI_FEE_ERR_HW_ERROR_DETECTED return code.
Hardware error details may be decoded according to the flash controller status register ("STAT") bit-map, documented in the Hardware Reference Manual (HRM). Flash hardware errors are separate and distinct from DMA errors, which have separate and distinct return codes (ADI_FEE_ERR_DMA_BUS_FAULT, ADI_FEE_ERR_DMA_INVALID_DESCR, and ADI_FEE_ERR_DMA_UNKNOWN_ERROR).

Flash Driver Static Configuration

A number of flash driver APIs manage configurations that very likely do not require dynamic (run-time) management. Such cases are documented with the respective APIs. In all such cases, the user is encouraged to consider using the static configuration equivalents (provided in the adi_flash_config.h file) in lieu of the dynamic APIs. In so doing, linker elimination may reduce the resulting code image footprint (provided the API is not called).

Note
- The application must include drivers/flash/adi_flash.h to use this driver.
- This driver also requires the DMA driver. The application must include the DMA driver sources to avoid link errors.
- This documentation presented here is API documentation only. The device drive user's guide, located in the Documents folder, explains how to use these APIs in an application.

Macro Definition Documentation

◆ ADI_FEE_MEMORY_SIZE

#define ADI_FEE_MEMORY_SIZE   (44u + ADI_SEM_SIZE)

Applications use the "ADI_FEE_MEMORY_SIZE" macro to allocate required flash driver memory. This memory (and size) are passed to the flash driver during the "adi_fee_Open()" driver initialization call. This memory is used to store internal flash driver state.

Definition at line 66 of file adi_flash.h.

◆ ADI_FEE_NUM_INSTANCES

#define ADI_FEE_NUM_INSTANCES   (1u)

Number of flash controller instances

Definition at line 69 of file adi_flash.h.

◆ FEE_FLASH_SIZE

#define FEE_FLASH_SIZE   (0x80000u)

Flash memory size is 512kB total

Definition at line 72 of file adi_flash.h.

◆ FEE_BLOCK_SHIFT

#define FEE_BLOCK_SHIFT   (14u)

16kB block size

Definition at line 73 of file adi_flash.h.

◆ FEE_PAGE_SHIFT

#define FEE_PAGE_SHIFT   (11u)

Flash Size and Page/Block macros:

ADuCM302x

  • 256kB total user space, broken up as
  • 128-pages, 2kB/page
  • 32-blocks, 8kB/block
  • 8 pages/block

ADuCM4x50

  • 512kB total user space, broken up as
  • 256-pages, 2kB/page
  • 32-blocks, 16kB/block
  • 8 pages/block2kB page size (2^11)

Definition at line 97 of file adi_flash.h.

◆ FEE_MAX_NUM_PAGES

#define FEE_MAX_NUM_PAGES   (FEE_FLASH_SIZE >> FEE_PAGE_SHIFT)

max number of pages

Definition at line 98 of file adi_flash.h.

◆ FEE_MAX_NUM_BLOCKS

#define FEE_MAX_NUM_BLOCKS   (FEE_FLASH_SIZE >> FEE_BLOCK_SHIFT)

max number of blocks (32)

Definition at line 99 of file adi_flash.h.

Typedef Documentation

◆ ADI_FEE_HANDLE

typedef struct __ADI_FEE_DEV_DATA_TYPE* ADI_FEE_HANDLE

A device handle used in all API functions to identify the flash device.

Definition at line 58 of file adi_flash.h.

Enumeration Type Documentation

◆ ADI_FEE_RESULT

Flash Controller return codes.

Enumerator
ADI_FEE_SUCCESS 

The function completed successfully.

ADI_FEE_ERR_ALIGNMENT 

The flash write source data pointer is misaligned.

ADI_FEE_ERR_ALREADY_INITIALIZED 

The flash device driver is already initialized.

ADI_FEE_ERR_BAD_DEVICE_NUM 

Device number passed is invalid.

ADI_FEE_ERR_BUFFER_ERR 

An error occurred while processing a write buffer.

ADI_FEE_ERR_DEVICE_BUSY 

The device is busy.

ADI_FEE_ERR_DMA_BUS_FAULT 

Runtime DMA bus fault detected.

ADI_FEE_ERR_DMA_INVALID_DESCR 

Runtime DMA invalid descriptor detected.

ADI_FEE_ERR_DMA_REGISTER 

Error registering DMA error callback function.

ADI_FEE_ERR_DMA_UNKNOWN_ERROR 

Unknown runtime DMA error detected.

ADI_FEE_ERR_HW_ERROR_DETECTED 

An FEE hardware error occurred (pHwErrors param).

ADI_FEE_ERR_INSUFFICIENT_MEM 

The memory passed is undersized.

ADI_FEE_ERR_INVALID_HANDLE 

Device Handle is invalid.

ADI_FEE_ERR_INVALID_PARAM 

A function parameter is invalid.

ADI_FEE_ERR_NO_DATA_TO_TRANSFER 

No transfer data detected.

ADI_FEE_ERR_TRANSFER_IN_PROGRESS 

Operation already in progress.

ADI_FEE_ERR_UNMATCHED_SUBMIT_QUERY 

Unmatched read/write vs. submit/get API call.

ADI_FEE_ERR_SEMAPHORE_FAILED 

An semaphore operation failed.

Definition at line 35 of file adi_flash.h.

◆ ADI_FEE_CALLBACK_EVENT

Enum for the callback events.

Enumerator
ADI_FEE_CALLBACK_EVENT_BUFFER_PROCESSED 

Buffer processed successfully event.

ADI_FEE_CALLBACK_EVENT_DEVICE_ERROR 

Device error(s) detected during command.

Definition at line 106 of file adi_flash.h.

◆ ADI_FEE_ECC_EVENT_TYPE

Enum for the Error-Correction-Code event type.

Enumerator
ADI_FEE_ECC_EVENT_TYPE_ERROR 

ECC Error Event.

ADI_FEE_ECC_EVENT_TYPE_CORRECT 

ECC correction event.

Definition at line 115 of file adi_flash.h.

◆ ADI_FEE_ECC_RESPONSE

Error-Correction-Code configuration codes.

Enumerator
ADI_FEE_ECC_RESPONSE_NONE 

No Response.

ADI_FEE_ECC_RESPONSE_BUS_ERROR 

Generate a Bus Error.

ADI_FEE_ECC_RESPONSE_IRQ 

Generate an IRQ.

Definition at line 124 of file adi_flash.h.

Function Documentation

◆ adi_fee_Open()

ADI_FEE_RESULT adi_fee_Open ( uint32_t const  nDeviceNum,
void *const  pMemory,
uint32_t const  nMemorySize,
ADI_FEE_HANDLE *const  phDevice 
)

Open the flash controller.

Parameters
[in]nDeviceNumThe zero-based device instance number of flash controller to be opened.
[in]pMemoryApplication supplied memory space for use by the driver.
[in]nMemorySizeSize of the application supplied memory (in bytes).
[in,out]phDeviceThe caller's device handle pointer for storing the initialized device instance data pointer.
Returns
Status

Initialize an instance of the flash device driver using default user configuration settings (from adi_flash_config.h) and allocate the device for use.

No other flash APIs may be called until the device open function is called. The returned device handle is required to be passed to all subsequent flash API calls to identify the physical device instance in use. The user device handle (pointed to by phDevice) is set to NULL on failure.

Note
Currently, only a singular flash physical device instance (device ID "0") exists.
See also
adi_fee_Close().

Definition at line 199 of file adi_flash.c.

◆ adi_fee_Close()

ADI_FEE_RESULT adi_fee_Close ( ADI_FEE_HANDLE const  hDevice)

Close the flash controller.

Parameters
[in]hDeviceThe handle to the flash controller device
Returns
Status

Uninitialize and release an allocated flash device, and memory associated with it for other use.

Note
The user memory is released from use by the flash driver, but is not freed.
See also
adi_fee_Open().

Definition at line 311 of file adi_flash.c.

Referenced by adi_fee_Open().

◆ adi_fee_RegisterCallback()

ADI_FEE_RESULT adi_fee_RegisterCallback ( ADI_FEE_HANDLE const  hDevice,
ADI_CALLBACK const  pfCallback,
void *const  pCBParam 
)

Register an application-defined callback function.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]pfCallbackA pointer to an application-supplied calllback function which is called to notify the application of device-related events. A value of NULL disables driver callbacks.
[in]pCBParamAn application-supplied callback parameter which will be passed back to the callback function.
Returns
Status

Links the user-provided callback function into the adi_fee_SubmitBuffer() API such that rather than polling for buffer completion (with adi_fee_IsBufferAvailable()) and eventually reacquiring the buffer (with adi_fee_GetBuffer()), the user can simply register a callback function that will be called upon buffer completion with no further action needed.
Error conditions are also passed to the callback, including DMA errors if DMA is active. Make sure to always check the event value passed to the callback, just as the various API return codes should always be checked.
However, callbacks are always made in context of an interrupt, so applications are strongly encouraged to exit the callback as quickly as possible so normal interrupt processing is disrupted as little as possible. This is also an argument for not using callbacks at at all.

Note
When using callbacks to reacquire buffers, DO NOT use the adi_fee_GetBuffer() API. The two methods are mutually exclusive.
See also
adi_fee_SubmitBuffer().
adi_fee_IsBufferAvailable().
adi_fee_GetBuffer().

Definition at line 407 of file adi_flash.c.

◆ adi_fee_PageErase()

ADI_FEE_RESULT adi_fee_PageErase ( ADI_FEE_HANDLE const  hDevice,
uint32_t const  nPageNumStart,
uint32_t const  nPageNumEnd,
uint32_t *const  pHwErrors 
)

Erase the given range of (2kB) page(s) within the flash user space memory. This is a blocking call.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]nPageNumStartStart page number (zero-based, inclusive).
[in]nPageNumEndEnd page number (zero-based, inclusive).
[in,out]pHwErrorsPointer to user location into which any flash hardware errors are reported.
Returns
Status

Erase a range of pages starting from page number nPageNumStart, through and including page number nPageNumEnd. Callers are expected to save/restore any existing partial page data prior to erasure, as needed. Translate literal flash addresses into zero-based flash page start and page end numbers with adi_fee_GetPageNumber(). Page start and end numbers are zero-based and inclusive; to erase a single page, specify the same start and end page numbers. Page numbers range from 0-127 for ADuCM302x devices (with 256kB flash) or 0-255 for ADuCM4x50 devices (with 512kB flash).

Note
Flash hardware errors are flagged with the ADI_FEE_ERR_HW_ERROR_DETECTED return code. Flash hardware error details are written to the location pointed to by the pHwErrors parameter. Hardware error details may be decoded according to the flash controller status register ("STAT") bit-map, documented in the Hardware Reference Manual (HRM).
See also
adi_fee_GetPageNumber().
adi_fee_MassErase().

Definition at line 458 of file adi_flash.c.

◆ adi_fee_MassErase()

ADI_FEE_RESULT adi_fee_MassErase ( ADI_FEE_HANDLE const  hDevice,
uint32_t *const  pHwErrors 
)

Erase the entire flash user space memory. This is a blocking call.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in,out]pHwErrorsPointer to user location into which any flash hardware errors are reported.
Returns
Status
Note
Do not call mass erase on or from code that is running from flash. Doing so will leave an indeterminate machine state.
Flash hardware errors are flagged with the ADI_FEE_ERR_HW_ERROR_DETECTED return code. Flash hardware error details are written to the location pointed to by the pHwErrors parameter. Hardware error details may be decoded according to the flash controller status register ("STAT") bit-map, documented in the Hardware Reference Manual (HRM).
See also
adi_fee_PageErase().

Definition at line 540 of file adi_flash.c.

◆ adi_fee_Write()

ADI_FEE_RESULT adi_fee_Write ( ADI_FEE_HANDLE const  hDevice,
ADI_FEE_TRANSACTION *const  pTransaction,
uint32_t *const  pHwErrors 
)

Perform a blocking flash data write operation.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]pTransactionPointer to a user-defined control block describing the data to be transferred, containing:
  • pWriteAddr; Pointer to a 64-bit-aligned destination address in flash.
  • pWriteData; Pointer to a 32-bit-aligned source data buffer in user memory.
  • nSize; Number of bytes to write (must be an integral multiple of 8).
  • bUseDma; Flag controlling use of DMA to perform the write.
[in,out]pHwErrorsPointer to user location into which any flash hardware errors are reported.
Returns
Status

Perform a blocking flash data write operation. This API does not return until the write operation is completed.

Note
Flash hardware errors are flagged with the ADI_FEE_ERR_HW_ERROR_DETECTED return code. Flash hardware error details are written to the location pointed to by the pHwErrors parameter. Hardware error details may be decoded according to the flash controller status register ("STAT") bit-map, documented in the Hardware Reference Manual (HRM). Flash hardware errors are separate and distinct from DMA errors, which have separate and distinct return codes, as described above.

Definition at line 606 of file adi_flash.c.

◆ adi_fee_SubmitBuffer()

ADI_FEE_RESULT adi_fee_SubmitBuffer ( ADI_FEE_HANDLE const  hDevice,
ADI_FEE_TRANSACTION *const  pTransaction 
)

Submit a non-blocking flash data write operation for background processing.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]pTransactionPointer to a user-defined control block describing the data to be transferred, containing:
  • pWriteAddr; Pointer to a 64-bit-aligned destination address in flash.
  • pWriteData; Pointer to a 32-bit-aligned source data buffer in user memory.
  • nSize; Number of bytes to write (must be an integral multiple of 8).
  • bUseDma; Flag controlling use of DMA to perform the write.
Returns
Status

Submit a flash data write transaction. This is a non-blocking function which returns immediately. The application may either: poll for transaction completion through the non-blocking adi_fee_IsBufferAvailable() API, and/or await transaction completion through the blocking mode adi_fee_GetBuffer() API. If an application callback has been registered, the application is advised of completion status through the callback.

Note
If using callback mode, DO NOT USE the adi_fee_GetBuffer() API, which are mutually exclusive protocols.
See also
adi_fee_IsBufferAvailable().
adi_fee_GetBuffer().

Definition at line 705 of file adi_flash.c.

◆ adi_fee_IsBufferAvailable()

ADI_FEE_RESULT adi_fee_IsBufferAvailable ( ADI_FEE_HANDLE const  hDevice,
bool *const  pbCompletionState 
)

Non-blocking check if a write transaction complete.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in,out]pbCompletionStateTrue if transfer is complete, false if not.
Returns
Status

Check if a non-blocking write transaction that was submitted via adi_fee_SubmitBuffer() is complete.

See also
adi_fee_SubmitBuffer().
adi_fee_GetBuffer().

Definition at line 773 of file adi_flash.c.

◆ adi_fee_GetBuffer()

ADI_FEE_RESULT adi_fee_GetBuffer ( ADI_FEE_HANDLE const  hDevice,
uint32_t *const  pHwErrors 
)

Blocking mode call to await transaction completion.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in,out]pHwErrorsPointer to user location into which any flash hardware errors are reported.
Returns
Status

This function blocks until a previously-submitted flash write operation has completed.

Note
Flash hardware errors are flagged with the ADI_FEE_ERR_HW_ERROR_DETECTED return code. Flash hardware error details are written to the location pointed to by the pHwErrors parameter. Hardware error details may be decoded according to the flash controller status register ("STAT") bit-map, documented in the Hardware Reference Manual (HRM).
See also
adi_fee_SubmitBuffer().
adi_fee_IsBufferAvailable().

Definition at line 828 of file adi_flash.c.

◆ adi_fee_GetPageNumber()

ADI_FEE_RESULT adi_fee_GetPageNumber ( ADI_FEE_HANDLE const  hDevice,
uint32_t const  nAddress,
uint32_t *const  pnPageNum 
)

Get the zero-based (2kB) page number within which a flash address resides.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]nAddressThe flash address for which the page number is required.
[in,out]pnPageNumPointer to a variable into which the zero-based page number corresponding to the provided flash address is written.
Returns
Status

Translates a literal flash address into a zero-based page number for use with various page-based flash operations.

See also
adi_fee_PageErase().
adi_fee_VerifySignature().
adi_fee_ConfigECC().
adi_fee_GetBlockNumber().

Definition at line 887 of file adi_flash.c.

◆ adi_fee_GetBlockNumber()

ADI_FEE_RESULT adi_fee_GetBlockNumber ( ADI_FEE_HANDLE const  hDevice,
uint32_t const  nAddress,
uint32_t *const  pnBlockNum 
)

Get the zero-based (16kB) block number within which a flash address resides.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]nAddressThe flash address for which the block number is required.
[in,out]pnBlockNumPointer to a variable into which the block number corresponding to the provided flash address is written.
Returns
Status

Translates a literal flash address into a zero-based block number for use with setting flash write protection on a block.

See also
adi_fee_WriteProtectBlock().
adi_fee_GetPageNumber().

Definition at line 927 of file adi_flash.c.

◆ adi_fee_VerifySignature()

ADI_FEE_RESULT adi_fee_VerifySignature ( ADI_FEE_HANDLE const  hDevice,
uint32_t const  nStartPage,
uint32_t const  nEndPage,
uint32_t *const  pSigResult,
uint32_t *const  pHwErrors 
)

Generate the CRC signature for a range of flash data page(s). This is a blocking call.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]nStartPageThe lower page number of the signature range (zero-based, inclusive).
[in]nEndPageThe upper page number of the signature range (zero-based, inclusive).
[in,out]pSigResultPointer to a variable into which the computed signature is stored.
[in,out]pHwErrorsPointer to user location into which any flash hardware errors are reported.
Returns
Status

Compute and return a CRC over a contiguous range of whole flash memory pages. The page numbers are zero-based and inclusive. The computed CRC signature may subsequently be written into the most-significant word of the region over which the signature was calculated. This is done in context of enabling bootloader enforcement of CRC signature verification during system startup. See HRM for signature storage programming requirements and bootloader operation.

Note
Flash hardware errors are flagged with the ADI_FEE_ERR_HW_ERROR_DETECTED return code. Flash hardware error details are written to the location pointed to by the pHwErrors parameter. Hardware error details may be decoded according to the flash controller status register ("STAT") bit-map, documented in the Hardware Reference Manual (HRM).
See also
adi_fee_GetPageNumber().

Definition at line 979 of file adi_flash.c.

◆ adi_fee_WriteProtectBlock()

ADI_FEE_RESULT adi_fee_WriteProtectBlock ( ADI_FEE_HANDLE const  hDevice,
uint32_t const  nBlockNum 
)

Set write protection on an (16kB) block.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]nBlockNumThe zero-based block number.
Returns
Status

Assert memory write-protection for the zero-based nBlockNum block. Note that only entire blocks are protectable, with each block spanning 8 full 2kB pages.

Note
Blocks may only be write-protected during user run-time code. Unprotecting is only possible with a power-on-reset or a mass erase; write-protection is not otherwise clearable.
Warning
Flash-based code that write-protects blocks will cause the write-protection (and data at time of write-protect assertion) to apparently not clear... even after a mass erase or power-on-reset. This apparently "stuck" write-protection results from the flash-based write-protect code running after reset (as usual), but still prior to the debugger halting the target through the debug interrupt. The debugger target halt occurs WELL AFTER the flash code has already run, thereby relocking the block and making it appear the write-protection was never reset. This can be difficult Catch-22 situation to recover from, requiring repeated hardware resets and reflashing new code that does not assert the write-protection.
See also
adi_fee_GetBlockNumber().

Definition at line 1064 of file adi_flash.c.

◆ adi_fee_Sleep()

ADI_FEE_RESULT adi_fee_Sleep ( ADI_FEE_HANDLE const  hDevice,
bool const  bSleep 
)

Sleep or awake the flash controller. This is a blocking call.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]bSleep'true' to enable to sleep the flash device and 'false' to wake up the device.
Returns
Status

Places the flash controller into a low-power sleep mode - see details in Hardware Reference Manual (HRM). Default wakeup time is approximately 5us, and is configurable with static configuration parameter ADI_FEE_CFG_PARAM1_TWK in adi_flash_config.h file.

Definition at line 1109 of file adi_flash.c.

◆ adi_fee_Abort()

ADI_FEE_RESULT adi_fee_Abort ( ADI_FEE_HANDLE const  hDevice)

Forcefully ABORT an ongoing flash operation. This is a blocking call.

Parameters
[in]hDeviceThe handle to the flash controller device.
Returns
Statuus
Warning
Use this command sparingly and as a last resort to satisfy critical time-sensitive events. Aborting any flash command results in prematurely ending the current flash access and may result in corrupted flash data.
See also
adi_fee_GetAbortAddr().

Definition at line 1154 of file adi_flash.c.

◆ adi_fee_GetAbortAddr()

ADI_FEE_RESULT adi_fee_GetAbortAddr ( ADI_FEE_HANDLE const  hDevice,
uint32_t *const  pnAddress 
)

Get the address of recently aborted write command.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in,out]pnAddressPointer to which the address is written.
Returns
Status

Users may use this result to determine the flash location(s) affected by a write abort command. Subsequent flash commands invalidate the write abort address register.

See also
adi_fee_Abort().

Definition at line 1191 of file adi_flash.c.

◆ adi_fee_ConfigECC()

ADI_FEE_RESULT adi_fee_ConfigECC ( ADI_FEE_HANDLE const  hDevice,
uint32_t const  nStartPage,
bool const  bInfoECCEnable 
)

Configure ECC start page and enablement.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]nStartPageThe zero-based start page for which ECC will be performed.
[in]bInfoECCEnableInfo space ECC enable:
  • 'true' to enable info space ECC, or
  • 'false' to disable info space ECC.
Returns
Status
Note
The settings this API manages are very likely not needed to be modified dynamically (at run-time). If so, consider using the static configuration equivalents (see adi_flash_config.h) in lieu of this API... which will reduce the resulting code image footprint through linker elimination.
Warning
This API leaves user space ECC disabled. Use adi_fee_EnableECC() to manage ECC enable/disable.
See also
adi_fee_GetPageNumber().
adi_fee_EnableECC().
adi_fee_ConfigECCEvents().
adi_fee_GetECCErrAddr().
adi_fee_GetECCCorrections().

Definition at line 1238 of file adi_flash.c.

◆ adi_fee_EnableECC()

ADI_FEE_RESULT adi_fee_EnableECC ( ADI_FEE_HANDLE const  hDevice,
bool const  bEnable 
)

Enable/Disable user space ECC for the device.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]bEnableUser space ECC enable:
  • 'true' to enable user space ECC, or
  • 'false' to disable user space ECC.
Returns
Status

Manage enablement of user space ECC function.

Note
The settings this API manages are very likely not needed to be modified dynamically (at run-time). If so, consider using the static configuration equivalents (see adi_flash_config.h) in lieu of this API... which will reduce the resulting code image footprint through linker elimination.
See also
adi_fee_ConfigECC().
adi_fee_ConfigECCEvents().
adi_fee_GetECCErrAddr().
adi_fee_GetECCCorrections().

Definition at line 1296 of file adi_flash.c.

◆ adi_fee_ConfigECCEvents()

ADI_FEE_RESULT adi_fee_ConfigECCEvents ( ADI_FEE_HANDLE const  hDevice,
ADI_FEE_ECC_EVENT_TYPE const  eEvent,
ADI_FEE_ECC_RESPONSE const  eResponse 
)

Confifure ECC event response.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in]eEventECC event - Either error or correction event.
[in]eResponseThe response to the eEvent - One of none, bus error, or interrupt.
Returns
Status

Configures two major aspects of ECC event response:

  • On ECC (2-bit) Error events, generate one of: no response, bus error, or flash interrupt.
  • On ECC (1-bit) Correction events, generate one of: no response, bus error, or flash interrupt.
Note
The settings this API manages are very likely not needed to be modified dynamically (at run-time). If so, consider using the static configuration equivalents (see adi_flash_config.h) in lieu of this API... which will reduce the resulting code image footprint through linker elimination.
See also
adi_fee_ConfigECC().
adi_fee_EnableECC().
adi_fee_GetECCErrAddr().
adi_fee_GetECCCorrections().

Definition at line 1346 of file adi_flash.c.

◆ adi_fee_GetECCErrAddr()

ADI_FEE_RESULT adi_fee_GetECCErrAddr ( ADI_FEE_HANDLE const  hDevice,
uint32_t *const  pnAddress 
)

Get the address for which the ECC event is detected.

`

Parameters
[in]hDeviceThe handle to the flash controller device.
[in,out]pnAddressPointer to which the address is written.
Returns
Status

Returns the address of the first ECC error or correction event to generate an interrupt since the last time ECC status bits were cleared (or since reset).

See also
adi_fee_ConfigECC().
adi_fee_EnableECC().
adi_fee_ConfigECCEvents().
adi_fee_GetECCCorrections().

Definition at line 1416 of file adi_flash.c.

◆ adi_fee_GetECCCorrections()

ADI_FEE_RESULT adi_fee_GetECCCorrections ( ADI_FEE_HANDLE const  hDevice,
uint32_t *const  pnNumCorrections 
)

Get the number of 1-bit error corrections.

Parameters
[in]hDeviceThe handle to the flash controller device.
[in,out]pnNumCorrectionsPointer to which the number of corrections are written.
Returns
Status

See HRM for details on how current ECC configuration affects this reporting.

See also
adi_fee_ConfigECC().
adi_fee_EnableECC().
adi_fee_ConfigECCEvents().
adi_fee_GetECCErrAddr().

Definition at line 1454 of file adi_flash.c.

◆ adi_fee_ConfigureWaitStates()

ADI_FEE_RESULT adi_fee_ConfigureWaitStates ( ADI_FEE_HANDLE const  hDevice,
uint8_t  numWaitStates 
)

Configure the flash wait states.

Parameters
[in]hDeviceThe handle to the flash controller device
[in]numWaitStatesThe number of wait states to access flash
Returns
Status

Definition at line 352 of file adi_flash.c.