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