From: Takashi Iwai <tiwai@suse.de>
To: alsa-devel@alsa-project.org
Subject: [alsa-devel] [PATCH 8/8] ALSA: docs: Update about the new PCM sync_stop ops
Date: Sun, 17 Nov 2019 09:53:08 +0100 [thread overview]
Message-ID: <20191117085308.23915-9-tiwai@suse.de> (raw)
In-Reply-To: <20191117085308.23915-1-tiwai@suse.de>
Add the documentation about the new PCM sync_stop ops and
card->sync_irq field.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
.../sound/kernel-api/writing-an-alsa-driver.rst | 41 ++++++++++++++++++++++
1 file changed, 41 insertions(+)
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 145bf6aad7cb..f169d58ca019 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -805,6 +805,7 @@ destructor and PCI entries. Example code is shown first, below.
return -EBUSY;
}
chip->irq = pci->irq;
+ card->sync_irq = chip->irq;
/* (2) initialization of the chip hardware */
.... /* (not implemented in this document) */
@@ -965,6 +966,15 @@ usually like the following:
return IRQ_HANDLED;
}
+After requesting the IRQ, you can passed it to ``card->sync_irq``
+field:
+::
+
+ card->irq = chip->irq;
+
+This allows PCM core automatically performing
+:c:func:`synchronize_irq()` at the necessary timing like ``hw_free``.
+See the later section `sync_stop callback`_ for details.
Now let's write the corresponding destructor for the resources above.
The role of destructor is simple: disable the hardware (if already
@@ -2059,6 +2069,37 @@ flag set, and you cannot call functions which may sleep. The
triggering the DMA. The other stuff should be initialized
``hw_params`` and ``prepare`` callbacks properly beforehand.
+sync_stop callback
+~~~~~~~~~~~~~~~~~~
+
+::
+
+ static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
+
+This callback is optional, and NULL can be passed. It's called after
+the PCM core stops the stream and changes the stream state
+``prepare``, ``hw_params`` or ``hw_free``.
+Since the IRQ handler might be still pending, we need to wait until
+the pending task finishes before moving to the next step; otherwise it
+might lead to a crash due to resource conflicts or access to the freed
+resources. A typical behavior is to call a synchronization function
+like :c:func:`synchronize_irq()` here.
+
+For majority of drivers that need only a call of
+:c:func:`synchronize_irq()`, there is a simpler setup, too.
+While keeping NULL to ``sync_stop`` PCM callback, the driver can set
+``card->sync_irq`` field to store the valid interrupt number after
+requesting an IRQ, instead. Then PCM core will look call
+:c:func:`synchronize_irq()` with the given IRQ appropriately.
+
+If the IRQ handler is released at the card destructor, you don't need
+to clear ``card->sync_irq``, as the card itself is being released.
+So, usually you'll need to add just a single line for assigning
+``card->sync_irq`` in the driver code unless the driver re-acquires
+the IRQ. When the driver frees and re-acquires the IRQ dynamically
+(e.g. for suspend/resume), it needs to clear and re-set
+``card->sync_irq`` again appropriately.
+
pointer callback
~~~~~~~~~~~~~~~~
--
2.16.4
_______________________________________________
Alsa-devel mailing list
Alsa-devel@alsa-project.org
https://mailman.alsa-project.org/mailman/listinfo/alsa-devel
prev parent reply other threads:[~2019-11-17 9:00 UTC|newest]
Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-11-17 8:53 [alsa-devel] [PATCH 0/8] ALSA: pcm: API cleanups and extensions Takashi Iwai
2019-11-17 8:53 ` [alsa-devel] [PATCH 1/8] ALSA: pcm: Introduce managed buffer allocation mode Takashi Iwai
2019-11-18 16:24 ` Pierre-Louis Bossart
2019-11-18 18:46 ` Takashi Iwai
2019-11-17 8:53 ` [alsa-devel] [PATCH 2/8] ALSA: docs: Update for " Takashi Iwai
2019-11-17 8:53 ` [alsa-devel] [PATCH 3/8] ALSA: pcm: Allow NULL ioctl ops Takashi Iwai
2019-11-17 8:53 ` [alsa-devel] [PATCH 4/8] ALSA: docs: Update document about the default PCM " Takashi Iwai
2019-11-17 8:53 ` [alsa-devel] [PATCH 5/8] ALSA: pcm: Move PCM_RUNTIME_CHECK() macro into local header Takashi Iwai
2019-11-17 9:42 ` kbuild test robot
2019-11-17 10:05 ` Takashi Iwai
2019-11-17 10:28 ` kbuild test robot
2019-11-17 8:53 ` [alsa-devel] [PATCH 6/8] ALSA: pcm: Add the support for sync-stop operation Takashi Iwai
2019-11-18 16:33 ` Pierre-Louis Bossart
2019-11-18 18:47 ` Takashi Iwai
2019-11-17 8:53 ` [alsa-devel] [PATCH 7/8] ALSA: pcm: Add card sync_irq field Takashi Iwai
2019-11-18 16:38 ` Pierre-Louis Bossart
2019-11-18 18:52 ` Takashi Iwai
2019-11-18 19:20 ` Sridharan, Ranjani
2019-11-18 19:49 ` Takashi Iwai
2019-11-18 19:55 ` Sridharan, Ranjani
2019-11-18 20:40 ` Takashi Iwai
2019-11-18 23:47 ` Ranjani Sridharan
2019-11-19 6:44 ` Takashi Iwai
2019-11-19 7:40 ` Ranjani Sridharan
2019-11-19 8:24 ` Takashi Iwai
2019-11-19 9:39 ` Takashi Iwai
2019-11-19 16:36 ` Ranjani Sridharan
2019-11-19 21:27 ` Takashi Iwai
2019-11-19 21:43 ` Sridharan, Ranjani
2019-11-21 19:22 ` Sridharan, Ranjani
2019-11-21 20:34 ` Takashi Iwai
2019-11-21 20:46 ` Sridharan, Ranjani
2019-11-21 21:13 ` Takashi Iwai
2019-11-21 21:17 ` Sridharan, Ranjani
2019-11-21 21:28 ` Takashi Iwai
2019-11-21 21:45 ` Sridharan, Ranjani
2019-11-22 4:08 ` Jie, Yang
2019-11-17 8:53 ` Takashi Iwai [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20191117085308.23915-9-tiwai@suse.de \
--to=tiwai@suse.de \
--cc=alsa-devel@alsa-project.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).