Storage Interface

Driver API for Storage Device Interface (Driver_Storage.h) More...

Content
	Use of Storage APIs
	Sample Use of Storage Driver

Data Structures
struct	ARM_STORAGE_BLOCK_ATTRIBUTES
	Attributes of the storage range within a storage block. More...
struct	ARM_STORAGE_BLOCK
	A storage block is a range of memory with uniform attributes. More...
struct	ARM_STORAGE_INFO
struct	ARM_DRIVER_STORAGE
struct	ARM_STORAGE_CAPABILITIES
	Storage Driver API Capabilities. More...
struct	ARM_STORAGE_STATUS
	Operating status of the storage controller. More...

Typedefs
typedef void(*	ARM_Storage_Callback_t) (int32_t status, ARM_STORAGE_OPERATION operation)

Enumerations
enum	ARM_STORAGE_OPERATION {   ARM_STORAGE_OPERATION_GET_VERSION ,   ARM_STORAGE_OPERATION_GET_CAPABILITIES ,   ARM_STORAGE_OPERATION_INITIALIZE ,   ARM_STORAGE_OPERATION_UNINITIALIZE ,   ARM_STORAGE_OPERATION_POWER_CONTROL ,   ARM_STORAGE_OPERATION_READ_DATA ,   ARM_STORAGE_OPERATION_PROGRAM_DATA ,   ARM_STORAGE_OPERATION_ERASE ,   ARM_STORAGE_OPERATION_ERASE_ALL ,   ARM_STORAGE_OPERATION_GET_STATUS ,   ARM_STORAGE_OPERATION_GET_INFO ,   ARM_STORAGE_OPERATION_RESOLVE_ADDRESS ,   ARM_STORAGE_OPERATION_GET_NEXT_BLOCK ,   ARM_STORAGE_OPERATION_GET_BLOCK }

Functions
ARM_DRIVER_VERSION	ARM_Storage_GetVersion (void)
	Get driver version.
ARM_STOR_CAPABILITIES	ARM_Storage_GetCapabilities (void)
	Get driver capabilities.
int32_t	ARM_Storage_Initialize (ARM_Storage_Callback_t callback)
	Initialize the Storage interface.
int32_t	ARM_Storage_Uninitialize (void)
	De-initialize the Storage Interface.
int32_t	ARM_Storage_PowerControl (ARM_POWER_STATE state)
	Control the Storage interface power.
int32_t	ARM_Storage_ReadData (uint64_t addr, void *data, uint32_t size)
	Read data from Storage.
int32_t	ARM_Storage_ProgramData (uint64_t addr, const void *data, uint32_t size)
	Program data to Storage.
int32_t	ARM_Storage_Erase (uint64_t addr, uint32_t size)
	Erase Storage range.
int32_t	ARM_Storage_EraseAll (void)
	Erase complete Storage.
ARM_Storage_STATUS	ARM_Storage_GetStatus (void)
	Get Storage status.
int32_t	ARM_Storage_GetInfo (ARM_STORAGE_INFO *info)
	Get Storage information.
uint32_t	ARM_Storage_ResolveAddress (uint64_t addr)
	Resolve an address relative to the storage controller into a memory address.
int32_t	ARM_Storage_GetNextBlock (const ARM_STORAGE_BLOCK *prev_block, ARM_STORAGE_BLOCK *next_block)
	Advance to the successor of the current block (iterator).
int32_t	ARM_Storage_GetBlock (uint64_t addr, ARM_STORAGE_BLOCK *block)
	Find the storage block (iterator) encompassing a given storage address.

Description

Driver API for Storage Device Interface (Driver_Storage.h)

This is an abstraction for a storage controller. It offers an interface to access an address space of storage locations, comprising APIs for initialization, erase, access, program, and status-fetch operations. It also offers APIs to iterate over the available Storage Blocks (ARM_STORAGE_BLOCK), allowing the discovery of block attributes such as write/erase granularities. Using the Storage abstraction, it becomes possible to write generic algorithms, such as block copy, to operate on any conforming storage device.

Note

The storage abstraction layer is not responsible for storage management. Algorithms such as block-allocation, wear-leveling, erase-before-write and other storage-management policies are the responsibility of modules external to the storage abstraction layer. In essence, the storage interface is the lowest abstraction upon which block management policies can be implemented.

Here's a picture to help locate the storage abstraction in the software stack. The part below the box labeled 'Storage abstraction layer' is implemented by a storage driver.

Storage API

The following header files define the Application Programming Interface (API) for the Flash interface:

• Driver_Storage.h : Driver API for Storage Device Interface

Driver Functions

The driver functions are published in the access struct as explained in Use of Storage APIs

• ARM_DRIVER_STORAGE : access struct for Storage driver functions

A sample use for the driver can be found at: Sample Use of Storage Driver

---

Data Structure Documentation

ARM_STORAGE_BLOCK_ATTRIBUTES

struct ARM_STORAGE_BLOCK_ATTRIBUTES

Attributes of the storage range within a storage block.

Contained in:

• ARM_STORAGE_BLOCK

Data Fields
uint32_t	erasable: 1	Erasing blocks is permitted with a minimum granularity of 'erase_unit'. Note if 'erasable' is 0 (i.e. the 'erase' operation isn't available) then 'erase_unit' (see below) is immaterial and should be 0.
uint32_t	programmable: 1	Writing to ranges is permitted with a minimum granularity of 'program_unit'. Writes are typically achieved through the ProgramData operation (following an erase); if storage isn't erasable (see 'erasable' above) but is memory-mapped (i.e. 'memory_mapped'), it can be written directly using memory-store operations.
uint32_t	executable: 1	This storage block can hold program data; the processor can fetch and execute code sourced from it. Often this is accompanied with the device being 'memory_mapped' (see ARM_STORAGE_INFO).
uint32_t	protectable: 1	The entire block can be protected from program and erase operations. Once protection is enabled for a block, its 'erasable' and 'programmable' bits are turned off.
uint32_t	reserved: 28
uint32_t	erase_unit	Minimum erase size in bytes. The offset of the start of the erase-range should also be aligned with this value. Applicable if the 'erasable' attribute is set for the block. Note if 'erasable' (see above) is 0 (i.e. the 'erase' operation isn't available) then 'erase_unit' is immaterial and should be 0.
uint32_t	protection_unit	Minimum protectable size in bytes. Applicable if the 'protectable' attribute is set for the block. This should be a divisor of the block's size. A block can be considered to be made up of consecutive, individually-protectable fragments.

ARM_STORAGE_BLOCK

struct ARM_STORAGE_BLOCK

A storage block is a range of memory with uniform attributes.

Storage blocks combine to make up the address map of a storage controller.

Data Fields
uint64_t	addr	This is the start address of the storage block. It is expressed as an offset from the start of the storage map maintained by the owning storage controller.
uint64_t	size	This is the size of the storage block, in units of bytes. Together with addr, it describes a range [addr, addr+size).
ARM_STORAGE_BLOCK_ATTRIBUTES	attributes	Attributes for this block.

ARM_STORAGE_INFO

struct ARM_STORAGE_INFO

Device level metadata regarding the Storage implementation.

It describes the characteristics of a Storage device. This includes total storage, programming size, a default value for erased memory etc. This information can be obtained from the Storage device datasheet and is used by the middleware in order to properly interact with the Storage device.

Total available storage (in bytes) is contained in total_storage. Minimum programming size (in bytes) is described by program_unit (applicable only if the programmable attribute is set for a block). It defines the granularity for programming data. The offset of the start of a program-range and the size should also be aligned with program_unit.

Note

: setting program_unit to 0 has the effect of disabling the size and alignment restrictions (setting it to 1 also has the same effect).

Optimal programming page-size (in bytes) is specified by optimal_program_unit. Some storage controllers have internal buffers into which to receive data. Writing in chunks of optimal_program_unit would achieve maximum programming speed. Like with program_unit, this is applicable only if the programmable attribute is set for the underlying storage block(s).

program_cycles is a measure of endurance for reprogramming. A value of ARM_STORAGE_PROGRAM_CYCLES_INFINITE may be used to signify infinite or unknown endurance.

Contents of erased memory is specified by the erased_value. It is usually 1 to indicate erased bytes with state 0xFF.

memory_mapped can be set to 1 to indicate that the storage device has a mapping onto the processor's memory address space.

Note

: For a memory-mapped block which isn't erasable but is programmable, writes should be possible directly to the memory-mapped storage without going through the ARM_Storage_ProgramData operation.

The field programmability holds a value to indicate storage programmability. Similarly, retention_level holds a for encoding data-retention levels for all storage blocks.

Note

These fields serve a different purpose than the ones contained in ARM_STORAGE_CAPABILITIES, which is another structure containing device-level metadata. ARM_STORAGE_CAPABILITIES describes the API capabilities, whereas ARM_STORAGE_INFO describes the device. Furthermore ARM_STORAGE_CAPABILITIES fits within a single word, and is designed to be passed around by value; ARM_STORAGE_INFO, on the other hand, contains metadata which doesn't fit into a single word and requires the use of pointers to be moved around.

Returned by:

• ARM_Storage_GetInfo

Data Fields
uint64_t	total_storage	Total available storage, in bytes.
uint32_t	program_unit	Minimum programming size in bytes. The offset of the start of the program-range should also be aligned with this value. Applicable only if the 'programmable' attribute is set for a block. Note setting program_unit to 0 has the effect of disabling the size and alignment restrictions (setting it to 1 also has the same effect).
uint32_t	optimal_program_unit	Optimal programming page-size in bytes. Some storage controllers have internal buffers into which to receive data. Writing in chunks of 'optimal_program_unit' would achieve maximum programming speed. Applicable only if the 'programmable' attribute is set for the underlying block(s).
uint32_t	program_cycles	A measure of endurance for reprogramming. Use ARM_STORAGE_PROGRAM_CYCLES_INFINITE for infinite or unknown endurance.
uint32_t	erased_value: 1	Contents of erased memory (usually 1 to indicate erased bytes with state 0xFF).
uint32_t	memory_mapped: 1	This storage device has a mapping onto the processor's memory address space. Note For a memory-mapped block which isn't erasable but is programmable (i.e. if 'erasable' is set to 0, but 'programmable' is 1), writes should be possible directly to the memory-mapped storage without going through the ProgramData operation.
uint32_t	programmability: 4	A value to indicate storage programmability.
uint32_t	retention_level: 4
uint32_t	reserved: 22
ARM_STORAGE_SECURITY_FEATURES	security	ARM_STORAGE_SECURITY_FEATURES

ARM_DRIVER_STORAGE

struct ARM_DRIVER_STORAGE

The set of operations constituting the Storage driver.

This is the set of operations constituting the Storage driver. Their implementation is platform-specific, and needs to be supplied by the porting effort. The functions of the Storage driver are accessed by function pointers exposed by this structure. Refer to Use of Storage APIs for overview information.

Each instance of a Storage interface provides such an access structure. The instance is identified by a postfix number in the symbol name of the access structure, for example:

• Driver_Storage0 is the name of the access struct of the first instance (no. 0).
• Driver_Storage1 is the name of the access struct of the second instance (no. 1).

A middleware configuration setting allows connecting the middleware to a specific driver instance Driver_Flashn. The default is 0, which connects a middleware to the first instance of a driver.

Data Fields
ARM_DRIVER_VERSION(*	GetVersion )(void)
	Pointer to ARM_Storage_GetVersion : Get driver version.
ARM_STORAGE_CAPABILITIES(*	GetCapabilities )(void)
	Pointer to ARM_Storage_GetCapabilities : Get driver capabilities.
int32_t(*	Initialize )(ARM_Storage_Callback_t callback)
	Pointer to ARM_Storage_Initialize : Initialize the Storage Interface.
int32_t(*	Uninitialize )(void)
	Pointer to ARM_Storage_Uninitialize : De-initialize the Storage Interface.
int32_t(*	PowerControl )(ARM_POWER_STATE state)
	Pointer to ARM_Storage_PowerControl : Control the Storage interface power.
int32_t(*	ReadData )(uint64_t addr, void *data, uint32_t size)
	Pointer to ARM_Storage_ReadData : Read data from Storage.
int32_t(*	ProgramData )(uint64_t addr, const void *data, uint32_t size)
	Pointer to ARM_Storage_ProgramData : Program data to Storage.
int32_t(*	Erase )(uint64_t addr, uint32_t size)
	Pointer to ARM_Storage_Erase : Erase Storage range.
int32_t(*	EraseAll )(void)
	Pointer to ARM_Storage_EraseAll : Erase complete Storage.
ARM_STORAGE_STATUS(*	GetStatus )(void)
	Pointer to ARM_Storage_GetStatus : Get Storage status.
int32_t(*	GetInfo )(ARM_STORAGE_INFO *info)
	Pointer to ARM_Storage_GetInfo : Get Storage information.
uint32_t(*	ResolveAddress )(uint64_t addr)
	Pointer to ARM_Storage_ResolveAddress : Resolve a storage address.
int32_t(*	GetNextBlock )(const ARM_STORAGE_BLOCK *prev, ARM_STORAGE_BLOCK *next)
	Pointer to ARM_Storage_GetNextBlock : fetch successor for current block.
int32_t(*	GetBlock )(uint64_t addr, ARM_STORAGE_BLOCK *block)
	Pointer to ARM_Storage_GetBlock :

Field Documentation

GetVersion

ARM_DRIVER_VERSION(* GetVersion) (void)

Pointer to ARM_Storage_GetVersion : Get driver version.

GetCapabilities

ARM_STORAGE_CAPABILITIES(* GetCapabilities) (void)

Pointer to ARM_Storage_GetCapabilities : Get driver capabilities.

Initialize

int32_t(* Initialize) (ARM_Storage_Callback_t callback)

Pointer to ARM_Storage_Initialize : Initialize the Storage Interface.

Uninitialize

int32_t(* Uninitialize) (void)

Pointer to ARM_Storage_Uninitialize : De-initialize the Storage Interface.

PowerControl

int32_t(* PowerControl) (ARM_POWER_STATE state)

Pointer to ARM_Storage_PowerControl : Control the Storage interface power.

ReadData

int32_t(* ReadData) (uint64_t addr, void *data, uint32_t size)

Pointer to ARM_Storage_ReadData : Read data from Storage.

ProgramData

int32_t(* ProgramData) (uint64_t addr, const void *data, uint32_t size)

Pointer to ARM_Storage_ProgramData : Program data to Storage.

Erase

int32_t(* Erase) (uint64_t addr, uint32_t size)

Pointer to ARM_Storage_Erase : Erase Storage range.

EraseAll

int32_t(* EraseAll) (void)

Pointer to ARM_Storage_EraseAll : Erase complete Storage.

GetStatus

ARM_STORAGE_STATUS(* GetStatus) (void)

Pointer to ARM_Storage_GetStatus : Get Storage status.

GetInfo

int32_t(* GetInfo) (ARM_STORAGE_INFO *info)

Pointer to ARM_Storage_GetInfo : Get Storage information.

ResolveAddress

uint32_t(* ResolveAddress) (uint64_t addr)

Pointer to ARM_Storage_ResolveAddress : Resolve a storage address.

GetNextBlock

int32_t(* GetNextBlock) (const ARM_STORAGE_BLOCK *prev, ARM_STORAGE_BLOCK *next)

Pointer to ARM_Storage_GetNextBlock : fetch successor for current block.

GetBlock

int32_t(* GetBlock) (uint64_t addr, ARM_STORAGE_BLOCK *block)

Pointer to ARM_Storage_GetBlock :

ARM_STORAGE_CAPABILITIES

struct ARM_STORAGE_CAPABILITIES

Storage Driver API Capabilities.

A Storage driver can be implemented with different capabilities. The data fields of this struct encode the API capabilities implemented by this driver.

The element asynchronous_ops indicates if APIs like initialize, read, erase, program, etc. can operate in asynchronous mode. Having this bit set to 1 means that the driver is capable of launching asynchronous operations; command completion for asynchronous operations is signaled by the invocation of a completion callback. If set to 1, drivers may still complete asynchronous operations synchronously as necessary–in which case they return a positive error code to indicate synchronous completion. If 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).

The element erase_all specifies that the ARM_Storage_EraseAll function is supported. Typically full chip erase is much faster than erasing the whole device using ARM_Storage_Erase.

Returned by:

• ARM_Storage_GetCapabilities

Note

This data structure is designed to fit within a single word so that it can be fetched cheaply using a call to driver->GetCapabilities().

Data Fields
uint32_t	asynchronous_ops: 1	Used to indicate if APIs like initialize, read, erase, program, etc. can operate in asynchronous mode. Setting this bit to 1 means that the driver is capable of launching asynchronous operations; command completion is signaled by the invocation of a completion callback. If set to 1, drivers may still complete asynchronous operations synchronously as necessary (in which case they return a positive error code to indicate synchronous completion).
uint32_t	erase_all: 1	Supports EraseAll operation.
uint32_t	reserved: 30	Reserved (must be zero)

ARM_STORAGE_STATUS

struct ARM_STORAGE_STATUS

Operating status of the storage controller.

Structure with information about the status of the Storage device.

The flag busy indicates that the driver is busy executing read/program/erase operation.

The flag error flag is cleared on start of read/program/erase operation and is set at the end of the current operation in case of error.

Returned by:

• ARM_Storage_GetStatus

Data Fields
uint32_t	busy: 1	Controller busy flag.
uint32_t	error: 1	Read/Program/Erase error flag (cleared on start of next operation)
uint32_t	reserved: 30

Typedef Documentation

ARM_Storage_Callback_t

ARM_Storage_Callback_t

Provides the typedef for the callback function ARM_Storage_Callback_t.

Provides the typedef for the callback function ARM_Storage_Callback_t.

Parameters

[in]	status	A code to indicate the status of the completed operation. For data transfer operations, the status field is overloaded in case of success to return the count of bytes successfully transferred; this can be done safely because error codes are negative values.
[in]	operation	The command op-code. This value isn't essential, but it is expected that this information could be a quick and useful filter for the handler.

Parameter for:

• ARM_Storage_Initialize

Enumeration Type Documentation

ARM_STORAGE_OPERATION

enum ARM_STORAGE_OPERATION

Command opcodes for Storage.

Command opcodes for the Storage interface. Completion callbacks use these codes to refer to completing commands. Refer to ARM_Storage_Callback_t.

Enumerator
ARM_STORAGE_OPERATION_GET_VERSION
ARM_STORAGE_OPERATION_GET_CAPABILITIES
ARM_STORAGE_OPERATION_INITIALIZE
ARM_STORAGE_OPERATION_UNINITIALIZE
ARM_STORAGE_OPERATION_POWER_CONTROL
ARM_STORAGE_OPERATION_READ_DATA
ARM_STORAGE_OPERATION_PROGRAM_DATA
ARM_STORAGE_OPERATION_ERASE
ARM_STORAGE_OPERATION_ERASE_ALL
ARM_STORAGE_OPERATION_GET_STATUS
ARM_STORAGE_OPERATION_GET_INFO
ARM_STORAGE_OPERATION_RESOLVE_ADDRESS
ARM_STORAGE_OPERATION_GET_NEXT_BLOCK
ARM_STORAGE_OPERATION_GET_BLOCK

Function Documentation

ARM_Storage_GetVersion()

ARM_DRIVER_VERSION ARM_Storage_GetVersion

(

void

)

Get driver version.

Returns

ARM_DRIVER_VERSION

The function ARM_Storage_GetVersion returns version information of the driver implementation in ARM_DRIVER_VERSION.

• API version is the version of the CMSIS-Driver specification used to implement this driver.
• Driver version is source code version of the actual driver implementation.

Example:

extern ARM_DRIVER_STORAGE *drv_info;
 
void read_version (void)  {
  ARM_DRIVER_VERSION  version;
 
  version = drv_info->GetVersion ();
  if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
    // error handling
    return;
  }
}

