ADuCM4x50 Device Drivers API Reference Manual
Release 4.0.0.0
|
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 |
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... | |
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).
#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.
#define ADI_FEE_NUM_INSTANCES (1u) |
Number of flash controller instances
Definition at line 69 of file adi_flash.h.
#define FEE_FLASH_SIZE (0x80000u) |
Flash memory size is 512kB total
Definition at line 72 of file adi_flash.h.
#define FEE_BLOCK_SHIFT (14u) |
16kB block size
Definition at line 73 of file adi_flash.h.
#define FEE_PAGE_SHIFT (11u) |
Flash Size and Page/Block macros:
ADuCM302x
ADuCM4x50
Definition at line 97 of file adi_flash.h.
#define FEE_MAX_NUM_PAGES (FEE_FLASH_SIZE >> FEE_PAGE_SHIFT) |
max number of pages
Definition at line 98 of file adi_flash.h.
#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 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.
enum ADI_FEE_RESULT |
Flash Controller return codes.
Definition at line 35 of file adi_flash.h.
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.
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.
enum 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.
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.
[in] | nDeviceNum | The zero-based device instance number of flash controller to be opened. |
[in] | pMemory | Application supplied memory space for use by the driver. |
[in] | nMemorySize | Size of the application supplied memory (in bytes). |
[in,out] | phDevice | The caller's device handle pointer for storing the initialized device instance data pointer. |
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.
Definition at line 199 of file adi_flash.c.
ADI_FEE_RESULT adi_fee_Close | ( | ADI_FEE_HANDLE const | hDevice | ) |
Close the flash controller.
[in] | hDevice | The handle to the flash controller device |
Uninitialize and release an allocated flash device, and memory associated with it for other use.
Definition at line 311 of file adi_flash.c.
Referenced by adi_fee_Open().
ADI_FEE_RESULT adi_fee_RegisterCallback | ( | ADI_FEE_HANDLE const | hDevice, |
ADI_CALLBACK const | pfCallback, | ||
void *const | pCBParam | ||
) |
Register an application-defined callback function.
[in] | hDevice | The handle to the flash controller device. |
[in] | pfCallback | A 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] | pCBParam | An application-supplied callback parameter which will be passed back to the callback function. |
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.
Definition at line 407 of file adi_flash.c.
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.
[in] | hDevice | The handle to the flash controller device. |
[in] | nPageNumStart | Start page number (zero-based, inclusive). |
[in] | nPageNumEnd | End page number (zero-based, inclusive). |
[in,out] | pHwErrors | Pointer to user location into which any flash hardware errors are reported. |
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).
Definition at line 458 of file adi_flash.c.
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.
[in] | hDevice | The handle to the flash controller device. |
[in,out] | pHwErrors | Pointer to user location into which any flash hardware errors are reported. |
Definition at line 540 of file adi_flash.c.
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.
[in] | hDevice | The handle to the flash controller device. |
[in] | pTransaction | Pointer to a user-defined control block describing the data to be transferred, containing:
|
[in,out] | pHwErrors | Pointer to user location into which any flash hardware errors are reported. |
Perform a blocking flash data write operation. This API does not return until the write operation is completed.
Definition at line 606 of file adi_flash.c.
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.
[in] | hDevice | The handle to the flash controller device. |
[in] | pTransaction | Pointer to a user-defined control block describing the data to be transferred, containing:
|
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.
Definition at line 705 of file adi_flash.c.
ADI_FEE_RESULT adi_fee_IsBufferAvailable | ( | ADI_FEE_HANDLE const | hDevice, |
bool *const | pbCompletionState | ||
) |
Non-blocking check if a write transaction complete.
[in] | hDevice | The handle to the flash controller device. |
[in,out] | pbCompletionState | True if transfer is complete, false if not. |
Check if a non-blocking write transaction that was submitted via adi_fee_SubmitBuffer() is complete.
Definition at line 773 of file adi_flash.c.
ADI_FEE_RESULT adi_fee_GetBuffer | ( | ADI_FEE_HANDLE const | hDevice, |
uint32_t *const | pHwErrors | ||
) |
Blocking mode call to await transaction completion.
[in] | hDevice | The handle to the flash controller device. |
[in,out] | pHwErrors | Pointer to user location into which any flash hardware errors are reported. |
This function blocks until a previously-submitted flash write operation has completed.
Definition at line 828 of file adi_flash.c.
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.
[in] | hDevice | The handle to the flash controller device. |
[in] | nAddress | The flash address for which the page number is required. |
[in,out] | pnPageNum | Pointer to a variable into which the zero-based page number corresponding to the provided flash address is written. |
Translates a literal flash address into a zero-based page number for use with various page-based flash operations.
Definition at line 887 of file adi_flash.c.
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.
[in] | hDevice | The handle to the flash controller device. |
[in] | nAddress | The flash address for which the block number is required. |
[in,out] | pnBlockNum | Pointer to a variable into which the block number corresponding to the provided flash address is written. |
Translates a literal flash address into a zero-based block number for use with setting flash write protection on a block.
Definition at line 927 of file adi_flash.c.
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.
[in] | hDevice | The handle to the flash controller device. |
[in] | nStartPage | The lower page number of the signature range (zero-based, inclusive). |
[in] | nEndPage | The upper page number of the signature range (zero-based, inclusive). |
[in,out] | pSigResult | Pointer to a variable into which the computed signature is stored. |
[in,out] | pHwErrors | Pointer to user location into which any flash hardware errors are reported. |
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.
Definition at line 979 of file adi_flash.c.
ADI_FEE_RESULT adi_fee_WriteProtectBlock | ( | ADI_FEE_HANDLE const | hDevice, |
uint32_t const | nBlockNum | ||
) |
Set write protection on an (16kB) block.
[in] | hDevice | The handle to the flash controller device. |
[in] | nBlockNum | The zero-based block number. |
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.
Definition at line 1064 of file adi_flash.c.
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.
[in] | hDevice | The handle to the flash controller device. |
[in] | bSleep | 'true' to enable to sleep the flash device and 'false' to wake up the device. |
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_RESULT adi_fee_Abort | ( | ADI_FEE_HANDLE const | hDevice | ) |
Forcefully ABORT an ongoing flash operation. This is a blocking call.
[in] | hDevice | The handle to the flash controller device. |
Definition at line 1154 of file adi_flash.c.
ADI_FEE_RESULT adi_fee_GetAbortAddr | ( | ADI_FEE_HANDLE const | hDevice, |
uint32_t *const | pnAddress | ||
) |
Get the address of recently aborted write command.
[in] | hDevice | The handle to the flash controller device. |
[in,out] | pnAddress | Pointer to which the address is written. |
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.
Definition at line 1191 of file adi_flash.c.
ADI_FEE_RESULT adi_fee_ConfigECC | ( | ADI_FEE_HANDLE const | hDevice, |
uint32_t const | nStartPage, | ||
bool const | bInfoECCEnable | ||
) |
Configure ECC start page and enablement.
[in] | hDevice | The handle to the flash controller device. |
[in] | nStartPage | The zero-based start page for which ECC will be performed. |
[in] | bInfoECCEnable | Info space ECC enable:
|
Definition at line 1238 of file adi_flash.c.
ADI_FEE_RESULT adi_fee_EnableECC | ( | ADI_FEE_HANDLE const | hDevice, |
bool const | bEnable | ||
) |
Enable/Disable user space ECC for the device.
[in] | hDevice | The handle to the flash controller device. |
[in] | bEnable | User space ECC enable:
|
Manage enablement of user space ECC function.
Definition at line 1296 of file adi_flash.c.
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.
[in] | hDevice | The handle to the flash controller device. |
[in] | eEvent | ECC event - Either error or correction event. |
[in] | eResponse | The response to the eEvent - One of none, bus error, or interrupt. |
Configures two major aspects of ECC event response:
Definition at line 1346 of file adi_flash.c.
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.
`
[in] | hDevice | The handle to the flash controller device. |
[in,out] | pnAddress | Pointer to which the address is written. |
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).
Definition at line 1416 of file adi_flash.c.
ADI_FEE_RESULT adi_fee_GetECCCorrections | ( | ADI_FEE_HANDLE const | hDevice, |
uint32_t *const | pnNumCorrections | ||
) |
Get the number of 1-bit error corrections.
[in] | hDevice | The handle to the flash controller device. |
[in,out] | pnNumCorrections | Pointer to which the number of corrections are written. |
See HRM for details on how current ECC configuration affects this reporting.
Definition at line 1454 of file adi_flash.c.
ADI_FEE_RESULT adi_fee_ConfigureWaitStates | ( | ADI_FEE_HANDLE const | hDevice, |
uint8_t | numWaitStates | ||
) |
Configure the flash wait states.
[in] | hDevice | The handle to the flash controller device |
[in] | numWaitStates | The number of wait states to access flash |
Definition at line 352 of file adi_flash.c.