media/c2/1.0/types.hal

/*
 * Copyright (C) 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.
 */

package hardware.google.media.c2@1.0;

import android.hardware.media.bufferpool@1.0::BufferStatusMessage;

enum Status : int32_t {
    /** operation completed successfully */
    OK        = 0,

    // bad input

    /** argument has invalid value (user error) */
    BAD_VALUE = -22,
    /** argument uses invalid index (user error) */
    BAD_INDEX = -75,
    /** argument/index is valid but not possible */
    CANNOT_DO = -2147483646,

    // bad sequencing of events

    /** object already exists */
    DUPLICATE = -17,
    /** object not found */
    NOT_FOUND = -2,
    /** operation is not permitted in the current state */
    BAD_STATE = -38,
    /** operation would block but blocking is not permitted */
    BLOCKING  = -9930,

    // bad environment

    /** not enough memory to complete operation */
    NO_MEMORY = -12,
    /** missing permission to complete operation */
    REFUSED   = -1,

    /** operation did not complete within timeout */
    TIMED_OUT = -110,

    // missing functionality

    /** operation is not implemented/supported (optional only) */
    OMITTED   = -74,

    // unknown fatal

    /** some unexpected error prevented the operation */
    CORRUPTED = -2147483648,

    // uninitialized

    /** status has not been initialized */
    NO_INIT   = -19,
};

/**
 * Codec 2.0 parameter index
 */
typedef uint32_t ParamIndex;

/**
 * Codec 2.0 parameter structure
 *
 * The description of a Params is provided by supplying a ParamIndex to
 * IComponentStore::getStructDescriptors().
 */
typedef vec<uint8_t> Params;

/**
 * Struct uniquely specifying a field in an arbitrary parameter structure.
 */
struct FieldId {
    /** Offset of the field in bytes */
    uint32_t offset;
    /** Size of the field in bytes */
    uint32_t size;
};

/**
 * Struct representing a location of a field in a parameter with a given index.
 */
struct ParamField {
    /** Index of the parameter */
    ParamIndex index;
    /** Field identifier */
    FieldId fieldId;
};

/**
 * Struct describing basic properties of a parameter with a given index.
 */
struct ParamDescriptor {
    /** Parameter index */
    ParamIndex index;

    enum Attrib : uint32_t {
        /**
         * Parameter is required to be specified.
         */
        REQUIRED   = 1u << 0,
        /**
         * Parameter retains its value.
         */
        PERSISTENT = 1u << 1,
        /**
         * Parameter is strict.
         */
        STRICT     = 1u << 2,
        /**
         * Parameter is publicly read-only.
         */
        READ_ONLY  = 1u << 3,
        /**
         * Parameter must not be visible to clients.
         */
        HIDDEN     = 1u << 4,
        /**
         * Parameter must not be used by framework (other than testing).
         */
        INTERNAL   = 1u << 5,
        /**
         * Parameter is publicly constant (hence read-only).
         */
        CONST      = 1u << 6,
    };
    /** Parameter attributes */
    bitfield<Attrib> attrib;

    /** Parameter name */
    string name;

    /** index of other parameters that this parameter depends on */
    vec<ParamIndex> dependencies;
};

// Generic way to describe supported numeric values for Codec 2.0 interfaces.

/**
 * An untyped value that can fit on 64 bits - the type of which is communicated
 * via a separate channel (FieldType).
 */
typedef uint64_t PrimitiveValue;

/*
 * Generic supported values for a field.
 *
 * This can be either a range or a set of values. The range can be linear or
 * geometric with clear minimum and maximum values, and can have an optional
 * step size or geometric ratio. Values can optionally represent flags.
 */
struct FieldSupportedValues {
    struct Range {
        PrimitiveValue min;
        PrimitiveValue max;
        PrimitiveValue step;
        PrimitiveValue num;
        PrimitiveValue denom;
    };

    enum Type : int32_t {
        /** No supported values */
        EMPTY,
        /** Numeric range that can be continuous or discrete */
        RANGE,
        /** List of values */
        VALUES,
        /** List of flags that can be OR-ed */
        FLAGS,
        /** Other representations */
        OTHER = 0xffffffff,
    };
    /**
     * Type of the supported values. The framework may not recognize `OTHER`.
     */
    Type type;
    /**
     * Codec2.0 type code of the supported values.
     *   * If #type is `OTHER`, #typeOther can be used to give more information.
     *     In this case, the interpretation of this structure is
     *     implementation-defined.
     *   * For all other values of #type, #typeOther is not used.
     * The framework may not inspect this value.
     */
    int32_t typeOther;

    /*
     * If #type = EMPTY, #range and #value are unused.
     */

    /**
     * If #type = RANGE, #range will specify the range of possible values.
     *
     * The intended type of members of #range will be clear in the context where
     * FieldSupportedValues is used.
     */
    Range range;