Note

HAPI returns synchronously–it does not result in an invocation of a completion callback.

The function GetVersion() can be called any time to obtain the required information from the driver (even before initialization). It always returns the same information.

ARM_Storage_GetCapabilities()

ARM_STORAGE_CAPABILITIES ARM_Storage_GetCapabilities

(

void

)

Get driver capabilities.

Returns

ARM_STORAGE_CAPABILITIES

The function ARM_Storage_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:

extern ARM_DRIVER_STORAGE *drv_info;
 
void read_capabilities (void)  {
  ARM_STORAGE_CAPABILITIES drv_capabilities;
 
  drv_capabilities = drv_info->GetCapabilities ();
  // interrogate capabilities
 
}

Note

This API returns synchronously–it does not result in an invocation of a completion callback.

The function GetCapabilities() can be called any time to obtain the required information from the driver (even before initialization). It always returns the same information.

ARM_Storage_Initialize()

int32_t ARM_Storage_Initialize

(

ARM_Storage_Callback_t

callback

)

Initialize the Storage interface.

Parameters

[in]

callback

Pointer to ARM_Storage_Callback_t. 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.

Returns

If asynchronous activity is launched, invocation ARM_DRIVER_OK, and the caller can expect to receive a callback in the future with a status value of ARM_DRIVER_OK or an error-code. In the case of synchronous execution, control returns after completion with a value of 1. Return values less than ARM_DRIVER_OK (0) signify errors.

