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