platform_hardware_interfaces/media/c2/1.0/IComponent.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.graphics.bufferqueue@1.0::IGraphicBufferProducer;
import android.hardware.media.omx@1.0::IGraphicBufferSource;

import IConfigurable;
import IComponentInterface;
import IComponentListener;

/**
 * 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 extends IComponentInterface {

    // METHODS AVAILABLE WHEN RUNNING
    // =========================================================================

    /**
     * Queues up work for the component.
     *
     * This method must be supported in running (including tripped) states.
     *
     * 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 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(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 for the component.
     *
     * This method must be supported in running (including tripped) states.
     *
     * 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
     * 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 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 (
            Status status,
            WorkBundle flushedWorkBundle
        );

    /**
     * Drains the component, and optionally downstream components. This is a
     * signalling method; as such it does not wait for any work completion.
     *
     * 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.
     *
     * 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 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.
     *
     * @param blockPoolId The id of the BlockPool to be associated with the
     * 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 component could not be connected within the time
     *                 limit. (unexpected)
     *   - CORRUPTED - Some unknown error prevented connecting the component.
     *                 (unexpected)
     */
    setOutputSurface(
            uint64_t blockPoolId,
            IGraphicBufferProducer surface
        ) generates (
            Status status
        );

    /**
     * Starts using a persistent OMX input surface for a component.
     *
     * The component must be in running state.
     *
     * @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 - 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);

    /**
     * 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 - 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 block pool backed by the given allocator and returns its
     * identifier.
     *
     * This call must return within 100 msec.
     *
     * @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 - 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,
        uint64_t blockPoolId,
        IConfigurable configurable
    );

    /**
     * Destroys a local block pool previously created by createBlockPool().
     *
     * 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 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);

    // STATE CHANGE METHODS
    // =========================================================================

    /**
     * Starts the component.
     *
     * 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 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
     * 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
     *                 thread.
     *   - 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);

    /**
     * Stops the component.
     *
     * This method must be supported in running (including tripped) state.
     *
     * 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.
     *
     * 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 component could not be stopped within the time limit.
     *                 (unexpected)
     *   - CORRUPTED - Some unknown error prevented starting the component.
     *                 (unexpected)
     */
    stop() generates (Status status);

    /**
     * Resets the component.
     *
     * This method must be supported in all (including tripped) states other
     * than released.
     *
     * This method must be supported during any other blocking call.
     *
     * This method must return withing 500ms.
     *
     * 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 shall be in the stopped state.
     *
     * 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
     *                 thread.
     *   - 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);

    /**
     * Releases the component.
     *
     * This method must be supported in stopped state.
     *
     * 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 component could not be released within the time
     *                 limit. (unexpected)
     *   - CORRUPTED - Some unknown error prevented releasing the component.
     *                 (unexpected)
     */
    release() generates (Status status);

};