The function ARM_Storage_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.

ARM_Storage_Initialize() needs to be called explicitly before powering the peripheral using ARM_Storage_PowerControl(), and before initiating other accesses to the storage controller.

The function performs the following operations:

• Initializes the resources needed for the Storage interface.
• Registers the ARM_Storage_Callback_t callback function.

To start working with a peripheral the functions ARM_Storage_Initialize and ARM_Storage_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

• ARM_Storage_Initialize() typically allocates the I/O resources (pins) for the peripheral. The function can be called multiple times; if the I/O resources are already initialized it performs no operation and just returns with ARM_DRIVER_OK.
• ARM_Storage_PowerControl (ARM_POWER_FULL) sets the peripheral registers including interrupt (NVIC) and optionally DMA. The function can be called multiple times; if the registers are already set it performs no operation and just returns with ARM_DRIVER_OK.

To stop working with a peripheral the functions ARM_Storage_PowerControl() and ARM_Storage_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 ARM_Storage_PowerControl() and ARM_Storage_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.

Note

This API may execute asynchronously if ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous execution is optional even if 'asynchronous_ops' is set.

ARM_Storage_Uninitialize()

int32_t ARM_Storage_Uninitialize

(

void

)

De-initialize the Storage Interface.

Returns

If asynchronous activity is launched, an invocation returns ARM_DRIVER_OK, and the caller can expect to receive a callback in the future with a status value of ARM_DRIVER_OK or an error-code. In the case of synchronous execution, control returns after completion with a value of 1. Return values less than ARM_DRIVER_OK (0) signify errors.

