Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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> |
Mattias Nissler | d2d0b67 | 2016-02-04 10:00:28 +0100 | [diff] [blame] | 24 | #include <hardware/nvram_defs.h> |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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) |
Darren Krahn | deda044 | 2016-03-03 14:10:06 -0800 | [diff] [blame] | 34 | #define NVRAM_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION(1, 1) |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 35 | |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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 | /** |
Darren Krahn | deda044 | 2016-03-03 14:10:06 -0800 | [diff] [blame] | 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 | /** |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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, |
Darren Krahn | ab3ea64 | 2016-02-04 13:57:27 -0800 | [diff] [blame] | 189 | const nvram_control_t* control_list, |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 190 | uint32_t list_size, |
Darren Krahn | ab3ea64 | 2016-02-04 13:57:27 -0800 | [diff] [blame] | 191 | const uint8_t* authorization_value, |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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, |
Darren Krahn | ab3ea64 | 2016-02-04 13:57:27 -0800 | [diff] [blame] | 208 | uint32_t index, |
| 209 | const uint8_t* authorization_value, |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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, |
Darren Krahn | ab3ea64 | 2016-02-04 13:57:27 -0800 | [diff] [blame] | 244 | const uint8_t* authorization_value, |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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, |
Darren Krahn | ab3ea64 | 2016-02-04 13:57:27 -0800 | [diff] [blame] | 274 | const uint8_t* authorization_value, |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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, |
Darren Krahn | ab3ea64 | 2016-02-04 13:57:27 -0800 | [diff] [blame] | 296 | const uint8_t* authorization_value, |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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, |
Darren Krahn | ab3ea64 | 2016-02-04 13:57:27 -0800 | [diff] [blame] | 319 | const uint8_t* authorization_value, |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 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. */ |
| 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, |
Colin Cross | cc8d9f9 | 2016-10-06 16:44:23 -0700 | [diff] [blame] | 329 | TO_HW_DEVICE_T_OPEN(device)); |
Darren Krahn | a59143b | 2015-12-18 11:30:18 -0800 | [diff] [blame] | 330 | } |
| 331 | |
| 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 |