A few other guarantees that the audio framework makes, that I forgot to
mention:
1) audio_engine_open() will only be called for an engine that is not
already opened
2) audio_engine_start() will only be called for an engine that is open,
but not started
3) audio_engine_stop() will only be called for an engine that is open,
and started
4) audio_engine_count() will only be called for an open, started engine
5) audio_engine_close() will only be called for an engine that is open
but not started
Basically, there is a state machine which one can pretty easily imagine
makes sense from the above. I won't offend your vision by trying to
draw the state diagram here in ASCII art, but I _think_ its pretty much
what you would expect given the above.
- Garrett
Garrett D'Amore - sun microsystems wrote:
> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
> This information is Copyright 2009 Sun Microsystems
> 1. Introduction
> 1.1. Project/Component Working Name:
> Audio DDI Simplifications
> 1.2. Name of Document Author/Supplier:
> Author: Garrett D'Amore
> 1.3 Date of This Document:
> 22 December, 2009
> 4. Technical Description
>
> PROBLEM
>
> Since Boomer (PSARC 2008/318) has integrated, we've gotten quite a bit of
> experience with audio drivers. As part of the work to move to an
> interrupt-free design (PSARC 2009/674), we found that most drivers were
> still retaining a fair bit of complexity simply to support to suspend/resume.
> Yet, since the framework had to suspend and resume the devices properly anyway
> (in order to prevent underruns) outside of the normal DDI suspend/resume
> framework for devices, this complexity seemed largely redundant.
>
>
> SOLUTION (SUMMARY)
>
> We therefore have come up with some changes to the audio DDI which will
> facilitate a number of changes, and another set of significant
> reductions in complexity for audio device drivers. (Indeed, in our work,
> these changes allow drivers like audiots and audio810 to run completely
> without any need for synchronization primitives, and with very little in
> the way of explicit code to support suspend/resume.)
>
>
> DETAILS
>
> We propose to add the following two functions:
>
> void audio_dev_suspend(audio_dev_t *);
> void audio_dev_resume(audio_dev_t *);
>
> The driver shall call these during DDI_SUSPEND and DDI_RESUME handling,
> respectively. The framework guarantees not to call any of the driver's
> entry points (either for controls or for engines) after audio_dev_suspend()
> returns, or before the driver calls audio_dev_resume().
>
> Additionally, the framework guarantees all audio engines will be be properly
> stopped during audio_dev_suspend(), and (if appropriate) restarted during
> audio_dev_resume(). (This is done using the audio_engine_t's entry points.)
>
> Furthermore, all audio controls will have their values saved and restored
> by these functions, provided that they are both readable and writable.
>
> Note that the driver must not be holding any locks while calling these
> suspend/resume functions, since they will call back into the driver.
>
> There is also a semantic requirement made of audio engines. Specifically
> it is now assumed that an audio_engine_t will perform a full reset of the
> engine (including resetting the processing index in the buffer to zero).
> The master count returned by audio_engine_count() must _not_, however,
> be reset. (Although it must stop incrementing between the calls to
> audio_engine_stop() and audio_engine_start(), as before.)
>
> As a consequence of these requirements, we are able to remove the exported
> audio_engine_reset() interface, as drivers no longer need to call it. (Its
> action is performed implicitly by the framework as part of audio_dev_resume()
> processing before the engine is restarted.)
>
> Additionally, the framework makes the following additional guarantees:
>
> 1. Each engine's entry points will be serialized. That is, no entry point
> for an audio_engine_t will be executed by the framework when any other
> entry point for the same audio_engine_t is active.
>
> 2. No entry point for an audio_ctrl_t on a given device (audio_dev_t)
> will be executed while any other entry points for audio_ctrl_t's on
> the same device are active.
>
> Ultimately, this means that if a device driver has no other need for an
> interrupt routine or asynchronous handling, and has separate state and
> registers for each of its engines (and collectively for its controls),
> the device can operate without any locks or explicit checks for suspended
> state on its hot code paths.
>
>
> AC'97 CHANGES
>
> With the above, we can also remove a lot of complexity from the AC'97 code
> which had explicit awareness and support for suspend/resume and concurrency.
>
> We therefore are removing the following two functions:
>
> ac97_suspend()
> ac97_resume()
>
> However, drivers which use AC'97 codecs must still perform a low-level
> reinitialization of the codec during DDI_RESUME handling. Previously
> this was performed by ac97_resume(). Instead, we now require the drivers
> to call ac97_reset(), which already existed.
>
>
> INTERFACE TABLES
>
> audio_dev_suspend() Cons. Private New function
> audio_dev_resume() " " " "
> audio_engine_reset() REMOVED REMOVED
> ac97_suspend() REMOVED REMOVED
> ac97_resume() REMOVED REMOVED
> ac97_reset() Cons. Private No change
> Synchronous guarantees Cons. Private New semantics
> audio_engine_start() Cons. Private New semantics
> audio_engine_stop() Cons. Private New semantics
>
>
> 6. Resources and Schedule
> 6.4. Steering Committee requested information
> 6.4.1. Consolidation C-team Name:
> ON
> 6.5. ARC review type: FastTrack
> 6.6. ARC Exposure: open
>
>
