From nobody Wed Nov 18 10:24:43 2026 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4jTyQM6svGz71JPc for ; Wed, 18 Nov 2026 10:24:43 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 4jTyQM2ShNz4fpS for ; Wed, 18 Nov 2026 10:24:43 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1794997483; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=HR7W7hxwQ4xY4R48bxfMe7cq38zFG80kPXi9p+LtF/8=; b=XM0vheXQYUGJaQtbPedvp0Npkkq57uOmK/SM04zQMqtXh7HPjrOWIHXJd9O5EQAXHEmrjY rgXyVlxEOB3M2oMU99WIuMjk4/jEutikp7I+dtBuMZkqNygwlHxPo0kuu850Ed/7eJ0uvn N/41YEgTKBh/hbD3wYwmaHK/r7LmwmVPXTzhMrfgDVQNBf1OSWcSHVbz3mf0OF5laY+yLb 1GCCJPb8W6jBESLibzEm817RkJx3aIXW5vNjo23RK6Dp5Ug+NSNoqdr8xkJJvZCL8OlqGE F/M9xeNRRnmHpbDOzLfEN/dd6CZzjmo6gfpVYeqDo42EJ+o8mh57ofOtTYxLiQ== ARC-Seal: i=1; a=rsa-sha256; d=freebsd.org; s=dkim; cv=none; t=1794997483; b=pHC/W0DTXdV6G+AA2u6NgHbenbyU2dHu6LknZ4WZXrjHzT7zKsG47SCsArFwwA0LBmb64f pNaQrQ7hr3Lr73NBFQ2kQOb7MfoKMtAIjzeqk4W6BTDSMZz7mrJVZxmmhAkGltiBYoBtVf YpdddK/7f+mo4UOA9UbgXSOmBRDS5dfCAqxtmHaPZdzs6peDop/+ajqgtX8EdMRE3BWejU Ekn5n79EHrqrC9Uhi+azpFszzsAX5gaOWPsLQ8J2Me1Y4bOgkHnlgsV3liA9G5X9drdoLJ Ff/HNsDHmB2/H2u+Ta8KUT76qiy1mG+GCknVeN/MBoVEd/KN9ByP2LYmeO+B3g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1794997483; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=HR7W7hxwQ4xY4R48bxfMe7cq38zFG80kPXi9p+LtF/8=; b=EMs8DmvtJ+QvS4SA93AwdMu9MhKW6CnJfosGeUm2f1QcXye9IWA4fY2CNy0ubzEeBEfqhV XXNWY2pGKtLByKBo/t8gRA+YstnpbBNCzNaS4jMvDxLIfnJq9f+rFtp5ZvIpnw8wVsbrXw 0q+mbDXL9F/3LUVW2JPjaBylGjRqJUsSUAmG8a77DLWeHbpd83zBoQRtwnXmbsqRV9fQOH TXvun3jAUfhhrG9BIJYzKClb0FWUlxYSL3dK+9W6VzAU9DmFi6y1o7D4/+TYCPqyk1i/L8 IOpCRe0+3nPt2/71oTmt/nQrXWspCBIdp+bzFUi+oONdzMcfFIs6VoXIyasWPA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4jTyQM1Pw1z1P0g for ; Wed, 18 Nov 2026 10:24:43 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 5492 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Wed, 18 Nov 2026 10:24:43 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Christos Margiolis Subject: git: 91dec580726f - main - sound: Document the locking protocol List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all X-BeenThere: dev-commits-src-all@freebsd.org List-Id: Commit messages for all branches of the src repository List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: christos X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 91dec580726f02651d8b3e41617b3e4dec145e5f Auto-Submitted: auto-generated Date: Wed, 18 Nov 2026 10:24:43 +0000 Message-Id: <6afd7ceb.5492.43a15c21@gitrepo.freebsd.org> The branch main has been updated by christos: URL: https://cgit.FreeBSD.org/src/commit/?id=91dec580726f02651d8b3e41617b3e4dec145e5f commit 91dec580726f02651d8b3e41617b3e4dec145e5f Author: Christos Margiolis AuthorDate: 2026-11-18 10:22:29 +0000 Commit: Christos Margiolis 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;