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>& callback, 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 status_t removeEffectFromHal_l() = 0; 218 virtual void release_l(const std::string& from) = 0; 219 }; 220 221 class IAfEffectChain : public RefBase { 222 // Most of these methods are accessed from AudioFlinger::Thread 223 public: 224 static sp<IAfEffectChain> create( 225 const sp<IAfThreadBase>& thread, 226 audio_session_t sessionId, 227 const sp<IAfThreadCallback>& afThreadCallback); 228 229 // special key used for an entry in mSuspendedEffects keyed vector 230 // corresponding to a suspend all request. 231 static constexpr int kKeyForSuspendAll = 0; 232 233 // minimum duration during which we force calling effect process when last track on 234 // a session is stopped or removed to allow effect tail to be rendered 235 static constexpr int kProcessTailDurationMs = 1000; 236 237 virtual void process_l() REQUIRES(audio_utils::EffectChain_Mutex) = 0; 238 239 virtual audio_utils::mutex& mutex() const RETURN_CAPABILITY(audio_utils::EffectChain_Mutex) = 0; 240 241 virtual status_t createEffect(sp<IAfEffectModule>& effect, effect_descriptor_t* desc, int id, 242 audio_session_t sessionId, bool pinned) 243 EXCLUDES_EffectChain_Mutex = 0; 244 245 virtual status_t addEffect(const sp<IAfEffectModule>& handle) 246 EXCLUDES_EffectChain_Mutex = 0; 247 virtual status_t addEffect_l(const sp<IAfEffectModule>& handle) 248 REQUIRES(audio_utils::EffectChain_Mutex) = 0; 249 virtual size_t removeEffect(const sp<IAfEffectModule>& handle, 250 bool release = false) EXCLUDES_EffectChain_Mutex = 0; 251 252 virtual audio_session_t sessionId() const = 0; 253 virtual void setSessionId(audio_session_t sessionId) = 0; 254 255 virtual sp<IAfEffectModule> getEffectFromDesc(effect_descriptor_t* descriptor) const 256 EXCLUDES_EffectChain_Mutex = 0; 257 virtual sp<IAfEffectModule> getEffectFromId_l(int id) const 258 REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0; 259 virtual sp<IAfEffectModule> getEffectFromType_l(const effect_uuid_t* type) const 260 REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0; 261 virtual std::vector<int> getEffectIds_l() const = 0; 262 virtual bool setVolume(uint32_t* left, uint32_t* right, 263 bool force = false) EXCLUDES_EffectChain_Mutex = 0; 264 virtual void resetVolume_l() REQUIRES(audio_utils::EffectChain_Mutex) = 0; 265 virtual void setDevices_l(const AudioDeviceTypeAddrVector& devices) 266 REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0; 267 virtual void setInputDevice_l(const AudioDeviceTypeAddr& device) 268 REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0; 269 virtual void setMode_l(audio_mode_t mode) 270 REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0; 271 virtual void setAudioSource_l(audio_source_t source) 272 REQUIRES(audio_utils::ThreadBase_Mutex) = 0; 273 274 virtual void setInBuffer(const sp<EffectBufferHalInterface>& buffer) = 0; 275 virtual float *inBuffer() const = 0; 276 virtual void setOutBuffer(const sp<EffectBufferHalInterface>& buffer) = 0; 277 virtual float *outBuffer() const = 0; 278 279 virtual void incTrackCnt() = 0; 280 virtual void decTrackCnt() = 0; 281 virtual int32_t trackCnt() const = 0; 282 283 virtual void incActiveTrackCnt() = 0; 284 virtual void decActiveTrackCnt() = 0; 285 virtual int32_t activeTrackCnt() const = 0; 286 287 virtual product_strategy_t strategy() const = 0; 288 virtual void setStrategy(product_strategy_t strategy) = 0; 289 290 // suspend or restore effects of the specified type. The number of suspend requests is counted 291 // and restore occurs once all suspend requests are cancelled. 292 virtual void setEffectSuspended_l(const effect_uuid_t* type, bool suspend) = 0; 293 // suspend all eligible effects 294 virtual void setEffectSuspendedAll_l(bool suspend) = 0; 295 // check if effects should be suspended or restored when a given effect is enable or disabled 296 virtual void checkSuspendOnEffectEnabled_l(const sp<IAfEffectModule>& effect, bool enabled) 297 REQUIRES(audio_utils::ThreadBase_Mutex) REQUIRES(audio_utils::ThreadBase_Mutex) = 0; 298 299 virtual void clearInputBuffer() EXCLUDES_EffectChain_Mutex = 0; 300 301 // At least one non offloadable effect in the chain is enabled 302 virtual bool isNonOffloadableEnabled() const EXCLUDES_EffectChain_Mutex = 0; 303 virtual bool isNonOffloadableEnabled_l() const REQUIRES(audio_utils::EffectChain_Mutex) = 0; 304 305 virtual void syncHalEffectsState_l() 306 REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0; 307 308 // flags is an ORed set of audio_output_flags_t which is updated on return. 309 virtual void checkOutputFlagCompatibility(audio_output_flags_t *flags) const = 0; 310 311 // flags is an ORed set of audio_input_flags_t which is updated on return. 312 virtual void checkInputFlagCompatibility(audio_input_flags_t *flags) const = 0; 313 314 // Is this EffectChain compatible with the RAW audio flag. 315 virtual bool isRawCompatible() const = 0; 316 317 // Is this EffectChain compatible with the FAST audio flag. 318 virtual bool isFastCompatible() const = 0; 319 320 // Is this EffectChain compatible with the bit-perfect audio flag. 321 virtual bool isBitPerfectCompatible() const = 0; 322 323 // isCompatibleWithThread_l() must be called with thread->mLock held 324 virtual bool isCompatibleWithThread_l(const sp<IAfThreadBase>& thread) const 325 REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0; 326 327 virtual bool containsHapticGeneratingEffect() 328 EXCLUDES_EffectChain_Mutex = 0; 329 330 virtual bool containsHapticGeneratingEffect_l() 331 REQUIRES(audio_utils::EffectChain_Mutex) = 0; 332 333 virtual void setHapticScale_l(int id, os::HapticScale hapticScale) 334 REQUIRES(audio_utils::ThreadBase_Mutex) EXCLUDES_EffectChain_Mutex = 0; 335 336 virtual sp<EffectCallbackInterface> effectCallback() const = 0; 337 338 virtual wp<IAfThreadBase> thread() const = 0; 339 virtual void setThread(const sp<IAfThreadBase>& thread) EXCLUDES_EffectChain_Mutex = 0; 340 341 virtual bool isFirstEffect_l(int id) const REQUIRES(audio_utils::EffectChain_Mutex) = 0; 342 343 virtual size_t numberOfEffects() const = 0; 344 virtual sp<IAfEffectModule> getEffectModule(size_t index) const = 0; 345 346 // sendMetadata_l() must be called with thread->mLock held 347 virtual void sendMetadata_l(const std::vector<playback_track_metadata_v7_t>& allMetadata, 348 const std::optional<const std::vector<playback_track_metadata_v7_t>> 349 spatializedMetadata) = 0; 350 351 virtual void dump(int fd, const Vector<String16>& args) const = 0; 352 }; 353 354 class IAfEffectHandle : public virtual RefBase { 355 friend class EffectBase; 356 friend class EffectChain; 357 friend class EffectModule; 358 359 public: 360 static sp<IAfEffectHandle> create( 361 const sp<IAfEffectBase>& effect, 362 const sp<Client>& client, 363 const sp<media::IEffectClient>& effectClient, 364 int32_t priority, bool notifyFramesProcessed); 365 366 virtual status_t initCheck() const = 0; 367 virtual bool enabled() const = 0; 368 virtual int id() const = 0; 369 virtual wp<IAfEffectBase> effect() const = 0; 370 virtual sp<android::media::IEffect> asIEffect() = 0; 371 virtual const sp<Client>& client() const = 0; 372 373 private: 374 virtual void setControl(bool hasControl, bool signal, bool enabled) = 0; 375 virtual bool hasControl() const = 0; 376 virtual void setEnabled(bool enabled) = 0; 377 virtual bool disconnected() const = 0; 378 virtual int priority() const = 0; 379 380 virtual void commandExecuted(uint32_t cmdCode, 381 const std::vector<uint8_t>& cmdData, 382 const std::vector<uint8_t>& replyData) = 0; 383 virtual void framesProcessed(int32_t frames) const = 0; 384 385 virtual void dumpToBuffer(char* buffer, size_t size) const = 0; 386 }; 387 388 class IAfDeviceEffectProxy : public virtual IAfEffectBase { 389 public: 390 static sp<IAfDeviceEffectProxy> create(const AudioDeviceTypeAddr& device, 391 const sp<DeviceEffectManagerCallback>& callback, 392 effect_descriptor_t *desc, int id, bool notifyFramesProcessed); 393 394 virtual status_t init_l(const std::map<audio_patch_handle_t, IAfPatchPanel::Patch>& patches) 395 REQUIRES(audio_utils::DeviceEffectManager_Mutex) EXCLUDES_EffectBase_Mutex = 0; 396 virtual const AudioDeviceTypeAddr& device() const = 0; 397 398 virtual status_t onCreatePatch( 399 audio_patch_handle_t patchHandle, 400 const IAfPatchPanel::Patch& patch) = 0; 401 virtual status_t onUpdatePatch(audio_patch_handle_t oldPatchHandle, 402 audio_patch_handle_t newPatchHandle, 403 const IAfPatchPanel::Patch& patch) = 0; 404 /** 405 * Checks (and release) of the effect handle is linked with the given release patch handle. 406 * 407 * @param patchHandle handle of the released patch 408 * @return a reference on the effect handle released if any, nullptr otherwise. 409 * It allows to delay the destruction of the handle. 410 */ 411 virtual sp<IAfEffectHandle> onReleasePatch(audio_patch_handle_t patchHandle) = 0; 412 413 virtual void dump2(int fd, int spaces) const = 0; // TODO(b/291319101) naming? 414 415 private: 416 // used by DeviceEffectProxy 417 virtual bool isOutput() const = 0; 418 virtual uint32_t sampleRate() const = 0; 419 virtual audio_channel_mask_t channelMask() const = 0; 420 virtual uint32_t channelCount() const = 0; 421 422 virtual size_t removeEffect(const sp<IAfEffectModule>& effect) = 0; 423 virtual status_t addEffectToHal(const sp<EffectHalInterface>& effect) = 0; 424 virtual status_t removeEffectFromHal(const sp<EffectHalInterface>& effect) = 0; 425 }; 426 427 } // namespace android 428