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