It is called when the middleware component stops operation, and wishes to release the software resources used by the interface.

Note

This API may execute asynchronously if ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous execution is optional even if 'asynchronous_ops' is set.

ARM_Storage_PowerControl()

int32_t ARM_Storage_PowerControl

(

ARM_POWER_STATE

state

)

Control the Storage interface power.

Parameters

[in]

state

Power state

Returns

If asynchronous activity is launched, an invocation returns ARM_DRIVER_OK, and the caller can expect to receive a callback in the future with a status value of ARM_DRIVER_OK or an error-code. In the case of synchronous execution, control returns after completion with a value of 1. Return values less than ARM_DRIVER_OK (0) signify errors.

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

• ARM_Storage_Initialize() typically allocates the I/O resources (pins) for the peripheral. The function can be called multiple times; if the I/O resources are already initialized it performs no operation and just returns with ARM_DRIVER_OK.
• PowerControl (ARM_POWER_FULL) sets the peripheral registers including interrupt (NVIC) and optionally DMA. The function can be called multiple times; if the registers are already set it performs no operation and just returns with ARM_DRIVER_OK.

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 ARM_Storage_PowerControl and ARM_Storage_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.

The parameter state can have the following values:

• ARM_POWER_FULL : set-up the Storage device for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times. If the device is already in this mode, then the function performs no operation and returns with ARM_DRIVER_OK.
• ARM_POWER_LOW : may use power saving. Returns ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
• ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.

