/* * Copyright (C) 2015 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef ANDROID_HARDWARE_NVRAM_H #define ANDROID_HARDWARE_NVRAM_H #include #include #include __BEGIN_DECLS /* The id of this module. */ #define NVRAM_HARDWARE_MODULE_ID "nvram" #define NVRAM_HARDWARE_DEVICE_ID "nvram-dev" /* The version of this module. */ #define NVRAM_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) #define NVRAM_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION(0, 1) /* Values returned by nvram_device methods. */ typedef uint32_t nvram_result_t; const nvram_result_t NV_RESULT_SUCCESS = 0; const nvram_result_t NV_RESULT_INTERNAL_ERROR = 1; const nvram_result_t NV_RESULT_ACCESS_DENIED = 2; const nvram_result_t NV_RESULT_INVALID_PARAMETER = 3; const nvram_result_t NV_RESULT_SPACE_DOES_NOT_EXIST = 4; const nvram_result_t NV_RESULT_SPACE_ALREADY_EXISTS = 5; const nvram_result_t NV_RESULT_OPERATION_DISABLED = 6; /* Values describing available access controls. */ typedef uint32_t nvram_control_t; const nvram_control_t NV_CONTROL_PERSISTENT_WRITE_LOCK = 1; const nvram_control_t NV_CONTROL_BOOT_WRITE_LOCK = 2; const nvram_control_t NV_CONTROL_BOOT_READ_LOCK = 3; const nvram_control_t NV_CONTROL_WRITE_AUTHORIZATION = 4; const nvram_control_t NV_CONTROL_READ_AUTHORIZATION = 5; const nvram_control_t NV_CONTROL_WRITE_EXTEND = 6; const uint32_t NV_UNLIMITED_SPACES = 0xFFFFFFFF; struct nvram_module { /** * Common methods of the nvram_module. This *must* be the first member of * nvram_module as users of this structure will cast a hw_module_t to * nvram_module pointer in contexts where it's known the hw_module_t * references a nvram_module. */ hw_module_t common; /* There are no module methods other than the common ones. */ }; struct nvram_device { /** * Common methods of the nvram_device. This *must* be the first member of * nvram_device as users of this structure will cast a hw_device_t to * nvram_device pointer in contexts where it's known the hw_device_t * references a nvram_device. */ struct hw_device_t common; /** * Outputs the total number of bytes available in NVRAM. This will * always be at least 2048. If an implementation does not know the * total size it may provide an estimate or 2048. * * device - The nvram_device instance. * total_size - Receives the output. Cannot be NULL. */ nvram_result_t (*get_total_size_in_bytes)(const struct nvram_device* device, uint64_t* total_size); /** * Outputs the unallocated number of bytes available in NVRAM. If an * implementation does not know the available size it may provide an * estimate or the total size. * * device - The nvram_device instance. * available_size - Receives the output. Cannot be NULL. */ nvram_result_t (*get_available_size_in_bytes)( const struct nvram_device* device, uint64_t* available_size); /** * Outputs the maximum total number of spaces that may be allocated. * This will always be at least 8. Outputs NV_UNLIMITED_SPACES if any * number of spaces are supported (limited only to available NVRAM * bytes). * * device - The nvram_device instance. * num_spaces - Receives the output. Cannot be NULL. */ nvram_result_t (*get_max_spaces)(const struct nvram_device* device, uint32_t* num_spaces); /** * Outputs a list of created space indices. If |max_list_size| is * 0, only |list_size| is populated. * * device - The nvram_device instance. * max_list_size - The number of items in the |space_index_list| * array. * space_index_list - Receives the list of created spaces up to the * given |max_list_size|. May be NULL if * |max_list_size| is 0. * list_size - Receives the number of items populated in * |space_index_list|, or the number of items available * if |space_index_list| is NULL. */ nvram_result_t (*get_space_list)(const struct nvram_device* device, uint32_t max_list_size, uint32_t* space_index_list, uint32_t* list_size); /** * Outputs the size, in bytes, of a given space. * * device - The nvram_device instance. * index - The space index. * size - Receives the output. Cannot be NULL. */ nvram_result_t (*get_space_size)(const struct nvram_device* device, uint32_t index, uint64_t* size); /** * Outputs the list of controls associated with a given space. * * device - The nvram_device instance. * index - The space index. * max_list_size - The number of items in the |control_list| array. * control_list - Receives the list of controls up to the given * |max_list_size|. May be NULL if |max_list_size| * is 0. * list_size - Receives the number of items populated in * |control_list|, or the number of items available if * |control_list| is NULL. */ nvram_result_t (*get_space_controls)(const struct nvram_device* device, uint32_t index, uint32_t max_list_size, nvram_control_t* control_list, uint32_t* list_size); /** * Outputs whether locks are enabled for the given space. When a lock * is enabled, the operation is disabled and any attempt to perform that * operation will result in NV_RESULT_OPERATION_DISABLED. * * device - The nvram_device instance. * index - The space index. * write_lock_enabled - Will be set to non-zero iff write * operations are currently disabled. * read_lock_enabled - Will be set to non-zero iff read operations * are currently disabled. */ nvram_result_t (*is_space_locked)(const struct nvram_device* device, uint32_t index, int* write_lock_enabled, int* read_lock_enabled); /** * Creates a new space with the given index, size, controls, and * authorization value. * * device - The nvram_device instance. * index - An index for the new space. The index can be any 32-bit * value but must not already be assigned to an existing * space. * size_in_bytes - The number of bytes to allocate for the space. * control_list - An array of controls to enforce for the space. * list_size - The number of items in |control_list|. * authorization_value - If |control_list| contains * NV_CONTROL_READ_AUTHORIZATION and / or * NV_CONTROL_WRITE_AUTHORIZATION, then this * parameter provides the authorization value * for these policies (if both controls are * set then this value applies to both). * Otherwise, this value is ignored and may * be NULL. * authorization_value_size - The number of bytes in * |authorization_value|. */ nvram_result_t (*create_space)(const struct nvram_device* device, uint32_t index, uint64_t size_in_bytes, const nvram_control_t* control_list, uint32_t list_size, const uint8_t* authorization_value, uint32_t authorization_value_size); /** * Deletes a space. * * device - The nvram_device instance. * index - The space index. * authorization_value - If the space has the * NV_CONTROL_WRITE_AUTHORIZATION policy, * then this parameter provides the * authorization value. Otherwise, this value * is ignored and may be NULL. * authorization_value_size - The number of bytes in * |authorization_value|. */ nvram_result_t (*delete_space)(const struct nvram_device* device, uint32_t index, const uint8_t* authorization_value, uint32_t authorization_value_size); /** * Disables any further creation of spaces until the next full device * reset (as in factory reset, not reboot). Subsequent calls to * NV_CreateSpace should return NV_RESULT_OPERATION_DISABLED. * * device - The nvram_device instance. */ nvram_result_t (*disable_create)(const struct nvram_device* device); /** * Writes the contents of a space. If the space is configured with * NV_CONTROL_WRITE_EXTEND then the input data is used to extend the * current data. * * device - The nvram_device instance. * index - The space index. * buffer - The data to write. * buffer_size - The number of bytes in |buffer|. If this is less * than the size of the space, the remaining bytes * will be set to 0x00. If this is more than the size * of the space, returns NV_RESULT_INVALID_PARAMETER. * authorization_value - If the space has the * NV_CONTROL_WRITE_AUTHORIZATION policy, * then this parameter provides the * authorization value. Otherwise, this value * is ignored and may be NULL. * authorization_value_size - The number of bytes in * |authorization_value|. */ nvram_result_t (*write_space)(const struct nvram_device* device, uint32_t index, const uint8_t* buffer, uint64_t buffer_size, const uint8_t* authorization_value, uint32_t authorization_value_size); /** * Reads the contents of a space. If the space has never been * written, all bytes read will be 0x00. * * device - The nvram_device instance. * index - The space index. * num_bytes_to_read - The number of bytes to read; |buffer| must * be large enough to hold this many bytes. If * this is more than the size of the space, the * entire space is read. If this is less than * the size of the space, the first bytes in * the space are read. * authorization_value - If the space has the * NV_CONTROL_READ_AUTHORIZATION policy, then * this parameter provides the authorization * value. Otherwise, this value is ignored * and may be NULL. * authorization_value_size - The number of bytes in * |authorization_value|. * buffer - Receives the data read from the space. Must be at least * |num_bytes_to_read| bytes in size. * bytes_read - The number of bytes read. If NV_RESULT_SUCCESS is * returned this will be set to the smaller of * |num_bytes_to_read| or the size of the space. */ nvram_result_t (*read_space)(const struct nvram_device* device, uint32_t index, uint64_t num_bytes_to_read, const uint8_t* authorization_value, uint32_t authorization_value_size, uint8_t* buffer, uint64_t* bytes_read); /** * Enables a write lock for the given space according to its policy. * If the space does not have NV_CONTROL_PERSISTENT_WRITE_LOCK or * NV_CONTROL_BOOT_WRITE_LOCK set then this function has no effect * and may return an error. * * device - The nvram_device instance. * index - The space index. * authorization_value - If the space has the * NV_CONTROL_WRITE_AUTHORIZATION policy, * then this parameter provides the * authorization value. Otherwise, this value * is ignored and may be NULL. * authorization_value_size - The number of bytes in * |authorization_value|. */ nvram_result_t (*enable_write_lock)(const struct nvram_device* device, uint32_t index, const uint8_t* authorization_value, uint32_t authorization_value_size); /** * Enables a read lock for the given space according to its policy. * If the space does not have NV_CONTROL_BOOT_READ_LOCK set then this * function has no effect and may return an error. * * device - The nvram_device instance. * index - The space index. * authorization_value - If the space has the * NV_CONTROL_READ_AUTHORIZATION policy, then * this parameter provides the authorization * value. (Note that there is no requirement * for write access in order to lock for * reading. A read lock is always volatile.) * Otherwise, this value is ignored and may * be NULL. * authorization_value_size - The number of bytes in * |authorization_value|. */ nvram_result_t (*enable_read_lock)(const struct nvram_device* device, uint32_t index, const uint8_t* authorization_value, uint32_t authorization_value_size); }; typedef struct nvram_device nvram_device_t; /* Convenience API for opening and closing nvram devices. */ static inline int nvram_open(const struct hw_module_t* module, nvram_device_t** device) { return module->methods->open(module, NVRAM_HARDWARE_DEVICE_ID, (struct hw_device_t**)device); } static inline int nvram_close(nvram_device_t* device) { return device->common.close(&device->common); } __END_DECLS #endif // ANDROID_HARDWARE_NVRAM_H