path: root/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 android.hardware.media.c2@1.0;

import android.hardware.media.bufferpool@2.0::BufferStatusMessage;
import android.hidl.safe_union@1.0::Monostate;

/**
 * Common return values for Codec2 operations.
 */
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,
};

/**
 * C2Param structure index.
 *
 * This is a number that is unique for each C2Param structure type.
 *
 * @sa Codec 2.0 standard.
 */
typedef uint32_t ParamIndex;

/**
 * Flattened representation of C2Param objects.
 *
 * The `Params` type is an array of bytes made up by concatenating a list of
 * C2Param objects. The start index (offset into @ref Params) of each C2Param
 * object in the list is divisible by 8. Up to 7 padding bytes may be added
 * after each C2Param object to achieve this 64-bit alignment.
 *
 * Each C2Param object has the following layout:
 * - 4 bytes: C2Param structure index (of type @ref ParamIndex) identifying the
 *   type of the C2Param object.
 * - 4 bytes: size of the C2Param object (unsigned 4-byte integer).
 * - (size - 8) bytes: data of the C2Param object.
 *
 * In order to interpret each C2Param object correctly, its structure must be
 * described by IComponentStore::getStructDescriptors().
 *
 * @note Please refer to the Codec 2.0 standard for the list of standard
 * parameter structures.
 *
 * @sa Codec 2.0 standard.
 */
typedef vec<uint8_t> Params;

/**
 * Identifying information of a field relative to a known C2Param structure.
 *
 * Within a given C2Param structure, each field is uniquely identified by @ref
 * FieldId.
 */
struct FieldId {
    /** Offset of the field in bytes. */
    uint32_t offset;
    /** Size of the field in bytes. */
    uint32_t size;
};

/**
 * Reference to a field in a C2Param structure.
 */
struct ParamField {
    /** Index of the C2Param structure. */
    ParamIndex index;
    /** Identifier of the field inside the C2Param structure. */
    FieldId fieldId;
};

/**
 * Usage description of a C2Param structure.
 *
 * @ref ParamDescriptor is returned by IConfigurable::querySupportedParams().
 */
struct ParamDescriptor {
    /**
     * Index of the C2Param structure being described.
     */
    ParamIndex index;

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

    /**
     * Name of the structure. This must be unique for each structure.
     */
    string name;

    /**
     * Indices of other C2Param structures that this C2Param structure depends
     * on.
     */
    vec<ParamIndex> dependencies;
};

// Generic way to describe supported numeric values for Codec2 interfaces.

/**
 * An untyped value that can fit in 64 bits, the type of which is communicated
 * via a separate channel (@ref FieldSupportedValues.type).
 */
typedef uint64_t PrimitiveValue;

/**
 * Description of a set of values.
 *
 * If the `step` member is 0, and `num` and `denom` are both 1, the `Range`
 * structure represents a closed interval bounded by `min` and `max`.
 *
 * Otherwise, the #ValueRange structure represents a finite sequence of numbers
 * produced from the following recurrence relation:
 *
 * @code
 * v[0] = min
 * v[i] = v[i - 1] * num / denom + step ; i >= 1
 * @endcode
 *
 * Both the ratio `num / denom` and the value `step` must be positive. The
 * last number in the sequence described by this #Range structure is the
 * largest number in the sequence that is smaller than or equal to `max`.
 *
 * @note
 * The division in the formula may truncate the result if the data type of
 * these values is an integral type.
 */
struct ValueRange {
    /**
     * Lower end of the range (inclusive).
     */
    PrimitiveValue min;
    /**
     * Upper end of the range (inclusive).
     */
    PrimitiveValue max;
    /**
     * The non-homogeneous term in the recurrence relation.
     */
    PrimitiveValue step;
    /**
     * The numerator of the scale coefficient in the recurrence relation.
     */
    PrimitiveValue num;
    /**
     * The denominator of the scale coefficient in the recurrence relation.
     */
    PrimitiveValue denom;
};

/*
 * Description of supported values for a field.
 *
 * This can be a continuous range or a discrete set of values.
 *
 * The intended type of values must be made clear in the context where
 * `FieldSupportedValues` is used.
 */
safe_union FieldSupportedValues {
    /** No supported values */
    Monostate empty;
    /** Numeric range, described in a #ValueRange structure */
    ValueRange range;
    /** List of values */
    vec<PrimitiveValue> values;
    /** List of flags that can be OR-ed */
    vec<PrimitiveValue> flags;
};