Note

This API may execute asynchronously if ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous execution is optional even if 'asynchronous_ops' is set.

ARM_Storage_ReadData()

int32_t ARM_Storage_ReadData	(	uint64_t	addr,
		void *	data,
		uint32_t	size
	)

Read data from Storage.

Parameters

[in]	addr	Data address.
[out]	data	Pointer to a buffer storing the data read from Storage.
[in]	size	Number of bytes to read. The data buffer should be at least as large as this size.

Returns

If asynchronous activity is launched, an invocation returns ARM_DRIVER_OK, and the caller can expect to receive a callback in the future with the number of successfully transferred bytes passed in as the 'status' parameter. In the case of synchronous execution, control returns after completion with a positive transfer-count. Return values less than ARM_DRIVER_OK (0) signify errors.

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.

Note

This API may execute asynchronously if ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous execution is optional even if 'asynchronous_ops' is set.

ARM_Storage_ProgramData()

int32_t ARM_Storage_ProgramData	(	uint64_t	addr,
		const void *	data,
		uint32_t	size
	)

Program data to Storage.

Parameters

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

Note

'size' should be a multiple of the device's 'program_unit' (see ARM_STORAGE_INFO).

Returns

If asynchronous activity is launched, an invocation returns ARM_DRIVER_OK, and the caller can expect to receive a callback in the future with the number of successfully transferred bytes passed in as the 'status' parameter. In the case of synchronous execution, control returns after completion with a positive transfer-count. Return values less than ARM_DRIVER_OK (0) signify errors.

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.

