Copy from the old version of Codec2 HAL
This CL makes transitioning of Codec2 HAL from private to public
smoother. The CL will be reverted later.
Test: Builds
Bug: 112362730
Change-Id: Id0e199112e968e35ed3b27413baae810f1ecb2df
diff --git a/media/c2/1.0/IComponent.hal b/media/c2/1.0/IComponent.hal
index 7fd551f..deb9255 100644
--- a/media/c2/1.0/IComponent.hal
+++ b/media/c2/1.0/IComponent.hal
@@ -22,19 +22,13 @@
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 @@
*
* 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 @@
* 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 @@
);
/**
- * 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 @@
/**
* 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 @@
*
* 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 @@
*
* 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 @@
*
* 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 @@
*
* 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 a007d02..d4b30b1 100644
--- a/media/c2/1.0/IComponentInterface.hal
+++ b/media/c2/1.0/IComponentInterface.hal
@@ -19,20 +19,21 @@
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 70d5fb2..eb71ecb 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<SettingResult> 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<RenderedFrame> 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<InputBuffer> inputBuffers);
};
diff --git a/media/c2/1.0/IComponentStore.hal b/media/c2/1.0/IComponentStore.hal
index a027afe..d2474cc 100644
--- a/media/c2/1.0/IComponentStore.hal
+++ b/media/c2/1.0/IComponentStore.hal
@@ -23,33 +23,27 @@
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 @@
/**
* 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 @@
*/
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<string> aliases;
@@ -136,51 +142,36 @@
/**
* 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<ComponentTraits> traits
- );
+ listComponents() generates (vec<ComponentTraits> 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<ParamIndex> indices
@@ -190,35 +181,33 @@
);
/**
- * 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 31dc4d3..cd4dd10 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<ParamIndex> indices,
@@ -99,60 +64,31 @@
);
/**
- * 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 @@
// =========================================================================
/**
- * 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 @@
/**
* 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<FieldSupportedValuesQuery> inFields,
diff --git a/media/c2/1.0/IInputSurface.hal b/media/c2/1.0/IInputSurface.hal
index 25c6c8e..c083a21 100644
--- a/media/c2/1.0/IInputSurface.hal
+++ b/media/c2/1.0/IInputSurface.hal
@@ -19,33 +19,43 @@
import android.hardware.graphics.bufferqueue@1.0::IGraphicBufferProducer;
import IConfigurable;
+import IComponent;
+import IInputSurfaceConnection;
/**
- * Input surface for a Codec2 component.
- *
- * An <em>input surface</em> 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 efd9c6e..500091d 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 13269d2..c06b415 100644
--- a/media/c2/1.0/types.hal
+++ b/media/c2/1.0/types.hal
@@ -18,278 +18,220 @@
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<uint8_t> Params;
/**
- * Identifying information of a field relative to a known C2Param structure.
- *
- * Within a given C2Param structure, each field is uniquely identified by @ref
- * FieldId.
+ * Struct 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> 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<ParamIndex> 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<PrimitiveValue> 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 @@
};
/**
- * 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 @@
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> 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<NamedValue> 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<FieldDescriptor> 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<ParamFieldValues> conflicts;
};
/**
- * Ordering information of @ref FrameData objects. Each member is used for
- * comparing urgency: a smaller difference from a reference value indicates that
- * the associated Work object is more urgent. The reference value for each
- * member is initialized the first time it is communicated between the client
- * and the codec, and it may be updated to later values that are communicated.
- *
- * Each member of `WorkOrdinal` is stored as an unsigned integer, but the actual
- * order it represents is derived by subtracting the reference value, then
- * interpreting the result as a signed number with the same storage size (using
- * two's complement).
- *
- * @note `WorkOrdinal` is the HIDL counterpart of `C2WorkOrdinalStruct` in the
- * Codec 2.0 standard.
+ * 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 @@
};
/**
- * 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 @@
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> flags;
/**
- * @ref WorkOrdinal of the frame.
+ * Ordinal of the frame.
*/
WorkOrdinal ordinal;
/**
- * List of frame buffers.
+ * Frame buffers.
*/
vec<Buffer> buffers;
/**
- * List of configuration updates.
+ * Params determining a configuration update.
*/
Params configUpdate;
/**
- * List of info buffers.
+ * Info buffers.
*/
vec<InfoBuffer> infoBuffers;
};
/**
- * In/out structure containing some instructions for and results from output
- * processing.
- *
- * This is a part of @ref Work. One `Worklet` corresponds to one output
- * @ref FrameData. The client must construct an original `Worklet` object inside
- * a @ref Work object for each expected output before calling
- * IComponent::queue().
+ * Struct 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<Params> 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<SettingResult> 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<Worklet> 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`.
+ * Whether the worklet was processed or not.
*/
- 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.
- */
+ 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 @@
};
/**
- * 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;
};