Commit:     6ca2cdcc5e40286e6bf5286056b50a56c8ce327e
Parent:     cb53c626e1145edf1d619bc4953f6293d3a77ace
Author:     Takashi Iwai <[EMAIL PROTECTED]>
AuthorDate: Fri Aug 10 17:22:34 2007 +0200
Committer:  Jaroslav Kysela <[EMAIL PROTECTED]>
CommitDate: Tue Oct 16 15:58:47 2007 +0200

    [ALSA] hda-codec - update of documentation
    Update the documentation to reflect the last changes regarding the
    power-saving mode and register caches.
    Signed-off-by: Takashi Iwai <[EMAIL PROTECTED]>
    Signed-off-by: Jaroslav Kysela <[EMAIL PROTECTED]>
 Documentation/sound/alsa/hda_codec.txt |   49 +++++++++++++++++++++++--------
 1 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/Documentation/sound/alsa/hda_codec.txt 
index 4eaae2a..8e1b025 100644
--- a/Documentation/sound/alsa/hda_codec.txt
+++ b/Documentation/sound/alsa/hda_codec.txt
@@ -49,6 +49,9 @@ struct hda_bus_ops {
                       unsigned int verb, unsigned int parm);
        unsigned int (*get_response)(struct hda_codec *codec);
        void (*private_free)(struct hda_bus *);
+       void (*pm_notify)(struct hda_codec *codec);
 The command callback is called when the codec module needs to send a
@@ -56,9 +59,16 @@ VERB to the controller.  It's always a single command.
 The get_response callback is called when the codec requires the answer
 for the last command.  These two callbacks are mandatory and have to
 be given.
-The last, private_free callback, is optional.  It's called in the
+The third, private_free callback, is optional.  It's called in the
 destructor to release any necessary data in the lowlevel driver.
+The pm_notify callback is available only with
+CONFIG_SND_HDA_POWER_SAVE kconfig.  It's called when the codec needs
+to power up or may power down.  The controller should check the all
+belonging codecs on the bus whether they are actually powered off
+(check codec->power_on), and optionally the driver may power down the
+contoller side, too.
 The bus instance is created via snd_hda_bus_new().  You need to pass
 the card instance, the template, and the pointer to store the
 resultant bus instance.
@@ -86,10 +96,8 @@ resultant codec instance (can be NULL if not needed).
 The codec is stored in a linked list of bus instance.  You can follow
 the codec list like:
-       struct list_head *p;
        struct hda_codec *codec;
-       list_for_each(p, &bus->codec_list) {
-               codec = list_entry(p, struct hda_codec, list);
+       list_for_each_entry(codec, &bus->codec_list, list) {
@@ -100,10 +108,15 @@ initialization sequence is called when the controls are 
built later.
 Codec Access
-To access codec, use snd_codec_read() and snd_codec_write().
+To access codec, use snd_hda_codec_read() and snd_hda_codec_write().
 snd_hda_param_read() is for reading parameters.
 For writing a sequence of verbs, use snd_hda_sequence_write().
+There are variants of cached read/write, snd_hda_codec_write_cache(),
+snd_hda_sequence_write_cache().  These are used for recording the
+register states for the power-mangement resume.  When no PM is needed,
+these are equivalent with non-cached version.
 To retrieve the number of sub nodes connected to the given node, use
 snd_hda_get_sub_nodes().  The connection list can be obtained via
 snd_hda_get_connections() call.
@@ -239,6 +252,10 @@ set the codec->patch_ops field.  This is defined as below:
                int (*suspend)(struct hda_codec *codec, pm_message_t state);
                int (*resume)(struct hda_codec *codec);
+               int (*check_power_status)(struct hda_codec *codec,
+                                         hda_nid_t nid);
+       #endif
 The build_controls callback is called from snd_hda_build_controls().
@@ -251,6 +268,18 @@ The unsol_event callback is called when an unsolicited 
event is
 The suspend and resume callbacks are for power management.
+They can be NULL if no special sequence is required.  When the resume
+callback is NULL, the driver calls the init callback and resumes the
+registers from the cache.  If other handling is needed, you'd need to
+write your own resume callback.  There, the amp values can be resumed
+       void snd_hda_codec_resume_amp(struct hda_codec *codec);
+and the other codec registers via
+       void snd_hda_codec_resume_cache(struct hda_codec *codec);
+The check_power_status callback is called when the amp value of the
+given widget NID is changed.  The codec code can turn on/off the power
+appropriately from this information.
 Each entry can be NULL if not necessary to be called.
@@ -267,8 +296,7 @@ Digital I/O
 Call snd_hda_create_spdif_out_ctls() from the patch to create controls
-related with SPDIF out.  In the patch resume callback, call
+related with SPDIF out.
 Helper Functions
@@ -284,12 +312,7 @@ as a module parameter, and PCI subsystem IDs.  If the 
matching entry
 is found, it returns the config field value.
 snd_hda_add_new_ctls() can be used to create and add control entries.
-Pass the zero-terminated array of struct snd_kcontrol_new.  The same array
-can be passed to snd_hda_resume_ctls() for resume.
-Note that this will call control->put callback of these entries.  So,
-put callback should check codec->in_resume and force to restore the
-given value if it's non-zero even if the value is identical with the
-cached value.
+Pass the zero-terminated array of struct snd_kcontrol_new
 Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be
 used for the entry of struct snd_kcontrol_new.
To unsubscribe from this list: send the line "unsubscribe git-commits-head" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at

Reply via email to