diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
index f2e59fe802bd7f3e45c9d4969291baaf5735d52f..4963d83d15118d332dedc2910b5e0836237689b0 100644
--- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
+++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
@@ -18,8 +18,8 @@
- October 6, 2005
- 0.3.5
+ November 17, 2005
+ 0.3.6
@@ -2329,9 +2329,14 @@ struct _snd_pcm_runtime {
PAUSE bit means that the pcm supports the
pause operation, while the
RESUME bit means that the pcm supports
- the suspend/resume operation. If these flags
- are set, the trigger callback below
- must handle the corresponding commands.
+ the full suspend/resume operation.
+ If PAUSE flag is set,
+ the trigger callback below
+ must handle the corresponding (pause push/release) commands.
+ The suspend/resume trigger commands can be defined even without
+ RESUME flag. See
+ Power Management section for details.
@@ -2903,8 +2908,8 @@ struct _snd_pcm_runtime {
- When the pcm supports the suspend/resume operation
- (i.e. SNDRV_PCM_INFO_RESUME flag is set),
+ When the pcm supports the suspend/resume operation,
+ regardless of full or partial suspend/resume support,
SUSPEND and RESUME
commands must be handled, too.
These commands are issued when the power-management status is
@@ -2913,6 +2918,8 @@ struct _snd_pcm_runtime {
do suspend and resume of the pcm substream, and usually, they
are identical with STOP and
START commands, respectively.
+ See
+ Power Management section for details.
@@ -5483,22 +5490,60 @@ struct _snd_pcm_runtime {
CONFIG_PM.
+
+ If the driver supports the suspend/resume
+ fully, that is, the device can be
+ properly resumed to the status at the suspend is called,
+ you can set SNDRV_PCM_INFO_RESUME flag
+ to pcm info field. Usually, this is possible when the
+ registers of ths chip can be safely saved and restored to the
+ RAM. If this is set, the trigger callback is called with
+ SNDRV_PCM_TRIGGER_RESUME after resume
+ callback is finished.
+
+
+
+ Even if the driver doesn't support PM fully but only the
+ partial suspend/resume is possible, it's still worthy to
+ implement suspend/resume callbacks. In such a case, applications
+ would reset the status by calling
+ snd_pcm_prepare() and restart the stream
+ appropriately. Hence, you can define suspend/resume callbacks
+ below but don't set SNDRV_PCM_INFO_RESUME
+ info flag to the PCM.
+
+
+
+ Note that the trigger with SUSPEND can be always called when
+ snd_pcm_suspend_all is called,
+ regardless of SNDRV_PCM_INFO_RESUME flag.
+ The RESUME flag affects only the behavior
+ of snd_pcm_resume().
+ (Thus, in theory,
+ SNDRV_PCM_TRIGGER_RESUME isn't needed
+ to be handled in the trigger callback when no
+ SNDRV_PCM_INFO_RESUME flag is set. But,
+ it's better to keep it for compatibility reason.)
+
- ALSA provides the common power-management layer. Each card driver
- needs to have only low-level suspend and resume callbacks.
+ In the earlier version of ALSA drivers, a common
+ power-management layer was provided, but it has been removed.
+ The driver needs to define the suspend/resume hooks according to
+ the bus the device is assigned. In the case of PCI driver, the
+ callbacks look like below:
- Retrieve the chip data from pm_private_data field.
+ Retrieve the card and the chip data.
+ Call snd_power_change_state() with
+ SNDRV_CTL_POWER_D3hot to change the
+ power status.Call snd_pcm_suspend_all() to suspend the running PCM streams.
+ If AC97 codecs are used, call
+ snd_ac97_resume() for each codec.Save the register values if necessary.Stop the hardware if necessary.
- Disable the PCI device by calling pci_disable_device().
+ Disable the PCI device by calling
+ pci_disable_device(). Then, call
+ pci_save_state() at last.
@@ -5525,18 +5577,24 @@ struct _snd_pcm_runtime {
pm_private_data;
+ struct snd_card *card = pci_get_drvdata(pci);
+ struct mychip *chip = card->private_data;
/* (2) */
- snd_pcm_suspend_all(chip->pcm);
+ snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
/* (3) */
- snd_mychip_save_registers(chip);
+ snd_pcm_suspend_all(chip->pcm);
/* (4) */
- snd_mychip_stop_hardware(chip);
+ snd_ac97_suspend(chip->ac97);
/* (5) */
- pci_disable_device(chip->pci);
+ snd_mychip_save_registers(chip);
+ /* (6) */
+ snd_mychip_stop_hardware(chip);
+ /* (7) */
+ pci_disable_device(pci);
+ pci_save_state(pci);
return 0;
}
]]>
@@ -5548,14 +5606,17 @@ struct _snd_pcm_runtime {
The scheme of the real resume job is as following.
- Retrieve the chip data from pm_private_data field.
- Enable the pci device again by calling
- pci_enable_device().
+ Retrieve the card and the chip data.
+ Set up PCI. First, call pci_restore_state().
+ Then enable the pci device again by calling pci_enable_device().
+ Call pci_set_master() if necessary, too.Re-initialize the chip.Restore the saved registers if necessary.Resume the mixer, e.g. calling
snd_ac97_resume().Restart the hardware (if any).
+ Call snd_power_change_state() with
+ SNDRV_CTL_POWER_D0 to notify the processes.
@@ -5565,12 +5626,15 @@ struct _snd_pcm_runtime {
pm_private_data;
+ struct snd_card *card = pci_get_drvdata(pci);
+ struct mychip *chip = card->private_data;
/* (2) */
- pci_enable_device(chip->pci);
+ pci_restore_state(pci);
+ pci_enable_device(pci);
+ pci_set_master(pci);
/* (3) */
snd_mychip_reinit_chip(chip);
/* (4) */
@@ -5579,6 +5643,8 @@ struct _snd_pcm_runtime {
snd_ac97_resume(chip->ac97);
/* (6) */
snd_mychip_restart_chip(chip);
+ /* (7) */
+ snd_power_change_state(card, SNDRV_CTL_POWER_D0);
return 0;
}
]]>
@@ -5587,8 +5653,48 @@ struct _snd_pcm_runtime {
- OK, we have all callbacks now. Let's set up them now. In the
- initialization of the card, add the following:
+ As shown in the above, it's better to save registers after
+ suspending the PCM operations via
+ snd_pcm_suspend_all() or
+ snd_pcm_suspend(). It means that the PCM
+ streams are already stoppped when the register snapshot is
+ taken. But, remind that you don't have to restart the PCM
+ stream in the resume callback. It'll be restarted via
+ trigger call with SNDRV_PCM_TRIGGER_RESUME
+ when necessary.
+
+
+
+ OK, we have all callbacks now. Let's set them up. In the
+ initialization of the card, make sure that you can get the chip
+ data from the card instance, typically via
+ private_data field, in case you
+ created the chip data individually.
+
+
+
+private_data = chip;
+ ....
+ }
+]]>
+
+
+
+ When you created the chip data with
+ snd_card_new(), it's anyway accessible
+ via private_data field.
@@ -5600,30 +5706,28 @@ struct _snd_pcm_runtime {
struct snd_card *card;
struct mychip *chip;
....
- snd_card_set_pm_callback(card, snd_my_suspend, snd_my_resume, chip);
+ card = snd_card_new(index[dev], id[dev], THIS_MODULE,
+ sizeof(struct mychip));
+ ....
+ chip = card->private_data;
....
}
]]>
- Here you don't have to put ifdef CONFIG_PM around, since it's already
- checked in the header and expanded to empty if not needed.
- If you need a space for saving the registers, you'll need to
- allocate the buffer for it here, too, since it would be fatal
+ If you need a space for saving the registers, allocate the
+ buffer for it here, too, since it would be fatal
if you cannot allocate a memory in the suspend phase.
The allocated buffer should be released in the corresponding
destructor.
- And next, set suspend/resume callbacks to the pci_driver,
- This can be done by passing a macro SND_PCI_PM_CALLBACKS
- in the pci_driver struct. This macro is expanded to the correct
- (global) callbacks if CONFIG_PM is set.
+ And next, set suspend/resume callbacks to the pci_driver.
@@ -5633,7 +5737,10 @@ struct _snd_pcm_runtime {
.id_table = snd_my_ids,
.probe = snd_my_probe,
.remove = __devexit_p(snd_my_remove),
- SND_PCI_PM_CALLBACKS
+ #ifdef CONFIG_PM
+ .suspend = snd_my_suspend,
+ .resume = snd_my_resume,
+ #endif
};
]]>