include: android: Add Android headers from Cros

Copy the Android Camera3 HAL headers from the ChromiumOS build system
and define a new inclusion directive in the meson build system for them.

The header files have been copied from:
https://chromium.googlesource.com/chromiumos/platform2
at revision 9e65ddd2c496e712f005ada9715decd2ff8e4a03
and provide:

1) Android CameraHAL3 HAL headers in include/android/hardware/
2) The Android system headers in include/android/system/
3) The Android camera metadata headers in include/android/metadata/

The original path in the Cros platform2/ repository is, respectively:
camera/android/header_files/include/hardware
camera/android/header_files/include/system
camera/android/libcamera_metadata/include/

Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

1 files changed, 580 insertions, 0 deletions

diff --git a/include/android/metadata/system/camera_metadata.h b/include/android/metadata/system/camera_metadata.h
new file mode 100644
index 00000000..46e7ac00
--- /dev/null
+++ b/include/android/metadata/system/camera_metadata.h
@@ -0,0 +1,580 @@
+/*
+ * 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 SYSTEM_MEDIA_INCLUDE_ANDROID_CAMERA_METADATA_H
+#define SYSTEM_MEDIA_INCLUDE_ANDROID_CAMERA_METADATA_H
+
+#include <string.h>
+#include <stdint.h>
+#include <cutils/compiler.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Tag hierarchy and enum definitions for camera_metadata_entry
+ * =============================================================================
+ */
+
+/**
+ * Main enum definitions are in a separate file to make it easy to
+ * maintain
+ */
+#include "camera_metadata_tags.h"
+
+/**
+ * Enum range for each top-level category
+ */
+ANDROID_API
+extern unsigned int camera_metadata_section_bounds[ANDROID_SECTION_COUNT][2];
+ANDROID_API
+extern const char *camera_metadata_section_names[ANDROID_SECTION_COUNT];
+
+/**
+ * Type definitions for camera_metadata_entry
+ * =============================================================================
+ */
+enum {
+    // Unsigned 8-bit integer (uint8_t)
+    TYPE_BYTE = 0,
+    // Signed 32-bit integer (int32_t)
+    TYPE_INT32 = 1,
+    // 32-bit float (float)
+    TYPE_FLOAT = 2,
+    // Signed 64-bit integer (int64_t)
+    TYPE_INT64 = 3,
+    // 64-bit float (double)
+    TYPE_DOUBLE = 4,
+    // A 64-bit fraction (camera_metadata_rational_t)
+    TYPE_RATIONAL = 5,
+    // Number of type fields
+    NUM_TYPES
+};
+
+typedef struct camera_metadata_rational {
+    int32_t numerator;
+    int32_t denominator;
+} camera_metadata_rational_t;
+
+/**
+ * A reference to a metadata entry in a buffer.
+ *
+ * The data union pointers point to the real data in the buffer, and can be
+ * modified in-place if the count does not need to change. The count is the
+ * number of entries in data of the entry's type, not a count of bytes.
+ */
+typedef struct camera_metadata_entry {
+    size_t   index;
+    uint32_t tag;
+    uint8_t  type;
+    size_t   count;
+    union {
+        uint8_t *u8;
+        int32_t *i32;
+        float   *f;
+        int64_t *i64;
+        double  *d;
+        camera_metadata_rational_t *r;
+    } data;
+} camera_metadata_entry_t;
+
+/**
+ * A read-only reference to a metadata entry in a buffer. Identical to
+ * camera_metadata_entry in layout
+ */
+typedef struct camera_metadata_ro_entry {
+    size_t   index;
+    uint32_t tag;
+    uint8_t  type;
+    size_t   count;
+    union {
+        const uint8_t *u8;
+        const int32_t *i32;
+        const float   *f;
+        const int64_t *i64;
+        const double  *d;
+        const camera_metadata_rational_t *r;
+    } data;
+} camera_metadata_ro_entry_t;
+
+/**
+ * Size in bytes of each entry type
+ */
+ANDROID_API
+extern const size_t camera_metadata_type_size[NUM_TYPES];
+
+/**
+ * Human-readable name of each entry type
+ */
+ANDROID_API
+extern const char* camera_metadata_type_names[NUM_TYPES];
+
+/**
+ * Main definitions for the metadata entry and array structures
+ * =============================================================================
+ */
+
+/**
+ * A packet of metadata. This is a list of metadata entries, each of which has
+ * an integer tag to identify its meaning, 'type' and 'count' field, and the
+ * data, which contains a 'count' number of entries of type 'type'. The packet
+ * has a fixed capacity for entries and for extra data.  A new entry uses up one
+ * entry slot, and possibly some amount of data capacity; the function
+ * calculate_camera_metadata_entry_data_size() provides the amount of data
+ * capacity that would be used up by an entry.
+ *
+ * Entries are not sorted by default, and are not forced to be unique - multiple
+ * entries with the same tag are allowed. The packet will not dynamically resize
+ * when full.
+ *
+ * The packet is contiguous in memory, with size in bytes given by
+ * get_camera_metadata_size(). Therefore, it can be copied safely with memcpy()
+ * to a buffer of sufficient size. The copy_camera_metadata() function is
+ * intended for eliminating unused capacity in the destination packet.
+ */
+struct camera_metadata;
+typedef struct camera_metadata camera_metadata_t;
+
+/**
+ * Functions for manipulating camera metadata
+ * =============================================================================
+ *
+ * NOTE: Unless otherwise specified, functions that return type "int"
+ * return 0 on success, and non-0 value on error.
+ */
+
+/**
+ * Allocate a new camera_metadata structure, with some initial space for entries
+ * and extra data. The entry_capacity is measured in entry counts, and
+ * data_capacity in bytes. The resulting structure is all contiguous in memory,
+ * and can be freed with free_camera_metadata().
+ */
+ANDROID_API
+camera_metadata_t *allocate_camera_metadata(size_t entry_capacity,
+        size_t data_capacity);
+
+/**
+ * Get the required alignment of a packet of camera metadata, which is the
+ * maximal alignment of the embedded camera_metadata, camera_metadata_buffer_entry,
+ * and camera_metadata_data.
+ */
+ANDROID_API
+size_t get_camera_metadata_alignment();
+
+/**
+ * Allocate a new camera_metadata structure of size src_size. Copy the data,
+ * ignoring alignment, and then attempt validation. If validation
+ * fails, free the memory and return NULL. Otherwise return the pointer.
+ *
+ * The resulting pointer can be freed with free_camera_metadata().
+ */
+ANDROID_API
+camera_metadata_t *allocate_copy_camera_metadata_checked(
+        const camera_metadata_t *src,
+        size_t src_size);
+
+/**
+ * Place a camera metadata structure into an existing buffer. Returns NULL if
+ * the buffer is too small for the requested number of reserved entries and
+ * bytes of data. The entry_capacity is measured in entry counts, and
+ * data_capacity in bytes. If the buffer is larger than the required space,
+ * unused space will be left at the end. If successful, returns a pointer to the
+ * metadata header placed at the start of the buffer. It is the caller's
+ * responsibility to free the original buffer; do not call
+ * free_camera_metadata() with the returned pointer.
+ */
+ANDROID_API
+camera_metadata_t *place_camera_metadata(void *dst, size_t dst_size,
+        size_t entry_capacity,
+        size_t data_capacity);
+
+/**
+ * Free a camera_metadata structure. Should only be used with structures
+ * allocated with allocate_camera_metadata().
+ */
+ANDROID_API
+void free_camera_metadata(camera_metadata_t *metadata);
+
+/**
+ * Calculate the buffer size needed for a metadata structure of entry_count
+ * metadata entries, needing a total of data_count bytes of extra data storage.
+ */
+ANDROID_API
+size_t calculate_camera_metadata_size(size_t entry_count,
+        size_t data_count);
+
+/**
+ * Get current size of entire metadata structure in bytes, including reserved
+ * but unused space.
+ */
+ANDROID_API
+size_t get_camera_metadata_size(const camera_metadata_t *metadata);
+
+/**
+ * Get size of entire metadata buffer in bytes, not including reserved but
+ * unused space. This is the amount of space needed by copy_camera_metadata for
+ * its dst buffer.
+ */
+ANDROID_API
+size_t get_camera_metadata_compact_size(const camera_metadata_t *metadata);
+
+/**
+ * Get the current number of entries in the metadata packet.
+ *
+ * metadata packet must be valid, which can be checked before the call with
+ * validate_camera_metadata_structure().
+ */
+ANDROID_API
+size_t get_camera_metadata_entry_count(const camera_metadata_t *metadata);
+
+/**
+ * Get the maximum number of entries that could fit in the metadata packet.
+ */
+ANDROID_API
+size_t get_camera_metadata_entry_capacity(const camera_metadata_t *metadata);
+
+/**
+ * Get the current count of bytes used for value storage in the metadata packet.
+ */
+ANDROID_API
+size_t get_camera_metadata_data_count(const camera_metadata_t *metadata);
+
+/**
+ * Get the maximum count of bytes that could be used for value storage in the
+ * metadata packet.
+ */
+ANDROID_API
+size_t get_camera_metadata_data_capacity(const camera_metadata_t *metadata);
+
+/**
+ * Copy a metadata structure to a memory buffer, compacting it along the
+ * way. That is, in the copied structure, entry_count == entry_capacity, and
+ * data_count == data_capacity.
+ *
+ * If dst_size > get_camera_metadata_compact_size(), the unused bytes are at the
+ * end of the buffer. If dst_size < get_camera_metadata_compact_size(), returns
+ * NULL. Otherwise returns a pointer to the metadata structure header placed at
+ * the start of dst.
+ *
+ * Since the buffer was not allocated by allocate_camera_metadata, the caller is
+ * responsible for freeing the underlying buffer when needed; do not call
+ * free_camera_metadata.
+ */
+ANDROID_API
+camera_metadata_t *copy_camera_metadata(void *dst, size_t dst_size,
+        const camera_metadata_t *src);
+
+
+// Non-zero return values for validate_camera_metadata_structure
+enum {
+    CAMERA_METADATA_VALIDATION_ERROR = 1,
+    CAMERA_METADATA_VALIDATION_SHIFTED = 2,
+};
+
+/**
+ * Validate that a metadata is structurally sane. That is, its internal
+ * state is such that we won't get buffer overflows or run into other
+ * 'impossible' issues when calling the other API functions.
+ *
+ * This is useful in particular after copying the binary metadata blob
+ * from an untrusted source, since passing this check means the data is at least
+ * consistent.
+ *
+ * The expected_size argument is optional.
+ *
+ * Returns 0: on success
+ *         CAMERA_METADATA_VALIDATION_ERROR: on error
+ *         CAMERA_METADATA_VALIDATION_SHIFTED: when the data is not properly aligned, but can be
+ *                 used as input of clone_camera_metadata and the returned metadata will be valid.
+ *
+ */
+ANDROID_API
+int validate_camera_metadata_structure(const camera_metadata_t *metadata,
+                                       const size_t *expected_size);
+
+/**
+ * Append camera metadata in src to an existing metadata structure in dst.  This
+ * does not resize the destination structure, so if it is too small, a non-zero
+ * value is returned. On success, 0 is returned. Appending onto a sorted
+ * structure results in a non-sorted combined structure.
+ */
+ANDROID_API
+int append_camera_metadata(camera_metadata_t *dst, const camera_metadata_t *src);
+
+/**
+ * Clone an existing metadata buffer, compacting along the way. This is
+ * equivalent to allocating a new buffer of the minimum needed size, then
+ * appending the buffer to be cloned into the new buffer. The resulting buffer
+ * can be freed with free_camera_metadata(). Returns NULL if cloning failed.
+ */
+ANDROID_API
+camera_metadata_t *clone_camera_metadata(const camera_metadata_t *src);
+
+/**
+ * Calculate the number of bytes of extra data a given metadata entry will take
+ * up. That is, if entry of 'type' with a payload of 'data_count' values is
+ * added, how much will the value returned by get_camera_metadata_data_count()
+ * be increased? This value may be zero, if no extra data storage is needed.
+ */
+ANDROID_API
+size_t calculate_camera_metadata_entry_data_size(uint8_t type,
+        size_t data_count);
+
+/**
+ * Add a metadata entry to a metadata structure. Returns 0 if the addition
+ * succeeded. Returns a non-zero value if there is insufficient reserved space
+ * left to add the entry, or if the tag is unknown.  data_count is the number of
+ * entries in the data array of the tag's type, not a count of
+ * bytes. Vendor-defined tags can not be added using this method, unless
+ * set_vendor_tag_query_ops() has been called first. Entries are always added to
+ * the end of the structure (highest index), so after addition, a
+ * previously-sorted array will be marked as unsorted.
+ *
+ * Returns 0 on success. A non-0 value is returned on error.
+ */
+ANDROID_API
+int add_camera_metadata_entry(camera_metadata_t *dst,
+        uint32_t tag,
+        const void *data,
+        size_t data_count);
+
+/**
+ * Sort the metadata buffer for fast searching. If already marked as sorted,
+ * does nothing. Adding or appending entries to the buffer will place the buffer
+ * back into an unsorted state.
+ *
+ * Returns 0 on success. A non-0 value is returned on error.
+ */
+ANDROID_API
+int sort_camera_metadata(camera_metadata_t *dst);
+
+/**
+ * Get metadata entry at position index in the metadata buffer.
+ * Index must be less than entry count, which is returned by
+ * get_camera_metadata_entry_count().
+ *
+ * src and index are inputs; the passed-in entry is updated with the details of
+ * the entry. The data pointer points to the real data in the buffer, and can be
+ * updated as long as the data count does not change.
+ *
+ * Returns 0 on success. A non-0 value is returned on error.
+ */
+ANDROID_API
+int get_camera_metadata_entry(camera_metadata_t *src,
+        size_t index,
+        camera_metadata_entry_t *entry);
+
+/**
+ * Get metadata entry at position index, but disallow editing the data.
+ */
+ANDROID_API
+int get_camera_metadata_ro_entry(const camera_metadata_t *src,
+        size_t index,
+        camera_metadata_ro_entry_t *entry);
+
+/**
+ * Find an entry with given tag value. If not found, returns -ENOENT. Otherwise,
+ * returns entry contents like get_camera_metadata_entry.
+ *
+ * If multiple entries with the same tag exist, does not have any guarantees on
+ * which is returned. To speed up searching for tags, sort the metadata
+ * structure first by calling sort_camera_metadata().
+ */
+ANDROID_API
+int find_camera_metadata_entry(camera_metadata_t *src,
+        uint32_t tag,
+        camera_metadata_entry_t *entry);
+
+/**
+ * Find an entry with given tag value, but disallow editing the data
+ */
+ANDROID_API
+int find_camera_metadata_ro_entry(const camera_metadata_t *src,
+        uint32_t tag,
+        camera_metadata_ro_entry_t *entry);
+
+/**
+ * Delete an entry at given index. This is an expensive operation, since it
+ * requires repacking entries and possibly entry data. This also invalidates any
+ * existing camera_metadata_entry.data pointers to this buffer. Sorting is
+ * maintained.
+ */
+ANDROID_API
+int delete_camera_metadata_entry(camera_metadata_t *dst,
+        size_t index);
+
+/**
+ * Updates a metadata entry with new data. If the data size is changing, may
+ * need to adjust the data array, making this an O(N) operation. If the data
+ * size is the same or still fits in the entry space, this is O(1). Maintains
+ * sorting, but invalidates camera_metadata_entry instances that point to the
+ * updated entry. If a non-NULL value is passed in to entry, the entry structure
+ * is updated to match the new buffer state.  Returns a non-zero value if there
+ * is no room for the new data in the buffer.
+ */
+ANDROID_API
+int update_camera_metadata_entry(camera_metadata_t *dst,
+        size_t index,
+        const void *data,
+        size_t data_count,
+        camera_metadata_entry_t *updated_entry);
+
+/**
+ * Retrieve human-readable name of section the tag is in. Returns NULL if
+ * no such tag is defined. Returns NULL for tags in the vendor section, unless
+ * set_vendor_tag_query_ops() has been used.
+ */
+ANDROID_API
+const char *get_camera_metadata_section_name(uint32_t tag);
+
+/**
+ * Retrieve human-readable name of tag (not including section). Returns NULL if
+ * no such tag is defined. Returns NULL for tags in the vendor section, unless
+ * set_vendor_tag_query_ops() has been used.
+ */
+ANDROID_API
+const char *get_camera_metadata_tag_name(uint32_t tag);
+
+/**
+ * Retrieve the type of a tag. Returns -1 if no such tag is defined. Returns -1
+ * for tags in the vendor section, unless set_vendor_tag_query_ops() has been
+ * used.
+ */
+ANDROID_API
+int get_camera_metadata_tag_type(uint32_t tag);
+
+/**
+ * Retrieve human-readable name of section the tag is in. Returns NULL if
+ * no such tag is defined.
+ */
+ANDROID_API
+const char *get_local_camera_metadata_section_name(uint32_t tag,
+        const camera_metadata_t *meta);
+
+/**
+ * Retrieve human-readable name of tag (not including section). Returns NULL if
+ * no such tag is defined.
+ */
+ANDROID_API
+const char *get_local_camera_metadata_tag_name(uint32_t tag,
+        const camera_metadata_t *meta);
+
+/**
+ * Retrieve the type of a tag. Returns -1 if no such tag is defined.
+ */
+ANDROID_API
+int get_local_camera_metadata_tag_type(uint32_t tag,
+        const camera_metadata_t *meta);
+
+/**
+ * Set up vendor-specific tag query methods. These are needed to properly add
+ * entries with vendor-specified tags and to use the
+ * get_camera_metadata_section_name, _tag_name, and _tag_type methods with
+ * vendor tags. Returns 0 on success.
+ *
+ * **DEPRECATED** - Please use vendor_tag_ops defined in camera_vendor_tags.h
+ *        instead.
+ */
+typedef struct vendor_tag_query_ops vendor_tag_query_ops_t;
+struct vendor_tag_query_ops {
+    /**
+     * Get vendor section name for a vendor-specified entry tag. Only called for
+     * tags >= 0x80000000. The section name must start with the name of the
+     * vendor in the Java package style. For example, CameraZoom inc must prefix
+     * their sections with "com.camerazoom." Must return NULL if the tag is
+     * outside the bounds of vendor-defined sections.
+     */
+    const char *(*get_camera_vendor_section_name)(
+        const vendor_tag_query_ops_t *v,
+        uint32_t tag);
+    /**
+     * Get tag name for a vendor-specified entry tag. Only called for tags >=
+     * 0x80000000. Must return NULL if the tag is outside the bounds of
+     * vendor-defined sections.
+     */
+    const char *(*get_camera_vendor_tag_name)(
+        const vendor_tag_query_ops_t *v,
+        uint32_t tag);
+    /**
+     * Get tag type for a vendor-specified entry tag. Only called for tags >=
+     * 0x80000000. Must return -1 if the tag is outside the bounds of
+     * vendor-defined sections.
+     */
+    int (*get_camera_vendor_tag_type)(
+        const vendor_tag_query_ops_t *v,
+        uint32_t tag);
+    /**
+     * Get the number of vendor tags supported on this platform. Used to
+     * calculate the size of buffer needed for holding the array of all tags
+     * returned by get_camera_vendor_tags().
+     */
+    int (*get_camera_vendor_tag_count)(
+        const vendor_tag_query_ops_t *v);
+    /**
+     * Fill an array with all the supported vendor tags on this platform.
+     * get_camera_vendor_tag_count() returns the number of tags supported, and
+     * tag_array should be allocated with enough space to hold all of the tags.
+     */
+    void (*get_camera_vendor_tags)(
+        const vendor_tag_query_ops_t *v,
+        uint32_t *tag_array);
+};
+
+/**
+ * **DEPRECATED** - This should only be used by the camera framework. Camera
+ *      metadata will transition to using vendor_tag_ops defined in
+ *      camera_vendor_tags.h instead.
+ */
+ANDROID_API
+int set_camera_metadata_vendor_tag_ops(const vendor_tag_query_ops_t *query_ops);
+
+/**
+ * Print fields in the metadata to the log.
+ * verbosity = 0: Only tag entry information
+ * verbosity = 1: Tag entry information plus at most 16 data values
+ * verbosity = 2: All information
+ */
+ANDROID_API
+void dump_camera_metadata(const camera_metadata_t *metadata,
+        int fd,
+        int verbosity);
+
+/**
+ * Print fields in the metadata to the log; adds indentation parameter, which
+ * specifies the number of spaces to insert before each line of the dump
+ */
+ANDROID_API
+void dump_indented_camera_metadata(const camera_metadata_t *metadata,
+        int fd,
+        int verbosity,
+        int indentation);
+
+/**
+ * Prints the specified tag value as a string. Only works for enum tags.
+ * Returns 0 on success, -1 on failure.
+ */
+ANDROID_API
+int camera_metadata_enum_snprint(uint32_t tag,
+                                 uint32_t value,
+                                 char *dst,
+                                 size_t size);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif