aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTakashi Iwai <tiwai@suse.de>2007-08-10 11:22:34 -0400
committerJaroslav Kysela <perex@perex.cz>2007-10-16 09:58:47 -0400
commit6ca2cdcc5e40286e6bf5286056b50a56c8ce327e (patch)
tree559d8c9f9ee312d0808274569dcc718335f8df4a
parentcb53c626e1145edf1d619bc4953f6293d3a77ace (diff)
[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>
-rw-r--r--Documentation/sound/alsa/hda_codec.txt49
1 files changed, 36 insertions, 13 deletions
diff --git a/Documentation/sound/alsa/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt
index 4eaae2a45534..8e1b02526698 100644
--- a/Documentation/sound/alsa/hda_codec.txt
+++ b/Documentation/sound/alsa/hda_codec.txt
@@ -49,6 +49,9 @@ struct hda_bus_ops {
49 unsigned int verb, unsigned int parm); 49 unsigned int verb, unsigned int parm);
50 unsigned int (*get_response)(struct hda_codec *codec); 50 unsigned int (*get_response)(struct hda_codec *codec);
51 void (*private_free)(struct hda_bus *); 51 void (*private_free)(struct hda_bus *);
52#ifdef CONFIG_SND_HDA_POWER_SAVE
53 void (*pm_notify)(struct hda_codec *codec);
54#endif
52}; 55};
53 56
54The command callback is called when the codec module needs to send a 57The 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.
56The get_response callback is called when the codec requires the answer 59The get_response callback is called when the codec requires the answer
57for the last command. These two callbacks are mandatory and have to 60for the last command. These two callbacks are mandatory and have to
58be given. 61be given.
59The last, private_free callback, is optional. It's called in the 62The third, private_free callback, is optional. It's called in the
60destructor to release any necessary data in the lowlevel driver. 63destructor to release any necessary data in the lowlevel driver.
61 64
65The pm_notify callback is available only with
66CONFIG_SND_HDA_POWER_SAVE kconfig. It's called when the codec needs
67to power up or may power down. The controller should check the all
68belonging codecs on the bus whether they are actually powered off
69(check codec->power_on), and optionally the driver may power down the
70contoller side, too.
71
62The bus instance is created via snd_hda_bus_new(). You need to pass 72The bus instance is created via snd_hda_bus_new(). You need to pass
63the card instance, the template, and the pointer to store the 73the card instance, the template, and the pointer to store the
64resultant bus instance. 74resultant bus instance.
@@ -86,10 +96,8 @@ resultant codec instance (can be NULL if not needed).
86The codec is stored in a linked list of bus instance. You can follow 96The codec is stored in a linked list of bus instance. You can follow
87the codec list like: 97the codec list like:
88 98
89 struct list_head *p;
90 struct hda_codec *codec; 99 struct hda_codec *codec;
91 list_for_each(p, &bus->codec_list) { 100 list_for_each_entry(codec, &bus->codec_list, list) {
92 codec = list_entry(p, struct hda_codec, list);
93 ... 101 ...
94 } 102 }
95 103
@@ -100,10 +108,15 @@ initialization sequence is called when the controls are built later.
100Codec Access 108Codec Access
101============ 109============
102 110
103To access codec, use snd_codec_read() and snd_codec_write(). 111To access codec, use snd_hda_codec_read() and snd_hda_codec_write().
104snd_hda_param_read() is for reading parameters. 112snd_hda_param_read() is for reading parameters.
105For writing a sequence of verbs, use snd_hda_sequence_write(). 113For writing a sequence of verbs, use snd_hda_sequence_write().
106 114
115There are variants of cached read/write, snd_hda_codec_write_cache(),
116snd_hda_sequence_write_cache(). These are used for recording the
117register states for the power-mangement resume. When no PM is needed,
118these are equivalent with non-cached version.
119
107To retrieve the number of sub nodes connected to the given node, use 120To retrieve the number of sub nodes connected to the given node, use
108snd_hda_get_sub_nodes(). The connection list can be obtained via 121snd_hda_get_sub_nodes(). The connection list can be obtained via
109snd_hda_get_connections() call. 122snd_hda_get_connections() call.
@@ -239,6 +252,10 @@ set the codec->patch_ops field. This is defined as below:
239 int (*suspend)(struct hda_codec *codec, pm_message_t state); 252 int (*suspend)(struct hda_codec *codec, pm_message_t state);
240 int (*resume)(struct hda_codec *codec); 253 int (*resume)(struct hda_codec *codec);
241 #endif 254 #endif
255 #ifdef CONFIG_SND_HDA_POWER_SAVE
256 int (*check_power_status)(struct hda_codec *codec,
257 hda_nid_t nid);
258 #endif
242 }; 259 };
243 260
244The build_controls callback is called from snd_hda_build_controls(). 261The 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
251received. 268received.
252 269
253The suspend and resume callbacks are for power management. 270The suspend and resume callbacks are for power management.
271They can be NULL if no special sequence is required. When the resume
272callback is NULL, the driver calls the init callback and resumes the
273registers from the cache. If other handling is needed, you'd need to
274write your own resume callback. There, the amp values can be resumed
275via
276 void snd_hda_codec_resume_amp(struct hda_codec *codec);
277and the other codec registers via
278 void snd_hda_codec_resume_cache(struct hda_codec *codec);
279
280The check_power_status callback is called when the amp value of the
281given widget NID is changed. The codec code can turn on/off the power
282appropriately from this information.
254 283
255Each entry can be NULL if not necessary to be called. 284Each entry can be NULL if not necessary to be called.
256 285
@@ -267,8 +296,7 @@ Digital I/O
267=========== 296===========
268 297
269Call snd_hda_create_spdif_out_ctls() from the patch to create controls 298Call snd_hda_create_spdif_out_ctls() from the patch to create controls
270related with SPDIF out. In the patch resume callback, call 299related with SPDIF out.
271snd_hda_resume_spdif().
272 300
273 301
274Helper Functions 302Helper Functions
@@ -284,12 +312,7 @@ as a module parameter, and PCI subsystem IDs. If the matching entry
284is found, it returns the config field value. 312is found, it returns the config field value.
285 313
286snd_hda_add_new_ctls() can be used to create and add control entries. 314snd_hda_add_new_ctls() can be used to create and add control entries.
287Pass the zero-terminated array of struct snd_kcontrol_new. The same array 315Pass the zero-terminated array of struct snd_kcontrol_new
288can be passed to snd_hda_resume_ctls() for resume.
289Note that this will call control->put callback of these entries. So,
290put callback should check codec->in_resume and force to restore the
291given value if it's non-zero even if the value is identical with the
292cached value.
293 316
294Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be 317Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be
295used for the entry of struct snd_kcontrol_new. 318used for the entry of struct snd_kcontrol_new.