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