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 // In addition, methods that lock the AudioPolicyService mutex (getOutputForEffect(), 29 // startOutput()...) should never be called with AudioFlinger or Threadbase mutex locked 30 // to avoid cross deadlock with other clients calling AudioPolicyService methods that in turn 31 // call AudioFlinger thus locking the same mutexes in the reverse order. 32 33 // The EffectModule class is a wrapper object controlling the effect engine implementation 34 // in the effect library. It prevents concurrent calls to process() and command() functions 35 // from different client threads. It keeps a list of EffectHandle objects corresponding 36 // to all client applications using this effect and notifies applications of effect state, 37 // control or parameter changes. It manages the activation state machine to send appropriate 38 // reset, enable, disable commands to effect engine and provide volume 39 // ramping when effects are activated/deactivated. 40 // When controlling an auxiliary effect, the EffectModule also provides an input buffer used by 41 // the attached track(s) to accumulate their auxiliary channel. 42 class EffectModule : public RefBase { 43 public: 44 EffectModule(ThreadBase *thread, 45 const wp<AudioFlinger::EffectChain>& chain, 46 effect_descriptor_t *desc, 47 int id, 48 audio_session_t sessionId); 49 virtual ~EffectModule(); 50 51 enum effect_state { 52 IDLE, 53 RESTART, 54 STARTING, 55 ACTIVE, 56 STOPPING, 57 STOPPED, 58 DESTROYED 59 }; 60 61 int id() const { return mId; } 62 void process(); 63 bool updateState(); 64 status_t command(uint32_t cmdCode, 65 uint32_t cmdSize, 66 void *pCmdData, 67 uint32_t *replySize, 68 void *pReplyData); 69 70 void reset_l(); 71 status_t configure(); 72 status_t init(); 73 effect_state state() const { 74 return mState; 75 } 76 uint32_t status() { 77 return mStatus; 78 } 79 audio_session_t sessionId() const { 80 return mSessionId; 81 } 82 status_t setEnabled(bool enabled); 83 status_t setEnabled_l(bool enabled); 84 bool isEnabled() const; 85 bool isProcessEnabled() const; 86 87 void setInBuffer(int16_t *buffer) { mConfig.inputCfg.buffer.s16 = buffer; } 88 int16_t *inBuffer() { return mConfig.inputCfg.buffer.s16; } 89 void setOutBuffer(int16_t *buffer) { mConfig.outputCfg.buffer.s16 = buffer; } 90 int16_t *outBuffer() { return mConfig.outputCfg.buffer.s16; } 91 void setChain(const wp<EffectChain>& chain) { mChain = chain; } 92 void setThread(const wp<ThreadBase>& thread) { mThread = thread; } 93 const wp<ThreadBase>& thread() { return mThread; } 94 95 status_t addHandle(EffectHandle *handle); 96 size_t disconnect(EffectHandle *handle, bool unpinIfLast); 97 size_t removeHandle(EffectHandle *handle); 98 99 const effect_descriptor_t& desc() const { return mDescriptor; } 100 wp<EffectChain>& chain() { return mChain; } 101 102 status_t setDevice(audio_devices_t device); 103 status_t setVolume(uint32_t *left, uint32_t *right, bool controller); 104 status_t setMode(audio_mode_t mode); 105 status_t setAudioSource(audio_source_t source); 106 status_t start(); 107 status_t stop(); 108 void setSuspended(bool suspended); 109 bool suspended() const; 110 111 EffectHandle* controlHandle_l(); 112 113 bool isPinned() const { return mPinned; } 114 void unPin() { mPinned = false; } 115 bool purgeHandles(); 116 void lock() { mLock.lock(); } 117 void unlock() { mLock.unlock(); } 118 bool isOffloadable() const 119 { return (mDescriptor.flags & EFFECT_FLAG_OFFLOAD_SUPPORTED) != 0; } 120 bool isImplementationSoftware() const 121 { return (mDescriptor.flags & EFFECT_FLAG_HW_ACC_MASK) == 0; } 122 bool isProcessImplemented() const 123 { return (mDescriptor.flags & EFFECT_FLAG_NO_PROCESS) == 0; } 124 status_t setOffloaded(bool offloaded, audio_io_handle_t io); 125 bool isOffloaded() const; 126 void addEffectToHal_l(); 127 128 void dump(int fd, const Vector<String16>& args); 129 130 protected: 131 friend class AudioFlinger; // for mHandles 132 bool mPinned; 133 134 // Maximum time allocated to effect engines to complete the turn off sequence 135 static const uint32_t MAX_DISABLE_TIME_MS = 10000; 136 137 EffectModule(const EffectModule&); 138 EffectModule& operator = (const EffectModule&); 139 140 status_t start_l(); 141 status_t stop_l(); 142 status_t remove_effect_from_hal_l(); 143 144 mutable Mutex mLock; // mutex for process, commands and handles list protection 145 wp<ThreadBase> mThread; // parent thread 146 wp<EffectChain> mChain; // parent effect chain 147 const int mId; // this instance unique ID 148 const audio_session_t mSessionId; // audio session ID 149 const effect_descriptor_t mDescriptor;// effect descriptor received from effect engine 150 effect_config_t mConfig; // input and output audio configuration 151 effect_handle_t mEffectInterface; // Effect module C API 152 status_t mStatus; // initialization status 153 effect_state mState; // current activation state 154 Vector<EffectHandle *> mHandles; // list of client handles 155 // First handle in mHandles has highest priority and controls the effect module 156 uint32_t mMaxDisableWaitCnt; // maximum grace period before forcing an effect off after 157 // sending disable command. 158 uint32_t mDisableWaitCnt; // current process() calls count during disable period. 159 bool mSuspended; // effect is suspended: temporarily disabled by framework 160 bool mOffloaded; // effect is currently offloaded to the audio DSP 161 wp<AudioFlinger> mAudioFlinger; 162 }; 163 164 // The EffectHandle class implements the IEffect interface. It provides resources 165 // to receive parameter updates, keeps track of effect control 166 // ownership and state and has a pointer to the EffectModule object it is controlling. 167 // There is one EffectHandle object for each application controlling (or using) 168 // an effect module. 169 // The EffectHandle is obtained by calling AudioFlinger::createEffect(). 170 class EffectHandle: public android::BnEffect { 171 public: 172 173 EffectHandle(const sp<EffectModule>& effect, 174 const sp<AudioFlinger::Client>& client, 175 const sp<IEffectClient>& effectClient, 176 int32_t priority); 177 virtual ~EffectHandle(); 178 virtual status_t initCheck(); 179 180 // IEffect 181 virtual status_t enable(); 182 virtual status_t disable(); 183 virtual status_t command(uint32_t cmdCode, 184 uint32_t cmdSize, 185 void *pCmdData, 186 uint32_t *replySize, 187 void *pReplyData); 188 virtual void disconnect(); 189 private: 190 void disconnect(bool unpinIfLast); 191 public: 192 virtual sp<IMemory> getCblk() const { return mCblkMemory; } 193 virtual status_t onTransact(uint32_t code, const Parcel& data, 194 Parcel* reply, uint32_t flags); 195 196 197 // Give or take control of effect module 198 // - hasControl: true if control is given, false if removed 199 // - signal: true client app should be signaled of change, false otherwise 200 // - enabled: state of the effect when control is passed 201 void setControl(bool hasControl, bool signal, bool enabled); 202 void commandExecuted(uint32_t cmdCode, 203 uint32_t cmdSize, 204 void *pCmdData, 205 uint32_t replySize, 206 void *pReplyData); 207 void setEnabled(bool enabled); 208 bool enabled() const { return mEnabled; } 209 210 // Getters 211 int id() const { return mEffect->id(); } 212 int priority() const { return mPriority; } 213 bool hasControl() const { return mHasControl; } 214 sp<EffectModule> effect() const { return mEffect; } 215 // destroyed_l() must be called with the associated EffectModule mLock held 216 bool destroyed_l() const { return mDestroyed; } 217 218 void dumpToBuffer(char* buffer, size_t size); 219 220 protected: 221 friend class AudioFlinger; // for mEffect, mHasControl, mEnabled 222 EffectHandle(const EffectHandle&); 223 EffectHandle& operator =(const EffectHandle&); 224 225 sp<EffectModule> mEffect; // pointer to controlled EffectModule 226 sp<IEffectClient> mEffectClient; // callback interface for client notifications 227 /*const*/ sp<Client> mClient; // client for shared memory allocation, see disconnect() 228 sp<IMemory> mCblkMemory; // shared memory for control block 229 effect_param_cblk_t* mCblk; // control block for deferred parameter setting via 230 // shared memory 231 uint8_t* mBuffer; // pointer to parameter area in shared memory 232 int mPriority; // client application priority to control the effect 233 bool mHasControl; // true if this handle is controlling the effect 234 bool mEnabled; // cached enable state: needed when the effect is 235 // restored after being suspended 236 bool mDestroyed; // Set to true by destructor. Access with EffectModule 237 // mLock held 238 }; 239 240 // the EffectChain class represents a group of effects associated to one audio session. 241 // There can be any number of EffectChain objects per output mixer thread (PlaybackThread). 242 // The EffectChain with session ID AUDIO_SESSION_OUTPUT_MIX contains global effects applied 243 // to the output mix. 244 // Effects in this chain can be insert or auxiliary. Effects in other chains (attached to 245 // tracks) are insert only. The EffectChain maintains an ordered list of effect module, the 246 // order corresponding in the effect process order. When attached to a track (session ID != 247 // AUDIO_SESSION_OUTPUT_MIX), 248 // it also provide it's own input buffer used by the track as accumulation buffer. 249 class EffectChain : public RefBase { 250 public: 251 EffectChain(const wp<ThreadBase>& wThread, audio_session_t sessionId); 252 EffectChain(ThreadBase *thread, audio_session_t sessionId); 253 virtual ~EffectChain(); 254 255 // special key used for an entry in mSuspendedEffects keyed vector 256 // corresponding to a suspend all request. 257 static const int kKeyForSuspendAll = 0; 258 259 // minimum duration during which we force calling effect process when last track on 260 // a session is stopped or removed to allow effect tail to be rendered 261 static const int kProcessTailDurationMs = 1000; 262 263 void process_l(); 264 265 void lock() { 266 mLock.lock(); 267 } 268 void unlock() { 269 mLock.unlock(); 270 } 271 272 status_t addEffect_l(const sp<EffectModule>& handle); 273 size_t removeEffect_l(const sp<EffectModule>& handle); 274 275 audio_session_t sessionId() const { return mSessionId; } 276 void setSessionId(audio_session_t sessionId) { mSessionId = sessionId; } 277 278 sp<EffectModule> getEffectFromDesc_l(effect_descriptor_t *descriptor); 279 sp<EffectModule> getEffectFromId_l(int id); 280 sp<EffectModule> getEffectFromType_l(const effect_uuid_t *type); 281 // FIXME use float to improve the dynamic range 282 bool setVolume_l(uint32_t *left, uint32_t *right, bool force = false); 283 void resetVolume_l(); 284 void setDevice_l(audio_devices_t device); 285 void setMode_l(audio_mode_t mode); 286 void setAudioSource_l(audio_source_t source); 287 288 void setInBuffer(int16_t *buffer, bool ownsBuffer = false) { 289 mInBuffer = buffer; 290 mOwnInBuffer = ownsBuffer; 291 } 292 int16_t *inBuffer() const { 293 return mInBuffer; 294 } 295 void setOutBuffer(int16_t *buffer) { 296 mOutBuffer = buffer; 297 } 298 int16_t *outBuffer() const { 299 return mOutBuffer; 300 } 301 302 void incTrackCnt() { android_atomic_inc(&mTrackCnt); } 303 void decTrackCnt() { android_atomic_dec(&mTrackCnt); } 304 int32_t trackCnt() const { return android_atomic_acquire_load(&mTrackCnt); } 305 306 void incActiveTrackCnt() { android_atomic_inc(&mActiveTrackCnt); 307 mTailBufferCount = mMaxTailBuffers; } 308 void decActiveTrackCnt() { android_atomic_dec(&mActiveTrackCnt); } 309 int32_t activeTrackCnt() const { return android_atomic_acquire_load(&mActiveTrackCnt); } 310 311 uint32_t strategy() const { return mStrategy; } 312 void setStrategy(uint32_t strategy) 313 { mStrategy = strategy; } 314 315 // suspend effect of the given type 316 void setEffectSuspended_l(const effect_uuid_t *type, 317 bool suspend); 318 // suspend all eligible effects 319 void setEffectSuspendedAll_l(bool suspend); 320 // check if effects should be suspend or restored when a given effect is enable or disabled 321 void checkSuspendOnEffectEnabled(const sp<EffectModule>& effect, 322 bool enabled); 323 324 void clearInputBuffer(); 325 326 // At least one non offloadable effect in the chain is enabled 327 bool isNonOffloadableEnabled(); 328 329 void syncHalEffectsState(); 330 331 // flags is an ORed set of audio_output_flags_t which is updated on return. 332 void checkOutputFlagCompatibility(audio_output_flags_t *flags) const; 333 334 // flags is an ORed set of audio_input_flags_t which is updated on return. 335 void checkInputFlagCompatibility(audio_input_flags_t *flags) const; 336 337 // Is this EffectChain compatible with the RAW audio flag. 338 bool isRawCompatible() const; 339 340 // Is this EffectChain compatible with the FAST audio flag. 341 bool isFastCompatible() const; 342 343 // isCompatibleWithThread_l() must be called with thread->mLock held 344 bool isCompatibleWithThread_l(const sp<ThreadBase>& thread) const; 345 346 void dump(int fd, const Vector<String16>& args); 347 348 protected: 349 friend class AudioFlinger; // for mThread, mEffects 350 EffectChain(const EffectChain&); 351 EffectChain& operator =(const EffectChain&); 352 353 class SuspendedEffectDesc : public RefBase { 354 public: 355 SuspendedEffectDesc() : mRefCount(0) {} 356 357 int mRefCount; 358 effect_uuid_t mType; 359 wp<EffectModule> mEffect; 360 }; 361 362 // get a list of effect modules to suspend when an effect of the type 363 // passed is enabled. 364 void getSuspendEligibleEffects(Vector< sp<EffectModule> > &effects); 365 366 // get an effect module if it is currently enable 367 sp<EffectModule> getEffectIfEnabled(const effect_uuid_t *type); 368 // true if the effect whose descriptor is passed can be suspended 369 // OEMs can modify the rules implemented in this method to exclude specific effect 370 // types or implementations from the suspend/restore mechanism. 371 bool isEffectEligibleForSuspend(const effect_descriptor_t& desc); 372 373 void clearInputBuffer_l(sp<ThreadBase> thread); 374 375 void setThread(const sp<ThreadBase>& thread); 376 377 wp<ThreadBase> mThread; // parent mixer thread 378 mutable Mutex mLock; // mutex protecting effect list 379 Vector< sp<EffectModule> > mEffects; // list of effect modules 380 audio_session_t mSessionId; // audio session ID 381 int16_t *mInBuffer; // chain input buffer 382 int16_t *mOutBuffer; // chain output buffer 383 384 // 'volatile' here means these are accessed with atomic operations instead of mutex 385 volatile int32_t mActiveTrackCnt; // number of active tracks connected 386 volatile int32_t mTrackCnt; // number of tracks connected 387 388 int32_t mTailBufferCount; // current effect tail buffer count 389 int32_t mMaxTailBuffers; // maximum effect tail buffers 390 bool mOwnInBuffer; // true if the chain owns its input buffer 391 int mVolumeCtrlIdx; // index of insert effect having control over volume 392 uint32_t mLeftVolume; // previous volume on left channel 393 uint32_t mRightVolume; // previous volume on right channel 394 uint32_t mNewLeftVolume; // new volume on left channel 395 uint32_t mNewRightVolume; // new volume on right channel 396 uint32_t mStrategy; // strategy for this effect chain 397 // mSuspendedEffects lists all effects currently suspended in the chain. 398 // Use effect type UUID timelow field as key. There is no real risk of identical 399 // timeLow fields among effect type UUIDs. 400 // Updated by updateSuspendedSessions_l() only. 401 KeyedVector< int, sp<SuspendedEffectDesc> > mSuspendedEffects; 402 }; 403
