1 /* 2 ** 3 ** Copyright 2012, The Android Open Source Project 4 ** 5 ** Licensed under the Apache License, Version 2.0 (the "License"); 6 ** you may not use this file except in compliance with the License. 7 ** You may obtain a copy of the License at 8 ** 9 ** http://www.apache.org/licenses/LICENSE-2.0 10 ** 11 ** Unless required by applicable law or agreed to in writing, software 12 ** distributed under the License is distributed on an "AS IS" BASIS, 13 ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 ** See the License for the specific language governing permissions and 15 ** limitations under the License. 16 */ 17 18 #ifndef INCLUDING_FROM_AUDIOFLINGER_H 19 #error This header file should only be included from AudioFlinger.h 20 #endif 21 22 //--- Audio Effect Management 23 24 // EffectModule and EffectChain classes both have their own mutex to protect 25 // state changes or resource modifications. Always respect the following order 26 // if multiple mutexes must be acquired to avoid cross deadlock: 27 // AudioFlinger -> ThreadBase -> EffectChain -> EffectModule 28 // AudioHandle -> ThreadBase -> EffectChain -> EffectModule 29 // In addition, methods that lock the AudioPolicyService mutex (getOutputForEffect(), 30 // startOutput(), getInputForAttr(), releaseInput()...) should never be called with AudioFlinger or 31 // Threadbase mutex locked to avoid cross deadlock with other clients calling AudioPolicyService 32 // methods that in turn call AudioFlinger thus locking the same mutexes in the reverse order. 33 34 // The EffectModule class is a wrapper object controlling the effect engine implementation 35 // in the effect library. It prevents concurrent calls to process() and command() functions 36 // from different client threads. It keeps a list of EffectHandle objects corresponding 37 // to all client applications using this effect and notifies applications of effect state, 38 // control or parameter changes. It manages the activation state machine to send appropriate 39 // reset, enable, disable commands to effect engine and provide volume 40 // ramping when effects are activated/deactivated. 41 // When controlling an auxiliary effect, the EffectModule also provides an input buffer used by 42 // the attached track(s) to accumulate their auxiliary channel. 43 class EffectModule : public RefBase { 44 public: 45 EffectModule(ThreadBase *thread, 46 const wp<AudioFlinger::EffectChain>& chain, 47 effect_descriptor_t *desc, 48 int id, 49 audio_session_t sessionId, 50 bool pinned); 51 virtual ~EffectModule(); 52 53 enum effect_state { 54 IDLE, 55 RESTART, 56 STARTING, 57 ACTIVE, 58 STOPPING, 59 STOPPED, 60 DESTROYED 61 }; 62 63 int id() const { return mId; } 64 void process(); 65 bool updateState(); 66 status_t command(uint32_t cmdCode, 67 uint32_t cmdSize, 68 void *pCmdData, 69 uint32_t *replySize, 70 void *pReplyData); 71 72 void reset_l(); 73 status_t configure(); 74 status_t init(); 75 effect_state state() const { 76 return mState; 77 } 78 uint32_t status() { 79 return mStatus; 80 } 81 audio_session_t sessionId() const { 82 return mSessionId; 83 } 84 status_t setEnabled(bool enabled); 85 status_t setEnabled_l(bool enabled); 86 bool isEnabled() const; 87 bool isProcessEnabled() const; 88 bool isOffloadedOrDirect() const; 89 bool isVolumeControlEnabled() const; 90 91 void setInBuffer(const sp<EffectBufferHalInterface>& buffer); 92 int16_t *inBuffer() const { 93 return mInBuffer != 0 ? reinterpret_cast<int16_t*>(mInBuffer->ptr()) : NULL; 94 } 95 void setOutBuffer(const sp<EffectBufferHalInterface>& buffer); 96 int16_t *outBuffer() const { 97 return mOutBuffer != 0 ? reinterpret_cast<int16_t*>(mOutBuffer->ptr()) : NULL; 98 } 99 void setChain(const wp<EffectChain>& chain) { mChain = chain; } 100 void setThread(const wp<ThreadBase>& thread) 101 { mThread = thread; mThreadType = thread.promote()->type(); } 102 const wp<ThreadBase>& thread() { return mThread; } 103 104 status_t addHandle(EffectHandle *handle); 105 ssize_t disconnectHandle(EffectHandle *handle, bool unpinIfLast); 106 ssize_t removeHandle(EffectHandle *handle); 107 ssize_t removeHandle_l(EffectHandle *handle); 108 109 const effect_descriptor_t& desc() const { return mDescriptor; } 110 wp<EffectChain>& chain() { return mChain; } 111 112 status_t setDevice(audio_devices_t device); 113 status_t setVolume(uint32_t *left, uint32_t *right, bool controller); 114 status_t setMode(audio_mode_t mode); 115 status_t setAudioSource(audio_source_t source); 116 status_t start(); 117 status_t stop(); 118 void setSuspended(bool suspended); 119 bool suspended() const; 120 121 EffectHandle* controlHandle_l(); 122 123 bool isPinned() const { return mPinned; } 124 void unPin() { mPinned = false; } 125 bool purgeHandles(); 126 void lock() { mLock.lock(); } 127 void unlock() { mLock.unlock(); } 128 bool isOffloadable() const 129 { return (mDescriptor.flags & EFFECT_FLAG_OFFLOAD_SUPPORTED) != 0; } 130 bool isImplementationSoftware() const 131 { return (mDescriptor.flags & EFFECT_FLAG_HW_ACC_MASK) == 0; } 132 bool isProcessImplemented() const 133 { return (mDescriptor.flags & EFFECT_FLAG_NO_PROCESS) == 0; } 134 bool isVolumeControl() const 135 { return (mDescriptor.flags & EFFECT_FLAG_VOLUME_MASK) 136 == EFFECT_FLAG_VOLUME_CTRL; } 137 bool isVolumeMonitor() const 138 { return (mDescriptor.flags & EFFECT_FLAG_VOLUME_MASK) 139 == EFFECT_FLAG_VOLUME_MONITOR; } 140 status_t setOffloaded(bool offloaded, audio_io_handle_t io); 141 bool isOffloaded() const; 142 void addEffectToHal_l(); 143 void release_l(); 144 145 status_t updatePolicyState(); 146 147 void dump(int fd, const Vector<String16>& args); 148 149 private: 150 friend class AudioFlinger; // for mHandles 151 bool mPinned; 152 153 // Maximum time allocated to effect engines to complete the turn off sequence 154 static const uint32_t MAX_DISABLE_TIME_MS = 10000; 155 156 DISALLOW_COPY_AND_ASSIGN(EffectModule); 157 158 status_t start_l(); 159 status_t stop_l(); 160 status_t remove_effect_from_hal_l(); 161 162 mutable Mutex mLock; // mutex for process, commands and handles list protection 163 wp<ThreadBase> mThread; // parent thread 164 ThreadBase::type_t mThreadType; // parent thread type 165 wp<EffectChain> mChain; // parent effect chain 166 const int mId; // this instance unique ID 167 const audio_session_t mSessionId; // audio session ID 168 const effect_descriptor_t mDescriptor;// effect descriptor received from effect engine 169 effect_config_t mConfig; // input and output audio configuration 170 sp<EffectHalInterface> mEffectInterface; // Effect module HAL 171 sp<EffectBufferHalInterface> mInBuffer; // Buffers for interacting with HAL 172 sp<EffectBufferHalInterface> mOutBuffer; 173 status_t mStatus; // initialization status 174 effect_state mState; // current activation state 175 Vector<EffectHandle *> mHandles; // list of client handles 176 // First handle in mHandles has highest priority and controls the effect module 177 uint32_t mMaxDisableWaitCnt; // maximum grace period before forcing an effect off after 178 // sending disable command. 179 uint32_t mDisableWaitCnt; // current process() calls count during disable period. 180 bool mSuspended; // effect is suspended: temporarily disabled by framework 181 bool mOffloaded; // effect is currently offloaded to the audio DSP 182 wp<AudioFlinger> mAudioFlinger; 183 184 #ifdef FLOAT_EFFECT_CHAIN 185 bool mSupportsFloat; // effect supports float processing 186 sp<EffectBufferHalInterface> mInConversionBuffer; // Buffers for HAL conversion if needed. 187 sp<EffectBufferHalInterface> mOutConversionBuffer; 188 uint32_t mInChannelCountRequested; 189 uint32_t mOutChannelCountRequested; 190 #endif 191 192 class AutoLockReentrant { 193 public: 194 AutoLockReentrant(Mutex& mutex, pid_t allowedTid) 195 : mMutex(gettid() == allowedTid ? nullptr : &mutex) 196 { 197 if (mMutex != nullptr) mMutex->lock(); 198 } 199 ~AutoLockReentrant() { 200 if (mMutex != nullptr) mMutex->unlock(); 201 } 202 private: 203 Mutex * const mMutex; 204 }; 205 206 static constexpr pid_t INVALID_PID = (pid_t)-1; 207 // this tid is allowed to call setVolume() without acquiring the mutex. 208 pid_t mSetVolumeReentrantTid = INVALID_PID; 209 210 // Audio policy effect state management 211 // Mutex protecting transactions with audio policy manager as mLock cannot 212 // be held to avoid cross deadlocks with audio policy mutex 213 Mutex mPolicyLock; 214 // Effect is registered in APM or not 215 bool mPolicyRegistered = false; 216 // Effect enabled state communicated to APM. Enabled state corresponds to 217 // state requested by the EffectHandle with control 218 bool mPolicyEnabled = false; 219 }; 220 221 // The EffectHandle class implements the IEffect interface. It provides resources 222 // to receive parameter updates, keeps track of effect control 223 // ownership and state and has a pointer to the EffectModule object it is controlling. 224 // There is one EffectHandle object for each application controlling (or using) 225 // an effect module. 226 // The EffectHandle is obtained by calling AudioFlinger::createEffect(). 227 class EffectHandle: public android::BnEffect { 228 public: 229 230 EffectHandle(const sp<EffectModule>& effect, 231 const sp<AudioFlinger::Client>& client, 232 const sp<IEffectClient>& effectClient, 233 int32_t priority); 234 virtual ~EffectHandle(); 235 virtual status_t initCheck(); 236 237 // IEffect 238 virtual status_t enable(); 239 virtual status_t disable(); 240 virtual status_t command(uint32_t cmdCode, 241 uint32_t cmdSize, 242 void *pCmdData, 243 uint32_t *replySize, 244 void *pReplyData); 245 virtual void disconnect(); 246 private: 247 void disconnect(bool unpinIfLast); 248 public: 249 virtual sp<IMemory> getCblk() const { return mCblkMemory; } 250 virtual status_t onTransact(uint32_t code, const Parcel& data, 251 Parcel* reply, uint32_t flags); 252 253 254 // Give or take control of effect module 255 // - hasControl: true if control is given, false if removed 256 // - signal: true client app should be signaled of change, false otherwise 257 // - enabled: state of the effect when control is passed 258 void setControl(bool hasControl, bool signal, bool enabled); 259 void commandExecuted(uint32_t cmdCode, 260 uint32_t cmdSize, 261 void *pCmdData, 262 uint32_t replySize, 263 void *pReplyData); 264 void setEnabled(bool enabled); 265 bool enabled() const { return mEnabled; } 266 267 // Getters 268 wp<EffectModule> effect() const { return mEffect; } 269 int id() const { 270 sp<EffectModule> effect = mEffect.promote(); 271 if (effect == 0) { 272 return 0; 273 } 274 return effect->id(); 275 } 276 int priority() const { return mPriority; } 277 bool hasControl() const { return mHasControl; } 278 bool disconnected() const { return mDisconnected; } 279 280 void dumpToBuffer(char* buffer, size_t size); 281 282 private: 283 friend class AudioFlinger; // for mEffect, mHasControl, mEnabled 284 DISALLOW_COPY_AND_ASSIGN(EffectHandle); 285 286 Mutex mLock; // protects IEffect method calls 287 wp<EffectModule> mEffect; // pointer to controlled EffectModule 288 sp<IEffectClient> mEffectClient; // callback interface for client notifications 289 /*const*/ sp<Client> mClient; // client for shared memory allocation, see disconnect() 290 sp<IMemory> mCblkMemory; // shared memory for control block 291 effect_param_cblk_t* mCblk; // control block for deferred parameter setting via 292 // shared memory 293 uint8_t* mBuffer; // pointer to parameter area in shared memory 294 int mPriority; // client application priority to control the effect 295 bool mHasControl; // true if this handle is controlling the effect 296 bool mEnabled; // cached enable state: needed when the effect is 297 // restored after being suspended 298 bool mDisconnected; // Set to true by disconnect() 299 }; 300 301 // the EffectChain class represents a group of effects associated to one audio session. 302 // There can be any number of EffectChain objects per output mixer thread (PlaybackThread). 303 // The EffectChain with session ID AUDIO_SESSION_OUTPUT_MIX contains global effects applied 304 // to the output mix. 305 // Effects in this chain can be insert or auxiliary. Effects in other chains (attached to 306 // tracks) are insert only. The EffectChain maintains an ordered list of effect module, the 307 // order corresponding in the effect process order. When attached to a track (session ID != 308 // AUDIO_SESSION_OUTPUT_MIX), 309 // it also provide it's own input buffer used by the track as accumulation buffer. 310 class EffectChain : public RefBase { 311 public: 312 EffectChain(const wp<ThreadBase>& wThread, audio_session_t sessionId); 313 EffectChain(ThreadBase *thread, audio_session_t sessionId); 314 virtual ~EffectChain(); 315 316 // special key used for an entry in mSuspendedEffects keyed vector 317 // corresponding to a suspend all request. 318 static const int kKeyForSuspendAll = 0; 319 320 // minimum duration during which we force calling effect process when last track on 321 // a session is stopped or removed to allow effect tail to be rendered 322 static const int kProcessTailDurationMs = 1000; 323 324 void process_l(); 325 326 void lock() { 327 mLock.lock(); 328 } 329 void unlock() { 330 mLock.unlock(); 331 } 332 333 status_t createEffect_l(sp<EffectModule>& effect, 334 ThreadBase *thread, 335 effect_descriptor_t *desc, 336 int id, 337 audio_session_t sessionId, 338 bool pinned); 339 status_t addEffect_l(const sp<EffectModule>& handle); 340 status_t addEffect_ll(const sp<EffectModule>& handle); 341 size_t removeEffect_l(const sp<EffectModule>& handle, bool release = false); 342 343 audio_session_t sessionId() const { return mSessionId; } 344 void setSessionId(audio_session_t sessionId) { mSessionId = sessionId; } 345 346 sp<EffectModule> getEffectFromDesc_l(effect_descriptor_t *descriptor); 347 sp<EffectModule> getEffectFromId_l(int id); 348 sp<EffectModule> getEffectFromType_l(const effect_uuid_t *type); 349 std::vector<int> getEffectIds(); 350 // FIXME use float to improve the dynamic range 351 bool setVolume_l(uint32_t *left, uint32_t *right, bool force = false); 352 void resetVolume_l(); 353 void setDevice_l(audio_devices_t device); 354 void setMode_l(audio_mode_t mode); 355 void setAudioSource_l(audio_source_t source); 356 357 void setInBuffer(const sp<EffectBufferHalInterface>& buffer) { 358 mInBuffer = buffer; 359 } 360 effect_buffer_t *inBuffer() const { 361 return mInBuffer != 0 ? reinterpret_cast<effect_buffer_t*>(mInBuffer->ptr()) : NULL; 362 } 363 void setOutBuffer(const sp<EffectBufferHalInterface>& buffer) { 364 mOutBuffer = buffer; 365 } 366 effect_buffer_t *outBuffer() const { 367 return mOutBuffer != 0 ? reinterpret_cast<effect_buffer_t*>(mOutBuffer->ptr()) : NULL; 368 } 369 370 void incTrackCnt() { android_atomic_inc(&mTrackCnt); } 371 void decTrackCnt() { android_atomic_dec(&mTrackCnt); } 372 int32_t trackCnt() const { return android_atomic_acquire_load(&mTrackCnt); } 373 374 void incActiveTrackCnt() { android_atomic_inc(&mActiveTrackCnt); 375 mTailBufferCount = mMaxTailBuffers; } 376 void decActiveTrackCnt() { android_atomic_dec(&mActiveTrackCnt); } 377 int32_t activeTrackCnt() const { return android_atomic_acquire_load(&mActiveTrackCnt); } 378 379 uint32_t strategy() const { return mStrategy; } 380 void setStrategy(uint32_t strategy) 381 { mStrategy = strategy; } 382 383 // suspend or restore effects of the specified type. The number of suspend requests is counted 384 // and restore occurs once all suspend requests are cancelled. 385 void setEffectSuspended_l(const effect_uuid_t *type, 386 bool suspend); 387 // suspend all eligible effects 388 void setEffectSuspendedAll_l(bool suspend); 389 // check if effects should be suspend or restored when a given effect is enable or disabled 390 void checkSuspendOnEffectEnabled(const sp<EffectModule>& effect, 391 bool enabled); 392 393 void clearInputBuffer(); 394 395 // At least one non offloadable effect in the chain is enabled 396 bool isNonOffloadableEnabled(); 397 bool isNonOffloadableEnabled_l(); 398 399 void syncHalEffectsState(); 400 401 // flags is an ORed set of audio_output_flags_t which is updated on return. 402 void checkOutputFlagCompatibility(audio_output_flags_t *flags) const; 403 404 // flags is an ORed set of audio_input_flags_t which is updated on return. 405 void checkInputFlagCompatibility(audio_input_flags_t *flags) const; 406 407 // Is this EffectChain compatible with the RAW audio flag. 408 bool isRawCompatible() const; 409 410 // Is this EffectChain compatible with the FAST audio flag. 411 bool isFastCompatible() const; 412 413 // isCompatibleWithThread_l() must be called with thread->mLock held 414 bool isCompatibleWithThread_l(const sp<ThreadBase>& thread) const; 415 416 void dump(int fd, const Vector<String16>& args); 417 418 private: 419 friend class AudioFlinger; // for mThread, mEffects 420 DISALLOW_COPY_AND_ASSIGN(EffectChain); 421 422 class SuspendedEffectDesc : public RefBase { 423 public: 424 SuspendedEffectDesc() : mRefCount(0) {} 425 426 int mRefCount; // > 0 when suspended 427 effect_uuid_t mType; 428 wp<EffectModule> mEffect; 429 }; 430 431 // get a list of effect modules to suspend when an effect of the type 432 // passed is enabled. 433 void getSuspendEligibleEffects(Vector< sp<EffectModule> > &effects); 434 435 // get an effect module if it is currently enable 436 sp<EffectModule> getEffectIfEnabled(const effect_uuid_t *type); 437 // true if the effect whose descriptor is passed can be suspended 438 // OEMs can modify the rules implemented in this method to exclude specific effect 439 // types or implementations from the suspend/restore mechanism. 440 bool isEffectEligibleForSuspend(const effect_descriptor_t& desc); 441 442 static bool isEffectEligibleForBtNrecSuspend(const effect_uuid_t *type); 443 444 void clearInputBuffer_l(const sp<ThreadBase>& thread); 445 446 void setThread(const sp<ThreadBase>& thread); 447 448 void setVolumeForOutput_l(uint32_t left, uint32_t right); 449 450 wp<ThreadBase> mThread; // parent mixer thread 451 mutable Mutex mLock; // mutex protecting effect list 452 Vector< sp<EffectModule> > mEffects; // list of effect modules 453 audio_session_t mSessionId; // audio session ID 454 sp<EffectBufferHalInterface> mInBuffer; // chain input buffer 455 sp<EffectBufferHalInterface> mOutBuffer; // chain output buffer 456 457 // 'volatile' here means these are accessed with atomic operations instead of mutex 458 volatile int32_t mActiveTrackCnt; // number of active tracks connected 459 volatile int32_t mTrackCnt; // number of tracks connected 460 461 int32_t mTailBufferCount; // current effect tail buffer count 462 int32_t mMaxTailBuffers; // maximum effect tail buffers 463 int mVolumeCtrlIdx; // index of insert effect having control over volume 464 uint32_t mLeftVolume; // previous volume on left channel 465 uint32_t mRightVolume; // previous volume on right channel 466 uint32_t mNewLeftVolume; // new volume on left channel 467 uint32_t mNewRightVolume; // new volume on right channel 468 uint32_t mStrategy; // strategy for this effect chain 469 // mSuspendedEffects lists all effects currently suspended in the chain. 470 // Use effect type UUID timelow field as key. There is no real risk of identical 471 // timeLow fields among effect type UUIDs. 472 // Updated by setEffectSuspended_l() and setEffectSuspendedAll_l() only. 473 KeyedVector< int, sp<SuspendedEffectDesc> > mSuspendedEffects; 474 }; 475
