伊生希 小林 / Mbed 2 deprecated cansat_main_copy

temp

Dependencies:   mbed SDFileSystem MS5607 ADXL345_I2C FATFileSystem

mbed/hal/Driver_Storage.h@0:c88c3b616c00, 2020-03-16 (annotated)

Committer:
IKobayashi
Date:
Mon Mar 16 23:37:42 2020 +0900
Revision:
0:c88c3b616c00
copy

Who changed what in which revision?

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