This is the set of operations constituting the Storage driver. More...
#include <Driver_Storage.h>
Data Fields | |
ARM_DRIVER_VERSION(* | GetVersion )(void) |
Get driver version. More... | |
ARM_STORAGE_CAPABILITIES(* | GetCapabilities )(void) |
Get driver capabilities. More... | |
int32_t(* | Initialize )(ARM_Storage_Callback_t callback) |
Initialize the Storage Interface. More... | |
int32_t(* | Uninitialize )(void) |
De-initialize the Storage Interface. More... | |
int32_t(* | PowerControl )(ARM_POWER_STATE state) |
Control the Storage interface power. More... | |
int32_t(* | ReadData )(uint64_t addr, void *data, uint32_t size) |
read the contents of a given address range from the storage device. More... | |
int32_t(* | ProgramData )(uint64_t addr, const void *data, uint32_t size) |
program (write into) the contents of a given address range of the storage device. More... | |
int32_t(* | Erase )(uint64_t addr, uint32_t size) |
Erase Storage range. More... | |
int32_t(* | EraseAll )(void) |
Erase complete storage. More... | |
ARM_STORAGE_STATUS(* | GetStatus )(void) |
Get the status of the current (or previous) command executed by the storage controller; stored in the structure ARM_STORAGE_STATUS. More... | |
int32_t(* | GetInfo )(ARM_STORAGE_INFO *info) |
Get information about the Storage device; stored in the structure ARM_STORAGE_INFO. More... | |
uint32_t(* | ResolveAddress )(uint64_t addr) |
For memory-mapped storage, resolve an address relative to the storage controller into a memory address. More... | |
int32_t(* | GetNextBlock )(const ARM_STORAGE_BLOCK *prev_block, ARM_STORAGE_BLOCK *next_block) |
Advance to the successor of the current block (iterator), or fetch the first block (if 'prev_block' is passed in as NULL). More... | |
int32_t(* | GetBlock )(uint64_t addr, ARM_STORAGE_BLOCK *block) |
Find the storage block (iterator) encompassing a given storage address. More... | |
This is the set of operations constituting the Storage driver.
Their implementation is platform-specific, and needs to be supplied by the porting effort.
Some APIs within ARM_DRIVER_STORAGE
will always operate synchronously: GetVersion, GetCapabilities, GetStatus, GetInfo, ResolveAddress, GetNextBlock, and GetBlock. This means that control returns to the caller with a relevant status code only after the completion of the operation (or the discovery of a failure condition).
The remainder of the APIs: Initialize, Uninitialize, PowerControl, ReadData, ProgramData, Erase, EraseAll, can function asynchronously if the underlying controller supports it–i.e. if ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. In the case of asynchronous operation, the invocation returns early (with ARM_DRIVER_OK) and results in a completion callback later. If ARM_STORAGE_CAPABILITIES::asynchronous_ops is not set, then all such APIs execute synchronously, and control returns to the caller with a status code only after the completion of the operation (or the discovery of a failure condition).
If ARM_STORAGE_CAPABILITIES::asynchronous_ops is set, a storage driver may still choose to execute asynchronous operations in a synchronous manner. If so, the driver returns a positive value to indicate successful synchronous completion (or an error code in case of failure) and no further invocation of completion callback should be expected. The expected return value for synchronous completion of such asynchronous operations varies depending on the operation. For operations involving data access, it often equals the amount of data transferred or affected. For non data-transfer operations, such as EraseAll or Initialize, it is usually 1.
Here's a code snippet to suggest how asynchronous APIs might be used by callers to handle both synchronous and asynchronous execution by the underlying storage driver:
Definition at line 292 of file Driver_Storage.h.
int32_t(* Erase) (uint64_t addr, uint32_t size) |
Erase Storage range.
This function erases a range of storage specified by [addr, addr + size). Both 'addr' and 'addr + size' should align with the 'erase_unit'(s) of the respective owning storage block(s) (see ARM_STORAGE_BLOCK and ARM_STORAGE_BLOCK_ATTRIBUTES). The range to be erased will have its contents returned to the un-programmed state– i.e. to 'erased_value' (see ARM_STORAGE_BLOCK_ATTRIBUTES), which is usually 1 to indicate the pattern of all ones: 0xFF.
[in] | addr | This is the start-address of the range to be erased. It must start at an 'erase_unit' boundary of the underlying block. |
[in] | size | Size (in bytes) of the range to be erased. 'addr + size' must be aligned with the 'erase_unit' of the underlying block. |
Definition at line 611 of file Driver_Storage.h.
int32_t(* EraseAll) (void) |
Erase complete storage.
Optional function for faster erase of the complete device.
This optional function erases the complete device. If the device does not support global erase then the function returns the error value ARM_DRIVER_ERROR_UNSUPPORTED. The data field 'erase_all' = 1 of the structure ARM_STORAGE_CAPABILITIES encodes that ARM_STORAGE_EraseAll is supported.
Definition at line 639 of file Driver_Storage.h.
int32_t(* GetBlock) (uint64_t addr, ARM_STORAGE_BLOCK *block) |
Find the storage block (iterator) encompassing a given storage address.
[in] | addr | Storage address in bytes. |
[out] | block | A caller-owned buffer large enough to be filled in with the ARM_STORAGE_BLOCK encapsulating the given address. This value can also be passed in as NULL if the caller isn't interested in populating a buffer with the block–if the caller only wishes to establish the presence of a containing storage block. |
Definition at line 766 of file Driver_Storage.h.
ARM_STORAGE_CAPABILITIES(* GetCapabilities) (void) |
Get driver capabilities.
The function GetCapabilities() returns information about capabilities in this driver implementation. The data fields of the struct ARM_STORAGE_CAPABILITIES encode various capabilities, for example if the device is able to execute operations asynchronously.
Example:
Definition at line 357 of file Driver_Storage.h.
int32_t(* GetInfo) (ARM_STORAGE_INFO *info) |
Get information about the Storage device; stored in the structure ARM_STORAGE_INFO.
[out] | info | A caller-supplied buffer capable of being filled in with an ARM_STORAGE_INFO. |
Definition at line 670 of file Driver_Storage.h.
int32_t(* GetNextBlock) (const ARM_STORAGE_BLOCK *prev_block, ARM_STORAGE_BLOCK *next_block) |
Advance to the successor of the current block (iterator), or fetch the first block (if 'prev_block' is passed in as NULL).
This helper function fetches (an iterator to) the next block (or the first block if 'prev_block' is passed in as NULL). In the failure case, a terminating, invalid block iterator is filled into the out parameter: 'next_block'. In combination with ARM_STORAGE_VALID_BLOCK(), it can be used to iterate over the sequence of blocks within the storage map:
[in] | prev_block | An existing block (iterator) within the same storage controller. The memory buffer holding this block is owned by the caller. This pointer may be NULL; if so, the invocation fills in the first block into the out parameter: 'next_block'. |
[out] | next_block | A caller-owned buffer large enough to be filled in with the following ARM_STORAGE_BLOCK. It is legal to provide the same buffer using 'next_block' as was passed in with 'prev_block'. It is also legal to pass a NULL into this parameter if the caller isn't interested in populating a buffer with the next block–i.e. if the caller only wishes to establish the presence of a next block. |
Definition at line 738 of file Driver_Storage.h.
ARM_STORAGE_STATUS(* GetStatus) (void) |
Get the status of the current (or previous) command executed by the storage controller; stored in the structure ARM_STORAGE_STATUS.
Definition at line 651 of file Driver_Storage.h.
ARM_DRIVER_VERSION(* GetVersion) (void) |
Get driver version.
The function GetVersion() returns version information of the driver implementation in ARM_DRIVER_VERSION.
Example:
Definition at line 325 of file Driver_Storage.h.
int32_t(* Initialize) (ARM_Storage_Callback_t callback) |
Initialize the Storage Interface.
The function Initialize is called when the middleware component starts operation. In addition to bringing the controller to a ready state, Initialize() receives a callback handler to be invoked upon completion of asynchronous operations.
Initialize() needs to be called explicitly before powering the peripheral using PowerControl(), and before initiating other accesses to the storage controller.
The function performs the following operations:
To start working with a peripheral the functions Initialize and PowerControl need to be called in this order: drv->Initialize (...); // Allocate I/O pins drv->PowerControl (ARM_POWER_FULL); // Power up peripheral, setup IRQ/DMA
To stop working with a peripheral the functions PowerControl and Uninitialize need to be called in this order: drv->PowerControl (ARM_POWER_OFF); // Terminate any pending transfers, reset IRQ/DMA, power off peripheral drv->Uninitialize (...); // Release I/O pins
The functions PowerControl and Uninitialize always execute and can be used to put the peripheral into a Safe State, for example after any data transmission errors. To restart the peripheral in an error condition, you should first execute the Stop Sequence and then the Start Sequence.
[in] | callback | Caller-defined callback to be invoked upon command completion for asynchronous APIs (including the completion of initialization). Use a NULL pointer when no callback signals are required. |
Definition at line 414 of file Driver_Storage.h.
int32_t(* PowerControl) (ARM_POWER_STATE state) |
Control the Storage interface power.
The function ARM_Storage_PowerControl operates the power modes of the Storage interface.
To start working with a peripheral the functions Initialize and PowerControl need to be called in this order: drv->Initialize (...); // Allocate I/O pins drv->PowerControl (ARM_POWER_FULL); // Power up peripheral, setup IRQ/DMA
To stop working with a peripheral the functions PowerControl and Uninitialize need to be called in this order:
drv->PowerControl (ARM_POWER_OFF); // Terminate any pending transfers, reset IRQ/DMA, power off peripheral drv->Uninitialize (...); // Release I/O pins
The functions PowerControl and Uninitialize always execute and can be used to put the peripheral into a Safe State, for example after any data transmission errors. To restart the peripheral in an error condition, you should first execute the Stop Sequence and then the Start Sequence.
state | ARM_POWER_STATE. The target power-state for the storage controller. The parameter state can have the following values:
|
Definition at line 485 of file Driver_Storage.h.
int32_t(* ProgramData) (uint64_t addr, const void *data, uint32_t size) |
program (write into) the contents of a given address range of the storage device.
Write the contents of a given memory buffer into a range of storage memory. In the case of flash memory, the destination range in storage memory typically has its contents in an erased state from a preceding erase operation. The source memory buffer is owned by the caller and should remain accessible for the lifetime of this command.
[in] | addr | This is the start address of the range to be written into. It needs to be aligned to the device's program_unit specified in ARM_STORAGE_INFO. |
[in] | data | The source of the write operation. The buffer is owned by the caller and should remain accessible for the lifetime of this command. |
[in] | size | The number of bytes requested to be written. The buffer should be at least as large as this size. |
Definition at line 558 of file Driver_Storage.h.
int32_t(* ReadData) (uint64_t addr, void *data, uint32_t size) |
read the contents of a given address range from the storage device.
Read the contents of a range of storage memory into a buffer supplied by the caller. The buffer is owned by the caller and should remain accessible for the lifetime of this command.
[in] | addr | This specifies the address from where to read data. |
[out] | data | The destination of the read operation. The buffer is owned by the caller and should remain accessible for the lifetime of this command. |
[in] | size | The number of bytes requested to read. The data buffer should be at least as large as this size. |
Definition at line 517 of file Driver_Storage.h.
uint32_t(* ResolveAddress) (uint64_t addr) |
For memory-mapped storage, resolve an address relative to the storage controller into a memory address.
addr | This is the address for which we want a resolution to the processor's physical address space. It is an offset from the start of the storage map maintained by the owning storage controller. |
Definition at line 689 of file Driver_Storage.h.
int32_t(* Uninitialize) (void) |
De-initialize the Storage Interface.
The function Uninitialize() de-initializes the resources of Storage interface.
It is called when the middleware component stops operation, and wishes to release the software resources used by the interface.
Definition at line 434 of file Driver_Storage.h.