diff options
author | Takashi Iwai <tiwai@suse.de> | 2007-08-10 11:22:34 -0400 |
---|---|---|
committer | Jaroslav Kysela <perex@perex.cz> | 2007-10-16 09:58:47 -0400 |
commit | 6ca2cdcc5e40286e6bf5286056b50a56c8ce327e (patch) | |
tree | 559d8c9f9ee312d0808274569dcc718335f8df4a | |
parent | cb53c626e1145edf1d619bc4953f6293d3a77ace (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.txt | 49 |
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 | ||
54 | The command callback is called when the codec module needs to send a | 57 | 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. | |||
56 | The get_response callback is called when the codec requires the answer | 59 | The get_response callback is called when the codec requires the answer |
57 | for the last command. These two callbacks are mandatory and have to | 60 | for the last command. These two callbacks are mandatory and have to |
58 | be given. | 61 | be given. |
59 | The last, private_free callback, is optional. It's called in the | 62 | The third, private_free callback, is optional. It's called in the |
60 | destructor to release any necessary data in the lowlevel driver. | 63 | destructor to release any necessary data in the lowlevel driver. |
61 | 64 | ||
65 | The pm_notify callback is available only with | ||
66 | CONFIG_SND_HDA_POWER_SAVE kconfig. It's called when the codec needs | ||
67 | to power up or may power down. The controller should check the all | ||
68 | belonging codecs on the bus whether they are actually powered off | ||
69 | (check codec->power_on), and optionally the driver may power down the | ||
70 | contoller side, too. | ||
71 | |||
62 | The bus instance is created via snd_hda_bus_new(). You need to pass | 72 | The bus instance is created via snd_hda_bus_new(). You need to pass |
63 | the card instance, the template, and the pointer to store the | 73 | the card instance, the template, and the pointer to store the |
64 | resultant bus instance. | 74 | resultant bus instance. |
@@ -86,10 +96,8 @@ resultant codec instance (can be NULL if not needed). | |||
86 | The codec is stored in a linked list of bus instance. You can follow | 96 | The codec is stored in a linked list of bus instance. You can follow |
87 | the codec list like: | 97 | the 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. | |||
100 | Codec Access | 108 | Codec Access |
101 | ============ | 109 | ============ |
102 | 110 | ||
103 | To access codec, use snd_codec_read() and snd_codec_write(). | 111 | To access codec, use snd_hda_codec_read() and snd_hda_codec_write(). |
104 | snd_hda_param_read() is for reading parameters. | 112 | snd_hda_param_read() is for reading parameters. |
105 | For writing a sequence of verbs, use snd_hda_sequence_write(). | 113 | For writing a sequence of verbs, use snd_hda_sequence_write(). |
106 | 114 | ||
115 | There are variants of cached read/write, snd_hda_codec_write_cache(), | ||
116 | snd_hda_sequence_write_cache(). These are used for recording the | ||
117 | register states for the power-mangement resume. When no PM is needed, | ||
118 | these are equivalent with non-cached version. | ||
119 | |||
107 | To retrieve the number of sub nodes connected to the given node, use | 120 | To retrieve the number of sub nodes connected to the given node, use |
108 | snd_hda_get_sub_nodes(). The connection list can be obtained via | 121 | snd_hda_get_sub_nodes(). The connection list can be obtained via |
109 | snd_hda_get_connections() call. | 122 | snd_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 | ||
244 | The build_controls callback is called from snd_hda_build_controls(). | 261 | 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 | |||
251 | received. | 268 | received. |
252 | 269 | ||
253 | The suspend and resume callbacks are for power management. | 270 | The suspend and resume callbacks are for power management. |
271 | They can be NULL if no special sequence is required. When the resume | ||
272 | callback is NULL, the driver calls the init callback and resumes the | ||
273 | registers from the cache. If other handling is needed, you'd need to | ||
274 | write your own resume callback. There, the amp values can be resumed | ||
275 | via | ||
276 | void snd_hda_codec_resume_amp(struct hda_codec *codec); | ||
277 | and the other codec registers via | ||
278 | void snd_hda_codec_resume_cache(struct hda_codec *codec); | ||
279 | |||
280 | The check_power_status callback is called when the amp value of the | ||
281 | given widget NID is changed. The codec code can turn on/off the power | ||
282 | appropriately from this information. | ||
254 | 283 | ||
255 | Each entry can be NULL if not necessary to be called. | 284 | Each entry can be NULL if not necessary to be called. |
256 | 285 | ||
@@ -267,8 +296,7 @@ Digital I/O | |||
267 | =========== | 296 | =========== |
268 | 297 | ||
269 | Call snd_hda_create_spdif_out_ctls() from the patch to create controls | 298 | Call snd_hda_create_spdif_out_ctls() from the patch to create controls |
270 | related with SPDIF out. In the patch resume callback, call | 299 | related with SPDIF out. |
271 | snd_hda_resume_spdif(). | ||
272 | 300 | ||
273 | 301 | ||
274 | Helper Functions | 302 | Helper Functions |
@@ -284,12 +312,7 @@ as a module parameter, and PCI subsystem IDs. If the matching entry | |||
284 | is found, it returns the config field value. | 312 | is found, it returns the config field value. |
285 | 313 | ||
286 | snd_hda_add_new_ctls() can be used to create and add control entries. | 314 | snd_hda_add_new_ctls() can be used to create and add control entries. |
287 | Pass the zero-terminated array of struct snd_kcontrol_new. The same array | 315 | Pass the zero-terminated array of struct snd_kcontrol_new |
288 | can be passed to snd_hda_resume_ctls() for resume. | ||
289 | Note that this will call control->put callback of these entries. So, | ||
290 | put callback should check codec->in_resume and force to restore the | ||
291 | given value if it's non-zero even if the value is identical with the | ||
292 | cached value. | ||
293 | 316 | ||
294 | Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be | 317 | Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be |
295 | used for the entry of struct snd_kcontrol_new. | 318 | used for the entry of struct snd_kcontrol_new. |