Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 8cedb0a0 authored by TreeHugger Robot's avatar TreeHugger Robot Committed by Android (Google) Code Review
Browse files

Merge "Copy from the old version of Codec2 HAL"

parents f837fa24 9d1cf2ab
Loading
Loading
Loading
Loading
+150 −186
Original line number Diff line number Diff line
@@ -22,19 +22,13 @@ import android.hardware.media.omx@1.0::IGraphicBufferSource;
import IConfigurable;
import IComponentInterface;
import IComponentListener;
import IInputSurface;
import IInputSurfaceConnection;

/**
 * Interface for a Codec2 component corresponding to API level 1.0 or below.
 * Components have two states: stopped and running. The running state has three
 * sub-states: executing, tripped and error.
 *
 * All methods in `IComponent` must not block. If a method call cannot be
 * completed in a timely manner, it must return `TIMED_OUT` in the return
 * status.
 * Interface for a Codec 2.0 component corresponding to API level 1.0 or
 * below. Components have two states: stopped and running. The running
 * state has three sub-states: executing, tripped and error.
 */
interface IComponent {
interface IComponent extends IComponentInterface {

    // METHODS AVAILABLE WHEN RUNNING
    // =========================================================================
@@ -44,42 +38,44 @@ interface IComponent {
     *
     * This method must be supported in running (including tripped) states.
     *
     * It is acceptable for this method to return `OK` and return an error value
     * using the IComponentListener::onWorkDone() callback.
     * This method must return within 1ms
     *
     * It is acceptable for this method to return OK and return an error value
     * using the onWorkDone() callback.
     *
     * @param workBundle `WorkBundle` object containing a list of `Work` objects
     *     to queue to the component.
     * @param workBundle WorkBundle object containing Works to queue to the
     * component.
     * @return status Status of the call, which may be
     *   - `OK`        - Works in @p workBundle were successfully queued.
     *   - `BAD_INDEX` - Some component id in some `Worklet` is not valid.
     *   - `CANNOT_DO` - The components are not tunneled but some `Work` object
     *                   contains tunneling information.
     *   - `NO_MEMORY` - Not enough memory to queue @p workBundle.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     *   - OK        - Works in \p workBundle were successfully queued.
     *   - BAD_INDEX - Some component(s) in some Work do(es) not exist.
     *   - CANNOT_DO - The components are not tunneled.
     *   - NO_MEMORY - Not enough memory to queue \p workBundle.
     *   - CORRUPTED - Some unknown error prevented queuing the Works.
     *                 (unexpected).
     */
    queue(WorkBundle workBundle) generates (Status status);

    /**
     * Discards and abandons any pending `Work` items for the component.
     * Discards and abandons any pending work for the component.
     *
     * This method must be supported in running (including tripped) states.
     *
     * `Work` that could be immediately abandoned/discarded must be returned in
     * @p flushedWorkBundle. The order in which queued `Work` items are
     * discarded can be arbitrary.
     * This method must return within 5ms.
     *
     * Work that could be immediately abandoned/discarded must be returned in
     * \p flushedWorks; this can be done in an arbitrary order.
     *
     * `Work` that could not be abandoned or discarded immediately must be
     * marked to be discarded at the earliest opportunity, and must be returned
     * via IComponentListener::onWorkDone(). This must be completed within
     * 500ms.
     * Work that could not be abandoned or discarded immediately must be marked
     * to be discarded at the earliest opportunity, and must be returned via
     * the onWorkDone() callback. This must be completed within 500ms.
     *
     * @return status Status of the call, which may be
     *   - `OK`        - The component has been successfully flushed.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     * @return flushedWorkBundle `WorkBundle` object containing flushed `Work`
     *     items.
     *   - OK        - The component has been successfully flushed.
     *   - TIMED_OUT - The flush could not be completed within the time limit.
     *                 (unexpected)
     *   - CORRUPTED - Some unknown error prevented flushing from
     *                 completion. (unexpected)
     * @return flushedWorkBundle WorkBundle object containing flushed Works.
     */
    flush(
        ) generates (
@@ -91,39 +87,42 @@ interface IComponent {
     * Drains the component, and optionally downstream components. This is a
     * signalling method; as such it does not wait for any work completion.
     *
     * The last `Work` item is marked as "drain-till-here", so the component is
     * notified not to wait for further `Work` before it processes what is
     * already queued. This method can also be used to set the end-of-stream
     * flag after `Work` has been queued. Client can continue to queue further
     * `Work` immediately after this method returns.
     * Marks last work item as "drain-till-here", so component is notified not
     * to wait for further work before it processes work already queued. This
     * method can also be used to set the end-of-stream flag after work has been
     * queued. Client can continue to queue further work immediately after this
     * method returns.
     *
     * This method must be supported in running (including tripped) states.
     *
     * `Work` that is completed must be returned via
     * IComponentListener::onWorkDone().
     * This method must return within 1ms.
     *
     * Work that is completed must be returned via the onWorkDone() callback.
     *
     * @param withEos Whether to drain the component with marking end-of-stream.
     * @return status Status of the call, which may be
     *   - `OK`        - The drain request has been successfully recorded.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     *   - OK        - The drain request has been successfully recorded.
     *   - TIMED_OUT - The flush could not be completed within the time limit.
     *                 (unexpected)
     *   - CORRUPTED - Some unknown error prevented flushing from completion.
     *                 (unexpected)
     */
    drain(bool withEos) generates (Status status);

    /**
     * Starts using a surface for output.
     *
     * This method must not block.
     *
     * @param blockPoolId Id of the `C2BlockPool` to be associated with the
     * @param blockPoolId The id of the BlockPool to be associated with the
     * output surface.
     * @param surface Output surface.
     * @param surface A surface to use for codec output.
     * @return status Status of the call, which may be
     *   - `OK`        - The operation completed successfully.
     *   - `CANNOT_DO` - The component does not support an output surface.
     *   - `REFUSED`   - The output surface cannot be accessed.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     *   - OK        - The operation completed successfully.
     *   - CANNOT_DO - The component does not support an output surface.
     *   - REFUSED   - The output surface cannot be accessed.
     *   - TIMED_OUT - The component could not be connected within the time
     *                 limit. (unexpected)
     *   - CORRUPTED - Some unknown error prevented connecting the component.
     *                 (unexpected)
     */
    setOutputSurface(
            uint64_t blockPoolId,
@@ -133,101 +132,65 @@ interface IComponent {
        );

    /**
     * Starts using an input surface.
     * Starts using a persistent OMX input surface for a component.
     *
     * The component must be in running state.
     *
     * @param inputSurface Input surface to connect to.
     * @param producer Producer component of an OMX persistent input surface.
     * @param source Source component of an OMX persistent input surface.
     * @return status Status of the call, which may be
     *   - `OK`        - The operation completed successfully.
     *   - `CANNOT_DO` - The component does not support an input surface.
     *   - `BAD_STATE` - The component is not in running state.
     *   - `DUPLICATE` - The component is already connected to an input surface.
     *   - `REFUSED`   - The input surface is already in use.
     *   - `NO_MEMORY` - Not enough memory to start the component.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     * @return connection `IInputSurfaceConnection` object, which can be used to
     *     query and configure properties of the connection. This cannot be
     *     null.
     */
    connectToInputSurface(
            IInputSurface inputSurface
        ) generates (
            Status status,
            IInputSurfaceConnection connection
        );

    /**
     * Starts using an OMX input surface.
     *
     * The component must be in running state.
     *
     * This method is similar to connectToInputSurface(), but it takes an OMX
     * input surface (as a pair of `IGraphicBufferProducer` and
     * `IGraphicBufferSource`) instead of Codec2's own `IInputSurface`.
     *
     * @param producer Producer component of an OMX input surface.
     * @param source Source component of an OMX input surface.
     * @return status Status of the call, which may be
     *   - `OK`        - The operation completed successfully.
     *   - `CANNOT_DO` - The component does not support an OMX input surface.
     *   - `BAD_STATE` - The component is not in running state.
     *   - `DUPLICATE` - The component is already connected to an input surface.
     *   - `REFUSED`   - The input surface is already in use.
     *   - `NO_MEMORY` - Not enough memory to start the component.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     * @return connection `IInputSurfaceConnection` object, which can be used to
     *     query and configure properties of the connection. This cannot be
     *     null.
     *   - OK        - The operation completed successfully.
     *   - CANNOT_DO - The component does not support an input surface.
     *   - BAD_STATE - Component is not in running state.
     *   - DUPLICATE - The component is already connected to an input surface.
     *   - REFUSED   - The input surface is already in use.
     *   - NO_MEMORY - Not enough memory to start the component.
     *   - TIMED_OUT - The component could not be connected within the time
     *                 limit. (unexpected)
     *   - CORRUPTED - Some unknown error prevented connecting the component.
     *                 (unexpected)
     */
    connectToOmxInputSurface(
            IGraphicBufferProducer producer,
            IGraphicBufferSource source
        ) generates (
            Status status,
            IInputSurfaceConnection connection
        );
        ) generates (Status status);

    /**
     * Stops using an input surface.
     *
     * This call is used for both Codec 2.0 and OMX input surfaces.
     *
     * The component must be in running state.
     *
     * @return status Status of the call, which may be
     *   - `OK`        - The operation completed successfully.
     *   - `CANNOT_DO` - The component does not support an input surface.
     *   - `BAD_STATE` - The component is not in running state.
     *   - `NOT_FOUND` - The component is not connected to an input surface.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     *   - OK        - The operation completed successfully.
     *   - CANNOT_DO - The component does not support an input surface.
     *   - BAD_STATE - Component is not in running state.
     *   - NOT_FOUND - The component is not connected to an input surface.
     *   - TIMED_OUT - The component could not be connected within the time
     *                 limit. (unexpected)
     *   - CORRUPTED - Some unknown error prevented connecting the component.
     *                 (unexpected)
     */
    disconnectFromInputSurface() generates (Status Status);

    /**
     * Creates a local `C2BlockPool` backed by the given allocator and returns
     * its id.
     *
     * The returned @p blockPoolId is the only way the client can refer to a
     * `C2BlockPool` object in the component. The id can be passed to
     * setOutputSurface() or used in some C2Param objects later.
     * Creates a local block pool backed by the given allocator and returns its
     * identifier.
     *
     * The created `C2BlockPool` object can be destroyed by calling
     * destroyBlockPool(), reset() or release(). reset() and release() must
     * destroy all `C2BlockPool` objects that have been created.
     * This call must return within 100 msec.
     *
     * @param allocatorId Id of a `C2Allocator`.
     * @param allocatorId The Codec 2.0 allocator ID
     * @return status Status of the call, which may be
     *   - `OK`        - The operation completed successfully.
     *   - `NO_MEMORY` - Not enough memory to create the pool.
     *   - `BAD_VALUE` - @p allocatorId is not recognized.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     * @return blockPoolId Id of the created C2BlockPool object. This may be
     *     used in setOutputSurface() if the allocator
     * @return configurable Configuration interface for the created pool. This
     *     must not be null.
     *   - OK        - The operation completed successfully.
     *   - NO_MEMORY - Not enough memory to create the pool.
     *   - BAD_VALUE - Invalid allocator.
     *   - TIMED_OUT - The pool could not be created within the time
     *                 limit. (unexpected)
     *   - CORRUPTED - Some unknown error prevented creating the pool.
     *                 (unexpected)
     * @return blockPoolId The Codec 2.0 blockpool ID for the created pool.
     * @return configurable Configuration interface for the created pool.
     */
    createBlockPool(uint32_t allocatorId) generates (
        Status status,
@@ -238,13 +201,17 @@ interface IComponent {
    /**
     * Destroys a local block pool previously created by createBlockPool().
     *
     * @param blockPoolId Id of a `C2BlockPool` that was previously returned by
     * This call must return within 100 msec.
     *
     * @param blockPoolId The block pool id previously returned by
     *      createBlockPool().
     * @return status Status of the call, which may be
     *   - `OK`        - The operation completed successfully.
     *   - `NOT_FOUND` - The supplied blockPoolId is not valid.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     *   - OK        - The operation completed successfully.
     *   - NOT_FOUND - The supplied blockPoolId is not valid.
     *   - TIMED_OUT - The pool could not be destroyedwithin the time limit.
     *                 (unexpected)
     *   - CORRUPTED - Some unknown error prevented destruction of the pool.
     *                 (unexpected)
     */
    destroyBlockPool(uint64_t blockPoolId) generates (Status status);

@@ -256,24 +223,28 @@ interface IComponent {
     *
     * This method must be supported in stopped state as well as tripped state.
     *
     * If the return value is `OK`, the component must be in the running state.
     * If the return value is `BAD_STATE` or `DUPLICATE`, no state change is
     * expected as a response to this call. Otherwise, the component must be in
     * the stopped state.
     * If the return value is OK, the component must be in the running state.
     * If the return value is BAD_STATE or DUPLICATE, no state change is
     * expected as a response to this call.
     * Otherwise, the component must be in the stopped state.
     *
     * If a component is in the tripped state and start() is called while the
     * component configuration still results in a trip, start() must succeed and
     * a new onTripped() callback must be used to communicate the configuration
     * component configuration still results in a trip, start must succeed and
     * a new onTripped callback must be used to communicate the configuration
     * conflict that results in the new trip.
     *
     * This method must return within 500ms.
     *
     * @return status Status of the call, which may be
     *   - `OK`        - The component has started successfully.
     *   - `BAD_STATE` - Component is not in stopped or tripped state.
     *   - `DUPLICATE` - When called during another start call from another
     *   - OK        - The component has started successfully.
     *   - BAD_STATE - Component is not in stopped or tripped state.
     *   - DUPLICATE - When called during another start call from another
     *                 thread.
     *   - `NO_MEMORY` - Not enough memory to start the component.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     *   - NO_MEMORY - Not enough memory to start the component.
     *   - TIMED_OUT - The component could not be started within the time limit.
     *                 (unexpected)
     *   - CORRUPTED - Some unknown error prevented starting the component.
     *                 (unexpected)
     */
    start() generates (Status status);

@@ -284,22 +255,22 @@ interface IComponent {
     *
     * This method must return withing 500ms.
     *
     * Upon this call, all pending `Work` must be abandoned.
     *
     * If the return value is `BAD_STATE` or `DUPLICATE`, no state change is
     * expected as a response to this call. For all other return values, the
     * component must be in the stopped state.
     * Upon this call, all pending work must be abandoned.
     * If the return value is BAD_STATE or DUPLICATE, no state change is
     * expected as a response to this call.
     * For all other return values, the component must be in the stopped state.
     *
     * This does not alter any settings and tunings that may have resulted in a
     * tripped state.
     *
     * @return status Status of the call, which may be
     *   - `OK`        - The component has stopped successfully.
     *   - `BAD_STATE` - Component is not in running state.
     *   - `DUPLICATE` - When called during another stop call from another
     *                   thread.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     *   - OK        - The component has stopped successfully.
     *   - BAD_STATE - Component is not in running state.
     *   - DUPLICATE - When called during another stop call from another thread.
     *   - TIMED_OUT - The component could not be stopped within the time limit.
     *                 (unexpected)
     *   - CORRUPTED - Some unknown error prevented starting the component.
     *                 (unexpected)
     */
    stop() generates (Status status);

@@ -313,24 +284,25 @@ interface IComponent {
     *
     * This method must return withing 500ms.
     *
     * When this call returns, if @p status is `OK`, all `Work` items must
     * have been abandoned, and all resources (including `C2BlockPool` objects
     * previously created by createBlockPool()) must have been released.
     * After this call returns all work must have been abandoned, all references
     * must have been released.
     *
     * If the return value is `BAD_STATE` or `DUPLICATE`, no state change is
     * expected as a response to this call. For all other return values, the
     * component must be in the stopped state.
     * If the return value is BAD_STATE or DUPLICATE, no state change is
     * expected as a response to this call.
     * For all other return values, the component shall be in the stopped state.
     *
     * This brings settings back to their default, "guaranteeing" no tripped
     * This brings settings back to their default - "guaranteeing" no tripped
     * state.
     *
     * @return status Status of the call, which may be
     *   - `OK`        - The component has been reset.
     *   - `BAD_STATE` - Component is in released state.
     *   - `DUPLICATE` - When called during another reset call from another
     *   - OK        - The component has been reset.
     *   - BAD_STATE - Component is in released state.
     *   - DUPLICATE - When called during another reset call from another
     *                 thread.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     *   - TIMED_OUT - The component could not be reset within the time limit.
     *                 (unexpected)
     *   - CORRUPTED - Some unknown error prevented resetting the component.
     *                 (unexpected)
     */
    reset() generates (Status status);

@@ -339,27 +311,19 @@ interface IComponent {
     *
     * This method must be supported in stopped state.
     *
     * This method destroys the component. Upon return, if @p status is `OK` or
     * `DUPLICATE`, all resources must have been released.
     * This method must return withing 500ms. Upon return all references must
     * be abandoned.
     *
     * @return status Status of the call, which may be
     *   - `OK`        - The component has been released.
     *   - `BAD_STATE` - The component is running.
     *   - `DUPLICATE` - The component is already released.
     *   - `TIMED_OUT` - The operation cannot be finished in a timely manner.
     *   - `CORRUPTED` - Some unknown error occurred.
     *   - OK        - The component has been released.
     *   - BAD_STATE - The component is running.
     *   - DUPLICATE - The component is already released.
     *   - TIMED_OUT - The component could not be released within the time
     *                 limit. (unexpected)
     *   - CORRUPTED - Some unknown error prevented releasing the component.
     *                 (unexpected)
     */
    release() generates (Status status);

    /**
     * Returns the @ref IComponentInterface instance associated to this
     * component.
     *
     * An @p IConfigurable instance for the component can be obtained by calling
     * IComponentInterface::getConfigurable() on the returned @p intf.
     *
     * @return intf `IComponentInterface` instance. This must not be null.
     */
    getInterface() generates (IComponentInterface intf);
};
+12 −11
Original line number Diff line number Diff line
@@ -19,20 +19,21 @@ package android.hardware.media.c2@1.0;
import IConfigurable;

/**
 * Component interface object. This object contains all of the configurations of
 * Component interface object. This object contains all of the configuration of
 * a potential or actual component. It can be created and used independently of
 * an actual Codec2 component to query supported parameters for various
 * component settings, and configurations for a potential component.
 *
 * An actual component exposes this interface via IComponent::getInterface().
 * an actual Codec 2.0 component instance to query support and parameters for
 * various component settings and configurations for a potential component.
 * Actual components also expose this interface.
 */
interface IComponentInterface {
    /**
     * Returns the @ref IConfigurable instance associated to this component
     * interface.
interface IComponentInterface extends IConfigurable {
    /*
     * There are no additional methods to IConfigurable interface.
     *
     * Component interfaces have no states.
     *
     * @return configurable `IConfigurable` instance. This must not be null.
     * The name of the component or component interface object is a unique name
     * for that component or component interface 'class'; however, multiple
     * instances of that component must have the same name.
     */
    getConfigurable() generates (IConfigurable configurable);
};
+12 −70

File changed.

Preview size limit exceeded, changes collapsed.

+83 −94

File changed.

Preview size limit exceeded, changes collapsed.

+69 −149

File changed.

Preview size limit exceeded, changes collapsed.

Loading