    /**
     * If #type is `VALUES` or `FLAGS`, #value will list supported values.
     *
     * The intended type of components of #value will be clear in the context
     * where FieldSupportedValues is used.
     */
    vec<PrimitiveValue> values;
};

/**
 * Supported values for a specific field.
 *
 * This is a pair of the field specifier together with an optional supported
 * values object. This structure is used when reporting parameter configuration
 * failures and conflicts.
 */
struct ParamFieldValues {
    /** the field or parameter */
    ParamField paramOrField;

    /**
     * optional supported values for the field if paramOrField specifies an
     * actual field that is numeric (non struct, blob or string). Supported
     * values for arrays (including string and blobs) describe the supported
     * values for each element (character for string, and bytes for blobs). It
     * is optional for read-only strings and blobs.
     */
    vec<FieldSupportedValues> values;
};

/**
 * Field descriptor.
 */
struct FieldDescriptor {

    /** Field id */
    FieldId fieldId;

    /**
     * Possible types of a field.
     */
    enum Type : uint32_t {
        NO_INIT,
        INT32,
        UINT32,
        CNTR32,
        INT64,
        UINT64,
        CNTR64,
        FLOAT,
        /**
         * Fixed-size string (POD)
         */
        STRING = 0x100,
        /**
         * blobs have no sub-elements and can be thought of as byte arrays.
         * However, bytes cannot be individually addressed by clients.
         */
        BLOB,
        /**
         * Structs. Marked with this flag in addition to their coreIndex.
         */
        STRUCT_FLAG = 0x20000,
    };
    /**
     * Type of the field.
     */
    bitfield<Type> type;

    /** Extent of the field */
    uint32_t length;
    /*
     * Note: the last member of a param struct can be of arbitrary length (e.g.
     * if it is T[] array, which extends to the last byte of the parameter.)
     * This is marked with extent 0.
     */

    /** Name of the field */
    string name;
    /** Named value type */
    struct NamedValue {
        string name;
        PrimitiveValue value;
    };
    /** Named values for the field */
    vec<NamedValue> namedValues;
};

/**
 * Struct descriptor.
 */
struct StructDescriptor {
    /** Struct type */
    ParamIndex type;
    /** Field descriptors for each field */
    vec<FieldDescriptor> fields;
};

/**
 * Information describing the reason a parameter settings may fail, or
 * may be overriden.
 */
struct SettingResult {
    /** Failure code (of Codec 2.0 SettingResult failure type) */
    enum Failure : uint32_t {
        /** Parameter is read-only and cannot be set. */
        READ_ONLY,
        /** Parameter mismatches input data. */
        MISMATCH,
        /** Parameter does not accept value. */
        BAD_VALUE,
        /** Parameter is not supported. */
        BAD_TYPE,
        /** Parameter is not supported on the specific port. */
        BAD_PORT,
        /** Parameter is not supported on the specific stream. */
        BAD_INDEX,
        /** Parameter is in conflict with an/other setting(s). */
        CONFLICT,
        /**
         * Parameter is out of range due to other settings. (This failure mode
         * can only be used for strict parameters.)
         */
        UNSUPPORTED,
        /**
         * Requested parameter value is in conflict with an/other setting(s)
         * and has been corrected to the closest supported value. This failure
         * mode is given to provide suggestion to the client as to how to enable
         * the requested parameter value. */
        INFO_CONFLICT,
        /**
         * This failure mode is reported when all the above failure modes do not
         * apply.
         */
        OTHER = 0xffffffff,
    };
    /**
     * The failure type. The framework might not recognize `OTHER`.
     */
    Failure failure;
    /**
     * The failure code.
     *   * If #failure is `OTHER`, #failureOther can be used to give more
     *     information.
     *   * For all other values of #failure, #failureOther is not used.
     * The framework may not inspect this value.
     */
    uint32_t failureOther;

    /**
     * Failing (or corrected) field. Currently supported values for the field.
     * This is set if different from the globally supported values (e.g. due to
     * restrictions by another param or input data)
     */
    ParamFieldValues field;

    /**
     * Conflicting parameters or fields with
     * (optional) suggested values for any conflicting fields to avoid the conflict.
     */
    vec<ParamFieldValues> conflicts;
};

/**
 * Data structure for ordering Work objects. Each member is used for comparing
 * urgency in the same fashion: a smaller value indicates that the associated
 * Work object is more urgent.
 */
struct WorkOrdinal {
    /**
     * Timestamp in microseconds - can wrap around.
     */
    uint64_t timestampUs;
    /**
     * Frame index - can wrap around.
     */
    uint64_t frameIndex;
    /**
     * Component specific frame ordinal - can wrap around.
     */
    uint64_t customOrdinal;
};

