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
ARM_Storage_GetVersion(void)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
ARM_Storage_GetCapabilities(void)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
ARM_Storage_Initialize(ARM_Storage_Callback_t callback)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
ARM_Storage_Uninitialize(void)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
ARM_Storage_PowerControl(ARM_POWER_STATE state)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
ARM_Storage_ReadData(uint64_t addr,void * data,uint32_t size)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
ARM_Storage_ProgramData(uint64_t addr,const void * data,uint32_t size)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
ARM_Storage_Erase(uint64_t addr,uint32_t size)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
ARM_Storage_EraseAll(void)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
ARM_Storage_GetStatus(void)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
ARM_Storage_GetInfo(ARM_STORAGE_INFO * info)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
ARM_Storage_ResolveAddress(uint64_t addr)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
ARM_Storage_GetNextBlock(const ARM_STORAGE_BLOCK * prev_block,ARM_STORAGE_BLOCK * next_block)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
ARM_Storage_GetBlock(uint64_t addr,ARM_STORAGE_BLOCK * block)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
771
