Effect AIDL: add IEffect.reopen to update the effect instances data FMQ am: 5b15e005a9 am: 2243d42834

Original change: https://android-review.googlesource.com/c/platform/hardware/interfaces/+/2897678

Change-Id: I58116d279cc4550f606e7fb97e923e31dcf3d330
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>

audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IEffect.aidl

@@ -41,6 +41,7 @@ interface IEffect {
   android.hardware.audio.effect.State getState();
   void setParameter(in android.hardware.audio.effect.Parameter param);
   android.hardware.audio.effect.Parameter getParameter(in android.hardware.audio.effect.Parameter.Id paramId);
+  android.hardware.audio.effect.IEffect.OpenEffectReturn reopen();
   @FixedSize @VintfStability
   parcelable Status {
     int status;

audio/aidl/android/hardware/audio/effect/IEffect.aidl

@@ -54,7 +54,16 @@ interface IEffect {
     }
 
     /**
-     * Return data structure of IEffect.open() interface.
+     * Return data structure of the IEffect.open() and IEffect.reopen() method.
+     *
+     * Contains Fast Message Queues (FMQs) for effect processing status and input/output data.
+     * The status FMQ remains valid and unchanged after opening, while input/output data FMQs can be
+     * modified with changes in input/output AudioConfig. If reallocation of data FMQ is necessary,
+     * the effect instance must release the existing data FMQs to signal the need to the audio
+     * framework.
+     * When the audio framework encounters a valid status FMQ and invalid input/output data FMQs,
+     * it must invoke the IEffect.reopen() method to request the effect instance to reallocate
+     * the FMQ and return to the audio framework.
      */
     @VintfStability
     parcelable OpenEffectReturn {
@@ -97,7 +106,7 @@ interface IEffect {
      * client responsibility to make sure all parameter/buffer is correct if client wants to reopen
      * a closed instance.
      *
-     * Effect instance close interface should always succeed unless:
+     * Effect instance close method should always succeed unless:
      * 1. The effect instance is not in a proper state to be closed, for example it's still in
      * State::PROCESSING state.
      * 2. There is system/hardware related failure when close.
@@ -154,8 +163,8 @@ interface IEffect {
     /**
      * Get a parameter from the effect instance with parameter ID.
      *
-     * This interface must return the current parameter of the effect instance, if no parameter
-     * has been set by client yet, the default value must be returned.
+     * This method must return the current parameter of the effect instance, if no parameter has
+     * been set by client yet, the default value must be returned.
      *
      * Must be available for the effect instance after open().
      *
@@ -165,4 +174,24 @@ interface IEffect {
      * @throws EX_ILLEGAL_ARGUMENT if the effect instance receive unsupported parameter tag.
      */
     Parameter getParameter(in Parameter.Id paramId);
+
+    /**
+     * Reopen the effect instance, keeping all previous parameters unchanged, and reallocate only
+     * the Fast Message Queues (FMQs) allocated during the open time as needed.
+     *
+     * When the audio framework encounters a valid status FMQ and invalid data FMQ(s), it calls
+     * this method to reopen the effect and request the latest data FMQ.
+     * Upon receiving this call, if the effect instance's data FMQ(s) is invalid, it must reallocate
+     * the necessary data FMQ(s) and return them to the audio framework. All previous parameters and
+     * states keep unchanged.
+     * Once the audio framework successfully completes the call, it must validate the returned FMQs,
+     * deprecate all old FMQs, and exclusively use the FMQs returned from this method.
+     *
+     * @return The reallocated data FMQ and the original status FMQ.
+     *
+     * @throws EX_ILLEGAL_STATE if the effect instance is not in a proper state  to reallocate FMQ.
+     * This may occur if the effect instance has already been closed or if there is no need to
+     * update any data FMQ.
+     */
+    OpenEffectReturn reopen();
 }

audio/aidl/android/hardware/audio/effect/state.gv

@@ -31,6 +31,8 @@ digraph effect_state_machine {
     IDLE -> INIT[label = "IEffect.close()"];
 
     INIT -> INIT[label = "IEffect.getState\nIEffect.getDescriptor"];
-    IDLE -> IDLE[label = "IEffect.getParameter\nIEffect.setParameter\nIEffect.getDescriptor\nIEffect.command(RESET)"];
-    PROCESSING -> PROCESSING[label = "IEffect.getParameter\nIEffect.setParameter\nIEffect.getDescriptor"];
+    IDLE -> IDLE[label = "IEffect.getParameter\nIEffect.setParameter\nIEffect.getDescriptor\nIEffect.command(RESET)\nIEffect.reopen"];
+    PROCESSING
+            -> PROCESSING
+                    [label = "IEffect.getParameter\nIEffect.setParameter\nIEffect.getDescriptor\nIEffect.reopen"];
 }

audio/aidl/default/EffectImpl.cpp

@@ -60,6 +60,16 @@ ndk::ScopedAStatus EffectImpl::open(const Parameter::Common& common,
     return ndk::ScopedAStatus::ok();
 }
 
+ndk::ScopedAStatus EffectImpl::reopen(OpenEffectReturn* ret) {
+    RETURN_IF(mState == State::INIT, EX_ILLEGAL_STATE, "alreadyClosed");
+
+    // TODO: b/302036943 add reopen implementation
+    auto context = getContext();
+    RETURN_IF(!context, EX_NULL_POINTER, "nullContext");
+    context->dupeFmq(ret);
+    return ndk::ScopedAStatus::ok();
+}
+
 ndk::ScopedAStatus EffectImpl::close() {
     RETURN_OK_IF(mState == State::INIT);
     RETURN_IF(mState == State::PROCESSING, EX_ILLEGAL_STATE, "closeAtProcessing");

audio/aidl/default/include/effect-impl/EffectImpl.h

@@ -43,6 +43,7 @@ class EffectImpl : public BnEffect, public EffectThread {
                                     OpenEffectReturn* ret) override;
     virtual ndk::ScopedAStatus close() override;
     virtual ndk::ScopedAStatus command(CommandId id) override;
+    virtual ndk::ScopedAStatus reopen(OpenEffectReturn* ret) override;
 
     virtual ndk::ScopedAStatus getState(State* state) override;
     virtual ndk::ScopedAStatus setParameter(const Parameter& param) override;