1 /*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #ifndef ANDROID_HARDWARE_NVRAM_H
18 #define ANDROID_HARDWARE_NVRAM_H
19
20 #include <stdint.h>
21 #include <sys/cdefs.h>
22
23 #include <hardware/hardware.h>
24 #include <hardware/nvram_defs.h>
25
26 __BEGIN_DECLS
27
28 /* The id of this module. */
29 #define NVRAM_HARDWARE_MODULE_ID "nvram"
30 #define NVRAM_HARDWARE_DEVICE_ID "nvram-dev"
31
32 /* The version of this module. */
33 #define NVRAM_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1)
34 #define NVRAM_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION(1, 1)
35
36 struct nvram_module {
37 /**
38 * Common methods of the nvram_module. This *must* be the first member of
39 * nvram_module as users of this structure will cast a hw_module_t to
40 * nvram_module pointer in contexts where it's known the hw_module_t
41 * references a nvram_module.
42 */
43 hw_module_t common;
44
45 /* There are no module methods other than the common ones. */
46 };
47
48 struct nvram_device {
49 /**
50 * Common methods of the nvram_device. This *must* be the first member of
51 * nvram_device as users of this structure will cast a hw_device_t to
52 * nvram_device pointer in contexts where it's known the hw_device_t
53 * references a nvram_device.
54 */
55 struct hw_device_t common;
56
57 /**
58 * Outputs the total number of bytes available in NVRAM. This will
59 * always be at least 2048. If an implementation does not know the
60 * total size it may provide an estimate or 2048.
61 *
62 * device - The nvram_device instance.
63 * total_size - Receives the output. Cannot be NULL.
64 */
65 nvram_result_t (*get_total_size_in_bytes)(const struct nvram_device* device,
66 uint64_t* total_size);
67
68 /**
69 * Outputs the unallocated number of bytes available in NVRAM. If an
70 * implementation does not know the available size it may provide an
71 * estimate or the total size.
72 *
73 * device - The nvram_device instance.
74 * available_size - Receives the output. Cannot be NULL.
75 */
76 nvram_result_t (*get_available_size_in_bytes)(
77 const struct nvram_device* device, uint64_t* available_size);
78
79 /**
80 * Outputs the maximum number of bytes that can be allocated for a single
81 * space. This will always be at least 32. If an implementation does not
82 * limit the maximum size it may provide the total size.
83 *
84 * device - The nvram_device instance.
85 * max_space_size - Receives the output. Cannot be NULL.
86 */
87 nvram_result_t (*get_max_space_size_in_bytes)(
88 const struct nvram_device* device, uint64_t* max_space_size);
89
90 /**
91 * Outputs the maximum total number of spaces that may be allocated.
92 * This will always be at least 8. Outputs NV_UNLIMITED_SPACES if any
93 * number of spaces are supported (limited only to available NVRAM
94 * bytes).
95 *
96 * device - The nvram_device instance.
97 * num_spaces - Receives the output. Cannot be NULL.
98 */
99 nvram_result_t (*get_max_spaces)(const struct nvram_device* device,
100 uint32_t* num_spaces);
101
102 /**
103 * Outputs a list of created space indices. If |max_list_size| is
104 * 0, only |list_size| is populated.
105 *
106 * device - The nvram_device instance.
107 * max_list_size - The number of items in the |space_index_list|
108 * array.
109 * space_index_list - Receives the list of created spaces up to the
110 * given |max_list_size|. May be NULL if
111 * |max_list_size| is 0.
112 * list_size - Receives the number of items populated in
113 * |space_index_list|, or the number of items available
114 * if |space_index_list| is NULL.
115 */
116 nvram_result_t (*get_space_list)(const struct nvram_device* device,
117 uint32_t max_list_size,
118 uint32_t* space_index_list,
119 uint32_t* list_size);
120
121 /**
122 * Outputs the size, in bytes, of a given space.
123 *
124 * device - The nvram_device instance.
125 * index - The space index.
126 * size - Receives the output. Cannot be NULL.
127 */
128 nvram_result_t (*get_space_size)(const struct nvram_device* device,
129 uint32_t index, uint64_t* size);
130
131 /**
132 * Outputs the list of controls associated with a given space.
133 *
134 * device - The nvram_device instance.
135 * index - The space index.
136 * max_list_size - The number of items in the |control_list| array.
137 * control_list - Receives the list of controls up to the given
138 * |max_list_size|. May be NULL if |max_list_size|
139 * is 0.
140 * list_size - Receives the number of items populated in
141 * |control_list|, or the number of items available if
142 * |control_list| is NULL.
143 */
144 nvram_result_t (*get_space_controls)(const struct nvram_device* device,
145 uint32_t index, uint32_t max_list_size,
146 nvram_control_t* control_list,
147 uint32_t* list_size);
148
149 /**
150 * Outputs whether locks are enabled for the given space. When a lock
151 * is enabled, the operation is disabled and any attempt to perform that
152 * operation will result in NV_RESULT_OPERATION_DISABLED.
153 *
154 * device - The nvram_device instance.
155 * index - The space index.
156 * write_lock_enabled - Will be set to non-zero iff write
157 * operations are currently disabled.
158 * read_lock_enabled - Will be set to non-zero iff read operations
159 * are currently disabled.
160 */
161 nvram_result_t (*is_space_locked)(const struct nvram_device* device,
162 uint32_t index, int* write_lock_enabled,
163 int* read_lock_enabled);
164
165 /**
166 * Creates a new space with the given index, size, controls, and
167 * authorization value.
168 *
169 * device - The nvram_device instance.
170 * index - An index for the new space. The index can be any 32-bit
171 * value but must not already be assigned to an existing
172 * space.
173 * size_in_bytes - The number of bytes to allocate for the space.
174 * control_list - An array of controls to enforce for the space.
175 * list_size - The number of items in |control_list|.
176 * authorization_value - If |control_list| contains
177 * NV_CONTROL_READ_AUTHORIZATION and / or
178 * NV_CONTROL_WRITE_AUTHORIZATION, then this
179 * parameter provides the authorization value
180 * for these policies (if both controls are
181 * set then this value applies to both).
182 * Otherwise, this value is ignored and may
183 * be NULL.
184 * authorization_value_size - The number of bytes in
185 * |authorization_value|.
186 */
187 nvram_result_t (*create_space)(const struct nvram_device* device,
188 uint32_t index, uint64_t size_in_bytes,
189 const nvram_control_t* control_list,
190 uint32_t list_size,
191 const uint8_t* authorization_value,
192 uint32_t authorization_value_size);
193
194 /**
195 * Deletes a space.
196 *
197 * device - The nvram_device instance.
198 * index - The space index.
199 * authorization_value - If the space has the
200 * NV_CONTROL_WRITE_AUTHORIZATION policy,
201 * then this parameter provides the
202 * authorization value. Otherwise, this value
203 * is ignored and may be NULL.
204 * authorization_value_size - The number of bytes in
205 * |authorization_value|.
206 */
207 nvram_result_t (*delete_space)(const struct nvram_device* device,
208 uint32_t index,
209 const uint8_t* authorization_value,
210 uint32_t authorization_value_size);
211
212 /**
213 * Disables any further creation of spaces until the next full device
214 * reset (as in factory reset, not reboot). Subsequent calls to
215 * NV_CreateSpace should return NV_RESULT_OPERATION_DISABLED.
216 *
217 * device - The nvram_device instance.
218 */
219 nvram_result_t (*disable_create)(const struct nvram_device* device);
220
221 /**
222 * Writes the contents of a space. If the space is configured with
223 * NV_CONTROL_WRITE_EXTEND then the input data is used to extend the
224 * current data.
225 *
226 * device - The nvram_device instance.
227 * index - The space index.
228 * buffer - The data to write.
229 * buffer_size - The number of bytes in |buffer|. If this is less
230 * than the size of the space, the remaining bytes
231 * will be set to 0x00. If this is more than the size
232 * of the space, returns NV_RESULT_INVALID_PARAMETER.
233 * authorization_value - If the space has the
234 * NV_CONTROL_WRITE_AUTHORIZATION policy,
235 * then this parameter provides the
236 * authorization value. Otherwise, this value
237 * is ignored and may be NULL.
238 * authorization_value_size - The number of bytes in
239 * |authorization_value|.
240 */
241 nvram_result_t (*write_space)(const struct nvram_device* device,
242 uint32_t index, const uint8_t* buffer,
243 uint64_t buffer_size,
244 const uint8_t* authorization_value,
245 uint32_t authorization_value_size);
246
247 /**
248 * Reads the contents of a space. If the space has never been
249 * written, all bytes read will be 0x00.
250 *
251 * device - The nvram_device instance.
252 * index - The space index.
253 * num_bytes_to_read - The number of bytes to read; |buffer| must
254 * be large enough to hold this many bytes. If
255 * this is more than the size of the space, the
256 * entire space is read. If this is less than
257 * the size of the space, the first bytes in
258 * the space are read.
259 * authorization_value - If the space has the
260 * NV_CONTROL_READ_AUTHORIZATION policy, then
261 * this parameter provides the authorization
262 * value. Otherwise, this value is ignored
263 * and may be NULL.
264 * authorization_value_size - The number of bytes in
265 * |authorization_value|.
266 * buffer - Receives the data read from the space. Must be at least
267 * |num_bytes_to_read| bytes in size.
268 * bytes_read - The number of bytes read. If NV_RESULT_SUCCESS is
269 * returned this will be set to the smaller of
270 * |num_bytes_to_read| or the size of the space.
271 */
272 nvram_result_t (*read_space)(const struct nvram_device* device,
273 uint32_t index, uint64_t num_bytes_to_read,
274 const uint8_t* authorization_value,
275 uint32_t authorization_value_size,
276 uint8_t* buffer, uint64_t* bytes_read);
277
278 /**
279 * Enables a write lock for the given space according to its policy.
280 * If the space does not have NV_CONTROL_PERSISTENT_WRITE_LOCK or
281 * NV_CONTROL_BOOT_WRITE_LOCK set then this function has no effect
282 * and may return an error.
283 *
284 * device - The nvram_device instance.
285 * index - The space index.
286 * authorization_value - If the space has the
287 * NV_CONTROL_WRITE_AUTHORIZATION policy,
288 * then this parameter provides the
289 * authorization value. Otherwise, this value
290 * is ignored and may be NULL.
291 * authorization_value_size - The number of bytes in
292 * |authorization_value|.
293 */
294 nvram_result_t (*enable_write_lock)(const struct nvram_device* device,
295 uint32_t index,
296 const uint8_t* authorization_value,
297 uint32_t authorization_value_size);
298
299 /**
300 * Enables a read lock for the given space according to its policy.
301 * If the space does not have NV_CONTROL_BOOT_READ_LOCK set then this
302 * function has no effect and may return an error.
303 *
304 * device - The nvram_device instance.
305 * index - The space index.
306 * authorization_value - If the space has the
307 * NV_CONTROL_READ_AUTHORIZATION policy, then
308 * this parameter provides the authorization
309 * value. (Note that there is no requirement
310 * for write access in order to lock for
311 * reading. A read lock is always volatile.)
312 * Otherwise, this value is ignored and may
313 * be NULL.
314 * authorization_value_size - The number of bytes in
315 * |authorization_value|.
316 */
317 nvram_result_t (*enable_read_lock)(const struct nvram_device* device,
318 uint32_t index,
319 const uint8_t* authorization_value,
320 uint32_t authorization_value_size);
321 };
322
323 typedef struct nvram_device nvram_device_t;
324
325 /* Convenience API for opening and closing nvram devices. */
nvram_open(const struct hw_module_t * module,nvram_device_t ** device)326 static inline int nvram_open(const struct hw_module_t* module,
327 nvram_device_t** device) {
328 return module->methods->open(module, NVRAM_HARDWARE_DEVICE_ID,
329 TO_HW_DEVICE_T_OPEN(device));
330 }
331
nvram_close(nvram_device_t * device)332 static inline int nvram_close(nvram_device_t* device) {
333 return device->common.close(&device->common);
334 }
335
336 __END_DECLS
337
338 #endif // ANDROID_HARDWARE_NVRAM_H
339