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

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