diff --git a/media/c2/1.0/IComponent.hal b/media/c2/1.0/IComponent.hal index 7fd551fc2b..deb9255ecd 100644 --- a/media/c2/1.0/IComponent.hal +++ b/media/c2/1.0/IComponent.hal @@ -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 * - * @param workBundle `WorkBundle` object containing a list of `Work` objects - * to queue to the component. + * 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 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 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 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 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 - * output surface. - * @param surface Output surface. + * @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 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. + * Creates a local block pool backed by the given allocator and returns its + * identifier. * - * 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. + * This call must return within 100 msec. * - * 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. - * - * @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 - * 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. + * - 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); @@ -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 - * thread. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. + * - 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); @@ -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); }; diff --git a/media/c2/1.0/IComponentInterface.hal b/media/c2/1.0/IComponentInterface.hal index a007d02fe3..d4b30b1b7b 100644 --- a/media/c2/1.0/IComponentInterface.hal +++ b/media/c2/1.0/IComponentInterface.hal @@ -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. * - * @return configurable `IConfigurable` instance. This must not be null. + * Component interfaces have no states. + * + * 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); }; diff --git a/media/c2/1.0/IComponentListener.hal b/media/c2/1.0/IComponentListener.hal index 70d5fb289e..eb71ecbdd5 100644 --- a/media/c2/1.0/IComponentListener.hal +++ b/media/c2/1.0/IComponentListener.hal @@ -17,112 +17,54 @@ package android.hardware.media.c2@1.0; /** - * Callback interface for handling notifications from @ref IComponent. + * This callback interface is used for handling notifications from IComponent. */ interface IComponentListener { /** - * Notify the listener that some `Work` items have been completed. - * - * All the input buffers in the returned `Work` objects must not be used by - * the component after onWorkDone() is called. - * - * @param workBundle List of completed `Work` objects. + * Notify the listener that some works have been completed. */ oneway onWorkDone(WorkBundle workBundle); /** * Notify the listener that the component is tripped. - * - * @param settingResults List of failures. */ oneway onTripped(vec settingResults); /** * Notify the listener of an error. * - * @param status Error type. @p status may be `OK`, which means that an - * error has occurred, but the error type does not fit into the type - * `Status`. In this case, additional information is provided by - * @p errorCode. - * @param errorCode Additional error information. The framework may not - * recognize the meaning of this value. + * @param status Error type. \p status may be `OK`, which means that an + * error has occurred, but the error type is unknown. + * @param errorCode Additional error code. The framework may not recognize + * this. */ oneway onError(Status status, uint32_t errorCode); /** - * Information about rendering of a frame to a `Surface`. + * Information about rendering of a frame. */ struct RenderedFrame { /** - * Id of the `BufferQueue` containing the rendered buffer. - * - * This value must have been obtained by an earlier call to - * IGraphicBufferProducer::getUniqueId(). + * Id of the buffer queue containing the rendered buffer. */ uint64_t bufferQueueId; /** * Id of the slot of the rendered buffer. - * - * This value must have been obtained by an earlier call to - * IGraphicBufferProducer::dequeueBuffer() or - * IGraphicBufferProducer::attachBuffer(). */ int32_t slotId; /** - * Timestamp the rendering happened. - * - * The reference point for the timestamp is determined by the - * `BufferQueue` that performed the rendering. + * Timestamp of the rendering (consistent with timestamps in + * the associated BufferQueue). */ int64_t timestampNs; }; /** - * Notify the listener that frames have been rendered. + * Notify the listener that frames are rendered. * - * @param renderedFrames List of @ref RenderedFrame objects. + * @param renderedFrames List of information about renderings of frames. */ oneway onFramesRendered(vec renderedFrames); - - /** - * Identifying information for an input buffer previously queued to the - * component via IComponent::queue(). - */ - struct InputBuffer { - /** - * This value comes from `Work::input.ordinal.frameIndex` in a `Work` - * object that was previously queued. - */ - uint64_t frameIndex; - /** - * This value is an index into `Work::input.buffers` (which is an array) - * in a `Work` object that was previously queued. - */ - uint32_t arrayIndex; - }; - - /** - * Notify the listener that some input buffers are no longer needed by the - * component, and hence can be released or reused by the client. - * - * Input buffers that are contained in a `Work` object returned by an - * earlier onWorkDone() call are assumed released, so they must not appear - * in any onInputBuffersReleased() calls. That means - * onInputBuffersReleased() must only report input buffers that are released - * before the output in the same `Work` item is produced. However, it is - * possible for an input buffer to be returned by onWorkDone() after it has - * been reported by onInputBuffersReleased(). - * - * @note onWorkDone() and onInputBuffersReleased() both notify the client - * that input buffers are no longer needed. However, in order to minimize - * IPC calls, onInputBuffersReleased() should be called only when - * onWorkDone() cannot be called, e.g., the component needs more input - * before an output can be produced. - * - * @param inputBuffers List of `InputBuffer` objects, identifying input - * buffers that are no longer needed by the component. - */ - oneway onInputBuffersReleased(vec inputBuffers); }; diff --git a/media/c2/1.0/IComponentStore.hal b/media/c2/1.0/IComponentStore.hal index a027afe465..d2474cc1c9 100644 --- a/media/c2/1.0/IComponentStore.hal +++ b/media/c2/1.0/IComponentStore.hal @@ -23,33 +23,27 @@ import IComponent; import IConfigurable; import IInputSurface; -/** - * Entry point for Codec2 HAL. - * - * All methods in `IComponentStore` must not block. If a method call cannot be - * completed in a timely manner, it must return `TIMED_OUT` in the return - * status. The only exceptions are getPoolClientManager() and getConfigurable(), - * which must always return immediately. - */ -interface IComponentStore { +interface IComponentStore extends IConfigurable { /** * Creates a component by name. * - * @param name Name of the component to create. This must match one of the - * names returned by listComponents(). - * @param listener Callback receiver. - * @param pool `IClientManager` object of the BufferPool in the client - * process. This may be null if the client does not own a BufferPool. - * @return status Status of the call, which may be - * - `OK` - The component was created successfully. - * - `NOT_FOUND` - There is no component with the given name. - * - `NO_MEMORY` - Not enough memory to create the component. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. - * @return comp The created component if @p status is `OK`. + * This method must return within 100ms. * - * @sa IComponentListener. + * @param name Name of the component to create. This should match one of the + * names returned by listComponents(). + * @param listener The component listener to use for the component. + * @param pool The buffer pool client manager of the component listener. + * This must be null if the listener process does not own a buffer pool. + * @return status Status of the call, which may be + * - OK - The component was created successfully. + * - NOT_FOUND - There is no component with the given name. + * - NO_MEMORY - Not enough memory to create the component. + * - TIMED_OUT - The component could not be created within the time limit. + * (unexpected) + * - CORRUPTED - Some unknown error prevented the creation of the + * component. (unexpected) + * @return comp The created component if `Status = OK`. */ createComponent( string name, @@ -63,15 +57,19 @@ interface IComponentStore { /** * Creates a component interface by name. * + * This method must return within 100ms. + * * @param name Name of the component interface to create. This should match * one of the names returned by listComponents(). * @return status Status of the call, which may be - * - `OK - The component interface was created successfully. - * - `NOT_FOUND` - There is no component interface with the given name. - * - `NO_MEMORY` - Not enough memory to create the component interface. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. - * @return compIntf The created component interface if @p status is `OK`. + * - OK - The component interface was created successfully. + * - NOT_FOUND - There is no component interface with the given name. + * - NO_MEMORY - Not enough memory to create the component interface. + * - TIMED_OUT - The component interface could not be created within the + * time limit. (unexpected) + * - CORRUPTED - Some unknown error prevented the creation of the + * component interface. (unexpected) + * @return compIntf The created component interface if `Status = OK`. */ createInterface( string name @@ -85,49 +83,57 @@ interface IComponentStore { */ struct ComponentTraits { /** - * Name of the component. This must be unique for each component. - * - * This name is use to identify the component to create in - * createComponent() and createComponentInterface(). + * Name of the component. */ string name; enum Domain : uint32_t { - OTHER = 0, - VIDEO, AUDIO, - IMAGE, + VIDEO, + OTHER = 0xffffffff, }; /** - * Component domain. + * Component domain. The framework may not recognize `OTHER`. */ Domain domain; + /** + * If #domain is `OTHER`, #domainOther can be used to provide additional + * information. Otherwise, #domainOther is ignored. The framework may + * not inspect this value. + */ + uint32_t domainOther; enum Kind : uint32_t { - OTHER = 0, DECODER, ENCODER, + OTHER = 0xffffffff, }; /** - * Component kind. + * Component kind. The framework may not recognize `OTHER`. */ Kind kind; + /** + * If #kind is `OTHER`, #kindOther can be used to provide additional + * information. Otherwise, #kindOther is ignored. The framework may not + * inspect this value. + */ + uint32_t kindOther; /** - * Rank used by `MediaCodecList` to determine component ordering. Lower + * Rank used by MediaCodecList to determine component ordering. Lower * value means higher priority. */ uint32_t rank; /** - * MIME type. + * Media type. */ string mediaType; /** * Aliases for component name for backward compatibility. * - * Multiple components can have the same alias (but not the same + * \note Multiple components can have the same alias (but not the same * component name) as long as their media types differ. */ vec aliases; @@ -136,51 +142,36 @@ interface IComponentStore { /** * Returns the list of components supported by this component store. * - * @return status Status of the call, which may be - * - `OK - The operation was successful. - * - `NO_MEMORY` - Not enough memory to complete this method. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. - * @return traits List of component traits for all components supported by - * this store (in no particular order). + * This method must return within 500ms. + * + * @return traits List of component traits for all components supported by this store in no + * particular order. */ - listComponents() generates ( - Status status, - vec traits - ); + listComponents() generates (vec traits); /** * Creates a persistent input surface that can be used as an input surface * for any IComponent instance * - * @return status Status of the call, which may be - * - `OK - The operation was successful. - * - `NO_MEMORY` - Not enough memory to complete this method. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. - * @return surface A persistent input surface. This may be null to indicate - * an error. + * This method must return within 100ms. + * + * @return surface A persistent input surface */ - createInputSurface() generates ( - Status status, - IInputSurface surface - ); + createInputSurface() generates (IInputSurface surface); /** - * Returns a list of `StructDescriptor` objects for a set of requested - * C2Param structure indices that this store is aware of. + * Returns a list of StructDescriptor object for a set of requested + * structures that this store is aware of. * * This operation must be performed at best effort, e.g. the component * store must simply ignore all struct indices that it is not aware of. * - * @param indices Indices of C2Param structures to describe. + * @param indices struct indices to return des * @return status Status of the call, which may be - * - `OK` - The operation completed successfully. - * - `NOT_FOUND` - Some indices were not known. - * - `NO_MEMORY` - Not enough memory to complete this method. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. - * @return structs List of `StructDescriptor` objects. + * - OK - The operation completed successfully. + * - NOT_FOUND - Some indices were not known. + * - NO_MEMORY - Not enough memory to complete this method. + * @return structs List of StructDescriptor objects. */ getStructDescriptors( vec indices @@ -190,35 +181,33 @@ interface IComponentStore { ); /** - * Copies the contents of @p src into @p dst without changing the format of - * @p dst. + * Returns information required for using BufferPool API in buffer passing. + * If the returned pool is not null, the client can call registerSender() to + * register its IAccessor instance, hence allowing the client to send + * buffers to components hosted by this process. + * + * @return pool If the component store supports receiving buffers via + * BufferPool API, \p pool must be a valid `IClientManager` instance. + * Otherwise, \p pool must be null. + */ + getPoolClientManager( + ) generates ( + IClientManager pool + ); + + /** + * The store must copy the contents of \p src into \p dst without changing + * the format of \p dst. * * @param src Source buffer. * @param dst Destination buffer. * @return status Status of the call, which may be - * - `OK` - The copy is successful. - * - `CANNOT_DO` - @p src and @p dst are not compatible. - * - `REFUSED` - No permission to copy. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. + * - OK - The copy is successful. + * - CANNOT_DO - \p src and \p dst are not compatible. + * - REFUSED - No permission to copy. + * - CORRUPTED - The copy cannot be done. (unexpected) */ copyBuffer(Buffer src, Buffer dst) generates (Status status); - /** - * Returns the `IClientManager` object for the component's BufferPool. - * - * @return pool If the component store supports receiving buffers via - * BufferPool API, @p pool must be a valid `IClientManager` instance. - * Otherwise, @p pool must be null. - */ - getPoolClientManager() generates (IClientManager pool); - - /** - * Returns the @ref IConfigurable instance associated to this component - * store. - * - * @return configurable `IConfigurable` instance. This must not be null. - */ - getConfigurable() generates (IConfigurable configurable); }; diff --git a/media/c2/1.0/IConfigurable.hal b/media/c2/1.0/IConfigurable.hal index 31dc4d3cba..cd4dd10151 100644 --- a/media/c2/1.0/IConfigurable.hal +++ b/media/c2/1.0/IConfigurable.hal @@ -17,78 +17,43 @@ package android.hardware.media.c2@1.0; /** - * Generic configuration interface presented by all configurable Codec2 objects. + * Generic configuration interface used by all configurable Codec 2.0 + * components. * - * This interface must be supported in all states of the owning object, and must - * not change the state of the owning object. + * This interface must be supported in all states of the inheriting + * object, and must not change the state of the inheriting object. */ interface IConfigurable { /** - * Returns the id of the object. This must be unique among all objects of - * the same type hosted by the same store. + * Returns the name of this object. This must match the name that was + * supplied during the creation of the object. * - * @return id Id of the object. - */ - getId() generates (uint32_t id); - - /** - * Returns the name of the object. - * - * This must match the name that was supplied during the creation of the - * object. - * - * @return name Name of the object. + * @return name Name of this object. */ getName() generates (string name); /** - * Queries a set of parameters from the object. + * Queries a set of parameters from the object. Querying is performed at + * best effort: the object must query all supported parameters and skip + * unsupported ones, or parameters that could not be allocated. Any errors + * are communicated in the return value. * - * Querying is performed at best effort: the object must query all supported - * parameters and skip unsupported ones (which may include parameters that - * could not be allocated). Any errors are communicated in the return value. + * \note Parameter values do not depend on the order of query. * - * If @p mayBlock is false, this method must not block. All parameter - * queries that require blocking must be skipped. + * This method must return within 1ms if \p mayBlock is DONT_BLOCK, and + * within 5ms otherwise. * - * If @p mayBlock is true, a query may block, but the whole method call - * has to complete in a timely manner, or `status = TIMED_OUT` is returned. - * - * If @p mayBlock is false, this method must not block. Otherwise, this - * method is allowed to block for a certain period of time before completing - * the operation. If the operation is not completed in a timely manner, - * `status = TIMED_OUT` is returned. - * - * @note The order of C2Param objects in @p param does not depend on the - * order of C2Param structure indices in @p indices. - * - * \par For IComponent - * - * When the object type is @ref IComponent, this method must be supported in - * any state except released. This call must not change the state nor the - * internal configuration of the component. - * - * The blocking behavior of this method differs among states: - * - In the stopped state, this must be non-blocking. @p mayBlock is - * ignored. (The method operates as if @p mayBlock was false.) - * - In any of the running states, this method may block momentarily if - * @p mayBlock is true. However, if the call cannot be completed in a - * timely manner, `status = TIMED_OUT` is returned. - * - * @param indices List of C2Param structure indices to query. + * @param indices List of param indices for params to be queried. * @param mayBlock Whether this call may block or not. * @return status Status of the call, which may be - * - `OK` - All parameters could be queried. - * - `BAD_INDEX` - All supported parameters could be queried, but some - * parameters were not supported. - * - `NO_MEMORY` - Could not allocate memory for a supported parameter. - * - `BLOCKING` - Querying some parameters requires blocking, but - * @p mayBlock is false. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. - * @return params Flattened representation of C2Param objects. - * - * @sa Params. + * - OK - All parameters could be queried. + * - BAD_INDEX - All supported parameters could be queried, but some + * parameters were not supported. + * - NO_MEMORY - Could not allocate memory for a supported parameter. + * - BLOCKING - Querying some parameters requires blocking. + * - CORRUPTED - Some unknown error prevented the querying of the + * parameters. (unexpected) + * @return params List of params queried corresponding to \p indices. */ query( vec indices, @@ -99,60 +64,31 @@ interface IConfigurable { ); /** - * Sets a set of parameters for the object. + * Sets a set of parameters for the object. Tuning is performed at best + * effort: the object must update all supported configuration at best + * effort and skip unsupported parameters. Any errors are communicated in + * the return value and in \p failures. * - * Tuning is performed at best effort: the object must update all supported - * configurations at best effort and skip unsupported parameters. Any errors - * are communicated in the return value and in @p failures. + * \note Parameter tuning DOES depend on the order of the tuning parameters. + * E.g. some parameter update may allow some subsequent parameter update. * - * A non-strict parameter update with an unsupported value shall cause an - * update to the closest supported value. A strict parameter update with an - * unsupported value shall be skipped and a failure shall be returned. - * - * If @p mayBlock is false, this method must not block. An update that - * requires blocking shall be skipped and a failure shall be returned. - * - * If @p mayBlock is true, an update may block, but the whole method call - * has to complete in a timely manner, or `status = TIMED_OUT` is returned. - * - * The final values for all parameters set are propagated back to the caller - * in @p params. - * - * \par For IComponent - * - * When the object type is @ref IComponent, this method must be supported in - * any state except released. - * - * The blocking behavior of this method differs among states: - * - In the stopped state, this must be non-blocking. @p mayBlock is - * ignored. (The method operates as if @p mayBlock was false.) - * - In any of the running states, this method may block momentarily if - * @p mayBlock is true. However, if the call cannot be completed in a - * timely manner, `status = TIMED_OUT` is returned. - * - * @note Parameter tuning @e does depend on the order of the tuning - * parameters, e.g., some parameter update may enable some subsequent - * parameter update. + * This method must return within 1ms if \p mayBlock is false, and within + * 5ms otherwise. * * @param inParams Requested parameter updates. * @param mayBlock Whether this call may block or not. * @return status Status of the call, which may be - * - `OK` - All parameters could be updated successfully. - * - `BAD_INDEX` - All supported parameters could be updated successfully, - * but some parameters were not supported. - * - `NO_MEMORY` - Some supported parameters could not be updated - * successfully because they contained unsupported values. - * These are returned in @p failures. - * - `BLOCKING` - Setting some parameters requires blocking, but - * @p mayBlock is false. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. - * @return failures List of update failures. - * @return outParams Flattened representation of configured parameters. The - * order of parameters in @p outParams is based on the order of - * requested updates in @p inParams. - * - * @sa SettingResult. + * - OK - All parameters could be updated successfully. + * - BAD_INDEX - All supported parameters could be updated successfully, + * but some parameters were not supported. + * - NO_MEMORY - Some supported parameters could not be updated + * successfully because they contained unsupported values. + * These are returned in \p failures. + * - BLOCKING - Setting some parameters requires blocking. + * - CORRUPTED - Some unknown error prevented the update of the + * parameters. (unexpected) + * @return failures List of parameter failures. + * @return outParams Resulting values for the configured parameters. */ config( Params inParams, @@ -167,19 +103,22 @@ interface IConfigurable { // ========================================================================= /** - * Returns a list of supported parameters within a selected range of C2Param - * structure indices. + * Returns a selected range of the set of supported parameters. * - * @param start The first index of the selected range. - * @param count The length of the selected range. + * The set of supported parameters are represented in a vector with a + * start index of 0, and the selected range are indices into this vector. + * Fewer than \p count parameters are returned if the selected range is + * not fully/not at all part of the available vector indices. + * + * This method must return within 1ms. + * + * @param start start index of selected range + * @param count size of the selected * @return status Status of the call, which may be - * - `OK` - The operation completed successfully. - * - `NO_MEMORY` - Not enough memory to complete this method. - * @return params List of supported parameters in the selected range. This - * list may have fewer than @p count elements if some indices in the - * range are not supported. - * - * @sa ParamDescriptor. + * - OK - The operation completed successfully. + * - NO_MEMORY - Not enough memory to complete this method. + * @return params Vector containing the selected range of supported + * parameters. */ querySupportedParams( uint32_t start, @@ -192,42 +131,23 @@ interface IConfigurable { /** * Retrieves the supported values for the queried fields. * - * The object must process all fields queried even if some queries fail. + * Upon return the object must fill in the supported + * values for the fields listed as well as a status for each field. + * Object shall process all fields queried even if some queries fail. * - * If @p mayBlock is false, this method must not block. Otherwise, this - * method is allowed to block for a certain period of time before completing - * the operation. If the operation cannot be completed in a timely manner, - * `status = TIMED_OUT` is returned. + * This method must return within 1ms if \p mayBlock is false, and within + * 5ms otherwise. * - * \par For IComponent - * - * When the object type is @ref IComponent, this method must be supported in - * any state except released. - * - * The blocking behavior of this method differs among states: - * - In the stopped state, this must be non-blocking. @p mayBlock is - * ignored. (The method operates as if @p mayBlock was false.) - * - In any of the running states, this method may block momentarily if - * @p mayBlock is true. However, if the call cannot be completed in a - * timely manner, `status = TIMED_OUT` is returned. - * - * @param inFields List of field queries. + * @param inFields Vector of field queries. * @param mayBlock Whether this call may block or not. * @return status Status of the call, which may be - * - `OK` - The operation completed successfully. - * - `BLOCKING` - Querying some parameters requires blocking, but - * @p mayBlock is false. - * - `NO_MEMORY` - Not enough memory to complete this method. - * - `BAD_INDEX` - At least one field was not recognized as a component - * field. - * - `BLOCKING` - Querying some fields requires blocking, but @p mayblock - * is false. - * - `TIMED_OUT` - The operation cannot be finished in a timely manner. - * - `CORRUPTED` - Some unknown error occurred. - * @return outFields List of supported values and results for the - * supplied queries. - * - * @sa FieldSupportedValuesQuery, FieldSupportedValuesQueryResult. + * - OK - The operation completed successfully. + * - BLOCKING - Querying some parameters requires blocking. + * - NO_MEMORY - Not enough memory to complete this method. + * - BAD_INDEX - At least one field was not recognized as a component + * field. + * @return outFields Vector containing supported values and query result + * for the selected fields. */ querySupportedValues( vec inFields, diff --git a/media/c2/1.0/IInputSurface.hal b/media/c2/1.0/IInputSurface.hal index 25c6c8e570..c083a21879 100644 --- a/media/c2/1.0/IInputSurface.hal +++ b/media/c2/1.0/IInputSurface.hal @@ -19,33 +19,43 @@ package android.hardware.media.c2@1.0; import android.hardware.graphics.bufferqueue@1.0::IGraphicBufferProducer; import IConfigurable; +import IComponent; +import IInputSurfaceConnection; /** - * Input surface for a Codec2 component. - * - * An input surface is an instance of `IInputSurface`, which may be - * created by calling IComponentStore::createInputSurface(). Once created, the - * client may - * 1. write data to it via the `IGraphicBufferProducer` interface; and - * 2. use it as input to a Codec2 encoder. - * - * @sa IInputSurfaceConnection, IComponentStore::createInputSurface(), - * IComponent::connectToInputSurface(). + * Input surface that can be configured for the IComponent. */ -interface IInputSurface { - /** - * Returns the producer interface into the internal buffer queue. - * - * @return producer `IGraphicBufferProducer` instance. This must not be - * null. - */ - getGraphicBufferProducer() generates (IGraphicBufferProducer producer); +interface IInputSurface extends IGraphicBufferProducer { /** - * Returns the @ref IConfigurable instance associated to this input surface. + * Connects this input surface to a component. * - * @return configurable `IConfigurable` instance. This must not be null. + * This call must return within 100 ms. + * + * @param component The component to connect to. This must have type + * IComponent. + * @return status Status of the call, which may be + * - OK - The operation succeeded. + * - BAD_STATE - The component is in running state. + * - DUPLICATE - The surface is already connected to a component. + * - NO_MEMORY - Could not allocate memory to connect to the component. + * - CORRUPTED - Some unknown error prevented the connection. (unexpected) + * @return connection Connection object that is used to disconnect + * from the component. + */ + connectToComponent( + IComponent component + ) generates ( + Status status, + IInputSurfaceConnection connection + ); + + /** + * Returns the Codec 2.0 configuration object for this surface. + * + * @return configurable The configuration object for this surface. */ getConfigurable() generates (IConfigurable configurable); + }; diff --git a/media/c2/1.0/IInputSurfaceConnection.hal b/media/c2/1.0/IInputSurfaceConnection.hal index efd9c6e9a5..500091dbbc 100644 --- a/media/c2/1.0/IInputSurfaceConnection.hal +++ b/media/c2/1.0/IInputSurfaceConnection.hal @@ -16,22 +16,20 @@ package android.hardware.media.c2@1.0; -import IConfigurable; - -/** - * Connection between a component and an input surface. - * - * An instance of `IInputSurfaceConnection` contains an `IConfigurable` - * interface for querying and configuring properties of the connection. - */ interface IInputSurfaceConnection { + /** - * Returns the @ref IConfigurable instance associated to this connection. + * Disconnects this input surface from the component. * - * This can be used to customize the connection. + * This call must return within 100 ms. * - * @return configurable `IConfigurable` instance. This must not be null. + * @return status Status of the call, which may be + * - OK - The operation succeeded. + * - BAD_STATE - The component is not in running state. + * - NOT_FOUND - The surface is not connected to a component. + * - CORRUPTED - Some unknown error prevented the connection. (unexpected) */ - getConfigurable() generates (IConfigurable configurable); + disconnect() generates (Status status); + }; diff --git a/media/c2/1.0/types.hal b/media/c2/1.0/types.hal index 13269d2ecb..c06b415024 100644 --- a/media/c2/1.0/types.hal +++ b/media/c2/1.0/types.hal @@ -18,278 +18,220 @@ package android.hardware.media.c2@1.0; import android.hardware.media.bufferpool@1.0::BufferStatusMessage; -/** - * Common return values for Codec2 operations. - */ enum Status : int32_t { - /** Operation completed successfully. */ + /** operation completed successfully */ OK = 0, // bad input - /** Argument has invalid value (user error). */ + /** argument has invalid value (user error) */ BAD_VALUE = -22, - /** Argument uses invalid index (user error). */ + /** argument uses invalid index (user error) */ BAD_INDEX = -75, - /** Argument/Index is valid but not possible. */ + /** argument/index is valid but not possible */ CANNOT_DO = -2147483646, // bad sequencing of events - /** Object already exists. */ + /** object already exists */ DUPLICATE = -17, - /** Object not found. */ + /** object not found */ NOT_FOUND = -2, - /** Operation is not permitted in the current state. */ + /** operation is not permitted in the current state */ BAD_STATE = -38, - /** Operation would block but blocking is not permitted. */ + /** operation would block but blocking is not permitted */ BLOCKING = -9930, // bad environment - /** Not enough memory to complete operation. */ + /** not enough memory to complete operation */ NO_MEMORY = -12, - /** Missing permission to complete operation. */ + /** missing permission to complete operation */ REFUSED = -1, - /** Operation did not complete within timeout. */ + /** operation did not complete within timeout */ TIMED_OUT = -110, // missing functionality - /** Operation is not implemented/supported (optional only). */ + /** operation is not implemented/supported (optional only) */ OMITTED = -74, // unknown fatal - /** Some unexpected error prevented the operation. */ + /** some unexpected error prevented the operation */ CORRUPTED = -2147483648, // uninitialized - /** Status has not been initialized. */ + /** 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. + * Codec 2.0 parameter index */ typedef uint32_t ParamIndex; /** - * Flattened representation of C2Param objects. + * Codec 2.0 parameter structure * - * 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. + * The description of a Params is provided by supplying a ParamIndex to + * IComponentStore::getStructDescriptors(). */ typedef vec 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 uniquely specifying a field in an arbitrary parameter structure. */ struct FieldId { - /** Offset of the field in bytes. */ + /** Offset of the field in bytes */ uint32_t offset; - /** Size of the field in bytes. */ + /** Size of the field in bytes */ uint32_t size; }; /** - * Reference to a field in a C2Param structure. + * Struct representing a location of a field in a parameter with a given index. */ struct ParamField { - /** Index of the C2Param structure. */ + /** Index of the parameter */ ParamIndex index; - /** Identifier of the field inside the C2Param structure. */ + /** Field identifier */ FieldId fieldId; }; /** - * Usage description of a C2Param structure. - * - * @ref ParamDescriptor is returned by IConfigurable::querySupportedParams(). + * Struct describing basic properties of a parameter with a given index. */ struct ParamDescriptor { - /** - * Index of the C2Param structure being described. - */ + /** Parameter index */ ParamIndex index; enum Attrib : uint32_t { /** - * The parameter is required to be specified. + * Parameter is required to be specified. */ REQUIRED = 1u << 0, /** - * The parameter retains its value. + * Parameter retains its value. */ PERSISTENT = 1u << 1, /** - * The parameter is strict. + * Parameter is strict. */ STRICT = 1u << 2, /** - * The parameter is publicly read-only. + * Parameter is publicly read-only. */ READ_ONLY = 1u << 3, /** - * The parameter must not be visible to clients. + * Parameter must not be visible to clients. */ HIDDEN = 1u << 4, /** - * The parameter must not be used by framework (other than testing). + * Parameter must not be used by framework (other than testing). */ INTERNAL = 1u << 5, /** - * The parameter is publicly constant (hence read-only). + * Parameter is publicly constant (hence read-only). */ CONST = 1u << 6, }; + /** Parameter attributes */ bitfield attrib; - /** - * Name of the structure. This must be unique for each structure. - */ + /** Parameter name */ string name; - /** - * Indices of other C2Param structures that this C2Param structure depends - * on. - */ + /** index of other parameters that this parameter depends on */ vec dependencies; }; -// Generic way to describe supported numeric values for Codec2 interfaces. +// Generic way to describe supported numeric values for Codec 2.0 interfaces. /** - * An untyped value that can fit in 64 bits, the type of which is communicated - * via a separate channel (@ref FieldSupportedValues.type). + * An untyped value that can fit on 64 bits - the type of which is communicated + * via a separate channel (FieldType). */ typedef uint64_t PrimitiveValue; /* - * Description of supported values for a field. + * Generic supported values for a field. * - * This can be a continuous range or a discrete set of values. + * 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 { - /** - * Used if #type is `RANGE`. - * - * 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 #Range 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 Range { - /** - * 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; }; enum Type : int32_t { /** No supported values */ - EMPTY = 0, - /** Numeric range, described in a #Range structure */ + 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. + * 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. + */ /** - * When #type is #Type.RANGE, #range shall specify the range of possible - * values. + * If #type = RANGE, #range will specify the range of possible values. * - * The intended type of members of #range shall be clear in the context - * where `FieldSupportedValues` is used. + * The intended type of members of #range will be clear in the context where + * FieldSupportedValues is used. */ Range range; /** - * When #type is #Type.VALUES or #Type.FLAGS, #value shall list supported - * values/flags. + * If #type is `VALUES` or `FLAGS`, #value will list supported values. * - * The intended type of components of #value shall be clear in the context - * where `FieldSupportedValues` is used. + * The intended type of components of #value will be clear in the context + * where FieldSupportedValues is used. */ vec values; }; /** - * Supported values for a field. + * 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 { - /** - * Reference to a field or a C2Param structure. - */ + /** the field or parameter */ ParamField paramOrField; /** - * Optional supported values for the field if #paramOrField specifies an + * 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 @@ -299,18 +241,18 @@ struct ParamFieldValues { }; /** - * Description of a field inside a C2Param structure. + * Field descriptor. */ struct FieldDescriptor { - /** Location of the field in the C2Param structure */ + /** Field id */ FieldId fieldId; /** - * Possible types of the field. + * Possible types of a field. */ enum Type : uint32_t { - NO_INIT = 0, + NO_INIT, INT32, UINT32, CNTR32, @@ -319,227 +261,186 @@ struct FieldDescriptor { CNTR64, FLOAT, /** - * Fixed-size string (POD). + * 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. + * blobs have no sub-elements and can be thought of as byte arrays. + * However, bytes cannot be individually addressed by clients. */ BLOB, /** - * The field is a structure that may contain other fields. + * Structs. Marked with this flag in addition to their coreIndex. */ - STRUCT = 0x20000, + STRUCT_FLAG = 0x20000, }; /** * Type of the field. */ bitfield type; - /** - * If #type is #Type.STRUCT, #structIndex is the C2Param structure index; - * otherwise, #structIndex is not used. + /** 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. */ - 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. - */ + /** Name of the field */ string name; - - /** - * Named value type. This is used for defining an enum value for a numeric - * type. - */ + /** Named value 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. - */ + /** Named values for the field */ vec namedValues; }; /** - * Description of a C2Param structure. It consists of an index and a list of - * `FieldDescriptor`s. + * Struct descriptor. */ struct StructDescriptor { - /** - * Index of the structure. - */ + /** Struct type */ 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. - */ + /** Field descriptors for each field */ vec fields; }; /** - * Information describing the reason the parameter settings may fail, or may be - * overridden. + * Information describing the reason a parameter settings may fail, or + * may be overriden. */ struct SettingResult { - /** Failure code */ + /** 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 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). - */ + /** Parameter 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.) + * Parameter is out of range due to other settings. (This failure mode + * can only be used for strict 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. - */ + * 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 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). + * 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. Values must only be set for - * `CONFLICT`, `UNSUPPORTED` or `INFO_CONFLICT` failure code. + * Conflicting parameters or fields with + * (optional) suggested values for any conflicting fields to avoid the conflict. */ vec 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. + * 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. + * Timestamp in microseconds - can wrap around. */ uint64_t timestampUs; /** - * Frame index. + * Frame index - can wrap around. */ uint64_t frameIndex; /** - * Component specific frame ordinal. + * Component specific frame ordinal - can wrap around. */ 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. + * 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. */ -safe_union BaseBlock { +struct BaseBlock { + enum Type : int32_t { + NATIVE, + POOLED, + }; /** - * #nativeBlock is the opaque representation of a buffer. + * There are two types of blocks: NATIVE and POOLED. + */ + Type type; + + /** + * A "NATIVE" block is represented by a native handle. */ handle nativeBlock; - /** - * #pooledBlock is a reference to a buffer handled by a BufferPool. + + /* + * A "POOLED" block is represented by `BufferStatusMessage`. */ 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`. + * 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 a `BaseBlock` within a `WorkBundle`. This is an index into - * #WorkBundle.baseBlocks. + * 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 this `Block`. + * Metadata associated with the block. */ Params meta; /** - * Fence for synchronizing `Block` access. + * 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. + * Type of buffers processed by a component. */ struct Buffer { /** @@ -553,37 +454,23 @@ struct Buffer { }; /** - * An extension of @ref Buffer that also contains a C2Param structure index. - * - * This is a part of @ref FrameData. + * An extension of Buffer that also contains an index. */ 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. + * 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 shall be generated when processing + * 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. */ @@ -595,183 +482,92 @@ struct FrameData { 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 + * 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 + * \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. + * Frame flags. */ bitfield flags; /** - * @ref WorkOrdinal of the frame. + * Ordinal of the frame. */ WorkOrdinal ordinal; /** - * List of frame buffers. + * Frame buffers. */ vec buffers; /** - * List of configuration updates. + * Params determining a configuration update. */ Params configUpdate; /** - * List of info buffers. + * Info buffers. */ vec 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 for */ struct Worklet { /** - * Component id. (Input) - * - * This is used only when tunneling is enabled. - * - * When used, this must match the return value from IConfigurable::getId(). + * List of Params describing tunings. */ - uint32_t componentId; + vec tunings; /** - * List of C2Param objects describing tunings to be applied before - * processing this `Worklet`. (Input) - */ - Params tunings; - - /** - * Flag determining whether this `Worklet` has output or not. - */ - bool hasOutput; - - /** - * List of failures. (Output) + * List of failures. */ vec failures; /** - * Output frame data. (Output) + * Output frame data. */ FrameData output; + + /* Note: Component id is not necessary as tunneling is not supported. */ }; /** - * 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. + * This structure holds information about a single work item. It must be passed + * by the client to the component. */ struct Work { /** - * Additional work chain info not part of this work. - */ - Params chainInfo; - - /** - * @ref FrameData for the input. + * FrameData for the input. Indices of Blocks inside #input refer to + * BaseBlocks in the member `blocks` of the containing `WorkBundle`. */ 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`. + * Worklet. Indices of Blocks inside `worklet.output` refer to + * BaseBlocks in the member `blocks` of the containing `WorkBundle`. */ - vec worklets; - + Worklet worklet; /** - * 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. + * Whether the worklet was processed or not. */ + bool workletProcessed; 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. + * This structure holds a list of Work objects and a list of BaseBlocks. */ struct WorkBundle { /** @@ -785,48 +581,27 @@ struct WorkBundle { }; /** - * Query information for supported values of a field. This is used as input to - * IConfigurable::querySupportedValues(). + * This structure describes a query for supported values of a field. This is + * used as input to IConfigurable::queryFieldSupportedValues(). */ struct FieldSupportedValuesQuery { - /** - * Identity of the field to query. - */ - ParamField field; - enum Type : uint32_t { - /** Query all possible values regardless of other settings. */ + /** Query all possible values regardless of other settings */ POSSIBLE, - /** Query currently possible values given dependent settings. */ + /** Query currently possible values given dependent settings */ CURRENT, }; - /** - * Type of the query. See #Type for more information. - */ + + ParamField field; Type type; }; /** * This structure is used to hold the result from - * IConfigurable::querySupportedValues(). + * IConfigurable::queryFieldSupportedValues(). */ 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; };