begriffs open source - cmsis/blob - CMSIS/Driver/Include/Driver_Storage.h

   1 /*
   2  * Copyright (c) 2006-2016, ARM Limited, All Rights Reserved
   3  * SPDX-License-Identifier: Apache-2.0
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License"); you may
   6  * not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  * http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 #ifndef __DRIVER_STORAGE_H
  19 #define __DRIVER_STORAGE_H
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif // __cplusplus
  24
  25 #include "Driver_Common.h"
  26
  27 #define ARM_STORAGE_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(1,00)  /* API version */
  28
  29
  30 #define _ARM_Driver_Storage_(n)      Driver_Storage##n
  31 #define  ARM_Driver_Storage_(n) _ARM_Driver_Storage_(n)
  32
  33 #define ARM_STORAGE_INVALID_OFFSET  (0xFFFFFFFFFFFFFFFFULL) ///< Invalid address (relative to a storage controller's
  34                                                             ///< address space). A storage block may never start at this address.
  35
  36 #define ARM_STORAGE_INVALID_ADDRESS (0xFFFFFFFFUL)          ///< Invalid address within the processor's memory address space.
  37                                                             ///< Refer to memory-mapped storage, i.e. < \ref ARM_DRIVER_STORAGE::ResolveAddress().
  38
  39 /****** Storage specific error codes *****/
  40 #define ARM_STORAGE_ERROR_NOT_ERASABLE      (ARM_DRIVER_ERROR_SPECIFIC - 1) ///< Part (or all) of the range provided to Erase() isn't erasable.
  41 #define ARM_STORAGE_ERROR_NOT_PROGRAMMABLE  (ARM_DRIVER_ERROR_SPECIFIC - 2) ///< Part (or all) of the range provided to ProgramData() isn't programmable.
  42 #define ARM_STORAGE_ERROR_PROTECTED         (ARM_DRIVER_ERROR_SPECIFIC - 3) ///< Part (or all) of the range to Erase() or ProgramData() is protected.
  43
  44 /**
  45  * Attributes of the storage range within a storage block.
  46  */
  47 typedef struct _ARM_STORAGE_BLOCK_ATTRIBUTES {
  48   uint32_t erasable      :  1;   ///< Erasing blocks is permitted with a minimum granularity of 'erase_unit'.
  49                                  ///< @note: if 'erasable' is 0--i.e. the 'erase' operation isn't available--then
  50                                  ///< 'erase_unit' (see below) is immaterial and should be 0.
  51
  52   uint32_t programmable  :  1;   ///< Writing to ranges is permitted with a minimum granularity of 'program_unit'.
  53                                  ///< Writes are typically achieved through the ProgramData operation (following an erase);
  54                                  ///< if storage isn't erasable (see 'erasable' above) but is memory-mapped
  55                                  ///< (i.e. 'memory_mapped'), it can be written directly using memory-store operations.
  56
  57   uint32_t executable    :  1;   ///< This storage block can hold program data; the processor can fetch and execute code
  58                                  ///< sourced from it. Often this is accompanied with the device being 'memory_mapped' (see \ref ARM_STORAGE_INFO).
  59
  60   uint32_t protectable   :  1;   ///< The entire block can be protected from program and erase operations. Once protection
  61                                  ///< is enabled for a block, its 'erasable' and 'programmable' bits are turned off.
  62
  63   uint32_t reserved      : 28;
  64
  65   uint32_t erase_unit;           ///< Minimum erase size in bytes.
  66                                  ///< The offset of the start of the erase-range should also be aligned with this value.
  67                                  ///< Applicable if the 'erasable' attribute is set for the block.
  68                                  ///< @note: if 'erasable' (see above) is 0--i.e. the 'erase' operation isn't available--then
  69                                  ///< 'erase_unit' is immaterial and should be 0.
  70
  71   uint32_t protection_unit;      ///< Minimum protectable size in bytes. Applicable if the 'protectable'
  72                                  ///< attribute is set for the block. This should be a divisor of the block's size. A
  73                                  ///< block can be considered to be made up of consecutive, individually-protectable fragments.
  74 } ARM_STORAGE_BLOCK_ATTRIBUTES;
  75
  76 /**
  77  * \brief A storage block is a range of memory with uniform attributes. Storage blocks
  78  * combine to make up the address map of a storage controller.
  79  */
  80 typedef struct _ARM_STORAGE_BLOCK {
  81   uint64_t                     addr;       ///< This is the start address of the storage block. It is
  82                                            ///< expressed as an offset from the start of the storage map
  83                                            ///< maintained by the owning storage controller.
  84
  85   uint64_t                     size;       ///< This is the size of the storage block, in units of bytes.
  86                                            ///< Together with addr, it describes a range [addr, addr+size).
  87
  88   ARM_STORAGE_BLOCK_ATTRIBUTES attributes; ///< Attributes for this block.
  89 } ARM_STORAGE_BLOCK;
  90
  91 /**
  92  * The check for a valid ARM_STORAGE_BLOCK.
  93  */
  94 #define ARM_STORAGE_VALID_BLOCK(BLK) (((BLK)->addr != ARM_STORAGE_INVALID_OFFSET) && ((BLK)->size != 0))
  95
  96 /**
  97  * \brief Values for encoding storage memory-types with respect to programmability.
  98  *
  99  * Please ensure that the maximum of the following memory types doesn't exceed 16; we
 100  * encode this in a 4-bit field within ARM_STORAGE_INFO::programmability.
 101  */
 102 #define ARM_STORAGE_PROGRAMMABILITY_RAM       (0x0)
 103 #define ARM_STORAGE_PROGRAMMABILITY_ROM       (0x1) ///< Read-only memory.
 104 #define ARM_STORAGE_PROGRAMMABILITY_WORM      (0x2) ///< write-once-read-only-memory (WORM).
 105 #define ARM_STORAGE_PROGRAMMABILITY_ERASABLE  (0x3) ///< re-programmable based on erase. Supports multiple writes.
 106
 107 /**
 108  * Values for encoding data-retention levels for storage blocks.
 109  *
 110  * Please ensure that the maximum of the following retention types doesn't exceed 16; we
 111  * encode this in a 4-bit field within ARM_STORAGE_INFO::retention_level.
 112  */
 113 #define ARM_RETENTION_WHILE_DEVICE_ACTIVE     (0x0) ///< Data is retained only during device activity.
 114 #define ARM_RETENTION_ACROSS_SLEEP            (0x1) ///< Data is retained across processor sleep.
 115 #define ARM_RETENTION_ACROSS_DEEP_SLEEP       (0x2) ///< Data is retained across processor deep-sleep.
 116 #define ARM_RETENTION_BATTERY_BACKED          (0x3) ///< Data is battery-backed. Device can be powered off.
 117 #define ARM_RETENTION_NVM                     (0x4) ///< Data is retained in non-volatile memory.
 118
 119 /**
 120  * Device Data Security Protection Features. Applicable mostly to EXTERNAL_NVM.
 121  */
 122 typedef struct _ARM_STORAGE_SECURITY_FEATURES {
 123   uint32_t acls                :  1; ///< Protection against internal software attacks using ACLs.
 124   uint32_t rollback_protection :  1; ///< Roll-back protection. Set to true if the creator of the storage
 125                                      ///<   can ensure that an external attacker can't force an
 126                                      ///<   older firmware to run or to revert back to a previous state.
 127   uint32_t tamper_proof        :  1; ///< Tamper-proof memory (will be deleted on tamper-attempts using board level or chip level sensors).
 128   uint32_t internal_flash      :  1; ///< Internal flash.
 129   uint32_t reserved1           : 12;
 130
 131   /**
 132    * Encode support for hardening against various classes of attacks.
 133    */
 134   uint32_t software_attacks     :  1; ///< device software (malware running on the device).
 135   uint32_t board_level_attacks  :  1; ///< board level attacks (debug probes, copy protection fuses.)
 136   uint32_t chip_level_attacks   :  1; ///< chip level attacks (tamper-protection).
 137   uint32_t side_channel_attacks :  1; ///< side channel attacks.
 138   uint32_t reserved2            : 12;
 139 } ARM_STORAGE_SECURITY_FEATURES;
 140
 141 #define ARM_STORAGE_PROGRAM_CYCLES_INFINITE (0UL) /**< Infinite or unknown endurance for reprogramming. */
 142
 143 /**
 144  * \brief Storage information. This contains device-metadata, and is the return
 145  *     value from calling GetInfo() on the storage driver.
 146  *
 147  * \details These fields serve a different purpose than the ones contained in
 148  *     ARM_STORAGE_CAPABILITIES (\ref ARM_STORAGE_CAPABILITIES), which is
 149  *     another structure containing device-level metadata.
 150  *     ARM_STORAGE_CAPABILITIES describes the API capabilities, whereas ARM_STORAGE_INFO
 151  *     describes the device. Furthermore ARM_STORAGE_CAPABILITIES fits within a
 152  *     single word, and is designed to be passed around by value;
 153  *     ARM_STORAGE_INFO, on the other hand contains metadata which doesn't fit
 154  *     into a single word and requires the use of pointers to be moved around.
 155  */
 156 typedef struct _ARM_STORAGE_INFO {
 157   uint64_t                      total_storage;        ///< Total available storage, in bytes.
 158
 159   uint32_t                      program_unit;         ///< Minimum programming size in bytes.
 160                                                       ///< The offset of the start of the program-range should also be aligned with this value.
 161                                                       ///< Applicable only if the 'programmable' attribute is set for a block.
 162                                                       ///< @note: setting program_unit to 0 has the effect of disabling the size and alignment
 163                                                       ///< restrictions (setting it to 1 also has the same effect).
 164
 165   uint32_t                      optimal_program_unit; ///< Optimal programming page-size in bytes. Some storage controllers
 166                                                       ///< have internal buffers into which to receive data. Writing in chunks of
 167                                                       ///< 'optimal_program_unit' would make the best use of such capabilities.
 168                                                       ///< Applicable only if the 'programmable' attribute is set a the block.
 169
 170   uint32_t                      program_cycles;       ///< A measure of endurance for reprogramming.
 171                                                       ///< Use ARM_STORAGE_PROGRAM_CYCLES_INFINITE for infinite or unknown endurance.
 172
 173   uint32_t                      erased_value    :  1; ///< Contents of erased memory (usually 1 to indicate erased bytes with state 0xFF).
 174
 175   uint32_t                      memory_mapped   :  1; ///< This storage device has a mapping onto the processor's memory address space.
 176                                                       ///< @note: For a memory-mapped block which isn't erasable but is programmable (i.e. if
 177                                                       ///< 'erasable' is set to 0, but 'programmable' is 1), writes should be possible directly to
 178                                                       ///< the memory-mapped storage without going through the ProgramData operation.
 179
 180   uint32_t                      programmability :  4; ///< A value to indicate storage programmability.
 181
 182   uint32_t                      retention_level :  4;
 183
 184   uint32_t                      reserved        : 22;
 185
 186   ARM_STORAGE_SECURITY_FEATURES security;             ///< \ref ARM_STORAGE_SECURITY_FEATURES
 187 } ARM_STORAGE_INFO;
 188
 189 /**
 190 \brief Operating status of the storage controller.
 191 */
 192 typedef struct _ARM_STORAGE_STATUS {
 193   uint32_t busy  : 1;                   ///< Controller busy flag
 194   uint32_t error : 1;                   ///< Read/Program/Erase error flag (cleared on start of next operation)
 195 } ARM_STORAGE_STATUS;
 196
 197 /**
 198  * \brief Storage Driver API Capabilities.
 199  *
 200  * This data structure is designed to fit within a single word so that it can be
 201  * fetched cheaply using a call to driver->GetCapabilities().
 202  */
 203 typedef struct _ARM_STORAGE_CAPABILITIES {
 204   uint32_t asynchronous_ops :  1; ///< Used to indicate if APIs like initialize,
 205                                   ///<   read, erase, program, etc. can operate in asynchronous mode.
 206                                   ///<   Setting this bit to 1 means that the driver is capable
 207                                   ///<   of launching asynchronous operations; command completion is
 208                                   ///<   signaled by the invocation of a completion callback. If
 209                                   ///<   set to 1, drivers may still complete asynchronous
 210                                   ///<   operations synchronously as necessary--in which case they
 211                                   ///<   return a positive error code to indicate synchronous completion.
 212
 213   uint32_t erase_all        :  1; ///< Supports EraseAll operation.
 214
 215   uint32_t reserved         : 30;
 216 } ARM_STORAGE_CAPABILITIES;
 217
 218 /**
 219  * Command opcodes for Storage. Completion callbacks use these codes to refer to
 220  * completing commands. Refer to \ref ARM_Storage_Callback_t.
 221  */
 222 typedef enum _ARM_STORAGE_OPERATION {
 223   ARM_STORAGE_OPERATION_GET_VERSION,
 224   ARM_STORAGE_OPERATION_GET_CAPABILITIES,
 225   ARM_STORAGE_OPERATION_INITIALIZE,
 226   ARM_STORAGE_OPERATION_UNINITIALIZE,
 227   ARM_STORAGE_OPERATION_POWER_CONTROL,
 228   ARM_STORAGE_OPERATION_READ_DATA,
 229   ARM_STORAGE_OPERATION_PROGRAM_DATA,
 230   ARM_STORAGE_OPERATION_ERASE,
 231   ARM_STORAGE_OPERATION_ERASE_ALL,
 232   ARM_STORAGE_OPERATION_GET_STATUS,
 233   ARM_STORAGE_OPERATION_GET_INFO,
 234   ARM_STORAGE_OPERATION_RESOLVE_ADDRESS,
 235   ARM_STORAGE_OPERATION_GET_FIRST_BLOCK,
 236   ARM_STORAGE_OPERATION_GET_NEXT_BLOCK,
 237   ARM_STORAGE_OPERATION_GET_BLOCK
 238 } ARM_STORAGE_OPERATION;
 239
 240 // Function documentation
 241 /**
 242   \fn          ARM_DRIVER_VERSION ARM_Storage_GetVersion (void)
 243   \brief       Get driver version.
 244   \return      \ref ARM_DRIVER_VERSION
 245 */
 246 /**
 247   \fn          ARM_STORAGE_CAPABILITIES ARM_Storage_GetCapabilities (void)
 248   \brief       Get driver capabilities.
 249   \return      \ref ARM_STORAGE_CAPABILITIES
 250 */
 251 /**
 252   \fn          int32_t ARM_Storage_Initialize (ARM_Storage_Callback_t callback)
 253   \brief       Initialize the Storage Interface.
 254   \param[in]   callback  Pointer to \ref ARM_Storage_Callback_t. Caller-defined callback to be invoked upon command completion.
 255   \return      ARM_DRIVER_OK (for asynchronous execution), 1 (for synchronous completion), or <ARM_DRIVER_OK (for error).
 256 */
 257 /**
 258   \fn          int32_t ARM_Storage_Uninitialize (void)
 259   \brief       De-initialize the Storage Interface.
 260   \return      ARM_DRIVER_OK (for asynchronous execution), 1 (for synchronous completion), or <ARM_DRIVER_OK (for error).
 261 */
 262 /**
 263   \fn          int32_t ARM_Storage_PowerControl (ARM_POWER_STATE state)
 264   \brief       Control the Storage interface power.
 265   \param[in]   state  Power state
 266   \return      ARM_DRIVER_OK (for asynchronous execution), 1 (for synchronous completion), or <ARM_DRIVER_OK (for error).
 267 */
 268 /**
 269   \fn          int32_t ARM_Storage_ReadData (uint64_t addr, void *data, uint32_t size)
 270   \brief       Read data from Storage.
 271   \param[in]   addr  Data address.
 272   \param[out]  data  Pointer to a buffer storing the data read from Storage.
 273   \param[in]   size  Number of bytes to read.
 274   \return      ARM_DRIVER_OK (for asynchronous execution), number of bytes read (for synchronous completion), or <ARM_DRIVER_OK (for error).
 275 */
 276 /**
 277   \fn          int32_t ARM_Storage_ProgramData (uint64_t addr, const void *data, uint32_t size)
 278   \brief       Program data to Storage.
 279   \param[in]   addr  Data address.
 280   \param[in]   data  Pointer to a buffer containing the data to be programmed to Storage.
 281   \param[in]   size  Number of bytes to program.
 282   \return      ARM_DRIVER_OK (for asynchronous execution), number of bytes programmed (for synchronous completion), or <ARM_DRIVER_OK (for error).
 283 */
 284 /**
 285   \fn          int32_t ARM_Storage_Erase (uint64_t addr, uint32_t size)
 286   \brief       Erase Storage range.
 287   \param[in]   addr  Start-address of the range to be erased.
 288   \param[in]   size  Size (in bytes) of the range to be erased.
 289   \return      ARM_DRIVER_OK (for asynchronous execution), number of bytes erased (for synchronous completion), or <ARM_DRIVER_OK (for error).
 290 */
 291 /**
 292   \fn          int32_t ARM_Storage_EraseAll (void)
 293   \brief       Erase complete Storage.
 294                Optional function for faster full chip erase.
 295   \return      ARM_DRIVER_OK (for asynchronous execution), 1 (for synchronous completion), or <ARM_DRIVER_OK (for error).
 296 */
 297 /**
 298   \fn          ARM_STORAGE_STATUS ARM_Storage_GetStatus (void)
 299   \brief       Get Storage status.
 300   \return      Storage status \ref ARM_STORAGE_STATUS
 301 */
 302 /**
 303   \fn          int32_t ARM_Storage_GetInfo (ARM_STORAGE_INFO *info)
 304   \brief       Get Storage information.
 305   \param[out]  info  A caller-supplied buffer capable of being filled in with an \ref ARM_STORAGE_INFO.
 306   \return      ARM_DRIVER_OK if successful, else an appropriate error value.
 307 */
 308 /**
 309   \fn          uint32_t ARM_Storage_ResolveAddress(uint64_t addr)
 310   \brief       Resolve an address relative to the storage controller into a memory address.
 311   \param[in]   addr The address for which we want a resolution to the processor's physical address space.
 312   \return      The resolved address in the processor's address space, else ARM_STORAGE_INVALID_ADDRESS.
 313 */
 314 /**
 315   \fn          int32_t ARM_Storage_GetNextBlock(const ARM_STORAGE_BLOCK* prev_block, ARM_STORAGE_BLOCK *next_block);
 316   \brief       Advance to the successor of the current block (iterator).
 317   \param[in]   prev_block An existing block (iterator) within the same storage controller, or NULL.
 318   \param[out]  next_block A caller-owned buffer large enough to be filled in with the following ARM_STORAGE_BLOCK.
 319   \return      ARM_DRIVER_OK if a valid next block is found, else <ARM_DRIVER_OK for errors.
 320 */
 321 /**
 322   \fn          int32_t ARM_Storage_GetBlock(uint64_t addr, ARM_STORAGE_BLOCK *block);
 323   \brief       Find the storage block (iterator) encompassing a given storage address.
 324   \param[in]   addr Storage address in bytes.
 325   \param[out]  block A caller-owned buffer large enough to be filled in with the ARM_STORAGE_BLOCK encapsulating the given address.
 326   \return      ARM_DRIVER_OK if a containing storage-block is found, else <ARM_DRIVER_OK for errors.
 327 */
 328
 329
 330 /**
 331  * Declaration of the callback-type for command completion.
 332  *
 333  * @param [in] status
 334  *               A code to indicate the status of the completed operation. For data
 335  *               transfer operations, the status field is overloaded in case of
 336  *               success to return the count of items successfully transferred; this
 337  *               can be done safely because error codes are negative values.
 338  *
 339  * @param [in] operation
 340  *               The command op-code. This value isn't essential for the callback in
 341  *               the presence of the command instance-id, but it is expected that
 342  *               this information could be a quick and useful filter.
 343  */
 344 typedef void (*ARM_Storage_Callback_t)(int32_t status, ARM_STORAGE_OPERATION operation);
 345
 346 /**
 347  * This is the set of operations constituting the Storage driver. Their
 348  * implementation is platform-specific, and needs to be supplied by the
 349  * porting effort.
 350  *
 351  * Some APIs within `ARM_DRIVER_STORAGE` will always operate synchronously:
 352  * GetVersion, GetCapabilities, GetStatus, GetInfo, ResolveAddress,
 353  * GetNextBlock, and GetBlock. This means that control returns to the caller
 354  * with a relevant status code only after the completion of the operation (or
 355  * the discovery of a failure condition).
 356  *
 357  * The remainder of the APIs: Initialize, Uninitialize, PowerControl, ReadData,
 358  * ProgramData, Erase, EraseAll, can function asynchronously if the underlying
 359  * controller supports it--i.e. if ARM_STORAGE_CAPABILITIES::asynchronous_ops is
 360  * set. In the case of asynchronous operation, the invocation returns early
 361  * (with ARM_DRIVER_OK) and results in a completion callback later. If
 362  * ARM_STORAGE_CAPABILITIES::asynchronous_ops is not set, then all such APIs
 363  * execute synchronously, and control returns to the caller with a status code
 364  * only after the completion of the operation (or the discovery of a failure
 365  * condition).
 366  *
 367  * If ARM_STORAGE_CAPABILITIES::asynchronous_ops is set, a storage driver may
 368  * still choose to execute asynchronous operations in a synchronous manner. If
 369  * so, the driver returns a positive value to indicate successful synchronous
 370  * completion (or an error code in case of failure) and no further invocation of
 371  * completion callback should be expected. The expected return value for
 372  * synchronous completion of such asynchronous operations varies depending on
 373  * the operation. For operations involving data access, it often equals the
 374  * amount of data transferred or affected. For non data-transfer operations,
 375  * such as EraseAll or Initialize, it is usually 1.
 376  *
 377  * Here's a code snippet to suggest how asynchronous APIs might be used by
 378  * callers to handle both synchronous and asynchronous execution by the
 379  * underlying storage driver:
 380  * \code
 381  *     ASSERT(ARM_DRIVER_OK == 0); // this is a precondition; it doesn't need to be put in code
 382  *     int32_t returnValue = drv->asynchronousAPI(...);
 383  *     if (returnValue < ARM_DRIVER_OK) {
 384  *         // handle error.
 385  *     } else if (returnValue == ARM_DRIVER_OK) {
 386  *         ASSERT(drv->GetCapabilities().asynchronous_ops == 1);
 387  *         // handle early return from asynchronous execution; remainder of the work is done in the callback handler.
 388  *     } else {
 389  *         ASSERT(returnValue == EXPECTED_RETURN_VALUE_FOR_SYNCHRONOUS_COMPLETION);
 390  *         // handle synchronous completion.
 391  *     }
 392  * \endcode
 393  */
 394 typedef struct _ARM_DRIVER_STORAGE {
 395   /**
 396    * \brief Get driver version.
 397    *
 398    * The function GetVersion() returns version information of the driver implementation in ARM_DRIVER_VERSION.
 399    *
 400    *    - API version is the version of the CMSIS-Driver specification used to implement this driver.
 401    *    - Driver version is source code version of the actual driver implementation.
 402    *
 403    * Example:
 404    * \code
 405    *     extern ARM_DRIVER_STORAGE *drv_info;
 406    *
 407    *     void read_version (void)  {
 408    *       ARM_DRIVER_VERSION  version;
 409    *
 410    *       version = drv_info->GetVersion ();
 411    *       if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 412    *         // error handling
 413    *         return;
 414    *       }
 415    *     }
 416    * \endcode
 417    *
 418    * @return \ref ARM_DRIVER_VERSION.
 419    *
 420    * @note This API returns synchronously--it does not result in an invocation
 421    *     of a completion callback.
 422    *
 423    * @note The functions GetVersion() can be called any time to obtain the
 424    *     required information from the driver (even before initialization). It
 425    *     always returns the same information.
 426    */
 427   ARM_DRIVER_VERSION (*GetVersion)(void);
 428
 429   /**
 430    * \brief Get driver capabilities.
 431    *
 432    * \details The function GetCapabilities() returns information about
 433    * capabilities in this driver implementation. The data fields of the struct
 434    * ARM_STORAGE_CAPABILITIES encode various capabilities, for example if the device
 435    * is able to execute operations asynchronously.
 436    *
 437    * Example:
 438    * \code
 439    *     extern ARM_DRIVER_STORAGE *drv_info;
 440    *
 441    *     void read_capabilities (void)  {
 442    *       ARM_STORAGE_CAPABILITIES drv_capabilities;
 443    *
 444    *       drv_capabilities = drv_info->GetCapabilities ();
 445    *       // interrogate capabilities
 446    *
 447    *     }
 448    * \endcode
 449    *
 450    * @return \ref ARM_STORAGE_CAPABILITIES.
 451    *
 452    * @note This API returns synchronously--it does not result in an invocation
 453    *     of a completion callback.
 454    *
 455    * @note The functions GetVersion() can be called any time to obtain the
 456    *     required information from the driver (even before initialization). It
 457    *     always returns the same information.
 458    */
 459   ARM_STORAGE_CAPABILITIES (*GetCapabilities)(void);
 460
 461   /**
 462    * \brief Initialize the Storage Interface.
 463    *
 464    * The function Initialize is called when the middleware component starts
 465    * operation. In addition to bringing the controller to a ready state,
 466    * Initialize() receives a callback handler to be invoked upon completion of
 467    * asynchronous operations.
 468    *
 469    * Initialize() needs to be called explicitly before
 470    * powering the peripheral using PowerControl(), and before initiating other
 471    * accesses to the storage controller.
 472    *
 473    * The function performs the following operations:
 474    *   - Initializes the resources needed for the Storage interface.
 475    *   - Registers the ARM_STOR_SignalEvent callback function.
 476    *
 477    * To start working with a peripheral the functions Initialize and PowerControl need to be called in this order:
 478    *     drv->Initialize (...); // Allocate I/O pins
 479    *     drv->PowerControl (ARM_POWER_FULL);        // Power up peripheral, setup IRQ/DMA
 480    *
 481    * - Initialize() typically allocates the I/O resources (pins) for the
 482    *   peripheral. The function can be called multiple times; if the I/O resources
 483    *   are already initialized it performs no operation and just returns with
 484    *   ARM_DRIVER_OK.
 485    *
 486    * - PowerControl (ARM_POWER_FULL) sets the peripheral registers including
 487    *   interrupt (NVIC) and optionally DMA. The function can be called multiple
 488    *   times; if the registers are already set it performs no operation and just
 489    *   returns with ARM_DRIVER_OK.
 490    *
 491    * To stop working with a peripheral the functions PowerControl and Uninitialize need to be called in this order:
 492    *     drv->PowerControl (ARM_POWER_OFF);     // Terminate any pending transfers, reset IRQ/DMA, power off peripheral
 493    *     drv->Uninitialize (...);               // Release I/O pins
 494    *
 495    * The functions PowerControl and Uninitialize always execute and can be used
 496    * to put the peripheral into a Safe State, for example after any data
 497    * transmission errors. To restart the peripheral in an error condition,
 498    * you should first execute the Stop Sequence and then the Start Sequence.
 499    *
 500    * @param [in] callback
 501    *               Caller-defined callback to be invoked upon command completion
 502    *               for asynchronous APIs (including the completion of
 503    *               initialization). Use a NULL pointer when no callback
 504    *               signals are required.
 505    *
 506    * @note This API may execute asynchronously if
 507    *     ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 508    *     execution is optional even if 'asynchronous_ops' is set.
 509    *
 510    * @return If asynchronous activity is launched, an invocation returns
 511    *     ARM_DRIVER_OK, and the caller can expect to receive a callback in the
 512    *     future with a status value of ARM_DRIVER_OK or an error-code. In the
 513    *     case of synchronous execution, control returns after completion with a
 514    *     value of 1. Return values less than ARM_DRIVER_OK (0) signify errors.
 515    */
 516   int32_t (*Initialize)(ARM_Storage_Callback_t callback);
 517
 518   /**
 519    * \brief De-initialize the Storage Interface.
 520    *
 521    * The function Uninitialize() de-initializes the resources of Storage interface.
 522    *
 523    * It is called when the middleware component stops operation, and wishes to
 524    * release the software resources used by the interface.
 525    *
 526    * @note This API may execute asynchronously if
 527    *     ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 528    *     execution is optional even if 'asynchronous_ops' is set.
 529    *
 530    * @return If asynchronous activity is launched, an invocation returns
 531    *     ARM_DRIVER_OK, and the caller can expect to receive a callback in the
 532    *     future with a status value of ARM_DRIVER_OK or an error-code. In the
 533    *     case of synchronous execution, control returns after completion with a
 534    *     value of 1. Return values less than ARM_DRIVER_OK (0) signify errors.
 535    */
 536   int32_t (*Uninitialize)(void);
 537
 538   /**
 539    * \brief Control the Storage interface power.
 540    *
 541    * The function ARM_STOR_PowerControl operates the power modes of the Storage interface.
 542    *
 543    * To start working with a peripheral the functions Initialize and PowerControl need to be called in this order:
 544    *     drv->Initialize (...);                 // Allocate I/O pins
 545    *     drv->PowerControl (ARM_POWER_FULL);    // Power up peripheral, setup IRQ/DMA
 546    *
 547    * - Initialize() typically allocates the I/O resources (pins) for the
 548    *   peripheral. The function can be called multiple times; if the I/O resources
 549    *   are already initialized it performs no operation and just returns with
 550    *   ARM_DRIVER_OK.
 551    *
 552    * - PowerControl (ARM_POWER_FULL) sets the peripheral registers including
 553    *   interrupt (NVIC) and optionally DMA. The function can be called multiple
 554    *   times; if the registers are already set it performs no operation and just
 555    *   returns with ARM_DRIVER_OK.
 556    *
 557    * To stop working with a peripheral the functions PowerControl and Uninitialize need to be called in this order:
 558    *
 559    *     drv->PowerControl (ARM_POWER_OFF);     // Terminate any pending transfers, reset IRQ/DMA, power off peripheral
 560    *     drv->Uninitialize (...);               // Release I/O pins
 561    *
 562    * The functions PowerControl and Uninitialize always execute and can be used
 563    * to put the peripheral into a Safe State, for example after any data
 564    * transmission errors. To restart the peripheral in an error condition,
 565    * you should first execute the Stop Sequence and then the Start Sequence.
 566    *
 567    * @param state
 568    *          \ref ARM_POWER_STATE. The target power-state for the storage controller.
 569    *          The parameter state can have the following values:
 570    *              - ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts
 571    *                                 (NVIC) and optionally DMA. Can be called multiple times. If the peripheral
 572    *                                 is already in this mode, then the function performs no operation and returns
 573    *                                 with ARM_DRIVER_OK.
 574    *              - ARM_POWER_LOW : may use power saving. Returns ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
 575    *              - ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
 576    *
 577    * @note This API may execute asynchronously if
 578    *     ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 579    *     execution is optional even if 'asynchronous_ops' is set.
 580    *
 581    * @return If asynchronous activity is launched, an invocation returns
 582    *     ARM_DRIVER_OK, and the caller can expect to receive a callback in the
 583    *     future with a status value of ARM_DRIVER_OK or an error-code. In the
 584    *     case of synchronous execution, control returns after completion with a
 585    *     value of 1. Return values less than ARM_DRIVER_OK (0) signify errors.
 586    */
 587   int32_t (*PowerControl)(ARM_POWER_STATE state);
 588
 589   /**
 590    * \brief read the contents of a given address range from the storage device.
 591    *
 592    * \details Read the contents of a range of storage memory into a buffer
 593    *   supplied by the caller. The buffer is owned by the caller and should
 594    *   remain accessible for the lifetime of this command.
 595    *
 596    * @param  [in] addr
 597    *                This specifies the address from where to read data.
 598    *
 599    * @param [out] data
 600    *                The destination of the read operation. The buffer
 601    *                is owned by the caller and should remain accessible for the
 602    *                lifetime of this command.
 603    *
 604    * @param  [in] size
 605    *                The number of bytes requested to read. The data buffer
 606    *                should be at least as large as this size.
 607    *
 608    * @note This API may execute asynchronously if
 609    *     ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 610    *     execution is optional even if 'asynchronous_ops' is set.
 611    *
 612    * @return If asynchronous activity is launched, an invocation returns
 613    *     ARM_DRIVER_OK, and the caller can expect to receive a callback in the
 614    *     future with the number of successfully transferred bytes passed in as
 615    *     the 'status' parameter. In the case of synchronous execution, control
 616    *     returns after completion with a positive transfer-count. Return values
 617    *     less than ARM_DRIVER_OK (0) signify errors.
 618    */
 619   int32_t (*ReadData)(uint64_t addr, void *data, uint32_t size);
 620
 621   /**
 622    * \brief program (write into) the contents of a given address range of the storage device.
 623    *
 624    * \details Write the contents of a given memory buffer into a range of
 625    *   storage memory. In the case of flash memory, the destination range in
 626    *   storage memory typically has its contents in an erased state from a
 627    *   preceding erase operation. The source memory buffer is owned by the
 628    *   caller and should remain accessible for the lifetime of this command.
 629    *
 630    * @param [in] addr
 631    *               This is the start address of the range to be written into. It
 632    *               needs to be aligned to the device's \em program_unit
 633    *               specified in \ref ARM_STORAGE_INFO.
 634    *
 635    * @param [in] data
 636    *               The source of the write operation. The buffer is owned by the
 637    *               caller and should remain accessible for the lifetime of this
 638    *               command.
 639    *
 640    * @param [in] size
 641    *               The number of bytes requested to be written. The buffer
 642    *               should be at least as large as this size. \note 'size' should
 643    *               be a multiple of the device's 'program_unit' (see \ref
 644    *               ARM_STORAGE_INFO).
 645    *
 646    * @note It is best for the middleware to write in units of
 647    *     'optimal_program_unit' (\ref ARM_STORAGE_INFO) of the device.
 648    *
 649    * @note This API may execute asynchronously if
 650    *     ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 651    *     execution is optional even if 'asynchronous_ops' is set.
 652    *
 653    * @return If asynchronous activity is launched, an invocation returns
 654    *     ARM_DRIVER_OK, and the caller can expect to receive a callback in the
 655    *     future with the number of successfully transferred bytes passed in as
 656    *     the 'status' parameter. In the case of synchronous execution, control
 657    *     returns after completion with a positive transfer-count. Return values
 658    *     less than ARM_DRIVER_OK (0) signify errors.
 659    */
 660   int32_t (*ProgramData)(uint64_t addr, const void *data, uint32_t size);
 661
 662   /**
 663    * @brief Erase Storage range.
 664    *
 665    * @details This function erases a range of storage specified by [addr, addr +
 666    *     size). Both 'addr' and 'addr + size' should align with the
 667    *     'erase_unit'(s) of the respective owning storage block(s) (see \ref
 668    *     ARM_STORAGE_BLOCK and \ref ARM_STORAGE_BLOCK_ATTRIBUTES). The range to
 669    *     be erased will have its contents returned to the un-programmed state--
 670    *     i.e. to 'erased_value' (see \ref ARM_STORAGE_BLOCK_ATTRIBUTES), which
 671    *     is usually 1 to indicate the pattern of all ones: 0xFF.
 672    *
 673    * @param [in] addr
 674    *               This is the start-address of the range to be erased. It must
 675    *               start at an 'erase_unit' boundary of the underlying block.
 676    *
 677    * @param [in] size
 678    *               Size (in bytes) of the range to be erased. 'addr + size'
 679    *               must be aligned with the 'erase_unit' of the underlying
 680    *               block.
 681    *
 682    * @note This API may execute asynchronously if
 683    *     ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 684    *     execution is optional even if 'asynchronous_ops' is set.
 685    *
 686    * @return
 687    *   If the range to be erased doesn't align with the erase_units of the
 688    *   respective start and end blocks, ARM_DRIVER_ERROR_PARAMETER is returned.
 689    *   If any part of the range is protected, ARM_STORAGE_ERROR_PROTECTED is
 690    *   returned. If any part of the range is not erasable,
 691    *   ARM_STORAGE_ERROR_NOT_ERASABLE is returned. All such sanity-check
 692    *   failures result in the error code being returned synchronously and the
 693    *   storage bytes within the range remain unaffected.
 694    *   Otherwise the function executes in the following ways:
 695    *     If asynchronous activity is launched, an invocation returns
 696    *     ARM_DRIVER_OK, and the caller can expect to receive a callback in the
 697    *     future with the number of successfully erased bytes passed in as
 698    *     the 'status' parameter. In the case of synchronous execution, control
 699    *     returns after completion with a positive erase-count. Return values
 700    *     less than ARM_DRIVER_OK (0) signify errors.
 701    *
 702    * @note Erase() may return a smaller (positive) value than the size of the
 703    *     requested range. The returned value indicates the actual number of bytes
 704    *     erased. It is the caller's responsibility to follow up with an appropriate
 705    *     request to complete the operation.
 706    *
 707    * @note in the case of a failed erase (except when
 708    *     ARM_DRIVER_ERROR_PARAMETER, ARM_STORAGE_ERROR_PROTECTED, or
 709    *     ARM_STORAGE_ERROR_NOT_ERASABLE is returned synchronously), the
 710    *     requested range should be assumed to be in an unknown state. The
 711    *     previous contents may not be retained.
 712    */
 713   int32_t (*Erase)(uint64_t addr, uint32_t size);
 714
 715   /**
 716    * @brief Erase complete storage. Optional function for faster erase of the complete device.
 717    *
 718    * This optional function erases the complete device. If the device does not
 719    *    support global erase then the function returns the error value \ref
 720    *    ARM_DRIVER_ERROR_UNSUPPORTED. The data field \em 'erase_all' =
 721    *    \token{1} of the structure \ref ARM_STORAGE_CAPABILITIES encodes that
 722    *    \ref ARM_STORAGE_EraseAll is supported.
 723    *
 724    * @note This API may execute asynchronously if
 725    *     ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 726    *     execution is optional even if 'asynchronous_ops' is set.
 727    *
 728    * @return
 729    *   If any part of the storage range is protected,
 730    *   ARM_STORAGE_ERROR_PROTECTED is returned. If any part of the storage
 731    *   range is not erasable, ARM_STORAGE_ERROR_NOT_ERASABLE is returned. All
 732    *   such sanity-check failures result in the error code being returned
 733    *   synchronously and the storage bytes within the range remain unaffected.
 734    *   Otherwise the function executes in the following ways:
 735    *     If asynchronous activity is launched, an invocation returns
 736    *     ARM_DRIVER_OK, and the caller can expect to receive a callback in the
 737    *     future with ARM_DRIVER_OK passed in as the 'status' parameter. In the
 738    *     case of synchronous execution, control returns after completion with a
 739    *     value of 1. Return values less than ARM_DRIVER_OK (0) signify errors.
 740    */
 741   int32_t (*EraseAll)(void);
 742
 743   /**
 744    * @brief Get the status of the current (or previous) command executed by the
 745    *     storage controller; stored in the structure \ref ARM_STORAGE_STATUS.
 746    *
 747    * @return
 748    *          The status of the underlying controller.
 749    *
 750    * @note This API returns synchronously--it does not result in an invocation
 751    *     of a completion callback.
 752    */
 753   ARM_STORAGE_STATUS (*GetStatus)(void);
 754
 755   /**
 756    * @brief Get information about the Storage device; stored in the structure \ref ARM_STORAGE_INFO.
 757    *
 758    * @param [out] info
 759    *                A caller-supplied buffer capable of being filled in with an
 760    *                \ref ARM_STORAGE_INFO.
 761    *
 762    * @return ARM_DRIVER_OK if a ARM_STORAGE_INFO structure containing top level
 763    *         metadata about the storage controller is filled into the supplied
 764    *         buffer, else an appropriate error value.
 765    *
 766    * @note It is the caller's responsibility to ensure that the buffer passed in
 767    *         is able to be initialized with a \ref ARM_STORAGE_INFO.
 768    *
 769    * @note This API returns synchronously--it does not result in an invocation
 770    *     of a completion callback.
 771    */
 772   int32_t (*GetInfo)(ARM_STORAGE_INFO *info);
 773
 774   /**
 775    * \brief For memory-mapped storage, resolve an address relative to
 776    *     the storage controller into a memory address.
 777    *
 778    * @param addr
 779    *          This is the address for which we want a resolution to the
 780    *          processor's physical address space. It is an offset from the
 781    *          start of the storage map maintained by the owning storage
 782    *          controller.
 783    *
 784    * @return
 785    *          The resolved address in the processor's address space; else
 786    *          ARM_STORAGE_INVALID_ADDRESS, if no resolution is possible.
 787    *
 788    * @note This API returns synchronously. The invocation should return quickly,
 789    *     and result in a resolved address.
 790    */
 791   uint32_t (*ResolveAddress)(uint64_t addr);
 792
 793   /**
 794    * @brief Advance to the successor of the current block (iterator), or fetch
 795    *     the first block (if 'prev_block' is passed in as NULL).
 796    *
 797    * @details This helper function fetches (an iterator to) the next block (or
 798    *     the first block if 'prev_block' is passed in as NULL). In the failure
 799    *     case, a terminating, invalid block iterator is filled into the out
 800    *     parameter: 'next_block'. In combination with \ref
 801    *     ARM_STORAGE_VALID_BLOCK(), it can be used to iterate over the sequence
 802    *     of blocks within the storage map:
 803    *
 804    * \code
 805    *   ARM_STORAGE_BLOCK block;
 806    *   for (drv->GetNextBlock(NULL, &block); ARM_STORAGE_VALID_BLOCK(&block); drv->GetNextBlock(&block, &block)) {
 807    *       // make use of block
 808    *   }
 809    * \endcode
 810    *
 811    * @param[in]  prev_block
 812    *               An existing block (iterator) within the same storage
 813    *               controller. The memory buffer holding this block is owned
 814    *               by the caller. This pointer may be NULL; if so, the
 815    *               invocation fills in the first block into the out parameter:
 816    *               'next_block'.
 817    *
 818    * @param[out] next_block
 819    *               A caller-owned buffer large enough to be filled in with
 820    *               the following ARM_STORAGE_BLOCK. It is legal to provide the
 821    *               same buffer using 'next_block' as was passed in with 'prev_block'. It
 822    *               is also legal to pass a NULL into this parameter if the
 823    *               caller isn't interested in populating a buffer with the next
 824    *               block--i.e. if the caller only wishes to establish the
 825    *               presence of a next block.
 826    *
 827    * @return ARM_DRIVER_OK if a valid next block is found (or first block, if
 828    *     prev_block is passed as NULL); upon successful operation, the contents
 829    *     of the next (or first) block are filled into the buffer pointed to by
 830    *     the parameter 'next_block' and ARM_STORAGE_VALID_BLOCK(next_block) is
 831    *     guaranteed to be true. Upon reaching the end of the sequence of blocks
 832    *     (iterators), or in case the driver is unable to fetch information about
 833    *     the next (or first) block, an error (negative) value is returned and an
 834    *     invalid StorageBlock is populated into the supplied buffer. If
 835    *     prev_block is NULL, the first block is returned.
 836    *
 837    * @note This API returns synchronously--it does not result in an invocation
 838    *     of a completion callback.
 839    */
 840    int32_t (*GetNextBlock)(const ARM_STORAGE_BLOCK* prev_block, ARM_STORAGE_BLOCK *next_block);
 841
 842   /**
 843    * @brief Find the storage block (iterator) encompassing a given storage address.
 844    *
 845    * @param[in]  addr
 846    *               Storage address in bytes.
 847    *
 848    * @param[out] block
 849    *               A caller-owned buffer large enough to be filled in with the
 850    *               ARM_STORAGE_BLOCK encapsulating the given address. This value
 851    *               can also be passed in as NULL if the caller isn't interested
 852    *               in populating a buffer with the block--if the caller only
 853    *               wishes to establish the presence of a containing storage
 854    *               block.
 855    *
 856    * @return ARM_DRIVER_OK if a containing storage-block is found. In this case,
 857    *     if block is non-NULL, the buffer pointed to by it is populated with
 858    *     the contents of the storage block--i.e. if block is valid and a block is
 859    *     found, ARM_STORAGE_VALID_BLOCK(block) would return true following this
 860    *     call. If there is no storage block containing the given offset, or in
 861    *     case the driver is unable to resolve an address to a storage-block, an
 862    *     error (negative) value is returned and an invalid StorageBlock is
 863    *     populated into the supplied buffer.
 864    *
 865    * @note This API returns synchronously--it does not result in an invocation
 866    *     of a completion callback.
 867    */
 868   int32_t (*GetBlock)(uint64_t addr, ARM_STORAGE_BLOCK *block);
 869 } const ARM_DRIVER_STORAGE;
 870
 871 #ifdef __cplusplus
 872 }
 873 #endif // __cplusplus
 874
 875 #endif /* __DRIVER_STORAGE_H */