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