Merge "Add header for new NVRAM HAL."
am: 6b09c49633
* commit '6b09c49633d9e86c1bf888e440c8601f04bfa10c':
Add header for new NVRAM HAL.
This commit is contained in:
Darren Krahn
android-build-merger
commit
330ee96ad9
1 changed files with 348 additions and 0 deletions
348
include/hardware/nvram.h
Normal file
348
include/hardware/nvram.h
Normal file
|
|
@ -0,0 +1,348 @@
|
|||
/*
|
||||
* 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 <stdint.h>
|
||||
#include <sys/cdefs.h>
|
||||
|
||||
#include <hardware/hardware.h>
|
||||
|
||||
__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,
|
||||
nvram_control_t* control_list,
|
||||
uint32_t list_size,
|
||||
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, 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,
|
||||
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,
|
||||
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,
|
||||
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,
|
||||
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
|
||||
Loading…
Reference in a new issue