1 /*
2  * Copyright (C) 2023 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #pragma once
18 
19 #include "IAfPatchPanel.h"  // full class Patch definition needed
20 
21 #include <android/media/AudioVibratorInfo.h>
22 #include <android/media/BnEffect.h>
23 #include <android/media/BnEffectClient.h>
24 #include <audio_utils/mutex.h>
25 #include <media/AudioCommonTypes.h>  // product_strategy_t
26 #include <media/AudioDeviceTypeAddr.h>
27 #include <media/audiohal/EffectHalInterface.h>
28 #include <utils/RefBase.h>
29 #include <vibrator/ExternalVibration.h>
30 
31 namespace android {
32 
33 class Client;
34 class DeviceEffectManagerCallback;
35 
36 class IAfDeviceEffectProxy;
37 class IAfEffectBase;
38 class IAfEffectChain;
39 class IAfEffectHandle;
40 class IAfEffectModule;
41 class IAfThreadBase;
42 
43 // Interface implemented by the EffectModule parent or owner (e.g an EffectChain) to abstract
44 // interactions between the EffectModule and the reset of the audio framework.
45 class EffectCallbackInterface : public RefBase {
46 public:
47     // Trivial methods usually implemented with help from ThreadBase
48     virtual audio_io_handle_t io() const = 0;
49     virtual bool isOutput() const = 0;
50     virtual bool isOffload() const = 0;
51     virtual bool isOffloadOrDirect() const = 0;
52     virtual bool isOffloadOrMmap() const = 0;
53     virtual bool isSpatializer() const = 0;
54     virtual uint32_t sampleRate() const = 0;
55     virtual audio_channel_mask_t inChannelMask(int id) const = 0;
56     virtual uint32_t inChannelCount(int id) const = 0;
57     virtual audio_channel_mask_t outChannelMask() const = 0;
58     virtual uint32_t outChannelCount() const = 0;
59     virtual audio_channel_mask_t hapticChannelMask() const = 0;
60     virtual size_t frameCount() const = 0;
61 
62     // Non trivial methods usually implemented with help from ThreadBase:
63     // pay attention to mutex locking order
latency()64     virtual uint32_t latency() const { return 0; }
65     virtual status_t addEffectToHal(const sp<EffectHalInterface>& effect) = 0;
66     virtual status_t removeEffectFromHal(const sp<EffectHalInterface>& effect) = 0;
67     virtual void setVolumeForOutput(float left, float right) const = 0;
68     virtual bool disconnectEffectHandle(IAfEffectHandle *handle, bool unpinIfLast) = 0;
69     virtual void checkSuspendOnEffectEnabled(
70             const sp<IAfEffectBase>& effect, bool enabled, bool threadLocked) = 0;
71     virtual void onEffectEnable(const sp<IAfEffectBase>& effect) = 0;
72     virtual void onEffectDisable(const sp<IAfEffectBase>& effect) = 0;
73 
74     // Methods usually implemented with help from AudioFlinger: pay attention to mutex locking order
75     virtual status_t createEffectHal(const effect_uuid_t *pEffectUuid,
76             int32_t sessionId, int32_t deviceId, sp<EffectHalInterface> *effect) = 0;
77     virtual status_t allocateHalBuffer(size_t size, sp<EffectBufferHalInterface>* buffer) = 0;
78     virtual bool updateOrphanEffectChains(const sp<IAfEffectBase>& effect) = 0;
79 
80     // Methods usually implemented with help from EffectChain: pay attention to mutex locking order
81     virtual product_strategy_t strategy() const = 0;
82     virtual int32_t activeTrackCnt() const = 0;
83     virtual void resetVolume_l() REQUIRES(audio_utils::EffectChain_Mutex) = 0;
84     virtual wp<IAfEffectChain> chain() const = 0;
85     virtual bool isAudioPolicyReady() const = 0;
86 };
87 
88 class IAfEffectBase : public virtual RefBase {
89     friend class EffectChain;
90     friend class EffectHandle;
91 
92 public:
93     enum effect_state {
94         IDLE,
95         RESTART,
96         STARTING,
97         ACTIVE,
98         STOPPING,
99         STOPPED,
100         DESTROYED
101     };
102     virtual int id() const = 0;
103     virtual effect_state state() const = 0;
104     virtual audio_session_t sessionId() const = 0;
105     virtual const effect_descriptor_t& desc() const = 0;
106     virtual bool isOffloadable() const = 0;
107     virtual bool isImplementationSoftware() const = 0;
108     virtual bool isProcessImplemented() const = 0;
109     virtual bool isVolumeControl() const REQUIRES(audio_utils::EffectChain_Mutex) = 0;
110     virtual bool isVolumeMonitor() const = 0;
111     virtual bool isEnabled() const = 0;
112     virtual bool isPinned() const = 0;
113     virtual void unPin() = 0;
114     virtual status_t updatePolicyState() EXCLUDES_EffectBase_Mutex = 0;
115     virtual bool purgeHandles() EXCLUDES_EffectBase_Mutex = 0;
116     virtual void checkSuspendOnEffectEnabled(bool enabled, bool threadLocked) = 0;
117 
118     // mCallback is atomic so this can be lock-free.
119     virtual void setCallback(const sp<EffectCallbackInterface>& callback) = 0;
120     virtual sp<EffectCallbackInterface> getCallback() const = 0;
121 
122     virtual status_t addHandle(IAfEffectHandle* handle) EXCLUDES_EffectBase_Mutex = 0;
123     virtual ssize_t removeHandle(IAfEffectHandle* handle) EXCLUDES_EffectBase_Mutex = 0;
124 
125     virtual sp<IAfEffectModule> asEffectModule() = 0;
126     virtual sp<IAfDeviceEffectProxy> asDeviceEffectProxy() = 0;
127 
128     virtual status_t command(int32_t cmdCode, const std::vector<uint8_t>& cmdData,
129                              int32_t maxReplySize, std::vector<uint8_t>* reply)
130             EXCLUDES(audio_utils::EffectBase_Mutex) = 0;
131 
132     virtual void dump(int fd, const Vector<String16>& args) const = 0;
133 
134 private:
135     virtual status_t setEnabled(bool enabled, bool fromHandle) EXCLUDES_EffectBase_Mutex = 0;
136     virtual status_t setEnabled_l(bool enabled) REQUIRES(audio_utils::EffectBase_Mutex) = 0;
137     virtual void setSuspended(bool suspended) EXCLUDES_EffectBase_Mutex = 0;
138     virtual bool suspended() const EXCLUDES_EffectBase_Mutex = 0;
139 
140     virtual ssize_t disconnectHandle(IAfEffectHandle* handle,
141                                      bool unpinIfLast) EXCLUDES_EffectBase_Mutex = 0;
142     virtual ssize_t removeHandle_l(IAfEffectHandle* handle)
143             REQUIRES(audio_utils::EffectBase_Mutex) = 0;
144     virtual IAfEffectHandle* controlHandle_l() REQUIRES(audio_utils::EffectBase_Mutex) = 0;
145 
146     virtual audio_utils::mutex& mutex() const
147             RETURN_CAPABILITY(android::audio_utils::EffectBase_Mutex) = 0;
148 };
149 
150 class IAfEffectModule : public virtual IAfEffectBase {
151     friend class DeviceEffectProxy;
152     friend class EffectChain;
153 
154 public:
155     static sp<IAfEffectModule> create(
156             const sp<EffectCallbackInterface>& callabck,
157             effect_descriptor_t *desc,
158             int id,
159             audio_session_t sessionId,
160             bool pinned,
161             audio_port_handle_t deviceId);
162 
163     virtual int16_t *inBuffer() const = 0;
164     virtual status_t setDevices(const AudioDeviceTypeAddrVector &devices) = 0;
165     virtual status_t setInputDevice(const AudioDeviceTypeAddr &device) = 0;
166     virtual status_t setVolume_l(uint32_t* left, uint32_t* right,
167                                  bool controller /* effect controlling chain volume */,
168                                  bool force = false) REQUIRES(audio_utils::EffectChain_Mutex) = 0;
169     virtual status_t setOffloaded_l(bool offloaded, audio_io_handle_t io) = 0;
170     virtual bool isOffloaded_l() const = 0;
171 
172     virtual status_t setAudioSource(audio_source_t source) = 0;
173     virtual status_t setMode(audio_mode_t mode) = 0;
174 
175     virtual status_t start_l() = 0;
176     virtual status_t getConfigs_l(audio_config_base_t* inputCfg, audio_config_base_t* outputCfg,
177                                   bool* isOutput) const
178             REQUIRES(audio_utils::EffectHandle_Mutex) EXCLUDES_EffectBase_Mutex = 0;
179 
180     static bool isHapticGenerator(const effect_uuid_t* type);
181     virtual bool isHapticGenerator() const = 0;
182     static bool isSpatializer(const effect_uuid_t* type);
183     virtual bool isSpatializer() const = 0;
184 
185     virtual status_t setHapticScale_l(int id, os::HapticScale hapticScale)
186             REQUIRES(audio_utils::EffectChain_Mutex) EXCLUDES_EffectBase_Mutex = 0;
187     virtual status_t setVibratorInfo_l(const media::AudioVibratorInfo& vibratorInfo)
188             REQUIRES(audio_utils::EffectChain_Mutex) EXCLUDES_EffectBase_Mutex = 0;
189     virtual status_t sendMetadata_ll(const std::vector<playback_track_metadata_v7_t>& metadata)
190             REQUIRES(audio_utils::ThreadBase_Mutex,
191                      audio_utils::EffectChain_Mutex) EXCLUDES_EffectBase_Mutex = 0;
192     // return true if there was a state change from STARTING to ACTIVE, or STOPPED to IDLE, effect
193     // chain will do a volume reset in these two cases
194     virtual bool updateState_l()
195             REQUIRES(audio_utils::EffectChain_Mutex) EXCLUDES_EffectBase_Mutex = 0;
196 
197 private:
198     virtual void process() = 0;
199     virtual void reset_l() REQUIRES(audio_utils::EffectChain_Mutex) = 0;
200     virtual status_t configure_l() REQUIRES(audio_utils::EffectChain_Mutex) = 0;
201     virtual status_t init_l()
202             REQUIRES(audio_utils::EffectChain_Mutex) EXCLUDES_EffectBase_Mutex = 0;
203     virtual uint32_t status() const = 0;
204     virtual bool isProcessEnabled() const = 0;
205     virtual bool isOffloadedOrDirect_l() const REQUIRES(audio_utils::EffectChain_Mutex) = 0;
206     virtual bool isVolumeControlEnabled_l() const REQUIRES(audio_utils::EffectChain_Mutex) = 0;
207 
208     virtual void setInBuffer(const sp<EffectBufferHalInterface>& buffer) = 0;
209     virtual void setOutBuffer(const sp<EffectBufferHalInterface>& buffer) = 0;
210     virtual int16_t *outBuffer() const = 0;
211 
212     // Updates the access mode if it is out of date.  May issue a new effect configure.
213     virtual void updateAccessMode_l() = 0;
214 
215     virtual status_t stop_l() = 0;
216     virtual void addEffectToHal_l() = 0;
217     virtual void release_l(const std::string& from) = 0;
218 };
219 
220 class IAfEffectChain : public RefBase {
221     // Most of these methods are accessed from AudioFlinger::Thread
222 public:
223     static sp<IAfEffectChain> create(
224             const sp<IAfThreadBase>& thread,
225             audio_session_t sessionId,
226             const sp<IAfThreadCallback>& afThreadCallback);
227 
228     // special key used for an entry in mSuspendedEffects keyed vector
229     // corresponding to a suspend all request.
230     static constexpr int kKeyForSuspendAll = 0;
231 
232     // minimum duration during which we force calling effect process when last track on
233     // a session is stopped or removed to allow effect tail to be rendered
234     static constexpr int kProcessTailDurationMs = 1000;
235 
236     virtual void process_l() REQUIRES(audio_utils::EffectChain_Mutex) = 0;
237 
238     virtual audio_utils::mutex& mutex() const RETURN_CAPABILITY(audio_utils::EffectChain_Mutex) = 0;
239 
240     virtual status_t createEffect(sp<IAfEffectModule>& effect, effect_descriptor_t* desc, int id,
241                                     audio_session_t sessionId, bool pinned)
242             EXCLUDES_EffectChain_Mutex = 0;
243 
244     virtual status_t addEffect(const sp<IAfEffectModule>& handle)
245             EXCLUDES_EffectChain_Mutex = 0;
246     virtual status_t addEffect_l(const sp<IAfEffectModule>& handle)
247             REQUIRES(audio_utils::EffectChain_Mutex) = 0;
248     virtual size_t removeEffect(const sp<IAfEffectModule>& handle,
249                                   bool release = false) EXCLUDES_EffectChain_Mutex = 0;
250 
251     virtual audio_session_t sessionId() const = 0;
252     virtual void setSessionId(audio_session_t sessionId) = 0;
253 
254     virtual sp<IAfEffectModule> getEffectFromDesc(effect_descriptor_t* descriptor) const
255             EXCLUDES_EffectChain_Mutex = 0;
256     virtual sp<IAfEffectModule> getEffectFromId_l(int id) const
257             REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0;
258     virtual sp<IAfEffectModule> getEffectFromType_l(const effect_uuid_t* type) const
259             REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0;
260     virtual std::vector<int> getEffectIds_l() const = 0;
261     virtual bool setVolume(uint32_t* left, uint32_t* right,
262                            bool force = false) EXCLUDES_EffectChain_Mutex = 0;
263     virtual void resetVolume_l() REQUIRES(audio_utils::EffectChain_Mutex) = 0;
264     virtual void setDevices_l(const AudioDeviceTypeAddrVector& devices)
265             REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0;
266     virtual void setInputDevice_l(const AudioDeviceTypeAddr& device)
267             REQUIRES(audio_utils::ThreadBase_Mutex)  EXCLUDES_EffectChain_Mutex = 0;
268     virtual void setMode_l(audio_mode_t mode)
269             REQUIRES(audio_utils::ThreadBase_Mutex)  EXCLUDES_EffectChain_Mutex = 0;
270     virtual void setAudioSource_l(audio_source_t source)
271             REQUIRES(audio_utils::ThreadBase_Mutex) = 0;
272 
273     virtual void setInBuffer(const sp<EffectBufferHalInterface>& buffer) = 0;
274     virtual float *inBuffer() const = 0;
275     virtual void setOutBuffer(const sp<EffectBufferHalInterface>& buffer) = 0;
276     virtual float *outBuffer() const = 0;
277 
278     virtual void incTrackCnt() = 0;
279     virtual void decTrackCnt() = 0;
280     virtual int32_t trackCnt() const = 0;
281 
282     virtual void incActiveTrackCnt() = 0;
283     virtual void decActiveTrackCnt() = 0;
284     virtual int32_t activeTrackCnt() const = 0;
285 
286     virtual product_strategy_t strategy() const = 0;
287     virtual void setStrategy(product_strategy_t strategy) = 0;
288 
289     // suspend or restore effects of the specified type. The number of suspend requests is counted
290     // and restore occurs once all suspend requests are cancelled.
291     virtual void setEffectSuspended_l(const effect_uuid_t* type, bool suspend) = 0;
292     // suspend all eligible effects
293     virtual void setEffectSuspendedAll_l(bool suspend) = 0;
294     // check if effects should be suspended or restored when a given effect is enable or disabled
295     virtual void checkSuspendOnEffectEnabled_l(const sp<IAfEffectModule>& effect, bool enabled)
296             REQUIRES(audio_utils::ThreadBase_Mutex) REQUIRES(audio_utils::ThreadBase_Mutex) = 0;
297 
298     virtual void clearInputBuffer() EXCLUDES_EffectChain_Mutex = 0;
299 
300     // At least one non offloadable effect in the chain is enabled
301     virtual bool isNonOffloadableEnabled() const EXCLUDES_EffectChain_Mutex = 0;
302     virtual bool isNonOffloadableEnabled_l() const REQUIRES(audio_utils::EffectChain_Mutex) = 0;
303 
304     virtual void syncHalEffectsState_l()
305             REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0;
306 
307     // flags is an ORed set of audio_output_flags_t which is updated on return.
308     virtual void checkOutputFlagCompatibility(audio_output_flags_t *flags) const = 0;
309 
310     // flags is an ORed set of audio_input_flags_t which is updated on return.
311     virtual void checkInputFlagCompatibility(audio_input_flags_t *flags) const = 0;
312 
313     // Is this EffectChain compatible with the RAW audio flag.
314     virtual bool isRawCompatible() const = 0;
315 
316     // Is this EffectChain compatible with the FAST audio flag.
317     virtual bool isFastCompatible() const = 0;
318 
319     // Is this EffectChain compatible with the bit-perfect audio flag.
320     virtual bool isBitPerfectCompatible() const = 0;
321 
322     // isCompatibleWithThread_l() must be called with thread->mLock held
323     virtual bool isCompatibleWithThread_l(const sp<IAfThreadBase>& thread) const
324             REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0;
325 
326     virtual bool containsHapticGeneratingEffect()
327             EXCLUDES_EffectChain_Mutex = 0;
328 
329     virtual bool containsHapticGeneratingEffect_l()
330             REQUIRES(audio_utils::EffectChain_Mutex) = 0;
331 
332     virtual void setHapticScale_l(int id, os::HapticScale hapticScale)
333             REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0;
334 
335     virtual sp<EffectCallbackInterface> effectCallback() const = 0;
336 
337     virtual wp<IAfThreadBase> thread() const = 0;
338     virtual void setThread(const sp<IAfThreadBase>& thread) EXCLUDES_EffectChain_Mutex = 0;
339 
340     virtual bool isFirstEffect_l(int id) const REQUIRES(audio_utils::EffectChain_Mutex) = 0;
341 
342     virtual size_t numberOfEffects() const = 0;
343     virtual sp<IAfEffectModule> getEffectModule(size_t index) const = 0;
344 
345     // sendMetadata_l() must be called with thread->mLock held
346     virtual void sendMetadata_l(const std::vector<playback_track_metadata_v7_t>& allMetadata,
347         const std::optional<const std::vector<playback_track_metadata_v7_t>> spatializedMetadata);
348 
349     virtual void dump(int fd, const Vector<String16>& args) const = 0;
350 };
351 
352 class IAfEffectHandle : public virtual RefBase {
353     friend class EffectBase;
354     friend class EffectChain;
355     friend class EffectModule;
356 
357 public:
358     static sp<IAfEffectHandle> create(
359             const sp<IAfEffectBase>& effect,
360             const sp<Client>& client,
361             const sp<media::IEffectClient>& effectClient,
362             int32_t priority, bool notifyFramesProcessed);
363 
364     virtual status_t initCheck() const = 0;
365     virtual bool enabled() const = 0;
366     virtual int id() const = 0;
367     virtual wp<IAfEffectBase> effect() const = 0;
368     virtual sp<android::media::IEffect> asIEffect() = 0;
369     virtual const sp<Client>& client() const = 0;
370 
371 private:
372     virtual void setControl(bool hasControl, bool signal, bool enabled) = 0;
373     virtual bool hasControl() const = 0;
374     virtual void setEnabled(bool enabled) = 0;
375     virtual bool disconnected() const = 0;
376     virtual int priority() const = 0;
377 
378     virtual void commandExecuted(uint32_t cmdCode,
379             const std::vector<uint8_t>& cmdData,
380             const std::vector<uint8_t>& replyData) = 0;
381     virtual void framesProcessed(int32_t frames) const = 0;
382 
383     virtual void dumpToBuffer(char* buffer, size_t size) const = 0;
384 };
385 
386 class IAfDeviceEffectProxy : public virtual IAfEffectBase {
387 public:
388     static sp<IAfDeviceEffectProxy> create(const AudioDeviceTypeAddr& device,
389                 const sp<DeviceEffectManagerCallback>& callback,
390                 effect_descriptor_t *desc, int id, bool notifyFramesProcessed);
391 
392     virtual status_t init_l(const std::map<audio_patch_handle_t, IAfPatchPanel::Patch>& patches)
393             REQUIRES(audio_utils::DeviceEffectManager_Mutex) EXCLUDES_EffectBase_Mutex = 0;
394     virtual const AudioDeviceTypeAddr& device() const = 0;
395 
396     virtual status_t onCreatePatch(
397             audio_patch_handle_t patchHandle,
398             const IAfPatchPanel::Patch& patch) = 0;
399     virtual status_t onUpdatePatch(audio_patch_handle_t oldPatchHandle,
400             audio_patch_handle_t newPatchHandle,
401             const IAfPatchPanel::Patch& patch) = 0;
402     virtual void onReleasePatch(audio_patch_handle_t patchHandle) = 0;
403 
404     virtual void dump2(int fd, int spaces) const = 0; // TODO(b/291319101) naming?
405 
406 private:
407     // used by DeviceEffectProxy
408     virtual bool isOutput() const = 0;
409     virtual uint32_t sampleRate() const = 0;
410     virtual audio_channel_mask_t channelMask() const = 0;
411     virtual uint32_t channelCount() const = 0;
412 
413     virtual size_t removeEffect(const sp<IAfEffectModule>& effect) = 0;
414     virtual status_t addEffectToHal(const sp<EffectHalInterface>& effect) = 0;
415     virtual status_t removeEffectFromHal(const sp<EffectHalInterface>& effect) = 0;
416 };
417 
418 }  // namespace android
419