Note

It is best for the middleware to write in units of 'optimal_program_unit' (ARM_STORAGE_INFO) of the device.

This API may execute asynchronously if ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous execution is optional even if 'asynchronous_ops' is set.

ARM_Storage_Erase()

int32_t ARM_Storage_Erase	(	uint64_t	addr,
		uint32_t	size
	)

Erase Storage range.

Parameters

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

Returns

If the range to be erased doesn't align with the erase_units of the respective start and end blocks, ARM_DRIVER_ERROR_PARAMETER is returned. If any part of the range is protected, ARM_STORAGE_ERROR_PROTECTED is returned. If any part of the range is not erasable, ARM_STORAGE_ERROR_NOT_ERASABLE is returned. All such sanity-check failures result in the error code being returned synchronously and the storage bytes within the range remain unaffected. Otherwise the function executes in the following ways: If asynchronous activity is launched, an invocation returns ARM_DRIVER_OK, and the caller can expect to receive a callback in the future with the number of successfully erased bytes passed in as the 'status' parameter. In the case of synchronous execution, control returns after completion with a positive erase-count. Return values less than ARM_DRIVER_OK (0) signify errors.

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 ARM_STORAGE_INFO::erased_value, which is usually 1 to indicate the pattern of all ones: 0xFF.

Note

This API may execute asynchronously if ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous execution is optional even if 'asynchronous_ops' is set.

Erase() may return a smaller (positive) value than the size of the requested range. The returned value indicates the actual number of bytes erased. It is the caller's responsibility to follow up with an appropriate request to complete the operation.

in the case of a failed erase (except when ARM_DRIVER_ERROR_PARAMETER, ARM_STORAGE_ERROR_PROTECTED, or ARM_STORAGE_ERROR_NOT_ERASABLE is returned synchronously), the requested range should be assumed to be in an unknown state. The previous contents may not be retained.

ARM_Storage_EraseAll()

int32_t ARM_Storage_EraseAll

(

void

)

Erase complete Storage.

Returns

