git: 91dec580726f - main - sound: Document the locking protocol

From: Christos Margiolis <christos_at_FreeBSD.org>
Date: Wed, 18 Nov 2026 10:24:43 UTC
The branch main has been updated by christos:

URL: https://cgit.FreeBSD.org/src/commit/?id=91dec580726f02651d8b3e41617b3e4dec145e5f

commit 91dec580726f02651d8b3e41617b3e4dec145e5f
Author:     Christos Margiolis <christos@FreeBSD.org>
AuthorDate: 2026-11-18 10:22:29 +0000
Commit:     Christos Margiolis <christos@FreeBSD.org>
CommitDate: 2026-11-18 10:22:29 +0000

    sound: Document the locking protocol
    
    MFC after:      2 weeks
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D60517
---
 sys/dev/sound/pcm/sound.h | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/sys/dev/sound/pcm/sound.h b/sys/dev/sound/pcm/sound.h
index 185159de84d1..c09ea120bcf0 100644
--- a/sys/dev/sound/pcm/sound.h
+++ b/sys/dev/sound/pcm/sound.h
@@ -157,6 +157,31 @@ void *pcm_getdevinfo(device_t dev);
 int snd_setup_intr(device_t dev, struct resource *res, int flags,
 		   driver_intr_t hand, void *param, void **cookiep);
 
+/*
+ * Locking protocol:
+ *
+ * Giant: Taken with PCM_GIANT_ENTER() or bus_topo_lock(). Used with non-MPSAFE
+ * drivers and when accessing the devclass, as well as for synchronizing device
+ * teardown.
+ *
+ * snddev_info->sx: Taken with PCM_ACQUIRE(). Busies the device and serializes
+ * writes to the flags (but not reads). It is held across sleeps and long
+ * operations: opening and closing the dsp cdev, creating and destroying
+ * channels, the ioctl and sysctl handlers, and detach. Holding it also blocks
+ * pcm_unregister() from destroying the device mid-operation, which is why
+ * handlers which never sleep also take the sx.
+ *
+ * snddev_info->lock: Taken with PCM_LOCK(). Also the primary mixer's lock (see
+ * mixer_obj_create()). It covers code which cannot sleep: the mixer, which is
+ * sometimes accessed from interrupt handlers, and channels.pcm.busy, mutated
+ * by chn_trigger(), which is only sometimes called with the sx already held.
+ *
+ * pcm_channel->lock: Taken with CHN_LOCK(). Covers the channel's own state.
+ *
+ * Lock order:
+ *
+ * Giant -> PCM_ACQUIRE() -> PCM_LOCK() -> CHN_LOCK(parent) -> CHN_LOCK(child).
+ */
 struct snddev_info {
 	struct {
 		struct {
@@ -178,14 +203,6 @@ struct snddev_info {
 	device_t dev;
 	char status[SND_STATUSLEN];
 	struct mtx lock;
-	/*
-	 * Unlike the mutex, this can be held across sleeps, in order to guard
-	 * long operations such as opening, closing and reconfiguring. It also
-	 * makes sure pcm_unregister() blocks until the operation finishes
-	 * before it tears down the channels. Drivers may change the flags
-	 * without it while attaching, since the device is not yet visible to
-	 * userland.
-	 */
 	struct sx sx;
 	struct cdev *dsp_dev;
 	struct snd_mixer *mixer;