{"id":2197675,"url":"http://patchwork.ozlabs.org/api/1.0/patches/2197675/?format=json","project":{"id":46,"url":"http://patchwork.ozlabs.org/api/1.0/projects/46/?format=json","name":"Intel Wired Ethernet development","link_name":"intel-wired-lan","list_id":"intel-wired-lan.osuosl.org","list_email":"intel-wired-lan@osuosl.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<297f164226148f52b0b9a814086f51ade04ff031.1771408406.git.mchehab+huawei@kernel.org>","date":"2026-02-18T10:12:56","name":"[26/38] docs: kdoc_parser: move transform lists to a separate file","commit_ref":null,"pull_url":null,"state":"handled-elsewhere","archived":false,"hash":"72e507e925ae587657391be57469d03bac50539b","submitter":{"id":78235,"url":"http://patchwork.ozlabs.org/api/1.0/people/78235/?format=json","name":"Mauro Carvalho Chehab","email":"mchehab+huawei@kernel.org"},"delegate":null,"mbox":"http://patchwork.ozlabs.org/project/intel-wired-lan/patch/297f164226148f52b0b9a814086f51ade04ff031.1771408406.git.mchehab+huawei@kernel.org/mbox/","series":[{"id":492532,"url":"http://patchwork.ozlabs.org/api/1.0/series/492532/?format=json","date":"2026-02-18T10:12:30","name":"docs: several improvements to kernel-doc","version":1,"mbox":"http://patchwork.ozlabs.org/series/492532/mbox/"}],"check":"pending","checks":"http://patchwork.ozlabs.org/api/patches/2197675/checks/","tags":{},"headers":{"Return-Path":"","X-Original-To":["incoming@patchwork.ozlabs.org","intel-wired-lan@lists.osuosl.org"],"Delivered-To":["patchwork-incoming@legolas.ozlabs.org","intel-wired-lan@lists.osuosl.org"],"Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (2048-bit key;\n unprotected) header.d=osuosl.org header.i=@osuosl.org header.a=rsa-sha256\n header.s=default header.b=3jc1GY57;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=osuosl.org\n (client-ip=2605:bc80:3010::138; helo=smtp1.osuosl.org;\n envelope-from=intel-wired-lan-bounces@osuosl.org;\n receiver=patchwork.ozlabs.org)"],"Received":["from smtp1.osuosl.org (smtp1.osuosl.org [IPv6:2605:bc80:3010::138])\n\t(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n\t key-exchange x25519 server-signature ECDSA (secp384r1) server-digest SHA384)\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4fGC5k3TYmz1xpl\n\tfor ; Wed, 18 Feb 2026 21:13:46 +1100 (AEDT)","from localhost (localhost [127.0.0.1])\n\tby smtp1.osuosl.org (Postfix) with ESMTP id ABE40810C2;\n\tWed, 18 Feb 2026 10:13:40 +0000 (UTC)","from smtp1.osuosl.org ([127.0.0.1])\n by localhost (smtp1.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP\n id vwds9-OVlURu; Wed, 18 Feb 2026 10:13:39 +0000 (UTC)","from lists1.osuosl.org (lists1.osuosl.org [140.211.166.142])\n\tby smtp1.osuosl.org (Postfix) with ESMTP id 846BF81091;\n\tWed, 18 Feb 2026 10:13:39 +0000 (UTC)","from smtp4.osuosl.org (smtp4.osuosl.org [IPv6:2605:bc80:3010::137])\n by lists1.osuosl.org (Postfix) with ESMTP id 14F2D206\n for ; Wed, 18 Feb 2026 10:13:31 +0000 (UTC)","from localhost (localhost [127.0.0.1])\n by smtp4.osuosl.org (Postfix) with ESMTP id 06499407EE\n for ; Wed, 18 Feb 2026 10:13:31 +0000 (UTC)","from smtp4.osuosl.org ([127.0.0.1])\n by localhost (smtp4.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP\n id Q69doBnQp4np for ;\n Wed, 18 Feb 2026 10:13:29 +0000 (UTC)","from sea.source.kernel.org (sea.source.kernel.org [172.234.252.31])\n by smtp4.osuosl.org (Postfix) with ESMTPS id 3F1FE407CF\n for ; Wed, 18 Feb 2026 10:13:29 +0000 (UTC)","from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58])\n by sea.source.kernel.org (Postfix) with ESMTP id 0248344582;\n Wed, 18 Feb 2026 10:13:29 +0000 (UTC)","by smtp.kernel.org (Postfix) with ESMTPSA id 8A58FC19423;\n Wed, 18 Feb 2026 10:13:28 +0000 (UTC)","from mchehab by mail.kernel.org with local (Exim 4.99.1)\n (envelope-from )\n id 1vseYg-00000000LqA-3IMj; Wed, 18 Feb 2026 11:13:26 +0100"],"X-Virus-Scanned":["amavis at osuosl.org","amavis at osuosl.org"],"X-Comment":"SPF check N/A for local connections - client-ip=140.211.166.142;\n helo=lists1.osuosl.org; envelope-from=intel-wired-lan-bounces@osuosl.org;\n receiver= ","DKIM-Filter":["OpenDKIM Filter v2.11.0 smtp1.osuosl.org 846BF81091","OpenDKIM Filter v2.11.0 smtp4.osuosl.org 3F1FE407CF"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=osuosl.org;\n\ts=default; t=1771409619;\n\tbh=SDBwfiZ+ObLVowVHAGC5zKKRZVcrpvn3u3jGoGw7SHs=;\n\th=From:To:Cc:Date:In-Reply-To:References:Subject:List-Id:\n\t List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe:\n\t From;\n\tb=3jc1GY57qtsAN5BpwfJ1WPCiIhvTPsjIjOEv0kRwFh0J5Pm0CkLL7dNKTcYiJpWgm\n\t f31ckYNme617/X+1jaZjklELB9llqIRj0NBt0wqar6svDVD5fhonr+UjRJNZjsOG8x\n\t HHZfZiffweClPVKW8T67xnvnJWsDomugxEg1qhmFDCKJYWiiWBUbNnRKbDk00zSzBS\n\t Yi3whW1bbwF0CWu/yyq5Pf5YJ9fC37PTeIxdO+dILOr1d0y40F3nAx2n0lcplBZD+S\n\t xGMHKmavu7JbxVT9TANborTIVJEqYzCdXh+JOuIEFh4bX0OUEDgTY9V4dB2blZOnmJ\n\t 62lr3dDlXqntw==","Received-SPF":"Pass (mailfrom) identity=mailfrom; client-ip=172.234.252.31;\n helo=sea.source.kernel.org; envelope-from=mchehab+huawei@kernel.org;\n receiver=","DMARC-Filter":"OpenDMARC Filter v1.4.2 smtp4.osuosl.org 3F1FE407CF","From":"Mauro Carvalho Chehab ","To":"Jonathan Corbet ,\n Linux Doc Mailing List ","Cc":"Mauro Carvalho Chehab ,\n intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org,\n linux-kernel@vger.kernel.org, netdev@vger.kernel.org,\n \"Gustavo A. R. Silva\" ,\n Aleksandr Loktionov ,\n Kees Cook , Randy Dunlap ,\n Shuah Khan ","Date":"Wed, 18 Feb 2026 11:12:56 +0100","Message-ID":"\n <297f164226148f52b0b9a814086f51ade04ff031.1771408406.git.mchehab+huawei@kernel.org>","X-Mailer":"git-send-email 2.52.0","In-Reply-To":"","References":"","MIME-Version":"1.0","Content-Type":"text/plain; charset=\"utf-8\"","Content-Transfer-Encoding":"8bit","X-Mailman-Original-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple;\n d=kernel.org; s=k20201202; t=1771409608;\n bh=3QK91KuqWdY00vyGOroyTR5vxbbyLrMwk3WJEOvMx9g=;\n h=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n b=etEnEmCC/c9IziG98TAAR4uadZWWirKhrzZMy3hZ++PLKrzTF3GF26q2tWLSIdj70\n PqNSzpBYWmEUHZWxUqKvRvcYrYKYMW+zCQdUKk2/XL0iFsxiyhyLbIwemZje1i1NlW\n UI9czqhW8tqWm/11RFSvcTJRrZBDKeY+iSK07T1Dou/exea7pTASKQ8NZm7CTUwvDG\n z7BE4IAiLvUJHDpBJbqm7qlE5nRnTVoY52af63E05PDLcK7+HIGMwt1UvP3/12r1Aa\n qxz32Ov0D778k1QwM2QlCST928NIz1UsIexFSp0OWHr9yGh+Mpbqplb9ocAozwj/Lx\n +Y6znOhohep2g==","X-Mailman-Original-Authentication-Results":["smtp4.osuosl.org;\n dmarc=pass (p=quarantine dis=none)\n header.from=kernel.org","smtp4.osuosl.org;\n dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org\n header.a=rsa-sha256 header.s=k20201202 header.b=etEnEmCC"],"Subject":"[Intel-wired-lan] [PATCH 26/38] docs: kdoc_parser: move transform\n lists to a separate file","X-BeenThere":"intel-wired-lan@osuosl.org","X-Mailman-Version":"2.1.30","Precedence":"list","List-Id":"Intel Wired Ethernet Linux Kernel Driver Development\n ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"intel-wired-lan-bounces@osuosl.org","Sender":"\"Intel-wired-lan\" "},"content":"Over the time, most of the changes at kernel-doc are related\nto maintaining a list of transforms to convert macros into pure\nC code.\n\nPlace such transforms on a separate module, to cleanup the\nparser module.\n\nWhile here, drop the now obsolete comment about the two-steps\nlogic to handle struct_group macros.\n\nThere is an advantage on that: QEMU also uses our own kernel-doc,\nbut the xforms list there is different. By placing it on a\nseparate module, we can minimize the differences and make it\neasier to keep QEMU in sync with Kernel upstream.\n\nSigned-off-by: Mauro Carvalho Chehab \nReviewed-by: Aleksandr Loktionov \n---\n Documentation/tools/kdoc_parser.rst | 8 ++\n tools/lib/python/kdoc/kdoc_files.py | 3 +-\n tools/lib/python/kdoc/kdoc_parser.py | 148 ++------------------------\n tools/lib/python/kdoc/xforms_lists.py | 118 ++++++++++++++++++++\n 4 files changed, 134 insertions(+), 143 deletions(-)\n create mode 100644 tools/lib/python/kdoc/xforms_lists.py","diff":"diff --git a/Documentation/tools/kdoc_parser.rst b/Documentation/tools/kdoc_parser.rst\nindex 03ee54a1b1cc..55b202173195 100644\n--- a/Documentation/tools/kdoc_parser.rst\n+++ b/Documentation/tools/kdoc_parser.rst\n@@ -4,6 +4,14 @@\n Kernel-doc parser stage\n =======================\n \n+C replacement rules used by the parser\n+======================================\n+\n+.. automodule:: lib.python.kdoc.xforms_lists\n+ :members:\n+ :show-inheritance:\n+ :undoc-members:\n+\n File handler classes\n ====================\n \ndiff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kdoc_files.py\nindex 022487ea2cc6..7357c97a4b01 100644\n--- a/tools/lib/python/kdoc/kdoc_files.py\n+++ b/tools/lib/python/kdoc/kdoc_files.py\n@@ -15,6 +15,7 @@ import os\n import re\n \n from kdoc.kdoc_parser import KernelDoc\n+from kdoc.xforms_lists import CTransforms\n from kdoc.kdoc_output import OutputFormat\n \n \n@@ -117,7 +118,7 @@ class KernelFiles():\n if fname in self.files:\n return\n \n- doc = KernelDoc(self.config, fname)\n+ doc = KernelDoc(self.config, fname, CTransforms)\n export_table, entries = doc.parse_kdoc()\n \n self.export_table[fname] = export_table\ndiff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py\nindex e735e79b5061..a280fe581937 100644\n--- a/tools/lib/python/kdoc/kdoc_parser.py\n+++ b/tools/lib/python/kdoc/kdoc_parser.py\n@@ -75,143 +75,6 @@ doc_begin_func = KernRe(str(doc_com) +\t\t\t# initial \" * '\n #\n struct_args_pattern = r'([^,)]+)'\n \n-struct_xforms = [\n- # Strip attributes\n- (KernRe(r\"__attribute__\\s*\\(\\([a-z0-9,_\\*\\s\\(\\)]*\\)\\)\", flags=re.I | re.S, cache=False), ' '),\n- (KernRe(r'\\s*__aligned\\s*\\([^;]*\\)', re.S), ' '),\n- (KernRe(r'\\s*__counted_by\\s*\\([^;]*\\)', re.S), ' '),\n- (KernRe(r'\\s*__counted_by_(le|be)\\s*\\([^;]*\\)', re.S), ' '),\n- (KernRe(r'\\s*__guarded_by\\s*\\([^\\)]*\\)', re.S), ' '),\n- (KernRe(r'\\s*__pt_guarded_by\\s*\\([^\\)]*\\)', re.S), ' '),\n- (KernRe(r'\\s*__packed\\s*', re.S), ' '),\n- (KernRe(r'\\s*CRYPTO_MINALIGN_ATTR', re.S), ' '),\n- (KernRe(r'\\s*__private', re.S), ' '),\n- (KernRe(r'\\s*__rcu', re.S), ' '),\n- (KernRe(r'\\s*____cacheline_aligned_in_smp', re.S), ' '),\n- (KernRe(r'\\s*____cacheline_aligned', re.S), ' '),\n- (KernRe(r'\\s*__cacheline_group_(begin|end)\\([^\\)]+\\);'), ''),\n- #\n- # Unwrap struct_group macros based on this definition:\n- # __struct_group(TAG, NAME, ATTRS, MEMBERS...)\n- # which has variants like: struct_group(NAME, MEMBERS...)\n- # Only MEMBERS arguments require documentation.\n- #\n- # Parsing them happens on two steps:\n- #\n- # 1. drop struct group arguments that aren't at MEMBERS,\n- # storing them as STRUCT_GROUP(MEMBERS)\n- #\n- # 2. remove STRUCT_GROUP() ancillary macro.\n- #\n- # The original logic used to remove STRUCT_GROUP() using an\n- # advanced regex:\n- #\n- # \\bSTRUCT_GROUP(\\(((?:(?>[^)(]+)|(?1))*)\\))[^;]*;\n- #\n- # with two patterns that are incompatible with\n- # Python re module, as it has:\n- #\n- # - a recursive pattern: (?1)\n- # - an atomic grouping: (?>...)\n- #\n- # I tried a simpler version: but it didn't work either:\n- # \\bSTRUCT_GROUP\\(([^\\)]+)\\)[^;]*;\n- #\n- # As it doesn't properly match the end parenthesis on some cases.\n- #\n- # So, a better solution was crafted: there's now a CFunction\n- # class that ensures that delimiters after a search are properly\n- # matched. So, the implementation to drop STRUCT_GROUP() will be\n- # handled in separate.\n- #\n- (CFunction('struct_group'), r'\\2'),\n- (CFunction('struct_group_attr'), r'\\3'),\n- (CFunction('struct_group_tagged'), r'struct \\1 \\2; \\3'),\n- (CFunction('__struct_group'), r'\\4'),\n-\n- #\n- # Replace macros\n- #\n- # TODO: use CFunction on all FOO($1, $2, ...) matches\n- #\n- # it is better to also move those to the CFunction logic,\n- # to ensure that parentheses will be properly matched.\n- #\n- (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\\s*\\(([^\\)]+)\\)', re.S),\n- r'DECLARE_BITMAP(\\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'),\n- (KernRe(r'DECLARE_PHY_INTERFACE_MASK\\s*\\(([^\\)]+)\\)', re.S),\n- r'DECLARE_BITMAP(\\1, PHY_INTERFACE_MODE_MAX)'),\n- (KernRe(r'DECLARE_BITMAP\\s*\\(' + struct_args_pattern + r',\\s*' + struct_args_pattern + r'\\)',\n- re.S), r'unsigned long \\1[BITS_TO_LONGS(\\2)]'),\n- (KernRe(r'DECLARE_HASHTABLE\\s*\\(' + struct_args_pattern + r',\\s*' + struct_args_pattern + r'\\)',\n- re.S), r'unsigned long \\1[1 << ((\\2) - 1)]'),\n- (KernRe(r'DECLARE_KFIFO\\s*\\(' + struct_args_pattern + r',\\s*' + struct_args_pattern +\n- r',\\s*' + struct_args_pattern + r'\\)', re.S), r'\\2 *\\1'),\n- (KernRe(r'DECLARE_KFIFO_PTR\\s*\\(' + struct_args_pattern + r',\\s*' +\n- struct_args_pattern + r'\\)', re.S), r'\\2 *\\1'),\n- (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\\s*\\(' + struct_args_pattern + r',\\s*' +\n- struct_args_pattern + r'\\)', re.S), r'\\1 \\2[]'),\n- (KernRe(r'DEFINE_DMA_UNMAP_ADDR\\s*\\(' + struct_args_pattern + r'\\)', re.S), r'dma_addr_t \\1'),\n- (KernRe(r'DEFINE_DMA_UNMAP_LEN\\s*\\(' + struct_args_pattern + r'\\)', re.S), r'__u32 \\1'),\n- (KernRe(r'VIRTIO_DECLARE_FEATURES\\(([\\w_]+)\\)'), r'union { u64 \\1; u64 \\1_array[VIRTIO_FEATURES_U64S]; }'),\n-]\n-\n-#\n-# Transforms for function prototypes\n-#\n-function_xforms = [\n- (KernRe(r\"^static +\"), \"\"),\n- (KernRe(r\"^extern +\"), \"\"),\n- (KernRe(r\"^asmlinkage +\"), \"\"),\n- (KernRe(r\"^inline +\"), \"\"),\n- (KernRe(r\"^__inline__ +\"), \"\"),\n- (KernRe(r\"^__inline +\"), \"\"),\n- (KernRe(r\"^__always_inline +\"), \"\"),\n- (KernRe(r\"^noinline +\"), \"\"),\n- (KernRe(r\"^__FORTIFY_INLINE +\"), \"\"),\n- (KernRe(r\"__init +\"), \"\"),\n- (KernRe(r\"__init_or_module +\"), \"\"),\n- (KernRe(r\"__exit +\"), \"\"),\n- (KernRe(r\"__deprecated +\"), \"\"),\n- (KernRe(r\"__flatten +\"), \"\"),\n- (KernRe(r\"__meminit +\"), \"\"),\n- (KernRe(r\"__must_check +\"), \"\"),\n- (KernRe(r\"__weak +\"), \"\"),\n- (KernRe(r\"__sched +\"), \"\"),\n- (KernRe(r\"_noprof\"), \"\"),\n- (KernRe(r\"__always_unused *\"), \"\"),\n- (KernRe(r\"__printf\\s*\\(\\s*\\d*\\s*,\\s*\\d*\\s*\\) +\"), \"\"),\n- (KernRe(r\"__(?:re)?alloc_size\\s*\\(\\s*\\d+\\s*(?:,\\s*\\d+\\s*)?\\) +\"), \"\"),\n- (KernRe(r\"__diagnose_as\\s*\\(\\s*\\S+\\s*(?:,\\s*\\d+\\s*)*\\) +\"), \"\"),\n- (KernRe(r\"DECL_BUCKET_PARAMS\\s*\\(\\s*(\\S+)\\s*,\\s*(\\S+)\\s*\\)\"), r\"\\1, \\2\"),\n- (KernRe(r\"__no_context_analysis\\s*\"), \"\"),\n- (KernRe(r\"__attribute_const__ +\"), \"\"),\n- (CFunction(\"__cond_acquires\"), \"\"),\n- (CFunction(\"__cond_releases\"), \"\"),\n- (CFunction(\"__acquires\"), \"\"),\n- (CFunction(\"__releases\"), \"\"),\n- (CFunction(\"__must_hold\"), \"\"),\n- (CFunction(\"__must_not_hold\"), \"\"),\n- (CFunction(\"__must_hold_shared\"), \"\"),\n- (CFunction(\"__cond_acquires_shared\"), \"\"),\n- (CFunction(\"__acquires_shared\"), \"\"),\n- (CFunction(\"__releases_shared\"), \"\"),\n- (CFunction(\"__attribute__\"), \"\"),\n-]\n-\n-#\n-# Transforms for variable prototypes\n-#\n-var_xforms = [\n- (KernRe(r\"__read_mostly\"), \"\"),\n- (KernRe(r\"__ro_after_init\"), \"\"),\n- (KernRe(r'\\s*__guarded_by\\s*\\([^\\)]*\\)', re.S), \"\"),\n- (KernRe(r'\\s*__pt_guarded_by\\s*\\([^\\)]*\\)', re.S), \"\"),\n- (KernRe(r\"LIST_HEAD\\(([\\w_]+)\\)\"), r\"struct list_head \\1\"),\n- (KernRe(r\"(?://.*)$\"), \"\"),\n- (KernRe(r\"(?:/\\*.*\\*/)\"), \"\"),\n- (KernRe(r\";$\"), \"\"),\n-]\n \n #\n # Ancillary functions\n@@ -395,11 +258,12 @@ class KernelDoc:\n #: String to write when a parameter is not described.\n undescribed = \"-- undescribed --\"\n \n- def __init__(self, config, fname):\n+ def __init__(self, config, fname, xforms):\n \"\"\"Initialize internal variables\"\"\"\n \n self.fname = fname\n self.config = config\n+ self.xforms = xforms\n \n # Initial state for the state machines\n self.state = state.NORMAL\n@@ -890,7 +754,7 @@ class KernelDoc:\n # Go through the list of members applying all of our transformations.\n #\n members = trim_private_members(members)\n- members = self.apply_transforms(struct_xforms, members)\n+ members = self.apply_transforms(self.xforms.struct_xforms, members)\n \n #\n # Deal with embedded struct and union members, and drop enums entirely.\n@@ -1012,8 +876,7 @@ class KernelDoc:\n # Drop comments and macros to have a pure C prototype\n #\n if not declaration_name:\n- for r, sub in var_xforms:\n- proto = r.sub(sub, proto)\n+ proto = self.apply_transforms(self.xforms.var_xforms, proto)\n \n proto = proto.rstrip()\n \n@@ -1105,7 +968,8 @@ class KernelDoc:\n #\n # Apply the initial transformations.\n #\n- prototype = self.apply_transforms(function_xforms, prototype)\n+ prototype = self.apply_transforms(self.xforms.function_xforms,\n+ prototype)\n \n # Yes, this truly is vile. We are looking for:\n # 1. Return type (may be nothing if we're looking at a macro)\ndiff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py\nnew file mode 100644\nindex 000000000000..2e7b470c4e65\n--- /dev/null\n+++ b/tools/lib/python/kdoc/xforms_lists.py\n@@ -0,0 +1,118 @@\n+#!/usr/bin/env python3\n+# SPDX-License-Identifier: GPL-2.0\n+# Copyright(c) 2026: Mauro Carvalho Chehab .\n+\n+import re\n+\n+from kdoc.kdoc_re import CFunction, KernRe\n+\n+struct_args_pattern = r'([^,)]+)'\n+\n+class CTransforms:\n+ \"\"\"\n+ Data class containing a long set of transformations to turn\n+ structure member prefixes, and macro invocations and variables\n+ into something we can parse and generate kdoc for.\n+ \"\"\"\n+\n+ #: Transforms for structs and unions.\n+ struct_xforms = [\n+ # Strip attributes\n+ (KernRe(r\"__attribute__\\s*\\(\\([a-z0-9,_\\*\\s\\(\\)]*\\)\\)\", flags=re.I | re.S, cache=False), ' '),\n+ (KernRe(r'\\s*__aligned\\s*\\([^;]*\\)', re.S), ' '),\n+ (KernRe(r'\\s*__counted_by\\s*\\([^;]*\\)', re.S), ' '),\n+ (KernRe(r'\\s*__counted_by_(le|be)\\s*\\([^;]*\\)', re.S), ' '),\n+ (KernRe(r'\\s*__guarded_by\\s*\\([^\\)]*\\)', re.S), ' '),\n+ (KernRe(r'\\s*__pt_guarded_by\\s*\\([^\\)]*\\)', re.S), ' '),\n+ (KernRe(r'\\s*__packed\\s*', re.S), ' '),\n+ (KernRe(r'\\s*CRYPTO_MINALIGN_ATTR', re.S), ' '),\n+ (KernRe(r'\\s*__private', re.S), ' '),\n+ (KernRe(r'\\s*__rcu', re.S), ' '),\n+ (KernRe(r'\\s*____cacheline_aligned_in_smp', re.S), ' '),\n+ (KernRe(r'\\s*____cacheline_aligned', re.S), ' '),\n+ (KernRe(r'\\s*__cacheline_group_(begin|end)\\([^\\)]+\\);'), ''),\n+\n+ (CFunction('struct_group'), r'\\2'),\n+ (CFunction('struct_group_attr'), r'\\3'),\n+ (CFunction('struct_group_tagged'), r'struct \\1 \\2; \\3'),\n+ (CFunction('__struct_group'), r'\\4'),\n+\n+ #\n+ # Replace macros\n+ #\n+ # TODO: use CFunction on all FOO($1, $2, ...) matches\n+ #\n+ # it is better to also move those to the CFunction logic,\n+ # to ensure that parentheses will be properly matched.\n+ #\n+ (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\\s*\\(([^\\)]+)\\)', re.S),\n+ r'DECLARE_BITMAP(\\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'),\n+ (KernRe(r'DECLARE_PHY_INTERFACE_MASK\\s*\\(([^\\)]+)\\)', re.S),\n+ r'DECLARE_BITMAP(\\1, PHY_INTERFACE_MODE_MAX)'),\n+ (KernRe(r'DECLARE_BITMAP\\s*\\(' + struct_args_pattern + r',\\s*' + struct_args_pattern + r'\\)',\n+ re.S), r'unsigned long \\1[BITS_TO_LONGS(\\2)]'),\n+ (KernRe(r'DECLARE_HASHTABLE\\s*\\(' + struct_args_pattern + r',\\s*' + struct_args_pattern + r'\\)',\n+ re.S), r'unsigned long \\1[1 << ((\\2) - 1)]'),\n+ (KernRe(r'DECLARE_KFIFO\\s*\\(' + struct_args_pattern + r',\\s*' + struct_args_pattern +\n+ r',\\s*' + struct_args_pattern + r'\\)', re.S), r'\\2 *\\1'),\n+ (KernRe(r'DECLARE_KFIFO_PTR\\s*\\(' + struct_args_pattern + r',\\s*' +\n+ struct_args_pattern + r'\\)', re.S), r'\\2 *\\1'),\n+ (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\\s*\\(' + struct_args_pattern + r',\\s*' +\n+ struct_args_pattern + r'\\)', re.S), r'\\1 \\2[]'),\n+ (KernRe(r'DEFINE_DMA_UNMAP_ADDR\\s*\\(' + struct_args_pattern + r'\\)', re.S), r'dma_addr_t \\1'),\n+ (KernRe(r'DEFINE_DMA_UNMAP_LEN\\s*\\(' + struct_args_pattern + r'\\)', re.S), r'__u32 \\1'),\n+ (KernRe(r'VIRTIO_DECLARE_FEATURES\\(([\\w_]+)\\)'), r'union { u64 \\1; u64 \\1_array[VIRTIO_FEATURES_U64S]; }'),\n+ ]\n+\n+ #: Transforms for function prototypes.\n+ function_xforms = [\n+ (KernRe(r\"^static +\"), \"\"),\n+ (KernRe(r\"^extern +\"), \"\"),\n+ (KernRe(r\"^asmlinkage +\"), \"\"),\n+ (KernRe(r\"^inline +\"), \"\"),\n+ (KernRe(r\"^__inline__ +\"), \"\"),\n+ (KernRe(r\"^__inline +\"), \"\"),\n+ (KernRe(r\"^__always_inline +\"), \"\"),\n+ (KernRe(r\"^noinline +\"), \"\"),\n+ (KernRe(r\"^__FORTIFY_INLINE +\"), \"\"),\n+ (KernRe(r\"__init +\"), \"\"),\n+ (KernRe(r\"__init_or_module +\"), \"\"),\n+ (KernRe(r\"__exit +\"), \"\"),\n+ (KernRe(r\"__deprecated +\"), \"\"),\n+ (KernRe(r\"__flatten +\"), \"\"),\n+ (KernRe(r\"__meminit +\"), \"\"),\n+ (KernRe(r\"__must_check +\"), \"\"),\n+ (KernRe(r\"__weak +\"), \"\"),\n+ (KernRe(r\"__sched +\"), \"\"),\n+ (KernRe(r\"_noprof\"), \"\"),\n+ (KernRe(r\"__always_unused *\"), \"\"),\n+ (KernRe(r\"__printf\\s*\\(\\s*\\d*\\s*,\\s*\\d*\\s*\\) +\"), \"\"),\n+ (KernRe(r\"__(?:re)?alloc_size\\s*\\(\\s*\\d+\\s*(?:,\\s*\\d+\\s*)?\\) +\"), \"\"),\n+ (KernRe(r\"__diagnose_as\\s*\\(\\s*\\S+\\s*(?:,\\s*\\d+\\s*)*\\) +\"), \"\"),\n+ (KernRe(r\"DECL_BUCKET_PARAMS\\s*\\(\\s*(\\S+)\\s*,\\s*(\\S+)\\s*\\)\"), r\"\\1, \\2\"),\n+ (KernRe(r\"__no_context_analysis\\s*\"), \"\"),\n+ (KernRe(r\"__attribute_const__ +\"), \"\"),\n+ (CFunction(\"__cond_acquires\"), \"\"),\n+ (CFunction(\"__cond_releases\"), \"\"),\n+ (CFunction(\"__acquires\"), \"\"),\n+ (CFunction(\"__releases\"), \"\"),\n+ (CFunction(\"__must_hold\"), \"\"),\n+ (CFunction(\"__must_not_hold\"), \"\"),\n+ (CFunction(\"__must_hold_shared\"), \"\"),\n+ (CFunction(\"__cond_acquires_shared\"), \"\"),\n+ (CFunction(\"__acquires_shared\"), \"\"),\n+ (CFunction(\"__releases_shared\"), \"\"),\n+ (CFunction(\"__attribute__\"), \"\"),\n+ ]\n+\n+ #: Transforms for variables.\n+ var_xforms = [\n+ (KernRe(r\"__read_mostly\"), \"\"),\n+ (KernRe(r\"__ro_after_init\"), \"\"),\n+ (KernRe(r'\\s*__guarded_by\\s*\\([^\\)]*\\)', re.S), \"\"),\n+ (KernRe(r'\\s*__pt_guarded_by\\s*\\([^\\)]*\\)', re.S), \"\"),\n+ (KernRe(r\"LIST_HEAD\\(([\\w_]+)\\)\"), r\"struct list_head \\1\"),\n+ (KernRe(r\"(?://.*)$\"), \"\"),\n+ (KernRe(r\"(?:/\\*.*\\*/)\"), \"\"),\n+ (KernRe(r\";$\"), \"\"),\n+ ]\n","prefixes":["26/38"]}