From nobody Wed Oct 1 21:24:19 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 A49602FDC37; 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=iimyCvGeN6UYZczIrPrhmHSWpk1AnFuPhDx4oqwxkBsXTBhAimTPdfONbI46RrDQtQ87+mO3s9TKkfuyt65vK+BCywQl8IqxHG/xrGmwyn6Nx4SUMaTp1spe5tvf5mu7DvXQjWXQuqfOzdYGL2MlEQ42S2y+Ei/idKm/nDTOCe8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1759330199; c=relaxed/simple; bh=7G19TBRqcSSvnXToM3u1Uoshyb2F1JhNkDvRwLoG1lg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=oJy//TvEwJKtlwtYH3c9BvAcm42TPuci/3SPWuMJVrhozaiioNq6/bP99MKxys5iq0Gs03/FWh4v/IYDtFe3aqXb2Cno/drh765ZtufB41B59nmsXxRbBhncZbikUbq/rzVauyqyJTEFlCHBDIXYfbIOKwTaPB3tgh8MvywMYmY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=h21DCwwn; 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="h21DCwwn" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 020F2C4CEFB; 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=7G19TBRqcSSvnXToM3u1Uoshyb2F1JhNkDvRwLoG1lg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=h21DCwwnNnwhWIgt4Nd/lj/Rg4FGlP3XWSWdLWAfdgLQf4PmN8DaAC3zSndlrfvfn CsqAf2f38Jcu2Bexz1Clg8HdEYscqSpXU+U9Y8z4D5DOs/CGWApyaxeVfmA+1Q1a+p 5jra5MRayKt7kU4RN4YsUzIuBiIGwZ1LiNDDDslPfAGznWaJrQJCAcgOe0qDXtiIoh JlK2a6BdpUPen0SMZwuOhdQ7Tan7v8iy3olTklAJWrOvr5VMEOBNa4usMMJlI6/IUl LR6yBikgOYGLIks7WLVpUhVsvSV0aaMLMX9pNIME134kKw5laL5AFHKoZJJTP6ItBW ON8UiGgOn65/g== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1v3y9V-0000000BLIF-0xSI; 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" , Benjamin Gaignard , Hans Verkuil , Hans de Goede , Ricardo Ribalda , Yunke Cao , linux-kernel@vger.kernel.org, linux-media@vger.kernel.org Subject: [PATCH 04/23] docs: kernel_include.py: propose alternatives Date: Wed, 1 Oct 2025 16:49:27 +0200 Message-ID: <4c75d277e950e619ea00ba2dea336853a4aac976.1759329363.git.mchehab+huawei@kernel.org> 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" Specially when using c::namespace, it is not hard to break a reference by forgetting to add a domain. Also, different cases and using "-"/"_" the wrong way are typical cases that people often gets wrong. We might use a more complex logic here to also check for typos, but let's keep it plain, simple. This is enough to get thos exeptions from media controller: .../include/uapi/linux/media.h:26: WARNING: Invalid xref: c:type:`media_d= evice_info`. Possible alternatives: c:type:`MC.media_device_info` (from mediactl/media-ioc-device-info) .../include/uapi/linux/media.h:149: WARNING: Invalid xref: c:type:`media_= entity_desc`. Possible alternatives: c:type:`MC.media_entity_desc` (from mediactl/media-ioc-enum-entities) .../include/uapi/linux/media.h:228: WARNING: Invalid xref: c:type:`media_= link_desc`. Possible alternatives: c:type:`MC.media_link_desc` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:235: WARNING: Invalid xref: c:type:`media_= links_enum`. Possible alternatives: c:type:`MC.media_links_enum` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:212: WARNING: Invalid xref: c:type:`media_= pad_desc`. Possible alternatives: c:type:`MC.media_pad_desc` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:298: WARNING: Invalid xref: c:type:`media_= v2_entity`. Possible alternatives: c:type:`MC.media_v2_entity` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:312: WARNING: Invalid xref: c:type:`media_= v2_interface`. Possible alternatives: c:type:`MC.media_v2_interface` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:307: WARNING: Invalid xref: c:type:`media_= v2_intf_devnode`. Possible alternatives: c:type:`MC.media_v2_intf_devnode` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:341: WARNING: Invalid xref: c:type:`media_= v2_link`. Possible alternatives: c:type:`MC.media_v2_link` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:333: WARNING: Invalid xref: c:type:`media_= v2_pad`. Possible alternatives: c:type:`MC.media_v2_pad` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:349: WARNING: Invalid xref: c:type:`media_= v2_topology`. Possible alternatives: c:type:`MC.media_v2_topology` (from mediactl/media-ioc-g-topology) Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/kernel_include.py | 70 ++++++++++++++++++- .../userspace-api/media/v4l/videodev.rst | 8 ++- .../media/v4l/videodev2.h.rst.exceptions | 3 + 3 files changed, 77 insertions(+), 4 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/= kernel_include.py index ed819e9821c2..e8f7e7a49758 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -105,6 +105,7 @@ logger =3D logging.getLogger(__name__) RE_DOMAIN_REF =3D re.compile(r'\\ :(ref|c:type|c:func):`([^<`]+)(?:<([^>]+= )>)?`\\') RE_SIMPLE_REF =3D re.compile(r'`([^`]+)`') RE_LINENO_REF =3D re.compile(r'^\s*-\s+LINENO_(\d+):\s+(.*)') +RE_SPLIT_DOMAIN =3D re.compile(r"(.*)\.(.*)") =20 def ErrorString(exc): # Shamelessly stolen from docutils return f'{exc.__class__.__name}: {exc}' @@ -399,6 +400,67 @@ class KernelInclude(Directive): =20 reported =3D set() =20 +DOMAIN_INFO =3D {} + +def fill_domain_info(env): + """ + Get supported reference types for each Sphinx domain and C namespaces + """ + if DOMAIN_INFO: + return + + for domain_name, domain_instance in env.domains.items(): + try: + object_types =3D list(domain_instance.object_types.keys()) + DOMAIN_INFO[domain_name] =3D object_types + except AttributeError: + # Ignore domains that we can't retrieve object types, if any + pass + +def get_suggestions(app, env, node, + original_target, original_domain, original_reftype): + """Check if target exists in the other domain or with different reftyp= es.""" + original_target =3D original_target.lower() + + # Remove namespace if present + if '.' in original_target: + original_target =3D original_target.split(".")[-1] + + targets =3D set([ + original_target, + original_target.replace("-", "_"), + original_target.replace("_", "-"), + ]) + + # Propose some suggestions, if possible + # The code below checks not only variants of the target, but also it + # works when .. c:namespace:: targets setting a different C namespace + # is in place + + suggestions =3D [] + for target in sorted(targets): + for domain in DOMAIN_INFO.keys(): + domain_obj =3D env.get_domain(domain) + for name, dispname, objtype, docname, anchor, priority in doma= in_obj.get_objects(): + lower_name =3D name.lower() + + if domain =3D=3D "c": + # Check if name belongs to a different C namespace + match =3D RE_SPLIT_DOMAIN.match(name) + if match: + if target !=3D match.group(2).lower(): + continue + else: + if target !=3D lower_name: + continue + else: + if target !=3D lower_name: + continue + + suggestions.append(f"\t{domain}:{objtype}:`{name}` (from {= docname})") + + return suggestions + def check_missing_refs(app, env, node, contnode): """Check broken refs for the files it creates xrefs""" if not node.source: @@ -414,11 +476,13 @@ def check_missing_refs(app, env, node, contnode): if node.source not in xref_files: return None =20 + fill_domain_info(env) + target =3D node.get('reftarget', '') domain =3D node.get('refdomain', 'std') reftype =3D node.get('reftype', '') =20 - msg =3D f"can't link to: {domain}:{reftype}:: {target}" + msg =3D f"Invalid xref: {domain}:{reftype}:`{target}`" =20 # Don't duplicate warnings data =3D (node.source, msg) @@ -426,6 +490,10 @@ def check_missing_refs(app, env, node, contnode): return None reported.add(data) =20 + suggestions =3D get_suggestions(app, env, node, target, domain, reftyp= e) + if suggestions: + msg +=3D ". Possible alternatives:\n" + '\n'.join(suggestions) + logger.warning(msg, location=3Dnode, type=3D'ref', subtype=3D'missing') =20 return None diff --git a/Documentation/userspace-api/media/v4l/videodev.rst b/Documenta= tion/userspace-api/media/v4l/videodev.rst index cde485bc9a5f..64be44716494 100644 --- a/Documentation/userspace-api/media/v4l/videodev.rst +++ b/Documentation/userspace-api/media/v4l/videodev.rst @@ -2,10 +2,12 @@ =20 .. _videodev: =20 -******************************* -Video For Linux Two Header File -******************************* +*************************************** +Video For Linux Two Header uAPI Symbols +*************************************** =20 .. kernel-include:: include/uapi/linux/videodev2.h :generate-cross-refs: :exception-file: videodev2.h.rst.exceptions + :toc: + :warn-broken: diff --git a/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptio= ns b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions index 35d3456cc812..951d01bf7579 100644 --- a/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions @@ -1,5 +1,8 @@ # SPDX-License-Identifier: GPL-2.0 =20 +# All symbols are mapped inside V4L C domain namespace +namespace V4L + # Ignore header name ignore define _UAPI__LINUX_VIDEODEV2_H =20 --=20 2.51.0