forked
Embed:
(wiki syntax)
Show/hide line numbers
Driver_Storage.h
00001 00002 /** \addtogroup hal */ 00003 /** @{*/ 00004 /* 00005 * Copyright (c) 2006-2016, ARM Limited, All Rights Reserved 00006 * SPDX-License-Identifier: Apache-2.0 00007 * 00008 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00009 * not use this file except in compliance with the License. 00010 * You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, software 00015 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00016 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00017 * See the License for the specific language governing permissions and 00018 * limitations under the License. 00019 */ 00020 00021 #ifndef __DRIVER_STORAGE_H 00022 #define __DRIVER_STORAGE_H 00023 00024 #include <stdint.h> 00025 00026 /****** This file has been deprecated since mbed-os-5.5 *****/ 00027 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif // __cplusplus 00031 00032 #include "Driver_Common.h" 00033 00034 #define ARM_STORAGE_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(1,00) /* API version */ 00035 00036 00037 #define _ARM_Driver_Storage_(n) Driver_Storage##n 00038 #define ARM_Driver_Storage_(n) _ARM_Driver_Storage_(n) 00039 00040 #define ARM_STORAGE_INVALID_OFFSET (0xFFFFFFFFFFFFFFFFULL) ///< Invalid address (relative to a storage controller's 00041 ///< address space). A storage block may never start at this address. 00042 00043 #define ARM_STORAGE_INVALID_ADDRESS (0xFFFFFFFFUL) ///< Invalid address within the processor's memory address space. 00044 ///< Refer to memory-mapped storage, i.e. < \ref ARM_DRIVER_STORAGE::ResolveAddress(). 00045 00046 /****** Storage specific error codes *****/ 00047 #define ARM_STORAGE_ERROR_NOT_ERASABLE (ARM_DRIVER_ERROR_SPECIFIC - 1) ///< Part (or all) of the range provided to Erase() isn't erasable. 00048 #define ARM_STORAGE_ERROR_NOT_PROGRAMMABLE (ARM_DRIVER_ERROR_SPECIFIC - 2) ///< Part (or all) of the range provided to ProgramData() isn't programmable. 00049 #define ARM_STORAGE_ERROR_PROTECTED (ARM_DRIVER_ERROR_SPECIFIC - 3) ///< Part (or all) of the range to Erase() or ProgramData() is protected. 00050 #define ARM_STORAGE_ERROR_RUNTIME_OR_INTEGRITY_FAILURE (ARM_DRIVER_ERROR_SPECIFIC - 4) ///< Runtime or sanity-check failure. 00051 00052 /** 00053 * \brief Attributes of the storage range within a storage block. 00054 */ 00055 typedef struct _ARM_STORAGE_BLOCK_ATTRIBUTES { 00056 uint32_t erasable : 1; ///< Erasing blocks is permitted with a minimum granularity of 'erase_unit'. 00057 ///< @note: if 'erasable' is 0--i.e. the 'erase' operation isn't available--then 00058 ///< 'erase_unit' (see below) is immaterial and should be 0. 00059 uint32_t programmable : 1; ///< Writing to ranges is permitted with a minimum granularity of 'program_unit'. 00060 ///< Writes are typically achieved through the ProgramData operation (following an erase); 00061 ///< if storage isn't erasable (see 'erasable' above) but is memory-mapped 00062 ///< (i.e. 'memory_mapped'), it can be written directly using memory-store operations. 00063 uint32_t executable : 1; ///< This storage block can hold program data; the processor can fetch and execute code 00064 ///< sourced from it. Often this is accompanied with the device being 'memory_mapped' (see \ref ARM_STORAGE_INFO). 00065 uint32_t protectable : 1; ///< The entire block can be protected from program and erase operations. Once protection 00066 ///< is enabled for a block, its 'erasable' and 'programmable' bits are turned off. 00067 uint32_t reserved : 28; 00068 uint32_t erase_unit; ///< Minimum erase size in bytes. 00069 ///< The offset of the start of the erase-range should also be aligned with this value. 00070 ///< Applicable if the 'erasable' attribute is set for the block. 00071 ///< @note: if 'erasable' (see above) is 0--i.e. the 'erase' operation isn't available--then 00072 ///< 'erase_unit' is immaterial and should be 0. 00073 uint32_t protection_unit; ///< Minimum protectable size in bytes. Applicable if the 'protectable' 00074 ///< attribute is set for the block. This should be a divisor of the block's size. A 00075 ///< block can be considered to be made up of consecutive, individually-protectable fragments. 00076 } ARM_STORAGE_BLOCK_ATTRIBUTES; 00077 00078 /** 00079 * \brief A storage block is a range of memory with uniform attributes. Storage blocks 00080 * combine to make up the address map of a storage controller. 00081 */ 00082 typedef struct _ARM_STORAGE_BLOCK { 00083 uint64_t addr; ///< This is the start address of the storage block. It is 00084 ///< expressed as an offset from the start of the storage map 00085 ///< maintained by the owning storage controller. 00086 uint64_t size; ///< This is the size of the storage block, in units of bytes. 00087 ///< Together with addr, it describes a range [addr, addr+size). 00088 ARM_STORAGE_BLOCK_ATTRIBUTES attributes; ///< Attributes for this block. 00089 } ARM_STORAGE_BLOCK; 00090 00091 /** 00092 * The check for a valid ARM_STORAGE_BLOCK. 00093 */ 00094 #define ARM_STORAGE_VALID_BLOCK(BLK) (((BLK)->addr != ARM_STORAGE_INVALID_OFFSET) && ((BLK)->size != 0)) 00095 00096 /** 00097 * \brief Values for encoding storage memory-types with respect to programmability. 00098 * 00099 * Please ensure that the maximum of the following memory types doesn't exceed 16; we 00100 * encode this in a 4-bit field within ARM_STORAGE_INFO::programmability. 00101 */ 00102 #define ARM_STORAGE_PROGRAMMABILITY_RAM (0x0) 00103 #define ARM_STORAGE_PROGRAMMABILITY_ROM (0x1) ///< Read-only memory. 00104 #define ARM_STORAGE_PROGRAMMABILITY_WORM (0x2) ///< write-once-read-only-memory (WORM). 00105 #define ARM_STORAGE_PROGRAMMABILITY_ERASABLE (0x3) ///< re-programmable based on erase. Supports multiple writes. 00106 00107 /** 00108 * Values for encoding data-retention levels for storage blocks. 00109 * 00110 * Please ensure that the maximum of the following retention types doesn't exceed 16; we 00111 * encode this in a 4-bit field within ARM_STORAGE_INFO::retention_level. 00112 */ 00113 #define ARM_RETENTION_WHILE_DEVICE_ACTIVE (0x0) ///< Data is retained only during device activity. 00114 #define ARM_RETENTION_ACROSS_SLEEP (0x1) ///< Data is retained across processor sleep. 00115 #define ARM_RETENTION_ACROSS_DEEP_SLEEP (0x2) ///< Data is retained across processor deep-sleep. 00116 #define ARM_RETENTION_BATTERY_BACKED (0x3) ///< Data is battery-backed. Device can be powered off. 00117 #define ARM_RETENTION_NVM (0x4) ///< Data is retained in non-volatile memory. 00118 00119 /** 00120 * Device Data Security Protection Features. Applicable mostly to EXTERNAL_NVM. 00121 */ 00122 typedef struct _ARM_STORAGE_SECURITY_FEATURES { 00123 uint32_t acls : 1; ///< Protection against internal software attacks using ACLs. 00124 uint32_t rollback_protection : 1; ///< Roll-back protection. Set to true if the creator of the storage 00125 ///< can ensure that an external attacker can't force an 00126 ///< older firmware to run or to revert back to a previous state. 00127 uint32_t tamper_proof : 1; ///< Tamper-proof memory (will be deleted on tamper-attempts using board level or chip level sensors). 00128 uint32_t internal_flash : 1; ///< Internal flash. 00129 uint32_t reserved1 : 12; 00130 00131 /** 00132 * Encode support for hardening against various classes of attacks. 00133 */ 00134 uint32_t software_attacks : 1; ///< device software (malware running on the device). 00135 uint32_t board_level_attacks : 1; ///< board level attacks (debug probes, copy protection fuses.) 00136 uint32_t chip_level_attacks : 1; ///< chip level attacks (tamper-protection). 00137 uint32_t side_channel_attacks : 1; ///< side channel attacks. 00138 uint32_t reserved2 : 12; 00139 } ARM_STORAGE_SECURITY_FEATURES; 00140 00141 #define ARM_STORAGE_PROGRAM_CYCLES_INFINITE (0UL) /**< Infinite or unknown endurance for reprogramming. */ 00142 00143 /** 00144 * \brief Storage information. This contains device-metadata. It is the return 00145 * value from calling GetInfo() on the storage driver. 00146 * 00147 * \details These fields serve a different purpose than the ones contained in 00148 * \ref ARM_STORAGE_CAPABILITIES, which is another structure containing 00149 * device-level metadata. ARM_STORAGE_CAPABILITIES describes the API 00150 * capabilities, whereas ARM_STORAGE_INFO describes the device. Furthermore 00151 * ARM_STORAGE_CAPABILITIES fits within a single word, and is designed to be 00152 * passed around by value; ARM_STORAGE_INFO, on the other hand, contains 00153 * metadata which doesn't fit into a single word and requires the use of 00154 * pointers to be moved around. 00155 */ 00156 typedef struct _ARM_STORAGE_INFO { 00157 uint64_t total_storage; ///< Total available storage, in bytes. 00158 uint32_t program_unit; ///< Minimum programming size in bytes. 00159 ///< The offset of the start of the program-range should also be aligned with this value. 00160 ///< Applicable only if the 'programmable' attribute is set for a block. 00161 ///< @note: setting program_unit to 0 has the effect of disabling the size and alignment 00162 ///< restrictions (setting it to 1 also has the same effect). 00163 uint32_t optimal_program_unit; ///< Optimal programming page-size in bytes. Some storage controllers 00164 ///< have internal buffers into which to receive data. Writing in chunks of 00165 ///< 'optimal_program_unit' would achieve maximum programming speed. 00166 ///< Applicable only if the 'programmable' attribute is set for the underlying block(s). 00167 uint32_t program_cycles; ///< A measure of endurance for reprogramming. 00168 ///< Use ARM_STORAGE_PROGRAM_CYCLES_INFINITE for infinite or unknown endurance. 00169 uint32_t erased_value : 1; ///< Contents of erased memory (usually 1 to indicate erased bytes with state 0xFF). 00170 uint32_t memory_mapped : 1; ///< This storage device has a mapping onto the processor's memory address space. 00171 ///< @note: For a memory-mapped block which isn't erasable but is programmable (i.e. if 00172 ///< 'erasable' is set to 0, but 'programmable' is 1), writes should be possible directly to 00173 ///< the memory-mapped storage without going through the ProgramData operation. 00174 uint32_t programmability : 4; ///< A value to indicate storage programmability. 00175 uint32_t retention_level : 4; 00176 uint32_t reserved : 22; 00177 ARM_STORAGE_SECURITY_FEATURES security; ///< \ref ARM_STORAGE_SECURITY_FEATURES 00178 } ARM_STORAGE_INFO; 00179 00180 /** 00181 \brief Operating status of the storage controller. 00182 */ 00183 typedef struct _ARM_STORAGE_STATUS { 00184 uint32_t busy : 1; ///< Controller busy flag 00185 uint32_t error : 1; ///< Read/Program/Erase error flag (cleared on start of next operation) 00186 } ARM_STORAGE_STATUS; 00187 00188 /** 00189 * \brief Storage Driver API Capabilities. 00190 * 00191 * This data structure is designed to fit within a single word so that it can be 00192 * fetched cheaply using a call to driver->GetCapabilities(). 00193 */ 00194 typedef struct _ARM_STORAGE_CAPABILITIES { 00195 uint32_t asynchronous_ops : 1; ///< Used to indicate if APIs like initialize, 00196 ///< read, erase, program, etc. can operate in asynchronous mode. 00197 ///< Setting this bit to 1 means that the driver is capable 00198 ///< of launching asynchronous operations; command completion is 00199 ///< signaled by the invocation of a completion callback. If 00200 ///< set to 1, drivers may still complete asynchronous 00201 ///< operations synchronously as necessary--in which case they 00202 ///< return a positive error code to indicate synchronous completion. 00203 uint32_t erase_all : 1; ///< Supports EraseAll operation. 00204 uint32_t reserved : 30; 00205 } ARM_STORAGE_CAPABILITIES; 00206 00207 /** 00208 * Command opcodes for Storage. Completion callbacks use these codes to refer to 00209 * completing commands. Refer to \ref ARM_Storage_Callback_t. 00210 */ 00211 typedef enum _ARM_STORAGE_OPERATION { 00212 ARM_STORAGE_OPERATION_GET_VERSION, 00213 ARM_STORAGE_OPERATION_GET_CAPABILITIES, 00214 ARM_STORAGE_OPERATION_INITIALIZE, 00215 ARM_STORAGE_OPERATION_UNINITIALIZE, 00216 ARM_STORAGE_OPERATION_POWER_CONTROL, 00217 ARM_STORAGE_OPERATION_READ_DATA, 00218 ARM_STORAGE_OPERATION_PROGRAM_DATA, 00219 ARM_STORAGE_OPERATION_ERASE, 00220 ARM_STORAGE_OPERATION_ERASE_ALL, 00221 ARM_STORAGE_OPERATION_GET_STATUS, 00222 ARM_STORAGE_OPERATION_GET_INFO, 00223 ARM_STORAGE_OPERATION_RESOLVE_ADDRESS, 00224 ARM_STORAGE_OPERATION_GET_NEXT_BLOCK, 00225 ARM_STORAGE_OPERATION_GET_BLOCK 00226 } ARM_STORAGE_OPERATION; 00227 00228 /** 00229 * Declaration of the callback-type for command completion. 00230 * 00231 * @param [in] status 00232 * A code to indicate the status of the completed operation. For data 00233 * transfer operations, the status field is overloaded in case of 00234 * success to return the count of items successfully transferred; this 00235 * can be done safely because error codes are negative values. 00236 * 00237 * @param [in] operation 00238 * The command op-code. This value isn't essential for the callback in 00239 * the presence of the command instance-id, but it is expected that 00240 * this information could be a quick and useful filter. 00241 */ 00242 typedef void (*ARM_Storage_Callback_t)(int32_t status, ARM_STORAGE_OPERATION operation); 00243 00244 /** 00245 * This is the set of operations constituting the Storage driver. Their 00246 * implementation is platform-specific, and needs to be supplied by the 00247 * porting effort. 00248 * 00249 * Some APIs within `ARM_DRIVER_STORAGE` will always operate synchronously: 00250 * GetVersion, GetCapabilities, GetStatus, GetInfo, ResolveAddress, 00251 * GetNextBlock, and GetBlock. This means that control returns to the caller 00252 * with a relevant status code only after the completion of the operation (or 00253 * the discovery of a failure condition). 00254 * 00255 * The remainder of the APIs: Initialize, Uninitialize, PowerControl, ReadData, 00256 * ProgramData, Erase, EraseAll, can function asynchronously if the underlying 00257 * controller supports it--i.e. if ARM_STORAGE_CAPABILITIES::asynchronous_ops is 00258 * set. In the case of asynchronous operation, the invocation returns early 00259 * (with ARM_DRIVER_OK) and results in a completion callback later. If 00260 * ARM_STORAGE_CAPABILITIES::asynchronous_ops is not set, then all such APIs 00261 * execute synchronously, and control returns to the caller with a status code 00262 * only after the completion of the operation (or the discovery of a failure 00263 * condition). 00264 * 00265 * If ARM_STORAGE_CAPABILITIES::asynchronous_ops is set, a storage driver may 00266 * still choose to execute asynchronous operations in a synchronous manner. If 00267 * so, the driver returns a positive value to indicate successful synchronous 00268 * completion (or an error code in case of failure) and no further invocation of 00269 * completion callback should be expected. The expected return value for 00270 * synchronous completion of such asynchronous operations varies depending on 00271 * the operation. For operations involving data access, it often equals the 00272 * amount of data transferred or affected. For non data-transfer operations, 00273 * such as EraseAll or Initialize, it is usually 1. 00274 * 00275 * Here's a code snippet to suggest how asynchronous APIs might be used by 00276 * callers to handle both synchronous and asynchronous execution by the 00277 * underlying storage driver: 00278 * \code 00279 * ASSERT(ARM_DRIVER_OK == 0); // this is a precondition; it doesn't need to be put in code 00280 * int32_t returnValue = drv->asynchronousAPI(...); 00281 * if (returnValue < ARM_DRIVER_OK) { 00282 * // handle error. 00283 * } else if (returnValue == ARM_DRIVER_OK) { 00284 * ASSERT(drv->GetCapabilities().asynchronous_ops == 1); 00285 * // handle early return from asynchronous execution; remainder of the work is done in the callback handler. 00286 * } else { 00287 * ASSERT(returnValue == EXPECTED_RETURN_VALUE_FOR_SYNCHRONOUS_COMPLETION); 00288 * // handle synchronous completion. 00289 * } 00290 * \endcode 00291 */ 00292 typedef struct _ARM_DRIVER_STORAGE { 00293 /** 00294 * \brief Get driver version. 00295 * 00296 * The function GetVersion() returns version information of the driver implementation in ARM_DRIVER_VERSION. 00297 * 00298 * - API version is the version of the CMSIS-Driver specification used to implement this driver. 00299 * - Driver version is source code version of the actual driver implementation. 00300 * 00301 * Example: 00302 * \code 00303 * extern ARM_DRIVER_STORAGE *drv_info; 00304 * 00305 * void read_version (void) { 00306 * ARM_DRIVER_VERSION version; 00307 * 00308 * version = drv_info->GetVersion (); 00309 * if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher 00310 * // error handling 00311 * return; 00312 * } 00313 * } 00314 * \endcode 00315 * 00316 * @return \ref ARM_DRIVER_VERSION. 00317 * 00318 * @note This API returns synchronously--it does not result in an invocation 00319 * of a completion callback. 00320 * 00321 * @note The function GetVersion() can be called any time to obtain the 00322 * required information from the driver (even before initialization). It 00323 * always returns the same information. 00324 */ 00325 ARM_DRIVER_VERSION (*GetVersion)(void); 00326 00327 /** 00328 * \brief Get driver capabilities. 00329 * 00330 * \details The function GetCapabilities() returns information about 00331 * capabilities in this driver implementation. The data fields of the struct 00332 * ARM_STORAGE_CAPABILITIES encode various capabilities, for example if the device 00333 * is able to execute operations asynchronously. 00334 * 00335 * Example: 00336 * \code 00337 * extern ARM_DRIVER_STORAGE *drv_info; 00338 * 00339 * void read_capabilities (void) { 00340 * ARM_STORAGE_CAPABILITIES drv_capabilities; 00341 * 00342 * drv_capabilities = drv_info->GetCapabilities (); 00343 * // interrogate capabilities 00344 * 00345 * } 00346 * \endcode 00347 * 00348 * @return \ref ARM_STORAGE_CAPABILITIES. 00349 * 00350 * @note This API returns synchronously--it does not result in an invocation 00351 * of a completion callback. 00352 * 00353 * @note The function GetCapabilities() can be called any time to obtain the 00354 * required information from the driver (even before initialization). It 00355 * always returns the same information. 00356 */ 00357 ARM_STORAGE_CAPABILITIES (*GetCapabilities)(void); 00358 00359 /** 00360 * \brief Initialize the Storage Interface. 00361 * 00362 * The function Initialize is called when the middleware component starts 00363 * operation. In addition to bringing the controller to a ready state, 00364 * Initialize() receives a callback handler to be invoked upon completion of 00365 * asynchronous operations. 00366 * 00367 * Initialize() needs to be called explicitly before 00368 * powering the peripheral using PowerControl(), and before initiating other 00369 * accesses to the storage controller. 00370 * 00371 * The function performs the following operations: 00372 * - Initializes the resources needed for the Storage interface. 00373 * - Registers the \ref ARM_Storage_Callback_t callback function. 00374 * 00375 * To start working with a peripheral the functions Initialize and PowerControl need to be called in this order: 00376 * drv->Initialize (...); // Allocate I/O pins 00377 * drv->PowerControl (ARM_POWER_FULL); // Power up peripheral, setup IRQ/DMA 00378 * 00379 * - Initialize() typically allocates the I/O resources (pins) for the 00380 * peripheral. The function can be called multiple times; if the I/O resources 00381 * are already initialized it performs no operation and just returns with 00382 * ARM_DRIVER_OK. 00383 * 00384 * - PowerControl (ARM_POWER_FULL) sets the peripheral registers including 00385 * interrupt (NVIC) and optionally DMA. The function can be called multiple 00386 * times; if the registers are already set it performs no operation and just 00387 * returns with ARM_DRIVER_OK. 00388 * 00389 * To stop working with a peripheral the functions PowerControl and Uninitialize need to be called in this order: 00390 * drv->PowerControl (ARM_POWER_OFF); // Terminate any pending transfers, reset IRQ/DMA, power off peripheral 00391 * drv->Uninitialize (...); // Release I/O pins 00392 * 00393 * The functions PowerControl and Uninitialize always execute and can be used 00394 * to put the peripheral into a Safe State, for example after any data 00395 * transmission errors. To restart the peripheral in an error condition, 00396 * you should first execute the Stop Sequence and then the Start Sequence. 00397 * 00398 * @param [in] callback 00399 * Caller-defined callback to be invoked upon command completion 00400 * for asynchronous APIs (including the completion of 00401 * initialization). Use a NULL pointer when no callback 00402 * signals are required. 00403 * 00404 * @note This API may execute asynchronously if 00405 * ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous 00406 * execution is optional even if 'asynchronous_ops' is set. 00407 * 00408 * @return If asynchronous activity is launched, an invocation returns 00409 * ARM_DRIVER_OK, and the caller can expect to receive a callback in the 00410 * future with a status value of ARM_DRIVER_OK or an error-code. In the 00411 * case of synchronous execution, control returns after completion with a 00412 * value of 1. Return values less than ARM_DRIVER_OK (0) signify errors. 00413 */ 00414 int32_t (*Initialize)(ARM_Storage_Callback_t callback); 00415 00416 /** 00417 * \brief De-initialize the Storage Interface. 00418 * 00419 * The function Uninitialize() de-initializes the resources of Storage interface. 00420 * 00421 * It is called when the middleware component stops operation, and wishes to 00422 * release the software resources used by the interface. 00423 * 00424 * @note This API may execute asynchronously if 00425 * ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous 00426 * execution is optional even if 'asynchronous_ops' is set. 00427 * 00428 * @return If asynchronous activity is launched, an invocation returns 00429 * ARM_DRIVER_OK, and the caller can expect to receive a callback in the 00430 * future with a status value of ARM_DRIVER_OK or an error-code. In the 00431 * case of synchronous execution, control returns after completion with a 00432 * value of 1. Return values less than ARM_DRIVER_OK (0) signify errors. 00433 */ 00434 int32_t (*Uninitialize)(void); 00435 00436 /** 00437 * \brief Control the Storage interface power. 00438 * 00439 * The function \b ARM_Storage_PowerControl operates the power modes of the Storage interface. 00440 * 00441 * To start working with a peripheral the functions Initialize and PowerControl need to be called in this order: 00442 * drv->Initialize (...); // Allocate I/O pins 00443 * drv->PowerControl (ARM_POWER_FULL); // Power up peripheral, setup IRQ/DMA 00444 * 00445 * - Initialize() typically allocates the I/O resources (pins) for the 00446 * peripheral. The function can be called multiple times; if the I/O resources 00447 * are already initialized it performs no operation and just returns with 00448 * ARM_DRIVER_OK. 00449 * 00450 * - PowerControl (ARM_POWER_FULL) sets the peripheral registers including 00451 * interrupt (NVIC) and optionally DMA. The function can be called multiple 00452 * times; if the registers are already set it performs no operation and just 00453 * returns with ARM_DRIVER_OK. 00454 * 00455 * To stop working with a peripheral the functions PowerControl and Uninitialize need to be called in this order: 00456 * 00457 * drv->PowerControl (ARM_POWER_OFF); // Terminate any pending transfers, reset IRQ/DMA, power off peripheral 00458 * drv->Uninitialize (...); // Release I/O pins 00459 * 00460 * The functions PowerControl and Uninitialize always execute and can be used 00461 * to put the peripheral into a Safe State, for example after any data 00462 * transmission errors. To restart the peripheral in an error condition, 00463 * you should first execute the Stop Sequence and then the Start Sequence. 00464 * 00465 * @param state 00466 * \ref ARM_POWER_STATE. The target power-state for the storage controller. 00467 * The parameter state can have the following values: 00468 * - ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts 00469 * (NVIC) and optionally DMA. Can be called multiple times. If the peripheral 00470 * is already in this mode, then the function performs no operation and returns 00471 * with ARM_DRIVER_OK. 00472 * - ARM_POWER_LOW : may use power saving. Returns ARM_DRIVER_ERROR_UNSUPPORTED when not implemented. 00473 * - ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA. 00474 * 00475 * @note This API may execute asynchronously if 00476 * ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous 00477 * execution is optional even if 'asynchronous_ops' is set. 00478 * 00479 * @return If asynchronous activity is launched, an invocation returns 00480 * ARM_DRIVER_OK, and the caller can expect to receive a callback in the 00481 * future with a status value of ARM_DRIVER_OK or an error-code. In the 00482 * case of synchronous execution, control returns after completion with a 00483 * value of 1. Return values less than ARM_DRIVER_OK (0) signify errors. 00484 */ 00485 int32_t (*PowerControl)(ARM_POWER_STATE state); 00486 00487 /** 00488 * \brief read the contents of a given address range from the storage device. 00489 * 00490 * \details Read the contents of a range of storage memory into a buffer 00491 * supplied by the caller. The buffer is owned by the caller and should 00492 * remain accessible for the lifetime of this command. 00493 * 00494 * @param [in] addr 00495 * This specifies the address from where to read data. 00496 * 00497 * @param [out] data 00498 * The destination of the read operation. The buffer 00499 * is owned by the caller and should remain accessible for the 00500 * lifetime of this command. 00501 * 00502 * @param [in] size 00503 * The number of bytes requested to read. The data buffer 00504 * should be at least as large as this size. 00505 * 00506 * @note This API may execute asynchronously if 00507 * ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous 00508 * execution is optional even if 'asynchronous_ops' is set. 00509 * 00510 * @return If asynchronous activity is launched, an invocation returns 00511 * ARM_DRIVER_OK, and the caller can expect to receive a callback in the 00512 * future with the number of successfully transferred bytes passed in as 00513 * the 'status' parameter. In the case of synchronous execution, control 00514 * returns after completion with a positive transfer-count. Return values 00515 * less than ARM_DRIVER_OK (0) signify errors. 00516 */ 00517 int32_t (*ReadData)(uint64_t addr, void *data, uint32_t size); 00518 00519 /** 00520 * \brief program (write into) the contents of a given address range of the storage device. 00521 * 00522 * \details Write the contents of a given memory buffer into a range of 00523 * storage memory. In the case of flash memory, the destination range in 00524 * storage memory typically has its contents in an erased state from a 00525 * preceding erase operation. The source memory buffer is owned by the 00526 * caller and should remain accessible for the lifetime of this command. 00527 * 00528 * @param [in] addr 00529 * This is the start address of the range to be written into. It 00530 * needs to be aligned to the device's \em program_unit 00531 * specified in \ref ARM_STORAGE_INFO. 00532 * 00533 * @param [in] data 00534 * The source of the write operation. The buffer is owned by the 00535 * caller and should remain accessible for the lifetime of this 00536 * command. 00537 * 00538 * @param [in] size 00539 * The number of bytes requested to be written. The buffer 00540 * should be at least as large as this size. \note 'size' should 00541 * be a multiple of the device's 'program_unit' (see \ref 00542 * ARM_STORAGE_INFO). 00543 * 00544 * @note It is best for the middleware to write in units of 00545 * 'optimal_program_unit' (\ref ARM_STORAGE_INFO) of the device. 00546 * 00547 * @note This API may execute asynchronously if 00548 * ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous 00549 * execution is optional even if 'asynchronous_ops' is set. 00550 * 00551 * @return If asynchronous activity is launched, an invocation returns 00552 * ARM_DRIVER_OK, and the caller can expect to receive a callback in the 00553 * future with the number of successfully transferred bytes passed in as 00554 * the 'status' parameter. In the case of synchronous execution, control 00555 * returns after completion with a positive transfer-count. Return values 00556 * less than ARM_DRIVER_OK (0) signify errors. 00557 */ 00558 int32_t (*ProgramData)(uint64_t addr, const void *data, uint32_t size); 00559 00560 /** 00561 * @brief Erase Storage range. 00562 * 00563 * @details This function erases a range of storage specified by [addr, addr + 00564 * size). Both 'addr' and 'addr + size' should align with the 00565 * 'erase_unit'(s) of the respective owning storage block(s) (see \ref 00566 * ARM_STORAGE_BLOCK and \ref ARM_STORAGE_BLOCK_ATTRIBUTES). The range to 00567 * be erased will have its contents returned to the un-programmed state-- 00568 * i.e. to 'erased_value' (see \ref ARM_STORAGE_BLOCK_ATTRIBUTES), which 00569 * is usually 1 to indicate the pattern of all ones: 0xFF. 00570 * 00571 * @param [in] addr 00572 * This is the start-address of the range to be erased. It must 00573 * start at an 'erase_unit' boundary of the underlying block. 00574 * 00575 * @param [in] size 00576 * Size (in bytes) of the range to be erased. 'addr + size' 00577 * must be aligned with the 'erase_unit' of the underlying 00578 * block. 00579 * 00580 * @note This API may execute asynchronously if 00581 * ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous 00582 * execution is optional even if 'asynchronous_ops' is set. 00583 * 00584 * @return 00585 * If the range to be erased doesn't align with the erase_units of the 00586 * respective start and end blocks, ARM_DRIVER_ERROR_PARAMETER is returned. 00587 * If any part of the range is protected, ARM_STORAGE_ERROR_PROTECTED is 00588 * returned. If any part of the range is not erasable, 00589 * ARM_STORAGE_ERROR_NOT_ERASABLE is returned. All such sanity-check 00590 * failures result in the error code being returned synchronously and the 00591 * storage bytes within the range remain unaffected. 00592 * Otherwise the function executes in the following ways: 00593 * If asynchronous activity is launched, an invocation returns 00594 * ARM_DRIVER_OK, and the caller can expect to receive a callback in the 00595 * future with the number of successfully erased bytes passed in as 00596 * the 'status' parameter. In the case of synchronous execution, control 00597 * returns after completion with a positive erase-count. Return values 00598 * less than ARM_DRIVER_OK (0) signify errors. 00599 * 00600 * @note Erase() may return a smaller (positive) value than the size of the 00601 * requested range. The returned value indicates the actual number of bytes 00602 * erased. It is the caller's responsibility to follow up with an appropriate 00603 * request to complete the operation. 00604 * 00605 * @note in the case of a failed erase (except when 00606 * ARM_DRIVER_ERROR_PARAMETER, ARM_STORAGE_ERROR_PROTECTED, or 00607 * ARM_STORAGE_ERROR_NOT_ERASABLE is returned synchronously), the 00608 * requested range should be assumed to be in an unknown state. The 00609 * previous contents may not be retained. 00610 */ 00611 int32_t (*Erase)(uint64_t addr, uint32_t size); 00612 00613 /** 00614 * @brief Erase complete storage. Optional function for faster erase of the complete device. 00615 * 00616 * This optional function erases the complete device. If the device does not 00617 * support global erase then the function returns the error value \ref 00618 * ARM_DRIVER_ERROR_UNSUPPORTED. The data field \em 'erase_all' = 1 00619 * of the structure \ref ARM_STORAGE_CAPABILITIES encodes that 00620 * ARM_STORAGE_EraseAll is supported. 00621 * 00622 * @note This API may execute asynchronously if 00623 * ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous 00624 * execution is optional even if 'asynchronous_ops' is set. 00625 * 00626 * @return 00627 * If any part of the storage range is protected, 00628 * ARM_STORAGE_ERROR_PROTECTED is returned. If any part of the storage 00629 * range is not erasable, ARM_STORAGE_ERROR_NOT_ERASABLE is returned. All 00630 * such sanity-check failures result in the error code being returned 00631 * synchronously and the storage bytes within the range remain unaffected. 00632 * Otherwise the function executes in the following ways: 00633 * If asynchronous activity is launched, an invocation returns 00634 * ARM_DRIVER_OK, and the caller can expect to receive a callback in the 00635 * future with ARM_DRIVER_OK passed in as the 'status' parameter. In the 00636 * case of synchronous execution, control returns after completion with a 00637 * value of 1. Return values less than ARM_DRIVER_OK (0) signify errors. 00638 */ 00639 int32_t (*EraseAll)(void); 00640 00641 /** 00642 * @brief Get the status of the current (or previous) command executed by the 00643 * storage controller; stored in the structure \ref ARM_STORAGE_STATUS. 00644 * 00645 * @return 00646 * The status of the underlying controller. 00647 * 00648 * @note This API returns synchronously--it does not result in an invocation 00649 * of a completion callback. 00650 */ 00651 ARM_STORAGE_STATUS (*GetStatus)(void); 00652 00653 /** 00654 * @brief Get information about the Storage device; stored in the structure \ref ARM_STORAGE_INFO. 00655 * 00656 * @param [out] info 00657 * A caller-supplied buffer capable of being filled in with an 00658 * \ref ARM_STORAGE_INFO. 00659 * 00660 * @return ARM_DRIVER_OK if a ARM_STORAGE_INFO structure containing top level 00661 * metadata about the storage controller is filled into the supplied 00662 * buffer, else an appropriate error value. 00663 * 00664 * @note It is the caller's responsibility to ensure that the buffer passed in 00665 * is able to be initialized with a \ref ARM_STORAGE_INFO. 00666 * 00667 * @note This API returns synchronously--it does not result in an invocation 00668 * of a completion callback. 00669 */ 00670 int32_t (*GetInfo)(ARM_STORAGE_INFO *info); 00671 00672 /** 00673 * \brief For memory-mapped storage, resolve an address relative to 00674 * the storage controller into a memory address. 00675 * 00676 * @param addr 00677 * This is the address for which we want a resolution to the 00678 * processor's physical address space. It is an offset from the 00679 * start of the storage map maintained by the owning storage 00680 * controller. 00681 * 00682 * @return 00683 * The resolved address in the processor's address space; else 00684 * ARM_STORAGE_INVALID_ADDRESS, if no resolution is possible. 00685 * 00686 * @note This API returns synchronously. The invocation should return quickly, 00687 * and result in a resolved address. 00688 */ 00689 uint32_t (*ResolveAddress)(uint64_t addr); 00690 00691 /** 00692 * @brief Advance to the successor of the current block (iterator), or fetch 00693 * the first block (if 'prev_block' is passed in as NULL). 00694 * 00695 * @details This helper function fetches (an iterator to) the next block (or 00696 * the first block if 'prev_block' is passed in as NULL). In the failure 00697 * case, a terminating, invalid block iterator is filled into the out 00698 * parameter: 'next_block'. In combination with \ref 00699 * ARM_STORAGE_VALID_BLOCK(), it can be used to iterate over the sequence 00700 * of blocks within the storage map: 00701 * 00702 * \code 00703 * ARM_STORAGE_BLOCK block; 00704 * for (drv->GetNextBlock(NULL, &block); ARM_STORAGE_VALID_BLOCK(&block); drv->GetNextBlock(&block, &block)) { 00705 * // make use of block 00706 * } 00707 * \endcode 00708 * 00709 * @param[in] prev_block 00710 * An existing block (iterator) within the same storage 00711 * controller. The memory buffer holding this block is owned 00712 * by the caller. This pointer may be NULL; if so, the 00713 * invocation fills in the first block into the out parameter: 00714 * 'next_block'. 00715 * 00716 * @param[out] next_block 00717 * A caller-owned buffer large enough to be filled in with 00718 * the following ARM_STORAGE_BLOCK. It is legal to provide the 00719 * same buffer using 'next_block' as was passed in with 'prev_block'. It 00720 * is also legal to pass a NULL into this parameter if the 00721 * caller isn't interested in populating a buffer with the next 00722 * block--i.e. if the caller only wishes to establish the 00723 * presence of a next block. 00724 * 00725 * @return ARM_DRIVER_OK if a valid next block is found (or first block, if 00726 * prev_block is passed as NULL); upon successful operation, the contents 00727 * of the next (or first) block are filled into the buffer pointed to by 00728 * the parameter 'next_block' and ARM_STORAGE_VALID_BLOCK(next_block) is 00729 * guaranteed to be true. Upon reaching the end of the sequence of blocks 00730 * (iterators), or in case the driver is unable to fetch information about 00731 * the next (or first) block, an error (negative) value is returned and an 00732 * invalid StorageBlock is populated into the supplied buffer. If 00733 * prev_block is NULL, the first block is returned. 00734 * 00735 * @note This API returns synchronously--it does not result in an invocation 00736 * of a completion callback. 00737 */ 00738 int32_t (*GetNextBlock)(const ARM_STORAGE_BLOCK* prev_block, ARM_STORAGE_BLOCK *next_block); 00739 00740 /** 00741 * @brief Find the storage block (iterator) encompassing a given storage address. 00742 * 00743 * @param[in] addr 00744 * Storage address in bytes. 00745 * 00746 * @param[out] block 00747 * A caller-owned buffer large enough to be filled in with the 00748 * ARM_STORAGE_BLOCK encapsulating the given address. This value 00749 * can also be passed in as NULL if the caller isn't interested 00750 * in populating a buffer with the block--if the caller only 00751 * wishes to establish the presence of a containing storage 00752 * block. 00753 * 00754 * @return ARM_DRIVER_OK if a containing storage-block is found. In this case, 00755 * if block is non-NULL, the buffer pointed to by it is populated with 00756 * the contents of the storage block--i.e. if block is valid and a block is 00757 * found, ARM_STORAGE_VALID_BLOCK(block) would return true following this 00758 * call. If there is no storage block containing the given offset, or in 00759 * case the driver is unable to resolve an address to a storage-block, an 00760 * error (negative) value is returned and an invalid StorageBlock is 00761 * populated into the supplied buffer. 00762 * 00763 * @note This API returns synchronously--it does not result in an invocation 00764 * of a completion callback. 00765 */ 00766 int32_t (*GetBlock)(uint64_t addr, ARM_STORAGE_BLOCK *block); 00767 } const ARM_DRIVER_STORAGE; 00768 00769 #ifdef __cplusplus 00770 } 00771 #endif // __cplusplus 00772 00773 #endif /* __DRIVER_STORAGE_H */ 00774 00775 /** @}*/
Generated on Tue Jul 12 2022 16:02:32 by 1.7.2