/**
 * Supported values for a 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 {
    /**
     * Reference to a field or a C2Param structure.
     */
    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;
};

/**
 * Description of a field inside a C2Param structure.
 */
struct FieldDescriptor {

    /** Location of the field in the C2Param structure */
    FieldId fieldId;

    /**
     * Possible types of the field.
     */
    enum Type : uint32_t {
        NO_INIT = 0,
        INT32,
        UINT32,
        CNTR32,
        INT64,
        UINT64,
        CNTR64,
        FLOAT,
        /**
         * Fixed-size string (POD).
         */
        STRING = 0x100,
        /**
         * A blob has no sub-elements and can be thought of as an array of
         * bytes. However, bytes cannot be individually addressed by clients.
         */
        BLOB,
        /**
         * The field is a structure that may contain other fields.
         */
        STRUCT = 0x20000,
    };
    /**
     * Type of the field.
     */
    bitfield<Type> type;

    /**
     * If #type is #Type.STRUCT, #structIndex is the C2Param structure index;
     * otherwise, #structIndex is not used.
     */
    ParamIndex structIndex;

    /**
     * Extent of the field.
     * - For a non-array field, #extent is 1.
     * - For a fixed-length array field, #extent is the length. An array field
     *   of length 1 is indistinguishable from a non-array field.
     * - For a variable-length array field, #extent is 0. This can only occur as
     *   the last member of a C2Param structure.
     */
    uint32_t extent;

    /**
     * Name of the field. This must be unique for each field in the same
     * structure.
     */
    string name;

    /**
     * Named value type. This is used for defining an enum value for a numeric
     * type.
     */
    struct NamedValue {
        /**
         * Name of the enum value. This must be unique for each enum value in
         * the same field.
         */
        string name;
        /**
         * Underlying value of the enum value. Multiple enum names may have the
         * same underlying value.
         */
        PrimitiveValue value;
    };
    /**
     * List of enum values. This is not used when #type is not one of the
     * numeric types.
     */
    vec<NamedValue> namedValues;
};

/**
 * Description of a C2Param structure. It consists of an index and a list of
 * `FieldDescriptor`s.
 */
struct StructDescriptor {
    /**
     * Index of the structure.
     */
    ParamIndex type;
    /**
     * List of fields in the structure.
     *
     * Fields are ordered by their offsets. A field that is a structure is
     * ordered before its members.
     */
    vec<FieldDescriptor> fields;
};

/**
 * Information describing the reason the parameter settings may fail, or may be
 * overridden.
 */
struct SettingResult {
    /** Failure code */
    enum Failure : uint32_t {
        /** 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 read-only and cannot be set. */
        READ_ONLY,
        /** Parameter mismatches input data. */
        MISMATCH,
        /** Strict parameter does not accept value for the field at all. */
        BAD_VALUE,
        /**
         * Strict parameter field value is in conflict with an/other
         * setting(s).
         */
        CONFLICT,
        /**
         * Parameter field is out of range due to other settings. (This failure
         * mode can only be used for strict calculated parameters.)
         */
        UNSUPPORTED,
        /**
         * Field does not access the requested parameter value at all. It has
         * been corrected to the closest supported value. This failure mode is
         * provided to give guidance as to what are the currently supported
         * values for this field (which may be a subset of the at-all-potential
         * values).
         */
        INFO_BAD_VALUE,
        /**
         * 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 guidance as to what are the currently
         * supported values as well as to optionally provide suggestion to the
         * client as to how to enable the requested parameter value.
         */
        INFO_CONFLICT,
    };
    Failure failure;

    /**
     * Failing (or corrected) field or parameter and optionally, currently
     * supported values for the field. Values must only be set for field
     * failures other than `BAD_VALUE`, and only if they are different from the
     * globally supported values (e.g. due to restrictions by another parameter
     * or input data).
     */
    ParamFieldValues field;

    /**
     * Conflicting parameters or fields with (optional) suggested values for any
     * conflicting fields to avoid the conflict. Values must only be set for
     * `CONFLICT`, `UNSUPPORTED` or `INFO_CONFLICT` failure code.
     */
    vec<ParamFieldValues> conflicts;
};

/**
 * Ordering information of @ref FrameData objects. Each member is used for
 * comparing urgency: a smaller difference from a reference value indicates that
 * the associated Work object is more urgent. The reference value for each
 * member is initialized the first time it is communicated between the client
 * and the codec, and it may be updated to later values that are communicated.
 *
 * Each member of `WorkOrdinal` is stored as an unsigned integer, but the actual
 * order it represents is derived by subtracting the reference value, then
 * interpreting the result as a signed number with the same storage size (using
 * two's complement).
 *
 * @note `WorkOrdinal` is the HIDL counterpart of `C2WorkOrdinalStruct` in the
 * Codec 2.0 standard.
 */
