git: 91dec580726f - main - sound: Document the locking protocol
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
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;