From nobody Mon Apr 6 21:59:15 2026 Received: from mail-ed1-f48.google.com (mail-ed1-f48.google.com [209.85.208.48]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 126FF3AB273 for ; Tue, 17 Mar 2026 15:12:30 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.208.48 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773760352; cv=none; b=Lrh0GWGdVeXmML996ccoREZnbdJWSF1gYQw/qfO694g3sIwiNJIY0CDl3s8cLa0i8PPNUIejbo3G9ITxWwBiQM4UpdjjBrSBQeFoP5tDt2aJF1XqQjJSIl84XC4Gv3PbSTzseNAlaRn5EuvwwQD6a1Wy2khxXp45mhoK8jsze0E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773760352; c=relaxed/simple; bh=ElmNSzj36ahoXwShZ7ULHU6+01vzlQ4NHHLLRiYgGxg=; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version; b=l6/nvLiNJuoH6v34256swDzpIVDY6BfQ0BTpACmHhwAhOviWxxJ8LIEtdVnPqRHxaTMHZhIn3iYNBTCA8dGwqGEHQqwp6Zc6uTwHpBG9IaqBKWUnvfH0cdAwfuo3YpQp9U3g6/BoLGgumxoPv+yZ1iTmZqlNK1SGF0AHhEf9xU8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=gXl7RI9L; arc=none smtp.client-ip=209.85.208.48 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="gXl7RI9L" Received: by mail-ed1-f48.google.com with SMTP id 4fb4d7f45d1cf-660a58841d4so7612285a12.0 for ; Tue, 17 Mar 2026 08:12:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1773760349; x=1774365149; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=VoX0sLLhblCiEStIbiYJ15WT9ZZm3Qh1HEveUrVMolU=; b=gXl7RI9LbF78N95CqGOM2TXN6jazS1z8B5nh8JpDCHm2hlXoKv0hMmCoJHglbd9qD9 Qcn+MxmZqt2MVkNJfcuYIz2DjLWAy7U7TmojrSrvZDgkIMRPDQz2mBymNt3eWmllgqAb YiIWitQ7FCQbybkb1blmjGMPIDhyMnBDqOKB4uLoS3uKTMr7pwjqzfE7y3F75V8JBY+N p+Lz0d9VGeUzeCDS0ffKkEmB3k98G4WX5VD80cju0s5TdiMbfXDoaU8skGm8+DhGuiLB CtQKU3RsbQnrFalL9ZHm4TD0CEC0mwIFqpTit7TpO0tBOSeKWRHMznsZ+5LcUIY9LKEp SWRg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1773760349; x=1774365149; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=VoX0sLLhblCiEStIbiYJ15WT9ZZm3Qh1HEveUrVMolU=; b=Yk3lp4za0xLq4e5nF2H9gAwL6QfjbRaFgxzNYOZXupjlqIZ+lTC74V5qw+EwoGs+hk P+pMaJsyKbv0p9xRgfhiDTLDQ03voQA4tH+/cb5fhv14sny68RnhUaL3affZ1R6Ufa7v 2CTCA9PY8FhgGuxuc2zD33UPS3HJFoKjEPY27f36DVTL3BCSLr+gL11EoNdDNyXAjloc meBXE4rsDdb6anLWrZ8g1dPvjL8mTSIJIb7HrU4yMLf0q9PFdXYt7bfUVHoYZCuTXHJU N2RUZxaeUA2aYjjTQ15odJGA2fC2/zpsWRjFrBHxob6C5LGmi9K414P9AEXg1cNVXigw oyZQ== X-Forwarded-Encrypted: i=1; AJvYcCXKKuVxz64T3rad15JomliBwsGD5dBoYSCxD6GmzEZpJ2U4br+CRbaQFkfOVksKhRdVfVB+VbcizAYN71o=@vger.kernel.org X-Gm-Message-State: AOJu0YzJw91sSSsOkNazL5djA1VeVer80Mk4gm01F1UiRydggee+or89 YD7UFHHBFOBu1ZLXljOO6aWeHQwCq0UB/6vVy2ST6QRo0tufv3T7XiRt X-Gm-Gg: ATEYQzxu1rUiKCAGTr+AViDu5xqq/cr/HFOAA6maoPnyknIrlsZCB8IJN1+5bHYyWMU zmSyjgf/QhQw/aOMvsUcOK+cOGZgUayt4WELlljlMwlBk/n8vmC+d3B83E29oPOqRafNHLefKeY DSNK2fobLeT11uzeLC5gG8RN1In9P9DFOqso3LOFzKqzmDCgrjQelA2DIZCoa2/TNCoCyHqQBtg uqCtEuQSCIWW3K7vtdm6MHXhgeuRHX/uygPAd5ecc2E5EvGn3F8tX7GYDpIAKzPlEhx/0w9/Kc+ 75/ZN4hQoeuokG00bpL0UEwWGY+ubhbHvF949GYmAS4vAlkQ+A4rTofbzl3x5oqSxO8djaEaj/E bHLu26jSZZ/41ppYdHKKYIiAhOoUstHfwT1loiJIOxUHpCGknvQgvl5K30BZCq5mA1DHZ7S9iUQ +HMUrGMFpL+snkoNCa7ZH8V0aKSRTDFsGOfI5MoO9MhVpS X-Received: by 2002:a17:907:7fa2:b0:b97:ad82:973f with SMTP id a640c23a62f3a-b97ad829ee0mr546189866b.13.1773760349135; Tue, 17 Mar 2026 08:12:29 -0700 (PDT) Received: from localhost.localdomain ([72.255.58.127]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-b97f1460749sm3876966b.26.2026.03.17.08.12.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 17 Mar 2026 08:12:28 -0700 (PDT) From: Mahad Ibrahim To: corbet@lwn.net Cc: skhan@linuxfoundation.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, mahad.ibrahim.dev@gmail.com Subject: [PATCH] docs: fix Sphinx C parser crash on __cond_acquires macro Date: Tue, 17 Mar 2026 11:11:56 -0400 Message-Id: <20260317151156.1106-1-mahad.ibrahim.dev@gmail.com> X-Mailer: git-send-email 2.39.5 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" When building the kernel-docs, the Sphinx C parser threw two errors: 1. /home/code/linux/Documentation/core-api/kref:328: ./include/linux/kref.h:72: WARNING: Invalid C declaration: Expected end of definition. [error at 96] int kref_put_mutex ( struct kref *kref, void (*release) (struct kref *kref), struct mutex *mutex) __cond_acquires(true# mutex) 2. /home/code/linux/Documentation/core-api/kref:328: ./include/linux/kref.h:94: WARNING: Invalid C declaration: Expected end of definition. [error at 92] int kref_put_lock ( struct kref *kref, void (*release)(struct kref *kref), spinlock_t *lock) __cond_acquires(true# lock) The root cause of these errors is due to the parser's inability to understand sparse __cond_acquires() parameterized macro attached to the function. The parser expects a ';' or a '{' to verify a valid function signature ending. As of Sphinx 3.0, the parser is equipped to handle such cases via the c_paren_attributes list however that functionality was not adopted. Out of all sparse/compiler-based context analysis parameterized macros inside the kernel, only __cond_acquires appears in the context of a kernel-docs comment and function, which is why it is the only macro that threw an error. This bug may be attributed to the kernel's recent shift from sparse to compiler-based context analysis, increased strictness of Sphinx C parser, or some other change which transcended domains. Add c_paren_attributes to enable Sphinx parser to handle parameterized function macros like __cond_acquires. Signed-off-by: Mahad Ibrahim --- Documentation/conf.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/conf.py b/Documentation/conf.py index 679861503a25..f2efe7fd107e 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -227,6 +227,13 @@ c_id_attributes =3D [ "__bpf_kfunc", ] =20 +# Since Sphinx 3.0, parameterized macros must be escaped using +# c_paren_attributes to prevent C domain parser crashes. +c_paren_attributes =3D [ + #include/linux/compiler-context-analysis.h + "__cond_acquires", +] + # Ensure that autosectionlabel will produce unique names autosectionlabel_prefix_document =3D True autosectionlabel_maxdepth =3D 2 --=20 2.39.5