struct WorkOrdinal {
    /**
     * Timestamp in microseconds.
     */
    uint64_t timestampUs;
    /**
     * Frame index.
     */
    uint64_t frameIndex;
    /**
     * Component specific frame ordinal.
     */
    uint64_t customOrdinal;
};

/**
 * Storage type for `BaseBlock`.
 *
 * A `BaseBlock` is a representation of a codec memory block. Coded data,
 * decoded data, codec-specific data, and other codec-related data are all sent
 * in the form of BaseBlocks.
 */
safe_union BaseBlock {
    /**
     * #nativeBlock is the opaque representation of a buffer.
     */
    handle nativeBlock;
    /**
     * #pooledBlock is a reference to a buffer handled by a BufferPool.
     */
    BufferStatusMessage pooledBlock;
};

/**
 * Reference to a @ref BaseBlock within a @ref WorkBundle.
 *
 * `Block` contains additional attributes that `BaseBlock` does not. These
 * attributes may differ among `Block` objects that refer to the same
 * `BaseBlock` in the same `WorkBundle`.
 */
struct Block {
    /**
     * Identity of a `BaseBlock` within a `WorkBundle`. This is an index into
     * #WorkBundle.baseBlocks.
     */
    uint32_t index;
    /**
     * Metadata associated with this `Block`.
     */
    Params meta;
    /**
     * Fence for synchronizing `Block` access.
     */
    handle fence;
};

/**
 * A codec buffer, which is a collection of @ref Block objects and metadata.
 *
 * This is a part of @ref FrameData.
 */
struct Buffer {
    /**
     * Metadata associated with the buffer.
     */
    Params info;
    /**
     * Blocks contained in the buffer.
     */
    vec<Block> blocks;
};

/**
 * An extension of @ref Buffer that also contains a C2Param structure index.
 *
 * This is a part of @ref FrameData.
 */
struct InfoBuffer {
    /**
     * A C2Param structure index.
     */
    ParamIndex index;
    /**
     * Associated @ref Buffer object.
     */
    Buffer buffer;
};

/**
 * Data for an input frame or an output frame.
 *
 * This structure represents a @e frame with its metadata. A @e frame consists
 * of an ordered set of buffers, configuration changes, and info buffers along
 * with some non-configuration metadata.
 *
 * @note `FrameData` is the HIDL counterpart of `C2FrameData` in the Codec 2.0
 * standard.
 */
struct FrameData {
    enum Flags : uint32_t {
        /**
         * For input frames: no output frame shall 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 is not the last frame produced for the input.
         *
         * This flag is normally set by the component - e.g. when an input frame
         * results in multiple output frames, this flag is set on all but the
         * last output frame.
         *
         * Also, when components are chained, this flag should be propagated
         * down the work chain. That is, if set on an earlier frame of a
         * work-chain, it should be propagated to all later frames in that
         * chain. Additionally, components down the chain could set this flag
         * even if not set earlier, e.g. if multiple output frames are generated
         * at that component for the input frame.
         */
        FLAG_INCOMPLETE = (1 << 3),
        /**
         * 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, as described in #Flags.
     */
    bitfield<Flags> flags;

    /**
     * @ref WorkOrdinal of the frame.
     */
    WorkOrdinal ordinal;

    /**
     * List of frame buffers.
     */
    vec<Buffer> buffers;

    /**
     * List of configuration updates.
     */
    Params configUpdate;

    /**
     * List of info buffers.
     */
    vec<InfoBuffer> infoBuffers;
};

/**
 * In/out structure containing some instructions for and results from output
 * processing.
 *
 * This is a part of @ref Work. One `Worklet` corresponds to one output
 * @ref FrameData. The client must construct an original `Worklet` object inside
 * a @ref Work object for each expected output before calling
 * IComponent::queue().
 */
struct Worklet {
    /**
     * Component id. (Input)
     *
     * This is used only when tunneling is enabled.
     *
     * When used, this must match the return value from IConfigurable::getId().
     */
    uint32_t componentId;

    /**
     * List of C2Param objects describing tunings to be applied before
     * processing this `Worklet`. (Input)
     */
    Params tunings;

    /**
     * List of failures. (Output)
     */
    vec<SettingResult> failures;

