From nobody Wed Oct 1 22:30:01 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5C7472EA74D; Wed, 1 Oct 2025 14:49:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1759330199; cv=none; b=WUkdiaplFiyFYtXajxXxAho1SUPPaJUZuwhogqDOZjMqe1La+P7hg8uEPs/5ocWx16jztzjcbjE9PYJ0QZY3H/I+fbll6d8DVEA3TrFD+n/gDd4EQqZj7c1HwZALhojEJBkwyPwlo7n1GBdywIyBMaw455qBc78z0gpgfuTVhKM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1759330199; c=relaxed/simple; bh=cpudc7RxxWHkEhpC0NFFpbwb/vOwgTPsZ8i0Bb1r0y4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=foAIvAzyj0rcD3CgBHeU/Z2g1Mh7g5HS5TFpwJGl26tSd1w85V4F88uGHCJeNJl1gBOXQYBrvNVOIpZbruxoTTKF16M/AZB9nfTLqShWsRrOVa6rHP8PPwhvjzsXm466jy817sfiCZKb4bRLApK4bF4kMW8PZvcOflD4gbxzxGI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LNTLK0bd; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="LNTLK0bd" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 171EFC4CEFC; Wed, 1 Oct 2025 14:49:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1759330199; bh=cpudc7RxxWHkEhpC0NFFpbwb/vOwgTPsZ8i0Bb1r0y4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LNTLK0bdEFGF1PCtKmj9vCgGEdMBQprPG8h3wkc9bzMAMcFUlie4WywkPrWbm1RDX 9qXIvxVQg5LbqTGbS3/BWvcPWO1NiKXSsJmYFRzHAHZUS1Xh53BmNUou8oP4z4rAIo 7pcKOziYZHwHQPN7hLaHFxCyI3YdX2WzCdFQJJjZWZJ4GKur7EqplW8OJ4wFj7F7S8 ljwMIgWaFSZfPMW4X9XL2rKlJJ0EB/Uxd9LZtlxqiQk0WZnjDhd7nk9AhZotjUAFfr yAInPl7iu3s5Vx+R3GWhs6/YIM/v/+nUoeajugEvuQ1ZiGR+ugoJSFBxu4MFohxa+V 2ZDqaWS0YkWqw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1v3y9V-0000000BLIR-1JUm; Wed, 01 Oct 2025 16:49:57 +0200 From: Mauro Carvalho Chehab To: "Jonathan Corbet" , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org, linux-media@vger.kernel.org Subject: [PATCH 07/23] tools: docs: parse_data_structs.py: add namespace support Date: Wed, 1 Oct 2025 16:49:30 +0200 Message-ID: X-Mailer: git-send-email 2.51.0 In-Reply-To: References: 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 Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" C domain supports a ".. c:namespace::" tag that allows setting a symbol namespace. This is used within the kernel to avoid warnings about duplicated symbols. This is specially important for syscalls, as each subsystem may have their own documentation for them. This is specially true for ioctl. When such tag is used, all C domain symbols have c++ style, e.g. they'll become "{namespace}.{reference}". Allow specifying C namespace at the exception files, avoiding the need of override rules for every symbol. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/lib/parse_data_structs.py | 43 +++++++++++++++++++++------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/tools/docs/lib/parse_data_structs.py b/tools/docs/lib/parse_da= ta_structs.py index cbdbf7dfe785..0d537e989ea7 100755 --- a/tools/docs/lib/parse_data_structs.py +++ b/tools/docs/lib/parse_data_structs.py @@ -53,11 +53,19 @@ class ParseDataStructs: =20 replace =20 - Replaces how old_symbol with a new reference. The new_reference can be: + Replaces how old_symbol with a new reference. The new_reference can= be: + - A simple symbol name; - A full Sphinx reference. =20 - On both cases, can be: + 3. Namespace rules + + namespace + + Sets C namespace to be used during cross-reference generation. Can + be overridden by replace rules. + + On ignore and replace rules, can be: - ioctl: for defines that end with _IO*, e.g. ioctl definitions - define: for other defines - symbol: for symbols defined within enums; @@ -71,6 +79,8 @@ class ParseDataStructs: ignore ioctl VIDIOC_ENUM_FMT replace ioctl VIDIOC_DQBUF vidioc_qbuf replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event= _motion_det` + + namespace MC """ =20 # Parser regexes with multiple ways to capture enums and structs @@ -140,6 +150,7 @@ class ParseDataStructs: =20 self.symbols =3D {} =20 + self.namespace =3D None self.ignore =3D [] self.replace =3D [] =20 @@ -173,6 +184,11 @@ class ParseDataStructs: match.group(3))) continue =20 + match =3D re.match(r"^namespace\s+(\S+)", line) + if match: + self.namespace =3D match.group(1) + continue + sys.exit(f"{name}:{ln}: invalid line: {line}") =20 def apply_exceptions(self): @@ -237,18 +253,23 @@ class ParseDataStructs: ref_type =3D defs.get("ref_type") =20 # Determine ref_link based on symbol type - if ref_type: - if symbol_type =3D=3D "enum": - ref_link =3D f"{ref_type}:`{symbol}`" - else: - if not ref_name: - ref_name =3D symbol.lower() + if ref_type or self.namespace: + if not ref_name: + ref_name =3D symbol.lower() =20 - # c-type references don't support hash - if ref_type =3D=3D ":ref" and replace_underscores: - ref_name =3D ref_name.replace("_", "-") + # c-type references don't support hash + if ref_type =3D=3D ":ref" and replace_underscores: + ref_name =3D ref_name.replace("_", "-") =20 + # C domain references may have namespaces + if ref_type.startswith(":c:"): + if self.namespace: + ref_name =3D f"{self.namespace}.{ref_name}" + + if ref_type: ref_link =3D f"{ref_type}:`{symbol} <{ref_name}>`" + else: + ref_link =3D f"`{symbol} <{ref_name}>`" else: ref_link =3D symbol =20 --=20 2.51.0