If any part of the storage range is protected, ARM_STORAGE_ERROR_PROTECTED is returned. If any part of the storage range is not erasable, ARM_STORAGE_ERROR_NOT_ERASABLE is returned. All such sanity-check failures result in the error code being returned synchronously and the storage bytes within the range remain unaffected. Otherwise the function executes in the following ways: If asynchronous activity is launched, an invocation returns ARM_DRIVER_OK, and the caller can expect to receive a callback in the future with ARM_DRIVER_OK passed in as the 'status' parameter. In the case of synchronous execution, control returns after completion with a value of 1. Return values less than ARM_DRIVER_OK (0) signify errors.

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.

Note

This API may execute asynchronously if ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous execution is optional even if 'asynchronous_ops' is set.

ARM_Storage_GetStatus()

ARM_STORAGE_STATUS ARM_Storage_GetStatus

(

void

)

Get Storage status.

Returns

Storage status ARM_STORAGE_STATUS

Get the status of the current (or previous) command executed by the storage controller; stored in the structure ARM_STORAGE_STATUS.

Note

This API returns synchronously–it does not result in an invocation of a completion callback.

ARM_Storage_GetInfo()

int32_t ARM_Storage_GetInfo

(

ARM_STORAGE_INFO *

info

)

Get Storage information.

Parameters

[out]

info

A caller-supplied buffer capable of being filled in with an ARM_STORAGE_INFO.

Returns

ARM_DRIVER_OK if a ARM_STORAGE_INFO structure containing top level metadata about the storage controller is filled into the supplied buffer, else an appropriate error value.

Get information about the Storage device; stored in the structure ARM_STORAGE_INFO.

Note

It is the caller's responsibility to ensure that the buffer passed in is able to be initialized with a ARM_STORAGE_INFO.

This API returns synchronously–it does not result in an invocation of a completion callback.

ARM_Storage_ResolveAddress()

uint32_t ARM_Storage_ResolveAddress

(

uint64_t

addr

)

Resolve an address relative to the storage controller into a memory address.

Parameters

[in]

addr

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.

Returns

The resolved address in the processor's address space, else ARM_STORAGE_INVALID_ADDRESS.

Only applicable to devices with memory-mapped storage.

Note

This API returns synchronously. The invocation should return quickly, and result in a resolved address.

ARM_Storage_GetNextBlock()

int32_t ARM_Storage_GetNextBlock	(	const ARM_STORAGE_BLOCK *	prev_block,
		ARM_STORAGE_BLOCK *	next_block
	)

Advance to the successor of the current block (iterator).

Parameters

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

Returns

ARM_DRIVER_OK if a valid next block is found (or first block, if prev_block is passed as NULL); upon successful operation, the contents of the next (or first) block are filled into the buffer pointed to by the parameter 'next_block' and ARM_STORAGE_VALID_BLOCK(next_block) is guaranteed to be true. Upon reaching the end of the sequence of blocks (iterators), or in case the driver is unable to fetch information about the next (or first) block, an error (negative) value is returned and an invalid StorageBlock is populated into the supplied buffer. If prev_block is NULL, the first block is returned.

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:

ARM_STORAGE_BLOCK block;
for (drv->GetNextBlock(NULL, &block); ARM_STORAGE_VALID_BLOCK(&block); drv->GetNextBlock(&block, &block)) {
    // make use of block
}

Note

This API returns synchronously–it does not result in an invocation of a completion callback.

ARM_Storage_GetBlock()

int32_t ARM_Storage_GetBlock	(	uint64_t	addr,
		ARM_STORAGE_BLOCK *	block
	)

Find the storage block (iterator) encompassing a given storage address.

Parameters

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

Returns

ARM_DRIVER_OK if a containing storage-block is found. In this case, if block is non-NULL, the buffer pointed to by it is populated with the contents of the storage block, i.e. if block is valid and a block is found, ARM_STORAGE_VALID_BLOCK(block) would return true following this call. If there is no storage block containing the given offset, or in case the driver is unable to resolve an address to a storage-block, an error (negative) value is returned and an invalid StorageBlock is populated into the supplied buffer.

Note

This API returns synchronously–it does not result in an invocation of a completion callback.