/**
 * A structure that holds information of a Block. There are two types of Blocks:
 * NATIVE and POOLED. Each type has its own way of identifying blocks.
 */
struct BaseBlock {
    enum Type : int32_t {
        NATIVE,
        POOLED,
    };
    /**
     * There are two types of blocks: NATIVE and POOLED.
     */
    Type type;

    /**
     * A "NATIVE" block is represented by a native handle.
     */
    handle nativeBlock;

    /*
     * A "POOLED" block is represented by `BufferStatusMessage`.
     */
    BufferStatusMessage pooledBlock;
};

/**
 * A Block in transfer consists of an index into an array of BaseBlock plus some
 * extra information. One BaseBlock may occur in multiple blocks in one
 * `WorkBundle`.
 */
struct Block {
    /**
     * Identity of the BaseBlock within a WorkBundle. This is an index into the
     * `baseBlocks` array of a `WorkBundle` object.
     */
    uint32_t index;
    /**
     * Metadata associated with the block.
     */
    Params meta;
    /**
     * Fence for synchronizing block access.
     */
    handle fence;
};

/**
 * Type of buffers processed by a component.
 */
struct Buffer {
    /**
     * Metadata associated with the buffer.
     */
    Params info;
    /**
     * Blocks contained in the buffer.
     */
    vec<Block> blocks;
};

/**
 * An extension of Buffer that also contains an index.
 */
struct InfoBuffer {
    ParamIndex index;
    Buffer buffer;
};

/**
 * This structure represents a frame with its metadata. A frame consists of an
 * ordered set of buffers, configuration changes, and info buffers along with
 * some non-configuration metadata.
 */
struct FrameData {
    enum Flags : uint32_t {
        /**
         * For input frames: no output frame will be generated when processing
         * this frame, but metadata must still be processed.
         * For output frames: this frame must be discarded but metadata is still
         * valid.
         */
        DROP_FRAME    = (1 << 0),
        /**
         * This frame is the last frame of the current stream. Further frames
         * are part of a new stream.
         */
        END_OF_STREAM = (1 << 1),
        /**
         * This frame must be discarded with its metadata.
         * This flag is only set by components - e.g. as a response to the flush
         * command.
         */
        DISCARD_FRAME = (1 << 2),
        /**
         * This frame contains only codec-specific configuration data, and no
         * actual access unit.
         *
         * \deprecated Pass codec configuration with the codec-specific
         * configuration info together with the access unit.
         */
        CODEC_CONFIG  = (1u << 31),
    };

    /**
     * Frame flags.
     */
    bitfield<Flags> flags;

    /**
     * Ordinal of the frame.
     */
    WorkOrdinal ordinal;

    /**
     * Frame buffers.
     */
    vec<Buffer> buffers;

    /**
     * Params determining a configuration update.
     */
    Params configUpdate;

    /**
     * Info buffers.
     */
    vec<InfoBuffer> infoBuffers;
};

/**
 * Struct for
 */
struct Worklet {
    /**
     * List of Params describing tunings.
     */
    vec<Params> tunings;

    /**
     * List of failures.
     */
    vec<SettingResult> failures;

    /**
     * Output frame data.
     */
    FrameData output;

    /* Note: Component id is not necessary as tunneling is not supported. */
};

/**
 * This structure holds information about a single work item. It must be passed
 * by the client to the component.
 */
struct Work {
    /**
     * FrameData for the input. Indices of Blocks inside #input refer to
     * BaseBlocks in the member `blocks` of the containing `WorkBundle`.
     */
    FrameData input;
    /**
     * Worklet. Indices of Blocks inside `worklet.output` refer to
     * BaseBlocks in the member `blocks` of the containing `WorkBundle`.
     */
    Worklet worklet;
    /**
     * Whether the worklet was processed or not.
     */
    bool workletProcessed;
    Status result;
};

/**
 * This structure holds a list of Work objects and a list of BaseBlocks.
 */
struct WorkBundle {
    /**
     * A list of Work items.
     */
    vec<Work> works;
    /**
     * A list of blocks indexed by elements of #works.
     */
    vec<BaseBlock> baseBlocks;
};

/**
 * This structure describes a query for supported values of a field. This is
 * used as input to IConfigurable::queryFieldSupportedValues().
 */
struct FieldSupportedValuesQuery {
    enum Type : uint32_t {
        /** Query all possible values regardless of other settings */
        POSSIBLE,
        /** Query currently possible values given dependent settings */
        CURRENT,
    };

    ParamField field;
    Type type;
};

/**
 * This structure is used to hold the result from
 * IConfigurable::queryFieldSupportedValues().
 */
struct FieldSupportedValuesQueryResult {
    Status status;
    FieldSupportedValues values;
};