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/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,