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