    /**
     * Output frame data. (Output)
     */
    FrameData output;
};

/**
 * A collection of input data to and output data from the component.
 *
 * A `Work` object holds information about a single work item. It is created by
 * the client and passed to the component via IComponent::queue(). The component
 * has two ways of returning a `Work` object to the client:
 *   1. If the queued `Work` object has been successfully processed,
 *      IComponentListener::onWorkDone() shall be called to notify the listener,
 *      and the output shall be included in the returned `Work` object.
 *   2. If the client calls IComponent::flush(), a `Work` object that has not
 *      been processed shall be returned.
 *
 * `Work` is a part of @ref WorkBundle.
 */
struct Work {
    /**
     * Additional work chain info not part of this work.
     */
    Params chainInfo;

    /**
     * @ref FrameData for the input.
     */
    FrameData input;

    /**
     * The chain of `Worklet`s.
     *
     * The length of #worklets is 1 when tunneling is not enabled.
     *
     * If #worklets has more than a single element, the tunnels between
     * successive components of the work chain must have been successfully
     * pre-registered at the time that the `Work` is submitted. Allocating the
     * output buffers in the `Worklet`s is the responsibility of each component
     * in the chain.
     *
     * Upon `Work` submission, #worklets must be an appropriately sized vector
     * containing `Worklet`s with @ref Worklet.hasOutput set to `false`. After a
     * successful processing, all but the final `Worklet` in the returned
     * #worklets must have @ref Worklet.hasOutput set to `false`.
     */
    vec<Worklet> worklets;

    /**
     * The number of `Worklet`s successfully processed in this chain.
     *
     * This must be initialized to 0 by the client when the `Work` is submitted,
     * and it must contain the number of `Worklet`s that were successfully
     * processed when the `Work` is returned to the client.
     *
     * #workletsProcessed cannot exceed the length of #worklets. If
     * #workletsProcessed is smaller than the length of #worklets, #result
     * cannot be `OK`.
     */
    uint32_t workletsProcessed;

    /**
     * The final outcome of the `Work` (corresponding to #workletsProcessed).
     *
     * The value of @ref Status.OK implies that all `Worklet`s have been
     * successfully processed.
     */
    Status result;
};

/**
 * List of `Work` objects.
 *
 * `WorkBundle` is used in IComponent::queue(), IComponent::flush() and
 * IComponentListener::onWorkDone(). A `WorkBundle` object consists of a list of
 * `Work` objects and a list of `BaseBlock` objects. Bundling multiple `Work`
 * objects together provides two benefits:
 *   1. Batching of `Work` objects can reduce the number of IPC calls.
 *   2. If multiple `Work` objects contain `Block`s that refer to the same
 *      `BaseBlock`, the number of `BaseBlock`s that is sent between processes
 *      is also reduced.
 *
 * @note `WorkBundle` is the HIDL counterpart of the vector of `C2Work` in the
 * Codec 2.0 standard. The presence of #baseBlocks helps with minimizing the
 * data transferred over an IPC.
 */
struct WorkBundle {
    /**
     * A list of Work items.
     */
    vec<Work> works;
    /**
     * A list of blocks indexed by elements of #works.
     */
    vec<BaseBlock> baseBlocks;
};

/**
 * Query information for supported values of a field. This is used as input to
 * IConfigurable::querySupportedValues().
 */
struct FieldSupportedValuesQuery {
    /**
     * Identity of the field to query.
     */
    ParamField field;

    enum Type : uint32_t {
        /** Query all possible values regardless of other settings. */
        POSSIBLE,
        /** Query currently possible values given dependent settings. */
        CURRENT,
    };
    /**
     * Type of the query. See #Type for more information.
     */
    Type type;
};

/**
 * This structure is used to hold the result from
 * IConfigurable::querySupportedValues().
 */
struct FieldSupportedValuesQueryResult {
    /**
     * Result of the query. Possible values are
     * - `OK`: The query was successful.
     * - `BAD_STATE`: The query was requested when the `IConfigurable` instance
     *   was in a bad state.
     * - `BAD_INDEX`: The requested field was not recognized.
     * - `TIMED_OUT`: The query could not be completed in a timely manner.
     * - `BLOCKING`: The query must block, but the parameter `mayBlock` in the
     *   call to `querySupportedValues()` was `false`.
     * - `CORRUPTED`: Some unknown error occurred.
     */
    Status status;

    /**
     * Supported values. This is meaningful only when #status is `OK`.
     */
    FieldSupportedValues values;
};