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