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
