begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_Storage.c

   1 /**
   2 \defgroup storage_interface_gr Storage Interface
   3 \brief    Driver API for Storage Device Interface (%Driver_Storage.h)
   4 \details
   5 This is an abstraction for a storage controller. It offers an interface to
   6 access an address space of storage locations, comprising APIs for
   7 initialization, erase, access, program, and status-fetch operations. It also
   8 offers APIs to iterate over the available Storage Blocks (\ref
   9 ARM_STORAGE_BLOCK), allowing the discovery of block attributes such as
  10 write/erase granularities. Using the Storage abstraction, it becomes possible to
  11 write generic algorithms, such as block copy, to operate on any conforming
  12 storage device.
  13
  14 \note The storage abstraction layer is not responsible for storage management.
  15 Algorithms such as block-allocation, wear-leveling, erase-before-write and other
  16 storage-management policies are the responsibility of modules external to the
  17 storage abstraction layer. In essence, the storage interface is the lowest
  18 abstraction upon which block management policies can be implemented.
  19
  20 Here's a picture to help locate the storage abstraction in the software stack.
  21 The part below the box labeled 'Storage abstraction layer' is implemented by a
  22 storage driver.
  23
  24 \image html storage_sw_stack.png
  25
  26 <b>Storage API</b>
  27
  28 The following header files define the Application Programming Interface (API) for the Flash interface:
  29   - \b %Driver_Storage.h : Driver API for Storage Device Interface
  30
  31
  32 <b>Driver Functions</b>
  33
  34 The driver functions are published in the access struct as explained in \ref StorageDriverFunctions
  35   - \ref ARM_DRIVER_STORAGE : access struct for Storage driver functions
  36
  37 A sample use for the driver can be found at: \ref SampleUseOfStorageDriver
  38 *******************************************************************************************************************/
  39
  40
  41
  42 /**
  43 \addtogroup storage_interface_gr
  44 @{
  45 *******************************************************************************************************************/
  46
  47 /**
  48 \struct     ARM_STORAGE_BLOCK_ATTRIBUTES
  49 <b>Contained in:</b>
  50   - \ref ARM_STORAGE_BLOCK
  51 *******************************************************************************************************************/
  52
  53 /**
  54 \struct     ARM_STORAGE_BLOCK
  55 \details Storage blocks combine to make up the address map of a storage controller.
  56 *******************************************************************************************************************/
  57
  58 /**
  59 \struct     ARM_STORAGE_INFO
  60 \details
  61 It describes the characteristics of a Storage device. This includes total
  62 storage, programming size, a default value for erased memory etc. This
  63 information can be obtained from the Storage device datasheet and is used by the
  64 middleware in order to properly interact with the Storage device.
  65
  66 Total available storage (in bytes) is contained in \em total_storage. Minimum
  67 programming size (in bytes) is described by \em program_unit (applicable only if
  68 the \em programmable attribute is set for a block). It defines the granularity
  69 for programming data. The offset of the start of a program-range and the size
  70 should also be aligned with \em program_unit.
  71 \note: setting \em program_unit to 0 has the effect of disabling the size and
  72 alignment restrictions (setting it to 1 also has the same effect).
  73
  74 Optimal programming page-size (in bytes) is specified by \em
  75 optimal_program_unit. Some storage controllers have internal buffers into which
  76 to receive data. Writing in chunks of \em optimal_program_unit would achieve
  77 maximum programming speed. Like with \em program_unit, this is applicable only
  78 if the \em programmable attribute is set for the underlying storage block(s).
  79
  80 \em program_cycles is a measure of endurance for reprogramming.
  81 A value of \em ARM_STORAGE_PROGRAM_CYCLES_INFINITE may be used to signify
  82 infinite or unknown endurance.
  83
  84 Contents of erased memory is specified by the \em erased_value. It is usually
  85 \token{1} to indicate erased bytes with state 0xFF.
  86
  87 \em memory_mapped can be set to \token{1} to indicate that the storage device
  88 has a mapping onto the processor's memory address space.
  89 \note: For a memory-mapped block which isn't erasable but is programmable,
  90 writes should be possible directly to the memory-mapped storage without going
  91 through the \ref ARM_Storage_ProgramData operation.
  92
  93 The field \em programmability holds a value to indicate storage programmability.
  94 Similarly, \em retention_level holds a for encoding data-retention levels for
  95 all storage blocks.
  96
  97 \note
  98 These fields serve a different purpose than the ones contained in
  99 \ref ARM_STORAGE_CAPABILITIES, which is another structure containing device-level
 100 metadata. ARM_STORAGE_CAPABILITIES describes the API capabilities, whereas
 101 ARM_STORAGE_INFO describes the device. Furthermore ARM_STORAGE_CAPABILITIES fits
 102 within a single word, and is designed to be passed around by value;
 103 ARM_STORAGE_INFO, on the other hand, contains metadata which doesn't fit into a
 104 single word and requires the use of pointers to be moved around.
 105
 106 <b>Returned by:</b>
 107   - \ref ARM_Storage_GetInfo
 108 *******************************************************************************************************************/
 109
 110 /**
 111 \struct ARM_DRIVER_STORAGE
 112 \details
 113 This is the set of operations constituting the Storage driver. Their
 114 implementation is platform-specific, and needs to be supplied by the porting
 115 effort. The functions of the Storage driver are accessed by function pointers
 116 exposed by this structure. Refer to \ref StorageDriverFunctions for overview
 117 information.
 118
 119 Each instance of a Storage interface provides such an access structure.
 120 The instance is identified by a postfix number in the symbol name of the access structure, for example:
 121  - \b Driver_Storage0 is the name of the access struct of the first instance (no. 0).
 122  - \b Driver_Storage1 is the name of the access struct of the second instance (no. 1).
 123
 124 A middleware configuration setting allows connecting the middleware to a specific driver instance \b %Driver_Flash<i>n</i>.
 125 The default is \token{0}, which connects a middleware to the first instance of a driver.
 126 *******************************************************************************************************************/
 127
 128 /**
 129 \defgroup StorageDriverFunctions Use of Storage APIs
 130
 131 Function pointers within \ref ARM_DRIVER_STORAGE form the set of operations
 132 constituting the Storage driver. Their implementation is platform-specific, and
 133 needs to be supplied by the porting effort.
 134
 135 Some of these APIs will always operate synchronously:
 136 - \ref ARM_Storage_GetVersion
 137 - \ref ARM_Storage_GetCapabilities
 138 - \ref ARM_Storage_GetStatus
 139 - \ref ARM_Storage_GetInfo
 140 - \ref ARM_Storage_ResolveAddress
 141 - \ref ARM_Storage_GetNextBlock and
 142 - \ref ARM_Storage_GetBlock.
 143
 144 This means that control returns to the caller with a relevant status code only after the completion of the operation (or
 145 the discovery of a failure condition).
 146
 147 The remainder of the APIs:
 148 - \ref ARM_Storage_Initialize
 149 - \ref ARM_Storage_Uninitialize
 150 - \ref ARM_Storage_PowerControl
 151 - \ref ARM_Storage_ReadData
 152 - \ref ARM_Storage_ProgramData
 153 - \ref ARM_Storage_Erase and
 154 - \ref ARM_Storage_EraseAll
 155
 156 can function asynchronously if the underlying controller supports it; that is if ARM_STORAGE_CAPABILITIES::asynchronous_ops
 157 is set. In the case of asynchronous operation, the invocation returns early (with ARM_DRIVER_OK) and results in a completion
 158 callback later. If ARM_STORAGE_CAPABILITIES::asynchronous_ops is not set, then all such APIs execute synchronously, and
 159 control returns to the caller with a status code only after the completion of the operation (or the discovery of a failure
 160 condition).
 161
 162 If ARM_STORAGE_CAPABILITIES::asynchronous_ops is set, a storage driver may
 163 still choose to execute asynchronous operations in a synchronous manner. If
 164 so, the driver returns a positive value to indicate successful synchronous
 165 completion (or an error code in case of failure) and no further invocation of
 166 completion callback should be expected. The expected return value for
 167 synchronous completion of such asynchronous operations varies depending on
 168 the operation. For operations involving data access, it often equals the
 169 amount of data transferred or affected. For non data-transfer operations,
 170 such as EraseAll or Initialize, it is usually 1.
 171
 172 Here's a code snippet to suggest how asynchronous APIs might be used by
 173 callers to handle both synchronous and asynchronous execution by the
 174 underlying storage driver:
 175 \code
 176     ASSERT(ARM_DRIVER_OK == 0); // this is a precondition; it doesn't need to be put in code
 177
 178     int32_t returnValue = drv->asynchronousAPI(...);
 179
 180     if (returnValue < ARM_DRIVER_OK) {
 181         // handle error.
 182
 183     } else if (returnValue == ARM_DRIVER_OK) {
 184         ASSERT(drv->GetCapabilities().asynchronous_ops == 1);
 185         // handle early return from asynchronous execution; remainder of the work is done in the callback handler.
 186
 187     } else {
 188         ASSERT(returnValue == EXPECTED_RETURN_VALUE_FOR_SYNCHRONOUS_COMPLETION);
 189         // handle synchronous completion.
 190     }
 191 \endcode
 192
 193 This example is mixing synchronous and asynchronous APIs: \ref SampleUseOfStorageDriver
 194 *******************************************************************************************************************/
 195
 196 /**
 197 \struct     ARM_STORAGE_CAPABILITIES
 198 \details
 199 A Storage driver can be implemented with different capabilities. The data fields
 200 of this struct encode the API capabilities implemented by this driver.
 201
 202 The element \em asynchronous_ops indicates if APIs like initialize, read, erase,
 203 program, etc. can operate in asynchronous mode. Having this bit set to 1 means
 204 that the driver is capable of launching asynchronous operations; command
 205 completion for asynchronous operations is signaled by the invocation of a
 206 completion callback. If set to 1, drivers may still complete asynchronous
 207 operations synchronously as necessary--in which case they return a positive
 208 error code to indicate synchronous completion.  If \em asynchronous_ops is not
 209 set, then all such APIs execute synchronously, and control returns to the caller
 210 with a status code only after the completion of the operation (or the discovery
 211 of a failure condition).
 212
 213 The element \em erase_all specifies that the \ref ARM_Storage_EraseAll function
 214 is supported. Typically full chip erase is much faster than erasing the whole
 215 device using \em ARM_Storage_Erase.
 216
 217 <b>Returned by:</b>
 218   - \ref ARM_Storage_GetCapabilities
 219
 220 \note
 221 This data structure is designed to fit within a single word so that it can be
 222 fetched cheaply using a call to driver->GetCapabilities().
 223 *******************************************************************************************************************/
 224
 225 /**
 226 \struct     ARM_STORAGE_STATUS
 227 \details
 228 Structure with information about the status of the Storage device.
 229
 230 The flag \em busy indicates that the driver is busy executing read/program/erase operation.
 231
 232 The flag \em 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.
 233
 234 <b>Returned by:</b>
 235   - \ref ARM_Storage_GetStatus
 236 *****************************************************************************************************************/
 237
 238 /**
 239 \typedef        ARM_STORAGE_OPERATION
 240 \details
 241 Command opcodes for the Storage interface. Completion callbacks use these codes
 242 to refer to completing commands. Refer to \ref ARM_Storage_Callback_t.
 243 *****************************************************************************************************************/
 244
 245 /**
 246 \typedef    ARM_Storage_Callback_t
 247 \details
 248 Provides the typedef for the callback function \ref ARM_Storage_Callback_t.
 249
 250 \param [in] status
 251               A code to indicate the status of the completed operation. For data
 252               transfer operations, the status field is overloaded in case of
 253               success to return the count of bytes successfully transferred; this
 254               can be done safely because error codes are negative values.
 255
 256 \param [in] operation
 257               The command op-code. This value isn't essential, but it is expected that
 258               this information could be a quick and useful filter for the handler.
 259
 260 <b>Parameter for:</b>
 261   - \ref ARM_Storage_Initialize
 262 *******************************************************************************************************************/
 263
 264
 265 //
 266 // Functions
 267 //
 268
 269 ARM_DRIVER_VERSION ARM_Storage_GetVersion (void)  {
 270   return { 0, 0 };
 271 }
 272 /**
 273 \fn ARM_DRIVER_VERSION ARM_Storage_GetVersion (void)
 274 \details
 275 The function \b ARM_Storage_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION.
 276  - API version is the version of the CMSIS-Driver specification used to implement this driver.
 277  - Driver version is source code version of the actual driver implementation.
 278
 279 Example:
 280 \code
 281 extern ARM_DRIVER_STORAGE *drv_info;
 282
 283 void read_version (void)  {
 284   ARM_DRIVER_VERSION  version;
 285
 286   version = drv_info->GetVersion ();
 287   if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 288     // error handling
 289     return;
 290   }
 291 }
 292 \endcode
 293
 294 \note HAPI returns synchronously--it does not result in an invocation
 295    of a completion callback.
 296
 297 \note The function GetVersion() can be called any time to obtain the
 298    required information from the driver (even before initialization). It
 299    always returns the same information.
 300 *******************************************************************************************************************/
 301
 302 ARM_STOR_CAPABILITIES ARM_Storage_GetCapabilities (void)  {
 303   return { 0 };
 304 }
 305 /**
 306 \fn ARM_STORAGE_CAPABILITIES ARM_Storage_GetCapabilities (void)
 307
 308 \details
 309 The function \b ARM_Storage_GetCapabilities returns information about
 310 capabilities in this driver implementation. The data fields of the struct
 311 ARM_STORAGE_CAPABILITIES encode various capabilities, for example if the device
 312 is able to execute operations asynchronously.
 313
 314 Example:
 315 \code
 316 extern ARM_DRIVER_STORAGE *drv_info;
 317
 318 void read_capabilities (void)  {
 319   ARM_STORAGE_CAPABILITIES drv_capabilities;
 320
 321   drv_capabilities = drv_info->GetCapabilities ();
 322   // interrogate capabilities
 323
 324 }
 325 \endcode
 326
 327 \note This API returns synchronously--it does not result in an invocation
 328    of a completion callback.
 329
 330 \note The function GetCapabilities() can be called any time to obtain the
 331    required information from the driver (even before initialization). It
 332    always returns the same information.
 333 *******************************************************************************************************************/
 334
 335 int32_t ARM_Storage_Initialize (ARM_Storage_Callback_t callback)  {
 336   return 0;
 337 }
 338 /**
 339 \fn int32_t ARM_Storage_Initialize (ARM_Storage_Callback_t callback)
 340 \details
 341 The function \b ARM_Storage_Initialize is called when the middleware component starts
 342 operation. In addition to bringing the controller to a ready state,
 343 Initialize() receives a callback handler to be invoked upon completion of
 344 asynchronous operations.
 345
 346 ARM_Storage_Initialize() needs to be called explicitly before
 347 powering the peripheral using ARM_Storage_PowerControl(), and before initiating other
 348 accesses to the storage controller.
 349
 350 The function performs the following operations:
 351  - Initializes the resources needed for the Storage interface.
 352  - Registers the \ref ARM_Storage_Callback_t callback function.
 353
 354 To start working with a peripheral the functions ARM_Storage_Initialize and ARM_Storage_PowerControl() need to be called in this order:
 355 \code
 356    drv->Initialize (...);              // Allocate I/O pins
 357    drv->PowerControl (ARM_POWER_FULL); // Power up peripheral, setup IRQ/DMA
 358 \endcode
 359
 360 - ARM_Storage_Initialize() typically allocates the I/O resources (pins) for the
 361  peripheral. The function can be called multiple times; if the I/O resources
 362  are already initialized it performs no operation and just returns with
 363  ARM_DRIVER_OK.
 364
 365 - ARM_Storage_PowerControl (ARM_POWER_FULL) sets the peripheral registers including
 366  interrupt (NVIC) and optionally DMA. The function can be called multiple
 367  times; if the registers are already set it performs no operation and just
 368  returns with ARM_DRIVER_OK.
 369
 370 To stop working with a peripheral the functions ARM_Storage_PowerControl() and ARM_Storage_Uninitialize() need to be called in this order:
 371 \code
 372    drv->PowerControl (ARM_POWER_OFF); // Terminate any pending transfers, reset IRQ/DMA, power off peripheral
 373    drv->Uninitialize (...);           // Release I/O pins
 374 \endcode
 375
 376 The functions ARM_Storage_PowerControl() and ARM_Storage_Uninitialize() always execute and can be used
 377 to put the peripheral into a Safe State, for example after any data
 378 transmission errors. To restart the peripheral in an error condition,
 379 you should first execute the Stop Sequence and then the Start Sequence.
 380
 381 \note This API may execute asynchronously if
 382    ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 383    execution is optional even if 'asynchronous_ops' is set.
 384 *******************************************************************************************************************/
 385
 386 int32_t ARM_Storage_Uninitialize (void)  {
 387   return 0;
 388 }
 389 /**
 390 \fn int32_t ARM_Storage_Uninitialize (void)
 391 \details
 392 It is called when the middleware component stops operation, and wishes to
 393 release the software resources used by the interface.
 394
 395 \note This API may execute asynchronously if
 396    ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 397    execution is optional even if 'asynchronous_ops' is set.
 398 *******************************************************************************************************************/
 399
 400 int32_t ARM_Storage_PowerControl (ARM_POWER_STATE state)  {
 401   return 0;
 402 }
 403 /**
 404 \fn int32_t ARM_Storage_PowerControl (ARM_POWER_STATE state)
 405 \details
 406 The function \b ARM_Storage_PowerControl operates the power modes of the Storage interface.
 407
 408 To start working with a peripheral the functions Initialize and PowerControl need to be called in this order:
 409 \code
 410    drv->Initialize (...);                 // Allocate I/O pins
 411    drv->PowerControl (ARM_POWER_FULL);    // Power up peripheral, setup IRQ/DMA
 412 \endcode
 413
 414 - ARM_Storage_Initialize() typically allocates the I/O resources (pins) for the
 415  peripheral. The function can be called multiple times; if the I/O resources
 416  are already initialized it performs no operation and just returns with
 417  ARM_DRIVER_OK.
 418
 419 - PowerControl (ARM_POWER_FULL) sets the peripheral registers including
 420  interrupt (NVIC) and optionally DMA. The function can be called multiple
 421  times; if the registers are already set it performs no operation and just
 422  returns with ARM_DRIVER_OK.
 423
 424 To stop working with a peripheral the functions PowerControl and Uninitialize need to be called in this order:
 425 \code
 426    drv->PowerControl (ARM_POWER_OFF);     // Terminate any pending transfers, reset IRQ/DMA, power off peripheral
 427    drv->Uninitialize (...);               // Release I/O pins
 428 \endcode
 429
 430 The functions ARM_Storage_PowerControl and ARM_Storage_Uninitialize always execute and can be used
 431 to put the peripheral into a Safe State, for example after any data
 432 transmission errors. To restart the peripheral in an error condition,
 433 you should first execute the Stop Sequence and then the Start Sequence.
 434
 435 The parameter \em state can have the following values:
 436   - \ref ARM_POWER_FULL : set-up the Storage device for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times.
 437                           If the device is already in this mode, then the function performs no operation and returns with \ref ARM_DRIVER_OK.
 438   - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
 439   - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
 440
 441 \note This API may execute asynchronously if
 442    ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 443    execution is optional even if 'asynchronous_ops' is set.
 444 *******************************************************************************************************************/
 445
 446 int32_t ARM_Storage_ReadData (uint64_t addr, void *data, uint32_t size)  {
 447   return 0;
 448 }
 449 /**
 450 \fn int32_t ARM_Storage_ReadData (uint64_t addr, void *data, uint32_t size)
 451 \details
 452 Read the contents of a range of storage memory into a buffer
 453 supplied by the caller. The buffer is owned by the caller and should
 454 remain accessible for the lifetime of this command.
 455
 456 \note This API may execute asynchronously if
 457    ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 458    execution is optional even if 'asynchronous_ops' is set.
 459 *******************************************************************************************************************/
 460
 461 int32_t ARM_Storage_ProgramData (uint64_t addr, const void *data, uint32_t size)  {
 462   return 0;
 463 }
 464 /**
 465 \fn int32_t ARM_Storage_ProgramData (uint64_t addr, const void *data, uint32_t size)
 466 \details
 467 Write the contents of a given memory buffer into a range of
 468 storage memory. In the case of flash memory, the destination range in
 469 storage memory typically has its contents in an erased state from a
 470 preceding erase operation. The source memory buffer is owned by the
 471 caller and should remain accessible for the lifetime of this command.
 472
 473 \note It is best for the middleware to write in units of
 474    'optimal_program_unit' (\ref ARM_STORAGE_INFO) of the device.
 475
 476 \note This API may execute asynchronously if
 477    ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 478    execution is optional even if 'asynchronous_ops' is set.
 479 *******************************************************************************************************************/
 480
 481 int32_t ARM_Storage_Erase (uint64_t addr, uint32_t size)  {
 482   return 0;
 483 }
 484 /**
 485 \fn int32_t ARM_Storage_Erase (uint64_t addr, uint32_t size)
 486
 487 \details
 488 This function erases a range of storage specified by [addr, addr +
 489 size). Both 'addr' and 'addr + size' should align with the
 490 'erase_unit'(s) of the respective owning storage block(s) (see \ref
 491 ARM_STORAGE_BLOCK and \ref ARM_STORAGE_BLOCK_ATTRIBUTES). The range to
 492 be erased will have its contents returned to the un-programmed state--
 493 i.e. to \ref ARM_STORAGE_INFO::erased_value, which
 494 is usually 1 to indicate the pattern of all ones: 0xFF.
 495
 496 \note This API may execute asynchronously if
 497    ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 498    execution is optional even if 'asynchronous_ops' is set.
 499
 500 \note Erase() may return a smaller (positive) value than the size of the
 501    requested range. The returned value indicates the actual number of bytes
 502    erased. It is the caller's responsibility to follow up with an appropriate
 503    request to complete the operation.
 504
 505 \note in the case of a failed erase (except when
 506    ARM_DRIVER_ERROR_PARAMETER, ARM_STORAGE_ERROR_PROTECTED, or
 507    ARM_STORAGE_ERROR_NOT_ERASABLE is returned synchronously), the
 508    requested range should be assumed to be in an unknown state. The
 509    previous contents may not be retained.
 510 *******************************************************************************************************************/
 511
 512 int32_t ARM_Storage_EraseAll (void)  {
 513   return 0;
 514 }
 515 /**
 516 \fn int32_t ARM_Storage_EraseAll (void)
 517 \details
 518 This optional function erases the complete device. If the device does not
 519 support global erase then the function returns the error value \ref
 520 ARM_DRIVER_ERROR_UNSUPPORTED. The data field \em 'erase_all' =
 521 \token{1} of the structure \ref ARM_STORAGE_CAPABILITIES encodes that
 522 \ref ARM_Storage_EraseAll is supported.
 523
 524 \note This API may execute asynchronously if
 525    ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous
 526    execution is optional even if 'asynchronous_ops' is set.
 527 *******************************************************************************************************************/
 528
 529 ARM_Storage_STATUS ARM_Storage_GetStatus (void)  {
 530   return 0;
 531 }
 532 /**
 533 \fn ARM_STORAGE_STATUS ARM_Storage_GetStatus (void)
 534 \details
 535 Get the status of the current (or previous) command executed by the
 536 storage controller; stored in the structure \ref ARM_STORAGE_STATUS.
 537
 538 \note This API returns synchronously--it does not result in an invocation
 539    of a completion callback.
 540 *******************************************************************************************************************/
 541
 542 int32_t ARM_Storage_GetInfo (ARM_STORAGE_INFO *info)  {
 543   return 0;
 544 }
 545 /**
 546 \fn int32_t ARM_Storage_GetInfo (ARM_STORAGE_INFO *info)
 547 \details
 548 Get information about the Storage device; stored in the structure \ref ARM_STORAGE_INFO.
 549
 550 \note It is the caller's responsibility to ensure that the buffer passed in
 551        is able to be initialized with a \ref ARM_STORAGE_INFO.
 552
 553 \note This API returns synchronously--it does not result in an invocation
 554    of a completion callback.
 555 *******************************************************************************************************************/
 556
 557 uint32_t ARM_Storage_ResolveAddress(uint64_t addr) {
 558   return 0;
 559 }
 560 /**
 561 \fn uint32_t ARM_Storage_ResolveAddress(uint64_t addr)
 562 \details
 563 Only applicable to devices with memory-mapped storage.
 564
 565 \note This API returns synchronously. The invocation should return quickly,
 566    and result in a resolved address.
 567 *******************************************************************************************************************/
 568
 569 int32_t ARM_Storage_GetNextBlock(const ARM_STORAGE_BLOCK* prev_block, ARM_STORAGE_BLOCK *next_block) {
 570   return 0;
 571 }
 572 /**
 573 \fn int32_t ARM_Storage_GetNextBlock(const ARM_STORAGE_BLOCK* prev_block, ARM_STORAGE_BLOCK *next_block);
 574 \details
 575 This helper function fetches (an iterator to) the next block (or
 576 the first block if 'prev_block' is passed in as NULL). In the failure
 577 case, a terminating, invalid block iterator is filled into the out
 578 parameter: 'next_block'. In combination with \ref
 579 ARM_STORAGE_VALID_BLOCK, it can be used to iterate over the sequence
 580 of blocks within the storage map:
 581
 582 \code
 583   ARM_STORAGE_BLOCK block;
 584   for (drv->GetNextBlock(NULL, &block); ARM_STORAGE_VALID_BLOCK(&block); drv->GetNextBlock(&block, &block)) {
 585       // make use of block
 586   }
 587 \endcode
 588
 589 \note This API returns synchronously--it does not result in an invocation
 590     of a completion callback.
 591 *******************************************************************************************************************/
 592
 593 int32_t ARM_Storage_GetBlock(uint64_t addr, ARM_STORAGE_BLOCK *block) {
 594   return 0;
 595 }
 596 /**
 597 \fn int32_t ARM_Storage_GetBlock(uint64_t addr, ARM_STORAGE_BLOCK *block);
 598 \note This API returns synchronously--it does not result in an invocation
 599     of a completion callback.
 600 *******************************************************************************************************************/
 601
 602 /**
 603 @}
 604 */
 605
 606 /**
 607 \defgroup SampleUseOfStorageDriver Sample Use of Storage Driver
 608 \ingroup storage_interface_gr
 609 @{
 610 <b>Example Code:</b>
 611
 612 The following is a generic algorithm to erase
 613 and program one \ref ARM_STORAGE_BLOCK_ATTRIBUTES::erase_unit worth of storage
 614 and then read it back to be verified. It handles both synchronous and
 615 asynchronous driver implementations.
 616
 617 \code
 618 // Copyright (c) 2006-2016, Arm Limited, All Rights Reserved
 619 // SPDX-License-Identifier: Apache-2.0
 620 //
 621 // Licensed under the Apache License, Version 2.0 (the "License"); you may
 622 // not use this file except in compliance with the License.
 623 // You may obtain a copy of the License at
 624 //
 625 // https://www.apache.org/licenses/LICENSE-2.0
 626 //
 627 // Unless required by applicable law or agreed to in writing, software
 628 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 629 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 630 // See the License for the specific language governing permissions and
 631 // limitations under the License.
 632
 633 #include "Driver_Storage.h"
 634 #include <stdio.h>
 635 #include <string.h>
 636
 637 #define TEST_ASSERT(Expr)                       if (!(Expr)) { printf("%s:%u: assertion failure\n", __FUNCTION__, __LINE__); while (1) ;}
 638 #define TEST_ASSERT_EQUAL(expected, actual)     if ((expected) != (actual)) {printf("%s:%u: assertion failure\n", __FUNCTION__, __LINE__); while (1) ;}
 639 #define TEST_ASSERT_NOT_EQUAL(expected, actual) if ((expected) == (actual)) {printf("%s:%u: assertion failure\n", __FUNCTION__, __LINE__); while (1) ;}
 640
 641 // forward declarations
 642 void callbackHandler(int32_t status, ARM_STORAGE_OPERATION operation);
 643 void progressStateMachine(void);
 644
 645 static enum {
 646     NEEDS_INITIALIZATION,
 647     NEEDS_ERASE,
 648     NEEDS_PROGRAMMING,
 649     NEEDS_READ,
 650     NEEDS_VERIFICATION_FOLLOWING_READ,
 651     FINISHED
 652 } state;
 653
 654 extern ARM_DRIVER_STORAGE ARM_Driver_Storage_(0);
 655 ARM_DRIVER_STORAGE *drv = &ARM_Driver_Storage_(0);
 656
 657 static const unsigned BUFFER_SIZE = 16384;
 658 static uint8_t buffer[BUFFER_SIZE];
 659
 660 void main(int argc __unused, char** argv __unused)
 661 {
 662     state = NEEDS_INITIALIZATION;
 663
 664     progressStateMachine();
 665     while (true) {
 666         // WFE(); // optional low-power sleep
 667     }
 668 }
 669
 670 void progressStateMachine(void)
 671 {
 672     int32_t rc;
 673
 674     static ARM_STORAGE_BLOCK firstBlock;
 675     if (!ARM_STORAGE_VALID_BLOCK(&firstBlock)) {
 676         // Get the first block. This block is entered only once.
 677         rc = drv->GetNextBlock(NULL, &firstBlock); // get first block
 678         TEST_ASSERT_EQUAL(ARM_DRIVER_OK, rc);
 679     }
 680     TEST_ASSERT(ARM_STORAGE_VALID_BLOCK(&firstBlock));
 681     TEST_ASSERT(firstBlock.size > 0);
 682
 683     switch (state) {
 684         case NEEDS_INITIALIZATION:
 685             rc = drv->Initialize(callbackHandler);
 686             TEST_ASSERT(rc >= ARM_DRIVER_OK);
 687             if (rc == ARM_DRIVER_OK) {
 688                 TEST_ASSERT_EQUAL(1, drv->GetCapabilities().asynchronous_ops);
 689                 state = NEEDS_ERASE;
 690                 return; // there is pending asynchronous activity which will lead to a completion callback later.
 691             }
 692             TEST_ASSERT_EQUAL(1, rc); // synchronous completion
 693
 694             // intentional fall-through
 695
 696         case NEEDS_ERASE:
 697             TEST_ASSERT(firstBlock.attributes.erase_unit > 0);
 698             rc = drv->Erase(firstBlock.addr, firstBlock.attributes.erase_unit);
 699             TEST_ASSERT(rc >= ARM_DRIVER_OK);
 700             if (rc == ARM_DRIVER_OK) {
 701                 TEST_ASSERT_EQUAL(1, drv->GetCapabilities().asynchronous_ops);
 702                 state = NEEDS_PROGRAMMING;
 703                 return; // there is pending asynchronous activity which will lead to a completion callback later.
 704             }
 705             TEST_ASSERT_EQUAL(firstBlock.attributes.erase_unit, (uint32_t)rc); // synchronous completion
 706
 707             // intentional fall-through
 708
 709         case NEEDS_PROGRAMMING:
 710             TEST_ASSERT(BUFFER_SIZE >= firstBlock.attributes.erase_unit);
 711             #define PATTERN 0xAA
 712             memset(buffer, PATTERN, firstBlock.attributes.erase_unit);
 713             rc = drv->ProgramData(firstBlock.addr, buffer, firstBlock.attributes.erase_unit);
 714             TEST_ASSERT(rc >= ARM_DRIVER_OK);
 715             if (rc == ARM_DRIVER_OK) {
 716                 TEST_ASSERT_EQUAL(1, drv->GetCapabilities().asynchronous_ops);
 717                 state = NEEDS_READ;
 718                 return;  // there is pending asynchronous activity which will lead to a completion callback later.
 719             }
 720             TEST_ASSERT_EQUAL(firstBlock.attributes.erase_unit, (uint32_t)rc); // synchronous completion
 721
 722             // intentional fall-through
 723
 724         case NEEDS_READ:
 725             rc = drv->ReadData(firstBlock.addr, buffer, firstBlock.attributes.erase_unit);
 726             TEST_ASSERT(rc >= ARM_DRIVER_OK);
 727             if (rc == ARM_DRIVER_OK) {
 728                 TEST_ASSERT_EQUAL(1, drv->GetCapabilities().asynchronous_ops);
 729                 state = NEEDS_VERIFICATION_FOLLOWING_READ;
 730                 return;  // there is pending asynchronous activity which will lead to a completion callback later.
 731             }
 732             TEST_ASSERT_EQUAL(firstBlock.attributes.erase_unit, (uint32_t)rc);
 733
 734             // intentional fall-through
 735
 736         case NEEDS_VERIFICATION_FOLLOWING_READ:
 737             printf("verifying data\r\n");
 738             for (unsigned i = 0; i < firstBlock.attributes.erase_unit; i++) {
 739                 TEST_ASSERT_EQUAL(PATTERN, buffer[i]);
 740             }
 741             state = FINISHED;
 742             printf("done\r\n");
 743             break;
 744
 745         case FINISHED:
 746             break;
 747     } // switch (state)
 748 }
 749
 750 void callbackHandler(int32_t status, ARM_STORAGE_OPERATION operation)
 751 {
 752     (void)status;
 753     (void)operation;
 754     switch (operation) {
 755         case ARM_STORAGE_OPERATION_INITIALIZE:
 756         case ARM_STORAGE_OPERATION_READ_DATA:
 757         case ARM_STORAGE_OPERATION_PROGRAM_DATA:
 758         case ARM_STORAGE_OPERATION_ERASE:
 759             progressStateMachine();
 760             break;
 761
 762         default:
 763             printf("callbackHandler: unexpected callback for opcode %u with status %ld\r\n", operation, status);
 764             break;
 765     }
 766 }
 767 \endcode
 768 @}
 769 *******************************************************************************************************************/
 770 // End Storage Interface