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. */ 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 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
