tequilaOS/platform_hardware_libhardware
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
platform_hardware_libhardware/include/hardware/nvram.h
Darren Krahn deda044730 nvram: Add a get_max_space_size_in_bytes method. 
This is useful for the Access-Controlled NVRAM HAL because
implementations may be able to achieve atomic writes if they are able to
limit the maximum space size. This method allows the module to report
that it is imposing such a limit.

BUG=27480753

Change-Id: Ia70f459d7d5fca894e52310ddb2cdcbb51bd8364
2016-03-08 15:43:41 -08:00

338 lines
15 KiB
C
Raw Blame History

/*
* 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>
#include <hardware/nvram_defs.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_1_1 HARDWARE_DEVICE_API_VERSION(1, 1)
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 number of bytes that can be allocated for a single
* space. This will always be at least 32. If an implementation does not
* limit the maximum size it may provide the total size.
*
* device - The nvram_device instance.
* max_space_size - Receives the output. Cannot be NULL.
*/
nvram_result_t (*get_max_space_size_in_bytes)(
const struct nvram_device* device, uint64_t* max_space_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
Reference in a new issue View git blame Copy permalink