Mohamed Moawya / SnakeGame

test test test

Dependencies:   mbed

snake-test/mbed/hal/Driver_Storage.h@0:e4c5e6ec922e, 2020-05-25 (annotated)

Committer:
mohamedmoawya
Date:
Mon May 25 19:06:11 2020 +0000
Revision:
0:e4c5e6ec922e
snake game tteest

Who changed what in which revision?

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