Johannes Stratmann / mbed-dev

added prescaler for 16 bit pwm in LPC1347 target

Fork of mbed-dev by mbed official

hal/storage_abstraction/Driver_Storage.h@147:ba84b7dc41a7, 2016-09-10 (annotated)

Committer:
JojoS
Date:
Sat Sep 10 15:32:04 2016 +0000
Revision:
147:ba84b7dc41a7
Parent:
144:ef7eb2e8f9f7 
added prescaler for 16 bit timers (solution as in LPC11xx), default prescaler 31 for max 28 ms period time

Who changed what in which revision?

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