diff options
| author | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | 2024-05-10 17:37:54 +0000 |
|---|---|---|
| committer | Gerrit Code Review <noreply-gerritcodereview@google.com> | 2024-05-10 17:37:54 +0000 |
| commit | 77845d46cb6fac7bec4515694484d783b241f67c (patch) | |
| tree | 85be1a592eccf39138a767f250979f12b9015630 | |
| parent | ab7decd74d6dd72e96f0ca514bb318718b9e3f7b (diff) | |
| parent | e58aba44bd945aa96d98c27450af2757095caea0 (diff) | |
| download | libhardware-busytown-mac-infra-release.tar.gz | |
Merge "Snap for 11819167 from 8e9c9d1220571fd8762887e44cde426485d9cd86 to busytown-mac-infra-release" into busytown-mac-infra-releasebusytown-mac-infra-release
111 files changed, 24352 insertions, 24030 deletions
@@ -32,38 +32,54 @@ license { cc_library_headers { name: "libhardware_headers", + header_libs: [ "libaudio_system_headers", "libsystem_headers", "libcutils_headers", - "libbluetooth-types-header", ], export_header_lib_headers: [ "libaudio_system_headers", "libsystem_headers", "libcutils_headers", - "libbluetooth-types-header", ], - export_include_dirs: ["include"], recovery_available: true, vendor_available: true, // TODO(b/153609531): remove when no longer needed. native_bridge_supported: true, + + // There are three include directories currently: + // - include: this directory is the original location of libhardware headers. It is globally + // available (even if you do not depend on libhardware). Many locations also use + // LOCAL_C_INCLUDES or include_dirs to access these from a global namespace. These processes + // should replace this dependency with a direct dependency on libhardware(_headers)?. + // - include_all: this directory is for system and vendor include files. Gradually, the number of + // files here should be reduced to 0 by moving them to vendor as old code is phased out. + // - include_vendor: this directory is the current designated resting place for these headers. + // They are kept around to try to help insure existing codebases can function. + export_include_dirs: ["include_all"], + target: { recovery: { exclude_header_libs: [ "libaudio_system_headers", - "libbluetooth-types-header", ], }, windows: { enabled: true, }, + vendor: { + override_export_include_dirs: [ + "include_all", + "include_vendor", + ], + }, }, apex_available: [ "//apex_available:platform", "com.android.btservices", + "com.android.media", "com.android.media.swcodec", ], min_sdk_version: "29", @@ -76,6 +92,7 @@ cc_library_shared { srcs: ["hardware.c"], shared_libs: [ + "libapexsupport", "libcutils", "liblog", "libvndksupport", @@ -92,16 +109,24 @@ cc_library_shared { host_supported: true, recovery_available: true, vendor_available: true, - vndk: { - enabled: true, - support_system_process: true, - }, + double_loadable: true, target: { host: { - exclude_shared_libs: ["libvndksupport"], + exclude_shared_libs: [ + "libapexsupport", + "libvndksupport", + ], }, recovery: { - exclude_shared_libs: ["libvndksupport"], + exclude_shared_libs: [ + "libapexsupport", + "libvndksupport", + ], + }, + non_apex: { + exclude_shared_libs: [ + "libapexsupport", + ], }, }, min_sdk_version: "29", @@ -34,17 +34,21 @@ #include <vndksupport/linker.h> #endif +#ifdef __ANDROID_APEX__ +#include <android/apexsupport.h> +#endif + /** Base path of the hal modules */ #if defined(__LP64__) -#define HAL_LIBRARY_PATH1 "/system/lib64/hw" -#define HAL_LIBRARY_PATH2 "/vendor/lib64/hw" -#define HAL_LIBRARY_PATH3 "/odm/lib64/hw" +#define HAL_LIBRARY_SUBDIR "lib64/hw" #else -#define HAL_LIBRARY_PATH1 "/system/lib/hw" -#define HAL_LIBRARY_PATH2 "/vendor/lib/hw" -#define HAL_LIBRARY_PATH3 "/odm/lib/hw" +#define HAL_LIBRARY_SUBDIR "lib/hw" #endif +#define HAL_LIBRARY_PATH1 "/system/" HAL_LIBRARY_SUBDIR +#define HAL_LIBRARY_PATH2 "/vendor/" HAL_LIBRARY_SUBDIR +#define HAL_LIBRARY_PATH3 "/odm/" HAL_LIBRARY_SUBDIR + /** * There are a set of variant filename for modules. The form of the filename * is "<MODULE_ID>.variant.so" so for the led module the Dream variants @@ -79,7 +83,7 @@ static int load(const char *id, int status = -EINVAL; void *handle = NULL; struct hw_module_t *hmi = NULL; -#ifdef __ANDROID_VNDK__ +#if defined(__ANDROID_VNDK__) || defined(__ANDROID_APEX__) const bool try_system = false; #else const bool try_system = true; @@ -97,7 +101,7 @@ static int load(const char *id, */ handle = dlopen(path, RTLD_NOW); } else { -#if defined(__ANDROID_RECOVERY__) || !defined(__ANDROID__) +#if defined(__ANDROID_RECOVERY__) || !defined(__ANDROID__) || defined(__ANDROID_APEX__) handle = dlopen(path, RTLD_NOW); #else handle = android_load_sphal_library(path, RTLD_NOW); @@ -151,7 +155,7 @@ static int load(const char *id, /* * If path is in in_path. */ -static bool path_in_path(const char *path, const char *in_path) { +static bool __attribute__ ((unused)) path_in_path(const char *path, const char *in_path) { char real_path[PATH_MAX]; if (realpath(path, real_path) == NULL) return false; @@ -174,6 +178,22 @@ static bool path_in_path(const char *path, const char *in_path) { static int hw_module_exists(char *path, size_t path_len, const char *name, const char *subname) { +#ifdef __ANDROID_APEX__ + // When used in VAPEX, it should look only into the same APEX because + // libhardware modules don't provide ABI stability. +#if __ANDROID_VENDOR_API__ >= 202404 + AApexInfo *apex_info; + if (AApexInfo_create(&apex_info) == AAPEXINFO_OK) { + snprintf(path, path_len, "/apex/%s/%s/%s.%s.so", + AApexInfo_getName(apex_info), HAL_LIBRARY_SUBDIR, name, subname); + AApexInfo_destroy(apex_info); + if (access(path, R_OK) == 0) + return 0; + } +#else // __ANDROID_VENDOR_API__ + ALOGE("hw_module_exists: libapexsupport is not supported in %d.", __ANDROID_VENDOR_API__); +#endif // __ANDROID_VENDOR_API__ +#else // __ANDROID_APEX__ snprintf(path, path_len, "%s/%s.%s.so", HAL_LIBRARY_PATH3, name, subname); if (path_in_path(path, HAL_LIBRARY_PATH3) && access(path, R_OK) == 0) @@ -191,6 +211,8 @@ static int hw_module_exists(char *path, size_t path_len, const char *name, return 0; #endif +#endif // __ANDROID_APEX__ + return -ENOENT; } diff --git a/include/hardware/audio.h b/include/hardware/audio.h index daaa16f1..7e25631f 100644..120000 --- a/include/hardware/audio.h +++ b/include/hardware/audio.h @@ -1,1088 +1 @@ -/* - * Copyright (C) 2011 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_AUDIO_HAL_INTERFACE_H -#define ANDROID_AUDIO_HAL_INTERFACE_H - -#include <stdint.h> -#include <strings.h> -#include <sys/cdefs.h> -#include <sys/types.h> -#include <time.h> - -#include <cutils/bitops.h> - -#include <hardware/hardware.h> -#include <system/audio.h> -#include <hardware/audio_effect.h> - -__BEGIN_DECLS - -/** - * The id of this module - */ -#define AUDIO_HARDWARE_MODULE_ID "audio" - -/** - * Name of the audio devices to open - */ -#define AUDIO_HARDWARE_INTERFACE "audio_hw_if" - - -/* Use version 0.1 to be compatible with first generation of audio hw module with version_major - * hardcoded to 1. No audio module API change. - */ -#define AUDIO_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) -#define AUDIO_MODULE_API_VERSION_CURRENT AUDIO_MODULE_API_VERSION_0_1 - -/* First generation of audio devices had version hardcoded to 0. all devices with versions < 1.0 - * will be considered of first generation API. - */ -#define AUDIO_DEVICE_API_VERSION_0_0 HARDWARE_DEVICE_API_VERSION(0, 0) -#define AUDIO_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) -#define AUDIO_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) -#define AUDIO_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0) -#define AUDIO_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1) -#define AUDIO_DEVICE_API_VERSION_3_2 HARDWARE_DEVICE_API_VERSION(3, 2) -#define AUDIO_DEVICE_API_VERSION_CURRENT AUDIO_DEVICE_API_VERSION_3_2 -/* Minimal audio HAL version supported by the audio framework */ -#define AUDIO_DEVICE_API_VERSION_MIN AUDIO_DEVICE_API_VERSION_2_0 - -/**************************************/ - -/** - * standard audio parameters that the HAL may need to handle - */ - -/** - * audio device parameters - */ - -/* TTY mode selection */ -#define AUDIO_PARAMETER_KEY_TTY_MODE "tty_mode" -#define AUDIO_PARAMETER_VALUE_TTY_OFF "tty_off" -#define AUDIO_PARAMETER_VALUE_TTY_VCO "tty_vco" -#define AUDIO_PARAMETER_VALUE_TTY_HCO "tty_hco" -#define AUDIO_PARAMETER_VALUE_TTY_FULL "tty_full" - -/* Hearing Aid Compatibility - Telecoil (HAC-T) mode on/off */ -#define AUDIO_PARAMETER_KEY_HAC "HACSetting" -#define AUDIO_PARAMETER_VALUE_HAC_ON "ON" -#define AUDIO_PARAMETER_VALUE_HAC_OFF "OFF" - -/* A2DP sink address set by framework */ -#define AUDIO_PARAMETER_A2DP_SINK_ADDRESS "a2dp_sink_address" - -/* A2DP source address set by framework */ -#define AUDIO_PARAMETER_A2DP_SOURCE_ADDRESS "a2dp_source_address" - -/* Bluetooth SCO wideband */ -#define AUDIO_PARAMETER_KEY_BT_SCO_WB "bt_wbs" - -/* BT SCO headset name for debug */ -#define AUDIO_PARAMETER_KEY_BT_SCO_HEADSET_NAME "bt_headset_name" - -/* BT SCO HFP control */ -#define AUDIO_PARAMETER_KEY_HFP_ENABLE "hfp_enable" -#define AUDIO_PARAMETER_KEY_HFP_SET_SAMPLING_RATE "hfp_set_sampling_rate" -#define AUDIO_PARAMETER_KEY_HFP_VOLUME "hfp_volume" - -/* Set screen orientation */ -#define AUDIO_PARAMETER_KEY_ROTATION "rotation" - -/** - * audio stream parameters - */ - -/* Enable AANC */ -#define AUDIO_PARAMETER_KEY_AANC "aanc_enabled" - -/**************************************/ - -/* common audio stream parameters and operations */ -struct audio_stream { - - /** - * Return the sampling rate in Hz - eg. 44100. - */ - uint32_t (*get_sample_rate)(const struct audio_stream *stream); - - /* currently unused - use set_parameters with key - * AUDIO_PARAMETER_STREAM_SAMPLING_RATE - */ - int (*set_sample_rate)(struct audio_stream *stream, uint32_t rate); - - /** - * Return size of input/output buffer in bytes for this stream - eg. 4800. - * It should be a multiple of the frame size. See also get_input_buffer_size. - */ - size_t (*get_buffer_size)(const struct audio_stream *stream); - - /** - * Return the channel mask - - * e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO - */ - audio_channel_mask_t (*get_channels)(const struct audio_stream *stream); - - /** - * Return the audio format - e.g. AUDIO_FORMAT_PCM_16_BIT - */ - audio_format_t (*get_format)(const struct audio_stream *stream); - - /* currently unused - use set_parameters with key - * AUDIO_PARAMETER_STREAM_FORMAT - */ - int (*set_format)(struct audio_stream *stream, audio_format_t format); - - /** - * Put the audio hardware input/output into standby mode. - * Driver should exit from standby mode at the next I/O operation. - * Returns 0 on success and <0 on failure. - */ - int (*standby)(struct audio_stream *stream); - - /** dump the state of the audio input/output device */ - int (*dump)(const struct audio_stream *stream, int fd); - - /** Return the set of device(s) which this stream is connected to */ - audio_devices_t (*get_device)(const struct audio_stream *stream); - - /** - * Currently unused - set_device() corresponds to set_parameters() with key - * AUDIO_PARAMETER_STREAM_ROUTING for both input and output. - * AUDIO_PARAMETER_STREAM_INPUT_SOURCE is an additional information used by - * input streams only. - */ - int (*set_device)(struct audio_stream *stream, audio_devices_t device); - - /** - * set/get audio stream parameters. The function accepts a list of - * parameter key value pairs in the form: key1=value1;key2=value2;... - * - * Some keys are reserved for standard parameters (See AudioParameter class) - * - * If the implementation does not accept a parameter change while - * the output is active but the parameter is acceptable otherwise, it must - * return -ENOSYS. - * - * The audio flinger will put the stream in standby and then change the - * parameter value. - */ - int (*set_parameters)(struct audio_stream *stream, const char *kv_pairs); - - /* - * Returns a pointer to a heap allocated string. The caller is responsible - * for freeing the memory for it using free(). - */ - char * (*get_parameters)(const struct audio_stream *stream, - const char *keys); - int (*add_audio_effect)(const struct audio_stream *stream, - effect_handle_t effect); - int (*remove_audio_effect)(const struct audio_stream *stream, - effect_handle_t effect); -}; -typedef struct audio_stream audio_stream_t; - -/* type of asynchronous write callback events. Mutually exclusive */ -typedef enum { - STREAM_CBK_EVENT_WRITE_READY, /* non blocking write completed */ - STREAM_CBK_EVENT_DRAIN_READY, /* drain completed */ - STREAM_CBK_EVENT_ERROR, /* stream hit some error, let AF take action */ -} stream_callback_event_t; - -typedef enum { - STREAM_EVENT_CBK_TYPE_CODEC_FORMAT_CHANGED, /* codec format of the stream changed */ -} stream_event_callback_type_t; - -typedef int (*stream_callback_t)(stream_callback_event_t event, void *param, void *cookie); - -typedef int (*stream_event_callback_t)(stream_event_callback_type_t event, - void *param, void *cookie); - -/* type of drain requested to audio_stream_out->drain(). Mutually exclusive */ -typedef enum { - AUDIO_DRAIN_ALL, /* drain() returns when all data has been played */ - AUDIO_DRAIN_EARLY_NOTIFY /* drain() returns a short time before all data - from the current track has been played to - give time for gapless track switch */ -} audio_drain_type_t; - -typedef struct source_metadata { - size_t track_count; - /** Array of metadata of each track connected to this source. */ - struct playback_track_metadata* tracks; -} source_metadata_t; - -typedef struct sink_metadata { - size_t track_count; - /** Array of metadata of each track connected to this sink. */ - struct record_track_metadata* tracks; -} sink_metadata_t; - -/* HAL version 3.2 and higher only. */ -typedef struct source_metadata_v7 { - size_t track_count; - /** Array of metadata of each track connected to this source. */ - struct playback_track_metadata_v7* tracks; -} source_metadata_v7_t; - -/* HAL version 3.2 and higher only. */ -typedef struct sink_metadata_v7 { - size_t track_count; - /** Array of metadata of each track connected to this sink. */ - struct record_track_metadata_v7* tracks; -} sink_metadata_v7_t; - -/** output stream callback method to indicate changes in supported latency modes */ -typedef void (*stream_latency_mode_callback_t)( - audio_latency_mode_t *modes, size_t num_modes, void *cookie); - -/** - * audio_stream_out is the abstraction interface for the audio output hardware. - * - * It provides information about various properties of the audio output - * hardware driver. - */ -struct audio_stream_out { - /** - * Common methods of the audio stream out. This *must* be the first member of audio_stream_out - * as users of this structure will cast a audio_stream to audio_stream_out pointer in contexts - * where it's known the audio_stream references an audio_stream_out. - */ - struct audio_stream common; - - /** - * Return the audio hardware driver estimated latency in milliseconds. - */ - uint32_t (*get_latency)(const struct audio_stream_out *stream); - - /** - * Use this method in situations where audio mixing is done in the - * hardware. This method serves as a direct interface with hardware, - * allowing you to directly set the volume as apposed to via the framework. - * This method might produce multiple PCM outputs or hardware accelerated - * codecs, such as MP3 or AAC. - */ - int (*set_volume)(struct audio_stream_out *stream, float left, float right); - - /** - * Write audio buffer to driver. Returns number of bytes written, or a - * negative status_t. If at least one frame was written successfully prior to the error, - * it is suggested that the driver return that successful (short) byte count - * and then return an error in the subsequent call. - * - * If set_callback() has previously been called to enable non-blocking mode - * the write() is not allowed to block. It must write only the number of - * bytes that currently fit in the driver/hardware buffer and then return - * this byte count. If this is less than the requested write size the - * callback function must be called when more space is available in the - * driver/hardware buffer. - */ - ssize_t (*write)(struct audio_stream_out *stream, const void* buffer, - size_t bytes); - - /* return the number of audio frames written by the audio dsp to DAC since - * the output has exited standby - */ - int (*get_render_position)(const struct audio_stream_out *stream, - uint32_t *dsp_frames); - - /** - * get the local time at which the next write to the audio driver will be presented. - * The units are microseconds, where the epoch is decided by the local audio HAL. - */ - int (*get_next_write_timestamp)(const struct audio_stream_out *stream, - int64_t *timestamp); - - /** - * set the callback function for notifying completion of non-blocking - * write and drain. - * Calling this function implies that all future write() and drain() - * must be non-blocking and use the callback to signal completion. - */ - int (*set_callback)(struct audio_stream_out *stream, - stream_callback_t callback, void *cookie); - - /** - * Notifies to the audio driver to stop playback however the queued buffers are - * retained by the hardware. Useful for implementing pause/resume. Empty implementation - * if not supported however should be implemented for hardware with non-trivial - * latency. In the pause state audio hardware could still be using power. User may - * consider calling suspend after a timeout. - * - * Implementation of this function is mandatory for offloaded playback. - */ - int (*pause)(struct audio_stream_out* stream); - - /** - * Notifies to the audio driver to resume playback following a pause. - * Returns error if called without matching pause. - * - * Implementation of this function is mandatory for offloaded playback. - */ - int (*resume)(struct audio_stream_out* stream); - - /** - * Requests notification when data buffered by the driver/hardware has - * been played. If set_callback() has previously been called to enable - * non-blocking mode, the drain() must not block, instead it should return - * quickly and completion of the drain is notified through the callback. - * If set_callback() has not been called, the drain() must block until - * completion. - * If type==AUDIO_DRAIN_ALL, the drain completes when all previously written - * data has been played. - * If type==AUDIO_DRAIN_EARLY_NOTIFY, the drain completes shortly before all - * data for the current track has played to allow time for the framework - * to perform a gapless track switch. - * - * Drain must return immediately on stop() and flush() call - * - * Implementation of this function is mandatory for offloaded playback. - */ - int (*drain)(struct audio_stream_out* stream, audio_drain_type_t type ); - - /** - * Notifies to the audio driver to flush the queued data. Stream must already - * be paused before calling flush(). - * - * Implementation of this function is mandatory for offloaded playback. - */ - int (*flush)(struct audio_stream_out* stream); - - /** - * Return a recent count of the number of audio frames presented to an external observer. - * This excludes frames which have been written but are still in the pipeline. - * The count is not reset to zero when output enters standby. - * Also returns the value of CLOCK_MONOTONIC as of this presentation count. - * The returned count is expected to be 'recent', - * but does not need to be the most recent possible value. - * However, the associated time should correspond to whatever count is returned. - * Example: assume that N+M frames have been presented, where M is a 'small' number. - * Then it is permissible to return N instead of N+M, - * and the timestamp should correspond to N rather than N+M. - * The terms 'recent' and 'small' are not defined. - * They reflect the quality of the implementation. - * - * 3.0 and higher only. - */ - int (*get_presentation_position)(const struct audio_stream_out *stream, - uint64_t *frames, struct timespec *timestamp); - - /** - * Called by the framework to start a stream operating in mmap mode. - * create_mmap_buffer must be called before calling start() - * - * \note Function only implemented by streams operating in mmap mode. - * - * \param[in] stream the stream object. - * \return 0 in case of success. - * -ENOSYS if called out of sequence or on non mmap stream - */ - int (*start)(const struct audio_stream_out* stream); - - /** - * Called by the framework to stop a stream operating in mmap mode. - * Must be called after start() - * - * \note Function only implemented by streams operating in mmap mode. - * - * \param[in] stream the stream object. - * \return 0 in case of success. - * -ENOSYS if called out of sequence or on non mmap stream - */ - int (*stop)(const struct audio_stream_out* stream); - - /** - * Called by the framework to retrieve information on the mmap buffer used for audio - * samples transfer. - * - * \note Function only implemented by streams operating in mmap mode. - * - * \param[in] stream the stream object. - * \param[in] min_size_frames minimum buffer size requested. The actual buffer - * size returned in struct audio_mmap_buffer_info can be larger. - * \param[out] info address at which the mmap buffer information should be returned. - * - * \return 0 if the buffer was allocated. - * -ENODEV in case of initialization error - * -EINVAL if the requested buffer size is too large - * -ENOSYS if called out of sequence (e.g. buffer already allocated) - */ - int (*create_mmap_buffer)(const struct audio_stream_out *stream, - int32_t min_size_frames, - struct audio_mmap_buffer_info *info); - - /** - * Called by the framework to read current read/write position in the mmap buffer - * with associated time stamp. - * - * \note Function only implemented by streams operating in mmap mode. - * - * \param[in] stream the stream object. - * \param[out] position address at which the mmap read/write position should be returned. - * - * \return 0 if the position is successfully returned. - * -ENODATA if the position cannot be retrieved - * -ENOSYS if called before create_mmap_buffer() - */ - int (*get_mmap_position)(const struct audio_stream_out *stream, - struct audio_mmap_position *position); - - /** - * Called when the metadata of the stream's source has been changed. - * @param source_metadata Description of the audio that is played by the clients. - */ - void (*update_source_metadata)(struct audio_stream_out *stream, - const struct source_metadata* source_metadata); - - /** - * Set the callback function for notifying events for an output stream. - */ - int (*set_event_callback)(struct audio_stream_out *stream, - stream_event_callback_t callback, - void *cookie); - - /** - * Called when the metadata of the stream's source has been changed. - * HAL version 3.2 and higher only. - * @param source_metadata Description of the audio that is played by the clients. - */ - void (*update_source_metadata_v7)(struct audio_stream_out *stream, - const struct source_metadata_v7* source_metadata); - - /** - * Returns the Dual Mono mode presentation setting. - * - * \param[in] stream the stream object. - * \param[out] mode current setting of Dual Mono mode. - * - * \return 0 if the position is successfully returned. - * -EINVAL if the arguments are invalid - * -ENOSYS if the function is not available - */ - int (*get_dual_mono_mode)(struct audio_stream_out *stream, audio_dual_mono_mode_t *mode); - - /** - * Sets the Dual Mono mode presentation on the output device. - * - * \param[in] stream the stream object. - * \param[in] mode selected Dual Mono mode. - * - * \return 0 in case of success. - * -EINVAL if the arguments are invalid - * -ENOSYS if the function is not available - */ - int (*set_dual_mono_mode)(struct audio_stream_out *stream, const audio_dual_mono_mode_t mode); - - /** - * Returns the Audio Description Mix level in dB. - * - * \param[in] stream the stream object. - * \param[out] leveldB the current Audio Description Mix Level in dB. - * - * \return 0 in case of success. - * -EINVAL if the arguments are invalid - * -ENOSYS if the function is not available - */ - int (*get_audio_description_mix_level)(struct audio_stream_out *stream, float *leveldB); - - /** - * Sets the Audio Description Mix level in dB. - * - * \param[in] stream the stream object. - * \param[in] leveldB Audio Description Mix Level in dB. - * - * \return 0 in case of success. - * -EINVAL if the arguments are invalid - * -ENOSYS if the function is not available - */ - int (*set_audio_description_mix_level)(struct audio_stream_out *stream, const float leveldB); - - /** - * Retrieves current playback rate parameters. - * - * \param[in] stream the stream object. - * \param[out] playbackRate current playback parameters. - * - * \return 0 in case of success. - * -EINVAL if the arguments are invalid - * -ENOSYS if the function is not available - */ - int (*get_playback_rate_parameters)(struct audio_stream_out *stream, - audio_playback_rate_t *playbackRate); - - /** - * Sets the playback rate parameters that control playback behavior. - * - * \param[in] stream the stream object. - * \param[in] playbackRate playback parameters. - * - * \return 0 in case of success. - * -EINVAL if the arguments are invalid - * -ENOSYS if the function is not available - */ - int (*set_playback_rate_parameters)(struct audio_stream_out *stream, - const audio_playback_rate_t *playbackRate); - - /** - * Indicates the requested latency mode for this output stream. - * - * The requested mode can be one of the modes returned by - * get_recommended_latency_modes(). - * - * Support for this method is optional but mandated on specific spatial audio - * streams indicated by AUDIO_OUTPUT_FLAG_SPATIALIZER flag if they can be routed - * to a BT classic sink. - * - * \param[in] stream the stream object. - * \param[in] mode the requested latency mode. - * \return 0 in case of success. - * -EINVAL if the arguments are invalid - * -ENOSYS if the function is not available - */ - int (*set_latency_mode)(struct audio_stream_out *stream, audio_latency_mode_t mode); - - /** - * Indicates which latency modes are currently supported on this output stream. - * If the transport protocol (e.g Bluetooth A2DP) used by this output stream to reach - * the output device supports variable latency modes, the HAL indicates which - * modes are currently supported. - * The framework can then call setLatencyMode() with one of the supported modes to select - * the desired operation mode. - * - * Support for this method is optional but mandated on specific spatial audio - * streams indicated by AUDIO_OUTPUT_FLAG_SPATIALIZER flag if they can be routed - * to a BT classic sink. - * - * \return 0 in case of success. - * -EINVAL if the arguments are invalid - * -ENOSYS if the function is not available - * \param[in] stream the stream object. - * \param[out] modes the supported latency modes. - * \param[in/out] num_modes as input the maximum number of modes to return, - * as output the actual number of modes returned. - */ - int (*get_recommended_latency_modes)(struct audio_stream_out *stream, - audio_latency_mode_t *modes, size_t *num_modes); - - /** - * Set the callback interface for notifying changes in supported latency modes. - * - * Calling this method with a null pointer will result in clearing a previously set callback. - * - * Support for this method is optional but mandated on specific spatial audio - * streams indicated by AUDIO_OUTPUT_FLAG_SPATIALIZER flag if they can be routed - * to a BT classic sink. - * - * \param[in] stream the stream object. - * \param[in] callback the registered callback or null to unregister. - * \param[in] cookie the context to pass when calling the callback. - * \return 0 in case of success. - * -EINVAL if the arguments are invalid - * -ENOSYS if the function is not available - */ - int (*set_latency_mode_callback)(struct audio_stream_out *stream, - stream_latency_mode_callback_t callback, void *cookie); -}; - -typedef struct audio_stream_out audio_stream_out_t; - -struct audio_stream_in { - /** - * Common methods of the audio stream in. This *must* be the first member of audio_stream_in - * as users of this structure will cast a audio_stream to audio_stream_in pointer in contexts - * where it's known the audio_stream references an audio_stream_in. - */ - struct audio_stream common; - - /** set the input gain for the audio driver. This method is for - * for future use */ - int (*set_gain)(struct audio_stream_in *stream, float gain); - - /** Read audio buffer in from audio driver. Returns number of bytes read, or a - * negative status_t. If at least one frame was read prior to the error, - * read should return that byte count and then return an error in the subsequent call. - */ - ssize_t (*read)(struct audio_stream_in *stream, void* buffer, - size_t bytes); - - /** - * Return the amount of input frames lost in the audio driver since the - * last call of this function. - * Audio driver is expected to reset the value to 0 and restart counting - * upon returning the current value by this function call. - * Such loss typically occurs when the user space process is blocked - * longer than the capacity of audio driver buffers. - * - * Unit: the number of input audio frames - */ - uint32_t (*get_input_frames_lost)(struct audio_stream_in *stream); - - /** - * Return a recent count of the number of audio frames received and - * the clock time associated with that frame count. - * - * frames is the total frame count received. This should be as early in - * the capture pipeline as possible. In general, - * frames should be non-negative and should not go "backwards". - * - * time is the clock MONOTONIC time when frames was measured. In general, - * time should be a positive quantity and should not go "backwards". - * - * The status returned is 0 on success, -ENOSYS if the device is not - * ready/available, or -EINVAL if the arguments are null or otherwise invalid. - */ - int (*get_capture_position)(const struct audio_stream_in *stream, - int64_t *frames, int64_t *time); - - /** - * Called by the framework to start a stream operating in mmap mode. - * create_mmap_buffer must be called before calling start() - * - * \note Function only implemented by streams operating in mmap mode. - * - * \param[in] stream the stream object. - * \return 0 in case off success. - * -ENOSYS if called out of sequence or on non mmap stream - */ - int (*start)(const struct audio_stream_in* stream); - - /** - * Called by the framework to stop a stream operating in mmap mode. - * - * \note Function only implemented by streams operating in mmap mode. - * - * \param[in] stream the stream object. - * \return 0 in case of success. - * -ENOSYS if called out of sequence or on non mmap stream - */ - int (*stop)(const struct audio_stream_in* stream); - - /** - * Called by the framework to retrieve information on the mmap buffer used for audio - * samples transfer. - * - * \note Function only implemented by streams operating in mmap mode. - * - * \param[in] stream the stream object. - * \param[in] min_size_frames minimum buffer size requested. The actual buffer - * size returned in struct audio_mmap_buffer_info can be larger. - * \param[out] info address at which the mmap buffer information should be returned. - * - * \return 0 if the buffer was allocated. - * -ENODEV in case of initialization error - * -EINVAL if the requested buffer size is too large - * -ENOSYS if called out of sequence (e.g. buffer already allocated) - */ - int (*create_mmap_buffer)(const struct audio_stream_in *stream, - int32_t min_size_frames, - struct audio_mmap_buffer_info *info); - - /** - * Called by the framework to read current read/write position in the mmap buffer - * with associated time stamp. - * - * \note Function only implemented by streams operating in mmap mode. - * - * \param[in] stream the stream object. - * \param[out] position address at which the mmap read/write position should be returned. - * - * \return 0 if the position is successfully returned. - * -ENODATA if the position cannot be retreived - * -ENOSYS if called before mmap_read_position() - */ - int (*get_mmap_position)(const struct audio_stream_in *stream, - struct audio_mmap_position *position); - - /** - * Called by the framework to read active microphones - * - * \param[in] stream the stream object. - * \param[out] mic_array Pointer to first element on array with microphone info - * \param[out] mic_count When called, this holds the value of the max number of elements - * allowed in the mic_array. The actual number of elements written - * is returned here. - * if mic_count is passed as zero, mic_array will not be populated, - * and mic_count will return the actual number of active microphones. - * - * \return 0 if the microphone array is successfully filled. - * -ENOSYS if there is an error filling the data - */ - int (*get_active_microphones)(const struct audio_stream_in *stream, - struct audio_microphone_characteristic_t *mic_array, - size_t *mic_count); - - /** - * Called by the framework to instruct the HAL to optimize the capture stream in the - * specified direction. - * - * \param[in] stream the stream object. - * \param[in] direction The direction constant (from audio-base.h) - * MIC_DIRECTION_UNSPECIFIED Don't do any directionality processing of the - * activated microphone(s). - * MIC_DIRECTION_FRONT Optimize capture for audio coming from the screen-side - * of the device. - * MIC_DIRECTION_BACK Optimize capture for audio coming from the side of the - * device opposite the screen. - * MIC_DIRECTION_EXTERNAL Optimize capture for audio coming from an off-device - * microphone. - * \return OK if the call is successful, an error code otherwise. - */ - int (*set_microphone_direction)(const struct audio_stream_in *stream, - audio_microphone_direction_t direction); - - /** - * Called by the framework to specify to the HAL the desired zoom factor for the selected - * microphone(s). - * - * \param[in] stream the stream object. - * \param[in] zoom the zoom factor. - * \return OK if the call is successful, an error code otherwise. - */ - int (*set_microphone_field_dimension)(const struct audio_stream_in *stream, - float zoom); - - /** - * Called when the metadata of the stream's sink has been changed. - * @param sink_metadata Description of the audio that is recorded by the clients. - */ - void (*update_sink_metadata)(struct audio_stream_in *stream, - const struct sink_metadata* sink_metadata); - - /** - * Called when the metadata of the stream's sink has been changed. - * HAL version 3.2 and higher only. - * @param sink_metadata Description of the audio that is recorded by the clients. - */ - void (*update_sink_metadata_v7)(struct audio_stream_in *stream, - const struct sink_metadata_v7* sink_metadata); -}; -typedef struct audio_stream_in audio_stream_in_t; - -/** - * return the frame size (number of bytes per sample). - * - * Deprecated: use audio_stream_out_frame_size() or audio_stream_in_frame_size() instead. - */ -__attribute__((__deprecated__)) -static inline size_t audio_stream_frame_size(const struct audio_stream *s) -{ - size_t chan_samp_sz; - audio_format_t format = s->get_format(s); - - if (audio_has_proportional_frames(format)) { - chan_samp_sz = audio_bytes_per_sample(format); - return popcount(s->get_channels(s)) * chan_samp_sz; - } - - return sizeof(int8_t); -} - -/** - * return the frame size (number of bytes per sample) of an output stream. - */ -static inline size_t audio_stream_out_frame_size(const struct audio_stream_out *s) -{ - size_t chan_samp_sz; - audio_format_t format = s->common.get_format(&s->common); - - if (audio_has_proportional_frames(format)) { - chan_samp_sz = audio_bytes_per_sample(format); - return audio_channel_count_from_out_mask(s->common.get_channels(&s->common)) * chan_samp_sz; - } - - return sizeof(int8_t); -} - -/** - * return the frame size (number of bytes per sample) of an input stream. - */ -static inline size_t audio_stream_in_frame_size(const struct audio_stream_in *s) -{ - size_t chan_samp_sz; - audio_format_t format = s->common.get_format(&s->common); - - if (audio_has_proportional_frames(format)) { - chan_samp_sz = audio_bytes_per_sample(format); - return audio_channel_count_from_in_mask(s->common.get_channels(&s->common)) * chan_samp_sz; - } - - return sizeof(int8_t); -} - -/**********************************************************************/ - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -struct audio_module { - struct hw_module_t common; -}; - -struct audio_hw_device { - /** - * Common methods of the audio device. This *must* be the first member of audio_hw_device - * as users of this structure will cast a hw_device_t to audio_hw_device pointer in contexts - * where it's known the hw_device_t references an audio_hw_device. - */ - struct hw_device_t common; - - /** - * used by audio flinger to enumerate what devices are supported by - * each audio_hw_device implementation. - * - * Return value is a bitmask of 1 or more values of audio_devices_t - * - * NOTE: audio HAL implementations starting with - * AUDIO_DEVICE_API_VERSION_2_0 do not implement this function. - * All supported devices should be listed in audio_policy.conf - * file and the audio policy manager must choose the appropriate - * audio module based on information in this file. - */ - uint32_t (*get_supported_devices)(const struct audio_hw_device *dev); - - /** - * check to see if the audio hardware interface has been initialized. - * returns 0 on success, -ENODEV on failure. - */ - int (*init_check)(const struct audio_hw_device *dev); - - /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */ - int (*set_voice_volume)(struct audio_hw_device *dev, float volume); - - /** - * set the audio volume for all audio activities other than voice call. - * Range between 0.0 and 1.0. If any value other than 0 is returned, - * the software mixer will emulate this capability. - */ - int (*set_master_volume)(struct audio_hw_device *dev, float volume); - - /** - * Get the current master volume value for the HAL, if the HAL supports - * master volume control. AudioFlinger will query this value from the - * primary audio HAL when the service starts and use the value for setting - * the initial master volume across all HALs. HALs which do not support - * this method may leave it set to NULL. - */ - int (*get_master_volume)(struct audio_hw_device *dev, float *volume); - - /** - * set_mode is called when the audio mode changes. AUDIO_MODE_NORMAL mode - * is for standard audio playback, AUDIO_MODE_RINGTONE when a ringtone is - * playing, and AUDIO_MODE_IN_CALL when a call is in progress. - */ - int (*set_mode)(struct audio_hw_device *dev, audio_mode_t mode); - - /* mic mute */ - int (*set_mic_mute)(struct audio_hw_device *dev, bool state); - int (*get_mic_mute)(const struct audio_hw_device *dev, bool *state); - - /* set/get global audio parameters */ - int (*set_parameters)(struct audio_hw_device *dev, const char *kv_pairs); - - /* - * Returns a pointer to a heap allocated string. The caller is responsible - * for freeing the memory for it using free(). - */ - char * (*get_parameters)(const struct audio_hw_device *dev, - const char *keys); - - /* Returns audio input buffer size according to parameters passed or - * 0 if one of the parameters is not supported. - * See also get_buffer_size which is for a particular stream. - */ - size_t (*get_input_buffer_size)(const struct audio_hw_device *dev, - const struct audio_config *config); - - /** This method creates and opens the audio hardware output stream. - * The "address" parameter qualifies the "devices" audio device type if needed. - * The format format depends on the device type: - * - Bluetooth devices use the MAC address of the device in the form "00:11:22:AA:BB:CC" - * - USB devices use the ALSA card and device numbers in the form "card=X;device=Y" - * - Other devices may use a number or any other string. - */ - - int (*open_output_stream)(struct audio_hw_device *dev, - audio_io_handle_t handle, - audio_devices_t devices, - audio_output_flags_t flags, - struct audio_config *config, - struct audio_stream_out **stream_out, - const char *address); - - void (*close_output_stream)(struct audio_hw_device *dev, - struct audio_stream_out* stream_out); - - /** This method creates and opens the audio hardware input stream */ - int (*open_input_stream)(struct audio_hw_device *dev, - audio_io_handle_t handle, - audio_devices_t devices, - struct audio_config *config, - struct audio_stream_in **stream_in, - audio_input_flags_t flags, - const char *address, - audio_source_t source); - - void (*close_input_stream)(struct audio_hw_device *dev, - struct audio_stream_in *stream_in); - - /** - * Called by the framework to read available microphones characteristics. - * - * \param[in] dev the hw_device object. - * \param[out] mic_array Pointer to first element on array with microphone info - * \param[out] mic_count When called, this holds the value of the max number of elements - * allowed in the mic_array. The actual number of elements written - * is returned here. - * if mic_count is passed as zero, mic_array will not be populated, - * and mic_count will return the actual number of microphones in the - * system. - * - * \return 0 if the microphone array is successfully filled. - * -ENOSYS if there is an error filling the data - */ - int (*get_microphones)(const struct audio_hw_device *dev, - struct audio_microphone_characteristic_t *mic_array, - size_t *mic_count); - - /** This method dumps the state of the audio hardware */ - int (*dump)(const struct audio_hw_device *dev, int fd); - - /** - * set the audio mute status for all audio activities. If any value other - * than 0 is returned, the software mixer will emulate this capability. - */ - int (*set_master_mute)(struct audio_hw_device *dev, bool mute); - - /** - * Get the current master mute status for the HAL, if the HAL supports - * master mute control. AudioFlinger will query this value from the primary - * audio HAL when the service starts and use the value for setting the - * initial master mute across all HALs. HALs which do not support this - * method may leave it set to NULL. - */ - int (*get_master_mute)(struct audio_hw_device *dev, bool *mute); - - /** - * Routing control - */ - - /* Creates an audio patch between several source and sink ports. - * The handle is allocated by the HAL and should be unique for this - * audio HAL module. */ - int (*create_audio_patch)(struct audio_hw_device *dev, - unsigned int num_sources, - const struct audio_port_config *sources, - unsigned int num_sinks, - const struct audio_port_config *sinks, - audio_patch_handle_t *handle); - - /* Release an audio patch */ - int (*release_audio_patch)(struct audio_hw_device *dev, - audio_patch_handle_t handle); - - /* Fills the list of supported attributes for a given audio port. - * As input, "port" contains the information (type, role, address etc...) - * needed by the HAL to identify the port. - * As output, "port" contains possible attributes (sampling rates, formats, - * channel masks, gain controllers...) for this port. - */ - int (*get_audio_port)(struct audio_hw_device *dev, - struct audio_port *port); - - /* Set audio port configuration */ - int (*set_audio_port_config)(struct audio_hw_device *dev, - const struct audio_port_config *config); - - /** - * Applies an audio effect to an audio device. - * - * @param dev the audio HAL device context. - * @param device identifies the sink or source device the effect must be applied to. - * "device" is the audio_port_handle_t indicated for the device when - * the audio patch connecting that device was created. - * @param effect effect interface handle corresponding to the effect being added. - * @return retval operation completion status. - */ - int (*add_device_effect)(struct audio_hw_device *dev, - audio_port_handle_t device, effect_handle_t effect); - - /** - * Stops applying an audio effect to an audio device. - * - * @param dev the audio HAL device context. - * @param device identifies the sink or source device this effect was applied to. - * "device" is the audio_port_handle_t indicated for the device when - * the audio patch is created. - * @param effect effect interface handle corresponding to the effect being removed. - * @return retval operation completion status. - */ - int (*remove_device_effect)(struct audio_hw_device *dev, - audio_port_handle_t device, effect_handle_t effect); - - /** - * Fills the list of supported attributes for a given audio port. - * As input, "port" contains the information (type, role, address etc...) - * needed by the HAL to identify the port. - * As output, "port" contains possible attributes (sampling rates, formats, - * channel masks, gain controllers...) for this port. The possible attributes - * are saved as audio profiles, which contains audio format and the supported - * sampling rates and channel masks. - */ - int (*get_audio_port_v7)(struct audio_hw_device *dev, - struct audio_port_v7 *port); - - /** - * Called when the state of the connection of an external device has been changed. - * The "port" parameter is only used as input and besides identifying the device - * port, also may contain additional information such as extra audio descriptors. - * - * HAL version 3.2 and higher only. If the HAL does not implement this method, - * it must leave the function entry as null, or return -ENOSYS. In this case - * the framework will use 'set_parameters', which can only pass the device address. - * - * @param dev the audio HAL device context. - * @param port device port identification and extra information. - * @param connected whether the external device is connected. - * @return retval operation completion status. - */ - int (*set_device_connected_state_v7)(struct audio_hw_device *dev, - struct audio_port_v7 *port, - bool connected); -}; -typedef struct audio_hw_device audio_hw_device_t; - -/** convenience API for opening and closing a supported device */ - -static inline int audio_hw_device_open(const struct hw_module_t* module, - struct audio_hw_device** device) -{ - return module->methods->open(module, AUDIO_HARDWARE_INTERFACE, - TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int audio_hw_device_close(struct audio_hw_device* device) -{ - return device->common.close(&device->common); -} - - -__END_DECLS - -#endif // ANDROID_AUDIO_INTERFACE_H +../../include_all/hardware/audio.h
\ No newline at end of file diff --git a/include/hardware/audio_effect.h b/include/hardware/audio_effect.h index a2809ba6..e557a2df 100644..120000 --- a/include/hardware/audio_effect.h +++ b/include/hardware/audio_effect.h @@ -1,354 +1 @@ -/* - * Copyright (C) 2011 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_AUDIO_EFFECT_H -#define ANDROID_AUDIO_EFFECT_H - -#include <errno.h> -#include <stdint.h> -#include <strings.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <cutils/bitops.h> - -#include <system/audio_effect.h> - - -__BEGIN_DECLS - - -///////////////////////////////////////////////// -// Common Definitions -///////////////////////////////////////////////// - -#define EFFECT_MAKE_API_VERSION(M, m) (((M)<<16) | ((m) & 0xFFFF)) -#define EFFECT_API_VERSION_MAJOR(v) ((v)>>16) -#define EFFECT_API_VERSION_MINOR(v) ((m) & 0xFFFF) - - -///////////////////////////////////////////////// -// Effect control interface -///////////////////////////////////////////////// - -// Effect control interface version 2.0 -#define EFFECT_CONTROL_API_VERSION EFFECT_MAKE_API_VERSION(2,0) - -// Effect control interface structure: effect_interface_s -// The effect control interface is exposed by each effect engine implementation. It consists of -// a set of functions controlling the configuration, activation and process of the engine. -// The functions are grouped in a structure of type effect_interface_s. -// -// Effect control interface handle: effect_handle_t -// The effect_handle_t serves two purposes regarding the implementation of the effect engine: -// - 1 it is the address of a pointer to an effect_interface_s structure where the functions -// of the effect control API for a particular effect are located. -// - 2 it is the address of the context of a particular effect instance. -// A typical implementation in the effect library would define a structure as follows: -// struct effect_module_s { -// const struct effect_interface_s *itfe; -// effect_config_t config; -// effect_context_t context; -// } -// The implementation of EffectCreate() function would then allocate a structure of this -// type and return its address as effect_handle_t -typedef struct effect_interface_s **effect_handle_t; - -// Effect control interface definition -struct effect_interface_s { - //////////////////////////////////////////////////////////////////////////////// - // - // Function: process - // - // Description: Effect process function. Takes input samples as specified - // (count and location) in input buffer descriptor and output processed - // samples as specified in output buffer descriptor. If the buffer descriptor - // is not specified the function must use either the buffer or the - // buffer provider function installed by the EFFECT_CMD_SET_CONFIG command. - // The effect framework will call the process() function after the EFFECT_CMD_ENABLE - // command is received and until the EFFECT_CMD_DISABLE is received. When the engine - // receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully - // and when done indicate that it is OK to stop calling the process() function by - // returning the -ENODATA status. - // - // NOTE: the process() function implementation should be "real-time safe" that is - // it should not perform blocking calls: malloc/free, sleep, read/write/open/close, - // pthread_cond_wait/pthread_mutex_lock... - // - // Input: - // self: handle to the effect interface this function - // is called on. - // inBuffer: buffer descriptor indicating where to read samples to process. - // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. - // - // outBuffer: buffer descriptor indicating where to write processed samples. - // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. - // - // Output: - // returned value: 0 successful operation - // -ENODATA the engine has finished the disable phase and the framework - // can stop calling process() - // -EINVAL invalid interface handle or - // invalid input/output buffer description - //////////////////////////////////////////////////////////////////////////////// - int32_t (*process)(effect_handle_t self, - audio_buffer_t *inBuffer, - audio_buffer_t *outBuffer); - //////////////////////////////////////////////////////////////////////////////// - // - // Function: command - // - // Description: Send a command and receive a response to/from effect engine. - // - // Input: - // self: handle to the effect interface this function - // is called on. - // cmdCode: command code: the command can be a standardized command defined in - // effect_command_e (see below) or a proprietary command. - // cmdSize: size of command in bytes - // pCmdData: pointer to command data - // pReplyData: pointer to reply data - // - // Input/Output: - // replySize: maximum size of reply data as input - // actual size of reply data as output - // - // Output: - // returned value: 0 successful operation - // -EINVAL invalid interface handle or - // invalid command/reply size or format according to - // command code - // The return code should be restricted to indicate problems related to this API - // specification. Status related to the execution of a particular command should be - // indicated as part of the reply field. - // - // *pReplyData updated with command response - // - //////////////////////////////////////////////////////////////////////////////// - int32_t (*command)(effect_handle_t self, - uint32_t cmdCode, - uint32_t cmdSize, - void *pCmdData, - uint32_t *replySize, - void *pReplyData); - //////////////////////////////////////////////////////////////////////////////// - // - // Function: get_descriptor - // - // Description: Returns the effect descriptor - // - // Input: - // self: handle to the effect interface this function - // is called on. - // - // Input/Output: - // pDescriptor: address where to return the effect descriptor. - // - // Output: - // returned value: 0 successful operation. - // -EINVAL invalid interface handle or invalid pDescriptor - // *pDescriptor: updated with the effect descriptor. - // - //////////////////////////////////////////////////////////////////////////////// - int32_t (*get_descriptor)(effect_handle_t self, - effect_descriptor_t *pDescriptor); - //////////////////////////////////////////////////////////////////////////////// - // - // Function: process_reverse - // - // Description: Process reverse stream function. This function is used to pass - // a reference stream to the effect engine. If the engine does not need a reference - // stream, this function pointer can be set to NULL. - // This function would typically implemented by an Echo Canceler. - // - // Input: - // self: handle to the effect interface this function - // is called on. - // inBuffer: buffer descriptor indicating where to read samples to process. - // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. - // - // outBuffer: buffer descriptor indicating where to write processed samples. - // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. - // If the buffer and buffer provider in the configuration received by - // EFFECT_CMD_SET_CONFIG_REVERSE are also NULL, do not return modified reverse - // stream data - // - // Output: - // returned value: 0 successful operation - // -ENODATA the engine has finished the disable phase and the framework - // can stop calling process_reverse() - // -EINVAL invalid interface handle or - // invalid input/output buffer description - //////////////////////////////////////////////////////////////////////////////// - int32_t (*process_reverse)(effect_handle_t self, - audio_buffer_t *inBuffer, - audio_buffer_t *outBuffer); -}; - -///////////////////////////////////////////////// -// Effect library interface -///////////////////////////////////////////////// - -// Effect library interface version 3.0 -// Note that EffectsFactory.c only checks the major version component, so changes to the minor -// number can only be used for fully backwards compatible changes -#define EFFECT_LIBRARY_API_VERSION EFFECT_MAKE_API_VERSION(3,0) -#define EFFECT_LIBRARY_API_VERSION_3_0 EFFECT_MAKE_API_VERSION(3,0) -#define EFFECT_LIBRARY_API_VERSION_3_1 EFFECT_MAKE_API_VERSION(3,1) - -#define AUDIO_EFFECT_LIBRARY_TAG ((('A') << 24) | (('E') << 16) | (('L') << 8) | ('T')) - -// Every effect library must have a data structure named AUDIO_EFFECT_LIBRARY_INFO_SYM -// and the fields of this data structure must begin with audio_effect_library_t - -typedef struct audio_effect_library_s { - // tag must be initialized to AUDIO_EFFECT_LIBRARY_TAG - uint32_t tag; - // Version of the effect library API : 0xMMMMmmmm MMMM: Major, mmmm: minor - uint32_t version; - // Name of this library - const char *name; - // Author/owner/implementor of the library - const char *implementor; - - //////////////////////////////////////////////////////////////////////////////// - // - // Function: create_effect - // - // Description: Creates an effect engine of the specified implementation uuid and - // returns an effect control interface on this engine. The function will allocate the - // resources for an instance of the requested effect engine and return - // a handle on the effect control interface. - // - // Input: - // uuid: pointer to the effect uuid. - // sessionId: audio session to which this effect instance will be attached. - // All effects created with the same session ID are connected in series and process - // the same signal stream. Knowing that two effects are part of the same effect - // chain can help the library implement some kind of optimizations. - // ioId: identifies the output or input stream this effect is directed to in - // audio HAL. - // For future use especially with tunneled HW accelerated effects - // - // Input/Output: - // pHandle: address where to return the effect interface handle. - // - // Output: - // returned value: 0 successful operation. - // -ENODEV library failed to initialize - // -EINVAL invalid pEffectUuid or pHandle - // -ENOENT no effect with this uuid found - // *pHandle: updated with the effect interface handle. - // - //////////////////////////////////////////////////////////////////////////////// - int32_t (*create_effect)(const effect_uuid_t *uuid, - int32_t sessionId, - int32_t ioId, - effect_handle_t *pHandle); - - //////////////////////////////////////////////////////////////////////////////// - // - // Function: release_effect - // - // Description: Releases the effect engine whose handle is given as argument. - // All resources allocated to this particular instance of the effect are - // released. - // - // Input: - // handle: handle on the effect interface to be released. - // - // Output: - // returned value: 0 successful operation. - // -ENODEV library failed to initialize - // -EINVAL invalid interface handle - // - //////////////////////////////////////////////////////////////////////////////// - int32_t (*release_effect)(effect_handle_t handle); - - //////////////////////////////////////////////////////////////////////////////// - // - // Function: get_descriptor - // - // Description: Returns the descriptor of the effect engine which implementation UUID is - // given as argument. - // - // Input/Output: - // uuid: pointer to the effect uuid. - // pDescriptor: address where to return the effect descriptor. - // - // Output: - // returned value: 0 successful operation. - // -ENODEV library failed to initialize - // -EINVAL invalid pDescriptor or uuid - // *pDescriptor: updated with the effect descriptor. - // - //////////////////////////////////////////////////////////////////////////////// - int32_t (*get_descriptor)(const effect_uuid_t *uuid, - effect_descriptor_t *pDescriptor); - - //////////////////////////////////////////////////////////////////////////////// - // - // Function: create_effect_3_1 - // - // Description: Creates an effect engine of the specified implementation uuid and - // returns an effect control interface on this engine. The function will allocate the - // resources for an instance of the requested effect engine and return - // a handle on the effect control interface. - // - // Input: - // uuid: pointer to the effect uuid. - // sessionId: audio session to which this effect instance will be attached. - // All effects created with the same session ID are connected in series and process - // the same signal stream. Knowing that two effects are part of the same effect - // chain can help the library implement some kind of optimizations. - // ioId: identifies the output or input stream this effect is directed to in - // audio HAL. - // For future use especially with tunneled HW accelerated effects - // deviceId: identifies the sink or source device this effect is directed to in - // audio HAL. Must be specified if sessionId is AUDIO_SESSION_DEVICE and is - // ignored otherwise. - // deviceId is the audio_port_handle_t used for the device when the audio - // patch is created at the audio HAL. - // - // Input/Output: - // pHandle: address where to return the effect interface handle. - // - // Output: - // returned value: 0 successful operation. - // -ENODEV library failed to initialize - // -EINVAL invalid pEffectUuid or pHandle - // -ENOENT no effect with this uuid found - // *pHandle: updated with the effect interface handle. - // - //////////////////////////////////////////////////////////////////////////////// - int32_t (*create_effect_3_1)(const effect_uuid_t *uuid, - int32_t sessionId, - int32_t ioId, - int32_t deviceId, - effect_handle_t *pHandle); - -} audio_effect_library_t; - -// Name of the hal_module_info -#define AUDIO_EFFECT_LIBRARY_INFO_SYM AELI - -// Name of the hal_module_info as a string -#define AUDIO_EFFECT_LIBRARY_INFO_SYM_AS_STR "AELI" - -__END_DECLS - -#endif // ANDROID_AUDIO_EFFECT_H +../../include_all/hardware/audio_effect.h
\ No newline at end of file diff --git a/include/hardware/audio_policy.h b/include/hardware/audio_policy.h index bacb1e55..d9dca236 100644..120000 --- a/include/hardware/audio_policy.h +++ b/include/hardware/audio_policy.h @@ -1,457 +1 @@ -/* - * Copyright (C) 2011 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_AUDIO_POLICY_INTERFACE_H -#define ANDROID_AUDIO_POLICY_INTERFACE_H - -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <hardware/hardware.h> - -#include <system/audio.h> -#include <system/audio_policy.h> - -__BEGIN_DECLS - -/** - * The id of this module - */ -#define AUDIO_POLICY_HARDWARE_MODULE_ID "audio_policy" - -/** - * Name of the audio devices to open - */ -#define AUDIO_POLICY_INTERFACE "policy" - -/* ---------------------------------------------------------------------------- */ - -/* - * The audio_policy and audio_policy_service_ops structs define the - * communication interfaces between the platform specific audio policy manager - * and Android generic audio policy manager. - * The platform specific audio policy manager must implement methods of the - * audio_policy struct. - * This implementation makes use of the audio_policy_service_ops to control - * the activity and configuration of audio input and output streams. - * - * The platform specific audio policy manager is in charge of the audio - * routing and volume control policies for a given platform. - * The main roles of this module are: - * - keep track of current system state (removable device connections, phone - * state, user requests...). - * System state changes and user actions are notified to audio policy - * manager with methods of the audio_policy. - * - * - process get_output() queries received when AudioTrack objects are - * created: Those queries return a handler on an output that has been - * selected, configured and opened by the audio policy manager and that - * must be used by the AudioTrack when registering to the AudioFlinger - * with the createTrack() method. - * When the AudioTrack object is released, a release_output() query - * is received and the audio policy manager can decide to close or - * reconfigure the output depending on other streams using this output and - * current system state. - * - * - similarly process get_input() and release_input() queries received from - * AudioRecord objects and configure audio inputs. - * - process volume control requests: the stream volume is converted from - * an index value (received from UI) to a float value applicable to each - * output as a function of platform specific settings and current output - * route (destination device). It also make sure that streams are not - * muted if not allowed (e.g. camera shutter sound in some countries). - */ - -/* XXX: this should be defined OUTSIDE of frameworks/base */ -struct effect_descriptor_s; - -struct audio_policy { - /* - * configuration functions - */ - - /* indicate a change in device connection status */ - int (*set_device_connection_state)(struct audio_policy *pol, - audio_devices_t device, - audio_policy_dev_state_t state, - const char *device_address); - - /* retrieve a device connection status */ - audio_policy_dev_state_t (*get_device_connection_state)( - const struct audio_policy *pol, - audio_devices_t device, - const char *device_address); - - /* indicate a change in phone state. Valid phones states are defined - * by audio_mode_t */ - void (*set_phone_state)(struct audio_policy *pol, audio_mode_t state); - - /* deprecated, never called (was "indicate a change in ringer mode") */ - void (*set_ringer_mode)(struct audio_policy *pol, uint32_t mode, - uint32_t mask); - - /* force using a specific device category for the specified usage */ - void (*set_force_use)(struct audio_policy *pol, - audio_policy_force_use_t usage, - audio_policy_forced_cfg_t config); - - /* retrieve current device category forced for a given usage */ - audio_policy_forced_cfg_t (*get_force_use)(const struct audio_policy *pol, - audio_policy_force_use_t usage); - - /* if can_mute is true, then audio streams that are marked ENFORCED_AUDIBLE - * can still be muted. */ - void (*set_can_mute_enforced_audible)(struct audio_policy *pol, - bool can_mute); - - /* check proper initialization */ - int (*init_check)(const struct audio_policy *pol); - - /* - * Audio routing query functions - */ - - /* request an output appropriate for playback of the supplied stream type and - * parameters */ - audio_io_handle_t (*get_output)(struct audio_policy *pol, - audio_stream_type_t stream, - uint32_t samplingRate, - audio_format_t format, - audio_channel_mask_t channelMask, - audio_output_flags_t flags, - const audio_offload_info_t *offloadInfo); - - /* indicates to the audio policy manager that the output starts being used - * by corresponding stream. */ - int (*start_output)(struct audio_policy *pol, - audio_io_handle_t output, - audio_stream_type_t stream, - audio_session_t session); - - /* indicates to the audio policy manager that the output stops being used - * by corresponding stream. */ - int (*stop_output)(struct audio_policy *pol, - audio_io_handle_t output, - audio_stream_type_t stream, - audio_session_t session); - - /* releases the output. */ - void (*release_output)(struct audio_policy *pol, audio_io_handle_t output); - - /* request an input appropriate for record from the supplied device with - * supplied parameters. */ - audio_io_handle_t (*get_input)(struct audio_policy *pol, audio_source_t inputSource, - uint32_t samplingRate, - audio_format_t format, - audio_channel_mask_t channelMask, - audio_in_acoustics_t acoustics); - - /* indicates to the audio policy manager that the input starts being used */ - int (*start_input)(struct audio_policy *pol, audio_io_handle_t input); - - /* indicates to the audio policy manager that the input stops being used. */ - int (*stop_input)(struct audio_policy *pol, audio_io_handle_t input); - - /* releases the input. */ - void (*release_input)(struct audio_policy *pol, audio_io_handle_t input); - - /* - * volume control functions - */ - - /* initialises stream volume conversion parameters by specifying volume - * index range. The index range for each stream is defined by AudioService. */ - void (*init_stream_volume)(struct audio_policy *pol, - audio_stream_type_t stream, - int index_min, - int index_max); - - /* sets the new stream volume at a level corresponding to the supplied - * index. The index is within the range specified by init_stream_volume() */ - int (*set_stream_volume_index)(struct audio_policy *pol, - audio_stream_type_t stream, - int index); - - /* retrieve current volume index for the specified stream */ - int (*get_stream_volume_index)(const struct audio_policy *pol, - audio_stream_type_t stream, - int *index); - - /* sets the new stream volume at a level corresponding to the supplied - * index for the specified device. - * The index is within the range specified by init_stream_volume() */ - int (*set_stream_volume_index_for_device)(struct audio_policy *pol, - audio_stream_type_t stream, - int index, - audio_devices_t device); - - /* retrieve current volume index for the specified stream for the specified device */ - int (*get_stream_volume_index_for_device)(const struct audio_policy *pol, - audio_stream_type_t stream, - int *index, - audio_devices_t device); - - /* return the strategy corresponding to a given stream type */ - uint32_t (*get_strategy_for_stream)(const struct audio_policy *pol, - audio_stream_type_t stream); - - /* return the enabled output devices for the given stream type */ - audio_devices_t (*get_devices_for_stream)(const struct audio_policy *pol, - audio_stream_type_t stream); - - /* Audio effect management */ - audio_io_handle_t (*get_output_for_effect)(struct audio_policy *pol, - const struct effect_descriptor_s *desc); - - int (*register_effect)(struct audio_policy *pol, - const struct effect_descriptor_s *desc, - audio_io_handle_t output, - uint32_t strategy, - audio_session_t session, - int id); - - int (*unregister_effect)(struct audio_policy *pol, int id); - - int (*set_effect_enabled)(struct audio_policy *pol, int id, bool enabled); - - bool (*is_stream_active)(const struct audio_policy *pol, - audio_stream_type_t stream, - uint32_t in_past_ms); - - bool (*is_stream_active_remotely)(const struct audio_policy *pol, - audio_stream_type_t stream, - uint32_t in_past_ms); - - bool (*is_source_active)(const struct audio_policy *pol, - audio_source_t source); - - /* dump state */ - int (*dump)(const struct audio_policy *pol, int fd); - - /* check if offload is possible for given sample rate, bitrate, duration, ... */ - bool (*is_offload_supported)(const struct audio_policy *pol, - const audio_offload_info_t *info); -}; - - -struct audio_policy_service_ops { - /* - * Audio output Control functions - */ - - /* Opens an audio output with the requested parameters. - * - * The parameter values can indicate to use the default values in case the - * audio policy manager has no specific requirements for the output being - * opened. - * - * When the function returns, the parameter values reflect the actual - * values used by the audio hardware output stream. - * - * The audio policy manager can check if the proposed parameters are - * suitable or not and act accordingly. - */ - audio_io_handle_t (*open_output)(void *service, - audio_devices_t *pDevices, - uint32_t *pSamplingRate, - audio_format_t *pFormat, - audio_channel_mask_t *pChannelMask, - uint32_t *pLatencyMs, - audio_output_flags_t flags); - - /* creates a special output that is duplicated to the two outputs passed as - * arguments. The duplication is performed by - * a special mixer thread in the AudioFlinger. - */ - audio_io_handle_t (*open_duplicate_output)(void *service, - audio_io_handle_t output1, - audio_io_handle_t output2); - - /* closes the output stream */ - int (*close_output)(void *service, audio_io_handle_t output); - - /* suspends the output. - * - * When an output is suspended, the corresponding audio hardware output - * stream is placed in standby and the AudioTracks attached to the mixer - * thread are still processed but the output mix is discarded. - */ - int (*suspend_output)(void *service, audio_io_handle_t output); - - /* restores a suspended output. */ - int (*restore_output)(void *service, audio_io_handle_t output); - - /* */ - /* Audio input Control functions */ - /* */ - - /* opens an audio input - * deprecated - new implementations should use open_input_on_module, - * and the acoustics parameter is ignored - */ - audio_io_handle_t (*open_input)(void *service, - audio_devices_t *pDevices, - uint32_t *pSamplingRate, - audio_format_t *pFormat, - audio_channel_mask_t *pChannelMask, - audio_in_acoustics_t acoustics); - - /* closes an audio input */ - int (*close_input)(void *service, audio_io_handle_t input); - - /* */ - /* misc control functions */ - /* */ - - /* set a stream volume for a particular output. - * - * For the same user setting, a given stream type can have different - * volumes for each output (destination device) it is attached to. - */ - int (*set_stream_volume)(void *service, - audio_stream_type_t stream, - float volume, - audio_io_handle_t output, - int delay_ms); - - /* invalidate a stream type, causing a reroute to an unspecified new output */ - int (*invalidate_stream)(void *service, - audio_stream_type_t stream); - - /* function enabling to send proprietary informations directly from audio - * policy manager to audio hardware interface. */ - void (*set_parameters)(void *service, - audio_io_handle_t io_handle, - const char *kv_pairs, - int delay_ms); - - /* function enabling to receive proprietary informations directly from - * audio hardware interface to audio policy manager. - * - * Returns a pointer to a heap allocated string. The caller is responsible - * for freeing the memory for it using free(). - */ - - char * (*get_parameters)(void *service, audio_io_handle_t io_handle, - const char *keys); - - /* request the playback of a tone on the specified stream. - * used for instance to replace notification sounds when playing over a - * telephony device during a phone call. - */ - int (*start_tone)(void *service, - audio_policy_tone_t tone, - audio_stream_type_t stream); - - int (*stop_tone)(void *service); - - /* set down link audio volume. */ - int (*set_voice_volume)(void *service, - float volume, - int delay_ms); - - /* move effect to the specified output */ - int (*move_effects)(void *service, - audio_session_t session, - audio_io_handle_t src_output, - audio_io_handle_t dst_output); - - /* loads an audio hw module. - * - * The module name passed is the base name of the HW module library, e.g "primary" or "a2dp". - * The function returns a handle on the module that will be used to specify a particular - * module when calling open_output_on_module() or open_input_on_module() - */ - audio_module_handle_t (*load_hw_module)(void *service, - const char *name); - - /* Opens an audio output on a particular HW module. - * - * Same as open_output() but specifying a specific HW module on which the output must be opened. - */ - audio_io_handle_t (*open_output_on_module)(void *service, - audio_module_handle_t module, - audio_devices_t *pDevices, - uint32_t *pSamplingRate, - audio_format_t *pFormat, - audio_channel_mask_t *pChannelMask, - uint32_t *pLatencyMs, - audio_output_flags_t flags, - const audio_offload_info_t *offloadInfo); - - /* Opens an audio input on a particular HW module. - * - * Same as open_input() but specifying a specific HW module on which the input must be opened. - * Also removed deprecated acoustics parameter - */ - audio_io_handle_t (*open_input_on_module)(void *service, - audio_module_handle_t module, - audio_devices_t *pDevices, - uint32_t *pSamplingRate, - audio_format_t *pFormat, - audio_channel_mask_t *pChannelMask); - -}; - -/**********************************************************************/ - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -typedef struct audio_policy_module { - struct hw_module_t common; -} audio_policy_module_t; - -struct audio_policy_device { - /** - * Common methods of the audio policy device. This *must* be the first member of - * audio_policy_device as users of this structure will cast a hw_device_t to - * audio_policy_device pointer in contexts where it's known the hw_device_t references an - * audio_policy_device. - */ - struct hw_device_t common; - - int (*create_audio_policy)(const struct audio_policy_device *device, - struct audio_policy_service_ops *aps_ops, - void *service, - struct audio_policy **ap); - - int (*destroy_audio_policy)(const struct audio_policy_device *device, - struct audio_policy *ap); -}; - -/** convenience API for opening and closing a supported device */ - -static inline int audio_policy_dev_open(const hw_module_t* module, - struct audio_policy_device** device) -{ - return module->methods->open(module, AUDIO_POLICY_INTERFACE, - (hw_device_t**)device); -} - -static inline int audio_policy_dev_close(struct audio_policy_device* device) -{ - return device->common.close(&device->common); -} - - -__END_DECLS - -#endif // ANDROID_AUDIO_POLICY_INTERFACE_H +../../include_all/hardware/audio_policy.h
\ No newline at end of file diff --git a/include/hardware/bluetooth.h b/include/hardware/bluetooth.h index 95a0b6e3..bcd8225e 100644..120000 --- a/include/hardware/bluetooth.h +++ b/include/hardware/bluetooth.h @@ -1,598 +1 @@ -/* - * Copyright (C) 2012 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_INCLUDE_BLUETOOTH_H -#define ANDROID_INCLUDE_BLUETOOTH_H - -#include <stdbool.h> -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <bluetooth/uuid.h> -#include <raw_address.h> - -__BEGIN_DECLS - -#define BLUETOOTH_INTERFACE_STRING "bluetoothInterface" - -/** Bluetooth profile interface IDs */ - -#define BT_PROFILE_HANDSFREE_ID "handsfree" -#define BT_PROFILE_HANDSFREE_CLIENT_ID "handsfree_client" -#define BT_PROFILE_ADVANCED_AUDIO_ID "a2dp" -#define BT_PROFILE_ADVANCED_AUDIO_SINK_ID "a2dp_sink" -#define BT_PROFILE_HEALTH_ID "health" -#define BT_PROFILE_SOCKETS_ID "socket" -#define BT_PROFILE_HIDHOST_ID "hidhost" -#define BT_PROFILE_HIDDEV_ID "hiddev" -#define BT_PROFILE_PAN_ID "pan" -#define BT_PROFILE_MAP_CLIENT_ID "map_client" -#define BT_PROFILE_SDP_CLIENT_ID "sdp" -#define BT_PROFILE_GATT_ID "gatt" -#define BT_PROFILE_AV_RC_ID "avrcp" -#define BT_PROFILE_AV_RC_CTRL_ID "avrcp_ctrl" - -/** Bluetooth test interface IDs */ -#define BT_TEST_INTERFACE_MCAP_ID "mcap_test" - -/** Bluetooth Device Name */ -typedef struct { - uint8_t name[249]; -} __attribute__((packed))bt_bdname_t; - -/** Bluetooth Adapter Visibility Modes*/ -typedef enum { - BT_SCAN_MODE_NONE, - BT_SCAN_MODE_CONNECTABLE, - BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE -} bt_scan_mode_t; - -/** Bluetooth Adapter State */ -typedef enum { - BT_STATE_OFF, - BT_STATE_ON -} bt_state_t; - -/** Bluetooth Error Status */ -/** We need to build on this */ - -typedef enum { - BT_STATUS_SUCCESS, - BT_STATUS_FAIL, - BT_STATUS_NOT_READY, - BT_STATUS_NOMEM, - BT_STATUS_BUSY, - BT_STATUS_DONE, /* request already completed */ - BT_STATUS_UNSUPPORTED, - BT_STATUS_PARM_INVALID, - BT_STATUS_UNHANDLED, - BT_STATUS_AUTH_FAILURE, - BT_STATUS_RMT_DEV_DOWN, - BT_STATUS_AUTH_REJECTED, - BT_STATUS_JNI_ENVIRONMENT_ERROR, - BT_STATUS_JNI_THREAD_ATTACH_ERROR, - BT_STATUS_WAKELOCK_ERROR -} bt_status_t; - -/** Bluetooth PinKey Code */ -typedef struct { - uint8_t pin[16]; -} __attribute__((packed))bt_pin_code_t; - -typedef struct { - uint8_t status; - uint8_t ctrl_state; /* stack reported state */ - uint64_t tx_time; /* in ms */ - uint64_t rx_time; /* in ms */ - uint64_t idle_time; /* in ms */ - uint64_t energy_used; /* a product of mA, V and ms */ -} __attribute__((packed))bt_activity_energy_info; - -typedef struct { - int32_t app_uid; - uint64_t tx_bytes; - uint64_t rx_bytes; -} __attribute__((packed))bt_uid_traffic_t; - -/** Bluetooth Adapter Discovery state */ -typedef enum { - BT_DISCOVERY_STOPPED, - BT_DISCOVERY_STARTED -} bt_discovery_state_t; - -/** Bluetooth ACL connection state */ -typedef enum { - BT_ACL_STATE_CONNECTED, - BT_ACL_STATE_DISCONNECTED -} bt_acl_state_t; - -/** Bluetooth SDP service record */ -typedef struct -{ - bluetooth::Uuid uuid; - uint16_t channel; - char name[256]; // what's the maximum length -} bt_service_record_t; - - -/** Bluetooth Remote Version info */ -typedef struct -{ - int version; - int sub_ver; - int manufacturer; -} bt_remote_version_t; - -typedef struct -{ - uint16_t version_supported; - uint8_t local_privacy_enabled; - uint8_t max_adv_instance; - uint8_t rpa_offload_supported; - uint8_t max_irk_list_size; - uint8_t max_adv_filter_supported; - uint8_t activity_energy_info_supported; - uint16_t scan_result_storage_size; - uint16_t total_trackable_advertisers; - bool extended_scan_support; - bool debug_logging_supported; - bool le_2m_phy_supported; - bool le_coded_phy_supported; - bool le_extended_advertising_supported; - bool le_periodic_advertising_supported; - uint16_t le_maximum_advertising_data_length; -}bt_local_le_features_t; - -/* Bluetooth Adapter and Remote Device property types */ -typedef enum { - /* Properties common to both adapter and remote device */ - /** - * Description - Bluetooth Device Name - * Access mode - Adapter name can be GET/SET. Remote device can be GET - * Data type - bt_bdname_t - */ - BT_PROPERTY_BDNAME = 0x1, - /** - * Description - Bluetooth Device Address - * Access mode - Only GET. - * Data type - RawAddress - */ - BT_PROPERTY_BDADDR, - /** - * Description - Bluetooth Service 128-bit UUIDs - * Access mode - Only GET. - * Data type - Array of bluetooth::Uuid (Array size inferred from property - * length). - */ - BT_PROPERTY_UUIDS, - /** - * Description - Bluetooth Class of Device as found in Assigned Numbers - * Access mode - Only GET. - * Data type - uint32_t. - */ - BT_PROPERTY_CLASS_OF_DEVICE, - /** - * Description - Device Type - BREDR, BLE or DUAL Mode - * Access mode - Only GET. - * Data type - bt_device_type_t - */ - BT_PROPERTY_TYPE_OF_DEVICE, - /** - * Description - Bluetooth Service Record - * Access mode - Only GET. - * Data type - bt_service_record_t - */ - BT_PROPERTY_SERVICE_RECORD, - - /* Properties unique to adapter */ - /** - * Description - Bluetooth Adapter scan mode - * Access mode - GET and SET - * Data type - bt_scan_mode_t. - */ - BT_PROPERTY_ADAPTER_SCAN_MODE, - /** - * Description - List of bonded devices - * Access mode - Only GET. - * Data type - Array of RawAddress of the bonded remote devices - * (Array size inferred from property length). - */ - BT_PROPERTY_ADAPTER_BONDED_DEVICES, - /** - * Description - Bluetooth Adapter Discovery timeout (in seconds) - * Access mode - GET and SET - * Data type - uint32_t - */ - BT_PROPERTY_ADAPTER_DISCOVERY_TIMEOUT, - - /* Properties unique to remote device */ - /** - * Description - User defined friendly name of the remote device - * Access mode - GET and SET - * Data type - bt_bdname_t. - */ - BT_PROPERTY_REMOTE_FRIENDLY_NAME, - /** - * Description - RSSI value of the inquired remote device - * Access mode - Only GET. - * Data type - int32_t. - */ - BT_PROPERTY_REMOTE_RSSI, - /** - * Description - Remote version info - * Access mode - SET/GET. - * Data type - bt_remote_version_t. - */ - - BT_PROPERTY_REMOTE_VERSION_INFO, - - /** - * Description - Local LE features - * Access mode - GET. - * Data type - bt_local_le_features_t. - */ - BT_PROPERTY_LOCAL_LE_FEATURES, - - BT_PROPERTY_REMOTE_DEVICE_TIMESTAMP = 0xFF, -} bt_property_type_t; - -/** Bluetooth Adapter Property data structure */ -typedef struct -{ - bt_property_type_t type; - int len; - void *val; -} bt_property_t; - -/** Represents the actual Out of Band data itself */ -typedef struct { - // Both - bool is_valid = false; /* Default to invalid data; force caller to verify */ - uint8_t address[7]; /* Bluetooth Device Address (6) plus Address Type (1) */ - uint8_t c[16]; /* Simple Pairing Hash C-192/256 (Classic or LE) */ - uint8_t r[16]; /* Simple Pairing Randomizer R-192/256 (Classic or LE) */ - uint8_t device_name[256]; /* Name of the device */ - - // Classic - uint8_t oob_data_length[2]; /* Classic only data Length. Value includes this - in length */ - uint8_t class_of_device[2]; /* Class of Device (Classic or LE) */ - - // LE - uint8_t le_device_role; /* Supported and preferred role of device */ - uint8_t sm_tk[16]; /* Security Manager TK Value (LE Only) */ - uint8_t le_flags; /* LE Flags for discoverability and features */ - uint8_t le_appearance[2]; /* For the appearance of the device */ -} bt_oob_data_t; - - -/** Bluetooth Device Type */ -typedef enum { - BT_DEVICE_DEVTYPE_BREDR = 0x1, - BT_DEVICE_DEVTYPE_BLE, - BT_DEVICE_DEVTYPE_DUAL -} bt_device_type_t; -/** Bluetooth Bond state */ -typedef enum { - BT_BOND_STATE_NONE, - BT_BOND_STATE_BONDING, - BT_BOND_STATE_BONDED -} bt_bond_state_t; - -/** Bluetooth SSP Bonding Variant */ -typedef enum { - BT_SSP_VARIANT_PASSKEY_CONFIRMATION, - BT_SSP_VARIANT_PASSKEY_ENTRY, - BT_SSP_VARIANT_CONSENT, - BT_SSP_VARIANT_PASSKEY_NOTIFICATION -} bt_ssp_variant_t; - -#define BT_MAX_NUM_UUIDS 32 - -/** Bluetooth Interface callbacks */ - -/** Bluetooth Enable/Disable Callback. */ -typedef void (*adapter_state_changed_callback)(bt_state_t state); - -/** GET/SET Adapter Properties callback */ -/* TODO: For the GET/SET property APIs/callbacks, we may need a session - * identifier to associate the call with the callback. This would be needed - * whenever more than one simultaneous instance of the same adapter_type - * is get/set. - * - * If this is going to be handled in the Java framework, then we do not need - * to manage sessions here. - */ -typedef void (*adapter_properties_callback)(bt_status_t status, - int num_properties, - bt_property_t *properties); - -/** GET/SET Remote Device Properties callback */ -/** TODO: For remote device properties, do not see a need to get/set - * multiple properties - num_properties shall be 1 - */ -typedef void (*remote_device_properties_callback)(bt_status_t status, - RawAddress *bd_addr, - int num_properties, - bt_property_t *properties); - -/** New device discovered callback */ -/** If EIR data is not present, then BD_NAME and RSSI shall be NULL and -1 - * respectively */ -typedef void (*device_found_callback)(int num_properties, - bt_property_t *properties); - -/** Discovery state changed callback */ -typedef void (*discovery_state_changed_callback)(bt_discovery_state_t state); - -/** Bluetooth Legacy PinKey Request callback */ -typedef void (*pin_request_callback)(RawAddress *remote_bd_addr, - bt_bdname_t *bd_name, uint32_t cod, bool min_16_digit); - -/** Bluetooth SSP Request callback - Just Works & Numeric Comparison*/ -/** pass_key - Shall be 0 for BT_SSP_PAIRING_VARIANT_CONSENT & - * BT_SSP_PAIRING_PASSKEY_ENTRY */ -/* TODO: Passkey request callback shall not be needed for devices with display - * capability. We still need support this in the stack for completeness */ -typedef void (*ssp_request_callback)(RawAddress *remote_bd_addr, - bt_bdname_t *bd_name, - uint32_t cod, - bt_ssp_variant_t pairing_variant, - uint32_t pass_key); - -/** Bluetooth Bond state changed callback */ -/* Invoked in response to create_bond, cancel_bond or remove_bond */ -typedef void (*bond_state_changed_callback)(bt_status_t status, - RawAddress *remote_bd_addr, - bt_bond_state_t state); - -/** Bluetooth ACL connection state changed callback */ -typedef void (*acl_state_changed_callback)(bt_status_t status, RawAddress *remote_bd_addr, - bt_acl_state_t state); - -typedef enum { - ASSOCIATE_JVM, - DISASSOCIATE_JVM -} bt_cb_thread_evt; - -/** Thread Associate/Disassociate JVM Callback */ -/* Callback that is invoked by the callback thread to allow upper layer to attach/detach to/from - * the JVM */ -typedef void (*callback_thread_event)(bt_cb_thread_evt evt); - -/** Bluetooth Test Mode Callback */ -/* Receive any HCI event from controller. Must be in DUT Mode for this callback to be received */ -typedef void (*dut_mode_recv_callback)(uint16_t opcode, uint8_t *buf, uint8_t len); - -/* LE Test mode callbacks -* This callback shall be invoked whenever the le_tx_test, le_rx_test or le_test_end is invoked -* The num_packets is valid only for le_test_end command */ -typedef void (*le_test_mode_callback)(bt_status_t status, uint16_t num_packets); - -/** Callback invoked when energy details are obtained */ -/* Ctrl_state-Current controller state-Active-1,scan-2,or idle-3 state as defined by HCI spec. - * If the ctrl_state value is 0, it means the API call failed - * Time values-In milliseconds as returned by the controller - * Energy used-Value as returned by the controller - * Status-Provides the status of the read_energy_info API call - * uid_data provides an array of bt_uid_traffic_t, where the array is terminated by an element with - * app_uid set to -1. - */ -typedef void (*energy_info_callback)(bt_activity_energy_info *energy_info, - bt_uid_traffic_t *uid_data); - -/** TODO: Add callbacks for Link Up/Down and other generic - * notifications/callbacks */ - -/** Bluetooth DM callback structure. */ -typedef struct { - /** set to sizeof(bt_callbacks_t) */ - size_t size; - adapter_state_changed_callback adapter_state_changed_cb; - adapter_properties_callback adapter_properties_cb; - remote_device_properties_callback remote_device_properties_cb; - device_found_callback device_found_cb; - discovery_state_changed_callback discovery_state_changed_cb; - pin_request_callback pin_request_cb; - ssp_request_callback ssp_request_cb; - bond_state_changed_callback bond_state_changed_cb; - acl_state_changed_callback acl_state_changed_cb; - callback_thread_event thread_evt_cb; - dut_mode_recv_callback dut_mode_recv_cb; - le_test_mode_callback le_test_mode_cb; - energy_info_callback energy_info_cb; -} bt_callbacks_t; - -typedef void (*alarm_cb)(void *data); -typedef bool (*set_wake_alarm_callout)(uint64_t delay_millis, bool should_wake, alarm_cb cb, void *data); -typedef int (*acquire_wake_lock_callout)(const char *lock_name); -typedef int (*release_wake_lock_callout)(const char *lock_name); - -/** The set of functions required by bluedroid to set wake alarms and - * grab wake locks. This struct is passed into the stack through the - * |set_os_callouts| function on |bt_interface_t|. - */ -typedef struct { - /* set to sizeof(bt_os_callouts_t) */ - size_t size; - - set_wake_alarm_callout set_wake_alarm; - acquire_wake_lock_callout acquire_wake_lock; - release_wake_lock_callout release_wake_lock; -} bt_os_callouts_t; - -/** NOTE: By default, no profiles are initialized at the time of init/enable. - * Whenever the application invokes the 'init' API of a profile, then one of - * the following shall occur: - * - * 1.) If Bluetooth is not enabled, then the Bluetooth core shall mark the - * profile as enabled. Subsequently, when the application invokes the - * Bluetooth 'enable', as part of the enable sequence the profile that were - * marked shall be enabled by calling appropriate stack APIs. The - * 'adapter_properties_cb' shall return the list of UUIDs of the - * enabled profiles. - * - * 2.) If Bluetooth is enabled, then the Bluetooth core shall invoke the stack - * profile API to initialize the profile and trigger a - * 'adapter_properties_cb' with the current list of UUIDs including the - * newly added profile's UUID. - * - * The reverse shall occur whenever the profile 'cleanup' APIs are invoked - */ - -/** Represents the standard Bluetooth DM interface. */ -typedef struct { - /** set to sizeof(bt_interface_t) */ - size_t size; - /** - * Opens the interface and provides the callback routines - * to the implemenation of this interface. - * The |is_atv| flag indicates whether the local device is an Android TV - */ - int (*init)(bt_callbacks_t* callbacks, bool is_atv); - - /** Enable Bluetooth. */ - int (*enable)(bool guest_mode); - - /** Disable Bluetooth. */ - int (*disable)(void); - - /** Closes the interface. */ - void (*cleanup)(void); - - /** Get all Bluetooth Adapter properties at init */ - int (*get_adapter_properties)(void); - - /** Get Bluetooth Adapter property of 'type' */ - int (*get_adapter_property)(bt_property_type_t type); - - /** Set Bluetooth Adapter property of 'type' */ - /* Based on the type, val shall be one of - * RawAddress or bt_bdname_t or bt_scanmode_t etc - */ - int (*set_adapter_property)(const bt_property_t *property); - - /** Get all Remote Device properties */ - int (*get_remote_device_properties)(RawAddress *remote_addr); - - /** Get Remote Device property of 'type' */ - int (*get_remote_device_property)(RawAddress *remote_addr, - bt_property_type_t type); - - /** Set Remote Device property of 'type' */ - int (*set_remote_device_property)(RawAddress *remote_addr, - const bt_property_t *property); - - /** Get Remote Device's service record for the given UUID */ - int (*get_remote_service_record)(const RawAddress& remote_addr, - const bluetooth::Uuid& uuid); - - /** Start SDP to get remote services */ - int (*get_remote_services)(RawAddress *remote_addr); - - /** Start Discovery */ - int (*start_discovery)(void); - - /** Cancel Discovery */ - int (*cancel_discovery)(void); - - /** Create Bluetooth Bonding */ - int (*create_bond)(const RawAddress *bd_addr, int transport); - - /** Create Bluetooth Bond using out of band data */ - int (*create_bond_out_of_band)(const RawAddress *bd_addr, int transport, - const bt_oob_data_t *p192_data, - const bt_oob_data_t *p256_data); - - /** Remove Bond */ - int (*remove_bond)(const RawAddress *bd_addr); - - /** Cancel Bond */ - int (*cancel_bond)(const RawAddress *bd_addr); - - /** - * Get the connection status for a given remote device. - * return value of 0 means the device is not connected, - * non-zero return status indicates an active connection. - */ - int (*get_connection_state)(const RawAddress *bd_addr); - - /** BT Legacy PinKey Reply */ - /** If accept==FALSE, then pin_len and pin_code shall be 0x0 */ - int (*pin_reply)(const RawAddress *bd_addr, uint8_t accept, - uint8_t pin_len, bt_pin_code_t *pin_code); - - /** BT SSP Reply - Just Works, Numeric Comparison and Passkey - * passkey shall be zero for BT_SSP_VARIANT_PASSKEY_COMPARISON & - * BT_SSP_VARIANT_CONSENT - * For BT_SSP_VARIANT_PASSKEY_ENTRY, if accept==FALSE, then passkey - * shall be zero */ - int (*ssp_reply)(const RawAddress *bd_addr, bt_ssp_variant_t variant, - uint8_t accept, uint32_t passkey); - - /** Get Bluetooth profile interface */ - const void* (*get_profile_interface) (const char *profile_id); - - /** Bluetooth Test Mode APIs - Bluetooth must be enabled for these APIs */ - /* Configure DUT Mode - Use this mode to enter/exit DUT mode */ - int (*dut_mode_configure)(uint8_t enable); - - /* Send any test HCI (vendor-specific) command to the controller. Must be in DUT Mode */ - int (*dut_mode_send)(uint16_t opcode, uint8_t *buf, uint8_t len); - /** BLE Test Mode APIs */ - /* opcode MUST be one of: LE_Receiver_Test, LE_Transmitter_Test, LE_Test_End */ - int (*le_test_mode)(uint16_t opcode, uint8_t *buf, uint8_t len); - - /** Sets the OS call-out functions that bluedroid needs for alarms and wake locks. - * This should be called immediately after a successful |init|. - */ - int (*set_os_callouts)(bt_os_callouts_t *callouts); - - /** Read Energy info details - return value indicates BT_STATUS_SUCCESS or BT_STATUS_NOT_READY - * Success indicates that the VSC command was sent to controller - */ - int (*read_energy_info)(); - - /** - * Native support for dumpsys function - * Function is synchronous and |fd| is owned by caller. - * |arguments| are arguments which may affect the output, encoded as - * UTF-8 strings. - */ - void (*dump)(int fd, const char **arguments); - - /** - * Clear /data/misc/bt_config.conf and erase all stored connections - */ - int (*config_clear)(void); - - /** - * Clear (reset) the dynamic portion of the device interoperability database. - */ - void (*interop_database_clear)(void); - - /** - * Add a new device interoperability workaround for a remote device whose - * first |len| bytes of the its device address match |addr|. - * NOTE: |feature| has to match an item defined in interop_feature_t (interop.h). - */ - void (*interop_database_add)(uint16_t feature, const RawAddress *addr, size_t len); -} bt_interface_t; - -__END_DECLS - -#endif /* ANDROID_INCLUDE_BLUETOOTH_H */ +../../include_all/hardware/bluetooth.h
\ No newline at end of file diff --git a/include/hardware/boot_control.h b/include/hardware/boot_control.h index abbf3f19..a514282b 100644..120000 --- a/include/hardware/boot_control.h +++ b/include/hardware/boot_control.h @@ -1,141 +1 @@ -/* - * 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_INCLUDE_HARDWARE_BOOT_CONTROL_H -#define ANDROID_INCLUDE_HARDWARE_BOOT_CONTROL_H - -#include <hardware/hardware.h> - -__BEGIN_DECLS - -#define BOOT_CONTROL_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) - -/** - * The id of this module - */ -#define BOOT_CONTROL_HARDWARE_MODULE_ID "bootctrl" - -/* - * The Boot Control HAL is designed to allow for managing sets of redundant - * partitions, called slots, that can be booted from independantly. Slots - * are sets of partitions whose names differ only by a given suffix. - * They are identified here by a 0 indexed number, and associated with their - * suffix, which can be appended to the base name for any particular partition - * to find the one associated with that slot. The bootloader must pass the suffix - * of the currently active slot either through a kernel command line property at - * androidboot.slot_suffix, or the device tree at /firmware/android/slot_suffix. - * The primary use of this set up is to allow for background updates while the - * device is running, and to provide a fallback in the event that the update fails. - */ - - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -typedef struct boot_control_module { - struct hw_module_t common; - - /* - * (*init)() perform any initialization tasks needed for the HAL. - * This is called only once. - */ - void (*init)(struct boot_control_module *module); - - /* - * (*getNumberSlots)() returns the number of available slots. - * For instance, a system with a single set of partitions would return - * 1, a system with A/B would return 2, A/B/C -> 3... - */ - unsigned (*getNumberSlots)(struct boot_control_module *module); - - /* - * (*getCurrentSlot)() returns the value letting the system know - * whether the current slot is A or B. The meaning of A and B is - * left up to the implementer. It is assumed that if the current slot - * is A, then the block devices underlying B can be accessed directly - * without any risk of corruption. - * The returned value is always guaranteed to be strictly less than the - * value returned by getNumberSlots. Slots start at 0 and - * finish at getNumberSlots() - 1 - */ - unsigned (*getCurrentSlot)(struct boot_control_module *module); - - /* - * (*markBootSuccessful)() marks the current slot - * as having booted successfully - * - * Returns 0 on success, -errno on error. - */ - int (*markBootSuccessful)(struct boot_control_module *module); - - /* - * (*setActiveBootSlot)() marks the slot passed in parameter as - * the active boot slot (see getCurrentSlot for an explanation - * of the "slot" parameter). This overrides any previous call to - * setSlotAsUnbootable. - * Returns 0 on success, -errno on error. - */ - int (*setActiveBootSlot)(struct boot_control_module *module, unsigned slot); - - /* - * (*setSlotAsUnbootable)() marks the slot passed in parameter as - * an unbootable. This can be used while updating the contents of the slot's - * partitions, so that the system will not attempt to boot a known bad set up. - * Returns 0 on success, -errno on error. - */ - int (*setSlotAsUnbootable)(struct boot_control_module *module, unsigned slot); - - /* - * (*isSlotBootable)() returns if the slot passed in parameter is - * bootable. Note that slots can be made unbootable by both the - * bootloader and by the OS using setSlotAsUnbootable. - * Returns 1 if the slot is bootable, 0 if it's not, and -errno on - * error. - */ - int (*isSlotBootable)(struct boot_control_module *module, unsigned slot); - - /* - * (*getSuffix)() returns the string suffix used by partitions that - * correspond to the slot number passed in parameter. The returned string - * is expected to be statically allocated and not need to be freed. - * Returns NULL if slot does not match an existing slot. - */ - const char* (*getSuffix)(struct boot_control_module *module, unsigned slot); - - /* - * (*isSlotMarkedSucessful)() returns if the slot passed in parameter has - * been marked as successful using markBootSuccessful. - * Returns 1 if the slot has been marked as successful, 0 if it's - * not the case, and -errno on error. - */ - int (*isSlotMarkedSuccessful)(struct boot_control_module *module, unsigned slot); - - /** - * Returns the active slot to boot into on the next boot. If - * setActiveBootSlot() has been called, the getter function should return - * the same slot as the one provided in the last setActiveBootSlot() call. - */ - unsigned (*getActiveBootSlot)(struct boot_control_module *module); - - void* reserved[30]; -} boot_control_module_t; - - -__END_DECLS - -#endif // ANDROID_INCLUDE_HARDWARE_BOOT_CONTROL_H +../../include_all/hardware/boot_control.h
\ No newline at end of file diff --git a/include/hardware/camera.h b/include/hardware/camera.h index b1f18fff..2f56bc81 100644..120000 --- a/include/hardware/camera.h +++ b/include/hardware/camera.h @@ -1,298 +1 @@ -/* - * Copyright (C) 2010-2011 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_INCLUDE_CAMERA_H -#define ANDROID_INCLUDE_CAMERA_H - -#include "camera_common.h" - -/** - * Camera device HAL, initial version [ CAMERA_DEVICE_API_VERSION_1_0 ] - * - * DEPRECATED. New devices should use Camera HAL v3.2 or newer. - * - * Supports the android.hardware.Camera API, and the android.hardware.camera2 - * API in legacy mode only. - * - * Camera devices that support this version of the HAL must return a value in - * the range HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF) in - * camera_device_t.common.version. CAMERA_DEVICE_API_VERSION_1_0 is the - * recommended value. - * - * Camera modules that implement version 2.0 or higher of camera_module_t must - * also return the value of camera_device_t.common.version in - * camera_info_t.device_version. - * - * See camera_common.h for more details. - */ - -__BEGIN_DECLS - -struct camera_memory; -typedef void (*camera_release_memory)(struct camera_memory *mem); - -typedef struct camera_memory { - void *data; - size_t size; - void *handle; - camera_release_memory release; -} camera_memory_t; - -typedef camera_memory_t* (*camera_request_memory)(int fd, size_t buf_size, unsigned int num_bufs, - void *user); - -typedef void (*camera_notify_callback)(int32_t msg_type, - int32_t ext1, - int32_t ext2, - void *user); - -typedef void (*camera_data_callback)(int32_t msg_type, - const camera_memory_t *data, unsigned int index, - camera_frame_metadata_t *metadata, void *user); - -typedef void (*camera_data_timestamp_callback)(int64_t timestamp, - int32_t msg_type, - const camera_memory_t *data, unsigned int index, - void *user); - -#define HAL_CAMERA_PREVIEW_WINDOW_TAG 0xcafed00d - -typedef struct preview_stream_ops { - int (*dequeue_buffer)(struct preview_stream_ops* w, - buffer_handle_t** buffer, int *stride); - int (*enqueue_buffer)(struct preview_stream_ops* w, - buffer_handle_t* buffer); - int (*cancel_buffer)(struct preview_stream_ops* w, - buffer_handle_t* buffer); - int (*set_buffer_count)(struct preview_stream_ops* w, int count); - int (*set_buffers_geometry)(struct preview_stream_ops* pw, - int w, int h, int format); - int (*set_crop)(struct preview_stream_ops *w, - int left, int top, int right, int bottom); - int (*set_usage)(struct preview_stream_ops* w, int usage); - int (*set_swap_interval)(struct preview_stream_ops *w, int interval); - int (*get_min_undequeued_buffer_count)(const struct preview_stream_ops *w, - int *count); - int (*lock_buffer)(struct preview_stream_ops* w, - buffer_handle_t* buffer); - // Timestamps are measured in nanoseconds, and must be comparable - // and monotonically increasing between two frames in the same - // preview stream. They do not need to be comparable between - // consecutive or parallel preview streams, cameras, or app runs. - int (*set_timestamp)(struct preview_stream_ops *w, int64_t timestamp); -} preview_stream_ops_t; - -struct camera_device; -typedef struct camera_device_ops { - /** Set the ANativeWindow to which preview frames are sent */ - int (*set_preview_window)(struct camera_device *, - struct preview_stream_ops *window); - - /** Set the notification and data callbacks */ - void (*set_callbacks)(struct camera_device *, - camera_notify_callback notify_cb, - camera_data_callback data_cb, - camera_data_timestamp_callback data_cb_timestamp, - camera_request_memory get_memory, - void *user); - - /** - * The following three functions all take a msg_type, which is a bitmask of - * the messages defined in include/ui/Camera.h - */ - - /** - * Enable a message, or set of messages. - */ - void (*enable_msg_type)(struct camera_device *, int32_t msg_type); - - /** - * Disable a message, or a set of messages. - * - * Once received a call to disableMsgType(CAMERA_MSG_VIDEO_FRAME), camera - * HAL should not rely on its client to call releaseRecordingFrame() to - * release video recording frames sent out by the cameral HAL before and - * after the disableMsgType(CAMERA_MSG_VIDEO_FRAME) call. Camera HAL - * clients must not modify/access any video recording frame after calling - * disableMsgType(CAMERA_MSG_VIDEO_FRAME). - */ - void (*disable_msg_type)(struct camera_device *, int32_t msg_type); - - /** - * Query whether a message, or a set of messages, is enabled. Note that - * this is operates as an AND, if any of the messages queried are off, this - * will return false. - */ - int (*msg_type_enabled)(struct camera_device *, int32_t msg_type); - - /** - * Start preview mode. - */ - int (*start_preview)(struct camera_device *); - - /** - * Stop a previously started preview. - */ - void (*stop_preview)(struct camera_device *); - - /** - * Returns true if preview is enabled. - */ - int (*preview_enabled)(struct camera_device *); - - /** - * Request the camera HAL to store meta data or real YUV data in the video - * buffers sent out via CAMERA_MSG_VIDEO_FRAME for a recording session. If - * it is not called, the default camera HAL behavior is to store real YUV - * data in the video buffers. - * - * This method should be called before startRecording() in order to be - * effective. - * - * If meta data is stored in the video buffers, it is up to the receiver of - * the video buffers to interpret the contents and to find the actual frame - * data with the help of the meta data in the buffer. How this is done is - * outside of the scope of this method. - * - * Some camera HALs may not support storing meta data in the video buffers, - * but all camera HALs should support storing real YUV data in the video - * buffers. If the camera HAL does not support storing the meta data in the - * video buffers when it is requested to do do, INVALID_OPERATION must be - * returned. It is very useful for the camera HAL to pass meta data rather - * than the actual frame data directly to the video encoder, since the - * amount of the uncompressed frame data can be very large if video size is - * large. - * - * @param enable if true to instruct the camera HAL to store - * meta data in the video buffers; false to instruct - * the camera HAL to store real YUV data in the video - * buffers. - * - * @return OK on success. - */ - int (*store_meta_data_in_buffers)(struct camera_device *, int enable); - - /** - * Start record mode. When a record image is available, a - * CAMERA_MSG_VIDEO_FRAME message is sent with the corresponding - * frame. Every record frame must be released by a camera HAL client via - * releaseRecordingFrame() before the client calls - * disableMsgType(CAMERA_MSG_VIDEO_FRAME). After the client calls - * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's - * responsibility to manage the life-cycle of the video recording frames, - * and the client must not modify/access any video recording frames. - */ - int (*start_recording)(struct camera_device *); - - /** - * Stop a previously started recording. - */ - void (*stop_recording)(struct camera_device *); - - /** - * Returns true if recording is enabled. - */ - int (*recording_enabled)(struct camera_device *); - - /** - * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME. - * - * It is camera HAL client's responsibility to release video recording - * frames sent out by the camera HAL before the camera HAL receives a call - * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to - * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's - * responsibility to manage the life-cycle of the video recording frames. - */ - void (*release_recording_frame)(struct camera_device *, - const void *opaque); - - /** - * Start auto focus, the notification callback routine is called with - * CAMERA_MSG_FOCUS once when focusing is complete. autoFocus() will be - * called again if another auto focus is needed. - */ - int (*auto_focus)(struct camera_device *); - - /** - * Cancels auto-focus function. If the auto-focus is still in progress, - * this function will cancel it. Whether the auto-focus is in progress or - * not, this function will return the focus position to the default. If - * the camera does not support auto-focus, this is a no-op. - */ - int (*cancel_auto_focus)(struct camera_device *); - - /** - * Take a picture. - */ - int (*take_picture)(struct camera_device *); - - /** - * Cancel a picture that was started with takePicture. Calling this method - * when no picture is being taken is a no-op. - */ - int (*cancel_picture)(struct camera_device *); - - /** - * Set the camera parameters. This returns BAD_VALUE if any parameter is - * invalid or not supported. - */ - int (*set_parameters)(struct camera_device *, const char *parms); - - /** Retrieve the camera parameters. The buffer returned by the camera HAL - must be returned back to it with put_parameters, if put_parameters - is not NULL. - */ - char *(*get_parameters)(struct camera_device *); - - /** The camera HAL uses its own memory to pass us the parameters when we - call get_parameters. Use this function to return the memory back to - the camera HAL, if put_parameters is not NULL. If put_parameters - is NULL, then you have to use free() to release the memory. - */ - void (*put_parameters)(struct camera_device *, char *); - - /** - * Send command to camera driver. - */ - int (*send_command)(struct camera_device *, - int32_t cmd, int32_t arg1, int32_t arg2); - - /** - * Release the hardware resources owned by this object. Note that this is - * *not* done in the destructor. - */ - void (*release)(struct camera_device *); - - /** - * Dump state of the camera hardware - */ - int (*dump)(struct camera_device *, int fd); -} camera_device_ops_t; - -typedef struct camera_device { - /** - * camera_device.common.version must be in the range - * HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF). CAMERA_DEVICE_API_VERSION_1_0 is - * recommended. - */ - hw_device_t common; - camera_device_ops_t *ops; - void *priv; -} camera_device_t; - -__END_DECLS - -#endif /* #ifdef ANDROID_INCLUDE_CAMERA_H */ +../../include_all/hardware/camera.h
\ No newline at end of file diff --git a/include/hardware/camera2.h b/include/hardware/camera2.h index 547a1d78..6edb861d 100644..120000 --- a/include/hardware/camera2.h +++ b/include/hardware/camera2.h @@ -1,842 +1 @@ -/* - * Copyright (C) 2012 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_INCLUDE_CAMERA2_H -#define ANDROID_INCLUDE_CAMERA2_H - -#include "camera_common.h" -#include "system/camera_metadata.h" - -/** - * Camera device HAL 2.1 [ CAMERA_DEVICE_API_VERSION_2_0, CAMERA_DEVICE_API_VERSION_2_1 ] - * - * NO LONGER SUPPORTED. The camera service will no longer load HAL modules that - * contain HAL v2.0 or v2.1 devices. - * - * New devices should use Camera HAL v3.2 or newer. - * - * Supports the android.hardware.Camera API, and the android.hardware.camera2 - * API in legacy mode only. - * - * Camera devices that support this version of the HAL must return - * CAMERA_DEVICE_API_VERSION_2_1 in camera_device_t.common.version and in - * camera_info_t.device_version (from camera_module_t.get_camera_info). - * - * Camera modules that may contain version 2.x devices must implement at least - * version 2.0 of the camera module interface (as defined by - * camera_module_t.common.module_api_version). - * - * See camera_common.h for more versioning details. - * - * Version history: - * - * 2.0: CAMERA_DEVICE_API_VERSION_2_0. Initial release (Android 4.2): - * - Sufficient for implementing existing android.hardware.Camera API. - * - Allows for ZSL queue in camera service layer - * - Not tested for any new features such manual capture control, - * Bayer RAW capture, reprocessing of RAW data. - * - * 2.1: CAMERA_DEVICE_API_VERSION_2_1. Support per-device static metadata: - * - Add get_instance_metadata() method to retrieve metadata that is fixed - * after device open, but may be variable between open() calls. - */ - -__BEGIN_DECLS - -struct camera2_device; - -/********************************************************************** - * - * Input/output stream buffer queue interface definitions - * - */ - -/** - * Output image stream queue interface. A set of these methods is provided to - * the HAL device in allocate_stream(), and are used to interact with the - * gralloc buffer queue for that stream. They may not be called until after - * allocate_stream returns. - */ -typedef struct camera2_stream_ops { - /** - * Get a buffer to fill from the queue. The size and format of the buffer - * are fixed for a given stream (defined in allocate_stream), and the stride - * should be queried from the platform gralloc module. The gralloc buffer - * will have been allocated based on the usage flags provided by - * allocate_stream, and will be locked for use. - */ - int (*dequeue_buffer)(const struct camera2_stream_ops* w, - buffer_handle_t** buffer); - - /** - * Push a filled buffer to the stream to be used by the consumer. - * - * The timestamp represents the time at start of exposure of the first row - * of the image; it must be from a monotonic clock, and is measured in - * nanoseconds. The timestamps do not need to be comparable between - * different cameras, or consecutive instances of the same camera. However, - * they must be comparable between streams from the same camera. If one - * capture produces buffers for multiple streams, each stream must have the - * same timestamp for that buffer, and that timestamp must match the - * timestamp in the output frame metadata. - */ - int (*enqueue_buffer)(const struct camera2_stream_ops* w, - int64_t timestamp, - buffer_handle_t* buffer); - /** - * Return a buffer to the queue without marking it as filled. - */ - int (*cancel_buffer)(const struct camera2_stream_ops* w, - buffer_handle_t* buffer); - /** - * Set the crop window for subsequently enqueued buffers. The parameters are - * measured in pixels relative to the buffer width and height. - */ - int (*set_crop)(const struct camera2_stream_ops *w, - int left, int top, int right, int bottom); - -} camera2_stream_ops_t; - -/** - * Temporary definition during transition. - * - * These formats will be removed and replaced with - * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. To maximize forward compatibility, - * HAL implementations are strongly recommended to treat FORMAT_OPAQUE and - * FORMAT_ZSL as equivalent to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, and - * return HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED in the format_actual output - * parameter of allocate_stream, allowing the gralloc module to select the - * specific format based on the usage flags from the camera and the stream - * consumer. - */ -enum { - CAMERA2_HAL_PIXEL_FORMAT_OPAQUE = HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, - CAMERA2_HAL_PIXEL_FORMAT_ZSL = -1 -}; - -/** - * Transport header for compressed JPEG buffers in output streams. - * - * To capture JPEG images, a stream is created using the pixel format - * HAL_PIXEL_FORMAT_BLOB, and the static metadata field android.jpeg.maxSize is - * used as the buffer size. Since compressed JPEG images are of variable size, - * the HAL needs to include the final size of the compressed image using this - * structure inside the output stream buffer. The JPEG blob ID field must be set - * to CAMERA2_JPEG_BLOB_ID. - * - * Transport header should be at the end of the JPEG output stream buffer. That - * means the jpeg_blob_id must start at byte[android.jpeg.maxSize - - * sizeof(camera2_jpeg_blob)]. Any HAL using this transport header must - * account for it in android.jpeg.maxSize. The JPEG data itself starts at - * byte[0] and should be jpeg_size bytes long. - */ -typedef struct camera2_jpeg_blob { - uint16_t jpeg_blob_id; - uint32_t jpeg_size; -} camera2_jpeg_blob_t; - -enum { - CAMERA2_JPEG_BLOB_ID = 0x00FF -}; - -/** - * Input reprocess stream queue management. A set of these methods is provided - * to the HAL device in allocate_reprocess_stream(); they are used to interact - * with the reprocess stream's input gralloc buffer queue. - */ -typedef struct camera2_stream_in_ops { - /** - * Get the next buffer of image data to reprocess. The width, height, and - * format of the buffer is fixed in allocate_reprocess_stream(), and the - * stride and other details should be queried from the platform gralloc - * module as needed. The buffer will already be locked for use. - */ - int (*acquire_buffer)(const struct camera2_stream_in_ops *w, - buffer_handle_t** buffer); - /** - * Return a used buffer to the buffer queue for reuse. - */ - int (*release_buffer)(const struct camera2_stream_in_ops *w, - buffer_handle_t* buffer); - -} camera2_stream_in_ops_t; - -/********************************************************************** - * - * Metadata queue management, used for requests sent to HAL module, and for - * frames produced by the HAL. - * - */ - -enum { - CAMERA2_REQUEST_QUEUE_IS_BOTTOMLESS = -1 -}; - -/** - * Request input queue protocol: - * - * The framework holds the queue and its contents. At start, the queue is empty. - * - * 1. When the first metadata buffer is placed into the queue, the framework - * signals the device by calling notify_request_queue_not_empty(). - * - * 2. After receiving notify_request_queue_not_empty, the device must call - * dequeue() once it's ready to handle the next buffer. - * - * 3. Once the device has processed a buffer, and is ready for the next buffer, - * it must call dequeue() again instead of waiting for a notification. If - * there are no more buffers available, dequeue() will return NULL. After - * this point, when a buffer becomes available, the framework must call - * notify_request_queue_not_empty() again. If the device receives a NULL - * return from dequeue, it does not need to query the queue again until a - * notify_request_queue_not_empty() call is received from the source. - * - * 4. If the device calls buffer_count() and receives 0, this does not mean that - * the framework will provide a notify_request_queue_not_empty() call. The - * framework will only provide such a notification after the device has - * received a NULL from dequeue, or on initial startup. - * - * 5. The dequeue() call in response to notify_request_queue_not_empty() may be - * on the same thread as the notify_request_queue_not_empty() call, and may - * be performed from within the notify call. - * - * 6. All dequeued request buffers must be returned to the framework by calling - * free_request, including when errors occur, a device flush is requested, or - * when the device is shutting down. - */ -typedef struct camera2_request_queue_src_ops { - /** - * Get the count of request buffers pending in the queue. May return - * CAMERA2_REQUEST_QUEUE_IS_BOTTOMLESS if a repeating request (stream - * request) is currently configured. Calling this method has no effect on - * whether the notify_request_queue_not_empty() method will be called by the - * framework. - */ - int (*request_count)(const struct camera2_request_queue_src_ops *q); - - /** - * Get a metadata buffer from the framework. Returns OK if there is no - * error. If the queue is empty, returns NULL in buffer. In that case, the - * device must wait for a notify_request_queue_not_empty() message before - * attempting to dequeue again. Buffers obtained in this way must be - * returned to the framework with free_request(). - */ - int (*dequeue_request)(const struct camera2_request_queue_src_ops *q, - camera_metadata_t **buffer); - /** - * Return a metadata buffer to the framework once it has been used, or if - * an error or shutdown occurs. - */ - int (*free_request)(const struct camera2_request_queue_src_ops *q, - camera_metadata_t *old_buffer); - -} camera2_request_queue_src_ops_t; - -/** - * Frame output queue protocol: - * - * The framework holds the queue and its contents. At start, the queue is empty. - * - * 1. When the device is ready to fill an output metadata frame, it must dequeue - * a metadata buffer of the required size. - * - * 2. It should then fill the metadata buffer, and place it on the frame queue - * using enqueue_frame. The framework takes ownership of the frame. - * - * 3. In case of an error, a request to flush the pipeline, or shutdown, the - * device must return any affected dequeued frames to the framework by - * calling cancel_frame. - */ -typedef struct camera2_frame_queue_dst_ops { - /** - * Get an empty metadata buffer to fill from the framework. The new metadata - * buffer will have room for entries number of metadata entries, plus - * data_bytes worth of extra storage. Frames dequeued here must be returned - * to the framework with either cancel_frame or enqueue_frame. - */ - int (*dequeue_frame)(const struct camera2_frame_queue_dst_ops *q, - size_t entries, size_t data_bytes, - camera_metadata_t **buffer); - - /** - * Return a dequeued metadata buffer to the framework for reuse; do not mark it as - * filled. Use when encountering errors, or flushing the internal request queue. - */ - int (*cancel_frame)(const struct camera2_frame_queue_dst_ops *q, - camera_metadata_t *buffer); - - /** - * Place a completed metadata frame on the frame output queue. - */ - int (*enqueue_frame)(const struct camera2_frame_queue_dst_ops *q, - camera_metadata_t *buffer); - -} camera2_frame_queue_dst_ops_t; - -/********************************************************************** - * - * Notification callback and message definition, and trigger definitions - * - */ - -/** - * Asynchronous notification callback from the HAL, fired for various - * reasons. Only for information independent of frame capture, or that require - * specific timing. The user pointer must be the same one that was passed to the - * device in set_notify_callback(). - */ -typedef void (*camera2_notify_callback)(int32_t msg_type, - int32_t ext1, - int32_t ext2, - int32_t ext3, - void *user); - -/** - * Possible message types for camera2_notify_callback - */ -enum { - /** - * An error has occurred. Argument ext1 contains the error code, and - * ext2 and ext3 contain any error-specific information. - */ - CAMERA2_MSG_ERROR = 0x0001, - /** - * The exposure of a given request has begun. Argument ext1 contains the - * frame number, and ext2 and ext3 contain the low-order and high-order - * bytes of the timestamp for when exposure began. - * (timestamp = (ext3 << 32 | ext2)) - */ - CAMERA2_MSG_SHUTTER = 0x0010, - /** - * The autofocus routine has changed state. Argument ext1 contains the new - * state; the values are the same as those for the metadata field - * android.control.afState. Ext2 contains the latest trigger ID passed to - * trigger_action(CAMERA2_TRIGGER_AUTOFOCUS) or - * trigger_action(CAMERA2_TRIGGER_CANCEL_AUTOFOCUS), or 0 if trigger has not - * been called with either of those actions. - */ - CAMERA2_MSG_AUTOFOCUS = 0x0020, - /** - * The autoexposure routine has changed state. Argument ext1 contains the - * new state; the values are the same as those for the metadata field - * android.control.aeState. Ext2 contains the latest trigger ID value passed to - * trigger_action(CAMERA2_TRIGGER_PRECAPTURE_METERING), or 0 if that method - * has not been called. - */ - CAMERA2_MSG_AUTOEXPOSURE = 0x0021, - /** - * The auto-whitebalance routine has changed state. Argument ext1 contains - * the new state; the values are the same as those for the metadata field - * android.control.awbState. Ext2 contains the latest trigger ID passed to - * trigger_action(CAMERA2_TRIGGER_PRECAPTURE_METERING), or 0 if that method - * has not been called. - */ - CAMERA2_MSG_AUTOWB = 0x0022 -}; - -/** - * Error codes for CAMERA_MSG_ERROR - */ -enum { - /** - * A serious failure occured. Camera device may not work without reboot, and - * no further frames or buffer streams will be produced by the - * device. Device should be treated as closed. - */ - CAMERA2_MSG_ERROR_HARDWARE = 0x0001, - /** - * A serious failure occured. No further frames or buffer streams will be - * produced by the device. Device should be treated as closed. The client - * must reopen the device to use it again. - */ - CAMERA2_MSG_ERROR_DEVICE, - /** - * An error has occurred in processing a request. No output (metadata or - * buffers) will be produced for this request. ext2 contains the frame - * number of the request. Subsequent requests are unaffected, and the device - * remains operational. - */ - CAMERA2_MSG_ERROR_REQUEST, - /** - * An error has occurred in producing an output frame metadata buffer for a - * request, but image buffers for it will still be available. Subsequent - * requests are unaffected, and the device remains operational. ext2 - * contains the frame number of the request. - */ - CAMERA2_MSG_ERROR_FRAME, - /** - * An error has occurred in placing an output buffer into a stream for a - * request. The frame metadata and other buffers may still be - * available. Subsequent requests are unaffected, and the device remains - * operational. ext2 contains the frame number of the request, and ext3 - * contains the stream id. - */ - CAMERA2_MSG_ERROR_STREAM, - /** - * Number of error types - */ - CAMERA2_MSG_NUM_ERRORS -}; - -/** - * Possible trigger ids for trigger_action() - */ -enum { - /** - * Trigger an autofocus cycle. The effect of the trigger depends on the - * autofocus mode in effect when the trigger is received, which is the mode - * listed in the latest capture request to be dequeued by the HAL. If the - * mode is OFF, EDOF, or FIXED, the trigger has no effect. In AUTO, MACRO, - * or CONTINUOUS_* modes, see below for the expected behavior. The state of - * the autofocus cycle can be tracked in android.control.afMode and the - * corresponding notifications. - * - ** - * In AUTO or MACRO mode, the AF state transitions (and notifications) - * when calling with trigger ID = N with the previous ID being K are: - * - * Initial state Transitions - * INACTIVE (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) - * AF_FOCUSED (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) - * AF_NOT_FOCUSED (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) - * ACTIVE_SCAN (K) -> AF_FOCUSED(N) or AF_NOT_FOCUSED(N) - * PASSIVE_SCAN (K) Not used in AUTO/MACRO mode - * PASSIVE_FOCUSED (K) Not used in AUTO/MACRO mode - * - ** - * In CONTINUOUS_PICTURE mode, triggering AF must lock the AF to the current - * lens position and transition the AF state to either AF_FOCUSED or - * NOT_FOCUSED. If a passive scan is underway, that scan must complete and - * then lock the lens position and change AF state. TRIGGER_CANCEL_AUTOFOCUS - * will allow the AF to restart its operation. - * - * Initial state Transitions - * INACTIVE (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) - * PASSIVE_FOCUSED (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) - * PASSIVE_SCAN (K) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) - * AF_FOCUSED (K) no effect except to change next notification ID to N - * AF_NOT_FOCUSED (K) no effect except to change next notification ID to N - * - ** - * In CONTINUOUS_VIDEO mode, triggering AF must lock the AF to the current - * lens position and transition the AF state to either AF_FOCUSED or - * NOT_FOCUSED. If a passive scan is underway, it must immediately halt, in - * contrast with CONTINUOUS_PICTURE mode. TRIGGER_CANCEL_AUTOFOCUS will - * allow the AF to restart its operation. - * - * Initial state Transitions - * INACTIVE (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) - * PASSIVE_FOCUSED (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) - * PASSIVE_SCAN (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) - * AF_FOCUSED (K) no effect except to change next notification ID to N - * AF_NOT_FOCUSED (K) no effect except to change next notification ID to N - * - * Ext1 is an ID that must be returned in subsequent auto-focus state change - * notifications through camera2_notify_callback() and stored in - * android.control.afTriggerId. - */ - CAMERA2_TRIGGER_AUTOFOCUS = 0x0001, - /** - * Send a cancel message to the autofocus algorithm. The effect of the - * cancellation depends on the autofocus mode in effect when the trigger is - * received, which is the mode listed in the latest capture request to be - * dequeued by the HAL. If the AF mode is OFF or EDOF, the cancel has no - * effect. For other modes, the lens should return to its default position, - * any current autofocus scan must be canceled, and the AF state should be - * set to INACTIVE. - * - * The state of the autofocus cycle can be tracked in android.control.afMode - * and the corresponding notification. Continuous autofocus modes may resume - * focusing operations thereafter exactly as if the camera had just been set - * to a continuous AF mode. - * - * Ext1 is an ID that must be returned in subsequent auto-focus state change - * notifications through camera2_notify_callback() and stored in - * android.control.afTriggerId. - */ - CAMERA2_TRIGGER_CANCEL_AUTOFOCUS, - /** - * Trigger a pre-capture metering cycle, which may include firing the flash - * to determine proper capture parameters. Typically, this trigger would be - * fired for a half-depress of a camera shutter key, or before a snapshot - * capture in general. The state of the metering cycle can be tracked in - * android.control.aeMode and the corresponding notification. If the - * auto-exposure mode is OFF, the trigger does nothing. - * - * Ext1 is an ID that must be returned in subsequent - * auto-exposure/auto-white balance state change notifications through - * camera2_notify_callback() and stored in android.control.aePrecaptureId. - */ - CAMERA2_TRIGGER_PRECAPTURE_METERING -}; - -/** - * Possible template types for construct_default_request() - */ -enum { - /** - * Standard camera preview operation with 3A on auto. - */ - CAMERA2_TEMPLATE_PREVIEW = 1, - /** - * Standard camera high-quality still capture with 3A and flash on auto. - */ - CAMERA2_TEMPLATE_STILL_CAPTURE, - /** - * Standard video recording plus preview with 3A on auto, torch off. - */ - CAMERA2_TEMPLATE_VIDEO_RECORD, - /** - * High-quality still capture while recording video. Application will - * include preview, video record, and full-resolution YUV or JPEG streams in - * request. Must not cause stuttering on video stream. 3A on auto. - */ - CAMERA2_TEMPLATE_VIDEO_SNAPSHOT, - /** - * Zero-shutter-lag mode. Application will request preview and - * full-resolution data for each frame, and reprocess it to JPEG when a - * still image is requested by user. Settings should provide highest-quality - * full-resolution images without compromising preview frame rate. 3A on - * auto. - */ - CAMERA2_TEMPLATE_ZERO_SHUTTER_LAG, - - /* Total number of templates */ - CAMERA2_TEMPLATE_COUNT -}; - - -/********************************************************************** - * - * Camera device operations - * - */ -typedef struct camera2_device_ops { - - /********************************************************************** - * Request and frame queue setup and management methods - */ - - /** - * Pass in input request queue interface methods. - */ - int (*set_request_queue_src_ops)(const struct camera2_device *, - const camera2_request_queue_src_ops_t *request_src_ops); - - /** - * Notify device that the request queue is no longer empty. Must only be - * called when the first buffer is added a new queue, or after the source - * has returned NULL in response to a dequeue call. - */ - int (*notify_request_queue_not_empty)(const struct camera2_device *); - - /** - * Pass in output frame queue interface methods - */ - int (*set_frame_queue_dst_ops)(const struct camera2_device *, - const camera2_frame_queue_dst_ops_t *frame_dst_ops); - - /** - * Number of camera requests being processed by the device at the moment - * (captures/reprocesses that have had their request dequeued, but have not - * yet been enqueued onto output pipeline(s) ). No streams may be released - * by the framework until the in-progress count is 0. - */ - int (*get_in_progress_count)(const struct camera2_device *); - - /** - * Flush all in-progress captures. This includes all dequeued requests - * (regular or reprocessing) that have not yet placed any outputs into a - * stream or the frame queue. Partially completed captures must be completed - * normally. No new requests may be dequeued from the request queue until - * the flush completes. - */ - int (*flush_captures_in_progress)(const struct camera2_device *); - - /** - * Create a filled-in default request for standard camera use cases. - * - * The device must return a complete request that is configured to meet the - * requested use case, which must be one of the CAMERA2_TEMPLATE_* - * enums. All request control fields must be included, except for - * android.request.outputStreams. - * - * The metadata buffer returned must be allocated with - * allocate_camera_metadata. The framework takes ownership of the buffer. - */ - int (*construct_default_request)(const struct camera2_device *, - int request_template, - camera_metadata_t **request); - - /********************************************************************** - * Stream management - */ - - /** - * allocate_stream: - * - * Allocate a new output stream for use, defined by the output buffer width, - * height, target, and possibly the pixel format. Returns the new stream's - * ID, gralloc usage flags, minimum queue buffer count, and possibly the - * pixel format, on success. Error conditions: - * - * - Requesting a width/height/format combination not listed as - * supported by the sensor's static characteristics - * - * - Asking for too many streams of a given format type (2 bayer raw - * streams, for example). - * - * Input parameters: - * - * - width, height, format: Specification for the buffers to be sent through - * this stream. Format is a value from the HAL_PIXEL_FORMAT_* list. If - * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform - * gralloc module will select a format based on the usage flags provided - * by the camera HAL and the consumer of the stream. The camera HAL should - * inspect the buffers handed to it in the register_stream_buffers call to - * obtain the implementation-specific format if necessary. - * - * - stream_ops: A structure of function pointers for obtaining and queuing - * up buffers for this stream. The underlying stream will be configured - * based on the usage and max_buffers outputs. The methods in this - * structure may not be called until after allocate_stream returns. - * - * Output parameters: - * - * - stream_id: An unsigned integer identifying this stream. This value is - * used in incoming requests to identify the stream, and in releasing the - * stream. - * - * - usage: The gralloc usage mask needed by the HAL device for producing - * the requested type of data. This is used in allocating new gralloc - * buffers for the stream buffer queue. - * - * - max_buffers: The maximum number of buffers the HAL device may need to - * have dequeued at the same time. The device may not dequeue more buffers - * than this value at the same time. - * - */ - int (*allocate_stream)( - const struct camera2_device *, - // inputs - uint32_t width, - uint32_t height, - int format, - const camera2_stream_ops_t *stream_ops, - // outputs - uint32_t *stream_id, - uint32_t *format_actual, // IGNORED, will be removed - uint32_t *usage, - uint32_t *max_buffers); - - /** - * Register buffers for a given stream. This is called after a successful - * allocate_stream call, and before the first request referencing the stream - * is enqueued. This method is intended to allow the HAL device to map or - * otherwise prepare the buffers for later use. num_buffers is guaranteed to - * be at least max_buffers (from allocate_stream), but may be larger. The - * buffers will already be locked for use. At the end of the call, all the - * buffers must be ready to be returned to the queue. If the stream format - * was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the camera HAL should - * inspect the passed-in buffers here to determine any platform-private - * pixel format information. - */ - int (*register_stream_buffers)( - const struct camera2_device *, - uint32_t stream_id, - int num_buffers, - buffer_handle_t *buffers); - - /** - * Release a stream. Returns an error if called when get_in_progress_count - * is non-zero, or if the stream id is invalid. - */ - int (*release_stream)( - const struct camera2_device *, - uint32_t stream_id); - - /** - * allocate_reprocess_stream: - * - * Allocate a new input stream for use, defined by the output buffer width, - * height, and the pixel format. Returns the new stream's ID, gralloc usage - * flags, and required simultaneously acquirable buffer count, on - * success. Error conditions: - * - * - Requesting a width/height/format combination not listed as - * supported by the sensor's static characteristics - * - * - Asking for too many reprocessing streams to be configured at once. - * - * Input parameters: - * - * - width, height, format: Specification for the buffers to be sent through - * this stream. Format must be a value from the HAL_PIXEL_FORMAT_* list. - * - * - reprocess_stream_ops: A structure of function pointers for acquiring - * and releasing buffers for this stream. The underlying stream will be - * configured based on the usage and max_buffers outputs. - * - * Output parameters: - * - * - stream_id: An unsigned integer identifying this stream. This value is - * used in incoming requests to identify the stream, and in releasing the - * stream. These ids are numbered separately from the input stream ids. - * - * - consumer_usage: The gralloc usage mask needed by the HAL device for - * consuming the requested type of data. This is used in allocating new - * gralloc buffers for the stream buffer queue. - * - * - max_buffers: The maximum number of buffers the HAL device may need to - * have acquired at the same time. The device may not have more buffers - * acquired at the same time than this value. - * - */ - int (*allocate_reprocess_stream)(const struct camera2_device *, - uint32_t width, - uint32_t height, - uint32_t format, - const camera2_stream_in_ops_t *reprocess_stream_ops, - // outputs - uint32_t *stream_id, - uint32_t *consumer_usage, - uint32_t *max_buffers); - - /** - * allocate_reprocess_stream_from_stream: - * - * Allocate a new input stream for use, which will use the buffers allocated - * for an existing output stream. That is, after the HAL enqueues a buffer - * onto the output stream, it may see that same buffer handed to it from - * this input reprocessing stream. After the HAL releases the buffer back to - * the reprocessing stream, it will be returned to the output queue for - * reuse. - * - * Error conditions: - * - * - Using an output stream of unsuitable size/format for the basis of the - * reprocessing stream. - * - * - Attempting to allocatee too many reprocessing streams at once. - * - * Input parameters: - * - * - output_stream_id: The ID of an existing output stream which has - * a size and format suitable for reprocessing. - * - * - reprocess_stream_ops: A structure of function pointers for acquiring - * and releasing buffers for this stream. The underlying stream will use - * the same graphics buffer handles as the output stream uses. - * - * Output parameters: - * - * - stream_id: An unsigned integer identifying this stream. This value is - * used in incoming requests to identify the stream, and in releasing the - * stream. These ids are numbered separately from the input stream ids. - * - * The HAL client must always release the reprocessing stream before it - * releases the output stream it is based on. - * - */ - int (*allocate_reprocess_stream_from_stream)(const struct camera2_device *, - uint32_t output_stream_id, - const camera2_stream_in_ops_t *reprocess_stream_ops, - // outputs - uint32_t *stream_id); - - /** - * Release a reprocessing stream. Returns an error if called when - * get_in_progress_count is non-zero, or if the stream id is not - * valid. - */ - int (*release_reprocess_stream)( - const struct camera2_device *, - uint32_t stream_id); - - /********************************************************************** - * Miscellaneous methods - */ - - /** - * Trigger asynchronous activity. This is used for triggering special - * behaviors of the camera 3A routines when they are in use. See the - * documentation for CAMERA2_TRIGGER_* above for details of the trigger ids - * and their arguments. - */ - int (*trigger_action)(const struct camera2_device *, - uint32_t trigger_id, - int32_t ext1, - int32_t ext2); - - /** - * Notification callback setup - */ - int (*set_notify_callback)(const struct camera2_device *, - camera2_notify_callback notify_cb, - void *user); - - /** - * Get methods to query for vendor extension metadata tag infomation. May - * set ops to NULL if no vendor extension tags are defined. - */ - int (*get_metadata_vendor_tag_ops)(const struct camera2_device*, - vendor_tag_query_ops_t **ops); - - /** - * Dump state of the camera hardware - */ - int (*dump)(const struct camera2_device *, int fd); - - /** - * Get device-instance-specific metadata. This metadata must be constant for - * a single instance of the camera device, but may be different between - * open() calls. The returned camera_metadata pointer must be valid until - * the device close() method is called. - * - * Version information: - * - * CAMERA_DEVICE_API_VERSION_2_0: - * - * Not available. Framework may not access this function pointer. - * - * CAMERA_DEVICE_API_VERSION_2_1: - * - * Valid. Can be called by the framework. - * - */ - int (*get_instance_metadata)(const struct camera2_device *, - camera_metadata **instance_metadata); - -} camera2_device_ops_t; - -/********************************************************************** - * - * Camera device definition - * - */ -typedef struct camera2_device { - /** - * common.version must equal CAMERA_DEVICE_API_VERSION_2_0 to identify - * this device as implementing version 2.0 of the camera device HAL. - */ - hw_device_t common; - camera2_device_ops_t *ops; - void *priv; -} camera2_device_t; - -__END_DECLS - -#endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */ +../../include_all/hardware/camera2.h
\ No newline at end of file diff --git a/include/hardware/camera3.h b/include/hardware/camera3.h index 7fb86dfb..10676a9d 100644..120000 --- a/include/hardware/camera3.h +++ b/include/hardware/camera3.h @@ -1,3564 +1 @@ -/* - * Copyright (C) 2013-2018 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_INCLUDE_CAMERA3_H -#define ANDROID_INCLUDE_CAMERA3_H - -#include <system/camera_metadata.h> -#include "camera_common.h" - -/** - * Camera device HAL 3.6[ CAMERA_DEVICE_API_VERSION_3_6 ] - * - * This is the current recommended version of the camera device HAL. - * - * Supports the android.hardware.Camera API, and as of v3.2, the - * android.hardware.camera2 API as LIMITED or above hardware level. - * - * Camera devices that support this version of the HAL must return - * CAMERA_DEVICE_API_VERSION_3_6 in camera_device_t.common.version and in - * camera_info_t.device_version (from camera_module_t.get_camera_info). - * - * CAMERA_DEVICE_API_VERSION_3_3 and above: - * Camera modules that may contain version 3.3 or above devices must - * implement at least version 2.2 of the camera module interface (as defined - * by camera_module_t.common.module_api_version). - * - * CAMERA_DEVICE_API_VERSION_3_2: - * Camera modules that may contain version 3.2 devices must implement at - * least version 2.2 of the camera module interface (as defined by - * camera_module_t.common.module_api_version). - * - * <= CAMERA_DEVICE_API_VERSION_3_1: - * Camera modules that may contain version 3.1 (or 3.0) devices must - * implement at least version 2.0 of the camera module interface - * (as defined by camera_module_t.common.module_api_version). - * - * See camera_common.h for more versioning details. - * - * Documentation index: - * S1. Version history - * S2. Startup and operation sequencing - * S3. Operational modes - * S4. 3A modes and state machines - * S5. Cropping - * S6. Error management - * S7. Key Performance Indicator (KPI) glossary - * S8. Sample Use Cases - * S9. Notes on Controls and Metadata - * S10. Reprocessing flow and controls - */ - -/** - * S1. Version history: - * - * 1.0: Initial Android camera HAL (Android 4.0) [camera.h]: - * - * - Converted from C++ CameraHardwareInterface abstraction layer. - * - * - Supports android.hardware.Camera API. - * - * 2.0: Initial release of expanded-capability HAL (Android 4.2) [camera2.h]: - * - * - Sufficient for implementing existing android.hardware.Camera API. - * - * - Allows for ZSL queue in camera service layer - * - * - Not tested for any new features such manual capture control, Bayer RAW - * capture, reprocessing of RAW data. - * - * 3.0: First revision of expanded-capability HAL: - * - * - Major version change since the ABI is completely different. No change to - * the required hardware capabilities or operational model from 2.0. - * - * - Reworked input request and stream queue interfaces: Framework calls into - * HAL with next request and stream buffers already dequeued. Sync framework - * support is included, necessary for efficient implementations. - * - * - Moved triggers into requests, most notifications into results. - * - * - Consolidated all callbacks into framework into one structure, and all - * setup methods into a single initialize() call. - * - * - Made stream configuration into a single call to simplify stream - * management. Bidirectional streams replace STREAM_FROM_STREAM construct. - * - * - Limited mode semantics for older/limited hardware devices. - * - * 3.1: Minor revision of expanded-capability HAL: - * - * - configure_streams passes consumer usage flags to the HAL. - * - * - flush call to drop all in-flight requests/buffers as fast as possible. - * - * 3.2: Minor revision of expanded-capability HAL: - * - * - Deprecates get_metadata_vendor_tag_ops. Please use get_vendor_tag_ops - * in camera_common.h instead. - * - * - register_stream_buffers deprecated. All gralloc buffers provided - * by framework to HAL in process_capture_request may be new at any time. - * - * - add partial result support. process_capture_result may be called - * multiple times with a subset of the available result before the full - * result is available. - * - * - add manual template to camera3_request_template. The applications may - * use this template to control the capture settings directly. - * - * - Rework the bidirectional and input stream specifications. - * - * - change the input buffer return path. The buffer is returned in - * process_capture_result instead of process_capture_request. - * - * 3.3: Minor revision of expanded-capability HAL: - * - * - OPAQUE and YUV reprocessing API updates. - * - * - Basic support for depth output buffers. - * - * - Addition of data_space field to camera3_stream_t. - * - * - Addition of rotation field to camera3_stream_t. - * - * - Addition of camera3 stream configuration operation mode to camera3_stream_configuration_t - * - * 3.4: Minor additions to supported metadata and changes to data_space support - * - * - Add ANDROID_SENSOR_OPAQUE_RAW_SIZE static metadata as mandatory if - * RAW_OPAQUE format is supported. - * - * - Add ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE static metadata as - * mandatory if any RAW format is supported - * - * - Switch camera3_stream_t data_space field to a more flexible definition, - * using the version 0 definition of dataspace encoding. - * - * - General metadata additions which are available to use for HALv3.2 or - * newer: - * - ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3 - * - ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST - * - ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE - * - ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL - * - ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL - * - ANDROID_SENSOR_OPAQUE_RAW_SIZE - * - ANDROID_SENSOR_OPTICAL_BLACK_REGIONS - * - * 3.5: Minor revisions to support session parameters and logical multi camera: - * - * - Add ANDROID_REQUEST_AVAILABLE_SESSION_KEYS static metadata, which is - * optional for implementations that want to support session parameters. If support is - * needed, then Hal should populate the list with all available capture request keys - * that can cause severe processing delays when modified by client. Typical examples - * include parameters that require time-consuming HW re-configuration or internal camera - * pipeline update. - * - * - Add a session parameter field to camera3_stream_configuration which can be populated - * by clients with initial values for the keys found in ANDROID_REQUEST_AVAILABLE_SESSION_KEYS. - * - * - Metadata additions for logical multi camera capability: - * - ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA - * - ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS - * - ANDROID_LOGICAL_MULTI_CAMERA_SYNC_TYPE - * - * - Add physical camera id field in camera3_stream, so that for a logical - * multi camera, the application has the option to specify which physical camera - * a particular stream is configured on. - * - * - Add physical camera id and settings field in camera3_capture_request, so that - * for a logical multi camera, the application has the option to specify individual - * settings for a particular physical device. - * - * 3.6: Minor revisions to support HAL buffer management APIs: - * - * - Add ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION static metadata, which allows HAL to - * opt in to the new buffer management APIs described below. - * - * - Add request_stream_buffers() and return_stream_buffers() to camera3_callback_ops_t for HAL to - * request and return output buffers from camera service. - * - * - Add signal_stream_flush() to camera3_device_ops_t for camera service to notify HAL an - * upcoming configure_streams() call requires HAL to return buffers of certain streams. - * - * - Add CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID to support BLOB with only JPEG apps - * segments and thumbnail (without main image bitstream). Camera framework - * uses such stream togerther with a HAL YUV_420_888/IMPLEMENTATION_DEFINED - * stream to encode HEIC (ISO/IEC 23008-12) image. - * - * - Add is_reconfiguration_required() to camera3_device_ops_t to enable HAL to skip or - * trigger stream reconfiguration depending on new session parameter values. - * - */ - -/** - * S2. Startup and general expected operation sequence: - * - * 1. Framework calls camera_module_t->common.open(), which returns a - * hardware_device_t structure. - * - * 2. Framework inspects the hardware_device_t->version field, and instantiates - * the appropriate handler for that version of the camera hardware device. In - * case the version is CAMERA_DEVICE_API_VERSION_3_0, the device is cast to - * a camera3_device_t. - * - * 3. Framework calls camera3_device_t->ops->initialize() with the framework - * callback function pointers. This will only be called this one time after - * open(), before any other functions in the ops structure are called. - * - * 4. The framework calls camera3_device_t->ops->configure_streams() with a list - * of input/output streams to the HAL device. - * - * 5. <= CAMERA_DEVICE_API_VERSION_3_1: - * - * The framework allocates gralloc buffers and calls - * camera3_device_t->ops->register_stream_buffers() for at least one of the - * output streams listed in configure_streams. The same stream is registered - * only once. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * camera3_device_t->ops->register_stream_buffers() is not called and must - * be NULL. - * - * 6. The framework requests default settings for some number of use cases with - * calls to camera3_device_t->ops->construct_default_request_settings(). This - * may occur any time after step 3. - * - * 7. The framework constructs and sends the first capture request to the HAL, - * with settings based on one of the sets of default settings, and with at - * least one output stream, which has been registered earlier by the - * framework. This is sent to the HAL with - * camera3_device_t->ops->process_capture_request(). The HAL must block the - * return of this call until it is ready for the next request to be sent. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * The buffer_handle_t provided in the camera3_stream_buffer_t array - * in the camera3_capture_request_t may be new and never-before-seen - * by the HAL on any given new request. - * - * 8. The framework continues to submit requests, and call - * construct_default_request_settings to get default settings buffers for - * other use cases. - * - * <= CAMERA_DEVICE_API_VERSION_3_1: - * - * The framework may call register_stream_buffers() at this time for - * not-yet-registered streams. - * - * 9. When the capture of a request begins (sensor starts exposing for the - * capture) or processing a reprocess request begins, the HAL - * calls camera3_callback_ops_t->notify() with the SHUTTER event, including - * the frame number and the timestamp for start of exposure. For a reprocess - * request, the timestamp must be the start of exposure of the input image - * which can be looked up with android.sensor.timestamp from - * camera3_capture_request_t.settings when process_capture_request() is - * called. - * - * <= CAMERA_DEVICE_API_VERSION_3_1: - * - * This notify call must be made before the first call to - * process_capture_result() for that frame number. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * The camera3_callback_ops_t->notify() call with the SHUTTER event should - * be made as early as possible since the framework will be unable to - * deliver gralloc buffers to the application layer (for that frame) until - * it has a valid timestamp for the start of exposure (or the input image's - * start of exposure for a reprocess request). - * - * Both partial metadata results and the gralloc buffers may be sent to the - * framework at any time before or after the SHUTTER event. - * - * 10. After some pipeline delay, the HAL begins to return completed captures to - * the framework with camera3_callback_ops_t->process_capture_result(). These - * are returned in the same order as the requests were submitted. Multiple - * requests can be in flight at once, depending on the pipeline depth of the - * camera HAL device. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * Once a buffer is returned by process_capture_result as part of the - * camera3_stream_buffer_t array, and the fence specified by release_fence - * has been signaled (this is a no-op for -1 fences), the ownership of that - * buffer is considered to be transferred back to the framework. After that, - * the HAL must no longer retain that particular buffer, and the - * framework may clean up the memory for it immediately. - * - * process_capture_result may be called multiple times for a single frame, - * each time with a new disjoint piece of metadata and/or set of gralloc - * buffers. The framework will accumulate these partial metadata results - * into one result. - * - * In particular, it is legal for a process_capture_result to be called - * simultaneously for both a frame N and a frame N+1 as long as the - * above rule holds for gralloc buffers (both input and output). - * - * 11. After some time, the framework may stop submitting new requests, wait for - * the existing captures to complete (all buffers filled, all results - * returned), and then call configure_streams() again. This resets the camera - * hardware and pipeline for a new set of input/output streams. Some streams - * may be reused from the previous configuration; if these streams' buffers - * had already been registered with the HAL, they will not be registered - * again. The framework then continues from step 7, if at least one - * registered output stream remains (otherwise, step 5 is required first). - * - * 12. Alternatively, the framework may call camera3_device_t->common->close() - * to end the camera session. This may be called at any time when no other - * calls from the framework are active, although the call may block until all - * in-flight captures have completed (all results returned, all buffers - * filled). After the close call returns, no more calls to the - * camera3_callback_ops_t functions are allowed from the HAL. Once the - * close() call is underway, the framework may not call any other HAL device - * functions. - * - * 13. In case of an error or other asynchronous event, the HAL must call - * camera3_callback_ops_t->notify() with the appropriate error/event - * message. After returning from a fatal device-wide error notification, the - * HAL should act as if close() had been called on it. However, the HAL must - * either cancel or complete all outstanding captures before calling - * notify(), so that once notify() is called with a fatal error, the - * framework will not receive further callbacks from the device. Methods - * besides close() should return -ENODEV or NULL after the notify() method - * returns from a fatal error message. - */ - -/** - * S3. Operational modes: - * - * The camera 3 HAL device can implement one of two possible operational modes; - * limited and full. Full support is expected from new higher-end - * devices. Limited mode has hardware requirements roughly in line with those - * for a camera HAL device v1 implementation, and is expected from older or - * inexpensive devices. Full is a strict superset of limited, and they share the - * same essential operational flow, as documented above. - * - * The HAL must indicate its level of support with the - * android.info.supportedHardwareLevel static metadata entry, with 0 indicating - * limited mode, and 1 indicating full mode support. - * - * Roughly speaking, limited-mode devices do not allow for application control - * of capture settings (3A control only), high-rate capture of high-resolution - * images, raw sensor readout, or support for YUV output streams above maximum - * recording resolution (JPEG only for large images). - * - * ** Details of limited mode behavior: - * - * - Limited-mode devices do not need to implement accurate synchronization - * between capture request settings and the actual image data - * captured. Instead, changes to settings may take effect some time in the - * future, and possibly not for the same output frame for each settings - * entry. Rapid changes in settings may result in some settings never being - * used for a capture. However, captures that include high-resolution output - * buffers ( > 1080p ) have to use the settings as specified (but see below - * for processing rate). - * - * - Limited-mode devices do not need to support most of the - * settings/result/static info metadata. Specifically, only the following settings - * are expected to be consumed or produced by a limited-mode HAL device: - * - * android.control.aeAntibandingMode (controls and dynamic) - * android.control.aeExposureCompensation (controls and dynamic) - * android.control.aeLock (controls and dynamic) - * android.control.aeMode (controls and dynamic) - * android.control.aeRegions (controls and dynamic) - * android.control.aeTargetFpsRange (controls and dynamic) - * android.control.aePrecaptureTrigger (controls and dynamic) - * android.control.afMode (controls and dynamic) - * android.control.afRegions (controls and dynamic) - * android.control.awbLock (controls and dynamic) - * android.control.awbMode (controls and dynamic) - * android.control.awbRegions (controls and dynamic) - * android.control.captureIntent (controls and dynamic) - * android.control.effectMode (controls and dynamic) - * android.control.mode (controls and dynamic) - * android.control.sceneMode (controls and dynamic) - * android.control.videoStabilizationMode (controls and dynamic) - * android.control.aeAvailableAntibandingModes (static) - * android.control.aeAvailableModes (static) - * android.control.aeAvailableTargetFpsRanges (static) - * android.control.aeCompensationRange (static) - * android.control.aeCompensationStep (static) - * android.control.afAvailableModes (static) - * android.control.availableEffects (static) - * android.control.availableSceneModes (static) - * android.control.availableVideoStabilizationModes (static) - * android.control.awbAvailableModes (static) - * android.control.maxRegions (static) - * android.control.sceneModeOverrides (static) - * android.control.aeState (dynamic) - * android.control.afState (dynamic) - * android.control.awbState (dynamic) - * - * android.flash.mode (controls and dynamic) - * android.flash.info.available (static) - * - * android.info.supportedHardwareLevel (static) - * - * android.jpeg.gpsCoordinates (controls and dynamic) - * android.jpeg.gpsProcessingMethod (controls and dynamic) - * android.jpeg.gpsTimestamp (controls and dynamic) - * android.jpeg.orientation (controls and dynamic) - * android.jpeg.quality (controls and dynamic) - * android.jpeg.thumbnailQuality (controls and dynamic) - * android.jpeg.thumbnailSize (controls and dynamic) - * android.jpeg.availableThumbnailSizes (static) - * android.jpeg.maxSize (static) - * - * android.lens.info.minimumFocusDistance (static) - * - * android.request.id (controls and dynamic) - * - * android.scaler.cropRegion (controls and dynamic) - * android.scaler.availableStreamConfigurations (static) - * android.scaler.availableMinFrameDurations (static) - * android.scaler.availableStallDurations (static) - * android.scaler.availableMaxDigitalZoom (static) - * android.scaler.maxDigitalZoom (static) - * android.scaler.croppingType (static) - * - * android.sensor.orientation (static) - * android.sensor.timestamp (dynamic) - * - * android.statistics.faceDetectMode (controls and dynamic) - * android.statistics.info.availableFaceDetectModes (static) - * android.statistics.faceIds (dynamic) - * android.statistics.faceLandmarks (dynamic) - * android.statistics.faceRectangles (dynamic) - * android.statistics.faceScores (dynamic) - * - * android.sync.frameNumber (dynamic) - * android.sync.maxLatency (static) - * - * - Captures in limited mode that include high-resolution (> 1080p) output - * buffers may block in process_capture_request() until all the output buffers - * have been filled. A full-mode HAL device must process sequences of - * high-resolution requests at the rate indicated in the static metadata for - * that pixel format. The HAL must still call process_capture_result() to - * provide the output; the framework must simply be prepared for - * process_capture_request() to block until after process_capture_result() for - * that request completes for high-resolution captures for limited-mode - * devices. - * - * - Full-mode devices must support below additional capabilities: - * - 30fps at maximum resolution is preferred, more than 20fps is required. - * - Per frame control (android.sync.maxLatency == PER_FRAME_CONTROL). - * - Sensor manual control metadata. See MANUAL_SENSOR defined in - * android.request.availableCapabilities. - * - Post-processing manual control metadata. See MANUAL_POST_PROCESSING defined - * in android.request.availableCapabilities. - * - */ - -/** - * S4. 3A modes and state machines: - * - * While the actual 3A algorithms are up to the HAL implementation, a high-level - * state machine description is defined by the HAL interface, to allow the HAL - * device and the framework to communicate about the current state of 3A, and to - * trigger 3A events. - * - * When the device is opened, all the individual 3A states must be - * STATE_INACTIVE. Stream configuration does not reset 3A. For example, locked - * focus must be maintained across the configure() call. - * - * Triggering a 3A action involves simply setting the relevant trigger entry in - * the settings for the next request to indicate start of trigger. For example, - * the trigger for starting an autofocus scan is setting the entry - * ANDROID_CONTROL_AF_TRIGGER to ANDROID_CONTROL_AF_TRIGGER_START for one - * request, and cancelling an autofocus scan is triggered by setting - * ANDROID_CONTROL_AF_TRIGGER to ANDROID_CONTRL_AF_TRIGGER_CANCEL. Otherwise, - * the entry will not exist, or be set to ANDROID_CONTROL_AF_TRIGGER_IDLE. Each - * request with a trigger entry set to a non-IDLE value will be treated as an - * independent triggering event. - * - * At the top level, 3A is controlled by the ANDROID_CONTROL_MODE setting, which - * selects between no 3A (ANDROID_CONTROL_MODE_OFF), normal AUTO mode - * (ANDROID_CONTROL_MODE_AUTO), and using the scene mode setting - * (ANDROID_CONTROL_USE_SCENE_MODE). - * - * - In OFF mode, each of the individual AE/AF/AWB modes are effectively OFF, - * and none of the capture controls may be overridden by the 3A routines. - * - * - In AUTO mode, Auto-focus, auto-exposure, and auto-whitebalance all run - * their own independent algorithms, and have their own mode, state, and - * trigger metadata entries, as listed in the next section. - * - * - In USE_SCENE_MODE, the value of the ANDROID_CONTROL_SCENE_MODE entry must - * be used to determine the behavior of 3A routines. In SCENE_MODEs other than - * FACE_PRIORITY, the HAL must override the values of - * ANDROId_CONTROL_AE/AWB/AF_MODE to be the mode it prefers for the selected - * SCENE_MODE. For example, the HAL may prefer SCENE_MODE_NIGHT to use - * CONTINUOUS_FOCUS AF mode. Any user selection of AE/AWB/AF_MODE when scene - * must be ignored for these scene modes. - * - * - For SCENE_MODE_FACE_PRIORITY, the AE/AWB/AF_MODE controls work as in - * ANDROID_CONTROL_MODE_AUTO, but the 3A routines must bias toward metering - * and focusing on any detected faces in the scene. - * - * S4.1. Auto-focus settings and result entries: - * - * Main metadata entries: - * - * ANDROID_CONTROL_AF_MODE: Control for selecting the current autofocus - * mode. Set by the framework in the request settings. - * - * AF_MODE_OFF: AF is disabled; the framework/app directly controls lens - * position. - * - * AF_MODE_AUTO: Single-sweep autofocus. No lens movement unless AF is - * triggered. - * - * AF_MODE_MACRO: Single-sweep up-close autofocus. No lens movement unless - * AF is triggered. - * - * AF_MODE_CONTINUOUS_VIDEO: Smooth continuous focusing, for recording - * video. Triggering immediately locks focus in current - * position. Canceling resumes cotinuous focusing. - * - * AF_MODE_CONTINUOUS_PICTURE: Fast continuous focusing, for - * zero-shutter-lag still capture. Triggering locks focus once currently - * active sweep concludes. Canceling resumes continuous focusing. - * - * AF_MODE_EDOF: Advanced extended depth of field focusing. There is no - * autofocus scan, so triggering one or canceling one has no effect. - * Images are focused automatically by the HAL. - * - * ANDROID_CONTROL_AF_STATE: Dynamic metadata describing the current AF - * algorithm state, reported by the HAL in the result metadata. - * - * AF_STATE_INACTIVE: No focusing has been done, or algorithm was - * reset. Lens is not moving. Always the state for MODE_OFF or MODE_EDOF. - * When the device is opened, it must start in this state. - * - * AF_STATE_PASSIVE_SCAN: A continuous focus algorithm is currently scanning - * for good focus. The lens is moving. - * - * AF_STATE_PASSIVE_FOCUSED: A continuous focus algorithm believes it is - * well focused. The lens is not moving. The HAL may spontaneously leave - * this state. - * - * AF_STATE_PASSIVE_UNFOCUSED: A continuous focus algorithm believes it is - * not well focused. The lens is not moving. The HAL may spontaneously - * leave this state. - * - * AF_STATE_ACTIVE_SCAN: A scan triggered by the user is underway. - * - * AF_STATE_FOCUSED_LOCKED: The AF algorithm believes it is focused. The - * lens is not moving. - * - * AF_STATE_NOT_FOCUSED_LOCKED: The AF algorithm has been unable to - * focus. The lens is not moving. - * - * ANDROID_CONTROL_AF_TRIGGER: Control for starting an autofocus scan, the - * meaning of which is mode- and state- dependent. Set by the framework in - * the request settings. - * - * AF_TRIGGER_IDLE: No current trigger. - * - * AF_TRIGGER_START: Trigger start of AF scan. Effect is mode and state - * dependent. - * - * AF_TRIGGER_CANCEL: Cancel current AF scan if any, and reset algorithm to - * default. - * - * Additional metadata entries: - * - * ANDROID_CONTROL_AF_REGIONS: Control for selecting the regions of the FOV - * that should be used to determine good focus. This applies to all AF - * modes that scan for focus. Set by the framework in the request - * settings. - * - * S4.2. Auto-exposure settings and result entries: - * - * Main metadata entries: - * - * ANDROID_CONTROL_AE_MODE: Control for selecting the current auto-exposure - * mode. Set by the framework in the request settings. - * - * AE_MODE_OFF: Autoexposure is disabled; the user controls exposure, gain, - * frame duration, and flash. - * - * AE_MODE_ON: Standard autoexposure, with flash control disabled. User may - * set flash to fire or to torch mode. - * - * AE_MODE_ON_AUTO_FLASH: Standard autoexposure, with flash on at HAL's - * discretion for precapture and still capture. User control of flash - * disabled. - * - * AE_MODE_ON_ALWAYS_FLASH: Standard autoexposure, with flash always fired - * for capture, and at HAL's discretion for precapture.. User control of - * flash disabled. - * - * AE_MODE_ON_AUTO_FLASH_REDEYE: Standard autoexposure, with flash on at - * HAL's discretion for precapture and still capture. Use a flash burst - * at end of precapture sequence to reduce redeye in the final - * picture. User control of flash disabled. - * - * ANDROID_CONTROL_AE_STATE: Dynamic metadata describing the current AE - * algorithm state, reported by the HAL in the result metadata. - * - * AE_STATE_INACTIVE: Initial AE state after mode switch. When the device is - * opened, it must start in this state. - * - * AE_STATE_SEARCHING: AE is not converged to a good value, and is adjusting - * exposure parameters. - * - * AE_STATE_CONVERGED: AE has found good exposure values for the current - * scene, and the exposure parameters are not changing. HAL may - * spontaneously leave this state to search for better solution. - * - * AE_STATE_LOCKED: AE has been locked with the AE_LOCK control. Exposure - * values are not changing. - * - * AE_STATE_FLASH_REQUIRED: The HAL has converged exposure, but believes - * flash is required for a sufficiently bright picture. Used for - * determining if a zero-shutter-lag frame can be used. - * - * AE_STATE_PRECAPTURE: The HAL is in the middle of a precapture - * sequence. Depending on AE mode, this mode may involve firing the - * flash for metering, or a burst of flash pulses for redeye reduction. - * - * ANDROID_CONTROL_AE_PRECAPTURE_TRIGGER: Control for starting a metering - * sequence before capturing a high-quality image. Set by the framework in - * the request settings. - * - * PRECAPTURE_TRIGGER_IDLE: No current trigger. - * - * PRECAPTURE_TRIGGER_START: Start a precapture sequence. The HAL should - * use the subsequent requests to measure good exposure/white balance - * for an upcoming high-resolution capture. - * - * Additional metadata entries: - * - * ANDROID_CONTROL_AE_LOCK: Control for locking AE controls to their current - * values - * - * ANDROID_CONTROL_AE_EXPOSURE_COMPENSATION: Control for adjusting AE - * algorithm target brightness point. - * - * ANDROID_CONTROL_AE_TARGET_FPS_RANGE: Control for selecting the target frame - * rate range for the AE algorithm. The AE routine cannot change the frame - * rate to be outside these bounds. - * - * ANDROID_CONTROL_AE_REGIONS: Control for selecting the regions of the FOV - * that should be used to determine good exposure levels. This applies to - * all AE modes besides OFF. - * - * S4.3. Auto-whitebalance settings and result entries: - * - * Main metadata entries: - * - * ANDROID_CONTROL_AWB_MODE: Control for selecting the current white-balance - * mode. - * - * AWB_MODE_OFF: Auto-whitebalance is disabled. User controls color matrix. - * - * AWB_MODE_AUTO: Automatic white balance is enabled; 3A controls color - * transform, possibly using more complex transforms than a simple - * matrix. - * - * AWB_MODE_INCANDESCENT: Fixed white balance settings good for indoor - * incandescent (tungsten) lighting, roughly 2700K. - * - * AWB_MODE_FLUORESCENT: Fixed white balance settings good for fluorescent - * lighting, roughly 5000K. - * - * AWB_MODE_WARM_FLUORESCENT: Fixed white balance settings good for - * fluorescent lighting, roughly 3000K. - * - * AWB_MODE_DAYLIGHT: Fixed white balance settings good for daylight, - * roughly 5500K. - * - * AWB_MODE_CLOUDY_DAYLIGHT: Fixed white balance settings good for clouded - * daylight, roughly 6500K. - * - * AWB_MODE_TWILIGHT: Fixed white balance settings good for - * near-sunset/sunrise, roughly 15000K. - * - * AWB_MODE_SHADE: Fixed white balance settings good for areas indirectly - * lit by the sun, roughly 7500K. - * - * ANDROID_CONTROL_AWB_STATE: Dynamic metadata describing the current AWB - * algorithm state, reported by the HAL in the result metadata. - * - * AWB_STATE_INACTIVE: Initial AWB state after mode switch. When the device - * is opened, it must start in this state. - * - * AWB_STATE_SEARCHING: AWB is not converged to a good value, and is - * changing color adjustment parameters. - * - * AWB_STATE_CONVERGED: AWB has found good color adjustment values for the - * current scene, and the parameters are not changing. HAL may - * spontaneously leave this state to search for better solution. - * - * AWB_STATE_LOCKED: AWB has been locked with the AWB_LOCK control. Color - * adjustment values are not changing. - * - * Additional metadata entries: - * - * ANDROID_CONTROL_AWB_LOCK: Control for locking AWB color adjustments to - * their current values. - * - * ANDROID_CONTROL_AWB_REGIONS: Control for selecting the regions of the FOV - * that should be used to determine good color balance. This applies only - * to auto-WB mode. - * - * S4.4. General state machine transition notes - * - * Switching between AF, AE, or AWB modes always resets the algorithm's state - * to INACTIVE. Similarly, switching between CONTROL_MODE or - * CONTROL_SCENE_MODE if CONTROL_MODE == USE_SCENE_MODE resets all the - * algorithm states to INACTIVE. - * - * The tables below are per-mode. - * - * S4.5. AF state machines - * - * when enabling AF or changing AF mode - *| state | trans. cause | new state | notes | - *+--------------------+---------------+--------------------+------------------+ - *| Any | AF mode change| INACTIVE | | - *+--------------------+---------------+--------------------+------------------+ - * - * mode = AF_MODE_OFF or AF_MODE_EDOF - *| state | trans. cause | new state | notes | - *+--------------------+---------------+--------------------+------------------+ - *| INACTIVE | | INACTIVE | Never changes | - *+--------------------+---------------+--------------------+------------------+ - * - * mode = AF_MODE_AUTO or AF_MODE_MACRO - *| state | trans. cause | new state | notes | - *+--------------------+---------------+--------------------+------------------+ - *| INACTIVE | AF_TRIGGER | ACTIVE_SCAN | Start AF sweep | - *| | | | Lens now moving | - *+--------------------+---------------+--------------------+------------------+ - *| ACTIVE_SCAN | AF sweep done | FOCUSED_LOCKED | If AF successful | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| ACTIVE_SCAN | AF sweep done | NOT_FOCUSED_LOCKED | If AF successful | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| ACTIVE_SCAN | AF_CANCEL | INACTIVE | Cancel/reset AF | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF | - *+--------------------+---------------+--------------------+------------------+ - *| FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep | - *| | | | Lens now moving | - *+--------------------+---------------+--------------------+------------------+ - *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF | - *+--------------------+---------------+--------------------+------------------+ - *| NOT_FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep | - *| | | | Lens now moving | - *+--------------------+---------------+--------------------+------------------+ - *| All states | mode change | INACTIVE | | - *+--------------------+---------------+--------------------+------------------+ - * - * mode = AF_MODE_CONTINUOUS_VIDEO - *| state | trans. cause | new state | notes | - *+--------------------+---------------+--------------------+------------------+ - *| INACTIVE | HAL initiates | PASSIVE_SCAN | Start AF scan | - *| | new scan | | Lens now moving | - *+--------------------+---------------+--------------------+------------------+ - *| INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | HAL completes | PASSIVE_FOCUSED | End AF scan | - *| | current scan | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | HAL fails | PASSIVE_UNFOCUSED | End AF scan | - *| | current scan | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | - *| | | | if focus is good | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | - *| | | | if focus is bad | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens | - *| | | | position | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_FOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | - *| | new scan | | Lens now moving | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_UNFOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | - *| | new scan | | Lens now moving | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect | - *+--------------------+---------------+--------------------+------------------+ - *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | - *+--------------------+---------------+--------------------+------------------+ - *| NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect | - *+--------------------+---------------+--------------------+------------------+ - *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | - *+--------------------+---------------+--------------------+------------------+ - * - * mode = AF_MODE_CONTINUOUS_PICTURE - *| state | trans. cause | new state | notes | - *+--------------------+---------------+--------------------+------------------+ - *| INACTIVE | HAL initiates | PASSIVE_SCAN | Start AF scan | - *| | new scan | | Lens now moving | - *+--------------------+---------------+--------------------+------------------+ - *| INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | HAL completes | PASSIVE_FOCUSED | End AF scan | - *| | current scan | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | HAL fails | PASSIVE_UNFOCUSED | End AF scan | - *| | current scan | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Eventual trans. | - *| | | | once focus good | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Eventual trans. | - *| | | | if cannot focus | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens | - *| | | | position | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_FOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | - *| | new scan | | Lens now moving | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_UNFOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | - *| | new scan | | Lens now moving | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | - *| | | | Lens now locked | - *+--------------------+---------------+--------------------+------------------+ - *| FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect | - *+--------------------+---------------+--------------------+------------------+ - *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | - *+--------------------+---------------+--------------------+------------------+ - *| NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect | - *+--------------------+---------------+--------------------+------------------+ - *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | - *+--------------------+---------------+--------------------+------------------+ - * - * S4.6. AE and AWB state machines - * - * The AE and AWB state machines are mostly identical. AE has additional - * FLASH_REQUIRED and PRECAPTURE states. So rows below that refer to those two - * states should be ignored for the AWB state machine. - * - * when enabling AE/AWB or changing AE/AWB mode - *| state | trans. cause | new state | notes | - *+--------------------+---------------+--------------------+------------------+ - *| Any | mode change | INACTIVE | | - *+--------------------+---------------+--------------------+------------------+ - * - * mode = AE_MODE_OFF / AWB mode not AUTO - *| state | trans. cause | new state | notes | - *+--------------------+---------------+--------------------+------------------+ - *| INACTIVE | | INACTIVE | AE/AWB disabled | - *+--------------------+---------------+--------------------+------------------+ - * - * mode = AE_MODE_ON_* / AWB_MODE_AUTO - *| state | trans. cause | new state | notes | - *+--------------------+---------------+--------------------+------------------+ - *| INACTIVE | HAL initiates | SEARCHING | | - *| | AE/AWB scan | | | - *+--------------------+---------------+--------------------+------------------+ - *| INACTIVE | AE/AWB_LOCK | LOCKED | values locked | - *| | on | | | - *+--------------------+---------------+--------------------+------------------+ - *| SEARCHING | HAL finishes | CONVERGED | good values, not | - *| | AE/AWB scan | | changing | - *+--------------------+---------------+--------------------+------------------+ - *| SEARCHING | HAL finishes | FLASH_REQUIRED | converged but too| - *| | AE scan | | dark w/o flash | - *+--------------------+---------------+--------------------+------------------+ - *| SEARCHING | AE/AWB_LOCK | LOCKED | values locked | - *| | on | | | - *+--------------------+---------------+--------------------+------------------+ - *| CONVERGED | HAL initiates | SEARCHING | values locked | - *| | AE/AWB scan | | | - *+--------------------+---------------+--------------------+------------------+ - *| CONVERGED | AE/AWB_LOCK | LOCKED | values locked | - *| | on | | | - *+--------------------+---------------+--------------------+------------------+ - *| FLASH_REQUIRED | HAL initiates | SEARCHING | values locked | - *| | AE/AWB scan | | | - *+--------------------+---------------+--------------------+------------------+ - *| FLASH_REQUIRED | AE/AWB_LOCK | LOCKED | values locked | - *| | on | | | - *+--------------------+---------------+--------------------+------------------+ - *| LOCKED | AE/AWB_LOCK | SEARCHING | values not good | - *| | off | | after unlock | - *+--------------------+---------------+--------------------+------------------+ - *| LOCKED | AE/AWB_LOCK | CONVERGED | values good | - *| | off | | after unlock | - *+--------------------+---------------+--------------------+------------------+ - *| LOCKED | AE_LOCK | FLASH_REQUIRED | exposure good, | - *| | off | | but too dark | - *+--------------------+---------------+--------------------+------------------+ - *| All AE states | PRECAPTURE_ | PRECAPTURE | Start precapture | - *| | START | | sequence | - *+--------------------+---------------+--------------------+------------------+ - *| PRECAPTURE | Sequence done.| CONVERGED | Ready for high- | - *| | AE_LOCK off | | quality capture | - *+--------------------+---------------+--------------------+------------------+ - *| PRECAPTURE | Sequence done.| LOCKED | Ready for high- | - *| | AE_LOCK on | | quality capture | - *+--------------------+---------------+--------------------+------------------+ - * - */ - -/** - * S5. Cropping: - * - * Cropping of the full pixel array (for digital zoom and other use cases where - * a smaller FOV is desirable) is communicated through the - * ANDROID_SCALER_CROP_REGION setting. This is a per-request setting, and can - * change on a per-request basis, which is critical for implementing smooth - * digital zoom. - * - * The region is defined as a rectangle (x, y, width, height), with (x, y) - * describing the top-left corner of the rectangle. The rectangle is defined on - * the coordinate system of the sensor active pixel array, with (0,0) being the - * top-left pixel of the active pixel array. Therefore, the width and height - * cannot be larger than the dimensions reported in the - * ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY static info field. The minimum allowed - * width and height are reported by the HAL through the - * ANDROID_SCALER_MAX_DIGITAL_ZOOM static info field, which describes the - * maximum supported zoom factor. Therefore, the minimum crop region width and - * height are: - * - * {width, height} = - * { floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[0] / - * ANDROID_SCALER_MAX_DIGITAL_ZOOM), - * floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[1] / - * ANDROID_SCALER_MAX_DIGITAL_ZOOM) } - * - * If the crop region needs to fulfill specific requirements (for example, it - * needs to start on even coordinates, and its width/height needs to be even), - * the HAL must do the necessary rounding and write out the final crop region - * used in the output result metadata. Similarly, if the HAL implements video - * stabilization, it must adjust the result crop region to describe the region - * actually included in the output after video stabilization is applied. In - * general, a camera-using application must be able to determine the field of - * view it is receiving based on the crop region, the dimensions of the image - * sensor, and the lens focal length. - * - * It is assumed that the cropping is applied after raw to other color space - * conversion. Raw streams (RAW16 and RAW_OPAQUE) don't have this conversion stage, - * and are not croppable. Therefore, the crop region must be ignored by the HAL - * for raw streams. - * - * Since the crop region applies to all non-raw streams, which may have different aspect - * ratios than the crop region, the exact sensor region used for each stream may - * be smaller than the crop region. Specifically, each stream should maintain - * square pixels and its aspect ratio by minimally further cropping the defined - * crop region. If the stream's aspect ratio is wider than the crop region, the - * stream should be further cropped vertically, and if the stream's aspect ratio - * is narrower than the crop region, the stream should be further cropped - * horizontally. - * - * In all cases, the stream crop must be centered within the full crop region, - * and each stream is only either cropped horizontally or vertical relative to - * the full crop region, never both. - * - * For example, if two streams are defined, a 640x480 stream (4:3 aspect), and a - * 1280x720 stream (16:9 aspect), below demonstrates the expected output regions - * for each stream for a few sample crop regions, on a hypothetical 3 MP (2000 x - * 1500 pixel array) sensor. - * - * Crop region: (500, 375, 1000, 750) (4:3 aspect ratio) - * - * 640x480 stream crop: (500, 375, 1000, 750) (equal to crop region) - * 1280x720 stream crop: (500, 469, 1000, 562) (marked with =) - * - * 0 1000 2000 - * +---------+---------+---------+----------+ - * | Active pixel array | - * | | - * | | - * + +-------------------+ + 375 - * | | | | - * | O===================O | - * | I 1280x720 stream I | - * + I I + 750 - * | I I | - * | O===================O | - * | | | | - * + +-------------------+ + 1125 - * | Crop region, 640x480 stream | - * | | - * | | - * +---------+---------+---------+----------+ 1500 - * - * Crop region: (500, 375, 1333, 750) (16:9 aspect ratio) - * - * 640x480 stream crop: (666, 375, 1000, 750) (marked with =) - * 1280x720 stream crop: (500, 375, 1333, 750) (equal to crop region) - * - * 0 1000 2000 - * +---------+---------+---------+----------+ - * | Active pixel array | - * | | - * | | - * + +---O==================O---+ + 375 - * | | I 640x480 stream I | | - * | | I I | | - * | | I I | | - * + | I I | + 750 - * | | I I | | - * | | I I | | - * | | I I | | - * + +---O==================O---+ + 1125 - * | Crop region, 1280x720 stream | - * | | - * | | - * +---------+---------+---------+----------+ 1500 - * - * Crop region: (500, 375, 750, 750) (1:1 aspect ratio) - * - * 640x480 stream crop: (500, 469, 750, 562) (marked with =) - * 1280x720 stream crop: (500, 543, 750, 414) (marged with #) - * - * 0 1000 2000 - * +---------+---------+---------+----------+ - * | Active pixel array | - * | | - * | | - * + +--------------+ + 375 - * | O==============O | - * | ################ | - * | # # | - * + # # + 750 - * | # # | - * | ################ 1280x720 | - * | O==============O 640x480 | - * + +--------------+ + 1125 - * | Crop region | - * | | - * | | - * +---------+---------+---------+----------+ 1500 - * - * And a final example, a 1024x1024 square aspect ratio stream instead of the - * 480p stream: - * - * Crop region: (500, 375, 1000, 750) (4:3 aspect ratio) - * - * 1024x1024 stream crop: (625, 375, 750, 750) (marked with #) - * 1280x720 stream crop: (500, 469, 1000, 562) (marked with =) - * - * 0 1000 2000 - * +---------+---------+---------+----------+ - * | Active pixel array | - * | | - * | 1024x1024 stream | - * + +--###############--+ + 375 - * | | # # | | - * | O===================O | - * | I 1280x720 stream I | - * + I I + 750 - * | I I | - * | O===================O | - * | | # # | | - * + +--###############--+ + 1125 - * | Crop region | - * | | - * | | - * +---------+---------+---------+----------+ 1500 - * - */ - -/** - * S6. Error management: - * - * Camera HAL device ops functions that have a return value will all return - * -ENODEV / NULL in case of a serious error. This means the device cannot - * continue operation, and must be closed by the framework. Once this error is - * returned by some method, or if notify() is called with ERROR_DEVICE, only - * the close() method can be called successfully. All other methods will return - * -ENODEV / NULL. - * - * If a device op is called in the wrong sequence, for example if the framework - * calls configure_streams() is called before initialize(), the device must - * return -ENOSYS from the call, and do nothing. - * - * Transient errors in image capture must be reported through notify() as follows: - * - * - The failure of an entire capture to occur must be reported by the HAL by - * calling notify() with ERROR_REQUEST. Individual errors for the result - * metadata or the output buffers must not be reported in this case. - * - * - If the metadata for a capture cannot be produced, but some image buffers - * were filled, the HAL must call notify() with ERROR_RESULT. - * - * - If an output image buffer could not be filled, but either the metadata was - * produced or some other buffers were filled, the HAL must call notify() with - * ERROR_BUFFER for each failed buffer. - * - * In each of these transient failure cases, the HAL must still call - * process_capture_result, with valid output and input (if an input buffer was - * submitted) buffer_handle_t. If the result metadata could not be produced, it - * should be NULL. If some buffers could not be filled, they must be returned with - * process_capture_result in the error state, their release fences must be set to - * the acquire fences passed by the framework, or -1 if they have been waited on by - * the HAL already. - * - * Invalid input arguments result in -EINVAL from the appropriate methods. In - * that case, the framework must act as if that call had never been made. - * - */ - -/** - * S7. Key Performance Indicator (KPI) glossary: - * - * This includes some critical definitions that are used by KPI metrics. - * - * Pipeline Latency: - * For a given capture request, the duration from the framework calling - * process_capture_request to the HAL sending capture result and all buffers - * back by process_capture_result call. To make the Pipeline Latency measure - * independent of frame rate, it is measured by frame count. - * - * For example, when frame rate is 30 (fps), the frame duration (time interval - * between adjacent frame capture time) is 33 (ms). - * If it takes 5 frames for framework to get the result and buffers back for - * a given request, then the Pipeline Latency is 5 (frames), instead of - * 5 x 33 = 165 (ms). - * - * The Pipeline Latency is determined by android.request.pipelineDepth and - * android.request.pipelineMaxDepth, see their definitions for more details. - * - */ - -/** - * S8. Sample Use Cases: - * - * This includes some typical use case examples the camera HAL may support. - * - * S8.1 Zero Shutter Lag (ZSL) with CAMERA3_STREAM_BIDIRECTIONAL stream. - * - * For this use case, the bidirectional stream will be used by the framework as follows: - * - * 1. The framework includes a buffer from this stream as output buffer in a - * request as normal. - * - * 2. Once the HAL device returns a filled output buffer to the framework, - * the framework may do one of two things with the filled buffer: - * - * 2. a. The framework uses the filled data, and returns the now-used buffer - * to the stream queue for reuse. This behavior exactly matches the - * OUTPUT type of stream. - * - * 2. b. The framework wants to reprocess the filled data, and uses the - * buffer as an input buffer for a request. Once the HAL device has - * used the reprocessing buffer, it then returns it to the - * framework. The framework then returns the now-used buffer to the - * stream queue for reuse. - * - * 3. The HAL device will be given the buffer again as an output buffer for - * a request at some future point. - * - * For ZSL use case, the pixel format for bidirectional stream will be - * HAL_PIXEL_FORMAT_RAW_OPAQUE or HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED if it - * is listed in android.scaler.availableInputOutputFormatsMap. When - * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, the gralloc - * usage flags for the consumer endpoint will be set to GRALLOC_USAGE_HW_CAMERA_ZSL. - * A configuration stream list that has BIDIRECTIONAL stream used as input, will - * usually also have a distinct OUTPUT stream to get the reprocessing data. For example, - * for the ZSL use case, the stream list might be configured with the following: - * - * - A HAL_PIXEL_FORMAT_RAW_OPAQUE bidirectional stream is used - * as input. - * - And a HAL_PIXEL_FORMAT_BLOB (JPEG) output stream. - * - * S8.2 ZSL (OPAQUE) reprocessing with CAMERA3_STREAM_INPUT stream. - * - * CAMERA_DEVICE_API_VERSION_3_3: - * When OPAQUE_REPROCESSING capability is supported by the camera device, the INPUT stream - * can be used for application/framework implemented use case like Zero Shutter Lag (ZSL). - * This kind of stream will be used by the framework as follows: - * - * 1. Application/framework configures an opaque (RAW or YUV based) format output stream that is - * used to produce the ZSL output buffers. The stream pixel format will be - * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. - * - * 2. Application/framework configures an opaque format input stream that is used to - * send the reprocessing ZSL buffers to the HAL. The stream pixel format will - * also be HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. - * - * 3. Application/framework configures a YUV/JPEG output stream that is used to receive the - * reprocessed data. The stream pixel format will be YCbCr_420/HAL_PIXEL_FORMAT_BLOB. - * - * 4. Application/framework picks a ZSL buffer from the ZSL output stream when a ZSL capture is - * issued by the application, and sends the data back as an input buffer in a - * reprocessing request, then sends to the HAL for reprocessing. - * - * 5. The HAL sends back the output YUV/JPEG result to framework. - * - * The HAL can select the actual opaque buffer format and configure the ISP pipeline - * appropriately based on the HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED format and - * the gralloc usage flag GRALLOC_USAGE_HW_CAMERA_ZSL. - - * S8.3 YUV reprocessing with CAMERA3_STREAM_INPUT stream. - * - * When YUV reprocessing is supported by the HAL, the INPUT stream - * can be used for the YUV reprocessing use cases like lucky-shot and image fusion. - * This kind of stream will be used by the framework as follows: - * - * 1. Application/framework configures an YCbCr_420 format output stream that is - * used to produce the output buffers. - * - * 2. Application/framework configures an YCbCr_420 format input stream that is used to - * send the reprocessing YUV buffers to the HAL. - * - * 3. Application/framework configures a YUV/JPEG output stream that is used to receive the - * reprocessed data. The stream pixel format will be YCbCr_420/HAL_PIXEL_FORMAT_BLOB. - * - * 4. Application/framework processes the output buffers (could be as simple as picking - * an output buffer directly) from the output stream when a capture is issued, and sends - * the data back as an input buffer in a reprocessing request, then sends to the HAL - * for reprocessing. - * - * 5. The HAL sends back the output YUV/JPEG result to framework. - * - */ - -/** - * S9. Notes on Controls and Metadata - * - * This section contains notes about the interpretation and usage of various metadata tags. - * - * S9.1 HIGH_QUALITY and FAST modes. - * - * Many camera post-processing blocks may be listed as having HIGH_QUALITY, - * FAST, and OFF operating modes. These blocks will typically also have an - * 'available modes' tag representing which of these operating modes are - * available on a given device. The general policy regarding implementing - * these modes is as follows: - * - * 1. Operating mode controls of hardware blocks that cannot be disabled - * must not list OFF in their corresponding 'available modes' tags. - * - * 2. OFF will always be included in their corresponding 'available modes' - * tag if it is possible to disable that hardware block. - * - * 3. FAST must always be included in the 'available modes' tags for all - * post-processing blocks supported on the device. If a post-processing - * block also has a slower and higher quality operating mode that does - * not meet the framerate requirements for FAST mode, HIGH_QUALITY should - * be included in the 'available modes' tag to represent this operating - * mode. - */ - -/** - * S10. Reprocessing flow and controls - * - * This section describes the OPAQUE and YUV reprocessing flow and controls. OPAQUE reprocessing - * uses an opaque format that is not directly application-visible, and the application can - * only select some of the output buffers and send back to HAL for reprocessing, while YUV - * reprocessing gives the application opportunity to process the buffers before reprocessing. - * - * S8 gives the stream configurations for the typical reprocessing uses cases, - * this section specifies the buffer flow and controls in more details. - * - * S10.1 OPAQUE (typically for ZSL use case) reprocessing flow and controls - * - * For OPAQUE reprocessing (e.g. ZSL) use case, after the application creates the specific - * output and input streams, runtime buffer flow and controls are specified as below: - * - * 1. Application starts output streaming by sending repeating requests for output - * opaque buffers and preview. The buffers are held by an application - * maintained circular buffer. The requests are based on CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG - * capture template, which should have all necessary settings that guarantee output - * frame rate is not slowed down relative to sensor output frame rate. - * - * 2. When a capture is issued, the application selects one output buffer based - * on application buffer selection logic, e.g. good AE and AF statistics etc. - * Application then creates an reprocess request based on the capture result associated - * with this selected buffer. The selected output buffer is now added to this reprocess - * request as an input buffer, the output buffer of this reprocess request should be - * either JPEG output buffer or YUV output buffer, or both, depending on the application - * choice. - * - * 3. Application then alters the reprocess settings to get best image quality. The HAL must - * support and only support below controls if the HAL support OPAQUE_REPROCESSING capability: - * - android.jpeg.* (if JPEG buffer is included as one of the output) - * - android.noiseReduction.mode (change to HIGH_QUALITY if it is supported) - * - android.edge.mode (change to HIGH_QUALITY if it is supported) - * All other controls must be ignored by the HAL. - * 4. HAL processed the input buffer and return the output buffers in the capture results - * as normal. - * - * S10.2 YUV reprocessing flow and controls - * - * The YUV reprocessing buffer flow is similar as OPAQUE reprocessing, with below difference: - * - * 1. Application may want to have finer granularity control of the intermediate YUV images - * (before reprocessing). For example, application may choose - * - android.noiseReduction.mode == MINIMAL - * to make sure the no YUV domain noise reduction has applied to the output YUV buffers, - * then it can do its own advanced noise reduction on them. For OPAQUE reprocessing case, this - * doesn't matter, as long as the final reprocessed image has the best quality. - * 2. Application may modify the YUV output buffer data. For example, for image fusion use - * case, where multiple output images are merged together to improve the signal-to-noise - * ratio (SNR). The input buffer may be generated from multiple buffers by the application. - * To avoid excessive amount of noise reduction and insufficient amount of edge enhancement - * being applied to the input buffer, the application can hint the HAL how much effective - * exposure time improvement has been done by the application, then the HAL can adjust the - * noise reduction and edge enhancement parameters to get best reprocessed image quality. - * Below tag can be used for this purpose: - * - android.reprocess.effectiveExposureFactor - * The value would be exposure time increase factor applied to the original output image, - * for example, if there are N image merged, the exposure time increase factor would be up - * to sqrt(N). See this tag spec for more details. - * - * S10.3 Reprocessing pipeline characteristics - * - * Reprocessing pipeline has below different characteristics comparing with normal output - * pipeline: - * - * 1. The reprocessing result can be returned ahead of the pending normal output results. But - * the FIFO ordering must be maintained for all reprocessing results. For example, there are - * below requests (A stands for output requests, B stands for reprocessing requests) - * being processed by the HAL: - * A1, A2, A3, A4, B1, A5, B2, A6... - * result of B1 can be returned before A1-A4, but result of B2 must be returned after B1. - * 2. Single input rule: For a given reprocessing request, all output buffers must be from the - * input buffer, rather than sensor output. For example, if a reprocess request include both - * JPEG and preview buffers, all output buffers must be produced from the input buffer - * included by the reprocessing request, rather than sensor. The HAL must not output preview - * buffers from sensor, while output JPEG buffer from the input buffer. - * 3. Input buffer will be from camera output directly (ZSL case) or indirectly(image fusion - * case). For the case where buffer is modified, the size will remain same. The HAL can - * notify CAMERA3_MSG_ERROR_REQUEST if buffer from unknown source is sent. - * 4. Result as reprocessing request: The HAL can expect that a reprocessing request is a copy - * of one of the output results with minor allowed setting changes. The HAL can notify - * CAMERA3_MSG_ERROR_REQUEST if a request from unknown source is issued. - * 5. Output buffers may not be used as inputs across the configure stream boundary, This is - * because an opaque stream like the ZSL output stream may have different actual image size - * inside of the ZSL buffer to save power and bandwidth for smaller resolution JPEG capture. - * The HAL may notify CAMERA3_MSG_ERROR_REQUEST if this case occurs. - * 6. HAL Reprocess requests error reporting during flush should follow the same rule specified - * by flush() method. - * - */ - -__BEGIN_DECLS - -struct camera3_device; - -/********************************************************************** - * - * Camera3 stream and stream buffer definitions. - * - * These structs and enums define the handles and contents of the input and - * output streams connecting the HAL to various framework and application buffer - * consumers. Each stream is backed by a gralloc buffer queue. - * - */ - -/** - * camera3_stream_type_t: - * - * The type of the camera stream, which defines whether the camera HAL device is - * the producer or the consumer for that stream, and how the buffers of the - * stream relate to the other streams. - */ -typedef enum camera3_stream_type { - /** - * This stream is an output stream; the camera HAL device will be - * responsible for filling buffers from this stream with newly captured or - * reprocessed image data. - */ - CAMERA3_STREAM_OUTPUT = 0, - - /** - * This stream is an input stream; the camera HAL device will be responsible - * for reading buffers from this stream and sending them through the camera - * processing pipeline, as if the buffer was a newly captured image from the - * imager. - * - * The pixel format for input stream can be any format reported by - * android.scaler.availableInputOutputFormatsMap. The pixel format of the - * output stream that is used to produce the reprocessing data may be any - * format reported by android.scaler.availableStreamConfigurations. The - * supported input/output stream combinations depends the camera device - * capabilities, see android.scaler.availableInputOutputFormatsMap for - * stream map details. - * - * This kind of stream is generally used to reprocess data into higher - * quality images (that otherwise would cause a frame rate performance - * loss), or to do off-line reprocessing. - * - * CAMERA_DEVICE_API_VERSION_3_3: - * The typical use cases are OPAQUE (typically ZSL) and YUV reprocessing, - * see S8.2, S8.3 and S10 for more details. - */ - CAMERA3_STREAM_INPUT = 1, - - /** - * This stream can be used for input and output. Typically, the stream is - * used as an output stream, but occasionally one already-filled buffer may - * be sent back to the HAL device for reprocessing. - * - * This kind of stream is meant generally for Zero Shutter Lag (ZSL) - * features, where copying the captured image from the output buffer to the - * reprocessing input buffer would be expensive. See S8.1 for more details. - * - * Note that the HAL will always be reprocessing data it produced. - * - */ - CAMERA3_STREAM_BIDIRECTIONAL = 2, - - /** - * Total number of framework-defined stream types - */ - CAMERA3_NUM_STREAM_TYPES - -} camera3_stream_type_t; - -/** - * camera3_stream_rotation_t: - * - * The required counterclockwise rotation of camera stream. - */ -typedef enum camera3_stream_rotation { - /* No rotation */ - CAMERA3_STREAM_ROTATION_0 = 0, - - /* Rotate by 90 degree counterclockwise */ - CAMERA3_STREAM_ROTATION_90 = 1, - - /* Rotate by 180 degree counterclockwise */ - CAMERA3_STREAM_ROTATION_180 = 2, - - /* Rotate by 270 degree counterclockwise */ - CAMERA3_STREAM_ROTATION_270 = 3 -} camera3_stream_rotation_t; - -/** - * camera3_stream_configuration_mode_t: - * - * This defines the general operation mode for the HAL (for a given stream configuration), where - * modes besides NORMAL have different semantics, and usually limit the generality of the API in - * exchange for higher performance in some particular area. - */ -typedef enum camera3_stream_configuration_mode { - /** - * Normal stream configuration operation mode. This is the default camera operation mode, - * where all semantics of HAL APIs and metadata controls apply. - */ - CAMERA3_STREAM_CONFIGURATION_NORMAL_MODE = 0, - - /** - * Special constrained high speed operation mode for devices that can not support high - * speed output in NORMAL mode. All streams in this configuration are operating at high speed - * mode and have different characteristics and limitations to achieve high speed output. - * The NORMAL mode can still be used for high speed output if the HAL can support high speed - * output while satisfying all the semantics of HAL APIs and metadata controls. It is - * recommended for the HAL to support high speed output in NORMAL mode (by advertising the high - * speed FPS ranges in android.control.aeAvailableTargetFpsRanges) if possible. - * - * This mode has below limitations/requirements: - * - * 1. The HAL must support up to 2 streams with sizes reported by - * android.control.availableHighSpeedVideoConfigurations. - * 2. In this mode, the HAL is expected to output up to 120fps or higher. This mode must - * support the targeted FPS range and size configurations reported by - * android.control.availableHighSpeedVideoConfigurations. - * 3. The HAL must support HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED output stream format. - * 4. To achieve efficient high speed streaming, the HAL may have to aggregate - * multiple frames together and send to camera device for processing where the request - * controls are same for all the frames in this batch (batch mode). The HAL must support - * max batch size and the max batch size requirements defined by - * android.control.availableHighSpeedVideoConfigurations. - * 5. In this mode, the HAL must override aeMode, awbMode, and afMode to ON, ON, and - * CONTINUOUS_VIDEO, respectively. All post-processing block mode controls must be - * overridden to be FAST. Therefore, no manual control of capture and post-processing - * parameters is possible. All other controls operate the same as when - * android.control.mode == AUTO. This means that all other android.control.* fields - * must continue to work, such as - * - * android.control.aeTargetFpsRange - * android.control.aeExposureCompensation - * android.control.aeLock - * android.control.awbLock - * android.control.effectMode - * android.control.aeRegions - * android.control.afRegions - * android.control.awbRegions - * android.control.afTrigger - * android.control.aePrecaptureTrigger - * - * Outside of android.control.*, the following controls must work: - * - * android.flash.mode (TORCH mode only, automatic flash for still capture will not work - * since aeMode is ON) - * android.lens.opticalStabilizationMode (if it is supported) - * android.scaler.cropRegion - * android.statistics.faceDetectMode (if it is supported) - * 6. To reduce the amount of data passed across process boundaries at - * high frame rate, within one batch, camera framework only propagates - * the last shutter notify and the last capture results (including partial - * results and final result) to the app. The shutter notifies and capture - * results for the other requests in the batch are derived by - * the camera framework. As a result, the HAL can return empty metadata - * except for the last result in the batch. - * - * For more details about high speed stream requirements, see - * android.control.availableHighSpeedVideoConfigurations and CONSTRAINED_HIGH_SPEED_VIDEO - * capability defined in android.request.availableCapabilities. - * - * This mode only needs to be supported by HALs that include CONSTRAINED_HIGH_SPEED_VIDEO in - * the android.request.availableCapabilities static metadata. - */ - CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE = 1, - - /** - * First value for vendor-defined stream configuration modes. - */ - CAMERA3_VENDOR_STREAM_CONFIGURATION_MODE_START = 0x8000 -} camera3_stream_configuration_mode_t; - -/** - * camera3_stream_t: - * - * A handle to a single camera input or output stream. A stream is defined by - * the framework by its buffer resolution and format, and additionally by the - * HAL with the gralloc usage flags and the maximum in-flight buffer count. - * - * The stream structures are owned by the framework, but pointers to a - * camera3_stream passed into the HAL by configure_streams() are valid until the - * end of the first subsequent configure_streams() call that _does not_ include - * that camera3_stream as an argument, or until the end of the close() call. - * - * All camera3_stream framework-controlled members are immutable once the - * camera3_stream is passed into configure_streams(). The HAL may only change - * the HAL-controlled parameters during a configure_streams() call, except for - * the contents of the private pointer. - * - * If a configure_streams() call returns a non-fatal error, all active streams - * remain valid as if configure_streams() had not been called. - * - * The endpoint of the stream is not visible to the camera HAL device. - * In DEVICE_API_VERSION_3_1, this was changed to share consumer usage flags - * on streams where the camera is a producer (OUTPUT and BIDIRECTIONAL stream - * types) see the usage field below. - */ -typedef struct camera3_stream { - - /***** - * Set by framework before configure_streams() - */ - - /** - * The type of the stream, one of the camera3_stream_type_t values. - */ - int stream_type; - - /** - * The width in pixels of the buffers in this stream - */ - uint32_t width; - - /** - * The height in pixels of the buffers in this stream - */ - uint32_t height; - - /** - * The pixel format for the buffers in this stream. Format is a value from - * the HAL_PIXEL_FORMAT_* list in system/core/include/system/graphics.h, or - * from device-specific headers. - * - * If HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform - * gralloc module will select a format based on the usage flags provided by - * the camera device and the other endpoint of the stream. - * - * <= CAMERA_DEVICE_API_VERSION_3_1: - * - * The camera HAL device must inspect the buffers handed to it in the - * subsequent register_stream_buffers() call to obtain the - * implementation-specific format details, if necessary. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * register_stream_buffers() won't be called by the framework, so the HAL - * should configure the ISP and sensor pipeline based purely on the sizes, - * usage flags, and formats for the configured streams. - */ - int format; - - /***** - * Set by HAL during configure_streams(). - */ - - /** - * The gralloc usage flags for this stream, as needed by the HAL. The usage - * flags are defined in gralloc.h (GRALLOC_USAGE_*), or in device-specific - * headers. - * - * For output streams, these are the HAL's producer usage flags. For input - * streams, these are the HAL's consumer usage flags. The usage flags from - * the producer and the consumer will be combined together and then passed - * to the platform gralloc HAL module for allocating the gralloc buffers for - * each stream. - * - * Version information: - * - * == CAMERA_DEVICE_API_VERSION_3_0: - * - * No initial value guaranteed when passed via configure_streams(). - * HAL may not use this field as input, and must write over this field - * with its usage flags. - * - * >= CAMERA_DEVICE_API_VERSION_3_1: - * - * For stream_type OUTPUT and BIDIRECTIONAL, when passed via - * configure_streams(), the initial value of this is the consumer's - * usage flags. The HAL may use these consumer flags to decide stream - * configuration. - * For stream_type INPUT, when passed via configure_streams(), the initial - * value of this is 0. - * For all streams passed via configure_streams(), the HAL must write - * over this field with its usage flags. - * - * From Android O, the usage flag for an output stream may be bitwise - * combination of usage flags for multiple consumers, for the purpose of - * sharing one camera stream between those consumers. The HAL must fail - * configure_streams call with -EINVAL if the combined flags cannot be - * supported due to imcompatible buffer format, dataSpace, or other hardware - * limitations. - */ - uint32_t usage; - - /** - * The maximum number of buffers the HAL device may need to have dequeued at - * the same time. The HAL device may not have more buffers in-flight from - * this stream than this value. - */ - uint32_t max_buffers; - - /** - * A handle to HAL-private information for the stream. Will not be inspected - * by the framework code. - */ - void *priv; - - /** - * A field that describes the contents of the buffer. The format and buffer - * dimensions define the memory layout and structure of the stream buffers, - * while dataSpace defines the meaning of the data within the buffer. - * - * For most formats, dataSpace defines the color space of the image data. - * In addition, for some formats, dataSpace indicates whether image- or - * depth-based data is requested. See system/core/include/system/graphics.h - * for details of formats and valid dataSpace values for each format. - * - * Version information: - * - * < CAMERA_DEVICE_API_VERSION_3_3: - * - * Not defined and should not be accessed. dataSpace should be assumed to - * be HAL_DATASPACE_UNKNOWN, and the appropriate color space, etc, should - * be determined from the usage flags and the format. - * - * = CAMERA_DEVICE_API_VERSION_3_3: - * - * Always set by the camera service. HAL must use this dataSpace to - * configure the stream to the correct colorspace, or to select between - * color and depth outputs if supported. The dataspace values are the - * legacy definitions in graphics.h - * - * >= CAMERA_DEVICE_API_VERSION_3_4: - * - * Always set by the camera service. HAL must use this dataSpace to - * configure the stream to the correct colorspace, or to select between - * color and depth outputs if supported. The dataspace values are set - * using the V0 dataspace definitions in graphics.h - */ - android_dataspace_t data_space; - - /** - * The required output rotation of the stream, one of - * the camera3_stream_rotation_t values. This must be inspected by HAL along - * with stream width and height. For example, if the rotation is 90 degree - * and the stream width and height is 720 and 1280 respectively, camera service - * will supply buffers of size 720x1280, and HAL should capture a 1280x720 image - * and rotate the image by 90 degree counterclockwise. The rotation field is - * no-op when the stream type is input. Camera HAL must ignore the rotation - * field for an input stream. - * - * <= CAMERA_DEVICE_API_VERSION_3_2: - * - * Not defined and must not be accessed. HAL must not apply any rotation - * on output images. - * - * >= CAMERA_DEVICE_API_VERSION_3_3: - * - * Always set by camera service. HAL must inspect this field during stream - * configuration and returns -EINVAL if HAL cannot perform such rotation. - * HAL must always support CAMERA3_STREAM_ROTATION_0, so a - * configure_streams() call must not fail for unsupported rotation if - * rotation field of all streams is CAMERA3_STREAM_ROTATION_0. - * - */ - int rotation; - - /** - * The physical camera id this stream belongs to. - * - * <= CAMERA_DEVICE_API_VERISON_3_4: - * - * Not defined and must not be accessed. - * - * >= CAMERA_DEVICE_API_VERISON_3_5: - * - * Always set by camera service. If the camera device is not a logical - * multi camera, or if the camera is a logical multi camera but the stream - * is not a physical output stream, this field will point to a 0-length - * string. - * - * A logical multi camera is a camera device backed by multiple physical - * cameras that are also exposed to the application. And for a logical - * multi camera, a physical output stream is an output stream specifically - * requested on an underlying physical camera. - * - * For an input stream, this field is guaranteed to be a 0-length string. - */ - const char* physical_camera_id; - - /* reserved for future use */ - void *reserved[6]; - -} camera3_stream_t; - -/** - * camera3_stream_configuration_t: - * - * A structure of stream definitions, used by configure_streams(). This - * structure defines all the output streams and the reprocessing input - * stream for the current camera use case. - */ -typedef struct camera3_stream_configuration { - /** - * The total number of streams requested by the framework. This includes - * both input and output streams. The number of streams will be at least 1, - * and there will be at least one output-capable stream. - */ - uint32_t num_streams; - - /** - * An array of camera stream pointers, defining the input/output - * configuration for the camera HAL device. - * - * At most one input-capable stream may be defined (INPUT or BIDIRECTIONAL) - * in a single configuration. - * - * At least one output-capable stream must be defined (OUTPUT or - * BIDIRECTIONAL). - */ - camera3_stream_t **streams; - - /** - * >= CAMERA_DEVICE_API_VERSION_3_3: - * - * The operation mode of streams in this configuration, one of the value - * defined in camera3_stream_configuration_mode_t. The HAL can use this - * mode as an indicator to set the stream property (e.g., - * camera3_stream->max_buffers) appropriately. For example, if the - * configuration is - * CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE, the HAL may - * want to set aside more buffers for batch mode operation (see - * android.control.availableHighSpeedVideoConfigurations for batch mode - * definition). - * - */ - uint32_t operation_mode; - - /** - * >= CAMERA_DEVICE_API_VERSION_3_5: - * - * The session metadata buffer contains the initial values of - * ANDROID_REQUEST_AVAILABLE_SESSION_KEYS. This field is optional - * and camera clients can choose to ignore it, in which case it will - * be set to NULL. If parameters are present, then Hal should examine - * the parameter values and configure its internal camera pipeline - * accordingly. - */ - const camera_metadata_t *session_parameters; -} camera3_stream_configuration_t; - -/** - * camera3_buffer_status_t: - * - * The current status of a single stream buffer. - */ -typedef enum camera3_buffer_status { - /** - * The buffer is in a normal state, and can be used after waiting on its - * sync fence. - */ - CAMERA3_BUFFER_STATUS_OK = 0, - - /** - * The buffer does not contain valid data, and the data in it should not be - * used. The sync fence must still be waited on before reusing the buffer. - */ - CAMERA3_BUFFER_STATUS_ERROR = 1 - -} camera3_buffer_status_t; - -/** - * camera3_stream_buffer_t: - * - * A single buffer from a camera3 stream. It includes a handle to its parent - * stream, the handle to the gralloc buffer itself, and sync fences - * - * The buffer does not specify whether it is to be used for input or output; - * that is determined by its parent stream type and how the buffer is passed to - * the HAL device. - */ -typedef struct camera3_stream_buffer { - /** - * The handle of the stream this buffer is associated with - */ - camera3_stream_t *stream; - - /** - * The native handle to the buffer - */ - buffer_handle_t *buffer; - - /** - * Current state of the buffer, one of the camera3_buffer_status_t - * values. The framework will not pass buffers to the HAL that are in an - * error state. In case a buffer could not be filled by the HAL, it must - * have its status set to CAMERA3_BUFFER_STATUS_ERROR when returned to the - * framework with process_capture_result(). - */ - int status; - - /** - * The acquire sync fence for this buffer. The HAL must wait on this fence - * fd before attempting to read from or write to this buffer. - * - * The framework may be set to -1 to indicate that no waiting is necessary - * for this buffer. - * - * When the HAL returns an output buffer to the framework with - * process_capture_result(), the acquire_fence must be set to -1. If the HAL - * never waits on the acquire_fence due to an error in filling a buffer, - * when calling process_capture_result() the HAL must set the release_fence - * of the buffer to be the acquire_fence passed to it by the framework. This - * will allow the framework to wait on the fence before reusing the buffer. - * - * For input buffers, the HAL must not change the acquire_fence field during - * the process_capture_request() call. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * When the HAL returns an input buffer to the framework with - * process_capture_result(), the acquire_fence must be set to -1. If the HAL - * never waits on input buffer acquire fence due to an error, the sync - * fences should be handled similarly to the way they are handled for output - * buffers. - */ - int acquire_fence; - - /** - * The release sync fence for this buffer. The HAL must set this fence when - * returning buffers to the framework, or write -1 to indicate that no - * waiting is required for this buffer. - * - * For the output buffers, the fences must be set in the output_buffers - * array passed to process_capture_result(). - * - * <= CAMERA_DEVICE_API_VERSION_3_1: - * - * For the input buffer, the release fence must be set by the - * process_capture_request() call. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * For the input buffer, the fences must be set in the input_buffer - * passed to process_capture_result(). - * - * After signaling the release_fence for this buffer, the HAL - * should not make any further attempts to access this buffer as the - * ownership has been fully transferred back to the framework. - * - * If a fence of -1 was specified then the ownership of this buffer - * is transferred back immediately upon the call of process_capture_result. - */ - int release_fence; - -} camera3_stream_buffer_t; - -/** - * camera3_stream_buffer_set_t: - * - * The complete set of gralloc buffers for a stream. This structure is given to - * register_stream_buffers() to allow the camera HAL device to register/map/etc - * newly allocated stream buffers. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * Deprecated (and not used). In particular, - * register_stream_buffers is also deprecated and will never be invoked. - * - */ -typedef struct camera3_stream_buffer_set { - /** - * The stream handle for the stream these buffers belong to - */ - camera3_stream_t *stream; - - /** - * The number of buffers in this stream. It is guaranteed to be at least - * stream->max_buffers. - */ - uint32_t num_buffers; - - /** - * The array of gralloc buffer handles for this stream. If the stream format - * is set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the camera HAL device - * should inspect the passed-in buffers to determine any platform-private - * pixel format information. - */ - buffer_handle_t **buffers; - -} camera3_stream_buffer_set_t; - -/** - * camera3_jpeg_blob: - * - * Transport header for compressed JPEG or JPEG_APP_SEGMENTS buffers in output streams. - * - * To capture JPEG or JPEG_APP_SEGMENTS images, a stream is created using the pixel format - * HAL_PIXEL_FORMAT_BLOB. The buffer size for the stream is calculated by the - * framework, based on the static metadata field android.jpeg.maxSize for JPEG, - * and android.jpeg.maxAppsSegments for JPEG_APP_SEGMENTS. - * - * Since compressed JPEG/JPEG_APP_SEGMENTS images are of variable size, the HAL needs to - * include the final size of the image using this structure inside the output - * stream buffer. The JPEG blob ID field must be set to CAMERA3_JPEG_BLOB_ID for - * JPEG and CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID for APP segments. - * - * Transport header should be at the end of the output stream buffer. That - * means the jpeg_blob_id must start at byte[buffer_size - - * sizeof(camera3_jpeg_blob)], where the buffer_size is the size of gralloc buffer. - * The blob data itself starts at the beginning of the buffer and should be - * jpeg_size bytes long. HAL using this transport header for JPEG must account for - * it in android.jpeg.maxSize. For JPEG APP segments, camera framework makes - * sure that the output stream buffer is large enough for the transport header. - */ -typedef struct camera3_jpeg_blob { - uint16_t jpeg_blob_id; - uint32_t jpeg_size; -} camera3_jpeg_blob_t; - -enum { - CAMERA3_JPEG_BLOB_ID = 0x00FF, - CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID = 0x0100, -}; - -/********************************************************************** - * - * Message definitions for the HAL notify() callback. - * - * These definitions are used for the HAL notify callback, to signal - * asynchronous events from the HAL device to the Android framework. - * - */ - -/** - * camera3_msg_type: - * - * Indicates the type of message sent, which specifies which member of the - * message union is valid. - * - */ -typedef enum camera3_msg_type { - /** - * An error has occurred. camera3_notify_msg.message.error contains the - * error information. - */ - CAMERA3_MSG_ERROR = 1, - - /** - * The exposure of a given request or processing a reprocess request has - * begun. camera3_notify_msg.message.shutter contains the information - * the capture. - */ - CAMERA3_MSG_SHUTTER = 2, - - /** - * Number of framework message types - */ - CAMERA3_NUM_MESSAGES - -} camera3_msg_type_t; - -/** - * Defined error codes for CAMERA_MSG_ERROR - */ -typedef enum camera3_error_msg_code { - /** - * A serious failure occured. No further frames or buffer streams will - * be produced by the device. Device should be treated as closed. The - * client must reopen the device to use it again. The frame_number field - * is unused. - */ - CAMERA3_MSG_ERROR_DEVICE = 1, - - /** - * An error has occurred in processing a request. No output (metadata or - * buffers) will be produced for this request. The frame_number field - * specifies which request has been dropped. Subsequent requests are - * unaffected, and the device remains operational. - */ - CAMERA3_MSG_ERROR_REQUEST = 2, - - /** - * An error has occurred in producing an output result metadata buffer - * for a request, but output stream buffers for it will still be - * available. Subsequent requests are unaffected, and the device remains - * operational. The frame_number field specifies the request for which - * result metadata won't be available. - * - * >= CAMERA_DEVICE_API_VERSION_3_6: - * - * In case the result metadata is absent for a logical camera device, then the - * error_stream pointer must be set to NULL. - * If the result metadata cannot be produced for a physical camera device, then - * error_stream must contain a pointer to a respective stream associated with - * that physical device. - */ - CAMERA3_MSG_ERROR_RESULT = 3, - - /** - * An error has occurred in placing an output buffer into a stream for a - * request. The frame metadata and other buffers may still be - * available. Subsequent requests are unaffected, and the device remains - * operational. The frame_number field specifies the request for which the - * buffer was dropped, and error_stream contains a pointer to the stream - * that dropped the frame. - */ - CAMERA3_MSG_ERROR_BUFFER = 4, - - /** - * Number of error types - */ - CAMERA3_MSG_NUM_ERRORS - -} camera3_error_msg_code_t; - -/** - * camera3_error_msg_t: - * - * Message contents for CAMERA3_MSG_ERROR - */ -typedef struct camera3_error_msg { - /** - * Frame number of the request the error applies to. 0 if the frame number - * isn't applicable to the error. - */ - uint32_t frame_number; - - /** - * Pointer to the stream that had a failure. NULL if the stream isn't - * applicable to the error. - */ - camera3_stream_t *error_stream; - - /** - * The code for this error; one of the CAMERA_MSG_ERROR enum values. - */ - int error_code; - -} camera3_error_msg_t; - -/** - * camera3_shutter_msg_t: - * - * Message contents for CAMERA3_MSG_SHUTTER - */ -typedef struct camera3_shutter_msg { - /** - * Frame number of the request that has begun exposure or reprocessing. - */ - uint32_t frame_number; - - /** - * Timestamp for the start of capture. For a reprocess request, this must - * be input image's start of capture. This must match the capture result - * metadata's sensor exposure start timestamp. - */ - uint64_t timestamp; - -} camera3_shutter_msg_t; - -/** - * camera3_notify_msg_t: - * - * The message structure sent to camera3_callback_ops_t.notify() - */ -typedef struct camera3_notify_msg { - - /** - * The message type. One of camera3_notify_msg_type, or a private extension. - */ - int type; - - union { - /** - * Error message contents. Valid if type is CAMERA3_MSG_ERROR - */ - camera3_error_msg_t error; - - /** - * Shutter message contents. Valid if type is CAMERA3_MSG_SHUTTER - */ - camera3_shutter_msg_t shutter; - - /** - * Generic message contents. Used to ensure a minimum size for custom - * message types. - */ - uint8_t generic[32]; - } message; - -} camera3_notify_msg_t; - - -/********************************************************************** - * - * Types definition for request_stream_buffers() callback. - * - */ - -/** - * camera3_buffer_request_status_t: - * - * The overall buffer request status returned by request_stream_buffers() - */ -typedef enum camera3_buffer_request_status { - /** - * request_stream_buffers() call succeeded and all requested buffers are - * returned. - */ - CAMERA3_BUF_REQ_OK = 0, - - /** - * request_stream_buffers() call failed for some streams. - * Check per stream status for each returned camera3_stream_buffer_ret_t. - */ - CAMERA3_BUF_REQ_FAILED_PARTIAL = 1, - - /** - * request_stream_buffers() call failed for all streams and no buffers are - * returned at all. Camera service is about to or is performing - * configure_streams() call. HAL must wait until next configure_streams() - * call is finished before requesting buffers again. - */ - CAMERA3_BUF_REQ_FAILED_CONFIGURING = 2, - - /** - * request_stream_buffers() call failed for all streams and no buffers are - * returned at all. Failure due to bad camera3_buffer_request input, eg: - * unknown stream or repeated stream in the list of buffer requests. - */ - CAMERA3_BUF_REQ_FAILED_ILLEGAL_ARGUMENTS = 3, - - /** - * request_stream_buffers() call failed for all streams and no buffers are - * returned at all. This can happen for unknown reasons or a combination - * of different failure reasons per stream. For the latter case, caller can - * check per stream failure reason returned in camera3_stream_buffer_ret. - */ - CAMERA3_BUF_REQ_FAILED_UNKNOWN = 4, - - /** - * Number of buffer request status - */ - CAMERA3_BUF_REQ_NUM_STATUS - -} camera3_buffer_request_status_t; - -/** - * camera3_stream_buffer_req_status_t: - * - * The per stream buffer request status returned by request_stream_buffers() - */ -typedef enum camera3_stream_buffer_req_status { - /** - * Get buffer succeeds and all requested buffers are returned. - */ - CAMERA3_PS_BUF_REQ_OK = 0, - - /** - * Get buffer failed due to timeout waiting for an available buffer. This is - * likely due to the client application holding too many buffers, or the - * system is under memory pressure. - * This is not a fatal error. HAL can try to request buffer for this stream - * later. If HAL cannot get a buffer for certain capture request in time - * due to this error, HAL can send an ERROR_REQUEST to camera service and - * drop processing that request. - */ - CAMERA3_PS_BUF_REQ_NO_BUFFER_AVAILABLE = 1, - - /** - * Get buffer failed due to HAL has reached its maxBuffer count. This is not - * a fatal error. HAL can try to request buffer for this stream again after - * it returns at least one buffer of that stream to camera service. - */ - CAMERA3_PS_BUF_REQ_MAX_BUFFER_EXCEEDED = 2, - - /** - * Get buffer failed due to the stream is disconnected by client - * application, has been removed, or not recognized by camera service. - * This means application is no longer interested in this stream. - * Requesting buffer for this stream will never succeed after this error is - * returned. HAL must safely return all buffers of this stream after - * getting this error. If HAL gets another capture request later targeting - * a disconnected stream, HAL must send an ERROR_REQUEST to camera service - * and drop processing that request. - */ - CAMERA3_PS_BUF_REQ_STREAM_DISCONNECTED = 3, - - /** - * Get buffer failed for unknown reason. This is a fatal error and HAL must - * send ERROR_DEVICE to camera service and be ready to be closed. - */ - CAMERA3_PS_BUF_REQ_UNKNOWN_ERROR = 4, - - /** - * Number of buffer request status - */ - CAMERA3_PS_BUF_REQ_NUM_STATUS -} camera3_stream_buffer_req_status_t; - -typedef struct camera3_buffer_request { - /** - * The stream HAL wants to request buffer from - */ - camera3_stream_t *stream; - - /** - * The number of buffers HAL requested - */ - uint32_t num_buffers_requested; -} camera3_buffer_request_t; - -typedef struct camera3_stream_buffer_ret { - /** - * The stream HAL wants to request buffer from - */ - camera3_stream_t *stream; - - /** - * The status of buffer request of this stream - */ - camera3_stream_buffer_req_status_t status; - - /** - * Number of output buffers returned. Must be 0 when above status is not - * CAMERA3_PS_BUF_REQ_OK; otherwise the value must be equal to - * num_buffers_requested in the corresponding camera3_buffer_request_t - */ - uint32_t num_output_buffers; - - /** - * The returned output buffers for the stream. - * Caller of request_stream_buffers() should supply this with enough memory - * (num_buffers_requested * sizeof(camera3_stream_buffer_t)) - */ - camera3_stream_buffer_t *output_buffers; -} camera3_stream_buffer_ret_t; - - -/********************************************************************** - * - * Capture request/result definitions for the HAL process_capture_request() - * method, and the process_capture_result() callback. - * - */ - -/** - * camera3_request_template_t: - * - * Available template types for - * camera3_device_ops.construct_default_request_settings() - */ -typedef enum camera3_request_template { - /** - * Standard camera preview operation with 3A on auto. - */ - CAMERA3_TEMPLATE_PREVIEW = 1, - - /** - * Standard camera high-quality still capture with 3A and flash on auto. - */ - CAMERA3_TEMPLATE_STILL_CAPTURE = 2, - - /** - * Standard video recording plus preview with 3A on auto, torch off. - */ - CAMERA3_TEMPLATE_VIDEO_RECORD = 3, - - /** - * High-quality still capture while recording video. Application will - * include preview, video record, and full-resolution YUV or JPEG streams in - * request. Must not cause stuttering on video stream. 3A on auto. - */ - CAMERA3_TEMPLATE_VIDEO_SNAPSHOT = 4, - - /** - * Zero-shutter-lag mode. Application will request preview and - * full-resolution data for each frame, and reprocess it to JPEG when a - * still image is requested by user. Settings should provide highest-quality - * full-resolution images without compromising preview frame rate. 3A on - * auto. - */ - CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG = 5, - - /** - * A basic template for direct application control of capture - * parameters. All automatic control is disabled (auto-exposure, auto-white - * balance, auto-focus), and post-processing parameters are set to preview - * quality. The manual capture parameters (exposure, sensitivity, etc.) - * are set to reasonable defaults, but should be overridden by the - * application depending on the intended use case. - */ - CAMERA3_TEMPLATE_MANUAL = 6, - - /* Total number of templates */ - CAMERA3_TEMPLATE_COUNT, - - /** - * First value for vendor-defined request templates - */ - CAMERA3_VENDOR_TEMPLATE_START = 0x40000000 - -} camera3_request_template_t; - -/** - * camera3_capture_request_t: - * - * A single request for image capture/buffer reprocessing, sent to the Camera - * HAL device by the framework in process_capture_request(). - * - * The request contains the settings to be used for this capture, and the set of - * output buffers to write the resulting image data in. It may optionally - * contain an input buffer, in which case the request is for reprocessing that - * input buffer instead of capturing a new image with the camera sensor. The - * capture is identified by the frame_number. - * - * In response, the camera HAL device must send a camera3_capture_result - * structure asynchronously to the framework, using the process_capture_result() - * callback. - */ -typedef struct camera3_capture_request { - /** - * The frame number is an incrementing integer set by the framework to - * uniquely identify this capture. It needs to be returned in the result - * call, and is also used to identify the request in asynchronous - * notifications sent to camera3_callback_ops_t.notify(). - */ - uint32_t frame_number; - - /** - * The settings buffer contains the capture and processing parameters for - * the request. As a special case, a NULL settings buffer indicates that the - * settings are identical to the most-recently submitted capture request. A - * NULL buffer cannot be used as the first submitted request after a - * configure_streams() call. - */ - const camera_metadata_t *settings; - - /** - * The input stream buffer to use for this request, if any. - * - * If input_buffer is NULL, then the request is for a new capture from the - * imager. If input_buffer is valid, the request is for reprocessing the - * image contained in input_buffer. - * - * In the latter case, the HAL must set the release_fence of the - * input_buffer to a valid sync fence, or to -1 if the HAL does not support - * sync, before process_capture_request() returns. - * - * The HAL is required to wait on the acquire sync fence of the input buffer - * before accessing it. - * - * <= CAMERA_DEVICE_API_VERSION_3_1: - * - * Any input buffer included here will have been registered with the HAL - * through register_stream_buffers() before its inclusion in a request. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * The buffers will not have been pre-registered with the HAL. - * Subsequent requests may reuse buffers, or provide entirely new buffers. - */ - camera3_stream_buffer_t *input_buffer; - - /** - * The number of output buffers for this capture request. Must be at least - * 1. - */ - uint32_t num_output_buffers; - - /** - * An array of num_output_buffers stream buffers, to be filled with image - * data from this capture/reprocess. The HAL must wait on the acquire fences - * of each stream buffer before writing to them. - * - * The HAL takes ownership of the actual buffer_handle_t entries in - * output_buffers; the framework does not access them until they are - * returned in a camera3_capture_result_t. - * - * <= CAMERA_DEVICE_API_VERSION_3_1: - * - * All the buffers included here will have been registered with the HAL - * through register_stream_buffers() before their inclusion in a request. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * Any or all of the buffers included here may be brand new in this - * request (having never before seen by the HAL). - */ - const camera3_stream_buffer_t *output_buffers; - - /** - * <= CAMERA_DEVICE_API_VERISON_3_4: - * - * Not defined and must not be accessed. - * - * >= CAMERA_DEVICE_API_VERSION_3_5: - * The number of physical camera settings to be applied. If 'num_physcam_settings' - * equals 0 or a physical device is not included, then Hal must decide the - * specific physical device settings based on the default 'settings'. - */ - uint32_t num_physcam_settings; - - /** - * <= CAMERA_DEVICE_API_VERISON_3_4: - * - * Not defined and must not be accessed. - * - * >= CAMERA_DEVICE_API_VERSION_3_5: - * The physical camera ids. The array will contain 'num_physcam_settings' - * camera id strings for all physical devices that have specific settings. - * In case some id is invalid, the process capture request must fail and return - * -EINVAL. - */ - const char **physcam_id; - - /** - * <= CAMERA_DEVICE_API_VERISON_3_4: - * - * Not defined and must not be accessed. - * - * >= CAMERA_DEVICE_API_VERSION_3_5: - * The capture settings for the physical cameras. The array will contain - * 'num_physcam_settings' settings for invididual physical devices. In - * case the settings at some particular index are empty, the process capture - * request must fail and return -EINVAL. - */ - const camera_metadata_t **physcam_settings; - -} camera3_capture_request_t; - -/** - * camera3_capture_result_t: - * - * The result of a single capture/reprocess by the camera HAL device. This is - * sent to the framework asynchronously with process_capture_result(), in - * response to a single capture request sent to the HAL with - * process_capture_request(). Multiple process_capture_result() calls may be - * performed by the HAL for each request. - * - * Each call, all with the same frame - * number, may contain some subset of the output buffers, and/or the result - * metadata. The metadata may only be provided once for a given frame number; - * all other calls must set the result metadata to NULL. - * - * The result structure contains the output metadata from this capture, and the - * set of output buffers that have been/will be filled for this capture. Each - * output buffer may come with a release sync fence that the framework will wait - * on before reading, in case the buffer has not yet been filled by the HAL. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * The metadata may be provided multiple times for a single frame number. The - * framework will accumulate together the final result set by combining each - * partial result together into the total result set. - * - * If an input buffer is given in a request, the HAL must return it in one of - * the process_capture_result calls, and the call may be to just return the input - * buffer, without metadata and output buffers; the sync fences must be handled - * the same way they are done for output buffers. - * - * - * Performance considerations: - * - * Applications will also receive these partial results immediately, so sending - * partial results is a highly recommended performance optimization to avoid - * the total pipeline latency before sending the results for what is known very - * early on in the pipeline. - * - * A typical use case might be calculating the AF state halfway through the - * pipeline; by sending the state back to the framework immediately, we get a - * 50% performance increase and perceived responsiveness of the auto-focus. - * - */ -typedef struct camera3_capture_result { - /** - * The frame number is an incrementing integer set by the framework in the - * submitted request to uniquely identify this capture. It is also used to - * identify the request in asynchronous notifications sent to - * camera3_callback_ops_t.notify(). - */ - uint32_t frame_number; - - /** - * The result metadata for this capture. This contains information about the - * final capture parameters, the state of the capture and post-processing - * hardware, the state of the 3A algorithms, if enabled, and the output of - * any enabled statistics units. - * - * Only one call to process_capture_result() with a given frame_number may - * include the result metadata. All other calls for the same frame_number - * must set this to NULL. - * - * If there was an error producing the result metadata, result must be an - * empty metadata buffer, and notify() must be called with ERROR_RESULT. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * Multiple calls to process_capture_result() with a given frame_number - * may include the result metadata. - * - * Partial metadata submitted should not include any metadata key returned - * in a previous partial result for a given frame. Each new partial result - * for that frame must also set a distinct partial_result value. - * - * If notify has been called with ERROR_RESULT, all further partial - * results for that frame are ignored by the framework. - */ - const camera_metadata_t *result; - - /** - * The number of output buffers returned in this result structure. Must be - * less than or equal to the matching capture request's count. If this is - * less than the buffer count in the capture request, at least one more call - * to process_capture_result with the same frame_number must be made, to - * return the remaining output buffers to the framework. This may only be - * zero if the structure includes valid result metadata or an input buffer - * is returned in this result. - */ - uint32_t num_output_buffers; - - /** - * The handles for the output stream buffers for this capture. They may not - * yet be filled at the time the HAL calls process_capture_result(); the - * framework will wait on the release sync fences provided by the HAL before - * reading the buffers. - * - * The HAL must set the stream buffer's release sync fence to a valid sync - * fd, or to -1 if the buffer has already been filled. - * - * If the HAL encounters an error while processing the buffer, and the - * buffer is not filled, the buffer's status field must be set to - * CAMERA3_BUFFER_STATUS_ERROR. If the HAL did not wait on the acquire fence - * before encountering the error, the acquire fence should be copied into - * the release fence, to allow the framework to wait on the fence before - * reusing the buffer. - * - * The acquire fence must be set to -1 for all output buffers. If - * num_output_buffers is zero, this may be NULL. In that case, at least one - * more process_capture_result call must be made by the HAL to provide the - * output buffers. - * - * When process_capture_result is called with a new buffer for a frame, - * all previous frames' buffers for that corresponding stream must have been - * already delivered (the fences need not have yet been signaled). - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * Gralloc buffers for a frame may be sent to framework before the - * corresponding SHUTTER-notify. - * - * Performance considerations: - * - * Buffers delivered to the framework will not be dispatched to the - * application layer until a start of exposure timestamp has been received - * via a SHUTTER notify() call. It is highly recommended to - * dispatch that call as early as possible. - */ - const camera3_stream_buffer_t *output_buffers; - - /** - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * The handle for the input stream buffer for this capture. It may not - * yet be consumed at the time the HAL calls process_capture_result(); the - * framework will wait on the release sync fences provided by the HAL before - * reusing the buffer. - * - * The HAL should handle the sync fences the same way they are done for - * output_buffers. - * - * Only one input buffer is allowed to be sent per request. Similarly to - * output buffers, the ordering of returned input buffers must be - * maintained by the HAL. - * - * Performance considerations: - * - * The input buffer should be returned as early as possible. If the HAL - * supports sync fences, it can call process_capture_result to hand it back - * with sync fences being set appropriately. If the sync fences are not - * supported, the buffer can only be returned when it is consumed, which - * may take long time; the HAL may choose to copy this input buffer to make - * the buffer return sooner. - */ - const camera3_stream_buffer_t *input_buffer; - - /** - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * In order to take advantage of partial results, the HAL must set the - * static metadata android.request.partialResultCount to the number of - * partial results it will send for each frame. - * - * Each new capture result with a partial result must set - * this field (partial_result) to a distinct inclusive value between - * 1 and android.request.partialResultCount. - * - * HALs not wishing to take advantage of this feature must not - * set an android.request.partialResultCount or partial_result to a value - * other than 1. - * - * This value must be set to 0 when a capture result contains buffers only - * and no metadata. - */ - uint32_t partial_result; - - /** - * >= CAMERA_DEVICE_API_VERSION_3_5: - * - * Specifies the number of physical camera metadata this capture result - * contains. It must be equal to the number of physical cameras being - * requested from. - * - * If the current camera device is not a logical multi-camera, or the - * corresponding capture_request doesn't request on any physical camera, - * this field must be 0. - */ - uint32_t num_physcam_metadata; - - /** - * >= CAMERA_DEVICE_API_VERSION_3_5: - * - * An array of strings containing the physical camera ids for the returned - * physical camera metadata. The length of the array is - * num_physcam_metadata. - */ - const char **physcam_ids; - - /** - * >= CAMERA_DEVICE_API_VERSION_3_5: - * - * The array of physical camera metadata for the physical cameras being - * requested upon. This array should have a 1-to-1 mapping with the - * physcam_ids. The length of the array is num_physcam_metadata. - */ - const camera_metadata_t **physcam_metadata; - -} camera3_capture_result_t; - -/********************************************************************** - * - * Callback methods for the HAL to call into the framework. - * - * These methods are used to return metadata and image buffers for a completed - * or failed captures, and to notify the framework of asynchronous events such - * as errors. - * - * The framework will not call back into the HAL from within these callbacks, - * and these calls will not block for extended periods. - * - */ -typedef struct camera3_callback_ops { - - /** - * process_capture_result: - * - * Send results from a completed capture to the framework. - * process_capture_result() may be invoked multiple times by the HAL in - * response to a single capture request. This allows, for example, the - * metadata and low-resolution buffers to be returned in one call, and - * post-processed JPEG buffers in a later call, once it is available. Each - * call must include the frame number of the request it is returning - * metadata or buffers for. - * - * A component (buffer or metadata) of the complete result may only be - * included in one process_capture_result call. A buffer for each stream, - * and the result metadata, must be returned by the HAL for each request in - * one of the process_capture_result calls, even in case of errors producing - * some of the output. A call to process_capture_result() with neither - * output buffers or result metadata is not allowed. - * - * The order of returning metadata and buffers for a single result does not - * matter, but buffers for a given stream must be returned in FIFO order. So - * the buffer for request 5 for stream A must always be returned before the - * buffer for request 6 for stream A. This also applies to the result - * metadata; the metadata for request 5 must be returned before the metadata - * for request 6. - * - * However, different streams are independent of each other, so it is - * acceptable and expected that the buffer for request 5 for stream A may be - * returned after the buffer for request 6 for stream B is. And it is - * acceptable that the result metadata for request 6 for stream B is - * returned before the buffer for request 5 for stream A is. - * - * The HAL retains ownership of result structure, which only needs to be - * valid to access during this call. The framework will copy whatever it - * needs before this call returns. - * - * The output buffers do not need to be filled yet; the framework will wait - * on the stream buffer release sync fence before reading the buffer - * data. Therefore, this method should be called by the HAL as soon as - * possible, even if some or all of the output buffers are still in - * being filled. The HAL must include valid release sync fences into each - * output_buffers stream buffer entry, or -1 if that stream buffer is - * already filled. - * - * If the result buffer cannot be constructed for a request, the HAL should - * return an empty metadata buffer, but still provide the output buffers and - * their sync fences. In addition, notify() must be called with an - * ERROR_RESULT message. - * - * If an output buffer cannot be filled, its status field must be set to - * STATUS_ERROR. In addition, notify() must be called with a ERROR_BUFFER - * message. - * - * If the entire capture has failed, then this method still needs to be - * called to return the output buffers to the framework. All the buffer - * statuses should be STATUS_ERROR, and the result metadata should be an - * empty buffer. In addition, notify() must be called with a ERROR_REQUEST - * message. In this case, individual ERROR_RESULT/ERROR_BUFFER messages - * should not be sent. - * - * Performance requirements: - * - * This is a non-blocking call. The framework will return this call in 5ms. - * - * The pipeline latency (see S7 for definition) should be less than or equal to - * 4 frame intervals, and must be less than or equal to 8 frame intervals. - * - */ - void (*process_capture_result)(const struct camera3_callback_ops *, - const camera3_capture_result_t *result); - - /** - * notify: - * - * Asynchronous notification callback from the HAL, fired for various - * reasons. Only for information independent of frame capture, or that - * require specific timing. The ownership of the message structure remains - * with the HAL, and the msg only needs to be valid for the duration of this - * call. - * - * Multiple threads may call notify() simultaneously. - * - * <= CAMERA_DEVICE_API_VERSION_3_1: - * - * The notification for the start of exposure for a given request must be - * sent by the HAL before the first call to process_capture_result() for - * that request is made. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * Buffers delivered to the framework will not be dispatched to the - * application layer until a start of exposure timestamp (or input image's - * start of exposure timestamp for a reprocess request) has been received - * via a SHUTTER notify() call. It is highly recommended to dispatch this - * call as early as possible. - * - * ------------------------------------------------------------------------ - * Performance requirements: - * - * This is a non-blocking call. The framework will return this call in 5ms. - */ - void (*notify)(const struct camera3_callback_ops *, - const camera3_notify_msg_t *msg); - - /** - * request_stream_buffers: - * - * <= CAMERA_DEVICE_API_VERISON_3_5: - * - * DO NOT USE: not defined and must be NULL. - * - * >= CAMERA_DEVICE_API_VERISON_3_6: - * - * Synchronous callback for HAL to ask for output buffer from camera service. - * - * This call may be serialized in camera service so it is strongly - * recommended to only call this method from one thread. - * - * When camera device advertises - * (android.info.supportedBufferManagementVersion == - * ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION_HIDL_DEVICE_3_5), HAL - * can use this method to request buffers from camera service. - * - * Caller is responsible for allocating enough memory for returned_buf_reqs - * argument (num_buffer_reqs * sizeof(camera3_stream_buffer_ret_t)) bytes - * and also the memory for the output_buffers field in each - * camera3_stream_buffer_ret_t - * (num_buffers_requested * sizeof(camera3_stream_buffer_t)) bytes - * - * Performance requirements: - * This is a blocking call that takes more time with more buffers requested. - * HAL should not request large amount of buffers on a latency critical code - * path. It is highly recommended to use a dedicated thread to perform - * all requestStreamBuffer calls, and adjust the thread priority and/or - * timing of making the call in order for buffers to arrive before HAL is - * ready to fill the buffer. - */ - camera3_buffer_request_status_t (*request_stream_buffers)( - const struct camera3_callback_ops *, - uint32_t num_buffer_reqs, - const camera3_buffer_request_t *buffer_reqs, - /*out*/uint32_t *num_returned_buf_reqs, - /*out*/camera3_stream_buffer_ret_t *returned_buf_reqs); - - /** - * return_stream_buffers: - * - * <= CAMERA_DEVICE_API_VERISON_3_5: - * - * DO NOT USE: not defined and must be NULL. - * - * >= CAMERA_DEVICE_API_VERISON_3_6: - * - * Synchronous callback for HAL to return output buffers to camera service. - * - * If this method is called during a configure_streams() call, it will be - * blocked until camera service finishes the ongoing configure_streams() call. - */ - void (*return_stream_buffers)( - const struct camera3_callback_ops *, - uint32_t num_buffers, - const camera3_stream_buffer_t* const* buffers); - -} camera3_callback_ops_t; - -/********************************************************************** - * - * Camera device operations - * - */ -typedef struct camera3_device_ops { - - /** - * initialize: - * - * One-time initialization to pass framework callback function pointers to - * the HAL. Will be called once after a successful open() call, before any - * other functions are called on the camera3_device_ops structure. - * - * Performance requirements: - * - * This should be a non-blocking call. The HAL should return from this call - * in 5ms, and must return from this call in 10ms. - * - * Return values: - * - * 0: On successful initialization - * - * -ENODEV: If initialization fails. Only close() can be called successfully - * by the framework after this. - */ - int (*initialize)(const struct camera3_device *, - const camera3_callback_ops_t *callback_ops); - - /********************************************************************** - * Stream management - */ - - /** - * configure_streams: - * - * CAMERA_DEVICE_API_VERSION_3_0 only: - * - * Reset the HAL camera device processing pipeline and set up new input and - * output streams. This call replaces any existing stream configuration with - * the streams defined in the stream_list. This method will be called at - * least once after initialize() before a request is submitted with - * process_capture_request(). - * - * The stream_list must contain at least one output-capable stream, and may - * not contain more than one input-capable stream. - * - * The stream_list may contain streams that are also in the currently-active - * set of streams (from the previous call to configure_stream()). These - * streams will already have valid values for usage, max_buffers, and the - * private pointer. - * - * If such a stream has already had its buffers registered, - * register_stream_buffers() will not be called again for the stream, and - * buffers from the stream can be immediately included in input requests. - * - * If the HAL needs to change the stream configuration for an existing - * stream due to the new configuration, it may rewrite the values of usage - * and/or max_buffers during the configure call. - * - * The framework will detect such a change, and will then reallocate the - * stream buffers, and call register_stream_buffers() again before using - * buffers from that stream in a request. - * - * If a currently-active stream is not included in stream_list, the HAL may - * safely remove any references to that stream. It will not be reused in a - * later configure() call by the framework, and all the gralloc buffers for - * it will be freed after the configure_streams() call returns. - * - * The stream_list structure is owned by the framework, and may not be - * accessed once this call completes. The address of an individual - * camera3_stream_t structure will remain valid for access by the HAL until - * the end of the first configure_stream() call which no longer includes - * that camera3_stream_t in the stream_list argument. The HAL may not change - * values in the stream structure outside of the private pointer, except for - * the usage and max_buffers members during the configure_streams() call - * itself. - * - * If the stream is new, the usage, max_buffer, and private pointer fields - * of the stream structure will all be set to 0. The HAL device must set - * these fields before the configure_streams() call returns. These fields - * are then used by the framework and the platform gralloc module to - * allocate the gralloc buffers for each stream. - * - * Before such a new stream can have its buffers included in a capture - * request, the framework will call register_stream_buffers() with that - * stream. However, the framework is not required to register buffers for - * _all_ streams before submitting a request. This allows for quick startup - * of (for example) a preview stream, with allocation for other streams - * happening later or concurrently. - * - * ------------------------------------------------------------------------ - * CAMERA_DEVICE_API_VERSION_3_1 only: - * - * Reset the HAL camera device processing pipeline and set up new input and - * output streams. This call replaces any existing stream configuration with - * the streams defined in the stream_list. This method will be called at - * least once after initialize() before a request is submitted with - * process_capture_request(). - * - * The stream_list must contain at least one output-capable stream, and may - * not contain more than one input-capable stream. - * - * The stream_list may contain streams that are also in the currently-active - * set of streams (from the previous call to configure_stream()). These - * streams will already have valid values for usage, max_buffers, and the - * private pointer. - * - * If such a stream has already had its buffers registered, - * register_stream_buffers() will not be called again for the stream, and - * buffers from the stream can be immediately included in input requests. - * - * If the HAL needs to change the stream configuration for an existing - * stream due to the new configuration, it may rewrite the values of usage - * and/or max_buffers during the configure call. - * - * The framework will detect such a change, and will then reallocate the - * stream buffers, and call register_stream_buffers() again before using - * buffers from that stream in a request. - * - * If a currently-active stream is not included in stream_list, the HAL may - * safely remove any references to that stream. It will not be reused in a - * later configure() call by the framework, and all the gralloc buffers for - * it will be freed after the configure_streams() call returns. - * - * The stream_list structure is owned by the framework, and may not be - * accessed once this call completes. The address of an individual - * camera3_stream_t structure will remain valid for access by the HAL until - * the end of the first configure_stream() call which no longer includes - * that camera3_stream_t in the stream_list argument. The HAL may not change - * values in the stream structure outside of the private pointer, except for - * the usage and max_buffers members during the configure_streams() call - * itself. - * - * If the stream is new, max_buffer, and private pointer fields of the - * stream structure will all be set to 0. The usage will be set to the - * consumer usage flags. The HAL device must set these fields before the - * configure_streams() call returns. These fields are then used by the - * framework and the platform gralloc module to allocate the gralloc - * buffers for each stream. - * - * Before such a new stream can have its buffers included in a capture - * request, the framework will call register_stream_buffers() with that - * stream. However, the framework is not required to register buffers for - * _all_ streams before submitting a request. This allows for quick startup - * of (for example) a preview stream, with allocation for other streams - * happening later or concurrently. - * - * ------------------------------------------------------------------------ - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * Reset the HAL camera device processing pipeline and set up new input and - * output streams. This call replaces any existing stream configuration with - * the streams defined in the stream_list. This method will be called at - * least once after initialize() before a request is submitted with - * process_capture_request(). - * - * The stream_list must contain at least one output-capable stream, and may - * not contain more than one input-capable stream. - * - * The stream_list may contain streams that are also in the currently-active - * set of streams (from the previous call to configure_stream()). These - * streams will already have valid values for usage, max_buffers, and the - * private pointer. - * - * If the HAL needs to change the stream configuration for an existing - * stream due to the new configuration, it may rewrite the values of usage - * and/or max_buffers during the configure call. - * - * The framework will detect such a change, and may then reallocate the - * stream buffers before using buffers from that stream in a request. - * - * If a currently-active stream is not included in stream_list, the HAL may - * safely remove any references to that stream. It will not be reused in a - * later configure() call by the framework, and all the gralloc buffers for - * it will be freed after the configure_streams() call returns. - * - * The stream_list structure is owned by the framework, and may not be - * accessed once this call completes. The address of an individual - * camera3_stream_t structure will remain valid for access by the HAL until - * the end of the first configure_stream() call which no longer includes - * that camera3_stream_t in the stream_list argument. The HAL may not change - * values in the stream structure outside of the private pointer, except for - * the usage and max_buffers members during the configure_streams() call - * itself. - * - * If the stream is new, max_buffer, and private pointer fields of the - * stream structure will all be set to 0. The usage will be set to the - * consumer usage flags. The HAL device must set these fields before the - * configure_streams() call returns. These fields are then used by the - * framework and the platform gralloc module to allocate the gralloc - * buffers for each stream. - * - * Newly allocated buffers may be included in a capture request at any time - * by the framework. Once a gralloc buffer is returned to the framework - * with process_capture_result (and its respective release_fence has been - * signaled) the framework may free or reuse it at any time. - * - * ------------------------------------------------------------------------ - * - * Preconditions: - * - * The framework will only call this method when no captures are being - * processed. That is, all results have been returned to the framework, and - * all in-flight input and output buffers have been returned and their - * release sync fences have been signaled by the HAL. The framework will not - * submit new requests for capture while the configure_streams() call is - * underway. - * - * Postconditions: - * - * The HAL device must configure itself to provide maximum possible output - * frame rate given the sizes and formats of the output streams, as - * documented in the camera device's static metadata. - * - * Performance requirements: - * - * This call is expected to be heavyweight and possibly take several hundred - * milliseconds to complete, since it may require resetting and - * reconfiguring the image sensor and the camera processing pipeline. - * Nevertheless, the HAL device should attempt to minimize the - * reconfiguration delay to minimize the user-visible pauses during - * application operational mode changes (such as switching from still - * capture to video recording). - * - * The HAL should return from this call in 500ms, and must return from this - * call in 1000ms. - * - * Return values: - * - * 0: On successful stream configuration - * - * -EINVAL: If the requested stream configuration is invalid. Some examples - * of invalid stream configurations include: - * - * - Including more than 1 input-capable stream (INPUT or - * BIDIRECTIONAL) - * - * - Not including any output-capable streams (OUTPUT or - * BIDIRECTIONAL) - * - * - Including streams with unsupported formats, or an unsupported - * size for that format. - * - * - Including too many output streams of a certain format. - * - * - Unsupported rotation configuration (only applies to - * devices with version >= CAMERA_DEVICE_API_VERSION_3_3) - * - * - Stream sizes/formats don't satisfy the - * camera3_stream_configuration_t->operation_mode requirements for non-NORMAL mode, - * or the requested operation_mode is not supported by the HAL. - * (only applies to devices with version >= CAMERA_DEVICE_API_VERSION_3_3) - * - * Note that the framework submitting an invalid stream - * configuration is not normal operation, since stream - * configurations are checked before configure. An invalid - * configuration means that a bug exists in the framework code, or - * there is a mismatch between the HAL's static metadata and the - * requirements on streams. - * - * -ENODEV: If there has been a fatal error and the device is no longer - * operational. Only close() can be called successfully by the - * framework after this error is returned. - */ - int (*configure_streams)(const struct camera3_device *, - camera3_stream_configuration_t *stream_list); - - /** - * register_stream_buffers: - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * DEPRECATED. This will not be called and must be set to NULL. - * - * <= CAMERA_DEVICE_API_VERSION_3_1: - * - * Register buffers for a given stream with the HAL device. This method is - * called by the framework after a new stream is defined by - * configure_streams, and before buffers from that stream are included in a - * capture request. If the same stream is listed in a subsequent - * configure_streams() call, register_stream_buffers will _not_ be called - * again for that stream. - * - * The framework does not need to register buffers for all configured - * streams before it submits the first capture request. This allows quick - * startup for preview (or similar use cases) while other streams are still - * being allocated. - * - * This method is intended to allow the HAL device to map or otherwise - * prepare the buffers for later use. The buffers passed in will already be - * locked for use. At the end of the call, all the buffers must be ready to - * be returned to the stream. The buffer_set argument is only valid for the - * duration of this call. - * - * If the stream format was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, - * the camera HAL should inspect the passed-in buffers here to determine any - * platform-private pixel format information. - * - * Performance requirements: - * - * This should be a non-blocking call. The HAL should return from this call - * in 1ms, and must return from this call in 5ms. - * - * Return values: - * - * 0: On successful registration of the new stream buffers - * - * -EINVAL: If the stream_buffer_set does not refer to a valid active - * stream, or if the buffers array is invalid. - * - * -ENOMEM: If there was a failure in registering the buffers. The framework - * must consider all the stream buffers to be unregistered, and can - * try to register again later. - * - * -ENODEV: If there is a fatal error, and the device is no longer - * operational. Only close() can be called successfully by the - * framework after this error is returned. - */ - int (*register_stream_buffers)(const struct camera3_device *, - const camera3_stream_buffer_set_t *buffer_set); - - /********************************************************************** - * Request creation and submission - */ - - /** - * construct_default_request_settings: - * - * Create capture settings for standard camera use cases. - * - * The device must return a settings buffer that is configured to meet the - * requested use case, which must be one of the CAMERA3_TEMPLATE_* - * enums. All request control fields must be included. - * - * The HAL retains ownership of this structure, but the pointer to the - * structure must be valid until the device is closed. The framework and the - * HAL may not modify the buffer once it is returned by this call. The same - * buffer may be returned for subsequent calls for the same template, or for - * other templates. - * - * Performance requirements: - * - * This should be a non-blocking call. The HAL should return from this call - * in 1ms, and must return from this call in 5ms. - * - * Return values: - * - * Valid metadata: On successful creation of a default settings - * buffer. - * - * NULL: In case of a fatal error. After this is returned, only - * the close() method can be called successfully by the - * framework. - */ - const camera_metadata_t* (*construct_default_request_settings)( - const struct camera3_device *, - int type); - - /** - * process_capture_request: - * - * Send a new capture request to the HAL. The HAL should not return from - * this call until it is ready to accept the next request to process. Only - * one call to process_capture_request() will be made at a time by the - * framework, and the calls will all be from the same thread. The next call - * to process_capture_request() will be made as soon as a new request and - * its associated buffers are available. In a normal preview scenario, this - * means the function will be called again by the framework almost - * instantly. - * - * The actual request processing is asynchronous, with the results of - * capture being returned by the HAL through the process_capture_result() - * call. This call requires the result metadata to be available, but output - * buffers may simply provide sync fences to wait on. Multiple requests are - * expected to be in flight at once, to maintain full output frame rate. - * - * The framework retains ownership of the request structure. It is only - * guaranteed to be valid during this call. The HAL device must make copies - * of the information it needs to retain for the capture processing. The HAL - * is responsible for waiting on and closing the buffers' fences and - * returning the buffer handles to the framework. - * - * The HAL must write the file descriptor for the input buffer's release - * sync fence into input_buffer->release_fence, if input_buffer is not - * NULL. If the HAL returns -1 for the input buffer release sync fence, the - * framework is free to immediately reuse the input buffer. Otherwise, the - * framework will wait on the sync fence before refilling and reusing the - * input buffer. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * - * The input/output buffers provided by the framework in each request - * may be brand new (having never before seen by the HAL). - * - * ------------------------------------------------------------------------ - * Performance considerations: - * - * Handling a new buffer should be extremely lightweight and there should be - * no frame rate degradation or frame jitter introduced. - * - * This call must return fast enough to ensure that the requested frame - * rate can be sustained, especially for streaming cases (post-processing - * quality settings set to FAST). The HAL should return this call in 1 - * frame interval, and must return from this call in 4 frame intervals. - * - * Return values: - * - * 0: On a successful start to processing the capture request - * - * -EINVAL: If the input is malformed (the settings are NULL when not - * allowed, invalid physical camera settings, - * there are 0 output buffers, etc) and capture processing - * cannot start. Failures during request processing should be - * handled by calling camera3_callback_ops_t.notify(). In case of - * this error, the framework will retain responsibility for the - * stream buffers' fences and the buffer handles; the HAL should - * not close the fences or return these buffers with - * process_capture_result. - * - * -ENODEV: If the camera device has encountered a serious error. After this - * error is returned, only the close() method can be successfully - * called by the framework. - * - */ - int (*process_capture_request)(const struct camera3_device *, - camera3_capture_request_t *request); - - /********************************************************************** - * Miscellaneous methods - */ - - /** - * get_metadata_vendor_tag_ops: - * - * Get methods to query for vendor extension metadata tag information. The - * HAL should fill in all the vendor tag operation methods, or leave ops - * unchanged if no vendor tags are defined. - * - * The definition of vendor_tag_query_ops_t can be found in - * system/media/camera/include/system/camera_metadata.h. - * - * >= CAMERA_DEVICE_API_VERSION_3_2: - * DEPRECATED. This function has been deprecated and should be set to - * NULL by the HAL. Please implement get_vendor_tag_ops in camera_common.h - * instead. - */ - void (*get_metadata_vendor_tag_ops)(const struct camera3_device*, - vendor_tag_query_ops_t* ops); - - /** - * dump: - * - * Print out debugging state for the camera device. This will be called by - * the framework when the camera service is asked for a debug dump, which - * happens when using the dumpsys tool, or when capturing a bugreport. - * - * The passed-in file descriptor can be used to write debugging text using - * dprintf() or write(). The text should be in ASCII encoding only. - * - * Performance requirements: - * - * This must be a non-blocking call. The HAL should return from this call - * in 1ms, must return from this call in 10ms. This call must avoid - * deadlocks, as it may be called at any point during camera operation. - * Any synchronization primitives used (such as mutex locks or semaphores) - * should be acquired with a timeout. - */ - void (*dump)(const struct camera3_device *, int fd); - - /** - * flush: - * - * Flush all currently in-process captures and all buffers in the pipeline - * on the given device. The framework will use this to dump all state as - * quickly as possible in order to prepare for a configure_streams() call. - * - * No buffers are required to be successfully returned, so every buffer - * held at the time of flush() (whether successfully filled or not) may be - * returned with CAMERA3_BUFFER_STATUS_ERROR. Note the HAL is still allowed - * to return valid (CAMERA3_BUFFER_STATUS_OK) buffers during this call, - * provided they are successfully filled. - * - * All requests currently in the HAL are expected to be returned as soon as - * possible. Not-in-process requests should return errors immediately. Any - * interruptible hardware blocks should be stopped, and any uninterruptible - * blocks should be waited on. - * - * flush() may be called concurrently to process_capture_request(), with the expectation that - * process_capture_request will return quickly and the request submitted in that - * process_capture_request call is treated like all other in-flight requests. Due to - * concurrency issues, it is possible that from the HAL's point of view, a - * process_capture_request() call may be started after flush has been invoked but has not - * returned yet. If such a call happens before flush() returns, the HAL should treat the new - * capture request like other in-flight pending requests (see #4 below). - * - * More specifically, the HAL must follow below requirements for various cases: - * - * 1. For captures that are too late for the HAL to cancel/stop, and will be - * completed normally by the HAL; i.e. the HAL can send shutter/notify and - * process_capture_result and buffers as normal. - * - * 2. For pending requests that have not done any processing, the HAL must call notify - * CAMERA3_MSG_ERROR_REQUEST, and return all the output buffers with - * process_capture_result in the error state (CAMERA3_BUFFER_STATUS_ERROR). - * The HAL must not place the release fence into an error state, instead, - * the release fences must be set to the acquire fences passed by the framework, - * or -1 if they have been waited on by the HAL already. This is also the path - * to follow for any captures for which the HAL already called notify() with - * CAMERA3_MSG_SHUTTER but won't be producing any metadata/valid buffers for. - * After CAMERA3_MSG_ERROR_REQUEST, for a given frame, only process_capture_results with - * buffers in CAMERA3_BUFFER_STATUS_ERROR are allowed. No further notifys or - * process_capture_result with non-null metadata is allowed. - * - * 3. For partially completed pending requests that will not have all the output - * buffers or perhaps missing metadata, the HAL should follow below: - * - * 3.1. Call notify with CAMERA3_MSG_ERROR_RESULT if some of the expected result - * metadata (i.e. one or more partial metadata) won't be available for the capture. - * - * 3.2. Call notify with CAMERA3_MSG_ERROR_BUFFER for every buffer that won't - * be produced for the capture. - * - * 3.3 Call notify with CAMERA3_MSG_SHUTTER with the capture timestamp before - * any buffers/metadata are returned with process_capture_result. - * - * 3.4 For captures that will produce some results, the HAL must not call - * CAMERA3_MSG_ERROR_REQUEST, since that indicates complete failure. - * - * 3.5. Valid buffers/metadata should be passed to the framework as normal. - * - * 3.6. Failed buffers should be returned to the framework as described for case 2. - * But failed buffers do not have to follow the strict ordering valid buffers do, - * and may be out-of-order with respect to valid buffers. For example, if buffers - * A, B, C, D, E are sent, D and E are failed, then A, E, B, D, C is an acceptable - * return order. - * - * 3.7. For fully-missing metadata, calling CAMERA3_MSG_ERROR_RESULT is sufficient, no - * need to call process_capture_result with NULL metadata or equivalent. - * - * 4. If a flush() is invoked while a process_capture_request() invocation is active, that - * process call should return as soon as possible. In addition, if a process_capture_request() - * call is made after flush() has been invoked but before flush() has returned, the - * capture request provided by the late process_capture_request call should be treated like - * a pending request in case #2 above. - * - * flush() should only return when there are no more outstanding buffers or - * requests left in the HAL. The framework may call configure_streams (as - * the HAL state is now quiesced) or may issue new requests. - * - * Note that it's sufficient to only support fully-succeeded and fully-failed result cases. - * However, it is highly desirable to support the partial failure cases as well, as it - * could help improve the flush call overall performance. - * - * Performance requirements: - * - * The HAL should return from this call in 100ms, and must return from this - * call in 1000ms. And this call must not be blocked longer than pipeline - * latency (see S7 for definition). - * - * Version information: - * - * only available if device version >= CAMERA_DEVICE_API_VERSION_3_1. - * - * Return values: - * - * 0: On a successful flush of the camera HAL. - * - * -EINVAL: If the input is malformed (the device is not valid). - * - * -ENODEV: If the camera device has encountered a serious error. After this - * error is returned, only the close() method can be successfully - * called by the framework. - */ - int (*flush)(const struct camera3_device *); - - /** - * signal_stream_flush: - * - * <= CAMERA_DEVICE_API_VERISON_3_5: - * - * Not defined and must be NULL - * - * >= CAMERA_DEVICE_API_VERISON_3_6: - * - * Signaling HAL camera service is about to perform configure_streams() call - * and HAL must return all buffers of designated streams. HAL must finish - * inflight requests normally and return all buffers belonging to the - * designated streams through process_capture_result() or - * return_stream_buffers() API in a timely manner, or camera service will run - * into a fatal error. - * - * Note that this call serves as an optional hint and camera service may - * skip calling this if all buffers are already returned. - * - */ - void (*signal_stream_flush)(const struct camera3_device*, - uint32_t num_streams, - const camera3_stream_t* const* streams); - - /** - * is_reconfiguration_required: - * - * <= CAMERA_DEVICE_API_VERISON_3_5: - * - * Not defined and must be NULL - * - * >= CAMERA_DEVICE_API_VERISON_3_6: - * - * Check whether complete stream reconfiguration is required for possible new session - * parameter values. - * - * This method must be called by the camera framework in case the client changes - * the value of any advertised session parameters. Depending on the specific values - * the HAL can decide whether a complete stream reconfiguration is required. In case - * the HAL returns -ENVAL, the camera framework must skip the internal reconfiguration. - * In case Hal returns 0, the framework must reconfigure the streams and pass the - * new session parameter values accordingly. - * This call may be done by the framework some time before the request with new parameters - * is submitted to the HAL, and the request may be cancelled before it ever gets submitted. - * Therefore, the HAL must not use this query as an indication to change its behavior in any - * way. - * ------------------------------------------------------------------------ - * - * Preconditions: - * - * The framework can call this method at any time after active - * session configuration. There must be no impact on the performance of - * pending camera requests in any way. In particular there must not be - * any glitches or delays during normal camera streaming. - * - * Performance requirements: - * HW and SW camera settings must not be changed and there must not be - * a user-visible impact on camera performance. - * - * @param oldSessionParams The currently applied session parameters. - * @param newSessionParams The new session parameters set by client. - * - * @return Status Status code for the operation, one of: - * 0: In case the stream reconfiguration is required - * - * -EINVAL: In case the stream reconfiguration is not required. - * - * -ENOSYS: In case the camera device does not support the - * reconfiguration query. - */ - int (*is_reconfiguration_required)(const struct camera3_device*, - const camera_metadata_t* old_session_params, - const camera_metadata_t* new_session_params); - - /* reserved for future use */ - void *reserved[6]; -} camera3_device_ops_t; - -/********************************************************************** - * - * Camera device definition - * - */ -typedef struct camera3_device { - /** - * common.version must equal CAMERA_DEVICE_API_VERSION_3_0 to identify this - * device as implementing version 3.0 of the camera device HAL. - * - * Performance requirements: - * - * Camera open (common.module->common.methods->open) should return in 200ms, and must return - * in 500ms. - * Camera close (common.close) should return in 200ms, and must return in 500ms. - * - */ - hw_device_t common; - camera3_device_ops_t *ops; - void *priv; -} camera3_device_t; - -__END_DECLS - -#endif /* #ifdef ANDROID_INCLUDE_CAMERA3_H */ +../../include_all/hardware/camera3.h
\ No newline at end of file diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h index 16651a94..359395a1 100644..120000 --- a/include/hardware/camera_common.h +++ b/include/hardware/camera_common.h @@ -1,1218 +1 @@ -/* - * Copyright (C) 2012 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. - */ - -// FIXME: add well-defined names for cameras - -#ifndef ANDROID_INCLUDE_CAMERA_COMMON_H -#define ANDROID_INCLUDE_CAMERA_COMMON_H - -#include <stdint.h> -#include <stdbool.h> -#include <sys/cdefs.h> -#include <sys/types.h> -#include <cutils/native_handle.h> -#include <system/camera.h> -#include <system/camera_vendor_tags.h> -#include <hardware/hardware.h> -#include <hardware/gralloc.h> - -__BEGIN_DECLS - -/** - * The id of this module - */ -#define CAMERA_HARDWARE_MODULE_ID "camera" - -/** - * Module versioning information for the Camera hardware module, based on - * camera_module_t.common.module_api_version. The two most significant hex - * digits represent the major version, and the two least significant represent - * the minor version. - * - ******************************************************************************* - * Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0] - * - * Camera modules that report these version numbers implement the initial - * camera module HAL interface. All camera devices openable through this - * module support only version 1 of the camera device HAL. The device_version - * and static_camera_characteristics fields of camera_info are not valid. Only - * the android.hardware.Camera API can be supported by this module and its - * devices. - * - ******************************************************************************* - * Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0] - * - * Camera modules that report this version number implement the second version - * of the camera module HAL interface. Camera devices openable through this - * module may support either version 1.0 or version 2.0 of the camera device - * HAL interface. The device_version field of camera_info is always valid; the - * static_camera_characteristics field of camera_info is valid if the - * device_version field is 2.0 or higher. - * - ******************************************************************************* - * Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1] - * - * This camera module version adds support for asynchronous callbacks to the - * framework from the camera HAL module, which is used to notify the framework - * about changes to the camera module state. Modules that provide a valid - * set_callbacks() method must report at least this version number. - * - ******************************************************************************* - * Version: 2.2 [CAMERA_MODULE_API_VERSION_2_2] - * - * This camera module version adds vendor tag support from the module, and - * deprecates the old vendor_tag_query_ops that were previously only - * accessible with a device open. - * - ******************************************************************************* - * Version: 2.3 [CAMERA_MODULE_API_VERSION_2_3] - * - * This camera module version adds open legacy camera HAL device support. - * Framework can use it to open the camera device as lower device HAL version - * HAL device if the same device can support multiple device API versions. - * The standard hardware module open call (common.methods->open) continues - * to open the camera device with the latest supported version, which is - * also the version listed in camera_info_t.device_version. - * - ******************************************************************************* - * Version: 2.4 [CAMERA_MODULE_API_VERSION_2_4] - * - * This camera module version adds below API changes: - * - * 1. Torch mode support. The framework can use it to turn on torch mode for - * any camera device that has a flash unit, without opening a camera device. The - * camera device has a higher priority accessing the flash unit than the camera - * module; opening a camera device will turn off the torch if it had been enabled - * through the module interface. When there are any resource conflicts, such as - * open() is called to open a camera device, the camera HAL module must notify the - * framework through the torch mode status callback that the torch mode has been - * turned off. - * - * 2. External camera (e.g. USB hot-plug camera) support. The API updates specify that - * the camera static info is only available when camera is connected and ready to - * use for external hot-plug cameras. Calls to get static info will be invalid - * calls when camera status is not CAMERA_DEVICE_STATUS_PRESENT. The frameworks - * will only count on device status change callbacks to manage the available external - * camera list. - * - * 3. Camera arbitration hints. This module version adds support for explicitly - * indicating the number of camera devices that can be simultaneously opened and used. - * To specify valid combinations of devices, the resource_cost and conflicting_devices - * fields should always be set in the camera_info structure returned by the - * get_camera_info call. - * - * 4. Module initialization method. This will be called by the camera service - * right after the HAL module is loaded, to allow for one-time initialization - * of the HAL. It is called before any other module methods are invoked. - * - ******************************************************************************* - * Version: 2.5 [CAMERA_MODULE_API_VERSION_2_5] - * - * This camera module version adds below API changes: - * - * 1. Support to query characteristics of a non-standalone physical camera, which can - * only be accessed as part of a logical camera. It also adds camera stream combination - * query. - * - * 2. Ability to query whether a particular camera stream combination is - * supported by the camera device. - * - * 3. Device state change notification. This module version also supports - * notification about the overall device state change, such as - * folding/unfolding, or covering/uncovering of shutter. - */ - -/** - * Predefined macros for currently-defined version numbers - */ - -/** - * All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated - * as CAMERA_MODULE_API_VERSION_1_0 - */ -#define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) -#define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) -#define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1) -#define CAMERA_MODULE_API_VERSION_2_2 HARDWARE_MODULE_API_VERSION(2, 2) -#define CAMERA_MODULE_API_VERSION_2_3 HARDWARE_MODULE_API_VERSION(2, 3) -#define CAMERA_MODULE_API_VERSION_2_4 HARDWARE_MODULE_API_VERSION(2, 4) -#define CAMERA_MODULE_API_VERSION_2_5 HARDWARE_MODULE_API_VERSION(2, 5) - -#define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_5 - -/** - * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated - * as CAMERA_DEVICE_API_VERSION_1_0 - */ -#define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) // DEPRECATED -#define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) // NO LONGER SUPPORTED -#define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1) // NO LONGER SUPPORTED -#define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0) // NO LONGER SUPPORTED -#define CAMERA_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1) // NO LONGER SUPPORTED -#define CAMERA_DEVICE_API_VERSION_3_2 HARDWARE_DEVICE_API_VERSION(3, 2) -#define CAMERA_DEVICE_API_VERSION_3_3 HARDWARE_DEVICE_API_VERSION(3, 3) -#define CAMERA_DEVICE_API_VERSION_3_4 HARDWARE_DEVICE_API_VERSION(3, 4) -#define CAMERA_DEVICE_API_VERSION_3_5 HARDWARE_DEVICE_API_VERSION(3, 5) -#define CAMERA_DEVICE_API_VERSION_3_6 HARDWARE_DEVICE_API_VERSION(3, 6) - -// Device version 3.5 is current, older HAL camera device versions are not -// recommended for new devices. -#define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_3_5 - -/** - * Defined in /system/media/camera/include/system/camera_metadata.h - */ -typedef struct camera_metadata camera_metadata_t; - -typedef struct camera_info { - /** - * The direction that the camera faces to. See system/core/include/system/camera.h - * for camera facing definitions. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_2_3 or lower: - * - * It should be CAMERA_FACING_BACK or CAMERA_FACING_FRONT. - * - * CAMERA_MODULE_API_VERSION_2_4 or higher: - * - * It should be CAMERA_FACING_BACK, CAMERA_FACING_FRONT or - * CAMERA_FACING_EXTERNAL. - */ - int facing; - - /** - * The orientation of the camera image. The value is the angle that the - * camera image needs to be rotated clockwise so it shows correctly on the - * display in its natural orientation. It should be 0, 90, 180, or 270. - * - * For example, suppose a device has a naturally tall screen. The - * back-facing camera sensor is mounted in landscape. You are looking at the - * screen. If the top side of the camera sensor is aligned with the right - * edge of the screen in natural orientation, the value should be 90. If the - * top side of a front-facing camera sensor is aligned with the right of the - * screen, the value should be 270. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_2_3 or lower: - * - * Valid in all camera_module versions. - * - * CAMERA_MODULE_API_VERSION_2_4 or higher: - * - * Valid if camera facing is CAMERA_FACING_BACK or CAMERA_FACING_FRONT, - * not valid if camera facing is CAMERA_FACING_EXTERNAL. - */ - int orientation; - - /** - * The value of camera_device_t.common.version. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_1_0: - * - * Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do - * not read this field. - * - * CAMERA_MODULE_API_VERSION_2_0 or higher: - * - * Always valid - * - */ - uint32_t device_version; - - /** - * The camera's fixed characteristics, which include all static camera metadata - * specified in system/media/camera/docs/docs.html. This should be a sorted metadata - * buffer, and may not be modified or freed by the caller. The pointer should remain - * valid for the lifetime of the camera module, and values in it may not - * change after it is returned by get_camera_info(). - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_1_0: - * - * Not valid. Extra characteristics are not available. Do not read this - * field. - * - * CAMERA_MODULE_API_VERSION_2_0 or higher: - * - * Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read - * otherwise. - * - */ - const camera_metadata_t *static_camera_characteristics; - - /** - * The total resource "cost" of using this camera, represented as an integer - * value in the range [0, 100] where 100 represents total usage of the shared - * resource that is the limiting bottleneck of the camera subsystem. This may - * be a very rough estimate, and is used as a hint to the camera service to - * determine when to disallow multiple applications from simultaneously - * opening different cameras advertised by the camera service. - * - * The camera service must be able to simultaneously open and use any - * combination of camera devices exposed by the HAL where the sum of - * the resource costs of these cameras is <= 100. For determining cost, - * each camera device must be assumed to be configured and operating at - * the maximally resource-consuming framerate and stream size settings - * available in the configuration settings exposed for that device through - * the camera metadata. - * - * The camera service may still attempt to simultaneously open combinations - * of camera devices with a total resource cost > 100. This may succeed or - * fail. If this succeeds, combinations of configurations that are not - * supported due to resource constraints from having multiple open devices - * should fail during the configure calls. If the total resource cost is - * <= 100, open and configure should never fail for any stream configuration - * settings or other device capabilities that would normally succeed for a - * device when it is the only open camera device. - * - * This field will be used to determine whether background applications are - * allowed to use this camera device while other applications are using other - * camera devices. Note: multiple applications will never be allowed by the - * camera service to simultaneously open the same camera device. - * - * Example use cases: - * - * Ex. 1: Camera Device 0 = Back Camera - * Camera Device 1 = Front Camera - * - Using both camera devices causes a large framerate slowdown due to - * limited ISP bandwidth. - * - * Configuration: - * - * Camera Device 0 - resource_cost = 51 - * conflicting_devices = null - * Camera Device 1 - resource_cost = 51 - * conflicting_devices = null - * - * Result: - * - * Since the sum of the resource costs is > 100, if a higher-priority - * application has either device open, no lower-priority applications will be - * allowed by the camera service to open either device. If a lower-priority - * application is using a device that a higher-priority subsequently attempts - * to open, the lower-priority application will be forced to disconnect the - * the device. - * - * If the highest-priority application chooses, it may still attempt to open - * both devices (since these devices are not listed as conflicting in the - * conflicting_devices fields), but usage of these devices may fail in the - * open or configure calls. - * - * Ex. 2: Camera Device 0 = Left Back Camera - * Camera Device 1 = Right Back Camera - * Camera Device 2 = Combined stereo camera using both right and left - * back camera sensors used by devices 0, and 1 - * Camera Device 3 = Front Camera - * - Due to do hardware constraints, up to two cameras may be open at once. The - * combined stereo camera may never be used at the same time as either of the - * two back camera devices (device 0, 1), and typically requires too much - * bandwidth to use at the same time as the front camera (device 3). - * - * Configuration: - * - * Camera Device 0 - resource_cost = 50 - * conflicting_devices = { 2 } - * Camera Device 1 - resource_cost = 50 - * conflicting_devices = { 2 } - * Camera Device 2 - resource_cost = 100 - * conflicting_devices = { 0, 1 } - * Camera Device 3 - resource_cost = 50 - * conflicting_devices = null - * - * Result: - * - * Based on the conflicting_devices fields, the camera service guarantees that - * the following sets of open devices will never be allowed: { 1, 2 }, { 0, 2 }. - * - * Based on the resource_cost fields, if a high-priority foreground application - * is using camera device 0, a background application would be allowed to open - * camera device 1 or 3 (but would be forced to disconnect it again if the - * foreground application opened another device). - * - * The highest priority application may still attempt to simultaneously open - * devices 0, 2, and 3, but the HAL may fail in open or configure calls for - * this combination. - * - * Ex. 3: Camera Device 0 = Back Camera - * Camera Device 1 = Front Camera - * Camera Device 2 = Low-power Front Camera that uses the same - * sensor as device 1, but only exposes image stream - * resolutions that can be used in low-power mode - * - Using both front cameras (device 1, 2) at the same time is impossible due - * a shared physical sensor. Using the back and "high-power" front camera - * (device 1) may be impossible for some stream configurations due to hardware - * limitations, but the "low-power" front camera option may always be used as - * it has special dedicated hardware. - * - * Configuration: - * - * Camera Device 0 - resource_cost = 100 - * conflicting_devices = null - * Camera Device 1 - resource_cost = 100 - * conflicting_devices = { 2 } - * Camera Device 2 - resource_cost = 0 - * conflicting_devices = { 1 } - * Result: - * - * Based on the conflicting_devices fields, the camera service guarantees that - * the following sets of open devices will never be allowed: { 1, 2 }. - * - * Based on the resource_cost fields, only the highest priority application - * may attempt to open both device 0 and 1 at the same time. If a higher-priority - * application is not using device 1 or 2, a low-priority background application - * may open device 2 (but will be forced to disconnect it if a higher-priority - * application subsequently opens device 1 or 2). - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_2_3 or lower: - * - * Not valid. Can be assumed to be 100. Do not read this field. - * - * CAMERA_MODULE_API_VERSION_2_4 or higher: - * - * Always valid. - */ - int resource_cost; - - /** - * An array of camera device IDs represented as NULL-terminated strings - * indicating other devices that cannot be simultaneously opened while this - * camera device is in use. - * - * This field is intended to be used to indicate that this camera device - * is a composite of several other camera devices, or otherwise has - * hardware dependencies that prohibit simultaneous usage. If there are no - * dependencies, a NULL may be returned in this field to indicate this. - * - * The camera service will never simultaneously open any of the devices - * in this list while this camera device is open. - * - * The strings pointed to in this field will not be cleaned up by the camera - * service, and must remain while this device is plugged in. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_2_3 or lower: - * - * Not valid. Can be assumed to be NULL. Do not read this field. - * - * CAMERA_MODULE_API_VERSION_2_4 or higher: - * - * Always valid. - */ - char** conflicting_devices; - - /** - * The length of the array given in the conflicting_devices field. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_2_3 or lower: - * - * Not valid. Can be assumed to be 0. Do not read this field. - * - * CAMERA_MODULE_API_VERSION_2_4 or higher: - * - * Always valid. - */ - size_t conflicting_devices_length; - -} camera_info_t; - -/** - * camera_device_status_t: - * - * The current status of the camera device, as provided by the HAL through the - * camera_module_callbacks.camera_device_status_change() call. - * - * At module load time, the framework will assume all camera devices are in the - * CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke - * camera_module_callbacks::camera_device_status_change to inform the framework - * of any initially NOT_PRESENT devices. - * - * Allowed transitions: - * PRESENT -> NOT_PRESENT - * NOT_PRESENT -> ENUMERATING - * NOT_PRESENT -> PRESENT - * ENUMERATING -> PRESENT - * ENUMERATING -> NOT_PRESENT - */ -typedef enum camera_device_status { - /** - * The camera device is not currently connected, and opening it will return - * failure. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_2_3 or lower: - * - * Calls to get_camera_info must still succeed, and provide the same information - * it would if the camera were connected. - * - * CAMERA_MODULE_API_VERSION_2_4: - * - * The camera device at this status must return -EINVAL for get_camera_info call, - * as the device is not connected. - */ - CAMERA_DEVICE_STATUS_NOT_PRESENT = 0, - - /** - * The camera device is connected, and opening it will succeed. - * - * CAMERA_MODULE_API_VERSION_2_3 or lower: - * - * The information returned by get_camera_info cannot change due to this status - * change. By default, the framework will assume all devices are in this state. - * - * CAMERA_MODULE_API_VERSION_2_4: - * - * The information returned by get_camera_info will become valid after a device's - * status changes to this. By default, the framework will assume all devices are in - * this state. - */ - CAMERA_DEVICE_STATUS_PRESENT = 1, - - /** - * The camera device is connected, but it is undergoing an enumeration and - * so opening the device will return -EBUSY. - * - * CAMERA_MODULE_API_VERSION_2_3 or lower: - * - * Calls to get_camera_info must still succeed, as if the camera was in the - * PRESENT status. - * - * CAMERA_MODULE_API_VERSION_2_4: - * - * The camera device at this status must return -EINVAL for get_camera_info for call, - * as the device is not ready. - */ - CAMERA_DEVICE_STATUS_ENUMERATING = 2, - -} camera_device_status_t; - -/** - * torch_mode_status_t: - * - * The current status of the torch mode, as provided by the HAL through the - * camera_module_callbacks.torch_mode_status_change() call. - * - * The torch mode status of a camera device is applicable only when the camera - * device is present. The framework will not call set_torch_mode() to turn on - * torch mode of a camera device if the camera device is not present. At module - * load time, the framework will assume torch modes are in the - * TORCH_MODE_STATUS_AVAILABLE_OFF state if the camera device is present and - * android.flash.info.available is reported as true via get_camera_info() call. - * - * The behaviors of the camera HAL module that the framework expects in the - * following situations when a camera device's status changes: - * 1. A previously-disconnected camera device becomes connected. - * After camera_module_callbacks::camera_device_status_change() is invoked - * to inform the framework that the camera device is present, the framework - * will assume the camera device's torch mode is in - * TORCH_MODE_STATUS_AVAILABLE_OFF state. The camera HAL module does not need - * to invoke camera_module_callbacks::torch_mode_status_change() unless the - * flash unit is unavailable to use by set_torch_mode(). - * - * 2. A previously-connected camera becomes disconnected. - * After camera_module_callbacks::camera_device_status_change() is invoked - * to inform the framework that the camera device is not present, the - * framework will not call set_torch_mode() for the disconnected camera - * device until its flash unit becomes available again. The camera HAL - * module does not need to invoke - * camera_module_callbacks::torch_mode_status_change() separately to inform - * that the flash unit has become unavailable. - * - * 3. open() is called to open a camera device. - * The camera HAL module must invoke - * camera_module_callbacks::torch_mode_status_change() for all flash units - * that have entered TORCH_MODE_STATUS_NOT_AVAILABLE state and can not be - * turned on by calling set_torch_mode() anymore due to this open() call. - * open() must not trigger TORCH_MODE_STATUS_AVAILABLE_OFF before - * TORCH_MODE_STATUS_NOT_AVAILABLE for all flash units that have become - * unavailable. - * - * 4. close() is called to close a camera device. - * The camera HAL module must invoke - * camera_module_callbacks::torch_mode_status_change() for all flash units - * that have entered TORCH_MODE_STATUS_AVAILABLE_OFF state and can be turned - * on by calling set_torch_mode() again because of enough resources freed - * up by this close() call. - * - * Note that the framework calling set_torch_mode() successfully must trigger - * TORCH_MODE_STATUS_AVAILABLE_OFF or TORCH_MODE_STATUS_AVAILABLE_ON callback - * for the given camera device. Additionally it must trigger - * TORCH_MODE_STATUS_AVAILABLE_OFF callbacks for other previously-on torch - * modes if HAL cannot keep multiple torch modes on simultaneously. - */ -typedef enum torch_mode_status { - - /** - * The flash unit is no longer available and the torch mode can not be - * turned on by calling set_torch_mode(). If the torch mode is on, it - * will be turned off by HAL before HAL calls torch_mode_status_change(). - */ - TORCH_MODE_STATUS_NOT_AVAILABLE = 0, - - /** - * A torch mode has become off and available to be turned on via - * set_torch_mode(). This may happen in the following - * cases: - * 1. After the resources to turn on the torch mode have become available. - * 2. After set_torch_mode() is called to turn off the torch mode. - * 3. After the framework turned on the torch mode of some other camera - * device and HAL had to turn off the torch modes of any camera devices - * that were previously on. - */ - TORCH_MODE_STATUS_AVAILABLE_OFF = 1, - - /** - * A torch mode has become on and available to be turned off via - * set_torch_mode(). This can happen only after set_torch_mode() is called - * to turn on the torch mode. - */ - TORCH_MODE_STATUS_AVAILABLE_ON = 2, - -} torch_mode_status_t; - -/** - * Callback functions for the camera HAL module to use to inform the framework - * of changes to the camera subsystem. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * Each callback is called only by HAL modules implementing the indicated - * version or higher of the HAL module API interface. - * - * CAMERA_MODULE_API_VERSION_2_1: - * camera_device_status_change() - * - * CAMERA_MODULE_API_VERSION_2_4: - * torch_mode_status_change() - - */ -typedef struct camera_module_callbacks { - - /** - * camera_device_status_change: - * - * Callback to the framework to indicate that the state of a specific camera - * device has changed. At module load time, the framework will assume all - * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL - * must call this method to inform the framework of any initially - * NOT_PRESENT devices. - * - * This callback is added for CAMERA_MODULE_API_VERSION_2_1. - * - * camera_module_callbacks: The instance of camera_module_callbacks_t passed - * to the module with set_callbacks. - * - * camera_id: The ID of the camera device that has a new status. - * - * new_status: The new status code, one of the camera_device_status_t enums, - * or a platform-specific status. - * - */ - void (*camera_device_status_change)(const struct camera_module_callbacks*, - int camera_id, - int new_status); - - /** - * torch_mode_status_change: - * - * Callback to the framework to indicate that the state of the torch mode - * of the flash unit associated with a specific camera device has changed. - * At module load time, the framework will assume the torch modes are in - * the TORCH_MODE_STATUS_AVAILABLE_OFF state if android.flash.info.available - * is reported as true via get_camera_info() call. - * - * This callback is added for CAMERA_MODULE_API_VERSION_2_4. - * - * camera_module_callbacks: The instance of camera_module_callbacks_t - * passed to the module with set_callbacks. - * - * camera_id: The ID of camera device whose flash unit has a new torch mode - * status. - * - * new_status: The new status code, one of the torch_mode_status_t enums. - */ - void (*torch_mode_status_change)(const struct camera_module_callbacks*, - const char* camera_id, - int new_status); - - -} camera_module_callbacks_t; - -/** - * camera_stream_t: - * - * A handle to a single camera input or output stream. A stream is defined by - * the framework by its buffer resolution and format and gralloc usage flags. - * - * The stream structures are owned by the framework and pointers to a - * camera_stream passed into the HAL by is_stream_combination_supported() are - * only valid within the scope of the call. - * - * All camera_stream members are immutable. - */ -typedef struct camera_stream { - /** - * The type of the stream, one of the camera3_stream_type_t values. - */ - int stream_type; - - /** - * The width in pixels of the buffers in this stream - */ - uint32_t width; - - /** - * The height in pixels of the buffers in this stream - */ - uint32_t height; - - /** - * The pixel format for the buffers in this stream. Format is a value from - * the HAL_PIXEL_FORMAT_* list in system/core/include/system/graphics.h, or - * from device-specific headers. - * - * If HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform - * gralloc module will select a format based on the usage flags provided by - * the camera device and the other endpoint of the stream. - * - */ - int format; - - /** - * The gralloc usage flags for this stream, as needed by the HAL. The usage - * flags are defined in gralloc.h (GRALLOC_USAGE_*), or in device-specific - * headers. - * - * For output streams, these are the HAL's producer usage flags. For input - * streams, these are the HAL's consumer usage flags. The usage flags from - * the producer and the consumer will be combined together and then passed - * to the platform gralloc HAL module for allocating the gralloc buffers for - * each stream. - * - * The usage flag for an output stream may be bitwise - * combination of usage flags for multiple consumers, for the purpose of - * sharing one camera stream between those consumers. The HAL must fail - * the stream combination query call with -EINVAL if the combined flags cannot be - * supported due to imcompatible buffer format, dataSpace, or other hardware - * limitations. - */ - uint32_t usage; - - /** - * A field that describes the contents of the buffer. The format and buffer - * dimensions define the memory layout and structure of the stream buffers, - * while dataSpace defines the meaning of the data within the buffer. - * - * For most formats, dataSpace defines the color space of the image data. - * In addition, for some formats, dataSpace indicates whether image- or - * depth-based data is requested. See system/core/include/system/graphics.h - * for details of formats and valid dataSpace values for each format. - * - * Always set by the camera service. The dataspace values are set - * using the V0 dataspace definitions in graphics.h - */ - android_dataspace_t data_space; - - /** - * The required output rotation of the stream, one of - * the camera3_stream_rotation_t values. This must be inspected by HAL along - * with stream width and height. For example, if the rotation is 90 degree - * and the stream width and height is 720 and 1280 respectively, camera service - * will supply buffers of size 720x1280, and HAL should capture a 1280x720 image - * and rotate the image by 90 degree counterclockwise. The rotation field is - * no-op when the stream type is input. Camera HAL must ignore the rotation - * field for an input stream. - * - * Always set by camera service. HAL must inspect this field during stream - * combination query and return -EINVAL if it cannot perform such rotation. - * HAL must always support CAMERA3_STREAM_ROTATION_0, so a - * is_stream_combination_supported() call must not fail for unsupported rotation if - * rotation field of all streams is CAMERA3_STREAM_ROTATION_0. - * - */ - int rotation; - - /** - * The physical camera id this stream belongs to. - * Always set by camera service. If the camera device is not a logical - * multi camera, or if the camera is a logical multi camera but the stream - * is not a physical output stream, this field will point to a 0-length - * string. - * - * A logical multi camera is a camera device backed by multiple physical - * cameras that are also exposed to the application. And for a logical - * multi camera, a physical output stream is an output stream specifically - * requested on an underlying physical camera. - * - * For an input stream, this field is guaranteed to be a 0-length string. - */ - const char* physical_camera_id; - -} camera_stream_t; - -/** - * camera_stream_combination_t: - * - * A structure of stream definitions, used by is_stream_combination_supported(). This - * structure defines all the input & output streams for specific camera use case. - */ -typedef struct camera_stream_combination { - /** - * The total number of streams by the framework. This includes - * both input and output streams. The number of streams will be at least 1, - * and there will be at least one output-capable stream. - */ - uint32_t num_streams; - - /** - * An array of camera streams, defining the input/output - * stream combination for the camera HAL device. - * - * At most one input-capable stream may be defined. - * - * At least one output-capable stream must be defined. - */ - camera_stream_t *streams; - - /** - * The operation mode of streams in this stream combination, one of the value - * defined in camera3_stream_configuration_mode_t. - * - */ - uint32_t operation_mode; - -} camera_stream_combination_t; - -/** - * device_state_t: - * - * Possible physical states of the overall device, for use with - * notify_device_state_change. - */ -typedef enum device_state { - /** - * The device is in its normal physical configuration. This is the default if the - * device does not support multiple different states. - */ - NORMAL = 0, - - /** - * Camera device(s) facing backward are covered. - */ - BACK_COVERED = 1 << 0, - - /** - * Camera device(s) facing foward are covered. - */ - FRONT_COVERED = 1 << 1, - - /** - * The device is folded. If not set, the device is unfolded or does not - * support folding. - * - * The exact point when this status change happens during the folding - * operation is device-specific. - */ - FOLDED = 1 << 2, - - /** - * First vendor-specific device state. All bits above and including this one - * are for vendor state values. Values below this one must only be used - * for framework-defined states. - */ - VENDOR_STATE_START = 1LL << 32 - -} device_state_t; - -typedef struct camera_module { - /** - * Common methods of the camera module. This *must* be the first member of - * camera_module as users of this structure will cast a hw_module_t to - * camera_module pointer in contexts where it's known the hw_module_t - * references a camera_module. - * - * The return values for common.methods->open for camera_module are: - * - * 0: On a successful open of the camera device. - * - * -ENODEV: The camera device cannot be opened due to an internal - * error. - * - * -EINVAL: The input arguments are invalid, i.e. the id is invalid, - * and/or the module is invalid. - * - * -EBUSY: The camera device was already opened for this camera id - * (by using this method or open_legacy), - * regardless of the device HAL version it was opened as. - * - * -EUSERS: The maximal number of camera devices that can be - * opened concurrently were opened already, either by - * this method or the open_legacy method. - * - * All other return values from common.methods->open will be treated as - * -ENODEV. - */ - hw_module_t common; - - /** - * get_number_of_cameras: - * - * Returns the number of camera devices accessible through the camera - * module. The camera devices are numbered 0 through N-1, where N is the - * value returned by this call. The name of the camera device for open() is - * simply the number converted to a string. That is, "0" for camera ID 0, - * "1" for camera ID 1. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_2_3 or lower: - * - * The value here must be static, and cannot change after the first call - * to this method. - * - * CAMERA_MODULE_API_VERSION_2_4 or higher: - * - * The value here must be static, and must count only built-in cameras, - * which have CAMERA_FACING_BACK or CAMERA_FACING_FRONT camera facing values - * (camera_info.facing). The HAL must not include the external cameras - * (camera_info.facing == CAMERA_FACING_EXTERNAL) into the return value - * of this call. Frameworks will use camera_device_status_change callback - * to manage number of external cameras. - */ - int (*get_number_of_cameras)(void); - - /** - * get_camera_info: - * - * Return the static camera information for a given camera device. This - * information may not change for a camera device. - * - * Return values: - * - * 0: On a successful operation - * - * -ENODEV: The information cannot be provided due to an internal - * error. - * - * -EINVAL: The input arguments are invalid, i.e. the id is invalid, - * and/or the module is invalid. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_2_4 or higher: - * - * When a camera is disconnected, its camera id becomes invalid. Calling this - * this method with this invalid camera id will get -EINVAL and NULL camera - * static metadata (camera_info.static_camera_characteristics). - */ - int (*get_camera_info)(int camera_id, struct camera_info *info); - - /** - * set_callbacks: - * - * Provide callback function pointers to the HAL module to inform framework - * of asynchronous camera module events. The framework will call this - * function once after initial camera HAL module load, after the - * get_number_of_cameras() method is called for the first time, and before - * any other calls to the module. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0: - * - * Not provided by HAL module. Framework may not call this function. - * - * CAMERA_MODULE_API_VERSION_2_1: - * - * Valid to be called by the framework. - * - * Return values: - * - * 0: On a successful operation - * - * -ENODEV: The operation cannot be completed due to an internal - * error. - * - * -EINVAL: The input arguments are invalid, i.e. the callbacks are - * null - */ - int (*set_callbacks)(const camera_module_callbacks_t *callbacks); - - /** - * get_vendor_tag_ops: - * - * Get methods to query for vendor extension metadata tag information. The - * HAL should fill in all the vendor tag operation methods, or leave ops - * unchanged if no vendor tags are defined. - * - * The vendor_tag_ops structure used here is defined in: - * system/media/camera/include/system/vendor_tags.h - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1: - * Not provided by HAL module. Framework may not call this function. - * - * CAMERA_MODULE_API_VERSION_2_2: - * Valid to be called by the framework. - */ - void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops); - - /** - * open_legacy: - * - * Open a specific legacy camera HAL device if multiple device HAL API - * versions are supported by this camera HAL module. For example, if the - * camera module supports both CAMERA_DEVICE_API_VERSION_1_0 and - * CAMERA_DEVICE_API_VERSION_3_2 device API for the same camera id, - * framework can call this function to open the camera device as - * CAMERA_DEVICE_API_VERSION_1_0 device. - * - * This is an optional method. A Camera HAL module does not need to support - * more than one device HAL version per device, and such modules may return - * -ENOSYS for all calls to this method. For all older HAL device API - * versions that are not supported, it may return -EOPNOTSUPP. When above - * cases occur, The normal open() method (common.methods->open) will be - * used by the framework instead. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2: - * Not provided by HAL module. Framework will not call this function. - * - * CAMERA_MODULE_API_VERSION_2_3: - * Valid to be called by the framework. - * - * Return values: - * - * 0: On a successful open of the camera device. - * - * -ENOSYS This method is not supported. - * - * -EOPNOTSUPP: The requested HAL version is not supported by this method. - * - * -EINVAL: The input arguments are invalid, i.e. the id is invalid, - * and/or the module is invalid. - * - * -EBUSY: The camera device was already opened for this camera id - * (by using this method or common.methods->open method), - * regardless of the device HAL version it was opened as. - * - * -EUSERS: The maximal number of camera devices that can be - * opened concurrently were opened already, either by - * this method or common.methods->open method. - */ - int (*open_legacy)(const struct hw_module_t* module, const char* id, - uint32_t halVersion, struct hw_device_t** device); - - /** - * set_torch_mode: - * - * Turn on or off the torch mode of the flash unit associated with a given - * camera ID. If the operation is successful, HAL must notify the framework - * torch state by invoking - * camera_module_callbacks.torch_mode_status_change() with the new state. - * - * The camera device has a higher priority accessing the flash unit. When - * there are any resource conflicts, such as open() is called to open a - * camera device, HAL module must notify the framework through - * camera_module_callbacks.torch_mode_status_change() that the - * torch mode has been turned off and the torch mode state has become - * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode - * become available again, HAL module must notify the framework through - * camera_module_callbacks.torch_mode_status_change() that the torch mode - * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to - * be called. - * - * When the framework calls set_torch_mode() to turn on the torch mode of a - * flash unit, if HAL cannot keep multiple torch modes on simultaneously, - * HAL should turn off the torch mode that was turned on by - * a previous set_torch_mode() call and notify the framework that the torch - * mode state of that flash unit has become TORCH_MODE_STATUS_AVAILABLE_OFF. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3: - * Not provided by HAL module. Framework will not call this function. - * - * CAMERA_MODULE_API_VERSION_2_4: - * Valid to be called by the framework. - * - * Return values: - * - * 0: On a successful operation. - * - * -ENOSYS: The camera device does not support this operation. It is - * returned if and only if android.flash.info.available is - * false. - * - * -EBUSY: The camera device is already in use. - * - * -EUSERS: The resources needed to turn on the torch mode are not - * available, typically because other camera devices are - * holding the resources to make using the flash unit not - * possible. - * - * -EINVAL: camera_id is invalid. - * - */ - int (*set_torch_mode)(const char* camera_id, bool enabled); - - /** - * init: - * - * This method is called by the camera service before any other methods - * are invoked, right after the camera HAL library has been successfully - * loaded. It may be left as NULL by the HAL module, if no initialization - * in needed. - * - * It can be used by HAL implementations to perform initialization and - * other one-time operations. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3: - * Not provided by HAL module. Framework will not call this function. - * - * CAMERA_MODULE_API_VERSION_2_4: - * If not NULL, will always be called by the framework once after the HAL - * module is loaded, before any other HAL module method is called. - * - * Return values: - * - * 0: On a successful operation. - * - * -ENODEV: Initialization cannot be completed due to an internal - * error. The HAL must be assumed to be in a nonfunctional - * state. - * - */ - int (*init)(); - - /** - * get_physical_camera_info: - * - * Return the static metadata for a physical camera as a part of a logical - * camera device. This function is only called for those physical camera - * ID(s) that are not exposed independently. In other words, camera_id will - * be greater or equal to the return value of get_number_of_cameras(). - * - * Return values: - * - * 0: On a successful operation - * - * -ENODEV: The information cannot be provided due to an internal - * error. - * - * -EINVAL: The input arguments are invalid, i.e. the id is invalid, - * and/or the module is invalid. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3/2_4: - * Not provided by HAL module. Framework will not call this function. - * - * CAMERA_MODULE_API_VERSION_2_5 or higher: - * If any of the camera devices accessible through this camera module is - * a logical multi-camera, and at least one of the physical cameras isn't - * a stand-alone camera device, this function will be called by the camera - * framework. Calling this function with invalid physical_camera_id will - * get -EINVAL, and NULL static_metadata. - */ - int (*get_physical_camera_info)(int physical_camera_id, - camera_metadata_t **static_metadata); - - /** - * is_stream_combination_supported: - * - * Check for device support of specific camera stream combination. - * - * Return values: - * - * 0: In case the stream combination is supported. - * - * -EINVAL: In case the stream combination is not supported. - * - * -ENOSYS: In case stream combination query is not supported. - * - * Version information (based on camera_module_t.common.module_api_version): - * - * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3/2_4: - * Not provided by HAL module. Framework will not call this function. - * - * CAMERA_MODULE_API_VERSION_2_5 or higher: - * Valid to be called by the framework. - */ - int (*is_stream_combination_supported)(int camera_id, - const camera_stream_combination_t *streams); - - /** - * notify_device_state_change: - * - * Notify the camera module that the state of the overall device has - * changed in some way that the HAL may want to know about. - * - * For example, a physical shutter may have been uncovered or covered, - * or a camera may have been covered or uncovered by an add-on keyboard - * or other accessory. - * - * The state is a bitfield of potential states, and some physical configurations - * could plausibly correspond to multiple different combinations of state bits. - * The HAL must ignore any state bits it is not actively using to determine - * the appropriate camera configuration. - * - * For example, on some devices the FOLDED state could mean that - * backward-facing cameras are covered by the fold, so FOLDED by itself implies - * BACK_COVERED. But other devices may support folding but not cover any cameras - * when folded, so for those FOLDED would not imply any of the other flags. - * Since these relationships are very device-specific, it is difficult to specify - * a comprehensive policy. But as a recommendation, it is suggested that if a flag - * necessarily implies other flags are set as well, then those flags should be set. - * So even though FOLDED would be enough to infer BACK_COVERED on some devices, the - * BACK_COVERED flag should also be set for clarity. - * - * This method may be invoked by the HAL client at any time. It must not - * cause any active camera device sessions to be closed, but may dynamically - * change which physical camera a logical multi-camera is using for its - * active and future output. - * - * The method must be invoked by the HAL client at least once before the - * client calls ICameraDevice::open on any camera device interfaces listed - * by this provider, to establish the initial device state. - * - * Note that the deviceState is 64-bit bitmask, with system defined states in - * lower 32-bit and vendor defined states in upper 32-bit. - */ - void (*notify_device_state_change)(uint64_t deviceState); - - /* reserved for future use */ - void* reserved[2]; -} camera_module_t; - -__END_DECLS - -#endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */ +../../include_all/hardware/camera_common.h
\ No newline at end of file diff --git a/include/hardware/context_hub.h b/include/hardware/context_hub.h index 137cb3e5..3f06d0a8 100644..120000 --- a/include/hardware/context_hub.h +++ b/include/hardware/context_hub.h @@ -1,450 +1 @@ -/* - * Copyright (C) 2016 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 CONTEXT_HUB_H -#define CONTEXT_HUB_H - -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <hardware/hardware.h> - -/** - * This header file defines the interface of a Context Hub Implementation to - * the Android service exposing Context hub capabilities to applications. - * The Context hub is expected to a low power compute domain with the following - * defining charecteristics - - * - * 1) Access to sensors like accelerometer, gyroscope, magenetometer. - * 2) Access to radios like GPS, Wifi, Bluetooth etc. - * 3) Access to low power audio sensing. - * - * Implementations of this HAL can add additional sensors not defined by the - * Android API. Such information sources shall be private to the implementation. - * - * The Context Hub HAL exposes the construct of code download. A piece of binary - * code can be pushed to the context hub through the supported APIs. - * - * This version of the HAL designs in the possibility of multiple context hubs. - */ - -__BEGIN_DECLS - -/*****************************************************************************/ - -#define CONTEXT_HUB_HEADER_MAJOR_VERSION 1 -#define CONTEXT_HUB_HEADER_MINOR_VERSION 1 -#define CONTEXT_HUB_DEVICE_API_VERSION \ - HARDWARE_DEVICE_API_VERSION(CONTEXT_HUB_HEADER_MAJOR_VERSION, \ - CONTEXT_HUB_HEADER_MINOR_VERSION) - -#define CONTEXT_HUB_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) -#define CONTEXT_HUB_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION(1, 1) - -/** - * The id of this module - */ -#define CONTEXT_HUB_MODULE_ID "context_hub" - -/** - * Name of the device to open - */ -#define CONTEXT_HUB_HARDWARE_POLL "ctxt_poll" - -/** - * Memory types for code upload. Device-specific. At least HUB_MEM_TYPE_MAIN must be supported - */ -#define HUB_MEM_TYPE_MAIN 0 -#define HUB_MEM_TYPE_SECONDARY 1 -#define HUB_MEM_TYPE_TCM 2 - - -#define HUB_MEM_TYPE_FIRST_VENDOR 0x80000000ul - -#define NANOAPP_VENDORS_ALL 0xFFFFFFFFFF000000ULL -#define NANOAPP_VENDOR_ALL_APPS 0x0000000000FFFFFFULL - -#define NANOAPP_VENDOR(name) \ - (((uint64_t)(name)[0] << 56) | \ - ((uint64_t)(name)[1] << 48) | \ - ((uint64_t)(name)[2] << 40) | \ - ((uint64_t)(name)[3] << 32) | \ - ((uint64_t)(name)[4] << 24)) - -/* - * generates the NANOAPP ID from vendor id and app seq# id - */ -#define NANO_APP_ID(vendor, seq_id) \ - (((uint64_t)(vendor) & NANOAPP_VENDORS_ALL) | ((uint64_t)(seq_id) & NANOAPP_VENDOR_ALL_APPS)) - -struct hub_app_name_t { - uint64_t id; -}; - -/** - * Other memory types (likely not writeable, informational only) - */ -#define HUB_MEM_TYPE_BOOTLOADER 0xfffffffful -#define HUB_MEM_TYPE_OS 0xfffffffeul -#define HUB_MEM_TYPE_EEDATA 0xfffffffdul -#define HUB_MEM_TYPE_RAM 0xfffffffcul - -/** - * Types of memory blocks on the context hub - * */ -#define MEM_FLAG_READ 0x1 // Memory can be written to -#define MEM_FLAG_WRITE 0x2 // Memory can be written to -#define MEM_FLAG_EXEC 0x4 // Memory can be executed from - -/** - * The following structure defines each memory block in detail - */ -struct mem_range_t { - uint32_t total_bytes; - uint32_t free_bytes; - uint32_t type; // HUB_MEM_TYPE_* - uint32_t mem_flags; // MEM_FLAG_* -}; - -#define NANOAPP_SIGNED_FLAG 0x1 -#define NANOAPP_ENCRYPTED_FLAG 0x2 -#define NANOAPP_MAGIC (((uint32_t)'N' << 0) | ((uint32_t)'A' << 8) | ((uint32_t)'N' << 16) | ((uint32_t)'O' << 24)) - -// The binary format below is in little endian format -struct nano_app_binary_t { - uint32_t header_version; // 0x1 for this version - uint32_t magic; // "NANO" - struct hub_app_name_t app_id; // App Id contains vendor id - uint32_t app_version; // Version of the app - uint32_t flags; // Signed, encrypted - uint64_t hw_hub_type; // which hub type is this compiled for - - // The version of the CHRE API that this nanoapp was compiled against. - // If these values are both set to 0, then they must be interpreted the same - // as if major version were set to 1, and minor 0 (the first valid CHRE API - // version). - uint8_t target_chre_api_major_version; - uint8_t target_chre_api_minor_version; - - uint8_t reserved[6]; // Should be all zeroes - uint8_t custom_binary[0]; // start of custom binary data -} __attribute__((packed)); - -struct hub_app_info { - struct hub_app_name_t app_name; - uint32_t version; - uint32_t num_mem_ranges; - struct mem_range_t mem_usage[2]; // Apps could only have RAM and SHARED_DATA -}; - -/** - * Following enum defines the types of sensors that a hub may declare support - * for. Declaration for support would mean that the hub can access and process - * data from that particular sensor type. - */ - -typedef enum { - CONTEXT_SENSOR_RESERVED, // 0 - CONTEXT_SENSOR_ACCELEROMETER, // 1 - CONTEXT_SENSOR_GYROSCOPE, // 2 - CONTEXT_SENSOR_MAGNETOMETER, // 3 - CONTEXT_SENSOR_BAROMETER, // 4 - CONTEXT_SENSOR_PROXIMITY_SENSOR, // 5 - CONTEXT_SENSOR_AMBIENT_LIGHT_SENSOR, // 6 - - CONTEXT_SENSOR_GPS = 0x100, // 0x100 - // Reserving this space for variants on GPS - CONTEXT_SENSOR_WIFI = 0x200, // 0x200 - // Reserving this space for variants on WIFI - CONTEXT_SENSOR_AUDIO = 0x300, // 0x300 - // Reserving this space for variants on Audio - CONTEXT_SENSOR_CAMERA = 0x400, // 0x400 - // Reserving this space for variants on Camera - CONTEXT_SENSOR_BLE = 0x500, // 0x500 - - CONTEXT_SENSOR_MAX = 0xffffffff, //make sure enum size is set -} context_sensor_e; - -/** - * Sensor types beyond CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE are custom types - */ -#define CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE 0x10000 - -/** - * The following structure describes a sensor - */ -struct physical_sensor_description_t { - uint32_t sensor_type; // From the definitions above eg: 100 - const char *type_string; // Type as a string. eg: "GPS" - const char *name; // Identifier eg: "Bosch BMI160" - const char *vendor; // Vendor : eg "STM" - uint32_t version; // Version : eg 0x1001 - uint32_t fifo_reserved_count; // Batching possible in hardware. Please - // note that here hardware does not include - // the context hub itself. Thus, this - // definition may be different from say the - // number advertised in the sensors HAL - // which allows for batching in a hub. - uint32_t fifo_max_count; // maximum number of batchable events. - uint64_t min_delay_ms; // in milliseconds, corresponding to highest - // sampling freq. - uint64_t max_delay_ms; // in milliseconds, corresponds to minimum - // sampling frequency - float peak_power_mw; // At max frequency & no batching, power - // in milliwatts -}; - -struct connected_sensor_t { - uint32_t sensor_id; // identifier for this sensor - - /* This union may be extended to other sensor types */ - union { - struct physical_sensor_description_t physical_sensor; - }; -}; - -struct hub_message_t { - struct hub_app_name_t app_name; /* To/From this nanoapp */ - uint32_t message_type; - uint32_t message_len; - const void *message; -}; - -/** - * Definition of a context hub. A device may contain more than one low - * power domain. In that case, please add an entry for each hub. However, - * it is perfectly OK for a device to declare one context hub and manage - * them internally as several - */ - -struct context_hub_t { - const char *name; // descriptive name eg: "Awesome Hub #1" - const char *vendor; // hub hardware vendor eg: "Qualcomm" - const char *toolchain; // toolchain to make binaries eg:"gcc ARM" - uint32_t platform_version; // Version of the hardware : eg 0x20 - uint32_t toolchain_version; // Version of the toolchain : eg: 0x484 - uint32_t hub_id; // a device unique id for this hub - - float peak_mips; // Peak MIPS platform can deliver - float stopped_power_draw_mw; // if stopped, retention power, milliwatts - float sleep_power_draw_mw; // if sleeping, retention power, milliwatts - float peak_power_draw_mw; // for a busy CPUm power in milliwatts - - const struct connected_sensor_t *connected_sensors; // array of connected sensors - uint32_t num_connected_sensors; // number of connected sensors - - const struct hub_app_name_t os_app_name; /* send msgs here for OS functions */ - uint32_t max_supported_msg_len; // This is the maximum size of the message that can - // be sent to the hub in one chunk (in bytes) -}; - -/** - * Definitions of message payloads, see hub_messages_e - */ - -struct status_response_t { - int32_t result; // 0 on success, < 0 : error on failure. > 0 for any descriptive status -}; - -struct apps_enable_request_t { - struct hub_app_name_t app_name; -}; - -struct apps_disable_request_t { - struct hub_app_name_t app_name; -}; - -struct load_app_request_t { - struct nano_app_binary_t app_binary; -}; - -struct unload_app_request_t { - struct hub_app_name_t app_name; -}; - -struct query_apps_request_t { - struct hub_app_name_t app_name; -}; - -/** - * CONTEXT_HUB_APPS_ENABLE - * Enables the specified nano-app(s) - * - * Payload : apps_enable_request_t - * - * Response : status_response_t - * On receipt of a successful response, it is - * expected that - * - * i) the app is executing and able to receive - * any messages. - * - * ii) the system should be able to respond to an - * CONTEXT_HUB_QUERY_APPS request. - * - */ - -/** - * CONTEXT_HUB_APPS_DISABLE - * Stops the specified nano-app(s) - * - * Payload : apps_disable_request_t - * - * Response : status_response_t - * On receipt of a successful response, - * i) No further events are delivered to the - * nanoapp. - * - * ii) The app should not show up in a - * CONTEXT_HUB_QUERY_APPS request. - */ - -/** - * CONTEXT_HUB_LOAD_APP - * Loads a nanoApp. Upon loading the nanoApp's init method is - * called. - * - * - * Payload : load_app_request_t - * - * Response : status_response_t On receipt of a successful - * response, it is expected that - * i) the app is executing and able to receive - * messages. - * - * ii) the system should be able to respond to a - * CONTEXT_HUB_QUERY_APPS. - */ - -/** - * CONTEXT_HUB_UNLOAD_APP - * Unloads a nanoApp. Before the unload, the app's deinit method - * is called. - * - * Payload : unload_app_request_t. - * - * Response : status_response_t On receipt of a - * successful response, it is expected that - * i) No further events are delivered to the - * nanoapp. - * - * ii) the system does not list the app in a - * response to a CONTEXT_HUB_QUERY_APPS. - * - * iii) Any resources used by the app should be - * freed up and available to the system. - */ - -/** - * CONTEXT_HUB_QUERY_APPS Queries for status of apps - * - * Payload : query_apps_request_t - * - * Response : struct hub_app_info[] - */ - -/** - * CONTEXT_HUB_QUERY_MEMORY Queries for memory regions on the - * hub - * - * Payload : NULL - * - * Response : struct mem_range_t[] - */ - -/** - * CONTEXT_HUB_OS_REBOOT - * Reboots context hub OS, restarts all the nanoApps. - * No reboot notification is sent to nanoApps; reboot happens immediately and - * unconditionally; all volatile FW state and any data is lost as a result - * - * Payload : none - * - * Response : status_response_t - * On receipt of a successful response, it is - * expected that - * - * i) system reboot has completed; - * status contains reboot reason code (platform-specific) - * - * Unsolicited response: - * System may send unsolicited response at any time; - * this should be interpreted as FW reboot, and necessary setup - * has to be done (same or similar to the setup done on system boot) - */ - -/** - * All communication between the context hubs and the Context Hub Service is in - * the form of messages. Some message types are distinguished and their - * Semantics shall be well defined. - * Custom message types should be defined starting above - * CONTEXT_HUB_PRIVATE_MSG_BASE - */ - -typedef enum { - CONTEXT_HUB_APPS_ENABLE = 1, // Enables loaded nano-app(s) - CONTEXT_HUB_APPS_DISABLE = 2, // Disables loaded nano-app(s) - CONTEXT_HUB_LOAD_APP = 3, // Load a supplied app - CONTEXT_HUB_UNLOAD_APP = 4, // Unload a specified app - CONTEXT_HUB_QUERY_APPS = 5, // Query for app(s) info on hub - CONTEXT_HUB_QUERY_MEMORY = 6, // Query for memory info - CONTEXT_HUB_OS_REBOOT = 7, // Request to reboot context HUB OS -} hub_messages_e; - -#define CONTEXT_HUB_TYPE_PRIVATE_MSG_BASE 0x00400 - -/** - * A callback registers with the context hub service to pass messages - * coming from the hub to the service/clients. - */ -typedef int context_hub_callback(uint32_t hub_id, const struct hub_message_t *rxed_msg, void *cookie); - - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -struct context_hub_module_t { - struct hw_module_t common; - - /** - * Enumerate all available hubs.The list is returned in "list". - * @return result : number of hubs in list or error (negative) - * - * This method shall be called at device bootup. - */ - int (*get_hubs)(struct context_hub_module_t* module, const struct context_hub_t ** list); - - /** - * Registers a callback for the HAL implementation to communicate - * with the context hub service. - * @return result : 0 if successful, error code otherwise - */ - int (*subscribe_messages)(uint32_t hub_id, context_hub_callback cbk, void *cookie); - - /** - * Send a message to a hub - * @return result : 0 if successful, error code otherwise - */ - int (*send_message)(uint32_t hub_id, const struct hub_message_t *msg); - -}; - -__END_DECLS - -#endif // CONTEXT_HUB_SENSORS_INTERFACE_H +../../include_all/hardware/context_hub.h
\ No newline at end of file diff --git a/include/hardware/fb.h b/include/hardware/fb.h index 65720a39..4606b504 100644..120000 --- a/include/hardware/fb.h +++ b/include/hardware/fb.h @@ -1,173 +1 @@ -/* - * Copyright (C) 2008 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_FB_INTERFACE_H -#define ANDROID_FB_INTERFACE_H - -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <cutils/native_handle.h> - -#include <hardware/hardware.h> - -__BEGIN_DECLS - -#define GRALLOC_HARDWARE_FB0 "fb0" - -/*****************************************************************************/ - - -/*****************************************************************************/ - -typedef struct framebuffer_device_t { - /** - * Common methods of the framebuffer device. This *must* be the first member of - * framebuffer_device_t as users of this structure will cast a hw_device_t to - * framebuffer_device_t pointer in contexts where it's known the hw_device_t references a - * framebuffer_device_t. - */ - struct hw_device_t common; - - /* flags describing some attributes of the framebuffer */ - const uint32_t flags; - - /* dimensions of the framebuffer in pixels */ - const uint32_t width; - const uint32_t height; - - /* frambuffer stride in pixels */ - const int stride; - - /* framebuffer pixel format */ - const int format; - - /* resolution of the framebuffer's display panel in pixel per inch*/ - const float xdpi; - const float ydpi; - - /* framebuffer's display panel refresh rate in frames per second */ - const float fps; - - /* min swap interval supported by this framebuffer */ - const int minSwapInterval; - - /* max swap interval supported by this framebuffer */ - const int maxSwapInterval; - - /* Number of framebuffers supported*/ - const int numFramebuffers; - - int reserved[7]; - - /* - * requests a specific swap-interval (same definition than EGL) - * - * Returns 0 on success or -errno on error. - */ - int (*setSwapInterval)(struct framebuffer_device_t* window, - int interval); - - /* - * This hook is OPTIONAL. - * - * It is non NULL If the framebuffer driver supports "update-on-demand" - * and the given rectangle is the area of the screen that gets - * updated during (*post)(). - * - * This is useful on devices that are able to DMA only a portion of - * the screen to the display panel, upon demand -- as opposed to - * constantly refreshing the panel 60 times per second, for instance. - * - * Only the area defined by this rectangle is guaranteed to be valid, that - * is, the driver is not allowed to post anything outside of this - * rectangle. - * - * The rectangle evaluated during (*post)() and specifies which area - * of the buffer passed in (*post)() shall to be posted. - * - * return -EINVAL if width or height <=0, or if left or top < 0 - */ - int (*setUpdateRect)(struct framebuffer_device_t* window, - int left, int top, int width, int height); - - /* - * Post <buffer> to the display (display it on the screen) - * The buffer must have been allocated with the - * GRALLOC_USAGE_HW_FB usage flag. - * buffer must be the same width and height as the display and must NOT - * be locked. - * - * The buffer is shown during the next VSYNC. - * - * If the same buffer is posted again (possibly after some other buffer), - * post() will block until the the first post is completed. - * - * Internally, post() is expected to lock the buffer so that a - * subsequent call to gralloc_module_t::(*lock)() with USAGE_RENDER or - * USAGE_*_WRITE will block until it is safe; that is typically once this - * buffer is shown and another buffer has been posted. - * - * Returns 0 on success or -errno on error. - */ - int (*post)(struct framebuffer_device_t* dev, buffer_handle_t buffer); - - - /* - * The (*compositionComplete)() method must be called after the - * compositor has finished issuing GL commands for client buffers. - */ - - int (*compositionComplete)(struct framebuffer_device_t* dev); - - /* - * This hook is OPTIONAL. - * - * If non NULL it will be caused by SurfaceFlinger on dumpsys - */ - void (*dump)(struct framebuffer_device_t* dev, char *buff, int buff_len); - - /* - * (*enableScreen)() is used to either blank (enable=0) or - * unblank (enable=1) the screen this framebuffer is attached to. - * - * Returns 0 on success or -errno on error. - */ - int (*enableScreen)(struct framebuffer_device_t* dev, int enable); - - void* reserved_proc[6]; - -} framebuffer_device_t; - - -/** convenience API for opening and closing a supported device */ - -static inline int framebuffer_open(const struct hw_module_t* module, - struct framebuffer_device_t** device) { - return module->methods->open(module, - GRALLOC_HARDWARE_FB0, TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int framebuffer_close(struct framebuffer_device_t* device) { - return device->common.close(&device->common); -} - - -__END_DECLS - -#endif // ANDROID_FB_INTERFACE_H +../../include_all/hardware/fb.h
\ No newline at end of file diff --git a/include/hardware/fingerprint.h b/include/hardware/fingerprint.h index 86ced9b4..65108894 100644..120000 --- a/include/hardware/fingerprint.h +++ b/include/hardware/fingerprint.h @@ -1,277 +1 @@ -/* - * Copyright (C) 2014 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_INCLUDE_HARDWARE_FINGERPRINT_H -#define ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H - -#include <hardware/hardware.h> -#include <hardware/hw_auth_token.h> - -#define FINGERPRINT_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) -#define FINGERPRINT_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) -#define FINGERPRINT_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1) -#define FINGERPRINT_MODULE_API_VERSION_3_0 HARDWARE_MODULE_API_VERSION(3, 0) -#define FINGERPRINT_HARDWARE_MODULE_ID "fingerprint" - -typedef enum fingerprint_msg_type { - FINGERPRINT_ERROR = -1, - FINGERPRINT_ACQUIRED = 1, - FINGERPRINT_TEMPLATE_ENROLLING = 3, - FINGERPRINT_TEMPLATE_REMOVED = 4, - FINGERPRINT_AUTHENTICATED = 5, - FINGERPRINT_TEMPLATE_ENUMERATING = 6, -} fingerprint_msg_type_t; - -/* - * Fingerprint errors are meant to tell the framework to terminate the current operation and ask - * for the user to correct the situation. These will almost always result in messaging and user - * interaction to correct the problem. - * - * For example, FINGERPRINT_ERROR_CANCELED should follow any acquisition message that results in - * a situation where the current operation can't continue without user interaction. For example, - * if the sensor is dirty during enrollment and no further enrollment progress can be made, - * send FINGERPRINT_ACQUIRED_IMAGER_DIRTY followed by FINGERPRINT_ERROR_CANCELED. - */ -typedef enum fingerprint_error { - FINGERPRINT_ERROR_HW_UNAVAILABLE = 1, /* The hardware has an error that can't be resolved. */ - FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2, /* Bad data; operation can't continue */ - FINGERPRINT_ERROR_TIMEOUT = 3, /* The operation has timed out waiting for user input. */ - FINGERPRINT_ERROR_NO_SPACE = 4, /* No space available to store a template */ - FINGERPRINT_ERROR_CANCELED = 5, /* The current operation can't proceed. See above. */ - FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint with given id can't be removed */ - FINGERPRINT_ERROR_LOCKOUT = 7, /* the fingerprint hardware is in lockout due to too many attempts */ - FINGERPRINT_ERROR_VENDOR_BASE = 1000 /* vendor-specific error messages start here */ -} fingerprint_error_t; - -/* - * Fingerprint acquisition info is meant as feedback for the current operation. Anything but - * FINGERPRINT_ACQUIRED_GOOD will be shown to the user as feedback on how to take action on the - * current operation. For example, FINGERPRINT_ACQUIRED_IMAGER_DIRTY can be used to tell the user - * to clean the sensor. If this will cause the current operation to fail, an additional - * FINGERPRINT_ERROR_CANCELED can be sent to stop the operation in progress (e.g. enrollment). - * In general, these messages will result in a "Try again" message. - */ -typedef enum fingerprint_acquired_info { - FINGERPRINT_ACQUIRED_GOOD = 0, - FINGERPRINT_ACQUIRED_PARTIAL = 1, /* sensor needs more data, i.e. longer swipe. */ - FINGERPRINT_ACQUIRED_INSUFFICIENT = 2, /* image doesn't contain enough detail for recognition*/ - FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3, /* sensor needs to be cleaned */ - FINGERPRINT_ACQUIRED_TOO_SLOW = 4, /* mostly swipe-type sensors; not enough data collected */ - FINGERPRINT_ACQUIRED_TOO_FAST = 5, /* for swipe and area sensors; tell user to slow down*/ - FINGERPRINT_ACQUIRED_DETECTED = 6, /* when the finger is first detected. Used to optimize wakeup. - Should be followed by one of the above messages */ - FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000 /* vendor-specific acquisition messages start here */ -} fingerprint_acquired_info_t; - -typedef struct fingerprint_finger_id { - uint32_t gid; - uint32_t fid; -} fingerprint_finger_id_t; - -typedef struct fingerprint_enroll { - fingerprint_finger_id_t finger; - /* samples_remaining goes from N (no data collected, but N scans needed) - * to 0 (no more data is needed to build a template). */ - uint32_t samples_remaining; - uint64_t msg; /* Vendor specific message. Used for user guidance */ -} fingerprint_enroll_t; - -typedef struct fingerprint_iterator { - fingerprint_finger_id_t finger; - uint32_t remaining_templates; -} fingerprint_iterator_t; - -typedef fingerprint_iterator_t fingerprint_enumerated_t; -typedef fingerprint_iterator_t fingerprint_removed_t; - -typedef struct fingerprint_acquired { - fingerprint_acquired_info_t acquired_info; /* information about the image */ -} fingerprint_acquired_t; - -typedef struct fingerprint_authenticated { - fingerprint_finger_id_t finger; - hw_auth_token_t hat; -} fingerprint_authenticated_t; - -typedef struct fingerprint_msg { - fingerprint_msg_type_t type; - union { - fingerprint_error_t error; - fingerprint_enroll_t enroll; - fingerprint_enumerated_t enumerated; - fingerprint_removed_t removed; - fingerprint_acquired_t acquired; - fingerprint_authenticated_t authenticated; - } data; -} fingerprint_msg_t; - -/* Callback function type */ -typedef void (*fingerprint_notify_t)(const fingerprint_msg_t *msg); - -/* Synchronous operation */ -typedef struct fingerprint_device { - /** - * Common methods of the fingerprint device. This *must* be the first member - * of fingerprint_device as users of this structure will cast a hw_device_t - * to fingerprint_device pointer in contexts where it's known - * the hw_device_t references a fingerprint_device. - */ - struct hw_device_t common; - - /* - * Client provided callback function to receive notifications. - * Do not set by hand, use the function above instead. - */ - fingerprint_notify_t notify; - - /* - * Set notification callback: - * Registers a user function that would receive notifications from the HAL - * The call will block if the HAL state machine is in busy state until HAL - * leaves the busy state. - * - * Function return: 0 if callback function is successfuly registered - * or a negative number in case of error, generally from the errno.h set. - */ - int (*set_notify)(struct fingerprint_device *dev, fingerprint_notify_t notify); - - /* - * Fingerprint pre-enroll enroll request: - * Generates a unique token to upper layers to indicate the start of an enrollment transaction. - * This token will be wrapped by security for verification and passed to enroll() for - * verification before enrollment will be allowed. This is to ensure adding a new fingerprint - * template was preceded by some kind of credential confirmation (e.g. device password). - * - * Function return: 0 if function failed - * otherwise, a uint64_t of token - */ - uint64_t (*pre_enroll)(struct fingerprint_device *dev); - - /* - * Fingerprint enroll request: - * Switches the HAL state machine to collect and store a new fingerprint - * template. Switches back as soon as enroll is complete - * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING && - * fingerprint_msg.data.enroll.samples_remaining == 0) - * or after timeout_sec seconds. - * The fingerprint template will be assigned to the group gid. User has a choice - * to supply the gid or set it to 0 in which case a unique group id will be generated. - * - * Function return: 0 if enrollment process can be successfully started - * or a negative number in case of error, generally from the errno.h set. - * A notify() function may be called indicating the error condition. - */ - int (*enroll)(struct fingerprint_device *dev, const hw_auth_token_t *hat, - uint32_t gid, uint32_t timeout_sec); - - /* - * Finishes the enroll operation and invalidates the pre_enroll() generated challenge. - * This will be called at the end of a multi-finger enrollment session to indicate - * that no more fingers will be added. - * - * Function return: 0 if the request is accepted - * or a negative number in case of error, generally from the errno.h set. - */ - int (*post_enroll)(struct fingerprint_device *dev); - - /* - * get_authenticator_id: - * Returns a token associated with the current fingerprint set. This value will - * change whenever a new fingerprint is enrolled, thus creating a new fingerprint - * set. - * - * Function return: current authenticator id or 0 if function failed. - */ - uint64_t (*get_authenticator_id)(struct fingerprint_device *dev); - - /* - * Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED - * to all running clients. Switches the HAL state machine back to the idle state. - * Unlike enroll_done() doesn't invalidate the pre_enroll() challenge. - * - * Function return: 0 if cancel request is accepted - * or a negative number in case of error, generally from the errno.h set. - */ - int (*cancel)(struct fingerprint_device *dev); - - /* - * Enumerate all the fingerprint templates found in the directory set by - * set_active_group() - * For each template found a notify() will be called with: - * fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENUMERATED - * fingerprint_msg.data.enumerated.finger indicating a template id - * fingerprint_msg.data.enumerated.remaining_templates indicating how many more - * enumeration messages to expect. - * Note: If there are no fingerprints, then this should return 0 and the first fingerprint - * enumerated should have fingerid=0 and remaining=0 - * Function return: 0 if enumerate request is accepted - * or a negative number in case of error, generally from the errno.h set. - */ - int (*enumerate)(struct fingerprint_device *dev); - - /* - * Fingerprint remove request: - * Deletes a fingerprint template. - * Works only within the path set by set_active_group(). - * The fid parameter can be used as a widcard: - * * fid == 0 -- delete all the templates in the group. - * * fid != 0 -- delete this specific template from the group. - * For each template found a notify() will be called with: - * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED - * fingerprint_msg.data.removed.finger indicating a template id deleted - * fingerprint_msg.data.removed.remaining_templates indicating how many more - * templates will be deleted by this operation. - * - * Function return: 0 if fingerprint template(s) can be successfully deleted - * or a negative number in case of error, generally from the errno.h set. - */ - int (*remove)(struct fingerprint_device *dev, uint32_t gid, uint32_t fid); - - /* - * Restricts the HAL operation to a set of fingerprints belonging to a - * group provided. - * The caller must provide a path to a storage location within the user's - * data directory. - * - * Function return: 0 on success - * or a negative number in case of error, generally from the errno.h set. - */ - int (*set_active_group)(struct fingerprint_device *dev, uint32_t gid, - const char *store_path); - - /* - * Authenticates an operation identifed by operation_id - * - * Function return: 0 on success - * or a negative number in case of error, generally from the errno.h set. - */ - int (*authenticate)(struct fingerprint_device *dev, uint64_t operation_id, uint32_t gid); - - /* Reserved for backward binary compatibility */ - void *reserved[4]; -} fingerprint_device_t; - -typedef struct fingerprint_module { - /** - * Common methods of the fingerprint module. This *must* be the first member - * of fingerprint_module as users of this structure will cast a hw_module_t - * to fingerprint_module pointer in contexts where it's known - * the hw_module_t references a fingerprint_module. - */ - struct hw_module_t common; -} fingerprint_module_t; - -#endif /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */ +../../include_all/hardware/fingerprint.h
\ No newline at end of file diff --git a/include/hardware/gatekeeper.h b/include/hardware/gatekeeper.h index 2bb2b08c..e186e3ce 100644..120000 --- a/include/hardware/gatekeeper.h +++ b/include/hardware/gatekeeper.h @@ -1,190 +1 @@ -/* - * 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_GATEKEEPER_H -#define ANDROID_HARDWARE_GATEKEEPER_H - -#include <sys/cdefs.h> -#include <sys/types.h> -#include <hardware/hardware.h> - -__BEGIN_DECLS - -#define GATEKEEPER_HARDWARE_MODULE_ID "gatekeeper" - -#define GATEKEEPER_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) - -#define HARDWARE_GATEKEEPER "gatekeeper" - -struct gatekeeper_module { - /** - * Comon methods of the gatekeeper module. This *must* be the first member of - * gatekeeper_module as users of this structure will cast a hw_module_t to - * a gatekeeper_module pointer in the appropriate context. - */ - hw_module_t common; -}; - -struct gatekeeper_device { - /** - * Common methods of the gatekeeper device. As above, this must be the first - * member of keymaster_device. - */ - hw_device_t common; - - /** - * Enrolls desired_password, which should be derived from a user selected pin or password, - * with the authentication factor private key used only for enrolling authentication - * factor data. - * - * If there was already a password enrolled, it should be provided in - * current_password_handle, along with the current password in current_password - * that should validate against current_password_handle. - * - * Parameters: - * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open - * - uid: the Android user identifier - * - * - current_password_handle: the currently enrolled password handle the user - * wants to replace. May be null if there's no currently enrolled password. - * - current_password_handle_length: the length in bytes of the buffer pointed - * at by current_password_handle. Must be 0 if current_password_handle is NULL. - * - * - current_password: the user's current password in plain text. If presented, - * it MUST verify against current_password_handle. - * - current_password_length: the size in bytes of the buffer pointed at by - * current_password. Must be 0 if the current_password is NULL. - * - * - desired_password: the new password the user wishes to enroll in plain-text. - * Cannot be NULL. - * - desired_password_length: the length in bytes of the buffer pointed at by - * desired_password. - * - * - enrolled_password_handle: on success, a buffer will be allocated with the - * new password handle referencing the password provided in desired_password. - * This buffer can be used on subsequent calls to enroll or verify. - * The caller is responsible for deallocating this buffer via a call to delete[] - * - enrolled_password_handle_length: pointer to the length in bytes of the buffer allocated - * by this function and pointed to by *enrolled_password_handle_length. - * - * Returns: - * - 0 on success - * - An error code < 0 on failure, or - * - A timeout value T > 0 if the call should not be re-attempted until T milliseconds - * have elapsed. - * - * On error, enrolled_password_handle will not be allocated. - */ - int (*enroll)(const struct gatekeeper_device *dev, uint32_t uid, - const uint8_t *current_password_handle, uint32_t current_password_handle_length, - const uint8_t *current_password, uint32_t current_password_length, - const uint8_t *desired_password, uint32_t desired_password_length, - uint8_t **enrolled_password_handle, uint32_t *enrolled_password_handle_length); - - /** - * Verifies provided_password matches enrolled_password_handle. - * - * Implementations of this module may retain the result of this call - * to attest to the recency of authentication. - * - * On success, writes the address of a verification token to auth_token, - * usable to attest password verification to other trusted services. Clients - * may pass NULL for this value. - * - * Parameters: - * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open - * - uid: the Android user identifier - * - * - challenge: An optional challenge to authenticate against, or 0. Used when a separate - * authenticator requests password verification, or for transactional - * password authentication. - * - * - enrolled_password_handle: the currently enrolled password handle that the - * user wishes to verify against. - * - enrolled_password_handle_length: the length in bytes of the buffer pointed - * to by enrolled_password_handle - * - * - provided_password: the plaintext password to be verified against the - * enrolled_password_handle - * - provided_password_length: the length in bytes of the buffer pointed to by - * provided_password - * - * - auth_token: on success, a buffer containing the authentication token - * resulting from this verification is assigned to *auth_token. The caller - * is responsible for deallocating this memory via a call to delete[] - * - auth_token_length: on success, the length in bytes of the authentication - * token assigned to *auth_token will be assigned to *auth_token_length - * - * - request_reenroll: a request to the upper layers to re-enroll the verified - * password due to a version change. Not set if verification fails. - * - * Returns: - * - 0 on success - * - An error code < 0 on failure, or - * - A timeout value T > 0 if the call should not be re-attempted until T milliseconds - * have elapsed. - * On error, auth token will not be allocated - */ - int (*verify)(const struct gatekeeper_device *dev, uint32_t uid, uint64_t challenge, - const uint8_t *enrolled_password_handle, uint32_t enrolled_password_handle_length, - const uint8_t *provided_password, uint32_t provided_password_length, - uint8_t **auth_token, uint32_t *auth_token_length, bool *request_reenroll); - - /* - * Deletes the enrolled_password_handle associated wth the uid. Once deleted - * the user cannot be verified anymore. - * This function is optional and should be set to NULL if it is not implemented. - * - * Parameters - * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open - * - uid: the Android user identifier - * - * Returns: - * - 0 on success - * - An error code < 0 on failure - */ - int (*delete_user)(const struct gatekeeper_device *dev, uint32_t uid); - - /* - * Deletes all the enrolled_password_handles for all uid's. Once called, - * no users will be enrolled on the device. - * This function is optional and should be set to NULL if it is not implemented. - * - * Parameters - * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open - * - * Returns: - * - 0 on success - * - An error code < 0 on failure - */ - int (*delete_all_users)(const struct gatekeeper_device *dev); -}; - -typedef struct gatekeeper_device gatekeeper_device_t; - -static inline int gatekeeper_open(const struct hw_module_t *module, - gatekeeper_device_t **device) { - return module->methods->open(module, HARDWARE_GATEKEEPER, - (struct hw_device_t **) device); -} - -static inline int gatekeeper_close(gatekeeper_device_t *device) { - return device->common.close(&device->common); -} - -__END_DECLS - -#endif // ANDROID_HARDWARE_GATEKEEPER_H +../../include_all/hardware/gatekeeper.h
\ No newline at end of file diff --git a/include/hardware/gnss-base.h b/include/hardware/gnss-base.h index 706aa387..c17eed76 100644..120000 --- a/include/hardware/gnss-base.h +++ b/include/hardware/gnss-base.h @@ -1,276 +1 @@ -// This file is autogenerated by hidl-gen. Do not edit manually. -// Source: android.hardware.gnss@1.0 -// Location: hardware/interfaces/gnss/1.0/ - -#ifndef HIDL_GENERATED_ANDROID_HARDWARE_GNSS_V1_0_EXPORTED_CONSTANTS_H_ -#define HIDL_GENERATED_ANDROID_HARDWARE_GNSS_V1_0_EXPORTED_CONSTANTS_H_ - -#ifdef __cplusplus -extern "C" { -#endif - -enum { - GNSS_MAX_SVS_COUNT = 64u, -}; - -enum { - GNSS_CONSTELLATION_UNKNOWN = 0, - GNSS_CONSTELLATION_GPS = 1, - GNSS_CONSTELLATION_SBAS = 2, - GNSS_CONSTELLATION_GLONASS = 3, - GNSS_CONSTELLATION_QZSS = 4, - GNSS_CONSTELLATION_BEIDOU = 5, - GNSS_CONSTELLATION_GALILEO = 6, -}; - -enum { - GPS_LOCATION_HAS_LAT_LONG = 1 /* 0x0001 */, - GPS_LOCATION_HAS_ALTITUDE = 2 /* 0x0002 */, - GPS_LOCATION_HAS_SPEED = 4 /* 0x0004 */, - GPS_LOCATION_HAS_BEARING = 8 /* 0x0008 */, - GPS_LOCATION_HAS_HORIZONTAL_ACCURACY = 16 /* 0x0010 */, - GPS_LOCATION_HAS_VERTICAL_ACCURACY = 32 /* 0x0020 */, - GPS_LOCATION_HAS_SPEED_ACCURACY = 64 /* 0x0040 */, - GPS_LOCATION_HAS_BEARING_ACCURACY = 128 /* 0x0080 */, -}; - -enum { - APN_IP_INVALID = 0, - APN_IP_IPV4 = 1, - APN_IP_IPV6 = 2, - APN_IP_IPV4V6 = 3, -}; - -enum { - AGPS_TYPE_SUPL = 1, - AGPS_TYPE_C2K = 2, -}; - -enum { - GNSS_REQUEST_AGNSS_DATA_CONN = 1, - GNSS_RELEASE_AGNSS_DATA_CONN = 2, - GNSS_AGNSS_DATA_CONNECTED = 3, - GNSS_AGNSS_DATA_CONN_DONE = 4, - GNSS_AGNSS_DATA_CONN_FAILED = 5, -}; - -enum { - AGPS_SETID_TYPE_NONE = 0, - AGPS_SETID_TYPE_IMSI = 1, - AGPS_SETID_TYPE_MSISDM = 2, -}; - -enum { - AGPS_RIL_NETWORK_TYPE_MOBILE = 0, - AGPS_RIL_NETWORK_TYPE_WIFI = 1, - AGPS_RIL_NETWORK_TYPE_MMS = 2, - AGPS_RIL_NETWORK_TYPE_SUPL = 3, - AGPS_RIL_NETWORK_TYPE_DUN = 4, - AGPS_RIL_NETWORK_TYPE_HIPRI = 5, - AGPS_RIL_NETWORK_TYPE_WIMAX = 6, -}; - -enum { - AGPS_REF_LOCATION_TYPE_GSM_CELLID = 1, - AGPS_REF_LOCATION_TYPE_UMTS_CELLID = 2, - AGPS_REF_LOCATION_TYPE_LTE_CELLID = 4, -}; - -enum { - AGPS_RIL_REQUEST_SETID_IMSI = 1u /* (1 << 0L) */, - AGPS_RIL_REQUEST_SETID_MSISDN = 2u /* (1 << 1L) */, -}; - -enum { - GPS_POSITION_MODE_STANDALONE = 0, - GPS_POSITION_MODE_MS_BASED = 1, - GPS_POSITION_MODE_MS_ASSISTED = 2, -}; - -enum { - GPS_POSITION_RECURRENCE_PERIODIC = 0u, - GPS_POSITION_RECURRENCE_SINGLE = 1u, -}; - -enum { - GPS_DELETE_EPHEMERIS = 1 /* 0x0001 */, - GPS_DELETE_ALMANAC = 2 /* 0x0002 */, - GPS_DELETE_POSITION = 4 /* 0x0004 */, - GPS_DELETE_TIME = 8 /* 0x0008 */, - GPS_DELETE_IONO = 16 /* 0x0010 */, - GPS_DELETE_UTC = 32 /* 0x0020 */, - GPS_DELETE_HEALTH = 64 /* 0x0040 */, - GPS_DELETE_SVDIR = 128 /* 0x0080 */, - GPS_DELETE_SVSTEER = 256 /* 0x0100 */, - GPS_DELETE_SADATA = 512 /* 0x0200 */, - GPS_DELETE_RTI = 1024 /* 0x0400 */, - GPS_DELETE_CELLDB_INFO = 32768 /* 0x8000 */, - GPS_DELETE_ALL = 65535 /* 0xFFFF */, -}; - -enum { - FLP_BATCH_WAKEUP_ON_FIFO_FULL = 1 /* 0x01 */, -}; - -enum { - GPS_CAPABILITY_SCHEDULING = 1u /* (1 << 0) */, - GPS_CAPABILITY_MSB = 2u /* (1 << 1) */, - GPS_CAPABILITY_MSA = 4u /* (1 << 2) */, - GPS_CAPABILITY_SINGLE_SHOT = 8u /* (1 << 3) */, - GPS_CAPABILITY_ON_DEMAND_TIME = 16u /* (1 << 4) */, - GPS_CAPABILITY_GEOFENCING = 32u /* (1 << 5) */, - GPS_CAPABILITY_MEASUREMENTS = 64u /* (1 << 6) */, - GPS_CAPABILITY_NAV_MESSAGES = 128u /* (1 << 7) */, -}; - -enum { - GPS_STATUS_NONE = 0, - GPS_STATUS_SESSION_BEGIN = 1, - GPS_STATUS_SESSION_END = 2, - GPS_STATUS_ENGINE_ON = 3, - GPS_STATUS_ENGINE_OFF = 4, -}; - -enum { - GNSS_SV_FLAGS_NONE = 0, - GNSS_SV_FLAGS_HAS_EPHEMERIS_DATA = 1 /* (1 << 0) */, - GNSS_SV_FLAGS_HAS_ALMANAC_DATA = 2 /* (1 << 1) */, - GNSS_SV_FLAGS_USED_IN_FIX = 4 /* (1 << 2) */, - GNSS_SV_FLAGS_HAS_CARRIER_FREQUENCY = 8 /* (1 << 3) */, -}; - -enum { - GPS_GEOFENCE_ENTERED = 1 /* (1 << 0L) */, - GPS_GEOFENCE_EXITED = 2 /* (1 << 1L) */, - GPS_GEOFENCE_UNCERTAIN = 4 /* (1 << 2L) */, -}; - -enum { - GPS_GEOFENCE_UNAVAILABLE = 1 /* (1 << 0L) */, - GPS_GEOFENCE_AVAILABLE = 2 /* (1 << 1L) */, -}; - -enum { - GPS_GEOFENCE_OPERATION_SUCCESS = 0, - GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES = -100 /* (-100) */, - GPS_GEOFENCE_ERROR_ID_EXISTS = -101 /* (-101) */, - GPS_GEOFENCE_ERROR_ID_UNKNOWN = -102 /* (-102) */, - GPS_GEOFENCE_ERROR_INVALID_TRANSITION = -103 /* (-103) */, - GPS_GEOFENCE_ERROR_GENERIC = -149 /* (-149) */, -}; - -enum { - GPS_MEASUREMENT_SUCCESS = 0, - GPS_MEASUREMENT_ERROR_ALREADY_INIT = -100 /* (-100) */, - GPS_MEASUREMENT_ERROR_GENERIC = -101 /* (-101) */, -}; - -enum { - GNSS_CLOCK_HAS_LEAP_SECOND = 1 /* (1 << 0) */, - GNSS_CLOCK_HAS_TIME_UNCERTAINTY = 2 /* (1 << 1) */, - GNSS_CLOCK_HAS_FULL_BIAS = 4 /* (1 << 2) */, - GNSS_CLOCK_HAS_BIAS = 8 /* (1 << 3) */, - GNSS_CLOCK_HAS_BIAS_UNCERTAINTY = 16 /* (1 << 4) */, - GNSS_CLOCK_HAS_DRIFT = 32 /* (1 << 5) */, - GNSS_CLOCK_HAS_DRIFT_UNCERTAINTY = 64 /* (1 << 6) */, -}; - -enum { - GNSS_MEASUREMENT_HAS_SNR = 1u /* (1 << 0) */, - GNSS_MEASUREMENT_HAS_CARRIER_FREQUENCY = 512u /* (1 << 9) */, - GNSS_MEASUREMENT_HAS_CARRIER_CYCLES = 1024u /* (1 << 10) */, - GNSS_MEASUREMENT_HAS_CARRIER_PHASE = 2048u /* (1 << 11) */, - GNSS_MEASUREMENT_HAS_CARRIER_PHASE_UNCERTAINTY = 4096u /* (1 << 12) */, - GNSS_MEASUREMENT_HAS_AUTOMATIC_GAIN_CONTROL = 8192u /* (1 << 13) */, -}; - -enum { - GNSS_MULTIPATH_INDICATOR_UNKNOWN = 0, - GNSS_MULTIPATH_INDICATOR_PRESENT = 1, - GNSS_MULTIPATH_INDICATIOR_NOT_PRESENT = 2, -}; - -enum { - GNSS_MEASUREMENT_STATE_UNKNOWN = 0u, - GNSS_MEASUREMENT_STATE_CODE_LOCK = 1u /* (1 << 0) */, - GNSS_MEASUREMENT_STATE_BIT_SYNC = 2u /* (1 << 1) */, - GNSS_MEASUREMENT_STATE_SUBFRAME_SYNC = 4u /* (1 << 2) */, - GNSS_MEASUREMENT_STATE_TOW_DECODED = 8u /* (1 << 3) */, - GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS = 16u /* (1 << 4) */, - GNSS_MEASUREMENT_STATE_SYMBOL_SYNC = 32u /* (1 << 5) */, - GNSS_MEASUREMENT_STATE_GLO_STRING_SYNC = 64u /* (1 << 6) */, - GNSS_MEASUREMENT_STATE_GLO_TOD_DECODED = 128u /* (1 << 7) */, - GNSS_MEASUREMENT_STATE_BDS_D2_BIT_SYNC = 256u /* (1 << 8) */, - GNSS_MEASUREMENT_STATE_BDS_D2_SUBFRAME_SYNC = 512u /* (1 << 9) */, - GNSS_MEASUREMENT_STATE_GAL_E1BC_CODE_LOCK = 1024u /* (1 << 10) */, - GNSS_MEASUREMENT_STATE_GAL_E1C_2ND_CODE_LOCK = 2048u /* (1 << 11) */, - GNSS_MEASUREMENT_STATE_GAL_E1B_PAGE_SYNC = 4096u /* (1 << 12) */, - GNSS_MEASUREMENT_STATE_SBAS_SYNC = 8192u /* (1 << 13) */, - GNSS_MEASUREMENT_STATE_TOW_KNOWN = 16384u /* (1 << 14) */, - GNSS_MEASUREMENT_STATE_GLO_TOD_KNOWN = 32768u /* (1 << 15) */, -}; - -enum { - GNSS_ADR_STATE_UNKNOWN = 0, - GNSS_ADR_STATE_VALID = 1 /* (1 << 0) */, - GNSS_ADR_STATE_RESET = 2 /* (1 << 1) */, - GNSS_ADR_STATE_CYCLE_SLIP = 4 /* (1 << 2) */, -}; - -enum { - GPS_NAVIGATION_MESSAGE_SUCCESS = 0, - GPS_NAVIGATION_MESSAGE_ERROR_ALREADY_INIT = -100 /* (-100) */, - GPS_NAVIGATION_MESSAGE_ERROR_GENERIC = -101 /* (-101) */, -}; - -enum { - GNSS_NAVIGATION_MESSAGE_TYPE_UNKNOWN = 0, - GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L1CA = 257 /* 0x0101 */, - GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L2CNAV = 258 /* 0x0102 */, - GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L5CNAV = 259 /* 0x0103 */, - GNSS_NAVIGATION_MESSAGE_TYPE_GPS_CNAV2 = 260 /* 0x0104 */, - GNSS_NAVIGATION_MESSAGE_TYPE_GLO_L1CA = 769 /* 0x0301 */, - GNSS_NAVIGATION_MESSAGE_TYPE_BDS_D1 = 1281 /* 0x0501 */, - GNSS_NAVIGATION_MESSAGE_TYPE_BDS_D2 = 1282 /* 0x0502 */, - GNSS_NAVIGATION_MESSAGE_TYPE_GAL_I = 1537 /* 0x0601 */, - GNSS_NAVIGATION_MESSAGE_TYPE_GAL_F = 1538 /* 0x0602 */, -}; - -typedef enum { - NAV_MESSAGE_STATUS_PARITY_PASSED = 1 /* (1 << 0) */, - NAV_MESSAGE_STATUS_PARITY_REBUILT = 2 /* (1 << 1) */, - NAV_MESSAGE_STATUS_UNKNOWN = 0, -} navigation_message_status; - -enum { - GPS_NI_TYPE_VOICE = 1, - GPS_NI_TYPE_UMTS_SUPL = 2, - GPS_NI_TYPE_UMTS_CTRL_PLANE = 3, - GPS_NI_TYPE_EMERGENCY_SUPL = 4, -}; - -enum { - GPS_NI_NEED_NOTIFY = 1u /* 0x0001 */, - GPS_NI_NEED_VERIFY = 2u /* 0x0002 */, - GPS_NI_PRIVACY_OVERRIDE = 4u /* 0x0004 */, -}; - -enum { - GPS_NI_RESPONSE_ACCEPT = 1, - GPS_NI_RESPONSE_DENY = 2, - GPS_NI_RESPONSE_NORESP = 3, -}; - -enum { - GPS_ENC_NONE = 0, - GPS_ENC_SUPL_GSM_DEFAULT = 1, - GPS_ENC_SUPL_UTF8 = 2, - GPS_ENC_SUPL_UCS2 = 3, - GPS_ENC_UNKNOWN = -1 /* (-1) */, -}; - -#ifdef __cplusplus -} -#endif - -#endif // HIDL_GENERATED_ANDROID_HARDWARE_GNSS_V1_0_EXPORTED_CONSTANTS_H_ +../../include_all/hardware/gnss-base.h
\ No newline at end of file diff --git a/include/hardware/gps.h b/include/hardware/gps.h index 4e108b3f..19b8cd35 100644..120000 --- a/include/hardware/gps.h +++ b/include/hardware/gps.h @@ -1,2004 +1 @@ -/* - * Copyright (C) 2010 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_INCLUDE_HARDWARE_GPS_H -#define ANDROID_INCLUDE_HARDWARE_GPS_H - -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> -#include <pthread.h> -#include <sys/socket.h> -#include <stdbool.h> - -#include <hardware/hardware.h> - -#include "gnss-base.h" - -__BEGIN_DECLS - -/* - * Enums defined in HIDL in hardware/interfaces are auto-generated and present - * in gnss-base.h. - */ - -/* for compatibility */ - -/** Maximum number of SVs for gps_sv_status_callback(). */ -#define GNSS_MAX_SVS GNSS_MAX_SVS_COUNT -/** Maximum number of Measurements in gnss_measurement_callback(). */ -#define GNSS_MAX_MEASUREMENT GNSS_MAX_SVS_COUNT - -#define GPS_REQUEST_AGPS_DATA_CONN GNSS_REQUEST_AGNSS_DATA_CONN -#define GPS_RELEASE_AGPS_DATA_CONN GNSS_RELEASE_AGNSS_DATA_CONN -#define GPS_AGPS_DATA_CONNECTED GNSS_AGNSS_DATA_CONNECTED -#define GPS_AGPS_DATA_CONN_DONE GNSS_AGNSS_DATA_CONN_DONE -#define GPS_AGPS_DATA_CONN_FAILED GNSS_AGNSS_DATA_CONN_FAILED -#define AGPS_RIL_NETWORK_TYPE_MOBILE_MMS AGPS_RIL_NETWORK_TYPE_MMS -#define AGPS_RIL_NETWORK_TYPE_MOBILE_SUPL AGPS_RIL_NETWORK_TYPE_SUPL -#define AGPS_RIL_NETWORK_TTYPE_MOBILE_DUN AGPS_RIL_NETWORK_TYPE_DUN -#define AGPS_RIL_NETWORK_TTYPE_MOBILE_HIPRI AGPS_RIL_NETWORK_TYPE_HIPRI -#define AGPS_RIL_NETWORK_TTYPE_WIMAX AGPS_RIL_NETWORK_TYPE_WIMAX -#define GNSS_MULTIPATH_INDICATOR_NOT_PRESENT GNSS_MULTIPATH_INDICATIOR_NOT_PRESENT -#define AGPS_SETID_TYPE_MSISDN AGPS_SETID_TYPE_MSISDM -#define GPS_MEASUREMENT_OPERATION_SUCCESS GPS_MEASUREMENT_SUCCESS -#define GPS_NAVIGATION_MESSAGE_OPERATION_SUCCESS GPS_NAVIGATION_MESSAGE_SUCCESS -#define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L1CA GNSS_NAVIGATION_MESSAGE_TYPE_GNSS_L1CA -#define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L2CNAV GNSS_NAVIGATION_MESSAGE_TYPE_GNSS_L2CNAV -#define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L5CNAV GNSS_NAVIGATION_MESSAGE_TYPE_GNSS_L5CNAV -#define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_CNAV2 GNSS_NAVIGATION_MESSAGE_TYPE_GNSS_CNAV2 -#define GPS_LOCATION_HAS_ACCURACY GPS_LOCATION_HAS_HORIZONTAL_ACCURACY - -/** - * The id of this module - */ -#define GPS_HARDWARE_MODULE_ID "gps" - - -/** Milliseconds since January 1, 1970 */ -typedef int64_t GpsUtcTime; - -/** Maximum number of SVs for gps_sv_status_callback(). */ -#define GPS_MAX_SVS 32 - -/** Maximum number of Measurements in gps_measurement_callback(). */ -#define GPS_MAX_MEASUREMENT 32 - -/** Requested operational mode for GPS operation. */ -typedef uint32_t GpsPositionMode; - -/** Requested recurrence mode for GPS operation. */ -typedef uint32_t GpsPositionRecurrence; - -/** GPS status event values. */ -typedef uint16_t GpsStatusValue; - -/** Flags to indicate which values are valid in a GpsLocation. */ -typedef uint16_t GpsLocationFlags; - -/** - * Flags used to specify which aiding data to delete when calling - * delete_aiding_data(). - */ -typedef uint16_t GpsAidingData; - -/** AGPS type */ -typedef uint16_t AGpsType; - -typedef uint16_t AGpsSetIDType; - -typedef uint16_t ApnIpType; - -/** - * String length constants - */ -#define GPS_NI_SHORT_STRING_MAXLEN 256 -#define GPS_NI_LONG_STRING_MAXLEN 2048 - -/** - * GpsNiType constants - */ -typedef uint32_t GpsNiType; - -/** - * GpsNiNotifyFlags constants - */ -typedef uint32_t GpsNiNotifyFlags; - -/** - * GPS NI responses, used to define the response in - * NI structures - */ -typedef int GpsUserResponseType; - -/** - * NI data encoding scheme - */ -typedef int GpsNiEncodingType; - -/** AGPS status event values. */ -typedef uint16_t AGpsStatusValue; - -typedef uint16_t AGpsRefLocationType; - -/* Deprecated, to be removed in the next Android release. */ -#define AGPS_REG_LOCATION_TYPE_MAC 3 - -/* The following typedef together with its constants below are deprecated, and - * will be removed in the next release. */ -typedef uint16_t GpsClockFlags; -#define GPS_CLOCK_HAS_LEAP_SECOND (1<<0) -#define GPS_CLOCK_HAS_TIME_UNCERTAINTY (1<<1) -#define GPS_CLOCK_HAS_FULL_BIAS (1<<2) -#define GPS_CLOCK_HAS_BIAS (1<<3) -#define GPS_CLOCK_HAS_BIAS_UNCERTAINTY (1<<4) -#define GPS_CLOCK_HAS_DRIFT (1<<5) -#define GPS_CLOCK_HAS_DRIFT_UNCERTAINTY (1<<6) - -/** - * Flags to indicate what fields in GnssClock are valid. - */ -typedef uint16_t GnssClockFlags; - -/* The following typedef together with its constants below are deprecated, and - * will be removed in the next release. */ -typedef uint8_t GpsClockType; -#define GPS_CLOCK_TYPE_UNKNOWN 0 -#define GPS_CLOCK_TYPE_LOCAL_HW_TIME 1 -#define GPS_CLOCK_TYPE_GPS_TIME 2 - -/* The following typedef together with its constants below are deprecated, and - * will be removed in the next release. */ -typedef uint32_t GpsMeasurementFlags; -#define GPS_MEASUREMENT_HAS_SNR (1<<0) -#define GPS_MEASUREMENT_HAS_ELEVATION (1<<1) -#define GPS_MEASUREMENT_HAS_ELEVATION_UNCERTAINTY (1<<2) -#define GPS_MEASUREMENT_HAS_AZIMUTH (1<<3) -#define GPS_MEASUREMENT_HAS_AZIMUTH_UNCERTAINTY (1<<4) -#define GPS_MEASUREMENT_HAS_PSEUDORANGE (1<<5) -#define GPS_MEASUREMENT_HAS_PSEUDORANGE_UNCERTAINTY (1<<6) -#define GPS_MEASUREMENT_HAS_CODE_PHASE (1<<7) -#define GPS_MEASUREMENT_HAS_CODE_PHASE_UNCERTAINTY (1<<8) -#define GPS_MEASUREMENT_HAS_CARRIER_FREQUENCY (1<<9) -#define GPS_MEASUREMENT_HAS_CARRIER_CYCLES (1<<10) -#define GPS_MEASUREMENT_HAS_CARRIER_PHASE (1<<11) -#define GPS_MEASUREMENT_HAS_CARRIER_PHASE_UNCERTAINTY (1<<12) -#define GPS_MEASUREMENT_HAS_BIT_NUMBER (1<<13) -#define GPS_MEASUREMENT_HAS_TIME_FROM_LAST_BIT (1<<14) -#define GPS_MEASUREMENT_HAS_DOPPLER_SHIFT (1<<15) -#define GPS_MEASUREMENT_HAS_DOPPLER_SHIFT_UNCERTAINTY (1<<16) -#define GPS_MEASUREMENT_HAS_USED_IN_FIX (1<<17) -#define GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE (1<<18) - -/** - * Flags to indicate what fields in GnssMeasurement are valid. - */ -typedef uint32_t GnssMeasurementFlags; - -/* The following typedef together with its constants below are deprecated, and - * will be removed in the next release. */ -typedef uint8_t GpsLossOfLock; -#define GPS_LOSS_OF_LOCK_UNKNOWN 0 -#define GPS_LOSS_OF_LOCK_OK 1 -#define GPS_LOSS_OF_LOCK_CYCLE_SLIP 2 - -/* The following typedef together with its constants below are deprecated, and - * will be removed in the next release. Use GnssMultipathIndicator instead. - */ -typedef uint8_t GpsMultipathIndicator; -#define GPS_MULTIPATH_INDICATOR_UNKNOWN 0 -#define GPS_MULTIPATH_INDICATOR_DETECTED 1 -#define GPS_MULTIPATH_INDICATOR_NOT_USED 2 - -/** - * Enumeration of available values for the GNSS Measurement's multipath - * indicator. - */ -typedef uint8_t GnssMultipathIndicator; - -/* The following typedef together with its constants below are deprecated, and - * will be removed in the next release. */ -typedef uint16_t GpsMeasurementState; -#define GPS_MEASUREMENT_STATE_UNKNOWN 0 -#define GPS_MEASUREMENT_STATE_CODE_LOCK (1<<0) -#define GPS_MEASUREMENT_STATE_BIT_SYNC (1<<1) -#define GPS_MEASUREMENT_STATE_SUBFRAME_SYNC (1<<2) -#define GPS_MEASUREMENT_STATE_TOW_DECODED (1<<3) -#define GPS_MEASUREMENT_STATE_MSEC_AMBIGUOUS (1<<4) - -/** - * Flags indicating the GNSS measurement state. - * - * The expected behavior here is for GPS HAL to set all the flags that applies. - * For example, if the state for a satellite is only C/A code locked and bit - * synchronized, and there is still millisecond ambiguity, the state should be - * set as: - * - * GNSS_MEASUREMENT_STATE_CODE_LOCK | GNSS_MEASUREMENT_STATE_BIT_SYNC | - * GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS - * - * If GNSS is still searching for a satellite, the corresponding state should be - * set to GNSS_MEASUREMENT_STATE_UNKNOWN(0). - */ -typedef uint32_t GnssMeasurementState; - -/* The following typedef together with its constants below are deprecated, and - * will be removed in the next release. */ -typedef uint16_t GpsAccumulatedDeltaRangeState; -#define GPS_ADR_STATE_UNKNOWN 0 -#define GPS_ADR_STATE_VALID (1<<0) -#define GPS_ADR_STATE_RESET (1<<1) -#define GPS_ADR_STATE_CYCLE_SLIP (1<<2) - -/** - * Flags indicating the Accumulated Delta Range's states. - */ -typedef uint16_t GnssAccumulatedDeltaRangeState; - -/* The following typedef together with its constants below are deprecated, and - * will be removed in the next release. */ -typedef uint8_t GpsNavigationMessageType; -#define GPS_NAVIGATION_MESSAGE_TYPE_UNKNOWN 0 -#define GPS_NAVIGATION_MESSAGE_TYPE_L1CA 1 -#define GPS_NAVIGATION_MESSAGE_TYPE_L2CNAV 2 -#define GPS_NAVIGATION_MESSAGE_TYPE_L5CNAV 3 -#define GPS_NAVIGATION_MESSAGE_TYPE_CNAV2 4 - -/** - * Enumeration of available values to indicate the GNSS Navigation message - * types. - * - * For convenience, first byte is the GnssConstellationType on which that signal - * is typically transmitted - */ -typedef int16_t GnssNavigationMessageType; - -/** - * Status of Navigation Message - * When a message is received properly without any parity error in its navigation words, the - * status should be set to NAV_MESSAGE_STATUS_PARITY_PASSED. But if a message is received - * with words that failed parity check, but GPS is able to correct those words, the status - * should be set to NAV_MESSAGE_STATUS_PARITY_REBUILT. - * No need to send any navigation message that contains words with parity error and cannot be - * corrected. - */ -typedef uint16_t NavigationMessageStatus; - -/* This constant is deprecated, and will be removed in the next release. */ -#define NAV_MESSAGE_STATUS_UNKONW 0 - -/** - * Flags that indicate information about the satellite - */ -typedef uint8_t GnssSvFlags; - -/** - * Constellation type of GnssSvInfo - */ -typedef uint8_t GnssConstellationType; - -/** - * Name for the GPS XTRA interface. - */ -#define GPS_XTRA_INTERFACE "gps-xtra" - -/** - * Name for the GPS DEBUG interface. - */ -#define GPS_DEBUG_INTERFACE "gps-debug" - -/** - * Name for the AGPS interface. - */ -#define AGPS_INTERFACE "agps" - -/** - * Name of the Supl Certificate interface. - */ -#define SUPL_CERTIFICATE_INTERFACE "supl-certificate" - -/** - * Name for NI interface - */ -#define GPS_NI_INTERFACE "gps-ni" - -/** - * Name for the AGPS-RIL interface. - */ -#define AGPS_RIL_INTERFACE "agps_ril" - -/** - * Name for the GPS_Geofencing interface. - */ -#define GPS_GEOFENCING_INTERFACE "gps_geofencing" - -/** - * Name of the GPS Measurements interface. - */ -#define GPS_MEASUREMENT_INTERFACE "gps_measurement" - -/** - * Name of the GPS navigation message interface. - */ -#define GPS_NAVIGATION_MESSAGE_INTERFACE "gps_navigation_message" - -/** - * Name of the GNSS/GPS configuration interface. - */ -#define GNSS_CONFIGURATION_INTERFACE "gnss_configuration" - -/** Represents a location. */ -typedef struct { - /** set to sizeof(GpsLocation) */ - size_t size; - /** Contains GpsLocationFlags bits. */ - uint16_t flags; - /** Represents latitude in degrees. */ - double latitude; - /** Represents longitude in degrees. */ - double longitude; - /** - * Represents altitude in meters above the WGS 84 reference ellipsoid. - */ - double altitude; - /** Represents speed in meters per second. */ - float speed; - /** Represents heading in degrees. */ - float bearing; - /** Represents expected accuracy in meters. */ - float accuracy; - /** Timestamp for the location fix. */ - GpsUtcTime timestamp; -} GpsLocation; - -/** Represents the status. */ -typedef struct { - /** set to sizeof(GpsStatus) */ - size_t size; - GpsStatusValue status; -} GpsStatus; - -/** - * Legacy struct to represents SV information. - * Deprecated, to be removed in the next Android release. - * Use GnssSvInfo instead. - */ -typedef struct { - /** set to sizeof(GpsSvInfo) */ - size_t size; - /** Pseudo-random number for the SV. */ - int prn; - /** Signal to noise ratio. */ - float snr; - /** Elevation of SV in degrees. */ - float elevation; - /** Azimuth of SV in degrees. */ - float azimuth; -} GpsSvInfo; - -typedef struct { - /** set to sizeof(GnssSvInfo) */ - size_t size; - - /** - * Pseudo-random number for the SV, or FCN/OSN number for Glonass. The - * distinction is made by looking at constellation field. Values should be - * in the range of: - * - * - GPS: 1-32 - * - SBAS: 120-151, 183-192 - * - GLONASS: 1-24, the orbital slot number (OSN), if known. Or, if not: - * 93-106, the frequency channel number (FCN) (-7 to +6) offset by + 100 - * i.e. report an FCN of -7 as 93, FCN of 0 as 100, and FCN of +6 as 106. - * - QZSS: 193-200 - * - Galileo: 1-36 - * - Beidou: 1-37 - */ - int16_t svid; - - /** - * Defines the constellation of the given SV. Value should be one of those - * GNSS_CONSTELLATION_* constants - */ - GnssConstellationType constellation; - - /** - * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. - * It contains the measured C/N0 value for the signal at the antenna port. - * - * This is a mandatory value. - */ - float c_n0_dbhz; - - /** Elevation of SV in degrees. */ - float elevation; - - /** Azimuth of SV in degrees. */ - float azimuth; - - /** - * Contains additional data about the given SV. Value should be one of those - * GNSS_SV_FLAGS_* constants - */ - GnssSvFlags flags; - -} GnssSvInfo; - -/** - * Legacy struct to represents SV status. - * Deprecated, to be removed in the next Android release. - * Use GnssSvStatus instead. - */ -typedef struct { - /** set to sizeof(GpsSvStatus) */ - size_t size; - int num_svs; - GpsSvInfo sv_list[GPS_MAX_SVS]; - uint32_t ephemeris_mask; - uint32_t almanac_mask; - uint32_t used_in_fix_mask; -} GpsSvStatus; - -/** - * Represents SV status. - */ -typedef struct { - /** set to sizeof(GnssSvStatus) */ - size_t size; - - /** Number of GPS SVs currently visible, refers to the SVs stored in sv_list */ - int num_svs; - /** - * Pointer to an array of SVs information for all GNSS constellations, - * except GPS, which is reported using sv_list - */ - GnssSvInfo gnss_sv_list[GNSS_MAX_SVS]; - -} GnssSvStatus; - -/* CellID for 2G, 3G and LTE, used in AGPS. */ -typedef struct { - AGpsRefLocationType type; - /** Mobile Country Code. */ - uint16_t mcc; - /** Mobile Network Code .*/ - uint16_t mnc; - /** Location Area Code in 2G, 3G and LTE. In 3G lac is discarded. In LTE, - * lac is populated with tac, to ensure that we don't break old clients that - * might rely in the old (wrong) behavior. - */ - uint16_t lac; - /** Cell id in 2G. Utran Cell id in 3G. Cell Global Id EUTRA in LTE. */ - uint32_t cid; - /** Tracking Area Code in LTE. */ - uint16_t tac; - /** Physical Cell id in LTE (not used in 2G and 3G) */ - uint16_t pcid; -} AGpsRefLocationCellID; - -typedef struct { - uint8_t mac[6]; -} AGpsRefLocationMac; - -/** Represents ref locations */ -typedef struct { - AGpsRefLocationType type; - union { - AGpsRefLocationCellID cellID; - AGpsRefLocationMac mac; - } u; -} AGpsRefLocation; - -/** - * Callback with location information. Can only be called from a thread created - * by create_thread_cb. - */ -typedef void (* gps_location_callback)(GpsLocation* location); - -/** - * Callback with status information. Can only be called from a thread created by - * create_thread_cb. - */ -typedef void (* gps_status_callback)(GpsStatus* status); - -/** - * Legacy callback with SV status information. - * Can only be called from a thread created by create_thread_cb. - * - * This callback is deprecated, and will be removed in the next release. Use - * gnss_sv_status_callback() instead. - */ -typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info); - -/** - * Callback with SV status information. - * Can only be called from a thread created by create_thread_cb. - */ -typedef void (* gnss_sv_status_callback)(GnssSvStatus* sv_info); - -/** - * Callback for reporting NMEA sentences. Can only be called from a thread - * created by create_thread_cb. - */ -typedef void (* gps_nmea_callback)(GpsUtcTime timestamp, const char* nmea, int length); - -/** - * Callback to inform framework of the GPS engine's capabilities. Capability - * parameter is a bit field of GPS_CAPABILITY_* flags. - */ -typedef void (* gps_set_capabilities)(uint32_t capabilities); - -/** - * Callback utility for acquiring the GPS wakelock. This can be used to prevent - * the CPU from suspending while handling GPS events. - */ -typedef void (* gps_acquire_wakelock)(); - -/** Callback utility for releasing the GPS wakelock. */ -typedef void (* gps_release_wakelock)(); - -/** Callback for requesting NTP time */ -typedef void (* gps_request_utc_time)(); - -/** - * Callback for creating a thread that can call into the Java framework code. - * This must be used to create any threads that report events up to the - * framework. - */ -typedef pthread_t (* gps_create_thread)(const char* name, void (*start)(void *), void* arg); - -/** - * Provides information about how new the underlying GPS/GNSS hardware and - * software is. - * - * This information will be available for Android Test Applications. If a GPS - * HAL does not provide this information, it will be considered "2015 or - * earlier". - * - * If a GPS HAL does provide this information, then newer years will need to - * meet newer CTS standards. E.g. if the date are 2016 or above, then N+ level - * GpsMeasurement support will be verified. - */ -typedef struct { - /** Set to sizeof(GnssSystemInfo) */ - size_t size; - /* year in which the last update was made to the underlying hardware/firmware - * used to capture GNSS signals, e.g. 2016 */ - uint16_t year_of_hw; -} GnssSystemInfo; - -/** - * Callback to inform framework of the engine's hardware version information. - */ -typedef void (*gnss_set_system_info)(const GnssSystemInfo* info); - -/** New GPS callback structure. */ -typedef struct { - /** set to sizeof(GpsCallbacks) */ - size_t size; - gps_location_callback location_cb; - gps_status_callback status_cb; - gps_sv_status_callback sv_status_cb; - gps_nmea_callback nmea_cb; - gps_set_capabilities set_capabilities_cb; - gps_acquire_wakelock acquire_wakelock_cb; - gps_release_wakelock release_wakelock_cb; - gps_create_thread create_thread_cb; - gps_request_utc_time request_utc_time_cb; - - gnss_set_system_info set_system_info_cb; - gnss_sv_status_callback gnss_sv_status_cb; -} GpsCallbacks; - -/** Represents the standard GPS interface. */ -typedef struct { - /** set to sizeof(GpsInterface) */ - size_t size; - /** - * Opens the interface and provides the callback routines - * to the implementation of this interface. - */ - int (*init)( GpsCallbacks* callbacks ); - - /** Starts navigating. */ - int (*start)( void ); - - /** Stops navigating. */ - int (*stop)( void ); - - /** Closes the interface. */ - void (*cleanup)( void ); - - /** Injects the current time. */ - int (*inject_time)(GpsUtcTime time, int64_t timeReference, - int uncertainty); - - /** - * Injects current location from another location provider (typically cell - * ID). Latitude and longitude are measured in degrees expected accuracy is - * measured in meters - */ - int (*inject_location)(double latitude, double longitude, float accuracy); - - /** - * Specifies that the next call to start will not use the - * information defined in the flags. GPS_DELETE_ALL is passed for - * a cold start. - */ - void (*delete_aiding_data)(GpsAidingData flags); - - /** - * min_interval represents the time between fixes in milliseconds. - * preferred_accuracy represents the requested fix accuracy in meters. - * preferred_time represents the requested time to first fix in milliseconds. - * - * 'mode' parameter should be one of GPS_POSITION_MODE_MS_BASED - * or GPS_POSITION_MODE_STANDALONE. - * It is allowed by the platform (and it is recommended) to fallback to - * GPS_POSITION_MODE_MS_BASED if GPS_POSITION_MODE_MS_ASSISTED is passed in, and - * GPS_POSITION_MODE_MS_BASED is supported. - */ - int (*set_position_mode)(GpsPositionMode mode, GpsPositionRecurrence recurrence, - uint32_t min_interval, uint32_t preferred_accuracy, uint32_t preferred_time); - - /** Get a pointer to extension information. */ - const void* (*get_extension)(const char* name); -} GpsInterface; - -/** - * Callback to request the client to download XTRA data. The client should - * download XTRA data and inject it by calling inject_xtra_data(). Can only be - * called from a thread created by create_thread_cb. - */ -typedef void (* gps_xtra_download_request)(); - -/** Callback structure for the XTRA interface. */ -typedef struct { - gps_xtra_download_request download_request_cb; - gps_create_thread create_thread_cb; -} GpsXtraCallbacks; - -/** Extended interface for XTRA support. */ -typedef struct { - /** set to sizeof(GpsXtraInterface) */ - size_t size; - /** - * Opens the XTRA interface and provides the callback routines - * to the implementation of this interface. - */ - int (*init)( GpsXtraCallbacks* callbacks ); - /** Injects XTRA data into the GPS. */ - int (*inject_xtra_data)( char* data, int length ); -} GpsXtraInterface; - -/** Extended interface for DEBUG support. */ -typedef struct { - /** set to sizeof(GpsDebugInterface) */ - size_t size; - - /** - * This function should return any information that the native - * implementation wishes to include in a bugreport. - */ - size_t (*get_internal_state)(char* buffer, size_t bufferSize); -} GpsDebugInterface; - -/* - * Represents the status of AGPS augmented to support IPv4 and IPv6. - */ -typedef struct { - /** set to sizeof(AGpsStatus) */ - size_t size; - - AGpsType type; - AGpsStatusValue status; - - /** - * Must be set to a valid IPv4 address if the field 'addr' contains an IPv4 - * address, or set to INADDR_NONE otherwise. - */ - uint32_t ipaddr; - - /** - * Must contain the IPv4 (AF_INET) or IPv6 (AF_INET6) address to report. - * Any other value of addr.ss_family will be rejected. - */ - struct sockaddr_storage addr; -} AGpsStatus; - -/** - * Callback with AGPS status information. Can only be called from a thread - * created by create_thread_cb. - */ -typedef void (* agps_status_callback)(AGpsStatus* status); - -/** Callback structure for the AGPS interface. */ -typedef struct { - agps_status_callback status_cb; - gps_create_thread create_thread_cb; -} AGpsCallbacks; - -/** - * Extended interface for AGPS support, it is augmented to enable to pass - * extra APN data. - */ -typedef struct { - /** set to sizeof(AGpsInterface) */ - size_t size; - - /** - * Opens the AGPS interface and provides the callback routines to the - * implementation of this interface. - */ - void (*init)(AGpsCallbacks* callbacks); - /** - * Deprecated. - * If the HAL supports AGpsInterface_v2 this API will not be used, see - * data_conn_open_with_apn_ip_type for more information. - */ - int (*data_conn_open)(const char* apn); - /** - * Notifies that the AGPS data connection has been closed. - */ - int (*data_conn_closed)(); - /** - * Notifies that a data connection is not available for AGPS. - */ - int (*data_conn_failed)(); - /** - * Sets the hostname and port for the AGPS server. - */ - int (*set_server)(AGpsType type, const char* hostname, int port); - - /** - * Notifies that a data connection is available and sets the name of the - * APN, and its IP type, to be used for SUPL connections. - */ - int (*data_conn_open_with_apn_ip_type)( - const char* apn, - ApnIpType apnIpType); -} AGpsInterface; - -/** Error codes associated with certificate operations */ -#define AGPS_CERTIFICATE_OPERATION_SUCCESS 0 -#define AGPS_CERTIFICATE_ERROR_GENERIC -100 -#define AGPS_CERTIFICATE_ERROR_TOO_MANY_CERTIFICATES -101 - -/** A data structure that represents an X.509 certificate using DER encoding */ -typedef struct { - size_t length; - u_char* data; -} DerEncodedCertificate; - -/** - * A type definition for SHA1 Fingerprints used to identify X.509 Certificates - * The Fingerprint is a digest of the DER Certificate that uniquely identifies it. - */ -typedef struct { - u_char data[20]; -} Sha1CertificateFingerprint; - -/** AGPS Interface to handle SUPL certificate operations */ -typedef struct { - /** set to sizeof(SuplCertificateInterface) */ - size_t size; - - /** - * Installs a set of Certificates used for SUPL connections to the AGPS server. - * If needed the HAL should find out internally any certificates that need to be removed to - * accommodate the certificates to install. - * The certificates installed represent a full set of valid certificates needed to connect to - * AGPS SUPL servers. - * The list of certificates is required, and all must be available at the same time, when trying - * to establish a connection with the AGPS Server. - * - * Parameters: - * certificates - A pointer to an array of DER encoded certificates that are need to be - * installed in the HAL. - * length - The number of certificates to install. - * Returns: - * AGPS_CERTIFICATE_OPERATION_SUCCESS if the operation is completed successfully - * AGPS_CERTIFICATE_ERROR_TOO_MANY_CERTIFICATES if the HAL cannot store the number of - * certificates attempted to be installed, the state of the certificates stored should - * remain the same as before on this error case. - * - * IMPORTANT: - * If needed the HAL should find out internally the set of certificates that need to be - * removed to accommodate the certificates to install. - */ - int (*install_certificates) ( const DerEncodedCertificate* certificates, size_t length ); - - /** - * Notifies the HAL that a list of certificates used for SUPL connections are revoked. It is - * expected that the given set of certificates is removed from the internal store of the HAL. - * - * Parameters: - * fingerprints - A pointer to an array of SHA1 Fingerprints to identify the set of - * certificates to revoke. - * length - The number of fingerprints provided. - * Returns: - * AGPS_CERTIFICATE_OPERATION_SUCCESS if the operation is completed successfully. - * - * IMPORTANT: - * If any of the certificates provided (through its fingerprint) is not known by the HAL, - * it should be ignored and continue revoking/deleting the rest of them. - */ - int (*revoke_certificates) ( const Sha1CertificateFingerprint* fingerprints, size_t length ); -} SuplCertificateInterface; - -/** Represents an NI request */ -typedef struct { - /** set to sizeof(GpsNiNotification) */ - size_t size; - - /** - * An ID generated by HAL to associate NI notifications and UI - * responses - */ - int notification_id; - - /** - * An NI type used to distinguish different categories of NI - * events, such as GPS_NI_TYPE_VOICE, GPS_NI_TYPE_UMTS_SUPL, ... - */ - GpsNiType ni_type; - - /** - * Notification/verification options, combinations of GpsNiNotifyFlags constants - */ - GpsNiNotifyFlags notify_flags; - - /** - * Timeout period to wait for user response. - * Set to 0 for no time out limit. - */ - int timeout; - - /** - * Default response when time out. - */ - GpsUserResponseType default_response; - - /** - * Requestor ID - */ - char requestor_id[GPS_NI_SHORT_STRING_MAXLEN]; - - /** - * Notification message. It can also be used to store client_id in some cases - */ - char text[GPS_NI_LONG_STRING_MAXLEN]; - - /** - * Client name decoding scheme - */ - GpsNiEncodingType requestor_id_encoding; - - /** - * Client name decoding scheme - */ - GpsNiEncodingType text_encoding; - - /** - * A pointer to extra data. Format: - * key_1 = value_1 - * key_2 = value_2 - */ - char extras[GPS_NI_LONG_STRING_MAXLEN]; - -} GpsNiNotification; - -/** - * Callback with NI notification. Can only be called from a thread created by - * create_thread_cb. - */ -typedef void (*gps_ni_notify_callback)(GpsNiNotification *notification); - -/** GPS NI callback structure. */ -typedef struct -{ - /** - * Sends the notification request from HAL to GPSLocationProvider. - */ - gps_ni_notify_callback notify_cb; - gps_create_thread create_thread_cb; -} GpsNiCallbacks; - -/** - * Extended interface for Network-initiated (NI) support. - */ -typedef struct -{ - /** set to sizeof(GpsNiInterface) */ - size_t size; - - /** Registers the callbacks for HAL to use. */ - void (*init) (GpsNiCallbacks *callbacks); - - /** Sends a response to HAL. */ - void (*respond) (int notif_id, GpsUserResponseType user_response); -} GpsNiInterface; - -struct gps_device_t { - struct hw_device_t common; - - /** - * Set the provided lights to the provided values. - * - * Returns: 0 on succes, error code on failure. - */ - const GpsInterface* (*get_gps_interface)(struct gps_device_t* dev); -}; - -#define AGPS_RIL_REQUEST_REFLOC_CELLID (1<<0L) -#define AGPS_RIL_REQUEST_REFLOC_MAC (1<<1L) - -typedef void (*agps_ril_request_set_id)(uint32_t flags); -typedef void (*agps_ril_request_ref_loc)(uint32_t flags); - -typedef struct { - agps_ril_request_set_id request_setid; - agps_ril_request_ref_loc request_refloc; - gps_create_thread create_thread_cb; -} AGpsRilCallbacks; - -/** Extended interface for AGPS_RIL support. */ -typedef struct { - /** set to sizeof(AGpsRilInterface) */ - size_t size; - /** - * Opens the AGPS interface and provides the callback routines - * to the implementation of this interface. - */ - void (*init)( AGpsRilCallbacks* callbacks ); - - /** - * Sets the reference location. - */ - void (*set_ref_location) (const AGpsRefLocation *agps_reflocation, size_t sz_struct); - /** - * Sets the set ID. - */ - void (*set_set_id) (AGpsSetIDType type, const char* setid); - - /** - * Send network initiated message. - */ - void (*ni_message) (uint8_t *msg, size_t len); - - /** - * Notify GPS of network status changes. - * These parameters match values in the android.net.NetworkInfo class. - */ - void (*update_network_state) (int connected, int type, int roaming, const char* extra_info); - - /** - * Notify GPS of network status changes. - * These parameters match values in the android.net.NetworkInfo class. - */ - void (*update_network_availability) (int avaiable, const char* apn); -} AGpsRilInterface; - -/** - * GPS Geofence. - * There are 3 states associated with a Geofence: Inside, Outside, Unknown. - * There are 3 transitions: ENTERED, EXITED, UNCERTAIN. - * - * An example state diagram with confidence level: 95% and Unknown time limit - * set as 30 secs is shown below. (confidence level and Unknown time limit are - * explained latter) - * ____________________________ - * | Unknown (30 secs) | - * """""""""""""""""""""""""""" - * ^ | | ^ - * UNCERTAIN| |ENTERED EXITED| |UNCERTAIN - * | v v | - * ________ EXITED _________ - * | Inside | -----------> | Outside | - * | | <----------- | | - * """""""" ENTERED """"""""" - * - * Inside state: We are 95% confident that the user is inside the geofence. - * Outside state: We are 95% confident that the user is outside the geofence - * Unknown state: Rest of the time. - * - * The Unknown state is better explained with an example: - * - * __________ - * | c| - * | ___ | _______ - * | |a| | | b | - * | """ | """"""" - * | | - * """""""""" - * In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy - * circle reported by the GPS subsystem. Now with regard to "b", the system is - * confident that the user is outside. But with regard to "a" is not confident - * whether it is inside or outside the geofence. If the accuracy remains the - * same for a sufficient period of time, the UNCERTAIN transition would be - * triggered with the state set to Unknown. If the accuracy improves later, an - * appropriate transition should be triggered. This "sufficient period of time" - * is defined by the parameter in the add_geofence_area API. - * In other words, Unknown state can be interpreted as a state in which the - * GPS subsystem isn't confident enough that the user is either inside or - * outside the Geofence. It moves to Unknown state only after the expiry of the - * timeout. - * - * The geofence callback needs to be triggered for the ENTERED and EXITED - * transitions, when the GPS system is confident that the user has entered - * (Inside state) or exited (Outside state) the Geofence. An implementation - * which uses a value of 95% as the confidence is recommended. The callback - * should be triggered only for the transitions requested by the - * add_geofence_area call. - * - * Even though the diagram and explanation talks about states and transitions, - * the callee is only interested in the transistions. The states are mentioned - * here for illustrative purposes. - * - * Startup Scenario: When the device boots up, if an application adds geofences, - * and then we get an accurate GPS location fix, it needs to trigger the - * appropriate (ENTERED or EXITED) transition for every Geofence it knows about. - * By default, all the Geofences will be in the Unknown state. - * - * When the GPS system is unavailable, gps_geofence_status_callback should be - * called to inform the upper layers of the same. Similarly, when it becomes - * available the callback should be called. This is a global state while the - * UNKNOWN transition described above is per geofence. - * - * An important aspect to note is that users of this API (framework), will use - * other subsystems like wifi, sensors, cell to handle Unknown case and - * hopefully provide a definitive state transition to the third party - * application. GPS Geofence will just be a signal indicating what the GPS - * subsystem knows about the Geofence. - * - */ - -/** - * The callback associated with the geofence. - * Parameters: - * geofence_id - The id associated with the add_geofence_area. - * location - The current GPS location. - * transition - Can be one of GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED, - * GPS_GEOFENCE_UNCERTAIN. - * timestamp - Timestamp when the transition was detected. - * - * The callback should only be called when the caller is interested in that - * particular transition. For instance, if the caller is interested only in - * ENTERED transition, then the callback should NOT be called with the EXITED - * transition. - * - * IMPORTANT: If a transition is triggered resulting in this callback, the GPS - * subsystem will wake up the application processor, if its in suspend state. - */ -typedef void (*gps_geofence_transition_callback) (int32_t geofence_id, GpsLocation* location, - int32_t transition, GpsUtcTime timestamp); - -/** - * The callback associated with the availability of the GPS system for geofencing - * monitoring. If the GPS system determines that it cannot monitor geofences - * because of lack of reliability or unavailability of the GPS signals, it will - * call this callback with GPS_GEOFENCE_UNAVAILABLE parameter. - * - * Parameters: - * status - GPS_GEOFENCE_UNAVAILABLE or GPS_GEOFENCE_AVAILABLE. - * last_location - Last known location. - */ -typedef void (*gps_geofence_status_callback) (int32_t status, GpsLocation* last_location); - -/** - * The callback associated with the add_geofence call. - * - * Parameter: - * geofence_id - Id of the geofence. - * status - GPS_GEOFENCE_OPERATION_SUCCESS - * GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES - geofence limit has been reached. - * GPS_GEOFENCE_ERROR_ID_EXISTS - geofence with id already exists - * GPS_GEOFENCE_ERROR_INVALID_TRANSITION - the monitorTransition contains an - * invalid transition - * GPS_GEOFENCE_ERROR_GENERIC - for other errors. - */ -typedef void (*gps_geofence_add_callback) (int32_t geofence_id, int32_t status); - -/** - * The callback associated with the remove_geofence call. - * - * Parameter: - * geofence_id - Id of the geofence. - * status - GPS_GEOFENCE_OPERATION_SUCCESS - * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id - * GPS_GEOFENCE_ERROR_GENERIC for others. - */ -typedef void (*gps_geofence_remove_callback) (int32_t geofence_id, int32_t status); - - -/** - * The callback associated with the pause_geofence call. - * - * Parameter: - * geofence_id - Id of the geofence. - * status - GPS_GEOFENCE_OPERATION_SUCCESS - * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id - * GPS_GEOFENCE_ERROR_INVALID_TRANSITION - - * when monitor_transitions is invalid - * GPS_GEOFENCE_ERROR_GENERIC for others. - */ -typedef void (*gps_geofence_pause_callback) (int32_t geofence_id, int32_t status); - -/** - * The callback associated with the resume_geofence call. - * - * Parameter: - * geofence_id - Id of the geofence. - * status - GPS_GEOFENCE_OPERATION_SUCCESS - * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id - * GPS_GEOFENCE_ERROR_GENERIC for others. - */ -typedef void (*gps_geofence_resume_callback) (int32_t geofence_id, int32_t status); - -typedef struct { - gps_geofence_transition_callback geofence_transition_callback; - gps_geofence_status_callback geofence_status_callback; - gps_geofence_add_callback geofence_add_callback; - gps_geofence_remove_callback geofence_remove_callback; - gps_geofence_pause_callback geofence_pause_callback; - gps_geofence_resume_callback geofence_resume_callback; - gps_create_thread create_thread_cb; -} GpsGeofenceCallbacks; - -/** Extended interface for GPS_Geofencing support */ -typedef struct { - /** set to sizeof(GpsGeofencingInterface) */ - size_t size; - - /** - * Opens the geofence interface and provides the callback routines - * to the implementation of this interface. - */ - void (*init)( GpsGeofenceCallbacks* callbacks ); - - /** - * Add a geofence area. This api currently supports circular geofences. - * Parameters: - * geofence_id - The id for the geofence. If a geofence with this id - * already exists, an error value (GPS_GEOFENCE_ERROR_ID_EXISTS) - * should be returned. - * latitude, longtitude, radius_meters - The lat, long and radius - * (in meters) for the geofence - * last_transition - The current state of the geofence. For example, if - * the system already knows that the user is inside the geofence, - * this will be set to GPS_GEOFENCE_ENTERED. In most cases, it - * will be GPS_GEOFENCE_UNCERTAIN. - * monitor_transition - Which transitions to monitor. Bitwise OR of - * GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and - * GPS_GEOFENCE_UNCERTAIN. - * notification_responsiveness_ms - Defines the best-effort description - * of how soon should the callback be called when the transition - * associated with the Geofence is triggered. For instance, if set - * to 1000 millseconds with GPS_GEOFENCE_ENTERED, the callback - * should be called 1000 milliseconds within entering the geofence. - * This parameter is defined in milliseconds. - * NOTE: This is not to be confused with the rate that the GPS is - * polled at. It is acceptable to dynamically vary the rate of - * sampling the GPS for power-saving reasons; thus the rate of - * sampling may be faster or slower than this. - * unknown_timer_ms - The time limit after which the UNCERTAIN transition - * should be triggered. This parameter is defined in milliseconds. - * See above for a detailed explanation. - */ - void (*add_geofence_area) (int32_t geofence_id, double latitude, double longitude, - double radius_meters, int last_transition, int monitor_transitions, - int notification_responsiveness_ms, int unknown_timer_ms); - - /** - * Pause monitoring a particular geofence. - * Parameters: - * geofence_id - The id for the geofence. - */ - void (*pause_geofence) (int32_t geofence_id); - - /** - * Resume monitoring a particular geofence. - * Parameters: - * geofence_id - The id for the geofence. - * monitor_transitions - Which transitions to monitor. Bitwise OR of - * GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and - * GPS_GEOFENCE_UNCERTAIN. - * This supersedes the value associated provided in the - * add_geofence_area call. - */ - void (*resume_geofence) (int32_t geofence_id, int monitor_transitions); - - /** - * Remove a geofence area. After the function returns, no notifications - * should be sent. - * Parameter: - * geofence_id - The id for the geofence. - */ - void (*remove_geofence_area) (int32_t geofence_id); -} GpsGeofencingInterface; - -/** - * Legacy struct to represent an estimate of the GPS clock time. - * Deprecated, to be removed in the next Android release. - * Use GnssClock instead. - */ -typedef struct { - /** set to sizeof(GpsClock) */ - size_t size; - GpsClockFlags flags; - int16_t leap_second; - GpsClockType type; - int64_t time_ns; - double time_uncertainty_ns; - int64_t full_bias_ns; - double bias_ns; - double bias_uncertainty_ns; - double drift_nsps; - double drift_uncertainty_nsps; -} GpsClock; - -/** - * Represents an estimate of the GPS clock time. - */ -typedef struct { - /** set to sizeof(GnssClock) */ - size_t size; - - /** - * A set of flags indicating the validity of the fields in this data - * structure. - */ - GnssClockFlags flags; - - /** - * Leap second data. - * The sign of the value is defined by the following equation: - * utc_time_ns = time_ns - (full_bias_ns + bias_ns) - leap_second * - * 1,000,000,000 - * - * If the data is available 'flags' must contain GNSS_CLOCK_HAS_LEAP_SECOND. - */ - int16_t leap_second; - - /** - * The GNSS receiver internal clock value. This is the local hardware clock - * value. - * - * For local hardware clock, this value is expected to be monotonically - * increasing while the hardware clock remains power on. (For the case of a - * HW clock that is not continuously on, see the - * hw_clock_discontinuity_count field). The receiver's estimate of GPS time - * can be derived by substracting the sum of full_bias_ns and bias_ns (when - * available) from this value. - * - * This GPS time is expected to be the best estimate of current GPS time - * that GNSS receiver can achieve. - * - * Sub-nanosecond accuracy can be provided by means of the 'bias_ns' field. - * The value contains the 'time uncertainty' in it. - * - * This field is mandatory. - */ - int64_t time_ns; - - /** - * 1-Sigma uncertainty associated with the clock's time in nanoseconds. - * The uncertainty is represented as an absolute (single sided) value. - * - * If the data is available, 'flags' must contain - * GNSS_CLOCK_HAS_TIME_UNCERTAINTY. This value is effectively zero (it is - * the reference local clock, by which all other times and time - * uncertainties are measured.) (And thus this field can be not provided, - * per GNSS_CLOCK_HAS_TIME_UNCERTAINTY flag, or provided & set to 0.) - */ - double time_uncertainty_ns; - - /** - * The difference between hardware clock ('time' field) inside GPS receiver - * and the true GPS time since 0000Z, January 6, 1980, in nanoseconds. - * - * The sign of the value is defined by the following equation: - * local estimate of GPS time = time_ns - (full_bias_ns + bias_ns) - * - * This value is mandatory if the receiver has estimated GPS time. If the - * computed time is for a non-GPS constellation, the time offset of that - * constellation to GPS has to be applied to fill this value. The error - * estimate for the sum of this and the bias_ns is the bias_uncertainty_ns, - * and the caller is responsible for using this uncertainty (it can be very - * large before the GPS time has been solved for.) If the data is available - * 'flags' must contain GNSS_CLOCK_HAS_FULL_BIAS. - */ - int64_t full_bias_ns; - - /** - * Sub-nanosecond bias. - * The error estimate for the sum of this and the full_bias_ns is the - * bias_uncertainty_ns - * - * If the data is available 'flags' must contain GNSS_CLOCK_HAS_BIAS. If GPS - * has computed a position fix. This value is mandatory if the receiver has - * estimated GPS time. - */ - double bias_ns; - - /** - * 1-Sigma uncertainty associated with the local estimate of GPS time (clock - * bias) in nanoseconds. The uncertainty is represented as an absolute - * (single sided) value. - * - * If the data is available 'flags' must contain - * GNSS_CLOCK_HAS_BIAS_UNCERTAINTY. This value is mandatory if the receiver - * has estimated GPS time. - */ - double bias_uncertainty_ns; - - /** - * The clock's drift in nanoseconds (per second). - * - * A positive value means that the frequency is higher than the nominal - * frequency, and that the (full_bias_ns + bias_ns) is growing more positive - * over time. - * - * The value contains the 'drift uncertainty' in it. - * If the data is available 'flags' must contain GNSS_CLOCK_HAS_DRIFT. - * - * This value is mandatory if the receiver has estimated GNSS time - */ - double drift_nsps; - - /** - * 1-Sigma uncertainty associated with the clock's drift in nanoseconds (per second). - * The uncertainty is represented as an absolute (single sided) value. - * - * If the data is available 'flags' must contain - * GNSS_CLOCK_HAS_DRIFT_UNCERTAINTY. If GPS has computed a position fix this - * field is mandatory and must be populated. - */ - double drift_uncertainty_nsps; - - /** - * When there are any discontinuities in the HW clock, this field is - * mandatory. - * - * A "discontinuity" is meant to cover the case of a switch from one source - * of clock to another. A single free-running crystal oscillator (XO) - * should generally not have any discontinuities, and this can be set and - * left at 0. - * - * If, however, the time_ns value (HW clock) is derived from a composite of - * sources, that is not as smooth as a typical XO, or is otherwise stopped & - * restarted, then this value shall be incremented each time a discontinuity - * occurs. (E.g. this value may start at zero at device boot-up and - * increment each time there is a change in clock continuity. In the - * unlikely event that this value reaches full scale, rollover (not - * clamping) is required, such that this value continues to change, during - * subsequent discontinuity events.) - * - * While this number stays the same, between GnssClock reports, it can be - * safely assumed that the time_ns value has been running continuously, e.g. - * derived from a single, high quality clock (XO like, or better, that's - * typically used during continuous GNSS signal sampling.) - * - * It is expected, esp. during periods where there are few GNSS signals - * available, that the HW clock be discontinuity-free as long as possible, - * as this avoids the need to use (waste) a GNSS measurement to fully - * re-solve for the GPS clock bias and drift, when using the accompanying - * measurements, from consecutive GnssData reports. - */ - uint32_t hw_clock_discontinuity_count; - -} GnssClock; - -/** - * Legacy struct to represent a GPS Measurement, it contains raw and computed - * information. - * Deprecated, to be removed in the next Android release. - * Use GnssMeasurement instead. - */ -typedef struct { - /** set to sizeof(GpsMeasurement) */ - size_t size; - GpsMeasurementFlags flags; - int8_t prn; - double time_offset_ns; - GpsMeasurementState state; - int64_t received_gps_tow_ns; - int64_t received_gps_tow_uncertainty_ns; - double c_n0_dbhz; - double pseudorange_rate_mps; - double pseudorange_rate_uncertainty_mps; - GpsAccumulatedDeltaRangeState accumulated_delta_range_state; - double accumulated_delta_range_m; - double accumulated_delta_range_uncertainty_m; - double pseudorange_m; - double pseudorange_uncertainty_m; - double code_phase_chips; - double code_phase_uncertainty_chips; - float carrier_frequency_hz; - int64_t carrier_cycles; - double carrier_phase; - double carrier_phase_uncertainty; - GpsLossOfLock loss_of_lock; - int32_t bit_number; - int16_t time_from_last_bit_ms; - double doppler_shift_hz; - double doppler_shift_uncertainty_hz; - GpsMultipathIndicator multipath_indicator; - double snr_db; - double elevation_deg; - double elevation_uncertainty_deg; - double azimuth_deg; - double azimuth_uncertainty_deg; - bool used_in_fix; -} GpsMeasurement; - -/** - * Represents a GNSS Measurement, it contains raw and computed information. - * - * Independence - All signal measurement information (e.g. sv_time, - * pseudorange_rate, multipath_indicator) reported in this struct should be - * based on GNSS signal measurements only. You may not synthesize measurements - * by calculating or reporting expected measurements based on known or estimated - * position, velocity, or time. - */ -typedef struct { - /** set to sizeof(GpsMeasurement) */ - size_t size; - - /** A set of flags indicating the validity of the fields in this data structure. */ - GnssMeasurementFlags flags; - - /** - * Satellite vehicle ID number, as defined in GnssSvInfo::svid - * This is a mandatory value. - */ - int16_t svid; - - /** - * Defines the constellation of the given SV. Value should be one of those - * GNSS_CONSTELLATION_* constants - */ - GnssConstellationType constellation; - - /** - * Time offset at which the measurement was taken in nanoseconds. - * The reference receiver's time is specified by GpsData::clock::time_ns and should be - * interpreted in the same way as indicated by GpsClock::type. - * - * The sign of time_offset_ns is given by the following equation: - * measurement time = GpsClock::time_ns + time_offset_ns - * - * It provides an individual time-stamp for the measurement, and allows sub-nanosecond accuracy. - * This is a mandatory value. - */ - double time_offset_ns; - - /** - * Per satellite sync state. It represents the current sync state for the associated satellite. - * Based on the sync state, the 'received GPS tow' field should be interpreted accordingly. - * - * This is a mandatory value. - */ - GnssMeasurementState state; - - /** - * The received GNSS Time-of-Week at the measurement time, in nanoseconds. - * Ensure that this field is independent (see comment at top of - * GnssMeasurement struct.) - * - * For GPS & QZSS, this is: - * Received GPS Time-of-Week at the measurement time, in nanoseconds. - * The value is relative to the beginning of the current GPS week. - * - * Given the highest sync state that can be achieved, per each satellite, valid range - * for this field can be: - * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN - * C/A code lock : [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set - * Bit sync : [ 0 20ms ] : GNSS_MEASUREMENT_STATE_BIT_SYNC is set - * Subframe sync : [ 0 6s ] : GNSS_MEASUREMENT_STATE_SUBFRAME_SYNC is set - * TOW decoded : [ 0 1week ] : GNSS_MEASUREMENT_STATE_TOW_DECODED is set - * - * Note well: if there is any ambiguity in integer millisecond, - * GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS should be set accordingly, in the 'state' field. - * - * This value must be populated if 'state' != GNSS_MEASUREMENT_STATE_UNKNOWN. - * - * For Glonass, this is: - * Received Glonass time of day, at the measurement time in nanoseconds. - * - * Given the highest sync state that can be achieved, per each satellite, valid range for - * this field can be: - * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN - * C/A code lock : [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set - * Symbol sync : [ 0 10ms ] : GNSS_MEASUREMENT_STATE_SYMBOL_SYNC is set - * Bit sync : [ 0 20ms ] : GNSS_MEASUREMENT_STATE_BIT_SYNC is set - * String sync : [ 0 2s ] : GNSS_MEASUREMENT_STATE_GLO_STRING_SYNC is set - * Time of day : [ 0 1day ] : GNSS_MEASUREMENT_STATE_GLO_TOD_DECODED is set - * - * For Beidou, this is: - * Received Beidou time of week, at the measurement time in nanoseconds. - * - * Given the highest sync state that can be achieved, per each satellite, valid range for - * this field can be: - * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN - * C/A code lock: [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set - * Bit sync (D2): [ 0 2ms ] : GNSS_MEASUREMENT_STATE_BDS_D2_BIT_SYNC is set - * Bit sync (D1): [ 0 20ms ] : GNSS_MEASUREMENT_STATE_BIT_SYNC is set - * Subframe (D2): [ 0 0.6s ] : GNSS_MEASUREMENT_STATE_BDS_D2_SUBFRAME_SYNC is set - * Subframe (D1): [ 0 6s ] : GNSS_MEASUREMENT_STATE_SUBFRAME_SYNC is set - * Time of week : [ 0 1week ] : GNSS_MEASUREMENT_STATE_TOW_DECODED is set - * - * For Galileo, this is: - * Received Galileo time of week, at the measurement time in nanoseconds. - * - * E1BC code lock : [ 0 4ms ] : GNSS_MEASUREMENT_STATE_GAL_E1BC_CODE_LOCK is set - * E1C 2nd code lock: [ 0 100ms ] : - * GNSS_MEASUREMENT_STATE_GAL_E1C_2ND_CODE_LOCK is set - * - * E1B page : [ 0 2s ] : GNSS_MEASUREMENT_STATE_GAL_E1B_PAGE_SYNC is set - * Time of week: [ 0 1week ] : GNSS_MEASUREMENT_STATE_TOW_DECODED is set - * - * For SBAS, this is: - * Received SBAS time, at the measurement time in nanoseconds. - * - * Given the highest sync state that can be achieved, per each satellite, - * valid range for this field can be: - * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN - * C/A code lock: [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set - * Symbol sync : [ 0 2ms ] : GNSS_MEASUREMENT_STATE_SYMBOL_SYNC is set - * Message : [ 0 1s ] : GNSS_MEASUREMENT_STATE_SBAS_SYNC is set - */ - int64_t received_sv_time_in_ns; - - /** - * 1-Sigma uncertainty of the Received GPS Time-of-Week in nanoseconds. - * - * This value must be populated if 'state' != GPS_MEASUREMENT_STATE_UNKNOWN. - */ - int64_t received_sv_time_uncertainty_in_ns; - - /** - * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. - * It contains the measured C/N0 value for the signal at the antenna port. - * - * This is a mandatory value. - */ - double c_n0_dbhz; - - /** - * Pseudorange rate at the timestamp in m/s. The correction of a given - * Pseudorange Rate value includes corrections for receiver and satellite - * clock frequency errors. Ensure that this field is independent (see - * comment at top of GnssMeasurement struct.) - * - * It is mandatory to provide the 'uncorrected' 'pseudorange rate', and provide GpsClock's - * 'drift' field as well (When providing the uncorrected pseudorange rate, do not apply the - * corrections described above.) - * - * The value includes the 'pseudorange rate uncertainty' in it. - * A positive 'uncorrected' value indicates that the SV is moving away from the receiver. - * - * The sign of the 'uncorrected' 'pseudorange rate' and its relation to the sign of 'doppler - * shift' is given by the equation: - * pseudorange rate = -k * doppler shift (where k is a constant) - * - * This should be the most accurate pseudorange rate available, based on - * fresh signal measurements from this channel. - * - * It is mandatory that this value be provided at typical carrier phase PRR - * quality (few cm/sec per second of uncertainty, or better) - when signals - * are sufficiently strong & stable, e.g. signals from a GPS simulator at >= - * 35 dB-Hz. - */ - double pseudorange_rate_mps; - - /** - * 1-Sigma uncertainty of the pseudorange_rate_mps. - * The uncertainty is represented as an absolute (single sided) value. - * - * This is a mandatory value. - */ - double pseudorange_rate_uncertainty_mps; - - /** - * Accumulated delta range's state. It indicates whether ADR is reset or there is a cycle slip - * (indicating loss of lock). - * - * This is a mandatory value. - */ - GnssAccumulatedDeltaRangeState accumulated_delta_range_state; - - /** - * Accumulated delta range since the last channel reset in meters. - * A positive value indicates that the SV is moving away from the receiver. - * - * The sign of the 'accumulated delta range' and its relation to the sign of 'carrier phase' - * is given by the equation: - * accumulated delta range = -k * carrier phase (where k is a constant) - * - * This value must be populated if 'accumulated delta range state' != GPS_ADR_STATE_UNKNOWN. - * However, it is expected that the data is only accurate when: - * 'accumulated delta range state' == GPS_ADR_STATE_VALID. - */ - double accumulated_delta_range_m; - - /** - * 1-Sigma uncertainty of the accumulated delta range in meters. - * This value must be populated if 'accumulated delta range state' != GPS_ADR_STATE_UNKNOWN. - */ - double accumulated_delta_range_uncertainty_m; - - /** - * Carrier frequency at which codes and messages are modulated, it can be L1 or L2. - * If the field is not set, the carrier frequency is assumed to be L1. - * - * If the data is available, 'flags' must contain - * GNSS_MEASUREMENT_HAS_CARRIER_FREQUENCY. - */ - float carrier_frequency_hz; - - /** - * The number of full carrier cycles between the satellite and the receiver. - * The reference frequency is given by the field 'carrier_frequency_hz'. - * Indications of possible cycle slips and resets in the accumulation of - * this value can be inferred from the accumulated_delta_range_state flags. - * - * If the data is available, 'flags' must contain - * GNSS_MEASUREMENT_HAS_CARRIER_CYCLES. - */ - int64_t carrier_cycles; - - /** - * The RF phase detected by the receiver, in the range [0.0, 1.0]. - * This is usually the fractional part of the complete carrier phase measurement. - * - * The reference frequency is given by the field 'carrier_frequency_hz'. - * The value contains the 'carrier-phase uncertainty' in it. - * - * If the data is available, 'flags' must contain - * GNSS_MEASUREMENT_HAS_CARRIER_PHASE. - */ - double carrier_phase; - - /** - * 1-Sigma uncertainty of the carrier-phase. - * If the data is available, 'flags' must contain - * GNSS_MEASUREMENT_HAS_CARRIER_PHASE_UNCERTAINTY. - */ - double carrier_phase_uncertainty; - - /** - * An enumeration that indicates the 'multipath' state of the event. - * - * The multipath Indicator is intended to report the presence of overlapping - * signals that manifest as distorted correlation peaks. - * - * - if there is a distorted correlation peak shape, report that multipath - * is GNSS_MULTIPATH_INDICATOR_PRESENT. - * - if there is not a distorted correlation peak shape, report - * GNSS_MULTIPATH_INDICATOR_NOT_PRESENT - * - if signals are too weak to discern this information, report - * GNSS_MULTIPATH_INDICATOR_UNKNOWN - * - * Example: when doing the standardized overlapping Multipath Performance - * test (3GPP TS 34.171) the Multipath indicator should report - * GNSS_MULTIPATH_INDICATOR_PRESENT for those signals that are tracked, and - * contain multipath, and GNSS_MULTIPATH_INDICATOR_NOT_PRESENT for those - * signals that are tracked and do not contain multipath. - */ - GnssMultipathIndicator multipath_indicator; - - /** - * Signal-to-noise ratio at correlator output in dB. - * If the data is available, 'flags' must contain GNSS_MEASUREMENT_HAS_SNR. - * This is the power ratio of the "correlation peak height above the - * observed noise floor" to "the noise RMS". - */ - double snr_db; -} GnssMeasurement; - -/** - * Legacy struct to represents a reading of GPS measurements. - * Deprecated, to be removed in the next Android release. - * Use GnssData instead. - */ -typedef struct { - /** set to sizeof(GpsData) */ - size_t size; - size_t measurement_count; - GpsMeasurement measurements[GPS_MAX_MEASUREMENT]; - - /** The GPS clock time reading. */ - GpsClock clock; -} GpsData; - -/** - * Represents a reading of GNSS measurements. For devices where GnssSystemInfo's - * year_of_hw is set to 2016+, it is mandatory that these be provided, on - * request, when the GNSS receiver is searching/tracking signals. - * - * - Reporting of GPS constellation measurements is mandatory. - * - Reporting of all tracked constellations are encouraged. - */ -typedef struct { - /** set to sizeof(GnssData) */ - size_t size; - - /** Number of measurements. */ - size_t measurement_count; - - /** The array of measurements. */ - GnssMeasurement measurements[GNSS_MAX_MEASUREMENT]; - - /** The GPS clock time reading. */ - GnssClock clock; -} GnssData; - -/** - * The legacy callback for to report measurements from the HAL. - * - * This callback is deprecated, and will be removed in the next release. Use - * gnss_measurement_callback() instead. - * - * Parameters: - * data - A data structure containing the measurements. - */ -typedef void (*gps_measurement_callback) (GpsData* data); - -/** - * The callback for to report measurements from the HAL. - * - * Parameters: - * data - A data structure containing the measurements. - */ -typedef void (*gnss_measurement_callback) (GnssData* data); - -typedef struct { - /** set to sizeof(GpsMeasurementCallbacks) */ - size_t size; - gps_measurement_callback measurement_callback; - gnss_measurement_callback gnss_measurement_callback; -} GpsMeasurementCallbacks; - -/** - * Extended interface for GPS Measurements support. - */ -typedef struct { - /** Set to sizeof(GpsMeasurementInterface) */ - size_t size; - - /** - * Initializes the interface and registers the callback routines with the HAL. - * After a successful call to 'init' the HAL must begin to provide updates at its own phase. - * - * Status: - * GPS_MEASUREMENT_OPERATION_SUCCESS - * GPS_MEASUREMENT_ERROR_ALREADY_INIT - if a callback has already been registered without a - * corresponding call to 'close' - * GPS_MEASUREMENT_ERROR_GENERIC - if any other error occurred, it is expected that the HAL - * will not generate any updates upon returning this error code. - */ - int (*init) (GpsMeasurementCallbacks* callbacks); - - /** - * Stops updates from the HAL, and unregisters the callback routines. - * After a call to stop, the previously registered callbacks must be considered invalid by the - * HAL. - * If stop is invoked without a previous 'init', this function should perform no work. - */ - void (*close) (); - -} GpsMeasurementInterface; - -/** - * Legacy struct to represents a GPS navigation message (or a fragment of it). - * Deprecated, to be removed in the next Android release. - * Use GnssNavigationMessage instead. - */ -typedef struct { - /** set to sizeof(GpsNavigationMessage) */ - size_t size; - int8_t prn; - GpsNavigationMessageType type; - NavigationMessageStatus status; - int16_t message_id; - int16_t submessage_id; - size_t data_length; - uint8_t* data; -} GpsNavigationMessage; - -/** Represents a GPS navigation message (or a fragment of it). */ -typedef struct { - /** set to sizeof(GnssNavigationMessage) */ - size_t size; - - /** - * Satellite vehicle ID number, as defined in GnssSvInfo::svid - * This is a mandatory value. - */ - int16_t svid; - - /** - * The type of message contained in the structure. - * This is a mandatory value. - */ - GnssNavigationMessageType type; - - /** - * The status of the received navigation message. - * No need to send any navigation message that contains words with parity error and cannot be - * corrected. - */ - NavigationMessageStatus status; - - /** - * Message identifier. It provides an index so the complete Navigation - * Message can be assembled. - * - * - For GPS L1 C/A subframe 4 and 5, this value corresponds to the 'frame - * id' of the navigation message, in the range of 1-25 (Subframe 1, 2, 3 - * does not contain a 'frame id' and this value can be set to -1.) - * - * - For Glonass L1 C/A, this refers to the frame ID, in the range of 1-5. - * - * - For BeiDou D1, this refers to the frame number in the range of 1-24 - * - * - For Beidou D2, this refers to the frame number, in the range of 1-120 - * - * - For Galileo F/NAV nominal frame structure, this refers to the subframe - * number, in the range of 1-12 - * - * - For Galileo I/NAV nominal frame structure, this refers to the subframe - * number in the range of 1-24 - */ - int16_t message_id; - - /** - * Sub-message identifier. If required by the message 'type', this value - * contains a sub-index within the current message (or frame) that is being - * transmitted. - * - * - For GPS L1 C/A, BeiDou D1 & BeiDou D2, the submessage id corresponds to - * the subframe number of the navigation message, in the range of 1-5. - * - * - For Glonass L1 C/A, this refers to the String number, in the range from - * 1-15 - * - * - For Galileo F/NAV, this refers to the page type in the range 1-6 - * - * - For Galileo I/NAV, this refers to the word type in the range 1-10+ - */ - int16_t submessage_id; - - /** - * The length of the data (in bytes) contained in the current message. - * If this value is different from zero, 'data' must point to an array of the same size. - * e.g. for L1 C/A the size of the sub-frame will be 40 bytes (10 words, 30 bits/word). - * - * This is a mandatory value. - */ - size_t data_length; - - /** - * The data of the reported GPS message. The bytes (or words) specified - * using big endian format (MSB first). - * - * - For GPS L1 C/A, Beidou D1 & Beidou D2, each subframe contains 10 30-bit - * words. Each word (30 bits) should be fit into the last 30 bits in a - * 4-byte word (skip B31 and B32), with MSB first, for a total of 40 - * bytes, covering a time period of 6, 6, and 0.6 seconds, respectively. - * - * - For Glonass L1 C/A, each string contains 85 data bits, including the - * checksum. These bits should be fit into 11 bytes, with MSB first (skip - * B86-B88), covering a time period of 2 seconds. - * - * - For Galileo F/NAV, each word consists of 238-bit (sync & tail symbols - * excluded). Each word should be fit into 30-bytes, with MSB first (skip - * B239, B240), covering a time period of 10 seconds. - * - * - For Galileo I/NAV, each page contains 2 page parts, even and odd, with - * a total of 2x114 = 228 bits, (sync & tail excluded) that should be fit - * into 29 bytes, with MSB first (skip B229-B232). - */ - uint8_t* data; - -} GnssNavigationMessage; - -/** - * The legacy callback to report an available fragment of a GPS navigation - * messages from the HAL. - * - * This callback is deprecated, and will be removed in the next release. Use - * gnss_navigation_message_callback() instead. - * - * Parameters: - * message - The GPS navigation submessage/subframe representation. - */ -typedef void (*gps_navigation_message_callback) (GpsNavigationMessage* message); - -/** - * The callback to report an available fragment of a GPS navigation messages from the HAL. - * - * Parameters: - * message - The GPS navigation submessage/subframe representation. - */ -typedef void (*gnss_navigation_message_callback) (GnssNavigationMessage* message); - -typedef struct { - /** set to sizeof(GpsNavigationMessageCallbacks) */ - size_t size; - gps_navigation_message_callback navigation_message_callback; - gnss_navigation_message_callback gnss_navigation_message_callback; -} GpsNavigationMessageCallbacks; - -/** - * Extended interface for GPS navigation message reporting support. - */ -typedef struct { - /** Set to sizeof(GpsNavigationMessageInterface) */ - size_t size; - - /** - * Initializes the interface and registers the callback routines with the HAL. - * After a successful call to 'init' the HAL must begin to provide updates as they become - * available. - * - * Status: - * GPS_NAVIGATION_MESSAGE_OPERATION_SUCCESS - * GPS_NAVIGATION_MESSAGE_ERROR_ALREADY_INIT - if a callback has already been registered - * without a corresponding call to 'close'. - * GPS_NAVIGATION_MESSAGE_ERROR_GENERIC - if any other error occurred, it is expected that - * the HAL will not generate any updates upon returning this error code. - */ - int (*init) (GpsNavigationMessageCallbacks* callbacks); - - /** - * Stops updates from the HAL, and unregisters the callback routines. - * After a call to stop, the previously registered callbacks must be considered invalid by the - * HAL. - * If stop is invoked without a previous 'init', this function should perform no work. - */ - void (*close) (); - -} GpsNavigationMessageInterface; - -/** - * Interface for passing GNSS configuration contents from platform to HAL. - */ -typedef struct { - /** Set to sizeof(GnssConfigurationInterface) */ - size_t size; - - /** - * Deliver GNSS configuration contents to HAL. - * Parameters: - * config_data - a pointer to a char array which holds what usually is expected from - file(/etc/gps.conf), i.e., a sequence of UTF8 strings separated by '\n'. - * length - total number of UTF8 characters in configuraiton data. - * - * IMPORTANT: - * GPS HAL should expect this function can be called multiple times. And it may be - * called even when GpsLocationProvider is already constructed and enabled. GPS HAL - * should maintain the existing requests for various callback regardless the change - * in configuration data. - */ - void (*configuration_update) (const char* config_data, int32_t length); -} GnssConfigurationInterface; - -__END_DECLS - -#endif /* ANDROID_INCLUDE_HARDWARE_GPS_H */ - +../../include_all/hardware/gps.h
\ No newline at end of file diff --git a/include/hardware/gps_internal.h b/include/hardware/gps_internal.h index 6a3833ba..7ae93d61 100644..120000 --- a/include/hardware/gps_internal.h +++ b/include/hardware/gps_internal.h @@ -1,96 +1 @@ -/* - * Copyright (C) 2016 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_INCLUDE_HARDWARE_GPS_INTERNAL_H -#define ANDROID_INCLUDE_HARDWARE_GPS_INTERNAL_H - -#include "hardware/gps.h" - -/**************************************************************************** - * This file contains legacy structs that are deprecated/retired from gps.h * - ****************************************************************************/ - -__BEGIN_DECLS - -/** - * Legacy GPS callback structure. - * Deprecated, to be removed in the next Android release. - * Use GpsCallbacks instead. - */ -typedef struct { - /** set to sizeof(GpsCallbacks_v1) */ - size_t size; - gps_location_callback location_cb; - gps_status_callback status_cb; - gps_sv_status_callback sv_status_cb; - gps_nmea_callback nmea_cb; - gps_set_capabilities set_capabilities_cb; - gps_acquire_wakelock acquire_wakelock_cb; - gps_release_wakelock release_wakelock_cb; - gps_create_thread create_thread_cb; - gps_request_utc_time request_utc_time_cb; -} GpsCallbacks_v1; - -#pragma pack(push,4) -// We need to keep the alignment of this data structure to 4-bytes, to ensure that in 64-bit -// environments the size of this legacy definition does not collide with _v2. Implementations should -// be using _v2 and _v3, so it's OK to pay the 'unaligned' penalty in 64-bit if an old -// implementation is still in use. - -/** - * Legacy struct to represent the status of AGPS. - */ -typedef struct { - /** set to sizeof(AGpsStatus_v1) */ - size_t size; - AGpsType type; - AGpsStatusValue status; -} AGpsStatus_v1; - -#pragma pack(pop) - -/** - * Legacy struct to represent the status of AGPS augmented with a IPv4 address - * field. - */ -typedef struct { - /** set to sizeof(AGpsStatus_v2) */ - size_t size; - AGpsType type; - AGpsStatusValue status; - - /*-------------------- New fields in _v2 --------------------*/ - - uint32_t ipaddr; -} AGpsStatus_v2; - -/** - * Legacy extended interface for AGPS support. - * See AGpsInterface_v2 for more information. - */ -typedef struct { - /** set to sizeof(AGpsInterface_v1) */ - size_t size; - void (*init)( AGpsCallbacks* callbacks ); - int (*data_conn_open)( const char* apn ); - int (*data_conn_closed)(); - int (*data_conn_failed)(); - int (*set_server)( AGpsType type, const char* hostname, int port ); -} AGpsInterface_v1; - -__END_DECLS - -#endif /* ANDROID_INCLUDE_HARDWARE_GPS_INTERNAL_H */ +../../include_all/hardware/gps_internal.h
\ No newline at end of file diff --git a/include/hardware/gralloc.h b/include/hardware/gralloc.h index 10a153c0..7842f87d 100644..120000 --- a/include/hardware/gralloc.h +++ b/include/hardware/gralloc.h @@ -1,448 +1 @@ -/* - * Copyright (C) 2008 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_GRALLOC_INTERFACE_H -#define ANDROID_GRALLOC_INTERFACE_H - -#include <system/graphics.h> -#include <hardware/hardware.h> - -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <cutils/native_handle.h> - -#include <hardware/hardware.h> -#include <hardware/fb.h> - -__BEGIN_DECLS - -/** - * Module versioning information for the Gralloc hardware module, based on - * gralloc_module_t.common.module_api_version. - * - * Version History: - * - * GRALLOC_MODULE_API_VERSION_0_1: - * Initial Gralloc hardware module API. - * - * GRALLOC_MODULE_API_VERSION_0_2: - * Add support for flexible YCbCr format with (*lock_ycbcr)() method. - * - * GRALLOC_MODULE_API_VERSION_0_3: - * Add support for fence passing to/from lock/unlock. - */ - -#define GRALLOC_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) -#define GRALLOC_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) -#define GRALLOC_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) - -#define GRALLOC_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION(0, 1) - -/** - * The id of this module - */ -#define GRALLOC_HARDWARE_MODULE_ID "gralloc" - -/** - * Name of the graphics device to open - */ - -#define GRALLOC_HARDWARE_GPU0 "gpu0" - -enum { - /* buffer is never read in software */ - GRALLOC_USAGE_SW_READ_NEVER = 0x00000000U, - /* buffer is rarely read in software */ - GRALLOC_USAGE_SW_READ_RARELY = 0x00000002U, - /* buffer is often read in software */ - GRALLOC_USAGE_SW_READ_OFTEN = 0x00000003U, - /* mask for the software read values */ - GRALLOC_USAGE_SW_READ_MASK = 0x0000000FU, - - /* buffer is never written in software */ - GRALLOC_USAGE_SW_WRITE_NEVER = 0x00000000U, - /* buffer is rarely written in software */ - GRALLOC_USAGE_SW_WRITE_RARELY = 0x00000020U, - /* buffer is often written in software */ - GRALLOC_USAGE_SW_WRITE_OFTEN = 0x00000030U, - /* mask for the software write values */ - GRALLOC_USAGE_SW_WRITE_MASK = 0x000000F0U, - - /* buffer will be used as an OpenGL ES texture */ - GRALLOC_USAGE_HW_TEXTURE = 0x00000100U, - /* buffer will be used as an OpenGL ES render target */ - GRALLOC_USAGE_HW_RENDER = 0x00000200U, - /* buffer will be used by the 2D hardware blitter */ - GRALLOC_USAGE_HW_2D = 0x00000400U, - /* buffer will be used by the HWComposer HAL module */ - GRALLOC_USAGE_HW_COMPOSER = 0x00000800U, - /* buffer will be used with the framebuffer device */ - GRALLOC_USAGE_HW_FB = 0x00001000U, - - /* buffer should be displayed full-screen on an external display when - * possible */ - GRALLOC_USAGE_EXTERNAL_DISP = 0x00002000U, - - /* Must have a hardware-protected path to external display sink for - * this buffer. If a hardware-protected path is not available, then - * either don't composite only this buffer (preferred) to the - * external sink, or (less desirable) do not route the entire - * composition to the external sink. */ - GRALLOC_USAGE_PROTECTED = 0x00004000U, - - /* buffer may be used as a cursor */ - GRALLOC_USAGE_CURSOR = 0x00008000U, - - /* buffer will be used with the HW video encoder */ - GRALLOC_USAGE_HW_VIDEO_ENCODER = 0x00010000U, - /* buffer will be written by the HW camera pipeline */ - GRALLOC_USAGE_HW_CAMERA_WRITE = 0x00020000U, - /* buffer will be read by the HW camera pipeline */ - GRALLOC_USAGE_HW_CAMERA_READ = 0x00040000U, - /* buffer will be used as part of zero-shutter-lag queue */ - GRALLOC_USAGE_HW_CAMERA_ZSL = 0x00060000U, - /* mask for the camera access values */ - GRALLOC_USAGE_HW_CAMERA_MASK = 0x00060000U, - /* mask for the software usage bit-mask */ - GRALLOC_USAGE_HW_MASK = 0x00071F00U, - - /* buffer will be used as a RenderScript Allocation */ - GRALLOC_USAGE_RENDERSCRIPT = 0x00100000U, - - /* Set by the consumer to indicate to the producer that they may attach a - * buffer that they did not detach from the BufferQueue. Will be filtered - * out by GRALLOC_USAGE_ALLOC_MASK, so gralloc modules will not need to - * handle this flag. */ - GRALLOC_USAGE_FOREIGN_BUFFERS = 0x00200000U, - - /* buffer will be used as input to HW HEIC image encoder */ - GRALLOC_USAGE_HW_IMAGE_ENCODER = 0x08000000U, - - /* Mask of all flags which could be passed to a gralloc module for buffer - * allocation. Any flags not in this mask do not need to be handled by - * gralloc modules. */ - GRALLOC_USAGE_ALLOC_MASK = ~(GRALLOC_USAGE_FOREIGN_BUFFERS), - - /* implementation-specific private usage flags */ - GRALLOC_USAGE_PRIVATE_0 = 0x10000000U, - GRALLOC_USAGE_PRIVATE_1 = 0x20000000U, - GRALLOC_USAGE_PRIVATE_2 = 0x40000000U, - GRALLOC_USAGE_PRIVATE_3 = 0x80000000U, - GRALLOC_USAGE_PRIVATE_MASK = 0xF0000000U, -}; - -/*****************************************************************************/ - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -typedef struct gralloc_module_t { - struct hw_module_t common; - - /* - * (*registerBuffer)() must be called before a buffer_handle_t that has not - * been created with (*alloc_device_t::alloc)() can be used. - * - * This is intended to be used with buffer_handle_t's that have been - * received in this process through IPC. - * - * This function checks that the handle is indeed a valid one and prepares - * it for use with (*lock)() and (*unlock)(). - * - * It is not necessary to call (*registerBuffer)() on a handle created - * with (*alloc_device_t::alloc)(). - * - * returns an error if this buffer_handle_t is not valid. - */ - int (*registerBuffer)(struct gralloc_module_t const* module, - buffer_handle_t handle); - - /* - * (*unregisterBuffer)() is called once this handle is no longer needed in - * this process. After this call, it is an error to call (*lock)(), - * (*unlock)(), or (*registerBuffer)(). - * - * This function doesn't close or free the handle itself; this is done - * by other means, usually through libcutils's native_handle_close() and - * native_handle_free(). - * - * It is an error to call (*unregisterBuffer)() on a buffer that wasn't - * explicitly registered first. - */ - int (*unregisterBuffer)(struct gralloc_module_t const* module, - buffer_handle_t handle); - - /* - * The (*lock)() method is called before a buffer is accessed for the - * specified usage. This call may block, for instance if the h/w needs - * to finish rendering or if CPU caches need to be synchronized. - * - * The caller promises to modify only pixels in the area specified - * by (l,t,w,h). - * - * The content of the buffer outside of the specified area is NOT modified - * by this call. - * - * If usage specifies GRALLOC_USAGE_SW_*, vaddr is filled with the address - * of the buffer in virtual memory. - * - * Note calling (*lock)() on HAL_PIXEL_FORMAT_YCbCr_*_888 buffers will fail - * and return -EINVAL. These buffers must be locked with (*lock_ycbcr)() - * instead. - * - * THREADING CONSIDERATIONS: - * - * It is legal for several different threads to lock a buffer from - * read access, none of the threads are blocked. - * - * However, locking a buffer simultaneously for write or read/write is - * undefined, but: - * - shall not result in termination of the process - * - shall not block the caller - * It is acceptable to return an error or to leave the buffer's content - * into an indeterminate state. - * - * If the buffer was created with a usage mask incompatible with the - * requested usage flags here, -EINVAL is returned. - * - */ - - int (*lock)(struct gralloc_module_t const* module, - buffer_handle_t handle, int usage, - int l, int t, int w, int h, - void** vaddr); - - - /* - * The (*unlock)() method must be called after all changes to the buffer - * are completed. - */ - - int (*unlock)(struct gralloc_module_t const* module, - buffer_handle_t handle); - - - /* reserved for future use */ - int (*perform)(struct gralloc_module_t const* module, - int operation, ... ); - - /* - * The (*lock_ycbcr)() method is like the (*lock)() method, with the - * difference that it fills a struct ycbcr with a description of the buffer - * layout, and zeroes out the reserved fields. - * - * If the buffer format is not compatible with a flexible YUV format (e.g. - * the buffer layout cannot be represented with the ycbcr struct), it - * will return -EINVAL. - * - * This method must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888 - * if supported by the device, as well as with any other format that is - * requested by the multimedia codecs when they are configured with a - * flexible-YUV-compatible color-format with android native buffers. - * - * Note that this method may also be called on buffers of other formats, - * including non-YUV formats. - * - * Added in GRALLOC_MODULE_API_VERSION_0_2. - */ - - int (*lock_ycbcr)(struct gralloc_module_t const* module, - buffer_handle_t handle, int usage, - int l, int t, int w, int h, - struct android_ycbcr *ycbcr); - - /* - * The (*lockAsync)() method is like the (*lock)() method except - * that the buffer's sync fence object is passed into the lock - * call instead of requiring the caller to wait for completion. - * - * The gralloc implementation takes ownership of the fenceFd and - * is responsible for closing it when no longer needed. - * - * Added in GRALLOC_MODULE_API_VERSION_0_3. - */ - int (*lockAsync)(struct gralloc_module_t const* module, - buffer_handle_t handle, int usage, - int l, int t, int w, int h, - void** vaddr, int fenceFd); - - /* - * The (*unlockAsync)() method is like the (*unlock)() method - * except that a buffer sync fence object is returned from the - * lock call, representing the completion of any pending work - * performed by the gralloc implementation. - * - * The caller takes ownership of the fenceFd and is responsible - * for closing it when no longer needed. - * - * Added in GRALLOC_MODULE_API_VERSION_0_3. - */ - int (*unlockAsync)(struct gralloc_module_t const* module, - buffer_handle_t handle, int* fenceFd); - - /* - * The (*lockAsync_ycbcr)() method is like the (*lock_ycbcr)() - * method except that the buffer's sync fence object is passed - * into the lock call instead of requiring the caller to wait for - * completion. - * - * The gralloc implementation takes ownership of the fenceFd and - * is responsible for closing it when no longer needed. - * - * Added in GRALLOC_MODULE_API_VERSION_0_3. - */ - int (*lockAsync_ycbcr)(struct gralloc_module_t const* module, - buffer_handle_t handle, int usage, - int l, int t, int w, int h, - struct android_ycbcr *ycbcr, int fenceFd); - - /* getTransportSize(..., outNumFds, outNumInts) - * This function is mandatory on devices running IMapper2.1 or higher. - * - * Get the transport size of a buffer. An imported buffer handle is a raw - * buffer handle with the process-local runtime data appended. This - * function, for example, allows a caller to omit the process-local - * runtime data at the tail when serializing the imported buffer handle. - * - * Note that a client might or might not omit the process-local runtime - * data when sending an imported buffer handle. The mapper must support - * both cases on the receiving end. - */ - int32_t (*getTransportSize)( - struct gralloc_module_t const* module, buffer_handle_t handle, uint32_t *outNumFds, - uint32_t *outNumInts); - - /* validateBufferSize(..., w, h, format, usage, stride) - * This function is mandatory on devices running IMapper2.1 or higher. - * - * Validate that the buffer can be safely accessed by a caller who assumes - * the specified width, height, format, usage, and stride. This must at least validate - * that the buffer size is large enough. Validating the buffer against - * individual buffer attributes is optional. - */ - int32_t (*validateBufferSize)( - struct gralloc_module_t const* device, buffer_handle_t handle, - uint32_t w, uint32_t h, int32_t format, int usage, - uint32_t stride); - - /* reserved for future use */ - void* reserved_proc[1]; - -} gralloc_module_t; - -/*****************************************************************************/ - -/** - * Every device data structure must begin with hw_device_t - * followed by module specific public methods and attributes. - */ - -typedef struct alloc_device_t { - struct hw_device_t common; - - /* - * (*alloc)() Allocates a buffer in graphic memory with the requested - * parameters and returns a buffer_handle_t and the stride in pixels to - * allow the implementation to satisfy hardware constraints on the width - * of a pixmap (eg: it may have to be multiple of 8 pixels). - * The CALLER TAKES OWNERSHIP of the buffer_handle_t. - * - * If format is HAL_PIXEL_FORMAT_YCbCr_420_888, the returned stride must be - * 0, since the actual strides are available from the android_ycbcr - * structure. - * - * Returns 0 on success or -errno on error. - */ - - int (*alloc)(struct alloc_device_t* dev, - int w, int h, int format, int usage, - buffer_handle_t* handle, int* stride); - - /* - * (*free)() Frees a previously allocated buffer. - * Behavior is undefined if the buffer is still mapped in any process, - * but shall not result in termination of the program or security breaches - * (allowing a process to get access to another process' buffers). - * THIS FUNCTION TAKES OWNERSHIP of the buffer_handle_t which becomes - * invalid after the call. - * - * Returns 0 on success or -errno on error. - */ - int (*free)(struct alloc_device_t* dev, - buffer_handle_t handle); - - /* This hook is OPTIONAL. - * - * If non NULL it will be caused by SurfaceFlinger on dumpsys - */ - void (*dump)(struct alloc_device_t *dev, char *buff, int buff_len); - - void* reserved_proc[7]; -} alloc_device_t; - - -/** convenience API for opening and closing a supported device */ - -static inline int gralloc_open(const struct hw_module_t* module, - struct alloc_device_t** device) { - return module->methods->open(module, - GRALLOC_HARDWARE_GPU0, TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int gralloc_close(struct alloc_device_t* device) { - return device->common.close(&device->common); -} - -/** - * map_usage_to_memtrack should be called after allocating a gralloc buffer. - * - * @param usage - it is the flag used when alloc function is called. - * - * This function maps the gralloc usage flags to appropriate memtrack bucket. - * GrallocHAL implementers and users should make an additional ION_IOCTL_TAG - * call using the memtrack tag returned by this function. This will help the - * in-kernel memtack to categorize the memory allocated by different processes - * according to their usage. - * - */ -static inline const char* map_usage_to_memtrack(uint32_t usage) { - usage &= GRALLOC_USAGE_ALLOC_MASK; - - if ((usage & GRALLOC_USAGE_HW_CAMERA_WRITE) != 0) { - return "camera"; - } else if ((usage & GRALLOC_USAGE_HW_VIDEO_ENCODER) != 0 || - (usage & GRALLOC_USAGE_EXTERNAL_DISP) != 0) { - return "video"; - } else if ((usage & GRALLOC_USAGE_HW_RENDER) != 0 || - (usage & GRALLOC_USAGE_HW_TEXTURE) != 0) { - return "gl"; - } else if ((usage & GRALLOC_USAGE_HW_CAMERA_READ) != 0) { - return "camera"; - } else if ((usage & GRALLOC_USAGE_SW_READ_MASK) != 0 || - (usage & GRALLOC_USAGE_SW_WRITE_MASK) != 0) { - return "cpu"; - } - return "graphics"; -} - -__END_DECLS - -#endif // ANDROID_GRALLOC_INTERFACE_H +../../include_all/hardware/gralloc.h
\ No newline at end of file diff --git a/include/hardware/gralloc1.h b/include/hardware/gralloc1.h index c211029a..9529fc31 100644..120000 --- a/include/hardware/gralloc1.h +++ b/include/hardware/gralloc1.h @@ -1,1044 +1 @@ -/* - * Copyright 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_GRALLOC1_H -#define ANDROID_HARDWARE_GRALLOC1_H - -#include <hardware/hardware.h> -#include <cutils/native_handle.h> - -__BEGIN_DECLS - -#define GRALLOC_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) -#define GRALLOC_HARDWARE_MODULE_ID "gralloc" - -/* - * Enums - */ - -typedef enum { - GRALLOC1_CAPABILITY_INVALID = 0, - - /* If this capability is supported, then the outBuffers parameter to - * allocate may be NULL, which instructs the device to report whether the - * given allocation is possible or not. */ - GRALLOC1_CAPABILITY_TEST_ALLOCATE = 1, - - /* If this capability is supported, then the implementation supports - * allocating buffers with more than one image layer. */ - GRALLOC1_CAPABILITY_LAYERED_BUFFERS = 2, - - /* If this capability is supported, then the implementation always closes - * and deletes a buffer handle whenever the last reference is removed. - * - * Supporting this capability is strongly recommended. It will become - * mandatory in future releases. */ - GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE = 3, - - GRALLOC1_LAST_CAPABILITY = 3, -} gralloc1_capability_t; - -typedef enum { - GRALLOC1_CONSUMER_USAGE_NONE = 0, - GRALLOC1_CONSUMER_USAGE_CPU_READ_NEVER = 0, - /* 1ULL << 0 */ - GRALLOC1_CONSUMER_USAGE_CPU_READ = 1ULL << 1, - GRALLOC1_CONSUMER_USAGE_CPU_READ_OFTEN = 1ULL << 2 | - GRALLOC1_CONSUMER_USAGE_CPU_READ, - /* 1ULL << 3 */ - /* 1ULL << 4 */ - /* 1ULL << 5 */ - /* 1ULL << 6 */ - /* 1ULL << 7 */ - GRALLOC1_CONSUMER_USAGE_GPU_TEXTURE = 1ULL << 8, - /* 1ULL << 9 */ - /* 1ULL << 10 */ - GRALLOC1_CONSUMER_USAGE_HWCOMPOSER = 1ULL << 11, - GRALLOC1_CONSUMER_USAGE_CLIENT_TARGET = 1ULL << 12, - /* 1ULL << 13 */ - /* 1ULL << 14 */ - GRALLOC1_CONSUMER_USAGE_CURSOR = 1ULL << 15, - GRALLOC1_CONSUMER_USAGE_VIDEO_ENCODER = 1ULL << 16, - /* 1ULL << 17 */ - GRALLOC1_CONSUMER_USAGE_CAMERA = 1ULL << 18, - /* 1ULL << 19 */ - GRALLOC1_CONSUMER_USAGE_RENDERSCRIPT = 1ULL << 20, - - /* Indicates that the consumer may attach buffers to their end of the - * BufferQueue, which means that the producer may never have seen a given - * dequeued buffer before. May be ignored by the gralloc device. */ - GRALLOC1_CONSUMER_USAGE_FOREIGN_BUFFERS = 1ULL << 21, - - /* 1ULL << 22 */ - GRALLOC1_CONSUMER_USAGE_GPU_DATA_BUFFER = 1ULL << 23, - /* 1ULL << 24 */ - /* 1ULL << 25 */ - /* 1ULL << 26 */ - /* 1ULL << 27 */ - - /* Bits reserved for implementation-specific usage flags */ - GRALLOC1_CONSUMER_USAGE_PRIVATE_0 = 1ULL << 28, - GRALLOC1_CONSUMER_USAGE_PRIVATE_1 = 1ULL << 29, - GRALLOC1_CONSUMER_USAGE_PRIVATE_2 = 1ULL << 30, - GRALLOC1_CONSUMER_USAGE_PRIVATE_3 = 1ULL << 31, - - /* 1ULL << 32 */ - /* 1ULL << 33 */ - /* 1ULL << 34 */ - /* 1ULL << 35 */ - /* 1ULL << 36 */ - /* 1ULL << 37 */ - /* 1ULL << 38 */ - /* 1ULL << 39 */ - /* 1ULL << 40 */ - /* 1ULL << 41 */ - /* 1ULL << 42 */ - /* 1ULL << 43 */ - /* 1ULL << 44 */ - /* 1ULL << 45 */ - /* 1ULL << 46 */ - /* 1ULL << 47 */ - - /* Bits reserved for implementation-specific usage flags */ - GRALLOC1_CONSUMER_USAGE_PRIVATE_19 = 1ULL << 48, - GRALLOC1_CONSUMER_USAGE_PRIVATE_18 = 1ULL << 49, - GRALLOC1_CONSUMER_USAGE_PRIVATE_17 = 1ULL << 50, - GRALLOC1_CONSUMER_USAGE_PRIVATE_16 = 1ULL << 51, - GRALLOC1_CONSUMER_USAGE_PRIVATE_15 = 1ULL << 52, - GRALLOC1_CONSUMER_USAGE_PRIVATE_14 = 1ULL << 53, - GRALLOC1_CONSUMER_USAGE_PRIVATE_13 = 1ULL << 54, - GRALLOC1_CONSUMER_USAGE_PRIVATE_12 = 1ULL << 55, - GRALLOC1_CONSUMER_USAGE_PRIVATE_11 = 1ULL << 56, - GRALLOC1_CONSUMER_USAGE_PRIVATE_10 = 1ULL << 57, - GRALLOC1_CONSUMER_USAGE_PRIVATE_9 = 1ULL << 58, - GRALLOC1_CONSUMER_USAGE_PRIVATE_8 = 1ULL << 59, - GRALLOC1_CONSUMER_USAGE_PRIVATE_7 = 1ULL << 60, - GRALLOC1_CONSUMER_USAGE_PRIVATE_6 = 1ULL << 61, - GRALLOC1_CONSUMER_USAGE_PRIVATE_5 = 1ULL << 62, - GRALLOC1_CONSUMER_USAGE_PRIVATE_4 = 1ULL << 63, -} gralloc1_consumer_usage_t; - -typedef enum { - GRALLOC1_FUNCTION_INVALID = 0, - GRALLOC1_FUNCTION_DUMP = 1, - GRALLOC1_FUNCTION_CREATE_DESCRIPTOR = 2, - GRALLOC1_FUNCTION_DESTROY_DESCRIPTOR = 3, - GRALLOC1_FUNCTION_SET_CONSUMER_USAGE = 4, - GRALLOC1_FUNCTION_SET_DIMENSIONS = 5, - GRALLOC1_FUNCTION_SET_FORMAT = 6, - GRALLOC1_FUNCTION_SET_PRODUCER_USAGE = 7, - GRALLOC1_FUNCTION_GET_BACKING_STORE = 8, - GRALLOC1_FUNCTION_GET_CONSUMER_USAGE = 9, - GRALLOC1_FUNCTION_GET_DIMENSIONS = 10, - GRALLOC1_FUNCTION_GET_FORMAT = 11, - GRALLOC1_FUNCTION_GET_PRODUCER_USAGE = 12, - GRALLOC1_FUNCTION_GET_STRIDE = 13, - GRALLOC1_FUNCTION_ALLOCATE = 14, - GRALLOC1_FUNCTION_RETAIN = 15, - GRALLOC1_FUNCTION_RELEASE = 16, - GRALLOC1_FUNCTION_GET_NUM_FLEX_PLANES = 17, - GRALLOC1_FUNCTION_LOCK = 18, - GRALLOC1_FUNCTION_LOCK_FLEX = 19, - GRALLOC1_FUNCTION_UNLOCK = 20, - GRALLOC1_FUNCTION_SET_LAYER_COUNT = 21, - GRALLOC1_FUNCTION_GET_LAYER_COUNT = 22, - GRALLOC1_FUNCTION_VALIDATE_BUFFER_SIZE = 23, - GRALLOC1_FUNCTION_GET_TRANSPORT_SIZE = 24, - GRALLOC1_FUNCTION_IMPORT_BUFFER = 25, - GRALLOC1_LAST_FUNCTION = 25, -} gralloc1_function_descriptor_t; - -typedef enum { - GRALLOC1_ERROR_NONE = 0, - GRALLOC1_ERROR_BAD_DESCRIPTOR = 1, - GRALLOC1_ERROR_BAD_HANDLE = 2, - GRALLOC1_ERROR_BAD_VALUE = 3, - GRALLOC1_ERROR_NOT_SHARED = 4, - GRALLOC1_ERROR_NO_RESOURCES = 5, - GRALLOC1_ERROR_UNDEFINED = 6, - GRALLOC1_ERROR_UNSUPPORTED = 7, -} gralloc1_error_t; - -typedef enum { - GRALLOC1_PRODUCER_USAGE_NONE = 0, - GRALLOC1_PRODUCER_USAGE_CPU_WRITE_NEVER = 0, - /* 1ULL << 0 */ - GRALLOC1_PRODUCER_USAGE_CPU_READ = 1ULL << 1, - GRALLOC1_PRODUCER_USAGE_CPU_READ_OFTEN = 1ULL << 2 | - GRALLOC1_PRODUCER_USAGE_CPU_READ, - /* 1ULL << 3 */ - /* 1ULL << 4 */ - GRALLOC1_PRODUCER_USAGE_CPU_WRITE = 1ULL << 5, - GRALLOC1_PRODUCER_USAGE_CPU_WRITE_OFTEN = 1ULL << 6 | - GRALLOC1_PRODUCER_USAGE_CPU_WRITE, - /* 1ULL << 7 */ - /* 1ULL << 8 */ - GRALLOC1_PRODUCER_USAGE_GPU_RENDER_TARGET = 1ULL << 9, - /* 1ULL << 10 */ - /* 1ULL << 11 */ - /* 1ULL << 12 */ - /* 1ULL << 13 */ - - /* The consumer must have a hardware-protected path to an external display - * sink for this buffer. If a hardware-protected path is not available, then - * do not attempt to display this buffer. */ - GRALLOC1_PRODUCER_USAGE_PROTECTED = 1ULL << 14, - - /* 1ULL << 15 */ - /* 1ULL << 16 */ - GRALLOC1_PRODUCER_USAGE_CAMERA = 1ULL << 17, - /* 1ULL << 18 */ - /* 1ULL << 19 */ - /* 1ULL << 20 */ - /* 1ULL << 21 */ - GRALLOC1_PRODUCER_USAGE_VIDEO_DECODER = 1ULL << 22, - GRALLOC1_PRODUCER_USAGE_SENSOR_DIRECT_DATA = 1ULL << 23, - /* 1ULL << 24 */ - /* 1ULL << 25 */ - /* 1ULL << 26 */ - /* 1ULL << 27 */ - - /* Bits reserved for implementation-specific usage flags */ - GRALLOC1_PRODUCER_USAGE_PRIVATE_0 = 1ULL << 28, - GRALLOC1_PRODUCER_USAGE_PRIVATE_1 = 1ULL << 29, - GRALLOC1_PRODUCER_USAGE_PRIVATE_2 = 1ULL << 30, - GRALLOC1_PRODUCER_USAGE_PRIVATE_3 = 1ULL << 31, - - /* 1ULL << 32 */ - /* 1ULL << 33 */ - /* 1ULL << 34 */ - /* 1ULL << 35 */ - /* 1ULL << 36 */ - /* 1ULL << 37 */ - /* 1ULL << 38 */ - /* 1ULL << 39 */ - /* 1ULL << 40 */ - /* 1ULL << 41 */ - /* 1ULL << 42 */ - /* 1ULL << 43 */ - /* 1ULL << 44 */ - /* 1ULL << 45 */ - /* 1ULL << 46 */ - /* 1ULL << 47 */ - - /* Bits reserved for implementation-specific usage flags */ - GRALLOC1_PRODUCER_USAGE_PRIVATE_19 = 1ULL << 48, - GRALLOC1_PRODUCER_USAGE_PRIVATE_18 = 1ULL << 49, - GRALLOC1_PRODUCER_USAGE_PRIVATE_17 = 1ULL << 50, - GRALLOC1_PRODUCER_USAGE_PRIVATE_16 = 1ULL << 51, - GRALLOC1_PRODUCER_USAGE_PRIVATE_15 = 1ULL << 52, - GRALLOC1_PRODUCER_USAGE_PRIVATE_14 = 1ULL << 53, - GRALLOC1_PRODUCER_USAGE_PRIVATE_13 = 1ULL << 54, - GRALLOC1_PRODUCER_USAGE_PRIVATE_12 = 1ULL << 55, - GRALLOC1_PRODUCER_USAGE_PRIVATE_11 = 1ULL << 56, - GRALLOC1_PRODUCER_USAGE_PRIVATE_10 = 1ULL << 57, - GRALLOC1_PRODUCER_USAGE_PRIVATE_9 = 1ULL << 58, - GRALLOC1_PRODUCER_USAGE_PRIVATE_8 = 1ULL << 59, - GRALLOC1_PRODUCER_USAGE_PRIVATE_7 = 1ULL << 60, - GRALLOC1_PRODUCER_USAGE_PRIVATE_6 = 1ULL << 61, - GRALLOC1_PRODUCER_USAGE_PRIVATE_5 = 1ULL << 62, - GRALLOC1_PRODUCER_USAGE_PRIVATE_4 = 1ULL << 63, -} gralloc1_producer_usage_t; - -/* - * Typedefs - */ - -typedef void (*gralloc1_function_pointer_t)(); - -typedef uint64_t gralloc1_backing_store_t; -typedef uint64_t gralloc1_buffer_descriptor_t; - -/* - * Device Struct - */ - -typedef struct gralloc1_device { - /* Must be the first member of this struct, since a pointer to this struct - * will be generated by casting from a hw_device_t* */ - struct hw_device_t common; - - /* getCapabilities(..., outCount, outCapabilities) - * - * Provides a list of capabilities (described in the definition of - * gralloc1_capability_t above) supported by this device. This list must not - * change after the device has been loaded. - * - * Parameters: - * outCount - if outCapabilities was NULL, the number of capabilities - * which would have been returned; if outCapabilities was not NULL, - * the number of capabilities returned, which must not exceed the - * value stored in outCount prior to the call - * outCapabilities - a list of capabilities supported by this device; may - * be NULL, in which case this function must write into outCount the - * number of capabilities which would have been written into - * outCapabilities - */ - void (*getCapabilities)(struct gralloc1_device* device, uint32_t* outCount, - int32_t* /*gralloc1_capability_t*/ outCapabilities); - - /* getFunction(..., descriptor) - * - * Returns a function pointer which implements the requested description. - * - * Parameters: - * descriptor - the function to return - * - * Returns either a function pointer implementing the requested descriptor - * or NULL if the described function is not supported by this device. - */ - gralloc1_function_pointer_t (*getFunction)(struct gralloc1_device* device, - int32_t /*gralloc1_function_descriptor_t*/ descriptor); -} gralloc1_device_t; - -static inline int gralloc1_open(const struct hw_module_t* module, - gralloc1_device_t** device) { - return module->methods->open(module, GRALLOC_HARDWARE_MODULE_ID, - TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int gralloc1_close(gralloc1_device_t* device) { - return device->common.close(&device->common); -} - -/* dump(..., outSize, outBuffer) - * Function descriptor: GRALLOC1_FUNCTION_DUMP - * Must be provided by all gralloc1 devices - * - * Retrieves implementation-defined debug information, which will be displayed - * during, for example, `dumpsys SurfaceFlinger`. - * - * If called with outBuffer == NULL, the device should store a copy of the - * desired output and return its length in bytes in outSize. If the device - * already has a stored copy, that copy should be purged and replaced with a - * fresh copy. - * - * If called with outBuffer != NULL, the device should copy its stored version - * of the output into outBuffer and store how many bytes of data it copied into - * outSize. Prior to this call, the client will have populated outSize with the - * maximum number of bytes outBuffer can hold. The device must not write more - * than this amount into outBuffer. If the device does not currently have a - * stored copy, then it should return 0 in outSize. - * - * Any data written into outBuffer need not be null-terminated. - * - * Parameters: - * outSize - if outBuffer was NULL, the number of bytes needed to copy the - * device's stored output; if outBuffer was not NULL, the number of bytes - * written into it, which must not exceed the value stored in outSize - * prior to the call; pointer will be non-NULL - * outBuffer - the buffer to write the dump output into; may be NULL as - * described above; data written into this buffer need not be - * null-terminated - */ -typedef void (*GRALLOC1_PFN_DUMP)(gralloc1_device_t* device, uint32_t* outSize, - char* outBuffer); - -/* - * Buffer descriptor lifecycle functions - * - * All of these functions take as their first parameter a device pointer, so - * this parameter is omitted from the described parameter lists. - */ - -/* createDescriptor(..., outDescriptor) - * Function descriptor: GRALLOC1_FUNCTION_CREATE_DESCRIPTOR - * Must be provided by all gralloc1 devices - * - * Creates a new, empty buffer descriptor. - * - * Parameters: - * outDescriptor - the new buffer descriptor - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_NO_RESOURCES - no more descriptors can currently be created - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_CREATE_DESCRIPTOR)( - gralloc1_device_t* device, gralloc1_buffer_descriptor_t* outDescriptor); - -/* destroyDescriptor(..., descriptor) - * Function descriptor: GRALLOC1_FUNCTION_DESTROY_DESCRIPTOR - * Must be provided by all gralloc1 devices - * - * Destroys an existing buffer descriptor. - * - * Parameters: - * descriptor - the buffer descriptor to destroy - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_DESCRIPTOR - descriptor does not refer to a valid - * buffer descriptor - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_DESTROY_DESCRIPTOR)( - gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor); - -/* - * Buffer descriptor modification functions - * - * All of these functions take as their first two parameters a device pointer - * and a buffer descriptor, so these parameters are omitted from the described - * parameter lists. - */ - -/* setConsumerUsage(..., usage) - * Function descriptor: GRALLOC1_FUNCTION_SET_CONSUMER_USAGE - * Must be provided by all gralloc1 devices - * - * Sets the desired consumer usage flags of the buffer. - * - * Valid usage flags can be found in the definition of gralloc1_consumer_usage_t - * above. - * - * Parameters: - * usage - the desired consumer usage flags - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid - * GRALLOC1_ERROR_BAD_VALUE - an invalid usage flag was passed in - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_CONSUMER_USAGE)( - gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, - uint64_t /*gralloc1_consumer_usage_t*/ usage); - -/* setDimensions(..., width, height) - * Function descriptor: GRALLOC1_FUNCTION_SET_DIMENSIONS - * Must be provided by all gralloc1 devices - * - * Sets the desired width and height of the buffer in pixels. - * - * The width specifies how many columns of pixels should be in the allocated - * buffer, but does not necessarily represent the offset in columns between the - * same column in adjacent rows. If this offset is required, consult getStride - * below. - * - * The height specifies how many rows of pixels should be in the allocated - * buffer. - * - * Parameters: - * width - the desired width in pixels - * height - the desired height in pixels - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_DIMENSIONS)( - gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, - uint32_t width, uint32_t height); - -/* setFormat(..., format) - * Function descriptor: GRALLOC1_FUNCTION_SET_FORMAT - * Must be provided by all gralloc1 devices - * - * Sets the desired format of the buffer. - * - * The valid formats can be found in <system/graphics.h>. - * - * Parameters: - * format - the desired format - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid - * GRALLOC1_ERROR_BAD_VALUE - format is invalid - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_FORMAT)( - gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, - int32_t /*android_pixel_format_t*/ format); - -/* setLayerCount(..., layerCount) - * Function descriptor: GRALLOC1_FUNCTION_SET_LAYER_COUNT - * Must be provided by all gralloc1 devices that provide the - * GRALLOC1_CAPABILITY_LAYERED_BUFFERS capability. - * - * Sets the number of layers in the buffer. - * - * A buffer with multiple layers may be used as the backing store of an array - * texture. All layers of a buffer share the same characteristics (e.g., - * dimensions, format, usage). Devices that do not support - * GRALLOC1_CAPABILITY_LAYERED_BUFFERS must allocate only buffers with a single - * layer. - * - * Parameters: - * layerCount - the desired number of layers, must be non-zero - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid - * GRALLOC1_ERROR_BAD_VALUE - the layer count is invalid - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_LAYER_COUNT)( - gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, - uint32_t layerCount); - -/* setProducerUsage(..., usage) - * Function descriptor: GRALLOC1_FUNCTION_SET_PRODUCER_USAGE - * Must be provided by all gralloc1 devices - * - * Sets the desired producer usage flags of the buffer. - * - * Valid usage flags can be found in the definition of gralloc1_producer_usage_t - * above. - * - * Parameters: - * usage - the desired producer usage flags - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid - * GRALLOC1_ERROR_BAD_VALUE - an invalid usage flag was passed in - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_PRODUCER_USAGE)( - gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, - uint64_t /*gralloc1_producer_usage_t*/ usage); - -/* - * Buffer handle query functions - * - * All of these functions take as their first two parameters a device pointer - * and a buffer handle, so these parameters are omitted from the described - * parameter lists. - * - * [1] Currently many of these functions may return GRALLOC1_ERROR_UNSUPPORTED, - * which means that the device is not able to retrieve the requested information - * from the buffer. This is necessary to enable a smooth transition from earlier - * versions of the gralloc HAL, but gralloc1 implementers are strongly - * discouraged from returning this value, as future versions of the platform - * code will require all of these functions to succeed given a valid handle. - */ - -/* getBackingStore(..., outStore) - * Function descriptor: GRALLOC1_FUNCTION_GET_BACKING_STORE - * Must be provided by all gralloc1 devices - * - * Gets a value that uniquely identifies the backing store of the given buffer. - * - * Buffers which share a backing store should return the same value from this - * function. If the buffer is present in more than one process, the backing - * store value for that buffer is not required to be the same in every process. - * - * Parameters: - * outStore - the backing store identifier for this buffer - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the - * backing store identifier from the buffer; see note [1] in this - * section's header for more information - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_BACKING_STORE)( - gralloc1_device_t* device, buffer_handle_t buffer, - gralloc1_backing_store_t* outStore); - -/* getConsumerUsage(..., outUsage) - * Function descriptor: GRALLOC1_FUNCTION_GET_CONSUMER_USAGE - * Must be provided by all gralloc1 devices - * - * Gets the consumer usage flags which were used to allocate this buffer. - * - * Usage flags can be found in the definition of gralloc1_consumer_usage_t above - * - * Parameters: - * outUsage - the consumer usage flags used to allocate this buffer; must be - * non-NULL - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the - * dimensions from the buffer; see note [1] in this section's header for - * more information - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_CONSUMER_USAGE)( - gralloc1_device_t* device, buffer_handle_t buffer, - uint64_t* /*gralloc1_consumer_usage_t*/ outUsage); - -/* getDimensions(..., outWidth, outHeight) - * Function descriptor: GRALLOC1_FUNCTION_GET_DIMENSIONS - * Must be provided by all gralloc1 devices - * - * Gets the width and height of the buffer in pixels. - * - * See setDimensions for more information about these values. - * - * Parameters: - * outWidth - the width of the buffer in pixels, must be non-NULL - * outHeight - the height of the buffer in pixels, must be non-NULL - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the - * dimensions from the buffer; see note [1] in this section's header for - * more information - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_DIMENSIONS)( - gralloc1_device_t* device, buffer_handle_t buffer, uint32_t* outWidth, - uint32_t* outHeight); - -/* getFormat(..., outFormat) - * Function descriptor: GRALLOC1_FUNCTION_GET_FORMAT - * Must be provided by all gralloc1 devices - * - * Gets the format of the buffer. - * - * The valid formats can be found in the HAL_PIXEL_FORMAT_* enum in - * system/graphics.h. - * - * Parameters: - * outFormat - the format of the buffer; must be non-NULL - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the format - * from the buffer; see note [1] in this section's header for more - * information - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_FORMAT)( - gralloc1_device_t* device, buffer_handle_t descriptor, - int32_t* outFormat); - -/* getLayerCount(..., outLayerCount) - * Function descriptor: GRALLOC1_FUNCTION_GET_LAYER_COUNT - * Must be provided by all gralloc1 devices that provide the - * GRALLOC1_CAPABILITY_LAYERED_BUFFERS capability. - * - * Gets the number of layers of the buffer. - * - * See setLayerCount for more information about this value. - * - * Parameters: - * outLayerCount - the number of layers in the image, must be non-NULL - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the - * layer count from the buffer; see note [1] in this section's header for - * more information - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_LAYER_COUNT)( - gralloc1_device_t* device, buffer_handle_t buffer, - uint32_t* outLayerCount); - -/* getProducerUsage(..., outUsage) - * Function descriptor: GRALLOC1_FUNCTION_GET_PRODUCER_USAGE - * Must be provided by all gralloc1 devices - * - * Gets the producer usage flags which were used to allocate this buffer. - * - * Usage flags can be found in the definition of gralloc1_producer_usage_t above - * - * Parameters: - * outUsage - the producer usage flags used to allocate this buffer; must be - * non-NULL - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the usage - * from the buffer; see note [1] in this section's header for more - * information - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_PRODUCER_USAGE)( - gralloc1_device_t* device, buffer_handle_t buffer, - uint64_t* /*gralloc1_producer_usage_t*/ outUsage); - -/* getStride(..., outStride) - * Function descriptor: GRALLOC1_FUNCTION_GET_STRIDE - * Must be provided by all gralloc1 devices - * - * Gets the stride of the buffer in pixels. - * - * The stride is the offset in pixel-sized elements between the same column in - * two adjacent rows of pixels. This may not be equal to the width of the - * buffer. - * - * Parameters: - * outStride - the stride in pixels; must be non-NULL - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_UNDEFINED - the notion of a stride is not meaningful for - * this format - * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the stride - * from the descriptor; see note [1] in this section's header for more - * information - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_STRIDE)( - gralloc1_device_t* device, buffer_handle_t buffer, uint32_t* outStride); - -/* getTransportSize(..., outNumFds, outNumInts) - * Function descriptor: GRALLOC1_FUNCTION_GET_TRANSPORT_SIZE - * - * Get the transport size of a buffer. An imported buffer handle is a raw - * buffer handle with the process-local runtime data appended. This - * function, for example, allows a caller to omit the process-local - * runtime data at the tail when serializing the imported buffer handle. - * - * Note that a client might or might not omit the process-local runtime - * data when sending an imported buffer handle. The mapper must support - * both cases on the receiving end. - * - * Parameters: - * outNumFds - the number of file descriptors needed for transport - * outNumInts - the number of integers needed for transport - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the numFds - * and numInts; see note [1] in this section's header for more information - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_TRANSPORT_SIZE)( - gralloc1_device_t* device, buffer_handle_t buffer, uint32_t *outNumFds, - uint32_t *outNumInts); - -typedef struct gralloc1_buffer_descriptor_info { - uint32_t width; - uint32_t height; - uint32_t layerCount; - int32_t /*android_pixel_format_t*/ format; - uint64_t producerUsage; - uint64_t consumerUsage; -} gralloc1_buffer_descriptor_info_t; - -/* validateBufferSize(..., ) - * Function descriptor: GRALLOC1_FUNCTION_VALIDATE_BUFFER_SIZE - * - * Validate that the buffer can be safely accessed by a caller who assumes - * the specified descriptorInfo and stride. This must at least validate - * that the buffer size is large enough. Validating the buffer against - * individual buffer attributes is optional. - * - * Parameters: - * descriptor - specifies the attributes of the buffer - * stride - the buffer stride returned by IAllocator::allocate - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_BAD_VALUE - when buffer cannot be safely accessed - * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to validate the buffer - * size; see note [1] in this section's header for more information - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_VALIDATE_BUFFER_SIZE)( - gralloc1_device_t* device, buffer_handle_t buffer, - const gralloc1_buffer_descriptor_info_t* descriptorInfo, - uint32_t stride); - -/* - * Buffer management functions - */ - -/* allocate(..., numDescriptors, descriptors, outBuffers) - * Function descriptor: GRALLOC1_FUNCTION_ALLOCATE - * Must be provided by all gralloc1 devices - * - * Attempts to allocate a number of buffers sharing a backing store. - * - * Each buffer will correspond to one of the descriptors passed into the - * function. If the device is unable to share the backing store between the - * buffers, it should attempt to allocate the buffers with different backing - * stores and return GRALLOC1_ERROR_NOT_SHARED if it is successful. - * - * If this call is successful, the client is responsible for freeing the - * buffer_handle_t using release() when it is finished with the buffer. It is - * not necessary to call retain() on the returned buffers, as they must have a - * reference added by the device before returning. - * - * If GRALLOC1_CAPABILITY_TEST_ALLOCATE is supported by this device, outBuffers - * may be NULL. In this case, the device must not attempt to allocate any - * buffers, but instead must return either GRALLOC1_ERROR_NONE if such an - * allocation is possible (ignoring potential resource contention which might - * lead to a GRALLOC1_ERROR_NO_RESOURCES error), GRALLOC1_ERROR_NOT_SHARED if - * the buffers can be allocated, but cannot share a backing store, or - * GRALLOC1_ERROR_UNSUPPORTED if one or more of the descriptors can never be - * allocated by the device. - * - * Parameters: - * numDescriptors - the number of buffer descriptors, which must also be equal - * to the size of the outBuffers array - * descriptors - the buffer descriptors to attempt to allocate - * outBuffers - the allocated buffers; must be non-NULL unless the device - * supports GRALLOC1_CAPABILITY_TEST_ALLOCATE (see above), and must not be - * modified by the device if allocation is unsuccessful - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_DESCRIPTOR - one of the descriptors does not refer to a - * valid buffer descriptor - * GRALLOC1_ERROR_NOT_SHARED - allocation was successful, but required more - * than one backing store to satisfy all of the buffer descriptors - * GRALLOC1_ERROR_NO_RESOURCES - allocation failed because one or more of the - * backing stores could not be created at this time (but this allocation - * might succeed at a future time) - * GRALLOC1_ERROR_UNSUPPORTED - one or more of the descriptors can never be - * satisfied by the device - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_ALLOCATE)( - gralloc1_device_t* device, uint32_t numDescriptors, - const gralloc1_buffer_descriptor_t* descriptors, - buffer_handle_t* outBuffers); - -/* importBuffer(..., rawHandle, outBuffer); - * Function descriptor: GRALLOC1_FUNCTION_IMPORT_BUFFER - * This function is optional for all gralloc1 devices. - * When supported, GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE must also be - * supported. - * - * Explictly imports a buffer into a proccess. - * - * This function can be called in place of retain when a raw buffer handle is - * received by a remote process. Import producess a import handle that can - * be used to access the underlying graphic buffer. The new import handle has a - * ref count of 1. - * - * This function must at least validate the raw handle before creating the - * imported handle. It must also support importing the same raw handle - * multiple times to create multiple imported handles. The imported handle - * must be considered valid everywhere in the process. - * - * Parameters: - * rawHandle - the raw buffer handle to import - * outBuffer - a handle to the newly imported buffer - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_NO_RESOURCES - it is not possible to add a import to this - * buffer at this time - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_IMPORT_BUFFER)( - gralloc1_device_t* device, const buffer_handle_t rawHandle, - buffer_handle_t* outBuffer); - -/* retain(..., buffer) - * Function descriptor: GRALLOC1_FUNCTION_RETAIN - * Must be provided by all gralloc1 devices - * - * Adds a reference to the given buffer. - * - * This function must be called when a buffer_handle_t is received from a remote - * process to prevent the buffer's data from being freed when the remote process - * releases the buffer. It may also be called to increase the reference count if - * two components in the same process want to interact with the buffer - * independently. - * - * Parameters: - * buffer - the buffer to which a reference should be added - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_NO_RESOURCES - it is not possible to add a reference to this - * buffer at this time - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RETAIN)( - gralloc1_device_t* device, buffer_handle_t buffer); - -/* release(..., buffer) - * Function descriptor: GRALLOC1_FUNCTION_RELEASE - * Must be provided by all gralloc1 devices - * - * Removes a reference from the given buffer. - * - * If no references remain, the buffer should be freed. When the last buffer - * referring to a particular backing store is freed, that backing store should - * also be freed. - * - * When GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE is supported, - * native_handle_close and native_handle_delete must always be called by the - * implementation whenever the last reference is removed. Otherwise, a call - * to release() will be followed by native_handle_close and native_handle_delete - * by the caller when the buffer is not allocated locally through allocate(). - * - * Parameters: - * buffer - the buffer from which a reference should be removed - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RELEASE)( - gralloc1_device_t* device, buffer_handle_t buffer); - -/* - * Buffer access functions - * - * All of these functions take as their first parameter a device pointer, so - * this parameter is omitted from the described parameter lists. - */ - -typedef struct gralloc1_rect { - int32_t left; - int32_t top; - int32_t width; - int32_t height; -} gralloc1_rect_t; - -/* getNumFlexPlanes(..., buffer, outNumPlanes) - * Function descriptor: GRALLOC1_FUNCTION_GET_NUM_FLEX_PLANES - * Must be provided by all gralloc1 devices - * - * Returns the number of flex layout planes which are needed to represent the - * given buffer. This may be used to efficiently allocate only as many plane - * structures as necessary before calling into lockFlex. - * - * If the given buffer cannot be locked as a flex format, this function may - * return GRALLOC1_ERROR_UNSUPPORTED (as lockFlex would). - * - * Parameters: - * buffer - the buffers for which the number of planes should be queried - * outNumPlanes - the number of flex planes required to describe the given - * buffer; must be non-NULL - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_UNSUPPORTED - the buffer's format cannot be represented in a - * flex layout - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_NUM_FLEX_PLANES)( - gralloc1_device_t* device, buffer_handle_t buffer, - uint32_t* outNumPlanes); - -/* lock(..., buffer, producerUsage, consumerUsage, accessRegion, outData, - * acquireFence) - * Function descriptor: GRALLOC1_FUNCTION_LOCK - * Must be provided by all gralloc1 devices - * - * Locks the given buffer for the specified CPU usage. - * - * Exactly one of producerUsage and consumerUsage must be *_USAGE_NONE. The - * usage which is not *_USAGE_NONE must be one of the *_USAGE_CPU_* values, as - * applicable. Locking a buffer for a non-CPU usage is not supported. - * - * Locking the same buffer simultaneously from multiple threads is permitted, - * but if any of the threads attempt to lock the buffer for writing, the - * behavior is undefined, except that it must not cause process termination or - * block the client indefinitely. Leaving the buffer content in an indeterminate - * state or returning an error are both acceptable. - * - * The client must not modify the content of the buffer outside of accessRegion, - * and the device need not guarantee that content outside of accessRegion is - * valid for reading. The result of reading or writing outside of accessRegion - * is undefined, except that it must not cause process termination. - * - * outData must be a non-NULL pointer, the contents of which which will be - * filled with a pointer to the locked buffer memory. This address will - * represent the top-left corner of the entire buffer, even if accessRegion does - * not begin at the top-left corner. - * - * acquireFence is a file descriptor referring to a acquire sync fence object, - * which will be signaled when it is safe for the device to access the contents - * of the buffer (prior to locking). If it is already safe to access the buffer - * contents, -1 may be passed instead. - * - * Parameters: - * buffer - the buffer to lock - * producerUsage - the producer usage flags to request; either this or - * consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a - * CPU usage - * consumerUsage - the consumer usage flags to request; either this or - * producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a - * CPU usage - * accessRegion - the portion of the buffer that the client intends to access; - * must be non-NULL - * outData - will be filled with a CPU-accessible pointer to the buffer data; - * must be non-NULL - * acquireFence - a sync fence file descriptor as described above - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and - * consumerUsage were GRALLOC1_*_USAGE_NONE, or the usage which was not - * *_USAGE_NONE was not a CPU usage - * GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but - * locking may succeed at a future time - * GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given - * usage, and any future attempts at locking will also fail - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK)( - gralloc1_device_t* device, buffer_handle_t buffer, - uint64_t /*gralloc1_producer_usage_t*/ producerUsage, - uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage, - const gralloc1_rect_t* accessRegion, void** outData, - int32_t acquireFence); - -/* lockFlex(..., buffer, producerUsage, consumerUsage, accessRegion, - * outFlexLayout, outAcquireFence) - * Function descriptor: GRALLOC1_FUNCTION_LOCK_FLEX - * Must be provided by all gralloc1 devices - * - * This is largely the same as lock(), except that instead of returning a - * pointer directly to the buffer data, it returns an android_flex_layout - * struct describing how to access the data planes. - * - * This function must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888 if - * supported by the device, as well as with any other formats requested by - * multimedia codecs when they are configured with a flexible-YUV-compatible - * color format. - * - * This function may also be called on buffers of other formats, including - * non-YUV formats, but if the buffer format is not compatible with a flexible - * representation, it may return GRALLOC1_ERROR_UNSUPPORTED. - * - * Parameters: - * buffer - the buffer to lock - * producerUsage - the producer usage flags to request; either this or - * consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a - * CPU usage - * consumerUsage - the consumer usage flags to request; either this or - * producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a - * CPU usage - * accessRegion - the portion of the buffer that the client intends to access; - * must be non-NULL - * outFlexLayout - will be filled with the description of the planes in the - * buffer - * acquireFence - a sync fence file descriptor as described in lock() - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - * GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and - * consumerUsage were *_USAGE_NONE, or the usage which was not - * *_USAGE_NONE was not a CPU usage - * GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but - * locking may succeed at a future time - * GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given - * usage, and any future attempts at locking will also fail - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK_FLEX)( - gralloc1_device_t* device, buffer_handle_t buffer, - uint64_t /*gralloc1_producer_usage_t*/ producerUsage, - uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage, - const gralloc1_rect_t* accessRegion, - struct android_flex_layout* outFlexLayout, int32_t acquireFence); - -/* unlock(..., buffer, releaseFence) - * Function descriptor: GRALLOC1_FUNCTION_UNLOCK - * Must be provided by all gralloc1 devices - * - * This function indicates to the device that the client will be done with the - * buffer when releaseFence signals. - * - * outReleaseFence will be filled with a file descriptor referring to a release - * sync fence object, which will be signaled when it is safe to access the - * contents of the buffer (after the buffer has been unlocked). If it is already - * safe to access the buffer contents, then -1 may be returned instead. - * - * This function is used to unlock both buffers locked by lock() and those - * locked by lockFlex(). - * - * Parameters: - * buffer - the buffer to unlock - * outReleaseFence - a sync fence file descriptor as described above - * - * Returns GRALLOC1_ERROR_NONE or one of the following errors: - * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid - */ -typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_UNLOCK)( - gralloc1_device_t* device, buffer_handle_t buffer, - int32_t* outReleaseFence); - -__END_DECLS - -#endif +../../include_all/hardware/gralloc1.h
\ No newline at end of file diff --git a/include/hardware/hardware.h b/include/hardware/hardware.h index bf076f6c..dd9251a5 100644..120000 --- a/include/hardware/hardware.h +++ b/include/hardware/hardware.h @@ -1,244 +1 @@ -/* - * Copyright (C) 2008 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_INCLUDE_HARDWARE_HARDWARE_H -#define ANDROID_INCLUDE_HARDWARE_HARDWARE_H - -#include <stdint.h> -#include <sys/cdefs.h> - -#include <cutils/native_handle.h> -#include <system/graphics.h> - -__BEGIN_DECLS - -/* - * Value for the hw_module_t.tag field - */ - -#define MAKE_TAG_CONSTANT(A,B,C,D) (((A) << 24) | ((B) << 16) | ((C) << 8) | (D)) - -#define HARDWARE_MODULE_TAG MAKE_TAG_CONSTANT('H', 'W', 'M', 'T') -#define HARDWARE_DEVICE_TAG MAKE_TAG_CONSTANT('H', 'W', 'D', 'T') - -#define HARDWARE_MAKE_API_VERSION(maj,min) \ - ((((maj) & 0xff) << 8) | ((min) & 0xff)) - -#define HARDWARE_MAKE_API_VERSION_2(maj,min,hdr) \ - ((((maj) & 0xff) << 24) | (((min) & 0xff) << 16) | ((hdr) & 0xffff)) -#define HARDWARE_API_VERSION_2_MAJ_MIN_MASK 0xffff0000 -#define HARDWARE_API_VERSION_2_HEADER_MASK 0x0000ffff - - -/* - * The current HAL API version. - * - * All module implementations must set the hw_module_t.hal_api_version field - * to this value when declaring the module with HAL_MODULE_INFO_SYM. - * - * Note that previous implementations have always set this field to 0. - * Therefore, libhardware HAL API will always consider versions 0.0 and 1.0 - * to be 100% binary compatible. - * - */ -#define HARDWARE_HAL_API_VERSION HARDWARE_MAKE_API_VERSION(1, 0) - -/* - * Helper macros for module implementors. - * - * The derived modules should provide convenience macros for supported - * versions so that implementations can explicitly specify module/device - * versions at definition time. - * - * Use this macro to set the hw_module_t.module_api_version field. - */ -#define HARDWARE_MODULE_API_VERSION(maj,min) HARDWARE_MAKE_API_VERSION(maj,min) -#define HARDWARE_MODULE_API_VERSION_2(maj,min,hdr) HARDWARE_MAKE_API_VERSION_2(maj,min,hdr) - -/* - * Use this macro to set the hw_device_t.version field - */ -#define HARDWARE_DEVICE_API_VERSION(maj,min) HARDWARE_MAKE_API_VERSION(maj,min) -#define HARDWARE_DEVICE_API_VERSION_2(maj,min,hdr) HARDWARE_MAKE_API_VERSION_2(maj,min,hdr) - -struct hw_module_t; -struct hw_module_methods_t; -struct hw_device_t; - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -typedef struct hw_module_t { - /** tag must be initialized to HARDWARE_MODULE_TAG */ - uint32_t tag; - - /** - * The API version of the implemented module. The module owner is - * responsible for updating the version when a module interface has - * changed. - * - * The derived modules such as gralloc and audio own and manage this field. - * The module user must interpret the version field to decide whether or - * not to inter-operate with the supplied module implementation. - * For example, SurfaceFlinger is responsible for making sure that - * it knows how to manage different versions of the gralloc-module API, - * and AudioFlinger must know how to do the same for audio-module API. - * - * The module API version should include a major and a minor component. - * For example, version 1.0 could be represented as 0x0100. This format - * implies that versions 0x0100-0x01ff are all API-compatible. - * - * In the future, libhardware will expose a hw_get_module_version() - * (or equivalent) function that will take minimum/maximum supported - * versions as arguments and would be able to reject modules with - * versions outside of the supplied range. - */ - uint16_t module_api_version; -#define version_major module_api_version - /** - * version_major/version_minor defines are supplied here for temporary - * source code compatibility. They will be removed in the next version. - * ALL clients must convert to the new version format. - */ - - /** - * The API version of the HAL module interface. This is meant to - * version the hw_module_t, hw_module_methods_t, and hw_device_t - * structures and definitions. - * - * The HAL interface owns this field. Module users/implementations - * must NOT rely on this value for version information. - * - * Presently, 0 is the only valid value. - */ - uint16_t hal_api_version; -#define version_minor hal_api_version - - /** Identifier of module */ - const char *id; - - /** Name of this module */ - const char *name; - - /** Author/owner/implementor of the module */ - const char *author; - - /** Modules methods */ - struct hw_module_methods_t* methods; - - /** module's dso */ - void* dso; - -#ifdef __LP64__ - uint64_t reserved[32-7]; -#else - /** padding to 128 bytes, reserved for future use */ - uint32_t reserved[32-7]; -#endif - -} hw_module_t; - -typedef struct hw_module_methods_t { - /** Open a specific device */ - int (*open)(const struct hw_module_t* module, const char* id, - struct hw_device_t** device); - -} hw_module_methods_t; - -/** - * Every device data structure must begin with hw_device_t - * followed by module specific public methods and attributes. - */ -typedef struct hw_device_t { - /** tag must be initialized to HARDWARE_DEVICE_TAG */ - uint32_t tag; - - /** - * Version of the module-specific device API. This value is used by - * the derived-module user to manage different device implementations. - * - * The module user is responsible for checking the module_api_version - * and device version fields to ensure that the user is capable of - * communicating with the specific module implementation. - * - * One module can support multiple devices with different versions. This - * can be useful when a device interface changes in an incompatible way - * but it is still necessary to support older implementations at the same - * time. One such example is the Camera 2.0 API. - * - * This field is interpreted by the module user and is ignored by the - * HAL interface itself. - */ - uint32_t version; - - /** reference to the module this device belongs to */ - struct hw_module_t* module; - - /** padding reserved for future use */ -#ifdef __LP64__ - uint64_t reserved[12]; -#else - uint32_t reserved[12]; -#endif - - /** Close this device */ - int (*close)(struct hw_device_t* device); - -} hw_device_t; - -#ifdef __cplusplus -#define TO_HW_DEVICE_T_OPEN(x) reinterpret_cast<struct hw_device_t**>(x) -#else -#define TO_HW_DEVICE_T_OPEN(x) (struct hw_device_t**)(x) -#endif - -/** - * Name of the hal_module_info - */ -#define HAL_MODULE_INFO_SYM HMI - -/** - * Name of the hal_module_info as a string - */ -#define HAL_MODULE_INFO_SYM_AS_STR "HMI" - -/** - * Get the module info associated with a module by id. - * - * @return: 0 == success, <0 == error and *module == NULL - */ -int hw_get_module(const char *id, const struct hw_module_t **module); - -/** - * Get the module info associated with a module instance by class 'class_id' - * and instance 'inst'. - * - * Some modules types necessitate multiple instances. For example audio supports - * multiple concurrent interfaces and thus 'audio' is the module class - * and 'primary' or 'a2dp' are module interfaces. This implies that the files - * providing these modules would be named audio.primary.<variant>.so and - * audio.a2dp.<variant>.so - * - * @return: 0 == success, <0 == error and *module == NULL - */ -int hw_get_module_by_class(const char *class_id, const char *inst, - const struct hw_module_t **module); - -__END_DECLS - -#endif /* ANDROID_INCLUDE_HARDWARE_HARDWARE_H */ +../../include_all/hardware/hardware.h
\ No newline at end of file diff --git a/include/hardware/hdmi_cec.h b/include/hardware/hdmi_cec.h index aa06384e..9b40a10e 100644..120000 --- a/include/hardware/hdmi_cec.h +++ b/include/hardware/hdmi_cec.h @@ -1,429 +1 @@ -/* - * Copyright (C) 2014 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_INCLUDE_HARDWARE_HDMI_CEC_H -#define ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H - -#include <stdint.h> -#include <sys/cdefs.h> - -#include <hardware/hardware.h> - -__BEGIN_DECLS - -#define HDMI_CEC_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) -#define HDMI_CEC_MODULE_API_VERSION_CURRENT HDMI_MODULE_API_VERSION_1_0 - -#define HDMI_CEC_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) -#define HDMI_CEC_DEVICE_API_VERSION_CURRENT HDMI_DEVICE_API_VERSION_1_0 - -#define HDMI_CEC_HARDWARE_MODULE_ID "hdmi_cec" -#define HDMI_CEC_HARDWARE_INTERFACE "hdmi_cec_hw_if" - -typedef enum cec_device_type { - CEC_DEVICE_INACTIVE = -1, - CEC_DEVICE_TV = 0, - CEC_DEVICE_RECORDER = 1, - CEC_DEVICE_RESERVED = 2, - CEC_DEVICE_TUNER = 3, - CEC_DEVICE_PLAYBACK = 4, - CEC_DEVICE_AUDIO_SYSTEM = 5, - CEC_DEVICE_MAX = CEC_DEVICE_AUDIO_SYSTEM -} cec_device_type_t; - -typedef enum cec_logical_address { - CEC_ADDR_TV = 0, - CEC_ADDR_RECORDER_1 = 1, - CEC_ADDR_RECORDER_2 = 2, - CEC_ADDR_TUNER_1 = 3, - CEC_ADDR_PLAYBACK_1 = 4, - CEC_ADDR_AUDIO_SYSTEM = 5, - CEC_ADDR_TUNER_2 = 6, - CEC_ADDR_TUNER_3 = 7, - CEC_ADDR_PLAYBACK_2 = 8, - CEC_ADDR_RECORDER_3 = 9, - CEC_ADDR_TUNER_4 = 10, - CEC_ADDR_PLAYBACK_3 = 11, - CEC_ADDR_RESERVED_1 = 12, - CEC_ADDR_RESERVED_2 = 13, - CEC_ADDR_FREE_USE = 14, - CEC_ADDR_UNREGISTERED = 15, - CEC_ADDR_BROADCAST = 15 -} cec_logical_address_t; - -/* - * HDMI CEC messages - */ -enum cec_message_type { - CEC_MESSAGE_FEATURE_ABORT = 0x00, - CEC_MESSAGE_IMAGE_VIEW_ON = 0x04, - CEC_MESSAGE_TUNER_STEP_INCREMENT = 0x05, - CEC_MESSAGE_TUNER_STEP_DECREMENT = 0x06, - CEC_MESSAGE_TUNER_DEVICE_STATUS = 0x07, - CEC_MESSAGE_GIVE_TUNER_DEVICE_STATUS = 0x08, - CEC_MESSAGE_RECORD_ON = 0x09, - CEC_MESSAGE_RECORD_STATUS = 0x0A, - CEC_MESSAGE_RECORD_OFF = 0x0B, - CEC_MESSAGE_TEXT_VIEW_ON = 0x0D, - CEC_MESSAGE_RECORD_TV_SCREEN = 0x0F, - CEC_MESSAGE_GIVE_DECK_STATUS = 0x1A, - CEC_MESSAGE_DECK_STATUS = 0x1B, - CEC_MESSAGE_SET_MENU_LANGUAGE = 0x32, - CEC_MESSAGE_CLEAR_ANALOG_TIMER = 0x33, - CEC_MESSAGE_SET_ANALOG_TIMER = 0x34, - CEC_MESSAGE_TIMER_STATUS = 0x35, - CEC_MESSAGE_STANDBY = 0x36, - CEC_MESSAGE_PLAY = 0x41, - CEC_MESSAGE_DECK_CONTROL = 0x42, - CEC_MESSAGE_TIMER_CLEARED_STATUS = 0x043, - CEC_MESSAGE_USER_CONTROL_PRESSED = 0x44, - CEC_MESSAGE_USER_CONTROL_RELEASED = 0x45, - CEC_MESSAGE_GIVE_OSD_NAME = 0x46, - CEC_MESSAGE_SET_OSD_NAME = 0x47, - CEC_MESSAGE_SET_OSD_STRING = 0x64, - CEC_MESSAGE_SET_TIMER_PROGRAM_TITLE = 0x67, - CEC_MESSAGE_SYSTEM_AUDIO_MODE_REQUEST = 0x70, - CEC_MESSAGE_GIVE_AUDIO_STATUS = 0x71, - CEC_MESSAGE_SET_SYSTEM_AUDIO_MODE = 0x72, - CEC_MESSAGE_REPORT_AUDIO_STATUS = 0x7A, - CEC_MESSAGE_GIVE_SYSTEM_AUDIO_MODE_STATUS = 0x7D, - CEC_MESSAGE_SYSTEM_AUDIO_MODE_STATUS = 0x7E, - CEC_MESSAGE_ROUTING_CHANGE = 0x80, - CEC_MESSAGE_ROUTING_INFORMATION = 0x81, - CEC_MESSAGE_ACTIVE_SOURCE = 0x82, - CEC_MESSAGE_GIVE_PHYSICAL_ADDRESS = 0x83, - CEC_MESSAGE_REPORT_PHYSICAL_ADDRESS = 0x84, - CEC_MESSAGE_REQUEST_ACTIVE_SOURCE = 0x85, - CEC_MESSAGE_SET_STREAM_PATH = 0x86, - CEC_MESSAGE_DEVICE_VENDOR_ID = 0x87, - CEC_MESSAGE_VENDOR_COMMAND = 0x89, - CEC_MESSAGE_VENDOR_REMOTE_BUTTON_DOWN = 0x8A, - CEC_MESSAGE_VENDOR_REMOTE_BUTTON_UP = 0x8B, - CEC_MESSAGE_GIVE_DEVICE_VENDOR_ID = 0x8C, - CEC_MESSAGE_MENU_REQUEST = 0x8D, - CEC_MESSAGE_MENU_STATUS = 0x8E, - CEC_MESSAGE_GIVE_DEVICE_POWER_STATUS = 0x8F, - CEC_MESSAGE_REPORT_POWER_STATUS = 0x90, - CEC_MESSAGE_GET_MENU_LANGUAGE = 0x91, - CEC_MESSAGE_SELECT_ANALOG_SERVICE = 0x92, - CEC_MESSAGE_SELECT_DIGITAL_SERVICE = 0x93, - CEC_MESSAGE_SET_DIGITAL_TIMER = 0x97, - CEC_MESSAGE_CLEAR_DIGITAL_TIMER = 0x99, - CEC_MESSAGE_SET_AUDIO_RATE = 0x9A, - CEC_MESSAGE_INACTIVE_SOURCE = 0x9D, - CEC_MESSAGE_CEC_VERSION = 0x9E, - CEC_MESSAGE_GET_CEC_VERSION = 0x9F, - CEC_MESSAGE_VENDOR_COMMAND_WITH_ID = 0xA0, - CEC_MESSAGE_CLEAR_EXTERNAL_TIMER = 0xA1, - CEC_MESSAGE_SET_EXTERNAL_TIMER = 0xA2, - CEC_MESSAGE_INITIATE_ARC = 0xC0, - CEC_MESSAGE_REPORT_ARC_INITIATED = 0xC1, - CEC_MESSAGE_REPORT_ARC_TERMINATED = 0xC2, - CEC_MESSAGE_REQUEST_ARC_INITIATION = 0xC3, - CEC_MESSAGE_REQUEST_ARC_TERMINATION = 0xC4, - CEC_MESSAGE_TERMINATE_ARC = 0xC5, - CEC_MESSAGE_ABORT = 0xFF -}; - -/* - * Operand description [Abort Reason] - */ -enum abort_reason { - ABORT_UNRECOGNIZED_MODE = 0, - ABORT_NOT_IN_CORRECT_MODE = 1, - ABORT_CANNOT_PROVIDE_SOURCE = 2, - ABORT_INVALID_OPERAND = 3, - ABORT_REFUSED = 4, - ABORT_UNABLE_TO_DETERMINE = 5 -}; - -/* - * HDMI event type. used for hdmi_event_t. - */ -enum { - HDMI_EVENT_CEC_MESSAGE = 1, - HDMI_EVENT_HOT_PLUG = 2, -}; - -/* - * HDMI hotplug event type. Used when the event - * type is HDMI_EVENT_HOT_PLUG. - */ -enum { - HDMI_NOT_CONNECTED = 0, - HDMI_CONNECTED = 1 -}; - -/* - * error code used for send_message. - */ -enum { - HDMI_RESULT_SUCCESS = 0, - HDMI_RESULT_NACK = 1, /* not acknowledged */ - HDMI_RESULT_BUSY = 2, /* bus is busy */ - HDMI_RESULT_FAIL = 3, -}; - -/* - * HDMI port type. - */ -typedef enum hdmi_port_type { - HDMI_INPUT = 0, - HDMI_OUTPUT = 1 -} hdmi_port_type_t; - -/* - * Flags used for set_option() - */ -enum { - /* When set to false, HAL does not wake up the system upon receiving - * <Image View On> or <Text View On>. Used when user changes the TV - * settings to disable the auto TV on functionality. - * True by default. - */ - HDMI_OPTION_WAKEUP = 1, - - /* When set to false, all the CEC commands are discarded. Used when - * user changes the TV settings to disable CEC functionality. - * True by default. - */ - HDMI_OPTION_ENABLE_CEC = 2, - - /* Setting this flag to false means Android system will stop handling - * CEC service and yield the control over to the microprocessor that is - * powered on through the standby mode. When set to true, the system - * will gain the control over, hence telling the microprocessor to stop - * handling the cec commands. This is called when system goes - * in and out of standby mode to notify the microprocessor that it should - * start/stop handling CEC commands on behalf of the system. - * False by default. - */ - HDMI_OPTION_SYSTEM_CEC_CONTROL = 3, - - /* Option 4 not used */ - - /* Passes the updated language information of Android system. - * Contains 3-byte ASCII code as defined in ISO/FDIS 639-2. Can be - * used for HAL to respond to <Get Menu Language> while in standby mode. - * English(eng), for example, is converted to 0x656e67. - */ - HDMI_OPTION_SET_LANG = 5, -}; - -/* - * Maximum length in bytes of cec message body (exclude header block), - * should not exceed 16 (spec CEC 6 Frame Description) - */ -#define CEC_MESSAGE_BODY_MAX_LENGTH 16 - -typedef struct cec_message { - /* logical address of sender */ - cec_logical_address_t initiator; - - /* logical address of receiver */ - cec_logical_address_t destination; - - /* Length in bytes of body, range [0, CEC_MESSAGE_BODY_MAX_LENGTH] */ - size_t length; - unsigned char body[CEC_MESSAGE_BODY_MAX_LENGTH]; -} cec_message_t; - -typedef struct hotplug_event { - /* - * true if the cable is connected; otherwise false. - */ - int connected; - int port_id; -} hotplug_event_t; - -typedef struct tx_status_event { - int status; - int opcode; /* CEC opcode */ -} tx_status_event_t; - -/* - * HDMI event generated from HAL. - */ -typedef struct hdmi_event { - int type; - struct hdmi_cec_device* dev; - union { - cec_message_t cec; - hotplug_event_t hotplug; - }; -} hdmi_event_t; - -/* - * HDMI port descriptor - */ -typedef struct hdmi_port_info { - hdmi_port_type_t type; - // Port ID should start from 1 which corresponds to HDMI "port 1". - int port_id; - int cec_supported; - int arc_supported; - uint16_t physical_address; -} hdmi_port_info_t; - -/* - * Callback function type that will be called by HAL implementation. - * Services can not close/open the device in the callback. - */ -typedef void (*event_callback_t)(const hdmi_event_t* event, void* arg); - -typedef struct hdmi_cec_module { - /** - * Common methods of the HDMI CEC module. This *must* be the first member of - * hdmi_cec_module as users of this structure will cast a hw_module_t to hdmi_cec_module - * pointer in contexts where it's known the hw_module_t references a hdmi_cec_module. - */ - struct hw_module_t common; -} hdmi_module_t; - -/* - * HDMI-CEC HAL interface definition. - */ -typedef struct hdmi_cec_device { - /** - * Common methods of the HDMI CEC device. This *must* be the first member of - * hdmi_cec_device as users of this structure will cast a hw_device_t to hdmi_cec_device - * pointer in contexts where it's known the hw_device_t references a hdmi_cec_device. - */ - struct hw_device_t common; - - /* - * (*add_logical_address)() passes the logical address that will be used - * in this system. - * - * HAL may use it to configure the hardware so that the CEC commands addressed - * the given logical address can be filtered in. This method can be called - * as many times as necessary in order to support multiple logical devices. - * addr should be in the range of valid logical addresses for the call - * to succeed. - * - * Returns 0 on success or -errno on error. - */ - int (*add_logical_address)(const struct hdmi_cec_device* dev, cec_logical_address_t addr); - - /* - * (*clear_logical_address)() tells HAL to reset all the logical addresses. - * - * It is used when the system doesn't need to process CEC command any more, - * hence to tell HAL to stop receiving commands from the CEC bus, and change - * the state back to the beginning. - */ - void (*clear_logical_address)(const struct hdmi_cec_device* dev); - - /* - * (*get_physical_address)() returns the CEC physical address. The - * address is written to addr. - * - * The physical address depends on the topology of the network formed - * by connected HDMI devices. It is therefore likely to change if the cable - * is plugged off and on again. It is advised to call get_physical_address - * to get the updated address when hot plug event takes place. - * - * Returns 0 on success or -errno on error. - */ - int (*get_physical_address)(const struct hdmi_cec_device* dev, uint16_t* addr); - - /* - * (*send_message)() transmits HDMI-CEC message to other HDMI device. - * - * The method should be designed to return in a certain amount of time not - * hanging forever, which can happen if CEC signal line is pulled low for - * some reason. HAL implementation should take the situation into account - * so as not to wait forever for the message to get sent out. - * - * It should try retransmission at least once as specified in the standard. - * - * Returns error code. See HDMI_RESULT_SUCCESS, HDMI_RESULT_NACK, and - * HDMI_RESULT_BUSY. - */ - int (*send_message)(const struct hdmi_cec_device* dev, const cec_message_t*); - - /* - * (*register_event_callback)() registers a callback that HDMI-CEC HAL - * can later use for incoming CEC messages or internal HDMI events. - * When calling from C++, use the argument arg to pass the calling object. - * It will be passed back when the callback is invoked so that the context - * can be retrieved. - */ - void (*register_event_callback)(const struct hdmi_cec_device* dev, - event_callback_t callback, void* arg); - - /* - * (*get_version)() returns the CEC version supported by underlying hardware. - */ - void (*get_version)(const struct hdmi_cec_device* dev, int* version); - - /* - * (*get_vendor_id)() returns the identifier of the vendor. It is - * the 24-bit unique company ID obtained from the IEEE Registration - * Authority Committee (RAC). - */ - void (*get_vendor_id)(const struct hdmi_cec_device* dev, uint32_t* vendor_id); - - /* - * (*get_port_info)() returns the hdmi port information of underlying hardware. - * info is the list of HDMI port information, and 'total' is the number of - * HDMI ports in the system. - */ - void (*get_port_info)(const struct hdmi_cec_device* dev, - struct hdmi_port_info* list[], int* total); - - /* - * (*set_option)() passes flags controlling the way HDMI-CEC service works down - * to HAL implementation. Those flags will be used in case the feature needs - * update in HAL itself, firmware or microcontroller. - */ - void (*set_option)(const struct hdmi_cec_device* dev, int flag, int value); - - /* - * (*set_audio_return_channel)() configures ARC circuit in the hardware logic - * to start or stop the feature. Flag can be either 1 to start the feature - * or 0 to stop it. - * - * Returns 0 on success or -errno on error. - */ - void (*set_audio_return_channel)(const struct hdmi_cec_device* dev, int port_id, int flag); - - /* - * (*is_connected)() returns the connection status of the specified port. - * Returns HDMI_CONNECTED if a device is connected, otherwise HDMI_NOT_CONNECTED. - * The HAL should watch for +5V power signal to determine the status. - */ - int (*is_connected)(const struct hdmi_cec_device* dev, int port_id); - - /* Reserved for future use to maximum 16 functions. Must be NULL. */ - void* reserved[16 - 11]; -} hdmi_cec_device_t; - -/** convenience API for opening and closing a device */ - -static inline int hdmi_cec_open(const struct hw_module_t* module, - struct hdmi_cec_device** device) { - return module->methods->open(module, - HDMI_CEC_HARDWARE_INTERFACE, TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int hdmi_cec_close(struct hdmi_cec_device* device) { - return device->common.close(&device->common); -} - -__END_DECLS - -#endif /* ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H */ +../../include_all/hardware/hdmi_cec.h
\ No newline at end of file diff --git a/include/hardware/hw_auth_token.h b/include/hardware/hw_auth_token.h index 3305f2c8..dba2b12e 100644..120000 --- a/include/hardware/hw_auth_token.h +++ b/include/hardware/hw_auth_token.h @@ -1,53 +1 @@ -/* - * Copyright (C) 2014 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. - */ - -#include <stdint.h> - -#ifndef ANDROID_HARDWARE_HW_AUTH_TOKEN_H -#define ANDROID_HARDWARE_HW_AUTH_TOKEN_H - -#ifdef __cplusplus -extern "C" { -#endif // __cplusplus - -#define HW_AUTH_TOKEN_VERSION 0 - -typedef enum { - HW_AUTH_NONE = 0, - HW_AUTH_PASSWORD = 1 << 0, - HW_AUTH_FINGERPRINT = 1 << 1, - // Additional entries should be powers of 2. - HW_AUTH_ANY = UINT32_MAX, -} hw_authenticator_type_t; - -/** - * Data format for an authentication record used to prove successful authentication. - */ -typedef struct __attribute__((__packed__)) { - uint8_t version; // Current version is 0 - uint64_t challenge; - uint64_t user_id; // secure user ID, not Android user ID - uint64_t authenticator_id; // secure authenticator ID - uint32_t authenticator_type; // hw_authenticator_type_t, in network order - uint64_t timestamp; // in network order - uint8_t hmac[32]; -} hw_auth_token_t; - -#ifdef __cplusplus -} // extern "C" -#endif // __cplusplus - -#endif // ANDROID_HARDWARE_HW_AUTH_TOKEN_H +../../include_all/hardware/hw_auth_token.h
\ No newline at end of file diff --git a/include/hardware/hwcomposer.h b/include/hardware/hwcomposer.h index 9eb1aafb..48b8766e 100644..120000 --- a/include/hardware/hwcomposer.h +++ b/include/hardware/hwcomposer.h @@ -1,798 +1 @@ -/* - * Copyright (C) 2010 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_INCLUDE_HARDWARE_HWCOMPOSER_H -#define ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H - -#include <stdint.h> -#include <sys/cdefs.h> - -#include <hardware/gralloc.h> -#include <hardware/hardware.h> -#include <cutils/native_handle.h> - -#include <hardware/hwcomposer_defs.h> - -__BEGIN_DECLS - -/*****************************************************************************/ - -/* for compatibility */ -#define HWC_MODULE_API_VERSION HWC_MODULE_API_VERSION_0_1 -#define HWC_DEVICE_API_VERSION HWC_DEVICE_API_VERSION_0_1 -#define HWC_API_VERSION HWC_DEVICE_API_VERSION - -/*****************************************************************************/ - -typedef struct hwc_layer_1 { - /* - * compositionType is used to specify this layer's type and is set by either - * the hardware composer implementation, or by the caller (see below). - * - * This field is always reset to HWC_BACKGROUND or HWC_FRAMEBUFFER - * before (*prepare)() is called when the HWC_GEOMETRY_CHANGED flag is - * also set, otherwise, this field is preserved between (*prepare)() - * calls. - * - * HWC_BACKGROUND - * Always set by the caller before calling (*prepare)(), this value - * indicates this is a special "background" layer. The only valid field - * is backgroundColor. - * The HWC can toggle this value to HWC_FRAMEBUFFER to indicate it CANNOT - * handle the background color. - * - * - * HWC_FRAMEBUFFER_TARGET - * Always set by the caller before calling (*prepare)(), this value - * indicates this layer is the framebuffer surface used as the target of - * OpenGL ES composition. If the HWC sets all other layers to HWC_OVERLAY - * or HWC_BACKGROUND, then no OpenGL ES composition will be done, and - * this layer should be ignored during set(). - * - * This flag (and the framebuffer surface layer) will only be used if the - * HWC version is HWC_DEVICE_API_VERSION_1_1 or higher. In older versions, - * the OpenGL ES target surface is communicated by the (dpy, sur) fields - * in hwc_compositor_device_1_t. - * - * This value cannot be set by the HWC implementation. - * - * - * HWC_FRAMEBUFFER - * Set by the caller before calling (*prepare)() ONLY when the - * HWC_GEOMETRY_CHANGED flag is also set. - * - * Set by the HWC implementation during (*prepare)(), this indicates - * that the layer will be drawn into the framebuffer using OpenGL ES. - * The HWC can toggle this value to HWC_OVERLAY to indicate it will - * handle the layer. - * - * - * HWC_OVERLAY - * Set by the HWC implementation during (*prepare)(), this indicates - * that the layer will be handled by the HWC (ie: it must not be - * composited with OpenGL ES). - * - * - * HWC_SIDEBAND - * Set by the caller before calling (*prepare)(), this value indicates - * the contents of this layer come from a sideband video stream. - * - * The h/w composer is responsible for receiving new image buffers from - * the stream at the appropriate time (e.g. synchronized to a separate - * audio stream), compositing them with the current contents of other - * layers, and displaying the resulting image. This happens - * independently of the normal prepare/set cycle. The prepare/set calls - * only happen when other layers change, or when properties of the - * sideband layer such as position or size change. - * - * If the h/w composer can't handle the layer as a sideband stream for - * some reason (e.g. unsupported scaling/blending/rotation, or too many - * sideband layers) it can set compositionType to HWC_FRAMEBUFFER in - * (*prepare)(). However, doing so will result in the layer being shown - * as a solid color since the platform is not currently able to composite - * sideband layers with the GPU. This may be improved in future - * versions of the platform. - * - * - * HWC_CURSOR_OVERLAY - * Set by the HWC implementation during (*prepare)(), this value - * indicates the layer's composition will now be handled by the HWC. - * Additionally, the client can now asynchronously update the on-screen - * position of this layer using the setCursorPositionAsync() api. - */ - int32_t compositionType; - - /* - * hints is bit mask set by the HWC implementation during (*prepare)(). - * It is preserved between (*prepare)() calls, unless the - * HWC_GEOMETRY_CHANGED flag is set, in which case it is reset to 0. - * - * see hwc_layer_t::hints - */ - uint32_t hints; - - /* see hwc_layer_t::flags */ - uint32_t flags; - - union { - /* color of the background. hwc_color_t.a is ignored */ - hwc_color_t backgroundColor; - - struct { - union { - /* When compositionType is HWC_FRAMEBUFFER, HWC_OVERLAY, - * HWC_FRAMEBUFFER_TARGET, this is the handle of the buffer to - * compose. This handle is guaranteed to have been allocated - * from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. - * If the layer's handle is unchanged across two consecutive - * prepare calls and the HWC_GEOMETRY_CHANGED flag is not set - * for the second call then the HWComposer implementation may - * assume that the contents of the buffer have not changed. */ - buffer_handle_t handle; - - /* When compositionType is HWC_SIDEBAND, this is the handle - * of the sideband video stream to compose. */ - const native_handle_t* sidebandStream; - }; - - /* transformation to apply to the buffer during composition */ - uint32_t transform; - - /* blending to apply during composition */ - int32_t blending; - - /* area of the source to consider, the origin is the top-left corner of - * the buffer. As of HWC_DEVICE_API_VERSION_1_3, sourceRect uses floats. - * If the h/w can't support a non-integer source crop rectangle, it should - * punt to OpenGL ES composition. - */ - union { - // crop rectangle in integer (pre HWC_DEVICE_API_VERSION_1_3) - hwc_rect_t sourceCropi; - hwc_rect_t sourceCrop; // just for source compatibility - // crop rectangle in floats (as of HWC_DEVICE_API_VERSION_1_3) - hwc_frect_t sourceCropf; - }; - - /* where to composite the sourceCrop onto the display. The sourceCrop - * is scaled using linear filtering to the displayFrame. The origin is the - * top-left corner of the screen. - */ - hwc_rect_t displayFrame; - - /* visible region in screen space. The origin is the - * top-left corner of the screen. - * The visible region INCLUDES areas overlapped by a translucent layer. - */ - hwc_region_t visibleRegionScreen; - - /* Sync fence object that will be signaled when the buffer's - * contents are available. May be -1 if the contents are already - * available. This field is only valid during set(), and should be - * ignored during prepare(). The set() call must not wait for the - * fence to be signaled before returning, but the HWC must wait for - * all buffers to be signaled before reading from them. - * - * HWC_FRAMEBUFFER layers will never have an acquire fence, since - * reads from them are complete before the framebuffer is ready for - * display. - * - * HWC_SIDEBAND layers will never have an acquire fence, since - * synchronization is handled through implementation-defined - * sideband mechanisms. - * - * The HWC takes ownership of the acquireFenceFd and is responsible - * for closing it when no longer needed. - */ - int acquireFenceFd; - - /* During set() the HWC must set this field to a file descriptor for - * a sync fence object that will signal after the HWC has finished - * reading from the buffer. The field is ignored by prepare(). Each - * layer should have a unique file descriptor, even if more than one - * refer to the same underlying fence object; this allows each to be - * closed independently. - * - * If buffer reads can complete at significantly different times, - * then using independent fences is preferred. For example, if the - * HWC handles some layers with a blit engine and others with - * overlays, then the blit layers can be reused immediately after - * the blit completes, but the overlay layers can't be reused until - * a subsequent frame has been displayed. - * - * Since HWC doesn't read from HWC_FRAMEBUFFER layers, it shouldn't - * produce a release fence for them. The releaseFenceFd will be -1 - * for these layers when set() is called. - * - * Since HWC_SIDEBAND buffers don't pass through the HWC client, - * the HWC shouldn't produce a release fence for them. The - * releaseFenceFd will be -1 for these layers when set() is called. - * - * The HWC client taks ownership of the releaseFenceFd and is - * responsible for closing it when no longer needed. - */ - int releaseFenceFd; - - /* - * Availability: HWC_DEVICE_API_VERSION_1_2 - * - * Alpha value applied to the whole layer. The effective - * value of each pixel is computed as: - * - * if (blending == HWC_BLENDING_PREMULT) - * pixel.rgb = pixel.rgb * planeAlpha / 255 - * pixel.a = pixel.a * planeAlpha / 255 - * - * Then blending proceeds as usual according to the "blending" - * field above. - * - * NOTE: planeAlpha applies to YUV layers as well: - * - * pixel.rgb = yuv_to_rgb(pixel.yuv) - * if (blending == HWC_BLENDING_PREMULT) - * pixel.rgb = pixel.rgb * planeAlpha / 255 - * pixel.a = planeAlpha - * - * - * IMPLEMENTATION NOTE: - * - * If the source image doesn't have an alpha channel, then - * the h/w can use the HWC_BLENDING_COVERAGE equations instead of - * HWC_BLENDING_PREMULT and simply set the alpha channel to - * planeAlpha. - * - * e.g.: - * - * if (blending == HWC_BLENDING_PREMULT) - * blending = HWC_BLENDING_COVERAGE; - * pixel.a = planeAlpha; - * - */ - uint8_t planeAlpha; - - /* Pad to 32 bits */ - uint8_t _pad[3]; - - /* - * Availability: HWC_DEVICE_API_VERSION_1_5 - * - * This defines the region of the source buffer that has been - * modified since the last frame. - * - * If surfaceDamage.numRects > 0, then it may be assumed that any - * portion of the source buffer not covered by one of the rects has - * not been modified this frame. If surfaceDamage.numRects == 0, - * then the whole source buffer must be treated as if it had been - * modified. - * - * If the layer's contents are not modified relative to the prior - * prepare/set cycle, surfaceDamage will contain exactly one empty - * rect ([0, 0, 0, 0]). - * - * The damage rects are relative to the pre-transformed buffer, and - * their origin is the top-left corner. - */ - hwc_region_t surfaceDamage; - }; - }; - -#ifdef __LP64__ - /* - * For 64-bit mode, this struct is 120 bytes (and 8-byte aligned), and needs - * to be padded as such to maintain binary compatibility. - */ - uint8_t reserved[120 - 112]; -#else - /* - * For 32-bit mode, this struct is 96 bytes, and needs to be padded as such - * to maintain binary compatibility. - */ - uint8_t reserved[96 - 84]; -#endif - -} hwc_layer_1_t; - -/* This represents a display, typically an EGLDisplay object */ -typedef void* hwc_display_t; - -/* This represents a surface, typically an EGLSurface object */ -typedef void* hwc_surface_t; - -/* - * hwc_display_contents_1_t::flags values - */ -enum { - /* - * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list - * passed to (*prepare)() has changed by more than just the buffer handles - * and acquire fences. - */ - HWC_GEOMETRY_CHANGED = 0x00000001, -}; - -/* - * Description of the contents to output on a display. - * - * This is the top-level structure passed to the prepare and set calls to - * negotiate and commit the composition of a display image. - */ -typedef struct hwc_display_contents_1 { - /* File descriptor referring to a Sync HAL fence object which will signal - * when this composition is retired. For a physical display, a composition - * is retired when it has been replaced on-screen by a subsequent set. For - * a virtual display, the composition is retired when the writes to - * outputBuffer are complete and can be read. The fence object is created - * and returned by the set call; this field will be -1 on entry to prepare - * and set. SurfaceFlinger will close the returned file descriptor. - */ - int retireFenceFd; - - union { - /* Fields only relevant for HWC_DEVICE_VERSION_1_0. */ - struct { - /* (dpy, sur) is the target of SurfaceFlinger's OpenGL ES - * composition for HWC_DEVICE_VERSION_1_0. They aren't relevant to - * prepare. The set call should commit this surface atomically to - * the display along with any overlay layers. - */ - hwc_display_t dpy; - hwc_surface_t sur; - }; - - /* These fields are used for virtual displays when the h/w composer - * version is at least HWC_DEVICE_VERSION_1_3. */ - struct { - /* outbuf is the buffer that receives the composed image for - * virtual displays. Writes to the outbuf must wait until - * outbufAcquireFenceFd signals. A fence that will signal when - * writes to outbuf are complete should be returned in - * retireFenceFd. - * - * This field is set before prepare(), so properties of the buffer - * can be used to decide which layers can be handled by h/w - * composer. - * - * If prepare() sets all layers to FRAMEBUFFER, then GLES - * composition will happen directly to the output buffer. In this - * case, both outbuf and the FRAMEBUFFER_TARGET layer's buffer will - * be the same, and set() has no work to do besides managing fences. - * - * If the TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS board config - * variable is defined (not the default), then this behavior is - * changed: if all layers are marked for FRAMEBUFFER, GLES - * composition will take place to a scratch framebuffer, and - * h/w composer must copy it to the output buffer. This allows the - * h/w composer to do format conversion if there are cases where - * that is more desirable than doing it in the GLES driver or at the - * virtual display consumer. - * - * If some or all layers are marked OVERLAY, then the framebuffer - * and output buffer will be different. As with physical displays, - * the framebuffer handle will not change between frames if all - * layers are marked for OVERLAY. - */ - buffer_handle_t outbuf; - - /* File descriptor for a fence that will signal when outbuf is - * ready to be written. The h/w composer is responsible for closing - * this when no longer needed. - * - * Will be -1 whenever outbuf is NULL, or when the outbuf can be - * written immediately. - */ - int outbufAcquireFenceFd; - }; - }; - - /* List of layers that will be composed on the display. The buffer handles - * in the list will be unique. If numHwLayers is 0, all composition will be - * performed by SurfaceFlinger. - */ - uint32_t flags; - size_t numHwLayers; - hwc_layer_1_t hwLayers[0]; - -} hwc_display_contents_1_t; - -/* see hwc_composer_device::registerProcs() - * All of the callbacks are required and non-NULL unless otherwise noted. - */ -typedef struct hwc_procs { - /* - * (*invalidate)() triggers a screen refresh, in particular prepare and set - * will be called shortly after this call is made. Note that there is - * NO GUARANTEE that the screen refresh will happen after invalidate() - * returns (in particular, it could happen before). - * invalidate() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL and - * it is safe to call invalidate() from any of hwc_composer_device - * hooks, unless noted otherwise. - */ - void (*invalidate)(const struct hwc_procs* procs); - - /* - * (*vsync)() is called by the h/w composer HAL when a vsync event is - * received and HWC_EVENT_VSYNC is enabled on a display - * (see: hwc_event_control). - * - * the "disp" parameter indicates which display the vsync event is for. - * the "timestamp" parameter is the system monotonic clock timestamp in - * nanosecond of when the vsync event happened. - * - * vsync() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL. - * - * It is expected that vsync() is called from a thread of at least - * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, - * typically less than 0.5 ms. - * - * It is a (silent) error to have HWC_EVENT_VSYNC enabled when calling - * hwc_composer_device.set(..., 0, 0, 0) (screen off). The implementation - * can either stop or continue to process VSYNC events, but must not - * crash or cause other problems. - */ - void (*vsync)(const struct hwc_procs* procs, int disp, int64_t timestamp); - - /* - * (*hotplug)() is called by the h/w composer HAL when a display is - * connected or disconnected. The PRIMARY display is always connected and - * the hotplug callback should not be called for it. - * - * The disp parameter indicates which display type this event is for. - * The connected parameter indicates whether the display has just been - * connected (1) or disconnected (0). - * - * The hotplug() callback may call back into the h/w composer on the same - * thread to query refresh rate and dpi for the display. Additionally, - * other threads may be calling into the h/w composer while the callback - * is in progress. - * - * The h/w composer must serialize calls to the hotplug callback; only - * one thread may call it at a time. - * - * This callback will be NULL if the h/w composer is using - * HWC_DEVICE_API_VERSION_1_0. - */ - void (*hotplug)(const struct hwc_procs* procs, int disp, int connected); - -} hwc_procs_t; - - -/*****************************************************************************/ - -typedef struct hwc_module { - /** - * Common methods of the hardware composer module. This *must* be the first member of - * hwc_module as users of this structure will cast a hw_module_t to - * hwc_module pointer in contexts where it's known the hw_module_t references a - * hwc_module. - */ - struct hw_module_t common; -} hwc_module_t; - -#define HWC_ERROR (-1) -typedef struct hwc_composer_device_1 { - /** - * Common methods of the hardware composer device. This *must* be the first member of - * hwc_composer_device_1 as users of this structure will cast a hw_device_t to - * hwc_composer_device_1 pointer in contexts where it's known the hw_device_t references a - * hwc_composer_device_1. - */ - struct hw_device_t common; - - /* - * (*prepare)() is called for each frame before composition and is used by - * SurfaceFlinger to determine what composition steps the HWC can handle. - * - * (*prepare)() can be called more than once, the last call prevails. - * - * The HWC responds by setting the compositionType field in each layer to - * either HWC_FRAMEBUFFER, HWC_OVERLAY, or HWC_CURSOR_OVERLAY. For the - * HWC_FRAMEBUFFER type, composition for the layer is handled by - * SurfaceFlinger with OpenGL ES. For the latter two overlay types, - * the HWC will have to handle the layer's composition. compositionType - * and hints are preserved between (*prepare)() calles unless the - * HWC_GEOMETRY_CHANGED flag is set. - * - * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the - * list's geometry has changed, that is, when more than just the buffer's - * handles have been updated. Typically this happens (but is not limited to) - * when a window is added, removed, resized or moved. In this case - * compositionType and hints are reset to their default value. - * - * For HWC 1.0, numDisplays will always be one, and displays[0] will be - * non-NULL. - * - * For HWC 1.1, numDisplays will always be HWC_NUM_PHYSICAL_DISPLAY_TYPES. - * Entries for unsupported or disabled/disconnected display types will be - * NULL. - * - * In HWC 1.3, numDisplays may be up to HWC_NUM_DISPLAY_TYPES. The extra - * entries correspond to enabled virtual displays, and will be non-NULL. - * - * returns: 0 on success. An negative error code on error. If an error is - * returned, SurfaceFlinger will assume that none of the layer will be - * handled by the HWC. - */ - int (*prepare)(struct hwc_composer_device_1 *dev, - size_t numDisplays, hwc_display_contents_1_t** displays); - - /* - * (*set)() is used in place of eglSwapBuffers(), and assumes the same - * functionality, except it also commits the work list atomically with - * the actual eglSwapBuffers(). - * - * The layer lists are guaranteed to be the same as the ones returned from - * the last call to (*prepare)(). - * - * When this call returns the caller assumes that the displays will be - * updated in the near future with the content of their work lists, without - * artifacts during the transition from the previous frame. - * - * A display with zero layers indicates that the entire composition has - * been handled by SurfaceFlinger with OpenGL ES. In this case, (*set)() - * behaves just like eglSwapBuffers(). - * - * For HWC 1.0, numDisplays will always be one, and displays[0] will be - * non-NULL. - * - * For HWC 1.1, numDisplays will always be HWC_NUM_PHYSICAL_DISPLAY_TYPES. - * Entries for unsupported or disabled/disconnected display types will be - * NULL. - * - * In HWC 1.3, numDisplays may be up to HWC_NUM_DISPLAY_TYPES. The extra - * entries correspond to enabled virtual displays, and will be non-NULL. - * - * IMPORTANT NOTE: There is an implicit layer containing opaque black - * pixels behind all the layers in the list. It is the responsibility of - * the hwcomposer module to make sure black pixels are output (or blended - * from). - * - * IMPORTANT NOTE: In the event of an error this call *MUST* still cause - * any fences returned in the previous call to set to eventually become - * signaled. The caller may have already issued wait commands on these - * fences, and having set return without causing those fences to signal - * will likely result in a deadlock. - * - * returns: 0 on success. A negative error code on error: - * HWC_EGL_ERROR: eglGetError() will provide the proper error code (only - * allowed prior to HWComposer 1.1) - * Another code for non EGL errors. - */ - int (*set)(struct hwc_composer_device_1 *dev, - size_t numDisplays, hwc_display_contents_1_t** displays); - - /* - * eventControl(..., event, enabled) - * Enables or disables h/w composer events for a display. - * - * eventControl can be called from any thread and takes effect - * immediately. - * - * Supported events are: - * HWC_EVENT_VSYNC - * - * returns -EINVAL if the "event" parameter is not one of the value above - * or if the "enabled" parameter is not 0 or 1. - */ - int (*eventControl)(struct hwc_composer_device_1* dev, int disp, - int event, int enabled); - - union { - /* - * For HWC 1.3 and earlier, the blank() interface is used. - * - * blank(..., blank) - * Blanks or unblanks a display's screen. - * - * Turns the screen off when blank is nonzero, on when blank is zero. - * Multiple sequential calls with the same blank value must be - * supported. - * The screen state transition must be be complete when the function - * returns. - * - * returns 0 on success, negative on error. - */ - int (*blank)(struct hwc_composer_device_1* dev, int disp, int blank); - - /* - * For HWC 1.4 and above, setPowerMode() will be used in place of - * blank(). - * - * setPowerMode(..., mode) - * Sets the display screen's power state. - * - * Refer to the documentation of the HWC_POWER_MODE_* constants - * for information about each power mode. - * - * The functionality is similar to the blank() command in previous - * versions of HWC, but with support for more power states. - * - * The display driver is expected to retain and restore the low power - * state of the display while entering and exiting from suspend. - * - * Multiple sequential calls with the same mode value must be supported. - * - * The screen state transition must be be complete when the function - * returns. - * - * returns 0 on success, negative on error. - */ - int (*setPowerMode)(struct hwc_composer_device_1* dev, int disp, - int mode); - }; - - /* - * Used to retrieve information about the h/w composer - * - * Returns 0 on success or -errno on error. - */ - int (*query)(struct hwc_composer_device_1* dev, int what, int* value); - - /* - * (*registerProcs)() registers callbacks that the h/w composer HAL can - * later use. It will be called immediately after the composer device is - * opened with non-NULL procs. It is FORBIDDEN to call any of the callbacks - * from within registerProcs(). registerProcs() must save the hwc_procs_t - * pointer which is needed when calling a registered callback. - */ - void (*registerProcs)(struct hwc_composer_device_1* dev, - hwc_procs_t const* procs); - - /* - * This field is OPTIONAL and can be NULL. - * - * If non NULL it will be called by SurfaceFlinger on dumpsys - */ - void (*dump)(struct hwc_composer_device_1* dev, char *buff, int buff_len); - - /* - * (*getDisplayConfigs)() returns handles for the configurations available - * on the connected display. These handles must remain valid as long as the - * display is connected. - * - * Configuration handles are written to configs. The number of entries - * allocated by the caller is passed in *numConfigs; getDisplayConfigs must - * not try to write more than this number of config handles. On return, the - * total number of configurations available for the display is returned in - * *numConfigs. If *numConfigs is zero on entry, then configs may be NULL. - * - * Hardware composers implementing HWC_DEVICE_API_VERSION_1_3 or prior - * shall choose one configuration to activate and report it as the first - * entry in the returned list. Reporting the inactive configurations is not - * required. - * - * HWC_DEVICE_API_VERSION_1_4 and later provide configuration management - * through SurfaceFlinger, and hardware composers implementing these APIs - * must also provide getActiveConfig and setActiveConfig. Hardware composers - * implementing these API versions may choose not to activate any - * configuration, leaving configuration selection to higher levels of the - * framework. - * - * Returns 0 on success or a negative error code on error. If disp is a - * hotpluggable display type and no display is connected, an error shall be - * returned. - * - * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later. - * It shall be NULL for previous versions. - */ - int (*getDisplayConfigs)(struct hwc_composer_device_1* dev, int disp, - uint32_t* configs, size_t* numConfigs); - - /* - * (*getDisplayAttributes)() returns attributes for a specific config of a - * connected display. The config parameter is one of the config handles - * returned by getDisplayConfigs. - * - * The list of attributes to return is provided in the attributes - * parameter, terminated by HWC_DISPLAY_NO_ATTRIBUTE. The value for each - * requested attribute is written in order to the values array. The - * HWC_DISPLAY_NO_ATTRIBUTE attribute does not have a value, so the values - * array will have one less value than the attributes array. - * - * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later. - * It shall be NULL for previous versions. - * - * If disp is a hotpluggable display type and no display is connected, - * or if config is not a valid configuration for the display, a negative - * error code shall be returned. - */ - int (*getDisplayAttributes)(struct hwc_composer_device_1* dev, int disp, - uint32_t config, const uint32_t* attributes, int32_t* values); - - /* - * (*getActiveConfig)() returns the index of the configuration that is - * currently active on the connected display. The index is relative to - * the list of configuration handles returned by getDisplayConfigs. If there - * is no active configuration, HWC_ERROR shall be returned. - * - * Returns the configuration index on success or HWC_ERROR on error. - * - * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_4 and later. - * It shall be NULL for previous versions. - */ - int (*getActiveConfig)(struct hwc_composer_device_1* dev, int disp); - - /* - * (*setActiveConfig)() instructs the hardware composer to switch to the - * display configuration at the given index in the list of configuration - * handles returned by getDisplayConfigs. - * - * If this function returns without error, any subsequent calls to - * getActiveConfig shall return the index set by this function until one - * of the following occurs: - * 1) Another successful call of this function - * 2) The display is disconnected - * - * Returns 0 on success or a negative error code on error. If disp is a - * hotpluggable display type and no display is connected, or if index is - * outside of the range of hardware configurations returned by - * getDisplayConfigs, an error shall be returned. - * - * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_4 and later. - * It shall be NULL for previous versions. - */ - int (*setActiveConfig)(struct hwc_composer_device_1* dev, int disp, - int index); - /* - * Asynchronously update the location of the cursor layer. - * - * Within the standard prepare()/set() composition loop, the client - * (surfaceflinger) can request that a given layer uses dedicated cursor - * composition hardware by specifiying the HWC_IS_CURSOR_LAYER flag. Only - * one layer per display can have this flag set. If the layer is suitable - * for the platform's cursor hardware, hwcomposer will return from prepare() - * a composition type of HWC_CURSOR_OVERLAY for that layer. This indicates - * not only that the client is not responsible for compositing that layer, - * but also that the client can continue to update the position of that layer - * after a call to set(). This can reduce the visible latency of mouse - * movement to visible, on-screen cursor updates. Calls to - * setCursorPositionAsync() may be made from a different thread doing the - * prepare()/set() composition loop, but care must be taken to not interleave - * calls of setCursorPositionAsync() between calls of set()/prepare(). - * - * Notes: - * - Only one layer per display can be specified as a cursor layer with - * HWC_IS_CURSOR_LAYER. - * - hwcomposer will only return one layer per display as HWC_CURSOR_OVERLAY - * - This returns 0 on success or -errno on error. - * - This field is optional for HWC_DEVICE_API_VERSION_1_4 and later. It - * should be null for previous versions. - */ - int (*setCursorPositionAsync)(struct hwc_composer_device_1 *dev, int disp, int x_pos, int y_pos); - - /* - * Reserved for future use. Must be NULL. - */ - void* reserved_proc[1]; - -} hwc_composer_device_1_t; - -/** convenience API for opening and closing a device */ - -static inline int hwc_open_1(const struct hw_module_t* module, - hwc_composer_device_1_t** device) { - return module->methods->open(module, - HWC_HARDWARE_COMPOSER, TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int hwc_close_1(hwc_composer_device_1_t* device) { - return device->common.close(&device->common); -} - -/*****************************************************************************/ - -__END_DECLS - -#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */ +../../include_all/hardware/hwcomposer.h
\ No newline at end of file diff --git a/include/hardware/hwcomposer2.h b/include/hardware/hwcomposer2.h index 76122a57..f1b1b80f 100644..120000 --- a/include/hardware/hwcomposer2.h +++ b/include/hardware/hwcomposer2.h @@ -1,3175 +1 @@ -/* - * Copyright 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_HWCOMPOSER2_H -#define ANDROID_HARDWARE_HWCOMPOSER2_H - -#include <sys/cdefs.h> - -#include <hardware/hardware.h> - -#include "hwcomposer_defs.h" - -__BEGIN_DECLS - -/* - * Enums - * - * For most of these enums, there is an invalid value defined to be 0. This is - * an attempt to catch uninitialized fields, and these values should not be - * used. - */ - -/* Display attributes queryable through getDisplayAttribute */ -typedef enum { - HWC2_ATTRIBUTE_INVALID = 0, - - /* Dimensions in pixels */ - HWC2_ATTRIBUTE_WIDTH = 1, - HWC2_ATTRIBUTE_HEIGHT = 2, - - /* Vsync period in nanoseconds */ - HWC2_ATTRIBUTE_VSYNC_PERIOD = 3, - - /* Dots per thousand inches (DPI * 1000). Scaling by 1000 allows these - * numbers to be stored in an int32_t without losing too much precision. If - * the DPI for a configuration is unavailable or is considered unreliable, - * the device may return -1 instead */ - HWC2_ATTRIBUTE_DPI_X = 4, - HWC2_ATTRIBUTE_DPI_Y = 5, - - /* The configuration group this config is associated to. - * Switching between configurations within the same group may be done seamlessly - * in some conditions via setActiveConfigWithConstraints. */ - HWC2_ATTRIBUTE_CONFIG_GROUP = 7, -} hwc2_attribute_t; - -/* Blend modes, settable per layer */ -typedef enum { - HWC2_BLEND_MODE_INVALID = 0, - - /* colorOut = colorSrc */ - HWC2_BLEND_MODE_NONE = 1, - - /* colorOut = colorSrc + colorDst * (1 - alphaSrc) */ - HWC2_BLEND_MODE_PREMULTIPLIED = 2, - - /* colorOut = colorSrc * alphaSrc + colorDst * (1 - alphaSrc) */ - HWC2_BLEND_MODE_COVERAGE = 3, -} hwc2_blend_mode_t; - -/* See the 'Callbacks' section for more detailed descriptions of what these - * functions do */ -typedef enum { - HWC2_CALLBACK_INVALID = 0, - HWC2_CALLBACK_HOTPLUG = 1, - HWC2_CALLBACK_REFRESH = 2, - HWC2_CALLBACK_VSYNC = 3, - HWC2_CALLBACK_VSYNC_2_4 = 4, - HWC2_CALLBACK_VSYNC_PERIOD_TIMING_CHANGED = 5, - HWC2_CALLBACK_SEAMLESS_POSSIBLE = 6, -} hwc2_callback_descriptor_t; - -/* Optional capabilities which may be supported by some devices. The particular - * set of supported capabilities for a given device may be retrieved using - * getCapabilities. */ -typedef enum { - HWC2_CAPABILITY_INVALID = 0, - - /* Specifies that the device supports sideband stream layers, for which - * buffer content updates and other synchronization will not be provided - * through the usual validate/present cycle and must be handled by an - * external implementation-defined mechanism. Only changes to layer state - * (such as position, size, etc.) need to be performed through the - * validate/present cycle. */ - HWC2_CAPABILITY_SIDEBAND_STREAM = 1, - - /* Specifies that the device will apply a color transform even when either - * the client or the device has chosen that all layers should be composed by - * the client. This will prevent the client from applying the color - * transform during its composition step. */ - HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM = 2, - - /* Specifies that the present fence must not be used as an accurate - * representation of the actual present time of a frame. - * This capability must never be set by HWC2 devices. - * This capability may be set for HWC1 devices that use the - * HWC2On1Adapter where emulation of the present fence using the retire - * fence is not feasible. - * In the future, CTS tests will require present time to be reliable. - */ - HWC2_CAPABILITY_PRESENT_FENCE_IS_NOT_RELIABLE = 3, - - /* Specifies that a device is able to skip the validateDisplay call before - * receiving a call to presentDisplay. The client will always skip - * validateDisplay and try to call presentDisplay regardless of the changes - * in the properties of the layers. If the device returns anything else than - * HWC2_ERROR_NONE, it will call validateDisplay then presentDisplay again. - * For this capability to be worthwhile the device implementation of - * presentDisplay should fail as fast as possible in the case a - * validateDisplay step is needed. - */ - HWC2_CAPABILITY_SKIP_VALIDATE = 4, -} hwc2_capability_t; - -/* Possible composition types for a given layer */ -typedef enum { - HWC2_COMPOSITION_INVALID = 0, - - /* The client will composite this layer into the client target buffer - * (provided to the device through setClientTarget). - * - * The device must not request any composition type changes for layers of - * this type. */ - HWC2_COMPOSITION_CLIENT = 1, - - /* The device will handle the composition of this layer through a hardware - * overlay or other similar means. - * - * Upon validateDisplay, the device may request a change from this type to - * HWC2_COMPOSITION_CLIENT. */ - HWC2_COMPOSITION_DEVICE = 2, - - /* The device will render this layer using the color set through - * setLayerColor. If this functionality is not supported on a layer that the - * client sets to HWC2_COMPOSITION_SOLID_COLOR, the device must request that - * the composition type of that layer is changed to HWC2_COMPOSITION_CLIENT - * upon the next call to validateDisplay. - * - * Upon validateDisplay, the device may request a change from this type to - * HWC2_COMPOSITION_CLIENT. */ - HWC2_COMPOSITION_SOLID_COLOR = 3, - - /* Similar to DEVICE, but the position of this layer may also be set - * asynchronously through setCursorPosition. If this functionality is not - * supported on a layer that the client sets to HWC2_COMPOSITION_CURSOR, the - * device must request that the composition type of that layer is changed to - * HWC2_COMPOSITION_CLIENT upon the next call to validateDisplay. - * - * Upon validateDisplay, the device may request a change from this type to - * either HWC2_COMPOSITION_DEVICE or HWC2_COMPOSITION_CLIENT. Changing to - * HWC2_COMPOSITION_DEVICE will prevent the use of setCursorPosition but - * still permit the device to composite the layer. */ - HWC2_COMPOSITION_CURSOR = 4, - - /* The device will handle the composition of this layer, as well as its - * buffer updates and content synchronization. Only supported on devices - * which provide HWC2_CAPABILITY_SIDEBAND_STREAM. - * - * Upon validateDisplay, the device may request a change from this type to - * either HWC2_COMPOSITION_DEVICE or HWC2_COMPOSITION_CLIENT, but it is - * unlikely that content will display correctly in these cases. */ - HWC2_COMPOSITION_SIDEBAND = 5, -} hwc2_composition_t; - -/* Possible connection options from the hotplug callback */ -typedef enum { - HWC2_CONNECTION_INVALID = 0, - - /* The display has been connected */ - HWC2_CONNECTION_CONNECTED = 1, - - /* The display has been disconnected */ - HWC2_CONNECTION_DISCONNECTED = 2, -} hwc2_connection_t; - -/* Display requests returned by getDisplayRequests */ -typedef enum { - /* Instructs the client to provide a new client target buffer, even if no - * layers are marked for client composition. */ - HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET = 1 << 0, - - /* Instructs the client to write the result of client composition directly - * into the virtual display output buffer. If any of the layers are not - * marked as HWC2_COMPOSITION_CLIENT or the given display is not a virtual - * display, this request has no effect. */ - HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT = 1 << 1, -} hwc2_display_request_t; - -/* Display types returned by getDisplayType */ -typedef enum { - HWC2_DISPLAY_TYPE_INVALID = 0, - - /* All physical displays, including both internal displays and hotpluggable - * external displays */ - HWC2_DISPLAY_TYPE_PHYSICAL = 1, - - /* Virtual displays created by createVirtualDisplay */ - HWC2_DISPLAY_TYPE_VIRTUAL = 2, -} hwc2_display_type_t; - -/* Physical display types returned by getDisplayConnectionType */ -typedef enum { - HWC2_DISPLAY_CONNECTION_TYPE_INTERNAL = 0, - HWC2_DISPLAY_CONNECTION_TYPE_EXTERNAL = 1, -} hwc2_display_connection_type_t; - -/* Return codes from all functions */ -typedef enum { - HWC2_ERROR_NONE = 0, - HWC2_ERROR_BAD_CONFIG, - HWC2_ERROR_BAD_DISPLAY, - HWC2_ERROR_BAD_LAYER, - HWC2_ERROR_BAD_PARAMETER, - HWC2_ERROR_HAS_CHANGES, - HWC2_ERROR_NO_RESOURCES, - HWC2_ERROR_NOT_VALIDATED, - HWC2_ERROR_UNSUPPORTED, - HWC2_ERROR_SEAMLESS_NOT_ALLOWED, - HWC2_ERROR_SEAMLESS_NOT_POSSIBLE, -} hwc2_error_t; - -/* Function descriptors for use with getFunction */ -typedef enum { - HWC2_FUNCTION_INVALID = 0, - HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES, - HWC2_FUNCTION_CREATE_LAYER, - HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY, - HWC2_FUNCTION_DESTROY_LAYER, - HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY, - HWC2_FUNCTION_DUMP, - HWC2_FUNCTION_GET_ACTIVE_CONFIG, - HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES, - HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT, - HWC2_FUNCTION_GET_COLOR_MODES, - HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE, - HWC2_FUNCTION_GET_DISPLAY_CONFIGS, - HWC2_FUNCTION_GET_DISPLAY_NAME, - HWC2_FUNCTION_GET_DISPLAY_REQUESTS, - HWC2_FUNCTION_GET_DISPLAY_TYPE, - HWC2_FUNCTION_GET_DOZE_SUPPORT, - HWC2_FUNCTION_GET_HDR_CAPABILITIES, - HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT, - HWC2_FUNCTION_GET_RELEASE_FENCES, - HWC2_FUNCTION_PRESENT_DISPLAY, - HWC2_FUNCTION_REGISTER_CALLBACK, - HWC2_FUNCTION_SET_ACTIVE_CONFIG, - HWC2_FUNCTION_SET_CLIENT_TARGET, - HWC2_FUNCTION_SET_COLOR_MODE, - HWC2_FUNCTION_SET_COLOR_TRANSFORM, - HWC2_FUNCTION_SET_CURSOR_POSITION, - HWC2_FUNCTION_SET_LAYER_BLEND_MODE, - HWC2_FUNCTION_SET_LAYER_BUFFER, - HWC2_FUNCTION_SET_LAYER_COLOR, - HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE, - HWC2_FUNCTION_SET_LAYER_DATASPACE, - HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME, - HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA, - HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM, - HWC2_FUNCTION_SET_LAYER_SOURCE_CROP, - HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE, - HWC2_FUNCTION_SET_LAYER_TRANSFORM, - HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION, - HWC2_FUNCTION_SET_LAYER_Z_ORDER, - HWC2_FUNCTION_SET_OUTPUT_BUFFER, - HWC2_FUNCTION_SET_POWER_MODE, - HWC2_FUNCTION_SET_VSYNC_ENABLED, - HWC2_FUNCTION_VALIDATE_DISPLAY, - HWC2_FUNCTION_SET_LAYER_FLOAT_COLOR, - HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA, - HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS, - HWC2_FUNCTION_SET_READBACK_BUFFER, - HWC2_FUNCTION_GET_READBACK_BUFFER_ATTRIBUTES, - HWC2_FUNCTION_GET_READBACK_BUFFER_FENCE, - HWC2_FUNCTION_GET_RENDER_INTENTS, - HWC2_FUNCTION_SET_COLOR_MODE_WITH_RENDER_INTENT, - HWC2_FUNCTION_GET_DATASPACE_SATURATION_MATRIX, - - // composer 2.3 - HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA, - HWC2_FUNCTION_GET_DISPLAY_CAPABILITIES, - HWC2_FUNCTION_SET_LAYER_COLOR_TRANSFORM, - HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES, - HWC2_FUNCTION_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED, - HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLE, - HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS, - HWC2_FUNCTION_GET_DISPLAY_BRIGHTNESS_SUPPORT, - HWC2_FUNCTION_SET_DISPLAY_BRIGHTNESS, - - // composer 2.4 - HWC2_FUNCTION_GET_DISPLAY_CONNECTION_TYPE, - HWC2_FUNCTION_GET_DISPLAY_VSYNC_PERIOD, - HWC2_FUNCTION_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS, - HWC2_FUNCTION_SET_AUTO_LOW_LATENCY_MODE, - HWC2_FUNCTION_GET_SUPPORTED_CONTENT_TYPES, - HWC2_FUNCTION_SET_CONTENT_TYPE, - HWC2_FUNCTION_GET_CLIENT_TARGET_PROPERTY, - HWC2_FUNCTION_SET_LAYER_GENERIC_METADATA, - HWC2_FUNCTION_GET_LAYER_GENERIC_METADATA_KEY, -} hwc2_function_descriptor_t; - -/* Layer requests returned from getDisplayRequests */ -typedef enum { - /* The client should clear its target with transparent pixels where this - * layer would be. The client may ignore this request if the layer must be - * blended. */ - HWC2_LAYER_REQUEST_CLEAR_CLIENT_TARGET = 1 << 0, -} hwc2_layer_request_t; - -/* Power modes for use with setPowerMode */ -typedef enum { - /* The display is fully off (blanked) */ - HWC2_POWER_MODE_OFF = 0, - - /* These are optional low power modes. getDozeSupport may be called to - * determine whether a given display supports these modes. */ - - /* The display is turned on and configured in a low power state that is - * suitable for presenting ambient information to the user, possibly with - * lower fidelity than HWC2_POWER_MODE_ON, but with greater efficiency. */ - HWC2_POWER_MODE_DOZE = 1, - - /* The display is configured as in HWC2_POWER_MODE_DOZE but may stop - * applying display updates from the client. This is effectively a hint to - * the device that drawing to the display has been suspended and that the - * the device should remain on in a low power state and continue displaying - * its current contents indefinitely until the power mode changes. - * - * This mode may also be used as a signal to enable hardware-based doze - * functionality. In this case, the device is free to take over the display - * and manage it autonomously to implement a low power always-on display. */ - HWC2_POWER_MODE_DOZE_SUSPEND = 3, - - /* The display is fully on */ - HWC2_POWER_MODE_ON = 2, -} hwc2_power_mode_t; - -typedef enum { - HWC2_CONTENT_TYPE_NONE = 0, - HWC2_CONTENT_TYPE_GRAPHICS = 1, - HWC2_CONTENT_TYPE_PHOTO = 2, - HWC2_CONTENT_TYPE_CINEMA = 3, - HWC2_CONTENT_TYPE_GAME = 4, -} hwc2_content_type_t; - -/* Vsync values passed to setVsyncEnabled */ -typedef enum { - HWC2_VSYNC_INVALID = 0, - - /* Enable vsync */ - HWC2_VSYNC_ENABLE = 1, - - /* Disable vsync */ - HWC2_VSYNC_DISABLE = 2, -} hwc2_vsync_t; - -/* MUST match HIDL's V2_2::IComposerClient::PerFrameMetadataKey */ -typedef enum { - /* SMPTE ST 2084:2014. - * Coordinates defined in CIE 1931 xy chromaticity space - */ - HWC2_DISPLAY_RED_PRIMARY_X = 0, - HWC2_DISPLAY_RED_PRIMARY_Y = 1, - HWC2_DISPLAY_GREEN_PRIMARY_X = 2, - HWC2_DISPLAY_GREEN_PRIMARY_Y = 3, - HWC2_DISPLAY_BLUE_PRIMARY_X = 4, - HWC2_DISPLAY_BLUE_PRIMARY_Y = 5, - HWC2_WHITE_POINT_X = 6, - HWC2_WHITE_POINT_Y = 7, - /* SMPTE ST 2084:2014. - * Units: nits - * max as defined by ST 2048: 10,000 nits - */ - HWC2_MAX_LUMINANCE = 8, - HWC2_MIN_LUMINANCE = 9, - - /* CTA 861.3 - * Units: nits - */ - HWC2_MAX_CONTENT_LIGHT_LEVEL = 10, - HWC2_MAX_FRAME_AVERAGE_LIGHT_LEVEL = 11, -} hwc2_per_frame_metadata_key_t; - -/* SetDisplayedContentSampling values passed to setDisplayedContentSamplingEnabled */ -typedef enum { - HWC2_DISPLAYED_CONTENT_SAMPLING_INVALID = 0, - - /* Enable displayed content sampling */ - HWC2_DISPLAYED_CONTENT_SAMPLING_ENABLE = 1, - - /* Disable displayed content sampling */ - HWC2_DISPLAYED_CONTENT_SAMPLING_DISABLE = 2, -} hwc2_displayed_content_sampling_t; - -typedef enum { - HWC2_FORMAT_COMPONENT_0 = 1 << 0, /* The first component (eg, for RGBA_8888, this is R) */ - HWC2_FORMAT_COMPONENT_1 = 1 << 1, /* The second component (eg, for RGBA_8888, this is G) */ - HWC2_FORMAT_COMPONENT_2 = 1 << 2, /* The third component (eg, for RGBA_8888, this is B) */ - HWC2_FORMAT_COMPONENT_3 = 1 << 3, /* The fourth component (eg, for RGBA_8888, this is A) */ -} hwc2_format_color_component_t; - -/* Optional display capabilities which may be supported by some displays. - * The particular set of supported capabilities for a given display may be - * retrieved using getDisplayCapabilities. */ -typedef enum { - HWC2_DISPLAY_CAPABILITY_INVALID = 0, - - /** - * Specifies that the display must apply a color transform even when either - * the client or the device has chosen that all layers should be composed by - * the client. This prevents the client from applying the color transform - * during its composition step. - * If getDisplayCapabilities is supported, the global capability - * HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM is ignored. - * If getDisplayCapabilities is not supported, and the global capability - * HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM is returned by getCapabilities, - * then all displays must be treated as having - * HWC2_DISPLAY_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM. - */ - HWC2_DISPLAY_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM = 1, - - /** - * Specifies that the display supports PowerMode::DOZE and - * PowerMode::DOZE_SUSPEND. DOZE_SUSPEND may not provide any benefit - * over DOZE (see the definition of PowerMode for more information), - * but if both DOZE and DOZE_SUSPEND are no different from - * PowerMode::ON, the device must not claim support. - * HWC2_DISPLAY_CAPABILITY_DOZE must be returned by getDisplayCapabilities - * when getDozeSupport indicates the display supports PowerMode::DOZE and - * PowerMode::DOZE_SUSPEND. - */ - HWC2_DISPLAY_CAPABILITY_DOZE = 2, - - /** - * Specified that the display supports brightness operations. - */ - HWC2_DISPLAY_CAPABILITY_BRIGHTNESS = 3, - - /** - * Specifies that the display supports a low latency mode. If the connection - * to the display is via HDMI, this specifies whether Auto Low Latency Mode - * is supported. If, instead, there is an internal connection to the display, - * then this specifies that the display has some other custom low latency - * mode. - */ - HWC2_DISPLAY_CAPABILITY_AUTO_LOW_LATENCY_MODE = 5, -} hwc2_display_capability_t; - -/* - * Stringification Functions - */ - -#ifdef HWC2_INCLUDE_STRINGIFICATION - -static inline const char* getAttributeName(hwc2_attribute_t attribute) { - switch (attribute) { - case HWC2_ATTRIBUTE_INVALID: return "Invalid"; - case HWC2_ATTRIBUTE_WIDTH: return "Width"; - case HWC2_ATTRIBUTE_HEIGHT: return "Height"; - case HWC2_ATTRIBUTE_VSYNC_PERIOD: return "VsyncPeriod"; - case HWC2_ATTRIBUTE_DPI_X: return "DpiX"; - case HWC2_ATTRIBUTE_DPI_Y: return "DpiY"; - case HWC2_ATTRIBUTE_CONFIG_GROUP: return "ConfigGroup"; - default: return "Unknown"; - } -} - -static inline const char* getBlendModeName(hwc2_blend_mode_t mode) { - switch (mode) { - case HWC2_BLEND_MODE_INVALID: return "Invalid"; - case HWC2_BLEND_MODE_NONE: return "None"; - case HWC2_BLEND_MODE_PREMULTIPLIED: return "Premultiplied"; - case HWC2_BLEND_MODE_COVERAGE: return "Coverage"; - default: return "Unknown"; - } -} - -static inline const char* getCallbackDescriptorName( - hwc2_callback_descriptor_t desc) { - switch (desc) { - case HWC2_CALLBACK_INVALID: return "Invalid"; - case HWC2_CALLBACK_HOTPLUG: return "Hotplug"; - case HWC2_CALLBACK_REFRESH: return "Refresh"; - case HWC2_CALLBACK_VSYNC: return "Vsync"; - case HWC2_CALLBACK_VSYNC_2_4: return "Vsync2.4"; - case HWC2_CALLBACK_VSYNC_PERIOD_TIMING_CHANGED: return "VsyncPeriodTimingChanged"; - case HWC2_CALLBACK_SEAMLESS_POSSIBLE: return "SeamlessPossible"; - default: return "Unknown"; - } -} - -static inline const char* getCapabilityName(hwc2_capability_t capability) { - switch (capability) { - case HWC2_CAPABILITY_INVALID: return "Invalid"; - case HWC2_CAPABILITY_SIDEBAND_STREAM: return "SidebandStream"; - case HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM: - return "SkipClientColorTransform"; - case HWC2_CAPABILITY_PRESENT_FENCE_IS_NOT_RELIABLE: - return "PresentFenceIsNotReliable"; - default: return "Unknown"; - } -} - -static inline const char* getCompositionName(hwc2_composition_t composition) { - switch (composition) { - case HWC2_COMPOSITION_INVALID: return "Invalid"; - case HWC2_COMPOSITION_CLIENT: return "Client"; - case HWC2_COMPOSITION_DEVICE: return "Device"; - case HWC2_COMPOSITION_SOLID_COLOR: return "SolidColor"; - case HWC2_COMPOSITION_CURSOR: return "Cursor"; - case HWC2_COMPOSITION_SIDEBAND: return "Sideband"; - default: return "Unknown"; - } -} - -static inline const char* getConnectionName(hwc2_connection_t connection) { - switch (connection) { - case HWC2_CONNECTION_INVALID: return "Invalid"; - case HWC2_CONNECTION_CONNECTED: return "Connected"; - case HWC2_CONNECTION_DISCONNECTED: return "Disconnected"; - default: return "Unknown"; - } -} - -static inline const char* getDisplayRequestName( - hwc2_display_request_t request) { - switch (__BIONIC_CAST(static_cast, int, request)) { - case 0: return "None"; - case HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET: return "FlipClientTarget"; - case HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT: - return "WriteClientTargetToOutput"; - case HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET | - HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT: - return "FlipClientTarget|WriteClientTargetToOutput"; - default: return "Unknown"; - } -} - -static inline const char* getDisplayTypeName(hwc2_display_type_t type) { - switch (type) { - case HWC2_DISPLAY_TYPE_INVALID: return "Invalid"; - case HWC2_DISPLAY_TYPE_PHYSICAL: return "Physical"; - case HWC2_DISPLAY_TYPE_VIRTUAL: return "Virtual"; - default: return "Unknown"; - } -} - -static inline const char* getDisplayConnectionTypeName(hwc2_display_connection_type_t type) { - switch (type) { - case HWC2_DISPLAY_CONNECTION_TYPE_INTERNAL: return "Internal"; - case HWC2_DISPLAY_CONNECTION_TYPE_EXTERNAL: return "External"; - default: return "Unknown"; - } -} - -static inline const char* getErrorName(hwc2_error_t error) { - switch (error) { - case HWC2_ERROR_NONE: return "None"; - case HWC2_ERROR_BAD_CONFIG: return "BadConfig"; - case HWC2_ERROR_BAD_DISPLAY: return "BadDisplay"; - case HWC2_ERROR_BAD_LAYER: return "BadLayer"; - case HWC2_ERROR_BAD_PARAMETER: return "BadParameter"; - case HWC2_ERROR_HAS_CHANGES: return "HasChanges"; - case HWC2_ERROR_NO_RESOURCES: return "NoResources"; - case HWC2_ERROR_NOT_VALIDATED: return "NotValidated"; - case HWC2_ERROR_UNSUPPORTED: return "Unsupported"; - case HWC2_ERROR_SEAMLESS_NOT_ALLOWED: return "SeamlessNotAllowed"; - case HWC2_ERROR_SEAMLESS_NOT_POSSIBLE: return "SeamlessNotPossible"; - default: return "Unknown"; - } -} - -static inline const char* getFunctionDescriptorName( - hwc2_function_descriptor_t desc) { - switch (desc) { - case HWC2_FUNCTION_INVALID: return "Invalid"; - case HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES: - return "AcceptDisplayChanges"; - case HWC2_FUNCTION_CREATE_LAYER: return "CreateLayer"; - case HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY: - return "CreateVirtualDisplay"; - case HWC2_FUNCTION_DESTROY_LAYER: return "DestroyLayer"; - case HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY: - return "DestroyVirtualDisplay"; - case HWC2_FUNCTION_DUMP: return "Dump"; - case HWC2_FUNCTION_GET_ACTIVE_CONFIG: return "GetActiveConfig"; - case HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES: - return "GetChangedCompositionTypes"; - case HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT: - return "GetClientTargetSupport"; - case HWC2_FUNCTION_GET_COLOR_MODES: return "GetColorModes"; - case HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE: return "GetDisplayAttribute"; - case HWC2_FUNCTION_GET_DISPLAY_CONFIGS: return "GetDisplayConfigs"; - case HWC2_FUNCTION_GET_DISPLAY_NAME: return "GetDisplayName"; - case HWC2_FUNCTION_GET_DISPLAY_REQUESTS: return "GetDisplayRequests"; - case HWC2_FUNCTION_GET_DISPLAY_TYPE: return "GetDisplayType"; - case HWC2_FUNCTION_GET_DOZE_SUPPORT: return "GetDozeSupport"; - case HWC2_FUNCTION_GET_HDR_CAPABILITIES: return "GetHdrCapabilities"; - case HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT: - return "GetMaxVirtualDisplayCount"; - case HWC2_FUNCTION_GET_RELEASE_FENCES: return "GetReleaseFences"; - case HWC2_FUNCTION_PRESENT_DISPLAY: return "PresentDisplay"; - case HWC2_FUNCTION_REGISTER_CALLBACK: return "RegisterCallback"; - case HWC2_FUNCTION_SET_ACTIVE_CONFIG: return "SetActiveConfig"; - case HWC2_FUNCTION_SET_CLIENT_TARGET: return "SetClientTarget"; - case HWC2_FUNCTION_SET_COLOR_MODE: return "SetColorMode"; - case HWC2_FUNCTION_SET_COLOR_TRANSFORM: return "SetColorTransform"; - case HWC2_FUNCTION_SET_CURSOR_POSITION: return "SetCursorPosition"; - case HWC2_FUNCTION_SET_LAYER_BLEND_MODE: return "SetLayerBlendMode"; - case HWC2_FUNCTION_SET_LAYER_BUFFER: return "SetLayerBuffer"; - case HWC2_FUNCTION_SET_LAYER_COLOR: return "SetLayerColor"; - case HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE: - return "SetLayerCompositionType"; - case HWC2_FUNCTION_SET_LAYER_DATASPACE: return "SetLayerDataspace"; - case HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME: - return "SetLayerDisplayFrame"; - case HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA: return "SetLayerPlaneAlpha"; - case HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM: - return "SetLayerSidebandStream"; - case HWC2_FUNCTION_SET_LAYER_SOURCE_CROP: return "SetLayerSourceCrop"; - case HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE: - return "SetLayerSurfaceDamage"; - case HWC2_FUNCTION_SET_LAYER_TRANSFORM: return "SetLayerTransform"; - case HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION: - return "SetLayerVisibleRegion"; - case HWC2_FUNCTION_SET_LAYER_Z_ORDER: return "SetLayerZOrder"; - case HWC2_FUNCTION_SET_OUTPUT_BUFFER: return "SetOutputBuffer"; - case HWC2_FUNCTION_SET_POWER_MODE: return "SetPowerMode"; - case HWC2_FUNCTION_SET_VSYNC_ENABLED: return "SetVsyncEnabled"; - case HWC2_FUNCTION_VALIDATE_DISPLAY: return "ValidateDisplay"; - case HWC2_FUNCTION_SET_LAYER_FLOAT_COLOR: return "SetLayerFloatColor"; - case HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA: return "SetLayerPerFrameMetadata"; - case HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS: return "GetPerFrameMetadataKeys"; - case HWC2_FUNCTION_SET_READBACK_BUFFER: return "SetReadbackBuffer"; - case HWC2_FUNCTION_GET_READBACK_BUFFER_ATTRIBUTES: return "GetReadbackBufferAttributes"; - case HWC2_FUNCTION_GET_READBACK_BUFFER_FENCE: return "GetReadbackBufferFence"; - case HWC2_FUNCTION_GET_RENDER_INTENTS: return "GetRenderIntents"; - case HWC2_FUNCTION_SET_COLOR_MODE_WITH_RENDER_INTENT: return "SetColorModeWithRenderIntent"; - case HWC2_FUNCTION_GET_DATASPACE_SATURATION_MATRIX: return "GetDataspaceSaturationMatrix"; - - // composer 2.3 - case HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA: return "GetDisplayIdentificationData"; - case HWC2_FUNCTION_GET_DISPLAY_CAPABILITIES: return "GetDisplayCapabilities"; - case HWC2_FUNCTION_SET_LAYER_COLOR_TRANSFORM: return "SetLayerColorTransform"; - case HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES: return "GetDisplayedContentSamplingAttributes"; - case HWC2_FUNCTION_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED: return "SetDisplayedContentSamplingEnabled"; - case HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLE: return "GetDisplayedContentSample"; - case HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS: return "SetLayerPerFrameMetadataBlobs"; - case HWC2_FUNCTION_GET_DISPLAY_BRIGHTNESS_SUPPORT: return "GetDisplayBrightnessSupport"; - case HWC2_FUNCTION_SET_DISPLAY_BRIGHTNESS: return "SetDisplayBrightness"; - - // composer 2.4 - case HWC2_FUNCTION_GET_DISPLAY_CONNECTION_TYPE: return "GetDisplayConnectionType"; - case HWC2_FUNCTION_GET_DISPLAY_VSYNC_PERIOD: return "GetDisplayVsyncPeriod"; - case HWC2_FUNCTION_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS: return "SetActiveConfigWithConstraints"; - case HWC2_FUNCTION_SET_AUTO_LOW_LATENCY_MODE: return "SetAutoLowLatencyMode"; - case HWC2_FUNCTION_GET_SUPPORTED_CONTENT_TYPES: return "GetSupportedContentTypes"; - case HWC2_FUNCTION_SET_CONTENT_TYPE: return "SetContentType"; - case HWC2_FUNCTION_GET_CLIENT_TARGET_PROPERTY: return "GetClientTargetProperty"; - case HWC2_FUNCTION_SET_LAYER_GENERIC_METADATA: return "SetLayerGenericMetadata"; - case HWC2_FUNCTION_GET_LAYER_GENERIC_METADATA_KEY: return "GetLayerGenericMetadataKey"; - - default: return "Unknown"; - } -} - -static inline const char* getLayerRequestName(hwc2_layer_request_t request) { - switch (__BIONIC_CAST(static_cast, int, request)) { - case 0: return "None"; - case HWC2_LAYER_REQUEST_CLEAR_CLIENT_TARGET: return "ClearClientTarget"; - default: return "Unknown"; - } -} - -static inline const char* getPowerModeName(hwc2_power_mode_t mode) { - switch (mode) { - case HWC2_POWER_MODE_OFF: return "Off"; - case HWC2_POWER_MODE_DOZE_SUSPEND: return "DozeSuspend"; - case HWC2_POWER_MODE_DOZE: return "Doze"; - case HWC2_POWER_MODE_ON: return "On"; - default: return "Unknown"; - } -} - -static inline const char* getContentTypeName(hwc2_content_type_t contentType) { - switch(contentType) { - case HWC2_CONTENT_TYPE_NONE: return "None"; - case HWC2_CONTENT_TYPE_GRAPHICS: return "Graphics"; - case HWC2_CONTENT_TYPE_PHOTO: return "Photo"; - case HWC2_CONTENT_TYPE_CINEMA: return "Cinema"; - case HWC2_CONTENT_TYPE_GAME: return "Game"; - default: return "Unknown"; - } -} - -static inline const char* getTransformName(hwc_transform_t transform) { - switch (__BIONIC_CAST(static_cast, int, transform)) { - case 0: return "None"; - case HWC_TRANSFORM_FLIP_H: return "FlipH"; - case HWC_TRANSFORM_FLIP_V: return "FlipV"; - case HWC_TRANSFORM_ROT_90: return "Rotate90"; - case HWC_TRANSFORM_ROT_180: return "Rotate180"; - case HWC_TRANSFORM_ROT_270: return "Rotate270"; - case HWC_TRANSFORM_FLIP_H_ROT_90: return "FlipHRotate90"; - case HWC_TRANSFORM_FLIP_V_ROT_90: return "FlipVRotate90"; - default: return "Unknown"; - } -} - -static inline const char* getVsyncName(hwc2_vsync_t vsync) { - switch (vsync) { - case HWC2_VSYNC_INVALID: return "Invalid"; - case HWC2_VSYNC_ENABLE: return "Enable"; - case HWC2_VSYNC_DISABLE: return "Disable"; - default: return "Unknown"; - } -} - -static inline const char* getDisplayedContentSamplingName( - hwc2_displayed_content_sampling_t sampling) { - switch (sampling) { - case HWC2_DISPLAYED_CONTENT_SAMPLING_INVALID: return "Invalid"; - case HWC2_DISPLAYED_CONTENT_SAMPLING_ENABLE: return "Enable"; - case HWC2_DISPLAYED_CONTENT_SAMPLING_DISABLE: return "Disable"; - default: return "Unknown"; - } -} - -static inline const char* getFormatColorComponentName(hwc2_format_color_component_t component) { - switch (component) { - case HWC2_FORMAT_COMPONENT_0: return "FirstComponent"; - case HWC2_FORMAT_COMPONENT_1: return "SecondComponent"; - case HWC2_FORMAT_COMPONENT_2: return "ThirdComponent"; - case HWC2_FORMAT_COMPONENT_3: return "FourthComponent"; - default: return "Unknown"; - } -} - -static inline const char* getDisplayCapabilityName(hwc2_display_capability_t capability) { - switch (capability) { - case HWC2_DISPLAY_CAPABILITY_INVALID: return "Invalid"; - case HWC2_DISPLAY_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM: - return "SkipClientColorTransform"; - case HWC2_DISPLAY_CAPABILITY_DOZE: - return "Doze"; - case HWC2_DISPLAY_CAPABILITY_BRIGHTNESS: - return "Brightness"; - case HWC2_DISPLAY_CAPABILITY_AUTO_LOW_LATENCY_MODE: - return "AutoLowLatencyMode"; - default: - return "Unknown"; - } -} - -#define TO_STRING(E, T, printer) \ - inline std::string to_string(E value) { return printer(value); } \ - inline std::string to_string(T value) { return to_string(static_cast<E>(value)); } -#else // !HWC2_INCLUDE_STRINGIFICATION -#define TO_STRING(name, printer) -#endif // HWC2_INCLUDE_STRINGIFICATION - -/* - * C++11 features - */ - -#ifdef HWC2_USE_CPP11 -__END_DECLS - -#ifdef HWC2_INCLUDE_STRINGIFICATION -#include <string> -#endif - -namespace HWC2 { - -enum class Attribute : int32_t { - Invalid = HWC2_ATTRIBUTE_INVALID, - Width = HWC2_ATTRIBUTE_WIDTH, - Height = HWC2_ATTRIBUTE_HEIGHT, - VsyncPeriod = HWC2_ATTRIBUTE_VSYNC_PERIOD, - DpiX = HWC2_ATTRIBUTE_DPI_X, - DpiY = HWC2_ATTRIBUTE_DPI_Y, - ConfigGroup = HWC2_ATTRIBUTE_CONFIG_GROUP, -}; -TO_STRING(hwc2_attribute_t, Attribute, getAttributeName) - -enum class BlendMode : int32_t { - Invalid = HWC2_BLEND_MODE_INVALID, - None = HWC2_BLEND_MODE_NONE, - Premultiplied = HWC2_BLEND_MODE_PREMULTIPLIED, - Coverage = HWC2_BLEND_MODE_COVERAGE, -}; -TO_STRING(hwc2_blend_mode_t, BlendMode, getBlendModeName) - -enum class Callback : int32_t { - Invalid = HWC2_CALLBACK_INVALID, - Hotplug = HWC2_CALLBACK_HOTPLUG, - Refresh = HWC2_CALLBACK_REFRESH, - Vsync = HWC2_CALLBACK_VSYNC, - Vsync_2_4 = HWC2_CALLBACK_VSYNC_2_4, - VsyncPeriodTimingChanged = HWC2_CALLBACK_VSYNC_PERIOD_TIMING_CHANGED, - SeamlessPossible = HWC2_CALLBACK_SEAMLESS_POSSIBLE, -}; -TO_STRING(hwc2_callback_descriptor_t, Callback, getCallbackDescriptorName) - -enum class Capability : int32_t { - Invalid = HWC2_CAPABILITY_INVALID, - SidebandStream = HWC2_CAPABILITY_SIDEBAND_STREAM, - SkipClientColorTransform = HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM, - PresentFenceIsNotReliable = HWC2_CAPABILITY_PRESENT_FENCE_IS_NOT_RELIABLE, - SkipValidate = HWC2_CAPABILITY_SKIP_VALIDATE, -}; -TO_STRING(hwc2_capability_t, Capability, getCapabilityName) - -enum class Composition : int32_t { - Invalid = HWC2_COMPOSITION_INVALID, - Client = HWC2_COMPOSITION_CLIENT, - Device = HWC2_COMPOSITION_DEVICE, - SolidColor = HWC2_COMPOSITION_SOLID_COLOR, - Cursor = HWC2_COMPOSITION_CURSOR, - Sideband = HWC2_COMPOSITION_SIDEBAND, -}; -TO_STRING(hwc2_composition_t, Composition, getCompositionName) - -enum class Connection : int32_t { - Invalid = HWC2_CONNECTION_INVALID, - Connected = HWC2_CONNECTION_CONNECTED, - Disconnected = HWC2_CONNECTION_DISCONNECTED, -}; -TO_STRING(hwc2_connection_t, Connection, getConnectionName) - -enum class DisplayRequest : int32_t { - FlipClientTarget = HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET, - WriteClientTargetToOutput = - HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT, -}; -TO_STRING(hwc2_display_request_t, DisplayRequest, getDisplayRequestName) - -enum class DisplayType : int32_t { - Invalid = HWC2_DISPLAY_TYPE_INVALID, - Physical = HWC2_DISPLAY_TYPE_PHYSICAL, - Virtual = HWC2_DISPLAY_TYPE_VIRTUAL, -}; -TO_STRING(hwc2_display_type_t, DisplayType, getDisplayTypeName) - -enum class DisplayConnectionType : uint32_t { - Internal = HWC2_DISPLAY_CONNECTION_TYPE_INTERNAL, - External = HWC2_DISPLAY_CONNECTION_TYPE_EXTERNAL, -}; -TO_STRING(hwc2_display_connection_type_t, DisplayConnectionType, getDisplayConnectionTypeName) - -enum class Error : int32_t { - None = HWC2_ERROR_NONE, - BadConfig = HWC2_ERROR_BAD_CONFIG, - BadDisplay = HWC2_ERROR_BAD_DISPLAY, - BadLayer = HWC2_ERROR_BAD_LAYER, - BadParameter = HWC2_ERROR_BAD_PARAMETER, - HasChanges = HWC2_ERROR_HAS_CHANGES, - NoResources = HWC2_ERROR_NO_RESOURCES, - NotValidated = HWC2_ERROR_NOT_VALIDATED, - Unsupported = HWC2_ERROR_UNSUPPORTED, - SeamlessNotAllowed = HWC2_ERROR_SEAMLESS_NOT_ALLOWED, - SeamlessNotPossible = HWC2_ERROR_SEAMLESS_NOT_POSSIBLE, -}; -TO_STRING(hwc2_error_t, Error, getErrorName) - -enum class FunctionDescriptor : int32_t { - Invalid = HWC2_FUNCTION_INVALID, - AcceptDisplayChanges = HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES, - CreateLayer = HWC2_FUNCTION_CREATE_LAYER, - CreateVirtualDisplay = HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY, - DestroyLayer = HWC2_FUNCTION_DESTROY_LAYER, - DestroyVirtualDisplay = HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY, - Dump = HWC2_FUNCTION_DUMP, - GetActiveConfig = HWC2_FUNCTION_GET_ACTIVE_CONFIG, - GetChangedCompositionTypes = HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES, - GetClientTargetSupport = HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT, - GetColorModes = HWC2_FUNCTION_GET_COLOR_MODES, - GetDisplayAttribute = HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE, - GetDisplayConfigs = HWC2_FUNCTION_GET_DISPLAY_CONFIGS, - GetDisplayName = HWC2_FUNCTION_GET_DISPLAY_NAME, - GetDisplayRequests = HWC2_FUNCTION_GET_DISPLAY_REQUESTS, - GetDisplayType = HWC2_FUNCTION_GET_DISPLAY_TYPE, - GetDozeSupport = HWC2_FUNCTION_GET_DOZE_SUPPORT, - GetHdrCapabilities = HWC2_FUNCTION_GET_HDR_CAPABILITIES, - GetMaxVirtualDisplayCount = HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT, - GetReleaseFences = HWC2_FUNCTION_GET_RELEASE_FENCES, - PresentDisplay = HWC2_FUNCTION_PRESENT_DISPLAY, - RegisterCallback = HWC2_FUNCTION_REGISTER_CALLBACK, - SetActiveConfig = HWC2_FUNCTION_SET_ACTIVE_CONFIG, - SetClientTarget = HWC2_FUNCTION_SET_CLIENT_TARGET, - SetColorMode = HWC2_FUNCTION_SET_COLOR_MODE, - SetColorTransform = HWC2_FUNCTION_SET_COLOR_TRANSFORM, - SetCursorPosition = HWC2_FUNCTION_SET_CURSOR_POSITION, - SetLayerBlendMode = HWC2_FUNCTION_SET_LAYER_BLEND_MODE, - SetLayerBuffer = HWC2_FUNCTION_SET_LAYER_BUFFER, - SetLayerColor = HWC2_FUNCTION_SET_LAYER_COLOR, - SetLayerCompositionType = HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE, - SetLayerDataspace = HWC2_FUNCTION_SET_LAYER_DATASPACE, - SetLayerDisplayFrame = HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME, - SetLayerPlaneAlpha = HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA, - SetLayerSidebandStream = HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM, - SetLayerSourceCrop = HWC2_FUNCTION_SET_LAYER_SOURCE_CROP, - SetLayerSurfaceDamage = HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE, - SetLayerTransform = HWC2_FUNCTION_SET_LAYER_TRANSFORM, - SetLayerVisibleRegion = HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION, - SetLayerZOrder = HWC2_FUNCTION_SET_LAYER_Z_ORDER, - SetOutputBuffer = HWC2_FUNCTION_SET_OUTPUT_BUFFER, - SetPowerMode = HWC2_FUNCTION_SET_POWER_MODE, - SetVsyncEnabled = HWC2_FUNCTION_SET_VSYNC_ENABLED, - ValidateDisplay = HWC2_FUNCTION_VALIDATE_DISPLAY, - SetLayerFloatColor = HWC2_FUNCTION_SET_LAYER_FLOAT_COLOR, - SetLayerPerFrameMetadata = HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA, - GetPerFrameMetadataKeys = HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS, - SetReadbackBuffer = HWC2_FUNCTION_SET_READBACK_BUFFER, - GetReadbackBufferAttributes = HWC2_FUNCTION_GET_READBACK_BUFFER_ATTRIBUTES, - GetReadbackBufferFence = HWC2_FUNCTION_GET_READBACK_BUFFER_FENCE, - GetRenderIntents = HWC2_FUNCTION_GET_RENDER_INTENTS, - SetColorModeWithRenderIntent = HWC2_FUNCTION_SET_COLOR_MODE_WITH_RENDER_INTENT, - GetDataspaceSaturationMatrix = HWC2_FUNCTION_GET_DATASPACE_SATURATION_MATRIX, - - // composer 2.3 - GetDisplayIdentificationData = HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA, - GetDisplayCapabilities = HWC2_FUNCTION_GET_DISPLAY_CAPABILITIES, - SetLayerColorTransform = HWC2_FUNCTION_SET_LAYER_COLOR_TRANSFORM, - GetDisplayedContentSamplingAttributes = HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES, - SetDisplayedContentSamplingEnabled = HWC2_FUNCTION_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED, - GetDisplayedContentSample = HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLE, - SetLayerPerFrameMetadataBlobs = HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS, - GetDisplayBrightnessSupport = HWC2_FUNCTION_GET_DISPLAY_BRIGHTNESS_SUPPORT, - SetDisplayBrightness = HWC2_FUNCTION_SET_DISPLAY_BRIGHTNESS, - - // composer 2.4 - GetDisplayConnectionType = HWC2_FUNCTION_GET_DISPLAY_CONNECTION_TYPE, - GetDisplayVsyncPeriod = HWC2_FUNCTION_GET_DISPLAY_VSYNC_PERIOD, - SetActiveConfigWithConstraints = HWC2_FUNCTION_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS, - SetAutoLowLatencyMode = HWC2_FUNCTION_SET_AUTO_LOW_LATENCY_MODE, - GetSupportedContentTypes = HWC2_FUNCTION_GET_SUPPORTED_CONTENT_TYPES, - SetContentType = HWC2_FUNCTION_SET_CONTENT_TYPE, - GetClientTargetProperty = HWC2_FUNCTION_GET_CLIENT_TARGET_PROPERTY, - SetLayerGenericMetadata = HWC2_FUNCTION_SET_LAYER_GENERIC_METADATA, - GetLayerGenericMetadataKey = HWC2_FUNCTION_GET_LAYER_GENERIC_METADATA_KEY, -}; -TO_STRING(hwc2_function_descriptor_t, FunctionDescriptor, - getFunctionDescriptorName) - -enum class LayerRequest : int32_t { - ClearClientTarget = HWC2_LAYER_REQUEST_CLEAR_CLIENT_TARGET, -}; -TO_STRING(hwc2_layer_request_t, LayerRequest, getLayerRequestName) - -enum class PowerMode : int32_t { - Off = HWC2_POWER_MODE_OFF, - DozeSuspend = HWC2_POWER_MODE_DOZE_SUSPEND, - Doze = HWC2_POWER_MODE_DOZE, - On = HWC2_POWER_MODE_ON, -}; -TO_STRING(hwc2_power_mode_t, PowerMode, getPowerModeName) - -enum class ContentType : int32_t { - None = HWC2_CONTENT_TYPE_NONE, - Graphics = HWC2_CONTENT_TYPE_GRAPHICS, - Photo = HWC2_CONTENT_TYPE_PHOTO, - Cinema = HWC2_CONTENT_TYPE_CINEMA, - Game = HWC2_CONTENT_TYPE_GAME, -}; -TO_STRING(hwc2_content_type_t, ContentType, getContentTypeName) - -enum class Transform : int32_t { - None = 0, - FlipH = HWC_TRANSFORM_FLIP_H, - FlipV = HWC_TRANSFORM_FLIP_V, - Rotate90 = HWC_TRANSFORM_ROT_90, - Rotate180 = HWC_TRANSFORM_ROT_180, - Rotate270 = HWC_TRANSFORM_ROT_270, - FlipHRotate90 = HWC_TRANSFORM_FLIP_H_ROT_90, - FlipVRotate90 = HWC_TRANSFORM_FLIP_V_ROT_90, -}; -TO_STRING(hwc_transform_t, Transform, getTransformName) - -enum class Vsync : int32_t { - Invalid = HWC2_VSYNC_INVALID, - Enable = HWC2_VSYNC_ENABLE, - Disable = HWC2_VSYNC_DISABLE, -}; -TO_STRING(hwc2_vsync_t, Vsync, getVsyncName) - -enum class DisplayCapability : int32_t { - Invalid = HWC2_DISPLAY_CAPABILITY_INVALID, - SkipClientColorTransform = HWC2_DISPLAY_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM, - Doze = HWC2_DISPLAY_CAPABILITY_DOZE, - Brightness = HWC2_DISPLAY_CAPABILITY_BRIGHTNESS, - AutoLowLatencyMode = HWC2_DISPLAY_CAPABILITY_AUTO_LOW_LATENCY_MODE, -}; -TO_STRING(hwc2_display_capability_t, DisplayCapability, getDisplayCapabilityName) - -} // namespace HWC2 - -__BEGIN_DECLS -#endif // HWC2_USE_CPP11 - -/* - * Typedefs - */ - -typedef void (*hwc2_function_pointer_t)(); - -typedef void* hwc2_callback_data_t; -typedef uint32_t hwc2_config_t; -typedef uint64_t hwc2_display_t; -typedef uint64_t hwc2_layer_t; -typedef uint32_t hwc2_vsync_period_t; - -/* - * Device Struct - */ - -typedef struct hwc2_device { - /* Must be the first member of this struct, since a pointer to this struct - * will be generated by casting from a hw_device_t* */ - struct hw_device_t common; - - /* getCapabilities(..., outCount, outCapabilities) - * - * Provides a list of capabilities (described in the definition of - * hwc2_capability_t above) supported by this device. This list must - * not change after the device has been loaded. - * - * Parameters: - * outCount - if outCapabilities was NULL, the number of capabilities - * which would have been returned; if outCapabilities was not NULL, - * the number of capabilities returned, which must not exceed the - * value stored in outCount prior to the call - * outCapabilities - a list of capabilities supported by this device; may - * be NULL, in which case this function must write into outCount the - * number of capabilities which would have been written into - * outCapabilities - */ - void (*getCapabilities)(struct hwc2_device* device, uint32_t* outCount, - int32_t* /*hwc2_capability_t*/ outCapabilities); - - /* getFunction(..., descriptor) - * - * Returns a function pointer which implements the requested description. - * - * Parameters: - * descriptor - the function to return - * - * Returns either a function pointer implementing the requested descriptor - * or NULL if the described function is not supported by this device. - */ - hwc2_function_pointer_t (*getFunction)(struct hwc2_device* device, - int32_t /*hwc2_function_descriptor_t*/ descriptor); -} hwc2_device_t; - -static inline int hwc2_open(const struct hw_module_t* module, - hwc2_device_t** device) { - return module->methods->open(module, HWC_HARDWARE_COMPOSER, - TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int hwc2_close(hwc2_device_t* device) { - return device->common.close(&device->common); -} - -/* - * Callbacks - * - * All of these callbacks take as their first parameter the callbackData which - * was provided at the time of callback registration, so this parameter is - * omitted from the described parameter lists. - */ - -/* hotplug(..., display, connected) - * Descriptor: HWC2_CALLBACK_HOTPLUG - * Will be provided to all HWC2 devices - * - * Notifies the client that the given display has either been connected or - * disconnected. Every active display (even a built-in physical display) must - * trigger at least one hotplug notification, even if it only occurs immediately - * after callback registration. - * - * The client may call back into the device on the same thread to query display - * properties (such as width, height, and vsync period), and other threads may - * call into the device while the callback is in progress. The device must - * serialize calls to this callback such that only one thread is calling it at a - * time. - * - * Displays which have been connected are assumed to be in HWC2_POWER_MODE_OFF, - * and the vsync callback should not be called for a display until vsync has - * been enabled with setVsyncEnabled. - * - * Parameters: - * display - the display which has been hotplugged - * connected - whether the display has been connected or disconnected - */ -typedef void (*HWC2_PFN_HOTPLUG)(hwc2_callback_data_t callbackData, - hwc2_display_t display, int32_t /*hwc2_connection_t*/ connected); - -/* refresh(..., display) - * Descriptor: HWC2_CALLBACK_REFRESH - * Will be provided to all HWC2 devices - * - * Notifies the client to trigger a screen refresh. This forces all layer state - * for this display to be resent, and the display to be validated and presented, - * even if there have been no changes. - * - * This refresh will occur some time after the callback is initiated, but not - * necessarily before it returns. This thread, however, is guaranteed not to - * call back into the device, thus it is safe to trigger this callback from - * other functions which call into the device. - * - * Parameters: - * display - the display to refresh - */ -typedef void (*HWC2_PFN_REFRESH)(hwc2_callback_data_t callbackData, - hwc2_display_t display); - -/* vsync(..., display, timestamp) - * Descriptor: HWC2_CALLBACK_VSYNC - * Will be provided to all HWC2 devices - * - * Notifies the client that a vsync event has occurred. This callback must - * only be triggered when vsync is enabled for this display (through - * setVsyncEnabled). - * - * This callback should be triggered from a thread of at least - * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, typically - * less than 0.5 ms. This thread is guaranteed not to call back into the device. - * - * Parameters: - * display - the display which has received a vsync event - * timestamp - the CLOCK_MONOTONIC time at which the vsync event occurred, in - * nanoseconds - */ -typedef void (*HWC2_PFN_VSYNC)(hwc2_callback_data_t callbackData, - hwc2_display_t display, int64_t timestamp); - -/* vsync_2_4(..., display, timestamp, vsyncPeriodNanos) - * Descriptor: HWC2_CALLBACK_VSYNC_2_4 - * Required for HWC2 devices for composer 2.4 - * - * Notifies the client that a vsync event has occurred. This callback must - * only be triggered when vsync is enabled for this display (through - * setVsyncEnabled). - * - * This callback should be triggered from a thread of at least - * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, typically - * less than 0.5 ms. This thread is guaranteed not to call back into the device. - * - * Parameters: - * display - the display which has received a vsync event - * timestamp - the CLOCK_MONOTONIC time at which the vsync event occurred, in - * nanoseconds - * vsyncPeriodNanos - the display vsync period in nanoseconds i.e. the next onVsync2_4 is - * expected to be called vsyncPeriod nanoseconds after this call. - */ -typedef void (*HWC2_PFN_VSYNC_2_4)(hwc2_callback_data_t callbackData, - hwc2_display_t display, int64_t timestamp, hwc2_vsync_period_t vsyncPeriodNanos); - -/* vsyncPeriodTimingChanged(..., display, updated_timeline) - * Descriptor: HWC2_CALLBACK_VSYNC_PERIOD_TIMING_CHANGED - * Optional for HWC2 devices for composer 2.4 - * - * Notifies the client that the previously reported timing for vsync period change has been - * updated. This may occur if the composer missed the deadline for changing the vsync period - * or the client submitted a refresh frame too late. - * - * This callback should be triggered from a thread of at least - * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, typically - * less than 0.5 ms. This thread is guaranteed not to call back into the device. - * - * Parameters: - * display - the display which has received a vsync event - * updated_timeline - new timeline for the vsync period change - */ -typedef void (*HWC2_PFN_VSYNC_PERIOD_TIMING_CHANGED)(hwc2_callback_data_t callbackData, - hwc2_display_t display, hwc_vsync_period_change_timeline_t* updated_timeline); - -/* SeamlessPossible(..., display) - * Descriptor: HWC2_CALLBACK_SEAMLESS_POSSIBLE - * Optional for HWC2 devices for composer 2.4 - * - * Notifies the client that the conditions which previously led to returning SEAMLESS_NOT_POSSIBLE - * from setActiveConfigWithConstraints have changed and now seamless may be possible. Client should - * retry calling setActiveConfigWithConstraints. - * - * - * Parameters: - * display - a display setActiveConfigWithConstraints previously failed with - * SEAMLESS_NOT_POSSIBLE. - */ -typedef void (*HWC2_PFN_SEAMLESS_POSSIBLE)(hwc2_callback_data_t callbackData, - hwc2_display_t display); - -/* - * Device Functions - * - * All of these functions take as their first parameter a device pointer, so - * this parameter is omitted from the described parameter lists. - */ - -/* createVirtualDisplay(..., width, height, format, outDisplay) - * Descriptor: HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY - * Must be provided by all HWC2 devices - * - * Creates a new virtual display with the given width and height. The format - * passed into this function is the default format requested by the consumer of - * the virtual display output buffers. If a different format will be returned by - * the device, it should be returned in this parameter so it can be set properly - * when handing the buffers to the consumer. - * - * The display will be assumed to be on from the time the first frame is - * presented until the display is destroyed. - * - * Parameters: - * width - width in pixels - * height - height in pixels - * format - prior to the call, the default output buffer format selected by - * the consumer; after the call, the format the device will produce - * outDisplay - the newly-created virtual display; pointer will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_UNSUPPORTED - the width or height is too large for the device to - * be able to create a virtual display - * HWC2_ERROR_NO_RESOURCES - the device is unable to create a new virtual - * display at this time - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_CREATE_VIRTUAL_DISPLAY)( - hwc2_device_t* device, uint32_t width, uint32_t height, - int32_t* /*android_pixel_format_t*/ format, hwc2_display_t* outDisplay); - -/* destroyVirtualDisplay(..., display) - * Descriptor: HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY - * Must be provided by all HWC2 devices - * - * Destroys a virtual display. After this call all resources consumed by this - * display may be freed by the device and any operations performed on this - * display should fail. - * - * Parameters: - * display - the virtual display to destroy - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - the display handle which was passed in does not - * refer to a virtual display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_DESTROY_VIRTUAL_DISPLAY)( - hwc2_device_t* device, hwc2_display_t display); - -/* dump(..., outSize, outBuffer) - * Descriptor: HWC2_FUNCTION_DUMP - * Must be provided by all HWC2 devices - * - * Retrieves implementation-defined debug information, which will be displayed - * during, for example, `dumpsys SurfaceFlinger`. - * - * If called with outBuffer == NULL, the device should store a copy of the - * desired output and return its length in bytes in outSize. If the device - * already has a stored copy, that copy should be purged and replaced with a - * fresh copy. - * - * If called with outBuffer != NULL, the device should copy its stored version - * of the output into outBuffer and store how many bytes of data it copied into - * outSize. Prior to this call, the client will have populated outSize with the - * maximum number of bytes outBuffer can hold. The device must not write more - * than this amount into outBuffer. If the device does not currently have a - * stored copy, then it should return 0 in outSize. - * - * Any data written into outBuffer need not be null-terminated. - * - * Parameters: - * outSize - if outBuffer was NULL, the number of bytes needed to copy the - * device's stored output; if outBuffer was not NULL, the number of bytes - * written into it, which must not exceed the value stored in outSize - * prior to the call; pointer will be non-NULL - * outBuffer - the buffer to write the dump output into; may be NULL as - * described above; data written into this buffer need not be - * null-terminated - */ -typedef void (*HWC2_PFN_DUMP)(hwc2_device_t* device, uint32_t* outSize, - char* outBuffer); - -/* getMaxVirtualDisplayCount(...) - * Descriptor: HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT - * Must be provided by all HWC2 devices - * - * Returns the maximum number of virtual displays supported by this device - * (which may be 0). The client will not attempt to create more than this many - * virtual displays on this device. This number must not change for the lifetime - * of the device. - */ -typedef uint32_t (*HWC2_PFN_GET_MAX_VIRTUAL_DISPLAY_COUNT)( - hwc2_device_t* device); - -/* registerCallback(..., descriptor, callbackData, pointer) - * Descriptor: HWC2_FUNCTION_REGISTER_CALLBACK - * Must be provided by all HWC2 devices - * - * Provides a callback for the device to call. All callbacks take a callbackData - * item as the first parameter, so this value should be stored with the callback - * for later use. The callbackData may differ from one callback to another. If - * this function is called multiple times with the same descriptor, later - * callbacks replace earlier ones. - * - * Parameters: - * descriptor - which callback should be set - * callBackdata - opaque data which must be passed back through the callback - * pointer - a non-NULL function pointer corresponding to the descriptor - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_PARAMETER - descriptor was invalid - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_REGISTER_CALLBACK)( - hwc2_device_t* device, - int32_t /*hwc2_callback_descriptor_t*/ descriptor, - hwc2_callback_data_t callbackData, hwc2_function_pointer_t pointer); - -/* getDataspaceSaturationMatrix(..., dataspace, outMatrix) - * Descriptor: HWC2_FUNCTION_GET_DATASPACE_SATURATION_MATRIX - * Provided by HWC2 devices which don't return nullptr function pointer. - * - * Get the saturation matrix of the specified dataspace. The saturation matrix - * can be used to approximate the dataspace saturation operation performed by - * the HWC2 device when non-colorimetric mapping is allowed. It is to be - * applied on linear pixel values. - * - * Parameters: - * dataspace - the dataspace to query for - * outMatrix - a column-major 4x4 matrix (16 floats). It must be an identity - * matrix unless dataspace is HAL_DATASPACE_SRGB_LINEAR. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_PARAMETER - dataspace was invalid - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DATASPACE_SATURATION_MATRIX)( - hwc2_device_t* device, int32_t /*android_dataspace_t*/ dataspace, - float* outMatrix); - -/* - * Display Functions - * - * All of these functions take as their first two parameters a device pointer - * and a display handle, so these parameters are omitted from the described - * parameter lists. - */ - -/* acceptDisplayChanges(...) - * Descriptor: HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES - * Must be provided by all HWC2 devices - * - * Accepts the changes required by the device from the previous validateDisplay - * call (which may be queried using getChangedCompositionTypes) and revalidates - * the display. This function is equivalent to requesting the changed types from - * getChangedCompositionTypes, setting those types on the corresponding layers, - * and then calling validateDisplay again. - * - * After this call it must be valid to present this display. Calling this after - * validateDisplay returns 0 changes must succeed with HWC2_ERROR_NONE, but - * should have no other effect. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_ACCEPT_DISPLAY_CHANGES)( - hwc2_device_t* device, hwc2_display_t display); - -/* createLayer(..., outLayer) - * Descriptor: HWC2_FUNCTION_CREATE_LAYER - * Must be provided by all HWC2 devices - * - * Creates a new layer on the given display. - * - * Parameters: - * outLayer - the handle of the new layer; pointer will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_NO_RESOURCES - the device was unable to create this layer - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_CREATE_LAYER)(hwc2_device_t* device, - hwc2_display_t display, hwc2_layer_t* outLayer); - -/* destroyLayer(..., layer) - * Descriptor: HWC2_FUNCTION_DESTROY_LAYER - * Must be provided by all HWC2 devices - * - * Destroys the given layer. - * - * Parameters: - * layer - the handle of the layer to destroy - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_DESTROY_LAYER)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer); - -/* getActiveConfig(..., outConfig) - * Descriptor: HWC2_FUNCTION_GET_ACTIVE_CONFIG - * Must be provided by all HWC2 devices - * - * Retrieves which display configuration is currently active. - * - * If no display configuration is currently active, this function must return - * HWC2_ERROR_BAD_CONFIG and place no configuration handle in outConfig. It is - * the responsibility of the client to call setActiveConfig with a valid - * configuration before attempting to present anything on the display. - * - * Parameters: - * outConfig - the currently active display configuration; pointer will be - * non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_CONFIG - no configuration is currently active - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_ACTIVE_CONFIG)( - hwc2_device_t* device, hwc2_display_t display, - hwc2_config_t* outConfig); - -/* getChangedCompositionTypes(..., outNumElements, outLayers, outTypes) - * Descriptor: HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES - * Must be provided by all HWC2 devices - * - * Retrieves the layers for which the device requires a different composition - * type than had been set prior to the last call to validateDisplay. The client - * will either update its state with these types and call acceptDisplayChanges, - * or will set new types and attempt to validate the display again. - * - * outLayers and outTypes may be NULL to retrieve the number of elements which - * will be returned. The number of elements returned must be the same as the - * value returned in outNumTypes from the last call to validateDisplay. - * - * Parameters: - * outNumElements - if outLayers or outTypes were NULL, the number of layers - * and types which would have been returned; if both were non-NULL, the - * number of elements returned in outLayers and outTypes, which must not - * exceed the value stored in outNumElements prior to the call; pointer - * will be non-NULL - * outLayers - an array of layer handles - * outTypes - an array of composition types, each corresponding to an element - * of outLayers - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called for this - * display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_CHANGED_COMPOSITION_TYPES)( - hwc2_device_t* device, hwc2_display_t display, - uint32_t* outNumElements, hwc2_layer_t* outLayers, - int32_t* /*hwc2_composition_t*/ outTypes); - -/* getClientTargetSupport(..., width, height, format, dataspace) - * Descriptor: HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT - * Must be provided by all HWC2 devices - * - * Returns whether a client target with the given properties can be handled by - * the device. - * - * The valid formats can be found in android_pixel_format_t in - * <system/graphics.h>. - * - * For more about dataspaces, see setLayerDataspace. - * - * This function must return true for a client target with width and height - * equal to the active display configuration dimensions, - * HAL_PIXEL_FORMAT_RGBA_8888, and HAL_DATASPACE_UNKNOWN. It is not required to - * return true for any other configuration. - * - * Parameters: - * width - client target width in pixels - * height - client target height in pixels - * format - client target format - * dataspace - client target dataspace, as described in setLayerDataspace - * - * Returns HWC2_ERROR_NONE if the given configuration is supported or one of the - * following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_UNSUPPORTED - the given configuration is not supported - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_CLIENT_TARGET_SUPPORT)( - hwc2_device_t* device, hwc2_display_t display, uint32_t width, - uint32_t height, int32_t /*android_pixel_format_t*/ format, - int32_t /*android_dataspace_t*/ dataspace); - -/* getColorModes(..., outNumModes, outModes) - * Descriptor: HWC2_FUNCTION_GET_COLOR_MODES - * Must be provided by all HWC2 devices - * - * Returns the color modes supported on this display. - * - * The valid color modes can be found in android_color_mode_t in - * <system/graphics.h>. All HWC2 devices must support at least - * HAL_COLOR_MODE_NATIVE. - * - * outNumModes may be NULL to retrieve the number of modes which will be - * returned. - * - * Parameters: - * outNumModes - if outModes was NULL, the number of modes which would have - * been returned; if outModes was not NULL, the number of modes returned, - * which must not exceed the value stored in outNumModes prior to the - * call; pointer will be non-NULL - * outModes - an array of color modes - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_COLOR_MODES)( - hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumModes, - int32_t* /*android_color_mode_t*/ outModes); - -/* getRenderIntents(..., mode, outNumIntents, outIntents) - * Descriptor: HWC2_FUNCTION_GET_RENDER_INTENTS - * Provided by HWC2 devices which don't return nullptr function pointer. - * - * Returns the render intents supported on this display. - * - * The valid render intents can be found in android_render_intent_v1_1_t in - * <system/graphics.h>. All HWC2 devices must support at least - * HAL_RENDER_INTENT_COLORIMETRIC. - * - * outNumIntents may be NULL to retrieve the number of intents which will be - * returned. - * - * Parameters: - * mode - the color mode to query the render intents for - * outNumIntents - if outIntents was NULL, the number of intents which would - * have been returned; if outIntents was not NULL, the number of intents - * returned, which must not exceed the value stored in outNumIntents - * prior to the call; pointer will be non-NULL - * outIntents - an array of render intents - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_RENDER_INTENTS)( - hwc2_device_t* device, hwc2_display_t display, int32_t mode, - uint32_t* outNumIntents, - int32_t* /*android_render_intent_v1_1_t*/ outIntents); - -/* getDisplayAttribute(..., config, attribute, outValue) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE - * Must be provided by all HWC2 devices - * - * Returns a display attribute value for a particular display configuration. - * - * Any attribute which is not supported or for which the value is unknown by the - * device must return a value of -1. - * - * Parameters: - * config - the display configuration for which to return attribute values - * attribute - the attribute to query - * outValue - the value of the attribute; the pointer will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_CONFIG - config does not name a valid configuration for this - * display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_ATTRIBUTE)( - hwc2_device_t* device, hwc2_display_t display, hwc2_config_t config, - int32_t /*hwc2_attribute_t*/ attribute, int32_t* outValue); - -/* getDisplayConfigs(..., outNumConfigs, outConfigs) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_CONFIGS - * Must be provided by all HWC2 devices - * - * Returns handles for all of the valid display configurations on this display. - * - * outConfigs may be NULL to retrieve the number of elements which will be - * returned. - * - * Parameters: - * outNumConfigs - if outConfigs was NULL, the number of configurations which - * would have been returned; if outConfigs was not NULL, the number of - * configurations returned, which must not exceed the value stored in - * outNumConfigs prior to the call; pointer will be non-NULL - * outConfigs - an array of configuration handles - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_CONFIGS)( - hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumConfigs, - hwc2_config_t* outConfigs); - -/* getDisplayName(..., outSize, outName) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_NAME - * Must be provided by all HWC2 devices - * - * Returns a human-readable version of the display's name. - * - * outName may be NULL to retrieve the length of the name. - * - * Parameters: - * outSize - if outName was NULL, the number of bytes needed to return the - * name if outName was not NULL, the number of bytes written into it, - * which must not exceed the value stored in outSize prior to the call; - * pointer will be non-NULL - * outName - the display's name - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_NAME)( - hwc2_device_t* device, hwc2_display_t display, uint32_t* outSize, - char* outName); - -/* getDisplayRequests(..., outDisplayRequests, outNumElements, outLayers, - * outLayerRequests) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_REQUESTS - * Must be provided by all HWC2 devices - * - * Returns the display requests and the layer requests required for the last - * validated configuration. - * - * Display requests provide information about how the client should handle the - * client target. Layer requests provide information about how the client - * should handle an individual layer. - * - * If outLayers or outLayerRequests is NULL, the required number of layers and - * requests must be returned in outNumElements, but this number may also be - * obtained from validateDisplay as outNumRequests (outNumElements must be equal - * to the value returned in outNumRequests from the last call to - * validateDisplay). - * - * Parameters: - * outDisplayRequests - the display requests for the current validated state - * outNumElements - if outLayers or outLayerRequests were NULL, the number of - * elements which would have been returned, which must be equal to the - * value returned in outNumRequests from the last validateDisplay call on - * this display; if both were not NULL, the number of elements in - * outLayers and outLayerRequests, which must not exceed the value stored - * in outNumElements prior to the call; pointer will be non-NULL - * outLayers - an array of layers which all have at least one request - * outLayerRequests - the requests corresponding to each element of outLayers - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called for this - * display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_REQUESTS)( - hwc2_device_t* device, hwc2_display_t display, - int32_t* /*hwc2_display_request_t*/ outDisplayRequests, - uint32_t* outNumElements, hwc2_layer_t* outLayers, - int32_t* /*hwc2_layer_request_t*/ outLayerRequests); - -/* getDisplayType(..., outType) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_TYPE - * Must be provided by all HWC2 devices - * - * Returns whether the given display is a physical or virtual display. - * - * Parameters: - * outType - the type of the display; pointer will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_TYPE)( - hwc2_device_t* device, hwc2_display_t display, - int32_t* /*hwc2_display_type_t*/ outType); - -/* getDisplayIdentificationData(..., outPort, outDataSize, outData) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA - * Optional for HWC2 devices - * - * If supported, getDisplayIdentificationData returns the port and data that - * describe a physical display. The port is a unique number that identifies a - * physical connector (e.g. eDP, HDMI) for display output. The data blob is - * parsed to determine its format, typically EDID 1.3 as specified in VESA - * E-EDID Standard Release A Revision 1. - * - * Devices for which display identification is unsupported must return null when - * getFunction is called with HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA. - * - * Parameters: - * outPort - the connector to which the display is connected; - * pointer will be non-NULL - * outDataSize - if outData is NULL, the size in bytes of the data which would - * have been returned; if outData is not NULL, the size of outData, which - * must not exceed the value stored in outDataSize prior to the call; - * pointer will be non-NULL - * outData - the EDID 1.3 blob identifying the display - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_IDENTIFICATION_DATA)( - hwc2_device_t* device, hwc2_display_t display, uint8_t* outPort, - uint32_t* outDataSize, uint8_t* outData); - -/* getDozeSupport(..., outSupport) - * Descriptor: HWC2_FUNCTION_GET_DOZE_SUPPORT - * Must be provided by all HWC2 devices - * - * Returns whether the given display supports HWC2_POWER_MODE_DOZE and - * HWC2_POWER_MODE_DOZE_SUSPEND. DOZE_SUSPEND may not provide any benefit over - * DOZE (see the definition of hwc2_power_mode_t for more information), but if - * both DOZE and DOZE_SUSPEND are no different from HWC2_POWER_MODE_ON, the - * device should not claim support. - * - * Parameters: - * outSupport - whether the display supports doze modes (1 for yes, 0 for no); - * pointer will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DOZE_SUPPORT)( - hwc2_device_t* device, hwc2_display_t display, int32_t* outSupport); - -/* getHdrCapabilities(..., outNumTypes, outTypes, outMaxLuminance, - * outMaxAverageLuminance, outMinLuminance) - * Descriptor: HWC2_FUNCTION_GET_HDR_CAPABILITIES - * Must be provided by all HWC2 devices - * - * Returns the high dynamic range (HDR) capabilities of the given display, which - * are invariant with regard to the active configuration. - * - * Displays which are not HDR-capable must return no types in outTypes and set - * outNumTypes to 0. - * - * If outTypes is NULL, the required number of HDR types must be returned in - * outNumTypes. - * - * Parameters: - * outNumTypes - if outTypes was NULL, the number of types which would have - * been returned; if it was not NULL, the number of types stored in - * outTypes, which must not exceed the value stored in outNumTypes prior - * to the call; pointer will be non-NULL - * outTypes - an array of HDR types, may have 0 elements if the display is not - * HDR-capable - * outMaxLuminance - the desired content maximum luminance for this display in - * cd/m^2; pointer will be non-NULL - * outMaxAverageLuminance - the desired content maximum frame-average - * luminance for this display in cd/m^2; pointer will be non-NULL - * outMinLuminance - the desired content minimum luminance for this display in - * cd/m^2; pointer will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_HDR_CAPABILITIES)( - hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumTypes, - int32_t* /*android_hdr_t*/ outTypes, float* outMaxLuminance, - float* outMaxAverageLuminance, float* outMinLuminance); - -/* getReleaseFences(..., outNumElements, outLayers, outFences) - * Descriptor: HWC2_FUNCTION_GET_RELEASE_FENCES - * Must be provided by all HWC2 devices - * - * Retrieves the release fences for device layers on this display which will - * receive new buffer contents this frame. - * - * A release fence is a file descriptor referring to a sync fence object which - * will be signaled after the device has finished reading from the buffer - * presented in the prior frame. This indicates that it is safe to start writing - * to the buffer again. If a given layer's fence is not returned from this - * function, it will be assumed that the buffer presented on the previous frame - * is ready to be written. - * - * The fences returned by this function should be unique for each layer (even if - * they point to the same underlying sync object), and ownership of the fences - * is transferred to the client, which is responsible for closing them. - * - * If outLayers or outFences is NULL, the required number of layers and fences - * must be returned in outNumElements. - * - * Parameters: - * outNumElements - if outLayers or outFences were NULL, the number of - * elements which would have been returned; if both were not NULL, the - * number of elements in outLayers and outFences, which must not exceed - * the value stored in outNumElements prior to the call; pointer will be - * non-NULL - * outLayers - an array of layer handles - * outFences - an array of sync fence file descriptors as described above, - * each corresponding to an element of outLayers - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_RELEASE_FENCES)( - hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumElements, - hwc2_layer_t* outLayers, int32_t* outFences); - -/* presentDisplay(..., outPresentFence) - * Descriptor: HWC2_FUNCTION_PRESENT_DISPLAY - * Must be provided by all HWC2 devices - * - * Presents the current display contents on the screen (or in the case of - * virtual displays, into the output buffer). - * - * Prior to calling this function, the display must be successfully validated - * with validateDisplay. Note that setLayerBuffer and setLayerSurfaceDamage - * specifically do not count as layer state, so if there are no other changes - * to the layer state (or to the buffer's properties as described in - * setLayerBuffer), then it is safe to call this function without first - * validating the display. - * - * If this call succeeds, outPresentFence will be populated with a file - * descriptor referring to a present sync fence object. For physical displays, - * this fence will be signaled at the vsync when the result of composition of - * this frame starts to appear (for video-mode panels) or starts to transfer to - * panel memory (for command-mode panels). For virtual displays, this fence will - * be signaled when writes to the output buffer have completed and it is safe to - * read from it. - * - * Parameters: - * outPresentFence - a sync fence file descriptor as described above; pointer - * will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_NO_RESOURCES - no valid output buffer has been set for a virtual - * display - * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not successfully been called - * for this display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_PRESENT_DISPLAY)( - hwc2_device_t* device, hwc2_display_t display, - int32_t* outPresentFence); - -/* setActiveConfig(..., config) - * Descriptor: HWC2_FUNCTION_SET_ACTIVE_CONFIG - * Must be provided by all HWC2 devices - * - * Sets the active configuration for this display. Upon returning, the given - * display configuration should be active and remain so until either this - * function is called again or the display is disconnected. - * - * Parameters: - * config - the new display configuration - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_CONFIG - the configuration handle passed in is not valid for - * this display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_ACTIVE_CONFIG)( - hwc2_device_t* device, hwc2_display_t display, hwc2_config_t config); - -/* setClientTarget(..., target, acquireFence, dataspace, damage) - * Descriptor: HWC2_FUNCTION_SET_CLIENT_TARGET - * Must be provided by all HWC2 devices - * - * Sets the buffer handle which will receive the output of client composition. - * Layers marked as HWC2_COMPOSITION_CLIENT will be composited into this buffer - * prior to the call to presentDisplay, and layers not marked as - * HWC2_COMPOSITION_CLIENT should be composited with this buffer by the device. - * - * The buffer handle provided may be null if no layers are being composited by - * the client. This must not result in an error (unless an invalid display - * handle is also provided). - * - * Also provides a file descriptor referring to an acquire sync fence object, - * which will be signaled when it is safe to read from the client target buffer. - * If it is already safe to read from this buffer, -1 may be passed instead. - * The device must ensure that it is safe for the client to close this file - * descriptor at any point after this function is called. - * - * For more about dataspaces, see setLayerDataspace. - * - * The damage parameter describes a surface damage region as defined in the - * description of setLayerSurfaceDamage. - * - * Will be called before presentDisplay if any of the layers are marked as - * HWC2_COMPOSITION_CLIENT. If no layers are so marked, then it is not - * necessary to call this function. It is not necessary to call validateDisplay - * after changing the target through this function. - * - * Parameters: - * target - the new target buffer - * acquireFence - a sync fence file descriptor as described above - * dataspace - the dataspace of the buffer, as described in setLayerDataspace - * damage - the surface damage region - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - the new target handle was invalid - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_CLIENT_TARGET)( - hwc2_device_t* device, hwc2_display_t display, buffer_handle_t target, - int32_t acquireFence, int32_t /*android_dataspace_t*/ dataspace, - hwc_region_t damage); - -/* setColorMode(..., mode) - * Descriptor: HWC2_FUNCTION_SET_COLOR_MODE - * Must be provided by all HWC2 devices - * - * Sets the color mode of the given display. - * - * This must be called outside of validateDisplay/presentDisplay, and it takes - * effect on next presentDisplay. - * - * The valid color modes can be found in android_color_mode_t in - * <system/graphics.h>. All HWC2 devices must support at least - * HAL_COLOR_MODE_NATIVE, and displays are assumed to be in this mode upon - * hotplug. - * - * Parameters: - * mode - the mode to set - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - mode is not a valid color mode - * HWC2_ERROR_UNSUPPORTED - mode is not supported on this display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_COLOR_MODE)( - hwc2_device_t* device, hwc2_display_t display, - int32_t /*android_color_mode_t*/ mode); - -/* setColorModeWithIntent(..., mode, intent) - * Descriptor: HWC2_FUNCTION_SET_COLOR_MODE_WITH_RENDER_INTENT - * Provided by HWC2 devices which don't return nullptr function pointer. - * - * This must be called outside of validateDisplay/presentDisplay, and it takes - * effect on next presentDisplay. - * - * The valid color modes and render intents can be found in - * android_color_mode_t and android_render_intent_v1_1_t in - * <system/graphics.h>. All HWC2 devices must support at least - * HAL_COLOR_MODE_NATIVE and HAL_RENDER_INTENT_COLORIMETRIC, and displays are - * assumed to be in this mode and intent upon hotplug. - * - * Parameters: - * mode - the mode to set - * intent - the intent to set - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - mode/intent is not a valid color mode or - * render intent - * HWC2_ERROR_UNSUPPORTED - mode or intent is not supported on this display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_COLOR_MODE_WITH_RENDER_INTENT)( - hwc2_device_t* device, hwc2_display_t display, - int32_t /*android_color_mode_t*/ mode, - int32_t /*android_render_intent_v1_1_t */ intent); - -/* setColorTransform(..., matrix, hint) - * Descriptor: HWC2_FUNCTION_SET_COLOR_TRANSFORM - * Must be provided by all HWC2 devices - * - * Sets a color transform which will be applied after composition. - * - * If hint is not HAL_COLOR_TRANSFORM_ARBITRARY, then the device may use the - * hint to apply the desired color transform instead of using the color matrix - * directly. - * - * If the device is not capable of either using the hint or the matrix to apply - * the desired color transform, it should force all layers to client composition - * during validateDisplay. - * - * If HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM is present, then the client - * will never apply the color transform during client composition, even if all - * layers are being composed by the client. - * - * The matrix provided is an affine color transformation of the following form: - * - * |r.r r.g r.b 0| - * |g.r g.g g.b 0| - * |b.r b.g b.b 0| - * |Tr Tg Tb 1| - * - * This matrix will be provided in row-major form: {r.r, r.g, r.b, 0, g.r, ...}. - * - * Given a matrix of this form and an input color [R_in, G_in, B_in], the output - * color [R_out, G_out, B_out] will be: - * - * R_out = R_in * r.r + G_in * g.r + B_in * b.r + Tr - * G_out = R_in * r.g + G_in * g.g + B_in * b.g + Tg - * B_out = R_in * r.b + G_in * g.b + B_in * b.b + Tb - * - * Parameters: - * matrix - a 4x4 transform matrix (16 floats) as described above - * hint - a hint value which may be used instead of the given matrix unless it - * is HAL_COLOR_TRANSFORM_ARBITRARY - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - hint is not a valid color transform hint - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_COLOR_TRANSFORM)( - hwc2_device_t* device, hwc2_display_t display, const float* matrix, - int32_t /*android_color_transform_t*/ hint); - -/* getPerFrameMetadataKeys(..., outKeys) - * Descriptor: HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS - * Optional for HWC2 devices - * - * If supported (getFunction(HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS) is non-null), - * getPerFrameMetadataKeys returns the list of supported PerFrameMetadataKeys - * which are invariant with regard to the active configuration. - * - * Devices which are not HDR-capable, must return null when getFunction is called - * with HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS. - * - * If outKeys is NULL, the required number of PerFrameMetadataKey keys - * must be returned in outNumKeys. - * - * Parameters: - * outNumKeys - if outKeys is NULL, the number of keys which would have - * been returned; if outKeys is not NULL, the number of keys stored in - * outKeys, which must not exceed the value stored in outNumKeys prior - * to the call; pointer will be non-NULL - * outKeys - an array of hwc2_per_frame_metadata_key_t keys - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_PER_FRAME_METADATA_KEYS)( - hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumKeys, - int32_t* /*hwc2_per_frame_metadata_key_t*/ outKeys); - -/* setOutputBuffer(..., buffer, releaseFence) - * Descriptor: HWC2_FUNCTION_SET_OUTPUT_BUFFER - * Must be provided by all HWC2 devices - * - * Sets the output buffer for a virtual display. That is, the buffer to which - * the composition result will be written. - * - * Also provides a file descriptor referring to a release sync fence object, - * which will be signaled when it is safe to write to the output buffer. If it - * is already safe to write to the output buffer, -1 may be passed instead. The - * device must ensure that it is safe for the client to close this file - * descriptor at any point after this function is called. - * - * Must be called at least once before presentDisplay, but does not have any - * interaction with layer state or display validation. - * - * Parameters: - * buffer - the new output buffer - * releaseFence - a sync fence file descriptor as described above - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - the new output buffer handle was invalid - * HWC2_ERROR_UNSUPPORTED - display does not refer to a virtual display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_OUTPUT_BUFFER)( - hwc2_device_t* device, hwc2_display_t display, buffer_handle_t buffer, - int32_t releaseFence); - -/* setPowerMode(..., mode) - * Descriptor: HWC2_FUNCTION_SET_POWER_MODE - * Must be provided by all HWC2 devices - * - * Sets the power mode of the given display. The transition must be complete - * when this function returns. It is valid to call this function multiple times - * with the same power mode. - * - * All displays must support HWC2_POWER_MODE_ON and HWC2_POWER_MODE_OFF. Whether - * a display supports HWC2_POWER_MODE_DOZE or HWC2_POWER_MODE_DOZE_SUSPEND may - * be queried using getDozeSupport. - * - * Parameters: - * mode - the new power mode - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - mode was not a valid power mode - * HWC2_ERROR_UNSUPPORTED - mode was a valid power mode, but is not supported - * on this display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_POWER_MODE)( - hwc2_device_t* device, hwc2_display_t display, - int32_t /*hwc2_power_mode_t*/ mode); - -/* getReadbackBufferAttributes(..., outFormat, outDataspace) - * Optional for HWC2 devices - * - * Returns the format which should be used when allocating a buffer for use by - * device readback as well as the dataspace in which its contents should be - * interpreted. - * - * If readback is not supported by this HWC implementation, this call will also - * be able to return HWC2_ERROR_UNSUPPORTED so we can fall back to another method. - * Returning NULL to a getFunction request for this function will also indicate - * that readback is not supported. - * - * The width and height of this buffer will be those of the currently-active - * display configuration, and the usage flags will consist of the following: - * BufferUsage::CPU_READ | BufferUsage::GPU_TEXTURE | - * BufferUsage::COMPOSER_OUTPUT - * - * The format and dataspace provided must be sufficient such that if a - * correctly-configured buffer is passed into setReadbackBuffer, filled by - * the device, and then displayed by the client as a full-screen buffer, the - * output of the display remains the same (subject to the note about protected - * content in the description of setReadbackBuffer). - * - * If the active configuration or color mode of this display has changed since - * the previous call to this function, it will be called again prior to setting - * a readback buffer such that the returned format and dataspace can be updated - * accordingly. - * - * Parameters: - * outFormat - the format the client should use when allocating a device - * readback buffer; pointer will be non-NULL - * outDataspace - the dataspace the client will use when interpreting the - * contents of a device readback buffer; pointer will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * - * See also: - * setReadbackBuffer - * getReadbackBufferFence - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_READBACK_BUFFER_ATTRIBUTES)( - hwc2_device_t* device, hwc2_display_t display, - int32_t* /*android_pixel_format_t*/ outFormat, - int32_t* /*android_dataspace_t*/ outDataspace); - -/* getReadbackBufferFence(..., outFence) - * Optional for HWC2 devices - * - * Returns an acquire sync fence file descriptor which will signal when the - * buffer provided to setReadbackBuffer has been filled by the device and is - * safe for the client to read. - * - * If it is already safe to read from this buffer, -1 may be returned instead. - * The client takes ownership of this file descriptor and is responsible for - * closing it when it is no longer needed. - * - * This function will be called immediately after the composition cycle being - * captured into the readback buffer. The complete ordering of a readback buffer - * capture is as follows: - * - * getReadbackBufferAttributes - * // Readback buffer is allocated - * // Many frames may pass - * - * setReadbackBuffer - * validateDisplay - * presentDisplay - * getReadbackBufferFence - * // Implicitly wait on the acquire fence before accessing the buffer - * - * Parameters: - * outFence - a sync fence file descriptor as described above; pointer - * will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_NO_RESOURCES - the readback operation was successful, but - * resulted in a different validate result than would have occurred - * without readback - * HWC2_ERROR_UNSUPPORTED - the readback operation was unsuccessful because - * of resource constraints, the presence of protected content, or other - * reasons; -1 must be returned in outFence - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_READBACK_BUFFER_FENCE)( - hwc2_device_t* device, hwc2_display_t display, - int32_t* outFence); - -/* setReadbackBuffer(..., buffer, releaseFence) - * Optional for HWC2 devices - * - * Sets the readback buffer to be filled with the contents of the next - * composition performed for this display (i.e., the contents present at the - * time of the next validateDisplay/presentDisplay cycle). - * - * This buffer will have been allocated as described in - * getReadbackBufferAttributes and will be interpreted as being in the dataspace - * provided by the same. - * - * If there is hardware protected content on the display at the time of the next - * composition, the area of the readback buffer covered by such content must be - * completely black. Any areas of the buffer not covered by such content may - * optionally be black as well. - * - * The release fence file descriptor provided works identically to the one - * described for setOutputBuffer. - * - * This function will not be called between any call to validateDisplay and a - * subsequent call to presentDisplay. - * - * Parameters: - * buffer - the new readback buffer - * releaseFence - a sync fence file descriptor as described in setOutputBuffer - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - the new readback buffer handle was invalid - * - * See also: - * getReadbackBufferAttributes - * getReadbackBufferFence - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_READBACK_BUFFER)( - hwc2_device_t* device, hwc2_display_t display, - buffer_handle_t buffer, int32_t releaseFence); - -/* setVsyncEnabled(..., enabled) - * Descriptor: HWC2_FUNCTION_SET_VSYNC_ENABLED - * Must be provided by all HWC2 devices - * - * Enables or disables the vsync signal for the given display. Virtual displays - * never generate vsync callbacks, and any attempt to enable vsync for a virtual - * display though this function must return HWC2_ERROR_NONE and have no other - * effect. - * - * Parameters: - * enabled - whether to enable or disable vsync - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - enabled was an invalid value - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_VSYNC_ENABLED)( - hwc2_device_t* device, hwc2_display_t display, - int32_t /*hwc2_vsync_t*/ enabled); - -/* validateDisplay(..., outNumTypes, outNumRequests) - * Descriptor: HWC2_FUNCTION_VALIDATE_DISPLAY - * Must be provided by all HWC2 devices - * - * Instructs the device to inspect all of the layer state and determine if - * there are any composition type changes necessary before presenting the - * display. Permitted changes are described in the definition of - * hwc2_composition_t above. - * - * Also returns the number of layer requests required - * by the given layer configuration. - * - * Parameters: - * outNumTypes - the number of composition type changes required by the - * device; if greater than 0, the client must either set and validate new - * types, or call acceptDisplayChanges to accept the changes returned by - * getChangedCompositionTypes; must be the same as the number of changes - * returned by getChangedCompositionTypes (see the declaration of that - * function for more information); pointer will be non-NULL - * outNumRequests - the number of layer requests required by this layer - * configuration; must be equal to the number of layer requests returned - * by getDisplayRequests (see the declaration of that function for - * more information); pointer will be non-NULL - * - * Returns HWC2_ERROR_NONE if no changes are necessary and it is safe to present - * the display using the current layer state. Otherwise returns one of the - * following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_HAS_CHANGES - outNumTypes was greater than 0 (see parameter list - * for more information) - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_VALIDATE_DISPLAY)( - hwc2_device_t* device, hwc2_display_t display, - uint32_t* outNumTypes, uint32_t* outNumRequests); - -/* - * Layer Functions - * - * These are functions which operate on layers, but which do not modify state - * that must be validated before use. See also 'Layer State Functions' below. - * - * All of these functions take as their first three parameters a device pointer, - * a display handle for the display which contains the layer, and a layer - * handle, so these parameters are omitted from the described parameter lists. - */ - -/* setCursorPosition(..., x, y) - * Descriptor: HWC2_FUNCTION_SET_CURSOR_POSITION - * Must be provided by all HWC2 devices - * - * Asynchonously sets the position of a cursor layer. - * - * Prior to validateDisplay, a layer may be marked as HWC2_COMPOSITION_CURSOR. - * If validation succeeds (i.e., the device does not request a composition - * change for that layer), then once a buffer has been set for the layer and it - * has been presented, its position may be set by this function at any time - * between presentDisplay and any subsequent validateDisplay calls for this - * display. - * - * Once validateDisplay is called, this function will not be called again until - * the validate/present sequence is completed. - * - * May be called from any thread so long as it is not interleaved with the - * validate/present sequence as described above. - * - * Parameters: - * x - the new x coordinate (in pixels from the left of the screen) - * y - the new y coordinate (in pixels from the top of the screen) - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_LAYER - the layer is invalid or is not currently marked as - * HWC2_COMPOSITION_CURSOR - * HWC2_ERROR_NOT_VALIDATED - the device is currently in the middle of the - * validate/present sequence - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_CURSOR_POSITION)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - int32_t x, int32_t y); - -/* setLayerBuffer(..., buffer, acquireFence) - * Descriptor: HWC2_FUNCTION_SET_LAYER_BUFFER - * Must be provided by all HWC2 devices - * - * Sets the buffer handle to be displayed for this layer. If the buffer - * properties set at allocation time (width, height, format, and usage) have not - * changed since the previous frame, it is not necessary to call validateDisplay - * before calling presentDisplay unless new state needs to be validated in the - * interim. - * - * Also provides a file descriptor referring to an acquire sync fence object, - * which will be signaled when it is safe to read from the given buffer. If it - * is already safe to read from the buffer, -1 may be passed instead. The - * device must ensure that it is safe for the client to close this file - * descriptor at any point after this function is called. - * - * This function must return HWC2_ERROR_NONE and have no other effect if called - * for a layer with a composition type of HWC2_COMPOSITION_SOLID_COLOR (because - * it has no buffer) or HWC2_COMPOSITION_SIDEBAND or HWC2_COMPOSITION_CLIENT - * (because synchronization and buffer updates for these layers are handled - * elsewhere). - * - * Parameters: - * buffer - the buffer handle to set - * acquireFence - a sync fence file descriptor as described above - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - * HWC2_ERROR_BAD_PARAMETER - the buffer handle passed in was invalid - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_BUFFER)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - buffer_handle_t buffer, int32_t acquireFence); - -/* setLayerSurfaceDamage(..., damage) - * Descriptor: HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE - * Must be provided by all HWC2 devices - * - * Provides the region of the source buffer which has been modified since the - * last frame. This region does not need to be validated before calling - * presentDisplay. - * - * Once set through this function, the damage region remains the same until a - * subsequent call to this function. - * - * If damage.numRects > 0, then it may be assumed that any portion of the source - * buffer not covered by one of the rects has not been modified this frame. If - * damage.numRects == 0, then the whole source buffer must be treated as if it - * has been modified. - * - * If the layer's contents are not modified relative to the prior frame, damage - * will contain exactly one empty rect([0, 0, 0, 0]). - * - * The damage rects are relative to the pre-transformed buffer, and their origin - * is the top-left corner. They will not exceed the dimensions of the latched - * buffer. - * - * Parameters: - * damage - the new surface damage region - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_SURFACE_DAMAGE)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - hwc_region_t damage); - -/* setLayerPerFrameMetadata(..., numMetadata, metadata) - * Descriptor: HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA - * Optional for HWC2 devices - * - * If supported (getFunction(HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA) is - * non-null), sets the metadata for the given display for all following - * frames. - * - * Upon returning from this function, the metadata change must have - * fully taken effect. - * - * This function will only be called if getPerFrameMetadataKeys is non-NULL - * and returns at least one key. - * - * Parameters: - * numElements is the number of elements in each of the keys and metadata arrays - * keys is a pointer to the array of keys. - * outMetadata is a pointer to the corresponding array of metadata. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - metadata is not valid - * HWC2_ERROR_UNSUPPORTED - metadata is not supported on this display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_PER_FRAME_METADATA)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - uint32_t numElements, const int32_t* /*hw2_per_frame_metadata_key_t*/ keys, - const float* metadata); - -/* setLayerPerFrameMetadataBlobs(...,numElements, keys, sizes, blobs) - * Descriptor: HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS - * Optional for HWC2 devices - * - * If supported, (getFunction(HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS) - * is non-null), sets the metadata for the given display and layer. - * - * Upon returning from this function, the metadata change must have fully taken - * effect. - * - * This function must only be called if getPerFrameMetadataKeys is non-NULL - * and returns at least one key that corresponds to a blob type. - * - * Current valid blob type keys are: HDR10_PLUS_SEI - * - * Parameters: - * numElements is the number of elements in each of the keys, sizes, and - * metadata arrays - * keys is a pointer to an array of keys. Current valid keys are those listed - * above as valid blob type keys. - * sizes is a pointer to an array of unsigned ints specifying the sizes of - * each metadata blob - * metadata is a pointer to a blob of data holding all blobs contiguously in - * memory - * - * Returns HWC2_ERROR_NONE or one of the following erros: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_PARAMETER - sizes of keys and metadata parameters does - * not match numElements, numElements < 0, or keys contains a - * non-valid key (see above for current valid blob type keys). - * HWC2_ERROR_UNSUPPORTED - metadata is not supported on this display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_PER_FRAME_METADATA_BLOBS)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - uint32_t numElements, const int32_t* keys, const uint32_t* sizes, - const uint8_t* metadata); -/* - * Layer State Functions - * - * These functions modify the state of a given layer. They do not take effect - * until the display configuration is successfully validated with - * validateDisplay and the display contents are presented with presentDisplay. - * - * All of these functions take as their first three parameters a device pointer, - * a display handle for the display which contains the layer, and a layer - * handle, so these parameters are omitted from the described parameter lists. - */ - -/* setLayerBlendMode(..., mode) - * Descriptor: HWC2_FUNCTION_SET_LAYER_BLEND_MODE - * Must be provided by all HWC2 devices - * - * Sets the blend mode of the given layer. - * - * Parameters: - * mode - the new blend mode - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - * HWC2_ERROR_BAD_PARAMETER - an invalid blend mode was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_BLEND_MODE)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - int32_t /*hwc2_blend_mode_t*/ mode); - -/* setLayerColor(..., color) - * Descriptor: HWC2_FUNCTION_SET_LAYER_COLOR - * Must be provided by all HWC2 devices - * - * Sets the color of the given layer. If the composition type of the layer is - * not HWC2_COMPOSITION_SOLID_COLOR, this call must return HWC2_ERROR_NONE and - * have no other effect. - * - * Parameters: - * color - the new color - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_COLOR)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - hwc_color_t color); - -/* setLayerFloatColor(..., color) - * Descriptor: HWC2_FUNCTION_SET_LAYER_FLOAT_COLOR - * Provided by HWC2 devices which don't return nullptr function pointer. - * - * Sets the color of the given layer. If the composition type of the layer is - * not HWC2_COMPOSITION_SOLID_COLOR, this call must return HWC2_ERROR_NONE and - * have no other effect. - * - * Parameters: - * color - the new color in float type, rage is [0.0, 1.0], the colorspace is - * defined by the dataspace that gets set by calling setLayerDataspace. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_FLOAT_COLOR)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - hwc_float_color_t color); - -/* setLayerCompositionType(..., type) - * Descriptor: HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE - * Must be provided by all HWC2 devices - * - * Sets the desired composition type of the given layer. During validateDisplay, - * the device may request changes to the composition types of any of the layers - * as described in the definition of hwc2_composition_t above. - * - * Parameters: - * type - the new composition type - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - * HWC2_ERROR_BAD_PARAMETER - an invalid composition type was passed in - * HWC2_ERROR_UNSUPPORTED - a valid composition type was passed in, but it is - * not supported by this device - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_COMPOSITION_TYPE)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - int32_t /*hwc2_composition_t*/ type); - -/* setLayerDataspace(..., dataspace) - * Descriptor: HWC2_FUNCTION_SET_LAYER_DATASPACE - * Must be provided by all HWC2 devices - * - * Sets the dataspace that the current buffer on this layer is in. - * - * The dataspace provides more information about how to interpret the buffer - * contents, such as the encoding standard and color transform. - * - * See the values of android_dataspace_t in <system/graphics.h> for more - * information. - * - * Parameters: - * dataspace - the new dataspace - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_DATASPACE)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - int32_t /*android_dataspace_t*/ dataspace); - -/* setLayerDisplayFrame(..., frame) - * Descriptor: HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME - * Must be provided by all HWC2 devices - * - * Sets the display frame (the portion of the display covered by a layer) of the - * given layer. This frame will not exceed the display dimensions. - * - * Parameters: - * frame - the new display frame - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_DISPLAY_FRAME)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - hwc_rect_t frame); - -/* setLayerPlaneAlpha(..., alpha) - * Descriptor: HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA - * Must be provided by all HWC2 devices - * - * Sets an alpha value (a floating point value in the range [0.0, 1.0]) which - * will be applied to the whole layer. It can be conceptualized as a - * preprocessing step which applies the following function: - * if (blendMode == HWC2_BLEND_MODE_PREMULTIPLIED) - * out.rgb = in.rgb * planeAlpha - * out.a = in.a * planeAlpha - * - * If the device does not support this operation on a layer which is marked - * HWC2_COMPOSITION_DEVICE, it must request a composition type change to - * HWC2_COMPOSITION_CLIENT upon the next validateDisplay call. - * - * Parameters: - * alpha - the plane alpha value to apply - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_PLANE_ALPHA)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - float alpha); - -/* setLayerSidebandStream(..., stream) - * Descriptor: HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM - * Provided by HWC2 devices which support HWC2_CAPABILITY_SIDEBAND_STREAM - * - * Sets the sideband stream for this layer. If the composition type of the given - * layer is not HWC2_COMPOSITION_SIDEBAND, this call must return HWC2_ERROR_NONE - * and have no other effect. - * - * Parameters: - * stream - the new sideband stream - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - * HWC2_ERROR_BAD_PARAMETER - an invalid sideband stream was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_SIDEBAND_STREAM)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - const native_handle_t* stream); - -/* setLayerSourceCrop(..., crop) - * Descriptor: HWC2_FUNCTION_SET_LAYER_SOURCE_CROP - * Must be provided by all HWC2 devices - * - * Sets the source crop (the portion of the source buffer which will fill the - * display frame) of the given layer. This crop rectangle will not exceed the - * dimensions of the latched buffer. - * - * If the device is not capable of supporting a true float source crop (i.e., it - * will truncate or round the floats to integers), it should set this layer to - * HWC2_COMPOSITION_CLIENT when crop is non-integral for the most accurate - * rendering. - * - * If the device cannot support float source crops, but still wants to handle - * the layer, it should use the following code (or similar) to convert to - * an integer crop: - * intCrop.left = (int) ceilf(crop.left); - * intCrop.top = (int) ceilf(crop.top); - * intCrop.right = (int) floorf(crop.right); - * intCrop.bottom = (int) floorf(crop.bottom); - * - * Parameters: - * crop - the new source crop - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_SOURCE_CROP)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - hwc_frect_t crop); - -/* setLayerTransform(..., transform) - * Descriptor: HWC2_FUNCTION_SET_LAYER_TRANSFORM - * Must be provided by all HWC2 devices - * - * Sets the transform (rotation/flip) of the given layer. - * - * Parameters: - * transform - the new transform - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - * HWC2_ERROR_BAD_PARAMETER - an invalid transform was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_TRANSFORM)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - int32_t /*hwc_transform_t*/ transform); - -/* setLayerVisibleRegion(..., visible) - * Descriptor: HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION - * Must be provided by all HWC2 devices - * - * Specifies the portion of the layer that is visible, including portions under - * translucent areas of other layers. The region is in screen space, and will - * not exceed the dimensions of the screen. - * - * Parameters: - * visible - the new visible region, in screen space - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_VISIBLE_REGION)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - hwc_region_t visible); - -/* setLayerZOrder(..., z) - * Descriptor: HWC2_FUNCTION_SET_LAYER_Z_ORDER - * Must be provided by all HWC2 devices - * - * Sets the desired Z order (height) of the given layer. A layer with a greater - * Z value occludes a layer with a lesser Z value. - * - * Parameters: - * z - the new Z order - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_Z_ORDER)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - uint32_t z); - -/* setLayerColorTransform(..., matrix) - * Descriptor: HWC2_FUNCTION_SET_LAYER_COLOR_TRANSFORM - * Optional by all HWC2 devices - * - * Sets a matrix for color transform which will be applied on this layer - * before composition. - * - * If the device is not capable of apply the matrix on this layer, it must force - * this layer to client composition during VALIDATE_DISPLAY. - * - * The matrix provided is an affine color transformation of the following form: - * - * |r.r r.g r.b 0| - * |g.r g.g g.b 0| - * |b.r b.g b.b 0| - * |Tr Tg Tb 1| - * - * This matrix must be provided in row-major form: - * - * {r.r, r.g, r.b, 0, g.r, ...}. - * - * Given a matrix of this form and an input color [R_in, G_in, B_in], - * the input color must first be converted to linear space - * [R_linear, G_linear, B_linear], then the output linear color - * [R_out_linear, G_out_linear, B_out_linear] will be: - * - * R_out_linear = R_linear * r.r + G_linear * g.r + B_linear * b.r + Tr - * G_out_linear = R_linear * r.g + G_linear * g.g + B_linear * b.g + Tg - * B_out_linear = R_linear * r.b + G_linear * g.b + B_linear * b.b + Tb - * - * [R_out_linear, G_out_linear, B_out_linear] must then be converted to - * gamma space: [R_out, G_out, B_out] before blending. - * - * Parameters: - * matrix - a 4x4 transform matrix (16 floats) as described above - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_COLOR_TRANSFORM)( - hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, - const float* matrix); - -/* getDisplayedContentSamplingAttributes(..., - * format, dataspace, supported_components, max_frames) - * Descriptor: HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES - * Optional by all HWC2 devices - * - * Query for what types of color sampling the hardware supports. - * - * Parameters: - * format - The format of the sampled pixels; pointer will be non-NULL - * dataspace - The dataspace of the sampled pixels; pointer will be non-NULL - * supported_components - The mask of which components can be sampled; pointer - * will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY when an invalid display was passed in, or - * HWC2_ERROR_UNSUPPORTED when there is no efficient way to sample. - */ -typedef int32_t (*HWC2_PFN_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES)( - hwc2_device_t* device, hwc2_display_t display, - int32_t* /* android_pixel_format_t */ format, - int32_t* /* android_dataspace_t */ dataspace, - uint8_t* /* mask of android_component_t */ supported_components); - -/* setDisplayedContentSamplingEnabled(..., enabled) - * Descriptor: HWC2_FUNCTION_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED - * Optional by all HWC2 devices - * - * Enables or disables the collection of color content statistics - * on this display. - * - * Sampling occurs on the contents of the final composition on this display - * (i.e., the contents presented on screen). - * - * Sampling support is optional, and is set to DISABLE by default. - * On each call to ENABLE, all collected statistics will be reset. - * - * Sample data can be queried via getDisplayedContentSample(). - * - * Parameters: - * enabled - indicates whether to enable or disable sampling. - * component_mask - The mask of which components should be sampled. - * If zero, all supported components are to be enabled. - * max_frames - is the maximum number of frames that should be stored before - * discard. The sample represents the most-recently posted frames. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY when an invalid display handle was passed in, - * HWC2_ERROR_BAD_PARAMETER when enabled was an invalid value, or - * HWC2_ERROR_NO_RESOURCES when the requested ringbuffer size via max_frames - * was not available. - * HWC2_ERROR_UNSUPPORTED when there is no efficient way to sample. - */ -typedef int32_t (*HWC2_PFN_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED)( - hwc2_device_t* device, hwc2_display_t display, - int32_t /*hwc2_displayed_content_sampling_t*/ enabled, - uint8_t /* mask of android_component_t */ component_mask, - uint64_t max_frames); - -/* getDisplayedContentSample(..., component, max_frames, timestamp, - * samples_size, samples, frame_count) - * Descriptor: HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLE - * Optional by all HWC2 devices - * - * Collects the results of display content color sampling for display. - * - * Collection of data can occur whether the sampling is in ENABLE or - * DISABLE state. - * - * Parameters: - * max_frames - is the maximum number of frames that should be represented in - * the sample. The sample represents the most-recently posted frames. - * If max_frames is 0, all frames are to be represented by the sample. - * timestamp - is the timestamp after which any frames were posted that should - * be included in the sample. Timestamp is CLOCK_MONOTONIC. - * If timestamp is 0, do not filter from the sample by time. - * frame_count - The number of frames represented by this sample; pointer will - * be non-NULL. - * samples_size - The sizes of the color histogram representing the color - * sampling. Sample_sizes are indexed in the same order as - * HWC2_FORMAT_COMPONENT_. - * samples - The arrays of data corresponding to the sampling data. Samples are - * indexed in the same order as HWC2_FORMAT_COMPONENT_. - * The size of each sample is the samples_size for the same index. - * Each components sample is an array that is to be filled with the - * evenly-weighted buckets of a histogram counting how many times a pixel - * of the given component was displayed onscreen. Caller owns the data and - * pointer may be NULL to query samples_size. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY when an invalid display was passed in, or - * HWC2_ERROR_UNSUPPORTED when there is no efficient way to sample, or - * HWC2_ERROR_BAD_PARAMETER when the component is not supported by the hardware. - */ -typedef int32_t (*HWC2_PFN_GET_DISPLAYED_CONTENT_SAMPLE)( - hwc2_device_t* device, hwc2_display_t display, - uint64_t max_frames, uint64_t timestamp, - uint64_t* frame_count, int32_t samples_size[4], uint64_t* samples[4]); - -/* getDisplayCapabilities(..., outCapabilities) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_CAPABILITIES - * Required for HWC2 devices for composer 2.3 - * Optional for HWC2 devices for composer 2.1 and 2.2 - * - * getDisplayCapabilities returns a list of supported capabilities - * (as described in the definition of Capability above). - * This list must not change after initialization. - * - * Parameters: - * outNumCapabilities - if outCapabilities was nullptr, returns the number of capabilities - * if outCapabilities was not nullptr, returns the number of capabilities stored in - * outCapabilities, which must not exceed the value stored in outNumCapabilities prior - * to the call; pointer will be non-NULL - * outCapabilities - a list of supported capabilities. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_CAPABILITIES)( - hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumCapabilities, - uint32_t* outCapabilities); - -/* Use getDisplayCapabilities instead. If brightness is supported, must return - * DisplayCapability::BRIGHTNESS as one of the display capabilities via getDisplayCapabilities. - * Only use getDisplayCapabilities as the source of truth to query brightness support. - * - * getDisplayBrightnessSupport(displayToken) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_BRIGHTNESS_SUPPORT - * Required for HWC2 devices for composer 2.3 - * Optional for HWC2 devices for composer 2.1 and 2.2 - * - * getDisplayBrightnessSupport returns whether brightness operations are supported on a display. - * - * Parameters: - * outSupport - whether the display supports operations. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY when the display is invalid. - */ -typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_GET_DISPLAY_BRIGHTNESS_SUPPORT)(hwc2_device_t* device, - hwc2_display_t display, bool* outSupport); - -/* setDisplayBrightness(displayToken, brightnesss) - * Descriptor: HWC2_FUNCTION_SET_DISPLAY_BRIGHTNESS - * Required for HWC2 devices for composer 2.3 - * Optional for HWC2 devices for composer 2.1 and 2.2 - * - * setDisplayBrightness sets the brightness of a display. - * - * Parameters: - * brightness - a number between 0.0f (minimum brightness) and 1.0f (maximum brightness), or - * -1.0f to turn the backlight off. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY when the display is invalid, or - * HWC2_ERROR_UNSUPPORTED when brightness operations are not supported, or - * HWC2_ERROR_BAD_PARAMETER when the brightness is invalid, or - * HWC2_ERROR_NO_RESOURCES when the brightness cannot be applied. - */ -typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_SET_DISPLAY_BRIGHTNESS)(hwc2_device_t* device, - hwc2_display_t display, float brightness); - -/* Composer 2.4 additions */ - -/* getDisplayConnectionType(..., outType) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_CONNECTION_TYPE - * Optional for all HWC2 devices - * - * Returns whether the given physical display is internal or external. - * - * Parameters: - * outType - the connection type of the display; pointer will be non-NULL - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY when the display is invalid or virtual. - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_CONNECTION_TYPE)( - hwc2_device_t* device, hwc2_display_t display, - uint32_t* /*hwc2_display_connection_type_t*/ outType); - -/* getDisplayVsyncPeriod(..., outVsyncPeriods) - * Descriptor: HWC2_FUNCTION_GET_DISPLAY_VSYNC_PERIOD - * Required for HWC2 devices for composer 2.4 - * - * Retrieves which vsync period the display is currently using. - * - * If no display configuration is currently active, this function must - * return BAD_CONFIG. If a vsync period is about to change due to a - * setActiveConfigWithConstraints call, this function must return the current vsync period - * until the change has taken place. - * - * Parameters: - * outVsyncPeriod - the current vsync period of the display. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_CONFIG - no configuration is currently active - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_VSYNC_PERIOD)( - hwc2_device_t* device, hwc2_display_t display, hwc2_vsync_period_t* outVsyncPeriod); - -/* setActiveConfigWithConstraints(..., - * config, - * vsyncPeriodChangeConstraints, - * outTimeline) - * Descriptor: HWC2_FUNCTION_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS - * Required for HWC2 devices for composer 2.4 - * - * Sets the active configuration and the refresh rate for this display. - * If the new config shares the same config group as the current config, - * only the vsync period shall change. - * Upon returning, the given display configuration, except vsync period, must be active and - * remain so until either this function is called again or the display is disconnected. - * When the display starts to refresh at the new vsync period, onVsync_2_4 callback must be - * called with the new vsync period. - * - * Parameters: - * config - the new display configuration. - * vsyncPeriodChangeConstraints - constraints required for changing vsync period: - * desiredTimeNanos - the time in CLOCK_MONOTONIC after - * which the vsync period may change - * (i.e., the vsync period must not change - * before this time). - * seamlessRequired - if true, requires that the vsync period - * change must happen seamlessly without - * a noticeable visual artifact. - * When the conditions change and it may be - * possible to change the vsync period - * seamlessly, HWC2_CALLBACK_SEAMLESS_POSSIBLE - * callback must be called to indicate that - * caller should retry. - * outTimeline - the timeline for the vsync period change. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in. - * HWC2_ERROR_BAD_CONFIG - an invalid configuration handle passed in. - * HWC2_ERROR_SEAMLESS_NOT_ALLOWED - when seamlessRequired was true but config provided doesn't - * share the same config group as the current config. - * HWC2_ERROR_SEAMLESS_NOT_POSSIBLE - when seamlessRequired was true but the display cannot - * achieve the vsync period change without a noticeable - * visual artifact. - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS)( - hwc2_device_t* device, hwc2_display_t display, hwc2_config_t config, - hwc_vsync_period_change_constraints_t* vsyncPeriodChangeConstraints, - hwc_vsync_period_change_timeline_t* outTimeline); - -/* setAutoLowLatencyMode(displayToken, on) - * Descriptor: HWC2_FUNCTION_SET_AUTO_LOW_LATENCY_MODE - * Optional for HWC2 devices - * - * setAutoLowLatencyMode requests that the display goes into low latency mode. If the display - * is connected via HDMI 2.1, then Auto Low Latency Mode should be triggered. If the display is - * internally connected, then a custom low latency mode should be triggered (if available). - * - * Parameters: - * on - indicates whether to turn low latency mode on (=true) or off (=false) - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - when the display is invalid, or - * HWC2_ERROR_UNSUPPORTED - when the display does not support any low latency mode - */ -typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_SET_AUTO_LOW_LATENCY_MODE)(hwc2_device_t* device, - hwc2_display_t display, bool on); - -/* getSupportedContentTypes(..., outSupportedContentTypes) - * Descriptor: HWC2_FUNCTION_GET_SUPPORTED_CONTENT_TYPES - * Optional for HWC2 devices - * - * getSupportedContentTypes returns a list of supported content types - * (as described in the definition of ContentType above). - * This list must not change after initialization. - * - * Parameters: - * outNumSupportedContentTypes - if outSupportedContentTypes was nullptr, returns the number - * of supported content types; if outSupportedContentTypes was not nullptr, returns the - * number of capabilities stored in outSupportedContentTypes, which must not exceed the - * value stored in outNumSupportedContentTypes prior to the call; pointer will be non-NULL - * outSupportedContentTypes - a list of supported content types. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - */ -typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_GET_SUPPORTED_CONTENT_TYPES)(hwc2_device_t* device, - hwc2_display_t display, uint32_t* outNumSupportedContentTypes, uint32_t* outSupportedContentTypes); - -/* setContentType(displayToken, contentType) - * Descriptor: HWC2_FUNCTION_SET_CONTENT_TYPE - * Optional for HWC2 devices - * - * setContentType instructs the display that the content being shown is of the given contentType - * (one of GRAPHICS, PHOTO, CINEMA, GAME). - * - * According to the HDMI 1.4 specification, supporting all content types is optional. Whether - * the display supports a given content type is reported by getSupportedContentTypes. - * - * Parameters: - * contentType - the type of content that is currently being shown on the display - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - when the display is invalid, or - * HWC2_ERROR_UNSUPPORTED - when the given content type is a valid content type, but is not - * supported on this display, or - * HWC2_ERROR_BAD_PARAMETER - when the given content type is invalid - */ -typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_SET_CONTENT_TYPE)(hwc2_device_t* device, - hwc2_display_t display, int32_t /* hwc2_content_type_t */ contentType); - -/* getClientTargetProperty(..., outClientTargetProperty) - * Descriptor: HWC2_FUNCTION_GET_CLIENT_TARGET_PROPERTY - * Optional for HWC2 devices - * - * Retrieves the client target properties for which the hardware composer - * requests after the last call to validateDisplay. The client must set the - * properties of the client target to match the returned values. - * When this API is implemented, if client composition is needed, the hardware - * composer must return meaningful client target property with dataspace not - * setting to UNKNOWN. - * When the returned dataspace is set to UNKNOWN, it means hardware composer - * requests nothing, the client must ignore the returned client target property - * structrue. - * - * Parameters: - * outClientTargetProperty - the client target properties that hardware - * composer requests. If dataspace field is set to UNKNOWN, it means - * the hardware composer requests nothing, the client must ignore the - * returned client target property structure. - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called for this - * display - */ -typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_CLIENT_TARGET_PROPERTY)( - hwc2_device_t* device, hwc2_display_t display, - hwc_client_target_property_t* outClientTargetProperty); - -/* setLayerGenericMetadata(..., keyLength, key, mandatory, valueLength, value) - * Descriptor: HWC2_FUNCTION_SET_LAYER_GENERIC_METADATA - * Optional for HWC2 devices for composer 2.4+ - * - * setLayerGenericMetadata sets a piece of generic metadata for the given layer. - * If this function is called twice with the same key but different values, the - * newer value must override the older one. Calling this function with - * valueLength == 0 must reset that key's metadata as if it had not been set. - * - * A given piece of metadata may either be mandatory or a hint (non-mandatory) - * as indicated by the `mandatory` parameter. Mandatory metadata may affect the - * composition result, which is to say that it may cause a visible change in the - * final image. By contrast, hints may only affect the composition strategy, - * such as which layers are composited by the client, but must not cause a - * visible change in the final image. - * - * This implies that if the device does not understand a given key: - * - If the key is marked as mandatory, it must mark this layer for client - * composition in order to ensure the correct composition result - * - If the key is a hint, the metadata provided may be ignored - * - * Parameters: - * keyLength - the length of the key parameter - * key - the metadata key - * mandatory - indicates whether this particular key represents mandatory - * metadata or a hint, as described above - * valueLength - the length of the value parameter - * value - the metadata value - * - * Returns HWC2_ERROR_NONE or one of the following errors: - * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in - * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in - * HWC2_ERROR_BAD_PARAMETER - an unsupported key was passed in, or the value - * does not conform to the expected format for the key - */ -typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_SET_LAYER_GENERIC_METADATA)(hwc2_device_t* device, - hwc2_display_t display, hwc2_layer_t layer, uint32_t keyLength, const char* key, - bool mandatory, uint32_t valueLength, const uint8_t* value); - -/* getLayerGenericMetadataKey(..., keyIndex, outKeyLength, outKey, outMandatory) - * Descriptor: HWC2_FUNCTION_GET_LAYER_GENERIC_METADATA_KEY - * Optional for HWC2 devices for composer 2.4+ - * - * getLayerGenericMetadataKey allows the client to query which metadata keys are - * supported by the composer implementation. Only keys in this list will be - * passed into setLayerGenericMetadata. Additionally, the key names in this list - * must meet the following requirements: - * - Must be specified in reverse domain name notation - * - Must not start with 'com.android' or 'android' - * - Must be unique within the returned list of keys - * - Must correspond to a matching HIDL struct type, which defines the structure - * of its values. For example, the key 'com.example.V1-3.Foo' should - * correspond to a value of type com.example@1.3::Foo, which is defined in a - * vendor HAL extension - * - * Client code which calls this function will look similar to this: - * - * struct Key { - * std::string name; - * bool mandatory; - * } - * - * std::vector<Key> keys; - * uint32_t index = 0; - * uint32_t keyLength = 0; - * while (true) { - * getLayerGenericMetadataKey(device, index, &keyLength, nullptr, nullptr); - * if (keyLength == 0) break; - * - * Key key; - * key.name.resize(keyLength); - * getLayerGenericMetadataKey(device, index, &keyLength, key.name.data(), &key.mandatory); - * keys.push_back(key); - * - * ++index; - * } - * - * Parameters: - * keyIndex - the index of the key to retrieve. For values beyond the end of - * the list of supported keys, outKeyLength should return 0, and the - * client may assume that if the length is 0 for keyIndex N, then it is - * also 0 for all keyIndex values > N. - * outKeyLength - if outKey was nullptr, returns the length of the key to - * allow the client to allocate an appropriately-sized buffer; if outKey - * was not nullptr, returns the length of the returned key, which must not - * exceed the value stored in outKeyLength prior to the call; pointer will - * be non-null - * outKey - the key at the given index, or nullptr to query the key's length - * outMandatory - whether the given metadata is mandatory or not (see - * setLayerGenericMetadata for more information), may be nullptr - */ -typedef void (*HWC2_PFN_GET_LAYER_GENERIC_METADATA_KEY)(hwc2_device_t* device, uint32_t keyIndex, - uint32_t* outKeyLength, char* outKey, bool* outMandatory); - -__END_DECLS - -#endif +../../include_all/hardware/hwcomposer2.h
\ No newline at end of file diff --git a/include/hardware/hwcomposer_defs.h b/include/hardware/hwcomposer_defs.h index 3823765f..b742cce8 100644..120000 --- a/include/hardware/hwcomposer_defs.h +++ b/include/hardware/hwcomposer_defs.h @@ -1,344 +1 @@ -/* - * Copyright (C) 2010 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_INCLUDE_HARDWARE_HWCOMPOSER_DEFS_H -#define ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_DEFS_H - -#include <stdint.h> -#include <sys/cdefs.h> - -#include <hardware/gralloc.h> -#include <hardware/hardware.h> -#include <cutils/native_handle.h> - -__BEGIN_DECLS - -/* Shared by HWC1 and HWC2 */ - -#define HWC_HEADER_VERSION 1 - -#define HWC_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) - -#define HWC_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, HWC_HEADER_VERSION) -#define HWC_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION_2(1, 1, HWC_HEADER_VERSION) -#define HWC_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION_2(1, 2, HWC_HEADER_VERSION) -#define HWC_DEVICE_API_VERSION_1_3 HARDWARE_DEVICE_API_VERSION_2(1, 3, HWC_HEADER_VERSION) -#define HWC_DEVICE_API_VERSION_1_4 HARDWARE_DEVICE_API_VERSION_2(1, 4, HWC_HEADER_VERSION) -#define HWC_DEVICE_API_VERSION_1_5 HARDWARE_DEVICE_API_VERSION_2(1, 5, HWC_HEADER_VERSION) - -#define HWC_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION_2(2, 0, HWC_HEADER_VERSION) - -/** - * The id of this module - */ -#define HWC_HARDWARE_MODULE_ID "hwcomposer" - -/** - * Name of the sensors device to open - */ -#define HWC_HARDWARE_COMPOSER "composer" - -typedef struct hwc_color { - uint8_t r; - uint8_t g; - uint8_t b; - uint8_t a; -} hwc_color_t; - -typedef struct hwc_float_color { - float r; - float g; - float b; - float a; -} hwc_float_color_t; - -typedef struct hwc_frect { - float left; - float top; - float right; - float bottom; -} hwc_frect_t; - -typedef struct hwc_rect { - int left; - int top; - int right; - int bottom; -} hwc_rect_t; - -typedef struct hwc_region { - size_t numRects; - hwc_rect_t const* rects; -} hwc_region_t; - -/* - * hwc_layer_t::transform values - */ -typedef enum { - /* flip source image horizontally */ - HWC_TRANSFORM_FLIP_H = HAL_TRANSFORM_FLIP_H, - /* flip source image vertically */ - HWC_TRANSFORM_FLIP_V = HAL_TRANSFORM_FLIP_V, - /* rotate source image 90 degrees clock-wise */ - HWC_TRANSFORM_ROT_90 = HAL_TRANSFORM_ROT_90, - /* rotate source image 180 degrees */ - HWC_TRANSFORM_ROT_180 = HAL_TRANSFORM_ROT_180, - /* rotate source image 270 degrees clock-wise */ - HWC_TRANSFORM_ROT_270 = HAL_TRANSFORM_ROT_270, - /* flip source image horizontally, the rotate 90 degrees clock-wise */ - HWC_TRANSFORM_FLIP_H_ROT_90 = HAL_TRANSFORM_FLIP_H | HAL_TRANSFORM_ROT_90, - /* flip source image vertically, the rotate 90 degrees clock-wise */ - HWC_TRANSFORM_FLIP_V_ROT_90 = HAL_TRANSFORM_FLIP_V | HAL_TRANSFORM_ROT_90, -} hwc_transform_t; - -/* Constraints for changing vsync period */ -typedef struct hwc_vsync_period_change_constraints { - /* Time in CLOCK_MONOTONIC after which the vsync period may change - * (i.e., the vsync period must not change before this time). */ - int64_t desiredTimeNanos; - /* - * If true, requires that the vsync period change must happen seamlessly without - * a noticeable visual artifact. */ - uint8_t seamlessRequired; -} hwc_vsync_period_change_constraints_t; - -/* Timing for a vsync period change. */ -typedef struct hwc_vsync_period_change_timeline { - /* The time in CLOCK_MONOTONIC when the new display will start to refresh at - * the new vsync period. */ - int64_t newVsyncAppliedTimeNanos; - - /* Set to true if the client is required to sent a frame to be displayed before - * the change can take place. */ - uint8_t refreshRequired; - - /* The time in CLOCK_MONOTONIC when the client is expected to send the new frame. - * Should be ignored if refreshRequired is false. */ - int64_t refreshTimeNanos; -} hwc_vsync_period_change_timeline_t; - -typedef struct hwc_client_target_property { - // The pixel format of client target requested by hardware composer. - int32_t pixelFormat; - // The dataspace of the client target requested by hardware composer. - int32_t dataspace; -} hwc_client_target_property_t; - -/******************************************************************************* - * Beyond this point are things only used by HWC1, which should be ignored when - * implementing a HWC2 device - ******************************************************************************/ - -enum { - /* hwc_composer_device_t::set failed in EGL */ - HWC_EGL_ERROR = -1 -}; - -/* - * hwc_layer_t::hints values - * Hints are set by the HAL and read by SurfaceFlinger - */ -enum { - /* - * HWC can set the HWC_HINT_TRIPLE_BUFFER hint to indicate to SurfaceFlinger - * that it should triple buffer this layer. Typically HWC does this when - * the layer will be unavailable for use for an extended period of time, - * e.g. if the display will be fetching data directly from the layer and - * the layer can not be modified until after the next set(). - */ - HWC_HINT_TRIPLE_BUFFER = 0x00000001, - - /* - * HWC sets HWC_HINT_CLEAR_FB to tell SurfaceFlinger that it should clear the - * framebuffer with transparent pixels where this layer would be. - * SurfaceFlinger will only honor this flag when the layer has no blending - * - */ - HWC_HINT_CLEAR_FB = 0x00000002 -}; - -/* - * hwc_layer_t::flags values - * Flags are set by SurfaceFlinger and read by the HAL - */ -enum { - /* - * HWC_SKIP_LAYER is set by SurfaceFlinger to indicate that the HAL - * shall not consider this layer for composition as it will be handled - * by SurfaceFlinger (just as if compositionType was set to HWC_FRAMEBUFFER). - */ - HWC_SKIP_LAYER = 0x00000001, - - /* - * HWC_IS_CURSOR_LAYER is set by surfaceflinger to indicate that this - * layer is being used as a cursor on this particular display, and that - * surfaceflinger can potentially perform asynchronous position updates for - * this layer. If a call to prepare() returns HWC_CURSOR_OVERLAY for the - * composition type of this layer, then the hwcomposer will allow async - * position updates to this layer via setCursorPositionAsync(). - */ - HWC_IS_CURSOR_LAYER = 0x00000002 -}; - -/* - * hwc_layer_t::compositionType values - */ -enum { - /* this layer is to be drawn into the framebuffer by SurfaceFlinger */ - HWC_FRAMEBUFFER = 0, - - /* this layer will be handled in the HWC */ - HWC_OVERLAY = 1, - - /* this is the background layer. it's used to set the background color. - * there is only a single background layer */ - HWC_BACKGROUND = 2, - - /* this layer holds the result of compositing the HWC_FRAMEBUFFER layers. - * Added in HWC_DEVICE_API_VERSION_1_1. */ - HWC_FRAMEBUFFER_TARGET = 3, - - /* this layer's contents are taken from a sideband buffer stream. - * Added in HWC_DEVICE_API_VERSION_1_4. */ - HWC_SIDEBAND = 4, - - /* this layer's composition will be handled by hwcomposer by dedicated - cursor overlay hardware. hwcomposer will also all async position updates - of this layer outside of the normal prepare()/set() loop. Added in - HWC_DEVICE_API_VERSION_1_4. */ - HWC_CURSOR_OVERLAY = 5 - }; -/* - * hwc_layer_t::blending values - */ -enum { - /* no blending */ - HWC_BLENDING_NONE = 0x0100, - - /* ONE / ONE_MINUS_SRC_ALPHA */ - HWC_BLENDING_PREMULT = 0x0105, - - /* SRC_ALPHA / ONE_MINUS_SRC_ALPHA */ - HWC_BLENDING_COVERAGE = 0x0405 -}; - -/* attributes queriable with query() */ -enum { - /* - * Must return 1 if the background layer is supported, 0 otherwise. - */ - HWC_BACKGROUND_LAYER_SUPPORTED = 0, - - /* - * Returns the vsync period in nanoseconds. - * - * This query is not used for HWC_DEVICE_API_VERSION_1_1 and later. - * Instead, the per-display attribute HWC_DISPLAY_VSYNC_PERIOD is used. - */ - HWC_VSYNC_PERIOD = 1, - - /* - * Availability: HWC_DEVICE_API_VERSION_1_1 - * Returns a mask of supported display types. - */ - HWC_DISPLAY_TYPES_SUPPORTED = 2, -}; - -/* display attributes returned by getDisplayAttributes() */ -enum { - /* Indicates the end of an attribute list */ - HWC_DISPLAY_NO_ATTRIBUTE = 0, - - /* The vsync period in nanoseconds */ - HWC_DISPLAY_VSYNC_PERIOD = 1, - - /* The number of pixels in the horizontal and vertical directions. */ - HWC_DISPLAY_WIDTH = 2, - HWC_DISPLAY_HEIGHT = 3, - - /* The number of pixels per thousand inches of this configuration. - * - * Scaling DPI by 1000 allows it to be stored in an int without losing - * too much precision. - * - * If the DPI for a configuration is unavailable or the HWC implementation - * considers it unreliable, it should set these attributes to zero. - */ - HWC_DISPLAY_DPI_X = 4, - HWC_DISPLAY_DPI_Y = 5, - - /* Indicates which of the vendor-defined color transforms is provided by - * this configuration. */ - HWC_DISPLAY_COLOR_TRANSFORM = 6, - - /* The configuration group this config is associated to. The groups are defined - * to mark certain configs as similar and changing configs within a certain group - * may be done seamlessly in some conditions. setActiveConfigWithConstraints. */ - HWC_DISPLAY_CONFIG_GROUP = 7, -}; - -/* Allowed events for hwc_methods::eventControl() */ -enum { - HWC_EVENT_VSYNC = 0 -}; - -/* Display types and associated mask bits. */ -enum { - HWC_DISPLAY_PRIMARY = 0, - HWC_DISPLAY_EXTERNAL = 1, // HDMI, DP, etc. - HWC_DISPLAY_VIRTUAL = 2, - - HWC_NUM_PHYSICAL_DISPLAY_TYPES = 2, - HWC_NUM_DISPLAY_TYPES = 3, -}; - -enum { - HWC_DISPLAY_PRIMARY_BIT = 1 << HWC_DISPLAY_PRIMARY, - HWC_DISPLAY_EXTERNAL_BIT = 1 << HWC_DISPLAY_EXTERNAL, - HWC_DISPLAY_VIRTUAL_BIT = 1 << HWC_DISPLAY_VIRTUAL, -}; - -/* Display power modes */ -enum { - /* The display is turned off (blanked). */ - HWC_POWER_MODE_OFF = 0, - /* The display is turned on and configured in a low power state - * that is suitable for presenting ambient information to the user, - * possibly with lower fidelity than normal but greater efficiency. */ - HWC_POWER_MODE_DOZE = 1, - /* The display is turned on normally. */ - HWC_POWER_MODE_NORMAL = 2, - /* The display is configured as in HWC_POWER_MODE_DOZE but may - * stop applying frame buffer updates from the graphics subsystem. - * This power mode is effectively a hint from the doze dream to - * tell the hardware that it is done drawing to the display for the - * time being and that the display should remain on in a low power - * state and continue showing its current contents indefinitely - * until the mode changes. - * - * This mode may also be used as a signal to enable hardware-based doze - * functionality. In this case, the doze dream is effectively - * indicating that the hardware is free to take over the display - * and manage it autonomously to implement low power always-on display - * functionality. */ - HWC_POWER_MODE_DOZE_SUSPEND = 3, -}; - -/*****************************************************************************/ - -__END_DECLS - -#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_DEFS_H */ +../../include_all/hardware/hwcomposer_defs.h
\ No newline at end of file diff --git a/include/hardware/input.h b/include/hardware/input.h index c4a4cb51..82154a2e 100644..120000 --- a/include/hardware/input.h +++ b/include/hardware/input.h @@ -1,573 +1 @@ -/* - * 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_INCLUDE_HARDWARE_INPUT_H -#define ANDROID_INCLUDE_HARDWARE_INPUT_H - -#include <hardware/hardware.h> -#include <stdint.h> - -__BEGIN_DECLS - -#define INPUT_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) -#define INPUT_HARDWARE_MODULE_ID "input" - -#define INPUT_INSTANCE_EVDEV "evdev" - -typedef enum input_bus { - INPUT_BUS_BT, - INPUT_BUS_USB, - INPUT_BUS_SERIAL, - INPUT_BUS_BUILTIN -} input_bus_t; - -typedef struct input_host input_host_t; - -typedef struct input_device_handle input_device_handle_t; - -typedef struct input_device_identifier input_device_identifier_t; - -typedef struct input_device_definition input_device_definition_t; - -typedef struct input_report_definition input_report_definition_t; - -typedef struct input_report input_report_t; - -typedef struct input_collection input_collection_t; - -typedef struct input_property_map input_property_map_t; - -typedef struct input_property input_property_t; - -typedef enum { - // keycodes - INPUT_USAGE_KEYCODE_UNKNOWN, - INPUT_USAGE_KEYCODE_SOFT_LEFT, - INPUT_USAGE_KEYCODE_SOFT_RIGHT, - INPUT_USAGE_KEYCODE_HOME, - INPUT_USAGE_KEYCODE_BACK, - INPUT_USAGE_KEYCODE_CALL, - INPUT_USAGE_KEYCODE_ENDCALL, - INPUT_USAGE_KEYCODE_0, - INPUT_USAGE_KEYCODE_1, - INPUT_USAGE_KEYCODE_2, - INPUT_USAGE_KEYCODE_3, - INPUT_USAGE_KEYCODE_4, - INPUT_USAGE_KEYCODE_5, - INPUT_USAGE_KEYCODE_6, - INPUT_USAGE_KEYCODE_7, - INPUT_USAGE_KEYCODE_8, - INPUT_USAGE_KEYCODE_9, - INPUT_USAGE_KEYCODE_STAR, - INPUT_USAGE_KEYCODE_POUND, - INPUT_USAGE_KEYCODE_DPAD_UP, - INPUT_USAGE_KEYCODE_DPAD_DOWN, - INPUT_USAGE_KEYCODE_DPAD_LEFT, - INPUT_USAGE_KEYCODE_DPAD_RIGHT, - INPUT_USAGE_KEYCODE_DPAD_CENTER, - INPUT_USAGE_KEYCODE_VOLUME_UP, - INPUT_USAGE_KEYCODE_VOLUME_DOWN, - INPUT_USAGE_KEYCODE_POWER, - INPUT_USAGE_KEYCODE_CAMERA, - INPUT_USAGE_KEYCODE_CLEAR, - INPUT_USAGE_KEYCODE_A, - INPUT_USAGE_KEYCODE_B, - INPUT_USAGE_KEYCODE_C, - INPUT_USAGE_KEYCODE_D, - INPUT_USAGE_KEYCODE_E, - INPUT_USAGE_KEYCODE_F, - INPUT_USAGE_KEYCODE_G, - INPUT_USAGE_KEYCODE_H, - INPUT_USAGE_KEYCODE_I, - INPUT_USAGE_KEYCODE_J, - INPUT_USAGE_KEYCODE_K, - INPUT_USAGE_KEYCODE_L, - INPUT_USAGE_KEYCODE_M, - INPUT_USAGE_KEYCODE_N, - INPUT_USAGE_KEYCODE_O, - INPUT_USAGE_KEYCODE_P, - INPUT_USAGE_KEYCODE_Q, - INPUT_USAGE_KEYCODE_R, - INPUT_USAGE_KEYCODE_S, - INPUT_USAGE_KEYCODE_T, - INPUT_USAGE_KEYCODE_U, - INPUT_USAGE_KEYCODE_V, - INPUT_USAGE_KEYCODE_W, - INPUT_USAGE_KEYCODE_X, - INPUT_USAGE_KEYCODE_Y, - INPUT_USAGE_KEYCODE_Z, - INPUT_USAGE_KEYCODE_COMMA, - INPUT_USAGE_KEYCODE_PERIOD, - INPUT_USAGE_KEYCODE_ALT_LEFT, - INPUT_USAGE_KEYCODE_ALT_RIGHT, - INPUT_USAGE_KEYCODE_SHIFT_LEFT, - INPUT_USAGE_KEYCODE_SHIFT_RIGHT, - INPUT_USAGE_KEYCODE_TAB, - INPUT_USAGE_KEYCODE_SPACE, - INPUT_USAGE_KEYCODE_SYM, - INPUT_USAGE_KEYCODE_EXPLORER, - INPUT_USAGE_KEYCODE_ENVELOPE, - INPUT_USAGE_KEYCODE_ENTER, - INPUT_USAGE_KEYCODE_DEL, - INPUT_USAGE_KEYCODE_GRAVE, - INPUT_USAGE_KEYCODE_MINUS, - INPUT_USAGE_KEYCODE_EQUALS, - INPUT_USAGE_KEYCODE_LEFT_BRACKET, - INPUT_USAGE_KEYCODE_RIGHT_BRACKET, - INPUT_USAGE_KEYCODE_BACKSLASH, - INPUT_USAGE_KEYCODE_SEMICOLON, - INPUT_USAGE_KEYCODE_APOSTROPHE, - INPUT_USAGE_KEYCODE_SLASH, - INPUT_USAGE_KEYCODE_AT, - INPUT_USAGE_KEYCODE_NUM, - INPUT_USAGE_KEYCODE_HEADSETHOOK, - INPUT_USAGE_KEYCODE_FOCUS, // *Camera* focus - INPUT_USAGE_KEYCODE_PLUS, - INPUT_USAGE_KEYCODE_MENU, - INPUT_USAGE_KEYCODE_NOTIFICATION, - INPUT_USAGE_KEYCODE_SEARCH, - INPUT_USAGE_KEYCODE_MEDIA_PLAY_PAUSE, - INPUT_USAGE_KEYCODE_MEDIA_STOP, - INPUT_USAGE_KEYCODE_MEDIA_NEXT, - INPUT_USAGE_KEYCODE_MEDIA_PREVIOUS, - INPUT_USAGE_KEYCODE_MEDIA_REWIND, - INPUT_USAGE_KEYCODE_MEDIA_FAST_FORWARD, - INPUT_USAGE_KEYCODE_MUTE, - INPUT_USAGE_KEYCODE_PAGE_UP, - INPUT_USAGE_KEYCODE_PAGE_DOWN, - INPUT_USAGE_KEYCODE_PICTSYMBOLS, - INPUT_USAGE_KEYCODE_SWITCH_CHARSET, - INPUT_USAGE_KEYCODE_BUTTON_A, - INPUT_USAGE_KEYCODE_BUTTON_B, - INPUT_USAGE_KEYCODE_BUTTON_C, - INPUT_USAGE_KEYCODE_BUTTON_X, - INPUT_USAGE_KEYCODE_BUTTON_Y, - INPUT_USAGE_KEYCODE_BUTTON_Z, - INPUT_USAGE_KEYCODE_BUTTON_L1, - INPUT_USAGE_KEYCODE_BUTTON_R1, - INPUT_USAGE_KEYCODE_BUTTON_L2, - INPUT_USAGE_KEYCODE_BUTTON_R2, - INPUT_USAGE_KEYCODE_BUTTON_THUMBL, - INPUT_USAGE_KEYCODE_BUTTON_THUMBR, - INPUT_USAGE_KEYCODE_BUTTON_START, - INPUT_USAGE_KEYCODE_BUTTON_SELECT, - INPUT_USAGE_KEYCODE_BUTTON_MODE, - INPUT_USAGE_KEYCODE_ESCAPE, - INPUT_USAGE_KEYCODE_FORWARD_DEL, - INPUT_USAGE_KEYCODE_CTRL_LEFT, - INPUT_USAGE_KEYCODE_CTRL_RIGHT, - INPUT_USAGE_KEYCODE_CAPS_LOCK, - INPUT_USAGE_KEYCODE_SCROLL_LOCK, - INPUT_USAGE_KEYCODE_META_LEFT, - INPUT_USAGE_KEYCODE_META_RIGHT, - INPUT_USAGE_KEYCODE_FUNCTION, - INPUT_USAGE_KEYCODE_SYSRQ, - INPUT_USAGE_KEYCODE_BREAK, - INPUT_USAGE_KEYCODE_MOVE_HOME, - INPUT_USAGE_KEYCODE_MOVE_END, - INPUT_USAGE_KEYCODE_INSERT, - INPUT_USAGE_KEYCODE_FORWARD, - INPUT_USAGE_KEYCODE_MEDIA_PLAY, - INPUT_USAGE_KEYCODE_MEDIA_PAUSE, - INPUT_USAGE_KEYCODE_MEDIA_CLOSE, - INPUT_USAGE_KEYCODE_MEDIA_EJECT, - INPUT_USAGE_KEYCODE_MEDIA_RECORD, - INPUT_USAGE_KEYCODE_F1, - INPUT_USAGE_KEYCODE_F2, - INPUT_USAGE_KEYCODE_F3, - INPUT_USAGE_KEYCODE_F4, - INPUT_USAGE_KEYCODE_F5, - INPUT_USAGE_KEYCODE_F6, - INPUT_USAGE_KEYCODE_F7, - INPUT_USAGE_KEYCODE_F8, - INPUT_USAGE_KEYCODE_F9, - INPUT_USAGE_KEYCODE_F10, - INPUT_USAGE_KEYCODE_F11, - INPUT_USAGE_KEYCODE_F12, - INPUT_USAGE_KEYCODE_NUM_LOCK, - INPUT_USAGE_KEYCODE_NUMPAD_0, - INPUT_USAGE_KEYCODE_NUMPAD_1, - INPUT_USAGE_KEYCODE_NUMPAD_2, - INPUT_USAGE_KEYCODE_NUMPAD_3, - INPUT_USAGE_KEYCODE_NUMPAD_4, - INPUT_USAGE_KEYCODE_NUMPAD_5, - INPUT_USAGE_KEYCODE_NUMPAD_6, - INPUT_USAGE_KEYCODE_NUMPAD_7, - INPUT_USAGE_KEYCODE_NUMPAD_8, - INPUT_USAGE_KEYCODE_NUMPAD_9, - INPUT_USAGE_KEYCODE_NUMPAD_DIVIDE, - INPUT_USAGE_KEYCODE_NUMPAD_MULTIPLY, - INPUT_USAGE_KEYCODE_NUMPAD_SUBTRACT, - INPUT_USAGE_KEYCODE_NUMPAD_ADD, - INPUT_USAGE_KEYCODE_NUMPAD_DOT, - INPUT_USAGE_KEYCODE_NUMPAD_COMMA, - INPUT_USAGE_KEYCODE_NUMPAD_ENTER, - INPUT_USAGE_KEYCODE_NUMPAD_EQUALS, - INPUT_USAGE_KEYCODE_NUMPAD_LEFT_PAREN, - INPUT_USAGE_KEYCODE_NUMPAD_RIGHT_PAREN, - INPUT_USAGE_KEYCODE_VOLUME_MUTE, - INPUT_USAGE_KEYCODE_INFO, - INPUT_USAGE_KEYCODE_CHANNEL_UP, - INPUT_USAGE_KEYCODE_CHANNEL_DOWN, - INPUT_USAGE_KEYCODE_ZOOM_IN, - INPUT_USAGE_KEYCODE_ZOOM_OUT, - INPUT_USAGE_KEYCODE_TV, - INPUT_USAGE_KEYCODE_WINDOW, - INPUT_USAGE_KEYCODE_GUIDE, - INPUT_USAGE_KEYCODE_DVR, - INPUT_USAGE_KEYCODE_BOOKMARK, - INPUT_USAGE_KEYCODE_CAPTIONS, - INPUT_USAGE_KEYCODE_SETTINGS, - INPUT_USAGE_KEYCODE_TV_POWER, - INPUT_USAGE_KEYCODE_TV_INPUT, - INPUT_USAGE_KEYCODE_STB_POWER, - INPUT_USAGE_KEYCODE_STB_INPUT, - INPUT_USAGE_KEYCODE_AVR_POWER, - INPUT_USAGE_KEYCODE_AVR_INPUT, - INPUT_USAGE_KEYCODE_PROG_RED, - INPUT_USAGE_KEYCODE_PROG_GREEN, - INPUT_USAGE_KEYCODE_PROG_YELLOW, - INPUT_USAGE_KEYCODE_PROG_BLUE, - INPUT_USAGE_KEYCODE_APP_SWITCH, - INPUT_USAGE_KEYCODE_BUTTON_1, - INPUT_USAGE_KEYCODE_BUTTON_2, - INPUT_USAGE_KEYCODE_BUTTON_3, - INPUT_USAGE_KEYCODE_BUTTON_4, - INPUT_USAGE_KEYCODE_BUTTON_5, - INPUT_USAGE_KEYCODE_BUTTON_6, - INPUT_USAGE_KEYCODE_BUTTON_7, - INPUT_USAGE_KEYCODE_BUTTON_8, - INPUT_USAGE_KEYCODE_BUTTON_9, - INPUT_USAGE_KEYCODE_BUTTON_10, - INPUT_USAGE_KEYCODE_BUTTON_11, - INPUT_USAGE_KEYCODE_BUTTON_12, - INPUT_USAGE_KEYCODE_BUTTON_13, - INPUT_USAGE_KEYCODE_BUTTON_14, - INPUT_USAGE_KEYCODE_BUTTON_15, - INPUT_USAGE_KEYCODE_BUTTON_16, - INPUT_USAGE_KEYCODE_LANGUAGE_SWITCH, - INPUT_USAGE_KEYCODE_MANNER_MODE, - INPUT_USAGE_KEYCODE_3D_MODE, - INPUT_USAGE_KEYCODE_CONTACTS, - INPUT_USAGE_KEYCODE_CALENDAR, - INPUT_USAGE_KEYCODE_MUSIC, - INPUT_USAGE_KEYCODE_CALCULATOR, - INPUT_USAGE_KEYCODE_ZENKAKU_HANKAKU, - INPUT_USAGE_KEYCODE_EISU, - INPUT_USAGE_KEYCODE_MUHENKAN, - INPUT_USAGE_KEYCODE_HENKAN, - INPUT_USAGE_KEYCODE_KATAKANA_HIRAGANA, - INPUT_USAGE_KEYCODE_YEN, - INPUT_USAGE_KEYCODE_RO, - INPUT_USAGE_KEYCODE_KANA, - INPUT_USAGE_KEYCODE_ASSIST, - INPUT_USAGE_KEYCODE_BRIGHTNESS_DOWN, - INPUT_USAGE_KEYCODE_BRIGHTNESS_UP, - INPUT_USAGE_KEYCODE_MEDIA_AUDIO_TRACK, - INPUT_USAGE_KEYCODE_SLEEP, - INPUT_USAGE_KEYCODE_WAKEUP, - INPUT_USAGE_KEYCODE_PAIRING, - INPUT_USAGE_KEYCODE_MEDIA_TOP_MENU, - INPUT_USAGE_KEYCODE_11, - INPUT_USAGE_KEYCODE_12, - INPUT_USAGE_KEYCODE_LAST_CHANNEL, - INPUT_USAGE_KEYCODE_TV_DATA_SERVICE, - INPUT_USAGE_KEYCODE_VOICE_ASSIST, - INPUT_USAGE_KEYCODE_TV_RADIO_SERVICE, - INPUT_USAGE_KEYCODE_TV_TELETEXT, - INPUT_USAGE_KEYCODE_TV_NUMBER_ENTRY, - INPUT_USAGE_KEYCODE_TV_TERRESTRIAL_ANALOG, - INPUT_USAGE_KEYCODE_TV_TERRESTRIAL_DIGITAL, - INPUT_USAGE_KEYCODE_TV_SATELLITE, - INPUT_USAGE_KEYCODE_TV_SATELLITE_BS, - INPUT_USAGE_KEYCODE_TV_SATELLITE_CS, - INPUT_USAGE_KEYCODE_TV_SATELLITE_SERVICE, - INPUT_USAGE_KEYCODE_TV_NETWORK, - INPUT_USAGE_KEYCODE_TV_ANTENNA_CABLE, - INPUT_USAGE_KEYCODE_TV_INPUT_HDMI_1, - INPUT_USAGE_KEYCODE_TV_INPUT_HDMI_2, - INPUT_USAGE_KEYCODE_TV_INPUT_HDMI_3, - INPUT_USAGE_KEYCODE_TV_INPUT_HDMI_4, - INPUT_USAGE_KEYCODE_TV_INPUT_COMPOSITE_1, - INPUT_USAGE_KEYCODE_TV_INPUT_COMPOSITE_2, - INPUT_USAGE_KEYCODE_TV_INPUT_COMPONENT_1, - INPUT_USAGE_KEYCODE_TV_INPUT_COMPONENT_2, - INPUT_USAGE_KEYCODE_TV_INPUT_VGA_1, - INPUT_USAGE_KEYCODE_TV_AUDIO_DESCRIPTION, - INPUT_USAGE_KEYCODE_TV_AUDIO_DESCRIPTION_MIX_UP, - INPUT_USAGE_KEYCODE_TV_AUDIO_DESCRIPTION_MIX_DOWN, - INPUT_USAGE_KEYCODE_TV_ZOOM_MODE, - INPUT_USAGE_KEYCODE_TV_CONTENTS_MENU, - INPUT_USAGE_KEYCODE_TV_MEDIA_CONTEXT_MENU, - INPUT_USAGE_KEYCODE_TV_TIMER_PROGRAMMING, - INPUT_USAGE_KEYCODE_HELP, - - // axes - INPUT_USAGE_AXIS_X, - INPUT_USAGE_AXIS_Y, - INPUT_USAGE_AXIS_Z, - INPUT_USAGE_AXIS_RX, - INPUT_USAGE_AXIS_RY, - INPUT_USAGE_AXIS_RZ, - INPUT_USAGE_AXIS_HAT_X, - INPUT_USAGE_AXIS_HAT_Y, - INPUT_USAGE_AXIS_PRESSURE, - INPUT_USAGE_AXIS_SIZE, - INPUT_USAGE_AXIS_TOUCH_MAJOR, - INPUT_USAGE_AXIS_TOUCH_MINOR, - INPUT_USAGE_AXIS_TOOL_MAJOR, - INPUT_USAGE_AXIS_TOOL_MINOR, - INPUT_USAGE_AXIS_ORIENTATION, - INPUT_USAGE_AXIS_VSCROLL, - INPUT_USAGE_AXIS_HSCROLL, - INPUT_USAGE_AXIS_LTRIGGER, - INPUT_USAGE_AXIS_RTRIGGER, - INPUT_USAGE_AXIS_THROTTLE, - INPUT_USAGE_AXIS_RUDDER, - INPUT_USAGE_AXIS_WHEEL, - INPUT_USAGE_AXIS_GAS, - INPUT_USAGE_AXIS_BRAKE, - INPUT_USAGE_AXIS_DISTANCE, - INPUT_USAGE_AXIS_TILT, - INPUT_USAGE_AXIS_GENERIC_1, - INPUT_USAGE_AXIS_GENERIC_2, - INPUT_USAGE_AXIS_GENERIC_3, - INPUT_USAGE_AXIS_GENERIC_4, - INPUT_USAGE_AXIS_GENERIC_5, - INPUT_USAGE_AXIS_GENERIC_6, - INPUT_USAGE_AXIS_GENERIC_7, - INPUT_USAGE_AXIS_GENERIC_8, - INPUT_USAGE_AXIS_GENERIC_9, - INPUT_USAGE_AXIS_GENERIC_10, - INPUT_USAGE_AXIS_GENERIC_11, - INPUT_USAGE_AXIS_GENERIC_12, - INPUT_USAGE_AXIS_GENERIC_13, - INPUT_USAGE_AXIS_GENERIC_14, - INPUT_USAGE_AXIS_GENERIC_15, - INPUT_USAGE_AXIS_GENERIC_16, - - // leds - INPUT_USAGE_LED_NUM_LOCK, - INPUT_USAGE_LED_CAPS_LOCK, - INPUT_USAGE_LED_SCROLL_LOCK, - INPUT_USAGE_LED_COMPOSE, - INPUT_USAGE_LED_KANA, - INPUT_USAGE_LED_SLEEP, - INPUT_USAGE_LED_SUSPEND, - INPUT_USAGE_LED_MUTE, - INPUT_USAGE_LED_MISC, - INPUT_USAGE_LED_MAIL, - INPUT_USAGE_LED_CHARGING, - INPUT_USAGE_LED_CONTROLLER_1, - INPUT_USAGE_LED_CONTROLLER_2, - INPUT_USAGE_LED_CONTROLLER_3, - INPUT_USAGE_LED_CONTROLLER_4, - - // switches - INPUT_USAGE_SWITCH_UNKNOWN, - INPUT_USAGE_SWITCH_LID, - INPUT_USAGE_SWITCH_KEYPAD_SLIDE, - INPUT_USAGE_SWITCH_HEADPHONE_INSERT, - INPUT_USAGE_SWITCH_MICROPHONE_INSERT, - INPUT_USAGE_SWITCH_LINEOUT_INSERT, - INPUT_USAGE_SWITCH_CAMERA_LENS_COVER, - - // mouse buttons - // (see android.view.MotionEvent) - INPUT_USAGE_BUTTON_UNKNOWN, - INPUT_USAGE_BUTTON_PRIMARY, // left - INPUT_USAGE_BUTTON_SECONDARY, // right - INPUT_USAGE_BUTTON_TERTIARY, // middle - INPUT_USAGE_BUTTON_FORWARD, - INPUT_USAGE_BUTTON_BACK, -} input_usage_t; - -typedef enum input_collection_id { - INPUT_COLLECTION_ID_TOUCH, - INPUT_COLLECTION_ID_KEYBOARD, - INPUT_COLLECTION_ID_MOUSE, - INPUT_COLLECTION_ID_TOUCHPAD, - INPUT_COLLECTION_ID_SWITCH, - // etc -} input_collection_id_t; - -typedef struct input_message input_message_t; - -typedef struct input_host_callbacks { - - /** - * Creates a device identifier with the given properties. - * The unique ID should be a string that precisely identifies a given piece of hardware. For - * example, an input device connected via Bluetooth could use its MAC address as its unique ID. - */ - input_device_identifier_t* (*create_device_identifier)(input_host_t* host, - const char* name, int32_t product_id, int32_t vendor_id, - input_bus_t bus, const char* unique_id); - - /** - * Allocates the device definition which will describe the input capabilities of a device. A - * device definition may be used to register as many devices as desired. - */ - input_device_definition_t* (*create_device_definition)(input_host_t* host); - - /** - * Allocate either an input report, which the HAL will use to tell the host of incoming input - * events, or an output report, which the host will use to tell the HAL of desired state - * changes (e.g. setting an LED). - */ - input_report_definition_t* (*create_input_report_definition)(input_host_t* host); - input_report_definition_t* (*create_output_report_definition)(input_host_t* host); - - /** - * Frees the report definition. - */ - void (*free_report_definition)(input_host_t* host, input_report_definition_t* report_def); - - /** - * Append the report to the given input device. - */ - void (*input_device_definition_add_report)(input_host_t* host, - input_device_definition_t* d, input_report_definition_t* r); - - /** - * Add a collection with the given arity and ID. A collection describes a set - * of logically grouped properties such as the X and Y coordinates of a single finger touch or - * the set of keys on a keyboard. The arity declares how many repeated instances of this - * collection will appear in whatever report it is attached to. The ID describes the type of - * grouping being represented by the collection. For example, a touchscreen capable of - * reporting up to 2 fingers simultaneously might have a collection with the X and Y - * coordinates, an arity of 2, and an ID of INPUT_COLLECTION_USAGE_TOUCHSCREEN. Any given ID - * may only be present once for a given report. - */ - void (*input_report_definition_add_collection)(input_host_t* host, - input_report_definition_t* report, input_collection_id_t id, int32_t arity); - - /** - * Declare an int usage with the given properties. The report and collection defines where the - * usage is being declared. - */ - void (*input_report_definition_declare_usage_int)(input_host_t* host, - input_report_definition_t* report, input_collection_id_t id, - input_usage_t usage, int32_t min, int32_t max, float resolution); - - /** - * Declare a set of boolean usages with the given properties. The report and collection - * defines where the usages are being declared. - */ - void (*input_report_definition_declare_usages_bool)(input_host_t* host, - input_report_definition_t* report, input_collection_id_t id, - input_usage_t* usage, size_t usage_count); - - - /** - * Register a given input device definition. This notifies the host that an input device has - * been connected and gives a description of all its capabilities. - */ - input_device_handle_t* (*register_device)(input_host_t* host, - input_device_identifier_t* id, input_device_definition_t* d); - - /** Unregister the given device */ - void (*unregister_device)(input_host_t* host, input_device_handle_t* handle); - - /** - * Allocate a report that will contain all of the state as described by the given report. - */ - input_report_t* (*input_allocate_report)(input_host_t* host, input_report_definition_t* r); - - /** - * Add an int usage value to a report. - */ - void (*input_report_set_usage_int)(input_host_t* host, input_report_t* r, - input_collection_id_t id, input_usage_t usage, int32_t value, int32_t arity_index); - - /** - * Add a boolean usage value to a report. - */ - void (*input_report_set_usage_bool)(input_host_t* host, input_report_t* r, - input_collection_id_t id, input_usage_t usage, bool value, int32_t arity_index); - - void (*report_event)(input_host_t* host, input_device_handle_t* d, input_report_t* report); - - /** - * Retrieve the set of properties for the device. The returned - * input_property_map_t* may be used to query specific properties via the - * input_get_device_property callback. - */ - input_property_map_t* (*input_get_device_property_map)(input_host_t* host, - input_device_identifier_t* id); - /** - * Retrieve a property for the device with the given key. Returns NULL if - * the key does not exist, or an input_property_t* that must be freed using - * input_free_device_property(). Using an input_property_t after the - * corresponding input_property_map_t is freed is undefined. - */ - input_property_t* (*input_get_device_property)(input_host_t* host, - input_property_map_t* map, const char* key); - - /** - * Get the key for the input property. Returns NULL if the property is NULL. - * The returned const char* is owned by the input_property_t. - */ - const char* (*input_get_property_key)(input_host_t* host, input_property_t* property); - - /** - * Get the value for the input property. Returns NULL if the property is - * NULL. The returned const char* is owned by the input_property_t. - */ - const char* (*input_get_property_value)(input_host_t* host, input_property_t* property); - - /** - * Frees the input_property_t*. - */ - void (*input_free_device_property)(input_host_t* host, input_property_t* property); - - /** - * Frees the input_property_map_t*. - */ - void (*input_free_device_property_map)(input_host_t* host, input_property_map_t* map); -} input_host_callbacks_t; - -typedef struct input_module input_module_t; - -struct input_module { - /** - * Common methods of the input module. This *must* be the first member - * of input_module as users of this structure will cast a hw_module_t - * to input_module pointer in contexts where it's known - * the hw_module_t references a input_module. - */ - struct hw_module_t common; - - /** - * Initialize the module with host callbacks. At this point the HAL should start up whatever - * infrastructure it needs to in order to process input events. - */ - void (*init)(const input_module_t* module, input_host_t* host, input_host_callbacks_t cb); - - /** - * Sends an output report with a new set of state the host would like the given device to - * assume. - */ - void (*notify_report)(const input_module_t* module, input_report_t* report); -}; - -static inline int input_open(const struct hw_module_t** module, const char* type) { - return hw_get_module_by_class(INPUT_HARDWARE_MODULE_ID, type, module); -} - -__END_DECLS - -#endif /* ANDROID_INCLUDE_HARDWARE_INPUT_H */ +../../include_all/hardware/input.h
\ No newline at end of file diff --git a/include/hardware/keymaster1.h b/include/hardware/keymaster1.h index 99693806..89c95266 100644..120000 --- a/include/hardware/keymaster1.h +++ b/include/hardware/keymaster1.h @@ -1,548 +1 @@ -/* - * 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_KEYMASTER1_H -#define ANDROID_HARDWARE_KEYMASTER1_H - -#include <hardware/keymaster_common.h> -#include <hardware/keymaster_defs.h> - -__BEGIN_DECLS - -/** - * Keymaster1 device definition - */ -struct keymaster1_device { - /** - * Common methods of the keymaster device. This *must* be the first member of - * keymaster_device as users of this structure will cast a hw_device_t to - * keymaster_device pointer in contexts where it's known the hw_device_t references a - * keymaster_device. - */ - struct hw_device_t common; - - /** - * THIS IS DEPRECATED. Use the new "module_api_version" and "hal_api_version" - * fields in the keymaster_module initialization instead. - */ - uint32_t client_version; - - /** - * See flags defined for keymaster0_devices::flags in keymaster_common.h - */ - uint32_t flags; - - void* context; - - /** - * \deprecated Generates a public and private key. The key-blob returned is opaque and must - * subsequently provided for signing and verification. - * - * Returns: 0 on success or an error code less than 0. - */ - int (*generate_keypair)(const struct keymaster1_device* dev, const keymaster_keypair_t key_type, - const void* key_params, uint8_t** key_blob, size_t* key_blob_length); - - /** - * \deprecated Imports a public and private key pair. The imported keys will be in PKCS#8 format - * with DER encoding (Java standard). The key-blob returned is opaque and will be subsequently - * provided for signing and verification. - * - * Returns: 0 on success or an error code less than 0. - */ - int (*import_keypair)(const struct keymaster1_device* dev, const uint8_t* key, - const size_t key_length, uint8_t** key_blob, size_t* key_blob_length); - - /** - * \deprecated Gets the public key part of a key pair. The public key must be in X.509 format - * (Java standard) encoded byte array. - * - * Returns: 0 on success or an error code less than 0. On error, x509_data - * should not be allocated. - */ - int (*get_keypair_public)(const struct keymaster1_device* dev, const uint8_t* key_blob, - const size_t key_blob_length, uint8_t** x509_data, - size_t* x509_data_length); - - /** - * \deprecated Deletes the key pair associated with the key blob. - * - * This function is optional and should be set to NULL if it is not - * implemented. - * - * Returns 0 on success or an error code less than 0. - */ - int (*delete_keypair)(const struct keymaster1_device* dev, const uint8_t* key_blob, - const size_t key_blob_length); - - /** - * \deprecated Deletes all keys in the hardware keystore. Used when keystore is reset - * completely. - * - * This function is optional and should be set to NULL if it is not - * implemented. - * - * Returns 0 on success or an error code less than 0. - */ - int (*delete_all)(const struct keymaster1_device* dev); - - /** - * \deprecated Signs data using a key-blob generated before. This can use either an asymmetric - * key or a secret key. - * - * Returns: 0 on success or an error code less than 0. - */ - int (*sign_data)(const struct keymaster1_device* dev, const void* signing_params, - const uint8_t* key_blob, const size_t key_blob_length, const uint8_t* data, - const size_t data_length, uint8_t** signed_data, size_t* signed_data_length); - - /** - * \deprecated Verifies data signed with a key-blob. This can use either an asymmetric key or a - * secret key. - * - * Returns: 0 on successful verification or an error code less than 0. - */ - int (*verify_data)(const struct keymaster1_device* dev, const void* signing_params, - const uint8_t* key_blob, const size_t key_blob_length, - const uint8_t* signed_data, const size_t signed_data_length, - const uint8_t* signature, const size_t signature_length); - - /** - * Gets algorithms supported. - * - * \param[in] dev The keymaster device structure. - * - * \param[out] algorithms Array of algorithms supported. The caller takes ownership of the - * array and must free() it. - * - * \param[out] algorithms_length Length of \p algorithms. - */ - keymaster_error_t (*get_supported_algorithms)(const struct keymaster1_device* dev, - keymaster_algorithm_t** algorithms, - size_t* algorithms_length); - - /** - * Gets the block modes supported for the specified algorithm. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] algorithm The algorithm for which supported modes will be returned. - * - * \param[out] modes Array of modes supported. The caller takes ownership of the array and must - * free() it. - * - * \param[out] modes_length Length of \p modes. - */ - keymaster_error_t (*get_supported_block_modes)(const struct keymaster1_device* dev, - keymaster_algorithm_t algorithm, - keymaster_purpose_t purpose, - keymaster_block_mode_t** modes, - size_t* modes_length); - - /** - * Gets the padding modes supported for the specified algorithm. Caller assumes ownership of - * the allocated array. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] algorithm The algorithm for which supported padding modes will be returned. - * - * \param[out] modes Array of padding modes supported. The caller takes ownership of the array - * and must free() it. - * - * \param[out] modes_length Length of \p modes. - */ - keymaster_error_t (*get_supported_padding_modes)(const struct keymaster1_device* dev, - keymaster_algorithm_t algorithm, - keymaster_purpose_t purpose, - keymaster_padding_t** modes, - size_t* modes_length); - - /** - * Gets the digests supported for the specified algorithm. Caller assumes ownership of the - * allocated array. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] algorithm The algorithm for which supported digests will be returned. - * - * \param[out] digests Array of digests supported. The caller takes ownership of the array and - * must free() it. - * - * \param[out] digests_length Length of \p digests. - */ - keymaster_error_t (*get_supported_digests)(const struct keymaster1_device* dev, - keymaster_algorithm_t algorithm, - keymaster_purpose_t purpose, - keymaster_digest_t** digests, - size_t* digests_length); - - /** - * Gets the key import formats supported for keys of the specified algorithm. Caller assumes - * ownership of the allocated array. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] algorithm The algorithm for which supported formats will be returned. - * - * \param[out] formats Array of formats supported. The caller takes ownership of the array and - * must free() it. - * - * \param[out] formats_length Length of \p formats. - */ - keymaster_error_t (*get_supported_import_formats)(const struct keymaster1_device* dev, - keymaster_algorithm_t algorithm, - keymaster_key_format_t** formats, - size_t* formats_length); - - /** - * Gets the key export formats supported for keys of the specified algorithm. Caller assumes - * ownership of the allocated array. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] algorithm The algorithm for which supported formats will be returned. - * - * \param[out] formats Array of formats supported. The caller takes ownership of the array and - * must free() it. - * - * \param[out] formats_length Length of \p formats. - */ - keymaster_error_t (*get_supported_export_formats)(const struct keymaster1_device* dev, - keymaster_algorithm_t algorithm, - keymaster_key_format_t** formats, - size_t* formats_length); - - /** - * Adds entropy to the RNG used by keymaster. Entropy added through this method is guaranteed - * not to be the only source of entropy used, and the mixing function is required to be secure, - * in the sense that if the RNG is seeded (from any source) with any data the attacker cannot - * predict (or control), then the RNG output is indistinguishable from random. Thus, if the - * entropy from any source is good, the output will be good. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] data Random data to be mixed in. - * - * \param[in] data_length Length of \p data. - */ - keymaster_error_t (*add_rng_entropy)(const struct keymaster1_device* dev, const uint8_t* data, - size_t data_length); - - /** - * Generates a key, or key pair, returning a key blob and/or a description of the key. - * - * Key generation parameters are defined as keymaster tag/value pairs, provided in \p params. - * See keymaster_tag_t for the full list. Some values that are always required for generation - * of useful keys are: - * - * - KM_TAG_ALGORITHM; - * - KM_TAG_PURPOSE; and - * - (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED. - * - * KM_TAG_AUTH_TIMEOUT should generally be specified unless KM_TAG_NO_AUTH_REQUIRED is present, - * or the user will have to authenticate for every use. - * - * KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH and KM_TAG_DIGEST must be specified for - * algorithms that require them. - * - * The following tags may not be specified; their values will be provided by the implementation. - * - * - KM_TAG_ORIGIN, - * - KM_TAG_ROLLBACK_RESISTANT, - * - KM_TAG_CREATION_DATETIME - * - * \param[in] dev The keymaster device structure. - * - * \param[in] params Array of key generation parameters. - * - * \param[in] params_count Length of \p params. - * - * \param[out] key_blob returns the generated key. \p key_blob must not be NULL. The caller - * assumes ownership key_blob->key_material and must free() it. - * - * \param[out] characteristics returns the characteristics of the key that was, generated, if - * non-NULL. If non-NULL, the caller assumes ownership and must deallocate with - * keymaster_free_characteristics(). Note that KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and - * KM_TAG_APPLICATION_DATA are never returned. - */ - keymaster_error_t (*generate_key)(const struct keymaster1_device* dev, - const keymaster_key_param_set_t* params, - keymaster_key_blob_t* key_blob, - keymaster_key_characteristics_t** characteristics); - - /** - * Returns the characteristics of the specified key, or KM_ERROR_INVALID_KEY_BLOB if the - * key_blob is invalid (implementations must fully validate the integrity of the key). - * client_id and app_data must be the ID and data provided when the key was generated or - * imported, or empty if KM_TAG_APPLICATION_ID and/or KM_TAG_APPLICATION_DATA were not provided - * during generation. Those values are not included in the returned characteristics. The - * caller assumes ownership of the allocated characteristics object, which must be deallocated - * with keymaster_free_characteristics(). - * - * Note that KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA are never - * returned. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] key_blob The key to retreive characteristics from. - * - * \param[in] client_id The client ID data, or NULL if none associated. - * - * \param[in] app_id The app data, or NULL if none associated. - * - * \param[out] characteristics The key characteristics. - */ - keymaster_error_t (*get_key_characteristics)(const struct keymaster1_device* dev, - const keymaster_key_blob_t* key_blob, - const keymaster_blob_t* client_id, - const keymaster_blob_t* app_data, - keymaster_key_characteristics_t** characteristics); - - /** - * Imports a key, or key pair, returning a key blob and/or a description of the key. - * - * Most key import parameters are defined as keymaster tag/value pairs, provided in "params". - * See keymaster_tag_t for the full list. Values that are always required for import of useful - * keys are: - * - * - KM_TAG_ALGORITHM; - * - KM_TAG_PURPOSE; and - * - (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED. - * - * KM_TAG_AUTH_TIMEOUT should generally be specified. If unspecified, the user will have to - * authenticate for every use. - * - * The following tags will take default values if unspecified: - * - * - KM_TAG_KEY_SIZE will default to the size of the key provided. - * - KM_TAG_RSA_PUBLIC_EXPONENT will default to the value in the key provided (for RSA keys) - * - * The following tags may not be specified; their values will be provided by the implementation. - * - * - KM_TAG_ORIGIN, - * - KM_TAG_ROLLBACK_RESISTANT, - * - KM_TAG_CREATION_DATETIME - * - * \param[in] dev The keymaster device structure. - * - * \param[in] params Parameters defining the imported key. - * - * \param[in] params_count The number of entries in \p params. - * - * \param[in] key_format specifies the format of the key data in key_data. - * - * \param[out] key_blob Used to return the opaque key blob. Must be non-NULL. The caller - * assumes ownership of the contained key_material. - * - * \param[out] characteristics Used to return the characteristics of the imported key. May be - * NULL, in which case no characteristics will be returned. If non-NULL, the caller assumes - * ownership and must deallocate with keymaster_free_characteristics(). Note that - * KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and - * KM_TAG_APPLICATION_DATA are never returned. - */ - keymaster_error_t (*import_key)(const struct keymaster1_device* dev, - const keymaster_key_param_set_t* params, - keymaster_key_format_t key_format, - const keymaster_blob_t* key_data, - keymaster_key_blob_t* key_blob, - keymaster_key_characteristics_t** characteristics); - - /** - * Exports a public key, returning a byte array in the specified format. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] export_format The format to be used for exporting the key. - * - * \param[in] key_to_export The key to export. - * - * \param[out] export_data The exported key material. The caller assumes ownership. - * - * \param[out] export_data_length The length of \p export_data. - */ - keymaster_error_t (*export_key)(const struct keymaster1_device* dev, - keymaster_key_format_t export_format, - const keymaster_key_blob_t* key_to_export, - const keymaster_blob_t* client_id, - const keymaster_blob_t* app_data, - keymaster_blob_t* export_data); - - /** - * Deletes the key, or key pair, associated with the key blob. After calling this function it - * will be impossible to use the key for any other operations. May be applied to keys from - * foreign roots of trust (keys not usable under the current root of trust). - * - * This function is optional and should be set to NULL if it is not implemented. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] key The key to be deleted. - */ - keymaster_error_t (*delete_key)(const struct keymaster1_device* dev, - const keymaster_key_blob_t* key); - - /** - * Deletes all keys in the hardware keystore. Used when keystore is reset completely. After - * calling this function it will be impossible to use any previously generated or imported key - * blobs for any operations. - * - * This function is optional and should be set to NULL if it is not implemented. - * - * \param[in] dev The keymaster device structure. - */ - keymaster_error_t (*delete_all_keys)(const struct keymaster1_device* dev); - - /** - * Begins a cryptographic operation using the specified key. If all is well, begin() will - * return KM_ERROR_OK and create an operation handle which must be passed to subsequent calls to - * update(), finish() or abort(). - * - * It is critical that each call to begin() be paired with a subsequent call to finish() or - * abort(), to allow the keymaster implementation to clean up any internal operation state. - * Failure to do this may leak internal state space or other internal resources and may - * eventually cause begin() to return KM_ERROR_TOO_MANY_OPERATIONS when it runs out of space for - * operations. Any result other than KM_ERROR_OK from begin(), update() or finish() implicitly - * aborts the operation, in which case abort() need not be called (and will return - * KM_ERROR_INVALID_OPERATION_HANDLE if called). - * - * \param[in] dev The keymaster device structure. - * - * \param[in] purpose The purpose of the operation, one of KM_PURPOSE_ENCRYPT, - * KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN or KM_PURPOSE_VERIFY. Note that for AEAD modes, - * encryption and decryption imply signing and verification, respectively, but should be - * specified as KM_PURPOSE_ENCRYPT and KM_PURPOSE_DECRYPT. - * - * \param[in] key The key to be used for the operation. \p key must have a purpose compatible - * with \p purpose and all of its usage requirements must be satisfied, or begin() will return - * an appropriate error code. - * - * \param[in] in_params Additional parameters for the operation. This is typically used to - * provide authentication data, with KM_TAG_AUTH_TOKEN. If KM_TAG_APPLICATION_ID or - * KM_TAG_APPLICATION_DATA were provided during generation, they must be provided here, or the - * operation will fail with KM_ERROR_INVALID_KEY_BLOB. For operations that require a nonce or - * IV, on keys that were generated with KM_TAG_CALLER_NONCE, in_params may contain a tag - * KM_TAG_NONCE. For AEAD operations KM_TAG_CHUNK_SIZE is specified here. - * - * \param[out] out_params Output parameters. Used to return additional data from the operation - * initialization, notably to return the IV or nonce from operations that generate an IV or - * nonce. The caller takes ownership of the output parameters array and must free it with - * keymaster_free_param_set(). out_params may be set to NULL if no output parameters are - * expected. If out_params is NULL, and output paramaters are generated, begin() will return - * KM_ERROR_OUTPUT_PARAMETER_NULL. - * - * \param[out] operation_handle The newly-created operation handle which must be passed to - * update(), finish() or abort(). If operation_handle is NULL, begin() will return - * KM_ERROR_OUTPUT_PARAMETER_NULL. - */ - keymaster_error_t (*begin)(const struct keymaster1_device* dev, keymaster_purpose_t purpose, - const keymaster_key_blob_t* key, - const keymaster_key_param_set_t* in_params, - keymaster_key_param_set_t* out_params, - keymaster_operation_handle_t* operation_handle); - - /** - * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun - * with begin(). - * - * If operation_handle is invalid, update() will return KM_ERROR_INVALID_OPERATION_HANDLE. - * - * update() may not consume all of the data provided in the data buffer. update() will return - * the amount consumed in *data_consumed. The caller should provide the unconsumed data in a - * subsequent call. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] operation_handle The operation handle returned by begin(). - * - * \param[in] in_params Additional parameters for the operation. For AEAD modes, this is used - * to specify KM_TAG_ADDITIONAL_DATA. Note that additional data may be provided in multiple - * calls to update(), but only until input data has been provided. - * - * \param[in] input Data to be processed, per the parameters established in the call to begin(). - * Note that update() may or may not consume all of the data provided. See \p input_consumed. - * - * \param[out] input_consumed Amount of data that was consumed by update(). If this is less - * than the amount provided, the caller should provide the remainder in a subsequent call to - * update(). - * - * \param[out] out_params Output parameters. Used to return additional data from the operation - * The caller takes ownership of the output parameters array and must free it with - * keymaster_free_param_set(). out_params may be set to NULL if no output parameters are - * expected. If out_params is NULL, and output paramaters are generated, begin() will return - * KM_ERROR_OUTPUT_PARAMETER_NULL. - * - * \param[out] output The output data, if any. The caller assumes ownership of the allocated - * buffer. output must not be NULL. - * - * Note that update() may not provide any output, in which case output->data_length will be - * zero, and output->data may be either NULL or zero-length (so the caller should always free() - * it). - */ - keymaster_error_t (*update)(const struct keymaster1_device* dev, - keymaster_operation_handle_t operation_handle, - const keymaster_key_param_set_t* in_params, - const keymaster_blob_t* input, size_t* input_consumed, - keymaster_key_param_set_t* out_params, keymaster_blob_t* output); - - /** - * Finalizes a cryptographic operation begun with begin() and invalidates \p operation_handle. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] operation_handle The operation handle returned by begin(). This handle will be - * invalidated. - * - * \param[in] params Additional parameters for the operation. For AEAD modes, this is used to - * specify KM_TAG_ADDITIONAL_DATA, but only if no input data was provided to update(). - * - * \param[in] signature The signature to be verified if the purpose specified in the begin() - * call was KM_PURPOSE_VERIFY. - * - * \param[out] output The output data, if any. The caller assumes ownership of the allocated - * buffer. - * - * If the operation being finished is a signature verification or an AEAD-mode decryption and - * verification fails then finish() will return KM_ERROR_VERIFICATION_FAILED. - */ - keymaster_error_t (*finish)(const struct keymaster1_device* dev, - keymaster_operation_handle_t operation_handle, - const keymaster_key_param_set_t* in_params, - const keymaster_blob_t* signature, - keymaster_key_param_set_t* out_params, keymaster_blob_t* output); - - /** - * Aborts a cryptographic operation begun with begin(), freeing all internal resources and - * invalidating \p operation_handle. - */ - keymaster_error_t (*abort)(const struct keymaster1_device* dev, - keymaster_operation_handle_t operation_handle); -}; -typedef struct keymaster1_device keymaster1_device_t; - -/* Convenience API for opening and closing keymaster devices */ - -static inline int keymaster1_open(const struct hw_module_t* module, keymaster1_device_t** device) { - return module->methods->open(module, KEYSTORE_KEYMASTER, TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int keymaster1_close(keymaster1_device_t* device) { - return device->common.close(&device->common); -} - -__END_DECLS - -#endif // ANDROID_HARDWARE_KEYMASTER1_H +../../include_all/hardware/keymaster1.h
\ No newline at end of file diff --git a/include/hardware/keymaster2.h b/include/hardware/keymaster2.h index f1993f88..1f23c5e6 100644..120000 --- a/include/hardware/keymaster2.h +++ b/include/hardware/keymaster2.h @@ -1,432 +1 @@ -/* - * 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_KEYMASTER2_H -#define ANDROID_HARDWARE_KEYMASTER2_H - -#include <hardware/keymaster_common.h> -#include <hardware/keymaster_defs.h> - -__BEGIN_DECLS - -/** - * Keymaster2 device definition - */ -struct keymaster2_device { - /** - * Common methods of the keymaster device. This *must* be the first member of - * keymaster_device as users of this structure will cast a hw_device_t to - * keymaster_device pointer in contexts where it's known the hw_device_t references a - * keymaster_device. - */ - struct hw_device_t common; - - void* context; - - /** - * See flags defined for keymaster0_devices::flags in keymaster_common.h. Used only for - * backward compatibility; keymaster2 hardware devices must set this to zero. - */ - uint32_t flags; - - /** - * Configures keymaster. This method must be called once after the device is opened and before - * it is used. It's used to provide KM_TAG_OS_VERSION and KM_TAG_OS_PATCHLEVEL to keymaster. - * Until this method is called, all other methods will return KM_ERROR_KEYMASTER_NOT_CONFIGURED. - * The values provided by this method are only accepted by keymaster once per boot. Subsequent - * calls will return KM_ERROR_OK, but do nothing. - * - * If the keymaster implementation is in secure hardware and the OS version and patch level - * values provided do not match the values provided to the secure hardware by the bootloader (or - * if the bootloader did not provide values), then this method will return - * KM_ERROR_INVALID_ARGUMENT, and all other methods will continue returning - * KM_ERROR_KEYMASTER_NOT_CONFIGURED. - */ - keymaster_error_t (*configure)(const struct keymaster2_device* dev, - const keymaster_key_param_set_t* params); - - /** - * Adds entropy to the RNG used by keymaster. Entropy added through this method is guaranteed - * not to be the only source of entropy used, and the mixing function is required to be secure, - * in the sense that if the RNG is seeded (from any source) with any data the attacker cannot - * predict (or control), then the RNG output is indistinguishable from random. Thus, if the - * entropy from any source is good, the output will be good. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] data Random data to be mixed in. - * - * \param[in] data_length Length of \p data. - */ - keymaster_error_t (*add_rng_entropy)(const struct keymaster2_device* dev, const uint8_t* data, - size_t data_length); - - /** - * Generates a key, or key pair, returning a key blob and/or a description of the key. - * - * Key generation parameters are defined as keymaster tag/value pairs, provided in \p params. - * See keymaster_tag_t for the full list. Some values that are always required for generation - * of useful keys are: - * - * - KM_TAG_ALGORITHM; - * - KM_TAG_PURPOSE; and - * - (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED. - * - * KM_TAG_AUTH_TIMEOUT should generally be specified unless KM_TAG_NO_AUTH_REQUIRED is present, - * or the user will have to authenticate for every use. - * - * KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH and KM_TAG_DIGEST must be specified for - * algorithms that require them. - * - * The following tags may not be specified; their values will be provided by the implementation. - * - * - KM_TAG_ORIGIN, - * - KM_TAG_ROLLBACK_RESISTANT, - * - KM_TAG_CREATION_DATETIME - * - * \param[in] dev The keymaster device structure. - * - * \param[in] params Array of key generation param - * - * \param[out] key_blob returns the generated key. \p key_blob must not be NULL. The caller - * assumes ownership key_blob->key_material and must free() it. - * - * \param[out] characteristics returns the characteristics of the key that was, generated, if - * non-NULL. If non-NULL, the caller assumes ownership and must deallocate with - * keymaster_free_characteristics(). Note that KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and - * KM_TAG_APPLICATION_DATA are never returned. - */ - keymaster_error_t (*generate_key)(const struct keymaster2_device* dev, - const keymaster_key_param_set_t* params, - keymaster_key_blob_t* key_blob, - keymaster_key_characteristics_t* characteristics); - - /** - * Returns the characteristics of the specified key, or KM_ERROR_INVALID_KEY_BLOB if the - * key_blob is invalid (implementations must fully validate the integrity of the key). - * client_id and app_data must be the ID and data provided when the key was generated or - * imported, or empty if KM_TAG_APPLICATION_ID and/or KM_TAG_APPLICATION_DATA were not provided - * during generation. Those values are not included in the returned characteristics. The - * caller assumes ownership of the allocated characteristics object, which must be deallocated - * with keymaster_free_characteristics(). - * - * Note that KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA are never returned. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] key_blob The key to retreive characteristics from. - * - * \param[in] client_id The client ID data, or NULL if none associated. - * - * \param[in] app_id The app data, or NULL if none associated. - * - * \param[out] characteristics The key characteristics. Must not be NULL. The caller assumes - * ownership of the contents and must deallocate with keymaster_free_characteristics(). - */ - keymaster_error_t (*get_key_characteristics)(const struct keymaster2_device* dev, - const keymaster_key_blob_t* key_blob, - const keymaster_blob_t* client_id, - const keymaster_blob_t* app_data, - keymaster_key_characteristics_t* characteristics); - - /** - * Imports a key, or key pair, returning a key blob and/or a description of the key. - * - * Most key import parameters are defined as keymaster tag/value pairs, provided in "params". - * See keymaster_tag_t for the full list. Values that are always required for import of useful - * keys are: - * - * - KM_TAG_ALGORITHM; - * - KM_TAG_PURPOSE; and - * - (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED. - * - * KM_TAG_AUTH_TIMEOUT should generally be specified. If unspecified, the user will have to - * authenticate for every use. - * - * The following tags will take default values if unspecified: - * - * - KM_TAG_KEY_SIZE will default to the size of the key provided. - * - KM_TAG_RSA_PUBLIC_EXPONENT will default to the value in the key provided (for RSA keys) - * - * The following tags may not be specified; their values will be provided by the implementation. - * - * - KM_TAG_ORIGIN, - * - KM_TAG_ROLLBACK_RESISTANT, - * - KM_TAG_CREATION_DATETIME - * - * \param[in] dev The keymaster device structure. - * - * \param[in] params Parameters defining the imported key. - * - * \param[in] params_count The number of entries in \p params. - * - * \param[in] key_format specifies the format of the key data in key_data. - * - * \param[out] key_blob Used to return the opaque key blob. Must be non-NULL. The caller - * assumes ownership of the contained key_material. - * - * \param[out] characteristics Used to return the characteristics of the imported key. May be - * NULL, in which case no characteristics will be returned. If non-NULL, the caller assumes - * ownership of the contents and must deallocate with keymaster_free_characteristics(). Note - * that KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA are never returned. - */ - keymaster_error_t (*import_key)(const struct keymaster2_device* dev, - const keymaster_key_param_set_t* params, - keymaster_key_format_t key_format, - const keymaster_blob_t* key_data, - keymaster_key_blob_t* key_blob, - keymaster_key_characteristics_t* characteristics); - - /** - * Exports a public or symmetric key, returning a byte array in the specified format. - * - * Note that symmetric key export is allowed only if the key was created with KM_TAG_EXPORTABLE, - * and only if all of the requirements for key usage (e.g. authentication) are met. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] export_format The format to be used for exporting the key. - * - * \param[in] key_to_export The key to export. - * - * \param[in] client_id Client ID blob, which must match the blob provided in - * KM_TAG_APPLICATION_ID during key generation (if any). - * - * \param[in] app_data Appliation data blob, which must match the blob provided in - * KM_TAG_APPLICATION_DATA during key generation (if any). - * - * \param[out] export_data The exported key material. The caller assumes ownership. - */ - keymaster_error_t (*export_key)(const struct keymaster2_device* dev, - keymaster_key_format_t export_format, - const keymaster_key_blob_t* key_to_export, - const keymaster_blob_t* client_id, - const keymaster_blob_t* app_data, - keymaster_blob_t* export_data); - - /** - * Generates a signed X.509 certificate chain attesting to the presence of \p key_to_attest in - * keymaster (TODO(swillden): Describe certificate contents in more detail). The certificate - * will contain an extension with OID 1.3.6.1.4.1.11129.2.1.17 and value defined in - * <TODO:swillden -- insert link here> which contains the key description. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] key_to_attest The keymaster key for which the attestation certificate will be - * generated. - * - * \param[in] attest_params Parameters defining how to do the attestation. At present the only - * parameter is KM_TAG_ALGORITHM, which must be either KM_ALGORITHM_EC or KM_ALGORITHM_RSA. - * This selects which of the provisioned attestation keys will be used to sign the certificate. - * - * \param[out] cert_chain An array of DER-encoded X.509 certificates. The first will be the - * certificate for \p key_to_attest. The remaining entries will chain back to the root. The - * caller takes ownership and must deallocate with keymaster_free_cert_chain. - */ - keymaster_error_t (*attest_key)(const struct keymaster2_device* dev, - const keymaster_key_blob_t* key_to_attest, - const keymaster_key_param_set_t* attest_params, - keymaster_cert_chain_t* cert_chain); - - /** - * Upgrades an old key. Keys can become "old" in two ways: Keymaster can be upgraded to a new - * version, or the system can be updated to invalidate the OS version and/or patch level. In - * either case, attempts to use an old key will result in keymaster returning - * KM_ERROR_KEY_REQUIRES_UPGRADE. This method should then be called to upgrade the key. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] key_to_upgrade The keymaster key to upgrade. - * - * \param[in] upgrade_params Parameters needed to complete the upgrade. In particular, - * KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA will be required if they were defined for - * the key. - * - * \param[out] upgraded_key The upgraded key blob. - */ - keymaster_error_t (*upgrade_key)(const struct keymaster2_device* dev, - const keymaster_key_blob_t* key_to_upgrade, - const keymaster_key_param_set_t* upgrade_params, - keymaster_key_blob_t* upgraded_key); - - /** - * Deletes the key, or key pair, associated with the key blob. After calling this function it - * will be impossible to use the key for any other operations. May be applied to keys from - * foreign roots of trust (keys not usable under the current root of trust). - * - * This function is optional and should be set to NULL if it is not implemented. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] key The key to be deleted. - */ - keymaster_error_t (*delete_key)(const struct keymaster2_device* dev, - const keymaster_key_blob_t* key); - - /** - * Deletes all keys in the hardware keystore. Used when keystore is reset completely. After - * calling this function it will be impossible to use any previously generated or imported key - * blobs for any operations. - * - * This function is optional and should be set to NULL if it is not implemented. - * - * \param[in] dev The keymaster device structure. - */ - keymaster_error_t (*delete_all_keys)(const struct keymaster2_device* dev); - - /** - * Begins a cryptographic operation using the specified key. If all is well, begin() will - * return KM_ERROR_OK and create an operation handle which must be passed to subsequent calls to - * update(), finish() or abort(). - * - * It is critical that each call to begin() be paired with a subsequent call to finish() or - * abort(), to allow the keymaster implementation to clean up any internal operation state. - * Failure to do this may leak internal state space or other internal resources and may - * eventually cause begin() to return KM_ERROR_TOO_MANY_OPERATIONS when it runs out of space for - * operations. Any result other than KM_ERROR_OK from begin(), update() or finish() implicitly - * aborts the operation, in which case abort() need not be called (and will return - * KM_ERROR_INVALID_OPERATION_HANDLE if called). - * - * \param[in] dev The keymaster device structure. - * - * \param[in] purpose The purpose of the operation, one of KM_PURPOSE_ENCRYPT, - * KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN or KM_PURPOSE_VERIFY. Note that for AEAD modes, - * encryption and decryption imply signing and verification, respectively, but should be - * specified as KM_PURPOSE_ENCRYPT and KM_PURPOSE_DECRYPT. - * - * \param[in] key The key to be used for the operation. \p key must have a purpose compatible - * with \p purpose and all of its usage requirements must be satisfied, or begin() will return - * an appropriate error code. - * - * \param[in] in_params Additional parameters for the operation. This is typically used to - * provide authentication data, with KM_TAG_AUTH_TOKEN. If KM_TAG_APPLICATION_ID or - * KM_TAG_APPLICATION_DATA were provided during generation, they must be provided here, or the - * operation will fail with KM_ERROR_INVALID_KEY_BLOB. For operations that require a nonce or - * IV, on keys that were generated with KM_TAG_CALLER_NONCE, in_params may contain a tag - * KM_TAG_NONCE. - * - * \param[out] out_params Output parameters. Used to return additional data from the operation - * initialization, notably to return the IV or nonce from operations that generate an IV or - * nonce. The caller takes ownership of the output parameters array and must free it with - * keymaster_free_param_set(). out_params may be set to NULL if no output parameters are - * expected. If out_params is NULL, and output paramaters are generated, begin() will return - * KM_ERROR_OUTPUT_PARAMETER_NULL. - * - * \param[out] operation_handle The newly-created operation handle which must be passed to - * update(), finish() or abort(). If operation_handle is NULL, begin() will return - * KM_ERROR_OUTPUT_PARAMETER_NULL. - */ - keymaster_error_t (*begin)(const struct keymaster2_device* dev, keymaster_purpose_t purpose, - const keymaster_key_blob_t* key, - const keymaster_key_param_set_t* in_params, - keymaster_key_param_set_t* out_params, - keymaster_operation_handle_t* operation_handle); - - /** - * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun - * with begin(). - * - * If operation_handle is invalid, update() will return KM_ERROR_INVALID_OPERATION_HANDLE. - * - * update() may not consume all of the data provided in the data buffer. update() will return - * the amount consumed in *data_consumed. The caller should provide the unconsumed data in a - * subsequent call. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] operation_handle The operation handle returned by begin(). - * - * \param[in] in_params Additional parameters for the operation. For AEAD modes, this is used - * to specify KM_TAG_ADDITIONAL_DATA. Note that additional data may be provided in multiple - * calls to update(), but only until input data has been provided. - * - * \param[in] input Data to be processed, per the parameters established in the call to begin(). - * Note that update() may or may not consume all of the data provided. See \p input_consumed. - * - * \param[out] input_consumed Amount of data that was consumed by update(). If this is less - * than the amount provided, the caller should provide the remainder in a subsequent call to - * update(). - * - * \param[out] out_params Output parameters. Used to return additional data from the operation - * The caller takes ownership of the output parameters array and must free it with - * keymaster_free_param_set(). out_params may be set to NULL if no output parameters are - * expected. If out_params is NULL, and output paramaters are generated, begin() will return - * KM_ERROR_OUTPUT_PARAMETER_NULL. - * - * \param[out] output The output data, if any. The caller assumes ownership of the allocated - * buffer. output must not be NULL. - * - * Note that update() may not provide any output, in which case output->data_length will be - * zero, and output->data may be either NULL or zero-length (so the caller should always free() - * it). - */ - keymaster_error_t (*update)(const struct keymaster2_device* dev, - keymaster_operation_handle_t operation_handle, - const keymaster_key_param_set_t* in_params, - const keymaster_blob_t* input, size_t* input_consumed, - keymaster_key_param_set_t* out_params, keymaster_blob_t* output); - - /** - * Finalizes a cryptographic operation begun with begin() and invalidates \p operation_handle. - * - * \param[in] dev The keymaster device structure. - * - * \param[in] operation_handle The operation handle returned by begin(). This handle will be - * invalidated. - * - * \param[in] in_params Additional parameters for the operation. For AEAD modes, this is used - * to specify KM_TAG_ADDITIONAL_DATA, but only if no input data was provided to update(). - * - * \param[in] input Data to be processed, per the parameters established in the call to - * begin(). finish() must consume all provided data or return KM_ERROR_INVALID_INPUT_LENGTH. - * - * \param[in] signature The signature to be verified if the purpose specified in the begin() - * call was KM_PURPOSE_VERIFY. - * - * \param[out] output The output data, if any. The caller assumes ownership of the allocated - * buffer. - * - * If the operation being finished is a signature verification or an AEAD-mode decryption and - * verification fails then finish() will return KM_ERROR_VERIFICATION_FAILED. - */ - keymaster_error_t (*finish)(const struct keymaster2_device* dev, - keymaster_operation_handle_t operation_handle, - const keymaster_key_param_set_t* in_params, - const keymaster_blob_t* input, const keymaster_blob_t* signature, - keymaster_key_param_set_t* out_params, keymaster_blob_t* output); - - /** - * Aborts a cryptographic operation begun with begin(), freeing all internal resources and - * invalidating \p operation_handle. - */ - keymaster_error_t (*abort)(const struct keymaster2_device* dev, - keymaster_operation_handle_t operation_handle); -}; -typedef struct keymaster2_device keymaster2_device_t; - -/* Convenience API for opening and closing keymaster devices */ - -static inline int keymaster2_open(const struct hw_module_t* module, keymaster2_device_t** device) { - return module->methods->open(module, KEYSTORE_KEYMASTER, TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int keymaster2_close(keymaster2_device_t* device) { - return device->common.close(&device->common); -} - -__END_DECLS - -#endif // ANDROID_HARDWARE_KEYMASTER2_H +../../include_all/hardware/keymaster2.h
\ No newline at end of file diff --git a/include/hardware/keymaster_common.h b/include/hardware/keymaster_common.h index c79c1226..b2033fb8 100644..120000 --- a/include/hardware/keymaster_common.h +++ b/include/hardware/keymaster_common.h @@ -1,191 +1 @@ -/* - * 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_KEYMASTER_COMMON_H -#define ANDROID_HARDWARE_KEYMASTER_COMMON_H - -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <hardware/hardware.h> - -__BEGIN_DECLS - -/** - * The id of this module - */ -#define KEYSTORE_HARDWARE_MODULE_ID "keystore" - -#define KEYSTORE_KEYMASTER "keymaster" - - -/** - * Settings for "module_api_version" and "hal_api_version" - * fields in the keymaster_module initialization. - */ - -/** - * Keymaster 0.X module version provide the same APIs, but later versions add more options - * for algorithms and flags. - */ -#define KEYMASTER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) -#define KEYMASTER_DEVICE_API_VERSION_0_2 HARDWARE_DEVICE_API_VERSION(0, 2) - -#define KEYMASTER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) -#define KEYMASTER_DEVICE_API_VERSION_0_3 HARDWARE_DEVICE_API_VERSION(0, 3) - -/** - * Keymaster 1.0 module version provides a completely different API, incompatible with 0.X. - */ -#define KEYMASTER_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) -#define KEYMASTER_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) - -/** - * Keymaster 2.0 module version provides third API, slightly modified and extended from 1.0. - */ -#define KEYMASTER_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) -#define KEYMASTER_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) - -struct keystore_module { - /** - * Common methods of the keystore module. This *must* be the first member of keystore_module as - * users of this structure will cast a hw_module_t to keystore_module pointer in contexts where - * it's known the hw_module_t references a keystore_module. - */ - hw_module_t common; - - /* There are no keystore module methods other than the common ones. */ -}; - -/** - * Flags for keymaster0_device::flags - */ -enum { - /* - * Indicates this keymaster implementation does not have hardware that - * keeps private keys out of user space. - * - * This should not be implemented on anything other than the default - * implementation. - */ - KEYMASTER_SOFTWARE_ONLY = 1 << 0, - - /* - * This indicates that the key blobs returned via all the primitives - * are sufficient to operate on their own without the trusted OS - * querying userspace to retrieve some other data. Key blobs of - * this type are normally returned encrypted with a - * Key Encryption Key (KEK). - * - * This is currently used by "vold" to know whether the whole disk - * encryption secret can be unwrapped without having some external - * service started up beforehand since the "/data" partition will - * be unavailable at that point. - */ - KEYMASTER_BLOBS_ARE_STANDALONE = 1 << 1, - - /* - * Indicates that the keymaster module supports DSA keys. - */ - KEYMASTER_SUPPORTS_DSA = 1 << 2, - - /* - * Indicates that the keymaster module supports EC keys. - */ - KEYMASTER_SUPPORTS_EC = 1 << 3, -}; - -/** - * Asymmetric key pair types. - */ -typedef enum { - TYPE_RSA = 1, - TYPE_DSA = 2, - TYPE_EC = 3, -} keymaster_keypair_t; - -/** - * Parameters needed to generate an RSA key. - */ -typedef struct { - uint32_t modulus_size; - uint64_t public_exponent; -} keymaster_rsa_keygen_params_t; - -/** - * Parameters needed to generate a DSA key. - */ -typedef struct { - uint32_t key_size; - uint32_t generator_len; - uint32_t prime_p_len; - uint32_t prime_q_len; - const uint8_t* generator; - const uint8_t* prime_p; - const uint8_t* prime_q; -} keymaster_dsa_keygen_params_t; - -/** - * Parameters needed to generate an EC key. - * - * Field size is the only parameter in version 2. The sizes correspond to these required curves: - * - * 192 = NIST P-192 - * 224 = NIST P-224 - * 256 = NIST P-256 - * 384 = NIST P-384 - * 521 = NIST P-521 - * - * The parameters for these curves are available at: http://www.nsa.gov/ia/_files/nist-routines.pdf - * in Chapter 4. - */ -typedef struct { - uint32_t field_size; -} keymaster_ec_keygen_params_t; - - -/** - * Digest type. - */ -typedef enum { - DIGEST_NONE, -} keymaster_digest_algorithm_t; - -/** - * Type of padding used for RSA operations. - */ -typedef enum { - PADDING_NONE, -} keymaster_rsa_padding_t; - - -typedef struct { - keymaster_digest_algorithm_t digest_type; -} keymaster_dsa_sign_params_t; - -typedef struct { - keymaster_digest_algorithm_t digest_type; -} keymaster_ec_sign_params_t; - -typedef struct { - keymaster_digest_algorithm_t digest_type; - keymaster_rsa_padding_t padding_type; -} keymaster_rsa_sign_params_t; - -__END_DECLS - -#endif // ANDROID_HARDWARE_KEYMASTER_COMMON_H +../../include_all/hardware/keymaster_common.h
\ No newline at end of file diff --git a/include/hardware/keymaster_defs.h b/include/hardware/keymaster_defs.h index dd286d6d..18abd60a 100644..120000 --- a/include/hardware/keymaster_defs.h +++ b/include/hardware/keymaster_defs.h @@ -1,707 +1 @@ -/* - * Copyright (C) 2014 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_KEYMASTER_DEFS_H -#define ANDROID_HARDWARE_KEYMASTER_DEFS_H - -#include <stdint.h> -#include <stdlib.h> -#include <string.h> - -#ifdef __cplusplus -extern "C" { -#endif // __cplusplus - -/** - * Authorization tags each have an associated type. This enumeration facilitates tagging each with - * a type, by using the high four bits (of an implied 32-bit unsigned enum value) to specify up to - * 16 data types. These values are ORed with tag IDs to generate the final tag ID values. - */ -typedef enum { - KM_INVALID = 0 << 28, /* Invalid type, used to designate a tag as uninitialized */ - KM_ENUM = 1 << 28, - KM_ENUM_REP = 2 << 28, /* Repeatable enumeration value. */ - KM_UINT = 3 << 28, - KM_UINT_REP = 4 << 28, /* Repeatable integer value */ - KM_ULONG = 5 << 28, - KM_DATE = 6 << 28, - KM_BOOL = 7 << 28, - KM_BIGNUM = 8 << 28, - KM_BYTES = 9 << 28, - KM_ULONG_REP = 10 << 28, /* Repeatable long value */ -} keymaster_tag_type_t; - -typedef enum { - KM_TAG_INVALID = KM_INVALID | 0, - - /* - * Tags that must be semantically enforced by hardware and software implementations. - */ - - /* Crypto parameters */ - KM_TAG_PURPOSE = KM_ENUM_REP | 1, /* keymaster_purpose_t. */ - KM_TAG_ALGORITHM = KM_ENUM | 2, /* keymaster_algorithm_t. */ - KM_TAG_KEY_SIZE = KM_UINT | 3, /* Key size in bits. */ - KM_TAG_BLOCK_MODE = KM_ENUM_REP | 4, /* keymaster_block_mode_t. */ - KM_TAG_DIGEST = KM_ENUM_REP | 5, /* keymaster_digest_t. */ - KM_TAG_PADDING = KM_ENUM_REP | 6, /* keymaster_padding_t. */ - KM_TAG_CALLER_NONCE = KM_BOOL | 7, /* Allow caller to specify nonce or IV. */ - KM_TAG_MIN_MAC_LENGTH = KM_UINT | 8, /* Minimum length of MAC or AEAD authentication tag in - * bits. */ - KM_TAG_KDF = KM_ENUM_REP | 9, /* keymaster_kdf_t (keymaster2) */ - KM_TAG_EC_CURVE = KM_ENUM | 10, /* keymaster_ec_curve_t (keymaster2) */ - - /* Algorithm-specific. */ - KM_TAG_RSA_PUBLIC_EXPONENT = KM_ULONG | 200, - KM_TAG_ECIES_SINGLE_HASH_MODE = KM_BOOL | 201, /* Whether the ephemeral public key is fed into - * the KDF */ - KM_TAG_INCLUDE_UNIQUE_ID = KM_BOOL | 202, /* If true, attestation certificates for this key - * will contain an application-scoped and - * time-bounded device-unique ID. (keymaster2) */ - KM_TAG_RSA_OAEP_MGF_DIGEST = KM_ENUM_REP | 203, /* keymaster_digest_t. */ - - /* Other hardware-enforced. */ - KM_TAG_BLOB_USAGE_REQUIREMENTS = KM_ENUM | 301, /* keymaster_key_blob_usage_requirements_t */ - KM_TAG_BOOTLOADER_ONLY = KM_BOOL | 302, /* Usable only by bootloader */ - KM_TAG_ROLLBACK_RESISTANCE = KM_BOOL | 303, /* Hardware enforced deletion with deleteKey - * or deleteAllKeys is supported */ - KM_TAG_EARLY_BOOT_ONLY = KM_BOOL | 305, /* Key can only be used during early boot. */ - - /* - * Tags that should be semantically enforced by hardware if possible and will otherwise be - * enforced by software (keystore). - */ - - /* Key validity period */ - KM_TAG_ACTIVE_DATETIME = KM_DATE | 400, /* Start of validity */ - KM_TAG_ORIGINATION_EXPIRE_DATETIME = KM_DATE | 401, /* Date when new "messages" should no - longer be created. */ - KM_TAG_USAGE_EXPIRE_DATETIME = KM_DATE | 402, /* Date when existing "messages" should no - longer be trusted. */ - KM_TAG_MIN_SECONDS_BETWEEN_OPS = KM_UINT | 403, /* Minimum elapsed time between - cryptographic operations with the key. */ - KM_TAG_MAX_USES_PER_BOOT = KM_UINT | 404, /* Number of times the key can be used per - boot. */ - KM_TAG_USAGE_COUNT_LIMIT = KM_UINT | 405, /* Number of cryptographic operations left - with the key.*/ - - /* User authentication */ - KM_TAG_ALL_USERS = KM_BOOL | 500, /* Reserved for future use -- ignore */ - KM_TAG_USER_ID = KM_UINT | 501, /* Reserved for future use -- ignore */ - KM_TAG_USER_SECURE_ID = KM_ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s). - Disallowed if KM_TAG_ALL_USERS or - KM_TAG_NO_AUTH_REQUIRED is present. */ - KM_TAG_NO_AUTH_REQUIRED = KM_BOOL | 503, /* If key is usable without authentication. */ - KM_TAG_USER_AUTH_TYPE = KM_ENUM | 504, /* Bitmask of authenticator types allowed when - * KM_TAG_USER_SECURE_ID contains a secure user ID, - * rather than a secure authenticator ID. Defined in - * hw_authenticator_type_t in hw_auth_token.h. */ - KM_TAG_AUTH_TIMEOUT = KM_UINT | 505, /* Required freshness of user authentication for - private/secret key operations, in seconds. - Public key operations require no authentication. - If absent, authentication is required for every - use. Authentication state is lost when the - device is powered off. */ - KM_TAG_ALLOW_WHILE_ON_BODY = KM_BOOL | 506, /* Allow key to be used after authentication timeout - * if device is still on-body (requires secure - * on-body sensor. */ - KM_TAG_TRUSTED_USER_PRESENCE_REQUIRED = KM_BOOL | 507,/* Require test of user presence - * to use this key. */ - KM_TAG_TRUSTED_CONFIRMATION_REQUIRED = KM_BOOL | 508, /* Require user confirmation through a - * trusted UI to use this key. */ - KM_TAG_UNLOCKED_DEVICE_REQUIRED = KM_BOOL | 509, /* Require the device screen to be unlocked if the - * key is used. */ - - /* Application access control */ - KM_TAG_ALL_APPLICATIONS = KM_BOOL | 600, /* Specified to indicate key is usable by all - * applications. */ - KM_TAG_APPLICATION_ID = KM_BYTES | 601, /* Byte string identifying the authorized - * application. */ - KM_TAG_EXPORTABLE = KM_BOOL | 602, /* If true, private/secret key can be exported, but - * only if all access control requirements for use are - * met. (keymaster2) */ - - /* - * Semantically unenforceable tags, either because they have no specific meaning or because - * they're informational only. - */ - KM_TAG_APPLICATION_DATA = KM_BYTES | 700, /* Data provided by authorized application. */ - KM_TAG_CREATION_DATETIME = KM_DATE | 701, /* Key creation time */ - KM_TAG_ORIGIN = KM_ENUM | 702, /* keymaster_key_origin_t. */ - KM_TAG_ROLLBACK_RESISTANT = KM_BOOL | 703, /* Whether key is rollback-resistant. */ - KM_TAG_ROOT_OF_TRUST = KM_BYTES | 704, /* Root of trust ID. */ - KM_TAG_OS_VERSION = KM_UINT | 705, /* Version of system (keymaster2) */ - KM_TAG_OS_PATCHLEVEL = KM_UINT | 706, /* Patch level of system (keymaster2) */ - KM_TAG_UNIQUE_ID = KM_BYTES | 707, /* Used to provide unique ID in attestation */ - KM_TAG_ATTESTATION_CHALLENGE = KM_BYTES | 708, /* Used to provide challenge in attestation */ - KM_TAG_ATTESTATION_APPLICATION_ID = KM_BYTES | 709, /* Used to identify the set of possible - * applications of which one has initiated - * a key attestation */ - KM_TAG_ATTESTATION_ID_BRAND = KM_BYTES | 710, /* Used to provide the device's brand name to be - included in attestation */ - KM_TAG_ATTESTATION_ID_DEVICE = KM_BYTES | 711, /* Used to provide the device's device name to be - included in attestation */ - KM_TAG_ATTESTATION_ID_PRODUCT = KM_BYTES | 712, /* Used to provide the device's product name to - be included in attestation */ - KM_TAG_ATTESTATION_ID_SERIAL = KM_BYTES | 713, /* Used to provide the device's serial number to - be included in attestation */ - KM_TAG_ATTESTATION_ID_IMEI = KM_BYTES | 714, /* Used to provide the device's IMEI to be - included in attestation */ - KM_TAG_ATTESTATION_ID_MEID = KM_BYTES | 715, /* Used to provide the device's MEID to be - included in attestation */ - KM_TAG_ATTESTATION_ID_MANUFACTURER = KM_BYTES | 716, /* Used to provide the device's - manufacturer name to be included in - attestation */ - KM_TAG_ATTESTATION_ID_MODEL = KM_BYTES | 717, /* Used to provide the device's model name to be - included in attestation */ - KM_TAG_VENDOR_PATCHLEVEL = KM_UINT | 718, /* specifies the vendor image security patch - level with which the key may be used */ - KM_TAG_BOOT_PATCHLEVEL = KM_UINT | 719, /* specifies the boot image (kernel) security - patch level with which the key may be used */ - KM_TAG_DEVICE_UNIQUE_ATTESTATION = KM_BOOL | 720, /* Indicates StrongBox device-unique - attestation is requested. */ - KM_TAG_IDENTITY_CREDENTIAL_KEY = KM_BOOL | 721, /* This is an identity credential key */ - KM_TAG_STORAGE_KEY = KM_BOOL | 722, /* storage encryption key */ - KM_TAG_ATTESTATION_ID_SECOND_IMEI = KM_BYTES | 723, /* Used to provide the device's second - IMEI to be included in attestation */ - - /* Tags used only to provide data to or receive data from operations */ - KM_TAG_ASSOCIATED_DATA = KM_BYTES | 1000, /* Used to provide associated data for AEAD modes. */ - KM_TAG_NONCE = KM_BYTES | 1001, /* Nonce or Initialization Vector */ - KM_TAG_AUTH_TOKEN = KM_BYTES | 1002, /* Authentication token that proves secure user - authentication has been performed. Structure - defined in hw_auth_token_t in hw_auth_token.h. */ - KM_TAG_MAC_LENGTH = KM_UINT | 1003, /* MAC or AEAD authentication tag length in - * bits. */ - - KM_TAG_RESET_SINCE_ID_ROTATION = KM_BOOL | 1004, /* Whether the device has beeen factory reset - since the last unique ID rotation. Used - for key attestation. */ - - KM_TAG_CONFIRMATION_TOKEN = KM_BYTES | 1005, /* used to deliver a cryptographic token - proving that the user confirmed a signing - request. */ - - KM_TAG_CERTIFICATE_SERIAL = KM_BIGNUM | 1006, /* The serial number that should be - set in the attestation certificate - to be generated. */ - - KM_TAG_CERTIFICATE_SUBJECT = KM_BYTES | 1007, /* A DER-encoded X.500 subject that should be - set in the attestation certificate - to be generated. */ - - KM_TAG_CERTIFICATE_NOT_BEFORE = KM_DATE | 1008, /* Epoch time in milliseconds of the start of - the to be generated certificate's validity. - The value should interpreted as too's - complement signed integer. Negative values - indicate dates before Jan 1970 */ - - KM_TAG_CERTIFICATE_NOT_AFTER = KM_DATE | 1009, /* Epoch time in milliseconds of the end of - the to be generated certificate's validity. - The value should interpreted as too's - complement signed integer. Negative values - indicate dates before Jan 1970 */ - KM_TAG_MAX_BOOT_LEVEL = KM_UINT | 1010, /* Specifies a maximum boot level at which a key - should function. */ -} keymaster_tag_t; - -/** - * Algorithms that may be provided by keymaster implementations. Those that must be provided by all - * implementations are tagged as "required". - */ -typedef enum { - /* Asymmetric algorithms. */ - KM_ALGORITHM_RSA = 1, - // KM_ALGORITHM_DSA = 2, -- Removed, do not re-use value 2. - KM_ALGORITHM_EC = 3, - - /* Block ciphers algorithms */ - KM_ALGORITHM_AES = 32, - KM_ALGORITHM_TRIPLE_DES = 33, - - /* MAC algorithms */ - KM_ALGORITHM_HMAC = 128, -} keymaster_algorithm_t; - -/** - * Symmetric block cipher modes provided by keymaster implementations. - */ -typedef enum { - /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended - * except for compatibility with existing other protocols. */ - KM_MODE_ECB = 1, - KM_MODE_CBC = 2, - KM_MODE_CTR = 3, - - /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended - * over unauthenticated modes for all purposes. */ - KM_MODE_GCM = 32, -} keymaster_block_mode_t; - -/** - * Padding modes that may be applied to plaintext for encryption operations. This list includes - * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not - * provide all possible combinations of algorithm and padding, only the - * cryptographically-appropriate pairs. - */ -typedef enum { - KM_PAD_NONE = 1, /* deprecated */ - KM_PAD_RSA_OAEP = 2, - KM_PAD_RSA_PSS = 3, - KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4, - KM_PAD_RSA_PKCS1_1_5_SIGN = 5, - KM_PAD_PKCS7 = 64, -} keymaster_padding_t; - -/** - * Digests provided by keymaster implementations. - */ -typedef enum { - KM_DIGEST_NONE = 0, - KM_DIGEST_MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software - * if needed. */ - KM_DIGEST_SHA1 = 2, - KM_DIGEST_SHA_2_224 = 3, - KM_DIGEST_SHA_2_256 = 4, - KM_DIGEST_SHA_2_384 = 5, - KM_DIGEST_SHA_2_512 = 6, -} keymaster_digest_t; - -/* - * Key derivation functions, mostly used in ECIES. - */ -typedef enum { - /* Do not apply a key derivation function; use the raw agreed key */ - KM_KDF_NONE = 0, - /* HKDF defined in RFC 5869 with SHA256 */ - KM_KDF_RFC5869_SHA256 = 1, - /* KDF1 defined in ISO 18033-2 with SHA1 */ - KM_KDF_ISO18033_2_KDF1_SHA1 = 2, - /* KDF1 defined in ISO 18033-2 with SHA256 */ - KM_KDF_ISO18033_2_KDF1_SHA256 = 3, - /* KDF2 defined in ISO 18033-2 with SHA1 */ - KM_KDF_ISO18033_2_KDF2_SHA1 = 4, - /* KDF2 defined in ISO 18033-2 with SHA256 */ - KM_KDF_ISO18033_2_KDF2_SHA256 = 5, -} keymaster_kdf_t; - -/** - * Supported EC curves, used in ECDSA/ECIES. - */ -typedef enum { - KM_EC_CURVE_P_224 = 0, - KM_EC_CURVE_P_256 = 1, - KM_EC_CURVE_P_384 = 2, - KM_EC_CURVE_P_521 = 3, - KM_EC_CURVE_CURVE_25519 = 4, -} keymaster_ec_curve_t; - -/** - * The origin of a key (or pair), i.e. where it was generated. Note that KM_TAG_ORIGIN can be found - * in either the hardware-enforced or software-enforced list for a key, indicating whether the key - * is hardware or software-based. Specifically, a key with KM_ORIGIN_GENERATED in the - * hardware-enforced list is guaranteed never to have existed outide the secure hardware. - */ -typedef enum { - KM_ORIGIN_GENERATED = 0, /* Generated in keymaster. Should not exist outside the TEE. */ - KM_ORIGIN_DERIVED = 1, /* Derived inside keymaster. Likely exists off-device. */ - KM_ORIGIN_IMPORTED = 2, /* Imported into keymaster. Existed as cleartext in Android. */ - KM_ORIGIN_UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on - * keys in a keymaster0 implementation. The keymaster0 adapter uses - * this value to document the fact that it is unkown whether the key - * was generated inside or imported into keymaster. */ -} keymaster_key_origin_t; - -/** - * Usability requirements of key blobs. This defines what system functionality must be available - * for the key to function. For example, key "blobs" which are actually handles referencing - * encrypted key material stored in the file system cannot be used until the file system is - * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added - * as needed for implementations. - */ -typedef enum { - KM_BLOB_STANDALONE = 0, - KM_BLOB_REQUIRES_FILE_SYSTEM = 1, -} keymaster_key_blob_usage_requirements_t; - -/** - * Possible purposes of a key (or pair). - */ -typedef enum { - KM_PURPOSE_ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */ - KM_PURPOSE_DECRYPT = 1, /* Usable with RSA, EC and AES keys. */ - KM_PURPOSE_SIGN = 2, /* Usable with RSA, EC and HMAC keys. */ - KM_PURPOSE_VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */ - KM_PURPOSE_DERIVE_KEY = 4, /* Usable with EC keys. */ - KM_PURPOSE_WRAP = 5, /* Usable with wrapped keys. */ - KM_PURPOSE_AGREE_KEY = 6, /* Usable with EC keys. */ - KM_PURPOSE_ATTEST_KEY = 7 /* Usabe with RSA and EC keys */ -} keymaster_purpose_t; - -typedef struct { - const uint8_t* data; - size_t data_length; -} keymaster_blob_t; - -typedef struct { - keymaster_tag_t tag; - union { - uint32_t enumerated; /* KM_ENUM and KM_ENUM_REP */ - bool boolean; /* KM_BOOL */ - uint32_t integer; /* KM_INT and KM_INT_REP */ - uint64_t long_integer; /* KM_LONG */ - uint64_t date_time; /* KM_DATE */ - keymaster_blob_t blob; /* KM_BIGNUM and KM_BYTES*/ - }; -} keymaster_key_param_t; - -typedef struct { - keymaster_key_param_t* params; /* may be NULL if length == 0 */ - size_t length; -} keymaster_key_param_set_t; - -/** - * Parameters that define a key's characteristics, including authorized modes of usage and access - * control restrictions. The parameters are divided into two categories, those that are enforced by - * secure hardware, and those that are not. For a software-only keymaster implementation the - * enforced array must NULL. Hardware implementations must enforce everything in the enforced - * array. - */ -typedef struct { - keymaster_key_param_set_t hw_enforced; - keymaster_key_param_set_t sw_enforced; -} keymaster_key_characteristics_t; - -typedef struct { - const uint8_t* key_material; - size_t key_material_size; -} keymaster_key_blob_t; - -typedef struct { - keymaster_blob_t* entries; - size_t entry_count; -} keymaster_cert_chain_t; - -typedef enum { - KM_VERIFIED_BOOT_VERIFIED = 0, /* Full chain of trust extending from the bootloader to - * verified partitions, including the bootloader, boot - * partition, and all verified partitions*/ - KM_VERIFIED_BOOT_SELF_SIGNED = 1, /* The boot partition has been verified using the embedded - * certificate, and the signature is valid. The bootloader - * displays a warning and the fingerprint of the public - * key before allowing the boot process to continue.*/ - KM_VERIFIED_BOOT_UNVERIFIED = 2, /* The device may be freely modified. Device integrity is left - * to the user to verify out-of-band. The bootloader - * displays a warning to the user before allowing the boot - * process to continue */ - KM_VERIFIED_BOOT_FAILED = 3, /* The device failed verification. The bootloader displays a - * warning and stops the boot process, so no keymaster - * implementation should ever actually return this value, - * since it should not run. Included here only for - * completeness. */ -} keymaster_verified_boot_t; - -typedef enum { - KM_SECURITY_LEVEL_SOFTWARE = 0, - KM_SECURITY_LEVEL_TRUSTED_ENVIRONMENT = 1, - KM_SECURITY_LEVEL_STRONGBOX = 2, -} keymaster_security_level_t; - -/** - * Formats for key import and export. - */ -typedef enum { - KM_KEY_FORMAT_X509 = 0, /* for public key export */ - KM_KEY_FORMAT_PKCS8 = 1, /* for asymmetric key pair import */ - KM_KEY_FORMAT_RAW = 3, /* for symmetric key import and export*/ -} keymaster_key_format_t; - -/** - * The keymaster operation API consists of begin, update, finish and abort. This is the type of the - * handle used to tie the sequence of calls together. A 64-bit value is used because it's important - * that handles not be predictable. Implementations must use strong random numbers for handle - * values. - */ -typedef uint64_t keymaster_operation_handle_t; - -typedef enum { - KM_ERROR_OK = 0, - KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1, - KM_ERROR_UNSUPPORTED_PURPOSE = -2, - KM_ERROR_INCOMPATIBLE_PURPOSE = -3, - KM_ERROR_UNSUPPORTED_ALGORITHM = -4, - KM_ERROR_INCOMPATIBLE_ALGORITHM = -5, - KM_ERROR_UNSUPPORTED_KEY_SIZE = -6, - KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7, - KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8, - KM_ERROR_UNSUPPORTED_MAC_LENGTH = -9, - KM_ERROR_UNSUPPORTED_PADDING_MODE = -10, - KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11, - KM_ERROR_UNSUPPORTED_DIGEST = -12, - KM_ERROR_INCOMPATIBLE_DIGEST = -13, - KM_ERROR_INVALID_EXPIRATION_TIME = -14, - KM_ERROR_INVALID_USER_ID = -15, - KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16, - KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17, - KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18, - KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */ - KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */ - KM_ERROR_INVALID_INPUT_LENGTH = -21, - KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22, - KM_ERROR_DELEGATION_NOT_ALLOWED = -23, - KM_ERROR_KEY_NOT_YET_VALID = -24, - KM_ERROR_KEY_EXPIRED = -25, - KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26, - KM_ERROR_OUTPUT_PARAMETER_NULL = -27, - KM_ERROR_INVALID_OPERATION_HANDLE = -28, - KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29, - KM_ERROR_VERIFICATION_FAILED = -30, - KM_ERROR_TOO_MANY_OPERATIONS = -31, - KM_ERROR_UNEXPECTED_NULL_POINTER = -32, - KM_ERROR_INVALID_KEY_BLOB = -33, - KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34, - KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35, - KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36, - KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37, - KM_ERROR_INVALID_ARGUMENT = -38, - KM_ERROR_UNSUPPORTED_TAG = -39, - KM_ERROR_INVALID_TAG = -40, - KM_ERROR_MEMORY_ALLOCATION_FAILED = -41, - KM_ERROR_IMPORT_PARAMETER_MISMATCH = -44, - KM_ERROR_SECURE_HW_ACCESS_DENIED = -45, - KM_ERROR_OPERATION_CANCELLED = -46, - KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47, - KM_ERROR_SECURE_HW_BUSY = -48, - KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49, - KM_ERROR_UNSUPPORTED_EC_FIELD = -50, - KM_ERROR_MISSING_NONCE = -51, - KM_ERROR_INVALID_NONCE = -52, - KM_ERROR_MISSING_MAC_LENGTH = -53, - KM_ERROR_KEY_RATE_LIMIT_EXCEEDED = -54, - KM_ERROR_CALLER_NONCE_PROHIBITED = -55, - KM_ERROR_KEY_MAX_OPS_EXCEEDED = -56, - KM_ERROR_INVALID_MAC_LENGTH = -57, - KM_ERROR_MISSING_MIN_MAC_LENGTH = -58, - KM_ERROR_UNSUPPORTED_MIN_MAC_LENGTH = -59, - KM_ERROR_UNSUPPORTED_KDF = -60, - KM_ERROR_UNSUPPORTED_EC_CURVE = -61, - KM_ERROR_KEY_REQUIRES_UPGRADE = -62, - KM_ERROR_ATTESTATION_CHALLENGE_MISSING = -63, - KM_ERROR_KEYMASTER_NOT_CONFIGURED = -64, - KM_ERROR_ATTESTATION_APPLICATION_ID_MISSING = -65, - KM_ERROR_CANNOT_ATTEST_IDS = -66, - KM_ERROR_ROLLBACK_RESISTANCE_UNAVAILABLE = -67, - KM_ERROR_NO_USER_CONFIRMATION = -71, - KM_ERROR_DEVICE_LOCKED = -72, - KM_ERROR_EARLY_BOOT_ENDED = -73, - KM_ERROR_ATTESTATION_KEYS_NOT_PROVISIONED = -74, - KM_ERROR_ATTESTATION_IDS_NOT_PROVISIONED = -75, - KM_ERROR_INCOMPATIBLE_MGF_DIGEST = -78, - KM_ERROR_UNSUPPORTED_MGF_DIGEST = -79, - KM_ERROR_MISSING_NOT_BEFORE = -80, - KM_ERROR_MISSING_NOT_AFTER = -81, - KM_ERROR_MISSING_ISSUER_SUBJECT = -82, - KM_ERROR_INVALID_ISSUER_SUBJECT = -83, - KM_ERROR_BOOT_LEVEL_EXCEEDED = -84, - - KM_ERROR_UNIMPLEMENTED = -100, - KM_ERROR_VERSION_MISMATCH = -101, - - KM_ERROR_UNKNOWN_ERROR = -1000, -} keymaster_error_t; - -/* Convenience functions for manipulating keymaster tag types */ - -static inline keymaster_tag_type_t keymaster_tag_get_type(keymaster_tag_t tag) { - return (keymaster_tag_type_t)(tag & (0xF << 28)); -} - -static inline uint32_t keymaster_tag_mask_type(keymaster_tag_t tag) { - return tag & 0x0FFFFFFF; -} - -static inline bool keymaster_tag_type_repeatable(keymaster_tag_type_t type) { - switch (type) { - case KM_UINT_REP: - case KM_ENUM_REP: - return true; - default: - return false; - } -} - -static inline bool keymaster_tag_repeatable(keymaster_tag_t tag) { - return keymaster_tag_type_repeatable(keymaster_tag_get_type(tag)); -} - -/* Convenience functions for manipulating keymaster_key_param_t structs */ - -inline keymaster_key_param_t keymaster_param_enum(keymaster_tag_t tag, uint32_t value) { - // assert(keymaster_tag_get_type(tag) == KM_ENUM || keymaster_tag_get_type(tag) == KM_ENUM_REP); - keymaster_key_param_t param; - memset(¶m, 0, sizeof(param)); - param.tag = tag; - param.enumerated = value; - return param; -} - -inline keymaster_key_param_t keymaster_param_int(keymaster_tag_t tag, uint32_t value) { - // assert(keymaster_tag_get_type(tag) == KM_INT || keymaster_tag_get_type(tag) == KM_INT_REP); - keymaster_key_param_t param; - memset(¶m, 0, sizeof(param)); - param.tag = tag; - param.integer = value; - return param; -} - -inline keymaster_key_param_t keymaster_param_long(keymaster_tag_t tag, uint64_t value) { - // assert(keymaster_tag_get_type(tag) == KM_LONG); - keymaster_key_param_t param; - memset(¶m, 0, sizeof(param)); - param.tag = tag; - param.long_integer = value; - return param; -} - -inline keymaster_key_param_t keymaster_param_blob(keymaster_tag_t tag, const uint8_t* bytes, - size_t bytes_len) { - // assert(keymaster_tag_get_type(tag) == KM_BYTES || keymaster_tag_get_type(tag) == KM_BIGNUM); - keymaster_key_param_t param; - memset(¶m, 0, sizeof(param)); - param.tag = tag; - param.blob.data = (uint8_t*)bytes; - param.blob.data_length = bytes_len; - return param; -} - -inline keymaster_key_param_t keymaster_param_bool(keymaster_tag_t tag) { - // assert(keymaster_tag_get_type(tag) == KM_BOOL); - keymaster_key_param_t param; - memset(¶m, 0, sizeof(param)); - param.tag = tag; - param.boolean = true; - return param; -} - -inline keymaster_key_param_t keymaster_param_date(keymaster_tag_t tag, uint64_t value) { - // assert(keymaster_tag_get_type(tag) == KM_DATE); - keymaster_key_param_t param; - memset(¶m, 0, sizeof(param)); - param.tag = tag; - param.date_time = value; - return param; -} - -#define KEYMASTER_SIMPLE_COMPARE(a, b) (a < b) ? -1 : ((a > b) ? 1 : 0) -inline int keymaster_param_compare(const keymaster_key_param_t* a, const keymaster_key_param_t* b) { - int retval = KEYMASTER_SIMPLE_COMPARE((uint32_t)a->tag, (uint32_t)b->tag); - if (retval != 0) - return retval; - - switch (keymaster_tag_get_type(a->tag)) { - case KM_INVALID: - case KM_BOOL: - return 0; - case KM_ENUM: - case KM_ENUM_REP: - return KEYMASTER_SIMPLE_COMPARE(a->enumerated, b->enumerated); - case KM_UINT: - case KM_UINT_REP: - return KEYMASTER_SIMPLE_COMPARE(a->integer, b->integer); - case KM_ULONG: - case KM_ULONG_REP: - return KEYMASTER_SIMPLE_COMPARE(a->long_integer, b->long_integer); - case KM_DATE: - return KEYMASTER_SIMPLE_COMPARE(a->date_time, b->date_time); - case KM_BIGNUM: - case KM_BYTES: - // Handle the empty cases. - if (a->blob.data_length != 0 && b->blob.data_length == 0) - return -1; - if (a->blob.data_length == 0 && b->blob.data_length == 0) - return 0; - if (a->blob.data_length == 0 && b->blob.data_length > 0) - return 1; - - retval = memcmp(a->blob.data, b->blob.data, a->blob.data_length < b->blob.data_length - ? a->blob.data_length - : b->blob.data_length); - if (retval != 0) - return retval; - else if (a->blob.data_length != b->blob.data_length) { - // Equal up to the common length; longer one is larger. - if (a->blob.data_length < b->blob.data_length) - return -1; - if (a->blob.data_length > b->blob.data_length) - return 1; - } - } - - return 0; -} -#undef KEYMASTER_SIMPLE_COMPARE - -inline void keymaster_free_param_values(keymaster_key_param_t* param, size_t param_count) { - while (param_count > 0) { - param_count--; - switch (keymaster_tag_get_type(param->tag)) { - case KM_BIGNUM: - case KM_BYTES: - free((void*)param->blob.data); - param->blob.data = NULL; - break; - default: - // NOP - break; - } - ++param; - } -} - -inline void keymaster_free_param_set(keymaster_key_param_set_t* set) { - if (set) { - keymaster_free_param_values(set->params, set->length); - free(set->params); - set->params = NULL; - set->length = 0; - } -} - -inline void keymaster_free_characteristics(keymaster_key_characteristics_t* characteristics) { - if (characteristics) { - keymaster_free_param_set(&characteristics->hw_enforced); - keymaster_free_param_set(&characteristics->sw_enforced); - } -} - -inline void keymaster_free_cert_chain(keymaster_cert_chain_t* chain) { - if (chain) { - for (size_t i = 0; i < chain->entry_count; ++i) { - free((uint8_t*)chain->entries[i].data); - chain->entries[i].data = NULL; - chain->entries[i].data_length = 0; - } - free(chain->entries); - chain->entries = NULL; - chain->entry_count = 0; - } -} - -#ifdef __cplusplus -} // extern "C" -#endif // __cplusplus - -#endif // ANDROID_HARDWARE_KEYMASTER_DEFS_H +../../include_all/hardware/keymaster_defs.h
\ No newline at end of file diff --git a/include/hardware/memtrack.h b/include/hardware/memtrack.h index 57ba4ad7..3bc44484 100644..120000 --- a/include/hardware/memtrack.h +++ b/include/hardware/memtrack.h @@ -1,160 +1 @@ -/* - * Copyright (C) 2013 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_INCLUDE_HARDWARE_MEMTRACK_H -#define ANDROID_INCLUDE_HARDWARE_MEMTRACK_H - -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <hardware/hardware.h> - -__BEGIN_DECLS - -#define MEMTRACK_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) - -/** - * The id of this module - */ -#define MEMTRACK_HARDWARE_MODULE_ID "memtrack" - -/* - * The Memory Tracker HAL is designed to return information about device-specific - * memory usage. The primary goal is to be able to track memory that is not - * trackable in any other way, for example texture memory that is allocated by - * a process, but not mapped in to that process' address space. - * A secondary goal is to be able to categorize memory used by a process into - * GL, graphics, etc. All memory sizes should be in real memory usage, - * accounting for stride, bit depth, rounding up to page size, etc. - * - * A process collecting memory statistics will call getMemory for each - * combination of pid and memory type. For each memory type that it recognizes - * the HAL should fill out an array of memtrack_record structures breaking - * down the statistics of that memory type as much as possible. For example, - * getMemory(<pid>, MEMTRACK_TYPE_GL) might return: - * { { 4096, ACCOUNTED | PRIVATE | SYSTEM }, - * { 40960, UNACCOUNTED | PRIVATE | SYSTEM }, - * { 8192, ACCOUNTED | PRIVATE | DEDICATED }, - * { 8192, UNACCOUNTED | PRIVATE | DEDICATED } } - * If the HAL could not differentiate between SYSTEM and DEDICATED memory, it - * could return: - * { { 12288, ACCOUNTED | PRIVATE }, - * { 49152, UNACCOUNTED | PRIVATE } } - * - * Memory should not overlap between types. For example, a graphics buffer - * that has been mapped into the GPU as a surface should show up when - * MEMTRACK_TYPE_GRAPHICS is requested, and not when MEMTRACK_TYPE_GL - * is requested. - */ - -enum memtrack_type { - MEMTRACK_TYPE_OTHER = 0, - MEMTRACK_TYPE_GL = 1, - MEMTRACK_TYPE_GRAPHICS = 2, - MEMTRACK_TYPE_MULTIMEDIA = 3, - MEMTRACK_TYPE_CAMERA = 4, - MEMTRACK_NUM_TYPES, -}; - -struct memtrack_record { - size_t size_in_bytes; - unsigned int flags; -}; - -/** - * Flags to differentiate memory that can already be accounted for in - * /proc/<pid>/smaps, - * (Shared_Clean + Shared_Dirty + Private_Clean + Private_Dirty = Size). - * In general, memory mapped in to a userspace process is accounted unless - * it was mapped with remap_pfn_range. - * Exactly one of these should be set. - */ -#define MEMTRACK_FLAG_SMAPS_ACCOUNTED (1 << 1) -#define MEMTRACK_FLAG_SMAPS_UNACCOUNTED (1 << 2) - -/** - * Flags to differentiate memory shared across multiple processes vs. memory - * used by a single process. Only zero or one of these may be set in a record. - * If none are set, record is assumed to count shared + private memory. - */ -#define MEMTRACK_FLAG_SHARED (1 << 3) -#define MEMTRACK_FLAG_SHARED_PSS (1 << 4) /* shared / num_procesess */ -#define MEMTRACK_FLAG_PRIVATE (1 << 5) - -/** - * Flags to differentiate memory taken from the kernel's allocation pool vs. - * memory that is dedicated to non-kernel allocations, for example a carveout - * or separate video memory. Only zero or one of these may be set in a record. - * If none are set, record is assumed to count system + dedicated memory. - */ -#define MEMTRACK_FLAG_SYSTEM (1 << 6) -#define MEMTRACK_FLAG_DEDICATED (1 << 7) - -/** - * Flags to differentiate memory accessible by the CPU in non-secure mode vs. - * memory that is protected. Only zero or one of these may be set in a record. - * If none are set, record is assumed to count secure + nonsecure memory. - */ -#define MEMTRACK_FLAG_NONSECURE (1 << 8) -#define MEMTRACK_FLAG_SECURE (1 << 9) - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -typedef struct memtrack_module { - struct hw_module_t common; - - /** - * (*init)() performs memtrack management setup actions and is called - * once before any calls to getMemory(). - * Returns 0 on success, -errno on error. - */ - int (*init)(const struct memtrack_module *module); - - /** - * (*getMemory)() expects an array of record objects and populates up to - * *num_record structures with the sizes of memory plus associated flags for - * that memory. It also updates *num_records with the total number of - * records it could return if *num_records was large enough when passed in. - * Returning records with size 0 is expected, the number of records should - * not vary between calls to getMemory for the same memory type, even - * for different pids. - * - * The caller will often call getMemory for a type and pid with - * *num_records == 0 to determine how many records to allocate room for, - * this case should be a fast-path in the HAL, returning a constant and - * not querying any kernel files. If *num_records passed in is 0, - * then records may be NULL. - * - * This function must be thread-safe, it may get called from multiple - * threads at the same time. - * - * Returns 0 on success, -ENODEV if the type is not supported, -errno - * on other errors. - */ - int (*getMemory)(const struct memtrack_module *module, - pid_t pid, - int type, - struct memtrack_record *records, - size_t *num_records); -} memtrack_module_t; - -__END_DECLS - -#endif // ANDROID_INCLUDE_HARDWARE_MEMTRACK_H +../../include_all/hardware/memtrack.h
\ No newline at end of file diff --git a/include/hardware/nfc-base.h b/include/hardware/nfc-base.h index d22cd5d8..adb2d5df 100644..120000 --- a/include/hardware/nfc-base.h +++ b/include/hardware/nfc-base.h @@ -1,34 +1 @@ -// This file is autogenerated by hidl-gen. Do not edit manually. -// Source: android.hardware.nfc@1.0 -// Location: hardware/interfaces/nfc/1.0/ - -#ifndef HIDL_GENERATED_ANDROID_HARDWARE_NFC_V1_0_EXPORTED_CONSTANTS_H_ -#define HIDL_GENERATED_ANDROID_HARDWARE_NFC_V1_0_EXPORTED_CONSTANTS_H_ - -#ifdef __cplusplus -extern "C" { -#endif - -enum { - HAL_NFC_OPEN_CPLT_EVT = 0u, - HAL_NFC_CLOSE_CPLT_EVT = 1u, - HAL_NFC_POST_INIT_CPLT_EVT = 2u, - HAL_NFC_PRE_DISCOVER_CPLT_EVT = 3u, - HAL_NFC_REQUEST_CONTROL_EVT = 4u, - HAL_NFC_RELEASE_CONTROL_EVT = 5u, - HAL_NFC_ERROR_EVT = 6u, -}; - -enum { - HAL_NFC_STATUS_OK = 0u, - HAL_NFC_STATUS_FAILED = 1u, - HAL_NFC_STATUS_ERR_TRANSPORT = 2u, - HAL_NFC_STATUS_ERR_CMD_TIMEOUT = 3u, - HAL_NFC_STATUS_REFUSED = 4u, -}; - -#ifdef __cplusplus -} -#endif - -#endif // HIDL_GENERATED_ANDROID_HARDWARE_NFC_V1_0_EXPORTED_CONSTANTS_H_ +../../include_all/hardware/nfc-base.h
\ No newline at end of file diff --git a/include/hardware/nfc.h b/include/hardware/nfc.h index fdd79a55..920dfd8b 100644..120000 --- a/include/hardware/nfc.h +++ b/include/hardware/nfc.h @@ -1,277 +1 @@ -/* - * Copyright (C) 2011, 2012 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_NFC_HAL_INTERFACE_H -#define ANDROID_NFC_HAL_INTERFACE_H - -#include <stdint.h> -#include <strings.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <hardware/hardware.h> -#include "nfc-base.h" - -__BEGIN_DECLS - - -/* NFC device HAL for NCI-based NFC controllers. - * - * This HAL allows NCI silicon vendors to make use - * of the core NCI stack in Android for their own silicon. - * - * The responibilities of the NCI HAL implementation - * are as follows: - * - * - Implement the transport to the NFC controller - * - Implement each of the HAL methods specified below as applicable to their silicon - * - Pass up received NCI messages from the controller to the stack - * - * A simplified timeline of NCI HAL method calls: - * 1) Core NCI stack calls open() - * 2) Core NCI stack executes CORE_RESET and CORE_INIT through calls to write() - * 3) Core NCI stack calls core_initialized() to allow HAL to do post-init configuration - * 4) Core NCI stack calls pre_discover() to allow HAL to prepare for RF discovery - * 5) Core NCI stack starts discovery through calls to write() - * 6) Core NCI stack stops discovery through calls to write() (e.g. screen turns off) - * 7) Core NCI stack calls pre_discover() to prepare for RF discovery (e.g. screen turned back on) - * 8) Core NCI stack starts discovery through calls to write() - * ... - * ... - * 9) Core NCI stack calls close() - */ -#define NFC_NCI_HARDWARE_MODULE_ID "nfc_nci" -#define NFC_NCI_BCM2079X_HARDWARE_MODULE_ID "nfc_nci.bcm2079x" -#define NFC_NCI_CONTROLLER "nci" - -/* - * nfc_nci_module_t should contain module-specific parameters - */ -typedef struct nfc_nci_module_t { - /** - * Common methods of the NFC NCI module. This *must* be the first member of - * nfc_nci_module_t as users of this structure will cast a hw_module_t to - * nfc_nci_module_t pointer in contexts where it's known the hw_module_t references a - * nfc_nci_module_t. - */ - struct hw_module_t common; -} nfc_nci_module_t; - -typedef uint8_t nfc_event_t; -typedef uint8_t nfc_status_t; - -/* - * The callback passed in from the NFC stack that the HAL - * can use to pass events back to the stack. - */ -typedef void (nfc_stack_callback_t) (nfc_event_t event, nfc_status_t event_status); - -/* - * The callback passed in from the NFC stack that the HAL - * can use to pass incomming data to the stack. - */ -typedef void (nfc_stack_data_callback_t) (uint16_t data_len, uint8_t* p_data); - -/* nfc_nci_device_t starts with a hw_device_t struct, - * followed by device-specific methods and members. - * - * All methods in the NCI HAL are asynchronous. - */ -typedef struct nfc_nci_device { - /** - * Common methods of the NFC NCI device. This *must* be the first member of - * nfc_nci_device_t as users of this structure will cast a hw_device_t to - * nfc_nci_device_t pointer in contexts where it's known the hw_device_t references a - * nfc_nci_device_t. - */ - struct hw_device_t common; - /* - * (*open)() Opens the NFC controller device and performs initialization. - * This may include patch download and other vendor-specific initialization. - * - * If open completes successfully, the controller should be ready to perform - * NCI initialization - ie accept CORE_RESET and subsequent commands through - * the write() call. - * - * If open() returns 0, the NCI stack will wait for a HAL_NFC_OPEN_CPLT_EVT - * before continuing. - * - * If open() returns any other value, the NCI stack will stop. - * - */ - int (*open)(const struct nfc_nci_device *p_dev, nfc_stack_callback_t *p_cback, - nfc_stack_data_callback_t *p_data_cback); - - /* - * (*write)() Performs an NCI write. - * - * This method may queue writes and return immediately. The only - * requirement is that the writes are executed in order. - */ - int (*write)(const struct nfc_nci_device *p_dev, uint16_t data_len, const uint8_t *p_data); - - /* - * (*core_initialized)() is called after the CORE_INIT_RSP is received from the NFCC. - * At this time, the HAL can do any chip-specific configuration. - * - * If core_initialized() returns 0, the NCI stack will wait for a HAL_NFC_POST_INIT_CPLT_EVT - * before continuing. - * - * If core_initialized() returns any other value, the NCI stack will continue - * immediately. - */ - int (*core_initialized)(const struct nfc_nci_device *p_dev, uint8_t* p_core_init_rsp_params); - - /* - * (*pre_discover)() Is called every time before starting RF discovery. - * It is a good place to do vendor-specific configuration that must be - * performed every time RF discovery is about to be started. - * - * If pre_discover() returns 0, the NCI stack will wait for a HAL_NFC_PRE_DISCOVER_CPLT_EVT - * before continuing. - * - * If pre_discover() returns any other value, the NCI stack will start - * RF discovery immediately. - */ - int (*pre_discover)(const struct nfc_nci_device *p_dev); - - /* - * (*close)() Closed the NFC controller. Should free all resources. - */ - int (*close)(const struct nfc_nci_device *p_dev); - - /* - * (*control_granted)() Grant HAL the exclusive control to send NCI commands. - * Called in response to HAL_REQUEST_CONTROL_EVT. - * Must only be called when there are no NCI commands pending. - * HAL_RELEASE_CONTROL_EVT will notify when HAL no longer needs exclusive control. - */ - int (*control_granted)(const struct nfc_nci_device *p_dev); - - /* - * (*power_cycle)() Restart controller by power cyle; - * HAL_OPEN_CPLT_EVT will notify when operation is complete. - */ - int (*power_cycle)(const struct nfc_nci_device *p_dev); -} nfc_nci_device_t; - -/* - * Convenience methods that the NFC stack can use to open - * and close an NCI device - */ -static inline int nfc_nci_open(const struct hw_module_t* module, - nfc_nci_device_t** dev) { - return module->methods->open(module, NFC_NCI_CONTROLLER, - (struct hw_device_t**) dev); -} - -static inline int nfc_nci_close(nfc_nci_device_t* dev) { - return dev->common.close(&dev->common); -} -/* - * End NFC NCI HAL - */ - -/* - * This is a limited NFC HAL for NXP PN544-based devices. - * This HAL as Android is moving to - * an NCI-based NFC stack. - * - * All NCI-based NFC controllers should use the NFC-NCI - * HAL instead. - * Begin PN544 specific HAL - */ -#define NFC_HARDWARE_MODULE_ID "nfc" - -#define NFC_PN544_CONTROLLER "pn544" - -typedef struct nfc_module_t { - /** - * Common methods of the NFC NXP PN544 module. This *must* be the first member of - * nfc_module_t as users of this structure will cast a hw_module_t to - * nfc_module_t pointer in contexts where it's known the hw_module_t references a - * nfc_module_t. - */ - struct hw_module_t common; -} nfc_module_t; - -/* - * PN544 linktypes. - * UART - * I2C - * USB (uses UART DAL) - */ -typedef enum { - PN544_LINK_TYPE_UART, - PN544_LINK_TYPE_I2C, - PN544_LINK_TYPE_USB, - PN544_LINK_TYPE_INVALID, -} nfc_pn544_linktype; - -typedef struct { - /** - * Common methods of the NFC NXP PN544 device. This *must* be the first member of - * nfc_pn544_device_t as users of this structure will cast a hw_device_t to - * nfc_pn544_device_t pointer in contexts where it's known the hw_device_t references a - * nfc_pn544_device_t. - */ - struct hw_device_t common; - - /* The number of EEPROM registers to write */ - uint32_t num_eeprom_settings; - - /* The actual EEPROM settings - * For PN544, each EEPROM setting is a 4-byte entry, - * of the format [0x00, addr_msb, addr_lsb, value]. - */ - uint8_t* eeprom_settings; - - /* The link type to which the PN544 is connected */ - nfc_pn544_linktype linktype; - - /* The device node to which the PN544 is connected */ - const char* device_node; - - /* On Crespo we had an I2C issue that would cause us to sometimes read - * the I2C slave address (0x57) over the bus. libnfc contains - * a hack to ignore this byte and try to read the length byte - * again. - * Set to 0 to disable the workaround, 1 to enable it. - */ - uint8_t enable_i2c_workaround; - /* I2C slave address. Multiple I2C addresses are - * possible for PN544 module. Configure address according to - * board design. - */ - uint8_t i2c_device_address; -} nfc_pn544_device_t; - -static inline int nfc_pn544_open(const struct hw_module_t* module, - nfc_pn544_device_t** dev) { - return module->methods->open(module, NFC_PN544_CONTROLLER, - (struct hw_device_t**) dev); -} - -static inline int nfc_pn544_close(nfc_pn544_device_t* dev) { - return dev->common.close(&dev->common); -} -/* - * End PN544 specific HAL - */ - -__END_DECLS - -#endif // ANDROID_NFC_HAL_INTERFACE_H +../../include_all/hardware/nfc.h
\ No newline at end of file diff --git a/include/hardware/nfc_tag.h b/include/hardware/nfc_tag.h index 040a07d8..34925574 100644..120000 --- a/include/hardware/nfc_tag.h +++ b/include/hardware/nfc_tag.h @@ -1,95 +1 @@ -/* - * Copyright (C) 2013 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_NFC_TAG_HAL_INTERFACE_H -#define ANDROID_NFC_TAG_HAL_INTERFACE_H - -#include <stdint.h> - -#include <hardware/hardware.h> - -__BEGIN_DECLS - -/* - * HAL for programmable NFC tags. - * - */ - -#define NFC_TAG_HARDWARE_MODULE_ID "nfc_tag" -#define NFC_TAG_ID "tag" - -typedef struct nfc_tag_module_t { - /** - * Common methods of the NFC tag module. This *must* be the first member of - * nfc_tag_module_t as users of this structure will cast a hw_module_t to - * nfc_tag_module_t pointer in contexts where it's known the hw_module_t references a - * nfc_tag_module_t. - */ - struct hw_module_t common; -} nfc_tag_module_t; - -typedef struct nfc_tag_device { - /** - * Common methods of the NFC tag device. This *must* be the first member of - * nfc_tag_device_t as users of this structure will cast a hw_device_t to - * nfc_tag_device_t pointer in contexts where it's known the hw_device_t references a - * nfc_tag_device_t. - */ - struct hw_device_t common; - - /** - * Initialize the NFC tag. - * - * The driver must: - * * Set the static lock bytes to read only - * * Configure the Capability Container to disable write acess - * eg: 0xE1 0x10 <size> 0x0F - * - * This function is called once before any calls to setContent(). - * - * Return 0 on success or -errno on error. - */ - int (*init)(const struct nfc_tag_device *dev); - - /** - * Set the NFC tag content. - * - * The driver must write <data> in the data area of the tag starting at - * byte 0 of block 4 and zero the rest of the data area. - * - * Returns 0 on success or -errno on error. - */ - int (*setContent)(const struct nfc_tag_device *dev, const uint8_t *data, size_t len); - - /** - * Returns the memory size of the data area. - */ - int (*getMemorySize)(const struct nfc_tag_device *dev); -} nfc_tag_device_t; - -static inline int nfc_tag_open(const struct hw_module_t* module, - nfc_tag_device_t** dev) { - return module->methods->open(module, NFC_TAG_ID, - (struct hw_device_t**)dev); -} - -static inline int nfc_tag_close(nfc_tag_device_t* dev) { - return dev->common.close(&dev->common); -} - -__END_DECLS - -#endif // ANDROID_NFC_TAG_HAL_INTERFACE_H +../../include_all/hardware/nfc_tag.h
\ No newline at end of file diff --git a/include/hardware/nvram.h b/include/hardware/nvram.h index 0654afef..75be0853 100644..120000 --- a/include/hardware/nvram.h +++ b/include/hardware/nvram.h @@ -1,338 +1 @@ -/* - * 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, - TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int nvram_close(nvram_device_t* device) { - return device->common.close(&device->common); -} - -__END_DECLS - -#endif // ANDROID_HARDWARE_NVRAM_H +../../include_all/hardware/nvram.h
\ No newline at end of file diff --git a/include/hardware/nvram_defs.h b/include/hardware/nvram_defs.h index 0256a3cf..2dca93b7 100644..120000 --- a/include/hardware/nvram_defs.h +++ b/include/hardware/nvram_defs.h @@ -1,61 +1 @@ -/* - * Copyright (C) 2016 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. - */ - -/* - * This file contains data type definitions and constants that are useful to - * code interacting with and implementing the NVRAM HAL, even though it doesn't - * use the actual NVRAM HAL module interface. Keeping this in a separate file - * simplifies inclusion in low-level code which can't easily include the heavier - * hardware.h due to lacking standard headers. - */ - -#ifndef ANDROID_HARDWARE_NVRAM_DEFS_H -#define ANDROID_HARDWARE_NVRAM_DEFS_H - -#include <stdint.h> - -#ifdef __cplusplus -extern "C" { -#endif // __cplusplus - -/* 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; - -#ifdef __cplusplus -} // extern "C" -#endif // __cplusplus - -#endif // ANDROID_HARDWARE_NVRAM_DEFS_H +../../include_all/hardware/nvram_defs.h
\ No newline at end of file diff --git a/include/hardware/power.h b/include/hardware/power.h index bd8216ef..d51a9229 100644..120000 --- a/include/hardware/power.h +++ b/include/hardware/power.h @@ -1,343 +1 @@ -/* - * Copyright (C) 2012 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_INCLUDE_HARDWARE_POWER_H -#define ANDROID_INCLUDE_HARDWARE_POWER_H - -#include <stdbool.h> -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <hardware/hardware.h> - -__BEGIN_DECLS - -#define POWER_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) -#define POWER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) -#define POWER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) -#define POWER_MODULE_API_VERSION_0_4 HARDWARE_MODULE_API_VERSION(0, 4) -#define POWER_MODULE_API_VERSION_0_5 HARDWARE_MODULE_API_VERSION(0, 5) - -/** - * The id of this module - */ -#define POWER_HARDWARE_MODULE_ID "power" - -/* - * Platform-level sleep state stats. - * Maximum length of Platform-level sleep state name. - */ -#define POWER_STATE_NAME_MAX_LENGTH 100 - -/* - * Platform-level sleep state stats. - * Maximum length of Platform-level sleep state voter name. - */ -#define POWER_STATE_VOTER_NAME_MAX_LENGTH 100 - -/* - * Power hint identifiers passed to (*powerHint) - */ - -typedef enum { - POWER_HINT_VSYNC = 0x00000001, - POWER_HINT_INTERACTION = 0x00000002, - /* DO NOT USE POWER_HINT_VIDEO_ENCODE/_DECODE! They will be removed in - * KLP. - */ - POWER_HINT_VIDEO_ENCODE = 0x00000003, - POWER_HINT_VIDEO_DECODE = 0x00000004, - POWER_HINT_LOW_POWER = 0x00000005, - POWER_HINT_SUSTAINED_PERFORMANCE = 0x00000006, - POWER_HINT_VR_MODE = 0x00000007, - POWER_HINT_LAUNCH = 0x00000008, - POWER_HINT_DISABLE_TOUCH = 0x00000009 -} power_hint_t; - -typedef enum { - POWER_FEATURE_DOUBLE_TAP_TO_WAKE = 0x00000001 -} feature_t; - -/* - * Platform-level sleep state stats: - * power_state_voter_t struct is useful for describing the individual voters when a - * Platform-level sleep state is chosen by aggregation of votes from multiple - * clients/system conditions. - * - * This helps in attirbuting what in the device is blocking the device from - * entering the lowest Platform-level sleep state. - */ -typedef struct { - /* - * Name of the voter. - */ - char name[POWER_STATE_VOTER_NAME_MAX_LENGTH]; - - /* - * Total time in msec the voter voted for the platform sleep state since boot. - */ - uint64_t total_time_in_msec_voted_for_since_boot; - - /* - * Number of times the voter voted for the platform sleep state since boot. - */ - uint64_t total_number_of_times_voted_since_boot; -} power_state_voter_t; - -/* - * Platform-level sleep state stats: - * power_state_platform_sleep_state_t represents the Platform-level sleep state the - * device is capable of getting into. - * - * SoCs usually have more than one Platform-level sleep state. - * - * The caller calls the get_number_of_platform_modes function to figure out the size - * of power_state_platform_sleep_state_t array where each array element represents - * a specific Platform-level sleep state. - * - * Higher the index deeper the state is i.e. lesser steady-state power is consumed - * by the platform to be resident in that state. - * - * Caller allocates power_state_voter_t *voters for each Platform-level sleep state by - * calling get_voter_list. - */ -typedef struct { - /* - * Platform-level Sleep state name. - */ - char name[POWER_STATE_NAME_MAX_LENGTH]; - - /* - * Time spent in msec at this platform-level sleep state since boot. - */ - uint64_t residency_in_msec_since_boot; - - /* - * Total number of times system entered this state. - */ - uint64_t total_transitions; - - /* - * This platform-level sleep state can only be reached during system suspend. - */ - bool supported_only_in_suspend; - - /* - * The following fields are useful if the Platform-level sleep state - * is chosen by aggregation votes from multiple clients/system conditions. - * All the voters have to say yes or all the system conditions need to be - * met to enter a platform-level sleep state. - * - * Setting number_of_voters to zero implies either the info is not available - * or the system does not follow a voting mechanism to choose this - * Platform-level sleep state. - */ - uint32_t number_of_voters; - - /* - * Voter list - Has to be allocated by the caller. - * - * Caller allocates power_state_voter_t *voters for each Platform-level sleep state - * by calling get_voter_list. - */ - power_state_voter_t *voters; -} power_state_platform_sleep_state_t; - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -typedef struct power_module { - struct hw_module_t common; - - /* - * (*init)() performs power management setup actions at runtime - * startup, such as to set default cpufreq parameters. This is - * called only by the Power HAL instance loaded by - * PowerManagerService. - * - * Platform-level sleep state stats: - * Can Also be used to initiate device specific Platform-level - * Sleep state nodes from version 0.5 onwards. - */ - void (*init)(struct power_module *module); - - /* - * (*setInteractive)() performs power management actions upon the - * system entering interactive state (that is, the system is awake - * and ready for interaction, often with UI devices such as - * display and touchscreen enabled) or non-interactive state (the - * system appears asleep, display usually turned off). The - * non-interactive state is usually entered after a period of - * inactivity, in order to conserve battery power during - * such inactive periods. - * - * Typical actions are to turn on or off devices and adjust - * cpufreq parameters. This function may also call the - * appropriate interfaces to allow the kernel to suspend the - * system to low-power sleep state when entering non-interactive - * state, and to disallow low-power suspend when the system is in - * interactive state. When low-power suspend state is allowed, the - * kernel may suspend the system whenever no wakelocks are held. - * - * on is non-zero when the system is transitioning to an - * interactive / awake state, and zero when transitioning to a - * non-interactive / asleep state. - * - * This function is called to enter non-interactive state after - * turning off the screen (if present), and called to enter - * interactive state prior to turning on the screen. - */ - void (*setInteractive)(struct power_module *module, int on); - - /* - * (*powerHint) is called to pass hints on power requirements, which - * may result in adjustment of power/performance parameters of the - * cpufreq governor and other controls. The possible hints are: - * - * POWER_HINT_VSYNC - * - * Foreground app has started or stopped requesting a VSYNC pulse - * from SurfaceFlinger. If the app has started requesting VSYNC - * then CPU and GPU load is expected soon, and it may be appropriate - * to raise speeds of CPU, memory bus, etc. The data parameter is - * non-zero to indicate VSYNC pulse is now requested, or zero for - * VSYNC pulse no longer requested. - * - * POWER_HINT_INTERACTION - * - * User is interacting with the device, for example, touchscreen - * events are incoming. CPU and GPU load may be expected soon, - * and it may be appropriate to raise speeds of CPU, memory bus, - * etc. The data parameter is the estimated length of the interaction - * in milliseconds, or 0 if unknown. - * - * POWER_HINT_LOW_POWER - * - * Low power mode is activated or deactivated. Low power mode - * is intended to save battery at the cost of performance. The data - * parameter is non-zero when low power mode is activated, and zero - * when deactivated. - * - * POWER_HINT_SUSTAINED_PERFORMANCE - * - * Sustained Performance mode is actived or deactivated. Sustained - * performance mode is intended to provide a consistent level of - * performance for a prolonged amount of time. The data parameter is - * non-zero when sustained performance mode is activated, and zero - * when deactivated. - * - * POWER_HINT_VR_MODE - * - * VR Mode is activated or deactivated. VR mode is intended to - * provide minimum guarantee for performance for the amount of time the - * device can sustain it. The data parameter is non-zero when the mode - * is activated and zero when deactivated. - * - * POWER_HINT_DISABLE_TOUCH - * - * When device enters some special modes, e.g. theater mode in Android - * Wear, there is no touch interaction expected between device and user. - * Touch controller could be disabled in those modes to save power. - * The data parameter is non-zero when touch could be disabled, and zero - * when touch needs to be re-enabled. - * - * A particular platform may choose to ignore any hint. - * - * availability: version 0.2 - * - */ - void (*powerHint)(struct power_module *module, power_hint_t hint, - void *data); - - /* - * (*setFeature) is called to turn on or off a particular feature - * depending on the state parameter. The possible features are: - * - * FEATURE_DOUBLE_TAP_TO_WAKE - * - * Enabling/Disabling this feature will allow/disallow the system - * to wake up by tapping the screen twice. - * - * availability: version 0.3 - * - */ - void (*setFeature)(struct power_module *module, feature_t feature, int state); - - /* - * Platform-level sleep state stats: - * Report cumulative info on the statistics on platform-level sleep states since boot. - * - * Caller of the function queries the get_number_of_sleep_states and allocates the - * memory for the power_state_platform_sleep_state_t *list before calling this function. - * - * power_stats module is responsible to assign values to all the fields as - * necessary. - * - * Higher the index deeper the state is i.e. lesser steady-state power is consumed - * by the platform to be resident in that state. - * - * The function returns 0 on success or negative value -errno on error. - * EINVAL - *list is NULL. - * EIO - filesystem nodes access error. - * - * availability: version 0.5 - */ - int (*get_platform_low_power_stats)(struct power_module *module, - power_state_platform_sleep_state_t *list); - - /* - * Platform-level sleep state stats: - * This function is called to determine the number of platform-level sleep states - * for get_platform_low_power_stats. - * - * The value returned by this function is used to allocate memory for - * power_state_platform_sleep_state_t *list for get_platform_low_power_stats. - * - * The number of parameters must not change for successive calls. - * - * Return number of parameters on success or negative value -errno on error. - * EIO - filesystem nodes access error. - * - * availability: version 0.5 - */ - ssize_t (*get_number_of_platform_modes)(struct power_module *module); - - /* - * Platform-level sleep state stats: - * Provides the number of voters for each of the Platform-level sleep state. - * - * Caller uses this function to allocate memory for the power_state_voter_t list. - * - * Caller has to allocate the space for the *voter array which is - * get_number_of_platform_modes() long. - * - * Return 0 on success or negative value -errno on error. - * EINVAL - *voter is NULL. - * EIO - filesystem nodes access error. - * - * availability: version 0.5 - */ - int (*get_voter_list)(struct power_module *module, size_t *voter); - -} power_module_t; - - -__END_DECLS - -#endif // ANDROID_INCLUDE_HARDWARE_POWER_H +../../include_all/hardware/power.h
\ No newline at end of file diff --git a/include/hardware/sensors-base.h b/include/hardware/sensors-base.h index dbf99f57..b64751df 100644..120000 --- a/include/hardware/sensors-base.h +++ b/include/hardware/sensors-base.h @@ -1,144 +1 @@ -// This file is autogenerated by hidl-gen. Do not edit manually. -// Source: android.hardware.sensors@1.0 -// Location: hardware/interfaces/sensors/1.0/ - -#ifndef HIDL_GENERATED_ANDROID_HARDWARE_SENSORS_V1_0_EXPORTED_CONSTANTS_H_ -#define HIDL_GENERATED_ANDROID_HARDWARE_SENSORS_V1_0_EXPORTED_CONSTANTS_H_ - -#ifdef __cplusplus -extern "C" { -#endif - -enum { - SENSOR_HAL_NORMAL_MODE = 0, - SENSOR_HAL_DATA_INJECTION_MODE = 1, -}; - -enum { - SENSOR_TYPE_META_DATA = 0, - SENSOR_TYPE_ACCELEROMETER = 1, - SENSOR_TYPE_MAGNETIC_FIELD = 2, - SENSOR_TYPE_ORIENTATION = 3, - SENSOR_TYPE_GYROSCOPE = 4, - SENSOR_TYPE_LIGHT = 5, - SENSOR_TYPE_PRESSURE = 6, - SENSOR_TYPE_TEMPERATURE = 7, - SENSOR_TYPE_PROXIMITY = 8, - SENSOR_TYPE_GRAVITY = 9, - SENSOR_TYPE_LINEAR_ACCELERATION = 10, - SENSOR_TYPE_ROTATION_VECTOR = 11, - SENSOR_TYPE_RELATIVE_HUMIDITY = 12, - SENSOR_TYPE_AMBIENT_TEMPERATURE = 13, - SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14, - SENSOR_TYPE_GAME_ROTATION_VECTOR = 15, - SENSOR_TYPE_GYROSCOPE_UNCALIBRATED = 16, - SENSOR_TYPE_SIGNIFICANT_MOTION = 17, - SENSOR_TYPE_STEP_DETECTOR = 18, - SENSOR_TYPE_STEP_COUNTER = 19, - SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR = 20, - SENSOR_TYPE_HEART_RATE = 21, - SENSOR_TYPE_TILT_DETECTOR = 22, - SENSOR_TYPE_WAKE_GESTURE = 23, - SENSOR_TYPE_GLANCE_GESTURE = 24, - SENSOR_TYPE_PICK_UP_GESTURE = 25, - SENSOR_TYPE_WRIST_TILT_GESTURE = 26, - SENSOR_TYPE_DEVICE_ORIENTATION = 27, - SENSOR_TYPE_POSE_6DOF = 28, - SENSOR_TYPE_STATIONARY_DETECT = 29, - SENSOR_TYPE_MOTION_DETECT = 30, - SENSOR_TYPE_HEART_BEAT = 31, - SENSOR_TYPE_DYNAMIC_SENSOR_META = 32, - SENSOR_TYPE_ADDITIONAL_INFO = 33, - SENSOR_TYPE_LOW_LATENCY_OFFBODY_DETECT = 34, - SENSOR_TYPE_ACCELEROMETER_UNCALIBRATED = 35, - SENSOR_TYPE_HINGE_ANGLE = 36, - SENSOR_TYPE_HEAD_TRACKER = 37, - SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES = 38, - SENSOR_TYPE_GYROSCOPE_LIMITED_AXES = 39, - SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED = 40, - SENSOR_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED = 41, - SENSOR_TYPE_HEADING = 42, - SENSOR_TYPE_DEVICE_PRIVATE_BASE = 65536 /* 0x10000 */, -}; - -enum { - SENSOR_FLAG_WAKE_UP = 1u, - SENSOR_FLAG_CONTINUOUS_MODE = 0u, - SENSOR_FLAG_ON_CHANGE_MODE = 2u, - SENSOR_FLAG_ONE_SHOT_MODE = 4u, - SENSOR_FLAG_SPECIAL_REPORTING_MODE = 6u, - SENSOR_FLAG_DATA_INJECTION = 16u /* 0x10 */, - SENSOR_FLAG_DYNAMIC_SENSOR = 32u /* 0x20 */, - SENSOR_FLAG_ADDITIONAL_INFO = 64u /* 0x40 */, - SENSOR_FLAG_DIRECT_CHANNEL_ASHMEM = 1024u /* 0x400 */, - SENSOR_FLAG_DIRECT_CHANNEL_GRALLOC = 2048u /* 0x800 */, - SENSOR_FLAG_MASK_REPORTING_MODE = 14u /* 0xE */, - SENSOR_FLAG_MASK_DIRECT_REPORT = 896u /* 0x380 */, - SENSOR_FLAG_MASK_DIRECT_CHANNEL = 3072u /* 0xC00 */, -}; - -typedef enum { - SENSOR_FLAG_SHIFT_REPORTING_MODE = 1, - SENSOR_FLAG_SHIFT_DATA_INJECTION = 4, - SENSOR_FLAG_SHIFT_DYNAMIC_SENSOR = 5, - SENSOR_FLAG_SHIFT_ADDITIONAL_INFO = 6, - SENSOR_FLAG_SHIFT_DIRECT_REPORT = 7, - SENSOR_FLAG_SHIFT_DIRECT_CHANNEL = 10, -} sensor_flag_shift_t; - -enum { - SENSOR_STATUS_NO_CONTACT = -1 /* -1 */, - SENSOR_STATUS_UNRELIABLE = 0, - SENSOR_STATUS_ACCURACY_LOW = 1, - SENSOR_STATUS_ACCURACY_MEDIUM = 2, - SENSOR_STATUS_ACCURACY_HIGH = 3, -}; - -enum { - META_DATA_FLUSH_COMPLETE = 1u, -}; - -typedef enum { - AINFO_BEGIN = 0u, - AINFO_END = 1u, - AINFO_UNTRACKED_DELAY = 65536u /* 0x10000 */, - AINFO_INTERNAL_TEMPERATURE = 65537u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_UNTRACKED_DELAY implicitly + 1 */, - AINFO_VEC3_CALIBRATION = 65538u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_INTERNAL_TEMPERATURE implicitly + 1 */, - AINFO_SENSOR_PLACEMENT = 65539u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_VEC3_CALIBRATION implicitly + 1 */, - AINFO_SAMPLING = 65540u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_SENSOR_PLACEMENT implicitly + 1 */, - AINFO_CHANNEL_NOISE = 131072u /* 0x20000 */, - AINFO_CHANNEL_SAMPLER = 131073u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_NOISE implicitly + 1 */, - AINFO_CHANNEL_FILTER = 131074u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_SAMPLER implicitly + 1 */, - AINFO_CHANNEL_LINEAR_TRANSFORM = 131075u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_FILTER implicitly + 1 */, - AINFO_CHANNEL_NONLINEAR_MAP = 131076u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_LINEAR_TRANSFORM implicitly + 1 */, - AINFO_CHANNEL_RESAMPLER = 131077u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_NONLINEAR_MAP implicitly + 1 */, - AINFO_LOCAL_GEOMAGNETIC_FIELD = 196608u /* 0x30000 */, - AINFO_LOCAL_GRAVITY = 196609u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_LOCAL_GEOMAGNETIC_FIELD implicitly + 1 */, - AINFO_DOCK_STATE = 196610u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_LOCAL_GRAVITY implicitly + 1 */, - AINFO_HIGH_PERFORMANCE_MODE = 196611u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_DOCK_STATE implicitly + 1 */, - AINFO_MAGNETIC_FIELD_CALIBRATION = 196612u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_HIGH_PERFORMANCE_MODE implicitly + 1 */, - AINFO_CUSTOM_START = 268435456u /* 0x10000000 */, - AINFO_DEBUGGING_START = 1073741824u /* 0x40000000 */, -} additional_info_type_t; - -typedef enum { - SENSOR_DIRECT_RATE_STOP = 0, - SENSOR_DIRECT_RATE_NORMAL = 1 /* ::android::hardware::sensors::V1_0::RateLevel.STOP implicitly + 1 */, - SENSOR_DIRECT_RATE_FAST = 2 /* ::android::hardware::sensors::V1_0::RateLevel.NORMAL implicitly + 1 */, - SENSOR_DIRECT_RATE_VERY_FAST = 3 /* ::android::hardware::sensors::V1_0::RateLevel.FAST implicitly + 1 */, -} direct_rate_level_t; - -typedef enum { - SENSOR_DIRECT_MEM_TYPE_ASHMEM = 1, - SENSOR_DIRECT_MEM_TYPE_GRALLOC = 2 /* ::android::hardware::sensors::V1_0::SharedMemType.ASHMEM implicitly + 1 */, -} direct_mem_type_t; - -typedef enum { - SENSOR_DIRECT_FMT_SENSORS_EVENT = 1, -} direct_format_t; - -#ifdef __cplusplus -} -#endif - -#endif // HIDL_GENERATED_ANDROID_HARDWARE_SENSORS_V1_0_EXPORTED_CONSTANTS_H_ +../../include_all/hardware/sensors-base.h
\ No newline at end of file diff --git a/include/hardware/sensors.h b/include/hardware/sensors.h index 7b844b8a..28591f82 100644..120000 --- a/include/hardware/sensors.h +++ b/include/hardware/sensors.h @@ -1,836 +1 @@ -/* - * Copyright (C) 2012 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_SENSORS_INTERFACE_H -#define ANDROID_SENSORS_INTERFACE_H - -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <hardware/hardware.h> -#include <cutils/native_handle.h> - -#include "sensors-base.h" - -__BEGIN_DECLS - -/*****************************************************************************/ - -#define SENSORS_HEADER_VERSION 1 -#define SENSORS_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) -#define SENSORS_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, SENSORS_HEADER_VERSION) -#define SENSORS_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION) -#define SENSORS_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION_2(1, 1, SENSORS_HEADER_VERSION) -#define SENSORS_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION_2(1, 2, SENSORS_HEADER_VERSION) -#define SENSORS_DEVICE_API_VERSION_1_3 HARDWARE_DEVICE_API_VERSION_2(1, 3, SENSORS_HEADER_VERSION) -#define SENSORS_DEVICE_API_VERSION_1_4 HARDWARE_DEVICE_API_VERSION_2(1, 4, SENSORS_HEADER_VERSION) - -/** - * Please see the Sensors section of source.android.com for an - * introduction to and detailed descriptions of Android sensor types: - * http://source.android.com/devices/sensors/index.html - */ - -/** - * The id of this module - */ -#define SENSORS_HARDWARE_MODULE_ID "sensors" - -/** - * Name of the sensors device to open - */ -#define SENSORS_HARDWARE_POLL "poll" - -/** - * Sensor handle is greater than 0 and less than INT32_MAX. - * - * **** Deprecated **** - * Defined values below are kept for code compatibility. Note sensor handle can be as large as - * INT32_MAX. - */ -#define SENSORS_HANDLE_BASE 0 -#define SENSORS_HANDLE_BITS 31 -#define SENSORS_HANDLE_COUNT (1ull<<SENSORS_HANDLE_BITS) - - -/* - * **** Deprecated ***** - * flags for (*batch)() - * Availability: SENSORS_DEVICE_API_VERSION_1_0 - * see (*batch)() documentation for details. - * Deprecated as of SENSORS_DEVICE_API_VERSION_1_3. - * WAKE_UP_* sensors replace WAKE_UPON_FIFO_FULL concept. - */ -enum { - SENSORS_BATCH_DRY_RUN = 0x00000001, - SENSORS_BATCH_WAKE_UPON_FIFO_FULL = 0x00000002 -}; - -/* - * what field for meta_data_event_t - */ -enum { - /* a previous flush operation has completed */ - // META_DATA_FLUSH_COMPLETE = 1, - META_DATA_VERSION /* always last, leave auto-assigned */ -}; - -/* - * The permission to use for body sensors (like heart rate monitors). - * See sensor types for more details on what sensors should require this - * permission. - */ -#define SENSOR_PERMISSION_BODY_SENSORS "android.permission.BODY_SENSORS" - -/* - * sensor flags legacy names - * - * please use SENSOR_FLAG_* directly for new implementation. - * @see sensor_t - */ - -#define SENSOR_FLAG_MASK(nbit, shift) (((1<<(nbit))-1)<<(shift)) -#define SENSOR_FLAG_MASK_1(shift) SENSOR_FLAG_MASK(1, shift) - -/* - * Mask and shift for reporting mode sensor flags defined above. - */ -#define REPORTING_MODE_SHIFT SENSOR_FLAG_SHIFT_REPORTING_MODE -#define REPORTING_MODE_NBIT (3) -#define REPORTING_MODE_MASK SENSOR_FLAG_MASK_REPORTING_MODE - -/* - * Mask and shift for data_injection mode sensor flags defined above. - */ -#define DATA_INJECTION_SHIFT SENSOR_FLAG_SHIFT_DATA_INJECTION -#define DATA_INJECTION_MASK SENSOR_FLAG_DATA_INJECTION - -/* - * Mask and shift for dynamic sensor flag. - */ -#define DYNAMIC_SENSOR_SHIFT SENSOR_FLAG_SHIFT_DYNAMIC_SENSOR -#define DYNAMIC_SENSOR_MASK SENSOR_FLAG_DYNAMIC_SENSOR - -/* - * Mask and shift for sensor additional information support. - */ -#define ADDITIONAL_INFO_SHIFT SENSOR_FLAG_SHIFT_ADDITIONAL_INFO -#define ADDITIONAL_INFO_MASK SENSOR_FLAG_ADDITIONAL_INFO - -/* - * Legacy alias of SENSOR_TYPE_MAGNETIC_FIELD. - * - * Previously, the type of a sensor measuring local magnetic field is named - * SENSOR_TYPE_GEOMAGNETIC_FIELD and SENSOR_TYPE_MAGNETIC_FIELD is its alias. - * SENSOR_TYPE_MAGNETIC_FIELD is redefined as primary name to avoid confusion. - * SENSOR_TYPE_GEOMAGNETIC_FIELD is the alias and is deprecating. New implementation must not use - * SENSOR_TYPE_GEOMAGNETIC_FIELD. - */ -#define SENSOR_TYPE_GEOMAGNETIC_FIELD SENSOR_TYPE_MAGNETIC_FIELD - -/* - * Sensor string types for Android defined sensor types. - * - * For Android defined sensor types, string type will be override in sensor service and thus no - * longer needed to be added to sensor_t data structure. - * - * These definitions are going to be removed soon. - */ -#define SENSOR_STRING_TYPE_ACCELEROMETER "android.sensor.accelerometer" -#define SENSOR_STRING_TYPE_MAGNETIC_FIELD "android.sensor.magnetic_field" -#define SENSOR_STRING_TYPE_ORIENTATION "android.sensor.orientation" -#define SENSOR_STRING_TYPE_GYROSCOPE "android.sensor.gyroscope" -#define SENSOR_STRING_TYPE_LIGHT "android.sensor.light" -#define SENSOR_STRING_TYPE_PRESSURE "android.sensor.pressure" -#define SENSOR_STRING_TYPE_TEMPERATURE "android.sensor.temperature" -#define SENSOR_STRING_TYPE_PROXIMITY "android.sensor.proximity" -#define SENSOR_STRING_TYPE_GRAVITY "android.sensor.gravity" -#define SENSOR_STRING_TYPE_LINEAR_ACCELERATION "android.sensor.linear_acceleration" -#define SENSOR_STRING_TYPE_ROTATION_VECTOR "android.sensor.rotation_vector" -#define SENSOR_STRING_TYPE_RELATIVE_HUMIDITY "android.sensor.relative_humidity" -#define SENSOR_STRING_TYPE_AMBIENT_TEMPERATURE "android.sensor.ambient_temperature" -#define SENSOR_STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED "android.sensor.magnetic_field_uncalibrated" -#define SENSOR_STRING_TYPE_GAME_ROTATION_VECTOR "android.sensor.game_rotation_vector" -#define SENSOR_STRING_TYPE_GYROSCOPE_UNCALIBRATED "android.sensor.gyroscope_uncalibrated" -#define SENSOR_STRING_TYPE_SIGNIFICANT_MOTION "android.sensor.significant_motion" -#define SENSOR_STRING_TYPE_STEP_DETECTOR "android.sensor.step_detector" -#define SENSOR_STRING_TYPE_STEP_COUNTER "android.sensor.step_counter" -#define SENSOR_STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR "android.sensor.geomagnetic_rotation_vector" -#define SENSOR_STRING_TYPE_HEART_RATE "android.sensor.heart_rate" -#define SENSOR_STRING_TYPE_TILT_DETECTOR "android.sensor.tilt_detector" -#define SENSOR_STRING_TYPE_WAKE_GESTURE "android.sensor.wake_gesture" -#define SENSOR_STRING_TYPE_GLANCE_GESTURE "android.sensor.glance_gesture" -#define SENSOR_STRING_TYPE_PICK_UP_GESTURE "android.sensor.pick_up_gesture" -#define SENSOR_STRING_TYPE_WRIST_TILT_GESTURE "android.sensor.wrist_tilt_gesture" -#define SENSOR_STRING_TYPE_DEVICE_ORIENTATION "android.sensor.device_orientation" -#define SENSOR_STRING_TYPE_POSE_6DOF "android.sensor.pose_6dof" -#define SENSOR_STRING_TYPE_STATIONARY_DETECT "android.sensor.stationary_detect" -#define SENSOR_STRING_TYPE_MOTION_DETECT "android.sensor.motion_detect" -#define SENSOR_STRING_TYPE_HEART_BEAT "android.sensor.heart_beat" -#define SENSOR_STRING_TYPE_DYNAMIC_SENSOR_META "android.sensor.dynamic_sensor_meta" -#define SENSOR_STRING_TYPE_ADDITIONAL_INFO "android.sensor.additional_info" -#define SENSOR_STRING_TYPE_LOW_LATENCY_OFFBODY_DETECT "android.sensor.low_latency_offbody_detect" -#define SENSOR_STRING_TYPE_ACCELEROMETER_UNCALIBRATED "android.sensor.accelerometer_uncalibrated" -#define SENSOR_STRING_TYPE_HINGE_ANGLE "android.sensor.hinge_angle" -#define SENSOR_STRING_TYPE_HEAD_TRACKER "android.sensor.head_tracker" -#define SENSOR_STRING_TYPE_ACCELEROMETER_LIMITED_AXES "android.sensor.accelerometer_limited_axes" -#define SENSOR_STRING_TYPE_GYROSCOPE_LIMITED_AXES "android.sensor.gyroscope_limited_axes" -#define SENSOR_STRING_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED "android.sensor.accelerometer_limited_axes_uncalibrated" -#define SENSOR_STRING_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED "android.sensor.gyroscope_limited_axes_uncalibrated" -#define SENSOR_STRING_TYPE_HEADING "android.sensor.heading" - -/** - * Values returned by the accelerometer in various locations in the universe. - * all values are in SI units (m/s^2) - */ -#define GRAVITY_SUN (275.0f) -#define GRAVITY_EARTH (9.80665f) - -/** Maximum magnetic field on Earth's surface */ -#define MAGNETIC_FIELD_EARTH_MAX (60.0f) - -/** Minimum magnetic field on Earth's surface */ -#define MAGNETIC_FIELD_EARTH_MIN (30.0f) - -struct sensor_t; - -/** - * sensor event data - */ -typedef struct { - union { - float v[3]; - struct { - float x; - float y; - float z; - }; - struct { - float azimuth; - float pitch; - float roll; - }; - }; - int8_t status; - uint8_t reserved[3]; -} sensors_vec_t; - -/** - * uncalibrated accelerometer, gyroscope and magnetometer event data - */ -typedef struct { - union { - float uncalib[3]; - struct { - float x_uncalib; - float y_uncalib; - float z_uncalib; - }; - }; - union { - float bias[3]; - struct { - float x_bias; - float y_bias; - float z_bias; - }; - }; -} uncalibrated_event_t; - -/** - * Meta data event data - */ -typedef struct meta_data_event { - int32_t what; - int32_t sensor; -} meta_data_event_t; - -/** - * Dynamic sensor meta event. See the description of SENSOR_TYPE_DYNAMIC_SENSOR_META type for - * details. - */ -typedef struct dynamic_sensor_meta_event { - int32_t connected; - int32_t handle; - const struct sensor_t * sensor; // should be NULL if connected == false - uint8_t uuid[16]; // UUID of a dynamic sensor (using RFC 4122 byte order) - // For UUID 12345678-90AB-CDEF-1122-334455667788 the uuid field - // should be initialized as: - // {0x12, 0x34, 0x56, 0x78, 0x90, 0xAB, 0xCD, 0xEF, 0x11, ...} -} dynamic_sensor_meta_event_t; - -/** - * Heart rate event data - */ -typedef struct { - // Heart rate in beats per minute. - // Set to 0 when status is SENSOR_STATUS_UNRELIABLE or ..._NO_CONTACT - float bpm; - // Status of the sensor for this reading. Set to one SENSOR_STATUS_... - // Note that this value should only be set for sensors that explicitly define - // the meaning of this field. This field is not piped through the framework - // for other sensors. - int8_t status; -} heart_rate_event_t; - -typedef struct { - int32_t type; // type of payload data, see additional_info_type_t - int32_t serial; // sequence number of this frame for this type - union { - // for each frame, a single data type, either int32_t or float, should be used. - int32_t data_int32[14]; - float data_float[14]; - }; -} additional_info_event_t; - -typedef struct { - float rx; - float ry; - float rz; - float vx; - float vy; - float vz; - int32_t discontinuity_count; -} head_tracker_event_t; - -/** - * limited axes imu event data - */ -typedef struct { - union { - float calib[3]; - struct { - float x; - float y; - float z; - }; - }; - union { - float supported[3]; - struct { - float x_supported; - float y_supported; - float z_supported; - }; - }; -} limited_axes_imu_event_t; - -/** - * limited axes uncalibrated imu event data - */ -typedef struct { - union { - float uncalib[3]; - struct { - float x_uncalib; - float y_uncalib; - float z_uncalib; - }; - }; - union { - float bias[3]; - struct { - float x_bias; - float y_bias; - float z_bias; - }; - }; - union { - float supported[3]; - struct { - float x_supported; - float y_supported; - float z_supported; - }; - }; -} limited_axes_imu_uncalibrated_event_t; - -/** - * Heading event data - */ -typedef struct { - float heading; - float accuracy; -} heading_event_t; - -// LINT.IfChange -/** - * Union of the various types of sensor data - * that can be returned. - * This type needs to remain identical to ASensorEvent. - */ -typedef struct sensors_event_t { - /* must be sizeof(struct sensors_event_t) */ - int32_t version; - - /* sensor identifier */ - int32_t sensor; - - /* sensor type */ - int32_t type; - - /* reserved */ - int32_t reserved0; - - /* time is in nanosecond */ - int64_t timestamp; - - union { - union { - float data[16]; - - /* acceleration values are in meter per second per second (m/s^2) */ - sensors_vec_t acceleration; - - /* magnetic vector values are in micro-Tesla (uT) */ - sensors_vec_t magnetic; - - /* orientation values are in degrees */ - sensors_vec_t orientation; - - /* gyroscope values are in rad/s */ - sensors_vec_t gyro; - - /* temperature is in degrees centigrade (Celsius) */ - float temperature; - - /* distance in centimeters */ - float distance; - - /* light in SI lux units */ - float light; - - /* pressure in hectopascal (hPa) */ - float pressure; - - /* relative humidity in percent */ - float relative_humidity; - - /* uncalibrated gyroscope values are in rad/s */ - uncalibrated_event_t uncalibrated_gyro; - - /* uncalibrated magnetometer values are in micro-Teslas */ - uncalibrated_event_t uncalibrated_magnetic; - - /* uncalibrated accelerometer values are in meter per second per second (m/s^2) */ - uncalibrated_event_t uncalibrated_accelerometer; - - /* heart rate data containing value in bpm and status */ - heart_rate_event_t heart_rate; - - /* this is a special event. see SENSOR_TYPE_META_DATA above. - * sensors_meta_data_event_t events are all reported with a type of - * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero. - */ - meta_data_event_t meta_data; - - /* dynamic sensor meta event. See SENSOR_TYPE_DYNAMIC_SENSOR_META type for details */ - dynamic_sensor_meta_event_t dynamic_sensor_meta; - - /* - * special additional sensor information frame, see - * SENSOR_TYPE_ADDITIONAL_INFO for details. - */ - additional_info_event_t additional_info; - - /* vector describing head orientation (added for legacy code support only) */ - head_tracker_event_t head_tracker; - - /* - * limited axes imu event, See - * SENSOR_TYPE_GYROSCOPE_LIMITED_AXES and - * SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES for details. - */ - limited_axes_imu_event_t limited_axes_imu; - - /* - * limited axes imu uncalibrated event, See - * SENSOR_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED and - * SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED for details. - */ - limited_axes_imu_uncalibrated_event_t limited_axes_imu_uncalibrated; - - /* heading data containing value in degrees and its accuracy */ - heading_event_t heading; - }; - - union { - uint64_t data[8]; - - /* step-counter */ - uint64_t step_counter; - } u64; - }; - - /* Reserved flags for internal use. Set to zero. */ - uint32_t flags; - - uint32_t reserved1[3]; -} sensors_event_t; -// LINT.ThenChange (frameworks/native/include/android/sensor.h) - - -/* see SENSOR_TYPE_META_DATA */ -typedef sensors_event_t sensors_meta_data_event_t; - - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -struct sensors_module_t { - struct hw_module_t common; - - /** - * Enumerate all available sensors. The list is returned in "list". - * return number of sensors in the list - */ - int (*get_sensors_list)(struct sensors_module_t* module, - struct sensor_t const** list); - - /** - * Place the module in a specific mode. The following modes are defined - * - * 0 - Normal operation. Default state of the module. - * 1 - Loopback mode. Data is injected for the supported - * sensors by the sensor service in this mode. - * return 0 on success - * -EINVAL if requested mode is not supported - * -EPERM if operation is not allowed - */ - int (*set_operation_mode)(unsigned int mode); -}; - -struct sensor_t { - - /* Name of this sensor. - * All sensors of the same "type" must have a different "name". - */ - const char* name; - - /* vendor of the hardware part */ - const char* vendor; - - /* version of the hardware part + driver. The value of this field - * must increase when the driver is updated in a way that changes the - * output of this sensor. This is important for fused sensors when the - * fusion algorithm is updated. - */ - int version; - - /* handle that identifies this sensors. This handle is used to reference - * this sensor throughout the HAL API. - */ - int handle; - - /* this sensor's type. */ - int type; - - /* maximum range of this sensor's value in SI units */ - float maxRange; - - /* smallest difference between two values reported by this sensor */ - float resolution; - - /* rough estimate of this sensor's power consumption in mA */ - float power; - - /* this value depends on the reporting mode: - * - * continuous: minimum sample period allowed in microseconds - * on-change : 0 - * one-shot :-1 - * special : 0, unless otherwise noted - */ - int32_t minDelay; - - /* number of events reserved for this sensor in the batch mode FIFO. - * If there is a dedicated FIFO for this sensor, then this is the - * size of this FIFO. If the FIFO is shared with other sensors, - * this is the size reserved for that sensor and it can be zero. - */ - uint32_t fifoReservedEventCount; - - /* maximum number of events of this sensor that could be batched. - * This is especially relevant when the FIFO is shared between - * several sensors; this value is then set to the size of that FIFO. - */ - uint32_t fifoMaxEventCount; - - /* type of this sensor as a string. - * - * If type is OEM specific or sensor manufacturer specific type - * (>=SENSOR_TYPE_DEVICE_PRIVATE_BASE), this string must be defined with reserved domain of - * vendor/OEM as a prefix, e.g. com.google.glass.onheaddetector - * - * For sensors of Android defined types, Android framework will override this value. It is ok to - * leave it pointing to an empty string. - */ - const char* stringType; - - /* permission required to see this sensor, register to it and receive data. - * Set to "" if no permission is required. Some sensor types like the - * heart rate monitor have a mandatory require_permission. - * For sensors that always require a specific permission, like the heart - * rate monitor, the android framework might overwrite this string - * automatically. - */ - const char* requiredPermission; - - /* This value is defined only for continuous mode and on-change sensors. It is the delay between - * two sensor events corresponding to the lowest frequency that this sensor supports. When lower - * frequencies are requested through batch()/setDelay() the events will be generated at this - * frequency instead. It can be used by the framework or applications to estimate when the batch - * FIFO may be full. - * - * NOTE: 1) period_ns is in nanoseconds where as maxDelay/minDelay are in microseconds. - * continuous, on-change: maximum sampling period allowed in microseconds. - * one-shot, special : 0 - * 2) maxDelay should always fit within a 32 bit signed integer. It is declared as 64 bit - * on 64 bit architectures only for binary compatibility reasons. - * Availability: SENSORS_DEVICE_API_VERSION_1_3 - */ - #ifdef __LP64__ - int64_t maxDelay; - #else - int32_t maxDelay; - #endif - - /* Flags for sensor. See SENSOR_FLAG_* above. Only the least significant 32 bits are used here. - * It is declared as 64 bit on 64 bit architectures only for binary compatibility reasons. - * Availability: SENSORS_DEVICE_API_VERSION_1_3 - */ - #ifdef __LP64__ - uint64_t flags; - #else - uint32_t flags; - #endif - - /* reserved fields, must be zero */ - void* reserved[2]; -}; - -/** - * Shared memory information for a direct channel - */ -struct sensors_direct_mem_t { - int type; // enum SENSOR_DIRECT_MEM_... - int format; // enum SENSOR_DIRECT_FMT_... - size_t size; // size of the memory region, in bytes - const struct native_handle *handle; // shared memory handle, which is interpreted differently - // depending on type -}; - -/** - * Direct channel report configuration - */ -struct sensors_direct_cfg_t { - int rate_level; // enum SENSOR_DIRECT_RATE_... -}; - -/* - * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1 - * and is present for backward binary and source compatibility. - * See the Sensors HAL interface section for complete descriptions of the - * following functions: - * http://source.android.com/devices/sensors/index.html#hal - */ -struct sensors_poll_device_t { - struct hw_device_t common; - int (*activate)(struct sensors_poll_device_t *dev, - int sensor_handle, int enabled); - int (*setDelay)(struct sensors_poll_device_t *dev, - int sensor_handle, int64_t sampling_period_ns); - int (*poll)(struct sensors_poll_device_t *dev, - sensors_event_t* data, int count); -}; - -/* - * struct sensors_poll_device_1 is used in HAL versions >= SENSORS_DEVICE_API_VERSION_1_0 - */ -typedef struct sensors_poll_device_1 { - union { - /* sensors_poll_device_1 is compatible with sensors_poll_device_t, - * and can be down-cast to it - */ - struct sensors_poll_device_t v0; - - struct { - struct hw_device_t common; - - /* Activate/de-activate one sensor. - * - * sensor_handle is the handle of the sensor to change. - * enabled set to 1 to enable, or 0 to disable the sensor. - * - * Before sensor activation, existing sensor events that have not - * been picked up by poll() should be abandoned so that application - * upon new activation request will not get stale events. - * (events that are generated during latter activation or during - * data injection mode after sensor deactivation) - * - * Return 0 on success, negative errno code otherwise. - */ - int (*activate)(struct sensors_poll_device_t *dev, - int sensor_handle, int enabled); - - /** - * Set the events's period in nanoseconds for a given sensor. - * If sampling_period_ns > max_delay it will be truncated to - * max_delay and if sampling_period_ns < min_delay it will be - * replaced by min_delay. - */ - int (*setDelay)(struct sensors_poll_device_t *dev, - int sensor_handle, int64_t sampling_period_ns); - - /** - * Write an array of sensor_event_t to data. The size of the - * available buffer is specified by count. Returns number of - * valid sensor_event_t. - * - * This function should block if there is no sensor event - * available when being called. Thus, return value should always be - * positive. - */ - int (*poll)(struct sensors_poll_device_t *dev, - sensors_event_t* data, int count); - }; - }; - - - /* - * Sets a sensor’s parameters, including sampling frequency and maximum - * report latency. This function can be called while the sensor is - * activated, in which case it must not cause any sensor measurements to - * be lost: transitioning from one sampling rate to the other cannot cause - * lost events, nor can transitioning from a high maximum report latency to - * a low maximum report latency. - * See the Batching sensor results page for details: - * http://source.android.com/devices/sensors/batching.html - */ - int (*batch)(struct sensors_poll_device_1* dev, - int sensor_handle, int flags, int64_t sampling_period_ns, - int64_t max_report_latency_ns); - - /* - * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t) - * to the end of the "batch mode" FIFO for the specified sensor and flushes - * the FIFO. - * If the FIFO is empty or if the sensor doesn't support batching (FIFO size zero), - * it should return SUCCESS along with a trivial META_DATA_FLUSH_COMPLETE event added to the - * event stream. This applies to all sensors other than one-shot sensors. - * If the sensor is a one-shot sensor, flush must return -EINVAL and not generate - * any flush complete metadata. - * If the sensor is not active at the time flush() is called, flush() should return - * -EINVAL. - */ - int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle); - - /* - * Inject a single sensor sample to be to this device. - * data points to the sensor event to be injected - * return 0 on success - * -EPERM if operation is not allowed - * -EINVAL if sensor event cannot be injected - */ - int (*inject_sensor_data)(struct sensors_poll_device_1 *dev, const sensors_event_t *data); - - /* - * Register/unregister direct report channel. - * - * A HAL declares support for direct report by setting non-NULL values for both - * register_direct_channel and config_direct_report. - * - * This function has two operation modes: - * - * Register: mem != NULL, register a channel using supplied shared memory information. By the - * time this function returns, sensors must finish initializing shared memory content - * (format dependent, see SENSOR_DIRECT_FMT_*). - * Parameters: - * mem points to a valid struct sensors_direct_mem_t. - * channel_handle is ignored. - * Return value: - * A handle of channel (>0, <INT32_MAX) when success, which later can be referred in - * unregister or config_direct_report call, or error code (<0) when failed - * Unregister: mem == NULL, unregister a previously registered channel. - * Parameters: - * mem set to NULL - * channel_handle contains handle of channel to be unregistered - * Return value: - * 0, even if the channel_handle is invalid, in which case it will be a no-op. - */ - int (*register_direct_channel)(struct sensors_poll_device_1 *dev, - const struct sensors_direct_mem_t* mem, int channel_handle); - - /* - * Configure direct sensor event report in direct channel. - * - * Start, modify rate or stop direct report of a sensor in a certain direct channel. A special - * case is setting sensor handle -1 to stop means to stop all active sensor report on the - * channel specified. - * - * A HAL declares support for direct report by setting non-NULL values for both - * register_direct_channel and config_direct_report. - * - * Parameters: - * sensor_handle sensor to be configured. The sensor has to support direct report - * mode by setting flags of sensor_t. Also, direct report mode is only - * defined for continuous reporting mode sensors. - * channel_handle channel handle to be configured. - * config direct report parameters, see sensor_direct_cfg_t. - * Return value: - * - when sensor is started or sensor rate level is changed: return positive identifier of - * sensor in specified channel if successful, otherwise return negative error code. - * - when sensor is stopped: return 0 for success or negative error code for failure. - */ - int (*config_direct_report)(struct sensors_poll_device_1 *dev, - int sensor_handle, int channel_handle, const struct sensors_direct_cfg_t *config); - - /* - * Reserved for future use, must be zero. - */ - void (*reserved_procs[5])(void); - -} sensors_poll_device_1_t; - - -/** convenience API for opening and closing a device */ - -static inline int sensors_open(const struct hw_module_t* module, - struct sensors_poll_device_t** device) { - return module->methods->open(module, - SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int sensors_close(struct sensors_poll_device_t* device) { - return device->common.close(&device->common); -} - -static inline int sensors_open_1(const struct hw_module_t* module, - sensors_poll_device_1_t** device) { - return module->methods->open(module, - SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int sensors_close_1(sensors_poll_device_1_t* device) { - return device->common.close(&device->common); -} - -__END_DECLS - -#endif // ANDROID_SENSORS_INTERFACE_H +../../include_all/hardware/sensors.h
\ No newline at end of file diff --git a/include/hardware/sound_trigger.h b/include/hardware/sound_trigger.h index 7119637b..0bd0d03d 100644..120000 --- a/include/hardware/sound_trigger.h +++ b/include/hardware/sound_trigger.h @@ -1,201 +1 @@ -/* - * Copyright (C) 2014 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. - */ - -#include <system/audio.h> -#include <system/sound_trigger.h> -#include <hardware/hardware.h> - -#ifndef ANDROID_SOUND_TRIGGER_HAL_H -#define ANDROID_SOUND_TRIGGER_HAL_H - - -__BEGIN_DECLS - -/** - * The id of this module - */ -#define SOUND_TRIGGER_HARDWARE_MODULE_ID "sound_trigger" - -/** - * Name of the audio devices to open - */ -#define SOUND_TRIGGER_HARDWARE_INTERFACE "sound_trigger_hw_if" - -#define SOUND_TRIGGER_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) -#define SOUND_TRIGGER_MODULE_API_VERSION_CURRENT SOUND_TRIGGER_MODULE_API_VERSION_1_0 - - -#define SOUND_TRIGGER_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) -#define SOUND_TRIGGER_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION(1, 1) -#define SOUND_TRIGGER_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION(1, 2) -#define SOUND_TRIGGER_DEVICE_API_VERSION_1_3 HARDWARE_DEVICE_API_VERSION(1, 3) -#define SOUND_TRIGGER_DEVICE_API_VERSION_CURRENT SOUND_TRIGGER_DEVICE_API_VERSION_1_3 - -/** - * List of known sound trigger HAL modules. This is the base name of the sound_trigger HAL - * library composed of the "sound_trigger." prefix, one of the base names below and - * a suffix specific to the device. - * e.g: sondtrigger.primary.goldfish.so or sound_trigger.primary.default.so - */ - -#define SOUND_TRIGGER_HARDWARE_MODULE_ID_PRIMARY "primary" - - -/** - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -struct sound_trigger_module { - struct hw_module_t common; -}; - -typedef void (*recognition_callback_t)(struct sound_trigger_recognition_event *event, void *cookie); -typedef void (*sound_model_callback_t)(struct sound_trigger_model_event *event, void *cookie); - -struct sound_trigger_hw_device { - struct hw_device_t common; - - /* - * Retrieve implementation properties. - */ - int (*get_properties)(const struct sound_trigger_hw_device *dev, - struct sound_trigger_properties *properties); - - /* - * Load a sound model. Once loaded, recognition of this model can be started and stopped. - * Only one active recognition per model at a time. The SoundTrigger service will handle - * concurrent recognition requests by different users/applications on the same model. - * The implementation returns a unique handle used by other functions (unload_sound_model(), - * start_recognition(), etc... - */ - int (*load_sound_model)(const struct sound_trigger_hw_device *dev, - struct sound_trigger_sound_model *sound_model, - sound_model_callback_t callback, - void *cookie, - sound_model_handle_t *handle); - - /* - * Unload a sound model. A sound model can be unloaded to make room for a new one to overcome - * implementation limitations. - */ - int (*unload_sound_model)(const struct sound_trigger_hw_device *dev, - sound_model_handle_t handle); - - /* Start recognition on a given model. Only one recognition active at a time per model. - * Once recognition succeeds of fails, the callback is called. - * TODO: group recognition configuration parameters into one struct and add key phrase options. - */ - int (*start_recognition)(const struct sound_trigger_hw_device *dev, - sound_model_handle_t sound_model_handle, - const struct sound_trigger_recognition_config *config, - recognition_callback_t callback, - void *cookie); - - /* Stop recognition on a given model. - * The implementation does not have to call the callback when stopped via this method. - */ - int (*stop_recognition)(const struct sound_trigger_hw_device *dev, - sound_model_handle_t sound_model_handle); - - /* Stop recognition on all models. - * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_1 or above. - * If no implementation is provided, stop_recognition will be called for each running model. - */ - int (*stop_all_recognitions)(const struct sound_trigger_hw_device* dev); - - /* Get the current state of a given model. - * The state will be returned as a recognition event, via the callback that was registered - * in the start_recognition method. - * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_2 or above. - */ - int (*get_model_state)(const struct sound_trigger_hw_device *dev, - sound_model_handle_t sound_model_handle); - - /* Set a model specific ModelParameter with the given value. This parameter - * will keep its value for the duration the model is loaded regardless of starting and stopping - * recognition. Once the model is unloaded, the value will be lost. - * Returns 0 or an error code. - * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. - */ - int (*set_parameter)(const struct sound_trigger_hw_device *dev, - sound_model_handle_t sound_model_handle, - sound_trigger_model_parameter_t model_param, int32_t value); - - /* Get a model specific ModelParameter. This parameter will keep its value - * for the duration the model is loaded regardless of starting and stopping recognition. - * Once the model is unloaded, the value will be lost. If the value is not set, a default - * value is returned. See sound_trigger_model_parameter_t for parameter default values. - * Returns 0 or an error code. On return 0, value pointer will be set. - * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. - */ - int (*get_parameter)(const struct sound_trigger_hw_device *dev, - sound_model_handle_t sound_model_handle, - sound_trigger_model_parameter_t model_param, int32_t* value); - - /* Get supported parameter attributes with respect to the provided model - * handle. Along with determining the valid range, this API is also used - * to determine if a given parameter ID is supported at all by the - * modelHandle for use with getParameter and setParameter APIs. - * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. - */ - int (*query_parameter)(const struct sound_trigger_hw_device *dev, - sound_model_handle_t sound_model_handle, - sound_trigger_model_parameter_t model_param, - sound_trigger_model_parameter_range_t* param_range); - - /* - * Retrieve verbose extended implementation properties. - * The header pointer is intented to be cast to the proper extended - * properties struct based on the header version. - * The returned pointer is valid throughout the lifetime of the driver. - * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. - */ - const struct sound_trigger_properties_header* (*get_properties_extended) - (const struct sound_trigger_hw_device *dev); - - /* Start recognition on a given model. Only one recognition active at a time per model. - * Once recognition succeeds of fails, the callback is called. - * Recognition API includes extended config fields. The header is intended to be base to - * the proper config struct based on the header version. - * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. - */ - int (*start_recognition_extended)(const struct sound_trigger_hw_device *dev, - sound_model_handle_t sound_model_handle, - const struct sound_trigger_recognition_config_header *header, - recognition_callback_t callback, - void *cookie); -}; - -typedef struct sound_trigger_hw_device sound_trigger_hw_device_t; - -/** convenience API for opening and closing a supported device */ - -static inline int sound_trigger_hw_device_open(const struct hw_module_t* module, - struct sound_trigger_hw_device** device) -{ - return module->methods->open(module, SOUND_TRIGGER_HARDWARE_INTERFACE, - TO_HW_DEVICE_T_OPEN(device)); -} - -static inline int sound_trigger_hw_device_close(struct sound_trigger_hw_device* device) -{ - return device->common.close(&device->common); -} - -__END_DECLS - -#endif // ANDROID_SOUND_TRIGGER_HAL_H +../../include_all/hardware/sound_trigger.h
\ No newline at end of file diff --git a/include/hardware/tv_input.h b/include/hardware/tv_input.h index b421d430..0c8780da 100644..120000 --- a/include/hardware/tv_input.h +++ b/include/hardware/tv_input.h @@ -1,405 +1 @@ -/* - * Copyright 2014 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_TV_INPUT_INTERFACE_H -#define ANDROID_TV_INPUT_INTERFACE_H - -#include <stdint.h> -#include <sys/cdefs.h> -#include <sys/types.h> - -#include <hardware/hardware.h> -#include <system/audio.h> -#include <cutils/native_handle.h> - -__BEGIN_DECLS - -/* - * Module versioning information for the TV input hardware module, based on - * tv_input_module_t.common.module_api_version. - * - * Version History: - * - * TV_INPUT_MODULE_API_VERSION_0_1: - * Initial TV input hardware module API. - * - */ - -#define TV_INPUT_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) - -#define TV_INPUT_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION(0, 1) - -/* - * The id of this module - */ -#define TV_INPUT_HARDWARE_MODULE_ID "tv_input" - -#define TV_INPUT_DEFAULT_DEVICE "default" - -/*****************************************************************************/ - -/* - * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM - * and the fields of this data structure must begin with hw_module_t - * followed by module specific information. - */ -typedef struct tv_input_module { - struct hw_module_t common; -} tv_input_module_t; - -/*****************************************************************************/ - -enum { - /* Generic hardware. */ - TV_INPUT_TYPE_OTHER_HARDWARE = 1, - /* Tuner. (e.g. built-in terrestrial tuner) */ - TV_INPUT_TYPE_TUNER = 2, - TV_INPUT_TYPE_COMPOSITE = 3, - TV_INPUT_TYPE_SVIDEO = 4, - TV_INPUT_TYPE_SCART = 5, - TV_INPUT_TYPE_COMPONENT = 6, - TV_INPUT_TYPE_VGA = 7, - TV_INPUT_TYPE_DVI = 8, - /* Physical HDMI port. (e.g. HDMI 1) */ - TV_INPUT_TYPE_HDMI = 9, - TV_INPUT_TYPE_DISPLAY_PORT = 10, -}; -typedef uint32_t tv_input_type_t; - -typedef struct tv_input_device_info { - /* Device ID */ - int device_id; - - /* Type of physical TV input. */ - tv_input_type_t type; - - union { - struct { - /* HDMI port ID number */ - uint32_t port_id; - } hdmi; - - /* TODO: add other type specific information. */ - - int32_t type_info_reserved[16]; - }; - - /* TODO: Add capability if necessary. */ - - /* - * Audio info - * - * audio_type == AUDIO_DEVICE_NONE if this input has no audio. - */ - audio_devices_t audio_type; - const char* audio_address; - - int32_t reserved[16]; -} tv_input_device_info_t; - -/* See tv_input_event_t for more details. */ -enum { - /* - * Hardware notifies the framework that a device is available. - * - * Note that DEVICE_AVAILABLE and DEVICE_UNAVAILABLE events do not represent - * hotplug events (i.e. plugging cable into or out of the physical port). - * These events notify the framework whether the port is available or not. - * For a concrete example, when a user plugs in or pulls out the HDMI cable - * from a HDMI port, it does not generate DEVICE_AVAILABLE and/or - * DEVICE_UNAVAILABLE events. However, if a user inserts a pluggable USB - * tuner into the Android device, it will generate a DEVICE_AVAILABLE event - * and when the port is removed, it should generate a DEVICE_UNAVAILABLE - * event. - * - * For hotplug events, please see STREAM_CONFIGURATION_CHANGED for more - * details. - * - * HAL implementation should register devices by using this event when the - * device boots up. The framework will recognize device reported via this - * event only. In addition, the implementation could use this event to - * notify the framework that a removable TV input device (such as USB tuner - * as stated in the example above) is attached. - */ - TV_INPUT_EVENT_DEVICE_AVAILABLE = 1, - /* - * Hardware notifies the framework that a device is unavailable. - * - * HAL implementation should generate this event when a device registered - * by TV_INPUT_EVENT_DEVICE_AVAILABLE is no longer available. For example, - * the event can indicate that a USB tuner is plugged out from the Android - * device. - * - * Note that this event is not for indicating cable plugged out of the port; - * for that purpose, the implementation should use - * STREAM_CONFIGURATION_CHANGED event. This event represents the port itself - * being no longer available. - */ - TV_INPUT_EVENT_DEVICE_UNAVAILABLE = 2, - /* - * Stream configurations are changed. Client should regard all open streams - * at the specific device are closed, and should call - * get_stream_configurations() again, opening some of them if necessary. - * - * HAL implementation should generate this event when the available stream - * configurations change for any reason. A typical use case of this event - * would be to notify the framework that the input signal has changed - * resolution, or that the cable is plugged out so that the number of - * available streams is 0. - * - * The implementation may use this event to indicate hotplug status of the - * port. the framework regards input devices with no available streams as - * disconnected, so the implementation can generate this event with no - * available streams to indicate that this device is disconnected, and vice - * versa. - */ - TV_INPUT_EVENT_STREAM_CONFIGURATIONS_CHANGED = 3, - /* - * Hardware is done with capture request with the buffer. Client can assume - * ownership of the buffer again. - * - * HAL implementation should generate this event after request_capture() if - * it succeeded. The event shall have the buffer with the captured image. - */ - TV_INPUT_EVENT_CAPTURE_SUCCEEDED = 4, - /* - * Hardware met a failure while processing a capture request or client - * canceled the request. Client can assume ownership of the buffer again. - * - * The event is similar to TV_INPUT_EVENT_CAPTURE_SUCCEEDED, but HAL - * implementation generates this event upon a failure to process - * request_capture(), or a request cancellation. - */ - TV_INPUT_EVENT_CAPTURE_FAILED = 5, -}; -typedef uint32_t tv_input_event_type_t; - -typedef struct tv_input_capture_result { - /* Device ID */ - int device_id; - - /* Stream ID */ - int stream_id; - - /* Sequence number of the request */ - uint32_t seq; - - /* - * The buffer passed to hardware in request_capture(). The content of - * buffer is undefined (although buffer itself is valid) for - * TV_INPUT_CAPTURE_FAILED event. - */ - buffer_handle_t buffer; - - /* - * Error code for the request. -ECANCELED if request is cancelled; other - * error codes are unknown errors. - */ - int error_code; -} tv_input_capture_result_t; - -typedef struct tv_input_event { - tv_input_event_type_t type; - - union { - /* - * TV_INPUT_EVENT_DEVICE_AVAILABLE: all fields are relevant - * TV_INPUT_EVENT_DEVICE_UNAVAILABLE: only device_id is relevant - * TV_INPUT_EVENT_STREAM_CONFIGURATIONS_CHANGED: only device_id is - * relevant - */ - tv_input_device_info_t device_info; - /* - * TV_INPUT_EVENT_CAPTURE_SUCCEEDED: error_code is not relevant - * TV_INPUT_EVENT_CAPTURE_FAILED: all fields are relevant - */ - tv_input_capture_result_t capture_result; - }; -} tv_input_event_t; - -typedef struct tv_input_callback_ops { - /* - * event contains the type of the event and additional data if necessary. - * The event object is guaranteed to be valid only for the duration of the - * call. - * - * data is an object supplied at device initialization, opaque to the - * hardware. - Â Â Â Â */ - void (*notify)(struct tv_input_device* dev, - tv_input_event_t* event, void* data); -} tv_input_callback_ops_t; - -enum { - TV_STREAM_TYPE_INDEPENDENT_VIDEO_SOURCE = 1, - TV_STREAM_TYPE_BUFFER_PRODUCER = 2, -}; -typedef uint32_t tv_stream_type_t; - -typedef struct tv_stream_config { - /* - * ID number of the stream. This value is used to identify the whole stream - * configuration. - */ - int stream_id; - - /* Type of the stream */ - tv_stream_type_t type; - - /* Max width/height of the stream. */ - uint32_t max_video_width; - uint32_t max_video_height; -} tv_stream_config_t; - -typedef struct buffer_producer_stream { - /* - * IN/OUT: Width / height of the stream. Client may request for specific - * size but hardware may change it. Client must allocate buffers with - * specified width and height. - */ - uint32_t width; - uint32_t height; - - /* OUT: Client must set this usage when allocating buffer. */ - uint32_t usage; - - /* OUT: Client must allocate a buffer with this format. */ - uint32_t format; -} buffer_producer_stream_t; - -typedef struct tv_stream { - /* IN: ID in the stream configuration */ - int stream_id; - - /* OUT: Type of the stream (for convenience) */ - tv_stream_type_t type; - - /* Data associated with the stream for client's use */ - union { - /* OUT: A native handle describing the sideband stream source */ - native_handle_t* sideband_stream_source_handle; - - /* IN/OUT: Details are in buffer_producer_stream_t */ - buffer_producer_stream_t buffer_producer; - }; -} tv_stream_t; - -/* - * Every device data structure must begin with hw_device_t - * followed by module specific public methods and attributes. - */ -typedef struct tv_input_device { - struct hw_device_t common; - - /* - * initialize: - * - * Provide callbacks to the device and start operation. At first, no device - * is available and after initialize() completes, currently available - * devices including static devices should notify via callback. - * - * Framework owns callbacks object. - * - * data is a framework-owned object which would be sent back to the - * framework for each callback notifications. - * - * Return 0 on success. - */ - int (*initialize)(struct tv_input_device* dev, - const tv_input_callback_ops_t* callback, void* data); - - /* - * get_stream_configurations: - * - * Get stream configurations for a specific device. An input device may have - * multiple configurations. - * - * The configs object is guaranteed to be valid only until the next call to - * get_stream_configurations() or STREAM_CONFIGURATIONS_CHANGED event. - * - * Return 0 on success. - */ - int (*get_stream_configurations)(const struct tv_input_device* dev, - int device_id, int* num_configurations, - const tv_stream_config_t** configs); - - /* - * open_stream: - * - * Open a stream with given stream ID. Caller owns stream object, and the - * populated data is only valid until the stream is closed. - * - * Return 0 on success; -EBUSY if the client should close other streams to - * open the stream; -EEXIST if the stream with the given ID is already open; - * -EINVAL if device_id and/or stream_id are invalid; other non-zero value - * denotes unknown error. - */ - int (*open_stream)(struct tv_input_device* dev, int device_id, - tv_stream_t* stream); - - /* - * close_stream: - * - * Close a stream to a device. data in tv_stream_t* object associated with - * the stream_id is obsolete once this call finishes. - * - * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if - * device_id and/or stream_id are invalid. - */ - int (*close_stream)(struct tv_input_device* dev, int device_id, - int stream_id); - - /* - * request_capture: - * - * Request buffer capture for a stream. This is only valid for buffer - * producer streams. The buffer should be created with size, format and - * usage specified in the stream. Framework provides seq in an - * increasing sequence per each stream. Hardware should provide the picture - * in a chronological order according to seq. For example, if two - * requests are being processed at the same time, the request with the - * smaller seq should get an earlier frame. - * - * The framework releases the ownership of the buffer upon calling this - * function. When the buffer is filled, hardware notifies the framework - * via TV_INPUT_EVENT_CAPTURE_FINISHED callback, and the ownership is - * transferred back to framework at that time. - * - * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if - * device_id and/or stream_id are invalid; -EWOULDBLOCK if HAL cannot take - * additional requests until it releases a buffer. - */ - int (*request_capture)(struct tv_input_device* dev, int device_id, - int stream_id, buffer_handle_t buffer, uint32_t seq); - - /* - * cancel_capture: - * - * Cancel an ongoing capture. Hardware should release the buffer as soon as - * possible via TV_INPUT_EVENT_CAPTURE_FAILED callback. - * - * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if - * device_id, stream_id, and/or seq are invalid. - */ - int (*cancel_capture)(struct tv_input_device* dev, int device_id, - int stream_id, uint32_t seq); - - void* reserved[16]; -} tv_input_device_t; - -__END_DECLS - -#endif // ANDROID_TV_INPUT_INTERFACE_H +../../include_all/hardware/tv_input.h
\ No newline at end of file diff --git a/include/hardware/vibrator.h b/include/hardware/vibrator.h index 361085f4..423e53e8 100644..120000 --- a/include/hardware/vibrator.h +++ b/include/hardware/vibrator.h @@ -1,73 +1 @@ -/* - * Copyright (C) 2013 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 _HARDWARE_VIBRATOR_H -#define _HARDWARE_VIBRATOR_H - -#include <hardware/hardware.h> - -__BEGIN_DECLS - -#define VIBRATOR_API_VERSION HARDWARE_MODULE_API_VERSION(1,0) - -/** - * The id of this module - */ -#define VIBRATOR_HARDWARE_MODULE_ID "vibrator" - -/** - * The id of the main vibrator device - */ -#define VIBRATOR_DEVICE_ID_MAIN "main_vibrator" - -struct vibrator_device; -typedef struct vibrator_device { - /** - * Common methods of the vibrator device. This *must* be the first member of - * vibrator_device as users of this structure will cast a hw_device_t to - * vibrator_device pointer in contexts where it's known the hw_device_t references a - * vibrator_device. - */ - struct hw_device_t common; - - /** Turn on vibrator - * - * This function must only be called after the previous timeout has expired or - * was canceled (through vibrator_off()). - * - * @param timeout_ms number of milliseconds to vibrate - * - * @return 0 in case of success, negative errno code else - */ - int (*vibrator_on)(struct vibrator_device* vibradev, unsigned int timeout_ms); - - /** Turn off vibrator - * - * Cancel a previously-started vibration, if any. - * - * @return 0 in case of success, negative errno code else - */ - int (*vibrator_off)(struct vibrator_device* vibradev); -} vibrator_device_t; - -static inline int vibrator_open(const struct hw_module_t* module, vibrator_device_t** device) -{ - return module->methods->open(module, VIBRATOR_DEVICE_ID_MAIN, TO_HW_DEVICE_T_OPEN(device)); -} - -__END_DECLS - -#endif // _HARDWARE_VIBRATOR_H +../../include_all/hardware/vibrator.h
\ No newline at end of file diff --git a/include_all/hardware/audio.h b/include_all/hardware/audio.h new file mode 100644 index 00000000..daaa16f1 --- /dev/null +++ b/include_all/hardware/audio.h @@ -0,0 +1,1088 @@ +/* + * Copyright (C) 2011 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_AUDIO_HAL_INTERFACE_H +#define ANDROID_AUDIO_HAL_INTERFACE_H + +#include <stdint.h> +#include <strings.h> +#include <sys/cdefs.h> +#include <sys/types.h> +#include <time.h> + +#include <cutils/bitops.h> + +#include <hardware/hardware.h> +#include <system/audio.h> +#include <hardware/audio_effect.h> + +__BEGIN_DECLS + +/** + * The id of this module + */ +#define AUDIO_HARDWARE_MODULE_ID "audio" + +/** + * Name of the audio devices to open + */ +#define AUDIO_HARDWARE_INTERFACE "audio_hw_if" + + +/* Use version 0.1 to be compatible with first generation of audio hw module with version_major + * hardcoded to 1. No audio module API change. + */ +#define AUDIO_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) +#define AUDIO_MODULE_API_VERSION_CURRENT AUDIO_MODULE_API_VERSION_0_1 + +/* First generation of audio devices had version hardcoded to 0. all devices with versions < 1.0 + * will be considered of first generation API. + */ +#define AUDIO_DEVICE_API_VERSION_0_0 HARDWARE_DEVICE_API_VERSION(0, 0) +#define AUDIO_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) +#define AUDIO_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) +#define AUDIO_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0) +#define AUDIO_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1) +#define AUDIO_DEVICE_API_VERSION_3_2 HARDWARE_DEVICE_API_VERSION(3, 2) +#define AUDIO_DEVICE_API_VERSION_CURRENT AUDIO_DEVICE_API_VERSION_3_2 +/* Minimal audio HAL version supported by the audio framework */ +#define AUDIO_DEVICE_API_VERSION_MIN AUDIO_DEVICE_API_VERSION_2_0 + +/**************************************/ + +/** + * standard audio parameters that the HAL may need to handle + */ + +/** + * audio device parameters + */ + +/* TTY mode selection */ +#define AUDIO_PARAMETER_KEY_TTY_MODE "tty_mode" +#define AUDIO_PARAMETER_VALUE_TTY_OFF "tty_off" +#define AUDIO_PARAMETER_VALUE_TTY_VCO "tty_vco" +#define AUDIO_PARAMETER_VALUE_TTY_HCO "tty_hco" +#define AUDIO_PARAMETER_VALUE_TTY_FULL "tty_full" + +/* Hearing Aid Compatibility - Telecoil (HAC-T) mode on/off */ +#define AUDIO_PARAMETER_KEY_HAC "HACSetting" +#define AUDIO_PARAMETER_VALUE_HAC_ON "ON" +#define AUDIO_PARAMETER_VALUE_HAC_OFF "OFF" + +/* A2DP sink address set by framework */ +#define AUDIO_PARAMETER_A2DP_SINK_ADDRESS "a2dp_sink_address" + +/* A2DP source address set by framework */ +#define AUDIO_PARAMETER_A2DP_SOURCE_ADDRESS "a2dp_source_address" + +/* Bluetooth SCO wideband */ +#define AUDIO_PARAMETER_KEY_BT_SCO_WB "bt_wbs" + +/* BT SCO headset name for debug */ +#define AUDIO_PARAMETER_KEY_BT_SCO_HEADSET_NAME "bt_headset_name" + +/* BT SCO HFP control */ +#define AUDIO_PARAMETER_KEY_HFP_ENABLE "hfp_enable" +#define AUDIO_PARAMETER_KEY_HFP_SET_SAMPLING_RATE "hfp_set_sampling_rate" +#define AUDIO_PARAMETER_KEY_HFP_VOLUME "hfp_volume" + +/* Set screen orientation */ +#define AUDIO_PARAMETER_KEY_ROTATION "rotation" + +/** + * audio stream parameters + */ + +/* Enable AANC */ +#define AUDIO_PARAMETER_KEY_AANC "aanc_enabled" + +/**************************************/ + +/* common audio stream parameters and operations */ +struct audio_stream { + + /** + * Return the sampling rate in Hz - eg. 44100. + */ + uint32_t (*get_sample_rate)(const struct audio_stream *stream); + + /* currently unused - use set_parameters with key + * AUDIO_PARAMETER_STREAM_SAMPLING_RATE + */ + int (*set_sample_rate)(struct audio_stream *stream, uint32_t rate); + + /** + * Return size of input/output buffer in bytes for this stream - eg. 4800. + * It should be a multiple of the frame size. See also get_input_buffer_size. + */ + size_t (*get_buffer_size)(const struct audio_stream *stream); + + /** + * Return the channel mask - + * e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO + */ + audio_channel_mask_t (*get_channels)(const struct audio_stream *stream); + + /** + * Return the audio format - e.g. AUDIO_FORMAT_PCM_16_BIT + */ + audio_format_t (*get_format)(const struct audio_stream *stream); + + /* currently unused - use set_parameters with key + * AUDIO_PARAMETER_STREAM_FORMAT + */ + int (*set_format)(struct audio_stream *stream, audio_format_t format); + + /** + * Put the audio hardware input/output into standby mode. + * Driver should exit from standby mode at the next I/O operation. + * Returns 0 on success and <0 on failure. + */ + int (*standby)(struct audio_stream *stream); + + /** dump the state of the audio input/output device */ + int (*dump)(const struct audio_stream *stream, int fd); + + /** Return the set of device(s) which this stream is connected to */ + audio_devices_t (*get_device)(const struct audio_stream *stream); + + /** + * Currently unused - set_device() corresponds to set_parameters() with key + * AUDIO_PARAMETER_STREAM_ROUTING for both input and output. + * AUDIO_PARAMETER_STREAM_INPUT_SOURCE is an additional information used by + * input streams only. + */ + int (*set_device)(struct audio_stream *stream, audio_devices_t device); + + /** + * set/get audio stream parameters. The function accepts a list of + * parameter key value pairs in the form: key1=value1;key2=value2;... + * + * Some keys are reserved for standard parameters (See AudioParameter class) + * + * If the implementation does not accept a parameter change while + * the output is active but the parameter is acceptable otherwise, it must + * return -ENOSYS. + * + * The audio flinger will put the stream in standby and then change the + * parameter value. + */ + int (*set_parameters)(struct audio_stream *stream, const char *kv_pairs); + + /* + * Returns a pointer to a heap allocated string. The caller is responsible + * for freeing the memory for it using free(). + */ + char * (*get_parameters)(const struct audio_stream *stream, + const char *keys); + int (*add_audio_effect)(const struct audio_stream *stream, + effect_handle_t effect); + int (*remove_audio_effect)(const struct audio_stream *stream, + effect_handle_t effect); +}; +typedef struct audio_stream audio_stream_t; + +/* type of asynchronous write callback events. Mutually exclusive */ +typedef enum { + STREAM_CBK_EVENT_WRITE_READY, /* non blocking write completed */ + STREAM_CBK_EVENT_DRAIN_READY, /* drain completed */ + STREAM_CBK_EVENT_ERROR, /* stream hit some error, let AF take action */ +} stream_callback_event_t; + +typedef enum { + STREAM_EVENT_CBK_TYPE_CODEC_FORMAT_CHANGED, /* codec format of the stream changed */ +} stream_event_callback_type_t; + +typedef int (*stream_callback_t)(stream_callback_event_t event, void *param, void *cookie); + +typedef int (*stream_event_callback_t)(stream_event_callback_type_t event, + void *param, void *cookie); + +/* type of drain requested to audio_stream_out->drain(). Mutually exclusive */ +typedef enum { + AUDIO_DRAIN_ALL, /* drain() returns when all data has been played */ + AUDIO_DRAIN_EARLY_NOTIFY /* drain() returns a short time before all data + from the current track has been played to + give time for gapless track switch */ +} audio_drain_type_t; + +typedef struct source_metadata { + size_t track_count; + /** Array of metadata of each track connected to this source. */ + struct playback_track_metadata* tracks; +} source_metadata_t; + +typedef struct sink_metadata { + size_t track_count; + /** Array of metadata of each track connected to this sink. */ + struct record_track_metadata* tracks; +} sink_metadata_t; + +/* HAL version 3.2 and higher only. */ +typedef struct source_metadata_v7 { + size_t track_count; + /** Array of metadata of each track connected to this source. */ + struct playback_track_metadata_v7* tracks; +} source_metadata_v7_t; + +/* HAL version 3.2 and higher only. */ +typedef struct sink_metadata_v7 { + size_t track_count; + /** Array of metadata of each track connected to this sink. */ + struct record_track_metadata_v7* tracks; +} sink_metadata_v7_t; + +/** output stream callback method to indicate changes in supported latency modes */ +typedef void (*stream_latency_mode_callback_t)( + audio_latency_mode_t *modes, size_t num_modes, void *cookie); + +/** + * audio_stream_out is the abstraction interface for the audio output hardware. + * + * It provides information about various properties of the audio output + * hardware driver. + */ +struct audio_stream_out { + /** + * Common methods of the audio stream out. This *must* be the first member of audio_stream_out + * as users of this structure will cast a audio_stream to audio_stream_out pointer in contexts + * where it's known the audio_stream references an audio_stream_out. + */ + struct audio_stream common; + + /** + * Return the audio hardware driver estimated latency in milliseconds. + */ + uint32_t (*get_latency)(const struct audio_stream_out *stream); + + /** + * Use this method in situations where audio mixing is done in the + * hardware. This method serves as a direct interface with hardware, + * allowing you to directly set the volume as apposed to via the framework. + * This method might produce multiple PCM outputs or hardware accelerated + * codecs, such as MP3 or AAC. + */ + int (*set_volume)(struct audio_stream_out *stream, float left, float right); + + /** + * Write audio buffer to driver. Returns number of bytes written, or a + * negative status_t. If at least one frame was written successfully prior to the error, + * it is suggested that the driver return that successful (short) byte count + * and then return an error in the subsequent call. + * + * If set_callback() has previously been called to enable non-blocking mode + * the write() is not allowed to block. It must write only the number of + * bytes that currently fit in the driver/hardware buffer and then return + * this byte count. If this is less than the requested write size the + * callback function must be called when more space is available in the + * driver/hardware buffer. + */ + ssize_t (*write)(struct audio_stream_out *stream, const void* buffer, + size_t bytes); + + /* return the number of audio frames written by the audio dsp to DAC since + * the output has exited standby + */ + int (*get_render_position)(const struct audio_stream_out *stream, + uint32_t *dsp_frames); + + /** + * get the local time at which the next write to the audio driver will be presented. + * The units are microseconds, where the epoch is decided by the local audio HAL. + */ + int (*get_next_write_timestamp)(const struct audio_stream_out *stream, + int64_t *timestamp); + + /** + * set the callback function for notifying completion of non-blocking + * write and drain. + * Calling this function implies that all future write() and drain() + * must be non-blocking and use the callback to signal completion. + */ + int (*set_callback)(struct audio_stream_out *stream, + stream_callback_t callback, void *cookie); + + /** + * Notifies to the audio driver to stop playback however the queued buffers are + * retained by the hardware. Useful for implementing pause/resume. Empty implementation + * if not supported however should be implemented for hardware with non-trivial + * latency. In the pause state audio hardware could still be using power. User may + * consider calling suspend after a timeout. + * + * Implementation of this function is mandatory for offloaded playback. + */ + int (*pause)(struct audio_stream_out* stream); + + /** + * Notifies to the audio driver to resume playback following a pause. + * Returns error if called without matching pause. + * + * Implementation of this function is mandatory for offloaded playback. + */ + int (*resume)(struct audio_stream_out* stream); + + /** + * Requests notification when data buffered by the driver/hardware has + * been played. If set_callback() has previously been called to enable + * non-blocking mode, the drain() must not block, instead it should return + * quickly and completion of the drain is notified through the callback. + * If set_callback() has not been called, the drain() must block until + * completion. + * If type==AUDIO_DRAIN_ALL, the drain completes when all previously written + * data has been played. + * If type==AUDIO_DRAIN_EARLY_NOTIFY, the drain completes shortly before all + * data for the current track has played to allow time for the framework + * to perform a gapless track switch. + * + * Drain must return immediately on stop() and flush() call + * + * Implementation of this function is mandatory for offloaded playback. + */ + int (*drain)(struct audio_stream_out* stream, audio_drain_type_t type ); + + /** + * Notifies to the audio driver to flush the queued data. Stream must already + * be paused before calling flush(). + * + * Implementation of this function is mandatory for offloaded playback. + */ + int (*flush)(struct audio_stream_out* stream); + + /** + * Return a recent count of the number of audio frames presented to an external observer. + * This excludes frames which have been written but are still in the pipeline. + * The count is not reset to zero when output enters standby. + * Also returns the value of CLOCK_MONOTONIC as of this presentation count. + * The returned count is expected to be 'recent', + * but does not need to be the most recent possible value. + * However, the associated time should correspond to whatever count is returned. + * Example: assume that N+M frames have been presented, where M is a 'small' number. + * Then it is permissible to return N instead of N+M, + * and the timestamp should correspond to N rather than N+M. + * The terms 'recent' and 'small' are not defined. + * They reflect the quality of the implementation. + * + * 3.0 and higher only. + */ + int (*get_presentation_position)(const struct audio_stream_out *stream, + uint64_t *frames, struct timespec *timestamp); + + /** + * Called by the framework to start a stream operating in mmap mode. + * create_mmap_buffer must be called before calling start() + * + * \note Function only implemented by streams operating in mmap mode. + * + * \param[in] stream the stream object. + * \return 0 in case of success. + * -ENOSYS if called out of sequence or on non mmap stream + */ + int (*start)(const struct audio_stream_out* stream); + + /** + * Called by the framework to stop a stream operating in mmap mode. + * Must be called after start() + * + * \note Function only implemented by streams operating in mmap mode. + * + * \param[in] stream the stream object. + * \return 0 in case of success. + * -ENOSYS if called out of sequence or on non mmap stream + */ + int (*stop)(const struct audio_stream_out* stream); + + /** + * Called by the framework to retrieve information on the mmap buffer used for audio + * samples transfer. + * + * \note Function only implemented by streams operating in mmap mode. + * + * \param[in] stream the stream object. + * \param[in] min_size_frames minimum buffer size requested. The actual buffer + * size returned in struct audio_mmap_buffer_info can be larger. + * \param[out] info address at which the mmap buffer information should be returned. + * + * \return 0 if the buffer was allocated. + * -ENODEV in case of initialization error + * -EINVAL if the requested buffer size is too large + * -ENOSYS if called out of sequence (e.g. buffer already allocated) + */ + int (*create_mmap_buffer)(const struct audio_stream_out *stream, + int32_t min_size_frames, + struct audio_mmap_buffer_info *info); + + /** + * Called by the framework to read current read/write position in the mmap buffer + * with associated time stamp. + * + * \note Function only implemented by streams operating in mmap mode. + * + * \param[in] stream the stream object. + * \param[out] position address at which the mmap read/write position should be returned. + * + * \return 0 if the position is successfully returned. + * -ENODATA if the position cannot be retrieved + * -ENOSYS if called before create_mmap_buffer() + */ + int (*get_mmap_position)(const struct audio_stream_out *stream, + struct audio_mmap_position *position); + + /** + * Called when the metadata of the stream's source has been changed. + * @param source_metadata Description of the audio that is played by the clients. + */ + void (*update_source_metadata)(struct audio_stream_out *stream, + const struct source_metadata* source_metadata); + + /** + * Set the callback function for notifying events for an output stream. + */ + int (*set_event_callback)(struct audio_stream_out *stream, + stream_event_callback_t callback, + void *cookie); + + /** + * Called when the metadata of the stream's source has been changed. + * HAL version 3.2 and higher only. + * @param source_metadata Description of the audio that is played by the clients. + */ + void (*update_source_metadata_v7)(struct audio_stream_out *stream, + const struct source_metadata_v7* source_metadata); + + /** + * Returns the Dual Mono mode presentation setting. + * + * \param[in] stream the stream object. + * \param[out] mode current setting of Dual Mono mode. + * + * \return 0 if the position is successfully returned. + * -EINVAL if the arguments are invalid + * -ENOSYS if the function is not available + */ + int (*get_dual_mono_mode)(struct audio_stream_out *stream, audio_dual_mono_mode_t *mode); + + /** + * Sets the Dual Mono mode presentation on the output device. + * + * \param[in] stream the stream object. + * \param[in] mode selected Dual Mono mode. + * + * \return 0 in case of success. + * -EINVAL if the arguments are invalid + * -ENOSYS if the function is not available + */ + int (*set_dual_mono_mode)(struct audio_stream_out *stream, const audio_dual_mono_mode_t mode); + + /** + * Returns the Audio Description Mix level in dB. + * + * \param[in] stream the stream object. + * \param[out] leveldB the current Audio Description Mix Level in dB. + * + * \return 0 in case of success. + * -EINVAL if the arguments are invalid + * -ENOSYS if the function is not available + */ + int (*get_audio_description_mix_level)(struct audio_stream_out *stream, float *leveldB); + + /** + * Sets the Audio Description Mix level in dB. + * + * \param[in] stream the stream object. + * \param[in] leveldB Audio Description Mix Level in dB. + * + * \return 0 in case of success. + * -EINVAL if the arguments are invalid + * -ENOSYS if the function is not available + */ + int (*set_audio_description_mix_level)(struct audio_stream_out *stream, const float leveldB); + + /** + * Retrieves current playback rate parameters. + * + * \param[in] stream the stream object. + * \param[out] playbackRate current playback parameters. + * + * \return 0 in case of success. + * -EINVAL if the arguments are invalid + * -ENOSYS if the function is not available + */ + int (*get_playback_rate_parameters)(struct audio_stream_out *stream, + audio_playback_rate_t *playbackRate); + + /** + * Sets the playback rate parameters that control playback behavior. + * + * \param[in] stream the stream object. + * \param[in] playbackRate playback parameters. + * + * \return 0 in case of success. + * -EINVAL if the arguments are invalid + * -ENOSYS if the function is not available + */ + int (*set_playback_rate_parameters)(struct audio_stream_out *stream, + const audio_playback_rate_t *playbackRate); + + /** + * Indicates the requested latency mode for this output stream. + * + * The requested mode can be one of the modes returned by + * get_recommended_latency_modes(). + * + * Support for this method is optional but mandated on specific spatial audio + * streams indicated by AUDIO_OUTPUT_FLAG_SPATIALIZER flag if they can be routed + * to a BT classic sink. + * + * \param[in] stream the stream object. + * \param[in] mode the requested latency mode. + * \return 0 in case of success. + * -EINVAL if the arguments are invalid + * -ENOSYS if the function is not available + */ + int (*set_latency_mode)(struct audio_stream_out *stream, audio_latency_mode_t mode); + + /** + * Indicates which latency modes are currently supported on this output stream. + * If the transport protocol (e.g Bluetooth A2DP) used by this output stream to reach + * the output device supports variable latency modes, the HAL indicates which + * modes are currently supported. + * The framework can then call setLatencyMode() with one of the supported modes to select + * the desired operation mode. + * + * Support for this method is optional but mandated on specific spatial audio + * streams indicated by AUDIO_OUTPUT_FLAG_SPATIALIZER flag if they can be routed + * to a BT classic sink. + * + * \return 0 in case of success. + * -EINVAL if the arguments are invalid + * -ENOSYS if the function is not available + * \param[in] stream the stream object. + * \param[out] modes the supported latency modes. + * \param[in/out] num_modes as input the maximum number of modes to return, + * as output the actual number of modes returned. + */ + int (*get_recommended_latency_modes)(struct audio_stream_out *stream, + audio_latency_mode_t *modes, size_t *num_modes); + + /** + * Set the callback interface for notifying changes in supported latency modes. + * + * Calling this method with a null pointer will result in clearing a previously set callback. + * + * Support for this method is optional but mandated on specific spatial audio + * streams indicated by AUDIO_OUTPUT_FLAG_SPATIALIZER flag if they can be routed + * to a BT classic sink. + * + * \param[in] stream the stream object. + * \param[in] callback the registered callback or null to unregister. + * \param[in] cookie the context to pass when calling the callback. + * \return 0 in case of success. + * -EINVAL if the arguments are invalid + * -ENOSYS if the function is not available + */ + int (*set_latency_mode_callback)(struct audio_stream_out *stream, + stream_latency_mode_callback_t callback, void *cookie); +}; + +typedef struct audio_stream_out audio_stream_out_t; + +struct audio_stream_in { + /** + * Common methods of the audio stream in. This *must* be the first member of audio_stream_in + * as users of this structure will cast a audio_stream to audio_stream_in pointer in contexts + * where it's known the audio_stream references an audio_stream_in. + */ + struct audio_stream common; + + /** set the input gain for the audio driver. This method is for + * for future use */ + int (*set_gain)(struct audio_stream_in *stream, float gain); + + /** Read audio buffer in from audio driver. Returns number of bytes read, or a + * negative status_t. If at least one frame was read prior to the error, + * read should return that byte count and then return an error in the subsequent call. + */ + ssize_t (*read)(struct audio_stream_in *stream, void* buffer, + size_t bytes); + + /** + * Return the amount of input frames lost in the audio driver since the + * last call of this function. + * Audio driver is expected to reset the value to 0 and restart counting + * upon returning the current value by this function call. + * Such loss typically occurs when the user space process is blocked + * longer than the capacity of audio driver buffers. + * + * Unit: the number of input audio frames + */ + uint32_t (*get_input_frames_lost)(struct audio_stream_in *stream); + + /** + * Return a recent count of the number of audio frames received and + * the clock time associated with that frame count. + * + * frames is the total frame count received. This should be as early in + * the capture pipeline as possible. In general, + * frames should be non-negative and should not go "backwards". + * + * time is the clock MONOTONIC time when frames was measured. In general, + * time should be a positive quantity and should not go "backwards". + * + * The status returned is 0 on success, -ENOSYS if the device is not + * ready/available, or -EINVAL if the arguments are null or otherwise invalid. + */ + int (*get_capture_position)(const struct audio_stream_in *stream, + int64_t *frames, int64_t *time); + + /** + * Called by the framework to start a stream operating in mmap mode. + * create_mmap_buffer must be called before calling start() + * + * \note Function only implemented by streams operating in mmap mode. + * + * \param[in] stream the stream object. + * \return 0 in case off success. + * -ENOSYS if called out of sequence or on non mmap stream + */ + int (*start)(const struct audio_stream_in* stream); + + /** + * Called by the framework to stop a stream operating in mmap mode. + * + * \note Function only implemented by streams operating in mmap mode. + * + * \param[in] stream the stream object. + * \return 0 in case of success. + * -ENOSYS if called out of sequence or on non mmap stream + */ + int (*stop)(const struct audio_stream_in* stream); + + /** + * Called by the framework to retrieve information on the mmap buffer used for audio + * samples transfer. + * + * \note Function only implemented by streams operating in mmap mode. + * + * \param[in] stream the stream object. + * \param[in] min_size_frames minimum buffer size requested. The actual buffer + * size returned in struct audio_mmap_buffer_info can be larger. + * \param[out] info address at which the mmap buffer information should be returned. + * + * \return 0 if the buffer was allocated. + * -ENODEV in case of initialization error + * -EINVAL if the requested buffer size is too large + * -ENOSYS if called out of sequence (e.g. buffer already allocated) + */ + int (*create_mmap_buffer)(const struct audio_stream_in *stream, + int32_t min_size_frames, + struct audio_mmap_buffer_info *info); + + /** + * Called by the framework to read current read/write position in the mmap buffer + * with associated time stamp. + * + * \note Function only implemented by streams operating in mmap mode. + * + * \param[in] stream the stream object. + * \param[out] position address at which the mmap read/write position should be returned. + * + * \return 0 if the position is successfully returned. + * -ENODATA if the position cannot be retreived + * -ENOSYS if called before mmap_read_position() + */ + int (*get_mmap_position)(const struct audio_stream_in *stream, + struct audio_mmap_position *position); + + /** + * Called by the framework to read active microphones + * + * \param[in] stream the stream object. + * \param[out] mic_array Pointer to first element on array with microphone info + * \param[out] mic_count When called, this holds the value of the max number of elements + * allowed in the mic_array. The actual number of elements written + * is returned here. + * if mic_count is passed as zero, mic_array will not be populated, + * and mic_count will return the actual number of active microphones. + * + * \return 0 if the microphone array is successfully filled. + * -ENOSYS if there is an error filling the data + */ + int (*get_active_microphones)(const struct audio_stream_in *stream, + struct audio_microphone_characteristic_t *mic_array, + size_t *mic_count); + + /** + * Called by the framework to instruct the HAL to optimize the capture stream in the + * specified direction. + * + * \param[in] stream the stream object. + * \param[in] direction The direction constant (from audio-base.h) + * MIC_DIRECTION_UNSPECIFIED Don't do any directionality processing of the + * activated microphone(s). + * MIC_DIRECTION_FRONT Optimize capture for audio coming from the screen-side + * of the device. + * MIC_DIRECTION_BACK Optimize capture for audio coming from the side of the + * device opposite the screen. + * MIC_DIRECTION_EXTERNAL Optimize capture for audio coming from an off-device + * microphone. + * \return OK if the call is successful, an error code otherwise. + */ + int (*set_microphone_direction)(const struct audio_stream_in *stream, + audio_microphone_direction_t direction); + + /** + * Called by the framework to specify to the HAL the desired zoom factor for the selected + * microphone(s). + * + * \param[in] stream the stream object. + * \param[in] zoom the zoom factor. + * \return OK if the call is successful, an error code otherwise. + */ + int (*set_microphone_field_dimension)(const struct audio_stream_in *stream, + float zoom); + + /** + * Called when the metadata of the stream's sink has been changed. + * @param sink_metadata Description of the audio that is recorded by the clients. + */ + void (*update_sink_metadata)(struct audio_stream_in *stream, + const struct sink_metadata* sink_metadata); + + /** + * Called when the metadata of the stream's sink has been changed. + * HAL version 3.2 and higher only. + * @param sink_metadata Description of the audio that is recorded by the clients. + */ + void (*update_sink_metadata_v7)(struct audio_stream_in *stream, + const struct sink_metadata_v7* sink_metadata); +}; +typedef struct audio_stream_in audio_stream_in_t; + +/** + * return the frame size (number of bytes per sample). + * + * Deprecated: use audio_stream_out_frame_size() or audio_stream_in_frame_size() instead. + */ +__attribute__((__deprecated__)) +static inline size_t audio_stream_frame_size(const struct audio_stream *s) +{ + size_t chan_samp_sz; + audio_format_t format = s->get_format(s); + + if (audio_has_proportional_frames(format)) { + chan_samp_sz = audio_bytes_per_sample(format); + return popcount(s->get_channels(s)) * chan_samp_sz; + } + + return sizeof(int8_t); +} + +/** + * return the frame size (number of bytes per sample) of an output stream. + */ +static inline size_t audio_stream_out_frame_size(const struct audio_stream_out *s) +{ + size_t chan_samp_sz; + audio_format_t format = s->common.get_format(&s->common); + + if (audio_has_proportional_frames(format)) { + chan_samp_sz = audio_bytes_per_sample(format); + return audio_channel_count_from_out_mask(s->common.get_channels(&s->common)) * chan_samp_sz; + } + + return sizeof(int8_t); +} + +/** + * return the frame size (number of bytes per sample) of an input stream. + */ +static inline size_t audio_stream_in_frame_size(const struct audio_stream_in *s) +{ + size_t chan_samp_sz; + audio_format_t format = s->common.get_format(&s->common); + + if (audio_has_proportional_frames(format)) { + chan_samp_sz = audio_bytes_per_sample(format); + return audio_channel_count_from_in_mask(s->common.get_channels(&s->common)) * chan_samp_sz; + } + + return sizeof(int8_t); +} + +/**********************************************************************/ + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +struct audio_module { + struct hw_module_t common; +}; + +struct audio_hw_device { + /** + * Common methods of the audio device. This *must* be the first member of audio_hw_device + * as users of this structure will cast a hw_device_t to audio_hw_device pointer in contexts + * where it's known the hw_device_t references an audio_hw_device. + */ + struct hw_device_t common; + + /** + * used by audio flinger to enumerate what devices are supported by + * each audio_hw_device implementation. + * + * Return value is a bitmask of 1 or more values of audio_devices_t + * + * NOTE: audio HAL implementations starting with + * AUDIO_DEVICE_API_VERSION_2_0 do not implement this function. + * All supported devices should be listed in audio_policy.conf + * file and the audio policy manager must choose the appropriate + * audio module based on information in this file. + */ + uint32_t (*get_supported_devices)(const struct audio_hw_device *dev); + + /** + * check to see if the audio hardware interface has been initialized. + * returns 0 on success, -ENODEV on failure. + */ + int (*init_check)(const struct audio_hw_device *dev); + + /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */ + int (*set_voice_volume)(struct audio_hw_device *dev, float volume); + + /** + * set the audio volume for all audio activities other than voice call. + * Range between 0.0 and 1.0. If any value other than 0 is returned, + * the software mixer will emulate this capability. + */ + int (*set_master_volume)(struct audio_hw_device *dev, float volume); + + /** + * Get the current master volume value for the HAL, if the HAL supports + * master volume control. AudioFlinger will query this value from the + * primary audio HAL when the service starts and use the value for setting + * the initial master volume across all HALs. HALs which do not support + * this method may leave it set to NULL. + */ + int (*get_master_volume)(struct audio_hw_device *dev, float *volume); + + /** + * set_mode is called when the audio mode changes. AUDIO_MODE_NORMAL mode + * is for standard audio playback, AUDIO_MODE_RINGTONE when a ringtone is + * playing, and AUDIO_MODE_IN_CALL when a call is in progress. + */ + int (*set_mode)(struct audio_hw_device *dev, audio_mode_t mode); + + /* mic mute */ + int (*set_mic_mute)(struct audio_hw_device *dev, bool state); + int (*get_mic_mute)(const struct audio_hw_device *dev, bool *state); + + /* set/get global audio parameters */ + int (*set_parameters)(struct audio_hw_device *dev, const char *kv_pairs); + + /* + * Returns a pointer to a heap allocated string. The caller is responsible + * for freeing the memory for it using free(). + */ + char * (*get_parameters)(const struct audio_hw_device *dev, + const char *keys); + + /* Returns audio input buffer size according to parameters passed or + * 0 if one of the parameters is not supported. + * See also get_buffer_size which is for a particular stream. + */ + size_t (*get_input_buffer_size)(const struct audio_hw_device *dev, + const struct audio_config *config); + + /** This method creates and opens the audio hardware output stream. + * The "address" parameter qualifies the "devices" audio device type if needed. + * The format format depends on the device type: + * - Bluetooth devices use the MAC address of the device in the form "00:11:22:AA:BB:CC" + * - USB devices use the ALSA card and device numbers in the form "card=X;device=Y" + * - Other devices may use a number or any other string. + */ + + int (*open_output_stream)(struct audio_hw_device *dev, + audio_io_handle_t handle, + audio_devices_t devices, + audio_output_flags_t flags, + struct audio_config *config, + struct audio_stream_out **stream_out, + const char *address); + + void (*close_output_stream)(struct audio_hw_device *dev, + struct audio_stream_out* stream_out); + + /** This method creates and opens the audio hardware input stream */ + int (*open_input_stream)(struct audio_hw_device *dev, + audio_io_handle_t handle, + audio_devices_t devices, + struct audio_config *config, + struct audio_stream_in **stream_in, + audio_input_flags_t flags, + const char *address, + audio_source_t source); + + void (*close_input_stream)(struct audio_hw_device *dev, + struct audio_stream_in *stream_in); + + /** + * Called by the framework to read available microphones characteristics. + * + * \param[in] dev the hw_device object. + * \param[out] mic_array Pointer to first element on array with microphone info + * \param[out] mic_count When called, this holds the value of the max number of elements + * allowed in the mic_array. The actual number of elements written + * is returned here. + * if mic_count is passed as zero, mic_array will not be populated, + * and mic_count will return the actual number of microphones in the + * system. + * + * \return 0 if the microphone array is successfully filled. + * -ENOSYS if there is an error filling the data + */ + int (*get_microphones)(const struct audio_hw_device *dev, + struct audio_microphone_characteristic_t *mic_array, + size_t *mic_count); + + /** This method dumps the state of the audio hardware */ + int (*dump)(const struct audio_hw_device *dev, int fd); + + /** + * set the audio mute status for all audio activities. If any value other + * than 0 is returned, the software mixer will emulate this capability. + */ + int (*set_master_mute)(struct audio_hw_device *dev, bool mute); + + /** + * Get the current master mute status for the HAL, if the HAL supports + * master mute control. AudioFlinger will query this value from the primary + * audio HAL when the service starts and use the value for setting the + * initial master mute across all HALs. HALs which do not support this + * method may leave it set to NULL. + */ + int (*get_master_mute)(struct audio_hw_device *dev, bool *mute); + + /** + * Routing control + */ + + /* Creates an audio patch between several source and sink ports. + * The handle is allocated by the HAL and should be unique for this + * audio HAL module. */ + int (*create_audio_patch)(struct audio_hw_device *dev, + unsigned int num_sources, + const struct audio_port_config *sources, + unsigned int num_sinks, + const struct audio_port_config *sinks, + audio_patch_handle_t *handle); + + /* Release an audio patch */ + int (*release_audio_patch)(struct audio_hw_device *dev, + audio_patch_handle_t handle); + + /* Fills the list of supported attributes for a given audio port. + * As input, "port" contains the information (type, role, address etc...) + * needed by the HAL to identify the port. + * As output, "port" contains possible attributes (sampling rates, formats, + * channel masks, gain controllers...) for this port. + */ + int (*get_audio_port)(struct audio_hw_device *dev, + struct audio_port *port); + + /* Set audio port configuration */ + int (*set_audio_port_config)(struct audio_hw_device *dev, + const struct audio_port_config *config); + + /** + * Applies an audio effect to an audio device. + * + * @param dev the audio HAL device context. + * @param device identifies the sink or source device the effect must be applied to. + * "device" is the audio_port_handle_t indicated for the device when + * the audio patch connecting that device was created. + * @param effect effect interface handle corresponding to the effect being added. + * @return retval operation completion status. + */ + int (*add_device_effect)(struct audio_hw_device *dev, + audio_port_handle_t device, effect_handle_t effect); + + /** + * Stops applying an audio effect to an audio device. + * + * @param dev the audio HAL device context. + * @param device identifies the sink or source device this effect was applied to. + * "device" is the audio_port_handle_t indicated for the device when + * the audio patch is created. + * @param effect effect interface handle corresponding to the effect being removed. + * @return retval operation completion status. + */ + int (*remove_device_effect)(struct audio_hw_device *dev, + audio_port_handle_t device, effect_handle_t effect); + + /** + * Fills the list of supported attributes for a given audio port. + * As input, "port" contains the information (type, role, address etc...) + * needed by the HAL to identify the port. + * As output, "port" contains possible attributes (sampling rates, formats, + * channel masks, gain controllers...) for this port. The possible attributes + * are saved as audio profiles, which contains audio format and the supported + * sampling rates and channel masks. + */ + int (*get_audio_port_v7)(struct audio_hw_device *dev, + struct audio_port_v7 *port); + + /** + * Called when the state of the connection of an external device has been changed. + * The "port" parameter is only used as input and besides identifying the device + * port, also may contain additional information such as extra audio descriptors. + * + * HAL version 3.2 and higher only. If the HAL does not implement this method, + * it must leave the function entry as null, or return -ENOSYS. In this case + * the framework will use 'set_parameters', which can only pass the device address. + * + * @param dev the audio HAL device context. + * @param port device port identification and extra information. + * @param connected whether the external device is connected. + * @return retval operation completion status. + */ + int (*set_device_connected_state_v7)(struct audio_hw_device *dev, + struct audio_port_v7 *port, + bool connected); +}; +typedef struct audio_hw_device audio_hw_device_t; + +/** convenience API for opening and closing a supported device */ + +static inline int audio_hw_device_open(const struct hw_module_t* module, + struct audio_hw_device** device) +{ + return module->methods->open(module, AUDIO_HARDWARE_INTERFACE, + TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int audio_hw_device_close(struct audio_hw_device* device) +{ + return device->common.close(&device->common); +} + + +__END_DECLS + +#endif // ANDROID_AUDIO_INTERFACE_H diff --git a/include_all/hardware/audio_effect.h b/include_all/hardware/audio_effect.h new file mode 100644 index 00000000..a2809ba6 --- /dev/null +++ b/include_all/hardware/audio_effect.h @@ -0,0 +1,354 @@ +/* + * Copyright (C) 2011 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_AUDIO_EFFECT_H +#define ANDROID_AUDIO_EFFECT_H + +#include <errno.h> +#include <stdint.h> +#include <strings.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <cutils/bitops.h> + +#include <system/audio_effect.h> + + +__BEGIN_DECLS + + +///////////////////////////////////////////////// +// Common Definitions +///////////////////////////////////////////////// + +#define EFFECT_MAKE_API_VERSION(M, m) (((M)<<16) | ((m) & 0xFFFF)) +#define EFFECT_API_VERSION_MAJOR(v) ((v)>>16) +#define EFFECT_API_VERSION_MINOR(v) ((m) & 0xFFFF) + + +///////////////////////////////////////////////// +// Effect control interface +///////////////////////////////////////////////// + +// Effect control interface version 2.0 +#define EFFECT_CONTROL_API_VERSION EFFECT_MAKE_API_VERSION(2,0) + +// Effect control interface structure: effect_interface_s +// The effect control interface is exposed by each effect engine implementation. It consists of +// a set of functions controlling the configuration, activation and process of the engine. +// The functions are grouped in a structure of type effect_interface_s. +// +// Effect control interface handle: effect_handle_t +// The effect_handle_t serves two purposes regarding the implementation of the effect engine: +// - 1 it is the address of a pointer to an effect_interface_s structure where the functions +// of the effect control API for a particular effect are located. +// - 2 it is the address of the context of a particular effect instance. +// A typical implementation in the effect library would define a structure as follows: +// struct effect_module_s { +// const struct effect_interface_s *itfe; +// effect_config_t config; +// effect_context_t context; +// } +// The implementation of EffectCreate() function would then allocate a structure of this +// type and return its address as effect_handle_t +typedef struct effect_interface_s **effect_handle_t; + +// Effect control interface definition +struct effect_interface_s { + //////////////////////////////////////////////////////////////////////////////// + // + // Function: process + // + // Description: Effect process function. Takes input samples as specified + // (count and location) in input buffer descriptor and output processed + // samples as specified in output buffer descriptor. If the buffer descriptor + // is not specified the function must use either the buffer or the + // buffer provider function installed by the EFFECT_CMD_SET_CONFIG command. + // The effect framework will call the process() function after the EFFECT_CMD_ENABLE + // command is received and until the EFFECT_CMD_DISABLE is received. When the engine + // receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully + // and when done indicate that it is OK to stop calling the process() function by + // returning the -ENODATA status. + // + // NOTE: the process() function implementation should be "real-time safe" that is + // it should not perform blocking calls: malloc/free, sleep, read/write/open/close, + // pthread_cond_wait/pthread_mutex_lock... + // + // Input: + // self: handle to the effect interface this function + // is called on. + // inBuffer: buffer descriptor indicating where to read samples to process. + // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. + // + // outBuffer: buffer descriptor indicating where to write processed samples. + // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. + // + // Output: + // returned value: 0 successful operation + // -ENODATA the engine has finished the disable phase and the framework + // can stop calling process() + // -EINVAL invalid interface handle or + // invalid input/output buffer description + //////////////////////////////////////////////////////////////////////////////// + int32_t (*process)(effect_handle_t self, + audio_buffer_t *inBuffer, + audio_buffer_t *outBuffer); + //////////////////////////////////////////////////////////////////////////////// + // + // Function: command + // + // Description: Send a command and receive a response to/from effect engine. + // + // Input: + // self: handle to the effect interface this function + // is called on. + // cmdCode: command code: the command can be a standardized command defined in + // effect_command_e (see below) or a proprietary command. + // cmdSize: size of command in bytes + // pCmdData: pointer to command data + // pReplyData: pointer to reply data + // + // Input/Output: + // replySize: maximum size of reply data as input + // actual size of reply data as output + // + // Output: + // returned value: 0 successful operation + // -EINVAL invalid interface handle or + // invalid command/reply size or format according to + // command code + // The return code should be restricted to indicate problems related to this API + // specification. Status related to the execution of a particular command should be + // indicated as part of the reply field. + // + // *pReplyData updated with command response + // + //////////////////////////////////////////////////////////////////////////////// + int32_t (*command)(effect_handle_t self, + uint32_t cmdCode, + uint32_t cmdSize, + void *pCmdData, + uint32_t *replySize, + void *pReplyData); + //////////////////////////////////////////////////////////////////////////////// + // + // Function: get_descriptor + // + // Description: Returns the effect descriptor + // + // Input: + // self: handle to the effect interface this function + // is called on. + // + // Input/Output: + // pDescriptor: address where to return the effect descriptor. + // + // Output: + // returned value: 0 successful operation. + // -EINVAL invalid interface handle or invalid pDescriptor + // *pDescriptor: updated with the effect descriptor. + // + //////////////////////////////////////////////////////////////////////////////// + int32_t (*get_descriptor)(effect_handle_t self, + effect_descriptor_t *pDescriptor); + //////////////////////////////////////////////////////////////////////////////// + // + // Function: process_reverse + // + // Description: Process reverse stream function. This function is used to pass + // a reference stream to the effect engine. If the engine does not need a reference + // stream, this function pointer can be set to NULL. + // This function would typically implemented by an Echo Canceler. + // + // Input: + // self: handle to the effect interface this function + // is called on. + // inBuffer: buffer descriptor indicating where to read samples to process. + // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. + // + // outBuffer: buffer descriptor indicating where to write processed samples. + // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. + // If the buffer and buffer provider in the configuration received by + // EFFECT_CMD_SET_CONFIG_REVERSE are also NULL, do not return modified reverse + // stream data + // + // Output: + // returned value: 0 successful operation + // -ENODATA the engine has finished the disable phase and the framework + // can stop calling process_reverse() + // -EINVAL invalid interface handle or + // invalid input/output buffer description + //////////////////////////////////////////////////////////////////////////////// + int32_t (*process_reverse)(effect_handle_t self, + audio_buffer_t *inBuffer, + audio_buffer_t *outBuffer); +}; + +///////////////////////////////////////////////// +// Effect library interface +///////////////////////////////////////////////// + +// Effect library interface version 3.0 +// Note that EffectsFactory.c only checks the major version component, so changes to the minor +// number can only be used for fully backwards compatible changes +#define EFFECT_LIBRARY_API_VERSION EFFECT_MAKE_API_VERSION(3,0) +#define EFFECT_LIBRARY_API_VERSION_3_0 EFFECT_MAKE_API_VERSION(3,0) +#define EFFECT_LIBRARY_API_VERSION_3_1 EFFECT_MAKE_API_VERSION(3,1) + +#define AUDIO_EFFECT_LIBRARY_TAG ((('A') << 24) | (('E') << 16) | (('L') << 8) | ('T')) + +// Every effect library must have a data structure named AUDIO_EFFECT_LIBRARY_INFO_SYM +// and the fields of this data structure must begin with audio_effect_library_t + +typedef struct audio_effect_library_s { + // tag must be initialized to AUDIO_EFFECT_LIBRARY_TAG + uint32_t tag; + // Version of the effect library API : 0xMMMMmmmm MMMM: Major, mmmm: minor + uint32_t version; + // Name of this library + const char *name; + // Author/owner/implementor of the library + const char *implementor; + + //////////////////////////////////////////////////////////////////////////////// + // + // Function: create_effect + // + // Description: Creates an effect engine of the specified implementation uuid and + // returns an effect control interface on this engine. The function will allocate the + // resources for an instance of the requested effect engine and return + // a handle on the effect control interface. + // + // Input: + // uuid: pointer to the effect uuid. + // sessionId: audio session to which this effect instance will be attached. + // All effects created with the same session ID are connected in series and process + // the same signal stream. Knowing that two effects are part of the same effect + // chain can help the library implement some kind of optimizations. + // ioId: identifies the output or input stream this effect is directed to in + // audio HAL. + // For future use especially with tunneled HW accelerated effects + // + // Input/Output: + // pHandle: address where to return the effect interface handle. + // + // Output: + // returned value: 0 successful operation. + // -ENODEV library failed to initialize + // -EINVAL invalid pEffectUuid or pHandle + // -ENOENT no effect with this uuid found + // *pHandle: updated with the effect interface handle. + // + //////////////////////////////////////////////////////////////////////////////// + int32_t (*create_effect)(const effect_uuid_t *uuid, + int32_t sessionId, + int32_t ioId, + effect_handle_t *pHandle); + + //////////////////////////////////////////////////////////////////////////////// + // + // Function: release_effect + // + // Description: Releases the effect engine whose handle is given as argument. + // All resources allocated to this particular instance of the effect are + // released. + // + // Input: + // handle: handle on the effect interface to be released. + // + // Output: + // returned value: 0 successful operation. + // -ENODEV library failed to initialize + // -EINVAL invalid interface handle + // + //////////////////////////////////////////////////////////////////////////////// + int32_t (*release_effect)(effect_handle_t handle); + + //////////////////////////////////////////////////////////////////////////////// + // + // Function: get_descriptor + // + // Description: Returns the descriptor of the effect engine which implementation UUID is + // given as argument. + // + // Input/Output: + // uuid: pointer to the effect uuid. + // pDescriptor: address where to return the effect descriptor. + // + // Output: + // returned value: 0 successful operation. + // -ENODEV library failed to initialize + // -EINVAL invalid pDescriptor or uuid + // *pDescriptor: updated with the effect descriptor. + // + //////////////////////////////////////////////////////////////////////////////// + int32_t (*get_descriptor)(const effect_uuid_t *uuid, + effect_descriptor_t *pDescriptor); + + //////////////////////////////////////////////////////////////////////////////// + // + // Function: create_effect_3_1 + // + // Description: Creates an effect engine of the specified implementation uuid and + // returns an effect control interface on this engine. The function will allocate the + // resources for an instance of the requested effect engine and return + // a handle on the effect control interface. + // + // Input: + // uuid: pointer to the effect uuid. + // sessionId: audio session to which this effect instance will be attached. + // All effects created with the same session ID are connected in series and process + // the same signal stream. Knowing that two effects are part of the same effect + // chain can help the library implement some kind of optimizations. + // ioId: identifies the output or input stream this effect is directed to in + // audio HAL. + // For future use especially with tunneled HW accelerated effects + // deviceId: identifies the sink or source device this effect is directed to in + // audio HAL. Must be specified if sessionId is AUDIO_SESSION_DEVICE and is + // ignored otherwise. + // deviceId is the audio_port_handle_t used for the device when the audio + // patch is created at the audio HAL. + // + // Input/Output: + // pHandle: address where to return the effect interface handle. + // + // Output: + // returned value: 0 successful operation. + // -ENODEV library failed to initialize + // -EINVAL invalid pEffectUuid or pHandle + // -ENOENT no effect with this uuid found + // *pHandle: updated with the effect interface handle. + // + //////////////////////////////////////////////////////////////////////////////// + int32_t (*create_effect_3_1)(const effect_uuid_t *uuid, + int32_t sessionId, + int32_t ioId, + int32_t deviceId, + effect_handle_t *pHandle); + +} audio_effect_library_t; + +// Name of the hal_module_info +#define AUDIO_EFFECT_LIBRARY_INFO_SYM AELI + +// Name of the hal_module_info as a string +#define AUDIO_EFFECT_LIBRARY_INFO_SYM_AS_STR "AELI" + +__END_DECLS + +#endif // ANDROID_AUDIO_EFFECT_H diff --git a/include_all/hardware/audio_policy.h b/include_all/hardware/audio_policy.h new file mode 100644 index 00000000..bacb1e55 --- /dev/null +++ b/include_all/hardware/audio_policy.h @@ -0,0 +1,457 @@ +/* + * Copyright (C) 2011 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_AUDIO_POLICY_INTERFACE_H +#define ANDROID_AUDIO_POLICY_INTERFACE_H + +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <hardware/hardware.h> + +#include <system/audio.h> +#include <system/audio_policy.h> + +__BEGIN_DECLS + +/** + * The id of this module + */ +#define AUDIO_POLICY_HARDWARE_MODULE_ID "audio_policy" + +/** + * Name of the audio devices to open + */ +#define AUDIO_POLICY_INTERFACE "policy" + +/* ---------------------------------------------------------------------------- */ + +/* + * The audio_policy and audio_policy_service_ops structs define the + * communication interfaces between the platform specific audio policy manager + * and Android generic audio policy manager. + * The platform specific audio policy manager must implement methods of the + * audio_policy struct. + * This implementation makes use of the audio_policy_service_ops to control + * the activity and configuration of audio input and output streams. + * + * The platform specific audio policy manager is in charge of the audio + * routing and volume control policies for a given platform. + * The main roles of this module are: + * - keep track of current system state (removable device connections, phone + * state, user requests...). + * System state changes and user actions are notified to audio policy + * manager with methods of the audio_policy. + * + * - process get_output() queries received when AudioTrack objects are + * created: Those queries return a handler on an output that has been + * selected, configured and opened by the audio policy manager and that + * must be used by the AudioTrack when registering to the AudioFlinger + * with the createTrack() method. + * When the AudioTrack object is released, a release_output() query + * is received and the audio policy manager can decide to close or + * reconfigure the output depending on other streams using this output and + * current system state. + * + * - similarly process get_input() and release_input() queries received from + * AudioRecord objects and configure audio inputs. + * - process volume control requests: the stream volume is converted from + * an index value (received from UI) to a float value applicable to each + * output as a function of platform specific settings and current output + * route (destination device). It also make sure that streams are not + * muted if not allowed (e.g. camera shutter sound in some countries). + */ + +/* XXX: this should be defined OUTSIDE of frameworks/base */ +struct effect_descriptor_s; + +struct audio_policy { + /* + * configuration functions + */ + + /* indicate a change in device connection status */ + int (*set_device_connection_state)(struct audio_policy *pol, + audio_devices_t device, + audio_policy_dev_state_t state, + const char *device_address); + + /* retrieve a device connection status */ + audio_policy_dev_state_t (*get_device_connection_state)( + const struct audio_policy *pol, + audio_devices_t device, + const char *device_address); + + /* indicate a change in phone state. Valid phones states are defined + * by audio_mode_t */ + void (*set_phone_state)(struct audio_policy *pol, audio_mode_t state); + + /* deprecated, never called (was "indicate a change in ringer mode") */ + void (*set_ringer_mode)(struct audio_policy *pol, uint32_t mode, + uint32_t mask); + + /* force using a specific device category for the specified usage */ + void (*set_force_use)(struct audio_policy *pol, + audio_policy_force_use_t usage, + audio_policy_forced_cfg_t config); + + /* retrieve current device category forced for a given usage */ + audio_policy_forced_cfg_t (*get_force_use)(const struct audio_policy *pol, + audio_policy_force_use_t usage); + + /* if can_mute is true, then audio streams that are marked ENFORCED_AUDIBLE + * can still be muted. */ + void (*set_can_mute_enforced_audible)(struct audio_policy *pol, + bool can_mute); + + /* check proper initialization */ + int (*init_check)(const struct audio_policy *pol); + + /* + * Audio routing query functions + */ + + /* request an output appropriate for playback of the supplied stream type and + * parameters */ + audio_io_handle_t (*get_output)(struct audio_policy *pol, + audio_stream_type_t stream, + uint32_t samplingRate, + audio_format_t format, + audio_channel_mask_t channelMask, + audio_output_flags_t flags, + const audio_offload_info_t *offloadInfo); + + /* indicates to the audio policy manager that the output starts being used + * by corresponding stream. */ + int (*start_output)(struct audio_policy *pol, + audio_io_handle_t output, + audio_stream_type_t stream, + audio_session_t session); + + /* indicates to the audio policy manager that the output stops being used + * by corresponding stream. */ + int (*stop_output)(struct audio_policy *pol, + audio_io_handle_t output, + audio_stream_type_t stream, + audio_session_t session); + + /* releases the output. */ + void (*release_output)(struct audio_policy *pol, audio_io_handle_t output); + + /* request an input appropriate for record from the supplied device with + * supplied parameters. */ + audio_io_handle_t (*get_input)(struct audio_policy *pol, audio_source_t inputSource, + uint32_t samplingRate, + audio_format_t format, + audio_channel_mask_t channelMask, + audio_in_acoustics_t acoustics); + + /* indicates to the audio policy manager that the input starts being used */ + int (*start_input)(struct audio_policy *pol, audio_io_handle_t input); + + /* indicates to the audio policy manager that the input stops being used. */ + int (*stop_input)(struct audio_policy *pol, audio_io_handle_t input); + + /* releases the input. */ + void (*release_input)(struct audio_policy *pol, audio_io_handle_t input); + + /* + * volume control functions + */ + + /* initialises stream volume conversion parameters by specifying volume + * index range. The index range for each stream is defined by AudioService. */ + void (*init_stream_volume)(struct audio_policy *pol, + audio_stream_type_t stream, + int index_min, + int index_max); + + /* sets the new stream volume at a level corresponding to the supplied + * index. The index is within the range specified by init_stream_volume() */ + int (*set_stream_volume_index)(struct audio_policy *pol, + audio_stream_type_t stream, + int index); + + /* retrieve current volume index for the specified stream */ + int (*get_stream_volume_index)(const struct audio_policy *pol, + audio_stream_type_t stream, + int *index); + + /* sets the new stream volume at a level corresponding to the supplied + * index for the specified device. + * The index is within the range specified by init_stream_volume() */ + int (*set_stream_volume_index_for_device)(struct audio_policy *pol, + audio_stream_type_t stream, + int index, + audio_devices_t device); + + /* retrieve current volume index for the specified stream for the specified device */ + int (*get_stream_volume_index_for_device)(const struct audio_policy *pol, + audio_stream_type_t stream, + int *index, + audio_devices_t device); + + /* return the strategy corresponding to a given stream type */ + uint32_t (*get_strategy_for_stream)(const struct audio_policy *pol, + audio_stream_type_t stream); + + /* return the enabled output devices for the given stream type */ + audio_devices_t (*get_devices_for_stream)(const struct audio_policy *pol, + audio_stream_type_t stream); + + /* Audio effect management */ + audio_io_handle_t (*get_output_for_effect)(struct audio_policy *pol, + const struct effect_descriptor_s *desc); + + int (*register_effect)(struct audio_policy *pol, + const struct effect_descriptor_s *desc, + audio_io_handle_t output, + uint32_t strategy, + audio_session_t session, + int id); + + int (*unregister_effect)(struct audio_policy *pol, int id); + + int (*set_effect_enabled)(struct audio_policy *pol, int id, bool enabled); + + bool (*is_stream_active)(const struct audio_policy *pol, + audio_stream_type_t stream, + uint32_t in_past_ms); + + bool (*is_stream_active_remotely)(const struct audio_policy *pol, + audio_stream_type_t stream, + uint32_t in_past_ms); + + bool (*is_source_active)(const struct audio_policy *pol, + audio_source_t source); + + /* dump state */ + int (*dump)(const struct audio_policy *pol, int fd); + + /* check if offload is possible for given sample rate, bitrate, duration, ... */ + bool (*is_offload_supported)(const struct audio_policy *pol, + const audio_offload_info_t *info); +}; + + +struct audio_policy_service_ops { + /* + * Audio output Control functions + */ + + /* Opens an audio output with the requested parameters. + * + * The parameter values can indicate to use the default values in case the + * audio policy manager has no specific requirements for the output being + * opened. + * + * When the function returns, the parameter values reflect the actual + * values used by the audio hardware output stream. + * + * The audio policy manager can check if the proposed parameters are + * suitable or not and act accordingly. + */ + audio_io_handle_t (*open_output)(void *service, + audio_devices_t *pDevices, + uint32_t *pSamplingRate, + audio_format_t *pFormat, + audio_channel_mask_t *pChannelMask, + uint32_t *pLatencyMs, + audio_output_flags_t flags); + + /* creates a special output that is duplicated to the two outputs passed as + * arguments. The duplication is performed by + * a special mixer thread in the AudioFlinger. + */ + audio_io_handle_t (*open_duplicate_output)(void *service, + audio_io_handle_t output1, + audio_io_handle_t output2); + + /* closes the output stream */ + int (*close_output)(void *service, audio_io_handle_t output); + + /* suspends the output. + * + * When an output is suspended, the corresponding audio hardware output + * stream is placed in standby and the AudioTracks attached to the mixer + * thread are still processed but the output mix is discarded. + */ + int (*suspend_output)(void *service, audio_io_handle_t output); + + /* restores a suspended output. */ + int (*restore_output)(void *service, audio_io_handle_t output); + + /* */ + /* Audio input Control functions */ + /* */ + + /* opens an audio input + * deprecated - new implementations should use open_input_on_module, + * and the acoustics parameter is ignored + */ + audio_io_handle_t (*open_input)(void *service, + audio_devices_t *pDevices, + uint32_t *pSamplingRate, + audio_format_t *pFormat, + audio_channel_mask_t *pChannelMask, + audio_in_acoustics_t acoustics); + + /* closes an audio input */ + int (*close_input)(void *service, audio_io_handle_t input); + + /* */ + /* misc control functions */ + /* */ + + /* set a stream volume for a particular output. + * + * For the same user setting, a given stream type can have different + * volumes for each output (destination device) it is attached to. + */ + int (*set_stream_volume)(void *service, + audio_stream_type_t stream, + float volume, + audio_io_handle_t output, + int delay_ms); + + /* invalidate a stream type, causing a reroute to an unspecified new output */ + int (*invalidate_stream)(void *service, + audio_stream_type_t stream); + + /* function enabling to send proprietary informations directly from audio + * policy manager to audio hardware interface. */ + void (*set_parameters)(void *service, + audio_io_handle_t io_handle, + const char *kv_pairs, + int delay_ms); + + /* function enabling to receive proprietary informations directly from + * audio hardware interface to audio policy manager. + * + * Returns a pointer to a heap allocated string. The caller is responsible + * for freeing the memory for it using free(). + */ + + char * (*get_parameters)(void *service, audio_io_handle_t io_handle, + const char *keys); + + /* request the playback of a tone on the specified stream. + * used for instance to replace notification sounds when playing over a + * telephony device during a phone call. + */ + int (*start_tone)(void *service, + audio_policy_tone_t tone, + audio_stream_type_t stream); + + int (*stop_tone)(void *service); + + /* set down link audio volume. */ + int (*set_voice_volume)(void *service, + float volume, + int delay_ms); + + /* move effect to the specified output */ + int (*move_effects)(void *service, + audio_session_t session, + audio_io_handle_t src_output, + audio_io_handle_t dst_output); + + /* loads an audio hw module. + * + * The module name passed is the base name of the HW module library, e.g "primary" or "a2dp". + * The function returns a handle on the module that will be used to specify a particular + * module when calling open_output_on_module() or open_input_on_module() + */ + audio_module_handle_t (*load_hw_module)(void *service, + const char *name); + + /* Opens an audio output on a particular HW module. + * + * Same as open_output() but specifying a specific HW module on which the output must be opened. + */ + audio_io_handle_t (*open_output_on_module)(void *service, + audio_module_handle_t module, + audio_devices_t *pDevices, + uint32_t *pSamplingRate, + audio_format_t *pFormat, + audio_channel_mask_t *pChannelMask, + uint32_t *pLatencyMs, + audio_output_flags_t flags, + const audio_offload_info_t *offloadInfo); + + /* Opens an audio input on a particular HW module. + * + * Same as open_input() but specifying a specific HW module on which the input must be opened. + * Also removed deprecated acoustics parameter + */ + audio_io_handle_t (*open_input_on_module)(void *service, + audio_module_handle_t module, + audio_devices_t *pDevices, + uint32_t *pSamplingRate, + audio_format_t *pFormat, + audio_channel_mask_t *pChannelMask); + +}; + +/**********************************************************************/ + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +typedef struct audio_policy_module { + struct hw_module_t common; +} audio_policy_module_t; + +struct audio_policy_device { + /** + * Common methods of the audio policy device. This *must* be the first member of + * audio_policy_device as users of this structure will cast a hw_device_t to + * audio_policy_device pointer in contexts where it's known the hw_device_t references an + * audio_policy_device. + */ + struct hw_device_t common; + + int (*create_audio_policy)(const struct audio_policy_device *device, + struct audio_policy_service_ops *aps_ops, + void *service, + struct audio_policy **ap); + + int (*destroy_audio_policy)(const struct audio_policy_device *device, + struct audio_policy *ap); +}; + +/** convenience API for opening and closing a supported device */ + +static inline int audio_policy_dev_open(const hw_module_t* module, + struct audio_policy_device** device) +{ + return module->methods->open(module, AUDIO_POLICY_INTERFACE, + (hw_device_t**)device); +} + +static inline int audio_policy_dev_close(struct audio_policy_device* device) +{ + return device->common.close(&device->common); +} + + +__END_DECLS + +#endif // ANDROID_AUDIO_POLICY_INTERFACE_H diff --git a/include_all/hardware/bluetooth.h b/include_all/hardware/bluetooth.h new file mode 100644 index 00000000..95a0b6e3 --- /dev/null +++ b/include_all/hardware/bluetooth.h @@ -0,0 +1,598 @@ +/* + * Copyright (C) 2012 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_INCLUDE_BLUETOOTH_H +#define ANDROID_INCLUDE_BLUETOOTH_H + +#include <stdbool.h> +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <bluetooth/uuid.h> +#include <raw_address.h> + +__BEGIN_DECLS + +#define BLUETOOTH_INTERFACE_STRING "bluetoothInterface" + +/** Bluetooth profile interface IDs */ + +#define BT_PROFILE_HANDSFREE_ID "handsfree" +#define BT_PROFILE_HANDSFREE_CLIENT_ID "handsfree_client" +#define BT_PROFILE_ADVANCED_AUDIO_ID "a2dp" +#define BT_PROFILE_ADVANCED_AUDIO_SINK_ID "a2dp_sink" +#define BT_PROFILE_HEALTH_ID "health" +#define BT_PROFILE_SOCKETS_ID "socket" +#define BT_PROFILE_HIDHOST_ID "hidhost" +#define BT_PROFILE_HIDDEV_ID "hiddev" +#define BT_PROFILE_PAN_ID "pan" +#define BT_PROFILE_MAP_CLIENT_ID "map_client" +#define BT_PROFILE_SDP_CLIENT_ID "sdp" +#define BT_PROFILE_GATT_ID "gatt" +#define BT_PROFILE_AV_RC_ID "avrcp" +#define BT_PROFILE_AV_RC_CTRL_ID "avrcp_ctrl" + +/** Bluetooth test interface IDs */ +#define BT_TEST_INTERFACE_MCAP_ID "mcap_test" + +/** Bluetooth Device Name */ +typedef struct { + uint8_t name[249]; +} __attribute__((packed))bt_bdname_t; + +/** Bluetooth Adapter Visibility Modes*/ +typedef enum { + BT_SCAN_MODE_NONE, + BT_SCAN_MODE_CONNECTABLE, + BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE +} bt_scan_mode_t; + +/** Bluetooth Adapter State */ +typedef enum { + BT_STATE_OFF, + BT_STATE_ON +} bt_state_t; + +/** Bluetooth Error Status */ +/** We need to build on this */ + +typedef enum { + BT_STATUS_SUCCESS, + BT_STATUS_FAIL, + BT_STATUS_NOT_READY, + BT_STATUS_NOMEM, + BT_STATUS_BUSY, + BT_STATUS_DONE, /* request already completed */ + BT_STATUS_UNSUPPORTED, + BT_STATUS_PARM_INVALID, + BT_STATUS_UNHANDLED, + BT_STATUS_AUTH_FAILURE, + BT_STATUS_RMT_DEV_DOWN, + BT_STATUS_AUTH_REJECTED, + BT_STATUS_JNI_ENVIRONMENT_ERROR, + BT_STATUS_JNI_THREAD_ATTACH_ERROR, + BT_STATUS_WAKELOCK_ERROR +} bt_status_t; + +/** Bluetooth PinKey Code */ +typedef struct { + uint8_t pin[16]; +} __attribute__((packed))bt_pin_code_t; + +typedef struct { + uint8_t status; + uint8_t ctrl_state; /* stack reported state */ + uint64_t tx_time; /* in ms */ + uint64_t rx_time; /* in ms */ + uint64_t idle_time; /* in ms */ + uint64_t energy_used; /* a product of mA, V and ms */ +} __attribute__((packed))bt_activity_energy_info; + +typedef struct { + int32_t app_uid; + uint64_t tx_bytes; + uint64_t rx_bytes; +} __attribute__((packed))bt_uid_traffic_t; + +/** Bluetooth Adapter Discovery state */ +typedef enum { + BT_DISCOVERY_STOPPED, + BT_DISCOVERY_STARTED +} bt_discovery_state_t; + +/** Bluetooth ACL connection state */ +typedef enum { + BT_ACL_STATE_CONNECTED, + BT_ACL_STATE_DISCONNECTED +} bt_acl_state_t; + +/** Bluetooth SDP service record */ +typedef struct +{ + bluetooth::Uuid uuid; + uint16_t channel; + char name[256]; // what's the maximum length +} bt_service_record_t; + + +/** Bluetooth Remote Version info */ +typedef struct +{ + int version; + int sub_ver; + int manufacturer; +} bt_remote_version_t; + +typedef struct +{ + uint16_t version_supported; + uint8_t local_privacy_enabled; + uint8_t max_adv_instance; + uint8_t rpa_offload_supported; + uint8_t max_irk_list_size; + uint8_t max_adv_filter_supported; + uint8_t activity_energy_info_supported; + uint16_t scan_result_storage_size; + uint16_t total_trackable_advertisers; + bool extended_scan_support; + bool debug_logging_supported; + bool le_2m_phy_supported; + bool le_coded_phy_supported; + bool le_extended_advertising_supported; + bool le_periodic_advertising_supported; + uint16_t le_maximum_advertising_data_length; +}bt_local_le_features_t; + +/* Bluetooth Adapter and Remote Device property types */ +typedef enum { + /* Properties common to both adapter and remote device */ + /** + * Description - Bluetooth Device Name + * Access mode - Adapter name can be GET/SET. Remote device can be GET + * Data type - bt_bdname_t + */ + BT_PROPERTY_BDNAME = 0x1, + /** + * Description - Bluetooth Device Address + * Access mode - Only GET. + * Data type - RawAddress + */ + BT_PROPERTY_BDADDR, + /** + * Description - Bluetooth Service 128-bit UUIDs + * Access mode - Only GET. + * Data type - Array of bluetooth::Uuid (Array size inferred from property + * length). + */ + BT_PROPERTY_UUIDS, + /** + * Description - Bluetooth Class of Device as found in Assigned Numbers + * Access mode - Only GET. + * Data type - uint32_t. + */ + BT_PROPERTY_CLASS_OF_DEVICE, + /** + * Description - Device Type - BREDR, BLE or DUAL Mode + * Access mode - Only GET. + * Data type - bt_device_type_t + */ + BT_PROPERTY_TYPE_OF_DEVICE, + /** + * Description - Bluetooth Service Record + * Access mode - Only GET. + * Data type - bt_service_record_t + */ + BT_PROPERTY_SERVICE_RECORD, + + /* Properties unique to adapter */ + /** + * Description - Bluetooth Adapter scan mode + * Access mode - GET and SET + * Data type - bt_scan_mode_t. + */ + BT_PROPERTY_ADAPTER_SCAN_MODE, + /** + * Description - List of bonded devices + * Access mode - Only GET. + * Data type - Array of RawAddress of the bonded remote devices + * (Array size inferred from property length). + */ + BT_PROPERTY_ADAPTER_BONDED_DEVICES, + /** + * Description - Bluetooth Adapter Discovery timeout (in seconds) + * Access mode - GET and SET + * Data type - uint32_t + */ + BT_PROPERTY_ADAPTER_DISCOVERY_TIMEOUT, + + /* Properties unique to remote device */ + /** + * Description - User defined friendly name of the remote device + * Access mode - GET and SET + * Data type - bt_bdname_t. + */ + BT_PROPERTY_REMOTE_FRIENDLY_NAME, + /** + * Description - RSSI value of the inquired remote device + * Access mode - Only GET. + * Data type - int32_t. + */ + BT_PROPERTY_REMOTE_RSSI, + /** + * Description - Remote version info + * Access mode - SET/GET. + * Data type - bt_remote_version_t. + */ + + BT_PROPERTY_REMOTE_VERSION_INFO, + + /** + * Description - Local LE features + * Access mode - GET. + * Data type - bt_local_le_features_t. + */ + BT_PROPERTY_LOCAL_LE_FEATURES, + + BT_PROPERTY_REMOTE_DEVICE_TIMESTAMP = 0xFF, +} bt_property_type_t; + +/** Bluetooth Adapter Property data structure */ +typedef struct +{ + bt_property_type_t type; + int len; + void *val; +} bt_property_t; + +/** Represents the actual Out of Band data itself */ +typedef struct { + // Both + bool is_valid = false; /* Default to invalid data; force caller to verify */ + uint8_t address[7]; /* Bluetooth Device Address (6) plus Address Type (1) */ + uint8_t c[16]; /* Simple Pairing Hash C-192/256 (Classic or LE) */ + uint8_t r[16]; /* Simple Pairing Randomizer R-192/256 (Classic or LE) */ + uint8_t device_name[256]; /* Name of the device */ + + // Classic + uint8_t oob_data_length[2]; /* Classic only data Length. Value includes this + in length */ + uint8_t class_of_device[2]; /* Class of Device (Classic or LE) */ + + // LE + uint8_t le_device_role; /* Supported and preferred role of device */ + uint8_t sm_tk[16]; /* Security Manager TK Value (LE Only) */ + uint8_t le_flags; /* LE Flags for discoverability and features */ + uint8_t le_appearance[2]; /* For the appearance of the device */ +} bt_oob_data_t; + + +/** Bluetooth Device Type */ +typedef enum { + BT_DEVICE_DEVTYPE_BREDR = 0x1, + BT_DEVICE_DEVTYPE_BLE, + BT_DEVICE_DEVTYPE_DUAL +} bt_device_type_t; +/** Bluetooth Bond state */ +typedef enum { + BT_BOND_STATE_NONE, + BT_BOND_STATE_BONDING, + BT_BOND_STATE_BONDED +} bt_bond_state_t; + +/** Bluetooth SSP Bonding Variant */ +typedef enum { + BT_SSP_VARIANT_PASSKEY_CONFIRMATION, + BT_SSP_VARIANT_PASSKEY_ENTRY, + BT_SSP_VARIANT_CONSENT, + BT_SSP_VARIANT_PASSKEY_NOTIFICATION +} bt_ssp_variant_t; + +#define BT_MAX_NUM_UUIDS 32 + +/** Bluetooth Interface callbacks */ + +/** Bluetooth Enable/Disable Callback. */ +typedef void (*adapter_state_changed_callback)(bt_state_t state); + +/** GET/SET Adapter Properties callback */ +/* TODO: For the GET/SET property APIs/callbacks, we may need a session + * identifier to associate the call with the callback. This would be needed + * whenever more than one simultaneous instance of the same adapter_type + * is get/set. + * + * If this is going to be handled in the Java framework, then we do not need + * to manage sessions here. + */ +typedef void (*adapter_properties_callback)(bt_status_t status, + int num_properties, + bt_property_t *properties); + +/** GET/SET Remote Device Properties callback */ +/** TODO: For remote device properties, do not see a need to get/set + * multiple properties - num_properties shall be 1 + */ +typedef void (*remote_device_properties_callback)(bt_status_t status, + RawAddress *bd_addr, + int num_properties, + bt_property_t *properties); + +/** New device discovered callback */ +/** If EIR data is not present, then BD_NAME and RSSI shall be NULL and -1 + * respectively */ +typedef void (*device_found_callback)(int num_properties, + bt_property_t *properties); + +/** Discovery state changed callback */ +typedef void (*discovery_state_changed_callback)(bt_discovery_state_t state); + +/** Bluetooth Legacy PinKey Request callback */ +typedef void (*pin_request_callback)(RawAddress *remote_bd_addr, + bt_bdname_t *bd_name, uint32_t cod, bool min_16_digit); + +/** Bluetooth SSP Request callback - Just Works & Numeric Comparison*/ +/** pass_key - Shall be 0 for BT_SSP_PAIRING_VARIANT_CONSENT & + * BT_SSP_PAIRING_PASSKEY_ENTRY */ +/* TODO: Passkey request callback shall not be needed for devices with display + * capability. We still need support this in the stack for completeness */ +typedef void (*ssp_request_callback)(RawAddress *remote_bd_addr, + bt_bdname_t *bd_name, + uint32_t cod, + bt_ssp_variant_t pairing_variant, + uint32_t pass_key); + +/** Bluetooth Bond state changed callback */ +/* Invoked in response to create_bond, cancel_bond or remove_bond */ +typedef void (*bond_state_changed_callback)(bt_status_t status, + RawAddress *remote_bd_addr, + bt_bond_state_t state); + +/** Bluetooth ACL connection state changed callback */ +typedef void (*acl_state_changed_callback)(bt_status_t status, RawAddress *remote_bd_addr, + bt_acl_state_t state); + +typedef enum { + ASSOCIATE_JVM, + DISASSOCIATE_JVM +} bt_cb_thread_evt; + +/** Thread Associate/Disassociate JVM Callback */ +/* Callback that is invoked by the callback thread to allow upper layer to attach/detach to/from + * the JVM */ +typedef void (*callback_thread_event)(bt_cb_thread_evt evt); + +/** Bluetooth Test Mode Callback */ +/* Receive any HCI event from controller. Must be in DUT Mode for this callback to be received */ +typedef void (*dut_mode_recv_callback)(uint16_t opcode, uint8_t *buf, uint8_t len); + +/* LE Test mode callbacks +* This callback shall be invoked whenever the le_tx_test, le_rx_test or le_test_end is invoked +* The num_packets is valid only for le_test_end command */ +typedef void (*le_test_mode_callback)(bt_status_t status, uint16_t num_packets); + +/** Callback invoked when energy details are obtained */ +/* Ctrl_state-Current controller state-Active-1,scan-2,or idle-3 state as defined by HCI spec. + * If the ctrl_state value is 0, it means the API call failed + * Time values-In milliseconds as returned by the controller + * Energy used-Value as returned by the controller + * Status-Provides the status of the read_energy_info API call + * uid_data provides an array of bt_uid_traffic_t, where the array is terminated by an element with + * app_uid set to -1. + */ +typedef void (*energy_info_callback)(bt_activity_energy_info *energy_info, + bt_uid_traffic_t *uid_data); + +/** TODO: Add callbacks for Link Up/Down and other generic + * notifications/callbacks */ + +/** Bluetooth DM callback structure. */ +typedef struct { + /** set to sizeof(bt_callbacks_t) */ + size_t size; + adapter_state_changed_callback adapter_state_changed_cb; + adapter_properties_callback adapter_properties_cb; + remote_device_properties_callback remote_device_properties_cb; + device_found_callback device_found_cb; + discovery_state_changed_callback discovery_state_changed_cb; + pin_request_callback pin_request_cb; + ssp_request_callback ssp_request_cb; + bond_state_changed_callback bond_state_changed_cb; + acl_state_changed_callback acl_state_changed_cb; + callback_thread_event thread_evt_cb; + dut_mode_recv_callback dut_mode_recv_cb; + le_test_mode_callback le_test_mode_cb; + energy_info_callback energy_info_cb; +} bt_callbacks_t; + +typedef void (*alarm_cb)(void *data); +typedef bool (*set_wake_alarm_callout)(uint64_t delay_millis, bool should_wake, alarm_cb cb, void *data); +typedef int (*acquire_wake_lock_callout)(const char *lock_name); +typedef int (*release_wake_lock_callout)(const char *lock_name); + +/** The set of functions required by bluedroid to set wake alarms and + * grab wake locks. This struct is passed into the stack through the + * |set_os_callouts| function on |bt_interface_t|. + */ +typedef struct { + /* set to sizeof(bt_os_callouts_t) */ + size_t size; + + set_wake_alarm_callout set_wake_alarm; + acquire_wake_lock_callout acquire_wake_lock; + release_wake_lock_callout release_wake_lock; +} bt_os_callouts_t; + +/** NOTE: By default, no profiles are initialized at the time of init/enable. + * Whenever the application invokes the 'init' API of a profile, then one of + * the following shall occur: + * + * 1.) If Bluetooth is not enabled, then the Bluetooth core shall mark the + * profile as enabled. Subsequently, when the application invokes the + * Bluetooth 'enable', as part of the enable sequence the profile that were + * marked shall be enabled by calling appropriate stack APIs. The + * 'adapter_properties_cb' shall return the list of UUIDs of the + * enabled profiles. + * + * 2.) If Bluetooth is enabled, then the Bluetooth core shall invoke the stack + * profile API to initialize the profile and trigger a + * 'adapter_properties_cb' with the current list of UUIDs including the + * newly added profile's UUID. + * + * The reverse shall occur whenever the profile 'cleanup' APIs are invoked + */ + +/** Represents the standard Bluetooth DM interface. */ +typedef struct { + /** set to sizeof(bt_interface_t) */ + size_t size; + /** + * Opens the interface and provides the callback routines + * to the implemenation of this interface. + * The |is_atv| flag indicates whether the local device is an Android TV + */ + int (*init)(bt_callbacks_t* callbacks, bool is_atv); + + /** Enable Bluetooth. */ + int (*enable)(bool guest_mode); + + /** Disable Bluetooth. */ + int (*disable)(void); + + /** Closes the interface. */ + void (*cleanup)(void); + + /** Get all Bluetooth Adapter properties at init */ + int (*get_adapter_properties)(void); + + /** Get Bluetooth Adapter property of 'type' */ + int (*get_adapter_property)(bt_property_type_t type); + + /** Set Bluetooth Adapter property of 'type' */ + /* Based on the type, val shall be one of + * RawAddress or bt_bdname_t or bt_scanmode_t etc + */ + int (*set_adapter_property)(const bt_property_t *property); + + /** Get all Remote Device properties */ + int (*get_remote_device_properties)(RawAddress *remote_addr); + + /** Get Remote Device property of 'type' */ + int (*get_remote_device_property)(RawAddress *remote_addr, + bt_property_type_t type); + + /** Set Remote Device property of 'type' */ + int (*set_remote_device_property)(RawAddress *remote_addr, + const bt_property_t *property); + + /** Get Remote Device's service record for the given UUID */ + int (*get_remote_service_record)(const RawAddress& remote_addr, + const bluetooth::Uuid& uuid); + + /** Start SDP to get remote services */ + int (*get_remote_services)(RawAddress *remote_addr); + + /** Start Discovery */ + int (*start_discovery)(void); + + /** Cancel Discovery */ + int (*cancel_discovery)(void); + + /** Create Bluetooth Bonding */ + int (*create_bond)(const RawAddress *bd_addr, int transport); + + /** Create Bluetooth Bond using out of band data */ + int (*create_bond_out_of_band)(const RawAddress *bd_addr, int transport, + const bt_oob_data_t *p192_data, + const bt_oob_data_t *p256_data); + + /** Remove Bond */ + int (*remove_bond)(const RawAddress *bd_addr); + + /** Cancel Bond */ + int (*cancel_bond)(const RawAddress *bd_addr); + + /** + * Get the connection status for a given remote device. + * return value of 0 means the device is not connected, + * non-zero return status indicates an active connection. + */ + int (*get_connection_state)(const RawAddress *bd_addr); + + /** BT Legacy PinKey Reply */ + /** If accept==FALSE, then pin_len and pin_code shall be 0x0 */ + int (*pin_reply)(const RawAddress *bd_addr, uint8_t accept, + uint8_t pin_len, bt_pin_code_t *pin_code); + + /** BT SSP Reply - Just Works, Numeric Comparison and Passkey + * passkey shall be zero for BT_SSP_VARIANT_PASSKEY_COMPARISON & + * BT_SSP_VARIANT_CONSENT + * For BT_SSP_VARIANT_PASSKEY_ENTRY, if accept==FALSE, then passkey + * shall be zero */ + int (*ssp_reply)(const RawAddress *bd_addr, bt_ssp_variant_t variant, + uint8_t accept, uint32_t passkey); + + /** Get Bluetooth profile interface */ + const void* (*get_profile_interface) (const char *profile_id); + + /** Bluetooth Test Mode APIs - Bluetooth must be enabled for these APIs */ + /* Configure DUT Mode - Use this mode to enter/exit DUT mode */ + int (*dut_mode_configure)(uint8_t enable); + + /* Send any test HCI (vendor-specific) command to the controller. Must be in DUT Mode */ + int (*dut_mode_send)(uint16_t opcode, uint8_t *buf, uint8_t len); + /** BLE Test Mode APIs */ + /* opcode MUST be one of: LE_Receiver_Test, LE_Transmitter_Test, LE_Test_End */ + int (*le_test_mode)(uint16_t opcode, uint8_t *buf, uint8_t len); + + /** Sets the OS call-out functions that bluedroid needs for alarms and wake locks. + * This should be called immediately after a successful |init|. + */ + int (*set_os_callouts)(bt_os_callouts_t *callouts); + + /** Read Energy info details - return value indicates BT_STATUS_SUCCESS or BT_STATUS_NOT_READY + * Success indicates that the VSC command was sent to controller + */ + int (*read_energy_info)(); + + /** + * Native support for dumpsys function + * Function is synchronous and |fd| is owned by caller. + * |arguments| are arguments which may affect the output, encoded as + * UTF-8 strings. + */ + void (*dump)(int fd, const char **arguments); + + /** + * Clear /data/misc/bt_config.conf and erase all stored connections + */ + int (*config_clear)(void); + + /** + * Clear (reset) the dynamic portion of the device interoperability database. + */ + void (*interop_database_clear)(void); + + /** + * Add a new device interoperability workaround for a remote device whose + * first |len| bytes of the its device address match |addr|. + * NOTE: |feature| has to match an item defined in interop_feature_t (interop.h). + */ + void (*interop_database_add)(uint16_t feature, const RawAddress *addr, size_t len); +} bt_interface_t; + +__END_DECLS + +#endif /* ANDROID_INCLUDE_BLUETOOTH_H */ diff --git a/include_all/hardware/boot_control.h b/include_all/hardware/boot_control.h new file mode 100644 index 00000000..abbf3f19 --- /dev/null +++ b/include_all/hardware/boot_control.h @@ -0,0 +1,141 @@ +/* + * 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_INCLUDE_HARDWARE_BOOT_CONTROL_H +#define ANDROID_INCLUDE_HARDWARE_BOOT_CONTROL_H + +#include <hardware/hardware.h> + +__BEGIN_DECLS + +#define BOOT_CONTROL_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) + +/** + * The id of this module + */ +#define BOOT_CONTROL_HARDWARE_MODULE_ID "bootctrl" + +/* + * The Boot Control HAL is designed to allow for managing sets of redundant + * partitions, called slots, that can be booted from independantly. Slots + * are sets of partitions whose names differ only by a given suffix. + * They are identified here by a 0 indexed number, and associated with their + * suffix, which can be appended to the base name for any particular partition + * to find the one associated with that slot. The bootloader must pass the suffix + * of the currently active slot either through a kernel command line property at + * androidboot.slot_suffix, or the device tree at /firmware/android/slot_suffix. + * The primary use of this set up is to allow for background updates while the + * device is running, and to provide a fallback in the event that the update fails. + */ + + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +typedef struct boot_control_module { + struct hw_module_t common; + + /* + * (*init)() perform any initialization tasks needed for the HAL. + * This is called only once. + */ + void (*init)(struct boot_control_module *module); + + /* + * (*getNumberSlots)() returns the number of available slots. + * For instance, a system with a single set of partitions would return + * 1, a system with A/B would return 2, A/B/C -> 3... + */ + unsigned (*getNumberSlots)(struct boot_control_module *module); + + /* + * (*getCurrentSlot)() returns the value letting the system know + * whether the current slot is A or B. The meaning of A and B is + * left up to the implementer. It is assumed that if the current slot + * is A, then the block devices underlying B can be accessed directly + * without any risk of corruption. + * The returned value is always guaranteed to be strictly less than the + * value returned by getNumberSlots. Slots start at 0 and + * finish at getNumberSlots() - 1 + */ + unsigned (*getCurrentSlot)(struct boot_control_module *module); + + /* + * (*markBootSuccessful)() marks the current slot + * as having booted successfully + * + * Returns 0 on success, -errno on error. + */ + int (*markBootSuccessful)(struct boot_control_module *module); + + /* + * (*setActiveBootSlot)() marks the slot passed in parameter as + * the active boot slot (see getCurrentSlot for an explanation + * of the "slot" parameter). This overrides any previous call to + * setSlotAsUnbootable. + * Returns 0 on success, -errno on error. + */ + int (*setActiveBootSlot)(struct boot_control_module *module, unsigned slot); + + /* + * (*setSlotAsUnbootable)() marks the slot passed in parameter as + * an unbootable. This can be used while updating the contents of the slot's + * partitions, so that the system will not attempt to boot a known bad set up. + * Returns 0 on success, -errno on error. + */ + int (*setSlotAsUnbootable)(struct boot_control_module *module, unsigned slot); + + /* + * (*isSlotBootable)() returns if the slot passed in parameter is + * bootable. Note that slots can be made unbootable by both the + * bootloader and by the OS using setSlotAsUnbootable. + * Returns 1 if the slot is bootable, 0 if it's not, and -errno on + * error. + */ + int (*isSlotBootable)(struct boot_control_module *module, unsigned slot); + + /* + * (*getSuffix)() returns the string suffix used by partitions that + * correspond to the slot number passed in parameter. The returned string + * is expected to be statically allocated and not need to be freed. + * Returns NULL if slot does not match an existing slot. + */ + const char* (*getSuffix)(struct boot_control_module *module, unsigned slot); + + /* + * (*isSlotMarkedSucessful)() returns if the slot passed in parameter has + * been marked as successful using markBootSuccessful. + * Returns 1 if the slot has been marked as successful, 0 if it's + * not the case, and -errno on error. + */ + int (*isSlotMarkedSuccessful)(struct boot_control_module *module, unsigned slot); + + /** + * Returns the active slot to boot into on the next boot. If + * setActiveBootSlot() has been called, the getter function should return + * the same slot as the one provided in the last setActiveBootSlot() call. + */ + unsigned (*getActiveBootSlot)(struct boot_control_module *module); + + void* reserved[30]; +} boot_control_module_t; + + +__END_DECLS + +#endif // ANDROID_INCLUDE_HARDWARE_BOOT_CONTROL_H diff --git a/include_all/hardware/camera.h b/include_all/hardware/camera.h new file mode 100644 index 00000000..b1f18fff --- /dev/null +++ b/include_all/hardware/camera.h @@ -0,0 +1,298 @@ +/* + * Copyright (C) 2010-2011 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_INCLUDE_CAMERA_H +#define ANDROID_INCLUDE_CAMERA_H + +#include "camera_common.h" + +/** + * Camera device HAL, initial version [ CAMERA_DEVICE_API_VERSION_1_0 ] + * + * DEPRECATED. New devices should use Camera HAL v3.2 or newer. + * + * Supports the android.hardware.Camera API, and the android.hardware.camera2 + * API in legacy mode only. + * + * Camera devices that support this version of the HAL must return a value in + * the range HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF) in + * camera_device_t.common.version. CAMERA_DEVICE_API_VERSION_1_0 is the + * recommended value. + * + * Camera modules that implement version 2.0 or higher of camera_module_t must + * also return the value of camera_device_t.common.version in + * camera_info_t.device_version. + * + * See camera_common.h for more details. + */ + +__BEGIN_DECLS + +struct camera_memory; +typedef void (*camera_release_memory)(struct camera_memory *mem); + +typedef struct camera_memory { + void *data; + size_t size; + void *handle; + camera_release_memory release; +} camera_memory_t; + +typedef camera_memory_t* (*camera_request_memory)(int fd, size_t buf_size, unsigned int num_bufs, + void *user); + +typedef void (*camera_notify_callback)(int32_t msg_type, + int32_t ext1, + int32_t ext2, + void *user); + +typedef void (*camera_data_callback)(int32_t msg_type, + const camera_memory_t *data, unsigned int index, + camera_frame_metadata_t *metadata, void *user); + +typedef void (*camera_data_timestamp_callback)(int64_t timestamp, + int32_t msg_type, + const camera_memory_t *data, unsigned int index, + void *user); + +#define HAL_CAMERA_PREVIEW_WINDOW_TAG 0xcafed00d + +typedef struct preview_stream_ops { + int (*dequeue_buffer)(struct preview_stream_ops* w, + buffer_handle_t** buffer, int *stride); + int (*enqueue_buffer)(struct preview_stream_ops* w, + buffer_handle_t* buffer); + int (*cancel_buffer)(struct preview_stream_ops* w, + buffer_handle_t* buffer); + int (*set_buffer_count)(struct preview_stream_ops* w, int count); + int (*set_buffers_geometry)(struct preview_stream_ops* pw, + int w, int h, int format); + int (*set_crop)(struct preview_stream_ops *w, + int left, int top, int right, int bottom); + int (*set_usage)(struct preview_stream_ops* w, int usage); + int (*set_swap_interval)(struct preview_stream_ops *w, int interval); + int (*get_min_undequeued_buffer_count)(const struct preview_stream_ops *w, + int *count); + int (*lock_buffer)(struct preview_stream_ops* w, + buffer_handle_t* buffer); + // Timestamps are measured in nanoseconds, and must be comparable + // and monotonically increasing between two frames in the same + // preview stream. They do not need to be comparable between + // consecutive or parallel preview streams, cameras, or app runs. + int (*set_timestamp)(struct preview_stream_ops *w, int64_t timestamp); +} preview_stream_ops_t; + +struct camera_device; +typedef struct camera_device_ops { + /** Set the ANativeWindow to which preview frames are sent */ + int (*set_preview_window)(struct camera_device *, + struct preview_stream_ops *window); + + /** Set the notification and data callbacks */ + void (*set_callbacks)(struct camera_device *, + camera_notify_callback notify_cb, + camera_data_callback data_cb, + camera_data_timestamp_callback data_cb_timestamp, + camera_request_memory get_memory, + void *user); + + /** + * The following three functions all take a msg_type, which is a bitmask of + * the messages defined in include/ui/Camera.h + */ + + /** + * Enable a message, or set of messages. + */ + void (*enable_msg_type)(struct camera_device *, int32_t msg_type); + + /** + * Disable a message, or a set of messages. + * + * Once received a call to disableMsgType(CAMERA_MSG_VIDEO_FRAME), camera + * HAL should not rely on its client to call releaseRecordingFrame() to + * release video recording frames sent out by the cameral HAL before and + * after the disableMsgType(CAMERA_MSG_VIDEO_FRAME) call. Camera HAL + * clients must not modify/access any video recording frame after calling + * disableMsgType(CAMERA_MSG_VIDEO_FRAME). + */ + void (*disable_msg_type)(struct camera_device *, int32_t msg_type); + + /** + * Query whether a message, or a set of messages, is enabled. Note that + * this is operates as an AND, if any of the messages queried are off, this + * will return false. + */ + int (*msg_type_enabled)(struct camera_device *, int32_t msg_type); + + /** + * Start preview mode. + */ + int (*start_preview)(struct camera_device *); + + /** + * Stop a previously started preview. + */ + void (*stop_preview)(struct camera_device *); + + /** + * Returns true if preview is enabled. + */ + int (*preview_enabled)(struct camera_device *); + + /** + * Request the camera HAL to store meta data or real YUV data in the video + * buffers sent out via CAMERA_MSG_VIDEO_FRAME for a recording session. If + * it is not called, the default camera HAL behavior is to store real YUV + * data in the video buffers. + * + * This method should be called before startRecording() in order to be + * effective. + * + * If meta data is stored in the video buffers, it is up to the receiver of + * the video buffers to interpret the contents and to find the actual frame + * data with the help of the meta data in the buffer. How this is done is + * outside of the scope of this method. + * + * Some camera HALs may not support storing meta data in the video buffers, + * but all camera HALs should support storing real YUV data in the video + * buffers. If the camera HAL does not support storing the meta data in the + * video buffers when it is requested to do do, INVALID_OPERATION must be + * returned. It is very useful for the camera HAL to pass meta data rather + * than the actual frame data directly to the video encoder, since the + * amount of the uncompressed frame data can be very large if video size is + * large. + * + * @param enable if true to instruct the camera HAL to store + * meta data in the video buffers; false to instruct + * the camera HAL to store real YUV data in the video + * buffers. + * + * @return OK on success. + */ + int (*store_meta_data_in_buffers)(struct camera_device *, int enable); + + /** + * Start record mode. When a record image is available, a + * CAMERA_MSG_VIDEO_FRAME message is sent with the corresponding + * frame. Every record frame must be released by a camera HAL client via + * releaseRecordingFrame() before the client calls + * disableMsgType(CAMERA_MSG_VIDEO_FRAME). After the client calls + * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's + * responsibility to manage the life-cycle of the video recording frames, + * and the client must not modify/access any video recording frames. + */ + int (*start_recording)(struct camera_device *); + + /** + * Stop a previously started recording. + */ + void (*stop_recording)(struct camera_device *); + + /** + * Returns true if recording is enabled. + */ + int (*recording_enabled)(struct camera_device *); + + /** + * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME. + * + * It is camera HAL client's responsibility to release video recording + * frames sent out by the camera HAL before the camera HAL receives a call + * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to + * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's + * responsibility to manage the life-cycle of the video recording frames. + */ + void (*release_recording_frame)(struct camera_device *, + const void *opaque); + + /** + * Start auto focus, the notification callback routine is called with + * CAMERA_MSG_FOCUS once when focusing is complete. autoFocus() will be + * called again if another auto focus is needed. + */ + int (*auto_focus)(struct camera_device *); + + /** + * Cancels auto-focus function. If the auto-focus is still in progress, + * this function will cancel it. Whether the auto-focus is in progress or + * not, this function will return the focus position to the default. If + * the camera does not support auto-focus, this is a no-op. + */ + int (*cancel_auto_focus)(struct camera_device *); + + /** + * Take a picture. + */ + int (*take_picture)(struct camera_device *); + + /** + * Cancel a picture that was started with takePicture. Calling this method + * when no picture is being taken is a no-op. + */ + int (*cancel_picture)(struct camera_device *); + + /** + * Set the camera parameters. This returns BAD_VALUE if any parameter is + * invalid or not supported. + */ + int (*set_parameters)(struct camera_device *, const char *parms); + + /** Retrieve the camera parameters. The buffer returned by the camera HAL + must be returned back to it with put_parameters, if put_parameters + is not NULL. + */ + char *(*get_parameters)(struct camera_device *); + + /** The camera HAL uses its own memory to pass us the parameters when we + call get_parameters. Use this function to return the memory back to + the camera HAL, if put_parameters is not NULL. If put_parameters + is NULL, then you have to use free() to release the memory. + */ + void (*put_parameters)(struct camera_device *, char *); + + /** + * Send command to camera driver. + */ + int (*send_command)(struct camera_device *, + int32_t cmd, int32_t arg1, int32_t arg2); + + /** + * Release the hardware resources owned by this object. Note that this is + * *not* done in the destructor. + */ + void (*release)(struct camera_device *); + + /** + * Dump state of the camera hardware + */ + int (*dump)(struct camera_device *, int fd); +} camera_device_ops_t; + +typedef struct camera_device { + /** + * camera_device.common.version must be in the range + * HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF). CAMERA_DEVICE_API_VERSION_1_0 is + * recommended. + */ + hw_device_t common; + camera_device_ops_t *ops; + void *priv; +} camera_device_t; + +__END_DECLS + +#endif /* #ifdef ANDROID_INCLUDE_CAMERA_H */ diff --git a/include_all/hardware/camera2.h b/include_all/hardware/camera2.h new file mode 100644 index 00000000..547a1d78 --- /dev/null +++ b/include_all/hardware/camera2.h @@ -0,0 +1,842 @@ +/* + * Copyright (C) 2012 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_INCLUDE_CAMERA2_H +#define ANDROID_INCLUDE_CAMERA2_H + +#include "camera_common.h" +#include "system/camera_metadata.h" + +/** + * Camera device HAL 2.1 [ CAMERA_DEVICE_API_VERSION_2_0, CAMERA_DEVICE_API_VERSION_2_1 ] + * + * NO LONGER SUPPORTED. The camera service will no longer load HAL modules that + * contain HAL v2.0 or v2.1 devices. + * + * New devices should use Camera HAL v3.2 or newer. + * + * Supports the android.hardware.Camera API, and the android.hardware.camera2 + * API in legacy mode only. + * + * Camera devices that support this version of the HAL must return + * CAMERA_DEVICE_API_VERSION_2_1 in camera_device_t.common.version and in + * camera_info_t.device_version (from camera_module_t.get_camera_info). + * + * Camera modules that may contain version 2.x devices must implement at least + * version 2.0 of the camera module interface (as defined by + * camera_module_t.common.module_api_version). + * + * See camera_common.h for more versioning details. + * + * Version history: + * + * 2.0: CAMERA_DEVICE_API_VERSION_2_0. Initial release (Android 4.2): + * - Sufficient for implementing existing android.hardware.Camera API. + * - Allows for ZSL queue in camera service layer + * - Not tested for any new features such manual capture control, + * Bayer RAW capture, reprocessing of RAW data. + * + * 2.1: CAMERA_DEVICE_API_VERSION_2_1. Support per-device static metadata: + * - Add get_instance_metadata() method to retrieve metadata that is fixed + * after device open, but may be variable between open() calls. + */ + +__BEGIN_DECLS + +struct camera2_device; + +/********************************************************************** + * + * Input/output stream buffer queue interface definitions + * + */ + +/** + * Output image stream queue interface. A set of these methods is provided to + * the HAL device in allocate_stream(), and are used to interact with the + * gralloc buffer queue for that stream. They may not be called until after + * allocate_stream returns. + */ +typedef struct camera2_stream_ops { + /** + * Get a buffer to fill from the queue. The size and format of the buffer + * are fixed for a given stream (defined in allocate_stream), and the stride + * should be queried from the platform gralloc module. The gralloc buffer + * will have been allocated based on the usage flags provided by + * allocate_stream, and will be locked for use. + */ + int (*dequeue_buffer)(const struct camera2_stream_ops* w, + buffer_handle_t** buffer); + + /** + * Push a filled buffer to the stream to be used by the consumer. + * + * The timestamp represents the time at start of exposure of the first row + * of the image; it must be from a monotonic clock, and is measured in + * nanoseconds. The timestamps do not need to be comparable between + * different cameras, or consecutive instances of the same camera. However, + * they must be comparable between streams from the same camera. If one + * capture produces buffers for multiple streams, each stream must have the + * same timestamp for that buffer, and that timestamp must match the + * timestamp in the output frame metadata. + */ + int (*enqueue_buffer)(const struct camera2_stream_ops* w, + int64_t timestamp, + buffer_handle_t* buffer); + /** + * Return a buffer to the queue without marking it as filled. + */ + int (*cancel_buffer)(const struct camera2_stream_ops* w, + buffer_handle_t* buffer); + /** + * Set the crop window for subsequently enqueued buffers. The parameters are + * measured in pixels relative to the buffer width and height. + */ + int (*set_crop)(const struct camera2_stream_ops *w, + int left, int top, int right, int bottom); + +} camera2_stream_ops_t; + +/** + * Temporary definition during transition. + * + * These formats will be removed and replaced with + * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. To maximize forward compatibility, + * HAL implementations are strongly recommended to treat FORMAT_OPAQUE and + * FORMAT_ZSL as equivalent to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, and + * return HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED in the format_actual output + * parameter of allocate_stream, allowing the gralloc module to select the + * specific format based on the usage flags from the camera and the stream + * consumer. + */ +enum { + CAMERA2_HAL_PIXEL_FORMAT_OPAQUE = HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, + CAMERA2_HAL_PIXEL_FORMAT_ZSL = -1 +}; + +/** + * Transport header for compressed JPEG buffers in output streams. + * + * To capture JPEG images, a stream is created using the pixel format + * HAL_PIXEL_FORMAT_BLOB, and the static metadata field android.jpeg.maxSize is + * used as the buffer size. Since compressed JPEG images are of variable size, + * the HAL needs to include the final size of the compressed image using this + * structure inside the output stream buffer. The JPEG blob ID field must be set + * to CAMERA2_JPEG_BLOB_ID. + * + * Transport header should be at the end of the JPEG output stream buffer. That + * means the jpeg_blob_id must start at byte[android.jpeg.maxSize - + * sizeof(camera2_jpeg_blob)]. Any HAL using this transport header must + * account for it in android.jpeg.maxSize. The JPEG data itself starts at + * byte[0] and should be jpeg_size bytes long. + */ +typedef struct camera2_jpeg_blob { + uint16_t jpeg_blob_id; + uint32_t jpeg_size; +} camera2_jpeg_blob_t; + +enum { + CAMERA2_JPEG_BLOB_ID = 0x00FF +}; + +/** + * Input reprocess stream queue management. A set of these methods is provided + * to the HAL device in allocate_reprocess_stream(); they are used to interact + * with the reprocess stream's input gralloc buffer queue. + */ +typedef struct camera2_stream_in_ops { + /** + * Get the next buffer of image data to reprocess. The width, height, and + * format of the buffer is fixed in allocate_reprocess_stream(), and the + * stride and other details should be queried from the platform gralloc + * module as needed. The buffer will already be locked for use. + */ + int (*acquire_buffer)(const struct camera2_stream_in_ops *w, + buffer_handle_t** buffer); + /** + * Return a used buffer to the buffer queue for reuse. + */ + int (*release_buffer)(const struct camera2_stream_in_ops *w, + buffer_handle_t* buffer); + +} camera2_stream_in_ops_t; + +/********************************************************************** + * + * Metadata queue management, used for requests sent to HAL module, and for + * frames produced by the HAL. + * + */ + +enum { + CAMERA2_REQUEST_QUEUE_IS_BOTTOMLESS = -1 +}; + +/** + * Request input queue protocol: + * + * The framework holds the queue and its contents. At start, the queue is empty. + * + * 1. When the first metadata buffer is placed into the queue, the framework + * signals the device by calling notify_request_queue_not_empty(). + * + * 2. After receiving notify_request_queue_not_empty, the device must call + * dequeue() once it's ready to handle the next buffer. + * + * 3. Once the device has processed a buffer, and is ready for the next buffer, + * it must call dequeue() again instead of waiting for a notification. If + * there are no more buffers available, dequeue() will return NULL. After + * this point, when a buffer becomes available, the framework must call + * notify_request_queue_not_empty() again. If the device receives a NULL + * return from dequeue, it does not need to query the queue again until a + * notify_request_queue_not_empty() call is received from the source. + * + * 4. If the device calls buffer_count() and receives 0, this does not mean that + * the framework will provide a notify_request_queue_not_empty() call. The + * framework will only provide such a notification after the device has + * received a NULL from dequeue, or on initial startup. + * + * 5. The dequeue() call in response to notify_request_queue_not_empty() may be + * on the same thread as the notify_request_queue_not_empty() call, and may + * be performed from within the notify call. + * + * 6. All dequeued request buffers must be returned to the framework by calling + * free_request, including when errors occur, a device flush is requested, or + * when the device is shutting down. + */ +typedef struct camera2_request_queue_src_ops { + /** + * Get the count of request buffers pending in the queue. May return + * CAMERA2_REQUEST_QUEUE_IS_BOTTOMLESS if a repeating request (stream + * request) is currently configured. Calling this method has no effect on + * whether the notify_request_queue_not_empty() method will be called by the + * framework. + */ + int (*request_count)(const struct camera2_request_queue_src_ops *q); + + /** + * Get a metadata buffer from the framework. Returns OK if there is no + * error. If the queue is empty, returns NULL in buffer. In that case, the + * device must wait for a notify_request_queue_not_empty() message before + * attempting to dequeue again. Buffers obtained in this way must be + * returned to the framework with free_request(). + */ + int (*dequeue_request)(const struct camera2_request_queue_src_ops *q, + camera_metadata_t **buffer); + /** + * Return a metadata buffer to the framework once it has been used, or if + * an error or shutdown occurs. + */ + int (*free_request)(const struct camera2_request_queue_src_ops *q, + camera_metadata_t *old_buffer); + +} camera2_request_queue_src_ops_t; + +/** + * Frame output queue protocol: + * + * The framework holds the queue and its contents. At start, the queue is empty. + * + * 1. When the device is ready to fill an output metadata frame, it must dequeue + * a metadata buffer of the required size. + * + * 2. It should then fill the metadata buffer, and place it on the frame queue + * using enqueue_frame. The framework takes ownership of the frame. + * + * 3. In case of an error, a request to flush the pipeline, or shutdown, the + * device must return any affected dequeued frames to the framework by + * calling cancel_frame. + */ +typedef struct camera2_frame_queue_dst_ops { + /** + * Get an empty metadata buffer to fill from the framework. The new metadata + * buffer will have room for entries number of metadata entries, plus + * data_bytes worth of extra storage. Frames dequeued here must be returned + * to the framework with either cancel_frame or enqueue_frame. + */ + int (*dequeue_frame)(const struct camera2_frame_queue_dst_ops *q, + size_t entries, size_t data_bytes, + camera_metadata_t **buffer); + + /** + * Return a dequeued metadata buffer to the framework for reuse; do not mark it as + * filled. Use when encountering errors, or flushing the internal request queue. + */ + int (*cancel_frame)(const struct camera2_frame_queue_dst_ops *q, + camera_metadata_t *buffer); + + /** + * Place a completed metadata frame on the frame output queue. + */ + int (*enqueue_frame)(const struct camera2_frame_queue_dst_ops *q, + camera_metadata_t *buffer); + +} camera2_frame_queue_dst_ops_t; + +/********************************************************************** + * + * Notification callback and message definition, and trigger definitions + * + */ + +/** + * Asynchronous notification callback from the HAL, fired for various + * reasons. Only for information independent of frame capture, or that require + * specific timing. The user pointer must be the same one that was passed to the + * device in set_notify_callback(). + */ +typedef void (*camera2_notify_callback)(int32_t msg_type, + int32_t ext1, + int32_t ext2, + int32_t ext3, + void *user); + +/** + * Possible message types for camera2_notify_callback + */ +enum { + /** + * An error has occurred. Argument ext1 contains the error code, and + * ext2 and ext3 contain any error-specific information. + */ + CAMERA2_MSG_ERROR = 0x0001, + /** + * The exposure of a given request has begun. Argument ext1 contains the + * frame number, and ext2 and ext3 contain the low-order and high-order + * bytes of the timestamp for when exposure began. + * (timestamp = (ext3 << 32 | ext2)) + */ + CAMERA2_MSG_SHUTTER = 0x0010, + /** + * The autofocus routine has changed state. Argument ext1 contains the new + * state; the values are the same as those for the metadata field + * android.control.afState. Ext2 contains the latest trigger ID passed to + * trigger_action(CAMERA2_TRIGGER_AUTOFOCUS) or + * trigger_action(CAMERA2_TRIGGER_CANCEL_AUTOFOCUS), or 0 if trigger has not + * been called with either of those actions. + */ + CAMERA2_MSG_AUTOFOCUS = 0x0020, + /** + * The autoexposure routine has changed state. Argument ext1 contains the + * new state; the values are the same as those for the metadata field + * android.control.aeState. Ext2 contains the latest trigger ID value passed to + * trigger_action(CAMERA2_TRIGGER_PRECAPTURE_METERING), or 0 if that method + * has not been called. + */ + CAMERA2_MSG_AUTOEXPOSURE = 0x0021, + /** + * The auto-whitebalance routine has changed state. Argument ext1 contains + * the new state; the values are the same as those for the metadata field + * android.control.awbState. Ext2 contains the latest trigger ID passed to + * trigger_action(CAMERA2_TRIGGER_PRECAPTURE_METERING), or 0 if that method + * has not been called. + */ + CAMERA2_MSG_AUTOWB = 0x0022 +}; + +/** + * Error codes for CAMERA_MSG_ERROR + */ +enum { + /** + * A serious failure occured. Camera device may not work without reboot, and + * no further frames or buffer streams will be produced by the + * device. Device should be treated as closed. + */ + CAMERA2_MSG_ERROR_HARDWARE = 0x0001, + /** + * A serious failure occured. No further frames or buffer streams will be + * produced by the device. Device should be treated as closed. The client + * must reopen the device to use it again. + */ + CAMERA2_MSG_ERROR_DEVICE, + /** + * An error has occurred in processing a request. No output (metadata or + * buffers) will be produced for this request. ext2 contains the frame + * number of the request. Subsequent requests are unaffected, and the device + * remains operational. + */ + CAMERA2_MSG_ERROR_REQUEST, + /** + * An error has occurred in producing an output frame metadata buffer for a + * request, but image buffers for it will still be available. Subsequent + * requests are unaffected, and the device remains operational. ext2 + * contains the frame number of the request. + */ + CAMERA2_MSG_ERROR_FRAME, + /** + * An error has occurred in placing an output buffer into a stream for a + * request. The frame metadata and other buffers may still be + * available. Subsequent requests are unaffected, and the device remains + * operational. ext2 contains the frame number of the request, and ext3 + * contains the stream id. + */ + CAMERA2_MSG_ERROR_STREAM, + /** + * Number of error types + */ + CAMERA2_MSG_NUM_ERRORS +}; + +/** + * Possible trigger ids for trigger_action() + */ +enum { + /** + * Trigger an autofocus cycle. The effect of the trigger depends on the + * autofocus mode in effect when the trigger is received, which is the mode + * listed in the latest capture request to be dequeued by the HAL. If the + * mode is OFF, EDOF, or FIXED, the trigger has no effect. In AUTO, MACRO, + * or CONTINUOUS_* modes, see below for the expected behavior. The state of + * the autofocus cycle can be tracked in android.control.afMode and the + * corresponding notifications. + * + ** + * In AUTO or MACRO mode, the AF state transitions (and notifications) + * when calling with trigger ID = N with the previous ID being K are: + * + * Initial state Transitions + * INACTIVE (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) + * AF_FOCUSED (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) + * AF_NOT_FOCUSED (K) -> ACTIVE_SCAN (N) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) + * ACTIVE_SCAN (K) -> AF_FOCUSED(N) or AF_NOT_FOCUSED(N) + * PASSIVE_SCAN (K) Not used in AUTO/MACRO mode + * PASSIVE_FOCUSED (K) Not used in AUTO/MACRO mode + * + ** + * In CONTINUOUS_PICTURE mode, triggering AF must lock the AF to the current + * lens position and transition the AF state to either AF_FOCUSED or + * NOT_FOCUSED. If a passive scan is underway, that scan must complete and + * then lock the lens position and change AF state. TRIGGER_CANCEL_AUTOFOCUS + * will allow the AF to restart its operation. + * + * Initial state Transitions + * INACTIVE (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) + * PASSIVE_FOCUSED (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) + * PASSIVE_SCAN (K) -> AF_FOCUSED (N) or AF_NOT_FOCUSED (N) + * AF_FOCUSED (K) no effect except to change next notification ID to N + * AF_NOT_FOCUSED (K) no effect except to change next notification ID to N + * + ** + * In CONTINUOUS_VIDEO mode, triggering AF must lock the AF to the current + * lens position and transition the AF state to either AF_FOCUSED or + * NOT_FOCUSED. If a passive scan is underway, it must immediately halt, in + * contrast with CONTINUOUS_PICTURE mode. TRIGGER_CANCEL_AUTOFOCUS will + * allow the AF to restart its operation. + * + * Initial state Transitions + * INACTIVE (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) + * PASSIVE_FOCUSED (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) + * PASSIVE_SCAN (K) -> immediate AF_FOCUSED (N) or AF_NOT_FOCUSED (N) + * AF_FOCUSED (K) no effect except to change next notification ID to N + * AF_NOT_FOCUSED (K) no effect except to change next notification ID to N + * + * Ext1 is an ID that must be returned in subsequent auto-focus state change + * notifications through camera2_notify_callback() and stored in + * android.control.afTriggerId. + */ + CAMERA2_TRIGGER_AUTOFOCUS = 0x0001, + /** + * Send a cancel message to the autofocus algorithm. The effect of the + * cancellation depends on the autofocus mode in effect when the trigger is + * received, which is the mode listed in the latest capture request to be + * dequeued by the HAL. If the AF mode is OFF or EDOF, the cancel has no + * effect. For other modes, the lens should return to its default position, + * any current autofocus scan must be canceled, and the AF state should be + * set to INACTIVE. + * + * The state of the autofocus cycle can be tracked in android.control.afMode + * and the corresponding notification. Continuous autofocus modes may resume + * focusing operations thereafter exactly as if the camera had just been set + * to a continuous AF mode. + * + * Ext1 is an ID that must be returned in subsequent auto-focus state change + * notifications through camera2_notify_callback() and stored in + * android.control.afTriggerId. + */ + CAMERA2_TRIGGER_CANCEL_AUTOFOCUS, + /** + * Trigger a pre-capture metering cycle, which may include firing the flash + * to determine proper capture parameters. Typically, this trigger would be + * fired for a half-depress of a camera shutter key, or before a snapshot + * capture in general. The state of the metering cycle can be tracked in + * android.control.aeMode and the corresponding notification. If the + * auto-exposure mode is OFF, the trigger does nothing. + * + * Ext1 is an ID that must be returned in subsequent + * auto-exposure/auto-white balance state change notifications through + * camera2_notify_callback() and stored in android.control.aePrecaptureId. + */ + CAMERA2_TRIGGER_PRECAPTURE_METERING +}; + +/** + * Possible template types for construct_default_request() + */ +enum { + /** + * Standard camera preview operation with 3A on auto. + */ + CAMERA2_TEMPLATE_PREVIEW = 1, + /** + * Standard camera high-quality still capture with 3A and flash on auto. + */ + CAMERA2_TEMPLATE_STILL_CAPTURE, + /** + * Standard video recording plus preview with 3A on auto, torch off. + */ + CAMERA2_TEMPLATE_VIDEO_RECORD, + /** + * High-quality still capture while recording video. Application will + * include preview, video record, and full-resolution YUV or JPEG streams in + * request. Must not cause stuttering on video stream. 3A on auto. + */ + CAMERA2_TEMPLATE_VIDEO_SNAPSHOT, + /** + * Zero-shutter-lag mode. Application will request preview and + * full-resolution data for each frame, and reprocess it to JPEG when a + * still image is requested by user. Settings should provide highest-quality + * full-resolution images without compromising preview frame rate. 3A on + * auto. + */ + CAMERA2_TEMPLATE_ZERO_SHUTTER_LAG, + + /* Total number of templates */ + CAMERA2_TEMPLATE_COUNT +}; + + +/********************************************************************** + * + * Camera device operations + * + */ +typedef struct camera2_device_ops { + + /********************************************************************** + * Request and frame queue setup and management methods + */ + + /** + * Pass in input request queue interface methods. + */ + int (*set_request_queue_src_ops)(const struct camera2_device *, + const camera2_request_queue_src_ops_t *request_src_ops); + + /** + * Notify device that the request queue is no longer empty. Must only be + * called when the first buffer is added a new queue, or after the source + * has returned NULL in response to a dequeue call. + */ + int (*notify_request_queue_not_empty)(const struct camera2_device *); + + /** + * Pass in output frame queue interface methods + */ + int (*set_frame_queue_dst_ops)(const struct camera2_device *, + const camera2_frame_queue_dst_ops_t *frame_dst_ops); + + /** + * Number of camera requests being processed by the device at the moment + * (captures/reprocesses that have had their request dequeued, but have not + * yet been enqueued onto output pipeline(s) ). No streams may be released + * by the framework until the in-progress count is 0. + */ + int (*get_in_progress_count)(const struct camera2_device *); + + /** + * Flush all in-progress captures. This includes all dequeued requests + * (regular or reprocessing) that have not yet placed any outputs into a + * stream or the frame queue. Partially completed captures must be completed + * normally. No new requests may be dequeued from the request queue until + * the flush completes. + */ + int (*flush_captures_in_progress)(const struct camera2_device *); + + /** + * Create a filled-in default request for standard camera use cases. + * + * The device must return a complete request that is configured to meet the + * requested use case, which must be one of the CAMERA2_TEMPLATE_* + * enums. All request control fields must be included, except for + * android.request.outputStreams. + * + * The metadata buffer returned must be allocated with + * allocate_camera_metadata. The framework takes ownership of the buffer. + */ + int (*construct_default_request)(const struct camera2_device *, + int request_template, + camera_metadata_t **request); + + /********************************************************************** + * Stream management + */ + + /** + * allocate_stream: + * + * Allocate a new output stream for use, defined by the output buffer width, + * height, target, and possibly the pixel format. Returns the new stream's + * ID, gralloc usage flags, minimum queue buffer count, and possibly the + * pixel format, on success. Error conditions: + * + * - Requesting a width/height/format combination not listed as + * supported by the sensor's static characteristics + * + * - Asking for too many streams of a given format type (2 bayer raw + * streams, for example). + * + * Input parameters: + * + * - width, height, format: Specification for the buffers to be sent through + * this stream. Format is a value from the HAL_PIXEL_FORMAT_* list. If + * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform + * gralloc module will select a format based on the usage flags provided + * by the camera HAL and the consumer of the stream. The camera HAL should + * inspect the buffers handed to it in the register_stream_buffers call to + * obtain the implementation-specific format if necessary. + * + * - stream_ops: A structure of function pointers for obtaining and queuing + * up buffers for this stream. The underlying stream will be configured + * based on the usage and max_buffers outputs. The methods in this + * structure may not be called until after allocate_stream returns. + * + * Output parameters: + * + * - stream_id: An unsigned integer identifying this stream. This value is + * used in incoming requests to identify the stream, and in releasing the + * stream. + * + * - usage: The gralloc usage mask needed by the HAL device for producing + * the requested type of data. This is used in allocating new gralloc + * buffers for the stream buffer queue. + * + * - max_buffers: The maximum number of buffers the HAL device may need to + * have dequeued at the same time. The device may not dequeue more buffers + * than this value at the same time. + * + */ + int (*allocate_stream)( + const struct camera2_device *, + // inputs + uint32_t width, + uint32_t height, + int format, + const camera2_stream_ops_t *stream_ops, + // outputs + uint32_t *stream_id, + uint32_t *format_actual, // IGNORED, will be removed + uint32_t *usage, + uint32_t *max_buffers); + + /** + * Register buffers for a given stream. This is called after a successful + * allocate_stream call, and before the first request referencing the stream + * is enqueued. This method is intended to allow the HAL device to map or + * otherwise prepare the buffers for later use. num_buffers is guaranteed to + * be at least max_buffers (from allocate_stream), but may be larger. The + * buffers will already be locked for use. At the end of the call, all the + * buffers must be ready to be returned to the queue. If the stream format + * was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the camera HAL should + * inspect the passed-in buffers here to determine any platform-private + * pixel format information. + */ + int (*register_stream_buffers)( + const struct camera2_device *, + uint32_t stream_id, + int num_buffers, + buffer_handle_t *buffers); + + /** + * Release a stream. Returns an error if called when get_in_progress_count + * is non-zero, or if the stream id is invalid. + */ + int (*release_stream)( + const struct camera2_device *, + uint32_t stream_id); + + /** + * allocate_reprocess_stream: + * + * Allocate a new input stream for use, defined by the output buffer width, + * height, and the pixel format. Returns the new stream's ID, gralloc usage + * flags, and required simultaneously acquirable buffer count, on + * success. Error conditions: + * + * - Requesting a width/height/format combination not listed as + * supported by the sensor's static characteristics + * + * - Asking for too many reprocessing streams to be configured at once. + * + * Input parameters: + * + * - width, height, format: Specification for the buffers to be sent through + * this stream. Format must be a value from the HAL_PIXEL_FORMAT_* list. + * + * - reprocess_stream_ops: A structure of function pointers for acquiring + * and releasing buffers for this stream. The underlying stream will be + * configured based on the usage and max_buffers outputs. + * + * Output parameters: + * + * - stream_id: An unsigned integer identifying this stream. This value is + * used in incoming requests to identify the stream, and in releasing the + * stream. These ids are numbered separately from the input stream ids. + * + * - consumer_usage: The gralloc usage mask needed by the HAL device for + * consuming the requested type of data. This is used in allocating new + * gralloc buffers for the stream buffer queue. + * + * - max_buffers: The maximum number of buffers the HAL device may need to + * have acquired at the same time. The device may not have more buffers + * acquired at the same time than this value. + * + */ + int (*allocate_reprocess_stream)(const struct camera2_device *, + uint32_t width, + uint32_t height, + uint32_t format, + const camera2_stream_in_ops_t *reprocess_stream_ops, + // outputs + uint32_t *stream_id, + uint32_t *consumer_usage, + uint32_t *max_buffers); + + /** + * allocate_reprocess_stream_from_stream: + * + * Allocate a new input stream for use, which will use the buffers allocated + * for an existing output stream. That is, after the HAL enqueues a buffer + * onto the output stream, it may see that same buffer handed to it from + * this input reprocessing stream. After the HAL releases the buffer back to + * the reprocessing stream, it will be returned to the output queue for + * reuse. + * + * Error conditions: + * + * - Using an output stream of unsuitable size/format for the basis of the + * reprocessing stream. + * + * - Attempting to allocatee too many reprocessing streams at once. + * + * Input parameters: + * + * - output_stream_id: The ID of an existing output stream which has + * a size and format suitable for reprocessing. + * + * - reprocess_stream_ops: A structure of function pointers for acquiring + * and releasing buffers for this stream. The underlying stream will use + * the same graphics buffer handles as the output stream uses. + * + * Output parameters: + * + * - stream_id: An unsigned integer identifying this stream. This value is + * used in incoming requests to identify the stream, and in releasing the + * stream. These ids are numbered separately from the input stream ids. + * + * The HAL client must always release the reprocessing stream before it + * releases the output stream it is based on. + * + */ + int (*allocate_reprocess_stream_from_stream)(const struct camera2_device *, + uint32_t output_stream_id, + const camera2_stream_in_ops_t *reprocess_stream_ops, + // outputs + uint32_t *stream_id); + + /** + * Release a reprocessing stream. Returns an error if called when + * get_in_progress_count is non-zero, or if the stream id is not + * valid. + */ + int (*release_reprocess_stream)( + const struct camera2_device *, + uint32_t stream_id); + + /********************************************************************** + * Miscellaneous methods + */ + + /** + * Trigger asynchronous activity. This is used for triggering special + * behaviors of the camera 3A routines when they are in use. See the + * documentation for CAMERA2_TRIGGER_* above for details of the trigger ids + * and their arguments. + */ + int (*trigger_action)(const struct camera2_device *, + uint32_t trigger_id, + int32_t ext1, + int32_t ext2); + + /** + * Notification callback setup + */ + int (*set_notify_callback)(const struct camera2_device *, + camera2_notify_callback notify_cb, + void *user); + + /** + * Get methods to query for vendor extension metadata tag infomation. May + * set ops to NULL if no vendor extension tags are defined. + */ + int (*get_metadata_vendor_tag_ops)(const struct camera2_device*, + vendor_tag_query_ops_t **ops); + + /** + * Dump state of the camera hardware + */ + int (*dump)(const struct camera2_device *, int fd); + + /** + * Get device-instance-specific metadata. This metadata must be constant for + * a single instance of the camera device, but may be different between + * open() calls. The returned camera_metadata pointer must be valid until + * the device close() method is called. + * + * Version information: + * + * CAMERA_DEVICE_API_VERSION_2_0: + * + * Not available. Framework may not access this function pointer. + * + * CAMERA_DEVICE_API_VERSION_2_1: + * + * Valid. Can be called by the framework. + * + */ + int (*get_instance_metadata)(const struct camera2_device *, + camera_metadata **instance_metadata); + +} camera2_device_ops_t; + +/********************************************************************** + * + * Camera device definition + * + */ +typedef struct camera2_device { + /** + * common.version must equal CAMERA_DEVICE_API_VERSION_2_0 to identify + * this device as implementing version 2.0 of the camera device HAL. + */ + hw_device_t common; + camera2_device_ops_t *ops; + void *priv; +} camera2_device_t; + +__END_DECLS + +#endif /* #ifdef ANDROID_INCLUDE_CAMERA2_H */ diff --git a/include_all/hardware/camera3.h b/include_all/hardware/camera3.h new file mode 100644 index 00000000..7fb86dfb --- /dev/null +++ b/include_all/hardware/camera3.h @@ -0,0 +1,3564 @@ +/* + * Copyright (C) 2013-2018 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_INCLUDE_CAMERA3_H +#define ANDROID_INCLUDE_CAMERA3_H + +#include <system/camera_metadata.h> +#include "camera_common.h" + +/** + * Camera device HAL 3.6[ CAMERA_DEVICE_API_VERSION_3_6 ] + * + * This is the current recommended version of the camera device HAL. + * + * Supports the android.hardware.Camera API, and as of v3.2, the + * android.hardware.camera2 API as LIMITED or above hardware level. + * + * Camera devices that support this version of the HAL must return + * CAMERA_DEVICE_API_VERSION_3_6 in camera_device_t.common.version and in + * camera_info_t.device_version (from camera_module_t.get_camera_info). + * + * CAMERA_DEVICE_API_VERSION_3_3 and above: + * Camera modules that may contain version 3.3 or above devices must + * implement at least version 2.2 of the camera module interface (as defined + * by camera_module_t.common.module_api_version). + * + * CAMERA_DEVICE_API_VERSION_3_2: + * Camera modules that may contain version 3.2 devices must implement at + * least version 2.2 of the camera module interface (as defined by + * camera_module_t.common.module_api_version). + * + * <= CAMERA_DEVICE_API_VERSION_3_1: + * Camera modules that may contain version 3.1 (or 3.0) devices must + * implement at least version 2.0 of the camera module interface + * (as defined by camera_module_t.common.module_api_version). + * + * See camera_common.h for more versioning details. + * + * Documentation index: + * S1. Version history + * S2. Startup and operation sequencing + * S3. Operational modes + * S4. 3A modes and state machines + * S5. Cropping + * S6. Error management + * S7. Key Performance Indicator (KPI) glossary + * S8. Sample Use Cases + * S9. Notes on Controls and Metadata + * S10. Reprocessing flow and controls + */ + +/** + * S1. Version history: + * + * 1.0: Initial Android camera HAL (Android 4.0) [camera.h]: + * + * - Converted from C++ CameraHardwareInterface abstraction layer. + * + * - Supports android.hardware.Camera API. + * + * 2.0: Initial release of expanded-capability HAL (Android 4.2) [camera2.h]: + * + * - Sufficient for implementing existing android.hardware.Camera API. + * + * - Allows for ZSL queue in camera service layer + * + * - Not tested for any new features such manual capture control, Bayer RAW + * capture, reprocessing of RAW data. + * + * 3.0: First revision of expanded-capability HAL: + * + * - Major version change since the ABI is completely different. No change to + * the required hardware capabilities or operational model from 2.0. + * + * - Reworked input request and stream queue interfaces: Framework calls into + * HAL with next request and stream buffers already dequeued. Sync framework + * support is included, necessary for efficient implementations. + * + * - Moved triggers into requests, most notifications into results. + * + * - Consolidated all callbacks into framework into one structure, and all + * setup methods into a single initialize() call. + * + * - Made stream configuration into a single call to simplify stream + * management. Bidirectional streams replace STREAM_FROM_STREAM construct. + * + * - Limited mode semantics for older/limited hardware devices. + * + * 3.1: Minor revision of expanded-capability HAL: + * + * - configure_streams passes consumer usage flags to the HAL. + * + * - flush call to drop all in-flight requests/buffers as fast as possible. + * + * 3.2: Minor revision of expanded-capability HAL: + * + * - Deprecates get_metadata_vendor_tag_ops. Please use get_vendor_tag_ops + * in camera_common.h instead. + * + * - register_stream_buffers deprecated. All gralloc buffers provided + * by framework to HAL in process_capture_request may be new at any time. + * + * - add partial result support. process_capture_result may be called + * multiple times with a subset of the available result before the full + * result is available. + * + * - add manual template to camera3_request_template. The applications may + * use this template to control the capture settings directly. + * + * - Rework the bidirectional and input stream specifications. + * + * - change the input buffer return path. The buffer is returned in + * process_capture_result instead of process_capture_request. + * + * 3.3: Minor revision of expanded-capability HAL: + * + * - OPAQUE and YUV reprocessing API updates. + * + * - Basic support for depth output buffers. + * + * - Addition of data_space field to camera3_stream_t. + * + * - Addition of rotation field to camera3_stream_t. + * + * - Addition of camera3 stream configuration operation mode to camera3_stream_configuration_t + * + * 3.4: Minor additions to supported metadata and changes to data_space support + * + * - Add ANDROID_SENSOR_OPAQUE_RAW_SIZE static metadata as mandatory if + * RAW_OPAQUE format is supported. + * + * - Add ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE static metadata as + * mandatory if any RAW format is supported + * + * - Switch camera3_stream_t data_space field to a more flexible definition, + * using the version 0 definition of dataspace encoding. + * + * - General metadata additions which are available to use for HALv3.2 or + * newer: + * - ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3 + * - ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST + * - ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE + * - ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL + * - ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL + * - ANDROID_SENSOR_OPAQUE_RAW_SIZE + * - ANDROID_SENSOR_OPTICAL_BLACK_REGIONS + * + * 3.5: Minor revisions to support session parameters and logical multi camera: + * + * - Add ANDROID_REQUEST_AVAILABLE_SESSION_KEYS static metadata, which is + * optional for implementations that want to support session parameters. If support is + * needed, then Hal should populate the list with all available capture request keys + * that can cause severe processing delays when modified by client. Typical examples + * include parameters that require time-consuming HW re-configuration or internal camera + * pipeline update. + * + * - Add a session parameter field to camera3_stream_configuration which can be populated + * by clients with initial values for the keys found in ANDROID_REQUEST_AVAILABLE_SESSION_KEYS. + * + * - Metadata additions for logical multi camera capability: + * - ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA + * - ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS + * - ANDROID_LOGICAL_MULTI_CAMERA_SYNC_TYPE + * + * - Add physical camera id field in camera3_stream, so that for a logical + * multi camera, the application has the option to specify which physical camera + * a particular stream is configured on. + * + * - Add physical camera id and settings field in camera3_capture_request, so that + * for a logical multi camera, the application has the option to specify individual + * settings for a particular physical device. + * + * 3.6: Minor revisions to support HAL buffer management APIs: + * + * - Add ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION static metadata, which allows HAL to + * opt in to the new buffer management APIs described below. + * + * - Add request_stream_buffers() and return_stream_buffers() to camera3_callback_ops_t for HAL to + * request and return output buffers from camera service. + * + * - Add signal_stream_flush() to camera3_device_ops_t for camera service to notify HAL an + * upcoming configure_streams() call requires HAL to return buffers of certain streams. + * + * - Add CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID to support BLOB with only JPEG apps + * segments and thumbnail (without main image bitstream). Camera framework + * uses such stream togerther with a HAL YUV_420_888/IMPLEMENTATION_DEFINED + * stream to encode HEIC (ISO/IEC 23008-12) image. + * + * - Add is_reconfiguration_required() to camera3_device_ops_t to enable HAL to skip or + * trigger stream reconfiguration depending on new session parameter values. + * + */ + +/** + * S2. Startup and general expected operation sequence: + * + * 1. Framework calls camera_module_t->common.open(), which returns a + * hardware_device_t structure. + * + * 2. Framework inspects the hardware_device_t->version field, and instantiates + * the appropriate handler for that version of the camera hardware device. In + * case the version is CAMERA_DEVICE_API_VERSION_3_0, the device is cast to + * a camera3_device_t. + * + * 3. Framework calls camera3_device_t->ops->initialize() with the framework + * callback function pointers. This will only be called this one time after + * open(), before any other functions in the ops structure are called. + * + * 4. The framework calls camera3_device_t->ops->configure_streams() with a list + * of input/output streams to the HAL device. + * + * 5. <= CAMERA_DEVICE_API_VERSION_3_1: + * + * The framework allocates gralloc buffers and calls + * camera3_device_t->ops->register_stream_buffers() for at least one of the + * output streams listed in configure_streams. The same stream is registered + * only once. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * camera3_device_t->ops->register_stream_buffers() is not called and must + * be NULL. + * + * 6. The framework requests default settings for some number of use cases with + * calls to camera3_device_t->ops->construct_default_request_settings(). This + * may occur any time after step 3. + * + * 7. The framework constructs and sends the first capture request to the HAL, + * with settings based on one of the sets of default settings, and with at + * least one output stream, which has been registered earlier by the + * framework. This is sent to the HAL with + * camera3_device_t->ops->process_capture_request(). The HAL must block the + * return of this call until it is ready for the next request to be sent. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * The buffer_handle_t provided in the camera3_stream_buffer_t array + * in the camera3_capture_request_t may be new and never-before-seen + * by the HAL on any given new request. + * + * 8. The framework continues to submit requests, and call + * construct_default_request_settings to get default settings buffers for + * other use cases. + * + * <= CAMERA_DEVICE_API_VERSION_3_1: + * + * The framework may call register_stream_buffers() at this time for + * not-yet-registered streams. + * + * 9. When the capture of a request begins (sensor starts exposing for the + * capture) or processing a reprocess request begins, the HAL + * calls camera3_callback_ops_t->notify() with the SHUTTER event, including + * the frame number and the timestamp for start of exposure. For a reprocess + * request, the timestamp must be the start of exposure of the input image + * which can be looked up with android.sensor.timestamp from + * camera3_capture_request_t.settings when process_capture_request() is + * called. + * + * <= CAMERA_DEVICE_API_VERSION_3_1: + * + * This notify call must be made before the first call to + * process_capture_result() for that frame number. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * The camera3_callback_ops_t->notify() call with the SHUTTER event should + * be made as early as possible since the framework will be unable to + * deliver gralloc buffers to the application layer (for that frame) until + * it has a valid timestamp for the start of exposure (or the input image's + * start of exposure for a reprocess request). + * + * Both partial metadata results and the gralloc buffers may be sent to the + * framework at any time before or after the SHUTTER event. + * + * 10. After some pipeline delay, the HAL begins to return completed captures to + * the framework with camera3_callback_ops_t->process_capture_result(). These + * are returned in the same order as the requests were submitted. Multiple + * requests can be in flight at once, depending on the pipeline depth of the + * camera HAL device. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * Once a buffer is returned by process_capture_result as part of the + * camera3_stream_buffer_t array, and the fence specified by release_fence + * has been signaled (this is a no-op for -1 fences), the ownership of that + * buffer is considered to be transferred back to the framework. After that, + * the HAL must no longer retain that particular buffer, and the + * framework may clean up the memory for it immediately. + * + * process_capture_result may be called multiple times for a single frame, + * each time with a new disjoint piece of metadata and/or set of gralloc + * buffers. The framework will accumulate these partial metadata results + * into one result. + * + * In particular, it is legal for a process_capture_result to be called + * simultaneously for both a frame N and a frame N+1 as long as the + * above rule holds for gralloc buffers (both input and output). + * + * 11. After some time, the framework may stop submitting new requests, wait for + * the existing captures to complete (all buffers filled, all results + * returned), and then call configure_streams() again. This resets the camera + * hardware and pipeline for a new set of input/output streams. Some streams + * may be reused from the previous configuration; if these streams' buffers + * had already been registered with the HAL, they will not be registered + * again. The framework then continues from step 7, if at least one + * registered output stream remains (otherwise, step 5 is required first). + * + * 12. Alternatively, the framework may call camera3_device_t->common->close() + * to end the camera session. This may be called at any time when no other + * calls from the framework are active, although the call may block until all + * in-flight captures have completed (all results returned, all buffers + * filled). After the close call returns, no more calls to the + * camera3_callback_ops_t functions are allowed from the HAL. Once the + * close() call is underway, the framework may not call any other HAL device + * functions. + * + * 13. In case of an error or other asynchronous event, the HAL must call + * camera3_callback_ops_t->notify() with the appropriate error/event + * message. After returning from a fatal device-wide error notification, the + * HAL should act as if close() had been called on it. However, the HAL must + * either cancel or complete all outstanding captures before calling + * notify(), so that once notify() is called with a fatal error, the + * framework will not receive further callbacks from the device. Methods + * besides close() should return -ENODEV or NULL after the notify() method + * returns from a fatal error message. + */ + +/** + * S3. Operational modes: + * + * The camera 3 HAL device can implement one of two possible operational modes; + * limited and full. Full support is expected from new higher-end + * devices. Limited mode has hardware requirements roughly in line with those + * for a camera HAL device v1 implementation, and is expected from older or + * inexpensive devices. Full is a strict superset of limited, and they share the + * same essential operational flow, as documented above. + * + * The HAL must indicate its level of support with the + * android.info.supportedHardwareLevel static metadata entry, with 0 indicating + * limited mode, and 1 indicating full mode support. + * + * Roughly speaking, limited-mode devices do not allow for application control + * of capture settings (3A control only), high-rate capture of high-resolution + * images, raw sensor readout, or support for YUV output streams above maximum + * recording resolution (JPEG only for large images). + * + * ** Details of limited mode behavior: + * + * - Limited-mode devices do not need to implement accurate synchronization + * between capture request settings and the actual image data + * captured. Instead, changes to settings may take effect some time in the + * future, and possibly not for the same output frame for each settings + * entry. Rapid changes in settings may result in some settings never being + * used for a capture. However, captures that include high-resolution output + * buffers ( > 1080p ) have to use the settings as specified (but see below + * for processing rate). + * + * - Limited-mode devices do not need to support most of the + * settings/result/static info metadata. Specifically, only the following settings + * are expected to be consumed or produced by a limited-mode HAL device: + * + * android.control.aeAntibandingMode (controls and dynamic) + * android.control.aeExposureCompensation (controls and dynamic) + * android.control.aeLock (controls and dynamic) + * android.control.aeMode (controls and dynamic) + * android.control.aeRegions (controls and dynamic) + * android.control.aeTargetFpsRange (controls and dynamic) + * android.control.aePrecaptureTrigger (controls and dynamic) + * android.control.afMode (controls and dynamic) + * android.control.afRegions (controls and dynamic) + * android.control.awbLock (controls and dynamic) + * android.control.awbMode (controls and dynamic) + * android.control.awbRegions (controls and dynamic) + * android.control.captureIntent (controls and dynamic) + * android.control.effectMode (controls and dynamic) + * android.control.mode (controls and dynamic) + * android.control.sceneMode (controls and dynamic) + * android.control.videoStabilizationMode (controls and dynamic) + * android.control.aeAvailableAntibandingModes (static) + * android.control.aeAvailableModes (static) + * android.control.aeAvailableTargetFpsRanges (static) + * android.control.aeCompensationRange (static) + * android.control.aeCompensationStep (static) + * android.control.afAvailableModes (static) + * android.control.availableEffects (static) + * android.control.availableSceneModes (static) + * android.control.availableVideoStabilizationModes (static) + * android.control.awbAvailableModes (static) + * android.control.maxRegions (static) + * android.control.sceneModeOverrides (static) + * android.control.aeState (dynamic) + * android.control.afState (dynamic) + * android.control.awbState (dynamic) + * + * android.flash.mode (controls and dynamic) + * android.flash.info.available (static) + * + * android.info.supportedHardwareLevel (static) + * + * android.jpeg.gpsCoordinates (controls and dynamic) + * android.jpeg.gpsProcessingMethod (controls and dynamic) + * android.jpeg.gpsTimestamp (controls and dynamic) + * android.jpeg.orientation (controls and dynamic) + * android.jpeg.quality (controls and dynamic) + * android.jpeg.thumbnailQuality (controls and dynamic) + * android.jpeg.thumbnailSize (controls and dynamic) + * android.jpeg.availableThumbnailSizes (static) + * android.jpeg.maxSize (static) + * + * android.lens.info.minimumFocusDistance (static) + * + * android.request.id (controls and dynamic) + * + * android.scaler.cropRegion (controls and dynamic) + * android.scaler.availableStreamConfigurations (static) + * android.scaler.availableMinFrameDurations (static) + * android.scaler.availableStallDurations (static) + * android.scaler.availableMaxDigitalZoom (static) + * android.scaler.maxDigitalZoom (static) + * android.scaler.croppingType (static) + * + * android.sensor.orientation (static) + * android.sensor.timestamp (dynamic) + * + * android.statistics.faceDetectMode (controls and dynamic) + * android.statistics.info.availableFaceDetectModes (static) + * android.statistics.faceIds (dynamic) + * android.statistics.faceLandmarks (dynamic) + * android.statistics.faceRectangles (dynamic) + * android.statistics.faceScores (dynamic) + * + * android.sync.frameNumber (dynamic) + * android.sync.maxLatency (static) + * + * - Captures in limited mode that include high-resolution (> 1080p) output + * buffers may block in process_capture_request() until all the output buffers + * have been filled. A full-mode HAL device must process sequences of + * high-resolution requests at the rate indicated in the static metadata for + * that pixel format. The HAL must still call process_capture_result() to + * provide the output; the framework must simply be prepared for + * process_capture_request() to block until after process_capture_result() for + * that request completes for high-resolution captures for limited-mode + * devices. + * + * - Full-mode devices must support below additional capabilities: + * - 30fps at maximum resolution is preferred, more than 20fps is required. + * - Per frame control (android.sync.maxLatency == PER_FRAME_CONTROL). + * - Sensor manual control metadata. See MANUAL_SENSOR defined in + * android.request.availableCapabilities. + * - Post-processing manual control metadata. See MANUAL_POST_PROCESSING defined + * in android.request.availableCapabilities. + * + */ + +/** + * S4. 3A modes and state machines: + * + * While the actual 3A algorithms are up to the HAL implementation, a high-level + * state machine description is defined by the HAL interface, to allow the HAL + * device and the framework to communicate about the current state of 3A, and to + * trigger 3A events. + * + * When the device is opened, all the individual 3A states must be + * STATE_INACTIVE. Stream configuration does not reset 3A. For example, locked + * focus must be maintained across the configure() call. + * + * Triggering a 3A action involves simply setting the relevant trigger entry in + * the settings for the next request to indicate start of trigger. For example, + * the trigger for starting an autofocus scan is setting the entry + * ANDROID_CONTROL_AF_TRIGGER to ANDROID_CONTROL_AF_TRIGGER_START for one + * request, and cancelling an autofocus scan is triggered by setting + * ANDROID_CONTROL_AF_TRIGGER to ANDROID_CONTRL_AF_TRIGGER_CANCEL. Otherwise, + * the entry will not exist, or be set to ANDROID_CONTROL_AF_TRIGGER_IDLE. Each + * request with a trigger entry set to a non-IDLE value will be treated as an + * independent triggering event. + * + * At the top level, 3A is controlled by the ANDROID_CONTROL_MODE setting, which + * selects between no 3A (ANDROID_CONTROL_MODE_OFF), normal AUTO mode + * (ANDROID_CONTROL_MODE_AUTO), and using the scene mode setting + * (ANDROID_CONTROL_USE_SCENE_MODE). + * + * - In OFF mode, each of the individual AE/AF/AWB modes are effectively OFF, + * and none of the capture controls may be overridden by the 3A routines. + * + * - In AUTO mode, Auto-focus, auto-exposure, and auto-whitebalance all run + * their own independent algorithms, and have their own mode, state, and + * trigger metadata entries, as listed in the next section. + * + * - In USE_SCENE_MODE, the value of the ANDROID_CONTROL_SCENE_MODE entry must + * be used to determine the behavior of 3A routines. In SCENE_MODEs other than + * FACE_PRIORITY, the HAL must override the values of + * ANDROId_CONTROL_AE/AWB/AF_MODE to be the mode it prefers for the selected + * SCENE_MODE. For example, the HAL may prefer SCENE_MODE_NIGHT to use + * CONTINUOUS_FOCUS AF mode. Any user selection of AE/AWB/AF_MODE when scene + * must be ignored for these scene modes. + * + * - For SCENE_MODE_FACE_PRIORITY, the AE/AWB/AF_MODE controls work as in + * ANDROID_CONTROL_MODE_AUTO, but the 3A routines must bias toward metering + * and focusing on any detected faces in the scene. + * + * S4.1. Auto-focus settings and result entries: + * + * Main metadata entries: + * + * ANDROID_CONTROL_AF_MODE: Control for selecting the current autofocus + * mode. Set by the framework in the request settings. + * + * AF_MODE_OFF: AF is disabled; the framework/app directly controls lens + * position. + * + * AF_MODE_AUTO: Single-sweep autofocus. No lens movement unless AF is + * triggered. + * + * AF_MODE_MACRO: Single-sweep up-close autofocus. No lens movement unless + * AF is triggered. + * + * AF_MODE_CONTINUOUS_VIDEO: Smooth continuous focusing, for recording + * video. Triggering immediately locks focus in current + * position. Canceling resumes cotinuous focusing. + * + * AF_MODE_CONTINUOUS_PICTURE: Fast continuous focusing, for + * zero-shutter-lag still capture. Triggering locks focus once currently + * active sweep concludes. Canceling resumes continuous focusing. + * + * AF_MODE_EDOF: Advanced extended depth of field focusing. There is no + * autofocus scan, so triggering one or canceling one has no effect. + * Images are focused automatically by the HAL. + * + * ANDROID_CONTROL_AF_STATE: Dynamic metadata describing the current AF + * algorithm state, reported by the HAL in the result metadata. + * + * AF_STATE_INACTIVE: No focusing has been done, or algorithm was + * reset. Lens is not moving. Always the state for MODE_OFF or MODE_EDOF. + * When the device is opened, it must start in this state. + * + * AF_STATE_PASSIVE_SCAN: A continuous focus algorithm is currently scanning + * for good focus. The lens is moving. + * + * AF_STATE_PASSIVE_FOCUSED: A continuous focus algorithm believes it is + * well focused. The lens is not moving. The HAL may spontaneously leave + * this state. + * + * AF_STATE_PASSIVE_UNFOCUSED: A continuous focus algorithm believes it is + * not well focused. The lens is not moving. The HAL may spontaneously + * leave this state. + * + * AF_STATE_ACTIVE_SCAN: A scan triggered by the user is underway. + * + * AF_STATE_FOCUSED_LOCKED: The AF algorithm believes it is focused. The + * lens is not moving. + * + * AF_STATE_NOT_FOCUSED_LOCKED: The AF algorithm has been unable to + * focus. The lens is not moving. + * + * ANDROID_CONTROL_AF_TRIGGER: Control for starting an autofocus scan, the + * meaning of which is mode- and state- dependent. Set by the framework in + * the request settings. + * + * AF_TRIGGER_IDLE: No current trigger. + * + * AF_TRIGGER_START: Trigger start of AF scan. Effect is mode and state + * dependent. + * + * AF_TRIGGER_CANCEL: Cancel current AF scan if any, and reset algorithm to + * default. + * + * Additional metadata entries: + * + * ANDROID_CONTROL_AF_REGIONS: Control for selecting the regions of the FOV + * that should be used to determine good focus. This applies to all AF + * modes that scan for focus. Set by the framework in the request + * settings. + * + * S4.2. Auto-exposure settings and result entries: + * + * Main metadata entries: + * + * ANDROID_CONTROL_AE_MODE: Control for selecting the current auto-exposure + * mode. Set by the framework in the request settings. + * + * AE_MODE_OFF: Autoexposure is disabled; the user controls exposure, gain, + * frame duration, and flash. + * + * AE_MODE_ON: Standard autoexposure, with flash control disabled. User may + * set flash to fire or to torch mode. + * + * AE_MODE_ON_AUTO_FLASH: Standard autoexposure, with flash on at HAL's + * discretion for precapture and still capture. User control of flash + * disabled. + * + * AE_MODE_ON_ALWAYS_FLASH: Standard autoexposure, with flash always fired + * for capture, and at HAL's discretion for precapture.. User control of + * flash disabled. + * + * AE_MODE_ON_AUTO_FLASH_REDEYE: Standard autoexposure, with flash on at + * HAL's discretion for precapture and still capture. Use a flash burst + * at end of precapture sequence to reduce redeye in the final + * picture. User control of flash disabled. + * + * ANDROID_CONTROL_AE_STATE: Dynamic metadata describing the current AE + * algorithm state, reported by the HAL in the result metadata. + * + * AE_STATE_INACTIVE: Initial AE state after mode switch. When the device is + * opened, it must start in this state. + * + * AE_STATE_SEARCHING: AE is not converged to a good value, and is adjusting + * exposure parameters. + * + * AE_STATE_CONVERGED: AE has found good exposure values for the current + * scene, and the exposure parameters are not changing. HAL may + * spontaneously leave this state to search for better solution. + * + * AE_STATE_LOCKED: AE has been locked with the AE_LOCK control. Exposure + * values are not changing. + * + * AE_STATE_FLASH_REQUIRED: The HAL has converged exposure, but believes + * flash is required for a sufficiently bright picture. Used for + * determining if a zero-shutter-lag frame can be used. + * + * AE_STATE_PRECAPTURE: The HAL is in the middle of a precapture + * sequence. Depending on AE mode, this mode may involve firing the + * flash for metering, or a burst of flash pulses for redeye reduction. + * + * ANDROID_CONTROL_AE_PRECAPTURE_TRIGGER: Control for starting a metering + * sequence before capturing a high-quality image. Set by the framework in + * the request settings. + * + * PRECAPTURE_TRIGGER_IDLE: No current trigger. + * + * PRECAPTURE_TRIGGER_START: Start a precapture sequence. The HAL should + * use the subsequent requests to measure good exposure/white balance + * for an upcoming high-resolution capture. + * + * Additional metadata entries: + * + * ANDROID_CONTROL_AE_LOCK: Control for locking AE controls to their current + * values + * + * ANDROID_CONTROL_AE_EXPOSURE_COMPENSATION: Control for adjusting AE + * algorithm target brightness point. + * + * ANDROID_CONTROL_AE_TARGET_FPS_RANGE: Control for selecting the target frame + * rate range for the AE algorithm. The AE routine cannot change the frame + * rate to be outside these bounds. + * + * ANDROID_CONTROL_AE_REGIONS: Control for selecting the regions of the FOV + * that should be used to determine good exposure levels. This applies to + * all AE modes besides OFF. + * + * S4.3. Auto-whitebalance settings and result entries: + * + * Main metadata entries: + * + * ANDROID_CONTROL_AWB_MODE: Control for selecting the current white-balance + * mode. + * + * AWB_MODE_OFF: Auto-whitebalance is disabled. User controls color matrix. + * + * AWB_MODE_AUTO: Automatic white balance is enabled; 3A controls color + * transform, possibly using more complex transforms than a simple + * matrix. + * + * AWB_MODE_INCANDESCENT: Fixed white balance settings good for indoor + * incandescent (tungsten) lighting, roughly 2700K. + * + * AWB_MODE_FLUORESCENT: Fixed white balance settings good for fluorescent + * lighting, roughly 5000K. + * + * AWB_MODE_WARM_FLUORESCENT: Fixed white balance settings good for + * fluorescent lighting, roughly 3000K. + * + * AWB_MODE_DAYLIGHT: Fixed white balance settings good for daylight, + * roughly 5500K. + * + * AWB_MODE_CLOUDY_DAYLIGHT: Fixed white balance settings good for clouded + * daylight, roughly 6500K. + * + * AWB_MODE_TWILIGHT: Fixed white balance settings good for + * near-sunset/sunrise, roughly 15000K. + * + * AWB_MODE_SHADE: Fixed white balance settings good for areas indirectly + * lit by the sun, roughly 7500K. + * + * ANDROID_CONTROL_AWB_STATE: Dynamic metadata describing the current AWB + * algorithm state, reported by the HAL in the result metadata. + * + * AWB_STATE_INACTIVE: Initial AWB state after mode switch. When the device + * is opened, it must start in this state. + * + * AWB_STATE_SEARCHING: AWB is not converged to a good value, and is + * changing color adjustment parameters. + * + * AWB_STATE_CONVERGED: AWB has found good color adjustment values for the + * current scene, and the parameters are not changing. HAL may + * spontaneously leave this state to search for better solution. + * + * AWB_STATE_LOCKED: AWB has been locked with the AWB_LOCK control. Color + * adjustment values are not changing. + * + * Additional metadata entries: + * + * ANDROID_CONTROL_AWB_LOCK: Control for locking AWB color adjustments to + * their current values. + * + * ANDROID_CONTROL_AWB_REGIONS: Control for selecting the regions of the FOV + * that should be used to determine good color balance. This applies only + * to auto-WB mode. + * + * S4.4. General state machine transition notes + * + * Switching between AF, AE, or AWB modes always resets the algorithm's state + * to INACTIVE. Similarly, switching between CONTROL_MODE or + * CONTROL_SCENE_MODE if CONTROL_MODE == USE_SCENE_MODE resets all the + * algorithm states to INACTIVE. + * + * The tables below are per-mode. + * + * S4.5. AF state machines + * + * when enabling AF or changing AF mode + *| state | trans. cause | new state | notes | + *+--------------------+---------------+--------------------+------------------+ + *| Any | AF mode change| INACTIVE | | + *+--------------------+---------------+--------------------+------------------+ + * + * mode = AF_MODE_OFF or AF_MODE_EDOF + *| state | trans. cause | new state | notes | + *+--------------------+---------------+--------------------+------------------+ + *| INACTIVE | | INACTIVE | Never changes | + *+--------------------+---------------+--------------------+------------------+ + * + * mode = AF_MODE_AUTO or AF_MODE_MACRO + *| state | trans. cause | new state | notes | + *+--------------------+---------------+--------------------+------------------+ + *| INACTIVE | AF_TRIGGER | ACTIVE_SCAN | Start AF sweep | + *| | | | Lens now moving | + *+--------------------+---------------+--------------------+------------------+ + *| ACTIVE_SCAN | AF sweep done | FOCUSED_LOCKED | If AF successful | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| ACTIVE_SCAN | AF sweep done | NOT_FOCUSED_LOCKED | If AF successful | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| ACTIVE_SCAN | AF_CANCEL | INACTIVE | Cancel/reset AF | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF | + *+--------------------+---------------+--------------------+------------------+ + *| FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep | + *| | | | Lens now moving | + *+--------------------+---------------+--------------------+------------------+ + *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF | + *+--------------------+---------------+--------------------+------------------+ + *| NOT_FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep | + *| | | | Lens now moving | + *+--------------------+---------------+--------------------+------------------+ + *| All states | mode change | INACTIVE | | + *+--------------------+---------------+--------------------+------------------+ + * + * mode = AF_MODE_CONTINUOUS_VIDEO + *| state | trans. cause | new state | notes | + *+--------------------+---------------+--------------------+------------------+ + *| INACTIVE | HAL initiates | PASSIVE_SCAN | Start AF scan | + *| | new scan | | Lens now moving | + *+--------------------+---------------+--------------------+------------------+ + *| INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | HAL completes | PASSIVE_FOCUSED | End AF scan | + *| | current scan | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | HAL fails | PASSIVE_UNFOCUSED | End AF scan | + *| | current scan | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | + *| | | | if focus is good | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | + *| | | | if focus is bad | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens | + *| | | | position | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_FOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | + *| | new scan | | Lens now moving | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_UNFOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | + *| | new scan | | Lens now moving | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect | + *+--------------------+---------------+--------------------+------------------+ + *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | + *+--------------------+---------------+--------------------+------------------+ + *| NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect | + *+--------------------+---------------+--------------------+------------------+ + *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | + *+--------------------+---------------+--------------------+------------------+ + * + * mode = AF_MODE_CONTINUOUS_PICTURE + *| state | trans. cause | new state | notes | + *+--------------------+---------------+--------------------+------------------+ + *| INACTIVE | HAL initiates | PASSIVE_SCAN | Start AF scan | + *| | new scan | | Lens now moving | + *+--------------------+---------------+--------------------+------------------+ + *| INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | HAL completes | PASSIVE_FOCUSED | End AF scan | + *| | current scan | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | HAL fails | PASSIVE_UNFOCUSED | End AF scan | + *| | current scan | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Eventual trans. | + *| | | | once focus good | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Eventual trans. | + *| | | | if cannot focus | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens | + *| | | | position | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_FOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | + *| | new scan | | Lens now moving | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_UNFOCUSED | HAL initiates | PASSIVE_SCAN | Start AF scan | + *| | new scan | | Lens now moving | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. | + *| | | | Lens now locked | + *+--------------------+---------------+--------------------+------------------+ + *| FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect | + *+--------------------+---------------+--------------------+------------------+ + *| FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | + *+--------------------+---------------+--------------------+------------------+ + *| NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect | + *+--------------------+---------------+--------------------+------------------+ + *| NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan | + *+--------------------+---------------+--------------------+------------------+ + * + * S4.6. AE and AWB state machines + * + * The AE and AWB state machines are mostly identical. AE has additional + * FLASH_REQUIRED and PRECAPTURE states. So rows below that refer to those two + * states should be ignored for the AWB state machine. + * + * when enabling AE/AWB or changing AE/AWB mode + *| state | trans. cause | new state | notes | + *+--------------------+---------------+--------------------+------------------+ + *| Any | mode change | INACTIVE | | + *+--------------------+---------------+--------------------+------------------+ + * + * mode = AE_MODE_OFF / AWB mode not AUTO + *| state | trans. cause | new state | notes | + *+--------------------+---------------+--------------------+------------------+ + *| INACTIVE | | INACTIVE | AE/AWB disabled | + *+--------------------+---------------+--------------------+------------------+ + * + * mode = AE_MODE_ON_* / AWB_MODE_AUTO + *| state | trans. cause | new state | notes | + *+--------------------+---------------+--------------------+------------------+ + *| INACTIVE | HAL initiates | SEARCHING | | + *| | AE/AWB scan | | | + *+--------------------+---------------+--------------------+------------------+ + *| INACTIVE | AE/AWB_LOCK | LOCKED | values locked | + *| | on | | | + *+--------------------+---------------+--------------------+------------------+ + *| SEARCHING | HAL finishes | CONVERGED | good values, not | + *| | AE/AWB scan | | changing | + *+--------------------+---------------+--------------------+------------------+ + *| SEARCHING | HAL finishes | FLASH_REQUIRED | converged but too| + *| | AE scan | | dark w/o flash | + *+--------------------+---------------+--------------------+------------------+ + *| SEARCHING | AE/AWB_LOCK | LOCKED | values locked | + *| | on | | | + *+--------------------+---------------+--------------------+------------------+ + *| CONVERGED | HAL initiates | SEARCHING | values locked | + *| | AE/AWB scan | | | + *+--------------------+---------------+--------------------+------------------+ + *| CONVERGED | AE/AWB_LOCK | LOCKED | values locked | + *| | on | | | + *+--------------------+---------------+--------------------+------------------+ + *| FLASH_REQUIRED | HAL initiates | SEARCHING | values locked | + *| | AE/AWB scan | | | + *+--------------------+---------------+--------------------+------------------+ + *| FLASH_REQUIRED | AE/AWB_LOCK | LOCKED | values locked | + *| | on | | | + *+--------------------+---------------+--------------------+------------------+ + *| LOCKED | AE/AWB_LOCK | SEARCHING | values not good | + *| | off | | after unlock | + *+--------------------+---------------+--------------------+------------------+ + *| LOCKED | AE/AWB_LOCK | CONVERGED | values good | + *| | off | | after unlock | + *+--------------------+---------------+--------------------+------------------+ + *| LOCKED | AE_LOCK | FLASH_REQUIRED | exposure good, | + *| | off | | but too dark | + *+--------------------+---------------+--------------------+------------------+ + *| All AE states | PRECAPTURE_ | PRECAPTURE | Start precapture | + *| | START | | sequence | + *+--------------------+---------------+--------------------+------------------+ + *| PRECAPTURE | Sequence done.| CONVERGED | Ready for high- | + *| | AE_LOCK off | | quality capture | + *+--------------------+---------------+--------------------+------------------+ + *| PRECAPTURE | Sequence done.| LOCKED | Ready for high- | + *| | AE_LOCK on | | quality capture | + *+--------------------+---------------+--------------------+------------------+ + * + */ + +/** + * S5. Cropping: + * + * Cropping of the full pixel array (for digital zoom and other use cases where + * a smaller FOV is desirable) is communicated through the + * ANDROID_SCALER_CROP_REGION setting. This is a per-request setting, and can + * change on a per-request basis, which is critical for implementing smooth + * digital zoom. + * + * The region is defined as a rectangle (x, y, width, height), with (x, y) + * describing the top-left corner of the rectangle. The rectangle is defined on + * the coordinate system of the sensor active pixel array, with (0,0) being the + * top-left pixel of the active pixel array. Therefore, the width and height + * cannot be larger than the dimensions reported in the + * ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY static info field. The minimum allowed + * width and height are reported by the HAL through the + * ANDROID_SCALER_MAX_DIGITAL_ZOOM static info field, which describes the + * maximum supported zoom factor. Therefore, the minimum crop region width and + * height are: + * + * {width, height} = + * { floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[0] / + * ANDROID_SCALER_MAX_DIGITAL_ZOOM), + * floor(ANDROID_SENSOR_ACTIVE_PIXEL_ARRAY[1] / + * ANDROID_SCALER_MAX_DIGITAL_ZOOM) } + * + * If the crop region needs to fulfill specific requirements (for example, it + * needs to start on even coordinates, and its width/height needs to be even), + * the HAL must do the necessary rounding and write out the final crop region + * used in the output result metadata. Similarly, if the HAL implements video + * stabilization, it must adjust the result crop region to describe the region + * actually included in the output after video stabilization is applied. In + * general, a camera-using application must be able to determine the field of + * view it is receiving based on the crop region, the dimensions of the image + * sensor, and the lens focal length. + * + * It is assumed that the cropping is applied after raw to other color space + * conversion. Raw streams (RAW16 and RAW_OPAQUE) don't have this conversion stage, + * and are not croppable. Therefore, the crop region must be ignored by the HAL + * for raw streams. + * + * Since the crop region applies to all non-raw streams, which may have different aspect + * ratios than the crop region, the exact sensor region used for each stream may + * be smaller than the crop region. Specifically, each stream should maintain + * square pixels and its aspect ratio by minimally further cropping the defined + * crop region. If the stream's aspect ratio is wider than the crop region, the + * stream should be further cropped vertically, and if the stream's aspect ratio + * is narrower than the crop region, the stream should be further cropped + * horizontally. + * + * In all cases, the stream crop must be centered within the full crop region, + * and each stream is only either cropped horizontally or vertical relative to + * the full crop region, never both. + * + * For example, if two streams are defined, a 640x480 stream (4:3 aspect), and a + * 1280x720 stream (16:9 aspect), below demonstrates the expected output regions + * for each stream for a few sample crop regions, on a hypothetical 3 MP (2000 x + * 1500 pixel array) sensor. + * + * Crop region: (500, 375, 1000, 750) (4:3 aspect ratio) + * + * 640x480 stream crop: (500, 375, 1000, 750) (equal to crop region) + * 1280x720 stream crop: (500, 469, 1000, 562) (marked with =) + * + * 0 1000 2000 + * +---------+---------+---------+----------+ + * | Active pixel array | + * | | + * | | + * + +-------------------+ + 375 + * | | | | + * | O===================O | + * | I 1280x720 stream I | + * + I I + 750 + * | I I | + * | O===================O | + * | | | | + * + +-------------------+ + 1125 + * | Crop region, 640x480 stream | + * | | + * | | + * +---------+---------+---------+----------+ 1500 + * + * Crop region: (500, 375, 1333, 750) (16:9 aspect ratio) + * + * 640x480 stream crop: (666, 375, 1000, 750) (marked with =) + * 1280x720 stream crop: (500, 375, 1333, 750) (equal to crop region) + * + * 0 1000 2000 + * +---------+---------+---------+----------+ + * | Active pixel array | + * | | + * | | + * + +---O==================O---+ + 375 + * | | I 640x480 stream I | | + * | | I I | | + * | | I I | | + * + | I I | + 750 + * | | I I | | + * | | I I | | + * | | I I | | + * + +---O==================O---+ + 1125 + * | Crop region, 1280x720 stream | + * | | + * | | + * +---------+---------+---------+----------+ 1500 + * + * Crop region: (500, 375, 750, 750) (1:1 aspect ratio) + * + * 640x480 stream crop: (500, 469, 750, 562) (marked with =) + * 1280x720 stream crop: (500, 543, 750, 414) (marged with #) + * + * 0 1000 2000 + * +---------+---------+---------+----------+ + * | Active pixel array | + * | | + * | | + * + +--------------+ + 375 + * | O==============O | + * | ################ | + * | # # | + * + # # + 750 + * | # # | + * | ################ 1280x720 | + * | O==============O 640x480 | + * + +--------------+ + 1125 + * | Crop region | + * | | + * | | + * +---------+---------+---------+----------+ 1500 + * + * And a final example, a 1024x1024 square aspect ratio stream instead of the + * 480p stream: + * + * Crop region: (500, 375, 1000, 750) (4:3 aspect ratio) + * + * 1024x1024 stream crop: (625, 375, 750, 750) (marked with #) + * 1280x720 stream crop: (500, 469, 1000, 562) (marked with =) + * + * 0 1000 2000 + * +---------+---------+---------+----------+ + * | Active pixel array | + * | | + * | 1024x1024 stream | + * + +--###############--+ + 375 + * | | # # | | + * | O===================O | + * | I 1280x720 stream I | + * + I I + 750 + * | I I | + * | O===================O | + * | | # # | | + * + +--###############--+ + 1125 + * | Crop region | + * | | + * | | + * +---------+---------+---------+----------+ 1500 + * + */ + +/** + * S6. Error management: + * + * Camera HAL device ops functions that have a return value will all return + * -ENODEV / NULL in case of a serious error. This means the device cannot + * continue operation, and must be closed by the framework. Once this error is + * returned by some method, or if notify() is called with ERROR_DEVICE, only + * the close() method can be called successfully. All other methods will return + * -ENODEV / NULL. + * + * If a device op is called in the wrong sequence, for example if the framework + * calls configure_streams() is called before initialize(), the device must + * return -ENOSYS from the call, and do nothing. + * + * Transient errors in image capture must be reported through notify() as follows: + * + * - The failure of an entire capture to occur must be reported by the HAL by + * calling notify() with ERROR_REQUEST. Individual errors for the result + * metadata or the output buffers must not be reported in this case. + * + * - If the metadata for a capture cannot be produced, but some image buffers + * were filled, the HAL must call notify() with ERROR_RESULT. + * + * - If an output image buffer could not be filled, but either the metadata was + * produced or some other buffers were filled, the HAL must call notify() with + * ERROR_BUFFER for each failed buffer. + * + * In each of these transient failure cases, the HAL must still call + * process_capture_result, with valid output and input (if an input buffer was + * submitted) buffer_handle_t. If the result metadata could not be produced, it + * should be NULL. If some buffers could not be filled, they must be returned with + * process_capture_result in the error state, their release fences must be set to + * the acquire fences passed by the framework, or -1 if they have been waited on by + * the HAL already. + * + * Invalid input arguments result in -EINVAL from the appropriate methods. In + * that case, the framework must act as if that call had never been made. + * + */ + +/** + * S7. Key Performance Indicator (KPI) glossary: + * + * This includes some critical definitions that are used by KPI metrics. + * + * Pipeline Latency: + * For a given capture request, the duration from the framework calling + * process_capture_request to the HAL sending capture result and all buffers + * back by process_capture_result call. To make the Pipeline Latency measure + * independent of frame rate, it is measured by frame count. + * + * For example, when frame rate is 30 (fps), the frame duration (time interval + * between adjacent frame capture time) is 33 (ms). + * If it takes 5 frames for framework to get the result and buffers back for + * a given request, then the Pipeline Latency is 5 (frames), instead of + * 5 x 33 = 165 (ms). + * + * The Pipeline Latency is determined by android.request.pipelineDepth and + * android.request.pipelineMaxDepth, see their definitions for more details. + * + */ + +/** + * S8. Sample Use Cases: + * + * This includes some typical use case examples the camera HAL may support. + * + * S8.1 Zero Shutter Lag (ZSL) with CAMERA3_STREAM_BIDIRECTIONAL stream. + * + * For this use case, the bidirectional stream will be used by the framework as follows: + * + * 1. The framework includes a buffer from this stream as output buffer in a + * request as normal. + * + * 2. Once the HAL device returns a filled output buffer to the framework, + * the framework may do one of two things with the filled buffer: + * + * 2. a. The framework uses the filled data, and returns the now-used buffer + * to the stream queue for reuse. This behavior exactly matches the + * OUTPUT type of stream. + * + * 2. b. The framework wants to reprocess the filled data, and uses the + * buffer as an input buffer for a request. Once the HAL device has + * used the reprocessing buffer, it then returns it to the + * framework. The framework then returns the now-used buffer to the + * stream queue for reuse. + * + * 3. The HAL device will be given the buffer again as an output buffer for + * a request at some future point. + * + * For ZSL use case, the pixel format for bidirectional stream will be + * HAL_PIXEL_FORMAT_RAW_OPAQUE or HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED if it + * is listed in android.scaler.availableInputOutputFormatsMap. When + * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, the gralloc + * usage flags for the consumer endpoint will be set to GRALLOC_USAGE_HW_CAMERA_ZSL. + * A configuration stream list that has BIDIRECTIONAL stream used as input, will + * usually also have a distinct OUTPUT stream to get the reprocessing data. For example, + * for the ZSL use case, the stream list might be configured with the following: + * + * - A HAL_PIXEL_FORMAT_RAW_OPAQUE bidirectional stream is used + * as input. + * - And a HAL_PIXEL_FORMAT_BLOB (JPEG) output stream. + * + * S8.2 ZSL (OPAQUE) reprocessing with CAMERA3_STREAM_INPUT stream. + * + * CAMERA_DEVICE_API_VERSION_3_3: + * When OPAQUE_REPROCESSING capability is supported by the camera device, the INPUT stream + * can be used for application/framework implemented use case like Zero Shutter Lag (ZSL). + * This kind of stream will be used by the framework as follows: + * + * 1. Application/framework configures an opaque (RAW or YUV based) format output stream that is + * used to produce the ZSL output buffers. The stream pixel format will be + * HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. + * + * 2. Application/framework configures an opaque format input stream that is used to + * send the reprocessing ZSL buffers to the HAL. The stream pixel format will + * also be HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED. + * + * 3. Application/framework configures a YUV/JPEG output stream that is used to receive the + * reprocessed data. The stream pixel format will be YCbCr_420/HAL_PIXEL_FORMAT_BLOB. + * + * 4. Application/framework picks a ZSL buffer from the ZSL output stream when a ZSL capture is + * issued by the application, and sends the data back as an input buffer in a + * reprocessing request, then sends to the HAL for reprocessing. + * + * 5. The HAL sends back the output YUV/JPEG result to framework. + * + * The HAL can select the actual opaque buffer format and configure the ISP pipeline + * appropriately based on the HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED format and + * the gralloc usage flag GRALLOC_USAGE_HW_CAMERA_ZSL. + + * S8.3 YUV reprocessing with CAMERA3_STREAM_INPUT stream. + * + * When YUV reprocessing is supported by the HAL, the INPUT stream + * can be used for the YUV reprocessing use cases like lucky-shot and image fusion. + * This kind of stream will be used by the framework as follows: + * + * 1. Application/framework configures an YCbCr_420 format output stream that is + * used to produce the output buffers. + * + * 2. Application/framework configures an YCbCr_420 format input stream that is used to + * send the reprocessing YUV buffers to the HAL. + * + * 3. Application/framework configures a YUV/JPEG output stream that is used to receive the + * reprocessed data. The stream pixel format will be YCbCr_420/HAL_PIXEL_FORMAT_BLOB. + * + * 4. Application/framework processes the output buffers (could be as simple as picking + * an output buffer directly) from the output stream when a capture is issued, and sends + * the data back as an input buffer in a reprocessing request, then sends to the HAL + * for reprocessing. + * + * 5. The HAL sends back the output YUV/JPEG result to framework. + * + */ + +/** + * S9. Notes on Controls and Metadata + * + * This section contains notes about the interpretation and usage of various metadata tags. + * + * S9.1 HIGH_QUALITY and FAST modes. + * + * Many camera post-processing blocks may be listed as having HIGH_QUALITY, + * FAST, and OFF operating modes. These blocks will typically also have an + * 'available modes' tag representing which of these operating modes are + * available on a given device. The general policy regarding implementing + * these modes is as follows: + * + * 1. Operating mode controls of hardware blocks that cannot be disabled + * must not list OFF in their corresponding 'available modes' tags. + * + * 2. OFF will always be included in their corresponding 'available modes' + * tag if it is possible to disable that hardware block. + * + * 3. FAST must always be included in the 'available modes' tags for all + * post-processing blocks supported on the device. If a post-processing + * block also has a slower and higher quality operating mode that does + * not meet the framerate requirements for FAST mode, HIGH_QUALITY should + * be included in the 'available modes' tag to represent this operating + * mode. + */ + +/** + * S10. Reprocessing flow and controls + * + * This section describes the OPAQUE and YUV reprocessing flow and controls. OPAQUE reprocessing + * uses an opaque format that is not directly application-visible, and the application can + * only select some of the output buffers and send back to HAL for reprocessing, while YUV + * reprocessing gives the application opportunity to process the buffers before reprocessing. + * + * S8 gives the stream configurations for the typical reprocessing uses cases, + * this section specifies the buffer flow and controls in more details. + * + * S10.1 OPAQUE (typically for ZSL use case) reprocessing flow and controls + * + * For OPAQUE reprocessing (e.g. ZSL) use case, after the application creates the specific + * output and input streams, runtime buffer flow and controls are specified as below: + * + * 1. Application starts output streaming by sending repeating requests for output + * opaque buffers and preview. The buffers are held by an application + * maintained circular buffer. The requests are based on CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG + * capture template, which should have all necessary settings that guarantee output + * frame rate is not slowed down relative to sensor output frame rate. + * + * 2. When a capture is issued, the application selects one output buffer based + * on application buffer selection logic, e.g. good AE and AF statistics etc. + * Application then creates an reprocess request based on the capture result associated + * with this selected buffer. The selected output buffer is now added to this reprocess + * request as an input buffer, the output buffer of this reprocess request should be + * either JPEG output buffer or YUV output buffer, or both, depending on the application + * choice. + * + * 3. Application then alters the reprocess settings to get best image quality. The HAL must + * support and only support below controls if the HAL support OPAQUE_REPROCESSING capability: + * - android.jpeg.* (if JPEG buffer is included as one of the output) + * - android.noiseReduction.mode (change to HIGH_QUALITY if it is supported) + * - android.edge.mode (change to HIGH_QUALITY if it is supported) + * All other controls must be ignored by the HAL. + * 4. HAL processed the input buffer and return the output buffers in the capture results + * as normal. + * + * S10.2 YUV reprocessing flow and controls + * + * The YUV reprocessing buffer flow is similar as OPAQUE reprocessing, with below difference: + * + * 1. Application may want to have finer granularity control of the intermediate YUV images + * (before reprocessing). For example, application may choose + * - android.noiseReduction.mode == MINIMAL + * to make sure the no YUV domain noise reduction has applied to the output YUV buffers, + * then it can do its own advanced noise reduction on them. For OPAQUE reprocessing case, this + * doesn't matter, as long as the final reprocessed image has the best quality. + * 2. Application may modify the YUV output buffer data. For example, for image fusion use + * case, where multiple output images are merged together to improve the signal-to-noise + * ratio (SNR). The input buffer may be generated from multiple buffers by the application. + * To avoid excessive amount of noise reduction and insufficient amount of edge enhancement + * being applied to the input buffer, the application can hint the HAL how much effective + * exposure time improvement has been done by the application, then the HAL can adjust the + * noise reduction and edge enhancement parameters to get best reprocessed image quality. + * Below tag can be used for this purpose: + * - android.reprocess.effectiveExposureFactor + * The value would be exposure time increase factor applied to the original output image, + * for example, if there are N image merged, the exposure time increase factor would be up + * to sqrt(N). See this tag spec for more details. + * + * S10.3 Reprocessing pipeline characteristics + * + * Reprocessing pipeline has below different characteristics comparing with normal output + * pipeline: + * + * 1. The reprocessing result can be returned ahead of the pending normal output results. But + * the FIFO ordering must be maintained for all reprocessing results. For example, there are + * below requests (A stands for output requests, B stands for reprocessing requests) + * being processed by the HAL: + * A1, A2, A3, A4, B1, A5, B2, A6... + * result of B1 can be returned before A1-A4, but result of B2 must be returned after B1. + * 2. Single input rule: For a given reprocessing request, all output buffers must be from the + * input buffer, rather than sensor output. For example, if a reprocess request include both + * JPEG and preview buffers, all output buffers must be produced from the input buffer + * included by the reprocessing request, rather than sensor. The HAL must not output preview + * buffers from sensor, while output JPEG buffer from the input buffer. + * 3. Input buffer will be from camera output directly (ZSL case) or indirectly(image fusion + * case). For the case where buffer is modified, the size will remain same. The HAL can + * notify CAMERA3_MSG_ERROR_REQUEST if buffer from unknown source is sent. + * 4. Result as reprocessing request: The HAL can expect that a reprocessing request is a copy + * of one of the output results with minor allowed setting changes. The HAL can notify + * CAMERA3_MSG_ERROR_REQUEST if a request from unknown source is issued. + * 5. Output buffers may not be used as inputs across the configure stream boundary, This is + * because an opaque stream like the ZSL output stream may have different actual image size + * inside of the ZSL buffer to save power and bandwidth for smaller resolution JPEG capture. + * The HAL may notify CAMERA3_MSG_ERROR_REQUEST if this case occurs. + * 6. HAL Reprocess requests error reporting during flush should follow the same rule specified + * by flush() method. + * + */ + +__BEGIN_DECLS + +struct camera3_device; + +/********************************************************************** + * + * Camera3 stream and stream buffer definitions. + * + * These structs and enums define the handles and contents of the input and + * output streams connecting the HAL to various framework and application buffer + * consumers. Each stream is backed by a gralloc buffer queue. + * + */ + +/** + * camera3_stream_type_t: + * + * The type of the camera stream, which defines whether the camera HAL device is + * the producer or the consumer for that stream, and how the buffers of the + * stream relate to the other streams. + */ +typedef enum camera3_stream_type { + /** + * This stream is an output stream; the camera HAL device will be + * responsible for filling buffers from this stream with newly captured or + * reprocessed image data. + */ + CAMERA3_STREAM_OUTPUT = 0, + + /** + * This stream is an input stream; the camera HAL device will be responsible + * for reading buffers from this stream and sending them through the camera + * processing pipeline, as if the buffer was a newly captured image from the + * imager. + * + * The pixel format for input stream can be any format reported by + * android.scaler.availableInputOutputFormatsMap. The pixel format of the + * output stream that is used to produce the reprocessing data may be any + * format reported by android.scaler.availableStreamConfigurations. The + * supported input/output stream combinations depends the camera device + * capabilities, see android.scaler.availableInputOutputFormatsMap for + * stream map details. + * + * This kind of stream is generally used to reprocess data into higher + * quality images (that otherwise would cause a frame rate performance + * loss), or to do off-line reprocessing. + * + * CAMERA_DEVICE_API_VERSION_3_3: + * The typical use cases are OPAQUE (typically ZSL) and YUV reprocessing, + * see S8.2, S8.3 and S10 for more details. + */ + CAMERA3_STREAM_INPUT = 1, + + /** + * This stream can be used for input and output. Typically, the stream is + * used as an output stream, but occasionally one already-filled buffer may + * be sent back to the HAL device for reprocessing. + * + * This kind of stream is meant generally for Zero Shutter Lag (ZSL) + * features, where copying the captured image from the output buffer to the + * reprocessing input buffer would be expensive. See S8.1 for more details. + * + * Note that the HAL will always be reprocessing data it produced. + * + */ + CAMERA3_STREAM_BIDIRECTIONAL = 2, + + /** + * Total number of framework-defined stream types + */ + CAMERA3_NUM_STREAM_TYPES + +} camera3_stream_type_t; + +/** + * camera3_stream_rotation_t: + * + * The required counterclockwise rotation of camera stream. + */ +typedef enum camera3_stream_rotation { + /* No rotation */ + CAMERA3_STREAM_ROTATION_0 = 0, + + /* Rotate by 90 degree counterclockwise */ + CAMERA3_STREAM_ROTATION_90 = 1, + + /* Rotate by 180 degree counterclockwise */ + CAMERA3_STREAM_ROTATION_180 = 2, + + /* Rotate by 270 degree counterclockwise */ + CAMERA3_STREAM_ROTATION_270 = 3 +} camera3_stream_rotation_t; + +/** + * camera3_stream_configuration_mode_t: + * + * This defines the general operation mode for the HAL (for a given stream configuration), where + * modes besides NORMAL have different semantics, and usually limit the generality of the API in + * exchange for higher performance in some particular area. + */ +typedef enum camera3_stream_configuration_mode { + /** + * Normal stream configuration operation mode. This is the default camera operation mode, + * where all semantics of HAL APIs and metadata controls apply. + */ + CAMERA3_STREAM_CONFIGURATION_NORMAL_MODE = 0, + + /** + * Special constrained high speed operation mode for devices that can not support high + * speed output in NORMAL mode. All streams in this configuration are operating at high speed + * mode and have different characteristics and limitations to achieve high speed output. + * The NORMAL mode can still be used for high speed output if the HAL can support high speed + * output while satisfying all the semantics of HAL APIs and metadata controls. It is + * recommended for the HAL to support high speed output in NORMAL mode (by advertising the high + * speed FPS ranges in android.control.aeAvailableTargetFpsRanges) if possible. + * + * This mode has below limitations/requirements: + * + * 1. The HAL must support up to 2 streams with sizes reported by + * android.control.availableHighSpeedVideoConfigurations. + * 2. In this mode, the HAL is expected to output up to 120fps or higher. This mode must + * support the targeted FPS range and size configurations reported by + * android.control.availableHighSpeedVideoConfigurations. + * 3. The HAL must support HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED output stream format. + * 4. To achieve efficient high speed streaming, the HAL may have to aggregate + * multiple frames together and send to camera device for processing where the request + * controls are same for all the frames in this batch (batch mode). The HAL must support + * max batch size and the max batch size requirements defined by + * android.control.availableHighSpeedVideoConfigurations. + * 5. In this mode, the HAL must override aeMode, awbMode, and afMode to ON, ON, and + * CONTINUOUS_VIDEO, respectively. All post-processing block mode controls must be + * overridden to be FAST. Therefore, no manual control of capture and post-processing + * parameters is possible. All other controls operate the same as when + * android.control.mode == AUTO. This means that all other android.control.* fields + * must continue to work, such as + * + * android.control.aeTargetFpsRange + * android.control.aeExposureCompensation + * android.control.aeLock + * android.control.awbLock + * android.control.effectMode + * android.control.aeRegions + * android.control.afRegions + * android.control.awbRegions + * android.control.afTrigger + * android.control.aePrecaptureTrigger + * + * Outside of android.control.*, the following controls must work: + * + * android.flash.mode (TORCH mode only, automatic flash for still capture will not work + * since aeMode is ON) + * android.lens.opticalStabilizationMode (if it is supported) + * android.scaler.cropRegion + * android.statistics.faceDetectMode (if it is supported) + * 6. To reduce the amount of data passed across process boundaries at + * high frame rate, within one batch, camera framework only propagates + * the last shutter notify and the last capture results (including partial + * results and final result) to the app. The shutter notifies and capture + * results for the other requests in the batch are derived by + * the camera framework. As a result, the HAL can return empty metadata + * except for the last result in the batch. + * + * For more details about high speed stream requirements, see + * android.control.availableHighSpeedVideoConfigurations and CONSTRAINED_HIGH_SPEED_VIDEO + * capability defined in android.request.availableCapabilities. + * + * This mode only needs to be supported by HALs that include CONSTRAINED_HIGH_SPEED_VIDEO in + * the android.request.availableCapabilities static metadata. + */ + CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE = 1, + + /** + * First value for vendor-defined stream configuration modes. + */ + CAMERA3_VENDOR_STREAM_CONFIGURATION_MODE_START = 0x8000 +} camera3_stream_configuration_mode_t; + +/** + * camera3_stream_t: + * + * A handle to a single camera input or output stream. A stream is defined by + * the framework by its buffer resolution and format, and additionally by the + * HAL with the gralloc usage flags and the maximum in-flight buffer count. + * + * The stream structures are owned by the framework, but pointers to a + * camera3_stream passed into the HAL by configure_streams() are valid until the + * end of the first subsequent configure_streams() call that _does not_ include + * that camera3_stream as an argument, or until the end of the close() call. + * + * All camera3_stream framework-controlled members are immutable once the + * camera3_stream is passed into configure_streams(). The HAL may only change + * the HAL-controlled parameters during a configure_streams() call, except for + * the contents of the private pointer. + * + * If a configure_streams() call returns a non-fatal error, all active streams + * remain valid as if configure_streams() had not been called. + * + * The endpoint of the stream is not visible to the camera HAL device. + * In DEVICE_API_VERSION_3_1, this was changed to share consumer usage flags + * on streams where the camera is a producer (OUTPUT and BIDIRECTIONAL stream + * types) see the usage field below. + */ +typedef struct camera3_stream { + + /***** + * Set by framework before configure_streams() + */ + + /** + * The type of the stream, one of the camera3_stream_type_t values. + */ + int stream_type; + + /** + * The width in pixels of the buffers in this stream + */ + uint32_t width; + + /** + * The height in pixels of the buffers in this stream + */ + uint32_t height; + + /** + * The pixel format for the buffers in this stream. Format is a value from + * the HAL_PIXEL_FORMAT_* list in system/core/include/system/graphics.h, or + * from device-specific headers. + * + * If HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform + * gralloc module will select a format based on the usage flags provided by + * the camera device and the other endpoint of the stream. + * + * <= CAMERA_DEVICE_API_VERSION_3_1: + * + * The camera HAL device must inspect the buffers handed to it in the + * subsequent register_stream_buffers() call to obtain the + * implementation-specific format details, if necessary. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * register_stream_buffers() won't be called by the framework, so the HAL + * should configure the ISP and sensor pipeline based purely on the sizes, + * usage flags, and formats for the configured streams. + */ + int format; + + /***** + * Set by HAL during configure_streams(). + */ + + /** + * The gralloc usage flags for this stream, as needed by the HAL. The usage + * flags are defined in gralloc.h (GRALLOC_USAGE_*), or in device-specific + * headers. + * + * For output streams, these are the HAL's producer usage flags. For input + * streams, these are the HAL's consumer usage flags. The usage flags from + * the producer and the consumer will be combined together and then passed + * to the platform gralloc HAL module for allocating the gralloc buffers for + * each stream. + * + * Version information: + * + * == CAMERA_DEVICE_API_VERSION_3_0: + * + * No initial value guaranteed when passed via configure_streams(). + * HAL may not use this field as input, and must write over this field + * with its usage flags. + * + * >= CAMERA_DEVICE_API_VERSION_3_1: + * + * For stream_type OUTPUT and BIDIRECTIONAL, when passed via + * configure_streams(), the initial value of this is the consumer's + * usage flags. The HAL may use these consumer flags to decide stream + * configuration. + * For stream_type INPUT, when passed via configure_streams(), the initial + * value of this is 0. + * For all streams passed via configure_streams(), the HAL must write + * over this field with its usage flags. + * + * From Android O, the usage flag for an output stream may be bitwise + * combination of usage flags for multiple consumers, for the purpose of + * sharing one camera stream between those consumers. The HAL must fail + * configure_streams call with -EINVAL if the combined flags cannot be + * supported due to imcompatible buffer format, dataSpace, or other hardware + * limitations. + */ + uint32_t usage; + + /** + * The maximum number of buffers the HAL device may need to have dequeued at + * the same time. The HAL device may not have more buffers in-flight from + * this stream than this value. + */ + uint32_t max_buffers; + + /** + * A handle to HAL-private information for the stream. Will not be inspected + * by the framework code. + */ + void *priv; + + /** + * A field that describes the contents of the buffer. The format and buffer + * dimensions define the memory layout and structure of the stream buffers, + * while dataSpace defines the meaning of the data within the buffer. + * + * For most formats, dataSpace defines the color space of the image data. + * In addition, for some formats, dataSpace indicates whether image- or + * depth-based data is requested. See system/core/include/system/graphics.h + * for details of formats and valid dataSpace values for each format. + * + * Version information: + * + * < CAMERA_DEVICE_API_VERSION_3_3: + * + * Not defined and should not be accessed. dataSpace should be assumed to + * be HAL_DATASPACE_UNKNOWN, and the appropriate color space, etc, should + * be determined from the usage flags and the format. + * + * = CAMERA_DEVICE_API_VERSION_3_3: + * + * Always set by the camera service. HAL must use this dataSpace to + * configure the stream to the correct colorspace, or to select between + * color and depth outputs if supported. The dataspace values are the + * legacy definitions in graphics.h + * + * >= CAMERA_DEVICE_API_VERSION_3_4: + * + * Always set by the camera service. HAL must use this dataSpace to + * configure the stream to the correct colorspace, or to select between + * color and depth outputs if supported. The dataspace values are set + * using the V0 dataspace definitions in graphics.h + */ + android_dataspace_t data_space; + + /** + * The required output rotation of the stream, one of + * the camera3_stream_rotation_t values. This must be inspected by HAL along + * with stream width and height. For example, if the rotation is 90 degree + * and the stream width and height is 720 and 1280 respectively, camera service + * will supply buffers of size 720x1280, and HAL should capture a 1280x720 image + * and rotate the image by 90 degree counterclockwise. The rotation field is + * no-op when the stream type is input. Camera HAL must ignore the rotation + * field for an input stream. + * + * <= CAMERA_DEVICE_API_VERSION_3_2: + * + * Not defined and must not be accessed. HAL must not apply any rotation + * on output images. + * + * >= CAMERA_DEVICE_API_VERSION_3_3: + * + * Always set by camera service. HAL must inspect this field during stream + * configuration and returns -EINVAL if HAL cannot perform such rotation. + * HAL must always support CAMERA3_STREAM_ROTATION_0, so a + * configure_streams() call must not fail for unsupported rotation if + * rotation field of all streams is CAMERA3_STREAM_ROTATION_0. + * + */ + int rotation; + + /** + * The physical camera id this stream belongs to. + * + * <= CAMERA_DEVICE_API_VERISON_3_4: + * + * Not defined and must not be accessed. + * + * >= CAMERA_DEVICE_API_VERISON_3_5: + * + * Always set by camera service. If the camera device is not a logical + * multi camera, or if the camera is a logical multi camera but the stream + * is not a physical output stream, this field will point to a 0-length + * string. + * + * A logical multi camera is a camera device backed by multiple physical + * cameras that are also exposed to the application. And for a logical + * multi camera, a physical output stream is an output stream specifically + * requested on an underlying physical camera. + * + * For an input stream, this field is guaranteed to be a 0-length string. + */ + const char* physical_camera_id; + + /* reserved for future use */ + void *reserved[6]; + +} camera3_stream_t; + +/** + * camera3_stream_configuration_t: + * + * A structure of stream definitions, used by configure_streams(). This + * structure defines all the output streams and the reprocessing input + * stream for the current camera use case. + */ +typedef struct camera3_stream_configuration { + /** + * The total number of streams requested by the framework. This includes + * both input and output streams. The number of streams will be at least 1, + * and there will be at least one output-capable stream. + */ + uint32_t num_streams; + + /** + * An array of camera stream pointers, defining the input/output + * configuration for the camera HAL device. + * + * At most one input-capable stream may be defined (INPUT or BIDIRECTIONAL) + * in a single configuration. + * + * At least one output-capable stream must be defined (OUTPUT or + * BIDIRECTIONAL). + */ + camera3_stream_t **streams; + + /** + * >= CAMERA_DEVICE_API_VERSION_3_3: + * + * The operation mode of streams in this configuration, one of the value + * defined in camera3_stream_configuration_mode_t. The HAL can use this + * mode as an indicator to set the stream property (e.g., + * camera3_stream->max_buffers) appropriately. For example, if the + * configuration is + * CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE, the HAL may + * want to set aside more buffers for batch mode operation (see + * android.control.availableHighSpeedVideoConfigurations for batch mode + * definition). + * + */ + uint32_t operation_mode; + + /** + * >= CAMERA_DEVICE_API_VERSION_3_5: + * + * The session metadata buffer contains the initial values of + * ANDROID_REQUEST_AVAILABLE_SESSION_KEYS. This field is optional + * and camera clients can choose to ignore it, in which case it will + * be set to NULL. If parameters are present, then Hal should examine + * the parameter values and configure its internal camera pipeline + * accordingly. + */ + const camera_metadata_t *session_parameters; +} camera3_stream_configuration_t; + +/** + * camera3_buffer_status_t: + * + * The current status of a single stream buffer. + */ +typedef enum camera3_buffer_status { + /** + * The buffer is in a normal state, and can be used after waiting on its + * sync fence. + */ + CAMERA3_BUFFER_STATUS_OK = 0, + + /** + * The buffer does not contain valid data, and the data in it should not be + * used. The sync fence must still be waited on before reusing the buffer. + */ + CAMERA3_BUFFER_STATUS_ERROR = 1 + +} camera3_buffer_status_t; + +/** + * camera3_stream_buffer_t: + * + * A single buffer from a camera3 stream. It includes a handle to its parent + * stream, the handle to the gralloc buffer itself, and sync fences + * + * The buffer does not specify whether it is to be used for input or output; + * that is determined by its parent stream type and how the buffer is passed to + * the HAL device. + */ +typedef struct camera3_stream_buffer { + /** + * The handle of the stream this buffer is associated with + */ + camera3_stream_t *stream; + + /** + * The native handle to the buffer + */ + buffer_handle_t *buffer; + + /** + * Current state of the buffer, one of the camera3_buffer_status_t + * values. The framework will not pass buffers to the HAL that are in an + * error state. In case a buffer could not be filled by the HAL, it must + * have its status set to CAMERA3_BUFFER_STATUS_ERROR when returned to the + * framework with process_capture_result(). + */ + int status; + + /** + * The acquire sync fence for this buffer. The HAL must wait on this fence + * fd before attempting to read from or write to this buffer. + * + * The framework may be set to -1 to indicate that no waiting is necessary + * for this buffer. + * + * When the HAL returns an output buffer to the framework with + * process_capture_result(), the acquire_fence must be set to -1. If the HAL + * never waits on the acquire_fence due to an error in filling a buffer, + * when calling process_capture_result() the HAL must set the release_fence + * of the buffer to be the acquire_fence passed to it by the framework. This + * will allow the framework to wait on the fence before reusing the buffer. + * + * For input buffers, the HAL must not change the acquire_fence field during + * the process_capture_request() call. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * When the HAL returns an input buffer to the framework with + * process_capture_result(), the acquire_fence must be set to -1. If the HAL + * never waits on input buffer acquire fence due to an error, the sync + * fences should be handled similarly to the way they are handled for output + * buffers. + */ + int acquire_fence; + + /** + * The release sync fence for this buffer. The HAL must set this fence when + * returning buffers to the framework, or write -1 to indicate that no + * waiting is required for this buffer. + * + * For the output buffers, the fences must be set in the output_buffers + * array passed to process_capture_result(). + * + * <= CAMERA_DEVICE_API_VERSION_3_1: + * + * For the input buffer, the release fence must be set by the + * process_capture_request() call. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * For the input buffer, the fences must be set in the input_buffer + * passed to process_capture_result(). + * + * After signaling the release_fence for this buffer, the HAL + * should not make any further attempts to access this buffer as the + * ownership has been fully transferred back to the framework. + * + * If a fence of -1 was specified then the ownership of this buffer + * is transferred back immediately upon the call of process_capture_result. + */ + int release_fence; + +} camera3_stream_buffer_t; + +/** + * camera3_stream_buffer_set_t: + * + * The complete set of gralloc buffers for a stream. This structure is given to + * register_stream_buffers() to allow the camera HAL device to register/map/etc + * newly allocated stream buffers. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * Deprecated (and not used). In particular, + * register_stream_buffers is also deprecated and will never be invoked. + * + */ +typedef struct camera3_stream_buffer_set { + /** + * The stream handle for the stream these buffers belong to + */ + camera3_stream_t *stream; + + /** + * The number of buffers in this stream. It is guaranteed to be at least + * stream->max_buffers. + */ + uint32_t num_buffers; + + /** + * The array of gralloc buffer handles for this stream. If the stream format + * is set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the camera HAL device + * should inspect the passed-in buffers to determine any platform-private + * pixel format information. + */ + buffer_handle_t **buffers; + +} camera3_stream_buffer_set_t; + +/** + * camera3_jpeg_blob: + * + * Transport header for compressed JPEG or JPEG_APP_SEGMENTS buffers in output streams. + * + * To capture JPEG or JPEG_APP_SEGMENTS images, a stream is created using the pixel format + * HAL_PIXEL_FORMAT_BLOB. The buffer size for the stream is calculated by the + * framework, based on the static metadata field android.jpeg.maxSize for JPEG, + * and android.jpeg.maxAppsSegments for JPEG_APP_SEGMENTS. + * + * Since compressed JPEG/JPEG_APP_SEGMENTS images are of variable size, the HAL needs to + * include the final size of the image using this structure inside the output + * stream buffer. The JPEG blob ID field must be set to CAMERA3_JPEG_BLOB_ID for + * JPEG and CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID for APP segments. + * + * Transport header should be at the end of the output stream buffer. That + * means the jpeg_blob_id must start at byte[buffer_size - + * sizeof(camera3_jpeg_blob)], where the buffer_size is the size of gralloc buffer. + * The blob data itself starts at the beginning of the buffer and should be + * jpeg_size bytes long. HAL using this transport header for JPEG must account for + * it in android.jpeg.maxSize. For JPEG APP segments, camera framework makes + * sure that the output stream buffer is large enough for the transport header. + */ +typedef struct camera3_jpeg_blob { + uint16_t jpeg_blob_id; + uint32_t jpeg_size; +} camera3_jpeg_blob_t; + +enum { + CAMERA3_JPEG_BLOB_ID = 0x00FF, + CAMERA3_JPEG_APP_SEGMENTS_BLOB_ID = 0x0100, +}; + +/********************************************************************** + * + * Message definitions for the HAL notify() callback. + * + * These definitions are used for the HAL notify callback, to signal + * asynchronous events from the HAL device to the Android framework. + * + */ + +/** + * camera3_msg_type: + * + * Indicates the type of message sent, which specifies which member of the + * message union is valid. + * + */ +typedef enum camera3_msg_type { + /** + * An error has occurred. camera3_notify_msg.message.error contains the + * error information. + */ + CAMERA3_MSG_ERROR = 1, + + /** + * The exposure of a given request or processing a reprocess request has + * begun. camera3_notify_msg.message.shutter contains the information + * the capture. + */ + CAMERA3_MSG_SHUTTER = 2, + + /** + * Number of framework message types + */ + CAMERA3_NUM_MESSAGES + +} camera3_msg_type_t; + +/** + * Defined error codes for CAMERA_MSG_ERROR + */ +typedef enum camera3_error_msg_code { + /** + * A serious failure occured. No further frames or buffer streams will + * be produced by the device. Device should be treated as closed. The + * client must reopen the device to use it again. The frame_number field + * is unused. + */ + CAMERA3_MSG_ERROR_DEVICE = 1, + + /** + * An error has occurred in processing a request. No output (metadata or + * buffers) will be produced for this request. The frame_number field + * specifies which request has been dropped. Subsequent requests are + * unaffected, and the device remains operational. + */ + CAMERA3_MSG_ERROR_REQUEST = 2, + + /** + * An error has occurred in producing an output result metadata buffer + * for a request, but output stream buffers for it will still be + * available. Subsequent requests are unaffected, and the device remains + * operational. The frame_number field specifies the request for which + * result metadata won't be available. + * + * >= CAMERA_DEVICE_API_VERSION_3_6: + * + * In case the result metadata is absent for a logical camera device, then the + * error_stream pointer must be set to NULL. + * If the result metadata cannot be produced for a physical camera device, then + * error_stream must contain a pointer to a respective stream associated with + * that physical device. + */ + CAMERA3_MSG_ERROR_RESULT = 3, + + /** + * An error has occurred in placing an output buffer into a stream for a + * request. The frame metadata and other buffers may still be + * available. Subsequent requests are unaffected, and the device remains + * operational. The frame_number field specifies the request for which the + * buffer was dropped, and error_stream contains a pointer to the stream + * that dropped the frame. + */ + CAMERA3_MSG_ERROR_BUFFER = 4, + + /** + * Number of error types + */ + CAMERA3_MSG_NUM_ERRORS + +} camera3_error_msg_code_t; + +/** + * camera3_error_msg_t: + * + * Message contents for CAMERA3_MSG_ERROR + */ +typedef struct camera3_error_msg { + /** + * Frame number of the request the error applies to. 0 if the frame number + * isn't applicable to the error. + */ + uint32_t frame_number; + + /** + * Pointer to the stream that had a failure. NULL if the stream isn't + * applicable to the error. + */ + camera3_stream_t *error_stream; + + /** + * The code for this error; one of the CAMERA_MSG_ERROR enum values. + */ + int error_code; + +} camera3_error_msg_t; + +/** + * camera3_shutter_msg_t: + * + * Message contents for CAMERA3_MSG_SHUTTER + */ +typedef struct camera3_shutter_msg { + /** + * Frame number of the request that has begun exposure or reprocessing. + */ + uint32_t frame_number; + + /** + * Timestamp for the start of capture. For a reprocess request, this must + * be input image's start of capture. This must match the capture result + * metadata's sensor exposure start timestamp. + */ + uint64_t timestamp; + +} camera3_shutter_msg_t; + +/** + * camera3_notify_msg_t: + * + * The message structure sent to camera3_callback_ops_t.notify() + */ +typedef struct camera3_notify_msg { + + /** + * The message type. One of camera3_notify_msg_type, or a private extension. + */ + int type; + + union { + /** + * Error message contents. Valid if type is CAMERA3_MSG_ERROR + */ + camera3_error_msg_t error; + + /** + * Shutter message contents. Valid if type is CAMERA3_MSG_SHUTTER + */ + camera3_shutter_msg_t shutter; + + /** + * Generic message contents. Used to ensure a minimum size for custom + * message types. + */ + uint8_t generic[32]; + } message; + +} camera3_notify_msg_t; + + +/********************************************************************** + * + * Types definition for request_stream_buffers() callback. + * + */ + +/** + * camera3_buffer_request_status_t: + * + * The overall buffer request status returned by request_stream_buffers() + */ +typedef enum camera3_buffer_request_status { + /** + * request_stream_buffers() call succeeded and all requested buffers are + * returned. + */ + CAMERA3_BUF_REQ_OK = 0, + + /** + * request_stream_buffers() call failed for some streams. + * Check per stream status for each returned camera3_stream_buffer_ret_t. + */ + CAMERA3_BUF_REQ_FAILED_PARTIAL = 1, + + /** + * request_stream_buffers() call failed for all streams and no buffers are + * returned at all. Camera service is about to or is performing + * configure_streams() call. HAL must wait until next configure_streams() + * call is finished before requesting buffers again. + */ + CAMERA3_BUF_REQ_FAILED_CONFIGURING = 2, + + /** + * request_stream_buffers() call failed for all streams and no buffers are + * returned at all. Failure due to bad camera3_buffer_request input, eg: + * unknown stream or repeated stream in the list of buffer requests. + */ + CAMERA3_BUF_REQ_FAILED_ILLEGAL_ARGUMENTS = 3, + + /** + * request_stream_buffers() call failed for all streams and no buffers are + * returned at all. This can happen for unknown reasons or a combination + * of different failure reasons per stream. For the latter case, caller can + * check per stream failure reason returned in camera3_stream_buffer_ret. + */ + CAMERA3_BUF_REQ_FAILED_UNKNOWN = 4, + + /** + * Number of buffer request status + */ + CAMERA3_BUF_REQ_NUM_STATUS + +} camera3_buffer_request_status_t; + +/** + * camera3_stream_buffer_req_status_t: + * + * The per stream buffer request status returned by request_stream_buffers() + */ +typedef enum camera3_stream_buffer_req_status { + /** + * Get buffer succeeds and all requested buffers are returned. + */ + CAMERA3_PS_BUF_REQ_OK = 0, + + /** + * Get buffer failed due to timeout waiting for an available buffer. This is + * likely due to the client application holding too many buffers, or the + * system is under memory pressure. + * This is not a fatal error. HAL can try to request buffer for this stream + * later. If HAL cannot get a buffer for certain capture request in time + * due to this error, HAL can send an ERROR_REQUEST to camera service and + * drop processing that request. + */ + CAMERA3_PS_BUF_REQ_NO_BUFFER_AVAILABLE = 1, + + /** + * Get buffer failed due to HAL has reached its maxBuffer count. This is not + * a fatal error. HAL can try to request buffer for this stream again after + * it returns at least one buffer of that stream to camera service. + */ + CAMERA3_PS_BUF_REQ_MAX_BUFFER_EXCEEDED = 2, + + /** + * Get buffer failed due to the stream is disconnected by client + * application, has been removed, or not recognized by camera service. + * This means application is no longer interested in this stream. + * Requesting buffer for this stream will never succeed after this error is + * returned. HAL must safely return all buffers of this stream after + * getting this error. If HAL gets another capture request later targeting + * a disconnected stream, HAL must send an ERROR_REQUEST to camera service + * and drop processing that request. + */ + CAMERA3_PS_BUF_REQ_STREAM_DISCONNECTED = 3, + + /** + * Get buffer failed for unknown reason. This is a fatal error and HAL must + * send ERROR_DEVICE to camera service and be ready to be closed. + */ + CAMERA3_PS_BUF_REQ_UNKNOWN_ERROR = 4, + + /** + * Number of buffer request status + */ + CAMERA3_PS_BUF_REQ_NUM_STATUS +} camera3_stream_buffer_req_status_t; + +typedef struct camera3_buffer_request { + /** + * The stream HAL wants to request buffer from + */ + camera3_stream_t *stream; + + /** + * The number of buffers HAL requested + */ + uint32_t num_buffers_requested; +} camera3_buffer_request_t; + +typedef struct camera3_stream_buffer_ret { + /** + * The stream HAL wants to request buffer from + */ + camera3_stream_t *stream; + + /** + * The status of buffer request of this stream + */ + camera3_stream_buffer_req_status_t status; + + /** + * Number of output buffers returned. Must be 0 when above status is not + * CAMERA3_PS_BUF_REQ_OK; otherwise the value must be equal to + * num_buffers_requested in the corresponding camera3_buffer_request_t + */ + uint32_t num_output_buffers; + + /** + * The returned output buffers for the stream. + * Caller of request_stream_buffers() should supply this with enough memory + * (num_buffers_requested * sizeof(camera3_stream_buffer_t)) + */ + camera3_stream_buffer_t *output_buffers; +} camera3_stream_buffer_ret_t; + + +/********************************************************************** + * + * Capture request/result definitions for the HAL process_capture_request() + * method, and the process_capture_result() callback. + * + */ + +/** + * camera3_request_template_t: + * + * Available template types for + * camera3_device_ops.construct_default_request_settings() + */ +typedef enum camera3_request_template { + /** + * Standard camera preview operation with 3A on auto. + */ + CAMERA3_TEMPLATE_PREVIEW = 1, + + /** + * Standard camera high-quality still capture with 3A and flash on auto. + */ + CAMERA3_TEMPLATE_STILL_CAPTURE = 2, + + /** + * Standard video recording plus preview with 3A on auto, torch off. + */ + CAMERA3_TEMPLATE_VIDEO_RECORD = 3, + + /** + * High-quality still capture while recording video. Application will + * include preview, video record, and full-resolution YUV or JPEG streams in + * request. Must not cause stuttering on video stream. 3A on auto. + */ + CAMERA3_TEMPLATE_VIDEO_SNAPSHOT = 4, + + /** + * Zero-shutter-lag mode. Application will request preview and + * full-resolution data for each frame, and reprocess it to JPEG when a + * still image is requested by user. Settings should provide highest-quality + * full-resolution images without compromising preview frame rate. 3A on + * auto. + */ + CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG = 5, + + /** + * A basic template for direct application control of capture + * parameters. All automatic control is disabled (auto-exposure, auto-white + * balance, auto-focus), and post-processing parameters are set to preview + * quality. The manual capture parameters (exposure, sensitivity, etc.) + * are set to reasonable defaults, but should be overridden by the + * application depending on the intended use case. + */ + CAMERA3_TEMPLATE_MANUAL = 6, + + /* Total number of templates */ + CAMERA3_TEMPLATE_COUNT, + + /** + * First value for vendor-defined request templates + */ + CAMERA3_VENDOR_TEMPLATE_START = 0x40000000 + +} camera3_request_template_t; + +/** + * camera3_capture_request_t: + * + * A single request for image capture/buffer reprocessing, sent to the Camera + * HAL device by the framework in process_capture_request(). + * + * The request contains the settings to be used for this capture, and the set of + * output buffers to write the resulting image data in. It may optionally + * contain an input buffer, in which case the request is for reprocessing that + * input buffer instead of capturing a new image with the camera sensor. The + * capture is identified by the frame_number. + * + * In response, the camera HAL device must send a camera3_capture_result + * structure asynchronously to the framework, using the process_capture_result() + * callback. + */ +typedef struct camera3_capture_request { + /** + * The frame number is an incrementing integer set by the framework to + * uniquely identify this capture. It needs to be returned in the result + * call, and is also used to identify the request in asynchronous + * notifications sent to camera3_callback_ops_t.notify(). + */ + uint32_t frame_number; + + /** + * The settings buffer contains the capture and processing parameters for + * the request. As a special case, a NULL settings buffer indicates that the + * settings are identical to the most-recently submitted capture request. A + * NULL buffer cannot be used as the first submitted request after a + * configure_streams() call. + */ + const camera_metadata_t *settings; + + /** + * The input stream buffer to use for this request, if any. + * + * If input_buffer is NULL, then the request is for a new capture from the + * imager. If input_buffer is valid, the request is for reprocessing the + * image contained in input_buffer. + * + * In the latter case, the HAL must set the release_fence of the + * input_buffer to a valid sync fence, or to -1 if the HAL does not support + * sync, before process_capture_request() returns. + * + * The HAL is required to wait on the acquire sync fence of the input buffer + * before accessing it. + * + * <= CAMERA_DEVICE_API_VERSION_3_1: + * + * Any input buffer included here will have been registered with the HAL + * through register_stream_buffers() before its inclusion in a request. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * The buffers will not have been pre-registered with the HAL. + * Subsequent requests may reuse buffers, or provide entirely new buffers. + */ + camera3_stream_buffer_t *input_buffer; + + /** + * The number of output buffers for this capture request. Must be at least + * 1. + */ + uint32_t num_output_buffers; + + /** + * An array of num_output_buffers stream buffers, to be filled with image + * data from this capture/reprocess. The HAL must wait on the acquire fences + * of each stream buffer before writing to them. + * + * The HAL takes ownership of the actual buffer_handle_t entries in + * output_buffers; the framework does not access them until they are + * returned in a camera3_capture_result_t. + * + * <= CAMERA_DEVICE_API_VERSION_3_1: + * + * All the buffers included here will have been registered with the HAL + * through register_stream_buffers() before their inclusion in a request. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * Any or all of the buffers included here may be brand new in this + * request (having never before seen by the HAL). + */ + const camera3_stream_buffer_t *output_buffers; + + /** + * <= CAMERA_DEVICE_API_VERISON_3_4: + * + * Not defined and must not be accessed. + * + * >= CAMERA_DEVICE_API_VERSION_3_5: + * The number of physical camera settings to be applied. If 'num_physcam_settings' + * equals 0 or a physical device is not included, then Hal must decide the + * specific physical device settings based on the default 'settings'. + */ + uint32_t num_physcam_settings; + + /** + * <= CAMERA_DEVICE_API_VERISON_3_4: + * + * Not defined and must not be accessed. + * + * >= CAMERA_DEVICE_API_VERSION_3_5: + * The physical camera ids. The array will contain 'num_physcam_settings' + * camera id strings for all physical devices that have specific settings. + * In case some id is invalid, the process capture request must fail and return + * -EINVAL. + */ + const char **physcam_id; + + /** + * <= CAMERA_DEVICE_API_VERISON_3_4: + * + * Not defined and must not be accessed. + * + * >= CAMERA_DEVICE_API_VERSION_3_5: + * The capture settings for the physical cameras. The array will contain + * 'num_physcam_settings' settings for invididual physical devices. In + * case the settings at some particular index are empty, the process capture + * request must fail and return -EINVAL. + */ + const camera_metadata_t **physcam_settings; + +} camera3_capture_request_t; + +/** + * camera3_capture_result_t: + * + * The result of a single capture/reprocess by the camera HAL device. This is + * sent to the framework asynchronously with process_capture_result(), in + * response to a single capture request sent to the HAL with + * process_capture_request(). Multiple process_capture_result() calls may be + * performed by the HAL for each request. + * + * Each call, all with the same frame + * number, may contain some subset of the output buffers, and/or the result + * metadata. The metadata may only be provided once for a given frame number; + * all other calls must set the result metadata to NULL. + * + * The result structure contains the output metadata from this capture, and the + * set of output buffers that have been/will be filled for this capture. Each + * output buffer may come with a release sync fence that the framework will wait + * on before reading, in case the buffer has not yet been filled by the HAL. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * The metadata may be provided multiple times for a single frame number. The + * framework will accumulate together the final result set by combining each + * partial result together into the total result set. + * + * If an input buffer is given in a request, the HAL must return it in one of + * the process_capture_result calls, and the call may be to just return the input + * buffer, without metadata and output buffers; the sync fences must be handled + * the same way they are done for output buffers. + * + * + * Performance considerations: + * + * Applications will also receive these partial results immediately, so sending + * partial results is a highly recommended performance optimization to avoid + * the total pipeline latency before sending the results for what is known very + * early on in the pipeline. + * + * A typical use case might be calculating the AF state halfway through the + * pipeline; by sending the state back to the framework immediately, we get a + * 50% performance increase and perceived responsiveness of the auto-focus. + * + */ +typedef struct camera3_capture_result { + /** + * The frame number is an incrementing integer set by the framework in the + * submitted request to uniquely identify this capture. It is also used to + * identify the request in asynchronous notifications sent to + * camera3_callback_ops_t.notify(). + */ + uint32_t frame_number; + + /** + * The result metadata for this capture. This contains information about the + * final capture parameters, the state of the capture and post-processing + * hardware, the state of the 3A algorithms, if enabled, and the output of + * any enabled statistics units. + * + * Only one call to process_capture_result() with a given frame_number may + * include the result metadata. All other calls for the same frame_number + * must set this to NULL. + * + * If there was an error producing the result metadata, result must be an + * empty metadata buffer, and notify() must be called with ERROR_RESULT. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * Multiple calls to process_capture_result() with a given frame_number + * may include the result metadata. + * + * Partial metadata submitted should not include any metadata key returned + * in a previous partial result for a given frame. Each new partial result + * for that frame must also set a distinct partial_result value. + * + * If notify has been called with ERROR_RESULT, all further partial + * results for that frame are ignored by the framework. + */ + const camera_metadata_t *result; + + /** + * The number of output buffers returned in this result structure. Must be + * less than or equal to the matching capture request's count. If this is + * less than the buffer count in the capture request, at least one more call + * to process_capture_result with the same frame_number must be made, to + * return the remaining output buffers to the framework. This may only be + * zero if the structure includes valid result metadata or an input buffer + * is returned in this result. + */ + uint32_t num_output_buffers; + + /** + * The handles for the output stream buffers for this capture. They may not + * yet be filled at the time the HAL calls process_capture_result(); the + * framework will wait on the release sync fences provided by the HAL before + * reading the buffers. + * + * The HAL must set the stream buffer's release sync fence to a valid sync + * fd, or to -1 if the buffer has already been filled. + * + * If the HAL encounters an error while processing the buffer, and the + * buffer is not filled, the buffer's status field must be set to + * CAMERA3_BUFFER_STATUS_ERROR. If the HAL did not wait on the acquire fence + * before encountering the error, the acquire fence should be copied into + * the release fence, to allow the framework to wait on the fence before + * reusing the buffer. + * + * The acquire fence must be set to -1 for all output buffers. If + * num_output_buffers is zero, this may be NULL. In that case, at least one + * more process_capture_result call must be made by the HAL to provide the + * output buffers. + * + * When process_capture_result is called with a new buffer for a frame, + * all previous frames' buffers for that corresponding stream must have been + * already delivered (the fences need not have yet been signaled). + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * Gralloc buffers for a frame may be sent to framework before the + * corresponding SHUTTER-notify. + * + * Performance considerations: + * + * Buffers delivered to the framework will not be dispatched to the + * application layer until a start of exposure timestamp has been received + * via a SHUTTER notify() call. It is highly recommended to + * dispatch that call as early as possible. + */ + const camera3_stream_buffer_t *output_buffers; + + /** + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * The handle for the input stream buffer for this capture. It may not + * yet be consumed at the time the HAL calls process_capture_result(); the + * framework will wait on the release sync fences provided by the HAL before + * reusing the buffer. + * + * The HAL should handle the sync fences the same way they are done for + * output_buffers. + * + * Only one input buffer is allowed to be sent per request. Similarly to + * output buffers, the ordering of returned input buffers must be + * maintained by the HAL. + * + * Performance considerations: + * + * The input buffer should be returned as early as possible. If the HAL + * supports sync fences, it can call process_capture_result to hand it back + * with sync fences being set appropriately. If the sync fences are not + * supported, the buffer can only be returned when it is consumed, which + * may take long time; the HAL may choose to copy this input buffer to make + * the buffer return sooner. + */ + const camera3_stream_buffer_t *input_buffer; + + /** + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * In order to take advantage of partial results, the HAL must set the + * static metadata android.request.partialResultCount to the number of + * partial results it will send for each frame. + * + * Each new capture result with a partial result must set + * this field (partial_result) to a distinct inclusive value between + * 1 and android.request.partialResultCount. + * + * HALs not wishing to take advantage of this feature must not + * set an android.request.partialResultCount or partial_result to a value + * other than 1. + * + * This value must be set to 0 when a capture result contains buffers only + * and no metadata. + */ + uint32_t partial_result; + + /** + * >= CAMERA_DEVICE_API_VERSION_3_5: + * + * Specifies the number of physical camera metadata this capture result + * contains. It must be equal to the number of physical cameras being + * requested from. + * + * If the current camera device is not a logical multi-camera, or the + * corresponding capture_request doesn't request on any physical camera, + * this field must be 0. + */ + uint32_t num_physcam_metadata; + + /** + * >= CAMERA_DEVICE_API_VERSION_3_5: + * + * An array of strings containing the physical camera ids for the returned + * physical camera metadata. The length of the array is + * num_physcam_metadata. + */ + const char **physcam_ids; + + /** + * >= CAMERA_DEVICE_API_VERSION_3_5: + * + * The array of physical camera metadata for the physical cameras being + * requested upon. This array should have a 1-to-1 mapping with the + * physcam_ids. The length of the array is num_physcam_metadata. + */ + const camera_metadata_t **physcam_metadata; + +} camera3_capture_result_t; + +/********************************************************************** + * + * Callback methods for the HAL to call into the framework. + * + * These methods are used to return metadata and image buffers for a completed + * or failed captures, and to notify the framework of asynchronous events such + * as errors. + * + * The framework will not call back into the HAL from within these callbacks, + * and these calls will not block for extended periods. + * + */ +typedef struct camera3_callback_ops { + + /** + * process_capture_result: + * + * Send results from a completed capture to the framework. + * process_capture_result() may be invoked multiple times by the HAL in + * response to a single capture request. This allows, for example, the + * metadata and low-resolution buffers to be returned in one call, and + * post-processed JPEG buffers in a later call, once it is available. Each + * call must include the frame number of the request it is returning + * metadata or buffers for. + * + * A component (buffer or metadata) of the complete result may only be + * included in one process_capture_result call. A buffer for each stream, + * and the result metadata, must be returned by the HAL for each request in + * one of the process_capture_result calls, even in case of errors producing + * some of the output. A call to process_capture_result() with neither + * output buffers or result metadata is not allowed. + * + * The order of returning metadata and buffers for a single result does not + * matter, but buffers for a given stream must be returned in FIFO order. So + * the buffer for request 5 for stream A must always be returned before the + * buffer for request 6 for stream A. This also applies to the result + * metadata; the metadata for request 5 must be returned before the metadata + * for request 6. + * + * However, different streams are independent of each other, so it is + * acceptable and expected that the buffer for request 5 for stream A may be + * returned after the buffer for request 6 for stream B is. And it is + * acceptable that the result metadata for request 6 for stream B is + * returned before the buffer for request 5 for stream A is. + * + * The HAL retains ownership of result structure, which only needs to be + * valid to access during this call. The framework will copy whatever it + * needs before this call returns. + * + * The output buffers do not need to be filled yet; the framework will wait + * on the stream buffer release sync fence before reading the buffer + * data. Therefore, this method should be called by the HAL as soon as + * possible, even if some or all of the output buffers are still in + * being filled. The HAL must include valid release sync fences into each + * output_buffers stream buffer entry, or -1 if that stream buffer is + * already filled. + * + * If the result buffer cannot be constructed for a request, the HAL should + * return an empty metadata buffer, but still provide the output buffers and + * their sync fences. In addition, notify() must be called with an + * ERROR_RESULT message. + * + * If an output buffer cannot be filled, its status field must be set to + * STATUS_ERROR. In addition, notify() must be called with a ERROR_BUFFER + * message. + * + * If the entire capture has failed, then this method still needs to be + * called to return the output buffers to the framework. All the buffer + * statuses should be STATUS_ERROR, and the result metadata should be an + * empty buffer. In addition, notify() must be called with a ERROR_REQUEST + * message. In this case, individual ERROR_RESULT/ERROR_BUFFER messages + * should not be sent. + * + * Performance requirements: + * + * This is a non-blocking call. The framework will return this call in 5ms. + * + * The pipeline latency (see S7 for definition) should be less than or equal to + * 4 frame intervals, and must be less than or equal to 8 frame intervals. + * + */ + void (*process_capture_result)(const struct camera3_callback_ops *, + const camera3_capture_result_t *result); + + /** + * notify: + * + * Asynchronous notification callback from the HAL, fired for various + * reasons. Only for information independent of frame capture, or that + * require specific timing. The ownership of the message structure remains + * with the HAL, and the msg only needs to be valid for the duration of this + * call. + * + * Multiple threads may call notify() simultaneously. + * + * <= CAMERA_DEVICE_API_VERSION_3_1: + * + * The notification for the start of exposure for a given request must be + * sent by the HAL before the first call to process_capture_result() for + * that request is made. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * Buffers delivered to the framework will not be dispatched to the + * application layer until a start of exposure timestamp (or input image's + * start of exposure timestamp for a reprocess request) has been received + * via a SHUTTER notify() call. It is highly recommended to dispatch this + * call as early as possible. + * + * ------------------------------------------------------------------------ + * Performance requirements: + * + * This is a non-blocking call. The framework will return this call in 5ms. + */ + void (*notify)(const struct camera3_callback_ops *, + const camera3_notify_msg_t *msg); + + /** + * request_stream_buffers: + * + * <= CAMERA_DEVICE_API_VERISON_3_5: + * + * DO NOT USE: not defined and must be NULL. + * + * >= CAMERA_DEVICE_API_VERISON_3_6: + * + * Synchronous callback for HAL to ask for output buffer from camera service. + * + * This call may be serialized in camera service so it is strongly + * recommended to only call this method from one thread. + * + * When camera device advertises + * (android.info.supportedBufferManagementVersion == + * ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION_HIDL_DEVICE_3_5), HAL + * can use this method to request buffers from camera service. + * + * Caller is responsible for allocating enough memory for returned_buf_reqs + * argument (num_buffer_reqs * sizeof(camera3_stream_buffer_ret_t)) bytes + * and also the memory for the output_buffers field in each + * camera3_stream_buffer_ret_t + * (num_buffers_requested * sizeof(camera3_stream_buffer_t)) bytes + * + * Performance requirements: + * This is a blocking call that takes more time with more buffers requested. + * HAL should not request large amount of buffers on a latency critical code + * path. It is highly recommended to use a dedicated thread to perform + * all requestStreamBuffer calls, and adjust the thread priority and/or + * timing of making the call in order for buffers to arrive before HAL is + * ready to fill the buffer. + */ + camera3_buffer_request_status_t (*request_stream_buffers)( + const struct camera3_callback_ops *, + uint32_t num_buffer_reqs, + const camera3_buffer_request_t *buffer_reqs, + /*out*/uint32_t *num_returned_buf_reqs, + /*out*/camera3_stream_buffer_ret_t *returned_buf_reqs); + + /** + * return_stream_buffers: + * + * <= CAMERA_DEVICE_API_VERISON_3_5: + * + * DO NOT USE: not defined and must be NULL. + * + * >= CAMERA_DEVICE_API_VERISON_3_6: + * + * Synchronous callback for HAL to return output buffers to camera service. + * + * If this method is called during a configure_streams() call, it will be + * blocked until camera service finishes the ongoing configure_streams() call. + */ + void (*return_stream_buffers)( + const struct camera3_callback_ops *, + uint32_t num_buffers, + const camera3_stream_buffer_t* const* buffers); + +} camera3_callback_ops_t; + +/********************************************************************** + * + * Camera device operations + * + */ +typedef struct camera3_device_ops { + + /** + * initialize: + * + * One-time initialization to pass framework callback function pointers to + * the HAL. Will be called once after a successful open() call, before any + * other functions are called on the camera3_device_ops structure. + * + * Performance requirements: + * + * This should be a non-blocking call. The HAL should return from this call + * in 5ms, and must return from this call in 10ms. + * + * Return values: + * + * 0: On successful initialization + * + * -ENODEV: If initialization fails. Only close() can be called successfully + * by the framework after this. + */ + int (*initialize)(const struct camera3_device *, + const camera3_callback_ops_t *callback_ops); + + /********************************************************************** + * Stream management + */ + + /** + * configure_streams: + * + * CAMERA_DEVICE_API_VERSION_3_0 only: + * + * Reset the HAL camera device processing pipeline and set up new input and + * output streams. This call replaces any existing stream configuration with + * the streams defined in the stream_list. This method will be called at + * least once after initialize() before a request is submitted with + * process_capture_request(). + * + * The stream_list must contain at least one output-capable stream, and may + * not contain more than one input-capable stream. + * + * The stream_list may contain streams that are also in the currently-active + * set of streams (from the previous call to configure_stream()). These + * streams will already have valid values for usage, max_buffers, and the + * private pointer. + * + * If such a stream has already had its buffers registered, + * register_stream_buffers() will not be called again for the stream, and + * buffers from the stream can be immediately included in input requests. + * + * If the HAL needs to change the stream configuration for an existing + * stream due to the new configuration, it may rewrite the values of usage + * and/or max_buffers during the configure call. + * + * The framework will detect such a change, and will then reallocate the + * stream buffers, and call register_stream_buffers() again before using + * buffers from that stream in a request. + * + * If a currently-active stream is not included in stream_list, the HAL may + * safely remove any references to that stream. It will not be reused in a + * later configure() call by the framework, and all the gralloc buffers for + * it will be freed after the configure_streams() call returns. + * + * The stream_list structure is owned by the framework, and may not be + * accessed once this call completes. The address of an individual + * camera3_stream_t structure will remain valid for access by the HAL until + * the end of the first configure_stream() call which no longer includes + * that camera3_stream_t in the stream_list argument. The HAL may not change + * values in the stream structure outside of the private pointer, except for + * the usage and max_buffers members during the configure_streams() call + * itself. + * + * If the stream is new, the usage, max_buffer, and private pointer fields + * of the stream structure will all be set to 0. The HAL device must set + * these fields before the configure_streams() call returns. These fields + * are then used by the framework and the platform gralloc module to + * allocate the gralloc buffers for each stream. + * + * Before such a new stream can have its buffers included in a capture + * request, the framework will call register_stream_buffers() with that + * stream. However, the framework is not required to register buffers for + * _all_ streams before submitting a request. This allows for quick startup + * of (for example) a preview stream, with allocation for other streams + * happening later or concurrently. + * + * ------------------------------------------------------------------------ + * CAMERA_DEVICE_API_VERSION_3_1 only: + * + * Reset the HAL camera device processing pipeline and set up new input and + * output streams. This call replaces any existing stream configuration with + * the streams defined in the stream_list. This method will be called at + * least once after initialize() before a request is submitted with + * process_capture_request(). + * + * The stream_list must contain at least one output-capable stream, and may + * not contain more than one input-capable stream. + * + * The stream_list may contain streams that are also in the currently-active + * set of streams (from the previous call to configure_stream()). These + * streams will already have valid values for usage, max_buffers, and the + * private pointer. + * + * If such a stream has already had its buffers registered, + * register_stream_buffers() will not be called again for the stream, and + * buffers from the stream can be immediately included in input requests. + * + * If the HAL needs to change the stream configuration for an existing + * stream due to the new configuration, it may rewrite the values of usage + * and/or max_buffers during the configure call. + * + * The framework will detect such a change, and will then reallocate the + * stream buffers, and call register_stream_buffers() again before using + * buffers from that stream in a request. + * + * If a currently-active stream is not included in stream_list, the HAL may + * safely remove any references to that stream. It will not be reused in a + * later configure() call by the framework, and all the gralloc buffers for + * it will be freed after the configure_streams() call returns. + * + * The stream_list structure is owned by the framework, and may not be + * accessed once this call completes. The address of an individual + * camera3_stream_t structure will remain valid for access by the HAL until + * the end of the first configure_stream() call which no longer includes + * that camera3_stream_t in the stream_list argument. The HAL may not change + * values in the stream structure outside of the private pointer, except for + * the usage and max_buffers members during the configure_streams() call + * itself. + * + * If the stream is new, max_buffer, and private pointer fields of the + * stream structure will all be set to 0. The usage will be set to the + * consumer usage flags. The HAL device must set these fields before the + * configure_streams() call returns. These fields are then used by the + * framework and the platform gralloc module to allocate the gralloc + * buffers for each stream. + * + * Before such a new stream can have its buffers included in a capture + * request, the framework will call register_stream_buffers() with that + * stream. However, the framework is not required to register buffers for + * _all_ streams before submitting a request. This allows for quick startup + * of (for example) a preview stream, with allocation for other streams + * happening later or concurrently. + * + * ------------------------------------------------------------------------ + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * Reset the HAL camera device processing pipeline and set up new input and + * output streams. This call replaces any existing stream configuration with + * the streams defined in the stream_list. This method will be called at + * least once after initialize() before a request is submitted with + * process_capture_request(). + * + * The stream_list must contain at least one output-capable stream, and may + * not contain more than one input-capable stream. + * + * The stream_list may contain streams that are also in the currently-active + * set of streams (from the previous call to configure_stream()). These + * streams will already have valid values for usage, max_buffers, and the + * private pointer. + * + * If the HAL needs to change the stream configuration for an existing + * stream due to the new configuration, it may rewrite the values of usage + * and/or max_buffers during the configure call. + * + * The framework will detect such a change, and may then reallocate the + * stream buffers before using buffers from that stream in a request. + * + * If a currently-active stream is not included in stream_list, the HAL may + * safely remove any references to that stream. It will not be reused in a + * later configure() call by the framework, and all the gralloc buffers for + * it will be freed after the configure_streams() call returns. + * + * The stream_list structure is owned by the framework, and may not be + * accessed once this call completes. The address of an individual + * camera3_stream_t structure will remain valid for access by the HAL until + * the end of the first configure_stream() call which no longer includes + * that camera3_stream_t in the stream_list argument. The HAL may not change + * values in the stream structure outside of the private pointer, except for + * the usage and max_buffers members during the configure_streams() call + * itself. + * + * If the stream is new, max_buffer, and private pointer fields of the + * stream structure will all be set to 0. The usage will be set to the + * consumer usage flags. The HAL device must set these fields before the + * configure_streams() call returns. These fields are then used by the + * framework and the platform gralloc module to allocate the gralloc + * buffers for each stream. + * + * Newly allocated buffers may be included in a capture request at any time + * by the framework. Once a gralloc buffer is returned to the framework + * with process_capture_result (and its respective release_fence has been + * signaled) the framework may free or reuse it at any time. + * + * ------------------------------------------------------------------------ + * + * Preconditions: + * + * The framework will only call this method when no captures are being + * processed. That is, all results have been returned to the framework, and + * all in-flight input and output buffers have been returned and their + * release sync fences have been signaled by the HAL. The framework will not + * submit new requests for capture while the configure_streams() call is + * underway. + * + * Postconditions: + * + * The HAL device must configure itself to provide maximum possible output + * frame rate given the sizes and formats of the output streams, as + * documented in the camera device's static metadata. + * + * Performance requirements: + * + * This call is expected to be heavyweight and possibly take several hundred + * milliseconds to complete, since it may require resetting and + * reconfiguring the image sensor and the camera processing pipeline. + * Nevertheless, the HAL device should attempt to minimize the + * reconfiguration delay to minimize the user-visible pauses during + * application operational mode changes (such as switching from still + * capture to video recording). + * + * The HAL should return from this call in 500ms, and must return from this + * call in 1000ms. + * + * Return values: + * + * 0: On successful stream configuration + * + * -EINVAL: If the requested stream configuration is invalid. Some examples + * of invalid stream configurations include: + * + * - Including more than 1 input-capable stream (INPUT or + * BIDIRECTIONAL) + * + * - Not including any output-capable streams (OUTPUT or + * BIDIRECTIONAL) + * + * - Including streams with unsupported formats, or an unsupported + * size for that format. + * + * - Including too many output streams of a certain format. + * + * - Unsupported rotation configuration (only applies to + * devices with version >= CAMERA_DEVICE_API_VERSION_3_3) + * + * - Stream sizes/formats don't satisfy the + * camera3_stream_configuration_t->operation_mode requirements for non-NORMAL mode, + * or the requested operation_mode is not supported by the HAL. + * (only applies to devices with version >= CAMERA_DEVICE_API_VERSION_3_3) + * + * Note that the framework submitting an invalid stream + * configuration is not normal operation, since stream + * configurations are checked before configure. An invalid + * configuration means that a bug exists in the framework code, or + * there is a mismatch between the HAL's static metadata and the + * requirements on streams. + * + * -ENODEV: If there has been a fatal error and the device is no longer + * operational. Only close() can be called successfully by the + * framework after this error is returned. + */ + int (*configure_streams)(const struct camera3_device *, + camera3_stream_configuration_t *stream_list); + + /** + * register_stream_buffers: + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * DEPRECATED. This will not be called and must be set to NULL. + * + * <= CAMERA_DEVICE_API_VERSION_3_1: + * + * Register buffers for a given stream with the HAL device. This method is + * called by the framework after a new stream is defined by + * configure_streams, and before buffers from that stream are included in a + * capture request. If the same stream is listed in a subsequent + * configure_streams() call, register_stream_buffers will _not_ be called + * again for that stream. + * + * The framework does not need to register buffers for all configured + * streams before it submits the first capture request. This allows quick + * startup for preview (or similar use cases) while other streams are still + * being allocated. + * + * This method is intended to allow the HAL device to map or otherwise + * prepare the buffers for later use. The buffers passed in will already be + * locked for use. At the end of the call, all the buffers must be ready to + * be returned to the stream. The buffer_set argument is only valid for the + * duration of this call. + * + * If the stream format was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, + * the camera HAL should inspect the passed-in buffers here to determine any + * platform-private pixel format information. + * + * Performance requirements: + * + * This should be a non-blocking call. The HAL should return from this call + * in 1ms, and must return from this call in 5ms. + * + * Return values: + * + * 0: On successful registration of the new stream buffers + * + * -EINVAL: If the stream_buffer_set does not refer to a valid active + * stream, or if the buffers array is invalid. + * + * -ENOMEM: If there was a failure in registering the buffers. The framework + * must consider all the stream buffers to be unregistered, and can + * try to register again later. + * + * -ENODEV: If there is a fatal error, and the device is no longer + * operational. Only close() can be called successfully by the + * framework after this error is returned. + */ + int (*register_stream_buffers)(const struct camera3_device *, + const camera3_stream_buffer_set_t *buffer_set); + + /********************************************************************** + * Request creation and submission + */ + + /** + * construct_default_request_settings: + * + * Create capture settings for standard camera use cases. + * + * The device must return a settings buffer that is configured to meet the + * requested use case, which must be one of the CAMERA3_TEMPLATE_* + * enums. All request control fields must be included. + * + * The HAL retains ownership of this structure, but the pointer to the + * structure must be valid until the device is closed. The framework and the + * HAL may not modify the buffer once it is returned by this call. The same + * buffer may be returned for subsequent calls for the same template, or for + * other templates. + * + * Performance requirements: + * + * This should be a non-blocking call. The HAL should return from this call + * in 1ms, and must return from this call in 5ms. + * + * Return values: + * + * Valid metadata: On successful creation of a default settings + * buffer. + * + * NULL: In case of a fatal error. After this is returned, only + * the close() method can be called successfully by the + * framework. + */ + const camera_metadata_t* (*construct_default_request_settings)( + const struct camera3_device *, + int type); + + /** + * process_capture_request: + * + * Send a new capture request to the HAL. The HAL should not return from + * this call until it is ready to accept the next request to process. Only + * one call to process_capture_request() will be made at a time by the + * framework, and the calls will all be from the same thread. The next call + * to process_capture_request() will be made as soon as a new request and + * its associated buffers are available. In a normal preview scenario, this + * means the function will be called again by the framework almost + * instantly. + * + * The actual request processing is asynchronous, with the results of + * capture being returned by the HAL through the process_capture_result() + * call. This call requires the result metadata to be available, but output + * buffers may simply provide sync fences to wait on. Multiple requests are + * expected to be in flight at once, to maintain full output frame rate. + * + * The framework retains ownership of the request structure. It is only + * guaranteed to be valid during this call. The HAL device must make copies + * of the information it needs to retain for the capture processing. The HAL + * is responsible for waiting on and closing the buffers' fences and + * returning the buffer handles to the framework. + * + * The HAL must write the file descriptor for the input buffer's release + * sync fence into input_buffer->release_fence, if input_buffer is not + * NULL. If the HAL returns -1 for the input buffer release sync fence, the + * framework is free to immediately reuse the input buffer. Otherwise, the + * framework will wait on the sync fence before refilling and reusing the + * input buffer. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * + * The input/output buffers provided by the framework in each request + * may be brand new (having never before seen by the HAL). + * + * ------------------------------------------------------------------------ + * Performance considerations: + * + * Handling a new buffer should be extremely lightweight and there should be + * no frame rate degradation or frame jitter introduced. + * + * This call must return fast enough to ensure that the requested frame + * rate can be sustained, especially for streaming cases (post-processing + * quality settings set to FAST). The HAL should return this call in 1 + * frame interval, and must return from this call in 4 frame intervals. + * + * Return values: + * + * 0: On a successful start to processing the capture request + * + * -EINVAL: If the input is malformed (the settings are NULL when not + * allowed, invalid physical camera settings, + * there are 0 output buffers, etc) and capture processing + * cannot start. Failures during request processing should be + * handled by calling camera3_callback_ops_t.notify(). In case of + * this error, the framework will retain responsibility for the + * stream buffers' fences and the buffer handles; the HAL should + * not close the fences or return these buffers with + * process_capture_result. + * + * -ENODEV: If the camera device has encountered a serious error. After this + * error is returned, only the close() method can be successfully + * called by the framework. + * + */ + int (*process_capture_request)(const struct camera3_device *, + camera3_capture_request_t *request); + + /********************************************************************** + * Miscellaneous methods + */ + + /** + * get_metadata_vendor_tag_ops: + * + * Get methods to query for vendor extension metadata tag information. The + * HAL should fill in all the vendor tag operation methods, or leave ops + * unchanged if no vendor tags are defined. + * + * The definition of vendor_tag_query_ops_t can be found in + * system/media/camera/include/system/camera_metadata.h. + * + * >= CAMERA_DEVICE_API_VERSION_3_2: + * DEPRECATED. This function has been deprecated and should be set to + * NULL by the HAL. Please implement get_vendor_tag_ops in camera_common.h + * instead. + */ + void (*get_metadata_vendor_tag_ops)(const struct camera3_device*, + vendor_tag_query_ops_t* ops); + + /** + * dump: + * + * Print out debugging state for the camera device. This will be called by + * the framework when the camera service is asked for a debug dump, which + * happens when using the dumpsys tool, or when capturing a bugreport. + * + * The passed-in file descriptor can be used to write debugging text using + * dprintf() or write(). The text should be in ASCII encoding only. + * + * Performance requirements: + * + * This must be a non-blocking call. The HAL should return from this call + * in 1ms, must return from this call in 10ms. This call must avoid + * deadlocks, as it may be called at any point during camera operation. + * Any synchronization primitives used (such as mutex locks or semaphores) + * should be acquired with a timeout. + */ + void (*dump)(const struct camera3_device *, int fd); + + /** + * flush: + * + * Flush all currently in-process captures and all buffers in the pipeline + * on the given device. The framework will use this to dump all state as + * quickly as possible in order to prepare for a configure_streams() call. + * + * No buffers are required to be successfully returned, so every buffer + * held at the time of flush() (whether successfully filled or not) may be + * returned with CAMERA3_BUFFER_STATUS_ERROR. Note the HAL is still allowed + * to return valid (CAMERA3_BUFFER_STATUS_OK) buffers during this call, + * provided they are successfully filled. + * + * All requests currently in the HAL are expected to be returned as soon as + * possible. Not-in-process requests should return errors immediately. Any + * interruptible hardware blocks should be stopped, and any uninterruptible + * blocks should be waited on. + * + * flush() may be called concurrently to process_capture_request(), with the expectation that + * process_capture_request will return quickly and the request submitted in that + * process_capture_request call is treated like all other in-flight requests. Due to + * concurrency issues, it is possible that from the HAL's point of view, a + * process_capture_request() call may be started after flush has been invoked but has not + * returned yet. If such a call happens before flush() returns, the HAL should treat the new + * capture request like other in-flight pending requests (see #4 below). + * + * More specifically, the HAL must follow below requirements for various cases: + * + * 1. For captures that are too late for the HAL to cancel/stop, and will be + * completed normally by the HAL; i.e. the HAL can send shutter/notify and + * process_capture_result and buffers as normal. + * + * 2. For pending requests that have not done any processing, the HAL must call notify + * CAMERA3_MSG_ERROR_REQUEST, and return all the output buffers with + * process_capture_result in the error state (CAMERA3_BUFFER_STATUS_ERROR). + * The HAL must not place the release fence into an error state, instead, + * the release fences must be set to the acquire fences passed by the framework, + * or -1 if they have been waited on by the HAL already. This is also the path + * to follow for any captures for which the HAL already called notify() with + * CAMERA3_MSG_SHUTTER but won't be producing any metadata/valid buffers for. + * After CAMERA3_MSG_ERROR_REQUEST, for a given frame, only process_capture_results with + * buffers in CAMERA3_BUFFER_STATUS_ERROR are allowed. No further notifys or + * process_capture_result with non-null metadata is allowed. + * + * 3. For partially completed pending requests that will not have all the output + * buffers or perhaps missing metadata, the HAL should follow below: + * + * 3.1. Call notify with CAMERA3_MSG_ERROR_RESULT if some of the expected result + * metadata (i.e. one or more partial metadata) won't be available for the capture. + * + * 3.2. Call notify with CAMERA3_MSG_ERROR_BUFFER for every buffer that won't + * be produced for the capture. + * + * 3.3 Call notify with CAMERA3_MSG_SHUTTER with the capture timestamp before + * any buffers/metadata are returned with process_capture_result. + * + * 3.4 For captures that will produce some results, the HAL must not call + * CAMERA3_MSG_ERROR_REQUEST, since that indicates complete failure. + * + * 3.5. Valid buffers/metadata should be passed to the framework as normal. + * + * 3.6. Failed buffers should be returned to the framework as described for case 2. + * But failed buffers do not have to follow the strict ordering valid buffers do, + * and may be out-of-order with respect to valid buffers. For example, if buffers + * A, B, C, D, E are sent, D and E are failed, then A, E, B, D, C is an acceptable + * return order. + * + * 3.7. For fully-missing metadata, calling CAMERA3_MSG_ERROR_RESULT is sufficient, no + * need to call process_capture_result with NULL metadata or equivalent. + * + * 4. If a flush() is invoked while a process_capture_request() invocation is active, that + * process call should return as soon as possible. In addition, if a process_capture_request() + * call is made after flush() has been invoked but before flush() has returned, the + * capture request provided by the late process_capture_request call should be treated like + * a pending request in case #2 above. + * + * flush() should only return when there are no more outstanding buffers or + * requests left in the HAL. The framework may call configure_streams (as + * the HAL state is now quiesced) or may issue new requests. + * + * Note that it's sufficient to only support fully-succeeded and fully-failed result cases. + * However, it is highly desirable to support the partial failure cases as well, as it + * could help improve the flush call overall performance. + * + * Performance requirements: + * + * The HAL should return from this call in 100ms, and must return from this + * call in 1000ms. And this call must not be blocked longer than pipeline + * latency (see S7 for definition). + * + * Version information: + * + * only available if device version >= CAMERA_DEVICE_API_VERSION_3_1. + * + * Return values: + * + * 0: On a successful flush of the camera HAL. + * + * -EINVAL: If the input is malformed (the device is not valid). + * + * -ENODEV: If the camera device has encountered a serious error. After this + * error is returned, only the close() method can be successfully + * called by the framework. + */ + int (*flush)(const struct camera3_device *); + + /** + * signal_stream_flush: + * + * <= CAMERA_DEVICE_API_VERISON_3_5: + * + * Not defined and must be NULL + * + * >= CAMERA_DEVICE_API_VERISON_3_6: + * + * Signaling HAL camera service is about to perform configure_streams() call + * and HAL must return all buffers of designated streams. HAL must finish + * inflight requests normally and return all buffers belonging to the + * designated streams through process_capture_result() or + * return_stream_buffers() API in a timely manner, or camera service will run + * into a fatal error. + * + * Note that this call serves as an optional hint and camera service may + * skip calling this if all buffers are already returned. + * + */ + void (*signal_stream_flush)(const struct camera3_device*, + uint32_t num_streams, + const camera3_stream_t* const* streams); + + /** + * is_reconfiguration_required: + * + * <= CAMERA_DEVICE_API_VERISON_3_5: + * + * Not defined and must be NULL + * + * >= CAMERA_DEVICE_API_VERISON_3_6: + * + * Check whether complete stream reconfiguration is required for possible new session + * parameter values. + * + * This method must be called by the camera framework in case the client changes + * the value of any advertised session parameters. Depending on the specific values + * the HAL can decide whether a complete stream reconfiguration is required. In case + * the HAL returns -ENVAL, the camera framework must skip the internal reconfiguration. + * In case Hal returns 0, the framework must reconfigure the streams and pass the + * new session parameter values accordingly. + * This call may be done by the framework some time before the request with new parameters + * is submitted to the HAL, and the request may be cancelled before it ever gets submitted. + * Therefore, the HAL must not use this query as an indication to change its behavior in any + * way. + * ------------------------------------------------------------------------ + * + * Preconditions: + * + * The framework can call this method at any time after active + * session configuration. There must be no impact on the performance of + * pending camera requests in any way. In particular there must not be + * any glitches or delays during normal camera streaming. + * + * Performance requirements: + * HW and SW camera settings must not be changed and there must not be + * a user-visible impact on camera performance. + * + * @param oldSessionParams The currently applied session parameters. + * @param newSessionParams The new session parameters set by client. + * + * @return Status Status code for the operation, one of: + * 0: In case the stream reconfiguration is required + * + * -EINVAL: In case the stream reconfiguration is not required. + * + * -ENOSYS: In case the camera device does not support the + * reconfiguration query. + */ + int (*is_reconfiguration_required)(const struct camera3_device*, + const camera_metadata_t* old_session_params, + const camera_metadata_t* new_session_params); + + /* reserved for future use */ + void *reserved[6]; +} camera3_device_ops_t; + +/********************************************************************** + * + * Camera device definition + * + */ +typedef struct camera3_device { + /** + * common.version must equal CAMERA_DEVICE_API_VERSION_3_0 to identify this + * device as implementing version 3.0 of the camera device HAL. + * + * Performance requirements: + * + * Camera open (common.module->common.methods->open) should return in 200ms, and must return + * in 500ms. + * Camera close (common.close) should return in 200ms, and must return in 500ms. + * + */ + hw_device_t common; + camera3_device_ops_t *ops; + void *priv; +} camera3_device_t; + +__END_DECLS + +#endif /* #ifdef ANDROID_INCLUDE_CAMERA3_H */ diff --git a/include_all/hardware/camera_common.h b/include_all/hardware/camera_common.h new file mode 100644 index 00000000..16651a94 --- /dev/null +++ b/include_all/hardware/camera_common.h @@ -0,0 +1,1218 @@ +/* + * Copyright (C) 2012 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. + */ + +// FIXME: add well-defined names for cameras + +#ifndef ANDROID_INCLUDE_CAMERA_COMMON_H +#define ANDROID_INCLUDE_CAMERA_COMMON_H + +#include <stdint.h> +#include <stdbool.h> +#include <sys/cdefs.h> +#include <sys/types.h> +#include <cutils/native_handle.h> +#include <system/camera.h> +#include <system/camera_vendor_tags.h> +#include <hardware/hardware.h> +#include <hardware/gralloc.h> + +__BEGIN_DECLS + +/** + * The id of this module + */ +#define CAMERA_HARDWARE_MODULE_ID "camera" + +/** + * Module versioning information for the Camera hardware module, based on + * camera_module_t.common.module_api_version. The two most significant hex + * digits represent the major version, and the two least significant represent + * the minor version. + * + ******************************************************************************* + * Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0] + * + * Camera modules that report these version numbers implement the initial + * camera module HAL interface. All camera devices openable through this + * module support only version 1 of the camera device HAL. The device_version + * and static_camera_characteristics fields of camera_info are not valid. Only + * the android.hardware.Camera API can be supported by this module and its + * devices. + * + ******************************************************************************* + * Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0] + * + * Camera modules that report this version number implement the second version + * of the camera module HAL interface. Camera devices openable through this + * module may support either version 1.0 or version 2.0 of the camera device + * HAL interface. The device_version field of camera_info is always valid; the + * static_camera_characteristics field of camera_info is valid if the + * device_version field is 2.0 or higher. + * + ******************************************************************************* + * Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1] + * + * This camera module version adds support for asynchronous callbacks to the + * framework from the camera HAL module, which is used to notify the framework + * about changes to the camera module state. Modules that provide a valid + * set_callbacks() method must report at least this version number. + * + ******************************************************************************* + * Version: 2.2 [CAMERA_MODULE_API_VERSION_2_2] + * + * This camera module version adds vendor tag support from the module, and + * deprecates the old vendor_tag_query_ops that were previously only + * accessible with a device open. + * + ******************************************************************************* + * Version: 2.3 [CAMERA_MODULE_API_VERSION_2_3] + * + * This camera module version adds open legacy camera HAL device support. + * Framework can use it to open the camera device as lower device HAL version + * HAL device if the same device can support multiple device API versions. + * The standard hardware module open call (common.methods->open) continues + * to open the camera device with the latest supported version, which is + * also the version listed in camera_info_t.device_version. + * + ******************************************************************************* + * Version: 2.4 [CAMERA_MODULE_API_VERSION_2_4] + * + * This camera module version adds below API changes: + * + * 1. Torch mode support. The framework can use it to turn on torch mode for + * any camera device that has a flash unit, without opening a camera device. The + * camera device has a higher priority accessing the flash unit than the camera + * module; opening a camera device will turn off the torch if it had been enabled + * through the module interface. When there are any resource conflicts, such as + * open() is called to open a camera device, the camera HAL module must notify the + * framework through the torch mode status callback that the torch mode has been + * turned off. + * + * 2. External camera (e.g. USB hot-plug camera) support. The API updates specify that + * the camera static info is only available when camera is connected and ready to + * use for external hot-plug cameras. Calls to get static info will be invalid + * calls when camera status is not CAMERA_DEVICE_STATUS_PRESENT. The frameworks + * will only count on device status change callbacks to manage the available external + * camera list. + * + * 3. Camera arbitration hints. This module version adds support for explicitly + * indicating the number of camera devices that can be simultaneously opened and used. + * To specify valid combinations of devices, the resource_cost and conflicting_devices + * fields should always be set in the camera_info structure returned by the + * get_camera_info call. + * + * 4. Module initialization method. This will be called by the camera service + * right after the HAL module is loaded, to allow for one-time initialization + * of the HAL. It is called before any other module methods are invoked. + * + ******************************************************************************* + * Version: 2.5 [CAMERA_MODULE_API_VERSION_2_5] + * + * This camera module version adds below API changes: + * + * 1. Support to query characteristics of a non-standalone physical camera, which can + * only be accessed as part of a logical camera. It also adds camera stream combination + * query. + * + * 2. Ability to query whether a particular camera stream combination is + * supported by the camera device. + * + * 3. Device state change notification. This module version also supports + * notification about the overall device state change, such as + * folding/unfolding, or covering/uncovering of shutter. + */ + +/** + * Predefined macros for currently-defined version numbers + */ + +/** + * All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated + * as CAMERA_MODULE_API_VERSION_1_0 + */ +#define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) +#define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) +#define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1) +#define CAMERA_MODULE_API_VERSION_2_2 HARDWARE_MODULE_API_VERSION(2, 2) +#define CAMERA_MODULE_API_VERSION_2_3 HARDWARE_MODULE_API_VERSION(2, 3) +#define CAMERA_MODULE_API_VERSION_2_4 HARDWARE_MODULE_API_VERSION(2, 4) +#define CAMERA_MODULE_API_VERSION_2_5 HARDWARE_MODULE_API_VERSION(2, 5) + +#define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_5 + +/** + * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated + * as CAMERA_DEVICE_API_VERSION_1_0 + */ +#define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) // DEPRECATED +#define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) // NO LONGER SUPPORTED +#define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1) // NO LONGER SUPPORTED +#define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0) // NO LONGER SUPPORTED +#define CAMERA_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1) // NO LONGER SUPPORTED +#define CAMERA_DEVICE_API_VERSION_3_2 HARDWARE_DEVICE_API_VERSION(3, 2) +#define CAMERA_DEVICE_API_VERSION_3_3 HARDWARE_DEVICE_API_VERSION(3, 3) +#define CAMERA_DEVICE_API_VERSION_3_4 HARDWARE_DEVICE_API_VERSION(3, 4) +#define CAMERA_DEVICE_API_VERSION_3_5 HARDWARE_DEVICE_API_VERSION(3, 5) +#define CAMERA_DEVICE_API_VERSION_3_6 HARDWARE_DEVICE_API_VERSION(3, 6) + +// Device version 3.5 is current, older HAL camera device versions are not +// recommended for new devices. +#define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_3_5 + +/** + * Defined in /system/media/camera/include/system/camera_metadata.h + */ +typedef struct camera_metadata camera_metadata_t; + +typedef struct camera_info { + /** + * The direction that the camera faces to. See system/core/include/system/camera.h + * for camera facing definitions. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_2_3 or lower: + * + * It should be CAMERA_FACING_BACK or CAMERA_FACING_FRONT. + * + * CAMERA_MODULE_API_VERSION_2_4 or higher: + * + * It should be CAMERA_FACING_BACK, CAMERA_FACING_FRONT or + * CAMERA_FACING_EXTERNAL. + */ + int facing; + + /** + * The orientation of the camera image. The value is the angle that the + * camera image needs to be rotated clockwise so it shows correctly on the + * display in its natural orientation. It should be 0, 90, 180, or 270. + * + * For example, suppose a device has a naturally tall screen. The + * back-facing camera sensor is mounted in landscape. You are looking at the + * screen. If the top side of the camera sensor is aligned with the right + * edge of the screen in natural orientation, the value should be 90. If the + * top side of a front-facing camera sensor is aligned with the right of the + * screen, the value should be 270. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_2_3 or lower: + * + * Valid in all camera_module versions. + * + * CAMERA_MODULE_API_VERSION_2_4 or higher: + * + * Valid if camera facing is CAMERA_FACING_BACK or CAMERA_FACING_FRONT, + * not valid if camera facing is CAMERA_FACING_EXTERNAL. + */ + int orientation; + + /** + * The value of camera_device_t.common.version. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_0: + * + * Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do + * not read this field. + * + * CAMERA_MODULE_API_VERSION_2_0 or higher: + * + * Always valid + * + */ + uint32_t device_version; + + /** + * The camera's fixed characteristics, which include all static camera metadata + * specified in system/media/camera/docs/docs.html. This should be a sorted metadata + * buffer, and may not be modified or freed by the caller. The pointer should remain + * valid for the lifetime of the camera module, and values in it may not + * change after it is returned by get_camera_info(). + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_0: + * + * Not valid. Extra characteristics are not available. Do not read this + * field. + * + * CAMERA_MODULE_API_VERSION_2_0 or higher: + * + * Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read + * otherwise. + * + */ + const camera_metadata_t *static_camera_characteristics; + + /** + * The total resource "cost" of using this camera, represented as an integer + * value in the range [0, 100] where 100 represents total usage of the shared + * resource that is the limiting bottleneck of the camera subsystem. This may + * be a very rough estimate, and is used as a hint to the camera service to + * determine when to disallow multiple applications from simultaneously + * opening different cameras advertised by the camera service. + * + * The camera service must be able to simultaneously open and use any + * combination of camera devices exposed by the HAL where the sum of + * the resource costs of these cameras is <= 100. For determining cost, + * each camera device must be assumed to be configured and operating at + * the maximally resource-consuming framerate and stream size settings + * available in the configuration settings exposed for that device through + * the camera metadata. + * + * The camera service may still attempt to simultaneously open combinations + * of camera devices with a total resource cost > 100. This may succeed or + * fail. If this succeeds, combinations of configurations that are not + * supported due to resource constraints from having multiple open devices + * should fail during the configure calls. If the total resource cost is + * <= 100, open and configure should never fail for any stream configuration + * settings or other device capabilities that would normally succeed for a + * device when it is the only open camera device. + * + * This field will be used to determine whether background applications are + * allowed to use this camera device while other applications are using other + * camera devices. Note: multiple applications will never be allowed by the + * camera service to simultaneously open the same camera device. + * + * Example use cases: + * + * Ex. 1: Camera Device 0 = Back Camera + * Camera Device 1 = Front Camera + * - Using both camera devices causes a large framerate slowdown due to + * limited ISP bandwidth. + * + * Configuration: + * + * Camera Device 0 - resource_cost = 51 + * conflicting_devices = null + * Camera Device 1 - resource_cost = 51 + * conflicting_devices = null + * + * Result: + * + * Since the sum of the resource costs is > 100, if a higher-priority + * application has either device open, no lower-priority applications will be + * allowed by the camera service to open either device. If a lower-priority + * application is using a device that a higher-priority subsequently attempts + * to open, the lower-priority application will be forced to disconnect the + * the device. + * + * If the highest-priority application chooses, it may still attempt to open + * both devices (since these devices are not listed as conflicting in the + * conflicting_devices fields), but usage of these devices may fail in the + * open or configure calls. + * + * Ex. 2: Camera Device 0 = Left Back Camera + * Camera Device 1 = Right Back Camera + * Camera Device 2 = Combined stereo camera using both right and left + * back camera sensors used by devices 0, and 1 + * Camera Device 3 = Front Camera + * - Due to do hardware constraints, up to two cameras may be open at once. The + * combined stereo camera may never be used at the same time as either of the + * two back camera devices (device 0, 1), and typically requires too much + * bandwidth to use at the same time as the front camera (device 3). + * + * Configuration: + * + * Camera Device 0 - resource_cost = 50 + * conflicting_devices = { 2 } + * Camera Device 1 - resource_cost = 50 + * conflicting_devices = { 2 } + * Camera Device 2 - resource_cost = 100 + * conflicting_devices = { 0, 1 } + * Camera Device 3 - resource_cost = 50 + * conflicting_devices = null + * + * Result: + * + * Based on the conflicting_devices fields, the camera service guarantees that + * the following sets of open devices will never be allowed: { 1, 2 }, { 0, 2 }. + * + * Based on the resource_cost fields, if a high-priority foreground application + * is using camera device 0, a background application would be allowed to open + * camera device 1 or 3 (but would be forced to disconnect it again if the + * foreground application opened another device). + * + * The highest priority application may still attempt to simultaneously open + * devices 0, 2, and 3, but the HAL may fail in open or configure calls for + * this combination. + * + * Ex. 3: Camera Device 0 = Back Camera + * Camera Device 1 = Front Camera + * Camera Device 2 = Low-power Front Camera that uses the same + * sensor as device 1, but only exposes image stream + * resolutions that can be used in low-power mode + * - Using both front cameras (device 1, 2) at the same time is impossible due + * a shared physical sensor. Using the back and "high-power" front camera + * (device 1) may be impossible for some stream configurations due to hardware + * limitations, but the "low-power" front camera option may always be used as + * it has special dedicated hardware. + * + * Configuration: + * + * Camera Device 0 - resource_cost = 100 + * conflicting_devices = null + * Camera Device 1 - resource_cost = 100 + * conflicting_devices = { 2 } + * Camera Device 2 - resource_cost = 0 + * conflicting_devices = { 1 } + * Result: + * + * Based on the conflicting_devices fields, the camera service guarantees that + * the following sets of open devices will never be allowed: { 1, 2 }. + * + * Based on the resource_cost fields, only the highest priority application + * may attempt to open both device 0 and 1 at the same time. If a higher-priority + * application is not using device 1 or 2, a low-priority background application + * may open device 2 (but will be forced to disconnect it if a higher-priority + * application subsequently opens device 1 or 2). + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_2_3 or lower: + * + * Not valid. Can be assumed to be 100. Do not read this field. + * + * CAMERA_MODULE_API_VERSION_2_4 or higher: + * + * Always valid. + */ + int resource_cost; + + /** + * An array of camera device IDs represented as NULL-terminated strings + * indicating other devices that cannot be simultaneously opened while this + * camera device is in use. + * + * This field is intended to be used to indicate that this camera device + * is a composite of several other camera devices, or otherwise has + * hardware dependencies that prohibit simultaneous usage. If there are no + * dependencies, a NULL may be returned in this field to indicate this. + * + * The camera service will never simultaneously open any of the devices + * in this list while this camera device is open. + * + * The strings pointed to in this field will not be cleaned up by the camera + * service, and must remain while this device is plugged in. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_2_3 or lower: + * + * Not valid. Can be assumed to be NULL. Do not read this field. + * + * CAMERA_MODULE_API_VERSION_2_4 or higher: + * + * Always valid. + */ + char** conflicting_devices; + + /** + * The length of the array given in the conflicting_devices field. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_2_3 or lower: + * + * Not valid. Can be assumed to be 0. Do not read this field. + * + * CAMERA_MODULE_API_VERSION_2_4 or higher: + * + * Always valid. + */ + size_t conflicting_devices_length; + +} camera_info_t; + +/** + * camera_device_status_t: + * + * The current status of the camera device, as provided by the HAL through the + * camera_module_callbacks.camera_device_status_change() call. + * + * At module load time, the framework will assume all camera devices are in the + * CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke + * camera_module_callbacks::camera_device_status_change to inform the framework + * of any initially NOT_PRESENT devices. + * + * Allowed transitions: + * PRESENT -> NOT_PRESENT + * NOT_PRESENT -> ENUMERATING + * NOT_PRESENT -> PRESENT + * ENUMERATING -> PRESENT + * ENUMERATING -> NOT_PRESENT + */ +typedef enum camera_device_status { + /** + * The camera device is not currently connected, and opening it will return + * failure. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_2_3 or lower: + * + * Calls to get_camera_info must still succeed, and provide the same information + * it would if the camera were connected. + * + * CAMERA_MODULE_API_VERSION_2_4: + * + * The camera device at this status must return -EINVAL for get_camera_info call, + * as the device is not connected. + */ + CAMERA_DEVICE_STATUS_NOT_PRESENT = 0, + + /** + * The camera device is connected, and opening it will succeed. + * + * CAMERA_MODULE_API_VERSION_2_3 or lower: + * + * The information returned by get_camera_info cannot change due to this status + * change. By default, the framework will assume all devices are in this state. + * + * CAMERA_MODULE_API_VERSION_2_4: + * + * The information returned by get_camera_info will become valid after a device's + * status changes to this. By default, the framework will assume all devices are in + * this state. + */ + CAMERA_DEVICE_STATUS_PRESENT = 1, + + /** + * The camera device is connected, but it is undergoing an enumeration and + * so opening the device will return -EBUSY. + * + * CAMERA_MODULE_API_VERSION_2_3 or lower: + * + * Calls to get_camera_info must still succeed, as if the camera was in the + * PRESENT status. + * + * CAMERA_MODULE_API_VERSION_2_4: + * + * The camera device at this status must return -EINVAL for get_camera_info for call, + * as the device is not ready. + */ + CAMERA_DEVICE_STATUS_ENUMERATING = 2, + +} camera_device_status_t; + +/** + * torch_mode_status_t: + * + * The current status of the torch mode, as provided by the HAL through the + * camera_module_callbacks.torch_mode_status_change() call. + * + * The torch mode status of a camera device is applicable only when the camera + * device is present. The framework will not call set_torch_mode() to turn on + * torch mode of a camera device if the camera device is not present. At module + * load time, the framework will assume torch modes are in the + * TORCH_MODE_STATUS_AVAILABLE_OFF state if the camera device is present and + * android.flash.info.available is reported as true via get_camera_info() call. + * + * The behaviors of the camera HAL module that the framework expects in the + * following situations when a camera device's status changes: + * 1. A previously-disconnected camera device becomes connected. + * After camera_module_callbacks::camera_device_status_change() is invoked + * to inform the framework that the camera device is present, the framework + * will assume the camera device's torch mode is in + * TORCH_MODE_STATUS_AVAILABLE_OFF state. The camera HAL module does not need + * to invoke camera_module_callbacks::torch_mode_status_change() unless the + * flash unit is unavailable to use by set_torch_mode(). + * + * 2. A previously-connected camera becomes disconnected. + * After camera_module_callbacks::camera_device_status_change() is invoked + * to inform the framework that the camera device is not present, the + * framework will not call set_torch_mode() for the disconnected camera + * device until its flash unit becomes available again. The camera HAL + * module does not need to invoke + * camera_module_callbacks::torch_mode_status_change() separately to inform + * that the flash unit has become unavailable. + * + * 3. open() is called to open a camera device. + * The camera HAL module must invoke + * camera_module_callbacks::torch_mode_status_change() for all flash units + * that have entered TORCH_MODE_STATUS_NOT_AVAILABLE state and can not be + * turned on by calling set_torch_mode() anymore due to this open() call. + * open() must not trigger TORCH_MODE_STATUS_AVAILABLE_OFF before + * TORCH_MODE_STATUS_NOT_AVAILABLE for all flash units that have become + * unavailable. + * + * 4. close() is called to close a camera device. + * The camera HAL module must invoke + * camera_module_callbacks::torch_mode_status_change() for all flash units + * that have entered TORCH_MODE_STATUS_AVAILABLE_OFF state and can be turned + * on by calling set_torch_mode() again because of enough resources freed + * up by this close() call. + * + * Note that the framework calling set_torch_mode() successfully must trigger + * TORCH_MODE_STATUS_AVAILABLE_OFF or TORCH_MODE_STATUS_AVAILABLE_ON callback + * for the given camera device. Additionally it must trigger + * TORCH_MODE_STATUS_AVAILABLE_OFF callbacks for other previously-on torch + * modes if HAL cannot keep multiple torch modes on simultaneously. + */ +typedef enum torch_mode_status { + + /** + * The flash unit is no longer available and the torch mode can not be + * turned on by calling set_torch_mode(). If the torch mode is on, it + * will be turned off by HAL before HAL calls torch_mode_status_change(). + */ + TORCH_MODE_STATUS_NOT_AVAILABLE = 0, + + /** + * A torch mode has become off and available to be turned on via + * set_torch_mode(). This may happen in the following + * cases: + * 1. After the resources to turn on the torch mode have become available. + * 2. After set_torch_mode() is called to turn off the torch mode. + * 3. After the framework turned on the torch mode of some other camera + * device and HAL had to turn off the torch modes of any camera devices + * that were previously on. + */ + TORCH_MODE_STATUS_AVAILABLE_OFF = 1, + + /** + * A torch mode has become on and available to be turned off via + * set_torch_mode(). This can happen only after set_torch_mode() is called + * to turn on the torch mode. + */ + TORCH_MODE_STATUS_AVAILABLE_ON = 2, + +} torch_mode_status_t; + +/** + * Callback functions for the camera HAL module to use to inform the framework + * of changes to the camera subsystem. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * Each callback is called only by HAL modules implementing the indicated + * version or higher of the HAL module API interface. + * + * CAMERA_MODULE_API_VERSION_2_1: + * camera_device_status_change() + * + * CAMERA_MODULE_API_VERSION_2_4: + * torch_mode_status_change() + + */ +typedef struct camera_module_callbacks { + + /** + * camera_device_status_change: + * + * Callback to the framework to indicate that the state of a specific camera + * device has changed. At module load time, the framework will assume all + * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL + * must call this method to inform the framework of any initially + * NOT_PRESENT devices. + * + * This callback is added for CAMERA_MODULE_API_VERSION_2_1. + * + * camera_module_callbacks: The instance of camera_module_callbacks_t passed + * to the module with set_callbacks. + * + * camera_id: The ID of the camera device that has a new status. + * + * new_status: The new status code, one of the camera_device_status_t enums, + * or a platform-specific status. + * + */ + void (*camera_device_status_change)(const struct camera_module_callbacks*, + int camera_id, + int new_status); + + /** + * torch_mode_status_change: + * + * Callback to the framework to indicate that the state of the torch mode + * of the flash unit associated with a specific camera device has changed. + * At module load time, the framework will assume the torch modes are in + * the TORCH_MODE_STATUS_AVAILABLE_OFF state if android.flash.info.available + * is reported as true via get_camera_info() call. + * + * This callback is added for CAMERA_MODULE_API_VERSION_2_4. + * + * camera_module_callbacks: The instance of camera_module_callbacks_t + * passed to the module with set_callbacks. + * + * camera_id: The ID of camera device whose flash unit has a new torch mode + * status. + * + * new_status: The new status code, one of the torch_mode_status_t enums. + */ + void (*torch_mode_status_change)(const struct camera_module_callbacks*, + const char* camera_id, + int new_status); + + +} camera_module_callbacks_t; + +/** + * camera_stream_t: + * + * A handle to a single camera input or output stream. A stream is defined by + * the framework by its buffer resolution and format and gralloc usage flags. + * + * The stream structures are owned by the framework and pointers to a + * camera_stream passed into the HAL by is_stream_combination_supported() are + * only valid within the scope of the call. + * + * All camera_stream members are immutable. + */ +typedef struct camera_stream { + /** + * The type of the stream, one of the camera3_stream_type_t values. + */ + int stream_type; + + /** + * The width in pixels of the buffers in this stream + */ + uint32_t width; + + /** + * The height in pixels of the buffers in this stream + */ + uint32_t height; + + /** + * The pixel format for the buffers in this stream. Format is a value from + * the HAL_PIXEL_FORMAT_* list in system/core/include/system/graphics.h, or + * from device-specific headers. + * + * If HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED is used, then the platform + * gralloc module will select a format based on the usage flags provided by + * the camera device and the other endpoint of the stream. + * + */ + int format; + + /** + * The gralloc usage flags for this stream, as needed by the HAL. The usage + * flags are defined in gralloc.h (GRALLOC_USAGE_*), or in device-specific + * headers. + * + * For output streams, these are the HAL's producer usage flags. For input + * streams, these are the HAL's consumer usage flags. The usage flags from + * the producer and the consumer will be combined together and then passed + * to the platform gralloc HAL module for allocating the gralloc buffers for + * each stream. + * + * The usage flag for an output stream may be bitwise + * combination of usage flags for multiple consumers, for the purpose of + * sharing one camera stream between those consumers. The HAL must fail + * the stream combination query call with -EINVAL if the combined flags cannot be + * supported due to imcompatible buffer format, dataSpace, or other hardware + * limitations. + */ + uint32_t usage; + + /** + * A field that describes the contents of the buffer. The format and buffer + * dimensions define the memory layout and structure of the stream buffers, + * while dataSpace defines the meaning of the data within the buffer. + * + * For most formats, dataSpace defines the color space of the image data. + * In addition, for some formats, dataSpace indicates whether image- or + * depth-based data is requested. See system/core/include/system/graphics.h + * for details of formats and valid dataSpace values for each format. + * + * Always set by the camera service. The dataspace values are set + * using the V0 dataspace definitions in graphics.h + */ + android_dataspace_t data_space; + + /** + * The required output rotation of the stream, one of + * the camera3_stream_rotation_t values. This must be inspected by HAL along + * with stream width and height. For example, if the rotation is 90 degree + * and the stream width and height is 720 and 1280 respectively, camera service + * will supply buffers of size 720x1280, and HAL should capture a 1280x720 image + * and rotate the image by 90 degree counterclockwise. The rotation field is + * no-op when the stream type is input. Camera HAL must ignore the rotation + * field for an input stream. + * + * Always set by camera service. HAL must inspect this field during stream + * combination query and return -EINVAL if it cannot perform such rotation. + * HAL must always support CAMERA3_STREAM_ROTATION_0, so a + * is_stream_combination_supported() call must not fail for unsupported rotation if + * rotation field of all streams is CAMERA3_STREAM_ROTATION_0. + * + */ + int rotation; + + /** + * The physical camera id this stream belongs to. + * Always set by camera service. If the camera device is not a logical + * multi camera, or if the camera is a logical multi camera but the stream + * is not a physical output stream, this field will point to a 0-length + * string. + * + * A logical multi camera is a camera device backed by multiple physical + * cameras that are also exposed to the application. And for a logical + * multi camera, a physical output stream is an output stream specifically + * requested on an underlying physical camera. + * + * For an input stream, this field is guaranteed to be a 0-length string. + */ + const char* physical_camera_id; + +} camera_stream_t; + +/** + * camera_stream_combination_t: + * + * A structure of stream definitions, used by is_stream_combination_supported(). This + * structure defines all the input & output streams for specific camera use case. + */ +typedef struct camera_stream_combination { + /** + * The total number of streams by the framework. This includes + * both input and output streams. The number of streams will be at least 1, + * and there will be at least one output-capable stream. + */ + uint32_t num_streams; + + /** + * An array of camera streams, defining the input/output + * stream combination for the camera HAL device. + * + * At most one input-capable stream may be defined. + * + * At least one output-capable stream must be defined. + */ + camera_stream_t *streams; + + /** + * The operation mode of streams in this stream combination, one of the value + * defined in camera3_stream_configuration_mode_t. + * + */ + uint32_t operation_mode; + +} camera_stream_combination_t; + +/** + * device_state_t: + * + * Possible physical states of the overall device, for use with + * notify_device_state_change. + */ +typedef enum device_state { + /** + * The device is in its normal physical configuration. This is the default if the + * device does not support multiple different states. + */ + NORMAL = 0, + + /** + * Camera device(s) facing backward are covered. + */ + BACK_COVERED = 1 << 0, + + /** + * Camera device(s) facing foward are covered. + */ + FRONT_COVERED = 1 << 1, + + /** + * The device is folded. If not set, the device is unfolded or does not + * support folding. + * + * The exact point when this status change happens during the folding + * operation is device-specific. + */ + FOLDED = 1 << 2, + + /** + * First vendor-specific device state. All bits above and including this one + * are for vendor state values. Values below this one must only be used + * for framework-defined states. + */ + VENDOR_STATE_START = 1LL << 32 + +} device_state_t; + +typedef struct camera_module { + /** + * Common methods of the camera module. This *must* be the first member of + * camera_module as users of this structure will cast a hw_module_t to + * camera_module pointer in contexts where it's known the hw_module_t + * references a camera_module. + * + * The return values for common.methods->open for camera_module are: + * + * 0: On a successful open of the camera device. + * + * -ENODEV: The camera device cannot be opened due to an internal + * error. + * + * -EINVAL: The input arguments are invalid, i.e. the id is invalid, + * and/or the module is invalid. + * + * -EBUSY: The camera device was already opened for this camera id + * (by using this method or open_legacy), + * regardless of the device HAL version it was opened as. + * + * -EUSERS: The maximal number of camera devices that can be + * opened concurrently were opened already, either by + * this method or the open_legacy method. + * + * All other return values from common.methods->open will be treated as + * -ENODEV. + */ + hw_module_t common; + + /** + * get_number_of_cameras: + * + * Returns the number of camera devices accessible through the camera + * module. The camera devices are numbered 0 through N-1, where N is the + * value returned by this call. The name of the camera device for open() is + * simply the number converted to a string. That is, "0" for camera ID 0, + * "1" for camera ID 1. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_2_3 or lower: + * + * The value here must be static, and cannot change after the first call + * to this method. + * + * CAMERA_MODULE_API_VERSION_2_4 or higher: + * + * The value here must be static, and must count only built-in cameras, + * which have CAMERA_FACING_BACK or CAMERA_FACING_FRONT camera facing values + * (camera_info.facing). The HAL must not include the external cameras + * (camera_info.facing == CAMERA_FACING_EXTERNAL) into the return value + * of this call. Frameworks will use camera_device_status_change callback + * to manage number of external cameras. + */ + int (*get_number_of_cameras)(void); + + /** + * get_camera_info: + * + * Return the static camera information for a given camera device. This + * information may not change for a camera device. + * + * Return values: + * + * 0: On a successful operation + * + * -ENODEV: The information cannot be provided due to an internal + * error. + * + * -EINVAL: The input arguments are invalid, i.e. the id is invalid, + * and/or the module is invalid. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_2_4 or higher: + * + * When a camera is disconnected, its camera id becomes invalid. Calling this + * this method with this invalid camera id will get -EINVAL and NULL camera + * static metadata (camera_info.static_camera_characteristics). + */ + int (*get_camera_info)(int camera_id, struct camera_info *info); + + /** + * set_callbacks: + * + * Provide callback function pointers to the HAL module to inform framework + * of asynchronous camera module events. The framework will call this + * function once after initial camera HAL module load, after the + * get_number_of_cameras() method is called for the first time, and before + * any other calls to the module. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0: + * + * Not provided by HAL module. Framework may not call this function. + * + * CAMERA_MODULE_API_VERSION_2_1: + * + * Valid to be called by the framework. + * + * Return values: + * + * 0: On a successful operation + * + * -ENODEV: The operation cannot be completed due to an internal + * error. + * + * -EINVAL: The input arguments are invalid, i.e. the callbacks are + * null + */ + int (*set_callbacks)(const camera_module_callbacks_t *callbacks); + + /** + * get_vendor_tag_ops: + * + * Get methods to query for vendor extension metadata tag information. The + * HAL should fill in all the vendor tag operation methods, or leave ops + * unchanged if no vendor tags are defined. + * + * The vendor_tag_ops structure used here is defined in: + * system/media/camera/include/system/vendor_tags.h + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1: + * Not provided by HAL module. Framework may not call this function. + * + * CAMERA_MODULE_API_VERSION_2_2: + * Valid to be called by the framework. + */ + void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops); + + /** + * open_legacy: + * + * Open a specific legacy camera HAL device if multiple device HAL API + * versions are supported by this camera HAL module. For example, if the + * camera module supports both CAMERA_DEVICE_API_VERSION_1_0 and + * CAMERA_DEVICE_API_VERSION_3_2 device API for the same camera id, + * framework can call this function to open the camera device as + * CAMERA_DEVICE_API_VERSION_1_0 device. + * + * This is an optional method. A Camera HAL module does not need to support + * more than one device HAL version per device, and such modules may return + * -ENOSYS for all calls to this method. For all older HAL device API + * versions that are not supported, it may return -EOPNOTSUPP. When above + * cases occur, The normal open() method (common.methods->open) will be + * used by the framework instead. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2: + * Not provided by HAL module. Framework will not call this function. + * + * CAMERA_MODULE_API_VERSION_2_3: + * Valid to be called by the framework. + * + * Return values: + * + * 0: On a successful open of the camera device. + * + * -ENOSYS This method is not supported. + * + * -EOPNOTSUPP: The requested HAL version is not supported by this method. + * + * -EINVAL: The input arguments are invalid, i.e. the id is invalid, + * and/or the module is invalid. + * + * -EBUSY: The camera device was already opened for this camera id + * (by using this method or common.methods->open method), + * regardless of the device HAL version it was opened as. + * + * -EUSERS: The maximal number of camera devices that can be + * opened concurrently were opened already, either by + * this method or common.methods->open method. + */ + int (*open_legacy)(const struct hw_module_t* module, const char* id, + uint32_t halVersion, struct hw_device_t** device); + + /** + * set_torch_mode: + * + * Turn on or off the torch mode of the flash unit associated with a given + * camera ID. If the operation is successful, HAL must notify the framework + * torch state by invoking + * camera_module_callbacks.torch_mode_status_change() with the new state. + * + * The camera device has a higher priority accessing the flash unit. When + * there are any resource conflicts, such as open() is called to open a + * camera device, HAL module must notify the framework through + * camera_module_callbacks.torch_mode_status_change() that the + * torch mode has been turned off and the torch mode state has become + * TORCH_MODE_STATUS_NOT_AVAILABLE. When resources to turn on torch mode + * become available again, HAL module must notify the framework through + * camera_module_callbacks.torch_mode_status_change() that the torch mode + * state has become TORCH_MODE_STATUS_AVAILABLE_OFF for set_torch_mode() to + * be called. + * + * When the framework calls set_torch_mode() to turn on the torch mode of a + * flash unit, if HAL cannot keep multiple torch modes on simultaneously, + * HAL should turn off the torch mode that was turned on by + * a previous set_torch_mode() call and notify the framework that the torch + * mode state of that flash unit has become TORCH_MODE_STATUS_AVAILABLE_OFF. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3: + * Not provided by HAL module. Framework will not call this function. + * + * CAMERA_MODULE_API_VERSION_2_4: + * Valid to be called by the framework. + * + * Return values: + * + * 0: On a successful operation. + * + * -ENOSYS: The camera device does not support this operation. It is + * returned if and only if android.flash.info.available is + * false. + * + * -EBUSY: The camera device is already in use. + * + * -EUSERS: The resources needed to turn on the torch mode are not + * available, typically because other camera devices are + * holding the resources to make using the flash unit not + * possible. + * + * -EINVAL: camera_id is invalid. + * + */ + int (*set_torch_mode)(const char* camera_id, bool enabled); + + /** + * init: + * + * This method is called by the camera service before any other methods + * are invoked, right after the camera HAL library has been successfully + * loaded. It may be left as NULL by the HAL module, if no initialization + * in needed. + * + * It can be used by HAL implementations to perform initialization and + * other one-time operations. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3: + * Not provided by HAL module. Framework will not call this function. + * + * CAMERA_MODULE_API_VERSION_2_4: + * If not NULL, will always be called by the framework once after the HAL + * module is loaded, before any other HAL module method is called. + * + * Return values: + * + * 0: On a successful operation. + * + * -ENODEV: Initialization cannot be completed due to an internal + * error. The HAL must be assumed to be in a nonfunctional + * state. + * + */ + int (*init)(); + + /** + * get_physical_camera_info: + * + * Return the static metadata for a physical camera as a part of a logical + * camera device. This function is only called for those physical camera + * ID(s) that are not exposed independently. In other words, camera_id will + * be greater or equal to the return value of get_number_of_cameras(). + * + * Return values: + * + * 0: On a successful operation + * + * -ENODEV: The information cannot be provided due to an internal + * error. + * + * -EINVAL: The input arguments are invalid, i.e. the id is invalid, + * and/or the module is invalid. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3/2_4: + * Not provided by HAL module. Framework will not call this function. + * + * CAMERA_MODULE_API_VERSION_2_5 or higher: + * If any of the camera devices accessible through this camera module is + * a logical multi-camera, and at least one of the physical cameras isn't + * a stand-alone camera device, this function will be called by the camera + * framework. Calling this function with invalid physical_camera_id will + * get -EINVAL, and NULL static_metadata. + */ + int (*get_physical_camera_info)(int physical_camera_id, + camera_metadata_t **static_metadata); + + /** + * is_stream_combination_supported: + * + * Check for device support of specific camera stream combination. + * + * Return values: + * + * 0: In case the stream combination is supported. + * + * -EINVAL: In case the stream combination is not supported. + * + * -ENOSYS: In case stream combination query is not supported. + * + * Version information (based on camera_module_t.common.module_api_version): + * + * CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2/2_3/2_4: + * Not provided by HAL module. Framework will not call this function. + * + * CAMERA_MODULE_API_VERSION_2_5 or higher: + * Valid to be called by the framework. + */ + int (*is_stream_combination_supported)(int camera_id, + const camera_stream_combination_t *streams); + + /** + * notify_device_state_change: + * + * Notify the camera module that the state of the overall device has + * changed in some way that the HAL may want to know about. + * + * For example, a physical shutter may have been uncovered or covered, + * or a camera may have been covered or uncovered by an add-on keyboard + * or other accessory. + * + * The state is a bitfield of potential states, and some physical configurations + * could plausibly correspond to multiple different combinations of state bits. + * The HAL must ignore any state bits it is not actively using to determine + * the appropriate camera configuration. + * + * For example, on some devices the FOLDED state could mean that + * backward-facing cameras are covered by the fold, so FOLDED by itself implies + * BACK_COVERED. But other devices may support folding but not cover any cameras + * when folded, so for those FOLDED would not imply any of the other flags. + * Since these relationships are very device-specific, it is difficult to specify + * a comprehensive policy. But as a recommendation, it is suggested that if a flag + * necessarily implies other flags are set as well, then those flags should be set. + * So even though FOLDED would be enough to infer BACK_COVERED on some devices, the + * BACK_COVERED flag should also be set for clarity. + * + * This method may be invoked by the HAL client at any time. It must not + * cause any active camera device sessions to be closed, but may dynamically + * change which physical camera a logical multi-camera is using for its + * active and future output. + * + * The method must be invoked by the HAL client at least once before the + * client calls ICameraDevice::open on any camera device interfaces listed + * by this provider, to establish the initial device state. + * + * Note that the deviceState is 64-bit bitmask, with system defined states in + * lower 32-bit and vendor defined states in upper 32-bit. + */ + void (*notify_device_state_change)(uint64_t deviceState); + + /* reserved for future use */ + void* reserved[2]; +} camera_module_t; + +__END_DECLS + +#endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */ diff --git a/include_all/hardware/context_hub.h b/include_all/hardware/context_hub.h new file mode 100644 index 00000000..137cb3e5 --- /dev/null +++ b/include_all/hardware/context_hub.h @@ -0,0 +1,450 @@ +/* + * Copyright (C) 2016 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 CONTEXT_HUB_H +#define CONTEXT_HUB_H + +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <hardware/hardware.h> + +/** + * This header file defines the interface of a Context Hub Implementation to + * the Android service exposing Context hub capabilities to applications. + * The Context hub is expected to a low power compute domain with the following + * defining charecteristics - + * + * 1) Access to sensors like accelerometer, gyroscope, magenetometer. + * 2) Access to radios like GPS, Wifi, Bluetooth etc. + * 3) Access to low power audio sensing. + * + * Implementations of this HAL can add additional sensors not defined by the + * Android API. Such information sources shall be private to the implementation. + * + * The Context Hub HAL exposes the construct of code download. A piece of binary + * code can be pushed to the context hub through the supported APIs. + * + * This version of the HAL designs in the possibility of multiple context hubs. + */ + +__BEGIN_DECLS + +/*****************************************************************************/ + +#define CONTEXT_HUB_HEADER_MAJOR_VERSION 1 +#define CONTEXT_HUB_HEADER_MINOR_VERSION 1 +#define CONTEXT_HUB_DEVICE_API_VERSION \ + HARDWARE_DEVICE_API_VERSION(CONTEXT_HUB_HEADER_MAJOR_VERSION, \ + CONTEXT_HUB_HEADER_MINOR_VERSION) + +#define CONTEXT_HUB_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) +#define CONTEXT_HUB_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION(1, 1) + +/** + * The id of this module + */ +#define CONTEXT_HUB_MODULE_ID "context_hub" + +/** + * Name of the device to open + */ +#define CONTEXT_HUB_HARDWARE_POLL "ctxt_poll" + +/** + * Memory types for code upload. Device-specific. At least HUB_MEM_TYPE_MAIN must be supported + */ +#define HUB_MEM_TYPE_MAIN 0 +#define HUB_MEM_TYPE_SECONDARY 1 +#define HUB_MEM_TYPE_TCM 2 + + +#define HUB_MEM_TYPE_FIRST_VENDOR 0x80000000ul + +#define NANOAPP_VENDORS_ALL 0xFFFFFFFFFF000000ULL +#define NANOAPP_VENDOR_ALL_APPS 0x0000000000FFFFFFULL + +#define NANOAPP_VENDOR(name) \ + (((uint64_t)(name)[0] << 56) | \ + ((uint64_t)(name)[1] << 48) | \ + ((uint64_t)(name)[2] << 40) | \ + ((uint64_t)(name)[3] << 32) | \ + ((uint64_t)(name)[4] << 24)) + +/* + * generates the NANOAPP ID from vendor id and app seq# id + */ +#define NANO_APP_ID(vendor, seq_id) \ + (((uint64_t)(vendor) & NANOAPP_VENDORS_ALL) | ((uint64_t)(seq_id) & NANOAPP_VENDOR_ALL_APPS)) + +struct hub_app_name_t { + uint64_t id; +}; + +/** + * Other memory types (likely not writeable, informational only) + */ +#define HUB_MEM_TYPE_BOOTLOADER 0xfffffffful +#define HUB_MEM_TYPE_OS 0xfffffffeul +#define HUB_MEM_TYPE_EEDATA 0xfffffffdul +#define HUB_MEM_TYPE_RAM 0xfffffffcul + +/** + * Types of memory blocks on the context hub + * */ +#define MEM_FLAG_READ 0x1 // Memory can be written to +#define MEM_FLAG_WRITE 0x2 // Memory can be written to +#define MEM_FLAG_EXEC 0x4 // Memory can be executed from + +/** + * The following structure defines each memory block in detail + */ +struct mem_range_t { + uint32_t total_bytes; + uint32_t free_bytes; + uint32_t type; // HUB_MEM_TYPE_* + uint32_t mem_flags; // MEM_FLAG_* +}; + +#define NANOAPP_SIGNED_FLAG 0x1 +#define NANOAPP_ENCRYPTED_FLAG 0x2 +#define NANOAPP_MAGIC (((uint32_t)'N' << 0) | ((uint32_t)'A' << 8) | ((uint32_t)'N' << 16) | ((uint32_t)'O' << 24)) + +// The binary format below is in little endian format +struct nano_app_binary_t { + uint32_t header_version; // 0x1 for this version + uint32_t magic; // "NANO" + struct hub_app_name_t app_id; // App Id contains vendor id + uint32_t app_version; // Version of the app + uint32_t flags; // Signed, encrypted + uint64_t hw_hub_type; // which hub type is this compiled for + + // The version of the CHRE API that this nanoapp was compiled against. + // If these values are both set to 0, then they must be interpreted the same + // as if major version were set to 1, and minor 0 (the first valid CHRE API + // version). + uint8_t target_chre_api_major_version; + uint8_t target_chre_api_minor_version; + + uint8_t reserved[6]; // Should be all zeroes + uint8_t custom_binary[0]; // start of custom binary data +} __attribute__((packed)); + +struct hub_app_info { + struct hub_app_name_t app_name; + uint32_t version; + uint32_t num_mem_ranges; + struct mem_range_t mem_usage[2]; // Apps could only have RAM and SHARED_DATA +}; + +/** + * Following enum defines the types of sensors that a hub may declare support + * for. Declaration for support would mean that the hub can access and process + * data from that particular sensor type. + */ + +typedef enum { + CONTEXT_SENSOR_RESERVED, // 0 + CONTEXT_SENSOR_ACCELEROMETER, // 1 + CONTEXT_SENSOR_GYROSCOPE, // 2 + CONTEXT_SENSOR_MAGNETOMETER, // 3 + CONTEXT_SENSOR_BAROMETER, // 4 + CONTEXT_SENSOR_PROXIMITY_SENSOR, // 5 + CONTEXT_SENSOR_AMBIENT_LIGHT_SENSOR, // 6 + + CONTEXT_SENSOR_GPS = 0x100, // 0x100 + // Reserving this space for variants on GPS + CONTEXT_SENSOR_WIFI = 0x200, // 0x200 + // Reserving this space for variants on WIFI + CONTEXT_SENSOR_AUDIO = 0x300, // 0x300 + // Reserving this space for variants on Audio + CONTEXT_SENSOR_CAMERA = 0x400, // 0x400 + // Reserving this space for variants on Camera + CONTEXT_SENSOR_BLE = 0x500, // 0x500 + + CONTEXT_SENSOR_MAX = 0xffffffff, //make sure enum size is set +} context_sensor_e; + +/** + * Sensor types beyond CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE are custom types + */ +#define CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE 0x10000 + +/** + * The following structure describes a sensor + */ +struct physical_sensor_description_t { + uint32_t sensor_type; // From the definitions above eg: 100 + const char *type_string; // Type as a string. eg: "GPS" + const char *name; // Identifier eg: "Bosch BMI160" + const char *vendor; // Vendor : eg "STM" + uint32_t version; // Version : eg 0x1001 + uint32_t fifo_reserved_count; // Batching possible in hardware. Please + // note that here hardware does not include + // the context hub itself. Thus, this + // definition may be different from say the + // number advertised in the sensors HAL + // which allows for batching in a hub. + uint32_t fifo_max_count; // maximum number of batchable events. + uint64_t min_delay_ms; // in milliseconds, corresponding to highest + // sampling freq. + uint64_t max_delay_ms; // in milliseconds, corresponds to minimum + // sampling frequency + float peak_power_mw; // At max frequency & no batching, power + // in milliwatts +}; + +struct connected_sensor_t { + uint32_t sensor_id; // identifier for this sensor + + /* This union may be extended to other sensor types */ + union { + struct physical_sensor_description_t physical_sensor; + }; +}; + +struct hub_message_t { + struct hub_app_name_t app_name; /* To/From this nanoapp */ + uint32_t message_type; + uint32_t message_len; + const void *message; +}; + +/** + * Definition of a context hub. A device may contain more than one low + * power domain. In that case, please add an entry for each hub. However, + * it is perfectly OK for a device to declare one context hub and manage + * them internally as several + */ + +struct context_hub_t { + const char *name; // descriptive name eg: "Awesome Hub #1" + const char *vendor; // hub hardware vendor eg: "Qualcomm" + const char *toolchain; // toolchain to make binaries eg:"gcc ARM" + uint32_t platform_version; // Version of the hardware : eg 0x20 + uint32_t toolchain_version; // Version of the toolchain : eg: 0x484 + uint32_t hub_id; // a device unique id for this hub + + float peak_mips; // Peak MIPS platform can deliver + float stopped_power_draw_mw; // if stopped, retention power, milliwatts + float sleep_power_draw_mw; // if sleeping, retention power, milliwatts + float peak_power_draw_mw; // for a busy CPUm power in milliwatts + + const struct connected_sensor_t *connected_sensors; // array of connected sensors + uint32_t num_connected_sensors; // number of connected sensors + + const struct hub_app_name_t os_app_name; /* send msgs here for OS functions */ + uint32_t max_supported_msg_len; // This is the maximum size of the message that can + // be sent to the hub in one chunk (in bytes) +}; + +/** + * Definitions of message payloads, see hub_messages_e + */ + +struct status_response_t { + int32_t result; // 0 on success, < 0 : error on failure. > 0 for any descriptive status +}; + +struct apps_enable_request_t { + struct hub_app_name_t app_name; +}; + +struct apps_disable_request_t { + struct hub_app_name_t app_name; +}; + +struct load_app_request_t { + struct nano_app_binary_t app_binary; +}; + +struct unload_app_request_t { + struct hub_app_name_t app_name; +}; + +struct query_apps_request_t { + struct hub_app_name_t app_name; +}; + +/** + * CONTEXT_HUB_APPS_ENABLE + * Enables the specified nano-app(s) + * + * Payload : apps_enable_request_t + * + * Response : status_response_t + * On receipt of a successful response, it is + * expected that + * + * i) the app is executing and able to receive + * any messages. + * + * ii) the system should be able to respond to an + * CONTEXT_HUB_QUERY_APPS request. + * + */ + +/** + * CONTEXT_HUB_APPS_DISABLE + * Stops the specified nano-app(s) + * + * Payload : apps_disable_request_t + * + * Response : status_response_t + * On receipt of a successful response, + * i) No further events are delivered to the + * nanoapp. + * + * ii) The app should not show up in a + * CONTEXT_HUB_QUERY_APPS request. + */ + +/** + * CONTEXT_HUB_LOAD_APP + * Loads a nanoApp. Upon loading the nanoApp's init method is + * called. + * + * + * Payload : load_app_request_t + * + * Response : status_response_t On receipt of a successful + * response, it is expected that + * i) the app is executing and able to receive + * messages. + * + * ii) the system should be able to respond to a + * CONTEXT_HUB_QUERY_APPS. + */ + +/** + * CONTEXT_HUB_UNLOAD_APP + * Unloads a nanoApp. Before the unload, the app's deinit method + * is called. + * + * Payload : unload_app_request_t. + * + * Response : status_response_t On receipt of a + * successful response, it is expected that + * i) No further events are delivered to the + * nanoapp. + * + * ii) the system does not list the app in a + * response to a CONTEXT_HUB_QUERY_APPS. + * + * iii) Any resources used by the app should be + * freed up and available to the system. + */ + +/** + * CONTEXT_HUB_QUERY_APPS Queries for status of apps + * + * Payload : query_apps_request_t + * + * Response : struct hub_app_info[] + */ + +/** + * CONTEXT_HUB_QUERY_MEMORY Queries for memory regions on the + * hub + * + * Payload : NULL + * + * Response : struct mem_range_t[] + */ + +/** + * CONTEXT_HUB_OS_REBOOT + * Reboots context hub OS, restarts all the nanoApps. + * No reboot notification is sent to nanoApps; reboot happens immediately and + * unconditionally; all volatile FW state and any data is lost as a result + * + * Payload : none + * + * Response : status_response_t + * On receipt of a successful response, it is + * expected that + * + * i) system reboot has completed; + * status contains reboot reason code (platform-specific) + * + * Unsolicited response: + * System may send unsolicited response at any time; + * this should be interpreted as FW reboot, and necessary setup + * has to be done (same or similar to the setup done on system boot) + */ + +/** + * All communication between the context hubs and the Context Hub Service is in + * the form of messages. Some message types are distinguished and their + * Semantics shall be well defined. + * Custom message types should be defined starting above + * CONTEXT_HUB_PRIVATE_MSG_BASE + */ + +typedef enum { + CONTEXT_HUB_APPS_ENABLE = 1, // Enables loaded nano-app(s) + CONTEXT_HUB_APPS_DISABLE = 2, // Disables loaded nano-app(s) + CONTEXT_HUB_LOAD_APP = 3, // Load a supplied app + CONTEXT_HUB_UNLOAD_APP = 4, // Unload a specified app + CONTEXT_HUB_QUERY_APPS = 5, // Query for app(s) info on hub + CONTEXT_HUB_QUERY_MEMORY = 6, // Query for memory info + CONTEXT_HUB_OS_REBOOT = 7, // Request to reboot context HUB OS +} hub_messages_e; + +#define CONTEXT_HUB_TYPE_PRIVATE_MSG_BASE 0x00400 + +/** + * A callback registers with the context hub service to pass messages + * coming from the hub to the service/clients. + */ +typedef int context_hub_callback(uint32_t hub_id, const struct hub_message_t *rxed_msg, void *cookie); + + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +struct context_hub_module_t { + struct hw_module_t common; + + /** + * Enumerate all available hubs.The list is returned in "list". + * @return result : number of hubs in list or error (negative) + * + * This method shall be called at device bootup. + */ + int (*get_hubs)(struct context_hub_module_t* module, const struct context_hub_t ** list); + + /** + * Registers a callback for the HAL implementation to communicate + * with the context hub service. + * @return result : 0 if successful, error code otherwise + */ + int (*subscribe_messages)(uint32_t hub_id, context_hub_callback cbk, void *cookie); + + /** + * Send a message to a hub + * @return result : 0 if successful, error code otherwise + */ + int (*send_message)(uint32_t hub_id, const struct hub_message_t *msg); + +}; + +__END_DECLS + +#endif // CONTEXT_HUB_SENSORS_INTERFACE_H diff --git a/include_all/hardware/fb.h b/include_all/hardware/fb.h new file mode 100644 index 00000000..65720a39 --- /dev/null +++ b/include_all/hardware/fb.h @@ -0,0 +1,173 @@ +/* + * Copyright (C) 2008 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_FB_INTERFACE_H +#define ANDROID_FB_INTERFACE_H + +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <cutils/native_handle.h> + +#include <hardware/hardware.h> + +__BEGIN_DECLS + +#define GRALLOC_HARDWARE_FB0 "fb0" + +/*****************************************************************************/ + + +/*****************************************************************************/ + +typedef struct framebuffer_device_t { + /** + * Common methods of the framebuffer device. This *must* be the first member of + * framebuffer_device_t as users of this structure will cast a hw_device_t to + * framebuffer_device_t pointer in contexts where it's known the hw_device_t references a + * framebuffer_device_t. + */ + struct hw_device_t common; + + /* flags describing some attributes of the framebuffer */ + const uint32_t flags; + + /* dimensions of the framebuffer in pixels */ + const uint32_t width; + const uint32_t height; + + /* frambuffer stride in pixels */ + const int stride; + + /* framebuffer pixel format */ + const int format; + + /* resolution of the framebuffer's display panel in pixel per inch*/ + const float xdpi; + const float ydpi; + + /* framebuffer's display panel refresh rate in frames per second */ + const float fps; + + /* min swap interval supported by this framebuffer */ + const int minSwapInterval; + + /* max swap interval supported by this framebuffer */ + const int maxSwapInterval; + + /* Number of framebuffers supported*/ + const int numFramebuffers; + + int reserved[7]; + + /* + * requests a specific swap-interval (same definition than EGL) + * + * Returns 0 on success or -errno on error. + */ + int (*setSwapInterval)(struct framebuffer_device_t* window, + int interval); + + /* + * This hook is OPTIONAL. + * + * It is non NULL If the framebuffer driver supports "update-on-demand" + * and the given rectangle is the area of the screen that gets + * updated during (*post)(). + * + * This is useful on devices that are able to DMA only a portion of + * the screen to the display panel, upon demand -- as opposed to + * constantly refreshing the panel 60 times per second, for instance. + * + * Only the area defined by this rectangle is guaranteed to be valid, that + * is, the driver is not allowed to post anything outside of this + * rectangle. + * + * The rectangle evaluated during (*post)() and specifies which area + * of the buffer passed in (*post)() shall to be posted. + * + * return -EINVAL if width or height <=0, or if left or top < 0 + */ + int (*setUpdateRect)(struct framebuffer_device_t* window, + int left, int top, int width, int height); + + /* + * Post <buffer> to the display (display it on the screen) + * The buffer must have been allocated with the + * GRALLOC_USAGE_HW_FB usage flag. + * buffer must be the same width and height as the display and must NOT + * be locked. + * + * The buffer is shown during the next VSYNC. + * + * If the same buffer is posted again (possibly after some other buffer), + * post() will block until the the first post is completed. + * + * Internally, post() is expected to lock the buffer so that a + * subsequent call to gralloc_module_t::(*lock)() with USAGE_RENDER or + * USAGE_*_WRITE will block until it is safe; that is typically once this + * buffer is shown and another buffer has been posted. + * + * Returns 0 on success or -errno on error. + */ + int (*post)(struct framebuffer_device_t* dev, buffer_handle_t buffer); + + + /* + * The (*compositionComplete)() method must be called after the + * compositor has finished issuing GL commands for client buffers. + */ + + int (*compositionComplete)(struct framebuffer_device_t* dev); + + /* + * This hook is OPTIONAL. + * + * If non NULL it will be caused by SurfaceFlinger on dumpsys + */ + void (*dump)(struct framebuffer_device_t* dev, char *buff, int buff_len); + + /* + * (*enableScreen)() is used to either blank (enable=0) or + * unblank (enable=1) the screen this framebuffer is attached to. + * + * Returns 0 on success or -errno on error. + */ + int (*enableScreen)(struct framebuffer_device_t* dev, int enable); + + void* reserved_proc[6]; + +} framebuffer_device_t; + + +/** convenience API for opening and closing a supported device */ + +static inline int framebuffer_open(const struct hw_module_t* module, + struct framebuffer_device_t** device) { + return module->methods->open(module, + GRALLOC_HARDWARE_FB0, TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int framebuffer_close(struct framebuffer_device_t* device) { + return device->common.close(&device->common); +} + + +__END_DECLS + +#endif // ANDROID_FB_INTERFACE_H diff --git a/include_all/hardware/fingerprint.h b/include_all/hardware/fingerprint.h new file mode 100644 index 00000000..86ced9b4 --- /dev/null +++ b/include_all/hardware/fingerprint.h @@ -0,0 +1,277 @@ +/* + * Copyright (C) 2014 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_INCLUDE_HARDWARE_FINGERPRINT_H +#define ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H + +#include <hardware/hardware.h> +#include <hardware/hw_auth_token.h> + +#define FINGERPRINT_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) +#define FINGERPRINT_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) +#define FINGERPRINT_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1) +#define FINGERPRINT_MODULE_API_VERSION_3_0 HARDWARE_MODULE_API_VERSION(3, 0) +#define FINGERPRINT_HARDWARE_MODULE_ID "fingerprint" + +typedef enum fingerprint_msg_type { + FINGERPRINT_ERROR = -1, + FINGERPRINT_ACQUIRED = 1, + FINGERPRINT_TEMPLATE_ENROLLING = 3, + FINGERPRINT_TEMPLATE_REMOVED = 4, + FINGERPRINT_AUTHENTICATED = 5, + FINGERPRINT_TEMPLATE_ENUMERATING = 6, +} fingerprint_msg_type_t; + +/* + * Fingerprint errors are meant to tell the framework to terminate the current operation and ask + * for the user to correct the situation. These will almost always result in messaging and user + * interaction to correct the problem. + * + * For example, FINGERPRINT_ERROR_CANCELED should follow any acquisition message that results in + * a situation where the current operation can't continue without user interaction. For example, + * if the sensor is dirty during enrollment and no further enrollment progress can be made, + * send FINGERPRINT_ACQUIRED_IMAGER_DIRTY followed by FINGERPRINT_ERROR_CANCELED. + */ +typedef enum fingerprint_error { + FINGERPRINT_ERROR_HW_UNAVAILABLE = 1, /* The hardware has an error that can't be resolved. */ + FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2, /* Bad data; operation can't continue */ + FINGERPRINT_ERROR_TIMEOUT = 3, /* The operation has timed out waiting for user input. */ + FINGERPRINT_ERROR_NO_SPACE = 4, /* No space available to store a template */ + FINGERPRINT_ERROR_CANCELED = 5, /* The current operation can't proceed. See above. */ + FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint with given id can't be removed */ + FINGERPRINT_ERROR_LOCKOUT = 7, /* the fingerprint hardware is in lockout due to too many attempts */ + FINGERPRINT_ERROR_VENDOR_BASE = 1000 /* vendor-specific error messages start here */ +} fingerprint_error_t; + +/* + * Fingerprint acquisition info is meant as feedback for the current operation. Anything but + * FINGERPRINT_ACQUIRED_GOOD will be shown to the user as feedback on how to take action on the + * current operation. For example, FINGERPRINT_ACQUIRED_IMAGER_DIRTY can be used to tell the user + * to clean the sensor. If this will cause the current operation to fail, an additional + * FINGERPRINT_ERROR_CANCELED can be sent to stop the operation in progress (e.g. enrollment). + * In general, these messages will result in a "Try again" message. + */ +typedef enum fingerprint_acquired_info { + FINGERPRINT_ACQUIRED_GOOD = 0, + FINGERPRINT_ACQUIRED_PARTIAL = 1, /* sensor needs more data, i.e. longer swipe. */ + FINGERPRINT_ACQUIRED_INSUFFICIENT = 2, /* image doesn't contain enough detail for recognition*/ + FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3, /* sensor needs to be cleaned */ + FINGERPRINT_ACQUIRED_TOO_SLOW = 4, /* mostly swipe-type sensors; not enough data collected */ + FINGERPRINT_ACQUIRED_TOO_FAST = 5, /* for swipe and area sensors; tell user to slow down*/ + FINGERPRINT_ACQUIRED_DETECTED = 6, /* when the finger is first detected. Used to optimize wakeup. + Should be followed by one of the above messages */ + FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000 /* vendor-specific acquisition messages start here */ +} fingerprint_acquired_info_t; + +typedef struct fingerprint_finger_id { + uint32_t gid; + uint32_t fid; +} fingerprint_finger_id_t; + +typedef struct fingerprint_enroll { + fingerprint_finger_id_t finger; + /* samples_remaining goes from N (no data collected, but N scans needed) + * to 0 (no more data is needed to build a template). */ + uint32_t samples_remaining; + uint64_t msg; /* Vendor specific message. Used for user guidance */ +} fingerprint_enroll_t; + +typedef struct fingerprint_iterator { + fingerprint_finger_id_t finger; + uint32_t remaining_templates; +} fingerprint_iterator_t; + +typedef fingerprint_iterator_t fingerprint_enumerated_t; +typedef fingerprint_iterator_t fingerprint_removed_t; + +typedef struct fingerprint_acquired { + fingerprint_acquired_info_t acquired_info; /* information about the image */ +} fingerprint_acquired_t; + +typedef struct fingerprint_authenticated { + fingerprint_finger_id_t finger; + hw_auth_token_t hat; +} fingerprint_authenticated_t; + +typedef struct fingerprint_msg { + fingerprint_msg_type_t type; + union { + fingerprint_error_t error; + fingerprint_enroll_t enroll; + fingerprint_enumerated_t enumerated; + fingerprint_removed_t removed; + fingerprint_acquired_t acquired; + fingerprint_authenticated_t authenticated; + } data; +} fingerprint_msg_t; + +/* Callback function type */ +typedef void (*fingerprint_notify_t)(const fingerprint_msg_t *msg); + +/* Synchronous operation */ +typedef struct fingerprint_device { + /** + * Common methods of the fingerprint device. This *must* be the first member + * of fingerprint_device as users of this structure will cast a hw_device_t + * to fingerprint_device pointer in contexts where it's known + * the hw_device_t references a fingerprint_device. + */ + struct hw_device_t common; + + /* + * Client provided callback function to receive notifications. + * Do not set by hand, use the function above instead. + */ + fingerprint_notify_t notify; + + /* + * Set notification callback: + * Registers a user function that would receive notifications from the HAL + * The call will block if the HAL state machine is in busy state until HAL + * leaves the busy state. + * + * Function return: 0 if callback function is successfuly registered + * or a negative number in case of error, generally from the errno.h set. + */ + int (*set_notify)(struct fingerprint_device *dev, fingerprint_notify_t notify); + + /* + * Fingerprint pre-enroll enroll request: + * Generates a unique token to upper layers to indicate the start of an enrollment transaction. + * This token will be wrapped by security for verification and passed to enroll() for + * verification before enrollment will be allowed. This is to ensure adding a new fingerprint + * template was preceded by some kind of credential confirmation (e.g. device password). + * + * Function return: 0 if function failed + * otherwise, a uint64_t of token + */ + uint64_t (*pre_enroll)(struct fingerprint_device *dev); + + /* + * Fingerprint enroll request: + * Switches the HAL state machine to collect and store a new fingerprint + * template. Switches back as soon as enroll is complete + * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING && + * fingerprint_msg.data.enroll.samples_remaining == 0) + * or after timeout_sec seconds. + * The fingerprint template will be assigned to the group gid. User has a choice + * to supply the gid or set it to 0 in which case a unique group id will be generated. + * + * Function return: 0 if enrollment process can be successfully started + * or a negative number in case of error, generally from the errno.h set. + * A notify() function may be called indicating the error condition. + */ + int (*enroll)(struct fingerprint_device *dev, const hw_auth_token_t *hat, + uint32_t gid, uint32_t timeout_sec); + + /* + * Finishes the enroll operation and invalidates the pre_enroll() generated challenge. + * This will be called at the end of a multi-finger enrollment session to indicate + * that no more fingers will be added. + * + * Function return: 0 if the request is accepted + * or a negative number in case of error, generally from the errno.h set. + */ + int (*post_enroll)(struct fingerprint_device *dev); + + /* + * get_authenticator_id: + * Returns a token associated with the current fingerprint set. This value will + * change whenever a new fingerprint is enrolled, thus creating a new fingerprint + * set. + * + * Function return: current authenticator id or 0 if function failed. + */ + uint64_t (*get_authenticator_id)(struct fingerprint_device *dev); + + /* + * Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED + * to all running clients. Switches the HAL state machine back to the idle state. + * Unlike enroll_done() doesn't invalidate the pre_enroll() challenge. + * + * Function return: 0 if cancel request is accepted + * or a negative number in case of error, generally from the errno.h set. + */ + int (*cancel)(struct fingerprint_device *dev); + + /* + * Enumerate all the fingerprint templates found in the directory set by + * set_active_group() + * For each template found a notify() will be called with: + * fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENUMERATED + * fingerprint_msg.data.enumerated.finger indicating a template id + * fingerprint_msg.data.enumerated.remaining_templates indicating how many more + * enumeration messages to expect. + * Note: If there are no fingerprints, then this should return 0 and the first fingerprint + * enumerated should have fingerid=0 and remaining=0 + * Function return: 0 if enumerate request is accepted + * or a negative number in case of error, generally from the errno.h set. + */ + int (*enumerate)(struct fingerprint_device *dev); + + /* + * Fingerprint remove request: + * Deletes a fingerprint template. + * Works only within the path set by set_active_group(). + * The fid parameter can be used as a widcard: + * * fid == 0 -- delete all the templates in the group. + * * fid != 0 -- delete this specific template from the group. + * For each template found a notify() will be called with: + * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED + * fingerprint_msg.data.removed.finger indicating a template id deleted + * fingerprint_msg.data.removed.remaining_templates indicating how many more + * templates will be deleted by this operation. + * + * Function return: 0 if fingerprint template(s) can be successfully deleted + * or a negative number in case of error, generally from the errno.h set. + */ + int (*remove)(struct fingerprint_device *dev, uint32_t gid, uint32_t fid); + + /* + * Restricts the HAL operation to a set of fingerprints belonging to a + * group provided. + * The caller must provide a path to a storage location within the user's + * data directory. + * + * Function return: 0 on success + * or a negative number in case of error, generally from the errno.h set. + */ + int (*set_active_group)(struct fingerprint_device *dev, uint32_t gid, + const char *store_path); + + /* + * Authenticates an operation identifed by operation_id + * + * Function return: 0 on success + * or a negative number in case of error, generally from the errno.h set. + */ + int (*authenticate)(struct fingerprint_device *dev, uint64_t operation_id, uint32_t gid); + + /* Reserved for backward binary compatibility */ + void *reserved[4]; +} fingerprint_device_t; + +typedef struct fingerprint_module { + /** + * Common methods of the fingerprint module. This *must* be the first member + * of fingerprint_module as users of this structure will cast a hw_module_t + * to fingerprint_module pointer in contexts where it's known + * the hw_module_t references a fingerprint_module. + */ + struct hw_module_t common; +} fingerprint_module_t; + +#endif /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */ diff --git a/include_all/hardware/gatekeeper.h b/include_all/hardware/gatekeeper.h new file mode 100644 index 00000000..2bb2b08c --- /dev/null +++ b/include_all/hardware/gatekeeper.h @@ -0,0 +1,190 @@ +/* + * 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_GATEKEEPER_H +#define ANDROID_HARDWARE_GATEKEEPER_H + +#include <sys/cdefs.h> +#include <sys/types.h> +#include <hardware/hardware.h> + +__BEGIN_DECLS + +#define GATEKEEPER_HARDWARE_MODULE_ID "gatekeeper" + +#define GATEKEEPER_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) + +#define HARDWARE_GATEKEEPER "gatekeeper" + +struct gatekeeper_module { + /** + * Comon methods of the gatekeeper module. This *must* be the first member of + * gatekeeper_module as users of this structure will cast a hw_module_t to + * a gatekeeper_module pointer in the appropriate context. + */ + hw_module_t common; +}; + +struct gatekeeper_device { + /** + * Common methods of the gatekeeper device. As above, this must be the first + * member of keymaster_device. + */ + hw_device_t common; + + /** + * Enrolls desired_password, which should be derived from a user selected pin or password, + * with the authentication factor private key used only for enrolling authentication + * factor data. + * + * If there was already a password enrolled, it should be provided in + * current_password_handle, along with the current password in current_password + * that should validate against current_password_handle. + * + * Parameters: + * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open + * - uid: the Android user identifier + * + * - current_password_handle: the currently enrolled password handle the user + * wants to replace. May be null if there's no currently enrolled password. + * - current_password_handle_length: the length in bytes of the buffer pointed + * at by current_password_handle. Must be 0 if current_password_handle is NULL. + * + * - current_password: the user's current password in plain text. If presented, + * it MUST verify against current_password_handle. + * - current_password_length: the size in bytes of the buffer pointed at by + * current_password. Must be 0 if the current_password is NULL. + * + * - desired_password: the new password the user wishes to enroll in plain-text. + * Cannot be NULL. + * - desired_password_length: the length in bytes of the buffer pointed at by + * desired_password. + * + * - enrolled_password_handle: on success, a buffer will be allocated with the + * new password handle referencing the password provided in desired_password. + * This buffer can be used on subsequent calls to enroll or verify. + * The caller is responsible for deallocating this buffer via a call to delete[] + * - enrolled_password_handle_length: pointer to the length in bytes of the buffer allocated + * by this function and pointed to by *enrolled_password_handle_length. + * + * Returns: + * - 0 on success + * - An error code < 0 on failure, or + * - A timeout value T > 0 if the call should not be re-attempted until T milliseconds + * have elapsed. + * + * On error, enrolled_password_handle will not be allocated. + */ + int (*enroll)(const struct gatekeeper_device *dev, uint32_t uid, + const uint8_t *current_password_handle, uint32_t current_password_handle_length, + const uint8_t *current_password, uint32_t current_password_length, + const uint8_t *desired_password, uint32_t desired_password_length, + uint8_t **enrolled_password_handle, uint32_t *enrolled_password_handle_length); + + /** + * Verifies provided_password matches enrolled_password_handle. + * + * Implementations of this module may retain the result of this call + * to attest to the recency of authentication. + * + * On success, writes the address of a verification token to auth_token, + * usable to attest password verification to other trusted services. Clients + * may pass NULL for this value. + * + * Parameters: + * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open + * - uid: the Android user identifier + * + * - challenge: An optional challenge to authenticate against, or 0. Used when a separate + * authenticator requests password verification, or for transactional + * password authentication. + * + * - enrolled_password_handle: the currently enrolled password handle that the + * user wishes to verify against. + * - enrolled_password_handle_length: the length in bytes of the buffer pointed + * to by enrolled_password_handle + * + * - provided_password: the plaintext password to be verified against the + * enrolled_password_handle + * - provided_password_length: the length in bytes of the buffer pointed to by + * provided_password + * + * - auth_token: on success, a buffer containing the authentication token + * resulting from this verification is assigned to *auth_token. The caller + * is responsible for deallocating this memory via a call to delete[] + * - auth_token_length: on success, the length in bytes of the authentication + * token assigned to *auth_token will be assigned to *auth_token_length + * + * - request_reenroll: a request to the upper layers to re-enroll the verified + * password due to a version change. Not set if verification fails. + * + * Returns: + * - 0 on success + * - An error code < 0 on failure, or + * - A timeout value T > 0 if the call should not be re-attempted until T milliseconds + * have elapsed. + * On error, auth token will not be allocated + */ + int (*verify)(const struct gatekeeper_device *dev, uint32_t uid, uint64_t challenge, + const uint8_t *enrolled_password_handle, uint32_t enrolled_password_handle_length, + const uint8_t *provided_password, uint32_t provided_password_length, + uint8_t **auth_token, uint32_t *auth_token_length, bool *request_reenroll); + + /* + * Deletes the enrolled_password_handle associated wth the uid. Once deleted + * the user cannot be verified anymore. + * This function is optional and should be set to NULL if it is not implemented. + * + * Parameters + * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open + * - uid: the Android user identifier + * + * Returns: + * - 0 on success + * - An error code < 0 on failure + */ + int (*delete_user)(const struct gatekeeper_device *dev, uint32_t uid); + + /* + * Deletes all the enrolled_password_handles for all uid's. Once called, + * no users will be enrolled on the device. + * This function is optional and should be set to NULL if it is not implemented. + * + * Parameters + * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open + * + * Returns: + * - 0 on success + * - An error code < 0 on failure + */ + int (*delete_all_users)(const struct gatekeeper_device *dev); +}; + +typedef struct gatekeeper_device gatekeeper_device_t; + +static inline int gatekeeper_open(const struct hw_module_t *module, + gatekeeper_device_t **device) { + return module->methods->open(module, HARDWARE_GATEKEEPER, + (struct hw_device_t **) device); +} + +static inline int gatekeeper_close(gatekeeper_device_t *device) { + return device->common.close(&device->common); +} + +__END_DECLS + +#endif // ANDROID_HARDWARE_GATEKEEPER_H diff --git a/include_all/hardware/gnss-base.h b/include_all/hardware/gnss-base.h new file mode 100644 index 00000000..706aa387 --- /dev/null +++ b/include_all/hardware/gnss-base.h @@ -0,0 +1,276 @@ +// This file is autogenerated by hidl-gen. Do not edit manually. +// Source: android.hardware.gnss@1.0 +// Location: hardware/interfaces/gnss/1.0/ + +#ifndef HIDL_GENERATED_ANDROID_HARDWARE_GNSS_V1_0_EXPORTED_CONSTANTS_H_ +#define HIDL_GENERATED_ANDROID_HARDWARE_GNSS_V1_0_EXPORTED_CONSTANTS_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +enum { + GNSS_MAX_SVS_COUNT = 64u, +}; + +enum { + GNSS_CONSTELLATION_UNKNOWN = 0, + GNSS_CONSTELLATION_GPS = 1, + GNSS_CONSTELLATION_SBAS = 2, + GNSS_CONSTELLATION_GLONASS = 3, + GNSS_CONSTELLATION_QZSS = 4, + GNSS_CONSTELLATION_BEIDOU = 5, + GNSS_CONSTELLATION_GALILEO = 6, +}; + +enum { + GPS_LOCATION_HAS_LAT_LONG = 1 /* 0x0001 */, + GPS_LOCATION_HAS_ALTITUDE = 2 /* 0x0002 */, + GPS_LOCATION_HAS_SPEED = 4 /* 0x0004 */, + GPS_LOCATION_HAS_BEARING = 8 /* 0x0008 */, + GPS_LOCATION_HAS_HORIZONTAL_ACCURACY = 16 /* 0x0010 */, + GPS_LOCATION_HAS_VERTICAL_ACCURACY = 32 /* 0x0020 */, + GPS_LOCATION_HAS_SPEED_ACCURACY = 64 /* 0x0040 */, + GPS_LOCATION_HAS_BEARING_ACCURACY = 128 /* 0x0080 */, +}; + +enum { + APN_IP_INVALID = 0, + APN_IP_IPV4 = 1, + APN_IP_IPV6 = 2, + APN_IP_IPV4V6 = 3, +}; + +enum { + AGPS_TYPE_SUPL = 1, + AGPS_TYPE_C2K = 2, +}; + +enum { + GNSS_REQUEST_AGNSS_DATA_CONN = 1, + GNSS_RELEASE_AGNSS_DATA_CONN = 2, + GNSS_AGNSS_DATA_CONNECTED = 3, + GNSS_AGNSS_DATA_CONN_DONE = 4, + GNSS_AGNSS_DATA_CONN_FAILED = 5, +}; + +enum { + AGPS_SETID_TYPE_NONE = 0, + AGPS_SETID_TYPE_IMSI = 1, + AGPS_SETID_TYPE_MSISDM = 2, +}; + +enum { + AGPS_RIL_NETWORK_TYPE_MOBILE = 0, + AGPS_RIL_NETWORK_TYPE_WIFI = 1, + AGPS_RIL_NETWORK_TYPE_MMS = 2, + AGPS_RIL_NETWORK_TYPE_SUPL = 3, + AGPS_RIL_NETWORK_TYPE_DUN = 4, + AGPS_RIL_NETWORK_TYPE_HIPRI = 5, + AGPS_RIL_NETWORK_TYPE_WIMAX = 6, +}; + +enum { + AGPS_REF_LOCATION_TYPE_GSM_CELLID = 1, + AGPS_REF_LOCATION_TYPE_UMTS_CELLID = 2, + AGPS_REF_LOCATION_TYPE_LTE_CELLID = 4, +}; + +enum { + AGPS_RIL_REQUEST_SETID_IMSI = 1u /* (1 << 0L) */, + AGPS_RIL_REQUEST_SETID_MSISDN = 2u /* (1 << 1L) */, +}; + +enum { + GPS_POSITION_MODE_STANDALONE = 0, + GPS_POSITION_MODE_MS_BASED = 1, + GPS_POSITION_MODE_MS_ASSISTED = 2, +}; + +enum { + GPS_POSITION_RECURRENCE_PERIODIC = 0u, + GPS_POSITION_RECURRENCE_SINGLE = 1u, +}; + +enum { + GPS_DELETE_EPHEMERIS = 1 /* 0x0001 */, + GPS_DELETE_ALMANAC = 2 /* 0x0002 */, + GPS_DELETE_POSITION = 4 /* 0x0004 */, + GPS_DELETE_TIME = 8 /* 0x0008 */, + GPS_DELETE_IONO = 16 /* 0x0010 */, + GPS_DELETE_UTC = 32 /* 0x0020 */, + GPS_DELETE_HEALTH = 64 /* 0x0040 */, + GPS_DELETE_SVDIR = 128 /* 0x0080 */, + GPS_DELETE_SVSTEER = 256 /* 0x0100 */, + GPS_DELETE_SADATA = 512 /* 0x0200 */, + GPS_DELETE_RTI = 1024 /* 0x0400 */, + GPS_DELETE_CELLDB_INFO = 32768 /* 0x8000 */, + GPS_DELETE_ALL = 65535 /* 0xFFFF */, +}; + +enum { + FLP_BATCH_WAKEUP_ON_FIFO_FULL = 1 /* 0x01 */, +}; + +enum { + GPS_CAPABILITY_SCHEDULING = 1u /* (1 << 0) */, + GPS_CAPABILITY_MSB = 2u /* (1 << 1) */, + GPS_CAPABILITY_MSA = 4u /* (1 << 2) */, + GPS_CAPABILITY_SINGLE_SHOT = 8u /* (1 << 3) */, + GPS_CAPABILITY_ON_DEMAND_TIME = 16u /* (1 << 4) */, + GPS_CAPABILITY_GEOFENCING = 32u /* (1 << 5) */, + GPS_CAPABILITY_MEASUREMENTS = 64u /* (1 << 6) */, + GPS_CAPABILITY_NAV_MESSAGES = 128u /* (1 << 7) */, +}; + +enum { + GPS_STATUS_NONE = 0, + GPS_STATUS_SESSION_BEGIN = 1, + GPS_STATUS_SESSION_END = 2, + GPS_STATUS_ENGINE_ON = 3, + GPS_STATUS_ENGINE_OFF = 4, +}; + +enum { + GNSS_SV_FLAGS_NONE = 0, + GNSS_SV_FLAGS_HAS_EPHEMERIS_DATA = 1 /* (1 << 0) */, + GNSS_SV_FLAGS_HAS_ALMANAC_DATA = 2 /* (1 << 1) */, + GNSS_SV_FLAGS_USED_IN_FIX = 4 /* (1 << 2) */, + GNSS_SV_FLAGS_HAS_CARRIER_FREQUENCY = 8 /* (1 << 3) */, +}; + +enum { + GPS_GEOFENCE_ENTERED = 1 /* (1 << 0L) */, + GPS_GEOFENCE_EXITED = 2 /* (1 << 1L) */, + GPS_GEOFENCE_UNCERTAIN = 4 /* (1 << 2L) */, +}; + +enum { + GPS_GEOFENCE_UNAVAILABLE = 1 /* (1 << 0L) */, + GPS_GEOFENCE_AVAILABLE = 2 /* (1 << 1L) */, +}; + +enum { + GPS_GEOFENCE_OPERATION_SUCCESS = 0, + GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES = -100 /* (-100) */, + GPS_GEOFENCE_ERROR_ID_EXISTS = -101 /* (-101) */, + GPS_GEOFENCE_ERROR_ID_UNKNOWN = -102 /* (-102) */, + GPS_GEOFENCE_ERROR_INVALID_TRANSITION = -103 /* (-103) */, + GPS_GEOFENCE_ERROR_GENERIC = -149 /* (-149) */, +}; + +enum { + GPS_MEASUREMENT_SUCCESS = 0, + GPS_MEASUREMENT_ERROR_ALREADY_INIT = -100 /* (-100) */, + GPS_MEASUREMENT_ERROR_GENERIC = -101 /* (-101) */, +}; + +enum { + GNSS_CLOCK_HAS_LEAP_SECOND = 1 /* (1 << 0) */, + GNSS_CLOCK_HAS_TIME_UNCERTAINTY = 2 /* (1 << 1) */, + GNSS_CLOCK_HAS_FULL_BIAS = 4 /* (1 << 2) */, + GNSS_CLOCK_HAS_BIAS = 8 /* (1 << 3) */, + GNSS_CLOCK_HAS_BIAS_UNCERTAINTY = 16 /* (1 << 4) */, + GNSS_CLOCK_HAS_DRIFT = 32 /* (1 << 5) */, + GNSS_CLOCK_HAS_DRIFT_UNCERTAINTY = 64 /* (1 << 6) */, +}; + +enum { + GNSS_MEASUREMENT_HAS_SNR = 1u /* (1 << 0) */, + GNSS_MEASUREMENT_HAS_CARRIER_FREQUENCY = 512u /* (1 << 9) */, + GNSS_MEASUREMENT_HAS_CARRIER_CYCLES = 1024u /* (1 << 10) */, + GNSS_MEASUREMENT_HAS_CARRIER_PHASE = 2048u /* (1 << 11) */, + GNSS_MEASUREMENT_HAS_CARRIER_PHASE_UNCERTAINTY = 4096u /* (1 << 12) */, + GNSS_MEASUREMENT_HAS_AUTOMATIC_GAIN_CONTROL = 8192u /* (1 << 13) */, +}; + +enum { + GNSS_MULTIPATH_INDICATOR_UNKNOWN = 0, + GNSS_MULTIPATH_INDICATOR_PRESENT = 1, + GNSS_MULTIPATH_INDICATIOR_NOT_PRESENT = 2, +}; + +enum { + GNSS_MEASUREMENT_STATE_UNKNOWN = 0u, + GNSS_MEASUREMENT_STATE_CODE_LOCK = 1u /* (1 << 0) */, + GNSS_MEASUREMENT_STATE_BIT_SYNC = 2u /* (1 << 1) */, + GNSS_MEASUREMENT_STATE_SUBFRAME_SYNC = 4u /* (1 << 2) */, + GNSS_MEASUREMENT_STATE_TOW_DECODED = 8u /* (1 << 3) */, + GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS = 16u /* (1 << 4) */, + GNSS_MEASUREMENT_STATE_SYMBOL_SYNC = 32u /* (1 << 5) */, + GNSS_MEASUREMENT_STATE_GLO_STRING_SYNC = 64u /* (1 << 6) */, + GNSS_MEASUREMENT_STATE_GLO_TOD_DECODED = 128u /* (1 << 7) */, + GNSS_MEASUREMENT_STATE_BDS_D2_BIT_SYNC = 256u /* (1 << 8) */, + GNSS_MEASUREMENT_STATE_BDS_D2_SUBFRAME_SYNC = 512u /* (1 << 9) */, + GNSS_MEASUREMENT_STATE_GAL_E1BC_CODE_LOCK = 1024u /* (1 << 10) */, + GNSS_MEASUREMENT_STATE_GAL_E1C_2ND_CODE_LOCK = 2048u /* (1 << 11) */, + GNSS_MEASUREMENT_STATE_GAL_E1B_PAGE_SYNC = 4096u /* (1 << 12) */, + GNSS_MEASUREMENT_STATE_SBAS_SYNC = 8192u /* (1 << 13) */, + GNSS_MEASUREMENT_STATE_TOW_KNOWN = 16384u /* (1 << 14) */, + GNSS_MEASUREMENT_STATE_GLO_TOD_KNOWN = 32768u /* (1 << 15) */, +}; + +enum { + GNSS_ADR_STATE_UNKNOWN = 0, + GNSS_ADR_STATE_VALID = 1 /* (1 << 0) */, + GNSS_ADR_STATE_RESET = 2 /* (1 << 1) */, + GNSS_ADR_STATE_CYCLE_SLIP = 4 /* (1 << 2) */, +}; + +enum { + GPS_NAVIGATION_MESSAGE_SUCCESS = 0, + GPS_NAVIGATION_MESSAGE_ERROR_ALREADY_INIT = -100 /* (-100) */, + GPS_NAVIGATION_MESSAGE_ERROR_GENERIC = -101 /* (-101) */, +}; + +enum { + GNSS_NAVIGATION_MESSAGE_TYPE_UNKNOWN = 0, + GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L1CA = 257 /* 0x0101 */, + GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L2CNAV = 258 /* 0x0102 */, + GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L5CNAV = 259 /* 0x0103 */, + GNSS_NAVIGATION_MESSAGE_TYPE_GPS_CNAV2 = 260 /* 0x0104 */, + GNSS_NAVIGATION_MESSAGE_TYPE_GLO_L1CA = 769 /* 0x0301 */, + GNSS_NAVIGATION_MESSAGE_TYPE_BDS_D1 = 1281 /* 0x0501 */, + GNSS_NAVIGATION_MESSAGE_TYPE_BDS_D2 = 1282 /* 0x0502 */, + GNSS_NAVIGATION_MESSAGE_TYPE_GAL_I = 1537 /* 0x0601 */, + GNSS_NAVIGATION_MESSAGE_TYPE_GAL_F = 1538 /* 0x0602 */, +}; + +typedef enum { + NAV_MESSAGE_STATUS_PARITY_PASSED = 1 /* (1 << 0) */, + NAV_MESSAGE_STATUS_PARITY_REBUILT = 2 /* (1 << 1) */, + NAV_MESSAGE_STATUS_UNKNOWN = 0, +} navigation_message_status; + +enum { + GPS_NI_TYPE_VOICE = 1, + GPS_NI_TYPE_UMTS_SUPL = 2, + GPS_NI_TYPE_UMTS_CTRL_PLANE = 3, + GPS_NI_TYPE_EMERGENCY_SUPL = 4, +}; + +enum { + GPS_NI_NEED_NOTIFY = 1u /* 0x0001 */, + GPS_NI_NEED_VERIFY = 2u /* 0x0002 */, + GPS_NI_PRIVACY_OVERRIDE = 4u /* 0x0004 */, +}; + +enum { + GPS_NI_RESPONSE_ACCEPT = 1, + GPS_NI_RESPONSE_DENY = 2, + GPS_NI_RESPONSE_NORESP = 3, +}; + +enum { + GPS_ENC_NONE = 0, + GPS_ENC_SUPL_GSM_DEFAULT = 1, + GPS_ENC_SUPL_UTF8 = 2, + GPS_ENC_SUPL_UCS2 = 3, + GPS_ENC_UNKNOWN = -1 /* (-1) */, +}; + +#ifdef __cplusplus +} +#endif + +#endif // HIDL_GENERATED_ANDROID_HARDWARE_GNSS_V1_0_EXPORTED_CONSTANTS_H_ diff --git a/include_all/hardware/gps.h b/include_all/hardware/gps.h new file mode 100644 index 00000000..4e108b3f --- /dev/null +++ b/include_all/hardware/gps.h @@ -0,0 +1,2004 @@ +/* + * Copyright (C) 2010 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_INCLUDE_HARDWARE_GPS_H +#define ANDROID_INCLUDE_HARDWARE_GPS_H + +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> +#include <pthread.h> +#include <sys/socket.h> +#include <stdbool.h> + +#include <hardware/hardware.h> + +#include "gnss-base.h" + +__BEGIN_DECLS + +/* + * Enums defined in HIDL in hardware/interfaces are auto-generated and present + * in gnss-base.h. + */ + +/* for compatibility */ + +/** Maximum number of SVs for gps_sv_status_callback(). */ +#define GNSS_MAX_SVS GNSS_MAX_SVS_COUNT +/** Maximum number of Measurements in gnss_measurement_callback(). */ +#define GNSS_MAX_MEASUREMENT GNSS_MAX_SVS_COUNT + +#define GPS_REQUEST_AGPS_DATA_CONN GNSS_REQUEST_AGNSS_DATA_CONN +#define GPS_RELEASE_AGPS_DATA_CONN GNSS_RELEASE_AGNSS_DATA_CONN +#define GPS_AGPS_DATA_CONNECTED GNSS_AGNSS_DATA_CONNECTED +#define GPS_AGPS_DATA_CONN_DONE GNSS_AGNSS_DATA_CONN_DONE +#define GPS_AGPS_DATA_CONN_FAILED GNSS_AGNSS_DATA_CONN_FAILED +#define AGPS_RIL_NETWORK_TYPE_MOBILE_MMS AGPS_RIL_NETWORK_TYPE_MMS +#define AGPS_RIL_NETWORK_TYPE_MOBILE_SUPL AGPS_RIL_NETWORK_TYPE_SUPL +#define AGPS_RIL_NETWORK_TTYPE_MOBILE_DUN AGPS_RIL_NETWORK_TYPE_DUN +#define AGPS_RIL_NETWORK_TTYPE_MOBILE_HIPRI AGPS_RIL_NETWORK_TYPE_HIPRI +#define AGPS_RIL_NETWORK_TTYPE_WIMAX AGPS_RIL_NETWORK_TYPE_WIMAX +#define GNSS_MULTIPATH_INDICATOR_NOT_PRESENT GNSS_MULTIPATH_INDICATIOR_NOT_PRESENT +#define AGPS_SETID_TYPE_MSISDN AGPS_SETID_TYPE_MSISDM +#define GPS_MEASUREMENT_OPERATION_SUCCESS GPS_MEASUREMENT_SUCCESS +#define GPS_NAVIGATION_MESSAGE_OPERATION_SUCCESS GPS_NAVIGATION_MESSAGE_SUCCESS +#define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L1CA GNSS_NAVIGATION_MESSAGE_TYPE_GNSS_L1CA +#define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L2CNAV GNSS_NAVIGATION_MESSAGE_TYPE_GNSS_L2CNAV +#define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_L5CNAV GNSS_NAVIGATION_MESSAGE_TYPE_GNSS_L5CNAV +#define GNSS_NAVIGATION_MESSAGE_TYPE_GPS_CNAV2 GNSS_NAVIGATION_MESSAGE_TYPE_GNSS_CNAV2 +#define GPS_LOCATION_HAS_ACCURACY GPS_LOCATION_HAS_HORIZONTAL_ACCURACY + +/** + * The id of this module + */ +#define GPS_HARDWARE_MODULE_ID "gps" + + +/** Milliseconds since January 1, 1970 */ +typedef int64_t GpsUtcTime; + +/** Maximum number of SVs for gps_sv_status_callback(). */ +#define GPS_MAX_SVS 32 + +/** Maximum number of Measurements in gps_measurement_callback(). */ +#define GPS_MAX_MEASUREMENT 32 + +/** Requested operational mode for GPS operation. */ +typedef uint32_t GpsPositionMode; + +/** Requested recurrence mode for GPS operation. */ +typedef uint32_t GpsPositionRecurrence; + +/** GPS status event values. */ +typedef uint16_t GpsStatusValue; + +/** Flags to indicate which values are valid in a GpsLocation. */ +typedef uint16_t GpsLocationFlags; + +/** + * Flags used to specify which aiding data to delete when calling + * delete_aiding_data(). + */ +typedef uint16_t GpsAidingData; + +/** AGPS type */ +typedef uint16_t AGpsType; + +typedef uint16_t AGpsSetIDType; + +typedef uint16_t ApnIpType; + +/** + * String length constants + */ +#define GPS_NI_SHORT_STRING_MAXLEN 256 +#define GPS_NI_LONG_STRING_MAXLEN 2048 + +/** + * GpsNiType constants + */ +typedef uint32_t GpsNiType; + +/** + * GpsNiNotifyFlags constants + */ +typedef uint32_t GpsNiNotifyFlags; + +/** + * GPS NI responses, used to define the response in + * NI structures + */ +typedef int GpsUserResponseType; + +/** + * NI data encoding scheme + */ +typedef int GpsNiEncodingType; + +/** AGPS status event values. */ +typedef uint16_t AGpsStatusValue; + +typedef uint16_t AGpsRefLocationType; + +/* Deprecated, to be removed in the next Android release. */ +#define AGPS_REG_LOCATION_TYPE_MAC 3 + +/* The following typedef together with its constants below are deprecated, and + * will be removed in the next release. */ +typedef uint16_t GpsClockFlags; +#define GPS_CLOCK_HAS_LEAP_SECOND (1<<0) +#define GPS_CLOCK_HAS_TIME_UNCERTAINTY (1<<1) +#define GPS_CLOCK_HAS_FULL_BIAS (1<<2) +#define GPS_CLOCK_HAS_BIAS (1<<3) +#define GPS_CLOCK_HAS_BIAS_UNCERTAINTY (1<<4) +#define GPS_CLOCK_HAS_DRIFT (1<<5) +#define GPS_CLOCK_HAS_DRIFT_UNCERTAINTY (1<<6) + +/** + * Flags to indicate what fields in GnssClock are valid. + */ +typedef uint16_t GnssClockFlags; + +/* The following typedef together with its constants below are deprecated, and + * will be removed in the next release. */ +typedef uint8_t GpsClockType; +#define GPS_CLOCK_TYPE_UNKNOWN 0 +#define GPS_CLOCK_TYPE_LOCAL_HW_TIME 1 +#define GPS_CLOCK_TYPE_GPS_TIME 2 + +/* The following typedef together with its constants below are deprecated, and + * will be removed in the next release. */ +typedef uint32_t GpsMeasurementFlags; +#define GPS_MEASUREMENT_HAS_SNR (1<<0) +#define GPS_MEASUREMENT_HAS_ELEVATION (1<<1) +#define GPS_MEASUREMENT_HAS_ELEVATION_UNCERTAINTY (1<<2) +#define GPS_MEASUREMENT_HAS_AZIMUTH (1<<3) +#define GPS_MEASUREMENT_HAS_AZIMUTH_UNCERTAINTY (1<<4) +#define GPS_MEASUREMENT_HAS_PSEUDORANGE (1<<5) +#define GPS_MEASUREMENT_HAS_PSEUDORANGE_UNCERTAINTY (1<<6) +#define GPS_MEASUREMENT_HAS_CODE_PHASE (1<<7) +#define GPS_MEASUREMENT_HAS_CODE_PHASE_UNCERTAINTY (1<<8) +#define GPS_MEASUREMENT_HAS_CARRIER_FREQUENCY (1<<9) +#define GPS_MEASUREMENT_HAS_CARRIER_CYCLES (1<<10) +#define GPS_MEASUREMENT_HAS_CARRIER_PHASE (1<<11) +#define GPS_MEASUREMENT_HAS_CARRIER_PHASE_UNCERTAINTY (1<<12) +#define GPS_MEASUREMENT_HAS_BIT_NUMBER (1<<13) +#define GPS_MEASUREMENT_HAS_TIME_FROM_LAST_BIT (1<<14) +#define GPS_MEASUREMENT_HAS_DOPPLER_SHIFT (1<<15) +#define GPS_MEASUREMENT_HAS_DOPPLER_SHIFT_UNCERTAINTY (1<<16) +#define GPS_MEASUREMENT_HAS_USED_IN_FIX (1<<17) +#define GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE (1<<18) + +/** + * Flags to indicate what fields in GnssMeasurement are valid. + */ +typedef uint32_t GnssMeasurementFlags; + +/* The following typedef together with its constants below are deprecated, and + * will be removed in the next release. */ +typedef uint8_t GpsLossOfLock; +#define GPS_LOSS_OF_LOCK_UNKNOWN 0 +#define GPS_LOSS_OF_LOCK_OK 1 +#define GPS_LOSS_OF_LOCK_CYCLE_SLIP 2 + +/* The following typedef together with its constants below are deprecated, and + * will be removed in the next release. Use GnssMultipathIndicator instead. + */ +typedef uint8_t GpsMultipathIndicator; +#define GPS_MULTIPATH_INDICATOR_UNKNOWN 0 +#define GPS_MULTIPATH_INDICATOR_DETECTED 1 +#define GPS_MULTIPATH_INDICATOR_NOT_USED 2 + +/** + * Enumeration of available values for the GNSS Measurement's multipath + * indicator. + */ +typedef uint8_t GnssMultipathIndicator; + +/* The following typedef together with its constants below are deprecated, and + * will be removed in the next release. */ +typedef uint16_t GpsMeasurementState; +#define GPS_MEASUREMENT_STATE_UNKNOWN 0 +#define GPS_MEASUREMENT_STATE_CODE_LOCK (1<<0) +#define GPS_MEASUREMENT_STATE_BIT_SYNC (1<<1) +#define GPS_MEASUREMENT_STATE_SUBFRAME_SYNC (1<<2) +#define GPS_MEASUREMENT_STATE_TOW_DECODED (1<<3) +#define GPS_MEASUREMENT_STATE_MSEC_AMBIGUOUS (1<<4) + +/** + * Flags indicating the GNSS measurement state. + * + * The expected behavior here is for GPS HAL to set all the flags that applies. + * For example, if the state for a satellite is only C/A code locked and bit + * synchronized, and there is still millisecond ambiguity, the state should be + * set as: + * + * GNSS_MEASUREMENT_STATE_CODE_LOCK | GNSS_MEASUREMENT_STATE_BIT_SYNC | + * GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS + * + * If GNSS is still searching for a satellite, the corresponding state should be + * set to GNSS_MEASUREMENT_STATE_UNKNOWN(0). + */ +typedef uint32_t GnssMeasurementState; + +/* The following typedef together with its constants below are deprecated, and + * will be removed in the next release. */ +typedef uint16_t GpsAccumulatedDeltaRangeState; +#define GPS_ADR_STATE_UNKNOWN 0 +#define GPS_ADR_STATE_VALID (1<<0) +#define GPS_ADR_STATE_RESET (1<<1) +#define GPS_ADR_STATE_CYCLE_SLIP (1<<2) + +/** + * Flags indicating the Accumulated Delta Range's states. + */ +typedef uint16_t GnssAccumulatedDeltaRangeState; + +/* The following typedef together with its constants below are deprecated, and + * will be removed in the next release. */ +typedef uint8_t GpsNavigationMessageType; +#define GPS_NAVIGATION_MESSAGE_TYPE_UNKNOWN 0 +#define GPS_NAVIGATION_MESSAGE_TYPE_L1CA 1 +#define GPS_NAVIGATION_MESSAGE_TYPE_L2CNAV 2 +#define GPS_NAVIGATION_MESSAGE_TYPE_L5CNAV 3 +#define GPS_NAVIGATION_MESSAGE_TYPE_CNAV2 4 + +/** + * Enumeration of available values to indicate the GNSS Navigation message + * types. + * + * For convenience, first byte is the GnssConstellationType on which that signal + * is typically transmitted + */ +typedef int16_t GnssNavigationMessageType; + +/** + * Status of Navigation Message + * When a message is received properly without any parity error in its navigation words, the + * status should be set to NAV_MESSAGE_STATUS_PARITY_PASSED. But if a message is received + * with words that failed parity check, but GPS is able to correct those words, the status + * should be set to NAV_MESSAGE_STATUS_PARITY_REBUILT. + * No need to send any navigation message that contains words with parity error and cannot be + * corrected. + */ +typedef uint16_t NavigationMessageStatus; + +/* This constant is deprecated, and will be removed in the next release. */ +#define NAV_MESSAGE_STATUS_UNKONW 0 + +/** + * Flags that indicate information about the satellite + */ +typedef uint8_t GnssSvFlags; + +/** + * Constellation type of GnssSvInfo + */ +typedef uint8_t GnssConstellationType; + +/** + * Name for the GPS XTRA interface. + */ +#define GPS_XTRA_INTERFACE "gps-xtra" + +/** + * Name for the GPS DEBUG interface. + */ +#define GPS_DEBUG_INTERFACE "gps-debug" + +/** + * Name for the AGPS interface. + */ +#define AGPS_INTERFACE "agps" + +/** + * Name of the Supl Certificate interface. + */ +#define SUPL_CERTIFICATE_INTERFACE "supl-certificate" + +/** + * Name for NI interface + */ +#define GPS_NI_INTERFACE "gps-ni" + +/** + * Name for the AGPS-RIL interface. + */ +#define AGPS_RIL_INTERFACE "agps_ril" + +/** + * Name for the GPS_Geofencing interface. + */ +#define GPS_GEOFENCING_INTERFACE "gps_geofencing" + +/** + * Name of the GPS Measurements interface. + */ +#define GPS_MEASUREMENT_INTERFACE "gps_measurement" + +/** + * Name of the GPS navigation message interface. + */ +#define GPS_NAVIGATION_MESSAGE_INTERFACE "gps_navigation_message" + +/** + * Name of the GNSS/GPS configuration interface. + */ +#define GNSS_CONFIGURATION_INTERFACE "gnss_configuration" + +/** Represents a location. */ +typedef struct { + /** set to sizeof(GpsLocation) */ + size_t size; + /** Contains GpsLocationFlags bits. */ + uint16_t flags; + /** Represents latitude in degrees. */ + double latitude; + /** Represents longitude in degrees. */ + double longitude; + /** + * Represents altitude in meters above the WGS 84 reference ellipsoid. + */ + double altitude; + /** Represents speed in meters per second. */ + float speed; + /** Represents heading in degrees. */ + float bearing; + /** Represents expected accuracy in meters. */ + float accuracy; + /** Timestamp for the location fix. */ + GpsUtcTime timestamp; +} GpsLocation; + +/** Represents the status. */ +typedef struct { + /** set to sizeof(GpsStatus) */ + size_t size; + GpsStatusValue status; +} GpsStatus; + +/** + * Legacy struct to represents SV information. + * Deprecated, to be removed in the next Android release. + * Use GnssSvInfo instead. + */ +typedef struct { + /** set to sizeof(GpsSvInfo) */ + size_t size; + /** Pseudo-random number for the SV. */ + int prn; + /** Signal to noise ratio. */ + float snr; + /** Elevation of SV in degrees. */ + float elevation; + /** Azimuth of SV in degrees. */ + float azimuth; +} GpsSvInfo; + +typedef struct { + /** set to sizeof(GnssSvInfo) */ + size_t size; + + /** + * Pseudo-random number for the SV, or FCN/OSN number for Glonass. The + * distinction is made by looking at constellation field. Values should be + * in the range of: + * + * - GPS: 1-32 + * - SBAS: 120-151, 183-192 + * - GLONASS: 1-24, the orbital slot number (OSN), if known. Or, if not: + * 93-106, the frequency channel number (FCN) (-7 to +6) offset by + 100 + * i.e. report an FCN of -7 as 93, FCN of 0 as 100, and FCN of +6 as 106. + * - QZSS: 193-200 + * - Galileo: 1-36 + * - Beidou: 1-37 + */ + int16_t svid; + + /** + * Defines the constellation of the given SV. Value should be one of those + * GNSS_CONSTELLATION_* constants + */ + GnssConstellationType constellation; + + /** + * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. + * It contains the measured C/N0 value for the signal at the antenna port. + * + * This is a mandatory value. + */ + float c_n0_dbhz; + + /** Elevation of SV in degrees. */ + float elevation; + + /** Azimuth of SV in degrees. */ + float azimuth; + + /** + * Contains additional data about the given SV. Value should be one of those + * GNSS_SV_FLAGS_* constants + */ + GnssSvFlags flags; + +} GnssSvInfo; + +/** + * Legacy struct to represents SV status. + * Deprecated, to be removed in the next Android release. + * Use GnssSvStatus instead. + */ +typedef struct { + /** set to sizeof(GpsSvStatus) */ + size_t size; + int num_svs; + GpsSvInfo sv_list[GPS_MAX_SVS]; + uint32_t ephemeris_mask; + uint32_t almanac_mask; + uint32_t used_in_fix_mask; +} GpsSvStatus; + +/** + * Represents SV status. + */ +typedef struct { + /** set to sizeof(GnssSvStatus) */ + size_t size; + + /** Number of GPS SVs currently visible, refers to the SVs stored in sv_list */ + int num_svs; + /** + * Pointer to an array of SVs information for all GNSS constellations, + * except GPS, which is reported using sv_list + */ + GnssSvInfo gnss_sv_list[GNSS_MAX_SVS]; + +} GnssSvStatus; + +/* CellID for 2G, 3G and LTE, used in AGPS. */ +typedef struct { + AGpsRefLocationType type; + /** Mobile Country Code. */ + uint16_t mcc; + /** Mobile Network Code .*/ + uint16_t mnc; + /** Location Area Code in 2G, 3G and LTE. In 3G lac is discarded. In LTE, + * lac is populated with tac, to ensure that we don't break old clients that + * might rely in the old (wrong) behavior. + */ + uint16_t lac; + /** Cell id in 2G. Utran Cell id in 3G. Cell Global Id EUTRA in LTE. */ + uint32_t cid; + /** Tracking Area Code in LTE. */ + uint16_t tac; + /** Physical Cell id in LTE (not used in 2G and 3G) */ + uint16_t pcid; +} AGpsRefLocationCellID; + +typedef struct { + uint8_t mac[6]; +} AGpsRefLocationMac; + +/** Represents ref locations */ +typedef struct { + AGpsRefLocationType type; + union { + AGpsRefLocationCellID cellID; + AGpsRefLocationMac mac; + } u; +} AGpsRefLocation; + +/** + * Callback with location information. Can only be called from a thread created + * by create_thread_cb. + */ +typedef void (* gps_location_callback)(GpsLocation* location); + +/** + * Callback with status information. Can only be called from a thread created by + * create_thread_cb. + */ +typedef void (* gps_status_callback)(GpsStatus* status); + +/** + * Legacy callback with SV status information. + * Can only be called from a thread created by create_thread_cb. + * + * This callback is deprecated, and will be removed in the next release. Use + * gnss_sv_status_callback() instead. + */ +typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info); + +/** + * Callback with SV status information. + * Can only be called from a thread created by create_thread_cb. + */ +typedef void (* gnss_sv_status_callback)(GnssSvStatus* sv_info); + +/** + * Callback for reporting NMEA sentences. Can only be called from a thread + * created by create_thread_cb. + */ +typedef void (* gps_nmea_callback)(GpsUtcTime timestamp, const char* nmea, int length); + +/** + * Callback to inform framework of the GPS engine's capabilities. Capability + * parameter is a bit field of GPS_CAPABILITY_* flags. + */ +typedef void (* gps_set_capabilities)(uint32_t capabilities); + +/** + * Callback utility for acquiring the GPS wakelock. This can be used to prevent + * the CPU from suspending while handling GPS events. + */ +typedef void (* gps_acquire_wakelock)(); + +/** Callback utility for releasing the GPS wakelock. */ +typedef void (* gps_release_wakelock)(); + +/** Callback for requesting NTP time */ +typedef void (* gps_request_utc_time)(); + +/** + * Callback for creating a thread that can call into the Java framework code. + * This must be used to create any threads that report events up to the + * framework. + */ +typedef pthread_t (* gps_create_thread)(const char* name, void (*start)(void *), void* arg); + +/** + * Provides information about how new the underlying GPS/GNSS hardware and + * software is. + * + * This information will be available for Android Test Applications. If a GPS + * HAL does not provide this information, it will be considered "2015 or + * earlier". + * + * If a GPS HAL does provide this information, then newer years will need to + * meet newer CTS standards. E.g. if the date are 2016 or above, then N+ level + * GpsMeasurement support will be verified. + */ +typedef struct { + /** Set to sizeof(GnssSystemInfo) */ + size_t size; + /* year in which the last update was made to the underlying hardware/firmware + * used to capture GNSS signals, e.g. 2016 */ + uint16_t year_of_hw; +} GnssSystemInfo; + +/** + * Callback to inform framework of the engine's hardware version information. + */ +typedef void (*gnss_set_system_info)(const GnssSystemInfo* info); + +/** New GPS callback structure. */ +typedef struct { + /** set to sizeof(GpsCallbacks) */ + size_t size; + gps_location_callback location_cb; + gps_status_callback status_cb; + gps_sv_status_callback sv_status_cb; + gps_nmea_callback nmea_cb; + gps_set_capabilities set_capabilities_cb; + gps_acquire_wakelock acquire_wakelock_cb; + gps_release_wakelock release_wakelock_cb; + gps_create_thread create_thread_cb; + gps_request_utc_time request_utc_time_cb; + + gnss_set_system_info set_system_info_cb; + gnss_sv_status_callback gnss_sv_status_cb; +} GpsCallbacks; + +/** Represents the standard GPS interface. */ +typedef struct { + /** set to sizeof(GpsInterface) */ + size_t size; + /** + * Opens the interface and provides the callback routines + * to the implementation of this interface. + */ + int (*init)( GpsCallbacks* callbacks ); + + /** Starts navigating. */ + int (*start)( void ); + + /** Stops navigating. */ + int (*stop)( void ); + + /** Closes the interface. */ + void (*cleanup)( void ); + + /** Injects the current time. */ + int (*inject_time)(GpsUtcTime time, int64_t timeReference, + int uncertainty); + + /** + * Injects current location from another location provider (typically cell + * ID). Latitude and longitude are measured in degrees expected accuracy is + * measured in meters + */ + int (*inject_location)(double latitude, double longitude, float accuracy); + + /** + * Specifies that the next call to start will not use the + * information defined in the flags. GPS_DELETE_ALL is passed for + * a cold start. + */ + void (*delete_aiding_data)(GpsAidingData flags); + + /** + * min_interval represents the time between fixes in milliseconds. + * preferred_accuracy represents the requested fix accuracy in meters. + * preferred_time represents the requested time to first fix in milliseconds. + * + * 'mode' parameter should be one of GPS_POSITION_MODE_MS_BASED + * or GPS_POSITION_MODE_STANDALONE. + * It is allowed by the platform (and it is recommended) to fallback to + * GPS_POSITION_MODE_MS_BASED if GPS_POSITION_MODE_MS_ASSISTED is passed in, and + * GPS_POSITION_MODE_MS_BASED is supported. + */ + int (*set_position_mode)(GpsPositionMode mode, GpsPositionRecurrence recurrence, + uint32_t min_interval, uint32_t preferred_accuracy, uint32_t preferred_time); + + /** Get a pointer to extension information. */ + const void* (*get_extension)(const char* name); +} GpsInterface; + +/** + * Callback to request the client to download XTRA data. The client should + * download XTRA data and inject it by calling inject_xtra_data(). Can only be + * called from a thread created by create_thread_cb. + */ +typedef void (* gps_xtra_download_request)(); + +/** Callback structure for the XTRA interface. */ +typedef struct { + gps_xtra_download_request download_request_cb; + gps_create_thread create_thread_cb; +} GpsXtraCallbacks; + +/** Extended interface for XTRA support. */ +typedef struct { + /** set to sizeof(GpsXtraInterface) */ + size_t size; + /** + * Opens the XTRA interface and provides the callback routines + * to the implementation of this interface. + */ + int (*init)( GpsXtraCallbacks* callbacks ); + /** Injects XTRA data into the GPS. */ + int (*inject_xtra_data)( char* data, int length ); +} GpsXtraInterface; + +/** Extended interface for DEBUG support. */ +typedef struct { + /** set to sizeof(GpsDebugInterface) */ + size_t size; + + /** + * This function should return any information that the native + * implementation wishes to include in a bugreport. + */ + size_t (*get_internal_state)(char* buffer, size_t bufferSize); +} GpsDebugInterface; + +/* + * Represents the status of AGPS augmented to support IPv4 and IPv6. + */ +typedef struct { + /** set to sizeof(AGpsStatus) */ + size_t size; + + AGpsType type; + AGpsStatusValue status; + + /** + * Must be set to a valid IPv4 address if the field 'addr' contains an IPv4 + * address, or set to INADDR_NONE otherwise. + */ + uint32_t ipaddr; + + /** + * Must contain the IPv4 (AF_INET) or IPv6 (AF_INET6) address to report. + * Any other value of addr.ss_family will be rejected. + */ + struct sockaddr_storage addr; +} AGpsStatus; + +/** + * Callback with AGPS status information. Can only be called from a thread + * created by create_thread_cb. + */ +typedef void (* agps_status_callback)(AGpsStatus* status); + +/** Callback structure for the AGPS interface. */ +typedef struct { + agps_status_callback status_cb; + gps_create_thread create_thread_cb; +} AGpsCallbacks; + +/** + * Extended interface for AGPS support, it is augmented to enable to pass + * extra APN data. + */ +typedef struct { + /** set to sizeof(AGpsInterface) */ + size_t size; + + /** + * Opens the AGPS interface and provides the callback routines to the + * implementation of this interface. + */ + void (*init)(AGpsCallbacks* callbacks); + /** + * Deprecated. + * If the HAL supports AGpsInterface_v2 this API will not be used, see + * data_conn_open_with_apn_ip_type for more information. + */ + int (*data_conn_open)(const char* apn); + /** + * Notifies that the AGPS data connection has been closed. + */ + int (*data_conn_closed)(); + /** + * Notifies that a data connection is not available for AGPS. + */ + int (*data_conn_failed)(); + /** + * Sets the hostname and port for the AGPS server. + */ + int (*set_server)(AGpsType type, const char* hostname, int port); + + /** + * Notifies that a data connection is available and sets the name of the + * APN, and its IP type, to be used for SUPL connections. + */ + int (*data_conn_open_with_apn_ip_type)( + const char* apn, + ApnIpType apnIpType); +} AGpsInterface; + +/** Error codes associated with certificate operations */ +#define AGPS_CERTIFICATE_OPERATION_SUCCESS 0 +#define AGPS_CERTIFICATE_ERROR_GENERIC -100 +#define AGPS_CERTIFICATE_ERROR_TOO_MANY_CERTIFICATES -101 + +/** A data structure that represents an X.509 certificate using DER encoding */ +typedef struct { + size_t length; + u_char* data; +} DerEncodedCertificate; + +/** + * A type definition for SHA1 Fingerprints used to identify X.509 Certificates + * The Fingerprint is a digest of the DER Certificate that uniquely identifies it. + */ +typedef struct { + u_char data[20]; +} Sha1CertificateFingerprint; + +/** AGPS Interface to handle SUPL certificate operations */ +typedef struct { + /** set to sizeof(SuplCertificateInterface) */ + size_t size; + + /** + * Installs a set of Certificates used for SUPL connections to the AGPS server. + * If needed the HAL should find out internally any certificates that need to be removed to + * accommodate the certificates to install. + * The certificates installed represent a full set of valid certificates needed to connect to + * AGPS SUPL servers. + * The list of certificates is required, and all must be available at the same time, when trying + * to establish a connection with the AGPS Server. + * + * Parameters: + * certificates - A pointer to an array of DER encoded certificates that are need to be + * installed in the HAL. + * length - The number of certificates to install. + * Returns: + * AGPS_CERTIFICATE_OPERATION_SUCCESS if the operation is completed successfully + * AGPS_CERTIFICATE_ERROR_TOO_MANY_CERTIFICATES if the HAL cannot store the number of + * certificates attempted to be installed, the state of the certificates stored should + * remain the same as before on this error case. + * + * IMPORTANT: + * If needed the HAL should find out internally the set of certificates that need to be + * removed to accommodate the certificates to install. + */ + int (*install_certificates) ( const DerEncodedCertificate* certificates, size_t length ); + + /** + * Notifies the HAL that a list of certificates used for SUPL connections are revoked. It is + * expected that the given set of certificates is removed from the internal store of the HAL. + * + * Parameters: + * fingerprints - A pointer to an array of SHA1 Fingerprints to identify the set of + * certificates to revoke. + * length - The number of fingerprints provided. + * Returns: + * AGPS_CERTIFICATE_OPERATION_SUCCESS if the operation is completed successfully. + * + * IMPORTANT: + * If any of the certificates provided (through its fingerprint) is not known by the HAL, + * it should be ignored and continue revoking/deleting the rest of them. + */ + int (*revoke_certificates) ( const Sha1CertificateFingerprint* fingerprints, size_t length ); +} SuplCertificateInterface; + +/** Represents an NI request */ +typedef struct { + /** set to sizeof(GpsNiNotification) */ + size_t size; + + /** + * An ID generated by HAL to associate NI notifications and UI + * responses + */ + int notification_id; + + /** + * An NI type used to distinguish different categories of NI + * events, such as GPS_NI_TYPE_VOICE, GPS_NI_TYPE_UMTS_SUPL, ... + */ + GpsNiType ni_type; + + /** + * Notification/verification options, combinations of GpsNiNotifyFlags constants + */ + GpsNiNotifyFlags notify_flags; + + /** + * Timeout period to wait for user response. + * Set to 0 for no time out limit. + */ + int timeout; + + /** + * Default response when time out. + */ + GpsUserResponseType default_response; + + /** + * Requestor ID + */ + char requestor_id[GPS_NI_SHORT_STRING_MAXLEN]; + + /** + * Notification message. It can also be used to store client_id in some cases + */ + char text[GPS_NI_LONG_STRING_MAXLEN]; + + /** + * Client name decoding scheme + */ + GpsNiEncodingType requestor_id_encoding; + + /** + * Client name decoding scheme + */ + GpsNiEncodingType text_encoding; + + /** + * A pointer to extra data. Format: + * key_1 = value_1 + * key_2 = value_2 + */ + char extras[GPS_NI_LONG_STRING_MAXLEN]; + +} GpsNiNotification; + +/** + * Callback with NI notification. Can only be called from a thread created by + * create_thread_cb. + */ +typedef void (*gps_ni_notify_callback)(GpsNiNotification *notification); + +/** GPS NI callback structure. */ +typedef struct +{ + /** + * Sends the notification request from HAL to GPSLocationProvider. + */ + gps_ni_notify_callback notify_cb; + gps_create_thread create_thread_cb; +} GpsNiCallbacks; + +/** + * Extended interface for Network-initiated (NI) support. + */ +typedef struct +{ + /** set to sizeof(GpsNiInterface) */ + size_t size; + + /** Registers the callbacks for HAL to use. */ + void (*init) (GpsNiCallbacks *callbacks); + + /** Sends a response to HAL. */ + void (*respond) (int notif_id, GpsUserResponseType user_response); +} GpsNiInterface; + +struct gps_device_t { + struct hw_device_t common; + + /** + * Set the provided lights to the provided values. + * + * Returns: 0 on succes, error code on failure. + */ + const GpsInterface* (*get_gps_interface)(struct gps_device_t* dev); +}; + +#define AGPS_RIL_REQUEST_REFLOC_CELLID (1<<0L) +#define AGPS_RIL_REQUEST_REFLOC_MAC (1<<1L) + +typedef void (*agps_ril_request_set_id)(uint32_t flags); +typedef void (*agps_ril_request_ref_loc)(uint32_t flags); + +typedef struct { + agps_ril_request_set_id request_setid; + agps_ril_request_ref_loc request_refloc; + gps_create_thread create_thread_cb; +} AGpsRilCallbacks; + +/** Extended interface for AGPS_RIL support. */ +typedef struct { + /** set to sizeof(AGpsRilInterface) */ + size_t size; + /** + * Opens the AGPS interface and provides the callback routines + * to the implementation of this interface. + */ + void (*init)( AGpsRilCallbacks* callbacks ); + + /** + * Sets the reference location. + */ + void (*set_ref_location) (const AGpsRefLocation *agps_reflocation, size_t sz_struct); + /** + * Sets the set ID. + */ + void (*set_set_id) (AGpsSetIDType type, const char* setid); + + /** + * Send network initiated message. + */ + void (*ni_message) (uint8_t *msg, size_t len); + + /** + * Notify GPS of network status changes. + * These parameters match values in the android.net.NetworkInfo class. + */ + void (*update_network_state) (int connected, int type, int roaming, const char* extra_info); + + /** + * Notify GPS of network status changes. + * These parameters match values in the android.net.NetworkInfo class. + */ + void (*update_network_availability) (int avaiable, const char* apn); +} AGpsRilInterface; + +/** + * GPS Geofence. + * There are 3 states associated with a Geofence: Inside, Outside, Unknown. + * There are 3 transitions: ENTERED, EXITED, UNCERTAIN. + * + * An example state diagram with confidence level: 95% and Unknown time limit + * set as 30 secs is shown below. (confidence level and Unknown time limit are + * explained latter) + * ____________________________ + * | Unknown (30 secs) | + * """""""""""""""""""""""""""" + * ^ | | ^ + * UNCERTAIN| |ENTERED EXITED| |UNCERTAIN + * | v v | + * ________ EXITED _________ + * | Inside | -----------> | Outside | + * | | <----------- | | + * """""""" ENTERED """"""""" + * + * Inside state: We are 95% confident that the user is inside the geofence. + * Outside state: We are 95% confident that the user is outside the geofence + * Unknown state: Rest of the time. + * + * The Unknown state is better explained with an example: + * + * __________ + * | c| + * | ___ | _______ + * | |a| | | b | + * | """ | """"""" + * | | + * """""""""" + * In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy + * circle reported by the GPS subsystem. Now with regard to "b", the system is + * confident that the user is outside. But with regard to "a" is not confident + * whether it is inside or outside the geofence. If the accuracy remains the + * same for a sufficient period of time, the UNCERTAIN transition would be + * triggered with the state set to Unknown. If the accuracy improves later, an + * appropriate transition should be triggered. This "sufficient period of time" + * is defined by the parameter in the add_geofence_area API. + * In other words, Unknown state can be interpreted as a state in which the + * GPS subsystem isn't confident enough that the user is either inside or + * outside the Geofence. It moves to Unknown state only after the expiry of the + * timeout. + * + * The geofence callback needs to be triggered for the ENTERED and EXITED + * transitions, when the GPS system is confident that the user has entered + * (Inside state) or exited (Outside state) the Geofence. An implementation + * which uses a value of 95% as the confidence is recommended. The callback + * should be triggered only for the transitions requested by the + * add_geofence_area call. + * + * Even though the diagram and explanation talks about states and transitions, + * the callee is only interested in the transistions. The states are mentioned + * here for illustrative purposes. + * + * Startup Scenario: When the device boots up, if an application adds geofences, + * and then we get an accurate GPS location fix, it needs to trigger the + * appropriate (ENTERED or EXITED) transition for every Geofence it knows about. + * By default, all the Geofences will be in the Unknown state. + * + * When the GPS system is unavailable, gps_geofence_status_callback should be + * called to inform the upper layers of the same. Similarly, when it becomes + * available the callback should be called. This is a global state while the + * UNKNOWN transition described above is per geofence. + * + * An important aspect to note is that users of this API (framework), will use + * other subsystems like wifi, sensors, cell to handle Unknown case and + * hopefully provide a definitive state transition to the third party + * application. GPS Geofence will just be a signal indicating what the GPS + * subsystem knows about the Geofence. + * + */ + +/** + * The callback associated with the geofence. + * Parameters: + * geofence_id - The id associated with the add_geofence_area. + * location - The current GPS location. + * transition - Can be one of GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED, + * GPS_GEOFENCE_UNCERTAIN. + * timestamp - Timestamp when the transition was detected. + * + * The callback should only be called when the caller is interested in that + * particular transition. For instance, if the caller is interested only in + * ENTERED transition, then the callback should NOT be called with the EXITED + * transition. + * + * IMPORTANT: If a transition is triggered resulting in this callback, the GPS + * subsystem will wake up the application processor, if its in suspend state. + */ +typedef void (*gps_geofence_transition_callback) (int32_t geofence_id, GpsLocation* location, + int32_t transition, GpsUtcTime timestamp); + +/** + * The callback associated with the availability of the GPS system for geofencing + * monitoring. If the GPS system determines that it cannot monitor geofences + * because of lack of reliability or unavailability of the GPS signals, it will + * call this callback with GPS_GEOFENCE_UNAVAILABLE parameter. + * + * Parameters: + * status - GPS_GEOFENCE_UNAVAILABLE or GPS_GEOFENCE_AVAILABLE. + * last_location - Last known location. + */ +typedef void (*gps_geofence_status_callback) (int32_t status, GpsLocation* last_location); + +/** + * The callback associated with the add_geofence call. + * + * Parameter: + * geofence_id - Id of the geofence. + * status - GPS_GEOFENCE_OPERATION_SUCCESS + * GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES - geofence limit has been reached. + * GPS_GEOFENCE_ERROR_ID_EXISTS - geofence with id already exists + * GPS_GEOFENCE_ERROR_INVALID_TRANSITION - the monitorTransition contains an + * invalid transition + * GPS_GEOFENCE_ERROR_GENERIC - for other errors. + */ +typedef void (*gps_geofence_add_callback) (int32_t geofence_id, int32_t status); + +/** + * The callback associated with the remove_geofence call. + * + * Parameter: + * geofence_id - Id of the geofence. + * status - GPS_GEOFENCE_OPERATION_SUCCESS + * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id + * GPS_GEOFENCE_ERROR_GENERIC for others. + */ +typedef void (*gps_geofence_remove_callback) (int32_t geofence_id, int32_t status); + + +/** + * The callback associated with the pause_geofence call. + * + * Parameter: + * geofence_id - Id of the geofence. + * status - GPS_GEOFENCE_OPERATION_SUCCESS + * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id + * GPS_GEOFENCE_ERROR_INVALID_TRANSITION - + * when monitor_transitions is invalid + * GPS_GEOFENCE_ERROR_GENERIC for others. + */ +typedef void (*gps_geofence_pause_callback) (int32_t geofence_id, int32_t status); + +/** + * The callback associated with the resume_geofence call. + * + * Parameter: + * geofence_id - Id of the geofence. + * status - GPS_GEOFENCE_OPERATION_SUCCESS + * GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id + * GPS_GEOFENCE_ERROR_GENERIC for others. + */ +typedef void (*gps_geofence_resume_callback) (int32_t geofence_id, int32_t status); + +typedef struct { + gps_geofence_transition_callback geofence_transition_callback; + gps_geofence_status_callback geofence_status_callback; + gps_geofence_add_callback geofence_add_callback; + gps_geofence_remove_callback geofence_remove_callback; + gps_geofence_pause_callback geofence_pause_callback; + gps_geofence_resume_callback geofence_resume_callback; + gps_create_thread create_thread_cb; +} GpsGeofenceCallbacks; + +/** Extended interface for GPS_Geofencing support */ +typedef struct { + /** set to sizeof(GpsGeofencingInterface) */ + size_t size; + + /** + * Opens the geofence interface and provides the callback routines + * to the implementation of this interface. + */ + void (*init)( GpsGeofenceCallbacks* callbacks ); + + /** + * Add a geofence area. This api currently supports circular geofences. + * Parameters: + * geofence_id - The id for the geofence. If a geofence with this id + * already exists, an error value (GPS_GEOFENCE_ERROR_ID_EXISTS) + * should be returned. + * latitude, longtitude, radius_meters - The lat, long and radius + * (in meters) for the geofence + * last_transition - The current state of the geofence. For example, if + * the system already knows that the user is inside the geofence, + * this will be set to GPS_GEOFENCE_ENTERED. In most cases, it + * will be GPS_GEOFENCE_UNCERTAIN. + * monitor_transition - Which transitions to monitor. Bitwise OR of + * GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and + * GPS_GEOFENCE_UNCERTAIN. + * notification_responsiveness_ms - Defines the best-effort description + * of how soon should the callback be called when the transition + * associated with the Geofence is triggered. For instance, if set + * to 1000 millseconds with GPS_GEOFENCE_ENTERED, the callback + * should be called 1000 milliseconds within entering the geofence. + * This parameter is defined in milliseconds. + * NOTE: This is not to be confused with the rate that the GPS is + * polled at. It is acceptable to dynamically vary the rate of + * sampling the GPS for power-saving reasons; thus the rate of + * sampling may be faster or slower than this. + * unknown_timer_ms - The time limit after which the UNCERTAIN transition + * should be triggered. This parameter is defined in milliseconds. + * See above for a detailed explanation. + */ + void (*add_geofence_area) (int32_t geofence_id, double latitude, double longitude, + double radius_meters, int last_transition, int monitor_transitions, + int notification_responsiveness_ms, int unknown_timer_ms); + + /** + * Pause monitoring a particular geofence. + * Parameters: + * geofence_id - The id for the geofence. + */ + void (*pause_geofence) (int32_t geofence_id); + + /** + * Resume monitoring a particular geofence. + * Parameters: + * geofence_id - The id for the geofence. + * monitor_transitions - Which transitions to monitor. Bitwise OR of + * GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and + * GPS_GEOFENCE_UNCERTAIN. + * This supersedes the value associated provided in the + * add_geofence_area call. + */ + void (*resume_geofence) (int32_t geofence_id, int monitor_transitions); + + /** + * Remove a geofence area. After the function returns, no notifications + * should be sent. + * Parameter: + * geofence_id - The id for the geofence. + */ + void (*remove_geofence_area) (int32_t geofence_id); +} GpsGeofencingInterface; + +/** + * Legacy struct to represent an estimate of the GPS clock time. + * Deprecated, to be removed in the next Android release. + * Use GnssClock instead. + */ +typedef struct { + /** set to sizeof(GpsClock) */ + size_t size; + GpsClockFlags flags; + int16_t leap_second; + GpsClockType type; + int64_t time_ns; + double time_uncertainty_ns; + int64_t full_bias_ns; + double bias_ns; + double bias_uncertainty_ns; + double drift_nsps; + double drift_uncertainty_nsps; +} GpsClock; + +/** + * Represents an estimate of the GPS clock time. + */ +typedef struct { + /** set to sizeof(GnssClock) */ + size_t size; + + /** + * A set of flags indicating the validity of the fields in this data + * structure. + */ + GnssClockFlags flags; + + /** + * Leap second data. + * The sign of the value is defined by the following equation: + * utc_time_ns = time_ns - (full_bias_ns + bias_ns) - leap_second * + * 1,000,000,000 + * + * If the data is available 'flags' must contain GNSS_CLOCK_HAS_LEAP_SECOND. + */ + int16_t leap_second; + + /** + * The GNSS receiver internal clock value. This is the local hardware clock + * value. + * + * For local hardware clock, this value is expected to be monotonically + * increasing while the hardware clock remains power on. (For the case of a + * HW clock that is not continuously on, see the + * hw_clock_discontinuity_count field). The receiver's estimate of GPS time + * can be derived by substracting the sum of full_bias_ns and bias_ns (when + * available) from this value. + * + * This GPS time is expected to be the best estimate of current GPS time + * that GNSS receiver can achieve. + * + * Sub-nanosecond accuracy can be provided by means of the 'bias_ns' field. + * The value contains the 'time uncertainty' in it. + * + * This field is mandatory. + */ + int64_t time_ns; + + /** + * 1-Sigma uncertainty associated with the clock's time in nanoseconds. + * The uncertainty is represented as an absolute (single sided) value. + * + * If the data is available, 'flags' must contain + * GNSS_CLOCK_HAS_TIME_UNCERTAINTY. This value is effectively zero (it is + * the reference local clock, by which all other times and time + * uncertainties are measured.) (And thus this field can be not provided, + * per GNSS_CLOCK_HAS_TIME_UNCERTAINTY flag, or provided & set to 0.) + */ + double time_uncertainty_ns; + + /** + * The difference between hardware clock ('time' field) inside GPS receiver + * and the true GPS time since 0000Z, January 6, 1980, in nanoseconds. + * + * The sign of the value is defined by the following equation: + * local estimate of GPS time = time_ns - (full_bias_ns + bias_ns) + * + * This value is mandatory if the receiver has estimated GPS time. If the + * computed time is for a non-GPS constellation, the time offset of that + * constellation to GPS has to be applied to fill this value. The error + * estimate for the sum of this and the bias_ns is the bias_uncertainty_ns, + * and the caller is responsible for using this uncertainty (it can be very + * large before the GPS time has been solved for.) If the data is available + * 'flags' must contain GNSS_CLOCK_HAS_FULL_BIAS. + */ + int64_t full_bias_ns; + + /** + * Sub-nanosecond bias. + * The error estimate for the sum of this and the full_bias_ns is the + * bias_uncertainty_ns + * + * If the data is available 'flags' must contain GNSS_CLOCK_HAS_BIAS. If GPS + * has computed a position fix. This value is mandatory if the receiver has + * estimated GPS time. + */ + double bias_ns; + + /** + * 1-Sigma uncertainty associated with the local estimate of GPS time (clock + * bias) in nanoseconds. The uncertainty is represented as an absolute + * (single sided) value. + * + * If the data is available 'flags' must contain + * GNSS_CLOCK_HAS_BIAS_UNCERTAINTY. This value is mandatory if the receiver + * has estimated GPS time. + */ + double bias_uncertainty_ns; + + /** + * The clock's drift in nanoseconds (per second). + * + * A positive value means that the frequency is higher than the nominal + * frequency, and that the (full_bias_ns + bias_ns) is growing more positive + * over time. + * + * The value contains the 'drift uncertainty' in it. + * If the data is available 'flags' must contain GNSS_CLOCK_HAS_DRIFT. + * + * This value is mandatory if the receiver has estimated GNSS time + */ + double drift_nsps; + + /** + * 1-Sigma uncertainty associated with the clock's drift in nanoseconds (per second). + * The uncertainty is represented as an absolute (single sided) value. + * + * If the data is available 'flags' must contain + * GNSS_CLOCK_HAS_DRIFT_UNCERTAINTY. If GPS has computed a position fix this + * field is mandatory and must be populated. + */ + double drift_uncertainty_nsps; + + /** + * When there are any discontinuities in the HW clock, this field is + * mandatory. + * + * A "discontinuity" is meant to cover the case of a switch from one source + * of clock to another. A single free-running crystal oscillator (XO) + * should generally not have any discontinuities, and this can be set and + * left at 0. + * + * If, however, the time_ns value (HW clock) is derived from a composite of + * sources, that is not as smooth as a typical XO, or is otherwise stopped & + * restarted, then this value shall be incremented each time a discontinuity + * occurs. (E.g. this value may start at zero at device boot-up and + * increment each time there is a change in clock continuity. In the + * unlikely event that this value reaches full scale, rollover (not + * clamping) is required, such that this value continues to change, during + * subsequent discontinuity events.) + * + * While this number stays the same, between GnssClock reports, it can be + * safely assumed that the time_ns value has been running continuously, e.g. + * derived from a single, high quality clock (XO like, or better, that's + * typically used during continuous GNSS signal sampling.) + * + * It is expected, esp. during periods where there are few GNSS signals + * available, that the HW clock be discontinuity-free as long as possible, + * as this avoids the need to use (waste) a GNSS measurement to fully + * re-solve for the GPS clock bias and drift, when using the accompanying + * measurements, from consecutive GnssData reports. + */ + uint32_t hw_clock_discontinuity_count; + +} GnssClock; + +/** + * Legacy struct to represent a GPS Measurement, it contains raw and computed + * information. + * Deprecated, to be removed in the next Android release. + * Use GnssMeasurement instead. + */ +typedef struct { + /** set to sizeof(GpsMeasurement) */ + size_t size; + GpsMeasurementFlags flags; + int8_t prn; + double time_offset_ns; + GpsMeasurementState state; + int64_t received_gps_tow_ns; + int64_t received_gps_tow_uncertainty_ns; + double c_n0_dbhz; + double pseudorange_rate_mps; + double pseudorange_rate_uncertainty_mps; + GpsAccumulatedDeltaRangeState accumulated_delta_range_state; + double accumulated_delta_range_m; + double accumulated_delta_range_uncertainty_m; + double pseudorange_m; + double pseudorange_uncertainty_m; + double code_phase_chips; + double code_phase_uncertainty_chips; + float carrier_frequency_hz; + int64_t carrier_cycles; + double carrier_phase; + double carrier_phase_uncertainty; + GpsLossOfLock loss_of_lock; + int32_t bit_number; + int16_t time_from_last_bit_ms; + double doppler_shift_hz; + double doppler_shift_uncertainty_hz; + GpsMultipathIndicator multipath_indicator; + double snr_db; + double elevation_deg; + double elevation_uncertainty_deg; + double azimuth_deg; + double azimuth_uncertainty_deg; + bool used_in_fix; +} GpsMeasurement; + +/** + * Represents a GNSS Measurement, it contains raw and computed information. + * + * Independence - All signal measurement information (e.g. sv_time, + * pseudorange_rate, multipath_indicator) reported in this struct should be + * based on GNSS signal measurements only. You may not synthesize measurements + * by calculating or reporting expected measurements based on known or estimated + * position, velocity, or time. + */ +typedef struct { + /** set to sizeof(GpsMeasurement) */ + size_t size; + + /** A set of flags indicating the validity of the fields in this data structure. */ + GnssMeasurementFlags flags; + + /** + * Satellite vehicle ID number, as defined in GnssSvInfo::svid + * This is a mandatory value. + */ + int16_t svid; + + /** + * Defines the constellation of the given SV. Value should be one of those + * GNSS_CONSTELLATION_* constants + */ + GnssConstellationType constellation; + + /** + * Time offset at which the measurement was taken in nanoseconds. + * The reference receiver's time is specified by GpsData::clock::time_ns and should be + * interpreted in the same way as indicated by GpsClock::type. + * + * The sign of time_offset_ns is given by the following equation: + * measurement time = GpsClock::time_ns + time_offset_ns + * + * It provides an individual time-stamp for the measurement, and allows sub-nanosecond accuracy. + * This is a mandatory value. + */ + double time_offset_ns; + + /** + * Per satellite sync state. It represents the current sync state for the associated satellite. + * Based on the sync state, the 'received GPS tow' field should be interpreted accordingly. + * + * This is a mandatory value. + */ + GnssMeasurementState state; + + /** + * The received GNSS Time-of-Week at the measurement time, in nanoseconds. + * Ensure that this field is independent (see comment at top of + * GnssMeasurement struct.) + * + * For GPS & QZSS, this is: + * Received GPS Time-of-Week at the measurement time, in nanoseconds. + * The value is relative to the beginning of the current GPS week. + * + * Given the highest sync state that can be achieved, per each satellite, valid range + * for this field can be: + * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN + * C/A code lock : [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set + * Bit sync : [ 0 20ms ] : GNSS_MEASUREMENT_STATE_BIT_SYNC is set + * Subframe sync : [ 0 6s ] : GNSS_MEASUREMENT_STATE_SUBFRAME_SYNC is set + * TOW decoded : [ 0 1week ] : GNSS_MEASUREMENT_STATE_TOW_DECODED is set + * + * Note well: if there is any ambiguity in integer millisecond, + * GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS should be set accordingly, in the 'state' field. + * + * This value must be populated if 'state' != GNSS_MEASUREMENT_STATE_UNKNOWN. + * + * For Glonass, this is: + * Received Glonass time of day, at the measurement time in nanoseconds. + * + * Given the highest sync state that can be achieved, per each satellite, valid range for + * this field can be: + * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN + * C/A code lock : [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set + * Symbol sync : [ 0 10ms ] : GNSS_MEASUREMENT_STATE_SYMBOL_SYNC is set + * Bit sync : [ 0 20ms ] : GNSS_MEASUREMENT_STATE_BIT_SYNC is set + * String sync : [ 0 2s ] : GNSS_MEASUREMENT_STATE_GLO_STRING_SYNC is set + * Time of day : [ 0 1day ] : GNSS_MEASUREMENT_STATE_GLO_TOD_DECODED is set + * + * For Beidou, this is: + * Received Beidou time of week, at the measurement time in nanoseconds. + * + * Given the highest sync state that can be achieved, per each satellite, valid range for + * this field can be: + * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN + * C/A code lock: [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set + * Bit sync (D2): [ 0 2ms ] : GNSS_MEASUREMENT_STATE_BDS_D2_BIT_SYNC is set + * Bit sync (D1): [ 0 20ms ] : GNSS_MEASUREMENT_STATE_BIT_SYNC is set + * Subframe (D2): [ 0 0.6s ] : GNSS_MEASUREMENT_STATE_BDS_D2_SUBFRAME_SYNC is set + * Subframe (D1): [ 0 6s ] : GNSS_MEASUREMENT_STATE_SUBFRAME_SYNC is set + * Time of week : [ 0 1week ] : GNSS_MEASUREMENT_STATE_TOW_DECODED is set + * + * For Galileo, this is: + * Received Galileo time of week, at the measurement time in nanoseconds. + * + * E1BC code lock : [ 0 4ms ] : GNSS_MEASUREMENT_STATE_GAL_E1BC_CODE_LOCK is set + * E1C 2nd code lock: [ 0 100ms ] : + * GNSS_MEASUREMENT_STATE_GAL_E1C_2ND_CODE_LOCK is set + * + * E1B page : [ 0 2s ] : GNSS_MEASUREMENT_STATE_GAL_E1B_PAGE_SYNC is set + * Time of week: [ 0 1week ] : GNSS_MEASUREMENT_STATE_TOW_DECODED is set + * + * For SBAS, this is: + * Received SBAS time, at the measurement time in nanoseconds. + * + * Given the highest sync state that can be achieved, per each satellite, + * valid range for this field can be: + * Searching : [ 0 ] : GNSS_MEASUREMENT_STATE_UNKNOWN + * C/A code lock: [ 0 1ms ] : GNSS_MEASUREMENT_STATE_CODE_LOCK is set + * Symbol sync : [ 0 2ms ] : GNSS_MEASUREMENT_STATE_SYMBOL_SYNC is set + * Message : [ 0 1s ] : GNSS_MEASUREMENT_STATE_SBAS_SYNC is set + */ + int64_t received_sv_time_in_ns; + + /** + * 1-Sigma uncertainty of the Received GPS Time-of-Week in nanoseconds. + * + * This value must be populated if 'state' != GPS_MEASUREMENT_STATE_UNKNOWN. + */ + int64_t received_sv_time_uncertainty_in_ns; + + /** + * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. + * It contains the measured C/N0 value for the signal at the antenna port. + * + * This is a mandatory value. + */ + double c_n0_dbhz; + + /** + * Pseudorange rate at the timestamp in m/s. The correction of a given + * Pseudorange Rate value includes corrections for receiver and satellite + * clock frequency errors. Ensure that this field is independent (see + * comment at top of GnssMeasurement struct.) + * + * It is mandatory to provide the 'uncorrected' 'pseudorange rate', and provide GpsClock's + * 'drift' field as well (When providing the uncorrected pseudorange rate, do not apply the + * corrections described above.) + * + * The value includes the 'pseudorange rate uncertainty' in it. + * A positive 'uncorrected' value indicates that the SV is moving away from the receiver. + * + * The sign of the 'uncorrected' 'pseudorange rate' and its relation to the sign of 'doppler + * shift' is given by the equation: + * pseudorange rate = -k * doppler shift (where k is a constant) + * + * This should be the most accurate pseudorange rate available, based on + * fresh signal measurements from this channel. + * + * It is mandatory that this value be provided at typical carrier phase PRR + * quality (few cm/sec per second of uncertainty, or better) - when signals + * are sufficiently strong & stable, e.g. signals from a GPS simulator at >= + * 35 dB-Hz. + */ + double pseudorange_rate_mps; + + /** + * 1-Sigma uncertainty of the pseudorange_rate_mps. + * The uncertainty is represented as an absolute (single sided) value. + * + * This is a mandatory value. + */ + double pseudorange_rate_uncertainty_mps; + + /** + * Accumulated delta range's state. It indicates whether ADR is reset or there is a cycle slip + * (indicating loss of lock). + * + * This is a mandatory value. + */ + GnssAccumulatedDeltaRangeState accumulated_delta_range_state; + + /** + * Accumulated delta range since the last channel reset in meters. + * A positive value indicates that the SV is moving away from the receiver. + * + * The sign of the 'accumulated delta range' and its relation to the sign of 'carrier phase' + * is given by the equation: + * accumulated delta range = -k * carrier phase (where k is a constant) + * + * This value must be populated if 'accumulated delta range state' != GPS_ADR_STATE_UNKNOWN. + * However, it is expected that the data is only accurate when: + * 'accumulated delta range state' == GPS_ADR_STATE_VALID. + */ + double accumulated_delta_range_m; + + /** + * 1-Sigma uncertainty of the accumulated delta range in meters. + * This value must be populated if 'accumulated delta range state' != GPS_ADR_STATE_UNKNOWN. + */ + double accumulated_delta_range_uncertainty_m; + + /** + * Carrier frequency at which codes and messages are modulated, it can be L1 or L2. + * If the field is not set, the carrier frequency is assumed to be L1. + * + * If the data is available, 'flags' must contain + * GNSS_MEASUREMENT_HAS_CARRIER_FREQUENCY. + */ + float carrier_frequency_hz; + + /** + * The number of full carrier cycles between the satellite and the receiver. + * The reference frequency is given by the field 'carrier_frequency_hz'. + * Indications of possible cycle slips and resets in the accumulation of + * this value can be inferred from the accumulated_delta_range_state flags. + * + * If the data is available, 'flags' must contain + * GNSS_MEASUREMENT_HAS_CARRIER_CYCLES. + */ + int64_t carrier_cycles; + + /** + * The RF phase detected by the receiver, in the range [0.0, 1.0]. + * This is usually the fractional part of the complete carrier phase measurement. + * + * The reference frequency is given by the field 'carrier_frequency_hz'. + * The value contains the 'carrier-phase uncertainty' in it. + * + * If the data is available, 'flags' must contain + * GNSS_MEASUREMENT_HAS_CARRIER_PHASE. + */ + double carrier_phase; + + /** + * 1-Sigma uncertainty of the carrier-phase. + * If the data is available, 'flags' must contain + * GNSS_MEASUREMENT_HAS_CARRIER_PHASE_UNCERTAINTY. + */ + double carrier_phase_uncertainty; + + /** + * An enumeration that indicates the 'multipath' state of the event. + * + * The multipath Indicator is intended to report the presence of overlapping + * signals that manifest as distorted correlation peaks. + * + * - if there is a distorted correlation peak shape, report that multipath + * is GNSS_MULTIPATH_INDICATOR_PRESENT. + * - if there is not a distorted correlation peak shape, report + * GNSS_MULTIPATH_INDICATOR_NOT_PRESENT + * - if signals are too weak to discern this information, report + * GNSS_MULTIPATH_INDICATOR_UNKNOWN + * + * Example: when doing the standardized overlapping Multipath Performance + * test (3GPP TS 34.171) the Multipath indicator should report + * GNSS_MULTIPATH_INDICATOR_PRESENT for those signals that are tracked, and + * contain multipath, and GNSS_MULTIPATH_INDICATOR_NOT_PRESENT for those + * signals that are tracked and do not contain multipath. + */ + GnssMultipathIndicator multipath_indicator; + + /** + * Signal-to-noise ratio at correlator output in dB. + * If the data is available, 'flags' must contain GNSS_MEASUREMENT_HAS_SNR. + * This is the power ratio of the "correlation peak height above the + * observed noise floor" to "the noise RMS". + */ + double snr_db; +} GnssMeasurement; + +/** + * Legacy struct to represents a reading of GPS measurements. + * Deprecated, to be removed in the next Android release. + * Use GnssData instead. + */ +typedef struct { + /** set to sizeof(GpsData) */ + size_t size; + size_t measurement_count; + GpsMeasurement measurements[GPS_MAX_MEASUREMENT]; + + /** The GPS clock time reading. */ + GpsClock clock; +} GpsData; + +/** + * Represents a reading of GNSS measurements. For devices where GnssSystemInfo's + * year_of_hw is set to 2016+, it is mandatory that these be provided, on + * request, when the GNSS receiver is searching/tracking signals. + * + * - Reporting of GPS constellation measurements is mandatory. + * - Reporting of all tracked constellations are encouraged. + */ +typedef struct { + /** set to sizeof(GnssData) */ + size_t size; + + /** Number of measurements. */ + size_t measurement_count; + + /** The array of measurements. */ + GnssMeasurement measurements[GNSS_MAX_MEASUREMENT]; + + /** The GPS clock time reading. */ + GnssClock clock; +} GnssData; + +/** + * The legacy callback for to report measurements from the HAL. + * + * This callback is deprecated, and will be removed in the next release. Use + * gnss_measurement_callback() instead. + * + * Parameters: + * data - A data structure containing the measurements. + */ +typedef void (*gps_measurement_callback) (GpsData* data); + +/** + * The callback for to report measurements from the HAL. + * + * Parameters: + * data - A data structure containing the measurements. + */ +typedef void (*gnss_measurement_callback) (GnssData* data); + +typedef struct { + /** set to sizeof(GpsMeasurementCallbacks) */ + size_t size; + gps_measurement_callback measurement_callback; + gnss_measurement_callback gnss_measurement_callback; +} GpsMeasurementCallbacks; + +/** + * Extended interface for GPS Measurements support. + */ +typedef struct { + /** Set to sizeof(GpsMeasurementInterface) */ + size_t size; + + /** + * Initializes the interface and registers the callback routines with the HAL. + * After a successful call to 'init' the HAL must begin to provide updates at its own phase. + * + * Status: + * GPS_MEASUREMENT_OPERATION_SUCCESS + * GPS_MEASUREMENT_ERROR_ALREADY_INIT - if a callback has already been registered without a + * corresponding call to 'close' + * GPS_MEASUREMENT_ERROR_GENERIC - if any other error occurred, it is expected that the HAL + * will not generate any updates upon returning this error code. + */ + int (*init) (GpsMeasurementCallbacks* callbacks); + + /** + * Stops updates from the HAL, and unregisters the callback routines. + * After a call to stop, the previously registered callbacks must be considered invalid by the + * HAL. + * If stop is invoked without a previous 'init', this function should perform no work. + */ + void (*close) (); + +} GpsMeasurementInterface; + +/** + * Legacy struct to represents a GPS navigation message (or a fragment of it). + * Deprecated, to be removed in the next Android release. + * Use GnssNavigationMessage instead. + */ +typedef struct { + /** set to sizeof(GpsNavigationMessage) */ + size_t size; + int8_t prn; + GpsNavigationMessageType type; + NavigationMessageStatus status; + int16_t message_id; + int16_t submessage_id; + size_t data_length; + uint8_t* data; +} GpsNavigationMessage; + +/** Represents a GPS navigation message (or a fragment of it). */ +typedef struct { + /** set to sizeof(GnssNavigationMessage) */ + size_t size; + + /** + * Satellite vehicle ID number, as defined in GnssSvInfo::svid + * This is a mandatory value. + */ + int16_t svid; + + /** + * The type of message contained in the structure. + * This is a mandatory value. + */ + GnssNavigationMessageType type; + + /** + * The status of the received navigation message. + * No need to send any navigation message that contains words with parity error and cannot be + * corrected. + */ + NavigationMessageStatus status; + + /** + * Message identifier. It provides an index so the complete Navigation + * Message can be assembled. + * + * - For GPS L1 C/A subframe 4 and 5, this value corresponds to the 'frame + * id' of the navigation message, in the range of 1-25 (Subframe 1, 2, 3 + * does not contain a 'frame id' and this value can be set to -1.) + * + * - For Glonass L1 C/A, this refers to the frame ID, in the range of 1-5. + * + * - For BeiDou D1, this refers to the frame number in the range of 1-24 + * + * - For Beidou D2, this refers to the frame number, in the range of 1-120 + * + * - For Galileo F/NAV nominal frame structure, this refers to the subframe + * number, in the range of 1-12 + * + * - For Galileo I/NAV nominal frame structure, this refers to the subframe + * number in the range of 1-24 + */ + int16_t message_id; + + /** + * Sub-message identifier. If required by the message 'type', this value + * contains a sub-index within the current message (or frame) that is being + * transmitted. + * + * - For GPS L1 C/A, BeiDou D1 & BeiDou D2, the submessage id corresponds to + * the subframe number of the navigation message, in the range of 1-5. + * + * - For Glonass L1 C/A, this refers to the String number, in the range from + * 1-15 + * + * - For Galileo F/NAV, this refers to the page type in the range 1-6 + * + * - For Galileo I/NAV, this refers to the word type in the range 1-10+ + */ + int16_t submessage_id; + + /** + * The length of the data (in bytes) contained in the current message. + * If this value is different from zero, 'data' must point to an array of the same size. + * e.g. for L1 C/A the size of the sub-frame will be 40 bytes (10 words, 30 bits/word). + * + * This is a mandatory value. + */ + size_t data_length; + + /** + * The data of the reported GPS message. The bytes (or words) specified + * using big endian format (MSB first). + * + * - For GPS L1 C/A, Beidou D1 & Beidou D2, each subframe contains 10 30-bit + * words. Each word (30 bits) should be fit into the last 30 bits in a + * 4-byte word (skip B31 and B32), with MSB first, for a total of 40 + * bytes, covering a time period of 6, 6, and 0.6 seconds, respectively. + * + * - For Glonass L1 C/A, each string contains 85 data bits, including the + * checksum. These bits should be fit into 11 bytes, with MSB first (skip + * B86-B88), covering a time period of 2 seconds. + * + * - For Galileo F/NAV, each word consists of 238-bit (sync & tail symbols + * excluded). Each word should be fit into 30-bytes, with MSB first (skip + * B239, B240), covering a time period of 10 seconds. + * + * - For Galileo I/NAV, each page contains 2 page parts, even and odd, with + * a total of 2x114 = 228 bits, (sync & tail excluded) that should be fit + * into 29 bytes, with MSB first (skip B229-B232). + */ + uint8_t* data; + +} GnssNavigationMessage; + +/** + * The legacy callback to report an available fragment of a GPS navigation + * messages from the HAL. + * + * This callback is deprecated, and will be removed in the next release. Use + * gnss_navigation_message_callback() instead. + * + * Parameters: + * message - The GPS navigation submessage/subframe representation. + */ +typedef void (*gps_navigation_message_callback) (GpsNavigationMessage* message); + +/** + * The callback to report an available fragment of a GPS navigation messages from the HAL. + * + * Parameters: + * message - The GPS navigation submessage/subframe representation. + */ +typedef void (*gnss_navigation_message_callback) (GnssNavigationMessage* message); + +typedef struct { + /** set to sizeof(GpsNavigationMessageCallbacks) */ + size_t size; + gps_navigation_message_callback navigation_message_callback; + gnss_navigation_message_callback gnss_navigation_message_callback; +} GpsNavigationMessageCallbacks; + +/** + * Extended interface for GPS navigation message reporting support. + */ +typedef struct { + /** Set to sizeof(GpsNavigationMessageInterface) */ + size_t size; + + /** + * Initializes the interface and registers the callback routines with the HAL. + * After a successful call to 'init' the HAL must begin to provide updates as they become + * available. + * + * Status: + * GPS_NAVIGATION_MESSAGE_OPERATION_SUCCESS + * GPS_NAVIGATION_MESSAGE_ERROR_ALREADY_INIT - if a callback has already been registered + * without a corresponding call to 'close'. + * GPS_NAVIGATION_MESSAGE_ERROR_GENERIC - if any other error occurred, it is expected that + * the HAL will not generate any updates upon returning this error code. + */ + int (*init) (GpsNavigationMessageCallbacks* callbacks); + + /** + * Stops updates from the HAL, and unregisters the callback routines. + * After a call to stop, the previously registered callbacks must be considered invalid by the + * HAL. + * If stop is invoked without a previous 'init', this function should perform no work. + */ + void (*close) (); + +} GpsNavigationMessageInterface; + +/** + * Interface for passing GNSS configuration contents from platform to HAL. + */ +typedef struct { + /** Set to sizeof(GnssConfigurationInterface) */ + size_t size; + + /** + * Deliver GNSS configuration contents to HAL. + * Parameters: + * config_data - a pointer to a char array which holds what usually is expected from + file(/etc/gps.conf), i.e., a sequence of UTF8 strings separated by '\n'. + * length - total number of UTF8 characters in configuraiton data. + * + * IMPORTANT: + * GPS HAL should expect this function can be called multiple times. And it may be + * called even when GpsLocationProvider is already constructed and enabled. GPS HAL + * should maintain the existing requests for various callback regardless the change + * in configuration data. + */ + void (*configuration_update) (const char* config_data, int32_t length); +} GnssConfigurationInterface; + +__END_DECLS + +#endif /* ANDROID_INCLUDE_HARDWARE_GPS_H */ + diff --git a/include_all/hardware/gps_internal.h b/include_all/hardware/gps_internal.h new file mode 100644 index 00000000..6a3833ba --- /dev/null +++ b/include_all/hardware/gps_internal.h @@ -0,0 +1,96 @@ +/* + * Copyright (C) 2016 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_INCLUDE_HARDWARE_GPS_INTERNAL_H +#define ANDROID_INCLUDE_HARDWARE_GPS_INTERNAL_H + +#include "hardware/gps.h" + +/**************************************************************************** + * This file contains legacy structs that are deprecated/retired from gps.h * + ****************************************************************************/ + +__BEGIN_DECLS + +/** + * Legacy GPS callback structure. + * Deprecated, to be removed in the next Android release. + * Use GpsCallbacks instead. + */ +typedef struct { + /** set to sizeof(GpsCallbacks_v1) */ + size_t size; + gps_location_callback location_cb; + gps_status_callback status_cb; + gps_sv_status_callback sv_status_cb; + gps_nmea_callback nmea_cb; + gps_set_capabilities set_capabilities_cb; + gps_acquire_wakelock acquire_wakelock_cb; + gps_release_wakelock release_wakelock_cb; + gps_create_thread create_thread_cb; + gps_request_utc_time request_utc_time_cb; +} GpsCallbacks_v1; + +#pragma pack(push,4) +// We need to keep the alignment of this data structure to 4-bytes, to ensure that in 64-bit +// environments the size of this legacy definition does not collide with _v2. Implementations should +// be using _v2 and _v3, so it's OK to pay the 'unaligned' penalty in 64-bit if an old +// implementation is still in use. + +/** + * Legacy struct to represent the status of AGPS. + */ +typedef struct { + /** set to sizeof(AGpsStatus_v1) */ + size_t size; + AGpsType type; + AGpsStatusValue status; +} AGpsStatus_v1; + +#pragma pack(pop) + +/** + * Legacy struct to represent the status of AGPS augmented with a IPv4 address + * field. + */ +typedef struct { + /** set to sizeof(AGpsStatus_v2) */ + size_t size; + AGpsType type; + AGpsStatusValue status; + + /*-------------------- New fields in _v2 --------------------*/ + + uint32_t ipaddr; +} AGpsStatus_v2; + +/** + * Legacy extended interface for AGPS support. + * See AGpsInterface_v2 for more information. + */ +typedef struct { + /** set to sizeof(AGpsInterface_v1) */ + size_t size; + void (*init)( AGpsCallbacks* callbacks ); + int (*data_conn_open)( const char* apn ); + int (*data_conn_closed)(); + int (*data_conn_failed)(); + int (*set_server)( AGpsType type, const char* hostname, int port ); +} AGpsInterface_v1; + +__END_DECLS + +#endif /* ANDROID_INCLUDE_HARDWARE_GPS_INTERNAL_H */ diff --git a/include_all/hardware/gralloc.h b/include_all/hardware/gralloc.h new file mode 100644 index 00000000..10a153c0 --- /dev/null +++ b/include_all/hardware/gralloc.h @@ -0,0 +1,448 @@ +/* + * Copyright (C) 2008 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_GRALLOC_INTERFACE_H +#define ANDROID_GRALLOC_INTERFACE_H + +#include <system/graphics.h> +#include <hardware/hardware.h> + +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <cutils/native_handle.h> + +#include <hardware/hardware.h> +#include <hardware/fb.h> + +__BEGIN_DECLS + +/** + * Module versioning information for the Gralloc hardware module, based on + * gralloc_module_t.common.module_api_version. + * + * Version History: + * + * GRALLOC_MODULE_API_VERSION_0_1: + * Initial Gralloc hardware module API. + * + * GRALLOC_MODULE_API_VERSION_0_2: + * Add support for flexible YCbCr format with (*lock_ycbcr)() method. + * + * GRALLOC_MODULE_API_VERSION_0_3: + * Add support for fence passing to/from lock/unlock. + */ + +#define GRALLOC_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) +#define GRALLOC_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) +#define GRALLOC_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) + +#define GRALLOC_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION(0, 1) + +/** + * The id of this module + */ +#define GRALLOC_HARDWARE_MODULE_ID "gralloc" + +/** + * Name of the graphics device to open + */ + +#define GRALLOC_HARDWARE_GPU0 "gpu0" + +enum { + /* buffer is never read in software */ + GRALLOC_USAGE_SW_READ_NEVER = 0x00000000U, + /* buffer is rarely read in software */ + GRALLOC_USAGE_SW_READ_RARELY = 0x00000002U, + /* buffer is often read in software */ + GRALLOC_USAGE_SW_READ_OFTEN = 0x00000003U, + /* mask for the software read values */ + GRALLOC_USAGE_SW_READ_MASK = 0x0000000FU, + + /* buffer is never written in software */ + GRALLOC_USAGE_SW_WRITE_NEVER = 0x00000000U, + /* buffer is rarely written in software */ + GRALLOC_USAGE_SW_WRITE_RARELY = 0x00000020U, + /* buffer is often written in software */ + GRALLOC_USAGE_SW_WRITE_OFTEN = 0x00000030U, + /* mask for the software write values */ + GRALLOC_USAGE_SW_WRITE_MASK = 0x000000F0U, + + /* buffer will be used as an OpenGL ES texture */ + GRALLOC_USAGE_HW_TEXTURE = 0x00000100U, + /* buffer will be used as an OpenGL ES render target */ + GRALLOC_USAGE_HW_RENDER = 0x00000200U, + /* buffer will be used by the 2D hardware blitter */ + GRALLOC_USAGE_HW_2D = 0x00000400U, + /* buffer will be used by the HWComposer HAL module */ + GRALLOC_USAGE_HW_COMPOSER = 0x00000800U, + /* buffer will be used with the framebuffer device */ + GRALLOC_USAGE_HW_FB = 0x00001000U, + + /* buffer should be displayed full-screen on an external display when + * possible */ + GRALLOC_USAGE_EXTERNAL_DISP = 0x00002000U, + + /* Must have a hardware-protected path to external display sink for + * this buffer. If a hardware-protected path is not available, then + * either don't composite only this buffer (preferred) to the + * external sink, or (less desirable) do not route the entire + * composition to the external sink. */ + GRALLOC_USAGE_PROTECTED = 0x00004000U, + + /* buffer may be used as a cursor */ + GRALLOC_USAGE_CURSOR = 0x00008000U, + + /* buffer will be used with the HW video encoder */ + GRALLOC_USAGE_HW_VIDEO_ENCODER = 0x00010000U, + /* buffer will be written by the HW camera pipeline */ + GRALLOC_USAGE_HW_CAMERA_WRITE = 0x00020000U, + /* buffer will be read by the HW camera pipeline */ + GRALLOC_USAGE_HW_CAMERA_READ = 0x00040000U, + /* buffer will be used as part of zero-shutter-lag queue */ + GRALLOC_USAGE_HW_CAMERA_ZSL = 0x00060000U, + /* mask for the camera access values */ + GRALLOC_USAGE_HW_CAMERA_MASK = 0x00060000U, + /* mask for the software usage bit-mask */ + GRALLOC_USAGE_HW_MASK = 0x00071F00U, + + /* buffer will be used as a RenderScript Allocation */ + GRALLOC_USAGE_RENDERSCRIPT = 0x00100000U, + + /* Set by the consumer to indicate to the producer that they may attach a + * buffer that they did not detach from the BufferQueue. Will be filtered + * out by GRALLOC_USAGE_ALLOC_MASK, so gralloc modules will not need to + * handle this flag. */ + GRALLOC_USAGE_FOREIGN_BUFFERS = 0x00200000U, + + /* buffer will be used as input to HW HEIC image encoder */ + GRALLOC_USAGE_HW_IMAGE_ENCODER = 0x08000000U, + + /* Mask of all flags which could be passed to a gralloc module for buffer + * allocation. Any flags not in this mask do not need to be handled by + * gralloc modules. */ + GRALLOC_USAGE_ALLOC_MASK = ~(GRALLOC_USAGE_FOREIGN_BUFFERS), + + /* implementation-specific private usage flags */ + GRALLOC_USAGE_PRIVATE_0 = 0x10000000U, + GRALLOC_USAGE_PRIVATE_1 = 0x20000000U, + GRALLOC_USAGE_PRIVATE_2 = 0x40000000U, + GRALLOC_USAGE_PRIVATE_3 = 0x80000000U, + GRALLOC_USAGE_PRIVATE_MASK = 0xF0000000U, +}; + +/*****************************************************************************/ + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +typedef struct gralloc_module_t { + struct hw_module_t common; + + /* + * (*registerBuffer)() must be called before a buffer_handle_t that has not + * been created with (*alloc_device_t::alloc)() can be used. + * + * This is intended to be used with buffer_handle_t's that have been + * received in this process through IPC. + * + * This function checks that the handle is indeed a valid one and prepares + * it for use with (*lock)() and (*unlock)(). + * + * It is not necessary to call (*registerBuffer)() on a handle created + * with (*alloc_device_t::alloc)(). + * + * returns an error if this buffer_handle_t is not valid. + */ + int (*registerBuffer)(struct gralloc_module_t const* module, + buffer_handle_t handle); + + /* + * (*unregisterBuffer)() is called once this handle is no longer needed in + * this process. After this call, it is an error to call (*lock)(), + * (*unlock)(), or (*registerBuffer)(). + * + * This function doesn't close or free the handle itself; this is done + * by other means, usually through libcutils's native_handle_close() and + * native_handle_free(). + * + * It is an error to call (*unregisterBuffer)() on a buffer that wasn't + * explicitly registered first. + */ + int (*unregisterBuffer)(struct gralloc_module_t const* module, + buffer_handle_t handle); + + /* + * The (*lock)() method is called before a buffer is accessed for the + * specified usage. This call may block, for instance if the h/w needs + * to finish rendering or if CPU caches need to be synchronized. + * + * The caller promises to modify only pixels in the area specified + * by (l,t,w,h). + * + * The content of the buffer outside of the specified area is NOT modified + * by this call. + * + * If usage specifies GRALLOC_USAGE_SW_*, vaddr is filled with the address + * of the buffer in virtual memory. + * + * Note calling (*lock)() on HAL_PIXEL_FORMAT_YCbCr_*_888 buffers will fail + * and return -EINVAL. These buffers must be locked with (*lock_ycbcr)() + * instead. + * + * THREADING CONSIDERATIONS: + * + * It is legal for several different threads to lock a buffer from + * read access, none of the threads are blocked. + * + * However, locking a buffer simultaneously for write or read/write is + * undefined, but: + * - shall not result in termination of the process + * - shall not block the caller + * It is acceptable to return an error or to leave the buffer's content + * into an indeterminate state. + * + * If the buffer was created with a usage mask incompatible with the + * requested usage flags here, -EINVAL is returned. + * + */ + + int (*lock)(struct gralloc_module_t const* module, + buffer_handle_t handle, int usage, + int l, int t, int w, int h, + void** vaddr); + + + /* + * The (*unlock)() method must be called after all changes to the buffer + * are completed. + */ + + int (*unlock)(struct gralloc_module_t const* module, + buffer_handle_t handle); + + + /* reserved for future use */ + int (*perform)(struct gralloc_module_t const* module, + int operation, ... ); + + /* + * The (*lock_ycbcr)() method is like the (*lock)() method, with the + * difference that it fills a struct ycbcr with a description of the buffer + * layout, and zeroes out the reserved fields. + * + * If the buffer format is not compatible with a flexible YUV format (e.g. + * the buffer layout cannot be represented with the ycbcr struct), it + * will return -EINVAL. + * + * This method must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888 + * if supported by the device, as well as with any other format that is + * requested by the multimedia codecs when they are configured with a + * flexible-YUV-compatible color-format with android native buffers. + * + * Note that this method may also be called on buffers of other formats, + * including non-YUV formats. + * + * Added in GRALLOC_MODULE_API_VERSION_0_2. + */ + + int (*lock_ycbcr)(struct gralloc_module_t const* module, + buffer_handle_t handle, int usage, + int l, int t, int w, int h, + struct android_ycbcr *ycbcr); + + /* + * The (*lockAsync)() method is like the (*lock)() method except + * that the buffer's sync fence object is passed into the lock + * call instead of requiring the caller to wait for completion. + * + * The gralloc implementation takes ownership of the fenceFd and + * is responsible for closing it when no longer needed. + * + * Added in GRALLOC_MODULE_API_VERSION_0_3. + */ + int (*lockAsync)(struct gralloc_module_t const* module, + buffer_handle_t handle, int usage, + int l, int t, int w, int h, + void** vaddr, int fenceFd); + + /* + * The (*unlockAsync)() method is like the (*unlock)() method + * except that a buffer sync fence object is returned from the + * lock call, representing the completion of any pending work + * performed by the gralloc implementation. + * + * The caller takes ownership of the fenceFd and is responsible + * for closing it when no longer needed. + * + * Added in GRALLOC_MODULE_API_VERSION_0_3. + */ + int (*unlockAsync)(struct gralloc_module_t const* module, + buffer_handle_t handle, int* fenceFd); + + /* + * The (*lockAsync_ycbcr)() method is like the (*lock_ycbcr)() + * method except that the buffer's sync fence object is passed + * into the lock call instead of requiring the caller to wait for + * completion. + * + * The gralloc implementation takes ownership of the fenceFd and + * is responsible for closing it when no longer needed. + * + * Added in GRALLOC_MODULE_API_VERSION_0_3. + */ + int (*lockAsync_ycbcr)(struct gralloc_module_t const* module, + buffer_handle_t handle, int usage, + int l, int t, int w, int h, + struct android_ycbcr *ycbcr, int fenceFd); + + /* getTransportSize(..., outNumFds, outNumInts) + * This function is mandatory on devices running IMapper2.1 or higher. + * + * Get the transport size of a buffer. An imported buffer handle is a raw + * buffer handle with the process-local runtime data appended. This + * function, for example, allows a caller to omit the process-local + * runtime data at the tail when serializing the imported buffer handle. + * + * Note that a client might or might not omit the process-local runtime + * data when sending an imported buffer handle. The mapper must support + * both cases on the receiving end. + */ + int32_t (*getTransportSize)( + struct gralloc_module_t const* module, buffer_handle_t handle, uint32_t *outNumFds, + uint32_t *outNumInts); + + /* validateBufferSize(..., w, h, format, usage, stride) + * This function is mandatory on devices running IMapper2.1 or higher. + * + * Validate that the buffer can be safely accessed by a caller who assumes + * the specified width, height, format, usage, and stride. This must at least validate + * that the buffer size is large enough. Validating the buffer against + * individual buffer attributes is optional. + */ + int32_t (*validateBufferSize)( + struct gralloc_module_t const* device, buffer_handle_t handle, + uint32_t w, uint32_t h, int32_t format, int usage, + uint32_t stride); + + /* reserved for future use */ + void* reserved_proc[1]; + +} gralloc_module_t; + +/*****************************************************************************/ + +/** + * Every device data structure must begin with hw_device_t + * followed by module specific public methods and attributes. + */ + +typedef struct alloc_device_t { + struct hw_device_t common; + + /* + * (*alloc)() Allocates a buffer in graphic memory with the requested + * parameters and returns a buffer_handle_t and the stride in pixels to + * allow the implementation to satisfy hardware constraints on the width + * of a pixmap (eg: it may have to be multiple of 8 pixels). + * The CALLER TAKES OWNERSHIP of the buffer_handle_t. + * + * If format is HAL_PIXEL_FORMAT_YCbCr_420_888, the returned stride must be + * 0, since the actual strides are available from the android_ycbcr + * structure. + * + * Returns 0 on success or -errno on error. + */ + + int (*alloc)(struct alloc_device_t* dev, + int w, int h, int format, int usage, + buffer_handle_t* handle, int* stride); + + /* + * (*free)() Frees a previously allocated buffer. + * Behavior is undefined if the buffer is still mapped in any process, + * but shall not result in termination of the program or security breaches + * (allowing a process to get access to another process' buffers). + * THIS FUNCTION TAKES OWNERSHIP of the buffer_handle_t which becomes + * invalid after the call. + * + * Returns 0 on success or -errno on error. + */ + int (*free)(struct alloc_device_t* dev, + buffer_handle_t handle); + + /* This hook is OPTIONAL. + * + * If non NULL it will be caused by SurfaceFlinger on dumpsys + */ + void (*dump)(struct alloc_device_t *dev, char *buff, int buff_len); + + void* reserved_proc[7]; +} alloc_device_t; + + +/** convenience API for opening and closing a supported device */ + +static inline int gralloc_open(const struct hw_module_t* module, + struct alloc_device_t** device) { + return module->methods->open(module, + GRALLOC_HARDWARE_GPU0, TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int gralloc_close(struct alloc_device_t* device) { + return device->common.close(&device->common); +} + +/** + * map_usage_to_memtrack should be called after allocating a gralloc buffer. + * + * @param usage - it is the flag used when alloc function is called. + * + * This function maps the gralloc usage flags to appropriate memtrack bucket. + * GrallocHAL implementers and users should make an additional ION_IOCTL_TAG + * call using the memtrack tag returned by this function. This will help the + * in-kernel memtack to categorize the memory allocated by different processes + * according to their usage. + * + */ +static inline const char* map_usage_to_memtrack(uint32_t usage) { + usage &= GRALLOC_USAGE_ALLOC_MASK; + + if ((usage & GRALLOC_USAGE_HW_CAMERA_WRITE) != 0) { + return "camera"; + } else if ((usage & GRALLOC_USAGE_HW_VIDEO_ENCODER) != 0 || + (usage & GRALLOC_USAGE_EXTERNAL_DISP) != 0) { + return "video"; + } else if ((usage & GRALLOC_USAGE_HW_RENDER) != 0 || + (usage & GRALLOC_USAGE_HW_TEXTURE) != 0) { + return "gl"; + } else if ((usage & GRALLOC_USAGE_HW_CAMERA_READ) != 0) { + return "camera"; + } else if ((usage & GRALLOC_USAGE_SW_READ_MASK) != 0 || + (usage & GRALLOC_USAGE_SW_WRITE_MASK) != 0) { + return "cpu"; + } + return "graphics"; +} + +__END_DECLS + +#endif // ANDROID_GRALLOC_INTERFACE_H diff --git a/include_all/hardware/gralloc1.h b/include_all/hardware/gralloc1.h new file mode 100644 index 00000000..c211029a --- /dev/null +++ b/include_all/hardware/gralloc1.h @@ -0,0 +1,1044 @@ +/* + * Copyright 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_GRALLOC1_H +#define ANDROID_HARDWARE_GRALLOC1_H + +#include <hardware/hardware.h> +#include <cutils/native_handle.h> + +__BEGIN_DECLS + +#define GRALLOC_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) +#define GRALLOC_HARDWARE_MODULE_ID "gralloc" + +/* + * Enums + */ + +typedef enum { + GRALLOC1_CAPABILITY_INVALID = 0, + + /* If this capability is supported, then the outBuffers parameter to + * allocate may be NULL, which instructs the device to report whether the + * given allocation is possible or not. */ + GRALLOC1_CAPABILITY_TEST_ALLOCATE = 1, + + /* If this capability is supported, then the implementation supports + * allocating buffers with more than one image layer. */ + GRALLOC1_CAPABILITY_LAYERED_BUFFERS = 2, + + /* If this capability is supported, then the implementation always closes + * and deletes a buffer handle whenever the last reference is removed. + * + * Supporting this capability is strongly recommended. It will become + * mandatory in future releases. */ + GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE = 3, + + GRALLOC1_LAST_CAPABILITY = 3, +} gralloc1_capability_t; + +typedef enum { + GRALLOC1_CONSUMER_USAGE_NONE = 0, + GRALLOC1_CONSUMER_USAGE_CPU_READ_NEVER = 0, + /* 1ULL << 0 */ + GRALLOC1_CONSUMER_USAGE_CPU_READ = 1ULL << 1, + GRALLOC1_CONSUMER_USAGE_CPU_READ_OFTEN = 1ULL << 2 | + GRALLOC1_CONSUMER_USAGE_CPU_READ, + /* 1ULL << 3 */ + /* 1ULL << 4 */ + /* 1ULL << 5 */ + /* 1ULL << 6 */ + /* 1ULL << 7 */ + GRALLOC1_CONSUMER_USAGE_GPU_TEXTURE = 1ULL << 8, + /* 1ULL << 9 */ + /* 1ULL << 10 */ + GRALLOC1_CONSUMER_USAGE_HWCOMPOSER = 1ULL << 11, + GRALLOC1_CONSUMER_USAGE_CLIENT_TARGET = 1ULL << 12, + /* 1ULL << 13 */ + /* 1ULL << 14 */ + GRALLOC1_CONSUMER_USAGE_CURSOR = 1ULL << 15, + GRALLOC1_CONSUMER_USAGE_VIDEO_ENCODER = 1ULL << 16, + /* 1ULL << 17 */ + GRALLOC1_CONSUMER_USAGE_CAMERA = 1ULL << 18, + /* 1ULL << 19 */ + GRALLOC1_CONSUMER_USAGE_RENDERSCRIPT = 1ULL << 20, + + /* Indicates that the consumer may attach buffers to their end of the + * BufferQueue, which means that the producer may never have seen a given + * dequeued buffer before. May be ignored by the gralloc device. */ + GRALLOC1_CONSUMER_USAGE_FOREIGN_BUFFERS = 1ULL << 21, + + /* 1ULL << 22 */ + GRALLOC1_CONSUMER_USAGE_GPU_DATA_BUFFER = 1ULL << 23, + /* 1ULL << 24 */ + /* 1ULL << 25 */ + /* 1ULL << 26 */ + /* 1ULL << 27 */ + + /* Bits reserved for implementation-specific usage flags */ + GRALLOC1_CONSUMER_USAGE_PRIVATE_0 = 1ULL << 28, + GRALLOC1_CONSUMER_USAGE_PRIVATE_1 = 1ULL << 29, + GRALLOC1_CONSUMER_USAGE_PRIVATE_2 = 1ULL << 30, + GRALLOC1_CONSUMER_USAGE_PRIVATE_3 = 1ULL << 31, + + /* 1ULL << 32 */ + /* 1ULL << 33 */ + /* 1ULL << 34 */ + /* 1ULL << 35 */ + /* 1ULL << 36 */ + /* 1ULL << 37 */ + /* 1ULL << 38 */ + /* 1ULL << 39 */ + /* 1ULL << 40 */ + /* 1ULL << 41 */ + /* 1ULL << 42 */ + /* 1ULL << 43 */ + /* 1ULL << 44 */ + /* 1ULL << 45 */ + /* 1ULL << 46 */ + /* 1ULL << 47 */ + + /* Bits reserved for implementation-specific usage flags */ + GRALLOC1_CONSUMER_USAGE_PRIVATE_19 = 1ULL << 48, + GRALLOC1_CONSUMER_USAGE_PRIVATE_18 = 1ULL << 49, + GRALLOC1_CONSUMER_USAGE_PRIVATE_17 = 1ULL << 50, + GRALLOC1_CONSUMER_USAGE_PRIVATE_16 = 1ULL << 51, + GRALLOC1_CONSUMER_USAGE_PRIVATE_15 = 1ULL << 52, + GRALLOC1_CONSUMER_USAGE_PRIVATE_14 = 1ULL << 53, + GRALLOC1_CONSUMER_USAGE_PRIVATE_13 = 1ULL << 54, + GRALLOC1_CONSUMER_USAGE_PRIVATE_12 = 1ULL << 55, + GRALLOC1_CONSUMER_USAGE_PRIVATE_11 = 1ULL << 56, + GRALLOC1_CONSUMER_USAGE_PRIVATE_10 = 1ULL << 57, + GRALLOC1_CONSUMER_USAGE_PRIVATE_9 = 1ULL << 58, + GRALLOC1_CONSUMER_USAGE_PRIVATE_8 = 1ULL << 59, + GRALLOC1_CONSUMER_USAGE_PRIVATE_7 = 1ULL << 60, + GRALLOC1_CONSUMER_USAGE_PRIVATE_6 = 1ULL << 61, + GRALLOC1_CONSUMER_USAGE_PRIVATE_5 = 1ULL << 62, + GRALLOC1_CONSUMER_USAGE_PRIVATE_4 = 1ULL << 63, +} gralloc1_consumer_usage_t; + +typedef enum { + GRALLOC1_FUNCTION_INVALID = 0, + GRALLOC1_FUNCTION_DUMP = 1, + GRALLOC1_FUNCTION_CREATE_DESCRIPTOR = 2, + GRALLOC1_FUNCTION_DESTROY_DESCRIPTOR = 3, + GRALLOC1_FUNCTION_SET_CONSUMER_USAGE = 4, + GRALLOC1_FUNCTION_SET_DIMENSIONS = 5, + GRALLOC1_FUNCTION_SET_FORMAT = 6, + GRALLOC1_FUNCTION_SET_PRODUCER_USAGE = 7, + GRALLOC1_FUNCTION_GET_BACKING_STORE = 8, + GRALLOC1_FUNCTION_GET_CONSUMER_USAGE = 9, + GRALLOC1_FUNCTION_GET_DIMENSIONS = 10, + GRALLOC1_FUNCTION_GET_FORMAT = 11, + GRALLOC1_FUNCTION_GET_PRODUCER_USAGE = 12, + GRALLOC1_FUNCTION_GET_STRIDE = 13, + GRALLOC1_FUNCTION_ALLOCATE = 14, + GRALLOC1_FUNCTION_RETAIN = 15, + GRALLOC1_FUNCTION_RELEASE = 16, + GRALLOC1_FUNCTION_GET_NUM_FLEX_PLANES = 17, + GRALLOC1_FUNCTION_LOCK = 18, + GRALLOC1_FUNCTION_LOCK_FLEX = 19, + GRALLOC1_FUNCTION_UNLOCK = 20, + GRALLOC1_FUNCTION_SET_LAYER_COUNT = 21, + GRALLOC1_FUNCTION_GET_LAYER_COUNT = 22, + GRALLOC1_FUNCTION_VALIDATE_BUFFER_SIZE = 23, + GRALLOC1_FUNCTION_GET_TRANSPORT_SIZE = 24, + GRALLOC1_FUNCTION_IMPORT_BUFFER = 25, + GRALLOC1_LAST_FUNCTION = 25, +} gralloc1_function_descriptor_t; + +typedef enum { + GRALLOC1_ERROR_NONE = 0, + GRALLOC1_ERROR_BAD_DESCRIPTOR = 1, + GRALLOC1_ERROR_BAD_HANDLE = 2, + GRALLOC1_ERROR_BAD_VALUE = 3, + GRALLOC1_ERROR_NOT_SHARED = 4, + GRALLOC1_ERROR_NO_RESOURCES = 5, + GRALLOC1_ERROR_UNDEFINED = 6, + GRALLOC1_ERROR_UNSUPPORTED = 7, +} gralloc1_error_t; + +typedef enum { + GRALLOC1_PRODUCER_USAGE_NONE = 0, + GRALLOC1_PRODUCER_USAGE_CPU_WRITE_NEVER = 0, + /* 1ULL << 0 */ + GRALLOC1_PRODUCER_USAGE_CPU_READ = 1ULL << 1, + GRALLOC1_PRODUCER_USAGE_CPU_READ_OFTEN = 1ULL << 2 | + GRALLOC1_PRODUCER_USAGE_CPU_READ, + /* 1ULL << 3 */ + /* 1ULL << 4 */ + GRALLOC1_PRODUCER_USAGE_CPU_WRITE = 1ULL << 5, + GRALLOC1_PRODUCER_USAGE_CPU_WRITE_OFTEN = 1ULL << 6 | + GRALLOC1_PRODUCER_USAGE_CPU_WRITE, + /* 1ULL << 7 */ + /* 1ULL << 8 */ + GRALLOC1_PRODUCER_USAGE_GPU_RENDER_TARGET = 1ULL << 9, + /* 1ULL << 10 */ + /* 1ULL << 11 */ + /* 1ULL << 12 */ + /* 1ULL << 13 */ + + /* The consumer must have a hardware-protected path to an external display + * sink for this buffer. If a hardware-protected path is not available, then + * do not attempt to display this buffer. */ + GRALLOC1_PRODUCER_USAGE_PROTECTED = 1ULL << 14, + + /* 1ULL << 15 */ + /* 1ULL << 16 */ + GRALLOC1_PRODUCER_USAGE_CAMERA = 1ULL << 17, + /* 1ULL << 18 */ + /* 1ULL << 19 */ + /* 1ULL << 20 */ + /* 1ULL << 21 */ + GRALLOC1_PRODUCER_USAGE_VIDEO_DECODER = 1ULL << 22, + GRALLOC1_PRODUCER_USAGE_SENSOR_DIRECT_DATA = 1ULL << 23, + /* 1ULL << 24 */ + /* 1ULL << 25 */ + /* 1ULL << 26 */ + /* 1ULL << 27 */ + + /* Bits reserved for implementation-specific usage flags */ + GRALLOC1_PRODUCER_USAGE_PRIVATE_0 = 1ULL << 28, + GRALLOC1_PRODUCER_USAGE_PRIVATE_1 = 1ULL << 29, + GRALLOC1_PRODUCER_USAGE_PRIVATE_2 = 1ULL << 30, + GRALLOC1_PRODUCER_USAGE_PRIVATE_3 = 1ULL << 31, + + /* 1ULL << 32 */ + /* 1ULL << 33 */ + /* 1ULL << 34 */ + /* 1ULL << 35 */ + /* 1ULL << 36 */ + /* 1ULL << 37 */ + /* 1ULL << 38 */ + /* 1ULL << 39 */ + /* 1ULL << 40 */ + /* 1ULL << 41 */ + /* 1ULL << 42 */ + /* 1ULL << 43 */ + /* 1ULL << 44 */ + /* 1ULL << 45 */ + /* 1ULL << 46 */ + /* 1ULL << 47 */ + + /* Bits reserved for implementation-specific usage flags */ + GRALLOC1_PRODUCER_USAGE_PRIVATE_19 = 1ULL << 48, + GRALLOC1_PRODUCER_USAGE_PRIVATE_18 = 1ULL << 49, + GRALLOC1_PRODUCER_USAGE_PRIVATE_17 = 1ULL << 50, + GRALLOC1_PRODUCER_USAGE_PRIVATE_16 = 1ULL << 51, + GRALLOC1_PRODUCER_USAGE_PRIVATE_15 = 1ULL << 52, + GRALLOC1_PRODUCER_USAGE_PRIVATE_14 = 1ULL << 53, + GRALLOC1_PRODUCER_USAGE_PRIVATE_13 = 1ULL << 54, + GRALLOC1_PRODUCER_USAGE_PRIVATE_12 = 1ULL << 55, + GRALLOC1_PRODUCER_USAGE_PRIVATE_11 = 1ULL << 56, + GRALLOC1_PRODUCER_USAGE_PRIVATE_10 = 1ULL << 57, + GRALLOC1_PRODUCER_USAGE_PRIVATE_9 = 1ULL << 58, + GRALLOC1_PRODUCER_USAGE_PRIVATE_8 = 1ULL << 59, + GRALLOC1_PRODUCER_USAGE_PRIVATE_7 = 1ULL << 60, + GRALLOC1_PRODUCER_USAGE_PRIVATE_6 = 1ULL << 61, + GRALLOC1_PRODUCER_USAGE_PRIVATE_5 = 1ULL << 62, + GRALLOC1_PRODUCER_USAGE_PRIVATE_4 = 1ULL << 63, +} gralloc1_producer_usage_t; + +/* + * Typedefs + */ + +typedef void (*gralloc1_function_pointer_t)(); + +typedef uint64_t gralloc1_backing_store_t; +typedef uint64_t gralloc1_buffer_descriptor_t; + +/* + * Device Struct + */ + +typedef struct gralloc1_device { + /* Must be the first member of this struct, since a pointer to this struct + * will be generated by casting from a hw_device_t* */ + struct hw_device_t common; + + /* getCapabilities(..., outCount, outCapabilities) + * + * Provides a list of capabilities (described in the definition of + * gralloc1_capability_t above) supported by this device. This list must not + * change after the device has been loaded. + * + * Parameters: + * outCount - if outCapabilities was NULL, the number of capabilities + * which would have been returned; if outCapabilities was not NULL, + * the number of capabilities returned, which must not exceed the + * value stored in outCount prior to the call + * outCapabilities - a list of capabilities supported by this device; may + * be NULL, in which case this function must write into outCount the + * number of capabilities which would have been written into + * outCapabilities + */ + void (*getCapabilities)(struct gralloc1_device* device, uint32_t* outCount, + int32_t* /*gralloc1_capability_t*/ outCapabilities); + + /* getFunction(..., descriptor) + * + * Returns a function pointer which implements the requested description. + * + * Parameters: + * descriptor - the function to return + * + * Returns either a function pointer implementing the requested descriptor + * or NULL if the described function is not supported by this device. + */ + gralloc1_function_pointer_t (*getFunction)(struct gralloc1_device* device, + int32_t /*gralloc1_function_descriptor_t*/ descriptor); +} gralloc1_device_t; + +static inline int gralloc1_open(const struct hw_module_t* module, + gralloc1_device_t** device) { + return module->methods->open(module, GRALLOC_HARDWARE_MODULE_ID, + TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int gralloc1_close(gralloc1_device_t* device) { + return device->common.close(&device->common); +} + +/* dump(..., outSize, outBuffer) + * Function descriptor: GRALLOC1_FUNCTION_DUMP + * Must be provided by all gralloc1 devices + * + * Retrieves implementation-defined debug information, which will be displayed + * during, for example, `dumpsys SurfaceFlinger`. + * + * If called with outBuffer == NULL, the device should store a copy of the + * desired output and return its length in bytes in outSize. If the device + * already has a stored copy, that copy should be purged and replaced with a + * fresh copy. + * + * If called with outBuffer != NULL, the device should copy its stored version + * of the output into outBuffer and store how many bytes of data it copied into + * outSize. Prior to this call, the client will have populated outSize with the + * maximum number of bytes outBuffer can hold. The device must not write more + * than this amount into outBuffer. If the device does not currently have a + * stored copy, then it should return 0 in outSize. + * + * Any data written into outBuffer need not be null-terminated. + * + * Parameters: + * outSize - if outBuffer was NULL, the number of bytes needed to copy the + * device's stored output; if outBuffer was not NULL, the number of bytes + * written into it, which must not exceed the value stored in outSize + * prior to the call; pointer will be non-NULL + * outBuffer - the buffer to write the dump output into; may be NULL as + * described above; data written into this buffer need not be + * null-terminated + */ +typedef void (*GRALLOC1_PFN_DUMP)(gralloc1_device_t* device, uint32_t* outSize, + char* outBuffer); + +/* + * Buffer descriptor lifecycle functions + * + * All of these functions take as their first parameter a device pointer, so + * this parameter is omitted from the described parameter lists. + */ + +/* createDescriptor(..., outDescriptor) + * Function descriptor: GRALLOC1_FUNCTION_CREATE_DESCRIPTOR + * Must be provided by all gralloc1 devices + * + * Creates a new, empty buffer descriptor. + * + * Parameters: + * outDescriptor - the new buffer descriptor + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_NO_RESOURCES - no more descriptors can currently be created + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_CREATE_DESCRIPTOR)( + gralloc1_device_t* device, gralloc1_buffer_descriptor_t* outDescriptor); + +/* destroyDescriptor(..., descriptor) + * Function descriptor: GRALLOC1_FUNCTION_DESTROY_DESCRIPTOR + * Must be provided by all gralloc1 devices + * + * Destroys an existing buffer descriptor. + * + * Parameters: + * descriptor - the buffer descriptor to destroy + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_DESCRIPTOR - descriptor does not refer to a valid + * buffer descriptor + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_DESTROY_DESCRIPTOR)( + gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor); + +/* + * Buffer descriptor modification functions + * + * All of these functions take as their first two parameters a device pointer + * and a buffer descriptor, so these parameters are omitted from the described + * parameter lists. + */ + +/* setConsumerUsage(..., usage) + * Function descriptor: GRALLOC1_FUNCTION_SET_CONSUMER_USAGE + * Must be provided by all gralloc1 devices + * + * Sets the desired consumer usage flags of the buffer. + * + * Valid usage flags can be found in the definition of gralloc1_consumer_usage_t + * above. + * + * Parameters: + * usage - the desired consumer usage flags + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid + * GRALLOC1_ERROR_BAD_VALUE - an invalid usage flag was passed in + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_CONSUMER_USAGE)( + gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, + uint64_t /*gralloc1_consumer_usage_t*/ usage); + +/* setDimensions(..., width, height) + * Function descriptor: GRALLOC1_FUNCTION_SET_DIMENSIONS + * Must be provided by all gralloc1 devices + * + * Sets the desired width and height of the buffer in pixels. + * + * The width specifies how many columns of pixels should be in the allocated + * buffer, but does not necessarily represent the offset in columns between the + * same column in adjacent rows. If this offset is required, consult getStride + * below. + * + * The height specifies how many rows of pixels should be in the allocated + * buffer. + * + * Parameters: + * width - the desired width in pixels + * height - the desired height in pixels + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_DIMENSIONS)( + gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, + uint32_t width, uint32_t height); + +/* setFormat(..., format) + * Function descriptor: GRALLOC1_FUNCTION_SET_FORMAT + * Must be provided by all gralloc1 devices + * + * Sets the desired format of the buffer. + * + * The valid formats can be found in <system/graphics.h>. + * + * Parameters: + * format - the desired format + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid + * GRALLOC1_ERROR_BAD_VALUE - format is invalid + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_FORMAT)( + gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, + int32_t /*android_pixel_format_t*/ format); + +/* setLayerCount(..., layerCount) + * Function descriptor: GRALLOC1_FUNCTION_SET_LAYER_COUNT + * Must be provided by all gralloc1 devices that provide the + * GRALLOC1_CAPABILITY_LAYERED_BUFFERS capability. + * + * Sets the number of layers in the buffer. + * + * A buffer with multiple layers may be used as the backing store of an array + * texture. All layers of a buffer share the same characteristics (e.g., + * dimensions, format, usage). Devices that do not support + * GRALLOC1_CAPABILITY_LAYERED_BUFFERS must allocate only buffers with a single + * layer. + * + * Parameters: + * layerCount - the desired number of layers, must be non-zero + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid + * GRALLOC1_ERROR_BAD_VALUE - the layer count is invalid + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_LAYER_COUNT)( + gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, + uint32_t layerCount); + +/* setProducerUsage(..., usage) + * Function descriptor: GRALLOC1_FUNCTION_SET_PRODUCER_USAGE + * Must be provided by all gralloc1 devices + * + * Sets the desired producer usage flags of the buffer. + * + * Valid usage flags can be found in the definition of gralloc1_producer_usage_t + * above. + * + * Parameters: + * usage - the desired producer usage flags + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid + * GRALLOC1_ERROR_BAD_VALUE - an invalid usage flag was passed in + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_PRODUCER_USAGE)( + gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, + uint64_t /*gralloc1_producer_usage_t*/ usage); + +/* + * Buffer handle query functions + * + * All of these functions take as their first two parameters a device pointer + * and a buffer handle, so these parameters are omitted from the described + * parameter lists. + * + * [1] Currently many of these functions may return GRALLOC1_ERROR_UNSUPPORTED, + * which means that the device is not able to retrieve the requested information + * from the buffer. This is necessary to enable a smooth transition from earlier + * versions of the gralloc HAL, but gralloc1 implementers are strongly + * discouraged from returning this value, as future versions of the platform + * code will require all of these functions to succeed given a valid handle. + */ + +/* getBackingStore(..., outStore) + * Function descriptor: GRALLOC1_FUNCTION_GET_BACKING_STORE + * Must be provided by all gralloc1 devices + * + * Gets a value that uniquely identifies the backing store of the given buffer. + * + * Buffers which share a backing store should return the same value from this + * function. If the buffer is present in more than one process, the backing + * store value for that buffer is not required to be the same in every process. + * + * Parameters: + * outStore - the backing store identifier for this buffer + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the + * backing store identifier from the buffer; see note [1] in this + * section's header for more information + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_BACKING_STORE)( + gralloc1_device_t* device, buffer_handle_t buffer, + gralloc1_backing_store_t* outStore); + +/* getConsumerUsage(..., outUsage) + * Function descriptor: GRALLOC1_FUNCTION_GET_CONSUMER_USAGE + * Must be provided by all gralloc1 devices + * + * Gets the consumer usage flags which were used to allocate this buffer. + * + * Usage flags can be found in the definition of gralloc1_consumer_usage_t above + * + * Parameters: + * outUsage - the consumer usage flags used to allocate this buffer; must be + * non-NULL + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the + * dimensions from the buffer; see note [1] in this section's header for + * more information + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_CONSUMER_USAGE)( + gralloc1_device_t* device, buffer_handle_t buffer, + uint64_t* /*gralloc1_consumer_usage_t*/ outUsage); + +/* getDimensions(..., outWidth, outHeight) + * Function descriptor: GRALLOC1_FUNCTION_GET_DIMENSIONS + * Must be provided by all gralloc1 devices + * + * Gets the width and height of the buffer in pixels. + * + * See setDimensions for more information about these values. + * + * Parameters: + * outWidth - the width of the buffer in pixels, must be non-NULL + * outHeight - the height of the buffer in pixels, must be non-NULL + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the + * dimensions from the buffer; see note [1] in this section's header for + * more information + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_DIMENSIONS)( + gralloc1_device_t* device, buffer_handle_t buffer, uint32_t* outWidth, + uint32_t* outHeight); + +/* getFormat(..., outFormat) + * Function descriptor: GRALLOC1_FUNCTION_GET_FORMAT + * Must be provided by all gralloc1 devices + * + * Gets the format of the buffer. + * + * The valid formats can be found in the HAL_PIXEL_FORMAT_* enum in + * system/graphics.h. + * + * Parameters: + * outFormat - the format of the buffer; must be non-NULL + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the format + * from the buffer; see note [1] in this section's header for more + * information + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_FORMAT)( + gralloc1_device_t* device, buffer_handle_t descriptor, + int32_t* outFormat); + +/* getLayerCount(..., outLayerCount) + * Function descriptor: GRALLOC1_FUNCTION_GET_LAYER_COUNT + * Must be provided by all gralloc1 devices that provide the + * GRALLOC1_CAPABILITY_LAYERED_BUFFERS capability. + * + * Gets the number of layers of the buffer. + * + * See setLayerCount for more information about this value. + * + * Parameters: + * outLayerCount - the number of layers in the image, must be non-NULL + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the + * layer count from the buffer; see note [1] in this section's header for + * more information + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_LAYER_COUNT)( + gralloc1_device_t* device, buffer_handle_t buffer, + uint32_t* outLayerCount); + +/* getProducerUsage(..., outUsage) + * Function descriptor: GRALLOC1_FUNCTION_GET_PRODUCER_USAGE + * Must be provided by all gralloc1 devices + * + * Gets the producer usage flags which were used to allocate this buffer. + * + * Usage flags can be found in the definition of gralloc1_producer_usage_t above + * + * Parameters: + * outUsage - the producer usage flags used to allocate this buffer; must be + * non-NULL + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the usage + * from the buffer; see note [1] in this section's header for more + * information + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_PRODUCER_USAGE)( + gralloc1_device_t* device, buffer_handle_t buffer, + uint64_t* /*gralloc1_producer_usage_t*/ outUsage); + +/* getStride(..., outStride) + * Function descriptor: GRALLOC1_FUNCTION_GET_STRIDE + * Must be provided by all gralloc1 devices + * + * Gets the stride of the buffer in pixels. + * + * The stride is the offset in pixel-sized elements between the same column in + * two adjacent rows of pixels. This may not be equal to the width of the + * buffer. + * + * Parameters: + * outStride - the stride in pixels; must be non-NULL + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_UNDEFINED - the notion of a stride is not meaningful for + * this format + * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the stride + * from the descriptor; see note [1] in this section's header for more + * information + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_STRIDE)( + gralloc1_device_t* device, buffer_handle_t buffer, uint32_t* outStride); + +/* getTransportSize(..., outNumFds, outNumInts) + * Function descriptor: GRALLOC1_FUNCTION_GET_TRANSPORT_SIZE + * + * Get the transport size of a buffer. An imported buffer handle is a raw + * buffer handle with the process-local runtime data appended. This + * function, for example, allows a caller to omit the process-local + * runtime data at the tail when serializing the imported buffer handle. + * + * Note that a client might or might not omit the process-local runtime + * data when sending an imported buffer handle. The mapper must support + * both cases on the receiving end. + * + * Parameters: + * outNumFds - the number of file descriptors needed for transport + * outNumInts - the number of integers needed for transport + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the numFds + * and numInts; see note [1] in this section's header for more information + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_TRANSPORT_SIZE)( + gralloc1_device_t* device, buffer_handle_t buffer, uint32_t *outNumFds, + uint32_t *outNumInts); + +typedef struct gralloc1_buffer_descriptor_info { + uint32_t width; + uint32_t height; + uint32_t layerCount; + int32_t /*android_pixel_format_t*/ format; + uint64_t producerUsage; + uint64_t consumerUsage; +} gralloc1_buffer_descriptor_info_t; + +/* validateBufferSize(..., ) + * Function descriptor: GRALLOC1_FUNCTION_VALIDATE_BUFFER_SIZE + * + * Validate that the buffer can be safely accessed by a caller who assumes + * the specified descriptorInfo and stride. This must at least validate + * that the buffer size is large enough. Validating the buffer against + * individual buffer attributes is optional. + * + * Parameters: + * descriptor - specifies the attributes of the buffer + * stride - the buffer stride returned by IAllocator::allocate + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_BAD_VALUE - when buffer cannot be safely accessed + * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to validate the buffer + * size; see note [1] in this section's header for more information + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_VALIDATE_BUFFER_SIZE)( + gralloc1_device_t* device, buffer_handle_t buffer, + const gralloc1_buffer_descriptor_info_t* descriptorInfo, + uint32_t stride); + +/* + * Buffer management functions + */ + +/* allocate(..., numDescriptors, descriptors, outBuffers) + * Function descriptor: GRALLOC1_FUNCTION_ALLOCATE + * Must be provided by all gralloc1 devices + * + * Attempts to allocate a number of buffers sharing a backing store. + * + * Each buffer will correspond to one of the descriptors passed into the + * function. If the device is unable to share the backing store between the + * buffers, it should attempt to allocate the buffers with different backing + * stores and return GRALLOC1_ERROR_NOT_SHARED if it is successful. + * + * If this call is successful, the client is responsible for freeing the + * buffer_handle_t using release() when it is finished with the buffer. It is + * not necessary to call retain() on the returned buffers, as they must have a + * reference added by the device before returning. + * + * If GRALLOC1_CAPABILITY_TEST_ALLOCATE is supported by this device, outBuffers + * may be NULL. In this case, the device must not attempt to allocate any + * buffers, but instead must return either GRALLOC1_ERROR_NONE if such an + * allocation is possible (ignoring potential resource contention which might + * lead to a GRALLOC1_ERROR_NO_RESOURCES error), GRALLOC1_ERROR_NOT_SHARED if + * the buffers can be allocated, but cannot share a backing store, or + * GRALLOC1_ERROR_UNSUPPORTED if one or more of the descriptors can never be + * allocated by the device. + * + * Parameters: + * numDescriptors - the number of buffer descriptors, which must also be equal + * to the size of the outBuffers array + * descriptors - the buffer descriptors to attempt to allocate + * outBuffers - the allocated buffers; must be non-NULL unless the device + * supports GRALLOC1_CAPABILITY_TEST_ALLOCATE (see above), and must not be + * modified by the device if allocation is unsuccessful + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_DESCRIPTOR - one of the descriptors does not refer to a + * valid buffer descriptor + * GRALLOC1_ERROR_NOT_SHARED - allocation was successful, but required more + * than one backing store to satisfy all of the buffer descriptors + * GRALLOC1_ERROR_NO_RESOURCES - allocation failed because one or more of the + * backing stores could not be created at this time (but this allocation + * might succeed at a future time) + * GRALLOC1_ERROR_UNSUPPORTED - one or more of the descriptors can never be + * satisfied by the device + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_ALLOCATE)( + gralloc1_device_t* device, uint32_t numDescriptors, + const gralloc1_buffer_descriptor_t* descriptors, + buffer_handle_t* outBuffers); + +/* importBuffer(..., rawHandle, outBuffer); + * Function descriptor: GRALLOC1_FUNCTION_IMPORT_BUFFER + * This function is optional for all gralloc1 devices. + * When supported, GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE must also be + * supported. + * + * Explictly imports a buffer into a proccess. + * + * This function can be called in place of retain when a raw buffer handle is + * received by a remote process. Import producess a import handle that can + * be used to access the underlying graphic buffer. The new import handle has a + * ref count of 1. + * + * This function must at least validate the raw handle before creating the + * imported handle. It must also support importing the same raw handle + * multiple times to create multiple imported handles. The imported handle + * must be considered valid everywhere in the process. + * + * Parameters: + * rawHandle - the raw buffer handle to import + * outBuffer - a handle to the newly imported buffer + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_NO_RESOURCES - it is not possible to add a import to this + * buffer at this time + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_IMPORT_BUFFER)( + gralloc1_device_t* device, const buffer_handle_t rawHandle, + buffer_handle_t* outBuffer); + +/* retain(..., buffer) + * Function descriptor: GRALLOC1_FUNCTION_RETAIN + * Must be provided by all gralloc1 devices + * + * Adds a reference to the given buffer. + * + * This function must be called when a buffer_handle_t is received from a remote + * process to prevent the buffer's data from being freed when the remote process + * releases the buffer. It may also be called to increase the reference count if + * two components in the same process want to interact with the buffer + * independently. + * + * Parameters: + * buffer - the buffer to which a reference should be added + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_NO_RESOURCES - it is not possible to add a reference to this + * buffer at this time + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RETAIN)( + gralloc1_device_t* device, buffer_handle_t buffer); + +/* release(..., buffer) + * Function descriptor: GRALLOC1_FUNCTION_RELEASE + * Must be provided by all gralloc1 devices + * + * Removes a reference from the given buffer. + * + * If no references remain, the buffer should be freed. When the last buffer + * referring to a particular backing store is freed, that backing store should + * also be freed. + * + * When GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE is supported, + * native_handle_close and native_handle_delete must always be called by the + * implementation whenever the last reference is removed. Otherwise, a call + * to release() will be followed by native_handle_close and native_handle_delete + * by the caller when the buffer is not allocated locally through allocate(). + * + * Parameters: + * buffer - the buffer from which a reference should be removed + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RELEASE)( + gralloc1_device_t* device, buffer_handle_t buffer); + +/* + * Buffer access functions + * + * All of these functions take as their first parameter a device pointer, so + * this parameter is omitted from the described parameter lists. + */ + +typedef struct gralloc1_rect { + int32_t left; + int32_t top; + int32_t width; + int32_t height; +} gralloc1_rect_t; + +/* getNumFlexPlanes(..., buffer, outNumPlanes) + * Function descriptor: GRALLOC1_FUNCTION_GET_NUM_FLEX_PLANES + * Must be provided by all gralloc1 devices + * + * Returns the number of flex layout planes which are needed to represent the + * given buffer. This may be used to efficiently allocate only as many plane + * structures as necessary before calling into lockFlex. + * + * If the given buffer cannot be locked as a flex format, this function may + * return GRALLOC1_ERROR_UNSUPPORTED (as lockFlex would). + * + * Parameters: + * buffer - the buffers for which the number of planes should be queried + * outNumPlanes - the number of flex planes required to describe the given + * buffer; must be non-NULL + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_UNSUPPORTED - the buffer's format cannot be represented in a + * flex layout + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_NUM_FLEX_PLANES)( + gralloc1_device_t* device, buffer_handle_t buffer, + uint32_t* outNumPlanes); + +/* lock(..., buffer, producerUsage, consumerUsage, accessRegion, outData, + * acquireFence) + * Function descriptor: GRALLOC1_FUNCTION_LOCK + * Must be provided by all gralloc1 devices + * + * Locks the given buffer for the specified CPU usage. + * + * Exactly one of producerUsage and consumerUsage must be *_USAGE_NONE. The + * usage which is not *_USAGE_NONE must be one of the *_USAGE_CPU_* values, as + * applicable. Locking a buffer for a non-CPU usage is not supported. + * + * Locking the same buffer simultaneously from multiple threads is permitted, + * but if any of the threads attempt to lock the buffer for writing, the + * behavior is undefined, except that it must not cause process termination or + * block the client indefinitely. Leaving the buffer content in an indeterminate + * state or returning an error are both acceptable. + * + * The client must not modify the content of the buffer outside of accessRegion, + * and the device need not guarantee that content outside of accessRegion is + * valid for reading. The result of reading or writing outside of accessRegion + * is undefined, except that it must not cause process termination. + * + * outData must be a non-NULL pointer, the contents of which which will be + * filled with a pointer to the locked buffer memory. This address will + * represent the top-left corner of the entire buffer, even if accessRegion does + * not begin at the top-left corner. + * + * acquireFence is a file descriptor referring to a acquire sync fence object, + * which will be signaled when it is safe for the device to access the contents + * of the buffer (prior to locking). If it is already safe to access the buffer + * contents, -1 may be passed instead. + * + * Parameters: + * buffer - the buffer to lock + * producerUsage - the producer usage flags to request; either this or + * consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a + * CPU usage + * consumerUsage - the consumer usage flags to request; either this or + * producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a + * CPU usage + * accessRegion - the portion of the buffer that the client intends to access; + * must be non-NULL + * outData - will be filled with a CPU-accessible pointer to the buffer data; + * must be non-NULL + * acquireFence - a sync fence file descriptor as described above + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and + * consumerUsage were GRALLOC1_*_USAGE_NONE, or the usage which was not + * *_USAGE_NONE was not a CPU usage + * GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but + * locking may succeed at a future time + * GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given + * usage, and any future attempts at locking will also fail + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK)( + gralloc1_device_t* device, buffer_handle_t buffer, + uint64_t /*gralloc1_producer_usage_t*/ producerUsage, + uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage, + const gralloc1_rect_t* accessRegion, void** outData, + int32_t acquireFence); + +/* lockFlex(..., buffer, producerUsage, consumerUsage, accessRegion, + * outFlexLayout, outAcquireFence) + * Function descriptor: GRALLOC1_FUNCTION_LOCK_FLEX + * Must be provided by all gralloc1 devices + * + * This is largely the same as lock(), except that instead of returning a + * pointer directly to the buffer data, it returns an android_flex_layout + * struct describing how to access the data planes. + * + * This function must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888 if + * supported by the device, as well as with any other formats requested by + * multimedia codecs when they are configured with a flexible-YUV-compatible + * color format. + * + * This function may also be called on buffers of other formats, including + * non-YUV formats, but if the buffer format is not compatible with a flexible + * representation, it may return GRALLOC1_ERROR_UNSUPPORTED. + * + * Parameters: + * buffer - the buffer to lock + * producerUsage - the producer usage flags to request; either this or + * consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a + * CPU usage + * consumerUsage - the consumer usage flags to request; either this or + * producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a + * CPU usage + * accessRegion - the portion of the buffer that the client intends to access; + * must be non-NULL + * outFlexLayout - will be filled with the description of the planes in the + * buffer + * acquireFence - a sync fence file descriptor as described in lock() + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + * GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and + * consumerUsage were *_USAGE_NONE, or the usage which was not + * *_USAGE_NONE was not a CPU usage + * GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but + * locking may succeed at a future time + * GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given + * usage, and any future attempts at locking will also fail + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK_FLEX)( + gralloc1_device_t* device, buffer_handle_t buffer, + uint64_t /*gralloc1_producer_usage_t*/ producerUsage, + uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage, + const gralloc1_rect_t* accessRegion, + struct android_flex_layout* outFlexLayout, int32_t acquireFence); + +/* unlock(..., buffer, releaseFence) + * Function descriptor: GRALLOC1_FUNCTION_UNLOCK + * Must be provided by all gralloc1 devices + * + * This function indicates to the device that the client will be done with the + * buffer when releaseFence signals. + * + * outReleaseFence will be filled with a file descriptor referring to a release + * sync fence object, which will be signaled when it is safe to access the + * contents of the buffer (after the buffer has been unlocked). If it is already + * safe to access the buffer contents, then -1 may be returned instead. + * + * This function is used to unlock both buffers locked by lock() and those + * locked by lockFlex(). + * + * Parameters: + * buffer - the buffer to unlock + * outReleaseFence - a sync fence file descriptor as described above + * + * Returns GRALLOC1_ERROR_NONE or one of the following errors: + * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid + */ +typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_UNLOCK)( + gralloc1_device_t* device, buffer_handle_t buffer, + int32_t* outReleaseFence); + +__END_DECLS + +#endif diff --git a/include_all/hardware/hardware.h b/include_all/hardware/hardware.h new file mode 100644 index 00000000..bf076f6c --- /dev/null +++ b/include_all/hardware/hardware.h @@ -0,0 +1,244 @@ +/* + * Copyright (C) 2008 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_INCLUDE_HARDWARE_HARDWARE_H +#define ANDROID_INCLUDE_HARDWARE_HARDWARE_H + +#include <stdint.h> +#include <sys/cdefs.h> + +#include <cutils/native_handle.h> +#include <system/graphics.h> + +__BEGIN_DECLS + +/* + * Value for the hw_module_t.tag field + */ + +#define MAKE_TAG_CONSTANT(A,B,C,D) (((A) << 24) | ((B) << 16) | ((C) << 8) | (D)) + +#define HARDWARE_MODULE_TAG MAKE_TAG_CONSTANT('H', 'W', 'M', 'T') +#define HARDWARE_DEVICE_TAG MAKE_TAG_CONSTANT('H', 'W', 'D', 'T') + +#define HARDWARE_MAKE_API_VERSION(maj,min) \ + ((((maj) & 0xff) << 8) | ((min) & 0xff)) + +#define HARDWARE_MAKE_API_VERSION_2(maj,min,hdr) \ + ((((maj) & 0xff) << 24) | (((min) & 0xff) << 16) | ((hdr) & 0xffff)) +#define HARDWARE_API_VERSION_2_MAJ_MIN_MASK 0xffff0000 +#define HARDWARE_API_VERSION_2_HEADER_MASK 0x0000ffff + + +/* + * The current HAL API version. + * + * All module implementations must set the hw_module_t.hal_api_version field + * to this value when declaring the module with HAL_MODULE_INFO_SYM. + * + * Note that previous implementations have always set this field to 0. + * Therefore, libhardware HAL API will always consider versions 0.0 and 1.0 + * to be 100% binary compatible. + * + */ +#define HARDWARE_HAL_API_VERSION HARDWARE_MAKE_API_VERSION(1, 0) + +/* + * Helper macros for module implementors. + * + * The derived modules should provide convenience macros for supported + * versions so that implementations can explicitly specify module/device + * versions at definition time. + * + * Use this macro to set the hw_module_t.module_api_version field. + */ +#define HARDWARE_MODULE_API_VERSION(maj,min) HARDWARE_MAKE_API_VERSION(maj,min) +#define HARDWARE_MODULE_API_VERSION_2(maj,min,hdr) HARDWARE_MAKE_API_VERSION_2(maj,min,hdr) + +/* + * Use this macro to set the hw_device_t.version field + */ +#define HARDWARE_DEVICE_API_VERSION(maj,min) HARDWARE_MAKE_API_VERSION(maj,min) +#define HARDWARE_DEVICE_API_VERSION_2(maj,min,hdr) HARDWARE_MAKE_API_VERSION_2(maj,min,hdr) + +struct hw_module_t; +struct hw_module_methods_t; +struct hw_device_t; + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +typedef struct hw_module_t { + /** tag must be initialized to HARDWARE_MODULE_TAG */ + uint32_t tag; + + /** + * The API version of the implemented module. The module owner is + * responsible for updating the version when a module interface has + * changed. + * + * The derived modules such as gralloc and audio own and manage this field. + * The module user must interpret the version field to decide whether or + * not to inter-operate with the supplied module implementation. + * For example, SurfaceFlinger is responsible for making sure that + * it knows how to manage different versions of the gralloc-module API, + * and AudioFlinger must know how to do the same for audio-module API. + * + * The module API version should include a major and a minor component. + * For example, version 1.0 could be represented as 0x0100. This format + * implies that versions 0x0100-0x01ff are all API-compatible. + * + * In the future, libhardware will expose a hw_get_module_version() + * (or equivalent) function that will take minimum/maximum supported + * versions as arguments and would be able to reject modules with + * versions outside of the supplied range. + */ + uint16_t module_api_version; +#define version_major module_api_version + /** + * version_major/version_minor defines are supplied here for temporary + * source code compatibility. They will be removed in the next version. + * ALL clients must convert to the new version format. + */ + + /** + * The API version of the HAL module interface. This is meant to + * version the hw_module_t, hw_module_methods_t, and hw_device_t + * structures and definitions. + * + * The HAL interface owns this field. Module users/implementations + * must NOT rely on this value for version information. + * + * Presently, 0 is the only valid value. + */ + uint16_t hal_api_version; +#define version_minor hal_api_version + + /** Identifier of module */ + const char *id; + + /** Name of this module */ + const char *name; + + /** Author/owner/implementor of the module */ + const char *author; + + /** Modules methods */ + struct hw_module_methods_t* methods; + + /** module's dso */ + void* dso; + +#ifdef __LP64__ + uint64_t reserved[32-7]; +#else + /** padding to 128 bytes, reserved for future use */ + uint32_t reserved[32-7]; +#endif + +} hw_module_t; + +typedef struct hw_module_methods_t { + /** Open a specific device */ + int (*open)(const struct hw_module_t* module, const char* id, + struct hw_device_t** device); + +} hw_module_methods_t; + +/** + * Every device data structure must begin with hw_device_t + * followed by module specific public methods and attributes. + */ +typedef struct hw_device_t { + /** tag must be initialized to HARDWARE_DEVICE_TAG */ + uint32_t tag; + + /** + * Version of the module-specific device API. This value is used by + * the derived-module user to manage different device implementations. + * + * The module user is responsible for checking the module_api_version + * and device version fields to ensure that the user is capable of + * communicating with the specific module implementation. + * + * One module can support multiple devices with different versions. This + * can be useful when a device interface changes in an incompatible way + * but it is still necessary to support older implementations at the same + * time. One such example is the Camera 2.0 API. + * + * This field is interpreted by the module user and is ignored by the + * HAL interface itself. + */ + uint32_t version; + + /** reference to the module this device belongs to */ + struct hw_module_t* module; + + /** padding reserved for future use */ +#ifdef __LP64__ + uint64_t reserved[12]; +#else + uint32_t reserved[12]; +#endif + + /** Close this device */ + int (*close)(struct hw_device_t* device); + +} hw_device_t; + +#ifdef __cplusplus +#define TO_HW_DEVICE_T_OPEN(x) reinterpret_cast<struct hw_device_t**>(x) +#else +#define TO_HW_DEVICE_T_OPEN(x) (struct hw_device_t**)(x) +#endif + +/** + * Name of the hal_module_info + */ +#define HAL_MODULE_INFO_SYM HMI + +/** + * Name of the hal_module_info as a string + */ +#define HAL_MODULE_INFO_SYM_AS_STR "HMI" + +/** + * Get the module info associated with a module by id. + * + * @return: 0 == success, <0 == error and *module == NULL + */ +int hw_get_module(const char *id, const struct hw_module_t **module); + +/** + * Get the module info associated with a module instance by class 'class_id' + * and instance 'inst'. + * + * Some modules types necessitate multiple instances. For example audio supports + * multiple concurrent interfaces and thus 'audio' is the module class + * and 'primary' or 'a2dp' are module interfaces. This implies that the files + * providing these modules would be named audio.primary.<variant>.so and + * audio.a2dp.<variant>.so + * + * @return: 0 == success, <0 == error and *module == NULL + */ +int hw_get_module_by_class(const char *class_id, const char *inst, + const struct hw_module_t **module); + +__END_DECLS + +#endif /* ANDROID_INCLUDE_HARDWARE_HARDWARE_H */ diff --git a/include_all/hardware/hdmi_cec.h b/include_all/hardware/hdmi_cec.h new file mode 100644 index 00000000..aa06384e --- /dev/null +++ b/include_all/hardware/hdmi_cec.h @@ -0,0 +1,429 @@ +/* + * Copyright (C) 2014 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_INCLUDE_HARDWARE_HDMI_CEC_H +#define ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H + +#include <stdint.h> +#include <sys/cdefs.h> + +#include <hardware/hardware.h> + +__BEGIN_DECLS + +#define HDMI_CEC_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) +#define HDMI_CEC_MODULE_API_VERSION_CURRENT HDMI_MODULE_API_VERSION_1_0 + +#define HDMI_CEC_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) +#define HDMI_CEC_DEVICE_API_VERSION_CURRENT HDMI_DEVICE_API_VERSION_1_0 + +#define HDMI_CEC_HARDWARE_MODULE_ID "hdmi_cec" +#define HDMI_CEC_HARDWARE_INTERFACE "hdmi_cec_hw_if" + +typedef enum cec_device_type { + CEC_DEVICE_INACTIVE = -1, + CEC_DEVICE_TV = 0, + CEC_DEVICE_RECORDER = 1, + CEC_DEVICE_RESERVED = 2, + CEC_DEVICE_TUNER = 3, + CEC_DEVICE_PLAYBACK = 4, + CEC_DEVICE_AUDIO_SYSTEM = 5, + CEC_DEVICE_MAX = CEC_DEVICE_AUDIO_SYSTEM +} cec_device_type_t; + +typedef enum cec_logical_address { + CEC_ADDR_TV = 0, + CEC_ADDR_RECORDER_1 = 1, + CEC_ADDR_RECORDER_2 = 2, + CEC_ADDR_TUNER_1 = 3, + CEC_ADDR_PLAYBACK_1 = 4, + CEC_ADDR_AUDIO_SYSTEM = 5, + CEC_ADDR_TUNER_2 = 6, + CEC_ADDR_TUNER_3 = 7, + CEC_ADDR_PLAYBACK_2 = 8, + CEC_ADDR_RECORDER_3 = 9, + CEC_ADDR_TUNER_4 = 10, + CEC_ADDR_PLAYBACK_3 = 11, + CEC_ADDR_RESERVED_1 = 12, + CEC_ADDR_RESERVED_2 = 13, + CEC_ADDR_FREE_USE = 14, + CEC_ADDR_UNREGISTERED = 15, + CEC_ADDR_BROADCAST = 15 +} cec_logical_address_t; + +/* + * HDMI CEC messages + */ +enum cec_message_type { + CEC_MESSAGE_FEATURE_ABORT = 0x00, + CEC_MESSAGE_IMAGE_VIEW_ON = 0x04, + CEC_MESSAGE_TUNER_STEP_INCREMENT = 0x05, + CEC_MESSAGE_TUNER_STEP_DECREMENT = 0x06, + CEC_MESSAGE_TUNER_DEVICE_STATUS = 0x07, + CEC_MESSAGE_GIVE_TUNER_DEVICE_STATUS = 0x08, + CEC_MESSAGE_RECORD_ON = 0x09, + CEC_MESSAGE_RECORD_STATUS = 0x0A, + CEC_MESSAGE_RECORD_OFF = 0x0B, + CEC_MESSAGE_TEXT_VIEW_ON = 0x0D, + CEC_MESSAGE_RECORD_TV_SCREEN = 0x0F, + CEC_MESSAGE_GIVE_DECK_STATUS = 0x1A, + CEC_MESSAGE_DECK_STATUS = 0x1B, + CEC_MESSAGE_SET_MENU_LANGUAGE = 0x32, + CEC_MESSAGE_CLEAR_ANALOG_TIMER = 0x33, + CEC_MESSAGE_SET_ANALOG_TIMER = 0x34, + CEC_MESSAGE_TIMER_STATUS = 0x35, + CEC_MESSAGE_STANDBY = 0x36, + CEC_MESSAGE_PLAY = 0x41, + CEC_MESSAGE_DECK_CONTROL = 0x42, + CEC_MESSAGE_TIMER_CLEARED_STATUS = 0x043, + CEC_MESSAGE_USER_CONTROL_PRESSED = 0x44, + CEC_MESSAGE_USER_CONTROL_RELEASED = 0x45, + CEC_MESSAGE_GIVE_OSD_NAME = 0x46, + CEC_MESSAGE_SET_OSD_NAME = 0x47, + CEC_MESSAGE_SET_OSD_STRING = 0x64, + CEC_MESSAGE_SET_TIMER_PROGRAM_TITLE = 0x67, + CEC_MESSAGE_SYSTEM_AUDIO_MODE_REQUEST = 0x70, + CEC_MESSAGE_GIVE_AUDIO_STATUS = 0x71, + CEC_MESSAGE_SET_SYSTEM_AUDIO_MODE = 0x72, + CEC_MESSAGE_REPORT_AUDIO_STATUS = 0x7A, + CEC_MESSAGE_GIVE_SYSTEM_AUDIO_MODE_STATUS = 0x7D, + CEC_MESSAGE_SYSTEM_AUDIO_MODE_STATUS = 0x7E, + CEC_MESSAGE_ROUTING_CHANGE = 0x80, + CEC_MESSAGE_ROUTING_INFORMATION = 0x81, + CEC_MESSAGE_ACTIVE_SOURCE = 0x82, + CEC_MESSAGE_GIVE_PHYSICAL_ADDRESS = 0x83, + CEC_MESSAGE_REPORT_PHYSICAL_ADDRESS = 0x84, + CEC_MESSAGE_REQUEST_ACTIVE_SOURCE = 0x85, + CEC_MESSAGE_SET_STREAM_PATH = 0x86, + CEC_MESSAGE_DEVICE_VENDOR_ID = 0x87, + CEC_MESSAGE_VENDOR_COMMAND = 0x89, + CEC_MESSAGE_VENDOR_REMOTE_BUTTON_DOWN = 0x8A, + CEC_MESSAGE_VENDOR_REMOTE_BUTTON_UP = 0x8B, + CEC_MESSAGE_GIVE_DEVICE_VENDOR_ID = 0x8C, + CEC_MESSAGE_MENU_REQUEST = 0x8D, + CEC_MESSAGE_MENU_STATUS = 0x8E, + CEC_MESSAGE_GIVE_DEVICE_POWER_STATUS = 0x8F, + CEC_MESSAGE_REPORT_POWER_STATUS = 0x90, + CEC_MESSAGE_GET_MENU_LANGUAGE = 0x91, + CEC_MESSAGE_SELECT_ANALOG_SERVICE = 0x92, + CEC_MESSAGE_SELECT_DIGITAL_SERVICE = 0x93, + CEC_MESSAGE_SET_DIGITAL_TIMER = 0x97, + CEC_MESSAGE_CLEAR_DIGITAL_TIMER = 0x99, + CEC_MESSAGE_SET_AUDIO_RATE = 0x9A, + CEC_MESSAGE_INACTIVE_SOURCE = 0x9D, + CEC_MESSAGE_CEC_VERSION = 0x9E, + CEC_MESSAGE_GET_CEC_VERSION = 0x9F, + CEC_MESSAGE_VENDOR_COMMAND_WITH_ID = 0xA0, + CEC_MESSAGE_CLEAR_EXTERNAL_TIMER = 0xA1, + CEC_MESSAGE_SET_EXTERNAL_TIMER = 0xA2, + CEC_MESSAGE_INITIATE_ARC = 0xC0, + CEC_MESSAGE_REPORT_ARC_INITIATED = 0xC1, + CEC_MESSAGE_REPORT_ARC_TERMINATED = 0xC2, + CEC_MESSAGE_REQUEST_ARC_INITIATION = 0xC3, + CEC_MESSAGE_REQUEST_ARC_TERMINATION = 0xC4, + CEC_MESSAGE_TERMINATE_ARC = 0xC5, + CEC_MESSAGE_ABORT = 0xFF +}; + +/* + * Operand description [Abort Reason] + */ +enum abort_reason { + ABORT_UNRECOGNIZED_MODE = 0, + ABORT_NOT_IN_CORRECT_MODE = 1, + ABORT_CANNOT_PROVIDE_SOURCE = 2, + ABORT_INVALID_OPERAND = 3, + ABORT_REFUSED = 4, + ABORT_UNABLE_TO_DETERMINE = 5 +}; + +/* + * HDMI event type. used for hdmi_event_t. + */ +enum { + HDMI_EVENT_CEC_MESSAGE = 1, + HDMI_EVENT_HOT_PLUG = 2, +}; + +/* + * HDMI hotplug event type. Used when the event + * type is HDMI_EVENT_HOT_PLUG. + */ +enum { + HDMI_NOT_CONNECTED = 0, + HDMI_CONNECTED = 1 +}; + +/* + * error code used for send_message. + */ +enum { + HDMI_RESULT_SUCCESS = 0, + HDMI_RESULT_NACK = 1, /* not acknowledged */ + HDMI_RESULT_BUSY = 2, /* bus is busy */ + HDMI_RESULT_FAIL = 3, +}; + +/* + * HDMI port type. + */ +typedef enum hdmi_port_type { + HDMI_INPUT = 0, + HDMI_OUTPUT = 1 +} hdmi_port_type_t; + +/* + * Flags used for set_option() + */ +enum { + /* When set to false, HAL does not wake up the system upon receiving + * <Image View On> or <Text View On>. Used when user changes the TV + * settings to disable the auto TV on functionality. + * True by default. + */ + HDMI_OPTION_WAKEUP = 1, + + /* When set to false, all the CEC commands are discarded. Used when + * user changes the TV settings to disable CEC functionality. + * True by default. + */ + HDMI_OPTION_ENABLE_CEC = 2, + + /* Setting this flag to false means Android system will stop handling + * CEC service and yield the control over to the microprocessor that is + * powered on through the standby mode. When set to true, the system + * will gain the control over, hence telling the microprocessor to stop + * handling the cec commands. This is called when system goes + * in and out of standby mode to notify the microprocessor that it should + * start/stop handling CEC commands on behalf of the system. + * False by default. + */ + HDMI_OPTION_SYSTEM_CEC_CONTROL = 3, + + /* Option 4 not used */ + + /* Passes the updated language information of Android system. + * Contains 3-byte ASCII code as defined in ISO/FDIS 639-2. Can be + * used for HAL to respond to <Get Menu Language> while in standby mode. + * English(eng), for example, is converted to 0x656e67. + */ + HDMI_OPTION_SET_LANG = 5, +}; + +/* + * Maximum length in bytes of cec message body (exclude header block), + * should not exceed 16 (spec CEC 6 Frame Description) + */ +#define CEC_MESSAGE_BODY_MAX_LENGTH 16 + +typedef struct cec_message { + /* logical address of sender */ + cec_logical_address_t initiator; + + /* logical address of receiver */ + cec_logical_address_t destination; + + /* Length in bytes of body, range [0, CEC_MESSAGE_BODY_MAX_LENGTH] */ + size_t length; + unsigned char body[CEC_MESSAGE_BODY_MAX_LENGTH]; +} cec_message_t; + +typedef struct hotplug_event { + /* + * true if the cable is connected; otherwise false. + */ + int connected; + int port_id; +} hotplug_event_t; + +typedef struct tx_status_event { + int status; + int opcode; /* CEC opcode */ +} tx_status_event_t; + +/* + * HDMI event generated from HAL. + */ +typedef struct hdmi_event { + int type; + struct hdmi_cec_device* dev; + union { + cec_message_t cec; + hotplug_event_t hotplug; + }; +} hdmi_event_t; + +/* + * HDMI port descriptor + */ +typedef struct hdmi_port_info { + hdmi_port_type_t type; + // Port ID should start from 1 which corresponds to HDMI "port 1". + int port_id; + int cec_supported; + int arc_supported; + uint16_t physical_address; +} hdmi_port_info_t; + +/* + * Callback function type that will be called by HAL implementation. + * Services can not close/open the device in the callback. + */ +typedef void (*event_callback_t)(const hdmi_event_t* event, void* arg); + +typedef struct hdmi_cec_module { + /** + * Common methods of the HDMI CEC module. This *must* be the first member of + * hdmi_cec_module as users of this structure will cast a hw_module_t to hdmi_cec_module + * pointer in contexts where it's known the hw_module_t references a hdmi_cec_module. + */ + struct hw_module_t common; +} hdmi_module_t; + +/* + * HDMI-CEC HAL interface definition. + */ +typedef struct hdmi_cec_device { + /** + * Common methods of the HDMI CEC device. This *must* be the first member of + * hdmi_cec_device as users of this structure will cast a hw_device_t to hdmi_cec_device + * pointer in contexts where it's known the hw_device_t references a hdmi_cec_device. + */ + struct hw_device_t common; + + /* + * (*add_logical_address)() passes the logical address that will be used + * in this system. + * + * HAL may use it to configure the hardware so that the CEC commands addressed + * the given logical address can be filtered in. This method can be called + * as many times as necessary in order to support multiple logical devices. + * addr should be in the range of valid logical addresses for the call + * to succeed. + * + * Returns 0 on success or -errno on error. + */ + int (*add_logical_address)(const struct hdmi_cec_device* dev, cec_logical_address_t addr); + + /* + * (*clear_logical_address)() tells HAL to reset all the logical addresses. + * + * It is used when the system doesn't need to process CEC command any more, + * hence to tell HAL to stop receiving commands from the CEC bus, and change + * the state back to the beginning. + */ + void (*clear_logical_address)(const struct hdmi_cec_device* dev); + + /* + * (*get_physical_address)() returns the CEC physical address. The + * address is written to addr. + * + * The physical address depends on the topology of the network formed + * by connected HDMI devices. It is therefore likely to change if the cable + * is plugged off and on again. It is advised to call get_physical_address + * to get the updated address when hot plug event takes place. + * + * Returns 0 on success or -errno on error. + */ + int (*get_physical_address)(const struct hdmi_cec_device* dev, uint16_t* addr); + + /* + * (*send_message)() transmits HDMI-CEC message to other HDMI device. + * + * The method should be designed to return in a certain amount of time not + * hanging forever, which can happen if CEC signal line is pulled low for + * some reason. HAL implementation should take the situation into account + * so as not to wait forever for the message to get sent out. + * + * It should try retransmission at least once as specified in the standard. + * + * Returns error code. See HDMI_RESULT_SUCCESS, HDMI_RESULT_NACK, and + * HDMI_RESULT_BUSY. + */ + int (*send_message)(const struct hdmi_cec_device* dev, const cec_message_t*); + + /* + * (*register_event_callback)() registers a callback that HDMI-CEC HAL + * can later use for incoming CEC messages or internal HDMI events. + * When calling from C++, use the argument arg to pass the calling object. + * It will be passed back when the callback is invoked so that the context + * can be retrieved. + */ + void (*register_event_callback)(const struct hdmi_cec_device* dev, + event_callback_t callback, void* arg); + + /* + * (*get_version)() returns the CEC version supported by underlying hardware. + */ + void (*get_version)(const struct hdmi_cec_device* dev, int* version); + + /* + * (*get_vendor_id)() returns the identifier of the vendor. It is + * the 24-bit unique company ID obtained from the IEEE Registration + * Authority Committee (RAC). + */ + void (*get_vendor_id)(const struct hdmi_cec_device* dev, uint32_t* vendor_id); + + /* + * (*get_port_info)() returns the hdmi port information of underlying hardware. + * info is the list of HDMI port information, and 'total' is the number of + * HDMI ports in the system. + */ + void (*get_port_info)(const struct hdmi_cec_device* dev, + struct hdmi_port_info* list[], int* total); + + /* + * (*set_option)() passes flags controlling the way HDMI-CEC service works down + * to HAL implementation. Those flags will be used in case the feature needs + * update in HAL itself, firmware or microcontroller. + */ + void (*set_option)(const struct hdmi_cec_device* dev, int flag, int value); + + /* + * (*set_audio_return_channel)() configures ARC circuit in the hardware logic + * to start or stop the feature. Flag can be either 1 to start the feature + * or 0 to stop it. + * + * Returns 0 on success or -errno on error. + */ + void (*set_audio_return_channel)(const struct hdmi_cec_device* dev, int port_id, int flag); + + /* + * (*is_connected)() returns the connection status of the specified port. + * Returns HDMI_CONNECTED if a device is connected, otherwise HDMI_NOT_CONNECTED. + * The HAL should watch for +5V power signal to determine the status. + */ + int (*is_connected)(const struct hdmi_cec_device* dev, int port_id); + + /* Reserved for future use to maximum 16 functions. Must be NULL. */ + void* reserved[16 - 11]; +} hdmi_cec_device_t; + +/** convenience API for opening and closing a device */ + +static inline int hdmi_cec_open(const struct hw_module_t* module, + struct hdmi_cec_device** device) { + return module->methods->open(module, + HDMI_CEC_HARDWARE_INTERFACE, TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int hdmi_cec_close(struct hdmi_cec_device* device) { + return device->common.close(&device->common); +} + +__END_DECLS + +#endif /* ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H */ diff --git a/include_all/hardware/hw_auth_token.h b/include_all/hardware/hw_auth_token.h new file mode 100644 index 00000000..3305f2c8 --- /dev/null +++ b/include_all/hardware/hw_auth_token.h @@ -0,0 +1,53 @@ +/* + * Copyright (C) 2014 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. + */ + +#include <stdint.h> + +#ifndef ANDROID_HARDWARE_HW_AUTH_TOKEN_H +#define ANDROID_HARDWARE_HW_AUTH_TOKEN_H + +#ifdef __cplusplus +extern "C" { +#endif // __cplusplus + +#define HW_AUTH_TOKEN_VERSION 0 + +typedef enum { + HW_AUTH_NONE = 0, + HW_AUTH_PASSWORD = 1 << 0, + HW_AUTH_FINGERPRINT = 1 << 1, + // Additional entries should be powers of 2. + HW_AUTH_ANY = UINT32_MAX, +} hw_authenticator_type_t; + +/** + * Data format for an authentication record used to prove successful authentication. + */ +typedef struct __attribute__((__packed__)) { + uint8_t version; // Current version is 0 + uint64_t challenge; + uint64_t user_id; // secure user ID, not Android user ID + uint64_t authenticator_id; // secure authenticator ID + uint32_t authenticator_type; // hw_authenticator_type_t, in network order + uint64_t timestamp; // in network order + uint8_t hmac[32]; +} hw_auth_token_t; + +#ifdef __cplusplus +} // extern "C" +#endif // __cplusplus + +#endif // ANDROID_HARDWARE_HW_AUTH_TOKEN_H diff --git a/include_all/hardware/hwcomposer.h b/include_all/hardware/hwcomposer.h new file mode 100644 index 00000000..9eb1aafb --- /dev/null +++ b/include_all/hardware/hwcomposer.h @@ -0,0 +1,798 @@ +/* + * Copyright (C) 2010 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_INCLUDE_HARDWARE_HWCOMPOSER_H +#define ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H + +#include <stdint.h> +#include <sys/cdefs.h> + +#include <hardware/gralloc.h> +#include <hardware/hardware.h> +#include <cutils/native_handle.h> + +#include <hardware/hwcomposer_defs.h> + +__BEGIN_DECLS + +/*****************************************************************************/ + +/* for compatibility */ +#define HWC_MODULE_API_VERSION HWC_MODULE_API_VERSION_0_1 +#define HWC_DEVICE_API_VERSION HWC_DEVICE_API_VERSION_0_1 +#define HWC_API_VERSION HWC_DEVICE_API_VERSION + +/*****************************************************************************/ + +typedef struct hwc_layer_1 { + /* + * compositionType is used to specify this layer's type and is set by either + * the hardware composer implementation, or by the caller (see below). + * + * This field is always reset to HWC_BACKGROUND or HWC_FRAMEBUFFER + * before (*prepare)() is called when the HWC_GEOMETRY_CHANGED flag is + * also set, otherwise, this field is preserved between (*prepare)() + * calls. + * + * HWC_BACKGROUND + * Always set by the caller before calling (*prepare)(), this value + * indicates this is a special "background" layer. The only valid field + * is backgroundColor. + * The HWC can toggle this value to HWC_FRAMEBUFFER to indicate it CANNOT + * handle the background color. + * + * + * HWC_FRAMEBUFFER_TARGET + * Always set by the caller before calling (*prepare)(), this value + * indicates this layer is the framebuffer surface used as the target of + * OpenGL ES composition. If the HWC sets all other layers to HWC_OVERLAY + * or HWC_BACKGROUND, then no OpenGL ES composition will be done, and + * this layer should be ignored during set(). + * + * This flag (and the framebuffer surface layer) will only be used if the + * HWC version is HWC_DEVICE_API_VERSION_1_1 or higher. In older versions, + * the OpenGL ES target surface is communicated by the (dpy, sur) fields + * in hwc_compositor_device_1_t. + * + * This value cannot be set by the HWC implementation. + * + * + * HWC_FRAMEBUFFER + * Set by the caller before calling (*prepare)() ONLY when the + * HWC_GEOMETRY_CHANGED flag is also set. + * + * Set by the HWC implementation during (*prepare)(), this indicates + * that the layer will be drawn into the framebuffer using OpenGL ES. + * The HWC can toggle this value to HWC_OVERLAY to indicate it will + * handle the layer. + * + * + * HWC_OVERLAY + * Set by the HWC implementation during (*prepare)(), this indicates + * that the layer will be handled by the HWC (ie: it must not be + * composited with OpenGL ES). + * + * + * HWC_SIDEBAND + * Set by the caller before calling (*prepare)(), this value indicates + * the contents of this layer come from a sideband video stream. + * + * The h/w composer is responsible for receiving new image buffers from + * the stream at the appropriate time (e.g. synchronized to a separate + * audio stream), compositing them with the current contents of other + * layers, and displaying the resulting image. This happens + * independently of the normal prepare/set cycle. The prepare/set calls + * only happen when other layers change, or when properties of the + * sideband layer such as position or size change. + * + * If the h/w composer can't handle the layer as a sideband stream for + * some reason (e.g. unsupported scaling/blending/rotation, or too many + * sideband layers) it can set compositionType to HWC_FRAMEBUFFER in + * (*prepare)(). However, doing so will result in the layer being shown + * as a solid color since the platform is not currently able to composite + * sideband layers with the GPU. This may be improved in future + * versions of the platform. + * + * + * HWC_CURSOR_OVERLAY + * Set by the HWC implementation during (*prepare)(), this value + * indicates the layer's composition will now be handled by the HWC. + * Additionally, the client can now asynchronously update the on-screen + * position of this layer using the setCursorPositionAsync() api. + */ + int32_t compositionType; + + /* + * hints is bit mask set by the HWC implementation during (*prepare)(). + * It is preserved between (*prepare)() calls, unless the + * HWC_GEOMETRY_CHANGED flag is set, in which case it is reset to 0. + * + * see hwc_layer_t::hints + */ + uint32_t hints; + + /* see hwc_layer_t::flags */ + uint32_t flags; + + union { + /* color of the background. hwc_color_t.a is ignored */ + hwc_color_t backgroundColor; + + struct { + union { + /* When compositionType is HWC_FRAMEBUFFER, HWC_OVERLAY, + * HWC_FRAMEBUFFER_TARGET, this is the handle of the buffer to + * compose. This handle is guaranteed to have been allocated + * from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. + * If the layer's handle is unchanged across two consecutive + * prepare calls and the HWC_GEOMETRY_CHANGED flag is not set + * for the second call then the HWComposer implementation may + * assume that the contents of the buffer have not changed. */ + buffer_handle_t handle; + + /* When compositionType is HWC_SIDEBAND, this is the handle + * of the sideband video stream to compose. */ + const native_handle_t* sidebandStream; + }; + + /* transformation to apply to the buffer during composition */ + uint32_t transform; + + /* blending to apply during composition */ + int32_t blending; + + /* area of the source to consider, the origin is the top-left corner of + * the buffer. As of HWC_DEVICE_API_VERSION_1_3, sourceRect uses floats. + * If the h/w can't support a non-integer source crop rectangle, it should + * punt to OpenGL ES composition. + */ + union { + // crop rectangle in integer (pre HWC_DEVICE_API_VERSION_1_3) + hwc_rect_t sourceCropi; + hwc_rect_t sourceCrop; // just for source compatibility + // crop rectangle in floats (as of HWC_DEVICE_API_VERSION_1_3) + hwc_frect_t sourceCropf; + }; + + /* where to composite the sourceCrop onto the display. The sourceCrop + * is scaled using linear filtering to the displayFrame. The origin is the + * top-left corner of the screen. + */ + hwc_rect_t displayFrame; + + /* visible region in screen space. The origin is the + * top-left corner of the screen. + * The visible region INCLUDES areas overlapped by a translucent layer. + */ + hwc_region_t visibleRegionScreen; + + /* Sync fence object that will be signaled when the buffer's + * contents are available. May be -1 if the contents are already + * available. This field is only valid during set(), and should be + * ignored during prepare(). The set() call must not wait for the + * fence to be signaled before returning, but the HWC must wait for + * all buffers to be signaled before reading from them. + * + * HWC_FRAMEBUFFER layers will never have an acquire fence, since + * reads from them are complete before the framebuffer is ready for + * display. + * + * HWC_SIDEBAND layers will never have an acquire fence, since + * synchronization is handled through implementation-defined + * sideband mechanisms. + * + * The HWC takes ownership of the acquireFenceFd and is responsible + * for closing it when no longer needed. + */ + int acquireFenceFd; + + /* During set() the HWC must set this field to a file descriptor for + * a sync fence object that will signal after the HWC has finished + * reading from the buffer. The field is ignored by prepare(). Each + * layer should have a unique file descriptor, even if more than one + * refer to the same underlying fence object; this allows each to be + * closed independently. + * + * If buffer reads can complete at significantly different times, + * then using independent fences is preferred. For example, if the + * HWC handles some layers with a blit engine and others with + * overlays, then the blit layers can be reused immediately after + * the blit completes, but the overlay layers can't be reused until + * a subsequent frame has been displayed. + * + * Since HWC doesn't read from HWC_FRAMEBUFFER layers, it shouldn't + * produce a release fence for them. The releaseFenceFd will be -1 + * for these layers when set() is called. + * + * Since HWC_SIDEBAND buffers don't pass through the HWC client, + * the HWC shouldn't produce a release fence for them. The + * releaseFenceFd will be -1 for these layers when set() is called. + * + * The HWC client taks ownership of the releaseFenceFd and is + * responsible for closing it when no longer needed. + */ + int releaseFenceFd; + + /* + * Availability: HWC_DEVICE_API_VERSION_1_2 + * + * Alpha value applied to the whole layer. The effective + * value of each pixel is computed as: + * + * if (blending == HWC_BLENDING_PREMULT) + * pixel.rgb = pixel.rgb * planeAlpha / 255 + * pixel.a = pixel.a * planeAlpha / 255 + * + * Then blending proceeds as usual according to the "blending" + * field above. + * + * NOTE: planeAlpha applies to YUV layers as well: + * + * pixel.rgb = yuv_to_rgb(pixel.yuv) + * if (blending == HWC_BLENDING_PREMULT) + * pixel.rgb = pixel.rgb * planeAlpha / 255 + * pixel.a = planeAlpha + * + * + * IMPLEMENTATION NOTE: + * + * If the source image doesn't have an alpha channel, then + * the h/w can use the HWC_BLENDING_COVERAGE equations instead of + * HWC_BLENDING_PREMULT and simply set the alpha channel to + * planeAlpha. + * + * e.g.: + * + * if (blending == HWC_BLENDING_PREMULT) + * blending = HWC_BLENDING_COVERAGE; + * pixel.a = planeAlpha; + * + */ + uint8_t planeAlpha; + + /* Pad to 32 bits */ + uint8_t _pad[3]; + + /* + * Availability: HWC_DEVICE_API_VERSION_1_5 + * + * This defines the region of the source buffer that has been + * modified since the last frame. + * + * If surfaceDamage.numRects > 0, then it may be assumed that any + * portion of the source buffer not covered by one of the rects has + * not been modified this frame. If surfaceDamage.numRects == 0, + * then the whole source buffer must be treated as if it had been + * modified. + * + * If the layer's contents are not modified relative to the prior + * prepare/set cycle, surfaceDamage will contain exactly one empty + * rect ([0, 0, 0, 0]). + * + * The damage rects are relative to the pre-transformed buffer, and + * their origin is the top-left corner. + */ + hwc_region_t surfaceDamage; + }; + }; + +#ifdef __LP64__ + /* + * For 64-bit mode, this struct is 120 bytes (and 8-byte aligned), and needs + * to be padded as such to maintain binary compatibility. + */ + uint8_t reserved[120 - 112]; +#else + /* + * For 32-bit mode, this struct is 96 bytes, and needs to be padded as such + * to maintain binary compatibility. + */ + uint8_t reserved[96 - 84]; +#endif + +} hwc_layer_1_t; + +/* This represents a display, typically an EGLDisplay object */ +typedef void* hwc_display_t; + +/* This represents a surface, typically an EGLSurface object */ +typedef void* hwc_surface_t; + +/* + * hwc_display_contents_1_t::flags values + */ +enum { + /* + * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list + * passed to (*prepare)() has changed by more than just the buffer handles + * and acquire fences. + */ + HWC_GEOMETRY_CHANGED = 0x00000001, +}; + +/* + * Description of the contents to output on a display. + * + * This is the top-level structure passed to the prepare and set calls to + * negotiate and commit the composition of a display image. + */ +typedef struct hwc_display_contents_1 { + /* File descriptor referring to a Sync HAL fence object which will signal + * when this composition is retired. For a physical display, a composition + * is retired when it has been replaced on-screen by a subsequent set. For + * a virtual display, the composition is retired when the writes to + * outputBuffer are complete and can be read. The fence object is created + * and returned by the set call; this field will be -1 on entry to prepare + * and set. SurfaceFlinger will close the returned file descriptor. + */ + int retireFenceFd; + + union { + /* Fields only relevant for HWC_DEVICE_VERSION_1_0. */ + struct { + /* (dpy, sur) is the target of SurfaceFlinger's OpenGL ES + * composition for HWC_DEVICE_VERSION_1_0. They aren't relevant to + * prepare. The set call should commit this surface atomically to + * the display along with any overlay layers. + */ + hwc_display_t dpy; + hwc_surface_t sur; + }; + + /* These fields are used for virtual displays when the h/w composer + * version is at least HWC_DEVICE_VERSION_1_3. */ + struct { + /* outbuf is the buffer that receives the composed image for + * virtual displays. Writes to the outbuf must wait until + * outbufAcquireFenceFd signals. A fence that will signal when + * writes to outbuf are complete should be returned in + * retireFenceFd. + * + * This field is set before prepare(), so properties of the buffer + * can be used to decide which layers can be handled by h/w + * composer. + * + * If prepare() sets all layers to FRAMEBUFFER, then GLES + * composition will happen directly to the output buffer. In this + * case, both outbuf and the FRAMEBUFFER_TARGET layer's buffer will + * be the same, and set() has no work to do besides managing fences. + * + * If the TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS board config + * variable is defined (not the default), then this behavior is + * changed: if all layers are marked for FRAMEBUFFER, GLES + * composition will take place to a scratch framebuffer, and + * h/w composer must copy it to the output buffer. This allows the + * h/w composer to do format conversion if there are cases where + * that is more desirable than doing it in the GLES driver or at the + * virtual display consumer. + * + * If some or all layers are marked OVERLAY, then the framebuffer + * and output buffer will be different. As with physical displays, + * the framebuffer handle will not change between frames if all + * layers are marked for OVERLAY. + */ + buffer_handle_t outbuf; + + /* File descriptor for a fence that will signal when outbuf is + * ready to be written. The h/w composer is responsible for closing + * this when no longer needed. + * + * Will be -1 whenever outbuf is NULL, or when the outbuf can be + * written immediately. + */ + int outbufAcquireFenceFd; + }; + }; + + /* List of layers that will be composed on the display. The buffer handles + * in the list will be unique. If numHwLayers is 0, all composition will be + * performed by SurfaceFlinger. + */ + uint32_t flags; + size_t numHwLayers; + hwc_layer_1_t hwLayers[0]; + +} hwc_display_contents_1_t; + +/* see hwc_composer_device::registerProcs() + * All of the callbacks are required and non-NULL unless otherwise noted. + */ +typedef struct hwc_procs { + /* + * (*invalidate)() triggers a screen refresh, in particular prepare and set + * will be called shortly after this call is made. Note that there is + * NO GUARANTEE that the screen refresh will happen after invalidate() + * returns (in particular, it could happen before). + * invalidate() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL and + * it is safe to call invalidate() from any of hwc_composer_device + * hooks, unless noted otherwise. + */ + void (*invalidate)(const struct hwc_procs* procs); + + /* + * (*vsync)() is called by the h/w composer HAL when a vsync event is + * received and HWC_EVENT_VSYNC is enabled on a display + * (see: hwc_event_control). + * + * the "disp" parameter indicates which display the vsync event is for. + * the "timestamp" parameter is the system monotonic clock timestamp in + * nanosecond of when the vsync event happened. + * + * vsync() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL. + * + * It is expected that vsync() is called from a thread of at least + * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, + * typically less than 0.5 ms. + * + * It is a (silent) error to have HWC_EVENT_VSYNC enabled when calling + * hwc_composer_device.set(..., 0, 0, 0) (screen off). The implementation + * can either stop or continue to process VSYNC events, but must not + * crash or cause other problems. + */ + void (*vsync)(const struct hwc_procs* procs, int disp, int64_t timestamp); + + /* + * (*hotplug)() is called by the h/w composer HAL when a display is + * connected or disconnected. The PRIMARY display is always connected and + * the hotplug callback should not be called for it. + * + * The disp parameter indicates which display type this event is for. + * The connected parameter indicates whether the display has just been + * connected (1) or disconnected (0). + * + * The hotplug() callback may call back into the h/w composer on the same + * thread to query refresh rate and dpi for the display. Additionally, + * other threads may be calling into the h/w composer while the callback + * is in progress. + * + * The h/w composer must serialize calls to the hotplug callback; only + * one thread may call it at a time. + * + * This callback will be NULL if the h/w composer is using + * HWC_DEVICE_API_VERSION_1_0. + */ + void (*hotplug)(const struct hwc_procs* procs, int disp, int connected); + +} hwc_procs_t; + + +/*****************************************************************************/ + +typedef struct hwc_module { + /** + * Common methods of the hardware composer module. This *must* be the first member of + * hwc_module as users of this structure will cast a hw_module_t to + * hwc_module pointer in contexts where it's known the hw_module_t references a + * hwc_module. + */ + struct hw_module_t common; +} hwc_module_t; + +#define HWC_ERROR (-1) +typedef struct hwc_composer_device_1 { + /** + * Common methods of the hardware composer device. This *must* be the first member of + * hwc_composer_device_1 as users of this structure will cast a hw_device_t to + * hwc_composer_device_1 pointer in contexts where it's known the hw_device_t references a + * hwc_composer_device_1. + */ + struct hw_device_t common; + + /* + * (*prepare)() is called for each frame before composition and is used by + * SurfaceFlinger to determine what composition steps the HWC can handle. + * + * (*prepare)() can be called more than once, the last call prevails. + * + * The HWC responds by setting the compositionType field in each layer to + * either HWC_FRAMEBUFFER, HWC_OVERLAY, or HWC_CURSOR_OVERLAY. For the + * HWC_FRAMEBUFFER type, composition for the layer is handled by + * SurfaceFlinger with OpenGL ES. For the latter two overlay types, + * the HWC will have to handle the layer's composition. compositionType + * and hints are preserved between (*prepare)() calles unless the + * HWC_GEOMETRY_CHANGED flag is set. + * + * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the + * list's geometry has changed, that is, when more than just the buffer's + * handles have been updated. Typically this happens (but is not limited to) + * when a window is added, removed, resized or moved. In this case + * compositionType and hints are reset to their default value. + * + * For HWC 1.0, numDisplays will always be one, and displays[0] will be + * non-NULL. + * + * For HWC 1.1, numDisplays will always be HWC_NUM_PHYSICAL_DISPLAY_TYPES. + * Entries for unsupported or disabled/disconnected display types will be + * NULL. + * + * In HWC 1.3, numDisplays may be up to HWC_NUM_DISPLAY_TYPES. The extra + * entries correspond to enabled virtual displays, and will be non-NULL. + * + * returns: 0 on success. An negative error code on error. If an error is + * returned, SurfaceFlinger will assume that none of the layer will be + * handled by the HWC. + */ + int (*prepare)(struct hwc_composer_device_1 *dev, + size_t numDisplays, hwc_display_contents_1_t** displays); + + /* + * (*set)() is used in place of eglSwapBuffers(), and assumes the same + * functionality, except it also commits the work list atomically with + * the actual eglSwapBuffers(). + * + * The layer lists are guaranteed to be the same as the ones returned from + * the last call to (*prepare)(). + * + * When this call returns the caller assumes that the displays will be + * updated in the near future with the content of their work lists, without + * artifacts during the transition from the previous frame. + * + * A display with zero layers indicates that the entire composition has + * been handled by SurfaceFlinger with OpenGL ES. In this case, (*set)() + * behaves just like eglSwapBuffers(). + * + * For HWC 1.0, numDisplays will always be one, and displays[0] will be + * non-NULL. + * + * For HWC 1.1, numDisplays will always be HWC_NUM_PHYSICAL_DISPLAY_TYPES. + * Entries for unsupported or disabled/disconnected display types will be + * NULL. + * + * In HWC 1.3, numDisplays may be up to HWC_NUM_DISPLAY_TYPES. The extra + * entries correspond to enabled virtual displays, and will be non-NULL. + * + * IMPORTANT NOTE: There is an implicit layer containing opaque black + * pixels behind all the layers in the list. It is the responsibility of + * the hwcomposer module to make sure black pixels are output (or blended + * from). + * + * IMPORTANT NOTE: In the event of an error this call *MUST* still cause + * any fences returned in the previous call to set to eventually become + * signaled. The caller may have already issued wait commands on these + * fences, and having set return without causing those fences to signal + * will likely result in a deadlock. + * + * returns: 0 on success. A negative error code on error: + * HWC_EGL_ERROR: eglGetError() will provide the proper error code (only + * allowed prior to HWComposer 1.1) + * Another code for non EGL errors. + */ + int (*set)(struct hwc_composer_device_1 *dev, + size_t numDisplays, hwc_display_contents_1_t** displays); + + /* + * eventControl(..., event, enabled) + * Enables or disables h/w composer events for a display. + * + * eventControl can be called from any thread and takes effect + * immediately. + * + * Supported events are: + * HWC_EVENT_VSYNC + * + * returns -EINVAL if the "event" parameter is not one of the value above + * or if the "enabled" parameter is not 0 or 1. + */ + int (*eventControl)(struct hwc_composer_device_1* dev, int disp, + int event, int enabled); + + union { + /* + * For HWC 1.3 and earlier, the blank() interface is used. + * + * blank(..., blank) + * Blanks or unblanks a display's screen. + * + * Turns the screen off when blank is nonzero, on when blank is zero. + * Multiple sequential calls with the same blank value must be + * supported. + * The screen state transition must be be complete when the function + * returns. + * + * returns 0 on success, negative on error. + */ + int (*blank)(struct hwc_composer_device_1* dev, int disp, int blank); + + /* + * For HWC 1.4 and above, setPowerMode() will be used in place of + * blank(). + * + * setPowerMode(..., mode) + * Sets the display screen's power state. + * + * Refer to the documentation of the HWC_POWER_MODE_* constants + * for information about each power mode. + * + * The functionality is similar to the blank() command in previous + * versions of HWC, but with support for more power states. + * + * The display driver is expected to retain and restore the low power + * state of the display while entering and exiting from suspend. + * + * Multiple sequential calls with the same mode value must be supported. + * + * The screen state transition must be be complete when the function + * returns. + * + * returns 0 on success, negative on error. + */ + int (*setPowerMode)(struct hwc_composer_device_1* dev, int disp, + int mode); + }; + + /* + * Used to retrieve information about the h/w composer + * + * Returns 0 on success or -errno on error. + */ + int (*query)(struct hwc_composer_device_1* dev, int what, int* value); + + /* + * (*registerProcs)() registers callbacks that the h/w composer HAL can + * later use. It will be called immediately after the composer device is + * opened with non-NULL procs. It is FORBIDDEN to call any of the callbacks + * from within registerProcs(). registerProcs() must save the hwc_procs_t + * pointer which is needed when calling a registered callback. + */ + void (*registerProcs)(struct hwc_composer_device_1* dev, + hwc_procs_t const* procs); + + /* + * This field is OPTIONAL and can be NULL. + * + * If non NULL it will be called by SurfaceFlinger on dumpsys + */ + void (*dump)(struct hwc_composer_device_1* dev, char *buff, int buff_len); + + /* + * (*getDisplayConfigs)() returns handles for the configurations available + * on the connected display. These handles must remain valid as long as the + * display is connected. + * + * Configuration handles are written to configs. The number of entries + * allocated by the caller is passed in *numConfigs; getDisplayConfigs must + * not try to write more than this number of config handles. On return, the + * total number of configurations available for the display is returned in + * *numConfigs. If *numConfigs is zero on entry, then configs may be NULL. + * + * Hardware composers implementing HWC_DEVICE_API_VERSION_1_3 or prior + * shall choose one configuration to activate and report it as the first + * entry in the returned list. Reporting the inactive configurations is not + * required. + * + * HWC_DEVICE_API_VERSION_1_4 and later provide configuration management + * through SurfaceFlinger, and hardware composers implementing these APIs + * must also provide getActiveConfig and setActiveConfig. Hardware composers + * implementing these API versions may choose not to activate any + * configuration, leaving configuration selection to higher levels of the + * framework. + * + * Returns 0 on success or a negative error code on error. If disp is a + * hotpluggable display type and no display is connected, an error shall be + * returned. + * + * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later. + * It shall be NULL for previous versions. + */ + int (*getDisplayConfigs)(struct hwc_composer_device_1* dev, int disp, + uint32_t* configs, size_t* numConfigs); + + /* + * (*getDisplayAttributes)() returns attributes for a specific config of a + * connected display. The config parameter is one of the config handles + * returned by getDisplayConfigs. + * + * The list of attributes to return is provided in the attributes + * parameter, terminated by HWC_DISPLAY_NO_ATTRIBUTE. The value for each + * requested attribute is written in order to the values array. The + * HWC_DISPLAY_NO_ATTRIBUTE attribute does not have a value, so the values + * array will have one less value than the attributes array. + * + * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later. + * It shall be NULL for previous versions. + * + * If disp is a hotpluggable display type and no display is connected, + * or if config is not a valid configuration for the display, a negative + * error code shall be returned. + */ + int (*getDisplayAttributes)(struct hwc_composer_device_1* dev, int disp, + uint32_t config, const uint32_t* attributes, int32_t* values); + + /* + * (*getActiveConfig)() returns the index of the configuration that is + * currently active on the connected display. The index is relative to + * the list of configuration handles returned by getDisplayConfigs. If there + * is no active configuration, HWC_ERROR shall be returned. + * + * Returns the configuration index on success or HWC_ERROR on error. + * + * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_4 and later. + * It shall be NULL for previous versions. + */ + int (*getActiveConfig)(struct hwc_composer_device_1* dev, int disp); + + /* + * (*setActiveConfig)() instructs the hardware composer to switch to the + * display configuration at the given index in the list of configuration + * handles returned by getDisplayConfigs. + * + * If this function returns without error, any subsequent calls to + * getActiveConfig shall return the index set by this function until one + * of the following occurs: + * 1) Another successful call of this function + * 2) The display is disconnected + * + * Returns 0 on success or a negative error code on error. If disp is a + * hotpluggable display type and no display is connected, or if index is + * outside of the range of hardware configurations returned by + * getDisplayConfigs, an error shall be returned. + * + * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_4 and later. + * It shall be NULL for previous versions. + */ + int (*setActiveConfig)(struct hwc_composer_device_1* dev, int disp, + int index); + /* + * Asynchronously update the location of the cursor layer. + * + * Within the standard prepare()/set() composition loop, the client + * (surfaceflinger) can request that a given layer uses dedicated cursor + * composition hardware by specifiying the HWC_IS_CURSOR_LAYER flag. Only + * one layer per display can have this flag set. If the layer is suitable + * for the platform's cursor hardware, hwcomposer will return from prepare() + * a composition type of HWC_CURSOR_OVERLAY for that layer. This indicates + * not only that the client is not responsible for compositing that layer, + * but also that the client can continue to update the position of that layer + * after a call to set(). This can reduce the visible latency of mouse + * movement to visible, on-screen cursor updates. Calls to + * setCursorPositionAsync() may be made from a different thread doing the + * prepare()/set() composition loop, but care must be taken to not interleave + * calls of setCursorPositionAsync() between calls of set()/prepare(). + * + * Notes: + * - Only one layer per display can be specified as a cursor layer with + * HWC_IS_CURSOR_LAYER. + * - hwcomposer will only return one layer per display as HWC_CURSOR_OVERLAY + * - This returns 0 on success or -errno on error. + * - This field is optional for HWC_DEVICE_API_VERSION_1_4 and later. It + * should be null for previous versions. + */ + int (*setCursorPositionAsync)(struct hwc_composer_device_1 *dev, int disp, int x_pos, int y_pos); + + /* + * Reserved for future use. Must be NULL. + */ + void* reserved_proc[1]; + +} hwc_composer_device_1_t; + +/** convenience API for opening and closing a device */ + +static inline int hwc_open_1(const struct hw_module_t* module, + hwc_composer_device_1_t** device) { + return module->methods->open(module, + HWC_HARDWARE_COMPOSER, TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int hwc_close_1(hwc_composer_device_1_t* device) { + return device->common.close(&device->common); +} + +/*****************************************************************************/ + +__END_DECLS + +#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */ diff --git a/include_all/hardware/hwcomposer2.h b/include_all/hardware/hwcomposer2.h new file mode 100644 index 00000000..76122a57 --- /dev/null +++ b/include_all/hardware/hwcomposer2.h @@ -0,0 +1,3175 @@ +/* + * Copyright 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_HWCOMPOSER2_H +#define ANDROID_HARDWARE_HWCOMPOSER2_H + +#include <sys/cdefs.h> + +#include <hardware/hardware.h> + +#include "hwcomposer_defs.h" + +__BEGIN_DECLS + +/* + * Enums + * + * For most of these enums, there is an invalid value defined to be 0. This is + * an attempt to catch uninitialized fields, and these values should not be + * used. + */ + +/* Display attributes queryable through getDisplayAttribute */ +typedef enum { + HWC2_ATTRIBUTE_INVALID = 0, + + /* Dimensions in pixels */ + HWC2_ATTRIBUTE_WIDTH = 1, + HWC2_ATTRIBUTE_HEIGHT = 2, + + /* Vsync period in nanoseconds */ + HWC2_ATTRIBUTE_VSYNC_PERIOD = 3, + + /* Dots per thousand inches (DPI * 1000). Scaling by 1000 allows these + * numbers to be stored in an int32_t without losing too much precision. If + * the DPI for a configuration is unavailable or is considered unreliable, + * the device may return -1 instead */ + HWC2_ATTRIBUTE_DPI_X = 4, + HWC2_ATTRIBUTE_DPI_Y = 5, + + /* The configuration group this config is associated to. + * Switching between configurations within the same group may be done seamlessly + * in some conditions via setActiveConfigWithConstraints. */ + HWC2_ATTRIBUTE_CONFIG_GROUP = 7, +} hwc2_attribute_t; + +/* Blend modes, settable per layer */ +typedef enum { + HWC2_BLEND_MODE_INVALID = 0, + + /* colorOut = colorSrc */ + HWC2_BLEND_MODE_NONE = 1, + + /* colorOut = colorSrc + colorDst * (1 - alphaSrc) */ + HWC2_BLEND_MODE_PREMULTIPLIED = 2, + + /* colorOut = colorSrc * alphaSrc + colorDst * (1 - alphaSrc) */ + HWC2_BLEND_MODE_COVERAGE = 3, +} hwc2_blend_mode_t; + +/* See the 'Callbacks' section for more detailed descriptions of what these + * functions do */ +typedef enum { + HWC2_CALLBACK_INVALID = 0, + HWC2_CALLBACK_HOTPLUG = 1, + HWC2_CALLBACK_REFRESH = 2, + HWC2_CALLBACK_VSYNC = 3, + HWC2_CALLBACK_VSYNC_2_4 = 4, + HWC2_CALLBACK_VSYNC_PERIOD_TIMING_CHANGED = 5, + HWC2_CALLBACK_SEAMLESS_POSSIBLE = 6, +} hwc2_callback_descriptor_t; + +/* Optional capabilities which may be supported by some devices. The particular + * set of supported capabilities for a given device may be retrieved using + * getCapabilities. */ +typedef enum { + HWC2_CAPABILITY_INVALID = 0, + + /* Specifies that the device supports sideband stream layers, for which + * buffer content updates and other synchronization will not be provided + * through the usual validate/present cycle and must be handled by an + * external implementation-defined mechanism. Only changes to layer state + * (such as position, size, etc.) need to be performed through the + * validate/present cycle. */ + HWC2_CAPABILITY_SIDEBAND_STREAM = 1, + + /* Specifies that the device will apply a color transform even when either + * the client or the device has chosen that all layers should be composed by + * the client. This will prevent the client from applying the color + * transform during its composition step. */ + HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM = 2, + + /* Specifies that the present fence must not be used as an accurate + * representation of the actual present time of a frame. + * This capability must never be set by HWC2 devices. + * This capability may be set for HWC1 devices that use the + * HWC2On1Adapter where emulation of the present fence using the retire + * fence is not feasible. + * In the future, CTS tests will require present time to be reliable. + */ + HWC2_CAPABILITY_PRESENT_FENCE_IS_NOT_RELIABLE = 3, + + /* Specifies that a device is able to skip the validateDisplay call before + * receiving a call to presentDisplay. The client will always skip + * validateDisplay and try to call presentDisplay regardless of the changes + * in the properties of the layers. If the device returns anything else than + * HWC2_ERROR_NONE, it will call validateDisplay then presentDisplay again. + * For this capability to be worthwhile the device implementation of + * presentDisplay should fail as fast as possible in the case a + * validateDisplay step is needed. + */ + HWC2_CAPABILITY_SKIP_VALIDATE = 4, +} hwc2_capability_t; + +/* Possible composition types for a given layer */ +typedef enum { + HWC2_COMPOSITION_INVALID = 0, + + /* The client will composite this layer into the client target buffer + * (provided to the device through setClientTarget). + * + * The device must not request any composition type changes for layers of + * this type. */ + HWC2_COMPOSITION_CLIENT = 1, + + /* The device will handle the composition of this layer through a hardware + * overlay or other similar means. + * + * Upon validateDisplay, the device may request a change from this type to + * HWC2_COMPOSITION_CLIENT. */ + HWC2_COMPOSITION_DEVICE = 2, + + /* The device will render this layer using the color set through + * setLayerColor. If this functionality is not supported on a layer that the + * client sets to HWC2_COMPOSITION_SOLID_COLOR, the device must request that + * the composition type of that layer is changed to HWC2_COMPOSITION_CLIENT + * upon the next call to validateDisplay. + * + * Upon validateDisplay, the device may request a change from this type to + * HWC2_COMPOSITION_CLIENT. */ + HWC2_COMPOSITION_SOLID_COLOR = 3, + + /* Similar to DEVICE, but the position of this layer may also be set + * asynchronously through setCursorPosition. If this functionality is not + * supported on a layer that the client sets to HWC2_COMPOSITION_CURSOR, the + * device must request that the composition type of that layer is changed to + * HWC2_COMPOSITION_CLIENT upon the next call to validateDisplay. + * + * Upon validateDisplay, the device may request a change from this type to + * either HWC2_COMPOSITION_DEVICE or HWC2_COMPOSITION_CLIENT. Changing to + * HWC2_COMPOSITION_DEVICE will prevent the use of setCursorPosition but + * still permit the device to composite the layer. */ + HWC2_COMPOSITION_CURSOR = 4, + + /* The device will handle the composition of this layer, as well as its + * buffer updates and content synchronization. Only supported on devices + * which provide HWC2_CAPABILITY_SIDEBAND_STREAM. + * + * Upon validateDisplay, the device may request a change from this type to + * either HWC2_COMPOSITION_DEVICE or HWC2_COMPOSITION_CLIENT, but it is + * unlikely that content will display correctly in these cases. */ + HWC2_COMPOSITION_SIDEBAND = 5, +} hwc2_composition_t; + +/* Possible connection options from the hotplug callback */ +typedef enum { + HWC2_CONNECTION_INVALID = 0, + + /* The display has been connected */ + HWC2_CONNECTION_CONNECTED = 1, + + /* The display has been disconnected */ + HWC2_CONNECTION_DISCONNECTED = 2, +} hwc2_connection_t; + +/* Display requests returned by getDisplayRequests */ +typedef enum { + /* Instructs the client to provide a new client target buffer, even if no + * layers are marked for client composition. */ + HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET = 1 << 0, + + /* Instructs the client to write the result of client composition directly + * into the virtual display output buffer. If any of the layers are not + * marked as HWC2_COMPOSITION_CLIENT or the given display is not a virtual + * display, this request has no effect. */ + HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT = 1 << 1, +} hwc2_display_request_t; + +/* Display types returned by getDisplayType */ +typedef enum { + HWC2_DISPLAY_TYPE_INVALID = 0, + + /* All physical displays, including both internal displays and hotpluggable + * external displays */ + HWC2_DISPLAY_TYPE_PHYSICAL = 1, + + /* Virtual displays created by createVirtualDisplay */ + HWC2_DISPLAY_TYPE_VIRTUAL = 2, +} hwc2_display_type_t; + +/* Physical display types returned by getDisplayConnectionType */ +typedef enum { + HWC2_DISPLAY_CONNECTION_TYPE_INTERNAL = 0, + HWC2_DISPLAY_CONNECTION_TYPE_EXTERNAL = 1, +} hwc2_display_connection_type_t; + +/* Return codes from all functions */ +typedef enum { + HWC2_ERROR_NONE = 0, + HWC2_ERROR_BAD_CONFIG, + HWC2_ERROR_BAD_DISPLAY, + HWC2_ERROR_BAD_LAYER, + HWC2_ERROR_BAD_PARAMETER, + HWC2_ERROR_HAS_CHANGES, + HWC2_ERROR_NO_RESOURCES, + HWC2_ERROR_NOT_VALIDATED, + HWC2_ERROR_UNSUPPORTED, + HWC2_ERROR_SEAMLESS_NOT_ALLOWED, + HWC2_ERROR_SEAMLESS_NOT_POSSIBLE, +} hwc2_error_t; + +/* Function descriptors for use with getFunction */ +typedef enum { + HWC2_FUNCTION_INVALID = 0, + HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES, + HWC2_FUNCTION_CREATE_LAYER, + HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY, + HWC2_FUNCTION_DESTROY_LAYER, + HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY, + HWC2_FUNCTION_DUMP, + HWC2_FUNCTION_GET_ACTIVE_CONFIG, + HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES, + HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT, + HWC2_FUNCTION_GET_COLOR_MODES, + HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE, + HWC2_FUNCTION_GET_DISPLAY_CONFIGS, + HWC2_FUNCTION_GET_DISPLAY_NAME, + HWC2_FUNCTION_GET_DISPLAY_REQUESTS, + HWC2_FUNCTION_GET_DISPLAY_TYPE, + HWC2_FUNCTION_GET_DOZE_SUPPORT, + HWC2_FUNCTION_GET_HDR_CAPABILITIES, + HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT, + HWC2_FUNCTION_GET_RELEASE_FENCES, + HWC2_FUNCTION_PRESENT_DISPLAY, + HWC2_FUNCTION_REGISTER_CALLBACK, + HWC2_FUNCTION_SET_ACTIVE_CONFIG, + HWC2_FUNCTION_SET_CLIENT_TARGET, + HWC2_FUNCTION_SET_COLOR_MODE, + HWC2_FUNCTION_SET_COLOR_TRANSFORM, + HWC2_FUNCTION_SET_CURSOR_POSITION, + HWC2_FUNCTION_SET_LAYER_BLEND_MODE, + HWC2_FUNCTION_SET_LAYER_BUFFER, + HWC2_FUNCTION_SET_LAYER_COLOR, + HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE, + HWC2_FUNCTION_SET_LAYER_DATASPACE, + HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME, + HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA, + HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM, + HWC2_FUNCTION_SET_LAYER_SOURCE_CROP, + HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE, + HWC2_FUNCTION_SET_LAYER_TRANSFORM, + HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION, + HWC2_FUNCTION_SET_LAYER_Z_ORDER, + HWC2_FUNCTION_SET_OUTPUT_BUFFER, + HWC2_FUNCTION_SET_POWER_MODE, + HWC2_FUNCTION_SET_VSYNC_ENABLED, + HWC2_FUNCTION_VALIDATE_DISPLAY, + HWC2_FUNCTION_SET_LAYER_FLOAT_COLOR, + HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA, + HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS, + HWC2_FUNCTION_SET_READBACK_BUFFER, + HWC2_FUNCTION_GET_READBACK_BUFFER_ATTRIBUTES, + HWC2_FUNCTION_GET_READBACK_BUFFER_FENCE, + HWC2_FUNCTION_GET_RENDER_INTENTS, + HWC2_FUNCTION_SET_COLOR_MODE_WITH_RENDER_INTENT, + HWC2_FUNCTION_GET_DATASPACE_SATURATION_MATRIX, + + // composer 2.3 + HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA, + HWC2_FUNCTION_GET_DISPLAY_CAPABILITIES, + HWC2_FUNCTION_SET_LAYER_COLOR_TRANSFORM, + HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES, + HWC2_FUNCTION_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED, + HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLE, + HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS, + HWC2_FUNCTION_GET_DISPLAY_BRIGHTNESS_SUPPORT, + HWC2_FUNCTION_SET_DISPLAY_BRIGHTNESS, + + // composer 2.4 + HWC2_FUNCTION_GET_DISPLAY_CONNECTION_TYPE, + HWC2_FUNCTION_GET_DISPLAY_VSYNC_PERIOD, + HWC2_FUNCTION_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS, + HWC2_FUNCTION_SET_AUTO_LOW_LATENCY_MODE, + HWC2_FUNCTION_GET_SUPPORTED_CONTENT_TYPES, + HWC2_FUNCTION_SET_CONTENT_TYPE, + HWC2_FUNCTION_GET_CLIENT_TARGET_PROPERTY, + HWC2_FUNCTION_SET_LAYER_GENERIC_METADATA, + HWC2_FUNCTION_GET_LAYER_GENERIC_METADATA_KEY, +} hwc2_function_descriptor_t; + +/* Layer requests returned from getDisplayRequests */ +typedef enum { + /* The client should clear its target with transparent pixels where this + * layer would be. The client may ignore this request if the layer must be + * blended. */ + HWC2_LAYER_REQUEST_CLEAR_CLIENT_TARGET = 1 << 0, +} hwc2_layer_request_t; + +/* Power modes for use with setPowerMode */ +typedef enum { + /* The display is fully off (blanked) */ + HWC2_POWER_MODE_OFF = 0, + + /* These are optional low power modes. getDozeSupport may be called to + * determine whether a given display supports these modes. */ + + /* The display is turned on and configured in a low power state that is + * suitable for presenting ambient information to the user, possibly with + * lower fidelity than HWC2_POWER_MODE_ON, but with greater efficiency. */ + HWC2_POWER_MODE_DOZE = 1, + + /* The display is configured as in HWC2_POWER_MODE_DOZE but may stop + * applying display updates from the client. This is effectively a hint to + * the device that drawing to the display has been suspended and that the + * the device should remain on in a low power state and continue displaying + * its current contents indefinitely until the power mode changes. + * + * This mode may also be used as a signal to enable hardware-based doze + * functionality. In this case, the device is free to take over the display + * and manage it autonomously to implement a low power always-on display. */ + HWC2_POWER_MODE_DOZE_SUSPEND = 3, + + /* The display is fully on */ + HWC2_POWER_MODE_ON = 2, +} hwc2_power_mode_t; + +typedef enum { + HWC2_CONTENT_TYPE_NONE = 0, + HWC2_CONTENT_TYPE_GRAPHICS = 1, + HWC2_CONTENT_TYPE_PHOTO = 2, + HWC2_CONTENT_TYPE_CINEMA = 3, + HWC2_CONTENT_TYPE_GAME = 4, +} hwc2_content_type_t; + +/* Vsync values passed to setVsyncEnabled */ +typedef enum { + HWC2_VSYNC_INVALID = 0, + + /* Enable vsync */ + HWC2_VSYNC_ENABLE = 1, + + /* Disable vsync */ + HWC2_VSYNC_DISABLE = 2, +} hwc2_vsync_t; + +/* MUST match HIDL's V2_2::IComposerClient::PerFrameMetadataKey */ +typedef enum { + /* SMPTE ST 2084:2014. + * Coordinates defined in CIE 1931 xy chromaticity space + */ + HWC2_DISPLAY_RED_PRIMARY_X = 0, + HWC2_DISPLAY_RED_PRIMARY_Y = 1, + HWC2_DISPLAY_GREEN_PRIMARY_X = 2, + HWC2_DISPLAY_GREEN_PRIMARY_Y = 3, + HWC2_DISPLAY_BLUE_PRIMARY_X = 4, + HWC2_DISPLAY_BLUE_PRIMARY_Y = 5, + HWC2_WHITE_POINT_X = 6, + HWC2_WHITE_POINT_Y = 7, + /* SMPTE ST 2084:2014. + * Units: nits + * max as defined by ST 2048: 10,000 nits + */ + HWC2_MAX_LUMINANCE = 8, + HWC2_MIN_LUMINANCE = 9, + + /* CTA 861.3 + * Units: nits + */ + HWC2_MAX_CONTENT_LIGHT_LEVEL = 10, + HWC2_MAX_FRAME_AVERAGE_LIGHT_LEVEL = 11, +} hwc2_per_frame_metadata_key_t; + +/* SetDisplayedContentSampling values passed to setDisplayedContentSamplingEnabled */ +typedef enum { + HWC2_DISPLAYED_CONTENT_SAMPLING_INVALID = 0, + + /* Enable displayed content sampling */ + HWC2_DISPLAYED_CONTENT_SAMPLING_ENABLE = 1, + + /* Disable displayed content sampling */ + HWC2_DISPLAYED_CONTENT_SAMPLING_DISABLE = 2, +} hwc2_displayed_content_sampling_t; + +typedef enum { + HWC2_FORMAT_COMPONENT_0 = 1 << 0, /* The first component (eg, for RGBA_8888, this is R) */ + HWC2_FORMAT_COMPONENT_1 = 1 << 1, /* The second component (eg, for RGBA_8888, this is G) */ + HWC2_FORMAT_COMPONENT_2 = 1 << 2, /* The third component (eg, for RGBA_8888, this is B) */ + HWC2_FORMAT_COMPONENT_3 = 1 << 3, /* The fourth component (eg, for RGBA_8888, this is A) */ +} hwc2_format_color_component_t; + +/* Optional display capabilities which may be supported by some displays. + * The particular set of supported capabilities for a given display may be + * retrieved using getDisplayCapabilities. */ +typedef enum { + HWC2_DISPLAY_CAPABILITY_INVALID = 0, + + /** + * Specifies that the display must apply a color transform even when either + * the client or the device has chosen that all layers should be composed by + * the client. This prevents the client from applying the color transform + * during its composition step. + * If getDisplayCapabilities is supported, the global capability + * HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM is ignored. + * If getDisplayCapabilities is not supported, and the global capability + * HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM is returned by getCapabilities, + * then all displays must be treated as having + * HWC2_DISPLAY_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM. + */ + HWC2_DISPLAY_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM = 1, + + /** + * Specifies that the display supports PowerMode::DOZE and + * PowerMode::DOZE_SUSPEND. DOZE_SUSPEND may not provide any benefit + * over DOZE (see the definition of PowerMode for more information), + * but if both DOZE and DOZE_SUSPEND are no different from + * PowerMode::ON, the device must not claim support. + * HWC2_DISPLAY_CAPABILITY_DOZE must be returned by getDisplayCapabilities + * when getDozeSupport indicates the display supports PowerMode::DOZE and + * PowerMode::DOZE_SUSPEND. + */ + HWC2_DISPLAY_CAPABILITY_DOZE = 2, + + /** + * Specified that the display supports brightness operations. + */ + HWC2_DISPLAY_CAPABILITY_BRIGHTNESS = 3, + + /** + * Specifies that the display supports a low latency mode. If the connection + * to the display is via HDMI, this specifies whether Auto Low Latency Mode + * is supported. If, instead, there is an internal connection to the display, + * then this specifies that the display has some other custom low latency + * mode. + */ + HWC2_DISPLAY_CAPABILITY_AUTO_LOW_LATENCY_MODE = 5, +} hwc2_display_capability_t; + +/* + * Stringification Functions + */ + +#ifdef HWC2_INCLUDE_STRINGIFICATION + +static inline const char* getAttributeName(hwc2_attribute_t attribute) { + switch (attribute) { + case HWC2_ATTRIBUTE_INVALID: return "Invalid"; + case HWC2_ATTRIBUTE_WIDTH: return "Width"; + case HWC2_ATTRIBUTE_HEIGHT: return "Height"; + case HWC2_ATTRIBUTE_VSYNC_PERIOD: return "VsyncPeriod"; + case HWC2_ATTRIBUTE_DPI_X: return "DpiX"; + case HWC2_ATTRIBUTE_DPI_Y: return "DpiY"; + case HWC2_ATTRIBUTE_CONFIG_GROUP: return "ConfigGroup"; + default: return "Unknown"; + } +} + +static inline const char* getBlendModeName(hwc2_blend_mode_t mode) { + switch (mode) { + case HWC2_BLEND_MODE_INVALID: return "Invalid"; + case HWC2_BLEND_MODE_NONE: return "None"; + case HWC2_BLEND_MODE_PREMULTIPLIED: return "Premultiplied"; + case HWC2_BLEND_MODE_COVERAGE: return "Coverage"; + default: return "Unknown"; + } +} + +static inline const char* getCallbackDescriptorName( + hwc2_callback_descriptor_t desc) { + switch (desc) { + case HWC2_CALLBACK_INVALID: return "Invalid"; + case HWC2_CALLBACK_HOTPLUG: return "Hotplug"; + case HWC2_CALLBACK_REFRESH: return "Refresh"; + case HWC2_CALLBACK_VSYNC: return "Vsync"; + case HWC2_CALLBACK_VSYNC_2_4: return "Vsync2.4"; + case HWC2_CALLBACK_VSYNC_PERIOD_TIMING_CHANGED: return "VsyncPeriodTimingChanged"; + case HWC2_CALLBACK_SEAMLESS_POSSIBLE: return "SeamlessPossible"; + default: return "Unknown"; + } +} + +static inline const char* getCapabilityName(hwc2_capability_t capability) { + switch (capability) { + case HWC2_CAPABILITY_INVALID: return "Invalid"; + case HWC2_CAPABILITY_SIDEBAND_STREAM: return "SidebandStream"; + case HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM: + return "SkipClientColorTransform"; + case HWC2_CAPABILITY_PRESENT_FENCE_IS_NOT_RELIABLE: + return "PresentFenceIsNotReliable"; + default: return "Unknown"; + } +} + +static inline const char* getCompositionName(hwc2_composition_t composition) { + switch (composition) { + case HWC2_COMPOSITION_INVALID: return "Invalid"; + case HWC2_COMPOSITION_CLIENT: return "Client"; + case HWC2_COMPOSITION_DEVICE: return "Device"; + case HWC2_COMPOSITION_SOLID_COLOR: return "SolidColor"; + case HWC2_COMPOSITION_CURSOR: return "Cursor"; + case HWC2_COMPOSITION_SIDEBAND: return "Sideband"; + default: return "Unknown"; + } +} + +static inline const char* getConnectionName(hwc2_connection_t connection) { + switch (connection) { + case HWC2_CONNECTION_INVALID: return "Invalid"; + case HWC2_CONNECTION_CONNECTED: return "Connected"; + case HWC2_CONNECTION_DISCONNECTED: return "Disconnected"; + default: return "Unknown"; + } +} + +static inline const char* getDisplayRequestName( + hwc2_display_request_t request) { + switch (__BIONIC_CAST(static_cast, int, request)) { + case 0: return "None"; + case HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET: return "FlipClientTarget"; + case HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT: + return "WriteClientTargetToOutput"; + case HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET | + HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT: + return "FlipClientTarget|WriteClientTargetToOutput"; + default: return "Unknown"; + } +} + +static inline const char* getDisplayTypeName(hwc2_display_type_t type) { + switch (type) { + case HWC2_DISPLAY_TYPE_INVALID: return "Invalid"; + case HWC2_DISPLAY_TYPE_PHYSICAL: return "Physical"; + case HWC2_DISPLAY_TYPE_VIRTUAL: return "Virtual"; + default: return "Unknown"; + } +} + +static inline const char* getDisplayConnectionTypeName(hwc2_display_connection_type_t type) { + switch (type) { + case HWC2_DISPLAY_CONNECTION_TYPE_INTERNAL: return "Internal"; + case HWC2_DISPLAY_CONNECTION_TYPE_EXTERNAL: return "External"; + default: return "Unknown"; + } +} + +static inline const char* getErrorName(hwc2_error_t error) { + switch (error) { + case HWC2_ERROR_NONE: return "None"; + case HWC2_ERROR_BAD_CONFIG: return "BadConfig"; + case HWC2_ERROR_BAD_DISPLAY: return "BadDisplay"; + case HWC2_ERROR_BAD_LAYER: return "BadLayer"; + case HWC2_ERROR_BAD_PARAMETER: return "BadParameter"; + case HWC2_ERROR_HAS_CHANGES: return "HasChanges"; + case HWC2_ERROR_NO_RESOURCES: return "NoResources"; + case HWC2_ERROR_NOT_VALIDATED: return "NotValidated"; + case HWC2_ERROR_UNSUPPORTED: return "Unsupported"; + case HWC2_ERROR_SEAMLESS_NOT_ALLOWED: return "SeamlessNotAllowed"; + case HWC2_ERROR_SEAMLESS_NOT_POSSIBLE: return "SeamlessNotPossible"; + default: return "Unknown"; + } +} + +static inline const char* getFunctionDescriptorName( + hwc2_function_descriptor_t desc) { + switch (desc) { + case HWC2_FUNCTION_INVALID: return "Invalid"; + case HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES: + return "AcceptDisplayChanges"; + case HWC2_FUNCTION_CREATE_LAYER: return "CreateLayer"; + case HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY: + return "CreateVirtualDisplay"; + case HWC2_FUNCTION_DESTROY_LAYER: return "DestroyLayer"; + case HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY: + return "DestroyVirtualDisplay"; + case HWC2_FUNCTION_DUMP: return "Dump"; + case HWC2_FUNCTION_GET_ACTIVE_CONFIG: return "GetActiveConfig"; + case HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES: + return "GetChangedCompositionTypes"; + case HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT: + return "GetClientTargetSupport"; + case HWC2_FUNCTION_GET_COLOR_MODES: return "GetColorModes"; + case HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE: return "GetDisplayAttribute"; + case HWC2_FUNCTION_GET_DISPLAY_CONFIGS: return "GetDisplayConfigs"; + case HWC2_FUNCTION_GET_DISPLAY_NAME: return "GetDisplayName"; + case HWC2_FUNCTION_GET_DISPLAY_REQUESTS: return "GetDisplayRequests"; + case HWC2_FUNCTION_GET_DISPLAY_TYPE: return "GetDisplayType"; + case HWC2_FUNCTION_GET_DOZE_SUPPORT: return "GetDozeSupport"; + case HWC2_FUNCTION_GET_HDR_CAPABILITIES: return "GetHdrCapabilities"; + case HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT: + return "GetMaxVirtualDisplayCount"; + case HWC2_FUNCTION_GET_RELEASE_FENCES: return "GetReleaseFences"; + case HWC2_FUNCTION_PRESENT_DISPLAY: return "PresentDisplay"; + case HWC2_FUNCTION_REGISTER_CALLBACK: return "RegisterCallback"; + case HWC2_FUNCTION_SET_ACTIVE_CONFIG: return "SetActiveConfig"; + case HWC2_FUNCTION_SET_CLIENT_TARGET: return "SetClientTarget"; + case HWC2_FUNCTION_SET_COLOR_MODE: return "SetColorMode"; + case HWC2_FUNCTION_SET_COLOR_TRANSFORM: return "SetColorTransform"; + case HWC2_FUNCTION_SET_CURSOR_POSITION: return "SetCursorPosition"; + case HWC2_FUNCTION_SET_LAYER_BLEND_MODE: return "SetLayerBlendMode"; + case HWC2_FUNCTION_SET_LAYER_BUFFER: return "SetLayerBuffer"; + case HWC2_FUNCTION_SET_LAYER_COLOR: return "SetLayerColor"; + case HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE: + return "SetLayerCompositionType"; + case HWC2_FUNCTION_SET_LAYER_DATASPACE: return "SetLayerDataspace"; + case HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME: + return "SetLayerDisplayFrame"; + case HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA: return "SetLayerPlaneAlpha"; + case HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM: + return "SetLayerSidebandStream"; + case HWC2_FUNCTION_SET_LAYER_SOURCE_CROP: return "SetLayerSourceCrop"; + case HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE: + return "SetLayerSurfaceDamage"; + case HWC2_FUNCTION_SET_LAYER_TRANSFORM: return "SetLayerTransform"; + case HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION: + return "SetLayerVisibleRegion"; + case HWC2_FUNCTION_SET_LAYER_Z_ORDER: return "SetLayerZOrder"; + case HWC2_FUNCTION_SET_OUTPUT_BUFFER: return "SetOutputBuffer"; + case HWC2_FUNCTION_SET_POWER_MODE: return "SetPowerMode"; + case HWC2_FUNCTION_SET_VSYNC_ENABLED: return "SetVsyncEnabled"; + case HWC2_FUNCTION_VALIDATE_DISPLAY: return "ValidateDisplay"; + case HWC2_FUNCTION_SET_LAYER_FLOAT_COLOR: return "SetLayerFloatColor"; + case HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA: return "SetLayerPerFrameMetadata"; + case HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS: return "GetPerFrameMetadataKeys"; + case HWC2_FUNCTION_SET_READBACK_BUFFER: return "SetReadbackBuffer"; + case HWC2_FUNCTION_GET_READBACK_BUFFER_ATTRIBUTES: return "GetReadbackBufferAttributes"; + case HWC2_FUNCTION_GET_READBACK_BUFFER_FENCE: return "GetReadbackBufferFence"; + case HWC2_FUNCTION_GET_RENDER_INTENTS: return "GetRenderIntents"; + case HWC2_FUNCTION_SET_COLOR_MODE_WITH_RENDER_INTENT: return "SetColorModeWithRenderIntent"; + case HWC2_FUNCTION_GET_DATASPACE_SATURATION_MATRIX: return "GetDataspaceSaturationMatrix"; + + // composer 2.3 + case HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA: return "GetDisplayIdentificationData"; + case HWC2_FUNCTION_GET_DISPLAY_CAPABILITIES: return "GetDisplayCapabilities"; + case HWC2_FUNCTION_SET_LAYER_COLOR_TRANSFORM: return "SetLayerColorTransform"; + case HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES: return "GetDisplayedContentSamplingAttributes"; + case HWC2_FUNCTION_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED: return "SetDisplayedContentSamplingEnabled"; + case HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLE: return "GetDisplayedContentSample"; + case HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS: return "SetLayerPerFrameMetadataBlobs"; + case HWC2_FUNCTION_GET_DISPLAY_BRIGHTNESS_SUPPORT: return "GetDisplayBrightnessSupport"; + case HWC2_FUNCTION_SET_DISPLAY_BRIGHTNESS: return "SetDisplayBrightness"; + + // composer 2.4 + case HWC2_FUNCTION_GET_DISPLAY_CONNECTION_TYPE: return "GetDisplayConnectionType"; + case HWC2_FUNCTION_GET_DISPLAY_VSYNC_PERIOD: return "GetDisplayVsyncPeriod"; + case HWC2_FUNCTION_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS: return "SetActiveConfigWithConstraints"; + case HWC2_FUNCTION_SET_AUTO_LOW_LATENCY_MODE: return "SetAutoLowLatencyMode"; + case HWC2_FUNCTION_GET_SUPPORTED_CONTENT_TYPES: return "GetSupportedContentTypes"; + case HWC2_FUNCTION_SET_CONTENT_TYPE: return "SetContentType"; + case HWC2_FUNCTION_GET_CLIENT_TARGET_PROPERTY: return "GetClientTargetProperty"; + case HWC2_FUNCTION_SET_LAYER_GENERIC_METADATA: return "SetLayerGenericMetadata"; + case HWC2_FUNCTION_GET_LAYER_GENERIC_METADATA_KEY: return "GetLayerGenericMetadataKey"; + + default: return "Unknown"; + } +} + +static inline const char* getLayerRequestName(hwc2_layer_request_t request) { + switch (__BIONIC_CAST(static_cast, int, request)) { + case 0: return "None"; + case HWC2_LAYER_REQUEST_CLEAR_CLIENT_TARGET: return "ClearClientTarget"; + default: return "Unknown"; + } +} + +static inline const char* getPowerModeName(hwc2_power_mode_t mode) { + switch (mode) { + case HWC2_POWER_MODE_OFF: return "Off"; + case HWC2_POWER_MODE_DOZE_SUSPEND: return "DozeSuspend"; + case HWC2_POWER_MODE_DOZE: return "Doze"; + case HWC2_POWER_MODE_ON: return "On"; + default: return "Unknown"; + } +} + +static inline const char* getContentTypeName(hwc2_content_type_t contentType) { + switch(contentType) { + case HWC2_CONTENT_TYPE_NONE: return "None"; + case HWC2_CONTENT_TYPE_GRAPHICS: return "Graphics"; + case HWC2_CONTENT_TYPE_PHOTO: return "Photo"; + case HWC2_CONTENT_TYPE_CINEMA: return "Cinema"; + case HWC2_CONTENT_TYPE_GAME: return "Game"; + default: return "Unknown"; + } +} + +static inline const char* getTransformName(hwc_transform_t transform) { + switch (__BIONIC_CAST(static_cast, int, transform)) { + case 0: return "None"; + case HWC_TRANSFORM_FLIP_H: return "FlipH"; + case HWC_TRANSFORM_FLIP_V: return "FlipV"; + case HWC_TRANSFORM_ROT_90: return "Rotate90"; + case HWC_TRANSFORM_ROT_180: return "Rotate180"; + case HWC_TRANSFORM_ROT_270: return "Rotate270"; + case HWC_TRANSFORM_FLIP_H_ROT_90: return "FlipHRotate90"; + case HWC_TRANSFORM_FLIP_V_ROT_90: return "FlipVRotate90"; + default: return "Unknown"; + } +} + +static inline const char* getVsyncName(hwc2_vsync_t vsync) { + switch (vsync) { + case HWC2_VSYNC_INVALID: return "Invalid"; + case HWC2_VSYNC_ENABLE: return "Enable"; + case HWC2_VSYNC_DISABLE: return "Disable"; + default: return "Unknown"; + } +} + +static inline const char* getDisplayedContentSamplingName( + hwc2_displayed_content_sampling_t sampling) { + switch (sampling) { + case HWC2_DISPLAYED_CONTENT_SAMPLING_INVALID: return "Invalid"; + case HWC2_DISPLAYED_CONTENT_SAMPLING_ENABLE: return "Enable"; + case HWC2_DISPLAYED_CONTENT_SAMPLING_DISABLE: return "Disable"; + default: return "Unknown"; + } +} + +static inline const char* getFormatColorComponentName(hwc2_format_color_component_t component) { + switch (component) { + case HWC2_FORMAT_COMPONENT_0: return "FirstComponent"; + case HWC2_FORMAT_COMPONENT_1: return "SecondComponent"; + case HWC2_FORMAT_COMPONENT_2: return "ThirdComponent"; + case HWC2_FORMAT_COMPONENT_3: return "FourthComponent"; + default: return "Unknown"; + } +} + +static inline const char* getDisplayCapabilityName(hwc2_display_capability_t capability) { + switch (capability) { + case HWC2_DISPLAY_CAPABILITY_INVALID: return "Invalid"; + case HWC2_DISPLAY_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM: + return "SkipClientColorTransform"; + case HWC2_DISPLAY_CAPABILITY_DOZE: + return "Doze"; + case HWC2_DISPLAY_CAPABILITY_BRIGHTNESS: + return "Brightness"; + case HWC2_DISPLAY_CAPABILITY_AUTO_LOW_LATENCY_MODE: + return "AutoLowLatencyMode"; + default: + return "Unknown"; + } +} + +#define TO_STRING(E, T, printer) \ + inline std::string to_string(E value) { return printer(value); } \ + inline std::string to_string(T value) { return to_string(static_cast<E>(value)); } +#else // !HWC2_INCLUDE_STRINGIFICATION +#define TO_STRING(name, printer) +#endif // HWC2_INCLUDE_STRINGIFICATION + +/* + * C++11 features + */ + +#ifdef HWC2_USE_CPP11 +__END_DECLS + +#ifdef HWC2_INCLUDE_STRINGIFICATION +#include <string> +#endif + +namespace HWC2 { + +enum class Attribute : int32_t { + Invalid = HWC2_ATTRIBUTE_INVALID, + Width = HWC2_ATTRIBUTE_WIDTH, + Height = HWC2_ATTRIBUTE_HEIGHT, + VsyncPeriod = HWC2_ATTRIBUTE_VSYNC_PERIOD, + DpiX = HWC2_ATTRIBUTE_DPI_X, + DpiY = HWC2_ATTRIBUTE_DPI_Y, + ConfigGroup = HWC2_ATTRIBUTE_CONFIG_GROUP, +}; +TO_STRING(hwc2_attribute_t, Attribute, getAttributeName) + +enum class BlendMode : int32_t { + Invalid = HWC2_BLEND_MODE_INVALID, + None = HWC2_BLEND_MODE_NONE, + Premultiplied = HWC2_BLEND_MODE_PREMULTIPLIED, + Coverage = HWC2_BLEND_MODE_COVERAGE, +}; +TO_STRING(hwc2_blend_mode_t, BlendMode, getBlendModeName) + +enum class Callback : int32_t { + Invalid = HWC2_CALLBACK_INVALID, + Hotplug = HWC2_CALLBACK_HOTPLUG, + Refresh = HWC2_CALLBACK_REFRESH, + Vsync = HWC2_CALLBACK_VSYNC, + Vsync_2_4 = HWC2_CALLBACK_VSYNC_2_4, + VsyncPeriodTimingChanged = HWC2_CALLBACK_VSYNC_PERIOD_TIMING_CHANGED, + SeamlessPossible = HWC2_CALLBACK_SEAMLESS_POSSIBLE, +}; +TO_STRING(hwc2_callback_descriptor_t, Callback, getCallbackDescriptorName) + +enum class Capability : int32_t { + Invalid = HWC2_CAPABILITY_INVALID, + SidebandStream = HWC2_CAPABILITY_SIDEBAND_STREAM, + SkipClientColorTransform = HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM, + PresentFenceIsNotReliable = HWC2_CAPABILITY_PRESENT_FENCE_IS_NOT_RELIABLE, + SkipValidate = HWC2_CAPABILITY_SKIP_VALIDATE, +}; +TO_STRING(hwc2_capability_t, Capability, getCapabilityName) + +enum class Composition : int32_t { + Invalid = HWC2_COMPOSITION_INVALID, + Client = HWC2_COMPOSITION_CLIENT, + Device = HWC2_COMPOSITION_DEVICE, + SolidColor = HWC2_COMPOSITION_SOLID_COLOR, + Cursor = HWC2_COMPOSITION_CURSOR, + Sideband = HWC2_COMPOSITION_SIDEBAND, +}; +TO_STRING(hwc2_composition_t, Composition, getCompositionName) + +enum class Connection : int32_t { + Invalid = HWC2_CONNECTION_INVALID, + Connected = HWC2_CONNECTION_CONNECTED, + Disconnected = HWC2_CONNECTION_DISCONNECTED, +}; +TO_STRING(hwc2_connection_t, Connection, getConnectionName) + +enum class DisplayRequest : int32_t { + FlipClientTarget = HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET, + WriteClientTargetToOutput = + HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT, +}; +TO_STRING(hwc2_display_request_t, DisplayRequest, getDisplayRequestName) + +enum class DisplayType : int32_t { + Invalid = HWC2_DISPLAY_TYPE_INVALID, + Physical = HWC2_DISPLAY_TYPE_PHYSICAL, + Virtual = HWC2_DISPLAY_TYPE_VIRTUAL, +}; +TO_STRING(hwc2_display_type_t, DisplayType, getDisplayTypeName) + +enum class DisplayConnectionType : uint32_t { + Internal = HWC2_DISPLAY_CONNECTION_TYPE_INTERNAL, + External = HWC2_DISPLAY_CONNECTION_TYPE_EXTERNAL, +}; +TO_STRING(hwc2_display_connection_type_t, DisplayConnectionType, getDisplayConnectionTypeName) + +enum class Error : int32_t { + None = HWC2_ERROR_NONE, + BadConfig = HWC2_ERROR_BAD_CONFIG, + BadDisplay = HWC2_ERROR_BAD_DISPLAY, + BadLayer = HWC2_ERROR_BAD_LAYER, + BadParameter = HWC2_ERROR_BAD_PARAMETER, + HasChanges = HWC2_ERROR_HAS_CHANGES, + NoResources = HWC2_ERROR_NO_RESOURCES, + NotValidated = HWC2_ERROR_NOT_VALIDATED, + Unsupported = HWC2_ERROR_UNSUPPORTED, + SeamlessNotAllowed = HWC2_ERROR_SEAMLESS_NOT_ALLOWED, + SeamlessNotPossible = HWC2_ERROR_SEAMLESS_NOT_POSSIBLE, +}; +TO_STRING(hwc2_error_t, Error, getErrorName) + +enum class FunctionDescriptor : int32_t { + Invalid = HWC2_FUNCTION_INVALID, + AcceptDisplayChanges = HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES, + CreateLayer = HWC2_FUNCTION_CREATE_LAYER, + CreateVirtualDisplay = HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY, + DestroyLayer = HWC2_FUNCTION_DESTROY_LAYER, + DestroyVirtualDisplay = HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY, + Dump = HWC2_FUNCTION_DUMP, + GetActiveConfig = HWC2_FUNCTION_GET_ACTIVE_CONFIG, + GetChangedCompositionTypes = HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES, + GetClientTargetSupport = HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT, + GetColorModes = HWC2_FUNCTION_GET_COLOR_MODES, + GetDisplayAttribute = HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE, + GetDisplayConfigs = HWC2_FUNCTION_GET_DISPLAY_CONFIGS, + GetDisplayName = HWC2_FUNCTION_GET_DISPLAY_NAME, + GetDisplayRequests = HWC2_FUNCTION_GET_DISPLAY_REQUESTS, + GetDisplayType = HWC2_FUNCTION_GET_DISPLAY_TYPE, + GetDozeSupport = HWC2_FUNCTION_GET_DOZE_SUPPORT, + GetHdrCapabilities = HWC2_FUNCTION_GET_HDR_CAPABILITIES, + GetMaxVirtualDisplayCount = HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT, + GetReleaseFences = HWC2_FUNCTION_GET_RELEASE_FENCES, + PresentDisplay = HWC2_FUNCTION_PRESENT_DISPLAY, + RegisterCallback = HWC2_FUNCTION_REGISTER_CALLBACK, + SetActiveConfig = HWC2_FUNCTION_SET_ACTIVE_CONFIG, + SetClientTarget = HWC2_FUNCTION_SET_CLIENT_TARGET, + SetColorMode = HWC2_FUNCTION_SET_COLOR_MODE, + SetColorTransform = HWC2_FUNCTION_SET_COLOR_TRANSFORM, + SetCursorPosition = HWC2_FUNCTION_SET_CURSOR_POSITION, + SetLayerBlendMode = HWC2_FUNCTION_SET_LAYER_BLEND_MODE, + SetLayerBuffer = HWC2_FUNCTION_SET_LAYER_BUFFER, + SetLayerColor = HWC2_FUNCTION_SET_LAYER_COLOR, + SetLayerCompositionType = HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE, + SetLayerDataspace = HWC2_FUNCTION_SET_LAYER_DATASPACE, + SetLayerDisplayFrame = HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME, + SetLayerPlaneAlpha = HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA, + SetLayerSidebandStream = HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM, + SetLayerSourceCrop = HWC2_FUNCTION_SET_LAYER_SOURCE_CROP, + SetLayerSurfaceDamage = HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE, + SetLayerTransform = HWC2_FUNCTION_SET_LAYER_TRANSFORM, + SetLayerVisibleRegion = HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION, + SetLayerZOrder = HWC2_FUNCTION_SET_LAYER_Z_ORDER, + SetOutputBuffer = HWC2_FUNCTION_SET_OUTPUT_BUFFER, + SetPowerMode = HWC2_FUNCTION_SET_POWER_MODE, + SetVsyncEnabled = HWC2_FUNCTION_SET_VSYNC_ENABLED, + ValidateDisplay = HWC2_FUNCTION_VALIDATE_DISPLAY, + SetLayerFloatColor = HWC2_FUNCTION_SET_LAYER_FLOAT_COLOR, + SetLayerPerFrameMetadata = HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA, + GetPerFrameMetadataKeys = HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS, + SetReadbackBuffer = HWC2_FUNCTION_SET_READBACK_BUFFER, + GetReadbackBufferAttributes = HWC2_FUNCTION_GET_READBACK_BUFFER_ATTRIBUTES, + GetReadbackBufferFence = HWC2_FUNCTION_GET_READBACK_BUFFER_FENCE, + GetRenderIntents = HWC2_FUNCTION_GET_RENDER_INTENTS, + SetColorModeWithRenderIntent = HWC2_FUNCTION_SET_COLOR_MODE_WITH_RENDER_INTENT, + GetDataspaceSaturationMatrix = HWC2_FUNCTION_GET_DATASPACE_SATURATION_MATRIX, + + // composer 2.3 + GetDisplayIdentificationData = HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA, + GetDisplayCapabilities = HWC2_FUNCTION_GET_DISPLAY_CAPABILITIES, + SetLayerColorTransform = HWC2_FUNCTION_SET_LAYER_COLOR_TRANSFORM, + GetDisplayedContentSamplingAttributes = HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES, + SetDisplayedContentSamplingEnabled = HWC2_FUNCTION_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED, + GetDisplayedContentSample = HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLE, + SetLayerPerFrameMetadataBlobs = HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS, + GetDisplayBrightnessSupport = HWC2_FUNCTION_GET_DISPLAY_BRIGHTNESS_SUPPORT, + SetDisplayBrightness = HWC2_FUNCTION_SET_DISPLAY_BRIGHTNESS, + + // composer 2.4 + GetDisplayConnectionType = HWC2_FUNCTION_GET_DISPLAY_CONNECTION_TYPE, + GetDisplayVsyncPeriod = HWC2_FUNCTION_GET_DISPLAY_VSYNC_PERIOD, + SetActiveConfigWithConstraints = HWC2_FUNCTION_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS, + SetAutoLowLatencyMode = HWC2_FUNCTION_SET_AUTO_LOW_LATENCY_MODE, + GetSupportedContentTypes = HWC2_FUNCTION_GET_SUPPORTED_CONTENT_TYPES, + SetContentType = HWC2_FUNCTION_SET_CONTENT_TYPE, + GetClientTargetProperty = HWC2_FUNCTION_GET_CLIENT_TARGET_PROPERTY, + SetLayerGenericMetadata = HWC2_FUNCTION_SET_LAYER_GENERIC_METADATA, + GetLayerGenericMetadataKey = HWC2_FUNCTION_GET_LAYER_GENERIC_METADATA_KEY, +}; +TO_STRING(hwc2_function_descriptor_t, FunctionDescriptor, + getFunctionDescriptorName) + +enum class LayerRequest : int32_t { + ClearClientTarget = HWC2_LAYER_REQUEST_CLEAR_CLIENT_TARGET, +}; +TO_STRING(hwc2_layer_request_t, LayerRequest, getLayerRequestName) + +enum class PowerMode : int32_t { + Off = HWC2_POWER_MODE_OFF, + DozeSuspend = HWC2_POWER_MODE_DOZE_SUSPEND, + Doze = HWC2_POWER_MODE_DOZE, + On = HWC2_POWER_MODE_ON, +}; +TO_STRING(hwc2_power_mode_t, PowerMode, getPowerModeName) + +enum class ContentType : int32_t { + None = HWC2_CONTENT_TYPE_NONE, + Graphics = HWC2_CONTENT_TYPE_GRAPHICS, + Photo = HWC2_CONTENT_TYPE_PHOTO, + Cinema = HWC2_CONTENT_TYPE_CINEMA, + Game = HWC2_CONTENT_TYPE_GAME, +}; +TO_STRING(hwc2_content_type_t, ContentType, getContentTypeName) + +enum class Transform : int32_t { + None = 0, + FlipH = HWC_TRANSFORM_FLIP_H, + FlipV = HWC_TRANSFORM_FLIP_V, + Rotate90 = HWC_TRANSFORM_ROT_90, + Rotate180 = HWC_TRANSFORM_ROT_180, + Rotate270 = HWC_TRANSFORM_ROT_270, + FlipHRotate90 = HWC_TRANSFORM_FLIP_H_ROT_90, + FlipVRotate90 = HWC_TRANSFORM_FLIP_V_ROT_90, +}; +TO_STRING(hwc_transform_t, Transform, getTransformName) + +enum class Vsync : int32_t { + Invalid = HWC2_VSYNC_INVALID, + Enable = HWC2_VSYNC_ENABLE, + Disable = HWC2_VSYNC_DISABLE, +}; +TO_STRING(hwc2_vsync_t, Vsync, getVsyncName) + +enum class DisplayCapability : int32_t { + Invalid = HWC2_DISPLAY_CAPABILITY_INVALID, + SkipClientColorTransform = HWC2_DISPLAY_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM, + Doze = HWC2_DISPLAY_CAPABILITY_DOZE, + Brightness = HWC2_DISPLAY_CAPABILITY_BRIGHTNESS, + AutoLowLatencyMode = HWC2_DISPLAY_CAPABILITY_AUTO_LOW_LATENCY_MODE, +}; +TO_STRING(hwc2_display_capability_t, DisplayCapability, getDisplayCapabilityName) + +} // namespace HWC2 + +__BEGIN_DECLS +#endif // HWC2_USE_CPP11 + +/* + * Typedefs + */ + +typedef void (*hwc2_function_pointer_t)(); + +typedef void* hwc2_callback_data_t; +typedef uint32_t hwc2_config_t; +typedef uint64_t hwc2_display_t; +typedef uint64_t hwc2_layer_t; +typedef uint32_t hwc2_vsync_period_t; + +/* + * Device Struct + */ + +typedef struct hwc2_device { + /* Must be the first member of this struct, since a pointer to this struct + * will be generated by casting from a hw_device_t* */ + struct hw_device_t common; + + /* getCapabilities(..., outCount, outCapabilities) + * + * Provides a list of capabilities (described in the definition of + * hwc2_capability_t above) supported by this device. This list must + * not change after the device has been loaded. + * + * Parameters: + * outCount - if outCapabilities was NULL, the number of capabilities + * which would have been returned; if outCapabilities was not NULL, + * the number of capabilities returned, which must not exceed the + * value stored in outCount prior to the call + * outCapabilities - a list of capabilities supported by this device; may + * be NULL, in which case this function must write into outCount the + * number of capabilities which would have been written into + * outCapabilities + */ + void (*getCapabilities)(struct hwc2_device* device, uint32_t* outCount, + int32_t* /*hwc2_capability_t*/ outCapabilities); + + /* getFunction(..., descriptor) + * + * Returns a function pointer which implements the requested description. + * + * Parameters: + * descriptor - the function to return + * + * Returns either a function pointer implementing the requested descriptor + * or NULL if the described function is not supported by this device. + */ + hwc2_function_pointer_t (*getFunction)(struct hwc2_device* device, + int32_t /*hwc2_function_descriptor_t*/ descriptor); +} hwc2_device_t; + +static inline int hwc2_open(const struct hw_module_t* module, + hwc2_device_t** device) { + return module->methods->open(module, HWC_HARDWARE_COMPOSER, + TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int hwc2_close(hwc2_device_t* device) { + return device->common.close(&device->common); +} + +/* + * Callbacks + * + * All of these callbacks take as their first parameter the callbackData which + * was provided at the time of callback registration, so this parameter is + * omitted from the described parameter lists. + */ + +/* hotplug(..., display, connected) + * Descriptor: HWC2_CALLBACK_HOTPLUG + * Will be provided to all HWC2 devices + * + * Notifies the client that the given display has either been connected or + * disconnected. Every active display (even a built-in physical display) must + * trigger at least one hotplug notification, even if it only occurs immediately + * after callback registration. + * + * The client may call back into the device on the same thread to query display + * properties (such as width, height, and vsync period), and other threads may + * call into the device while the callback is in progress. The device must + * serialize calls to this callback such that only one thread is calling it at a + * time. + * + * Displays which have been connected are assumed to be in HWC2_POWER_MODE_OFF, + * and the vsync callback should not be called for a display until vsync has + * been enabled with setVsyncEnabled. + * + * Parameters: + * display - the display which has been hotplugged + * connected - whether the display has been connected or disconnected + */ +typedef void (*HWC2_PFN_HOTPLUG)(hwc2_callback_data_t callbackData, + hwc2_display_t display, int32_t /*hwc2_connection_t*/ connected); + +/* refresh(..., display) + * Descriptor: HWC2_CALLBACK_REFRESH + * Will be provided to all HWC2 devices + * + * Notifies the client to trigger a screen refresh. This forces all layer state + * for this display to be resent, and the display to be validated and presented, + * even if there have been no changes. + * + * This refresh will occur some time after the callback is initiated, but not + * necessarily before it returns. This thread, however, is guaranteed not to + * call back into the device, thus it is safe to trigger this callback from + * other functions which call into the device. + * + * Parameters: + * display - the display to refresh + */ +typedef void (*HWC2_PFN_REFRESH)(hwc2_callback_data_t callbackData, + hwc2_display_t display); + +/* vsync(..., display, timestamp) + * Descriptor: HWC2_CALLBACK_VSYNC + * Will be provided to all HWC2 devices + * + * Notifies the client that a vsync event has occurred. This callback must + * only be triggered when vsync is enabled for this display (through + * setVsyncEnabled). + * + * This callback should be triggered from a thread of at least + * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, typically + * less than 0.5 ms. This thread is guaranteed not to call back into the device. + * + * Parameters: + * display - the display which has received a vsync event + * timestamp - the CLOCK_MONOTONIC time at which the vsync event occurred, in + * nanoseconds + */ +typedef void (*HWC2_PFN_VSYNC)(hwc2_callback_data_t callbackData, + hwc2_display_t display, int64_t timestamp); + +/* vsync_2_4(..., display, timestamp, vsyncPeriodNanos) + * Descriptor: HWC2_CALLBACK_VSYNC_2_4 + * Required for HWC2 devices for composer 2.4 + * + * Notifies the client that a vsync event has occurred. This callback must + * only be triggered when vsync is enabled for this display (through + * setVsyncEnabled). + * + * This callback should be triggered from a thread of at least + * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, typically + * less than 0.5 ms. This thread is guaranteed not to call back into the device. + * + * Parameters: + * display - the display which has received a vsync event + * timestamp - the CLOCK_MONOTONIC time at which the vsync event occurred, in + * nanoseconds + * vsyncPeriodNanos - the display vsync period in nanoseconds i.e. the next onVsync2_4 is + * expected to be called vsyncPeriod nanoseconds after this call. + */ +typedef void (*HWC2_PFN_VSYNC_2_4)(hwc2_callback_data_t callbackData, + hwc2_display_t display, int64_t timestamp, hwc2_vsync_period_t vsyncPeriodNanos); + +/* vsyncPeriodTimingChanged(..., display, updated_timeline) + * Descriptor: HWC2_CALLBACK_VSYNC_PERIOD_TIMING_CHANGED + * Optional for HWC2 devices for composer 2.4 + * + * Notifies the client that the previously reported timing for vsync period change has been + * updated. This may occur if the composer missed the deadline for changing the vsync period + * or the client submitted a refresh frame too late. + * + * This callback should be triggered from a thread of at least + * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, typically + * less than 0.5 ms. This thread is guaranteed not to call back into the device. + * + * Parameters: + * display - the display which has received a vsync event + * updated_timeline - new timeline for the vsync period change + */ +typedef void (*HWC2_PFN_VSYNC_PERIOD_TIMING_CHANGED)(hwc2_callback_data_t callbackData, + hwc2_display_t display, hwc_vsync_period_change_timeline_t* updated_timeline); + +/* SeamlessPossible(..., display) + * Descriptor: HWC2_CALLBACK_SEAMLESS_POSSIBLE + * Optional for HWC2 devices for composer 2.4 + * + * Notifies the client that the conditions which previously led to returning SEAMLESS_NOT_POSSIBLE + * from setActiveConfigWithConstraints have changed and now seamless may be possible. Client should + * retry calling setActiveConfigWithConstraints. + * + * + * Parameters: + * display - a display setActiveConfigWithConstraints previously failed with + * SEAMLESS_NOT_POSSIBLE. + */ +typedef void (*HWC2_PFN_SEAMLESS_POSSIBLE)(hwc2_callback_data_t callbackData, + hwc2_display_t display); + +/* + * Device Functions + * + * All of these functions take as their first parameter a device pointer, so + * this parameter is omitted from the described parameter lists. + */ + +/* createVirtualDisplay(..., width, height, format, outDisplay) + * Descriptor: HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY + * Must be provided by all HWC2 devices + * + * Creates a new virtual display with the given width and height. The format + * passed into this function is the default format requested by the consumer of + * the virtual display output buffers. If a different format will be returned by + * the device, it should be returned in this parameter so it can be set properly + * when handing the buffers to the consumer. + * + * The display will be assumed to be on from the time the first frame is + * presented until the display is destroyed. + * + * Parameters: + * width - width in pixels + * height - height in pixels + * format - prior to the call, the default output buffer format selected by + * the consumer; after the call, the format the device will produce + * outDisplay - the newly-created virtual display; pointer will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_UNSUPPORTED - the width or height is too large for the device to + * be able to create a virtual display + * HWC2_ERROR_NO_RESOURCES - the device is unable to create a new virtual + * display at this time + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_CREATE_VIRTUAL_DISPLAY)( + hwc2_device_t* device, uint32_t width, uint32_t height, + int32_t* /*android_pixel_format_t*/ format, hwc2_display_t* outDisplay); + +/* destroyVirtualDisplay(..., display) + * Descriptor: HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY + * Must be provided by all HWC2 devices + * + * Destroys a virtual display. After this call all resources consumed by this + * display may be freed by the device and any operations performed on this + * display should fail. + * + * Parameters: + * display - the virtual display to destroy + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - the display handle which was passed in does not + * refer to a virtual display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_DESTROY_VIRTUAL_DISPLAY)( + hwc2_device_t* device, hwc2_display_t display); + +/* dump(..., outSize, outBuffer) + * Descriptor: HWC2_FUNCTION_DUMP + * Must be provided by all HWC2 devices + * + * Retrieves implementation-defined debug information, which will be displayed + * during, for example, `dumpsys SurfaceFlinger`. + * + * If called with outBuffer == NULL, the device should store a copy of the + * desired output and return its length in bytes in outSize. If the device + * already has a stored copy, that copy should be purged and replaced with a + * fresh copy. + * + * If called with outBuffer != NULL, the device should copy its stored version + * of the output into outBuffer and store how many bytes of data it copied into + * outSize. Prior to this call, the client will have populated outSize with the + * maximum number of bytes outBuffer can hold. The device must not write more + * than this amount into outBuffer. If the device does not currently have a + * stored copy, then it should return 0 in outSize. + * + * Any data written into outBuffer need not be null-terminated. + * + * Parameters: + * outSize - if outBuffer was NULL, the number of bytes needed to copy the + * device's stored output; if outBuffer was not NULL, the number of bytes + * written into it, which must not exceed the value stored in outSize + * prior to the call; pointer will be non-NULL + * outBuffer - the buffer to write the dump output into; may be NULL as + * described above; data written into this buffer need not be + * null-terminated + */ +typedef void (*HWC2_PFN_DUMP)(hwc2_device_t* device, uint32_t* outSize, + char* outBuffer); + +/* getMaxVirtualDisplayCount(...) + * Descriptor: HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT + * Must be provided by all HWC2 devices + * + * Returns the maximum number of virtual displays supported by this device + * (which may be 0). The client will not attempt to create more than this many + * virtual displays on this device. This number must not change for the lifetime + * of the device. + */ +typedef uint32_t (*HWC2_PFN_GET_MAX_VIRTUAL_DISPLAY_COUNT)( + hwc2_device_t* device); + +/* registerCallback(..., descriptor, callbackData, pointer) + * Descriptor: HWC2_FUNCTION_REGISTER_CALLBACK + * Must be provided by all HWC2 devices + * + * Provides a callback for the device to call. All callbacks take a callbackData + * item as the first parameter, so this value should be stored with the callback + * for later use. The callbackData may differ from one callback to another. If + * this function is called multiple times with the same descriptor, later + * callbacks replace earlier ones. + * + * Parameters: + * descriptor - which callback should be set + * callBackdata - opaque data which must be passed back through the callback + * pointer - a non-NULL function pointer corresponding to the descriptor + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_PARAMETER - descriptor was invalid + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_REGISTER_CALLBACK)( + hwc2_device_t* device, + int32_t /*hwc2_callback_descriptor_t*/ descriptor, + hwc2_callback_data_t callbackData, hwc2_function_pointer_t pointer); + +/* getDataspaceSaturationMatrix(..., dataspace, outMatrix) + * Descriptor: HWC2_FUNCTION_GET_DATASPACE_SATURATION_MATRIX + * Provided by HWC2 devices which don't return nullptr function pointer. + * + * Get the saturation matrix of the specified dataspace. The saturation matrix + * can be used to approximate the dataspace saturation operation performed by + * the HWC2 device when non-colorimetric mapping is allowed. It is to be + * applied on linear pixel values. + * + * Parameters: + * dataspace - the dataspace to query for + * outMatrix - a column-major 4x4 matrix (16 floats). It must be an identity + * matrix unless dataspace is HAL_DATASPACE_SRGB_LINEAR. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_PARAMETER - dataspace was invalid + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DATASPACE_SATURATION_MATRIX)( + hwc2_device_t* device, int32_t /*android_dataspace_t*/ dataspace, + float* outMatrix); + +/* + * Display Functions + * + * All of these functions take as their first two parameters a device pointer + * and a display handle, so these parameters are omitted from the described + * parameter lists. + */ + +/* acceptDisplayChanges(...) + * Descriptor: HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES + * Must be provided by all HWC2 devices + * + * Accepts the changes required by the device from the previous validateDisplay + * call (which may be queried using getChangedCompositionTypes) and revalidates + * the display. This function is equivalent to requesting the changed types from + * getChangedCompositionTypes, setting those types on the corresponding layers, + * and then calling validateDisplay again. + * + * After this call it must be valid to present this display. Calling this after + * validateDisplay returns 0 changes must succeed with HWC2_ERROR_NONE, but + * should have no other effect. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_ACCEPT_DISPLAY_CHANGES)( + hwc2_device_t* device, hwc2_display_t display); + +/* createLayer(..., outLayer) + * Descriptor: HWC2_FUNCTION_CREATE_LAYER + * Must be provided by all HWC2 devices + * + * Creates a new layer on the given display. + * + * Parameters: + * outLayer - the handle of the new layer; pointer will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_NO_RESOURCES - the device was unable to create this layer + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_CREATE_LAYER)(hwc2_device_t* device, + hwc2_display_t display, hwc2_layer_t* outLayer); + +/* destroyLayer(..., layer) + * Descriptor: HWC2_FUNCTION_DESTROY_LAYER + * Must be provided by all HWC2 devices + * + * Destroys the given layer. + * + * Parameters: + * layer - the handle of the layer to destroy + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_DESTROY_LAYER)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer); + +/* getActiveConfig(..., outConfig) + * Descriptor: HWC2_FUNCTION_GET_ACTIVE_CONFIG + * Must be provided by all HWC2 devices + * + * Retrieves which display configuration is currently active. + * + * If no display configuration is currently active, this function must return + * HWC2_ERROR_BAD_CONFIG and place no configuration handle in outConfig. It is + * the responsibility of the client to call setActiveConfig with a valid + * configuration before attempting to present anything on the display. + * + * Parameters: + * outConfig - the currently active display configuration; pointer will be + * non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_CONFIG - no configuration is currently active + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_ACTIVE_CONFIG)( + hwc2_device_t* device, hwc2_display_t display, + hwc2_config_t* outConfig); + +/* getChangedCompositionTypes(..., outNumElements, outLayers, outTypes) + * Descriptor: HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES + * Must be provided by all HWC2 devices + * + * Retrieves the layers for which the device requires a different composition + * type than had been set prior to the last call to validateDisplay. The client + * will either update its state with these types and call acceptDisplayChanges, + * or will set new types and attempt to validate the display again. + * + * outLayers and outTypes may be NULL to retrieve the number of elements which + * will be returned. The number of elements returned must be the same as the + * value returned in outNumTypes from the last call to validateDisplay. + * + * Parameters: + * outNumElements - if outLayers or outTypes were NULL, the number of layers + * and types which would have been returned; if both were non-NULL, the + * number of elements returned in outLayers and outTypes, which must not + * exceed the value stored in outNumElements prior to the call; pointer + * will be non-NULL + * outLayers - an array of layer handles + * outTypes - an array of composition types, each corresponding to an element + * of outLayers + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called for this + * display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_CHANGED_COMPOSITION_TYPES)( + hwc2_device_t* device, hwc2_display_t display, + uint32_t* outNumElements, hwc2_layer_t* outLayers, + int32_t* /*hwc2_composition_t*/ outTypes); + +/* getClientTargetSupport(..., width, height, format, dataspace) + * Descriptor: HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT + * Must be provided by all HWC2 devices + * + * Returns whether a client target with the given properties can be handled by + * the device. + * + * The valid formats can be found in android_pixel_format_t in + * <system/graphics.h>. + * + * For more about dataspaces, see setLayerDataspace. + * + * This function must return true for a client target with width and height + * equal to the active display configuration dimensions, + * HAL_PIXEL_FORMAT_RGBA_8888, and HAL_DATASPACE_UNKNOWN. It is not required to + * return true for any other configuration. + * + * Parameters: + * width - client target width in pixels + * height - client target height in pixels + * format - client target format + * dataspace - client target dataspace, as described in setLayerDataspace + * + * Returns HWC2_ERROR_NONE if the given configuration is supported or one of the + * following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_UNSUPPORTED - the given configuration is not supported + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_CLIENT_TARGET_SUPPORT)( + hwc2_device_t* device, hwc2_display_t display, uint32_t width, + uint32_t height, int32_t /*android_pixel_format_t*/ format, + int32_t /*android_dataspace_t*/ dataspace); + +/* getColorModes(..., outNumModes, outModes) + * Descriptor: HWC2_FUNCTION_GET_COLOR_MODES + * Must be provided by all HWC2 devices + * + * Returns the color modes supported on this display. + * + * The valid color modes can be found in android_color_mode_t in + * <system/graphics.h>. All HWC2 devices must support at least + * HAL_COLOR_MODE_NATIVE. + * + * outNumModes may be NULL to retrieve the number of modes which will be + * returned. + * + * Parameters: + * outNumModes - if outModes was NULL, the number of modes which would have + * been returned; if outModes was not NULL, the number of modes returned, + * which must not exceed the value stored in outNumModes prior to the + * call; pointer will be non-NULL + * outModes - an array of color modes + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_COLOR_MODES)( + hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumModes, + int32_t* /*android_color_mode_t*/ outModes); + +/* getRenderIntents(..., mode, outNumIntents, outIntents) + * Descriptor: HWC2_FUNCTION_GET_RENDER_INTENTS + * Provided by HWC2 devices which don't return nullptr function pointer. + * + * Returns the render intents supported on this display. + * + * The valid render intents can be found in android_render_intent_v1_1_t in + * <system/graphics.h>. All HWC2 devices must support at least + * HAL_RENDER_INTENT_COLORIMETRIC. + * + * outNumIntents may be NULL to retrieve the number of intents which will be + * returned. + * + * Parameters: + * mode - the color mode to query the render intents for + * outNumIntents - if outIntents was NULL, the number of intents which would + * have been returned; if outIntents was not NULL, the number of intents + * returned, which must not exceed the value stored in outNumIntents + * prior to the call; pointer will be non-NULL + * outIntents - an array of render intents + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_RENDER_INTENTS)( + hwc2_device_t* device, hwc2_display_t display, int32_t mode, + uint32_t* outNumIntents, + int32_t* /*android_render_intent_v1_1_t*/ outIntents); + +/* getDisplayAttribute(..., config, attribute, outValue) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE + * Must be provided by all HWC2 devices + * + * Returns a display attribute value for a particular display configuration. + * + * Any attribute which is not supported or for which the value is unknown by the + * device must return a value of -1. + * + * Parameters: + * config - the display configuration for which to return attribute values + * attribute - the attribute to query + * outValue - the value of the attribute; the pointer will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_CONFIG - config does not name a valid configuration for this + * display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_ATTRIBUTE)( + hwc2_device_t* device, hwc2_display_t display, hwc2_config_t config, + int32_t /*hwc2_attribute_t*/ attribute, int32_t* outValue); + +/* getDisplayConfigs(..., outNumConfigs, outConfigs) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_CONFIGS + * Must be provided by all HWC2 devices + * + * Returns handles for all of the valid display configurations on this display. + * + * outConfigs may be NULL to retrieve the number of elements which will be + * returned. + * + * Parameters: + * outNumConfigs - if outConfigs was NULL, the number of configurations which + * would have been returned; if outConfigs was not NULL, the number of + * configurations returned, which must not exceed the value stored in + * outNumConfigs prior to the call; pointer will be non-NULL + * outConfigs - an array of configuration handles + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_CONFIGS)( + hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumConfigs, + hwc2_config_t* outConfigs); + +/* getDisplayName(..., outSize, outName) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_NAME + * Must be provided by all HWC2 devices + * + * Returns a human-readable version of the display's name. + * + * outName may be NULL to retrieve the length of the name. + * + * Parameters: + * outSize - if outName was NULL, the number of bytes needed to return the + * name if outName was not NULL, the number of bytes written into it, + * which must not exceed the value stored in outSize prior to the call; + * pointer will be non-NULL + * outName - the display's name + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_NAME)( + hwc2_device_t* device, hwc2_display_t display, uint32_t* outSize, + char* outName); + +/* getDisplayRequests(..., outDisplayRequests, outNumElements, outLayers, + * outLayerRequests) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_REQUESTS + * Must be provided by all HWC2 devices + * + * Returns the display requests and the layer requests required for the last + * validated configuration. + * + * Display requests provide information about how the client should handle the + * client target. Layer requests provide information about how the client + * should handle an individual layer. + * + * If outLayers or outLayerRequests is NULL, the required number of layers and + * requests must be returned in outNumElements, but this number may also be + * obtained from validateDisplay as outNumRequests (outNumElements must be equal + * to the value returned in outNumRequests from the last call to + * validateDisplay). + * + * Parameters: + * outDisplayRequests - the display requests for the current validated state + * outNumElements - if outLayers or outLayerRequests were NULL, the number of + * elements which would have been returned, which must be equal to the + * value returned in outNumRequests from the last validateDisplay call on + * this display; if both were not NULL, the number of elements in + * outLayers and outLayerRequests, which must not exceed the value stored + * in outNumElements prior to the call; pointer will be non-NULL + * outLayers - an array of layers which all have at least one request + * outLayerRequests - the requests corresponding to each element of outLayers + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called for this + * display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_REQUESTS)( + hwc2_device_t* device, hwc2_display_t display, + int32_t* /*hwc2_display_request_t*/ outDisplayRequests, + uint32_t* outNumElements, hwc2_layer_t* outLayers, + int32_t* /*hwc2_layer_request_t*/ outLayerRequests); + +/* getDisplayType(..., outType) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_TYPE + * Must be provided by all HWC2 devices + * + * Returns whether the given display is a physical or virtual display. + * + * Parameters: + * outType - the type of the display; pointer will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_TYPE)( + hwc2_device_t* device, hwc2_display_t display, + int32_t* /*hwc2_display_type_t*/ outType); + +/* getDisplayIdentificationData(..., outPort, outDataSize, outData) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA + * Optional for HWC2 devices + * + * If supported, getDisplayIdentificationData returns the port and data that + * describe a physical display. The port is a unique number that identifies a + * physical connector (e.g. eDP, HDMI) for display output. The data blob is + * parsed to determine its format, typically EDID 1.3 as specified in VESA + * E-EDID Standard Release A Revision 1. + * + * Devices for which display identification is unsupported must return null when + * getFunction is called with HWC2_FUNCTION_GET_DISPLAY_IDENTIFICATION_DATA. + * + * Parameters: + * outPort - the connector to which the display is connected; + * pointer will be non-NULL + * outDataSize - if outData is NULL, the size in bytes of the data which would + * have been returned; if outData is not NULL, the size of outData, which + * must not exceed the value stored in outDataSize prior to the call; + * pointer will be non-NULL + * outData - the EDID 1.3 blob identifying the display + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_IDENTIFICATION_DATA)( + hwc2_device_t* device, hwc2_display_t display, uint8_t* outPort, + uint32_t* outDataSize, uint8_t* outData); + +/* getDozeSupport(..., outSupport) + * Descriptor: HWC2_FUNCTION_GET_DOZE_SUPPORT + * Must be provided by all HWC2 devices + * + * Returns whether the given display supports HWC2_POWER_MODE_DOZE and + * HWC2_POWER_MODE_DOZE_SUSPEND. DOZE_SUSPEND may not provide any benefit over + * DOZE (see the definition of hwc2_power_mode_t for more information), but if + * both DOZE and DOZE_SUSPEND are no different from HWC2_POWER_MODE_ON, the + * device should not claim support. + * + * Parameters: + * outSupport - whether the display supports doze modes (1 for yes, 0 for no); + * pointer will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DOZE_SUPPORT)( + hwc2_device_t* device, hwc2_display_t display, int32_t* outSupport); + +/* getHdrCapabilities(..., outNumTypes, outTypes, outMaxLuminance, + * outMaxAverageLuminance, outMinLuminance) + * Descriptor: HWC2_FUNCTION_GET_HDR_CAPABILITIES + * Must be provided by all HWC2 devices + * + * Returns the high dynamic range (HDR) capabilities of the given display, which + * are invariant with regard to the active configuration. + * + * Displays which are not HDR-capable must return no types in outTypes and set + * outNumTypes to 0. + * + * If outTypes is NULL, the required number of HDR types must be returned in + * outNumTypes. + * + * Parameters: + * outNumTypes - if outTypes was NULL, the number of types which would have + * been returned; if it was not NULL, the number of types stored in + * outTypes, which must not exceed the value stored in outNumTypes prior + * to the call; pointer will be non-NULL + * outTypes - an array of HDR types, may have 0 elements if the display is not + * HDR-capable + * outMaxLuminance - the desired content maximum luminance for this display in + * cd/m^2; pointer will be non-NULL + * outMaxAverageLuminance - the desired content maximum frame-average + * luminance for this display in cd/m^2; pointer will be non-NULL + * outMinLuminance - the desired content minimum luminance for this display in + * cd/m^2; pointer will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_HDR_CAPABILITIES)( + hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumTypes, + int32_t* /*android_hdr_t*/ outTypes, float* outMaxLuminance, + float* outMaxAverageLuminance, float* outMinLuminance); + +/* getReleaseFences(..., outNumElements, outLayers, outFences) + * Descriptor: HWC2_FUNCTION_GET_RELEASE_FENCES + * Must be provided by all HWC2 devices + * + * Retrieves the release fences for device layers on this display which will + * receive new buffer contents this frame. + * + * A release fence is a file descriptor referring to a sync fence object which + * will be signaled after the device has finished reading from the buffer + * presented in the prior frame. This indicates that it is safe to start writing + * to the buffer again. If a given layer's fence is not returned from this + * function, it will be assumed that the buffer presented on the previous frame + * is ready to be written. + * + * The fences returned by this function should be unique for each layer (even if + * they point to the same underlying sync object), and ownership of the fences + * is transferred to the client, which is responsible for closing them. + * + * If outLayers or outFences is NULL, the required number of layers and fences + * must be returned in outNumElements. + * + * Parameters: + * outNumElements - if outLayers or outFences were NULL, the number of + * elements which would have been returned; if both were not NULL, the + * number of elements in outLayers and outFences, which must not exceed + * the value stored in outNumElements prior to the call; pointer will be + * non-NULL + * outLayers - an array of layer handles + * outFences - an array of sync fence file descriptors as described above, + * each corresponding to an element of outLayers + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_RELEASE_FENCES)( + hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumElements, + hwc2_layer_t* outLayers, int32_t* outFences); + +/* presentDisplay(..., outPresentFence) + * Descriptor: HWC2_FUNCTION_PRESENT_DISPLAY + * Must be provided by all HWC2 devices + * + * Presents the current display contents on the screen (or in the case of + * virtual displays, into the output buffer). + * + * Prior to calling this function, the display must be successfully validated + * with validateDisplay. Note that setLayerBuffer and setLayerSurfaceDamage + * specifically do not count as layer state, so if there are no other changes + * to the layer state (or to the buffer's properties as described in + * setLayerBuffer), then it is safe to call this function without first + * validating the display. + * + * If this call succeeds, outPresentFence will be populated with a file + * descriptor referring to a present sync fence object. For physical displays, + * this fence will be signaled at the vsync when the result of composition of + * this frame starts to appear (for video-mode panels) or starts to transfer to + * panel memory (for command-mode panels). For virtual displays, this fence will + * be signaled when writes to the output buffer have completed and it is safe to + * read from it. + * + * Parameters: + * outPresentFence - a sync fence file descriptor as described above; pointer + * will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_NO_RESOURCES - no valid output buffer has been set for a virtual + * display + * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not successfully been called + * for this display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_PRESENT_DISPLAY)( + hwc2_device_t* device, hwc2_display_t display, + int32_t* outPresentFence); + +/* setActiveConfig(..., config) + * Descriptor: HWC2_FUNCTION_SET_ACTIVE_CONFIG + * Must be provided by all HWC2 devices + * + * Sets the active configuration for this display. Upon returning, the given + * display configuration should be active and remain so until either this + * function is called again or the display is disconnected. + * + * Parameters: + * config - the new display configuration + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_CONFIG - the configuration handle passed in is not valid for + * this display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_ACTIVE_CONFIG)( + hwc2_device_t* device, hwc2_display_t display, hwc2_config_t config); + +/* setClientTarget(..., target, acquireFence, dataspace, damage) + * Descriptor: HWC2_FUNCTION_SET_CLIENT_TARGET + * Must be provided by all HWC2 devices + * + * Sets the buffer handle which will receive the output of client composition. + * Layers marked as HWC2_COMPOSITION_CLIENT will be composited into this buffer + * prior to the call to presentDisplay, and layers not marked as + * HWC2_COMPOSITION_CLIENT should be composited with this buffer by the device. + * + * The buffer handle provided may be null if no layers are being composited by + * the client. This must not result in an error (unless an invalid display + * handle is also provided). + * + * Also provides a file descriptor referring to an acquire sync fence object, + * which will be signaled when it is safe to read from the client target buffer. + * If it is already safe to read from this buffer, -1 may be passed instead. + * The device must ensure that it is safe for the client to close this file + * descriptor at any point after this function is called. + * + * For more about dataspaces, see setLayerDataspace. + * + * The damage parameter describes a surface damage region as defined in the + * description of setLayerSurfaceDamage. + * + * Will be called before presentDisplay if any of the layers are marked as + * HWC2_COMPOSITION_CLIENT. If no layers are so marked, then it is not + * necessary to call this function. It is not necessary to call validateDisplay + * after changing the target through this function. + * + * Parameters: + * target - the new target buffer + * acquireFence - a sync fence file descriptor as described above + * dataspace - the dataspace of the buffer, as described in setLayerDataspace + * damage - the surface damage region + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - the new target handle was invalid + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_CLIENT_TARGET)( + hwc2_device_t* device, hwc2_display_t display, buffer_handle_t target, + int32_t acquireFence, int32_t /*android_dataspace_t*/ dataspace, + hwc_region_t damage); + +/* setColorMode(..., mode) + * Descriptor: HWC2_FUNCTION_SET_COLOR_MODE + * Must be provided by all HWC2 devices + * + * Sets the color mode of the given display. + * + * This must be called outside of validateDisplay/presentDisplay, and it takes + * effect on next presentDisplay. + * + * The valid color modes can be found in android_color_mode_t in + * <system/graphics.h>. All HWC2 devices must support at least + * HAL_COLOR_MODE_NATIVE, and displays are assumed to be in this mode upon + * hotplug. + * + * Parameters: + * mode - the mode to set + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - mode is not a valid color mode + * HWC2_ERROR_UNSUPPORTED - mode is not supported on this display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_COLOR_MODE)( + hwc2_device_t* device, hwc2_display_t display, + int32_t /*android_color_mode_t*/ mode); + +/* setColorModeWithIntent(..., mode, intent) + * Descriptor: HWC2_FUNCTION_SET_COLOR_MODE_WITH_RENDER_INTENT + * Provided by HWC2 devices which don't return nullptr function pointer. + * + * This must be called outside of validateDisplay/presentDisplay, and it takes + * effect on next presentDisplay. + * + * The valid color modes and render intents can be found in + * android_color_mode_t and android_render_intent_v1_1_t in + * <system/graphics.h>. All HWC2 devices must support at least + * HAL_COLOR_MODE_NATIVE and HAL_RENDER_INTENT_COLORIMETRIC, and displays are + * assumed to be in this mode and intent upon hotplug. + * + * Parameters: + * mode - the mode to set + * intent - the intent to set + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - mode/intent is not a valid color mode or + * render intent + * HWC2_ERROR_UNSUPPORTED - mode or intent is not supported on this display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_COLOR_MODE_WITH_RENDER_INTENT)( + hwc2_device_t* device, hwc2_display_t display, + int32_t /*android_color_mode_t*/ mode, + int32_t /*android_render_intent_v1_1_t */ intent); + +/* setColorTransform(..., matrix, hint) + * Descriptor: HWC2_FUNCTION_SET_COLOR_TRANSFORM + * Must be provided by all HWC2 devices + * + * Sets a color transform which will be applied after composition. + * + * If hint is not HAL_COLOR_TRANSFORM_ARBITRARY, then the device may use the + * hint to apply the desired color transform instead of using the color matrix + * directly. + * + * If the device is not capable of either using the hint or the matrix to apply + * the desired color transform, it should force all layers to client composition + * during validateDisplay. + * + * If HWC2_CAPABILITY_SKIP_CLIENT_COLOR_TRANSFORM is present, then the client + * will never apply the color transform during client composition, even if all + * layers are being composed by the client. + * + * The matrix provided is an affine color transformation of the following form: + * + * |r.r r.g r.b 0| + * |g.r g.g g.b 0| + * |b.r b.g b.b 0| + * |Tr Tg Tb 1| + * + * This matrix will be provided in row-major form: {r.r, r.g, r.b, 0, g.r, ...}. + * + * Given a matrix of this form and an input color [R_in, G_in, B_in], the output + * color [R_out, G_out, B_out] will be: + * + * R_out = R_in * r.r + G_in * g.r + B_in * b.r + Tr + * G_out = R_in * r.g + G_in * g.g + B_in * b.g + Tg + * B_out = R_in * r.b + G_in * g.b + B_in * b.b + Tb + * + * Parameters: + * matrix - a 4x4 transform matrix (16 floats) as described above + * hint - a hint value which may be used instead of the given matrix unless it + * is HAL_COLOR_TRANSFORM_ARBITRARY + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - hint is not a valid color transform hint + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_COLOR_TRANSFORM)( + hwc2_device_t* device, hwc2_display_t display, const float* matrix, + int32_t /*android_color_transform_t*/ hint); + +/* getPerFrameMetadataKeys(..., outKeys) + * Descriptor: HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS + * Optional for HWC2 devices + * + * If supported (getFunction(HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS) is non-null), + * getPerFrameMetadataKeys returns the list of supported PerFrameMetadataKeys + * which are invariant with regard to the active configuration. + * + * Devices which are not HDR-capable, must return null when getFunction is called + * with HWC2_FUNCTION_GET_PER_FRAME_METADATA_KEYS. + * + * If outKeys is NULL, the required number of PerFrameMetadataKey keys + * must be returned in outNumKeys. + * + * Parameters: + * outNumKeys - if outKeys is NULL, the number of keys which would have + * been returned; if outKeys is not NULL, the number of keys stored in + * outKeys, which must not exceed the value stored in outNumKeys prior + * to the call; pointer will be non-NULL + * outKeys - an array of hwc2_per_frame_metadata_key_t keys + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_PER_FRAME_METADATA_KEYS)( + hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumKeys, + int32_t* /*hwc2_per_frame_metadata_key_t*/ outKeys); + +/* setOutputBuffer(..., buffer, releaseFence) + * Descriptor: HWC2_FUNCTION_SET_OUTPUT_BUFFER + * Must be provided by all HWC2 devices + * + * Sets the output buffer for a virtual display. That is, the buffer to which + * the composition result will be written. + * + * Also provides a file descriptor referring to a release sync fence object, + * which will be signaled when it is safe to write to the output buffer. If it + * is already safe to write to the output buffer, -1 may be passed instead. The + * device must ensure that it is safe for the client to close this file + * descriptor at any point after this function is called. + * + * Must be called at least once before presentDisplay, but does not have any + * interaction with layer state or display validation. + * + * Parameters: + * buffer - the new output buffer + * releaseFence - a sync fence file descriptor as described above + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - the new output buffer handle was invalid + * HWC2_ERROR_UNSUPPORTED - display does not refer to a virtual display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_OUTPUT_BUFFER)( + hwc2_device_t* device, hwc2_display_t display, buffer_handle_t buffer, + int32_t releaseFence); + +/* setPowerMode(..., mode) + * Descriptor: HWC2_FUNCTION_SET_POWER_MODE + * Must be provided by all HWC2 devices + * + * Sets the power mode of the given display. The transition must be complete + * when this function returns. It is valid to call this function multiple times + * with the same power mode. + * + * All displays must support HWC2_POWER_MODE_ON and HWC2_POWER_MODE_OFF. Whether + * a display supports HWC2_POWER_MODE_DOZE or HWC2_POWER_MODE_DOZE_SUSPEND may + * be queried using getDozeSupport. + * + * Parameters: + * mode - the new power mode + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - mode was not a valid power mode + * HWC2_ERROR_UNSUPPORTED - mode was a valid power mode, but is not supported + * on this display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_POWER_MODE)( + hwc2_device_t* device, hwc2_display_t display, + int32_t /*hwc2_power_mode_t*/ mode); + +/* getReadbackBufferAttributes(..., outFormat, outDataspace) + * Optional for HWC2 devices + * + * Returns the format which should be used when allocating a buffer for use by + * device readback as well as the dataspace in which its contents should be + * interpreted. + * + * If readback is not supported by this HWC implementation, this call will also + * be able to return HWC2_ERROR_UNSUPPORTED so we can fall back to another method. + * Returning NULL to a getFunction request for this function will also indicate + * that readback is not supported. + * + * The width and height of this buffer will be those of the currently-active + * display configuration, and the usage flags will consist of the following: + * BufferUsage::CPU_READ | BufferUsage::GPU_TEXTURE | + * BufferUsage::COMPOSER_OUTPUT + * + * The format and dataspace provided must be sufficient such that if a + * correctly-configured buffer is passed into setReadbackBuffer, filled by + * the device, and then displayed by the client as a full-screen buffer, the + * output of the display remains the same (subject to the note about protected + * content in the description of setReadbackBuffer). + * + * If the active configuration or color mode of this display has changed since + * the previous call to this function, it will be called again prior to setting + * a readback buffer such that the returned format and dataspace can be updated + * accordingly. + * + * Parameters: + * outFormat - the format the client should use when allocating a device + * readback buffer; pointer will be non-NULL + * outDataspace - the dataspace the client will use when interpreting the + * contents of a device readback buffer; pointer will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * + * See also: + * setReadbackBuffer + * getReadbackBufferFence + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_READBACK_BUFFER_ATTRIBUTES)( + hwc2_device_t* device, hwc2_display_t display, + int32_t* /*android_pixel_format_t*/ outFormat, + int32_t* /*android_dataspace_t*/ outDataspace); + +/* getReadbackBufferFence(..., outFence) + * Optional for HWC2 devices + * + * Returns an acquire sync fence file descriptor which will signal when the + * buffer provided to setReadbackBuffer has been filled by the device and is + * safe for the client to read. + * + * If it is already safe to read from this buffer, -1 may be returned instead. + * The client takes ownership of this file descriptor and is responsible for + * closing it when it is no longer needed. + * + * This function will be called immediately after the composition cycle being + * captured into the readback buffer. The complete ordering of a readback buffer + * capture is as follows: + * + * getReadbackBufferAttributes + * // Readback buffer is allocated + * // Many frames may pass + * + * setReadbackBuffer + * validateDisplay + * presentDisplay + * getReadbackBufferFence + * // Implicitly wait on the acquire fence before accessing the buffer + * + * Parameters: + * outFence - a sync fence file descriptor as described above; pointer + * will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_NO_RESOURCES - the readback operation was successful, but + * resulted in a different validate result than would have occurred + * without readback + * HWC2_ERROR_UNSUPPORTED - the readback operation was unsuccessful because + * of resource constraints, the presence of protected content, or other + * reasons; -1 must be returned in outFence + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_READBACK_BUFFER_FENCE)( + hwc2_device_t* device, hwc2_display_t display, + int32_t* outFence); + +/* setReadbackBuffer(..., buffer, releaseFence) + * Optional for HWC2 devices + * + * Sets the readback buffer to be filled with the contents of the next + * composition performed for this display (i.e., the contents present at the + * time of the next validateDisplay/presentDisplay cycle). + * + * This buffer will have been allocated as described in + * getReadbackBufferAttributes and will be interpreted as being in the dataspace + * provided by the same. + * + * If there is hardware protected content on the display at the time of the next + * composition, the area of the readback buffer covered by such content must be + * completely black. Any areas of the buffer not covered by such content may + * optionally be black as well. + * + * The release fence file descriptor provided works identically to the one + * described for setOutputBuffer. + * + * This function will not be called between any call to validateDisplay and a + * subsequent call to presentDisplay. + * + * Parameters: + * buffer - the new readback buffer + * releaseFence - a sync fence file descriptor as described in setOutputBuffer + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - the new readback buffer handle was invalid + * + * See also: + * getReadbackBufferAttributes + * getReadbackBufferFence + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_READBACK_BUFFER)( + hwc2_device_t* device, hwc2_display_t display, + buffer_handle_t buffer, int32_t releaseFence); + +/* setVsyncEnabled(..., enabled) + * Descriptor: HWC2_FUNCTION_SET_VSYNC_ENABLED + * Must be provided by all HWC2 devices + * + * Enables or disables the vsync signal for the given display. Virtual displays + * never generate vsync callbacks, and any attempt to enable vsync for a virtual + * display though this function must return HWC2_ERROR_NONE and have no other + * effect. + * + * Parameters: + * enabled - whether to enable or disable vsync + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - enabled was an invalid value + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_VSYNC_ENABLED)( + hwc2_device_t* device, hwc2_display_t display, + int32_t /*hwc2_vsync_t*/ enabled); + +/* validateDisplay(..., outNumTypes, outNumRequests) + * Descriptor: HWC2_FUNCTION_VALIDATE_DISPLAY + * Must be provided by all HWC2 devices + * + * Instructs the device to inspect all of the layer state and determine if + * there are any composition type changes necessary before presenting the + * display. Permitted changes are described in the definition of + * hwc2_composition_t above. + * + * Also returns the number of layer requests required + * by the given layer configuration. + * + * Parameters: + * outNumTypes - the number of composition type changes required by the + * device; if greater than 0, the client must either set and validate new + * types, or call acceptDisplayChanges to accept the changes returned by + * getChangedCompositionTypes; must be the same as the number of changes + * returned by getChangedCompositionTypes (see the declaration of that + * function for more information); pointer will be non-NULL + * outNumRequests - the number of layer requests required by this layer + * configuration; must be equal to the number of layer requests returned + * by getDisplayRequests (see the declaration of that function for + * more information); pointer will be non-NULL + * + * Returns HWC2_ERROR_NONE if no changes are necessary and it is safe to present + * the display using the current layer state. Otherwise returns one of the + * following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_HAS_CHANGES - outNumTypes was greater than 0 (see parameter list + * for more information) + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_VALIDATE_DISPLAY)( + hwc2_device_t* device, hwc2_display_t display, + uint32_t* outNumTypes, uint32_t* outNumRequests); + +/* + * Layer Functions + * + * These are functions which operate on layers, but which do not modify state + * that must be validated before use. See also 'Layer State Functions' below. + * + * All of these functions take as their first three parameters a device pointer, + * a display handle for the display which contains the layer, and a layer + * handle, so these parameters are omitted from the described parameter lists. + */ + +/* setCursorPosition(..., x, y) + * Descriptor: HWC2_FUNCTION_SET_CURSOR_POSITION + * Must be provided by all HWC2 devices + * + * Asynchonously sets the position of a cursor layer. + * + * Prior to validateDisplay, a layer may be marked as HWC2_COMPOSITION_CURSOR. + * If validation succeeds (i.e., the device does not request a composition + * change for that layer), then once a buffer has been set for the layer and it + * has been presented, its position may be set by this function at any time + * between presentDisplay and any subsequent validateDisplay calls for this + * display. + * + * Once validateDisplay is called, this function will not be called again until + * the validate/present sequence is completed. + * + * May be called from any thread so long as it is not interleaved with the + * validate/present sequence as described above. + * + * Parameters: + * x - the new x coordinate (in pixels from the left of the screen) + * y - the new y coordinate (in pixels from the top of the screen) + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_LAYER - the layer is invalid or is not currently marked as + * HWC2_COMPOSITION_CURSOR + * HWC2_ERROR_NOT_VALIDATED - the device is currently in the middle of the + * validate/present sequence + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_CURSOR_POSITION)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + int32_t x, int32_t y); + +/* setLayerBuffer(..., buffer, acquireFence) + * Descriptor: HWC2_FUNCTION_SET_LAYER_BUFFER + * Must be provided by all HWC2 devices + * + * Sets the buffer handle to be displayed for this layer. If the buffer + * properties set at allocation time (width, height, format, and usage) have not + * changed since the previous frame, it is not necessary to call validateDisplay + * before calling presentDisplay unless new state needs to be validated in the + * interim. + * + * Also provides a file descriptor referring to an acquire sync fence object, + * which will be signaled when it is safe to read from the given buffer. If it + * is already safe to read from the buffer, -1 may be passed instead. The + * device must ensure that it is safe for the client to close this file + * descriptor at any point after this function is called. + * + * This function must return HWC2_ERROR_NONE and have no other effect if called + * for a layer with a composition type of HWC2_COMPOSITION_SOLID_COLOR (because + * it has no buffer) or HWC2_COMPOSITION_SIDEBAND or HWC2_COMPOSITION_CLIENT + * (because synchronization and buffer updates for these layers are handled + * elsewhere). + * + * Parameters: + * buffer - the buffer handle to set + * acquireFence - a sync fence file descriptor as described above + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + * HWC2_ERROR_BAD_PARAMETER - the buffer handle passed in was invalid + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_BUFFER)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + buffer_handle_t buffer, int32_t acquireFence); + +/* setLayerSurfaceDamage(..., damage) + * Descriptor: HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE + * Must be provided by all HWC2 devices + * + * Provides the region of the source buffer which has been modified since the + * last frame. This region does not need to be validated before calling + * presentDisplay. + * + * Once set through this function, the damage region remains the same until a + * subsequent call to this function. + * + * If damage.numRects > 0, then it may be assumed that any portion of the source + * buffer not covered by one of the rects has not been modified this frame. If + * damage.numRects == 0, then the whole source buffer must be treated as if it + * has been modified. + * + * If the layer's contents are not modified relative to the prior frame, damage + * will contain exactly one empty rect([0, 0, 0, 0]). + * + * The damage rects are relative to the pre-transformed buffer, and their origin + * is the top-left corner. They will not exceed the dimensions of the latched + * buffer. + * + * Parameters: + * damage - the new surface damage region + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_SURFACE_DAMAGE)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + hwc_region_t damage); + +/* setLayerPerFrameMetadata(..., numMetadata, metadata) + * Descriptor: HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA + * Optional for HWC2 devices + * + * If supported (getFunction(HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA) is + * non-null), sets the metadata for the given display for all following + * frames. + * + * Upon returning from this function, the metadata change must have + * fully taken effect. + * + * This function will only be called if getPerFrameMetadataKeys is non-NULL + * and returns at least one key. + * + * Parameters: + * numElements is the number of elements in each of the keys and metadata arrays + * keys is a pointer to the array of keys. + * outMetadata is a pointer to the corresponding array of metadata. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - metadata is not valid + * HWC2_ERROR_UNSUPPORTED - metadata is not supported on this display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_PER_FRAME_METADATA)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + uint32_t numElements, const int32_t* /*hw2_per_frame_metadata_key_t*/ keys, + const float* metadata); + +/* setLayerPerFrameMetadataBlobs(...,numElements, keys, sizes, blobs) + * Descriptor: HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS + * Optional for HWC2 devices + * + * If supported, (getFunction(HWC2_FUNCTION_SET_LAYER_PER_FRAME_METADATA_BLOBS) + * is non-null), sets the metadata for the given display and layer. + * + * Upon returning from this function, the metadata change must have fully taken + * effect. + * + * This function must only be called if getPerFrameMetadataKeys is non-NULL + * and returns at least one key that corresponds to a blob type. + * + * Current valid blob type keys are: HDR10_PLUS_SEI + * + * Parameters: + * numElements is the number of elements in each of the keys, sizes, and + * metadata arrays + * keys is a pointer to an array of keys. Current valid keys are those listed + * above as valid blob type keys. + * sizes is a pointer to an array of unsigned ints specifying the sizes of + * each metadata blob + * metadata is a pointer to a blob of data holding all blobs contiguously in + * memory + * + * Returns HWC2_ERROR_NONE or one of the following erros: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_PARAMETER - sizes of keys and metadata parameters does + * not match numElements, numElements < 0, or keys contains a + * non-valid key (see above for current valid blob type keys). + * HWC2_ERROR_UNSUPPORTED - metadata is not supported on this display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_PER_FRAME_METADATA_BLOBS)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + uint32_t numElements, const int32_t* keys, const uint32_t* sizes, + const uint8_t* metadata); +/* + * Layer State Functions + * + * These functions modify the state of a given layer. They do not take effect + * until the display configuration is successfully validated with + * validateDisplay and the display contents are presented with presentDisplay. + * + * All of these functions take as their first three parameters a device pointer, + * a display handle for the display which contains the layer, and a layer + * handle, so these parameters are omitted from the described parameter lists. + */ + +/* setLayerBlendMode(..., mode) + * Descriptor: HWC2_FUNCTION_SET_LAYER_BLEND_MODE + * Must be provided by all HWC2 devices + * + * Sets the blend mode of the given layer. + * + * Parameters: + * mode - the new blend mode + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + * HWC2_ERROR_BAD_PARAMETER - an invalid blend mode was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_BLEND_MODE)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + int32_t /*hwc2_blend_mode_t*/ mode); + +/* setLayerColor(..., color) + * Descriptor: HWC2_FUNCTION_SET_LAYER_COLOR + * Must be provided by all HWC2 devices + * + * Sets the color of the given layer. If the composition type of the layer is + * not HWC2_COMPOSITION_SOLID_COLOR, this call must return HWC2_ERROR_NONE and + * have no other effect. + * + * Parameters: + * color - the new color + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_COLOR)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + hwc_color_t color); + +/* setLayerFloatColor(..., color) + * Descriptor: HWC2_FUNCTION_SET_LAYER_FLOAT_COLOR + * Provided by HWC2 devices which don't return nullptr function pointer. + * + * Sets the color of the given layer. If the composition type of the layer is + * not HWC2_COMPOSITION_SOLID_COLOR, this call must return HWC2_ERROR_NONE and + * have no other effect. + * + * Parameters: + * color - the new color in float type, rage is [0.0, 1.0], the colorspace is + * defined by the dataspace that gets set by calling setLayerDataspace. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_FLOAT_COLOR)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + hwc_float_color_t color); + +/* setLayerCompositionType(..., type) + * Descriptor: HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE + * Must be provided by all HWC2 devices + * + * Sets the desired composition type of the given layer. During validateDisplay, + * the device may request changes to the composition types of any of the layers + * as described in the definition of hwc2_composition_t above. + * + * Parameters: + * type - the new composition type + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + * HWC2_ERROR_BAD_PARAMETER - an invalid composition type was passed in + * HWC2_ERROR_UNSUPPORTED - a valid composition type was passed in, but it is + * not supported by this device + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_COMPOSITION_TYPE)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + int32_t /*hwc2_composition_t*/ type); + +/* setLayerDataspace(..., dataspace) + * Descriptor: HWC2_FUNCTION_SET_LAYER_DATASPACE + * Must be provided by all HWC2 devices + * + * Sets the dataspace that the current buffer on this layer is in. + * + * The dataspace provides more information about how to interpret the buffer + * contents, such as the encoding standard and color transform. + * + * See the values of android_dataspace_t in <system/graphics.h> for more + * information. + * + * Parameters: + * dataspace - the new dataspace + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_DATASPACE)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + int32_t /*android_dataspace_t*/ dataspace); + +/* setLayerDisplayFrame(..., frame) + * Descriptor: HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME + * Must be provided by all HWC2 devices + * + * Sets the display frame (the portion of the display covered by a layer) of the + * given layer. This frame will not exceed the display dimensions. + * + * Parameters: + * frame - the new display frame + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_DISPLAY_FRAME)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + hwc_rect_t frame); + +/* setLayerPlaneAlpha(..., alpha) + * Descriptor: HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA + * Must be provided by all HWC2 devices + * + * Sets an alpha value (a floating point value in the range [0.0, 1.0]) which + * will be applied to the whole layer. It can be conceptualized as a + * preprocessing step which applies the following function: + * if (blendMode == HWC2_BLEND_MODE_PREMULTIPLIED) + * out.rgb = in.rgb * planeAlpha + * out.a = in.a * planeAlpha + * + * If the device does not support this operation on a layer which is marked + * HWC2_COMPOSITION_DEVICE, it must request a composition type change to + * HWC2_COMPOSITION_CLIENT upon the next validateDisplay call. + * + * Parameters: + * alpha - the plane alpha value to apply + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_PLANE_ALPHA)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + float alpha); + +/* setLayerSidebandStream(..., stream) + * Descriptor: HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM + * Provided by HWC2 devices which support HWC2_CAPABILITY_SIDEBAND_STREAM + * + * Sets the sideband stream for this layer. If the composition type of the given + * layer is not HWC2_COMPOSITION_SIDEBAND, this call must return HWC2_ERROR_NONE + * and have no other effect. + * + * Parameters: + * stream - the new sideband stream + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + * HWC2_ERROR_BAD_PARAMETER - an invalid sideband stream was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_SIDEBAND_STREAM)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + const native_handle_t* stream); + +/* setLayerSourceCrop(..., crop) + * Descriptor: HWC2_FUNCTION_SET_LAYER_SOURCE_CROP + * Must be provided by all HWC2 devices + * + * Sets the source crop (the portion of the source buffer which will fill the + * display frame) of the given layer. This crop rectangle will not exceed the + * dimensions of the latched buffer. + * + * If the device is not capable of supporting a true float source crop (i.e., it + * will truncate or round the floats to integers), it should set this layer to + * HWC2_COMPOSITION_CLIENT when crop is non-integral for the most accurate + * rendering. + * + * If the device cannot support float source crops, but still wants to handle + * the layer, it should use the following code (or similar) to convert to + * an integer crop: + * intCrop.left = (int) ceilf(crop.left); + * intCrop.top = (int) ceilf(crop.top); + * intCrop.right = (int) floorf(crop.right); + * intCrop.bottom = (int) floorf(crop.bottom); + * + * Parameters: + * crop - the new source crop + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_SOURCE_CROP)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + hwc_frect_t crop); + +/* setLayerTransform(..., transform) + * Descriptor: HWC2_FUNCTION_SET_LAYER_TRANSFORM + * Must be provided by all HWC2 devices + * + * Sets the transform (rotation/flip) of the given layer. + * + * Parameters: + * transform - the new transform + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + * HWC2_ERROR_BAD_PARAMETER - an invalid transform was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_TRANSFORM)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + int32_t /*hwc_transform_t*/ transform); + +/* setLayerVisibleRegion(..., visible) + * Descriptor: HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION + * Must be provided by all HWC2 devices + * + * Specifies the portion of the layer that is visible, including portions under + * translucent areas of other layers. The region is in screen space, and will + * not exceed the dimensions of the screen. + * + * Parameters: + * visible - the new visible region, in screen space + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_VISIBLE_REGION)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + hwc_region_t visible); + +/* setLayerZOrder(..., z) + * Descriptor: HWC2_FUNCTION_SET_LAYER_Z_ORDER + * Must be provided by all HWC2 devices + * + * Sets the desired Z order (height) of the given layer. A layer with a greater + * Z value occludes a layer with a lesser Z value. + * + * Parameters: + * z - the new Z order + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_Z_ORDER)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + uint32_t z); + +/* setLayerColorTransform(..., matrix) + * Descriptor: HWC2_FUNCTION_SET_LAYER_COLOR_TRANSFORM + * Optional by all HWC2 devices + * + * Sets a matrix for color transform which will be applied on this layer + * before composition. + * + * If the device is not capable of apply the matrix on this layer, it must force + * this layer to client composition during VALIDATE_DISPLAY. + * + * The matrix provided is an affine color transformation of the following form: + * + * |r.r r.g r.b 0| + * |g.r g.g g.b 0| + * |b.r b.g b.b 0| + * |Tr Tg Tb 1| + * + * This matrix must be provided in row-major form: + * + * {r.r, r.g, r.b, 0, g.r, ...}. + * + * Given a matrix of this form and an input color [R_in, G_in, B_in], + * the input color must first be converted to linear space + * [R_linear, G_linear, B_linear], then the output linear color + * [R_out_linear, G_out_linear, B_out_linear] will be: + * + * R_out_linear = R_linear * r.r + G_linear * g.r + B_linear * b.r + Tr + * G_out_linear = R_linear * r.g + G_linear * g.g + B_linear * b.g + Tg + * B_out_linear = R_linear * r.b + G_linear * g.b + B_linear * b.b + Tb + * + * [R_out_linear, G_out_linear, B_out_linear] must then be converted to + * gamma space: [R_out, G_out, B_out] before blending. + * + * Parameters: + * matrix - a 4x4 transform matrix (16 floats) as described above + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_COLOR_TRANSFORM)( + hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer, + const float* matrix); + +/* getDisplayedContentSamplingAttributes(..., + * format, dataspace, supported_components, max_frames) + * Descriptor: HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES + * Optional by all HWC2 devices + * + * Query for what types of color sampling the hardware supports. + * + * Parameters: + * format - The format of the sampled pixels; pointer will be non-NULL + * dataspace - The dataspace of the sampled pixels; pointer will be non-NULL + * supported_components - The mask of which components can be sampled; pointer + * will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY when an invalid display was passed in, or + * HWC2_ERROR_UNSUPPORTED when there is no efficient way to sample. + */ +typedef int32_t (*HWC2_PFN_GET_DISPLAYED_CONTENT_SAMPLING_ATTRIBUTES)( + hwc2_device_t* device, hwc2_display_t display, + int32_t* /* android_pixel_format_t */ format, + int32_t* /* android_dataspace_t */ dataspace, + uint8_t* /* mask of android_component_t */ supported_components); + +/* setDisplayedContentSamplingEnabled(..., enabled) + * Descriptor: HWC2_FUNCTION_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED + * Optional by all HWC2 devices + * + * Enables or disables the collection of color content statistics + * on this display. + * + * Sampling occurs on the contents of the final composition on this display + * (i.e., the contents presented on screen). + * + * Sampling support is optional, and is set to DISABLE by default. + * On each call to ENABLE, all collected statistics will be reset. + * + * Sample data can be queried via getDisplayedContentSample(). + * + * Parameters: + * enabled - indicates whether to enable or disable sampling. + * component_mask - The mask of which components should be sampled. + * If zero, all supported components are to be enabled. + * max_frames - is the maximum number of frames that should be stored before + * discard. The sample represents the most-recently posted frames. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY when an invalid display handle was passed in, + * HWC2_ERROR_BAD_PARAMETER when enabled was an invalid value, or + * HWC2_ERROR_NO_RESOURCES when the requested ringbuffer size via max_frames + * was not available. + * HWC2_ERROR_UNSUPPORTED when there is no efficient way to sample. + */ +typedef int32_t (*HWC2_PFN_SET_DISPLAYED_CONTENT_SAMPLING_ENABLED)( + hwc2_device_t* device, hwc2_display_t display, + int32_t /*hwc2_displayed_content_sampling_t*/ enabled, + uint8_t /* mask of android_component_t */ component_mask, + uint64_t max_frames); + +/* getDisplayedContentSample(..., component, max_frames, timestamp, + * samples_size, samples, frame_count) + * Descriptor: HWC2_FUNCTION_GET_DISPLAYED_CONTENT_SAMPLE + * Optional by all HWC2 devices + * + * Collects the results of display content color sampling for display. + * + * Collection of data can occur whether the sampling is in ENABLE or + * DISABLE state. + * + * Parameters: + * max_frames - is the maximum number of frames that should be represented in + * the sample. The sample represents the most-recently posted frames. + * If max_frames is 0, all frames are to be represented by the sample. + * timestamp - is the timestamp after which any frames were posted that should + * be included in the sample. Timestamp is CLOCK_MONOTONIC. + * If timestamp is 0, do not filter from the sample by time. + * frame_count - The number of frames represented by this sample; pointer will + * be non-NULL. + * samples_size - The sizes of the color histogram representing the color + * sampling. Sample_sizes are indexed in the same order as + * HWC2_FORMAT_COMPONENT_. + * samples - The arrays of data corresponding to the sampling data. Samples are + * indexed in the same order as HWC2_FORMAT_COMPONENT_. + * The size of each sample is the samples_size for the same index. + * Each components sample is an array that is to be filled with the + * evenly-weighted buckets of a histogram counting how many times a pixel + * of the given component was displayed onscreen. Caller owns the data and + * pointer may be NULL to query samples_size. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY when an invalid display was passed in, or + * HWC2_ERROR_UNSUPPORTED when there is no efficient way to sample, or + * HWC2_ERROR_BAD_PARAMETER when the component is not supported by the hardware. + */ +typedef int32_t (*HWC2_PFN_GET_DISPLAYED_CONTENT_SAMPLE)( + hwc2_device_t* device, hwc2_display_t display, + uint64_t max_frames, uint64_t timestamp, + uint64_t* frame_count, int32_t samples_size[4], uint64_t* samples[4]); + +/* getDisplayCapabilities(..., outCapabilities) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_CAPABILITIES + * Required for HWC2 devices for composer 2.3 + * Optional for HWC2 devices for composer 2.1 and 2.2 + * + * getDisplayCapabilities returns a list of supported capabilities + * (as described in the definition of Capability above). + * This list must not change after initialization. + * + * Parameters: + * outNumCapabilities - if outCapabilities was nullptr, returns the number of capabilities + * if outCapabilities was not nullptr, returns the number of capabilities stored in + * outCapabilities, which must not exceed the value stored in outNumCapabilities prior + * to the call; pointer will be non-NULL + * outCapabilities - a list of supported capabilities. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_CAPABILITIES)( + hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumCapabilities, + uint32_t* outCapabilities); + +/* Use getDisplayCapabilities instead. If brightness is supported, must return + * DisplayCapability::BRIGHTNESS as one of the display capabilities via getDisplayCapabilities. + * Only use getDisplayCapabilities as the source of truth to query brightness support. + * + * getDisplayBrightnessSupport(displayToken) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_BRIGHTNESS_SUPPORT + * Required for HWC2 devices for composer 2.3 + * Optional for HWC2 devices for composer 2.1 and 2.2 + * + * getDisplayBrightnessSupport returns whether brightness operations are supported on a display. + * + * Parameters: + * outSupport - whether the display supports operations. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY when the display is invalid. + */ +typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_GET_DISPLAY_BRIGHTNESS_SUPPORT)(hwc2_device_t* device, + hwc2_display_t display, bool* outSupport); + +/* setDisplayBrightness(displayToken, brightnesss) + * Descriptor: HWC2_FUNCTION_SET_DISPLAY_BRIGHTNESS + * Required for HWC2 devices for composer 2.3 + * Optional for HWC2 devices for composer 2.1 and 2.2 + * + * setDisplayBrightness sets the brightness of a display. + * + * Parameters: + * brightness - a number between 0.0f (minimum brightness) and 1.0f (maximum brightness), or + * -1.0f to turn the backlight off. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY when the display is invalid, or + * HWC2_ERROR_UNSUPPORTED when brightness operations are not supported, or + * HWC2_ERROR_BAD_PARAMETER when the brightness is invalid, or + * HWC2_ERROR_NO_RESOURCES when the brightness cannot be applied. + */ +typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_SET_DISPLAY_BRIGHTNESS)(hwc2_device_t* device, + hwc2_display_t display, float brightness); + +/* Composer 2.4 additions */ + +/* getDisplayConnectionType(..., outType) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_CONNECTION_TYPE + * Optional for all HWC2 devices + * + * Returns whether the given physical display is internal or external. + * + * Parameters: + * outType - the connection type of the display; pointer will be non-NULL + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY when the display is invalid or virtual. + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_CONNECTION_TYPE)( + hwc2_device_t* device, hwc2_display_t display, + uint32_t* /*hwc2_display_connection_type_t*/ outType); + +/* getDisplayVsyncPeriod(..., outVsyncPeriods) + * Descriptor: HWC2_FUNCTION_GET_DISPLAY_VSYNC_PERIOD + * Required for HWC2 devices for composer 2.4 + * + * Retrieves which vsync period the display is currently using. + * + * If no display configuration is currently active, this function must + * return BAD_CONFIG. If a vsync period is about to change due to a + * setActiveConfigWithConstraints call, this function must return the current vsync period + * until the change has taken place. + * + * Parameters: + * outVsyncPeriod - the current vsync period of the display. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_CONFIG - no configuration is currently active + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_VSYNC_PERIOD)( + hwc2_device_t* device, hwc2_display_t display, hwc2_vsync_period_t* outVsyncPeriod); + +/* setActiveConfigWithConstraints(..., + * config, + * vsyncPeriodChangeConstraints, + * outTimeline) + * Descriptor: HWC2_FUNCTION_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS + * Required for HWC2 devices for composer 2.4 + * + * Sets the active configuration and the refresh rate for this display. + * If the new config shares the same config group as the current config, + * only the vsync period shall change. + * Upon returning, the given display configuration, except vsync period, must be active and + * remain so until either this function is called again or the display is disconnected. + * When the display starts to refresh at the new vsync period, onVsync_2_4 callback must be + * called with the new vsync period. + * + * Parameters: + * config - the new display configuration. + * vsyncPeriodChangeConstraints - constraints required for changing vsync period: + * desiredTimeNanos - the time in CLOCK_MONOTONIC after + * which the vsync period may change + * (i.e., the vsync period must not change + * before this time). + * seamlessRequired - if true, requires that the vsync period + * change must happen seamlessly without + * a noticeable visual artifact. + * When the conditions change and it may be + * possible to change the vsync period + * seamlessly, HWC2_CALLBACK_SEAMLESS_POSSIBLE + * callback must be called to indicate that + * caller should retry. + * outTimeline - the timeline for the vsync period change. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in. + * HWC2_ERROR_BAD_CONFIG - an invalid configuration handle passed in. + * HWC2_ERROR_SEAMLESS_NOT_ALLOWED - when seamlessRequired was true but config provided doesn't + * share the same config group as the current config. + * HWC2_ERROR_SEAMLESS_NOT_POSSIBLE - when seamlessRequired was true but the display cannot + * achieve the vsync period change without a noticeable + * visual artifact. + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_ACTIVE_CONFIG_WITH_CONSTRAINTS)( + hwc2_device_t* device, hwc2_display_t display, hwc2_config_t config, + hwc_vsync_period_change_constraints_t* vsyncPeriodChangeConstraints, + hwc_vsync_period_change_timeline_t* outTimeline); + +/* setAutoLowLatencyMode(displayToken, on) + * Descriptor: HWC2_FUNCTION_SET_AUTO_LOW_LATENCY_MODE + * Optional for HWC2 devices + * + * setAutoLowLatencyMode requests that the display goes into low latency mode. If the display + * is connected via HDMI 2.1, then Auto Low Latency Mode should be triggered. If the display is + * internally connected, then a custom low latency mode should be triggered (if available). + * + * Parameters: + * on - indicates whether to turn low latency mode on (=true) or off (=false) + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - when the display is invalid, or + * HWC2_ERROR_UNSUPPORTED - when the display does not support any low latency mode + */ +typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_SET_AUTO_LOW_LATENCY_MODE)(hwc2_device_t* device, + hwc2_display_t display, bool on); + +/* getSupportedContentTypes(..., outSupportedContentTypes) + * Descriptor: HWC2_FUNCTION_GET_SUPPORTED_CONTENT_TYPES + * Optional for HWC2 devices + * + * getSupportedContentTypes returns a list of supported content types + * (as described in the definition of ContentType above). + * This list must not change after initialization. + * + * Parameters: + * outNumSupportedContentTypes - if outSupportedContentTypes was nullptr, returns the number + * of supported content types; if outSupportedContentTypes was not nullptr, returns the + * number of capabilities stored in outSupportedContentTypes, which must not exceed the + * value stored in outNumSupportedContentTypes prior to the call; pointer will be non-NULL + * outSupportedContentTypes - a list of supported content types. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + */ +typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_GET_SUPPORTED_CONTENT_TYPES)(hwc2_device_t* device, + hwc2_display_t display, uint32_t* outNumSupportedContentTypes, uint32_t* outSupportedContentTypes); + +/* setContentType(displayToken, contentType) + * Descriptor: HWC2_FUNCTION_SET_CONTENT_TYPE + * Optional for HWC2 devices + * + * setContentType instructs the display that the content being shown is of the given contentType + * (one of GRAPHICS, PHOTO, CINEMA, GAME). + * + * According to the HDMI 1.4 specification, supporting all content types is optional. Whether + * the display supports a given content type is reported by getSupportedContentTypes. + * + * Parameters: + * contentType - the type of content that is currently being shown on the display + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - when the display is invalid, or + * HWC2_ERROR_UNSUPPORTED - when the given content type is a valid content type, but is not + * supported on this display, or + * HWC2_ERROR_BAD_PARAMETER - when the given content type is invalid + */ +typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_SET_CONTENT_TYPE)(hwc2_device_t* device, + hwc2_display_t display, int32_t /* hwc2_content_type_t */ contentType); + +/* getClientTargetProperty(..., outClientTargetProperty) + * Descriptor: HWC2_FUNCTION_GET_CLIENT_TARGET_PROPERTY + * Optional for HWC2 devices + * + * Retrieves the client target properties for which the hardware composer + * requests after the last call to validateDisplay. The client must set the + * properties of the client target to match the returned values. + * When this API is implemented, if client composition is needed, the hardware + * composer must return meaningful client target property with dataspace not + * setting to UNKNOWN. + * When the returned dataspace is set to UNKNOWN, it means hardware composer + * requests nothing, the client must ignore the returned client target property + * structrue. + * + * Parameters: + * outClientTargetProperty - the client target properties that hardware + * composer requests. If dataspace field is set to UNKNOWN, it means + * the hardware composer requests nothing, the client must ignore the + * returned client target property structure. + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called for this + * display + */ +typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_CLIENT_TARGET_PROPERTY)( + hwc2_device_t* device, hwc2_display_t display, + hwc_client_target_property_t* outClientTargetProperty); + +/* setLayerGenericMetadata(..., keyLength, key, mandatory, valueLength, value) + * Descriptor: HWC2_FUNCTION_SET_LAYER_GENERIC_METADATA + * Optional for HWC2 devices for composer 2.4+ + * + * setLayerGenericMetadata sets a piece of generic metadata for the given layer. + * If this function is called twice with the same key but different values, the + * newer value must override the older one. Calling this function with + * valueLength == 0 must reset that key's metadata as if it had not been set. + * + * A given piece of metadata may either be mandatory or a hint (non-mandatory) + * as indicated by the `mandatory` parameter. Mandatory metadata may affect the + * composition result, which is to say that it may cause a visible change in the + * final image. By contrast, hints may only affect the composition strategy, + * such as which layers are composited by the client, but must not cause a + * visible change in the final image. + * + * This implies that if the device does not understand a given key: + * - If the key is marked as mandatory, it must mark this layer for client + * composition in order to ensure the correct composition result + * - If the key is a hint, the metadata provided may be ignored + * + * Parameters: + * keyLength - the length of the key parameter + * key - the metadata key + * mandatory - indicates whether this particular key represents mandatory + * metadata or a hint, as described above + * valueLength - the length of the value parameter + * value - the metadata value + * + * Returns HWC2_ERROR_NONE or one of the following errors: + * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in + * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in + * HWC2_ERROR_BAD_PARAMETER - an unsupported key was passed in, or the value + * does not conform to the expected format for the key + */ +typedef int32_t /*hwc_error_t*/ (*HWC2_PFN_SET_LAYER_GENERIC_METADATA)(hwc2_device_t* device, + hwc2_display_t display, hwc2_layer_t layer, uint32_t keyLength, const char* key, + bool mandatory, uint32_t valueLength, const uint8_t* value); + +/* getLayerGenericMetadataKey(..., keyIndex, outKeyLength, outKey, outMandatory) + * Descriptor: HWC2_FUNCTION_GET_LAYER_GENERIC_METADATA_KEY + * Optional for HWC2 devices for composer 2.4+ + * + * getLayerGenericMetadataKey allows the client to query which metadata keys are + * supported by the composer implementation. Only keys in this list will be + * passed into setLayerGenericMetadata. Additionally, the key names in this list + * must meet the following requirements: + * - Must be specified in reverse domain name notation + * - Must not start with 'com.android' or 'android' + * - Must be unique within the returned list of keys + * - Must correspond to a matching HIDL struct type, which defines the structure + * of its values. For example, the key 'com.example.V1-3.Foo' should + * correspond to a value of type com.example@1.3::Foo, which is defined in a + * vendor HAL extension + * + * Client code which calls this function will look similar to this: + * + * struct Key { + * std::string name; + * bool mandatory; + * } + * + * std::vector<Key> keys; + * uint32_t index = 0; + * uint32_t keyLength = 0; + * while (true) { + * getLayerGenericMetadataKey(device, index, &keyLength, nullptr, nullptr); + * if (keyLength == 0) break; + * + * Key key; + * key.name.resize(keyLength); + * getLayerGenericMetadataKey(device, index, &keyLength, key.name.data(), &key.mandatory); + * keys.push_back(key); + * + * ++index; + * } + * + * Parameters: + * keyIndex - the index of the key to retrieve. For values beyond the end of + * the list of supported keys, outKeyLength should return 0, and the + * client may assume that if the length is 0 for keyIndex N, then it is + * also 0 for all keyIndex values > N. + * outKeyLength - if outKey was nullptr, returns the length of the key to + * allow the client to allocate an appropriately-sized buffer; if outKey + * was not nullptr, returns the length of the returned key, which must not + * exceed the value stored in outKeyLength prior to the call; pointer will + * be non-null + * outKey - the key at the given index, or nullptr to query the key's length + * outMandatory - whether the given metadata is mandatory or not (see + * setLayerGenericMetadata for more information), may be nullptr + */ +typedef void (*HWC2_PFN_GET_LAYER_GENERIC_METADATA_KEY)(hwc2_device_t* device, uint32_t keyIndex, + uint32_t* outKeyLength, char* outKey, bool* outMandatory); + +__END_DECLS + +#endif diff --git a/include_all/hardware/hwcomposer_defs.h b/include_all/hardware/hwcomposer_defs.h new file mode 100644 index 00000000..3823765f --- /dev/null +++ b/include_all/hardware/hwcomposer_defs.h @@ -0,0 +1,344 @@ +/* + * Copyright (C) 2010 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_INCLUDE_HARDWARE_HWCOMPOSER_DEFS_H +#define ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_DEFS_H + +#include <stdint.h> +#include <sys/cdefs.h> + +#include <hardware/gralloc.h> +#include <hardware/hardware.h> +#include <cutils/native_handle.h> + +__BEGIN_DECLS + +/* Shared by HWC1 and HWC2 */ + +#define HWC_HEADER_VERSION 1 + +#define HWC_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) + +#define HWC_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, HWC_HEADER_VERSION) +#define HWC_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION_2(1, 1, HWC_HEADER_VERSION) +#define HWC_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION_2(1, 2, HWC_HEADER_VERSION) +#define HWC_DEVICE_API_VERSION_1_3 HARDWARE_DEVICE_API_VERSION_2(1, 3, HWC_HEADER_VERSION) +#define HWC_DEVICE_API_VERSION_1_4 HARDWARE_DEVICE_API_VERSION_2(1, 4, HWC_HEADER_VERSION) +#define HWC_DEVICE_API_VERSION_1_5 HARDWARE_DEVICE_API_VERSION_2(1, 5, HWC_HEADER_VERSION) + +#define HWC_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION_2(2, 0, HWC_HEADER_VERSION) + +/** + * The id of this module + */ +#define HWC_HARDWARE_MODULE_ID "hwcomposer" + +/** + * Name of the sensors device to open + */ +#define HWC_HARDWARE_COMPOSER "composer" + +typedef struct hwc_color { + uint8_t r; + uint8_t g; + uint8_t b; + uint8_t a; +} hwc_color_t; + +typedef struct hwc_float_color { + float r; + float g; + float b; + float a; +} hwc_float_color_t; + +typedef struct hwc_frect { + float left; + float top; + float right; + float bottom; +} hwc_frect_t; + +typedef struct hwc_rect { + int left; + int top; + int right; + int bottom; +} hwc_rect_t; + +typedef struct hwc_region { + size_t numRects; + hwc_rect_t const* rects; +} hwc_region_t; + +/* + * hwc_layer_t::transform values + */ +typedef enum { + /* flip source image horizontally */ + HWC_TRANSFORM_FLIP_H = HAL_TRANSFORM_FLIP_H, + /* flip source image vertically */ + HWC_TRANSFORM_FLIP_V = HAL_TRANSFORM_FLIP_V, + /* rotate source image 90 degrees clock-wise */ + HWC_TRANSFORM_ROT_90 = HAL_TRANSFORM_ROT_90, + /* rotate source image 180 degrees */ + HWC_TRANSFORM_ROT_180 = HAL_TRANSFORM_ROT_180, + /* rotate source image 270 degrees clock-wise */ + HWC_TRANSFORM_ROT_270 = HAL_TRANSFORM_ROT_270, + /* flip source image horizontally, the rotate 90 degrees clock-wise */ + HWC_TRANSFORM_FLIP_H_ROT_90 = HAL_TRANSFORM_FLIP_H | HAL_TRANSFORM_ROT_90, + /* flip source image vertically, the rotate 90 degrees clock-wise */ + HWC_TRANSFORM_FLIP_V_ROT_90 = HAL_TRANSFORM_FLIP_V | HAL_TRANSFORM_ROT_90, +} hwc_transform_t; + +/* Constraints for changing vsync period */ +typedef struct hwc_vsync_period_change_constraints { + /* Time in CLOCK_MONOTONIC after which the vsync period may change + * (i.e., the vsync period must not change before this time). */ + int64_t desiredTimeNanos; + /* + * If true, requires that the vsync period change must happen seamlessly without + * a noticeable visual artifact. */ + uint8_t seamlessRequired; +} hwc_vsync_period_change_constraints_t; + +/* Timing for a vsync period change. */ +typedef struct hwc_vsync_period_change_timeline { + /* The time in CLOCK_MONOTONIC when the new display will start to refresh at + * the new vsync period. */ + int64_t newVsyncAppliedTimeNanos; + + /* Set to true if the client is required to sent a frame to be displayed before + * the change can take place. */ + uint8_t refreshRequired; + + /* The time in CLOCK_MONOTONIC when the client is expected to send the new frame. + * Should be ignored if refreshRequired is false. */ + int64_t refreshTimeNanos; +} hwc_vsync_period_change_timeline_t; + +typedef struct hwc_client_target_property { + // The pixel format of client target requested by hardware composer. + int32_t pixelFormat; + // The dataspace of the client target requested by hardware composer. + int32_t dataspace; +} hwc_client_target_property_t; + +/******************************************************************************* + * Beyond this point are things only used by HWC1, which should be ignored when + * implementing a HWC2 device + ******************************************************************************/ + +enum { + /* hwc_composer_device_t::set failed in EGL */ + HWC_EGL_ERROR = -1 +}; + +/* + * hwc_layer_t::hints values + * Hints are set by the HAL and read by SurfaceFlinger + */ +enum { + /* + * HWC can set the HWC_HINT_TRIPLE_BUFFER hint to indicate to SurfaceFlinger + * that it should triple buffer this layer. Typically HWC does this when + * the layer will be unavailable for use for an extended period of time, + * e.g. if the display will be fetching data directly from the layer and + * the layer can not be modified until after the next set(). + */ + HWC_HINT_TRIPLE_BUFFER = 0x00000001, + + /* + * HWC sets HWC_HINT_CLEAR_FB to tell SurfaceFlinger that it should clear the + * framebuffer with transparent pixels where this layer would be. + * SurfaceFlinger will only honor this flag when the layer has no blending + * + */ + HWC_HINT_CLEAR_FB = 0x00000002 +}; + +/* + * hwc_layer_t::flags values + * Flags are set by SurfaceFlinger and read by the HAL + */ +enum { + /* + * HWC_SKIP_LAYER is set by SurfaceFlinger to indicate that the HAL + * shall not consider this layer for composition as it will be handled + * by SurfaceFlinger (just as if compositionType was set to HWC_FRAMEBUFFER). + */ + HWC_SKIP_LAYER = 0x00000001, + + /* + * HWC_IS_CURSOR_LAYER is set by surfaceflinger to indicate that this + * layer is being used as a cursor on this particular display, and that + * surfaceflinger can potentially perform asynchronous position updates for + * this layer. If a call to prepare() returns HWC_CURSOR_OVERLAY for the + * composition type of this layer, then the hwcomposer will allow async + * position updates to this layer via setCursorPositionAsync(). + */ + HWC_IS_CURSOR_LAYER = 0x00000002 +}; + +/* + * hwc_layer_t::compositionType values + */ +enum { + /* this layer is to be drawn into the framebuffer by SurfaceFlinger */ + HWC_FRAMEBUFFER = 0, + + /* this layer will be handled in the HWC */ + HWC_OVERLAY = 1, + + /* this is the background layer. it's used to set the background color. + * there is only a single background layer */ + HWC_BACKGROUND = 2, + + /* this layer holds the result of compositing the HWC_FRAMEBUFFER layers. + * Added in HWC_DEVICE_API_VERSION_1_1. */ + HWC_FRAMEBUFFER_TARGET = 3, + + /* this layer's contents are taken from a sideband buffer stream. + * Added in HWC_DEVICE_API_VERSION_1_4. */ + HWC_SIDEBAND = 4, + + /* this layer's composition will be handled by hwcomposer by dedicated + cursor overlay hardware. hwcomposer will also all async position updates + of this layer outside of the normal prepare()/set() loop. Added in + HWC_DEVICE_API_VERSION_1_4. */ + HWC_CURSOR_OVERLAY = 5 + }; +/* + * hwc_layer_t::blending values + */ +enum { + /* no blending */ + HWC_BLENDING_NONE = 0x0100, + + /* ONE / ONE_MINUS_SRC_ALPHA */ + HWC_BLENDING_PREMULT = 0x0105, + + /* SRC_ALPHA / ONE_MINUS_SRC_ALPHA */ + HWC_BLENDING_COVERAGE = 0x0405 +}; + +/* attributes queriable with query() */ +enum { + /* + * Must return 1 if the background layer is supported, 0 otherwise. + */ + HWC_BACKGROUND_LAYER_SUPPORTED = 0, + + /* + * Returns the vsync period in nanoseconds. + * + * This query is not used for HWC_DEVICE_API_VERSION_1_1 and later. + * Instead, the per-display attribute HWC_DISPLAY_VSYNC_PERIOD is used. + */ + HWC_VSYNC_PERIOD = 1, + + /* + * Availability: HWC_DEVICE_API_VERSION_1_1 + * Returns a mask of supported display types. + */ + HWC_DISPLAY_TYPES_SUPPORTED = 2, +}; + +/* display attributes returned by getDisplayAttributes() */ +enum { + /* Indicates the end of an attribute list */ + HWC_DISPLAY_NO_ATTRIBUTE = 0, + + /* The vsync period in nanoseconds */ + HWC_DISPLAY_VSYNC_PERIOD = 1, + + /* The number of pixels in the horizontal and vertical directions. */ + HWC_DISPLAY_WIDTH = 2, + HWC_DISPLAY_HEIGHT = 3, + + /* The number of pixels per thousand inches of this configuration. + * + * Scaling DPI by 1000 allows it to be stored in an int without losing + * too much precision. + * + * If the DPI for a configuration is unavailable or the HWC implementation + * considers it unreliable, it should set these attributes to zero. + */ + HWC_DISPLAY_DPI_X = 4, + HWC_DISPLAY_DPI_Y = 5, + + /* Indicates which of the vendor-defined color transforms is provided by + * this configuration. */ + HWC_DISPLAY_COLOR_TRANSFORM = 6, + + /* The configuration group this config is associated to. The groups are defined + * to mark certain configs as similar and changing configs within a certain group + * may be done seamlessly in some conditions. setActiveConfigWithConstraints. */ + HWC_DISPLAY_CONFIG_GROUP = 7, +}; + +/* Allowed events for hwc_methods::eventControl() */ +enum { + HWC_EVENT_VSYNC = 0 +}; + +/* Display types and associated mask bits. */ +enum { + HWC_DISPLAY_PRIMARY = 0, + HWC_DISPLAY_EXTERNAL = 1, // HDMI, DP, etc. + HWC_DISPLAY_VIRTUAL = 2, + + HWC_NUM_PHYSICAL_DISPLAY_TYPES = 2, + HWC_NUM_DISPLAY_TYPES = 3, +}; + +enum { + HWC_DISPLAY_PRIMARY_BIT = 1 << HWC_DISPLAY_PRIMARY, + HWC_DISPLAY_EXTERNAL_BIT = 1 << HWC_DISPLAY_EXTERNAL, + HWC_DISPLAY_VIRTUAL_BIT = 1 << HWC_DISPLAY_VIRTUAL, +}; + +/* Display power modes */ +enum { + /* The display is turned off (blanked). */ + HWC_POWER_MODE_OFF = 0, + /* The display is turned on and configured in a low power state + * that is suitable for presenting ambient information to the user, + * possibly with lower fidelity than normal but greater efficiency. */ + HWC_POWER_MODE_DOZE = 1, + /* The display is turned on normally. */ + HWC_POWER_MODE_NORMAL = 2, + /* The display is configured as in HWC_POWER_MODE_DOZE but may + * stop applying frame buffer updates from the graphics subsystem. + * This power mode is effectively a hint from the doze dream to + * tell the hardware that it is done drawing to the display for the + * time being and that the display should remain on in a low power + * state and continue showing its current contents indefinitely + * until the mode changes. + * + * This mode may also be used as a signal to enable hardware-based doze + * functionality. In this case, the doze dream is effectively + * indicating that the hardware is free to take over the display + * and manage it autonomously to implement low power always-on display + * functionality. */ + HWC_POWER_MODE_DOZE_SUSPEND = 3, +}; + +/*****************************************************************************/ + +__END_DECLS + +#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_DEFS_H */ diff --git a/include_all/hardware/input.h b/include_all/hardware/input.h new file mode 100644 index 00000000..c4a4cb51 --- /dev/null +++ b/include_all/hardware/input.h @@ -0,0 +1,573 @@ +/* + * 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_INCLUDE_HARDWARE_INPUT_H +#define ANDROID_INCLUDE_HARDWARE_INPUT_H + +#include <hardware/hardware.h> +#include <stdint.h> + +__BEGIN_DECLS + +#define INPUT_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) +#define INPUT_HARDWARE_MODULE_ID "input" + +#define INPUT_INSTANCE_EVDEV "evdev" + +typedef enum input_bus { + INPUT_BUS_BT, + INPUT_BUS_USB, + INPUT_BUS_SERIAL, + INPUT_BUS_BUILTIN +} input_bus_t; + +typedef struct input_host input_host_t; + +typedef struct input_device_handle input_device_handle_t; + +typedef struct input_device_identifier input_device_identifier_t; + +typedef struct input_device_definition input_device_definition_t; + +typedef struct input_report_definition input_report_definition_t; + +typedef struct input_report input_report_t; + +typedef struct input_collection input_collection_t; + +typedef struct input_property_map input_property_map_t; + +typedef struct input_property input_property_t; + +typedef enum { + // keycodes + INPUT_USAGE_KEYCODE_UNKNOWN, + INPUT_USAGE_KEYCODE_SOFT_LEFT, + INPUT_USAGE_KEYCODE_SOFT_RIGHT, + INPUT_USAGE_KEYCODE_HOME, + INPUT_USAGE_KEYCODE_BACK, + INPUT_USAGE_KEYCODE_CALL, + INPUT_USAGE_KEYCODE_ENDCALL, + INPUT_USAGE_KEYCODE_0, + INPUT_USAGE_KEYCODE_1, + INPUT_USAGE_KEYCODE_2, + INPUT_USAGE_KEYCODE_3, + INPUT_USAGE_KEYCODE_4, + INPUT_USAGE_KEYCODE_5, + INPUT_USAGE_KEYCODE_6, + INPUT_USAGE_KEYCODE_7, + INPUT_USAGE_KEYCODE_8, + INPUT_USAGE_KEYCODE_9, + INPUT_USAGE_KEYCODE_STAR, + INPUT_USAGE_KEYCODE_POUND, + INPUT_USAGE_KEYCODE_DPAD_UP, + INPUT_USAGE_KEYCODE_DPAD_DOWN, + INPUT_USAGE_KEYCODE_DPAD_LEFT, + INPUT_USAGE_KEYCODE_DPAD_RIGHT, + INPUT_USAGE_KEYCODE_DPAD_CENTER, + INPUT_USAGE_KEYCODE_VOLUME_UP, + INPUT_USAGE_KEYCODE_VOLUME_DOWN, + INPUT_USAGE_KEYCODE_POWER, + INPUT_USAGE_KEYCODE_CAMERA, + INPUT_USAGE_KEYCODE_CLEAR, + INPUT_USAGE_KEYCODE_A, + INPUT_USAGE_KEYCODE_B, + INPUT_USAGE_KEYCODE_C, + INPUT_USAGE_KEYCODE_D, + INPUT_USAGE_KEYCODE_E, + INPUT_USAGE_KEYCODE_F, + INPUT_USAGE_KEYCODE_G, + INPUT_USAGE_KEYCODE_H, + INPUT_USAGE_KEYCODE_I, + INPUT_USAGE_KEYCODE_J, + INPUT_USAGE_KEYCODE_K, + INPUT_USAGE_KEYCODE_L, + INPUT_USAGE_KEYCODE_M, + INPUT_USAGE_KEYCODE_N, + INPUT_USAGE_KEYCODE_O, + INPUT_USAGE_KEYCODE_P, + INPUT_USAGE_KEYCODE_Q, + INPUT_USAGE_KEYCODE_R, + INPUT_USAGE_KEYCODE_S, + INPUT_USAGE_KEYCODE_T, + INPUT_USAGE_KEYCODE_U, + INPUT_USAGE_KEYCODE_V, + INPUT_USAGE_KEYCODE_W, + INPUT_USAGE_KEYCODE_X, + INPUT_USAGE_KEYCODE_Y, + INPUT_USAGE_KEYCODE_Z, + INPUT_USAGE_KEYCODE_COMMA, + INPUT_USAGE_KEYCODE_PERIOD, + INPUT_USAGE_KEYCODE_ALT_LEFT, + INPUT_USAGE_KEYCODE_ALT_RIGHT, + INPUT_USAGE_KEYCODE_SHIFT_LEFT, + INPUT_USAGE_KEYCODE_SHIFT_RIGHT, + INPUT_USAGE_KEYCODE_TAB, + INPUT_USAGE_KEYCODE_SPACE, + INPUT_USAGE_KEYCODE_SYM, + INPUT_USAGE_KEYCODE_EXPLORER, + INPUT_USAGE_KEYCODE_ENVELOPE, + INPUT_USAGE_KEYCODE_ENTER, + INPUT_USAGE_KEYCODE_DEL, + INPUT_USAGE_KEYCODE_GRAVE, + INPUT_USAGE_KEYCODE_MINUS, + INPUT_USAGE_KEYCODE_EQUALS, + INPUT_USAGE_KEYCODE_LEFT_BRACKET, + INPUT_USAGE_KEYCODE_RIGHT_BRACKET, + INPUT_USAGE_KEYCODE_BACKSLASH, + INPUT_USAGE_KEYCODE_SEMICOLON, + INPUT_USAGE_KEYCODE_APOSTROPHE, + INPUT_USAGE_KEYCODE_SLASH, + INPUT_USAGE_KEYCODE_AT, + INPUT_USAGE_KEYCODE_NUM, + INPUT_USAGE_KEYCODE_HEADSETHOOK, + INPUT_USAGE_KEYCODE_FOCUS, // *Camera* focus + INPUT_USAGE_KEYCODE_PLUS, + INPUT_USAGE_KEYCODE_MENU, + INPUT_USAGE_KEYCODE_NOTIFICATION, + INPUT_USAGE_KEYCODE_SEARCH, + INPUT_USAGE_KEYCODE_MEDIA_PLAY_PAUSE, + INPUT_USAGE_KEYCODE_MEDIA_STOP, + INPUT_USAGE_KEYCODE_MEDIA_NEXT, + INPUT_USAGE_KEYCODE_MEDIA_PREVIOUS, + INPUT_USAGE_KEYCODE_MEDIA_REWIND, + INPUT_USAGE_KEYCODE_MEDIA_FAST_FORWARD, + INPUT_USAGE_KEYCODE_MUTE, + INPUT_USAGE_KEYCODE_PAGE_UP, + INPUT_USAGE_KEYCODE_PAGE_DOWN, + INPUT_USAGE_KEYCODE_PICTSYMBOLS, + INPUT_USAGE_KEYCODE_SWITCH_CHARSET, + INPUT_USAGE_KEYCODE_BUTTON_A, + INPUT_USAGE_KEYCODE_BUTTON_B, + INPUT_USAGE_KEYCODE_BUTTON_C, + INPUT_USAGE_KEYCODE_BUTTON_X, + INPUT_USAGE_KEYCODE_BUTTON_Y, + INPUT_USAGE_KEYCODE_BUTTON_Z, + INPUT_USAGE_KEYCODE_BUTTON_L1, + INPUT_USAGE_KEYCODE_BUTTON_R1, + INPUT_USAGE_KEYCODE_BUTTON_L2, + INPUT_USAGE_KEYCODE_BUTTON_R2, + INPUT_USAGE_KEYCODE_BUTTON_THUMBL, + INPUT_USAGE_KEYCODE_BUTTON_THUMBR, + INPUT_USAGE_KEYCODE_BUTTON_START, + INPUT_USAGE_KEYCODE_BUTTON_SELECT, + INPUT_USAGE_KEYCODE_BUTTON_MODE, + INPUT_USAGE_KEYCODE_ESCAPE, + INPUT_USAGE_KEYCODE_FORWARD_DEL, + INPUT_USAGE_KEYCODE_CTRL_LEFT, + INPUT_USAGE_KEYCODE_CTRL_RIGHT, + INPUT_USAGE_KEYCODE_CAPS_LOCK, + INPUT_USAGE_KEYCODE_SCROLL_LOCK, + INPUT_USAGE_KEYCODE_META_LEFT, + INPUT_USAGE_KEYCODE_META_RIGHT, + INPUT_USAGE_KEYCODE_FUNCTION, + INPUT_USAGE_KEYCODE_SYSRQ, + INPUT_USAGE_KEYCODE_BREAK, + INPUT_USAGE_KEYCODE_MOVE_HOME, + INPUT_USAGE_KEYCODE_MOVE_END, + INPUT_USAGE_KEYCODE_INSERT, + INPUT_USAGE_KEYCODE_FORWARD, + INPUT_USAGE_KEYCODE_MEDIA_PLAY, + INPUT_USAGE_KEYCODE_MEDIA_PAUSE, + INPUT_USAGE_KEYCODE_MEDIA_CLOSE, + INPUT_USAGE_KEYCODE_MEDIA_EJECT, + INPUT_USAGE_KEYCODE_MEDIA_RECORD, + INPUT_USAGE_KEYCODE_F1, + INPUT_USAGE_KEYCODE_F2, + INPUT_USAGE_KEYCODE_F3, + INPUT_USAGE_KEYCODE_F4, + INPUT_USAGE_KEYCODE_F5, + INPUT_USAGE_KEYCODE_F6, + INPUT_USAGE_KEYCODE_F7, + INPUT_USAGE_KEYCODE_F8, + INPUT_USAGE_KEYCODE_F9, + INPUT_USAGE_KEYCODE_F10, + INPUT_USAGE_KEYCODE_F11, + INPUT_USAGE_KEYCODE_F12, + INPUT_USAGE_KEYCODE_NUM_LOCK, + INPUT_USAGE_KEYCODE_NUMPAD_0, + INPUT_USAGE_KEYCODE_NUMPAD_1, + INPUT_USAGE_KEYCODE_NUMPAD_2, + INPUT_USAGE_KEYCODE_NUMPAD_3, + INPUT_USAGE_KEYCODE_NUMPAD_4, + INPUT_USAGE_KEYCODE_NUMPAD_5, + INPUT_USAGE_KEYCODE_NUMPAD_6, + INPUT_USAGE_KEYCODE_NUMPAD_7, + INPUT_USAGE_KEYCODE_NUMPAD_8, + INPUT_USAGE_KEYCODE_NUMPAD_9, + INPUT_USAGE_KEYCODE_NUMPAD_DIVIDE, + INPUT_USAGE_KEYCODE_NUMPAD_MULTIPLY, + INPUT_USAGE_KEYCODE_NUMPAD_SUBTRACT, + INPUT_USAGE_KEYCODE_NUMPAD_ADD, + INPUT_USAGE_KEYCODE_NUMPAD_DOT, + INPUT_USAGE_KEYCODE_NUMPAD_COMMA, + INPUT_USAGE_KEYCODE_NUMPAD_ENTER, + INPUT_USAGE_KEYCODE_NUMPAD_EQUALS, + INPUT_USAGE_KEYCODE_NUMPAD_LEFT_PAREN, + INPUT_USAGE_KEYCODE_NUMPAD_RIGHT_PAREN, + INPUT_USAGE_KEYCODE_VOLUME_MUTE, + INPUT_USAGE_KEYCODE_INFO, + INPUT_USAGE_KEYCODE_CHANNEL_UP, + INPUT_USAGE_KEYCODE_CHANNEL_DOWN, + INPUT_USAGE_KEYCODE_ZOOM_IN, + INPUT_USAGE_KEYCODE_ZOOM_OUT, + INPUT_USAGE_KEYCODE_TV, + INPUT_USAGE_KEYCODE_WINDOW, + INPUT_USAGE_KEYCODE_GUIDE, + INPUT_USAGE_KEYCODE_DVR, + INPUT_USAGE_KEYCODE_BOOKMARK, + INPUT_USAGE_KEYCODE_CAPTIONS, + INPUT_USAGE_KEYCODE_SETTINGS, + INPUT_USAGE_KEYCODE_TV_POWER, + INPUT_USAGE_KEYCODE_TV_INPUT, + INPUT_USAGE_KEYCODE_STB_POWER, + INPUT_USAGE_KEYCODE_STB_INPUT, + INPUT_USAGE_KEYCODE_AVR_POWER, + INPUT_USAGE_KEYCODE_AVR_INPUT, + INPUT_USAGE_KEYCODE_PROG_RED, + INPUT_USAGE_KEYCODE_PROG_GREEN, + INPUT_USAGE_KEYCODE_PROG_YELLOW, + INPUT_USAGE_KEYCODE_PROG_BLUE, + INPUT_USAGE_KEYCODE_APP_SWITCH, + INPUT_USAGE_KEYCODE_BUTTON_1, + INPUT_USAGE_KEYCODE_BUTTON_2, + INPUT_USAGE_KEYCODE_BUTTON_3, + INPUT_USAGE_KEYCODE_BUTTON_4, + INPUT_USAGE_KEYCODE_BUTTON_5, + INPUT_USAGE_KEYCODE_BUTTON_6, + INPUT_USAGE_KEYCODE_BUTTON_7, + INPUT_USAGE_KEYCODE_BUTTON_8, + INPUT_USAGE_KEYCODE_BUTTON_9, + INPUT_USAGE_KEYCODE_BUTTON_10, + INPUT_USAGE_KEYCODE_BUTTON_11, + INPUT_USAGE_KEYCODE_BUTTON_12, + INPUT_USAGE_KEYCODE_BUTTON_13, + INPUT_USAGE_KEYCODE_BUTTON_14, + INPUT_USAGE_KEYCODE_BUTTON_15, + INPUT_USAGE_KEYCODE_BUTTON_16, + INPUT_USAGE_KEYCODE_LANGUAGE_SWITCH, + INPUT_USAGE_KEYCODE_MANNER_MODE, + INPUT_USAGE_KEYCODE_3D_MODE, + INPUT_USAGE_KEYCODE_CONTACTS, + INPUT_USAGE_KEYCODE_CALENDAR, + INPUT_USAGE_KEYCODE_MUSIC, + INPUT_USAGE_KEYCODE_CALCULATOR, + INPUT_USAGE_KEYCODE_ZENKAKU_HANKAKU, + INPUT_USAGE_KEYCODE_EISU, + INPUT_USAGE_KEYCODE_MUHENKAN, + INPUT_USAGE_KEYCODE_HENKAN, + INPUT_USAGE_KEYCODE_KATAKANA_HIRAGANA, + INPUT_USAGE_KEYCODE_YEN, + INPUT_USAGE_KEYCODE_RO, + INPUT_USAGE_KEYCODE_KANA, + INPUT_USAGE_KEYCODE_ASSIST, + INPUT_USAGE_KEYCODE_BRIGHTNESS_DOWN, + INPUT_USAGE_KEYCODE_BRIGHTNESS_UP, + INPUT_USAGE_KEYCODE_MEDIA_AUDIO_TRACK, + INPUT_USAGE_KEYCODE_SLEEP, + INPUT_USAGE_KEYCODE_WAKEUP, + INPUT_USAGE_KEYCODE_PAIRING, + INPUT_USAGE_KEYCODE_MEDIA_TOP_MENU, + INPUT_USAGE_KEYCODE_11, + INPUT_USAGE_KEYCODE_12, + INPUT_USAGE_KEYCODE_LAST_CHANNEL, + INPUT_USAGE_KEYCODE_TV_DATA_SERVICE, + INPUT_USAGE_KEYCODE_VOICE_ASSIST, + INPUT_USAGE_KEYCODE_TV_RADIO_SERVICE, + INPUT_USAGE_KEYCODE_TV_TELETEXT, + INPUT_USAGE_KEYCODE_TV_NUMBER_ENTRY, + INPUT_USAGE_KEYCODE_TV_TERRESTRIAL_ANALOG, + INPUT_USAGE_KEYCODE_TV_TERRESTRIAL_DIGITAL, + INPUT_USAGE_KEYCODE_TV_SATELLITE, + INPUT_USAGE_KEYCODE_TV_SATELLITE_BS, + INPUT_USAGE_KEYCODE_TV_SATELLITE_CS, + INPUT_USAGE_KEYCODE_TV_SATELLITE_SERVICE, + INPUT_USAGE_KEYCODE_TV_NETWORK, + INPUT_USAGE_KEYCODE_TV_ANTENNA_CABLE, + INPUT_USAGE_KEYCODE_TV_INPUT_HDMI_1, + INPUT_USAGE_KEYCODE_TV_INPUT_HDMI_2, + INPUT_USAGE_KEYCODE_TV_INPUT_HDMI_3, + INPUT_USAGE_KEYCODE_TV_INPUT_HDMI_4, + INPUT_USAGE_KEYCODE_TV_INPUT_COMPOSITE_1, + INPUT_USAGE_KEYCODE_TV_INPUT_COMPOSITE_2, + INPUT_USAGE_KEYCODE_TV_INPUT_COMPONENT_1, + INPUT_USAGE_KEYCODE_TV_INPUT_COMPONENT_2, + INPUT_USAGE_KEYCODE_TV_INPUT_VGA_1, + INPUT_USAGE_KEYCODE_TV_AUDIO_DESCRIPTION, + INPUT_USAGE_KEYCODE_TV_AUDIO_DESCRIPTION_MIX_UP, + INPUT_USAGE_KEYCODE_TV_AUDIO_DESCRIPTION_MIX_DOWN, + INPUT_USAGE_KEYCODE_TV_ZOOM_MODE, + INPUT_USAGE_KEYCODE_TV_CONTENTS_MENU, + INPUT_USAGE_KEYCODE_TV_MEDIA_CONTEXT_MENU, + INPUT_USAGE_KEYCODE_TV_TIMER_PROGRAMMING, + INPUT_USAGE_KEYCODE_HELP, + + // axes + INPUT_USAGE_AXIS_X, + INPUT_USAGE_AXIS_Y, + INPUT_USAGE_AXIS_Z, + INPUT_USAGE_AXIS_RX, + INPUT_USAGE_AXIS_RY, + INPUT_USAGE_AXIS_RZ, + INPUT_USAGE_AXIS_HAT_X, + INPUT_USAGE_AXIS_HAT_Y, + INPUT_USAGE_AXIS_PRESSURE, + INPUT_USAGE_AXIS_SIZE, + INPUT_USAGE_AXIS_TOUCH_MAJOR, + INPUT_USAGE_AXIS_TOUCH_MINOR, + INPUT_USAGE_AXIS_TOOL_MAJOR, + INPUT_USAGE_AXIS_TOOL_MINOR, + INPUT_USAGE_AXIS_ORIENTATION, + INPUT_USAGE_AXIS_VSCROLL, + INPUT_USAGE_AXIS_HSCROLL, + INPUT_USAGE_AXIS_LTRIGGER, + INPUT_USAGE_AXIS_RTRIGGER, + INPUT_USAGE_AXIS_THROTTLE, + INPUT_USAGE_AXIS_RUDDER, + INPUT_USAGE_AXIS_WHEEL, + INPUT_USAGE_AXIS_GAS, + INPUT_USAGE_AXIS_BRAKE, + INPUT_USAGE_AXIS_DISTANCE, + INPUT_USAGE_AXIS_TILT, + INPUT_USAGE_AXIS_GENERIC_1, + INPUT_USAGE_AXIS_GENERIC_2, + INPUT_USAGE_AXIS_GENERIC_3, + INPUT_USAGE_AXIS_GENERIC_4, + INPUT_USAGE_AXIS_GENERIC_5, + INPUT_USAGE_AXIS_GENERIC_6, + INPUT_USAGE_AXIS_GENERIC_7, + INPUT_USAGE_AXIS_GENERIC_8, + INPUT_USAGE_AXIS_GENERIC_9, + INPUT_USAGE_AXIS_GENERIC_10, + INPUT_USAGE_AXIS_GENERIC_11, + INPUT_USAGE_AXIS_GENERIC_12, + INPUT_USAGE_AXIS_GENERIC_13, + INPUT_USAGE_AXIS_GENERIC_14, + INPUT_USAGE_AXIS_GENERIC_15, + INPUT_USAGE_AXIS_GENERIC_16, + + // leds + INPUT_USAGE_LED_NUM_LOCK, + INPUT_USAGE_LED_CAPS_LOCK, + INPUT_USAGE_LED_SCROLL_LOCK, + INPUT_USAGE_LED_COMPOSE, + INPUT_USAGE_LED_KANA, + INPUT_USAGE_LED_SLEEP, + INPUT_USAGE_LED_SUSPEND, + INPUT_USAGE_LED_MUTE, + INPUT_USAGE_LED_MISC, + INPUT_USAGE_LED_MAIL, + INPUT_USAGE_LED_CHARGING, + INPUT_USAGE_LED_CONTROLLER_1, + INPUT_USAGE_LED_CONTROLLER_2, + INPUT_USAGE_LED_CONTROLLER_3, + INPUT_USAGE_LED_CONTROLLER_4, + + // switches + INPUT_USAGE_SWITCH_UNKNOWN, + INPUT_USAGE_SWITCH_LID, + INPUT_USAGE_SWITCH_KEYPAD_SLIDE, + INPUT_USAGE_SWITCH_HEADPHONE_INSERT, + INPUT_USAGE_SWITCH_MICROPHONE_INSERT, + INPUT_USAGE_SWITCH_LINEOUT_INSERT, + INPUT_USAGE_SWITCH_CAMERA_LENS_COVER, + + // mouse buttons + // (see android.view.MotionEvent) + INPUT_USAGE_BUTTON_UNKNOWN, + INPUT_USAGE_BUTTON_PRIMARY, // left + INPUT_USAGE_BUTTON_SECONDARY, // right + INPUT_USAGE_BUTTON_TERTIARY, // middle + INPUT_USAGE_BUTTON_FORWARD, + INPUT_USAGE_BUTTON_BACK, +} input_usage_t; + +typedef enum input_collection_id { + INPUT_COLLECTION_ID_TOUCH, + INPUT_COLLECTION_ID_KEYBOARD, + INPUT_COLLECTION_ID_MOUSE, + INPUT_COLLECTION_ID_TOUCHPAD, + INPUT_COLLECTION_ID_SWITCH, + // etc +} input_collection_id_t; + +typedef struct input_message input_message_t; + +typedef struct input_host_callbacks { + + /** + * Creates a device identifier with the given properties. + * The unique ID should be a string that precisely identifies a given piece of hardware. For + * example, an input device connected via Bluetooth could use its MAC address as its unique ID. + */ + input_device_identifier_t* (*create_device_identifier)(input_host_t* host, + const char* name, int32_t product_id, int32_t vendor_id, + input_bus_t bus, const char* unique_id); + + /** + * Allocates the device definition which will describe the input capabilities of a device. A + * device definition may be used to register as many devices as desired. + */ + input_device_definition_t* (*create_device_definition)(input_host_t* host); + + /** + * Allocate either an input report, which the HAL will use to tell the host of incoming input + * events, or an output report, which the host will use to tell the HAL of desired state + * changes (e.g. setting an LED). + */ + input_report_definition_t* (*create_input_report_definition)(input_host_t* host); + input_report_definition_t* (*create_output_report_definition)(input_host_t* host); + + /** + * Frees the report definition. + */ + void (*free_report_definition)(input_host_t* host, input_report_definition_t* report_def); + + /** + * Append the report to the given input device. + */ + void (*input_device_definition_add_report)(input_host_t* host, + input_device_definition_t* d, input_report_definition_t* r); + + /** + * Add a collection with the given arity and ID. A collection describes a set + * of logically grouped properties such as the X and Y coordinates of a single finger touch or + * the set of keys on a keyboard. The arity declares how many repeated instances of this + * collection will appear in whatever report it is attached to. The ID describes the type of + * grouping being represented by the collection. For example, a touchscreen capable of + * reporting up to 2 fingers simultaneously might have a collection with the X and Y + * coordinates, an arity of 2, and an ID of INPUT_COLLECTION_USAGE_TOUCHSCREEN. Any given ID + * may only be present once for a given report. + */ + void (*input_report_definition_add_collection)(input_host_t* host, + input_report_definition_t* report, input_collection_id_t id, int32_t arity); + + /** + * Declare an int usage with the given properties. The report and collection defines where the + * usage is being declared. + */ + void (*input_report_definition_declare_usage_int)(input_host_t* host, + input_report_definition_t* report, input_collection_id_t id, + input_usage_t usage, int32_t min, int32_t max, float resolution); + + /** + * Declare a set of boolean usages with the given properties. The report and collection + * defines where the usages are being declared. + */ + void (*input_report_definition_declare_usages_bool)(input_host_t* host, + input_report_definition_t* report, input_collection_id_t id, + input_usage_t* usage, size_t usage_count); + + + /** + * Register a given input device definition. This notifies the host that an input device has + * been connected and gives a description of all its capabilities. + */ + input_device_handle_t* (*register_device)(input_host_t* host, + input_device_identifier_t* id, input_device_definition_t* d); + + /** Unregister the given device */ + void (*unregister_device)(input_host_t* host, input_device_handle_t* handle); + + /** + * Allocate a report that will contain all of the state as described by the given report. + */ + input_report_t* (*input_allocate_report)(input_host_t* host, input_report_definition_t* r); + + /** + * Add an int usage value to a report. + */ + void (*input_report_set_usage_int)(input_host_t* host, input_report_t* r, + input_collection_id_t id, input_usage_t usage, int32_t value, int32_t arity_index); + + /** + * Add a boolean usage value to a report. + */ + void (*input_report_set_usage_bool)(input_host_t* host, input_report_t* r, + input_collection_id_t id, input_usage_t usage, bool value, int32_t arity_index); + + void (*report_event)(input_host_t* host, input_device_handle_t* d, input_report_t* report); + + /** + * Retrieve the set of properties for the device. The returned + * input_property_map_t* may be used to query specific properties via the + * input_get_device_property callback. + */ + input_property_map_t* (*input_get_device_property_map)(input_host_t* host, + input_device_identifier_t* id); + /** + * Retrieve a property for the device with the given key. Returns NULL if + * the key does not exist, or an input_property_t* that must be freed using + * input_free_device_property(). Using an input_property_t after the + * corresponding input_property_map_t is freed is undefined. + */ + input_property_t* (*input_get_device_property)(input_host_t* host, + input_property_map_t* map, const char* key); + + /** + * Get the key for the input property. Returns NULL if the property is NULL. + * The returned const char* is owned by the input_property_t. + */ + const char* (*input_get_property_key)(input_host_t* host, input_property_t* property); + + /** + * Get the value for the input property. Returns NULL if the property is + * NULL. The returned const char* is owned by the input_property_t. + */ + const char* (*input_get_property_value)(input_host_t* host, input_property_t* property); + + /** + * Frees the input_property_t*. + */ + void (*input_free_device_property)(input_host_t* host, input_property_t* property); + + /** + * Frees the input_property_map_t*. + */ + void (*input_free_device_property_map)(input_host_t* host, input_property_map_t* map); +} input_host_callbacks_t; + +typedef struct input_module input_module_t; + +struct input_module { + /** + * Common methods of the input module. This *must* be the first member + * of input_module as users of this structure will cast a hw_module_t + * to input_module pointer in contexts where it's known + * the hw_module_t references a input_module. + */ + struct hw_module_t common; + + /** + * Initialize the module with host callbacks. At this point the HAL should start up whatever + * infrastructure it needs to in order to process input events. + */ + void (*init)(const input_module_t* module, input_host_t* host, input_host_callbacks_t cb); + + /** + * Sends an output report with a new set of state the host would like the given device to + * assume. + */ + void (*notify_report)(const input_module_t* module, input_report_t* report); +}; + +static inline int input_open(const struct hw_module_t** module, const char* type) { + return hw_get_module_by_class(INPUT_HARDWARE_MODULE_ID, type, module); +} + +__END_DECLS + +#endif /* ANDROID_INCLUDE_HARDWARE_INPUT_H */ diff --git a/include_all/hardware/keymaster1.h b/include_all/hardware/keymaster1.h new file mode 100644 index 00000000..99693806 --- /dev/null +++ b/include_all/hardware/keymaster1.h @@ -0,0 +1,548 @@ +/* + * 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_KEYMASTER1_H +#define ANDROID_HARDWARE_KEYMASTER1_H + +#include <hardware/keymaster_common.h> +#include <hardware/keymaster_defs.h> + +__BEGIN_DECLS + +/** + * Keymaster1 device definition + */ +struct keymaster1_device { + /** + * Common methods of the keymaster device. This *must* be the first member of + * keymaster_device as users of this structure will cast a hw_device_t to + * keymaster_device pointer in contexts where it's known the hw_device_t references a + * keymaster_device. + */ + struct hw_device_t common; + + /** + * THIS IS DEPRECATED. Use the new "module_api_version" and "hal_api_version" + * fields in the keymaster_module initialization instead. + */ + uint32_t client_version; + + /** + * See flags defined for keymaster0_devices::flags in keymaster_common.h + */ + uint32_t flags; + + void* context; + + /** + * \deprecated Generates a public and private key. The key-blob returned is opaque and must + * subsequently provided for signing and verification. + * + * Returns: 0 on success or an error code less than 0. + */ + int (*generate_keypair)(const struct keymaster1_device* dev, const keymaster_keypair_t key_type, + const void* key_params, uint8_t** key_blob, size_t* key_blob_length); + + /** + * \deprecated Imports a public and private key pair. The imported keys will be in PKCS#8 format + * with DER encoding (Java standard). The key-blob returned is opaque and will be subsequently + * provided for signing and verification. + * + * Returns: 0 on success or an error code less than 0. + */ + int (*import_keypair)(const struct keymaster1_device* dev, const uint8_t* key, + const size_t key_length, uint8_t** key_blob, size_t* key_blob_length); + + /** + * \deprecated Gets the public key part of a key pair. The public key must be in X.509 format + * (Java standard) encoded byte array. + * + * Returns: 0 on success or an error code less than 0. On error, x509_data + * should not be allocated. + */ + int (*get_keypair_public)(const struct keymaster1_device* dev, const uint8_t* key_blob, + const size_t key_blob_length, uint8_t** x509_data, + size_t* x509_data_length); + + /** + * \deprecated Deletes the key pair associated with the key blob. + * + * This function is optional and should be set to NULL if it is not + * implemented. + * + * Returns 0 on success or an error code less than 0. + */ + int (*delete_keypair)(const struct keymaster1_device* dev, const uint8_t* key_blob, + const size_t key_blob_length); + + /** + * \deprecated Deletes all keys in the hardware keystore. Used when keystore is reset + * completely. + * + * This function is optional and should be set to NULL if it is not + * implemented. + * + * Returns 0 on success or an error code less than 0. + */ + int (*delete_all)(const struct keymaster1_device* dev); + + /** + * \deprecated Signs data using a key-blob generated before. This can use either an asymmetric + * key or a secret key. + * + * Returns: 0 on success or an error code less than 0. + */ + int (*sign_data)(const struct keymaster1_device* dev, const void* signing_params, + const uint8_t* key_blob, const size_t key_blob_length, const uint8_t* data, + const size_t data_length, uint8_t** signed_data, size_t* signed_data_length); + + /** + * \deprecated Verifies data signed with a key-blob. This can use either an asymmetric key or a + * secret key. + * + * Returns: 0 on successful verification or an error code less than 0. + */ + int (*verify_data)(const struct keymaster1_device* dev, const void* signing_params, + const uint8_t* key_blob, const size_t key_blob_length, + const uint8_t* signed_data, const size_t signed_data_length, + const uint8_t* signature, const size_t signature_length); + + /** + * Gets algorithms supported. + * + * \param[in] dev The keymaster device structure. + * + * \param[out] algorithms Array of algorithms supported. The caller takes ownership of the + * array and must free() it. + * + * \param[out] algorithms_length Length of \p algorithms. + */ + keymaster_error_t (*get_supported_algorithms)(const struct keymaster1_device* dev, + keymaster_algorithm_t** algorithms, + size_t* algorithms_length); + + /** + * Gets the block modes supported for the specified algorithm. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] algorithm The algorithm for which supported modes will be returned. + * + * \param[out] modes Array of modes supported. The caller takes ownership of the array and must + * free() it. + * + * \param[out] modes_length Length of \p modes. + */ + keymaster_error_t (*get_supported_block_modes)(const struct keymaster1_device* dev, + keymaster_algorithm_t algorithm, + keymaster_purpose_t purpose, + keymaster_block_mode_t** modes, + size_t* modes_length); + + /** + * Gets the padding modes supported for the specified algorithm. Caller assumes ownership of + * the allocated array. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] algorithm The algorithm for which supported padding modes will be returned. + * + * \param[out] modes Array of padding modes supported. The caller takes ownership of the array + * and must free() it. + * + * \param[out] modes_length Length of \p modes. + */ + keymaster_error_t (*get_supported_padding_modes)(const struct keymaster1_device* dev, + keymaster_algorithm_t algorithm, + keymaster_purpose_t purpose, + keymaster_padding_t** modes, + size_t* modes_length); + + /** + * Gets the digests supported for the specified algorithm. Caller assumes ownership of the + * allocated array. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] algorithm The algorithm for which supported digests will be returned. + * + * \param[out] digests Array of digests supported. The caller takes ownership of the array and + * must free() it. + * + * \param[out] digests_length Length of \p digests. + */ + keymaster_error_t (*get_supported_digests)(const struct keymaster1_device* dev, + keymaster_algorithm_t algorithm, + keymaster_purpose_t purpose, + keymaster_digest_t** digests, + size_t* digests_length); + + /** + * Gets the key import formats supported for keys of the specified algorithm. Caller assumes + * ownership of the allocated array. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] algorithm The algorithm for which supported formats will be returned. + * + * \param[out] formats Array of formats supported. The caller takes ownership of the array and + * must free() it. + * + * \param[out] formats_length Length of \p formats. + */ + keymaster_error_t (*get_supported_import_formats)(const struct keymaster1_device* dev, + keymaster_algorithm_t algorithm, + keymaster_key_format_t** formats, + size_t* formats_length); + + /** + * Gets the key export formats supported for keys of the specified algorithm. Caller assumes + * ownership of the allocated array. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] algorithm The algorithm for which supported formats will be returned. + * + * \param[out] formats Array of formats supported. The caller takes ownership of the array and + * must free() it. + * + * \param[out] formats_length Length of \p formats. + */ + keymaster_error_t (*get_supported_export_formats)(const struct keymaster1_device* dev, + keymaster_algorithm_t algorithm, + keymaster_key_format_t** formats, + size_t* formats_length); + + /** + * Adds entropy to the RNG used by keymaster. Entropy added through this method is guaranteed + * not to be the only source of entropy used, and the mixing function is required to be secure, + * in the sense that if the RNG is seeded (from any source) with any data the attacker cannot + * predict (or control), then the RNG output is indistinguishable from random. Thus, if the + * entropy from any source is good, the output will be good. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] data Random data to be mixed in. + * + * \param[in] data_length Length of \p data. + */ + keymaster_error_t (*add_rng_entropy)(const struct keymaster1_device* dev, const uint8_t* data, + size_t data_length); + + /** + * Generates a key, or key pair, returning a key blob and/or a description of the key. + * + * Key generation parameters are defined as keymaster tag/value pairs, provided in \p params. + * See keymaster_tag_t for the full list. Some values that are always required for generation + * of useful keys are: + * + * - KM_TAG_ALGORITHM; + * - KM_TAG_PURPOSE; and + * - (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED. + * + * KM_TAG_AUTH_TIMEOUT should generally be specified unless KM_TAG_NO_AUTH_REQUIRED is present, + * or the user will have to authenticate for every use. + * + * KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH and KM_TAG_DIGEST must be specified for + * algorithms that require them. + * + * The following tags may not be specified; their values will be provided by the implementation. + * + * - KM_TAG_ORIGIN, + * - KM_TAG_ROLLBACK_RESISTANT, + * - KM_TAG_CREATION_DATETIME + * + * \param[in] dev The keymaster device structure. + * + * \param[in] params Array of key generation parameters. + * + * \param[in] params_count Length of \p params. + * + * \param[out] key_blob returns the generated key. \p key_blob must not be NULL. The caller + * assumes ownership key_blob->key_material and must free() it. + * + * \param[out] characteristics returns the characteristics of the key that was, generated, if + * non-NULL. If non-NULL, the caller assumes ownership and must deallocate with + * keymaster_free_characteristics(). Note that KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and + * KM_TAG_APPLICATION_DATA are never returned. + */ + keymaster_error_t (*generate_key)(const struct keymaster1_device* dev, + const keymaster_key_param_set_t* params, + keymaster_key_blob_t* key_blob, + keymaster_key_characteristics_t** characteristics); + + /** + * Returns the characteristics of the specified key, or KM_ERROR_INVALID_KEY_BLOB if the + * key_blob is invalid (implementations must fully validate the integrity of the key). + * client_id and app_data must be the ID and data provided when the key was generated or + * imported, or empty if KM_TAG_APPLICATION_ID and/or KM_TAG_APPLICATION_DATA were not provided + * during generation. Those values are not included in the returned characteristics. The + * caller assumes ownership of the allocated characteristics object, which must be deallocated + * with keymaster_free_characteristics(). + * + * Note that KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA are never + * returned. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] key_blob The key to retreive characteristics from. + * + * \param[in] client_id The client ID data, or NULL if none associated. + * + * \param[in] app_id The app data, or NULL if none associated. + * + * \param[out] characteristics The key characteristics. + */ + keymaster_error_t (*get_key_characteristics)(const struct keymaster1_device* dev, + const keymaster_key_blob_t* key_blob, + const keymaster_blob_t* client_id, + const keymaster_blob_t* app_data, + keymaster_key_characteristics_t** characteristics); + + /** + * Imports a key, or key pair, returning a key blob and/or a description of the key. + * + * Most key import parameters are defined as keymaster tag/value pairs, provided in "params". + * See keymaster_tag_t for the full list. Values that are always required for import of useful + * keys are: + * + * - KM_TAG_ALGORITHM; + * - KM_TAG_PURPOSE; and + * - (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED. + * + * KM_TAG_AUTH_TIMEOUT should generally be specified. If unspecified, the user will have to + * authenticate for every use. + * + * The following tags will take default values if unspecified: + * + * - KM_TAG_KEY_SIZE will default to the size of the key provided. + * - KM_TAG_RSA_PUBLIC_EXPONENT will default to the value in the key provided (for RSA keys) + * + * The following tags may not be specified; their values will be provided by the implementation. + * + * - KM_TAG_ORIGIN, + * - KM_TAG_ROLLBACK_RESISTANT, + * - KM_TAG_CREATION_DATETIME + * + * \param[in] dev The keymaster device structure. + * + * \param[in] params Parameters defining the imported key. + * + * \param[in] params_count The number of entries in \p params. + * + * \param[in] key_format specifies the format of the key data in key_data. + * + * \param[out] key_blob Used to return the opaque key blob. Must be non-NULL. The caller + * assumes ownership of the contained key_material. + * + * \param[out] characteristics Used to return the characteristics of the imported key. May be + * NULL, in which case no characteristics will be returned. If non-NULL, the caller assumes + * ownership and must deallocate with keymaster_free_characteristics(). Note that + * KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and + * KM_TAG_APPLICATION_DATA are never returned. + */ + keymaster_error_t (*import_key)(const struct keymaster1_device* dev, + const keymaster_key_param_set_t* params, + keymaster_key_format_t key_format, + const keymaster_blob_t* key_data, + keymaster_key_blob_t* key_blob, + keymaster_key_characteristics_t** characteristics); + + /** + * Exports a public key, returning a byte array in the specified format. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] export_format The format to be used for exporting the key. + * + * \param[in] key_to_export The key to export. + * + * \param[out] export_data The exported key material. The caller assumes ownership. + * + * \param[out] export_data_length The length of \p export_data. + */ + keymaster_error_t (*export_key)(const struct keymaster1_device* dev, + keymaster_key_format_t export_format, + const keymaster_key_blob_t* key_to_export, + const keymaster_blob_t* client_id, + const keymaster_blob_t* app_data, + keymaster_blob_t* export_data); + + /** + * Deletes the key, or key pair, associated with the key blob. After calling this function it + * will be impossible to use the key for any other operations. May be applied to keys from + * foreign roots of trust (keys not usable under the current root of trust). + * + * This function is optional and should be set to NULL if it is not implemented. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] key The key to be deleted. + */ + keymaster_error_t (*delete_key)(const struct keymaster1_device* dev, + const keymaster_key_blob_t* key); + + /** + * Deletes all keys in the hardware keystore. Used when keystore is reset completely. After + * calling this function it will be impossible to use any previously generated or imported key + * blobs for any operations. + * + * This function is optional and should be set to NULL if it is not implemented. + * + * \param[in] dev The keymaster device structure. + */ + keymaster_error_t (*delete_all_keys)(const struct keymaster1_device* dev); + + /** + * Begins a cryptographic operation using the specified key. If all is well, begin() will + * return KM_ERROR_OK and create an operation handle which must be passed to subsequent calls to + * update(), finish() or abort(). + * + * It is critical that each call to begin() be paired with a subsequent call to finish() or + * abort(), to allow the keymaster implementation to clean up any internal operation state. + * Failure to do this may leak internal state space or other internal resources and may + * eventually cause begin() to return KM_ERROR_TOO_MANY_OPERATIONS when it runs out of space for + * operations. Any result other than KM_ERROR_OK from begin(), update() or finish() implicitly + * aborts the operation, in which case abort() need not be called (and will return + * KM_ERROR_INVALID_OPERATION_HANDLE if called). + * + * \param[in] dev The keymaster device structure. + * + * \param[in] purpose The purpose of the operation, one of KM_PURPOSE_ENCRYPT, + * KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN or KM_PURPOSE_VERIFY. Note that for AEAD modes, + * encryption and decryption imply signing and verification, respectively, but should be + * specified as KM_PURPOSE_ENCRYPT and KM_PURPOSE_DECRYPT. + * + * \param[in] key The key to be used for the operation. \p key must have a purpose compatible + * with \p purpose and all of its usage requirements must be satisfied, or begin() will return + * an appropriate error code. + * + * \param[in] in_params Additional parameters for the operation. This is typically used to + * provide authentication data, with KM_TAG_AUTH_TOKEN. If KM_TAG_APPLICATION_ID or + * KM_TAG_APPLICATION_DATA were provided during generation, they must be provided here, or the + * operation will fail with KM_ERROR_INVALID_KEY_BLOB. For operations that require a nonce or + * IV, on keys that were generated with KM_TAG_CALLER_NONCE, in_params may contain a tag + * KM_TAG_NONCE. For AEAD operations KM_TAG_CHUNK_SIZE is specified here. + * + * \param[out] out_params Output parameters. Used to return additional data from the operation + * initialization, notably to return the IV or nonce from operations that generate an IV or + * nonce. The caller takes ownership of the output parameters array and must free it with + * keymaster_free_param_set(). out_params may be set to NULL if no output parameters are + * expected. If out_params is NULL, and output paramaters are generated, begin() will return + * KM_ERROR_OUTPUT_PARAMETER_NULL. + * + * \param[out] operation_handle The newly-created operation handle which must be passed to + * update(), finish() or abort(). If operation_handle is NULL, begin() will return + * KM_ERROR_OUTPUT_PARAMETER_NULL. + */ + keymaster_error_t (*begin)(const struct keymaster1_device* dev, keymaster_purpose_t purpose, + const keymaster_key_blob_t* key, + const keymaster_key_param_set_t* in_params, + keymaster_key_param_set_t* out_params, + keymaster_operation_handle_t* operation_handle); + + /** + * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun + * with begin(). + * + * If operation_handle is invalid, update() will return KM_ERROR_INVALID_OPERATION_HANDLE. + * + * update() may not consume all of the data provided in the data buffer. update() will return + * the amount consumed in *data_consumed. The caller should provide the unconsumed data in a + * subsequent call. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] operation_handle The operation handle returned by begin(). + * + * \param[in] in_params Additional parameters for the operation. For AEAD modes, this is used + * to specify KM_TAG_ADDITIONAL_DATA. Note that additional data may be provided in multiple + * calls to update(), but only until input data has been provided. + * + * \param[in] input Data to be processed, per the parameters established in the call to begin(). + * Note that update() may or may not consume all of the data provided. See \p input_consumed. + * + * \param[out] input_consumed Amount of data that was consumed by update(). If this is less + * than the amount provided, the caller should provide the remainder in a subsequent call to + * update(). + * + * \param[out] out_params Output parameters. Used to return additional data from the operation + * The caller takes ownership of the output parameters array and must free it with + * keymaster_free_param_set(). out_params may be set to NULL if no output parameters are + * expected. If out_params is NULL, and output paramaters are generated, begin() will return + * KM_ERROR_OUTPUT_PARAMETER_NULL. + * + * \param[out] output The output data, if any. The caller assumes ownership of the allocated + * buffer. output must not be NULL. + * + * Note that update() may not provide any output, in which case output->data_length will be + * zero, and output->data may be either NULL or zero-length (so the caller should always free() + * it). + */ + keymaster_error_t (*update)(const struct keymaster1_device* dev, + keymaster_operation_handle_t operation_handle, + const keymaster_key_param_set_t* in_params, + const keymaster_blob_t* input, size_t* input_consumed, + keymaster_key_param_set_t* out_params, keymaster_blob_t* output); + + /** + * Finalizes a cryptographic operation begun with begin() and invalidates \p operation_handle. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] operation_handle The operation handle returned by begin(). This handle will be + * invalidated. + * + * \param[in] params Additional parameters for the operation. For AEAD modes, this is used to + * specify KM_TAG_ADDITIONAL_DATA, but only if no input data was provided to update(). + * + * \param[in] signature The signature to be verified if the purpose specified in the begin() + * call was KM_PURPOSE_VERIFY. + * + * \param[out] output The output data, if any. The caller assumes ownership of the allocated + * buffer. + * + * If the operation being finished is a signature verification or an AEAD-mode decryption and + * verification fails then finish() will return KM_ERROR_VERIFICATION_FAILED. + */ + keymaster_error_t (*finish)(const struct keymaster1_device* dev, + keymaster_operation_handle_t operation_handle, + const keymaster_key_param_set_t* in_params, + const keymaster_blob_t* signature, + keymaster_key_param_set_t* out_params, keymaster_blob_t* output); + + /** + * Aborts a cryptographic operation begun with begin(), freeing all internal resources and + * invalidating \p operation_handle. + */ + keymaster_error_t (*abort)(const struct keymaster1_device* dev, + keymaster_operation_handle_t operation_handle); +}; +typedef struct keymaster1_device keymaster1_device_t; + +/* Convenience API for opening and closing keymaster devices */ + +static inline int keymaster1_open(const struct hw_module_t* module, keymaster1_device_t** device) { + return module->methods->open(module, KEYSTORE_KEYMASTER, TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int keymaster1_close(keymaster1_device_t* device) { + return device->common.close(&device->common); +} + +__END_DECLS + +#endif // ANDROID_HARDWARE_KEYMASTER1_H diff --git a/include_all/hardware/keymaster2.h b/include_all/hardware/keymaster2.h new file mode 100644 index 00000000..f1993f88 --- /dev/null +++ b/include_all/hardware/keymaster2.h @@ -0,0 +1,432 @@ +/* + * 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_KEYMASTER2_H +#define ANDROID_HARDWARE_KEYMASTER2_H + +#include <hardware/keymaster_common.h> +#include <hardware/keymaster_defs.h> + +__BEGIN_DECLS + +/** + * Keymaster2 device definition + */ +struct keymaster2_device { + /** + * Common methods of the keymaster device. This *must* be the first member of + * keymaster_device as users of this structure will cast a hw_device_t to + * keymaster_device pointer in contexts where it's known the hw_device_t references a + * keymaster_device. + */ + struct hw_device_t common; + + void* context; + + /** + * See flags defined for keymaster0_devices::flags in keymaster_common.h. Used only for + * backward compatibility; keymaster2 hardware devices must set this to zero. + */ + uint32_t flags; + + /** + * Configures keymaster. This method must be called once after the device is opened and before + * it is used. It's used to provide KM_TAG_OS_VERSION and KM_TAG_OS_PATCHLEVEL to keymaster. + * Until this method is called, all other methods will return KM_ERROR_KEYMASTER_NOT_CONFIGURED. + * The values provided by this method are only accepted by keymaster once per boot. Subsequent + * calls will return KM_ERROR_OK, but do nothing. + * + * If the keymaster implementation is in secure hardware and the OS version and patch level + * values provided do not match the values provided to the secure hardware by the bootloader (or + * if the bootloader did not provide values), then this method will return + * KM_ERROR_INVALID_ARGUMENT, and all other methods will continue returning + * KM_ERROR_KEYMASTER_NOT_CONFIGURED. + */ + keymaster_error_t (*configure)(const struct keymaster2_device* dev, + const keymaster_key_param_set_t* params); + + /** + * Adds entropy to the RNG used by keymaster. Entropy added through this method is guaranteed + * not to be the only source of entropy used, and the mixing function is required to be secure, + * in the sense that if the RNG is seeded (from any source) with any data the attacker cannot + * predict (or control), then the RNG output is indistinguishable from random. Thus, if the + * entropy from any source is good, the output will be good. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] data Random data to be mixed in. + * + * \param[in] data_length Length of \p data. + */ + keymaster_error_t (*add_rng_entropy)(const struct keymaster2_device* dev, const uint8_t* data, + size_t data_length); + + /** + * Generates a key, or key pair, returning a key blob and/or a description of the key. + * + * Key generation parameters are defined as keymaster tag/value pairs, provided in \p params. + * See keymaster_tag_t for the full list. Some values that are always required for generation + * of useful keys are: + * + * - KM_TAG_ALGORITHM; + * - KM_TAG_PURPOSE; and + * - (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED. + * + * KM_TAG_AUTH_TIMEOUT should generally be specified unless KM_TAG_NO_AUTH_REQUIRED is present, + * or the user will have to authenticate for every use. + * + * KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH and KM_TAG_DIGEST must be specified for + * algorithms that require them. + * + * The following tags may not be specified; their values will be provided by the implementation. + * + * - KM_TAG_ORIGIN, + * - KM_TAG_ROLLBACK_RESISTANT, + * - KM_TAG_CREATION_DATETIME + * + * \param[in] dev The keymaster device structure. + * + * \param[in] params Array of key generation param + * + * \param[out] key_blob returns the generated key. \p key_blob must not be NULL. The caller + * assumes ownership key_blob->key_material and must free() it. + * + * \param[out] characteristics returns the characteristics of the key that was, generated, if + * non-NULL. If non-NULL, the caller assumes ownership and must deallocate with + * keymaster_free_characteristics(). Note that KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID and + * KM_TAG_APPLICATION_DATA are never returned. + */ + keymaster_error_t (*generate_key)(const struct keymaster2_device* dev, + const keymaster_key_param_set_t* params, + keymaster_key_blob_t* key_blob, + keymaster_key_characteristics_t* characteristics); + + /** + * Returns the characteristics of the specified key, or KM_ERROR_INVALID_KEY_BLOB if the + * key_blob is invalid (implementations must fully validate the integrity of the key). + * client_id and app_data must be the ID and data provided when the key was generated or + * imported, or empty if KM_TAG_APPLICATION_ID and/or KM_TAG_APPLICATION_DATA were not provided + * during generation. Those values are not included in the returned characteristics. The + * caller assumes ownership of the allocated characteristics object, which must be deallocated + * with keymaster_free_characteristics(). + * + * Note that KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA are never returned. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] key_blob The key to retreive characteristics from. + * + * \param[in] client_id The client ID data, or NULL if none associated. + * + * \param[in] app_id The app data, or NULL if none associated. + * + * \param[out] characteristics The key characteristics. Must not be NULL. The caller assumes + * ownership of the contents and must deallocate with keymaster_free_characteristics(). + */ + keymaster_error_t (*get_key_characteristics)(const struct keymaster2_device* dev, + const keymaster_key_blob_t* key_blob, + const keymaster_blob_t* client_id, + const keymaster_blob_t* app_data, + keymaster_key_characteristics_t* characteristics); + + /** + * Imports a key, or key pair, returning a key blob and/or a description of the key. + * + * Most key import parameters are defined as keymaster tag/value pairs, provided in "params". + * See keymaster_tag_t for the full list. Values that are always required for import of useful + * keys are: + * + * - KM_TAG_ALGORITHM; + * - KM_TAG_PURPOSE; and + * - (KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE) or KM_TAG_NO_AUTH_REQUIRED. + * + * KM_TAG_AUTH_TIMEOUT should generally be specified. If unspecified, the user will have to + * authenticate for every use. + * + * The following tags will take default values if unspecified: + * + * - KM_TAG_KEY_SIZE will default to the size of the key provided. + * - KM_TAG_RSA_PUBLIC_EXPONENT will default to the value in the key provided (for RSA keys) + * + * The following tags may not be specified; their values will be provided by the implementation. + * + * - KM_TAG_ORIGIN, + * - KM_TAG_ROLLBACK_RESISTANT, + * - KM_TAG_CREATION_DATETIME + * + * \param[in] dev The keymaster device structure. + * + * \param[in] params Parameters defining the imported key. + * + * \param[in] params_count The number of entries in \p params. + * + * \param[in] key_format specifies the format of the key data in key_data. + * + * \param[out] key_blob Used to return the opaque key blob. Must be non-NULL. The caller + * assumes ownership of the contained key_material. + * + * \param[out] characteristics Used to return the characteristics of the imported key. May be + * NULL, in which case no characteristics will be returned. If non-NULL, the caller assumes + * ownership of the contents and must deallocate with keymaster_free_characteristics(). Note + * that KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA are never returned. + */ + keymaster_error_t (*import_key)(const struct keymaster2_device* dev, + const keymaster_key_param_set_t* params, + keymaster_key_format_t key_format, + const keymaster_blob_t* key_data, + keymaster_key_blob_t* key_blob, + keymaster_key_characteristics_t* characteristics); + + /** + * Exports a public or symmetric key, returning a byte array in the specified format. + * + * Note that symmetric key export is allowed only if the key was created with KM_TAG_EXPORTABLE, + * and only if all of the requirements for key usage (e.g. authentication) are met. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] export_format The format to be used for exporting the key. + * + * \param[in] key_to_export The key to export. + * + * \param[in] client_id Client ID blob, which must match the blob provided in + * KM_TAG_APPLICATION_ID during key generation (if any). + * + * \param[in] app_data Appliation data blob, which must match the blob provided in + * KM_TAG_APPLICATION_DATA during key generation (if any). + * + * \param[out] export_data The exported key material. The caller assumes ownership. + */ + keymaster_error_t (*export_key)(const struct keymaster2_device* dev, + keymaster_key_format_t export_format, + const keymaster_key_blob_t* key_to_export, + const keymaster_blob_t* client_id, + const keymaster_blob_t* app_data, + keymaster_blob_t* export_data); + + /** + * Generates a signed X.509 certificate chain attesting to the presence of \p key_to_attest in + * keymaster (TODO(swillden): Describe certificate contents in more detail). The certificate + * will contain an extension with OID 1.3.6.1.4.1.11129.2.1.17 and value defined in + * <TODO:swillden -- insert link here> which contains the key description. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] key_to_attest The keymaster key for which the attestation certificate will be + * generated. + * + * \param[in] attest_params Parameters defining how to do the attestation. At present the only + * parameter is KM_TAG_ALGORITHM, which must be either KM_ALGORITHM_EC or KM_ALGORITHM_RSA. + * This selects which of the provisioned attestation keys will be used to sign the certificate. + * + * \param[out] cert_chain An array of DER-encoded X.509 certificates. The first will be the + * certificate for \p key_to_attest. The remaining entries will chain back to the root. The + * caller takes ownership and must deallocate with keymaster_free_cert_chain. + */ + keymaster_error_t (*attest_key)(const struct keymaster2_device* dev, + const keymaster_key_blob_t* key_to_attest, + const keymaster_key_param_set_t* attest_params, + keymaster_cert_chain_t* cert_chain); + + /** + * Upgrades an old key. Keys can become "old" in two ways: Keymaster can be upgraded to a new + * version, or the system can be updated to invalidate the OS version and/or patch level. In + * either case, attempts to use an old key will result in keymaster returning + * KM_ERROR_KEY_REQUIRES_UPGRADE. This method should then be called to upgrade the key. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] key_to_upgrade The keymaster key to upgrade. + * + * \param[in] upgrade_params Parameters needed to complete the upgrade. In particular, + * KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA will be required if they were defined for + * the key. + * + * \param[out] upgraded_key The upgraded key blob. + */ + keymaster_error_t (*upgrade_key)(const struct keymaster2_device* dev, + const keymaster_key_blob_t* key_to_upgrade, + const keymaster_key_param_set_t* upgrade_params, + keymaster_key_blob_t* upgraded_key); + + /** + * Deletes the key, or key pair, associated with the key blob. After calling this function it + * will be impossible to use the key for any other operations. May be applied to keys from + * foreign roots of trust (keys not usable under the current root of trust). + * + * This function is optional and should be set to NULL if it is not implemented. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] key The key to be deleted. + */ + keymaster_error_t (*delete_key)(const struct keymaster2_device* dev, + const keymaster_key_blob_t* key); + + /** + * Deletes all keys in the hardware keystore. Used when keystore is reset completely. After + * calling this function it will be impossible to use any previously generated or imported key + * blobs for any operations. + * + * This function is optional and should be set to NULL if it is not implemented. + * + * \param[in] dev The keymaster device structure. + */ + keymaster_error_t (*delete_all_keys)(const struct keymaster2_device* dev); + + /** + * Begins a cryptographic operation using the specified key. If all is well, begin() will + * return KM_ERROR_OK and create an operation handle which must be passed to subsequent calls to + * update(), finish() or abort(). + * + * It is critical that each call to begin() be paired with a subsequent call to finish() or + * abort(), to allow the keymaster implementation to clean up any internal operation state. + * Failure to do this may leak internal state space or other internal resources and may + * eventually cause begin() to return KM_ERROR_TOO_MANY_OPERATIONS when it runs out of space for + * operations. Any result other than KM_ERROR_OK from begin(), update() or finish() implicitly + * aborts the operation, in which case abort() need not be called (and will return + * KM_ERROR_INVALID_OPERATION_HANDLE if called). + * + * \param[in] dev The keymaster device structure. + * + * \param[in] purpose The purpose of the operation, one of KM_PURPOSE_ENCRYPT, + * KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN or KM_PURPOSE_VERIFY. Note that for AEAD modes, + * encryption and decryption imply signing and verification, respectively, but should be + * specified as KM_PURPOSE_ENCRYPT and KM_PURPOSE_DECRYPT. + * + * \param[in] key The key to be used for the operation. \p key must have a purpose compatible + * with \p purpose and all of its usage requirements must be satisfied, or begin() will return + * an appropriate error code. + * + * \param[in] in_params Additional parameters for the operation. This is typically used to + * provide authentication data, with KM_TAG_AUTH_TOKEN. If KM_TAG_APPLICATION_ID or + * KM_TAG_APPLICATION_DATA were provided during generation, they must be provided here, or the + * operation will fail with KM_ERROR_INVALID_KEY_BLOB. For operations that require a nonce or + * IV, on keys that were generated with KM_TAG_CALLER_NONCE, in_params may contain a tag + * KM_TAG_NONCE. + * + * \param[out] out_params Output parameters. Used to return additional data from the operation + * initialization, notably to return the IV or nonce from operations that generate an IV or + * nonce. The caller takes ownership of the output parameters array and must free it with + * keymaster_free_param_set(). out_params may be set to NULL if no output parameters are + * expected. If out_params is NULL, and output paramaters are generated, begin() will return + * KM_ERROR_OUTPUT_PARAMETER_NULL. + * + * \param[out] operation_handle The newly-created operation handle which must be passed to + * update(), finish() or abort(). If operation_handle is NULL, begin() will return + * KM_ERROR_OUTPUT_PARAMETER_NULL. + */ + keymaster_error_t (*begin)(const struct keymaster2_device* dev, keymaster_purpose_t purpose, + const keymaster_key_blob_t* key, + const keymaster_key_param_set_t* in_params, + keymaster_key_param_set_t* out_params, + keymaster_operation_handle_t* operation_handle); + + /** + * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun + * with begin(). + * + * If operation_handle is invalid, update() will return KM_ERROR_INVALID_OPERATION_HANDLE. + * + * update() may not consume all of the data provided in the data buffer. update() will return + * the amount consumed in *data_consumed. The caller should provide the unconsumed data in a + * subsequent call. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] operation_handle The operation handle returned by begin(). + * + * \param[in] in_params Additional parameters for the operation. For AEAD modes, this is used + * to specify KM_TAG_ADDITIONAL_DATA. Note that additional data may be provided in multiple + * calls to update(), but only until input data has been provided. + * + * \param[in] input Data to be processed, per the parameters established in the call to begin(). + * Note that update() may or may not consume all of the data provided. See \p input_consumed. + * + * \param[out] input_consumed Amount of data that was consumed by update(). If this is less + * than the amount provided, the caller should provide the remainder in a subsequent call to + * update(). + * + * \param[out] out_params Output parameters. Used to return additional data from the operation + * The caller takes ownership of the output parameters array and must free it with + * keymaster_free_param_set(). out_params may be set to NULL if no output parameters are + * expected. If out_params is NULL, and output paramaters are generated, begin() will return + * KM_ERROR_OUTPUT_PARAMETER_NULL. + * + * \param[out] output The output data, if any. The caller assumes ownership of the allocated + * buffer. output must not be NULL. + * + * Note that update() may not provide any output, in which case output->data_length will be + * zero, and output->data may be either NULL or zero-length (so the caller should always free() + * it). + */ + keymaster_error_t (*update)(const struct keymaster2_device* dev, + keymaster_operation_handle_t operation_handle, + const keymaster_key_param_set_t* in_params, + const keymaster_blob_t* input, size_t* input_consumed, + keymaster_key_param_set_t* out_params, keymaster_blob_t* output); + + /** + * Finalizes a cryptographic operation begun with begin() and invalidates \p operation_handle. + * + * \param[in] dev The keymaster device structure. + * + * \param[in] operation_handle The operation handle returned by begin(). This handle will be + * invalidated. + * + * \param[in] in_params Additional parameters for the operation. For AEAD modes, this is used + * to specify KM_TAG_ADDITIONAL_DATA, but only if no input data was provided to update(). + * + * \param[in] input Data to be processed, per the parameters established in the call to + * begin(). finish() must consume all provided data or return KM_ERROR_INVALID_INPUT_LENGTH. + * + * \param[in] signature The signature to be verified if the purpose specified in the begin() + * call was KM_PURPOSE_VERIFY. + * + * \param[out] output The output data, if any. The caller assumes ownership of the allocated + * buffer. + * + * If the operation being finished is a signature verification or an AEAD-mode decryption and + * verification fails then finish() will return KM_ERROR_VERIFICATION_FAILED. + */ + keymaster_error_t (*finish)(const struct keymaster2_device* dev, + keymaster_operation_handle_t operation_handle, + const keymaster_key_param_set_t* in_params, + const keymaster_blob_t* input, const keymaster_blob_t* signature, + keymaster_key_param_set_t* out_params, keymaster_blob_t* output); + + /** + * Aborts a cryptographic operation begun with begin(), freeing all internal resources and + * invalidating \p operation_handle. + */ + keymaster_error_t (*abort)(const struct keymaster2_device* dev, + keymaster_operation_handle_t operation_handle); +}; +typedef struct keymaster2_device keymaster2_device_t; + +/* Convenience API for opening and closing keymaster devices */ + +static inline int keymaster2_open(const struct hw_module_t* module, keymaster2_device_t** device) { + return module->methods->open(module, KEYSTORE_KEYMASTER, TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int keymaster2_close(keymaster2_device_t* device) { + return device->common.close(&device->common); +} + +__END_DECLS + +#endif // ANDROID_HARDWARE_KEYMASTER2_H diff --git a/include_all/hardware/keymaster_common.h b/include_all/hardware/keymaster_common.h new file mode 100644 index 00000000..c79c1226 --- /dev/null +++ b/include_all/hardware/keymaster_common.h @@ -0,0 +1,191 @@ +/* + * 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_KEYMASTER_COMMON_H +#define ANDROID_HARDWARE_KEYMASTER_COMMON_H + +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <hardware/hardware.h> + +__BEGIN_DECLS + +/** + * The id of this module + */ +#define KEYSTORE_HARDWARE_MODULE_ID "keystore" + +#define KEYSTORE_KEYMASTER "keymaster" + + +/** + * Settings for "module_api_version" and "hal_api_version" + * fields in the keymaster_module initialization. + */ + +/** + * Keymaster 0.X module version provide the same APIs, but later versions add more options + * for algorithms and flags. + */ +#define KEYMASTER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) +#define KEYMASTER_DEVICE_API_VERSION_0_2 HARDWARE_DEVICE_API_VERSION(0, 2) + +#define KEYMASTER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) +#define KEYMASTER_DEVICE_API_VERSION_0_3 HARDWARE_DEVICE_API_VERSION(0, 3) + +/** + * Keymaster 1.0 module version provides a completely different API, incompatible with 0.X. + */ +#define KEYMASTER_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) +#define KEYMASTER_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) + +/** + * Keymaster 2.0 module version provides third API, slightly modified and extended from 1.0. + */ +#define KEYMASTER_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) +#define KEYMASTER_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) + +struct keystore_module { + /** + * Common methods of the keystore module. This *must* be the first member of keystore_module as + * users of this structure will cast a hw_module_t to keystore_module pointer in contexts where + * it's known the hw_module_t references a keystore_module. + */ + hw_module_t common; + + /* There are no keystore module methods other than the common ones. */ +}; + +/** + * Flags for keymaster0_device::flags + */ +enum { + /* + * Indicates this keymaster implementation does not have hardware that + * keeps private keys out of user space. + * + * This should not be implemented on anything other than the default + * implementation. + */ + KEYMASTER_SOFTWARE_ONLY = 1 << 0, + + /* + * This indicates that the key blobs returned via all the primitives + * are sufficient to operate on their own without the trusted OS + * querying userspace to retrieve some other data. Key blobs of + * this type are normally returned encrypted with a + * Key Encryption Key (KEK). + * + * This is currently used by "vold" to know whether the whole disk + * encryption secret can be unwrapped without having some external + * service started up beforehand since the "/data" partition will + * be unavailable at that point. + */ + KEYMASTER_BLOBS_ARE_STANDALONE = 1 << 1, + + /* + * Indicates that the keymaster module supports DSA keys. + */ + KEYMASTER_SUPPORTS_DSA = 1 << 2, + + /* + * Indicates that the keymaster module supports EC keys. + */ + KEYMASTER_SUPPORTS_EC = 1 << 3, +}; + +/** + * Asymmetric key pair types. + */ +typedef enum { + TYPE_RSA = 1, + TYPE_DSA = 2, + TYPE_EC = 3, +} keymaster_keypair_t; + +/** + * Parameters needed to generate an RSA key. + */ +typedef struct { + uint32_t modulus_size; + uint64_t public_exponent; +} keymaster_rsa_keygen_params_t; + +/** + * Parameters needed to generate a DSA key. + */ +typedef struct { + uint32_t key_size; + uint32_t generator_len; + uint32_t prime_p_len; + uint32_t prime_q_len; + const uint8_t* generator; + const uint8_t* prime_p; + const uint8_t* prime_q; +} keymaster_dsa_keygen_params_t; + +/** + * Parameters needed to generate an EC key. + * + * Field size is the only parameter in version 2. The sizes correspond to these required curves: + * + * 192 = NIST P-192 + * 224 = NIST P-224 + * 256 = NIST P-256 + * 384 = NIST P-384 + * 521 = NIST P-521 + * + * The parameters for these curves are available at: http://www.nsa.gov/ia/_files/nist-routines.pdf + * in Chapter 4. + */ +typedef struct { + uint32_t field_size; +} keymaster_ec_keygen_params_t; + + +/** + * Digest type. + */ +typedef enum { + DIGEST_NONE, +} keymaster_digest_algorithm_t; + +/** + * Type of padding used for RSA operations. + */ +typedef enum { + PADDING_NONE, +} keymaster_rsa_padding_t; + + +typedef struct { + keymaster_digest_algorithm_t digest_type; +} keymaster_dsa_sign_params_t; + +typedef struct { + keymaster_digest_algorithm_t digest_type; +} keymaster_ec_sign_params_t; + +typedef struct { + keymaster_digest_algorithm_t digest_type; + keymaster_rsa_padding_t padding_type; +} keymaster_rsa_sign_params_t; + +__END_DECLS + +#endif // ANDROID_HARDWARE_KEYMASTER_COMMON_H diff --git a/include_all/hardware/keymaster_defs.h b/include_all/hardware/keymaster_defs.h new file mode 100644 index 00000000..dd286d6d --- /dev/null +++ b/include_all/hardware/keymaster_defs.h @@ -0,0 +1,707 @@ +/* + * Copyright (C) 2014 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_KEYMASTER_DEFS_H +#define ANDROID_HARDWARE_KEYMASTER_DEFS_H + +#include <stdint.h> +#include <stdlib.h> +#include <string.h> + +#ifdef __cplusplus +extern "C" { +#endif // __cplusplus + +/** + * Authorization tags each have an associated type. This enumeration facilitates tagging each with + * a type, by using the high four bits (of an implied 32-bit unsigned enum value) to specify up to + * 16 data types. These values are ORed with tag IDs to generate the final tag ID values. + */ +typedef enum { + KM_INVALID = 0 << 28, /* Invalid type, used to designate a tag as uninitialized */ + KM_ENUM = 1 << 28, + KM_ENUM_REP = 2 << 28, /* Repeatable enumeration value. */ + KM_UINT = 3 << 28, + KM_UINT_REP = 4 << 28, /* Repeatable integer value */ + KM_ULONG = 5 << 28, + KM_DATE = 6 << 28, + KM_BOOL = 7 << 28, + KM_BIGNUM = 8 << 28, + KM_BYTES = 9 << 28, + KM_ULONG_REP = 10 << 28, /* Repeatable long value */ +} keymaster_tag_type_t; + +typedef enum { + KM_TAG_INVALID = KM_INVALID | 0, + + /* + * Tags that must be semantically enforced by hardware and software implementations. + */ + + /* Crypto parameters */ + KM_TAG_PURPOSE = KM_ENUM_REP | 1, /* keymaster_purpose_t. */ + KM_TAG_ALGORITHM = KM_ENUM | 2, /* keymaster_algorithm_t. */ + KM_TAG_KEY_SIZE = KM_UINT | 3, /* Key size in bits. */ + KM_TAG_BLOCK_MODE = KM_ENUM_REP | 4, /* keymaster_block_mode_t. */ + KM_TAG_DIGEST = KM_ENUM_REP | 5, /* keymaster_digest_t. */ + KM_TAG_PADDING = KM_ENUM_REP | 6, /* keymaster_padding_t. */ + KM_TAG_CALLER_NONCE = KM_BOOL | 7, /* Allow caller to specify nonce or IV. */ + KM_TAG_MIN_MAC_LENGTH = KM_UINT | 8, /* Minimum length of MAC or AEAD authentication tag in + * bits. */ + KM_TAG_KDF = KM_ENUM_REP | 9, /* keymaster_kdf_t (keymaster2) */ + KM_TAG_EC_CURVE = KM_ENUM | 10, /* keymaster_ec_curve_t (keymaster2) */ + + /* Algorithm-specific. */ + KM_TAG_RSA_PUBLIC_EXPONENT = KM_ULONG | 200, + KM_TAG_ECIES_SINGLE_HASH_MODE = KM_BOOL | 201, /* Whether the ephemeral public key is fed into + * the KDF */ + KM_TAG_INCLUDE_UNIQUE_ID = KM_BOOL | 202, /* If true, attestation certificates for this key + * will contain an application-scoped and + * time-bounded device-unique ID. (keymaster2) */ + KM_TAG_RSA_OAEP_MGF_DIGEST = KM_ENUM_REP | 203, /* keymaster_digest_t. */ + + /* Other hardware-enforced. */ + KM_TAG_BLOB_USAGE_REQUIREMENTS = KM_ENUM | 301, /* keymaster_key_blob_usage_requirements_t */ + KM_TAG_BOOTLOADER_ONLY = KM_BOOL | 302, /* Usable only by bootloader */ + KM_TAG_ROLLBACK_RESISTANCE = KM_BOOL | 303, /* Hardware enforced deletion with deleteKey + * or deleteAllKeys is supported */ + KM_TAG_EARLY_BOOT_ONLY = KM_BOOL | 305, /* Key can only be used during early boot. */ + + /* + * Tags that should be semantically enforced by hardware if possible and will otherwise be + * enforced by software (keystore). + */ + + /* Key validity period */ + KM_TAG_ACTIVE_DATETIME = KM_DATE | 400, /* Start of validity */ + KM_TAG_ORIGINATION_EXPIRE_DATETIME = KM_DATE | 401, /* Date when new "messages" should no + longer be created. */ + KM_TAG_USAGE_EXPIRE_DATETIME = KM_DATE | 402, /* Date when existing "messages" should no + longer be trusted. */ + KM_TAG_MIN_SECONDS_BETWEEN_OPS = KM_UINT | 403, /* Minimum elapsed time between + cryptographic operations with the key. */ + KM_TAG_MAX_USES_PER_BOOT = KM_UINT | 404, /* Number of times the key can be used per + boot. */ + KM_TAG_USAGE_COUNT_LIMIT = KM_UINT | 405, /* Number of cryptographic operations left + with the key.*/ + + /* User authentication */ + KM_TAG_ALL_USERS = KM_BOOL | 500, /* Reserved for future use -- ignore */ + KM_TAG_USER_ID = KM_UINT | 501, /* Reserved for future use -- ignore */ + KM_TAG_USER_SECURE_ID = KM_ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s). + Disallowed if KM_TAG_ALL_USERS or + KM_TAG_NO_AUTH_REQUIRED is present. */ + KM_TAG_NO_AUTH_REQUIRED = KM_BOOL | 503, /* If key is usable without authentication. */ + KM_TAG_USER_AUTH_TYPE = KM_ENUM | 504, /* Bitmask of authenticator types allowed when + * KM_TAG_USER_SECURE_ID contains a secure user ID, + * rather than a secure authenticator ID. Defined in + * hw_authenticator_type_t in hw_auth_token.h. */ + KM_TAG_AUTH_TIMEOUT = KM_UINT | 505, /* Required freshness of user authentication for + private/secret key operations, in seconds. + Public key operations require no authentication. + If absent, authentication is required for every + use. Authentication state is lost when the + device is powered off. */ + KM_TAG_ALLOW_WHILE_ON_BODY = KM_BOOL | 506, /* Allow key to be used after authentication timeout + * if device is still on-body (requires secure + * on-body sensor. */ + KM_TAG_TRUSTED_USER_PRESENCE_REQUIRED = KM_BOOL | 507,/* Require test of user presence + * to use this key. */ + KM_TAG_TRUSTED_CONFIRMATION_REQUIRED = KM_BOOL | 508, /* Require user confirmation through a + * trusted UI to use this key. */ + KM_TAG_UNLOCKED_DEVICE_REQUIRED = KM_BOOL | 509, /* Require the device screen to be unlocked if the + * key is used. */ + + /* Application access control */ + KM_TAG_ALL_APPLICATIONS = KM_BOOL | 600, /* Specified to indicate key is usable by all + * applications. */ + KM_TAG_APPLICATION_ID = KM_BYTES | 601, /* Byte string identifying the authorized + * application. */ + KM_TAG_EXPORTABLE = KM_BOOL | 602, /* If true, private/secret key can be exported, but + * only if all access control requirements for use are + * met. (keymaster2) */ + + /* + * Semantically unenforceable tags, either because they have no specific meaning or because + * they're informational only. + */ + KM_TAG_APPLICATION_DATA = KM_BYTES | 700, /* Data provided by authorized application. */ + KM_TAG_CREATION_DATETIME = KM_DATE | 701, /* Key creation time */ + KM_TAG_ORIGIN = KM_ENUM | 702, /* keymaster_key_origin_t. */ + KM_TAG_ROLLBACK_RESISTANT = KM_BOOL | 703, /* Whether key is rollback-resistant. */ + KM_TAG_ROOT_OF_TRUST = KM_BYTES | 704, /* Root of trust ID. */ + KM_TAG_OS_VERSION = KM_UINT | 705, /* Version of system (keymaster2) */ + KM_TAG_OS_PATCHLEVEL = KM_UINT | 706, /* Patch level of system (keymaster2) */ + KM_TAG_UNIQUE_ID = KM_BYTES | 707, /* Used to provide unique ID in attestation */ + KM_TAG_ATTESTATION_CHALLENGE = KM_BYTES | 708, /* Used to provide challenge in attestation */ + KM_TAG_ATTESTATION_APPLICATION_ID = KM_BYTES | 709, /* Used to identify the set of possible + * applications of which one has initiated + * a key attestation */ + KM_TAG_ATTESTATION_ID_BRAND = KM_BYTES | 710, /* Used to provide the device's brand name to be + included in attestation */ + KM_TAG_ATTESTATION_ID_DEVICE = KM_BYTES | 711, /* Used to provide the device's device name to be + included in attestation */ + KM_TAG_ATTESTATION_ID_PRODUCT = KM_BYTES | 712, /* Used to provide the device's product name to + be included in attestation */ + KM_TAG_ATTESTATION_ID_SERIAL = KM_BYTES | 713, /* Used to provide the device's serial number to + be included in attestation */ + KM_TAG_ATTESTATION_ID_IMEI = KM_BYTES | 714, /* Used to provide the device's IMEI to be + included in attestation */ + KM_TAG_ATTESTATION_ID_MEID = KM_BYTES | 715, /* Used to provide the device's MEID to be + included in attestation */ + KM_TAG_ATTESTATION_ID_MANUFACTURER = KM_BYTES | 716, /* Used to provide the device's + manufacturer name to be included in + attestation */ + KM_TAG_ATTESTATION_ID_MODEL = KM_BYTES | 717, /* Used to provide the device's model name to be + included in attestation */ + KM_TAG_VENDOR_PATCHLEVEL = KM_UINT | 718, /* specifies the vendor image security patch + level with which the key may be used */ + KM_TAG_BOOT_PATCHLEVEL = KM_UINT | 719, /* specifies the boot image (kernel) security + patch level with which the key may be used */ + KM_TAG_DEVICE_UNIQUE_ATTESTATION = KM_BOOL | 720, /* Indicates StrongBox device-unique + attestation is requested. */ + KM_TAG_IDENTITY_CREDENTIAL_KEY = KM_BOOL | 721, /* This is an identity credential key */ + KM_TAG_STORAGE_KEY = KM_BOOL | 722, /* storage encryption key */ + KM_TAG_ATTESTATION_ID_SECOND_IMEI = KM_BYTES | 723, /* Used to provide the device's second + IMEI to be included in attestation */ + + /* Tags used only to provide data to or receive data from operations */ + KM_TAG_ASSOCIATED_DATA = KM_BYTES | 1000, /* Used to provide associated data for AEAD modes. */ + KM_TAG_NONCE = KM_BYTES | 1001, /* Nonce or Initialization Vector */ + KM_TAG_AUTH_TOKEN = KM_BYTES | 1002, /* Authentication token that proves secure user + authentication has been performed. Structure + defined in hw_auth_token_t in hw_auth_token.h. */ + KM_TAG_MAC_LENGTH = KM_UINT | 1003, /* MAC or AEAD authentication tag length in + * bits. */ + + KM_TAG_RESET_SINCE_ID_ROTATION = KM_BOOL | 1004, /* Whether the device has beeen factory reset + since the last unique ID rotation. Used + for key attestation. */ + + KM_TAG_CONFIRMATION_TOKEN = KM_BYTES | 1005, /* used to deliver a cryptographic token + proving that the user confirmed a signing + request. */ + + KM_TAG_CERTIFICATE_SERIAL = KM_BIGNUM | 1006, /* The serial number that should be + set in the attestation certificate + to be generated. */ + + KM_TAG_CERTIFICATE_SUBJECT = KM_BYTES | 1007, /* A DER-encoded X.500 subject that should be + set in the attestation certificate + to be generated. */ + + KM_TAG_CERTIFICATE_NOT_BEFORE = KM_DATE | 1008, /* Epoch time in milliseconds of the start of + the to be generated certificate's validity. + The value should interpreted as too's + complement signed integer. Negative values + indicate dates before Jan 1970 */ + + KM_TAG_CERTIFICATE_NOT_AFTER = KM_DATE | 1009, /* Epoch time in milliseconds of the end of + the to be generated certificate's validity. + The value should interpreted as too's + complement signed integer. Negative values + indicate dates before Jan 1970 */ + KM_TAG_MAX_BOOT_LEVEL = KM_UINT | 1010, /* Specifies a maximum boot level at which a key + should function. */ +} keymaster_tag_t; + +/** + * Algorithms that may be provided by keymaster implementations. Those that must be provided by all + * implementations are tagged as "required". + */ +typedef enum { + /* Asymmetric algorithms. */ + KM_ALGORITHM_RSA = 1, + // KM_ALGORITHM_DSA = 2, -- Removed, do not re-use value 2. + KM_ALGORITHM_EC = 3, + + /* Block ciphers algorithms */ + KM_ALGORITHM_AES = 32, + KM_ALGORITHM_TRIPLE_DES = 33, + + /* MAC algorithms */ + KM_ALGORITHM_HMAC = 128, +} keymaster_algorithm_t; + +/** + * Symmetric block cipher modes provided by keymaster implementations. + */ +typedef enum { + /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended + * except for compatibility with existing other protocols. */ + KM_MODE_ECB = 1, + KM_MODE_CBC = 2, + KM_MODE_CTR = 3, + + /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended + * over unauthenticated modes for all purposes. */ + KM_MODE_GCM = 32, +} keymaster_block_mode_t; + +/** + * Padding modes that may be applied to plaintext for encryption operations. This list includes + * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not + * provide all possible combinations of algorithm and padding, only the + * cryptographically-appropriate pairs. + */ +typedef enum { + KM_PAD_NONE = 1, /* deprecated */ + KM_PAD_RSA_OAEP = 2, + KM_PAD_RSA_PSS = 3, + KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4, + KM_PAD_RSA_PKCS1_1_5_SIGN = 5, + KM_PAD_PKCS7 = 64, +} keymaster_padding_t; + +/** + * Digests provided by keymaster implementations. + */ +typedef enum { + KM_DIGEST_NONE = 0, + KM_DIGEST_MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software + * if needed. */ + KM_DIGEST_SHA1 = 2, + KM_DIGEST_SHA_2_224 = 3, + KM_DIGEST_SHA_2_256 = 4, + KM_DIGEST_SHA_2_384 = 5, + KM_DIGEST_SHA_2_512 = 6, +} keymaster_digest_t; + +/* + * Key derivation functions, mostly used in ECIES. + */ +typedef enum { + /* Do not apply a key derivation function; use the raw agreed key */ + KM_KDF_NONE = 0, + /* HKDF defined in RFC 5869 with SHA256 */ + KM_KDF_RFC5869_SHA256 = 1, + /* KDF1 defined in ISO 18033-2 with SHA1 */ + KM_KDF_ISO18033_2_KDF1_SHA1 = 2, + /* KDF1 defined in ISO 18033-2 with SHA256 */ + KM_KDF_ISO18033_2_KDF1_SHA256 = 3, + /* KDF2 defined in ISO 18033-2 with SHA1 */ + KM_KDF_ISO18033_2_KDF2_SHA1 = 4, + /* KDF2 defined in ISO 18033-2 with SHA256 */ + KM_KDF_ISO18033_2_KDF2_SHA256 = 5, +} keymaster_kdf_t; + +/** + * Supported EC curves, used in ECDSA/ECIES. + */ +typedef enum { + KM_EC_CURVE_P_224 = 0, + KM_EC_CURVE_P_256 = 1, + KM_EC_CURVE_P_384 = 2, + KM_EC_CURVE_P_521 = 3, + KM_EC_CURVE_CURVE_25519 = 4, +} keymaster_ec_curve_t; + +/** + * The origin of a key (or pair), i.e. where it was generated. Note that KM_TAG_ORIGIN can be found + * in either the hardware-enforced or software-enforced list for a key, indicating whether the key + * is hardware or software-based. Specifically, a key with KM_ORIGIN_GENERATED in the + * hardware-enforced list is guaranteed never to have existed outide the secure hardware. + */ +typedef enum { + KM_ORIGIN_GENERATED = 0, /* Generated in keymaster. Should not exist outside the TEE. */ + KM_ORIGIN_DERIVED = 1, /* Derived inside keymaster. Likely exists off-device. */ + KM_ORIGIN_IMPORTED = 2, /* Imported into keymaster. Existed as cleartext in Android. */ + KM_ORIGIN_UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on + * keys in a keymaster0 implementation. The keymaster0 adapter uses + * this value to document the fact that it is unkown whether the key + * was generated inside or imported into keymaster. */ +} keymaster_key_origin_t; + +/** + * Usability requirements of key blobs. This defines what system functionality must be available + * for the key to function. For example, key "blobs" which are actually handles referencing + * encrypted key material stored in the file system cannot be used until the file system is + * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added + * as needed for implementations. + */ +typedef enum { + KM_BLOB_STANDALONE = 0, + KM_BLOB_REQUIRES_FILE_SYSTEM = 1, +} keymaster_key_blob_usage_requirements_t; + +/** + * Possible purposes of a key (or pair). + */ +typedef enum { + KM_PURPOSE_ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */ + KM_PURPOSE_DECRYPT = 1, /* Usable with RSA, EC and AES keys. */ + KM_PURPOSE_SIGN = 2, /* Usable with RSA, EC and HMAC keys. */ + KM_PURPOSE_VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */ + KM_PURPOSE_DERIVE_KEY = 4, /* Usable with EC keys. */ + KM_PURPOSE_WRAP = 5, /* Usable with wrapped keys. */ + KM_PURPOSE_AGREE_KEY = 6, /* Usable with EC keys. */ + KM_PURPOSE_ATTEST_KEY = 7 /* Usabe with RSA and EC keys */ +} keymaster_purpose_t; + +typedef struct { + const uint8_t* data; + size_t data_length; +} keymaster_blob_t; + +typedef struct { + keymaster_tag_t tag; + union { + uint32_t enumerated; /* KM_ENUM and KM_ENUM_REP */ + bool boolean; /* KM_BOOL */ + uint32_t integer; /* KM_INT and KM_INT_REP */ + uint64_t long_integer; /* KM_LONG */ + uint64_t date_time; /* KM_DATE */ + keymaster_blob_t blob; /* KM_BIGNUM and KM_BYTES*/ + }; +} keymaster_key_param_t; + +typedef struct { + keymaster_key_param_t* params; /* may be NULL if length == 0 */ + size_t length; +} keymaster_key_param_set_t; + +/** + * Parameters that define a key's characteristics, including authorized modes of usage and access + * control restrictions. The parameters are divided into two categories, those that are enforced by + * secure hardware, and those that are not. For a software-only keymaster implementation the + * enforced array must NULL. Hardware implementations must enforce everything in the enforced + * array. + */ +typedef struct { + keymaster_key_param_set_t hw_enforced; + keymaster_key_param_set_t sw_enforced; +} keymaster_key_characteristics_t; + +typedef struct { + const uint8_t* key_material; + size_t key_material_size; +} keymaster_key_blob_t; + +typedef struct { + keymaster_blob_t* entries; + size_t entry_count; +} keymaster_cert_chain_t; + +typedef enum { + KM_VERIFIED_BOOT_VERIFIED = 0, /* Full chain of trust extending from the bootloader to + * verified partitions, including the bootloader, boot + * partition, and all verified partitions*/ + KM_VERIFIED_BOOT_SELF_SIGNED = 1, /* The boot partition has been verified using the embedded + * certificate, and the signature is valid. The bootloader + * displays a warning and the fingerprint of the public + * key before allowing the boot process to continue.*/ + KM_VERIFIED_BOOT_UNVERIFIED = 2, /* The device may be freely modified. Device integrity is left + * to the user to verify out-of-band. The bootloader + * displays a warning to the user before allowing the boot + * process to continue */ + KM_VERIFIED_BOOT_FAILED = 3, /* The device failed verification. The bootloader displays a + * warning and stops the boot process, so no keymaster + * implementation should ever actually return this value, + * since it should not run. Included here only for + * completeness. */ +} keymaster_verified_boot_t; + +typedef enum { + KM_SECURITY_LEVEL_SOFTWARE = 0, + KM_SECURITY_LEVEL_TRUSTED_ENVIRONMENT = 1, + KM_SECURITY_LEVEL_STRONGBOX = 2, +} keymaster_security_level_t; + +/** + * Formats for key import and export. + */ +typedef enum { + KM_KEY_FORMAT_X509 = 0, /* for public key export */ + KM_KEY_FORMAT_PKCS8 = 1, /* for asymmetric key pair import */ + KM_KEY_FORMAT_RAW = 3, /* for symmetric key import and export*/ +} keymaster_key_format_t; + +/** + * The keymaster operation API consists of begin, update, finish and abort. This is the type of the + * handle used to tie the sequence of calls together. A 64-bit value is used because it's important + * that handles not be predictable. Implementations must use strong random numbers for handle + * values. + */ +typedef uint64_t keymaster_operation_handle_t; + +typedef enum { + KM_ERROR_OK = 0, + KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1, + KM_ERROR_UNSUPPORTED_PURPOSE = -2, + KM_ERROR_INCOMPATIBLE_PURPOSE = -3, + KM_ERROR_UNSUPPORTED_ALGORITHM = -4, + KM_ERROR_INCOMPATIBLE_ALGORITHM = -5, + KM_ERROR_UNSUPPORTED_KEY_SIZE = -6, + KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7, + KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8, + KM_ERROR_UNSUPPORTED_MAC_LENGTH = -9, + KM_ERROR_UNSUPPORTED_PADDING_MODE = -10, + KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11, + KM_ERROR_UNSUPPORTED_DIGEST = -12, + KM_ERROR_INCOMPATIBLE_DIGEST = -13, + KM_ERROR_INVALID_EXPIRATION_TIME = -14, + KM_ERROR_INVALID_USER_ID = -15, + KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16, + KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17, + KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18, + KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */ + KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */ + KM_ERROR_INVALID_INPUT_LENGTH = -21, + KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22, + KM_ERROR_DELEGATION_NOT_ALLOWED = -23, + KM_ERROR_KEY_NOT_YET_VALID = -24, + KM_ERROR_KEY_EXPIRED = -25, + KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26, + KM_ERROR_OUTPUT_PARAMETER_NULL = -27, + KM_ERROR_INVALID_OPERATION_HANDLE = -28, + KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29, + KM_ERROR_VERIFICATION_FAILED = -30, + KM_ERROR_TOO_MANY_OPERATIONS = -31, + KM_ERROR_UNEXPECTED_NULL_POINTER = -32, + KM_ERROR_INVALID_KEY_BLOB = -33, + KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34, + KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35, + KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36, + KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37, + KM_ERROR_INVALID_ARGUMENT = -38, + KM_ERROR_UNSUPPORTED_TAG = -39, + KM_ERROR_INVALID_TAG = -40, + KM_ERROR_MEMORY_ALLOCATION_FAILED = -41, + KM_ERROR_IMPORT_PARAMETER_MISMATCH = -44, + KM_ERROR_SECURE_HW_ACCESS_DENIED = -45, + KM_ERROR_OPERATION_CANCELLED = -46, + KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47, + KM_ERROR_SECURE_HW_BUSY = -48, + KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49, + KM_ERROR_UNSUPPORTED_EC_FIELD = -50, + KM_ERROR_MISSING_NONCE = -51, + KM_ERROR_INVALID_NONCE = -52, + KM_ERROR_MISSING_MAC_LENGTH = -53, + KM_ERROR_KEY_RATE_LIMIT_EXCEEDED = -54, + KM_ERROR_CALLER_NONCE_PROHIBITED = -55, + KM_ERROR_KEY_MAX_OPS_EXCEEDED = -56, + KM_ERROR_INVALID_MAC_LENGTH = -57, + KM_ERROR_MISSING_MIN_MAC_LENGTH = -58, + KM_ERROR_UNSUPPORTED_MIN_MAC_LENGTH = -59, + KM_ERROR_UNSUPPORTED_KDF = -60, + KM_ERROR_UNSUPPORTED_EC_CURVE = -61, + KM_ERROR_KEY_REQUIRES_UPGRADE = -62, + KM_ERROR_ATTESTATION_CHALLENGE_MISSING = -63, + KM_ERROR_KEYMASTER_NOT_CONFIGURED = -64, + KM_ERROR_ATTESTATION_APPLICATION_ID_MISSING = -65, + KM_ERROR_CANNOT_ATTEST_IDS = -66, + KM_ERROR_ROLLBACK_RESISTANCE_UNAVAILABLE = -67, + KM_ERROR_NO_USER_CONFIRMATION = -71, + KM_ERROR_DEVICE_LOCKED = -72, + KM_ERROR_EARLY_BOOT_ENDED = -73, + KM_ERROR_ATTESTATION_KEYS_NOT_PROVISIONED = -74, + KM_ERROR_ATTESTATION_IDS_NOT_PROVISIONED = -75, + KM_ERROR_INCOMPATIBLE_MGF_DIGEST = -78, + KM_ERROR_UNSUPPORTED_MGF_DIGEST = -79, + KM_ERROR_MISSING_NOT_BEFORE = -80, + KM_ERROR_MISSING_NOT_AFTER = -81, + KM_ERROR_MISSING_ISSUER_SUBJECT = -82, + KM_ERROR_INVALID_ISSUER_SUBJECT = -83, + KM_ERROR_BOOT_LEVEL_EXCEEDED = -84, + + KM_ERROR_UNIMPLEMENTED = -100, + KM_ERROR_VERSION_MISMATCH = -101, + + KM_ERROR_UNKNOWN_ERROR = -1000, +} keymaster_error_t; + +/* Convenience functions for manipulating keymaster tag types */ + +static inline keymaster_tag_type_t keymaster_tag_get_type(keymaster_tag_t tag) { + return (keymaster_tag_type_t)(tag & (0xF << 28)); +} + +static inline uint32_t keymaster_tag_mask_type(keymaster_tag_t tag) { + return tag & 0x0FFFFFFF; +} + +static inline bool keymaster_tag_type_repeatable(keymaster_tag_type_t type) { + switch (type) { + case KM_UINT_REP: + case KM_ENUM_REP: + return true; + default: + return false; + } +} + +static inline bool keymaster_tag_repeatable(keymaster_tag_t tag) { + return keymaster_tag_type_repeatable(keymaster_tag_get_type(tag)); +} + +/* Convenience functions for manipulating keymaster_key_param_t structs */ + +inline keymaster_key_param_t keymaster_param_enum(keymaster_tag_t tag, uint32_t value) { + // assert(keymaster_tag_get_type(tag) == KM_ENUM || keymaster_tag_get_type(tag) == KM_ENUM_REP); + keymaster_key_param_t param; + memset(¶m, 0, sizeof(param)); + param.tag = tag; + param.enumerated = value; + return param; +} + +inline keymaster_key_param_t keymaster_param_int(keymaster_tag_t tag, uint32_t value) { + // assert(keymaster_tag_get_type(tag) == KM_INT || keymaster_tag_get_type(tag) == KM_INT_REP); + keymaster_key_param_t param; + memset(¶m, 0, sizeof(param)); + param.tag = tag; + param.integer = value; + return param; +} + +inline keymaster_key_param_t keymaster_param_long(keymaster_tag_t tag, uint64_t value) { + // assert(keymaster_tag_get_type(tag) == KM_LONG); + keymaster_key_param_t param; + memset(¶m, 0, sizeof(param)); + param.tag = tag; + param.long_integer = value; + return param; +} + +inline keymaster_key_param_t keymaster_param_blob(keymaster_tag_t tag, const uint8_t* bytes, + size_t bytes_len) { + // assert(keymaster_tag_get_type(tag) == KM_BYTES || keymaster_tag_get_type(tag) == KM_BIGNUM); + keymaster_key_param_t param; + memset(¶m, 0, sizeof(param)); + param.tag = tag; + param.blob.data = (uint8_t*)bytes; + param.blob.data_length = bytes_len; + return param; +} + +inline keymaster_key_param_t keymaster_param_bool(keymaster_tag_t tag) { + // assert(keymaster_tag_get_type(tag) == KM_BOOL); + keymaster_key_param_t param; + memset(¶m, 0, sizeof(param)); + param.tag = tag; + param.boolean = true; + return param; +} + +inline keymaster_key_param_t keymaster_param_date(keymaster_tag_t tag, uint64_t value) { + // assert(keymaster_tag_get_type(tag) == KM_DATE); + keymaster_key_param_t param; + memset(¶m, 0, sizeof(param)); + param.tag = tag; + param.date_time = value; + return param; +} + +#define KEYMASTER_SIMPLE_COMPARE(a, b) (a < b) ? -1 : ((a > b) ? 1 : 0) +inline int keymaster_param_compare(const keymaster_key_param_t* a, const keymaster_key_param_t* b) { + int retval = KEYMASTER_SIMPLE_COMPARE((uint32_t)a->tag, (uint32_t)b->tag); + if (retval != 0) + return retval; + + switch (keymaster_tag_get_type(a->tag)) { + case KM_INVALID: + case KM_BOOL: + return 0; + case KM_ENUM: + case KM_ENUM_REP: + return KEYMASTER_SIMPLE_COMPARE(a->enumerated, b->enumerated); + case KM_UINT: + case KM_UINT_REP: + return KEYMASTER_SIMPLE_COMPARE(a->integer, b->integer); + case KM_ULONG: + case KM_ULONG_REP: + return KEYMASTER_SIMPLE_COMPARE(a->long_integer, b->long_integer); + case KM_DATE: + return KEYMASTER_SIMPLE_COMPARE(a->date_time, b->date_time); + case KM_BIGNUM: + case KM_BYTES: + // Handle the empty cases. + if (a->blob.data_length != 0 && b->blob.data_length == 0) + return -1; + if (a->blob.data_length == 0 && b->blob.data_length == 0) + return 0; + if (a->blob.data_length == 0 && b->blob.data_length > 0) + return 1; + + retval = memcmp(a->blob.data, b->blob.data, a->blob.data_length < b->blob.data_length + ? a->blob.data_length + : b->blob.data_length); + if (retval != 0) + return retval; + else if (a->blob.data_length != b->blob.data_length) { + // Equal up to the common length; longer one is larger. + if (a->blob.data_length < b->blob.data_length) + return -1; + if (a->blob.data_length > b->blob.data_length) + return 1; + } + } + + return 0; +} +#undef KEYMASTER_SIMPLE_COMPARE + +inline void keymaster_free_param_values(keymaster_key_param_t* param, size_t param_count) { + while (param_count > 0) { + param_count--; + switch (keymaster_tag_get_type(param->tag)) { + case KM_BIGNUM: + case KM_BYTES: + free((void*)param->blob.data); + param->blob.data = NULL; + break; + default: + // NOP + break; + } + ++param; + } +} + +inline void keymaster_free_param_set(keymaster_key_param_set_t* set) { + if (set) { + keymaster_free_param_values(set->params, set->length); + free(set->params); + set->params = NULL; + set->length = 0; + } +} + +inline void keymaster_free_characteristics(keymaster_key_characteristics_t* characteristics) { + if (characteristics) { + keymaster_free_param_set(&characteristics->hw_enforced); + keymaster_free_param_set(&characteristics->sw_enforced); + } +} + +inline void keymaster_free_cert_chain(keymaster_cert_chain_t* chain) { + if (chain) { + for (size_t i = 0; i < chain->entry_count; ++i) { + free((uint8_t*)chain->entries[i].data); + chain->entries[i].data = NULL; + chain->entries[i].data_length = 0; + } + free(chain->entries); + chain->entries = NULL; + chain->entry_count = 0; + } +} + +#ifdef __cplusplus +} // extern "C" +#endif // __cplusplus + +#endif // ANDROID_HARDWARE_KEYMASTER_DEFS_H diff --git a/include_all/hardware/memtrack.h b/include_all/hardware/memtrack.h new file mode 100644 index 00000000..57ba4ad7 --- /dev/null +++ b/include_all/hardware/memtrack.h @@ -0,0 +1,160 @@ +/* + * Copyright (C) 2013 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_INCLUDE_HARDWARE_MEMTRACK_H +#define ANDROID_INCLUDE_HARDWARE_MEMTRACK_H + +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <hardware/hardware.h> + +__BEGIN_DECLS + +#define MEMTRACK_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) + +/** + * The id of this module + */ +#define MEMTRACK_HARDWARE_MODULE_ID "memtrack" + +/* + * The Memory Tracker HAL is designed to return information about device-specific + * memory usage. The primary goal is to be able to track memory that is not + * trackable in any other way, for example texture memory that is allocated by + * a process, but not mapped in to that process' address space. + * A secondary goal is to be able to categorize memory used by a process into + * GL, graphics, etc. All memory sizes should be in real memory usage, + * accounting for stride, bit depth, rounding up to page size, etc. + * + * A process collecting memory statistics will call getMemory for each + * combination of pid and memory type. For each memory type that it recognizes + * the HAL should fill out an array of memtrack_record structures breaking + * down the statistics of that memory type as much as possible. For example, + * getMemory(<pid>, MEMTRACK_TYPE_GL) might return: + * { { 4096, ACCOUNTED | PRIVATE | SYSTEM }, + * { 40960, UNACCOUNTED | PRIVATE | SYSTEM }, + * { 8192, ACCOUNTED | PRIVATE | DEDICATED }, + * { 8192, UNACCOUNTED | PRIVATE | DEDICATED } } + * If the HAL could not differentiate between SYSTEM and DEDICATED memory, it + * could return: + * { { 12288, ACCOUNTED | PRIVATE }, + * { 49152, UNACCOUNTED | PRIVATE } } + * + * Memory should not overlap between types. For example, a graphics buffer + * that has been mapped into the GPU as a surface should show up when + * MEMTRACK_TYPE_GRAPHICS is requested, and not when MEMTRACK_TYPE_GL + * is requested. + */ + +enum memtrack_type { + MEMTRACK_TYPE_OTHER = 0, + MEMTRACK_TYPE_GL = 1, + MEMTRACK_TYPE_GRAPHICS = 2, + MEMTRACK_TYPE_MULTIMEDIA = 3, + MEMTRACK_TYPE_CAMERA = 4, + MEMTRACK_NUM_TYPES, +}; + +struct memtrack_record { + size_t size_in_bytes; + unsigned int flags; +}; + +/** + * Flags to differentiate memory that can already be accounted for in + * /proc/<pid>/smaps, + * (Shared_Clean + Shared_Dirty + Private_Clean + Private_Dirty = Size). + * In general, memory mapped in to a userspace process is accounted unless + * it was mapped with remap_pfn_range. + * Exactly one of these should be set. + */ +#define MEMTRACK_FLAG_SMAPS_ACCOUNTED (1 << 1) +#define MEMTRACK_FLAG_SMAPS_UNACCOUNTED (1 << 2) + +/** + * Flags to differentiate memory shared across multiple processes vs. memory + * used by a single process. Only zero or one of these may be set in a record. + * If none are set, record is assumed to count shared + private memory. + */ +#define MEMTRACK_FLAG_SHARED (1 << 3) +#define MEMTRACK_FLAG_SHARED_PSS (1 << 4) /* shared / num_procesess */ +#define MEMTRACK_FLAG_PRIVATE (1 << 5) + +/** + * Flags to differentiate memory taken from the kernel's allocation pool vs. + * memory that is dedicated to non-kernel allocations, for example a carveout + * or separate video memory. Only zero or one of these may be set in a record. + * If none are set, record is assumed to count system + dedicated memory. + */ +#define MEMTRACK_FLAG_SYSTEM (1 << 6) +#define MEMTRACK_FLAG_DEDICATED (1 << 7) + +/** + * Flags to differentiate memory accessible by the CPU in non-secure mode vs. + * memory that is protected. Only zero or one of these may be set in a record. + * If none are set, record is assumed to count secure + nonsecure memory. + */ +#define MEMTRACK_FLAG_NONSECURE (1 << 8) +#define MEMTRACK_FLAG_SECURE (1 << 9) + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +typedef struct memtrack_module { + struct hw_module_t common; + + /** + * (*init)() performs memtrack management setup actions and is called + * once before any calls to getMemory(). + * Returns 0 on success, -errno on error. + */ + int (*init)(const struct memtrack_module *module); + + /** + * (*getMemory)() expects an array of record objects and populates up to + * *num_record structures with the sizes of memory plus associated flags for + * that memory. It also updates *num_records with the total number of + * records it could return if *num_records was large enough when passed in. + * Returning records with size 0 is expected, the number of records should + * not vary between calls to getMemory for the same memory type, even + * for different pids. + * + * The caller will often call getMemory for a type and pid with + * *num_records == 0 to determine how many records to allocate room for, + * this case should be a fast-path in the HAL, returning a constant and + * not querying any kernel files. If *num_records passed in is 0, + * then records may be NULL. + * + * This function must be thread-safe, it may get called from multiple + * threads at the same time. + * + * Returns 0 on success, -ENODEV if the type is not supported, -errno + * on other errors. + */ + int (*getMemory)(const struct memtrack_module *module, + pid_t pid, + int type, + struct memtrack_record *records, + size_t *num_records); +} memtrack_module_t; + +__END_DECLS + +#endif // ANDROID_INCLUDE_HARDWARE_MEMTRACK_H diff --git a/include_all/hardware/nfc-base.h b/include_all/hardware/nfc-base.h new file mode 100644 index 00000000..d22cd5d8 --- /dev/null +++ b/include_all/hardware/nfc-base.h @@ -0,0 +1,34 @@ +// This file is autogenerated by hidl-gen. Do not edit manually. +// Source: android.hardware.nfc@1.0 +// Location: hardware/interfaces/nfc/1.0/ + +#ifndef HIDL_GENERATED_ANDROID_HARDWARE_NFC_V1_0_EXPORTED_CONSTANTS_H_ +#define HIDL_GENERATED_ANDROID_HARDWARE_NFC_V1_0_EXPORTED_CONSTANTS_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +enum { + HAL_NFC_OPEN_CPLT_EVT = 0u, + HAL_NFC_CLOSE_CPLT_EVT = 1u, + HAL_NFC_POST_INIT_CPLT_EVT = 2u, + HAL_NFC_PRE_DISCOVER_CPLT_EVT = 3u, + HAL_NFC_REQUEST_CONTROL_EVT = 4u, + HAL_NFC_RELEASE_CONTROL_EVT = 5u, + HAL_NFC_ERROR_EVT = 6u, +}; + +enum { + HAL_NFC_STATUS_OK = 0u, + HAL_NFC_STATUS_FAILED = 1u, + HAL_NFC_STATUS_ERR_TRANSPORT = 2u, + HAL_NFC_STATUS_ERR_CMD_TIMEOUT = 3u, + HAL_NFC_STATUS_REFUSED = 4u, +}; + +#ifdef __cplusplus +} +#endif + +#endif // HIDL_GENERATED_ANDROID_HARDWARE_NFC_V1_0_EXPORTED_CONSTANTS_H_ diff --git a/include_all/hardware/nfc.h b/include_all/hardware/nfc.h new file mode 100644 index 00000000..fdd79a55 --- /dev/null +++ b/include_all/hardware/nfc.h @@ -0,0 +1,277 @@ +/* + * Copyright (C) 2011, 2012 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_NFC_HAL_INTERFACE_H +#define ANDROID_NFC_HAL_INTERFACE_H + +#include <stdint.h> +#include <strings.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <hardware/hardware.h> +#include "nfc-base.h" + +__BEGIN_DECLS + + +/* NFC device HAL for NCI-based NFC controllers. + * + * This HAL allows NCI silicon vendors to make use + * of the core NCI stack in Android for their own silicon. + * + * The responibilities of the NCI HAL implementation + * are as follows: + * + * - Implement the transport to the NFC controller + * - Implement each of the HAL methods specified below as applicable to their silicon + * - Pass up received NCI messages from the controller to the stack + * + * A simplified timeline of NCI HAL method calls: + * 1) Core NCI stack calls open() + * 2) Core NCI stack executes CORE_RESET and CORE_INIT through calls to write() + * 3) Core NCI stack calls core_initialized() to allow HAL to do post-init configuration + * 4) Core NCI stack calls pre_discover() to allow HAL to prepare for RF discovery + * 5) Core NCI stack starts discovery through calls to write() + * 6) Core NCI stack stops discovery through calls to write() (e.g. screen turns off) + * 7) Core NCI stack calls pre_discover() to prepare for RF discovery (e.g. screen turned back on) + * 8) Core NCI stack starts discovery through calls to write() + * ... + * ... + * 9) Core NCI stack calls close() + */ +#define NFC_NCI_HARDWARE_MODULE_ID "nfc_nci" +#define NFC_NCI_BCM2079X_HARDWARE_MODULE_ID "nfc_nci.bcm2079x" +#define NFC_NCI_CONTROLLER "nci" + +/* + * nfc_nci_module_t should contain module-specific parameters + */ +typedef struct nfc_nci_module_t { + /** + * Common methods of the NFC NCI module. This *must* be the first member of + * nfc_nci_module_t as users of this structure will cast a hw_module_t to + * nfc_nci_module_t pointer in contexts where it's known the hw_module_t references a + * nfc_nci_module_t. + */ + struct hw_module_t common; +} nfc_nci_module_t; + +typedef uint8_t nfc_event_t; +typedef uint8_t nfc_status_t; + +/* + * The callback passed in from the NFC stack that the HAL + * can use to pass events back to the stack. + */ +typedef void (nfc_stack_callback_t) (nfc_event_t event, nfc_status_t event_status); + +/* + * The callback passed in from the NFC stack that the HAL + * can use to pass incomming data to the stack. + */ +typedef void (nfc_stack_data_callback_t) (uint16_t data_len, uint8_t* p_data); + +/* nfc_nci_device_t starts with a hw_device_t struct, + * followed by device-specific methods and members. + * + * All methods in the NCI HAL are asynchronous. + */ +typedef struct nfc_nci_device { + /** + * Common methods of the NFC NCI device. This *must* be the first member of + * nfc_nci_device_t as users of this structure will cast a hw_device_t to + * nfc_nci_device_t pointer in contexts where it's known the hw_device_t references a + * nfc_nci_device_t. + */ + struct hw_device_t common; + /* + * (*open)() Opens the NFC controller device and performs initialization. + * This may include patch download and other vendor-specific initialization. + * + * If open completes successfully, the controller should be ready to perform + * NCI initialization - ie accept CORE_RESET and subsequent commands through + * the write() call. + * + * If open() returns 0, the NCI stack will wait for a HAL_NFC_OPEN_CPLT_EVT + * before continuing. + * + * If open() returns any other value, the NCI stack will stop. + * + */ + int (*open)(const struct nfc_nci_device *p_dev, nfc_stack_callback_t *p_cback, + nfc_stack_data_callback_t *p_data_cback); + + /* + * (*write)() Performs an NCI write. + * + * This method may queue writes and return immediately. The only + * requirement is that the writes are executed in order. + */ + int (*write)(const struct nfc_nci_device *p_dev, uint16_t data_len, const uint8_t *p_data); + + /* + * (*core_initialized)() is called after the CORE_INIT_RSP is received from the NFCC. + * At this time, the HAL can do any chip-specific configuration. + * + * If core_initialized() returns 0, the NCI stack will wait for a HAL_NFC_POST_INIT_CPLT_EVT + * before continuing. + * + * If core_initialized() returns any other value, the NCI stack will continue + * immediately. + */ + int (*core_initialized)(const struct nfc_nci_device *p_dev, uint8_t* p_core_init_rsp_params); + + /* + * (*pre_discover)() Is called every time before starting RF discovery. + * It is a good place to do vendor-specific configuration that must be + * performed every time RF discovery is about to be started. + * + * If pre_discover() returns 0, the NCI stack will wait for a HAL_NFC_PRE_DISCOVER_CPLT_EVT + * before continuing. + * + * If pre_discover() returns any other value, the NCI stack will start + * RF discovery immediately. + */ + int (*pre_discover)(const struct nfc_nci_device *p_dev); + + /* + * (*close)() Closed the NFC controller. Should free all resources. + */ + int (*close)(const struct nfc_nci_device *p_dev); + + /* + * (*control_granted)() Grant HAL the exclusive control to send NCI commands. + * Called in response to HAL_REQUEST_CONTROL_EVT. + * Must only be called when there are no NCI commands pending. + * HAL_RELEASE_CONTROL_EVT will notify when HAL no longer needs exclusive control. + */ + int (*control_granted)(const struct nfc_nci_device *p_dev); + + /* + * (*power_cycle)() Restart controller by power cyle; + * HAL_OPEN_CPLT_EVT will notify when operation is complete. + */ + int (*power_cycle)(const struct nfc_nci_device *p_dev); +} nfc_nci_device_t; + +/* + * Convenience methods that the NFC stack can use to open + * and close an NCI device + */ +static inline int nfc_nci_open(const struct hw_module_t* module, + nfc_nci_device_t** dev) { + return module->methods->open(module, NFC_NCI_CONTROLLER, + (struct hw_device_t**) dev); +} + +static inline int nfc_nci_close(nfc_nci_device_t* dev) { + return dev->common.close(&dev->common); +} +/* + * End NFC NCI HAL + */ + +/* + * This is a limited NFC HAL for NXP PN544-based devices. + * This HAL as Android is moving to + * an NCI-based NFC stack. + * + * All NCI-based NFC controllers should use the NFC-NCI + * HAL instead. + * Begin PN544 specific HAL + */ +#define NFC_HARDWARE_MODULE_ID "nfc" + +#define NFC_PN544_CONTROLLER "pn544" + +typedef struct nfc_module_t { + /** + * Common methods of the NFC NXP PN544 module. This *must* be the first member of + * nfc_module_t as users of this structure will cast a hw_module_t to + * nfc_module_t pointer in contexts where it's known the hw_module_t references a + * nfc_module_t. + */ + struct hw_module_t common; +} nfc_module_t; + +/* + * PN544 linktypes. + * UART + * I2C + * USB (uses UART DAL) + */ +typedef enum { + PN544_LINK_TYPE_UART, + PN544_LINK_TYPE_I2C, + PN544_LINK_TYPE_USB, + PN544_LINK_TYPE_INVALID, +} nfc_pn544_linktype; + +typedef struct { + /** + * Common methods of the NFC NXP PN544 device. This *must* be the first member of + * nfc_pn544_device_t as users of this structure will cast a hw_device_t to + * nfc_pn544_device_t pointer in contexts where it's known the hw_device_t references a + * nfc_pn544_device_t. + */ + struct hw_device_t common; + + /* The number of EEPROM registers to write */ + uint32_t num_eeprom_settings; + + /* The actual EEPROM settings + * For PN544, each EEPROM setting is a 4-byte entry, + * of the format [0x00, addr_msb, addr_lsb, value]. + */ + uint8_t* eeprom_settings; + + /* The link type to which the PN544 is connected */ + nfc_pn544_linktype linktype; + + /* The device node to which the PN544 is connected */ + const char* device_node; + + /* On Crespo we had an I2C issue that would cause us to sometimes read + * the I2C slave address (0x57) over the bus. libnfc contains + * a hack to ignore this byte and try to read the length byte + * again. + * Set to 0 to disable the workaround, 1 to enable it. + */ + uint8_t enable_i2c_workaround; + /* I2C slave address. Multiple I2C addresses are + * possible for PN544 module. Configure address according to + * board design. + */ + uint8_t i2c_device_address; +} nfc_pn544_device_t; + +static inline int nfc_pn544_open(const struct hw_module_t* module, + nfc_pn544_device_t** dev) { + return module->methods->open(module, NFC_PN544_CONTROLLER, + (struct hw_device_t**) dev); +} + +static inline int nfc_pn544_close(nfc_pn544_device_t* dev) { + return dev->common.close(&dev->common); +} +/* + * End PN544 specific HAL + */ + +__END_DECLS + +#endif // ANDROID_NFC_HAL_INTERFACE_H diff --git a/include_all/hardware/nfc_tag.h b/include_all/hardware/nfc_tag.h new file mode 100644 index 00000000..040a07d8 --- /dev/null +++ b/include_all/hardware/nfc_tag.h @@ -0,0 +1,95 @@ +/* + * Copyright (C) 2013 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_NFC_TAG_HAL_INTERFACE_H +#define ANDROID_NFC_TAG_HAL_INTERFACE_H + +#include <stdint.h> + +#include <hardware/hardware.h> + +__BEGIN_DECLS + +/* + * HAL for programmable NFC tags. + * + */ + +#define NFC_TAG_HARDWARE_MODULE_ID "nfc_tag" +#define NFC_TAG_ID "tag" + +typedef struct nfc_tag_module_t { + /** + * Common methods of the NFC tag module. This *must* be the first member of + * nfc_tag_module_t as users of this structure will cast a hw_module_t to + * nfc_tag_module_t pointer in contexts where it's known the hw_module_t references a + * nfc_tag_module_t. + */ + struct hw_module_t common; +} nfc_tag_module_t; + +typedef struct nfc_tag_device { + /** + * Common methods of the NFC tag device. This *must* be the first member of + * nfc_tag_device_t as users of this structure will cast a hw_device_t to + * nfc_tag_device_t pointer in contexts where it's known the hw_device_t references a + * nfc_tag_device_t. + */ + struct hw_device_t common; + + /** + * Initialize the NFC tag. + * + * The driver must: + * * Set the static lock bytes to read only + * * Configure the Capability Container to disable write acess + * eg: 0xE1 0x10 <size> 0x0F + * + * This function is called once before any calls to setContent(). + * + * Return 0 on success or -errno on error. + */ + int (*init)(const struct nfc_tag_device *dev); + + /** + * Set the NFC tag content. + * + * The driver must write <data> in the data area of the tag starting at + * byte 0 of block 4 and zero the rest of the data area. + * + * Returns 0 on success or -errno on error. + */ + int (*setContent)(const struct nfc_tag_device *dev, const uint8_t *data, size_t len); + + /** + * Returns the memory size of the data area. + */ + int (*getMemorySize)(const struct nfc_tag_device *dev); +} nfc_tag_device_t; + +static inline int nfc_tag_open(const struct hw_module_t* module, + nfc_tag_device_t** dev) { + return module->methods->open(module, NFC_TAG_ID, + (struct hw_device_t**)dev); +} + +static inline int nfc_tag_close(nfc_tag_device_t* dev) { + return dev->common.close(&dev->common); +} + +__END_DECLS + +#endif // ANDROID_NFC_TAG_HAL_INTERFACE_H diff --git a/include_all/hardware/nvram.h b/include_all/hardware/nvram.h new file mode 100644 index 00000000..0654afef --- /dev/null +++ b/include_all/hardware/nvram.h @@ -0,0 +1,338 @@ +/* + * 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, + TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int nvram_close(nvram_device_t* device) { + return device->common.close(&device->common); +} + +__END_DECLS + +#endif // ANDROID_HARDWARE_NVRAM_H diff --git a/include_all/hardware/nvram_defs.h b/include_all/hardware/nvram_defs.h new file mode 100644 index 00000000..0256a3cf --- /dev/null +++ b/include_all/hardware/nvram_defs.h @@ -0,0 +1,61 @@ +/* + * Copyright (C) 2016 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. + */ + +/* + * This file contains data type definitions and constants that are useful to + * code interacting with and implementing the NVRAM HAL, even though it doesn't + * use the actual NVRAM HAL module interface. Keeping this in a separate file + * simplifies inclusion in low-level code which can't easily include the heavier + * hardware.h due to lacking standard headers. + */ + +#ifndef ANDROID_HARDWARE_NVRAM_DEFS_H +#define ANDROID_HARDWARE_NVRAM_DEFS_H + +#include <stdint.h> + +#ifdef __cplusplus +extern "C" { +#endif // __cplusplus + +/* 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; + +#ifdef __cplusplus +} // extern "C" +#endif // __cplusplus + +#endif // ANDROID_HARDWARE_NVRAM_DEFS_H diff --git a/include_all/hardware/power.h b/include_all/hardware/power.h new file mode 100644 index 00000000..bd8216ef --- /dev/null +++ b/include_all/hardware/power.h @@ -0,0 +1,343 @@ +/* + * Copyright (C) 2012 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_INCLUDE_HARDWARE_POWER_H +#define ANDROID_INCLUDE_HARDWARE_POWER_H + +#include <stdbool.h> +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <hardware/hardware.h> + +__BEGIN_DECLS + +#define POWER_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) +#define POWER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) +#define POWER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) +#define POWER_MODULE_API_VERSION_0_4 HARDWARE_MODULE_API_VERSION(0, 4) +#define POWER_MODULE_API_VERSION_0_5 HARDWARE_MODULE_API_VERSION(0, 5) + +/** + * The id of this module + */ +#define POWER_HARDWARE_MODULE_ID "power" + +/* + * Platform-level sleep state stats. + * Maximum length of Platform-level sleep state name. + */ +#define POWER_STATE_NAME_MAX_LENGTH 100 + +/* + * Platform-level sleep state stats. + * Maximum length of Platform-level sleep state voter name. + */ +#define POWER_STATE_VOTER_NAME_MAX_LENGTH 100 + +/* + * Power hint identifiers passed to (*powerHint) + */ + +typedef enum { + POWER_HINT_VSYNC = 0x00000001, + POWER_HINT_INTERACTION = 0x00000002, + /* DO NOT USE POWER_HINT_VIDEO_ENCODE/_DECODE! They will be removed in + * KLP. + */ + POWER_HINT_VIDEO_ENCODE = 0x00000003, + POWER_HINT_VIDEO_DECODE = 0x00000004, + POWER_HINT_LOW_POWER = 0x00000005, + POWER_HINT_SUSTAINED_PERFORMANCE = 0x00000006, + POWER_HINT_VR_MODE = 0x00000007, + POWER_HINT_LAUNCH = 0x00000008, + POWER_HINT_DISABLE_TOUCH = 0x00000009 +} power_hint_t; + +typedef enum { + POWER_FEATURE_DOUBLE_TAP_TO_WAKE = 0x00000001 +} feature_t; + +/* + * Platform-level sleep state stats: + * power_state_voter_t struct is useful for describing the individual voters when a + * Platform-level sleep state is chosen by aggregation of votes from multiple + * clients/system conditions. + * + * This helps in attirbuting what in the device is blocking the device from + * entering the lowest Platform-level sleep state. + */ +typedef struct { + /* + * Name of the voter. + */ + char name[POWER_STATE_VOTER_NAME_MAX_LENGTH]; + + /* + * Total time in msec the voter voted for the platform sleep state since boot. + */ + uint64_t total_time_in_msec_voted_for_since_boot; + + /* + * Number of times the voter voted for the platform sleep state since boot. + */ + uint64_t total_number_of_times_voted_since_boot; +} power_state_voter_t; + +/* + * Platform-level sleep state stats: + * power_state_platform_sleep_state_t represents the Platform-level sleep state the + * device is capable of getting into. + * + * SoCs usually have more than one Platform-level sleep state. + * + * The caller calls the get_number_of_platform_modes function to figure out the size + * of power_state_platform_sleep_state_t array where each array element represents + * a specific Platform-level sleep state. + * + * Higher the index deeper the state is i.e. lesser steady-state power is consumed + * by the platform to be resident in that state. + * + * Caller allocates power_state_voter_t *voters for each Platform-level sleep state by + * calling get_voter_list. + */ +typedef struct { + /* + * Platform-level Sleep state name. + */ + char name[POWER_STATE_NAME_MAX_LENGTH]; + + /* + * Time spent in msec at this platform-level sleep state since boot. + */ + uint64_t residency_in_msec_since_boot; + + /* + * Total number of times system entered this state. + */ + uint64_t total_transitions; + + /* + * This platform-level sleep state can only be reached during system suspend. + */ + bool supported_only_in_suspend; + + /* + * The following fields are useful if the Platform-level sleep state + * is chosen by aggregation votes from multiple clients/system conditions. + * All the voters have to say yes or all the system conditions need to be + * met to enter a platform-level sleep state. + * + * Setting number_of_voters to zero implies either the info is not available + * or the system does not follow a voting mechanism to choose this + * Platform-level sleep state. + */ + uint32_t number_of_voters; + + /* + * Voter list - Has to be allocated by the caller. + * + * Caller allocates power_state_voter_t *voters for each Platform-level sleep state + * by calling get_voter_list. + */ + power_state_voter_t *voters; +} power_state_platform_sleep_state_t; + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +typedef struct power_module { + struct hw_module_t common; + + /* + * (*init)() performs power management setup actions at runtime + * startup, such as to set default cpufreq parameters. This is + * called only by the Power HAL instance loaded by + * PowerManagerService. + * + * Platform-level sleep state stats: + * Can Also be used to initiate device specific Platform-level + * Sleep state nodes from version 0.5 onwards. + */ + void (*init)(struct power_module *module); + + /* + * (*setInteractive)() performs power management actions upon the + * system entering interactive state (that is, the system is awake + * and ready for interaction, often with UI devices such as + * display and touchscreen enabled) or non-interactive state (the + * system appears asleep, display usually turned off). The + * non-interactive state is usually entered after a period of + * inactivity, in order to conserve battery power during + * such inactive periods. + * + * Typical actions are to turn on or off devices and adjust + * cpufreq parameters. This function may also call the + * appropriate interfaces to allow the kernel to suspend the + * system to low-power sleep state when entering non-interactive + * state, and to disallow low-power suspend when the system is in + * interactive state. When low-power suspend state is allowed, the + * kernel may suspend the system whenever no wakelocks are held. + * + * on is non-zero when the system is transitioning to an + * interactive / awake state, and zero when transitioning to a + * non-interactive / asleep state. + * + * This function is called to enter non-interactive state after + * turning off the screen (if present), and called to enter + * interactive state prior to turning on the screen. + */ + void (*setInteractive)(struct power_module *module, int on); + + /* + * (*powerHint) is called to pass hints on power requirements, which + * may result in adjustment of power/performance parameters of the + * cpufreq governor and other controls. The possible hints are: + * + * POWER_HINT_VSYNC + * + * Foreground app has started or stopped requesting a VSYNC pulse + * from SurfaceFlinger. If the app has started requesting VSYNC + * then CPU and GPU load is expected soon, and it may be appropriate + * to raise speeds of CPU, memory bus, etc. The data parameter is + * non-zero to indicate VSYNC pulse is now requested, or zero for + * VSYNC pulse no longer requested. + * + * POWER_HINT_INTERACTION + * + * User is interacting with the device, for example, touchscreen + * events are incoming. CPU and GPU load may be expected soon, + * and it may be appropriate to raise speeds of CPU, memory bus, + * etc. The data parameter is the estimated length of the interaction + * in milliseconds, or 0 if unknown. + * + * POWER_HINT_LOW_POWER + * + * Low power mode is activated or deactivated. Low power mode + * is intended to save battery at the cost of performance. The data + * parameter is non-zero when low power mode is activated, and zero + * when deactivated. + * + * POWER_HINT_SUSTAINED_PERFORMANCE + * + * Sustained Performance mode is actived or deactivated. Sustained + * performance mode is intended to provide a consistent level of + * performance for a prolonged amount of time. The data parameter is + * non-zero when sustained performance mode is activated, and zero + * when deactivated. + * + * POWER_HINT_VR_MODE + * + * VR Mode is activated or deactivated. VR mode is intended to + * provide minimum guarantee for performance for the amount of time the + * device can sustain it. The data parameter is non-zero when the mode + * is activated and zero when deactivated. + * + * POWER_HINT_DISABLE_TOUCH + * + * When device enters some special modes, e.g. theater mode in Android + * Wear, there is no touch interaction expected between device and user. + * Touch controller could be disabled in those modes to save power. + * The data parameter is non-zero when touch could be disabled, and zero + * when touch needs to be re-enabled. + * + * A particular platform may choose to ignore any hint. + * + * availability: version 0.2 + * + */ + void (*powerHint)(struct power_module *module, power_hint_t hint, + void *data); + + /* + * (*setFeature) is called to turn on or off a particular feature + * depending on the state parameter. The possible features are: + * + * FEATURE_DOUBLE_TAP_TO_WAKE + * + * Enabling/Disabling this feature will allow/disallow the system + * to wake up by tapping the screen twice. + * + * availability: version 0.3 + * + */ + void (*setFeature)(struct power_module *module, feature_t feature, int state); + + /* + * Platform-level sleep state stats: + * Report cumulative info on the statistics on platform-level sleep states since boot. + * + * Caller of the function queries the get_number_of_sleep_states and allocates the + * memory for the power_state_platform_sleep_state_t *list before calling this function. + * + * power_stats module is responsible to assign values to all the fields as + * necessary. + * + * Higher the index deeper the state is i.e. lesser steady-state power is consumed + * by the platform to be resident in that state. + * + * The function returns 0 on success or negative value -errno on error. + * EINVAL - *list is NULL. + * EIO - filesystem nodes access error. + * + * availability: version 0.5 + */ + int (*get_platform_low_power_stats)(struct power_module *module, + power_state_platform_sleep_state_t *list); + + /* + * Platform-level sleep state stats: + * This function is called to determine the number of platform-level sleep states + * for get_platform_low_power_stats. + * + * The value returned by this function is used to allocate memory for + * power_state_platform_sleep_state_t *list for get_platform_low_power_stats. + * + * The number of parameters must not change for successive calls. + * + * Return number of parameters on success or negative value -errno on error. + * EIO - filesystem nodes access error. + * + * availability: version 0.5 + */ + ssize_t (*get_number_of_platform_modes)(struct power_module *module); + + /* + * Platform-level sleep state stats: + * Provides the number of voters for each of the Platform-level sleep state. + * + * Caller uses this function to allocate memory for the power_state_voter_t list. + * + * Caller has to allocate the space for the *voter array which is + * get_number_of_platform_modes() long. + * + * Return 0 on success or negative value -errno on error. + * EINVAL - *voter is NULL. + * EIO - filesystem nodes access error. + * + * availability: version 0.5 + */ + int (*get_voter_list)(struct power_module *module, size_t *voter); + +} power_module_t; + + +__END_DECLS + +#endif // ANDROID_INCLUDE_HARDWARE_POWER_H diff --git a/include_all/hardware/sensors-base.h b/include_all/hardware/sensors-base.h new file mode 100644 index 00000000..dbf99f57 --- /dev/null +++ b/include_all/hardware/sensors-base.h @@ -0,0 +1,144 @@ +// This file is autogenerated by hidl-gen. Do not edit manually. +// Source: android.hardware.sensors@1.0 +// Location: hardware/interfaces/sensors/1.0/ + +#ifndef HIDL_GENERATED_ANDROID_HARDWARE_SENSORS_V1_0_EXPORTED_CONSTANTS_H_ +#define HIDL_GENERATED_ANDROID_HARDWARE_SENSORS_V1_0_EXPORTED_CONSTANTS_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +enum { + SENSOR_HAL_NORMAL_MODE = 0, + SENSOR_HAL_DATA_INJECTION_MODE = 1, +}; + +enum { + SENSOR_TYPE_META_DATA = 0, + SENSOR_TYPE_ACCELEROMETER = 1, + SENSOR_TYPE_MAGNETIC_FIELD = 2, + SENSOR_TYPE_ORIENTATION = 3, + SENSOR_TYPE_GYROSCOPE = 4, + SENSOR_TYPE_LIGHT = 5, + SENSOR_TYPE_PRESSURE = 6, + SENSOR_TYPE_TEMPERATURE = 7, + SENSOR_TYPE_PROXIMITY = 8, + SENSOR_TYPE_GRAVITY = 9, + SENSOR_TYPE_LINEAR_ACCELERATION = 10, + SENSOR_TYPE_ROTATION_VECTOR = 11, + SENSOR_TYPE_RELATIVE_HUMIDITY = 12, + SENSOR_TYPE_AMBIENT_TEMPERATURE = 13, + SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14, + SENSOR_TYPE_GAME_ROTATION_VECTOR = 15, + SENSOR_TYPE_GYROSCOPE_UNCALIBRATED = 16, + SENSOR_TYPE_SIGNIFICANT_MOTION = 17, + SENSOR_TYPE_STEP_DETECTOR = 18, + SENSOR_TYPE_STEP_COUNTER = 19, + SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR = 20, + SENSOR_TYPE_HEART_RATE = 21, + SENSOR_TYPE_TILT_DETECTOR = 22, + SENSOR_TYPE_WAKE_GESTURE = 23, + SENSOR_TYPE_GLANCE_GESTURE = 24, + SENSOR_TYPE_PICK_UP_GESTURE = 25, + SENSOR_TYPE_WRIST_TILT_GESTURE = 26, + SENSOR_TYPE_DEVICE_ORIENTATION = 27, + SENSOR_TYPE_POSE_6DOF = 28, + SENSOR_TYPE_STATIONARY_DETECT = 29, + SENSOR_TYPE_MOTION_DETECT = 30, + SENSOR_TYPE_HEART_BEAT = 31, + SENSOR_TYPE_DYNAMIC_SENSOR_META = 32, + SENSOR_TYPE_ADDITIONAL_INFO = 33, + SENSOR_TYPE_LOW_LATENCY_OFFBODY_DETECT = 34, + SENSOR_TYPE_ACCELEROMETER_UNCALIBRATED = 35, + SENSOR_TYPE_HINGE_ANGLE = 36, + SENSOR_TYPE_HEAD_TRACKER = 37, + SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES = 38, + SENSOR_TYPE_GYROSCOPE_LIMITED_AXES = 39, + SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED = 40, + SENSOR_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED = 41, + SENSOR_TYPE_HEADING = 42, + SENSOR_TYPE_DEVICE_PRIVATE_BASE = 65536 /* 0x10000 */, +}; + +enum { + SENSOR_FLAG_WAKE_UP = 1u, + SENSOR_FLAG_CONTINUOUS_MODE = 0u, + SENSOR_FLAG_ON_CHANGE_MODE = 2u, + SENSOR_FLAG_ONE_SHOT_MODE = 4u, + SENSOR_FLAG_SPECIAL_REPORTING_MODE = 6u, + SENSOR_FLAG_DATA_INJECTION = 16u /* 0x10 */, + SENSOR_FLAG_DYNAMIC_SENSOR = 32u /* 0x20 */, + SENSOR_FLAG_ADDITIONAL_INFO = 64u /* 0x40 */, + SENSOR_FLAG_DIRECT_CHANNEL_ASHMEM = 1024u /* 0x400 */, + SENSOR_FLAG_DIRECT_CHANNEL_GRALLOC = 2048u /* 0x800 */, + SENSOR_FLAG_MASK_REPORTING_MODE = 14u /* 0xE */, + SENSOR_FLAG_MASK_DIRECT_REPORT = 896u /* 0x380 */, + SENSOR_FLAG_MASK_DIRECT_CHANNEL = 3072u /* 0xC00 */, +}; + +typedef enum { + SENSOR_FLAG_SHIFT_REPORTING_MODE = 1, + SENSOR_FLAG_SHIFT_DATA_INJECTION = 4, + SENSOR_FLAG_SHIFT_DYNAMIC_SENSOR = 5, + SENSOR_FLAG_SHIFT_ADDITIONAL_INFO = 6, + SENSOR_FLAG_SHIFT_DIRECT_REPORT = 7, + SENSOR_FLAG_SHIFT_DIRECT_CHANNEL = 10, +} sensor_flag_shift_t; + +enum { + SENSOR_STATUS_NO_CONTACT = -1 /* -1 */, + SENSOR_STATUS_UNRELIABLE = 0, + SENSOR_STATUS_ACCURACY_LOW = 1, + SENSOR_STATUS_ACCURACY_MEDIUM = 2, + SENSOR_STATUS_ACCURACY_HIGH = 3, +}; + +enum { + META_DATA_FLUSH_COMPLETE = 1u, +}; + +typedef enum { + AINFO_BEGIN = 0u, + AINFO_END = 1u, + AINFO_UNTRACKED_DELAY = 65536u /* 0x10000 */, + AINFO_INTERNAL_TEMPERATURE = 65537u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_UNTRACKED_DELAY implicitly + 1 */, + AINFO_VEC3_CALIBRATION = 65538u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_INTERNAL_TEMPERATURE implicitly + 1 */, + AINFO_SENSOR_PLACEMENT = 65539u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_VEC3_CALIBRATION implicitly + 1 */, + AINFO_SAMPLING = 65540u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_SENSOR_PLACEMENT implicitly + 1 */, + AINFO_CHANNEL_NOISE = 131072u /* 0x20000 */, + AINFO_CHANNEL_SAMPLER = 131073u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_NOISE implicitly + 1 */, + AINFO_CHANNEL_FILTER = 131074u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_SAMPLER implicitly + 1 */, + AINFO_CHANNEL_LINEAR_TRANSFORM = 131075u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_FILTER implicitly + 1 */, + AINFO_CHANNEL_NONLINEAR_MAP = 131076u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_LINEAR_TRANSFORM implicitly + 1 */, + AINFO_CHANNEL_RESAMPLER = 131077u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_CHANNEL_NONLINEAR_MAP implicitly + 1 */, + AINFO_LOCAL_GEOMAGNETIC_FIELD = 196608u /* 0x30000 */, + AINFO_LOCAL_GRAVITY = 196609u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_LOCAL_GEOMAGNETIC_FIELD implicitly + 1 */, + AINFO_DOCK_STATE = 196610u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_LOCAL_GRAVITY implicitly + 1 */, + AINFO_HIGH_PERFORMANCE_MODE = 196611u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_DOCK_STATE implicitly + 1 */, + AINFO_MAGNETIC_FIELD_CALIBRATION = 196612u /* ::android::hardware::sensors::V1_0::AdditionalInfoType.AINFO_HIGH_PERFORMANCE_MODE implicitly + 1 */, + AINFO_CUSTOM_START = 268435456u /* 0x10000000 */, + AINFO_DEBUGGING_START = 1073741824u /* 0x40000000 */, +} additional_info_type_t; + +typedef enum { + SENSOR_DIRECT_RATE_STOP = 0, + SENSOR_DIRECT_RATE_NORMAL = 1 /* ::android::hardware::sensors::V1_0::RateLevel.STOP implicitly + 1 */, + SENSOR_DIRECT_RATE_FAST = 2 /* ::android::hardware::sensors::V1_0::RateLevel.NORMAL implicitly + 1 */, + SENSOR_DIRECT_RATE_VERY_FAST = 3 /* ::android::hardware::sensors::V1_0::RateLevel.FAST implicitly + 1 */, +} direct_rate_level_t; + +typedef enum { + SENSOR_DIRECT_MEM_TYPE_ASHMEM = 1, + SENSOR_DIRECT_MEM_TYPE_GRALLOC = 2 /* ::android::hardware::sensors::V1_0::SharedMemType.ASHMEM implicitly + 1 */, +} direct_mem_type_t; + +typedef enum { + SENSOR_DIRECT_FMT_SENSORS_EVENT = 1, +} direct_format_t; + +#ifdef __cplusplus +} +#endif + +#endif // HIDL_GENERATED_ANDROID_HARDWARE_SENSORS_V1_0_EXPORTED_CONSTANTS_H_ diff --git a/include_all/hardware/sensors.h b/include_all/hardware/sensors.h new file mode 100644 index 00000000..5f490b53 --- /dev/null +++ b/include_all/hardware/sensors.h @@ -0,0 +1,836 @@ +/* + * Copyright (C) 2012 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_SENSORS_INTERFACE_H +#define ANDROID_SENSORS_INTERFACE_H + +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <hardware/hardware.h> +#include <cutils/native_handle.h> + +#include "sensors-base.h" + +__BEGIN_DECLS + +/*****************************************************************************/ + +#define SENSORS_HEADER_VERSION 1 +#define SENSORS_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) +#define SENSORS_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, SENSORS_HEADER_VERSION) +#define SENSORS_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION) +#define SENSORS_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION_2(1, 1, SENSORS_HEADER_VERSION) +#define SENSORS_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION_2(1, 2, SENSORS_HEADER_VERSION) +#define SENSORS_DEVICE_API_VERSION_1_3 HARDWARE_DEVICE_API_VERSION_2(1, 3, SENSORS_HEADER_VERSION) +#define SENSORS_DEVICE_API_VERSION_1_4 HARDWARE_DEVICE_API_VERSION_2(1, 4, SENSORS_HEADER_VERSION) + +/** + * Please see the Sensors section of source.android.com for an + * introduction to and detailed descriptions of Android sensor types: + * http://source.android.com/devices/sensors/index.html + */ + +/** + * The id of this module + */ +#define SENSORS_HARDWARE_MODULE_ID "sensors" + +/** + * Name of the sensors device to open + */ +#define SENSORS_HARDWARE_POLL "poll" + +/** + * Sensor handle is greater than 0 and less than INT32_MAX. + * + * **** Deprecated **** + * Defined values below are kept for code compatibility. Note sensor handle can be as large as + * INT32_MAX. + */ +#define SENSORS_HANDLE_BASE 0 +#define SENSORS_HANDLE_BITS 31 +#define SENSORS_HANDLE_COUNT (1ull<<SENSORS_HANDLE_BITS) + + +/* + * **** Deprecated ***** + * flags for (*batch)() + * Availability: SENSORS_DEVICE_API_VERSION_1_0 + * see (*batch)() documentation for details. + * Deprecated as of SENSORS_DEVICE_API_VERSION_1_3. + * WAKE_UP_* sensors replace WAKE_UPON_FIFO_FULL concept. + */ +enum { + SENSORS_BATCH_DRY_RUN = 0x00000001, + SENSORS_BATCH_WAKE_UPON_FIFO_FULL = 0x00000002 +}; + +/* + * what field for meta_data_event_t + */ +enum { + /* a previous flush operation has completed */ + // META_DATA_FLUSH_COMPLETE = 1, + META_DATA_VERSION /* always last, leave auto-assigned */ +}; + +/* + * The permission to use for body sensors (like heart rate monitors). + * See sensor types for more details on what sensors should require this + * permission. + */ +#define SENSOR_PERMISSION_BODY_SENSORS "android.permission.BODY_SENSORS" + +/* + * sensor flags legacy names + * + * please use SENSOR_FLAG_* directly for new implementation. + * @see sensor_t + */ + +#define SENSOR_FLAG_MASK(nbit, shift) (((1<<(nbit))-1)<<(shift)) +#define SENSOR_FLAG_MASK_1(shift) SENSOR_FLAG_MASK(1, shift) + +/* + * Mask and shift for reporting mode sensor flags defined above. + */ +#define REPORTING_MODE_SHIFT SENSOR_FLAG_SHIFT_REPORTING_MODE +#define REPORTING_MODE_NBIT (3) +#define REPORTING_MODE_MASK SENSOR_FLAG_MASK_REPORTING_MODE + +/* + * Mask and shift for data_injection mode sensor flags defined above. + */ +#define DATA_INJECTION_SHIFT SENSOR_FLAG_SHIFT_DATA_INJECTION +#define DATA_INJECTION_MASK SENSOR_FLAG_DATA_INJECTION + +/* + * Mask and shift for dynamic sensor flag. + */ +#define DYNAMIC_SENSOR_SHIFT SENSOR_FLAG_SHIFT_DYNAMIC_SENSOR +#define DYNAMIC_SENSOR_MASK SENSOR_FLAG_DYNAMIC_SENSOR + +/* + * Mask and shift for sensor additional information support. + */ +#define ADDITIONAL_INFO_SHIFT SENSOR_FLAG_SHIFT_ADDITIONAL_INFO +#define ADDITIONAL_INFO_MASK SENSOR_FLAG_ADDITIONAL_INFO + +/* + * Legacy alias of SENSOR_TYPE_MAGNETIC_FIELD. + * + * Previously, the type of a sensor measuring local magnetic field is named + * SENSOR_TYPE_GEOMAGNETIC_FIELD and SENSOR_TYPE_MAGNETIC_FIELD is its alias. + * SENSOR_TYPE_MAGNETIC_FIELD is redefined as primary name to avoid confusion. + * SENSOR_TYPE_GEOMAGNETIC_FIELD is the alias and is deprecating. New implementation must not use + * SENSOR_TYPE_GEOMAGNETIC_FIELD. + */ +#define SENSOR_TYPE_GEOMAGNETIC_FIELD SENSOR_TYPE_MAGNETIC_FIELD + +/* + * Sensor string types for Android defined sensor types. + * + * For Android defined sensor types, string type will be override in sensor service and thus no + * longer needed to be added to sensor_t data structure. + * + * These definitions are going to be removed soon. + */ +#define SENSOR_STRING_TYPE_ACCELEROMETER "android.sensor.accelerometer" +#define SENSOR_STRING_TYPE_MAGNETIC_FIELD "android.sensor.magnetic_field" +#define SENSOR_STRING_TYPE_ORIENTATION "android.sensor.orientation" +#define SENSOR_STRING_TYPE_GYROSCOPE "android.sensor.gyroscope" +#define SENSOR_STRING_TYPE_LIGHT "android.sensor.light" +#define SENSOR_STRING_TYPE_PRESSURE "android.sensor.pressure" +#define SENSOR_STRING_TYPE_TEMPERATURE "android.sensor.temperature" +#define SENSOR_STRING_TYPE_PROXIMITY "android.sensor.proximity" +#define SENSOR_STRING_TYPE_GRAVITY "android.sensor.gravity" +#define SENSOR_STRING_TYPE_LINEAR_ACCELERATION "android.sensor.linear_acceleration" +#define SENSOR_STRING_TYPE_ROTATION_VECTOR "android.sensor.rotation_vector" +#define SENSOR_STRING_TYPE_RELATIVE_HUMIDITY "android.sensor.relative_humidity" +#define SENSOR_STRING_TYPE_AMBIENT_TEMPERATURE "android.sensor.ambient_temperature" +#define SENSOR_STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED "android.sensor.magnetic_field_uncalibrated" +#define SENSOR_STRING_TYPE_GAME_ROTATION_VECTOR "android.sensor.game_rotation_vector" +#define SENSOR_STRING_TYPE_GYROSCOPE_UNCALIBRATED "android.sensor.gyroscope_uncalibrated" +#define SENSOR_STRING_TYPE_SIGNIFICANT_MOTION "android.sensor.significant_motion" +#define SENSOR_STRING_TYPE_STEP_DETECTOR "android.sensor.step_detector" +#define SENSOR_STRING_TYPE_STEP_COUNTER "android.sensor.step_counter" +#define SENSOR_STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR "android.sensor.geomagnetic_rotation_vector" +#define SENSOR_STRING_TYPE_HEART_RATE "android.sensor.heart_rate" +#define SENSOR_STRING_TYPE_TILT_DETECTOR "android.sensor.tilt_detector" +#define SENSOR_STRING_TYPE_WAKE_GESTURE "android.sensor.wake_gesture" +#define SENSOR_STRING_TYPE_GLANCE_GESTURE "android.sensor.glance_gesture" +#define SENSOR_STRING_TYPE_PICK_UP_GESTURE "android.sensor.pick_up_gesture" +#define SENSOR_STRING_TYPE_WRIST_TILT_GESTURE "android.sensor.wrist_tilt_gesture" +#define SENSOR_STRING_TYPE_DEVICE_ORIENTATION "android.sensor.device_orientation" +#define SENSOR_STRING_TYPE_POSE_6DOF "android.sensor.pose_6dof" +#define SENSOR_STRING_TYPE_STATIONARY_DETECT "android.sensor.stationary_detect" +#define SENSOR_STRING_TYPE_MOTION_DETECT "android.sensor.motion_detect" +#define SENSOR_STRING_TYPE_HEART_BEAT "android.sensor.heart_beat" +#define SENSOR_STRING_TYPE_DYNAMIC_SENSOR_META "android.sensor.dynamic_sensor_meta" +#define SENSOR_STRING_TYPE_ADDITIONAL_INFO "android.sensor.additional_info" +#define SENSOR_STRING_TYPE_LOW_LATENCY_OFFBODY_DETECT "android.sensor.low_latency_offbody_detect" +#define SENSOR_STRING_TYPE_ACCELEROMETER_UNCALIBRATED "android.sensor.accelerometer_uncalibrated" +#define SENSOR_STRING_TYPE_HINGE_ANGLE "android.sensor.hinge_angle" +#define SENSOR_STRING_TYPE_HEAD_TRACKER "android.sensor.head_tracker" +#define SENSOR_STRING_TYPE_ACCELEROMETER_LIMITED_AXES "android.sensor.accelerometer_limited_axes" +#define SENSOR_STRING_TYPE_GYROSCOPE_LIMITED_AXES "android.sensor.gyroscope_limited_axes" +#define SENSOR_STRING_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED "android.sensor.accelerometer_limited_axes_uncalibrated" +#define SENSOR_STRING_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED "android.sensor.gyroscope_limited_axes_uncalibrated" +#define SENSOR_STRING_TYPE_HEADING "android.sensor.heading" + +/** + * Values returned by the accelerometer in various locations in the universe. + * all values are in SI units (m/s^2) + */ +#define GRAVITY_SUN (275.0f) +#define GRAVITY_EARTH (9.80665f) + +/** Maximum magnetic field on Earth's surface */ +#define MAGNETIC_FIELD_EARTH_MAX (60.0f) + +/** Minimum magnetic field on Earth's surface */ +#define MAGNETIC_FIELD_EARTH_MIN (30.0f) + +struct sensor_t; + +/** + * sensor event data + */ +typedef struct { + union { + float v[3]; + struct { + float x; + float y; + float z; + }; + struct { + float azimuth; + float pitch; + float roll; + }; + }; + int8_t status; + uint8_t reserved[3]; +} sensors_vec_t; + +/** + * uncalibrated accelerometer, gyroscope and magnetometer event data + */ +typedef struct { + union { + float uncalib[3]; + struct { + float x_uncalib; + float y_uncalib; + float z_uncalib; + }; + }; + union { + float bias[3]; + struct { + float x_bias; + float y_bias; + float z_bias; + }; + }; +} uncalibrated_event_t; + +/** + * Meta data event data + */ +typedef struct meta_data_event { + int32_t what; + int32_t sensor; +} meta_data_event_t; + +/** + * Dynamic sensor meta event. See the description of SENSOR_TYPE_DYNAMIC_SENSOR_META type for + * details. + */ +typedef struct dynamic_sensor_meta_event { + int32_t connected; + int32_t handle; + const struct sensor_t * sensor; // should be NULL if connected == false + uint8_t uuid[16]; // UUID of a dynamic sensor (using RFC 4122 byte order) + // For UUID 12345678-90AB-CDEF-1122-334455667788 the uuid field + // should be initialized as: + // {0x12, 0x34, 0x56, 0x78, 0x90, 0xAB, 0xCD, 0xEF, 0x11, ...} +} dynamic_sensor_meta_event_t; + +/** + * Heart rate event data + */ +typedef struct { + // Heart rate in beats per minute. + // Set to 0 when status is SENSOR_STATUS_UNRELIABLE or ..._NO_CONTACT + float bpm; + // Status of the sensor for this reading. Set to one SENSOR_STATUS_... + // Note that this value should only be set for sensors that explicitly define + // the meaning of this field. This field is not piped through the framework + // for other sensors. + int8_t status; +} heart_rate_event_t; + +typedef struct { + int32_t type; // type of payload data, see additional_info_type_t + int32_t serial; // sequence number of this frame for this type + union { + // for each frame, a single data type, either int32_t or float, should be used. + int32_t data_int32[14]; + float data_float[14]; + }; +} additional_info_event_t; + +typedef struct { + float rx; + float ry; + float rz; + float vx; + float vy; + float vz; + int32_t discontinuity_count; +} head_tracker_event_t; + +/** + * limited axes imu event data + */ +typedef struct { + union { + float calib[3]; + struct { + float x; + float y; + float z; + }; + }; + union { + float supported[3]; + struct { + float x_supported; + float y_supported; + float z_supported; + }; + }; +} limited_axes_imu_event_t; + +/** + * limited axes uncalibrated imu event data + */ +typedef struct { + union { + float uncalib[3]; + struct { + float x_uncalib; + float y_uncalib; + float z_uncalib; + }; + }; + union { + float bias[3]; + struct { + float x_bias; + float y_bias; + float z_bias; + }; + }; + union { + float supported[3]; + struct { + float x_supported; + float y_supported; + float z_supported; + }; + }; +} limited_axes_imu_uncalibrated_event_t; + +/** + * Heading event data + */ +typedef struct { + float heading; + float accuracy; +} heading_event_t; + +// LINT.IfChange +/** + * Union of the various types of sensor data + * that can be returned. + * This type needs to remain identical to ASensorEvent. + */ +typedef struct sensors_event_t { + /* must be sizeof(struct sensors_event_t) */ + int32_t version; + + /* sensor identifier */ + int32_t sensor; + + /* sensor type */ + int32_t type; + + /* reserved */ + int32_t reserved0; + + /* time is in nanosecond */ + int64_t timestamp; + + union { + union { + float data[16]; + + /* acceleration values are in meter per second per second (m/s^2) */ + sensors_vec_t acceleration; + + /* magnetic vector values are in micro-Tesla (uT) */ + sensors_vec_t magnetic; + + /* orientation values are in degrees */ + sensors_vec_t orientation; + + /* gyroscope values are in rad/s */ + sensors_vec_t gyro; + + /* temperature is in degrees centigrade (Celsius) */ + float temperature; + + /* distance in centimeters */ + float distance; + + /* light in SI lux units */ + float light; + + /* pressure in hectopascal (hPa) */ + float pressure; + + /* relative humidity in percent */ + float relative_humidity; + + /* uncalibrated gyroscope values are in rad/s */ + uncalibrated_event_t uncalibrated_gyro; + + /* uncalibrated magnetometer values are in micro-Teslas */ + uncalibrated_event_t uncalibrated_magnetic; + + /* uncalibrated accelerometer values are in meter per second per second (m/s^2) */ + uncalibrated_event_t uncalibrated_accelerometer; + + /* heart rate data containing value in bpm and status */ + heart_rate_event_t heart_rate; + + /* this is a special event. see SENSOR_TYPE_META_DATA above. + * sensors_meta_data_event_t events are all reported with a type of + * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero. + */ + meta_data_event_t meta_data; + + /* dynamic sensor meta event. See SENSOR_TYPE_DYNAMIC_SENSOR_META type for details */ + dynamic_sensor_meta_event_t dynamic_sensor_meta; + + /* + * special additional sensor information frame, see + * SENSOR_TYPE_ADDITIONAL_INFO for details. + */ + additional_info_event_t additional_info; + + /* vector describing head orientation (added for legacy code support only) */ + head_tracker_event_t head_tracker; + + /* + * limited axes imu event, See + * SENSOR_TYPE_GYROSCOPE_LIMITED_AXES and + * SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES for details. + */ + limited_axes_imu_event_t limited_axes_imu; + + /* + * limited axes imu uncalibrated event, See + * SENSOR_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED and + * SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED for details. + */ + limited_axes_imu_uncalibrated_event_t limited_axes_imu_uncalibrated; + + /* heading data containing value in degrees and its accuracy */ + heading_event_t heading; + }; + + union { + uint64_t data[8]; + + /* step-counter */ + uint64_t step_counter; + } u64; + }; + + /* Reserved flags for internal use. Set to zero. */ + uint32_t flags; + + uint32_t reserved1[3]; +} sensors_event_t; +// LINT.ThenChange(frameworks/native/include/android/sensor.h) + + +/* see SENSOR_TYPE_META_DATA */ +typedef sensors_event_t sensors_meta_data_event_t; + + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +struct sensors_module_t { + struct hw_module_t common; + + /** + * Enumerate all available sensors. The list is returned in "list". + * return number of sensors in the list + */ + int (*get_sensors_list)(struct sensors_module_t* module, + struct sensor_t const** list); + + /** + * Place the module in a specific mode. The following modes are defined + * + * 0 - Normal operation. Default state of the module. + * 1 - Loopback mode. Data is injected for the supported + * sensors by the sensor service in this mode. + * return 0 on success + * -EINVAL if requested mode is not supported + * -EPERM if operation is not allowed + */ + int (*set_operation_mode)(unsigned int mode); +}; + +struct sensor_t { + + /* Name of this sensor. + * All sensors of the same "type" must have a different "name". + */ + const char* name; + + /* vendor of the hardware part */ + const char* vendor; + + /* version of the hardware part + driver. The value of this field + * must increase when the driver is updated in a way that changes the + * output of this sensor. This is important for fused sensors when the + * fusion algorithm is updated. + */ + int version; + + /* handle that identifies this sensors. This handle is used to reference + * this sensor throughout the HAL API. + */ + int handle; + + /* this sensor's type. */ + int type; + + /* maximum range of this sensor's value in SI units */ + float maxRange; + + /* smallest difference between two values reported by this sensor */ + float resolution; + + /* rough estimate of this sensor's power consumption in mA */ + float power; + + /* this value depends on the reporting mode: + * + * continuous: minimum sample period allowed in microseconds + * on-change : 0 + * one-shot :-1 + * special : 0, unless otherwise noted + */ + int32_t minDelay; + + /* number of events reserved for this sensor in the batch mode FIFO. + * If there is a dedicated FIFO for this sensor, then this is the + * size of this FIFO. If the FIFO is shared with other sensors, + * this is the size reserved for that sensor and it can be zero. + */ + uint32_t fifoReservedEventCount; + + /* maximum number of events of this sensor that could be batched. + * This is especially relevant when the FIFO is shared between + * several sensors; this value is then set to the size of that FIFO. + */ + uint32_t fifoMaxEventCount; + + /* type of this sensor as a string. + * + * If type is OEM specific or sensor manufacturer specific type + * (>=SENSOR_TYPE_DEVICE_PRIVATE_BASE), this string must be defined with reserved domain of + * vendor/OEM as a prefix, e.g. com.google.glass.onheaddetector + * + * For sensors of Android defined types, Android framework will override this value. It is ok to + * leave it pointing to an empty string. + */ + const char* stringType; + + /* permission required to see this sensor, register to it and receive data. + * Set to "" if no permission is required. Some sensor types like the + * heart rate monitor have a mandatory require_permission. + * For sensors that always require a specific permission, like the heart + * rate monitor, the android framework might overwrite this string + * automatically. + */ + const char* requiredPermission; + + /* This value is defined only for continuous mode and on-change sensors. It is the delay between + * two sensor events corresponding to the lowest frequency that this sensor supports. When lower + * frequencies are requested through batch()/setDelay() the events will be generated at this + * frequency instead. It can be used by the framework or applications to estimate when the batch + * FIFO may be full. + * + * NOTE: 1) period_ns is in nanoseconds where as maxDelay/minDelay are in microseconds. + * continuous, on-change: maximum sampling period allowed in microseconds. + * one-shot, special : 0 + * 2) maxDelay should always fit within a 32 bit signed integer. It is declared as 64 bit + * on 64 bit architectures only for binary compatibility reasons. + * Availability: SENSORS_DEVICE_API_VERSION_1_3 + */ + #ifdef __LP64__ + int64_t maxDelay; + #else + int32_t maxDelay; + #endif + + /* Flags for sensor. See SENSOR_FLAG_* above. Only the least significant 32 bits are used here. + * It is declared as 64 bit on 64 bit architectures only for binary compatibility reasons. + * Availability: SENSORS_DEVICE_API_VERSION_1_3 + */ + #ifdef __LP64__ + uint64_t flags; + #else + uint32_t flags; + #endif + + /* reserved fields, must be zero */ + void* reserved[2]; +}; + +/** + * Shared memory information for a direct channel + */ +struct sensors_direct_mem_t { + int type; // enum SENSOR_DIRECT_MEM_... + int format; // enum SENSOR_DIRECT_FMT_... + size_t size; // size of the memory region, in bytes + const struct native_handle *handle; // shared memory handle, which is interpreted differently + // depending on type +}; + +/** + * Direct channel report configuration + */ +struct sensors_direct_cfg_t { + int rate_level; // enum SENSOR_DIRECT_RATE_... +}; + +/* + * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1 + * and is present for backward binary and source compatibility. + * See the Sensors HAL interface section for complete descriptions of the + * following functions: + * http://source.android.com/devices/sensors/index.html#hal + */ +struct sensors_poll_device_t { + struct hw_device_t common; + int (*activate)(struct sensors_poll_device_t *dev, + int sensor_handle, int enabled); + int (*setDelay)(struct sensors_poll_device_t *dev, + int sensor_handle, int64_t sampling_period_ns); + int (*poll)(struct sensors_poll_device_t *dev, + sensors_event_t* data, int count); +}; + +/* + * struct sensors_poll_device_1 is used in HAL versions >= SENSORS_DEVICE_API_VERSION_1_0 + */ +typedef struct sensors_poll_device_1 { + union { + /* sensors_poll_device_1 is compatible with sensors_poll_device_t, + * and can be down-cast to it + */ + struct sensors_poll_device_t v0; + + struct { + struct hw_device_t common; + + /* Activate/de-activate one sensor. + * + * sensor_handle is the handle of the sensor to change. + * enabled set to 1 to enable, or 0 to disable the sensor. + * + * Before sensor activation, existing sensor events that have not + * been picked up by poll() should be abandoned so that application + * upon new activation request will not get stale events. + * (events that are generated during latter activation or during + * data injection mode after sensor deactivation) + * + * Return 0 on success, negative errno code otherwise. + */ + int (*activate)(struct sensors_poll_device_t *dev, + int sensor_handle, int enabled); + + /** + * Set the events's period in nanoseconds for a given sensor. + * If sampling_period_ns > max_delay it will be truncated to + * max_delay and if sampling_period_ns < min_delay it will be + * replaced by min_delay. + */ + int (*setDelay)(struct sensors_poll_device_t *dev, + int sensor_handle, int64_t sampling_period_ns); + + /** + * Write an array of sensor_event_t to data. The size of the + * available buffer is specified by count. Returns number of + * valid sensor_event_t. + * + * This function should block if there is no sensor event + * available when being called. Thus, return value should always be + * positive. + */ + int (*poll)(struct sensors_poll_device_t *dev, + sensors_event_t* data, int count); + }; + }; + + + /* + * Sets a sensor’s parameters, including sampling frequency and maximum + * report latency. This function can be called while the sensor is + * activated, in which case it must not cause any sensor measurements to + * be lost: transitioning from one sampling rate to the other cannot cause + * lost events, nor can transitioning from a high maximum report latency to + * a low maximum report latency. + * See the Batching sensor results page for details: + * http://source.android.com/devices/sensors/batching.html + */ + int (*batch)(struct sensors_poll_device_1* dev, + int sensor_handle, int flags, int64_t sampling_period_ns, + int64_t max_report_latency_ns); + + /* + * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t) + * to the end of the "batch mode" FIFO for the specified sensor and flushes + * the FIFO. + * If the FIFO is empty or if the sensor doesn't support batching (FIFO size zero), + * it should return SUCCESS along with a trivial META_DATA_FLUSH_COMPLETE event added to the + * event stream. This applies to all sensors other than one-shot sensors. + * If the sensor is a one-shot sensor, flush must return -EINVAL and not generate + * any flush complete metadata. + * If the sensor is not active at the time flush() is called, flush() should return + * -EINVAL. + */ + int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle); + + /* + * Inject a single sensor sample to be to this device. + * data points to the sensor event to be injected + * return 0 on success + * -EPERM if operation is not allowed + * -EINVAL if sensor event cannot be injected + */ + int (*inject_sensor_data)(struct sensors_poll_device_1 *dev, const sensors_event_t *data); + + /* + * Register/unregister direct report channel. + * + * A HAL declares support for direct report by setting non-NULL values for both + * register_direct_channel and config_direct_report. + * + * This function has two operation modes: + * + * Register: mem != NULL, register a channel using supplied shared memory information. By the + * time this function returns, sensors must finish initializing shared memory content + * (format dependent, see SENSOR_DIRECT_FMT_*). + * Parameters: + * mem points to a valid struct sensors_direct_mem_t. + * channel_handle is ignored. + * Return value: + * A handle of channel (>0, <INT32_MAX) when success, which later can be referred in + * unregister or config_direct_report call, or error code (<0) when failed + * Unregister: mem == NULL, unregister a previously registered channel. + * Parameters: + * mem set to NULL + * channel_handle contains handle of channel to be unregistered + * Return value: + * 0, even if the channel_handle is invalid, in which case it will be a no-op. + */ + int (*register_direct_channel)(struct sensors_poll_device_1 *dev, + const struct sensors_direct_mem_t* mem, int channel_handle); + + /* + * Configure direct sensor event report in direct channel. + * + * Start, modify rate or stop direct report of a sensor in a certain direct channel. A special + * case is setting sensor handle -1 to stop means to stop all active sensor report on the + * channel specified. + * + * A HAL declares support for direct report by setting non-NULL values for both + * register_direct_channel and config_direct_report. + * + * Parameters: + * sensor_handle sensor to be configured. The sensor has to support direct report + * mode by setting flags of sensor_t. Also, direct report mode is only + * defined for continuous reporting mode sensors. + * channel_handle channel handle to be configured. + * config direct report parameters, see sensor_direct_cfg_t. + * Return value: + * - when sensor is started or sensor rate level is changed: return positive identifier of + * sensor in specified channel if successful, otherwise return negative error code. + * - when sensor is stopped: return 0 for success or negative error code for failure. + */ + int (*config_direct_report)(struct sensors_poll_device_1 *dev, + int sensor_handle, int channel_handle, const struct sensors_direct_cfg_t *config); + + /* + * Reserved for future use, must be zero. + */ + void (*reserved_procs[5])(void); + +} sensors_poll_device_1_t; + + +/** convenience API for opening and closing a device */ + +static inline int sensors_open(const struct hw_module_t* module, + struct sensors_poll_device_t** device) { + return module->methods->open(module, + SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int sensors_close(struct sensors_poll_device_t* device) { + return device->common.close(&device->common); +} + +static inline int sensors_open_1(const struct hw_module_t* module, + sensors_poll_device_1_t** device) { + return module->methods->open(module, + SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int sensors_close_1(sensors_poll_device_1_t* device) { + return device->common.close(&device->common); +} + +__END_DECLS + +#endif // ANDROID_SENSORS_INTERFACE_H diff --git a/include_all/hardware/sound_trigger.h b/include_all/hardware/sound_trigger.h new file mode 100644 index 00000000..7119637b --- /dev/null +++ b/include_all/hardware/sound_trigger.h @@ -0,0 +1,201 @@ +/* + * Copyright (C) 2014 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. + */ + +#include <system/audio.h> +#include <system/sound_trigger.h> +#include <hardware/hardware.h> + +#ifndef ANDROID_SOUND_TRIGGER_HAL_H +#define ANDROID_SOUND_TRIGGER_HAL_H + + +__BEGIN_DECLS + +/** + * The id of this module + */ +#define SOUND_TRIGGER_HARDWARE_MODULE_ID "sound_trigger" + +/** + * Name of the audio devices to open + */ +#define SOUND_TRIGGER_HARDWARE_INTERFACE "sound_trigger_hw_if" + +#define SOUND_TRIGGER_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) +#define SOUND_TRIGGER_MODULE_API_VERSION_CURRENT SOUND_TRIGGER_MODULE_API_VERSION_1_0 + + +#define SOUND_TRIGGER_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) +#define SOUND_TRIGGER_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION(1, 1) +#define SOUND_TRIGGER_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION(1, 2) +#define SOUND_TRIGGER_DEVICE_API_VERSION_1_3 HARDWARE_DEVICE_API_VERSION(1, 3) +#define SOUND_TRIGGER_DEVICE_API_VERSION_CURRENT SOUND_TRIGGER_DEVICE_API_VERSION_1_3 + +/** + * List of known sound trigger HAL modules. This is the base name of the sound_trigger HAL + * library composed of the "sound_trigger." prefix, one of the base names below and + * a suffix specific to the device. + * e.g: sondtrigger.primary.goldfish.so or sound_trigger.primary.default.so + */ + +#define SOUND_TRIGGER_HARDWARE_MODULE_ID_PRIMARY "primary" + + +/** + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +struct sound_trigger_module { + struct hw_module_t common; +}; + +typedef void (*recognition_callback_t)(struct sound_trigger_recognition_event *event, void *cookie); +typedef void (*sound_model_callback_t)(struct sound_trigger_model_event *event, void *cookie); + +struct sound_trigger_hw_device { + struct hw_device_t common; + + /* + * Retrieve implementation properties. + */ + int (*get_properties)(const struct sound_trigger_hw_device *dev, + struct sound_trigger_properties *properties); + + /* + * Load a sound model. Once loaded, recognition of this model can be started and stopped. + * Only one active recognition per model at a time. The SoundTrigger service will handle + * concurrent recognition requests by different users/applications on the same model. + * The implementation returns a unique handle used by other functions (unload_sound_model(), + * start_recognition(), etc... + */ + int (*load_sound_model)(const struct sound_trigger_hw_device *dev, + struct sound_trigger_sound_model *sound_model, + sound_model_callback_t callback, + void *cookie, + sound_model_handle_t *handle); + + /* + * Unload a sound model. A sound model can be unloaded to make room for a new one to overcome + * implementation limitations. + */ + int (*unload_sound_model)(const struct sound_trigger_hw_device *dev, + sound_model_handle_t handle); + + /* Start recognition on a given model. Only one recognition active at a time per model. + * Once recognition succeeds of fails, the callback is called. + * TODO: group recognition configuration parameters into one struct and add key phrase options. + */ + int (*start_recognition)(const struct sound_trigger_hw_device *dev, + sound_model_handle_t sound_model_handle, + const struct sound_trigger_recognition_config *config, + recognition_callback_t callback, + void *cookie); + + /* Stop recognition on a given model. + * The implementation does not have to call the callback when stopped via this method. + */ + int (*stop_recognition)(const struct sound_trigger_hw_device *dev, + sound_model_handle_t sound_model_handle); + + /* Stop recognition on all models. + * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_1 or above. + * If no implementation is provided, stop_recognition will be called for each running model. + */ + int (*stop_all_recognitions)(const struct sound_trigger_hw_device* dev); + + /* Get the current state of a given model. + * The state will be returned as a recognition event, via the callback that was registered + * in the start_recognition method. + * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_2 or above. + */ + int (*get_model_state)(const struct sound_trigger_hw_device *dev, + sound_model_handle_t sound_model_handle); + + /* Set a model specific ModelParameter with the given value. This parameter + * will keep its value for the duration the model is loaded regardless of starting and stopping + * recognition. Once the model is unloaded, the value will be lost. + * Returns 0 or an error code. + * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. + */ + int (*set_parameter)(const struct sound_trigger_hw_device *dev, + sound_model_handle_t sound_model_handle, + sound_trigger_model_parameter_t model_param, int32_t value); + + /* Get a model specific ModelParameter. This parameter will keep its value + * for the duration the model is loaded regardless of starting and stopping recognition. + * Once the model is unloaded, the value will be lost. If the value is not set, a default + * value is returned. See sound_trigger_model_parameter_t for parameter default values. + * Returns 0 or an error code. On return 0, value pointer will be set. + * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. + */ + int (*get_parameter)(const struct sound_trigger_hw_device *dev, + sound_model_handle_t sound_model_handle, + sound_trigger_model_parameter_t model_param, int32_t* value); + + /* Get supported parameter attributes with respect to the provided model + * handle. Along with determining the valid range, this API is also used + * to determine if a given parameter ID is supported at all by the + * modelHandle for use with getParameter and setParameter APIs. + * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. + */ + int (*query_parameter)(const struct sound_trigger_hw_device *dev, + sound_model_handle_t sound_model_handle, + sound_trigger_model_parameter_t model_param, + sound_trigger_model_parameter_range_t* param_range); + + /* + * Retrieve verbose extended implementation properties. + * The header pointer is intented to be cast to the proper extended + * properties struct based on the header version. + * The returned pointer is valid throughout the lifetime of the driver. + * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. + */ + const struct sound_trigger_properties_header* (*get_properties_extended) + (const struct sound_trigger_hw_device *dev); + + /* Start recognition on a given model. Only one recognition active at a time per model. + * Once recognition succeeds of fails, the callback is called. + * Recognition API includes extended config fields. The header is intended to be base to + * the proper config struct based on the header version. + * Only supported for device api versions SOUND_TRIGGER_DEVICE_API_VERSION_1_3 or above. + */ + int (*start_recognition_extended)(const struct sound_trigger_hw_device *dev, + sound_model_handle_t sound_model_handle, + const struct sound_trigger_recognition_config_header *header, + recognition_callback_t callback, + void *cookie); +}; + +typedef struct sound_trigger_hw_device sound_trigger_hw_device_t; + +/** convenience API for opening and closing a supported device */ + +static inline int sound_trigger_hw_device_open(const struct hw_module_t* module, + struct sound_trigger_hw_device** device) +{ + return module->methods->open(module, SOUND_TRIGGER_HARDWARE_INTERFACE, + TO_HW_DEVICE_T_OPEN(device)); +} + +static inline int sound_trigger_hw_device_close(struct sound_trigger_hw_device* device) +{ + return device->common.close(&device->common); +} + +__END_DECLS + +#endif // ANDROID_SOUND_TRIGGER_HAL_H diff --git a/include_all/hardware/tv_input.h b/include_all/hardware/tv_input.h new file mode 100644 index 00000000..b421d430 --- /dev/null +++ b/include_all/hardware/tv_input.h @@ -0,0 +1,405 @@ +/* + * Copyright 2014 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_TV_INPUT_INTERFACE_H +#define ANDROID_TV_INPUT_INTERFACE_H + +#include <stdint.h> +#include <sys/cdefs.h> +#include <sys/types.h> + +#include <hardware/hardware.h> +#include <system/audio.h> +#include <cutils/native_handle.h> + +__BEGIN_DECLS + +/* + * Module versioning information for the TV input hardware module, based on + * tv_input_module_t.common.module_api_version. + * + * Version History: + * + * TV_INPUT_MODULE_API_VERSION_0_1: + * Initial TV input hardware module API. + * + */ + +#define TV_INPUT_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) + +#define TV_INPUT_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION(0, 1) + +/* + * The id of this module + */ +#define TV_INPUT_HARDWARE_MODULE_ID "tv_input" + +#define TV_INPUT_DEFAULT_DEVICE "default" + +/*****************************************************************************/ + +/* + * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM + * and the fields of this data structure must begin with hw_module_t + * followed by module specific information. + */ +typedef struct tv_input_module { + struct hw_module_t common; +} tv_input_module_t; + +/*****************************************************************************/ + +enum { + /* Generic hardware. */ + TV_INPUT_TYPE_OTHER_HARDWARE = 1, + /* Tuner. (e.g. built-in terrestrial tuner) */ + TV_INPUT_TYPE_TUNER = 2, + TV_INPUT_TYPE_COMPOSITE = 3, + TV_INPUT_TYPE_SVIDEO = 4, + TV_INPUT_TYPE_SCART = 5, + TV_INPUT_TYPE_COMPONENT = 6, + TV_INPUT_TYPE_VGA = 7, + TV_INPUT_TYPE_DVI = 8, + /* Physical HDMI port. (e.g. HDMI 1) */ + TV_INPUT_TYPE_HDMI = 9, + TV_INPUT_TYPE_DISPLAY_PORT = 10, +}; +typedef uint32_t tv_input_type_t; + +typedef struct tv_input_device_info { + /* Device ID */ + int device_id; + + /* Type of physical TV input. */ + tv_input_type_t type; + + union { + struct { + /* HDMI port ID number */ + uint32_t port_id; + } hdmi; + + /* TODO: add other type specific information. */ + + int32_t type_info_reserved[16]; + }; + + /* TODO: Add capability if necessary. */ + + /* + * Audio info + * + * audio_type == AUDIO_DEVICE_NONE if this input has no audio. + */ + audio_devices_t audio_type; + const char* audio_address; + + int32_t reserved[16]; +} tv_input_device_info_t; + +/* See tv_input_event_t for more details. */ +enum { + /* + * Hardware notifies the framework that a device is available. + * + * Note that DEVICE_AVAILABLE and DEVICE_UNAVAILABLE events do not represent + * hotplug events (i.e. plugging cable into or out of the physical port). + * These events notify the framework whether the port is available or not. + * For a concrete example, when a user plugs in or pulls out the HDMI cable + * from a HDMI port, it does not generate DEVICE_AVAILABLE and/or + * DEVICE_UNAVAILABLE events. However, if a user inserts a pluggable USB + * tuner into the Android device, it will generate a DEVICE_AVAILABLE event + * and when the port is removed, it should generate a DEVICE_UNAVAILABLE + * event. + * + * For hotplug events, please see STREAM_CONFIGURATION_CHANGED for more + * details. + * + * HAL implementation should register devices by using this event when the + * device boots up. The framework will recognize device reported via this + * event only. In addition, the implementation could use this event to + * notify the framework that a removable TV input device (such as USB tuner + * as stated in the example above) is attached. + */ + TV_INPUT_EVENT_DEVICE_AVAILABLE = 1, + /* + * Hardware notifies the framework that a device is unavailable. + * + * HAL implementation should generate this event when a device registered + * by TV_INPUT_EVENT_DEVICE_AVAILABLE is no longer available. For example, + * the event can indicate that a USB tuner is plugged out from the Android + * device. + * + * Note that this event is not for indicating cable plugged out of the port; + * for that purpose, the implementation should use + * STREAM_CONFIGURATION_CHANGED event. This event represents the port itself + * being no longer available. + */ + TV_INPUT_EVENT_DEVICE_UNAVAILABLE = 2, + /* + * Stream configurations are changed. Client should regard all open streams + * at the specific device are closed, and should call + * get_stream_configurations() again, opening some of them if necessary. + * + * HAL implementation should generate this event when the available stream + * configurations change for any reason. A typical use case of this event + * would be to notify the framework that the input signal has changed + * resolution, or that the cable is plugged out so that the number of + * available streams is 0. + * + * The implementation may use this event to indicate hotplug status of the + * port. the framework regards input devices with no available streams as + * disconnected, so the implementation can generate this event with no + * available streams to indicate that this device is disconnected, and vice + * versa. + */ + TV_INPUT_EVENT_STREAM_CONFIGURATIONS_CHANGED = 3, + /* + * Hardware is done with capture request with the buffer. Client can assume + * ownership of the buffer again. + * + * HAL implementation should generate this event after request_capture() if + * it succeeded. The event shall have the buffer with the captured image. + */ + TV_INPUT_EVENT_CAPTURE_SUCCEEDED = 4, + /* + * Hardware met a failure while processing a capture request or client + * canceled the request. Client can assume ownership of the buffer again. + * + * The event is similar to TV_INPUT_EVENT_CAPTURE_SUCCEEDED, but HAL + * implementation generates this event upon a failure to process + * request_capture(), or a request cancellation. + */ + TV_INPUT_EVENT_CAPTURE_FAILED = 5, +}; +typedef uint32_t tv_input_event_type_t; + +typedef struct tv_input_capture_result { + /* Device ID */ + int device_id; + + /* Stream ID */ + int stream_id; + + /* Sequence number of the request */ + uint32_t seq; + + /* + * The buffer passed to hardware in request_capture(). The content of + * buffer is undefined (although buffer itself is valid) for + * TV_INPUT_CAPTURE_FAILED event. + */ + buffer_handle_t buffer; + + /* + * Error code for the request. -ECANCELED if request is cancelled; other + * error codes are unknown errors. + */ + int error_code; +} tv_input_capture_result_t; + +typedef struct tv_input_event { + tv_input_event_type_t type; + + union { + /* + * TV_INPUT_EVENT_DEVICE_AVAILABLE: all fields are relevant + * TV_INPUT_EVENT_DEVICE_UNAVAILABLE: only device_id is relevant + * TV_INPUT_EVENT_STREAM_CONFIGURATIONS_CHANGED: only device_id is + * relevant + */ + tv_input_device_info_t device_info; + /* + * TV_INPUT_EVENT_CAPTURE_SUCCEEDED: error_code is not relevant + * TV_INPUT_EVENT_CAPTURE_FAILED: all fields are relevant + */ + tv_input_capture_result_t capture_result; + }; +} tv_input_event_t; + +typedef struct tv_input_callback_ops { + /* + * event contains the type of the event and additional data if necessary. + * The event object is guaranteed to be valid only for the duration of the + * call. + * + * data is an object supplied at device initialization, opaque to the + * hardware. +     */ + void (*notify)(struct tv_input_device* dev, + tv_input_event_t* event, void* data); +} tv_input_callback_ops_t; + +enum { + TV_STREAM_TYPE_INDEPENDENT_VIDEO_SOURCE = 1, + TV_STREAM_TYPE_BUFFER_PRODUCER = 2, +}; +typedef uint32_t tv_stream_type_t; + +typedef struct tv_stream_config { + /* + * ID number of the stream. This value is used to identify the whole stream + * configuration. + */ + int stream_id; + + /* Type of the stream */ + tv_stream_type_t type; + + /* Max width/height of the stream. */ + uint32_t max_video_width; + uint32_t max_video_height; +} tv_stream_config_t; + +typedef struct buffer_producer_stream { + /* + * IN/OUT: Width / height of the stream. Client may request for specific + * size but hardware may change it. Client must allocate buffers with + * specified width and height. + */ + uint32_t width; + uint32_t height; + + /* OUT: Client must set this usage when allocating buffer. */ + uint32_t usage; + + /* OUT: Client must allocate a buffer with this format. */ + uint32_t format; +} buffer_producer_stream_t; + +typedef struct tv_stream { + /* IN: ID in the stream configuration */ + int stream_id; + + /* OUT: Type of the stream (for convenience) */ + tv_stream_type_t type; + + /* Data associated with the stream for client's use */ + union { + /* OUT: A native handle describing the sideband stream source */ + native_handle_t* sideband_stream_source_handle; + + /* IN/OUT: Details are in buffer_producer_stream_t */ + buffer_producer_stream_t buffer_producer; + }; +} tv_stream_t; + +/* + * Every device data structure must begin with hw_device_t + * followed by module specific public methods and attributes. + */ +typedef struct tv_input_device { + struct hw_device_t common; + + /* + * initialize: + * + * Provide callbacks to the device and start operation. At first, no device + * is available and after initialize() completes, currently available + * devices including static devices should notify via callback. + * + * Framework owns callbacks object. + * + * data is a framework-owned object which would be sent back to the + * framework for each callback notifications. + * + * Return 0 on success. + */ + int (*initialize)(struct tv_input_device* dev, + const tv_input_callback_ops_t* callback, void* data); + + /* + * get_stream_configurations: + * + * Get stream configurations for a specific device. An input device may have + * multiple configurations. + * + * The configs object is guaranteed to be valid only until the next call to + * get_stream_configurations() or STREAM_CONFIGURATIONS_CHANGED event. + * + * Return 0 on success. + */ + int (*get_stream_configurations)(const struct tv_input_device* dev, + int device_id, int* num_configurations, + const tv_stream_config_t** configs); + + /* + * open_stream: + * + * Open a stream with given stream ID. Caller owns stream object, and the + * populated data is only valid until the stream is closed. + * + * Return 0 on success; -EBUSY if the client should close other streams to + * open the stream; -EEXIST if the stream with the given ID is already open; + * -EINVAL if device_id and/or stream_id are invalid; other non-zero value + * denotes unknown error. + */ + int (*open_stream)(struct tv_input_device* dev, int device_id, + tv_stream_t* stream); + + /* + * close_stream: + * + * Close a stream to a device. data in tv_stream_t* object associated with + * the stream_id is obsolete once this call finishes. + * + * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if + * device_id and/or stream_id are invalid. + */ + int (*close_stream)(struct tv_input_device* dev, int device_id, + int stream_id); + + /* + * request_capture: + * + * Request buffer capture for a stream. This is only valid for buffer + * producer streams. The buffer should be created with size, format and + * usage specified in the stream. Framework provides seq in an + * increasing sequence per each stream. Hardware should provide the picture + * in a chronological order according to seq. For example, if two + * requests are being processed at the same time, the request with the + * smaller seq should get an earlier frame. + * + * The framework releases the ownership of the buffer upon calling this + * function. When the buffer is filled, hardware notifies the framework + * via TV_INPUT_EVENT_CAPTURE_FINISHED callback, and the ownership is + * transferred back to framework at that time. + * + * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if + * device_id and/or stream_id are invalid; -EWOULDBLOCK if HAL cannot take + * additional requests until it releases a buffer. + */ + int (*request_capture)(struct tv_input_device* dev, int device_id, + int stream_id, buffer_handle_t buffer, uint32_t seq); + + /* + * cancel_capture: + * + * Cancel an ongoing capture. Hardware should release the buffer as soon as + * possible via TV_INPUT_EVENT_CAPTURE_FAILED callback. + * + * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if + * device_id, stream_id, and/or seq are invalid. + */ + int (*cancel_capture)(struct tv_input_device* dev, int device_id, + int stream_id, uint32_t seq); + + void* reserved[16]; +} tv_input_device_t; + +__END_DECLS + +#endif // ANDROID_TV_INPUT_INTERFACE_H diff --git a/include_all/hardware/vibrator.h b/include_all/hardware/vibrator.h new file mode 100644 index 00000000..361085f4 --- /dev/null +++ b/include_all/hardware/vibrator.h @@ -0,0 +1,73 @@ +/* + * Copyright (C) 2013 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 _HARDWARE_VIBRATOR_H +#define _HARDWARE_VIBRATOR_H + +#include <hardware/hardware.h> + +__BEGIN_DECLS + +#define VIBRATOR_API_VERSION HARDWARE_MODULE_API_VERSION(1,0) + +/** + * The id of this module + */ +#define VIBRATOR_HARDWARE_MODULE_ID "vibrator" + +/** + * The id of the main vibrator device + */ +#define VIBRATOR_DEVICE_ID_MAIN "main_vibrator" + +struct vibrator_device; +typedef struct vibrator_device { + /** + * Common methods of the vibrator device. This *must* be the first member of + * vibrator_device as users of this structure will cast a hw_device_t to + * vibrator_device pointer in contexts where it's known the hw_device_t references a + * vibrator_device. + */ + struct hw_device_t common; + + /** Turn on vibrator + * + * This function must only be called after the previous timeout has expired or + * was canceled (through vibrator_off()). + * + * @param timeout_ms number of milliseconds to vibrate + * + * @return 0 in case of success, negative errno code else + */ + int (*vibrator_on)(struct vibrator_device* vibradev, unsigned int timeout_ms); + + /** Turn off vibrator + * + * Cancel a previously-started vibration, if any. + * + * @return 0 in case of success, negative errno code else + */ + int (*vibrator_off)(struct vibrator_device* vibradev); +} vibrator_device_t; + +static inline int vibrator_open(const struct hw_module_t* module, vibrator_device_t** device) +{ + return module->methods->open(module, VIBRATOR_DEVICE_ID_MAIN, TO_HW_DEVICE_T_OPEN(device)); +} + +__END_DECLS + +#endif // _HARDWARE_VIBRATOR_H diff --git a/include/hardware/activity_recognition.h b/include_vendor/hardware/activity_recognition.h index 22007236..22007236 100644 --- a/include/hardware/activity_recognition.h +++ b/include_vendor/hardware/activity_recognition.h diff --git a/include/hardware/audio_alsaops.h b/include_vendor/hardware/audio_alsaops.h index 476c311f..476c311f 100644 --- a/include/hardware/audio_alsaops.h +++ b/include_vendor/hardware/audio_alsaops.h diff --git a/include/hardware/consumerir.h b/include_vendor/hardware/consumerir.h index 15334c11..15334c11 100644 --- a/include/hardware/consumerir.h +++ b/include_vendor/hardware/consumerir.h diff --git a/include/hardware/fused_location.h b/include_vendor/hardware/fused_location.h index 550e1933..d8cfc7b7 100644 --- a/include/hardware/fused_location.h +++ b/include_vendor/hardware/fused_location.h @@ -19,7 +19,7 @@ #include <hardware/hardware.h> -#include "gnss-base.h" +#include <hardware/gnss-base.h> /** * This header file defines the interface of the Fused Location Provider. diff --git a/include/hardware/lights.h b/include_vendor/hardware/lights.h index b3d28b0a..b3d28b0a 100644 --- a/include/hardware/lights.h +++ b/include_vendor/hardware/lights.h diff --git a/include/hardware/local_time_hal.h b/include_vendor/hardware/local_time_hal.h index 1bbbf116..1bbbf116 100644 --- a/include/hardware/local_time_hal.h +++ b/include_vendor/hardware/local_time_hal.h diff --git a/include/hardware/radio.h b/include_vendor/hardware/radio.h index 413f4133..413f4133 100644 --- a/include/hardware/radio.h +++ b/include_vendor/hardware/radio.h diff --git a/include/hardware/thermal.h b/include_vendor/hardware/thermal.h index 5db6ee0e..5db6ee0e 100644 --- a/include/hardware/thermal.h +++ b/include_vendor/hardware/thermal.h diff --git a/include/hardware/vr.h b/include_vendor/hardware/vr.h index 69f86547..69f86547 100644 --- a/include/hardware/vr.h +++ b/include_vendor/hardware/vr.h diff --git a/modules/audio_remote_submix/audio_hw.cpp b/modules/audio_remote_submix/audio_hw.cpp index f96854b5..d6c8c7b6 100644 --- a/modules/audio_remote_submix/audio_hw.cpp +++ b/modules/audio_remote_submix/audio_hw.cpp @@ -199,9 +199,9 @@ struct submix_stream_in { // Determine whether the specified sample rate is supported by the submix module. static bool sample_rate_supported(const uint32_t sample_rate) { - // Set of sample rates supported by Format_from_SR_C() frameworks/av/media/libnbaio/NAIO.cpp. static const unsigned int supported_sample_rates[] = { 8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, + 192000 /* for IEC 61937 encapsulated E-AC-3(-JOC) */ }; bool return_value; SUBMIX_VALUE_IN_SET(sample_rate, supported_sample_rates, &return_value); @@ -679,7 +679,8 @@ static int out_set_parameters(struct audio_stream *stream, const char *kvpairs) // FIXME this is using hard-coded strings but in the future, this functionality will be // converted to use audio HAL extensions required to support tunneling - if ((parms.getInt(String8("exiting"), exiting) == NO_ERROR) && (exiting > 0)) { + if ((parms.getInt(String8(AUDIO_PARAMETER_KEY_EXITING), exiting) == NO_ERROR) + && (exiting > 0)) { struct submix_audio_device * const rsxadev = audio_stream_get_submix_stream_out(stream)->dev; pthread_mutex_lock(&rsxadev->lock); @@ -1239,6 +1240,10 @@ static int adev_open_output_stream(struct audio_hw_device *dev, *stream_out = NULL; // Make sure it's possible to open the device given the current audio config. + if (!audio_is_linear_pcm(config->format)) { + ALOGD("adev_open_output_stream(): not supported for audio format %#x", config->format); + return -EINVAL; + } submix_sanitize_config(config, false); int route_idx = -1; @@ -1454,6 +1459,11 @@ static int adev_open_input_stream(struct audio_hw_device *dev, *stream_in = NULL; + if (!audio_is_linear_pcm(config->format)) { + ALOGD("adev_open_input_stream(): not supported for audio format %#x", config->format); + return -EINVAL; + } + // Do we already have a route for this address int route_idx = -1; diff --git a/modules/gralloc/gr.h b/modules/gralloc/gr.h index 14fe6a05..fe66c9be 100644 --- a/modules/gralloc/gr.h +++ b/modules/gralloc/gr.h @@ -24,6 +24,7 @@ #include <hardware/gralloc.h> #include <pthread.h> #include <errno.h> +#include <unistd.h> #include <cutils/native_handle.h> @@ -32,8 +33,10 @@ struct private_module_t; struct private_handle_t; +static const size_t kPageSize = getpagesize(); + inline size_t roundUpToPageSize(size_t x) { - return (x + (PAGE_SIZE-1)) & ~(PAGE_SIZE-1); + return (x + (kPageSize-1)) & ~(kPageSize-1); } int mapFrameBufferLocked(struct private_module_t* module, int format); diff --git a/modules/gralloc/gralloc.cpp b/modules/gralloc/gralloc.cpp index 87bda975..f7ea01cf 100644 --- a/modules/gralloc/gralloc.cpp +++ b/modules/gralloc/gralloc.cpp @@ -224,7 +224,11 @@ static int gralloc_alloc(alloc_device_t* dev, case HAL_PIXEL_FORMAT_RAW16: bytesPerPixel = 2; break; + case HAL_PIXEL_FORMAT_BLOB: + bytesPerPixel = 1; + break; default: + ALOGE("gralloc_alloc bad format %d", format); return -EINVAL; } diff --git a/modules/input/evdev/InputDevice.cpp b/modules/input/evdev/InputDevice.cpp index a1bce643..1e3da589 100644 --- a/modules/input/evdev/InputDevice.cpp +++ b/modules/input/evdev/InputDevice.cpp @@ -24,7 +24,6 @@ #include <linux/input.h> -#define __STDC_FORMAT_MACROS #include <cinttypes> #include <cstdlib> #include <string> diff --git a/modules/radio/Android.bp b/modules/radio/Android.bp index 7240869f..3d9ddef1 100644 --- a/modules/radio/Android.bp +++ b/modules/radio/Android.bp @@ -43,6 +43,7 @@ cc_library_shared { // Stub radio tool that can be run in native. cc_binary { name: "radio_hal_tool", + vendor: true, srcs: ["radio_hal_tool.c"], cflags: [ "-Wall", diff --git a/modules/sensors/dynamic_sensor/Android.bp b/modules/sensors/dynamic_sensor/Android.bp index 890da82d..160e5950 100644 --- a/modules/sensors/dynamic_sensor/Android.bp +++ b/modules/sensors/dynamic_sensor/Android.bp @@ -35,9 +35,17 @@ cc_defaults { export_include_dirs: ["."], shared_libs: [ + "libbase", "libhidparser", + "server_configurable_flags", ], + static_libs: [ + "dynamic_sensors_flags_c_lib", + ], + + cpp_std: "c++20", + target: { android: { srcs: [ @@ -53,12 +61,12 @@ cc_defaults { "RingBuffer.cpp", ], shared_libs: [ - "libbase", "libcutils", "liblog", "libutils", ], header_libs: [ + "libbase_headers", "libhardware_headers", "libstagefright_foundation_headers", ], @@ -182,3 +190,17 @@ cc_binary { "HidUtils/test", ], } + +aconfig_declarations { + name: "dynamic_sensors_flags", + package: "com.android.libhardware.dynamic.sensors.flags", + container: "system", + srcs: ["dynamic_sensors.aconfig"], +} + +cc_aconfig_library { + name: "dynamic_sensors_flags_c_lib", + aconfig_declarations: "dynamic_sensors_flags", + host_supported: true, + vendor: true, +}
\ No newline at end of file diff --git a/modules/sensors/dynamic_sensor/DynamicSensorManager.h b/modules/sensors/dynamic_sensor/DynamicSensorManager.h index b8a73203..2cae1208 100644 --- a/modules/sensors/dynamic_sensor/DynamicSensorManager.h +++ b/modules/sensors/dynamic_sensor/DynamicSensorManager.h @@ -125,10 +125,11 @@ private: // daemons std::vector<sp<BaseDynamicSensorDaemon>> mDaemonVector; - // Sensor operation queue. Calls to the sensor HAL must complete within 1 - // second. + // Sensor operation queue. Calls to the sensor HAL should complete within ~1 + // second, but to permit delayed replies due to sniff mode, etc., we use a + // slightly longer timeout here. static constexpr std::chrono::milliseconds - kSensorOpTimeout = std::chrono::milliseconds(900); + kSensorOpTimeout = std::chrono::milliseconds(1600); std::mutex mSensorOpQueueLock; std::queue<std::pair<uint64_t, std::shared_future<int>>> mSensorOpQueue; uint64_t mNextSensorOpIndex = 0; diff --git a/modules/sensors/dynamic_sensor/DynamicSensorsSubHal.cpp b/modules/sensors/dynamic_sensor/DynamicSensorsSubHal.cpp index d5a9b3c0..101b983c 100644 --- a/modules/sensors/dynamic_sensor/DynamicSensorsSubHal.cpp +++ b/modules/sensors/dynamic_sensor/DynamicSensorsSubHal.cpp @@ -118,7 +118,7 @@ Return<void> DynamicSensorsSubHal::getSensorsList_2_1( sensors[0].sensorHandle = sensor_info.handle; sensors[0].name = sensor_info.name; sensors[0].vendor = sensor_info.vendor; - sensors[0].version = 1; + sensors[0].version = sensor_info.version; sensors[0].type = static_cast<SensorType>(sensor_info.type); sensors[0].typeAsString = sensor_info.stringType; sensors[0].maxRange = sensor_info.maxRange; @@ -210,7 +210,7 @@ void DynamicSensorsSubHal::onSensorConnected( sensor_list[0].sensorHandle = handle; sensor_list[0].name = sensor_info->name; sensor_list[0].vendor = sensor_info->vendor; - sensor_list[0].version = 1; + sensor_list[0].version = sensor_info->version; sensor_list[0].type = static_cast<SensorType>(sensor_info->type); sensor_list[0].typeAsString = sensor_info->stringType; sensor_list[0].maxRange = sensor_info->maxRange; diff --git a/modules/sensors/dynamic_sensor/HidRawDevice.cpp b/modules/sensors/dynamic_sensor/HidRawDevice.cpp index 2588483a..6032ed95 100644 --- a/modules/sensors/dynamic_sensor/HidRawDevice.cpp +++ b/modules/sensors/dynamic_sensor/HidRawDevice.cpp @@ -204,7 +204,7 @@ bool HidRawDevice::getFeature(uint8_t id, std::vector<uint8_t> *out) { int res = ::ioctl(mDevFd, HIDIOCGFEATURE(size), mIoBuffer.data()); if (res < 0) { LOG_E << "HidRawDevice::getFeature: feature " << static_cast<int>(id) - << " ioctl returns " << res << " (" << ::strerror(res) << ")" << LOG_ENDL; + << " ioctl returned " << res << ", errno: " << ::strerror(errno) << LOG_ENDL; return false; } @@ -249,8 +249,8 @@ bool HidRawDevice::setFeature(uint8_t id, const std::vector<uint8_t> &in) { std::copy(in.begin(), in.end(), &mIoBuffer[1]); int res = ::ioctl(mDevFd, HIDIOCSFEATURE(size), mIoBuffer.data()); if (res < 0) { - LOG_E << "HidRawDevice::setFeature: feature " << id << " ioctl returns " << res - << " (" << ::strerror(res) << ")" << LOG_ENDL; + LOG_E << "HidRawDevice::setFeature: feature " << id << " ioctl returned " << res + << ", errno: " << ::strerror(errno) << LOG_ENDL; return false; } return true; @@ -287,8 +287,8 @@ bool HidRawDevice::sendReport(uint8_t id, std::vector<uint8_t> &data) { res = ::write(mDevFd, data.data(), size); } if (res < 0) { - LOG_E << "HidRawDevice::sendReport: output " << id << " write returns " << res - << " (" << ::strerror(res) << ")" << LOG_ENDL; + LOG_E << "HidRawDevice::sendReport: output " << id << " write returned " + << res << ", errno: " << ::strerror(errno) << LOG_ENDL; return false; } return true; @@ -302,8 +302,8 @@ bool HidRawDevice::receiveReport(uint8_t *id, std::vector<uint8_t> *data) { uint8_t buffer[256]; int res = ::read(mDevFd, buffer, 256); if (res < 0) { - LOG_E << "HidRawDevice::receiveReport: read returns " << res - << " (" << ::strerror(res) << ")" << LOG_ENDL; + LOG_E << "HidRawDevice::receiveReport: read returned " << res + << ", errno: " << ::strerror(errno) << LOG_ENDL; return false; } diff --git a/modules/sensors/dynamic_sensor/HidRawSensor.cpp b/modules/sensors/dynamic_sensor/HidRawSensor.cpp index c90f4f1a..939b58df 100644 --- a/modules/sensors/dynamic_sensor/HidRawSensor.cpp +++ b/modules/sensors/dynamic_sensor/HidRawSensor.cpp @@ -16,7 +16,9 @@ #include "HidRawSensor.h" #include "HidSensorDef.h" +#include <android-base/properties.h> #include <utils/Errors.h> +#include <com_android_libhardware_dynamic_sensors_flags.h> #include "HidLog.h" #include <HidUtils.h> @@ -30,15 +32,20 @@ namespace android { namespace SensorHalExt { +using ::android::base::GetProperty; + +namespace dynamic_sensors_flags = com::android::libhardware::dynamic::sensors::flags; + namespace { const std::string CUSTOM_TYPE_PREFIX("com.google.hardware.sensor.hid_dynamic."); + } HidRawSensor::HidRawSensor( SP(HidDevice) device, uint32_t usage, const std::vector<HidParser::ReportPacket> &packets) - : mReportingStateId(-1), mPowerStateId(-1), mReportIntervalId(-1), mInputReportId(-1), - mEnabled(false), mSamplingPeriod(1000LL*1000*1000), mBatchingPeriod(0), - mDevice(device), mValid(false) { + : mReportingStateId(-1), mPowerStateId(-1), mReportIntervalId(-1), mLeTransportId(-1), + mRequiresLeTransport(false), mInputReportId(-1), mEnabled(false), + mSamplingPeriod(1000LL*1000*1000), mBatchingPeriod(0), mDevice(device), mValid(false) { if (device == nullptr) { return; } @@ -631,10 +638,35 @@ void HidRawSensor::detectSensorFromDescription(const std::string &description) { bool HidRawSensor::detectAndroidHeadTrackerSensor( const std::string &description) { - if (description.find("#AndroidHeadTracker#1.") != 0) { + bool leAudioFlagEnabled = dynamic_sensors_flags::dynamic_sensors_le_audio(); + LOG_I << "detectAndroidHeadTrackerSensor: " << description << LOG_ENDL; + if (!description.starts_with("#AndroidHeadTracker#1.") + && (!leAudioFlagEnabled || !description.starts_with("#AndroidHeadTracker#2."))) { return false; } + // #AndroidHeadTracker#<major version>.<minor version>#<capability> + // We encode the major, minor, and capabilities in the following format: + // 0xMMmmcccc (Major, minor, capability bits) + if (leAudioFlagEnabled) { + uint32_t majorVersion = 0, minorVersion = 0, capability = 0; + mFeatureInfo.version = 0; + int ret = sscanf(description.c_str(), "#AndroidHeadTracker#%d.%d#%d", + &majorVersion, &minorVersion, &capability); + if (ret > 0) { + mRequiresLeTransport = (majorVersion == kLeAudioCapabilitiesMajorVersion); + mFeatureInfo.version = (majorVersion & 0xFF) << 24; + } + if (ret > 1) { + mFeatureInfo.version |= (minorVersion & 0xFF) << 16; + } + if (ret > 2) { + mFeatureInfo.version |= (capability & 0xFFFF); + } + } else { + mFeatureInfo.version = 1; + } + mFeatureInfo.type = SENSOR_TYPE_HEAD_TRACKER; mFeatureInfo.typeString = SENSOR_STRING_TYPE_HEAD_TRACKER; mFeatureInfo.reportModeFlag = SENSOR_FLAG_CONTINUOUS_MODE; @@ -817,6 +849,7 @@ bool HidRawSensor::findSensorControlUsage(const std::vector<HidParser::ReportPac using namespace Hid::Sensor::PowerStateUsage; using namespace Hid::Sensor::PropertyUsage; using namespace Hid::Sensor::ReportingStateUsage; + using namespace Hid::Sensor::LeTransportUsage; //REPORTING_STATE const HidParser::ReportItem *reportingState @@ -904,8 +937,43 @@ bool HidRawSensor::findSensorControlUsage(const std::vector<HidParser::ReportPac mFeatureInfo.maxDelay = std::min(static_cast<int64_t>(1000000000), mFeatureInfo.maxDelay); } - return true; - return (mPowerStateId >= 0 || mReportingStateId >= 0) && mReportIntervalId >= 0; + + bool leTransportExpected = mRequiresLeTransport; + if (leTransportExpected) { + //VENDOR_LE_TRANSPORT + const HidParser::ReportItem *leTransport + = find(packets, VENDOR_LE_TRANSPORT, HidParser::REPORT_TYPE_FEATURE); + if (leTransport == nullptr) { + LOG_W << "Cannot find valid LE transport feature" << LOG_ENDL; + } else { + mLeTransportId = leTransport->id; + mLeTransportBitOffset = leTransport->bitOffset; + mLeTransportBitSize = leTransport->bitSize; + + mLeTransportAclIndex = -1; + mLeTransportIsoIndex = -1; + for (unsigned i = 0; i < leTransport->usageVector.size(); ++i) { + if (leTransport->usageVector[i] == LE_TRANSPORT_ACL) { + mLeTransportAclIndex = i; + } + if (leTransport->usageVector[i] == LE_TRANSPORT_ISO) { + mLeTransportIsoIndex = i; + } + } + if (mLeTransportAclIndex < 0) { + LOG_W << "Cannot find LE transport to enable ACL" + << LOG_ENDL; + mLeTransportId = -1; + } + if (mLeTransportIsoIndex < 0) { + LOG_W << "Cannot find LE transport to enable ISO" << LOG_ENDL; + mLeTransportId = -1; + } + } + } + + return (mPowerStateId >= 0 || mReportingStateId >= 0) && mReportIntervalId >= 0 && + (!leTransportExpected || mLeTransportId >= 0); } const sensor_t* HidRawSensor::getSensor() const { @@ -928,6 +996,49 @@ int HidRawSensor::enable(bool enable) { } std::vector<uint8_t> buffer; + // TODO(b/298450041): Refactor the operations below in a separate function. + bool setLeAudioTransportOk = true; + if (mLeTransportId >= 0 && enable) { + setLeAudioTransportOk = false; + uint8_t id = static_cast<uint8_t>(mLeTransportId); + if (device->getFeature(id, &buffer) + && (8 * buffer.size()) >= + (mLeTransportBitOffset + mLeTransportBitSize)) { + // The following property, if defined, represents a comma-separated list of + // transport preferences for the following types: le-acl or iso-[sw|hw], + // which describes the priority list of transport selections used based on the + // capabilities reported by the HID device. + std::string prop = GetProperty("bluetooth.core.le.dsa_transport_preference", ""); + std::istringstream tokenStream(prop); + std::string line; + std::vector<std::string> priorityList; + while (std::getline(tokenStream, line, ',')) { + priorityList.push_back(line); + } + + uint16_t capability = mFeatureInfo.version & 0x0000FFFF; + uint8_t index; + if (capability == (kIsoBitMask | kAclBitMask)) { + if (!priorityList.empty() && priorityList[0].compare("le-acl") == 0) { + index = mLeTransportAclIndex; + } else { + index = mLeTransportIsoIndex; + } + } else { + index = (capability & kIsoBitMask) ? mLeTransportIsoIndex : mLeTransportAclIndex; + } + + HidUtil::copyBits(&index, &(buffer[0]), buffer.size(), 0, + mLeTransportBitOffset, mLeTransportBitSize); + setLeAudioTransportOk = device->setFeature(id, buffer); + if (!setLeAudioTransportOk) { + LOG_E << "enable: setFeature VENDOR LE TRANSPORT failed" << LOG_ENDL; + } + } else { + LOG_E << "enable: changing VENDOR LE TRANSPORT failed" << LOG_ENDL; + } + } + bool setPowerOk = true; if (mPowerStateId >= 0) { setPowerOk = false; @@ -939,6 +1050,9 @@ int HidRawSensor::enable(bool enable) { HidUtil::copyBits(&index, &(buffer[0]), buffer.size(), 0, mPowerStateBitOffset, mPowerStateBitSize); setPowerOk = device->setFeature(id, buffer); + if (!setPowerOk) { + LOG_E << "enable: setFeature POWER STATE failed" << LOG_ENDL; + } } else { LOG_E << "enable: changing POWER STATE failed" << LOG_ENDL; } @@ -956,12 +1070,15 @@ int HidRawSensor::enable(bool enable) { HidUtil::copyBits(&index, &(buffer[0]), buffer.size(),0, mReportingStateBitOffset, mReportingStateBitSize); setReportingOk = device->setFeature(id, buffer); + if (!setReportingOk) { + LOG_E << "enable: setFeature REPORTING STATE failed" << LOG_ENDL; + } } else { LOG_E << "enable: changing REPORTING STATE failed" << LOG_ENDL; } } - if (setPowerOk && setReportingOk) { + if (setPowerOk && setReportingOk && setLeAudioTransportOk) { mEnabled = enable; return NO_ERROR; } else { @@ -1100,6 +1217,7 @@ std::string HidRawSensor::dump() const { std::ostringstream ss; ss << "Feature Values " << LOG_ENDL << " name: " << mFeatureInfo.name << LOG_ENDL + << " version: 0x" << std::setfill('0') << std::setw(8) << std::hex << mFeatureInfo.version << LOG_ENDL << " vendor: " << mFeatureInfo.vendor << LOG_ENDL << " permission: " << mFeatureInfo.permission << LOG_ENDL << " typeString: " << mFeatureInfo.typeString << LOG_ENDL diff --git a/modules/sensors/dynamic_sensor/HidRawSensor.h b/modules/sensors/dynamic_sensor/HidRawSensor.h index e4564a0f..a9847c8e 100644 --- a/modules/sensors/dynamic_sensor/HidRawSensor.h +++ b/modules/sensors/dynamic_sensor/HidRawSensor.h @@ -200,6 +200,13 @@ private: double mReportIntervalScale; int64_t mReportIntervalOffset; + int mLeTransportId; + unsigned int mLeTransportBitOffset; + unsigned int mLeTransportBitSize; + bool mRequiresLeTransport; + int mLeTransportAclIndex; + int mLeTransportIsoIndex; + // Input report translate table std::vector<ReportTranslateRecord> mTranslateTable; unsigned mInputReportId; @@ -214,6 +221,20 @@ private: WP(HidDevice) mDevice; bool mValid; + + /** + * The first major version which LE audio capabilities are encoded. + * For this version, we expect the HID descriptor to be the following format: + * #AndroidHeadTracker#<major version>.<minor version>#<capability> + * where capability is an integer that defines where LE audio supported + * transports are indicated: + * - 1: ACL + * - 2: ISO + * - 3: ACL + ISO + */ + const uint8_t kLeAudioCapabilitiesMajorVersion = 2; + const uint8_t kAclBitMask = 0x1; + const uint8_t kIsoBitMask = 0x2; }; } // namespace SensorHalExt diff --git a/modules/sensors/dynamic_sensor/HidRawSensorDevice.cpp b/modules/sensors/dynamic_sensor/HidRawSensorDevice.cpp index 8aa4cf92..5bc4abc2 100644 --- a/modules/sensors/dynamic_sensor/HidRawSensorDevice.cpp +++ b/modules/sensors/dynamic_sensor/HidRawSensorDevice.cpp @@ -35,6 +35,15 @@ using namespace Hid::Sensor::PropertyUsage; const std::unordered_set<unsigned int> HidRawSensorDevice::sInterested{ ACCELEROMETER_3D, GYROMETER_3D, COMPASS_3D, CUSTOM}; +void HidRawSensorDevice::enableSchedFifoMode() { + constexpr int kHidRawSensorPriority = 10; // Matches with sensor service priority + struct sched_param param = {0}; + param.sched_priority = kHidRawSensorPriority; + if (sched_setscheduler(getTid(), SCHED_FIFO | SCHED_RESET_ON_FORK, ¶m) != 0) { + ALOGE("Couldn't set SCHED_FIFO for HidRawSensor thread: %s", strerror(errno)); + } +} + sp<HidRawSensorDevice> HidRawSensorDevice::create(const std::string &devName) { sp<HidRawSensorDevice> device(new HidRawSensorDevice(devName)); // offset +1 strong count added by constructor @@ -74,7 +83,8 @@ HidRawSensorDevice::HidRawSensorDevice(const std::string &devName) return; } - run("HidRawSensor"); + run("HidRawSensor", PRIORITY_URGENT_DISPLAY); + enableSchedFifoMode(); mValid = true; } diff --git a/modules/sensors/dynamic_sensor/HidRawSensorDevice.h b/modules/sensors/dynamic_sensor/HidRawSensorDevice.h index 06d435e7..7818bf16 100644 --- a/modules/sensors/dynamic_sensor/HidRawSensorDevice.h +++ b/modules/sensors/dynamic_sensor/HidRawSensorDevice.h @@ -41,6 +41,7 @@ private: // constructor will result in +1 strong count explicit HidRawSensorDevice(const std::string &devName); + void enableSchedFifoMode(); // implement function of Thread virtual bool threadLoop() override; std::unordered_map<unsigned int/*reportId*/, sp<HidRawSensor>> mSensors; diff --git a/modules/sensors/dynamic_sensor/HidSensorDef.h b/modules/sensors/dynamic_sensor/HidSensorDef.h index 8f47a850..d347ef67 100644 --- a/modules/sensors/dynamic_sensor/HidSensorDef.h +++ b/modules/sensors/dynamic_sensor/HidSensorDef.h @@ -42,6 +42,7 @@ enum { SENSOR_MODEL = 0x200306, SENSOR_SERIAL_NUMBER = 0x200307, SENSOR_STATUS = 0x200303, + VENDOR_LE_TRANSPORT = 0x20F410, }; } // nsmespace PropertyUsage @@ -99,6 +100,13 @@ enum { }; } // namespace PowerStateUsage +namespace LeTransportUsage { +enum { + LE_TRANSPORT_ACL = 0xF800, + LE_TRANSPORT_ISO = 0xF801, +}; +} // namespace LeTransportUsage + } // namespace Sensor } // namespace Hid #endif // HID_SENSOR_DEF_H_ diff --git a/modules/sensors/dynamic_sensor/dynamic_sensors.aconfig b/modules/sensors/dynamic_sensor/dynamic_sensors.aconfig new file mode 100644 index 00000000..42f2fb89 --- /dev/null +++ b/modules/sensors/dynamic_sensor/dynamic_sensors.aconfig @@ -0,0 +1,9 @@ +package: "com.android.libhardware.dynamic.sensors.flags" +container: "system" + +flag { + name: "dynamic_sensors_le_audio" + namespace: "sensors" + description: "This flag controls the enablement of LE audio support on dynamic sensors" + bug: "298450041" +}
\ No newline at end of file diff --git a/modules/usbaudio/audio_hal.c b/modules/usbaudio/audio_hal.c index 1bd53c27..57f523b9 100644 --- a/modules/usbaudio/audio_hal.c +++ b/modules/usbaudio/audio_hal.c @@ -809,6 +809,8 @@ static int start_output_stream(struct stream_out *out) ALOGE("%s failed to open device(card: %d device: %d)", __func__, device_info->profile.card, device_info->profile.device); goto exit; + } else { + out->standby = false; } } @@ -835,7 +837,6 @@ static ssize_t out_write(struct audio_stream_out *stream, const void* buffer, si if (ret != 0) { goto err; } - out->standby = false; } struct listnode* node; @@ -1262,7 +1263,7 @@ static int in_set_gain(struct audio_stream_in *stream, float gain) return 0; } -/* must be called with hw device and output stream mutexes locked */ +/* must be called with hw device and input stream mutexes locked */ static int start_input_stream(struct stream_in *in) { // Only care about the first device as only one input device is allowed. @@ -1273,7 +1274,11 @@ static int start_input_stream(struct stream_in *in) ALOGV("start_input_stream(card:%d device:%d)", device_info->profile.card, device_info->profile.device); - return proxy_open(&device_info->proxy); + int ret = proxy_open(&device_info->proxy); + if (ret == 0) { + in->standby = false; + } + return ret; } /* TODO mutex stuff here (see out_write) */ @@ -1292,7 +1297,6 @@ static ssize_t in_read(struct audio_stream_in *stream, void* buffer, size_t byte if (ret != 0) { goto err; } - in->standby = false; } // Only care about the first device as only one input device is allowed. @@ -1510,6 +1514,8 @@ static int adev_open_input_stream(struct audio_hw_device *hw_dev, ret = 0; } } + } else if (profile_is_sample_rate_valid(&device_info->profile, config->sample_rate)) { + in->config.rate = config->sample_rate; } } else if (profile_is_sample_rate_valid(&device_info->profile, config->sample_rate)) { in->config.rate = config->sample_rate; @@ -1855,10 +1861,10 @@ static int adev_create_audio_patch(struct audio_hw_device *dev, if (!wasStandby) { device_lock(adev); if (in != NULL) { - start_input_stream(in); + ret = start_input_stream(in); } if (out != NULL) { - start_output_stream(out); + ret = start_output_stream(out); } device_unlock(adev); } diff --git a/tests/hardware/Android.bp b/tests/hardware/Android.bp index b1376840..a52a4ab1 100644 --- a/tests/hardware/Android.bp +++ b/tests/hardware/Android.bp @@ -21,5 +21,7 @@ cc_library_static { "-Werror", ], + vendor: true, + include_dirs: ["system/media/camera/include"], } diff --git a/update-includes.sh b/update-includes.sh new file mode 100755 index 00000000..92aafc9c --- /dev/null +++ b/update-includes.sh @@ -0,0 +1,19 @@ +#!/bin/bash + +set +ex + +if [ ! "$ANDROID_BUILD_TOP" ]; then + echo "lunch?" + exit 1 +fi + +function update-includes() { + find -L "$ANDROID_BUILD_TOP/hardware/libhardware/include/hardware" -maxdepth 1 -xtype l -exec rm {} \; + + for f in $ANDROID_BUILD_TOP/hardware/libhardware/include_all/hardware/*; do + local bn="$(basename $f)" + ln -s "../../include_all/hardware/$bn" "$ANDROID_BUILD_TOP/hardware/libhardware/include/hardware/$bn" + done +} + +update-includes |