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