[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 <tiwai@suse.de>
Signed-off-by: Jaroslav Kysela <perex@suse.cz>

1 files changed, 36 insertions, 13 deletions

diff --git a/Documentation/sound/alsa/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt
index 4eaae2a4553..8e1b0252669 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 *);
+#ifdef CONFIG_SND_HDA_POWER_SAVE
+        void (*pm_notify)(struct hda_codec *codec);
+#endif
 };
 
 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);
         #endif
+        #ifdef CONFIG_SND_HDA_POWER_SAVE
+                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
 received.
 
 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
+via
+        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
-snd_hda_resume_spdif().
+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.