From patchwork Mon Jul 5 10:51:00 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Fancellu X-Patchwork-Id: 12358849 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 43F4DC07E99 for ; Mon, 5 Jul 2021 10:55:55 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 1009A6135B for ; Mon, 5 Jul 2021 10:55:55 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 1009A6135B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=arm.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from list by lists.xenproject.org with outflank-mailman.150105.277664 (Exim 4.92) (envelope-from ) id 1m0MGQ-0006v0-9F; Mon, 05 Jul 2021 10:55:46 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 150105.277664; Mon, 05 Jul 2021 10:55:46 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1m0MGQ-0006uE-0y; Mon, 05 Jul 2021 10:55:46 +0000 Received: by outflank-mailman (input) for mailman id 150105; Mon, 05 Jul 2021 10:55:44 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1m0MGO-0003rB-D9 for xen-devel@lists.xenproject.org; Mon, 05 Jul 2021 10:55:44 +0000 Received: from foss.arm.com (unknown [217.140.110.172]) by us1-rack-iad1.inumbo.com (Halon) with ESMTP id 24bae97d-96b5-498a-bcec-3f13d65b9b7f; Mon, 05 Jul 2021 10:55:26 +0000 (UTC) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id B33B41042; Mon, 5 Jul 2021 03:55:26 -0700 (PDT) Received: from e125770.cambridge.arm.com (e125770.cambridge.arm.com [10.1.197.16]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 630913F5A1; Mon, 5 Jul 2021 03:55:25 -0700 (PDT) X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: 24bae97d-96b5-498a-bcec-3f13d65b9b7f From: Luca Fancellu To: xen-devel@lists.xenproject.org Cc: bertrand.marquis@arm.com, wei.chen@arm.com, Andrew Cooper , George Dunlap , Ian Jackson , Jan Beulich , Julien Grall , Stefano Stabellini , Wei Liu Subject: [PATCH v7 6/9] docs: add doxygen preprocessor and related files Date: Mon, 5 Jul 2021 11:51:00 +0100 Message-Id: <20210705105103.14509-7-luca.fancellu@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20210705105103.14509-1-luca.fancellu@arm.com> References: <20210705105103.14509-1-luca.fancellu@arm.com> Add preprocessor called by doxygen before parsing headers, it will include in every header a doxygen_include.h file that provides missing defines and includes that are usually passed by the compiler, it will also handle the problem of anonymous union/struct not recognized by doxygen giving them names. There is only one limitation that is described by a comment in the script. Add doxy_input.list that is a text file containing the relative path to the source code file to be parsed by doxygen. The path sould be relative to the xen folder: E.g. xen/include/public/grant_table.h Signed-off-by: Luca Fancellu --- v7 changes: - add comment to address one limitation of the preprocessor and change commit message. --- docs/xen-doxygen/doxy-preprocessor.py | 116 ++++++++++++++++++++++++++ docs/xen-doxygen/doxy_input.list | 0 docs/xen-doxygen/doxygen_include.h.in | 32 +++++++ 3 files changed, 148 insertions(+) create mode 100755 docs/xen-doxygen/doxy-preprocessor.py create mode 100644 docs/xen-doxygen/doxy_input.list create mode 100644 docs/xen-doxygen/doxygen_include.h.in diff --git a/docs/xen-doxygen/doxy-preprocessor.py b/docs/xen-doxygen/doxy-preprocessor.py new file mode 100755 index 0000000000..90ba030e7e --- /dev/null +++ b/docs/xen-doxygen/doxy-preprocessor.py @@ -0,0 +1,116 @@ +#!/usr/bin/python3 +# +# Copyright (c) 2021, Arm Limited. +# +# SPDX-License-Identifier: GPL-2.0 +# + +import os, sys, re + + +# Variables that holds the preprocessed header text +output_text = "" +header_file_name = "" + +# Variables to enumerate the anonymous structs/unions +anonymous_struct_count = 0 +anonymous_union_count = 0 + + +def error(text): + sys.stderr.write("{}\n".format(text)) + sys.exit(1) + + +def write_to_output(text): + sys.stdout.write(text) + + +def insert_doxygen_header(text): + # Here the strategy is to insert the #include in the + # first line of the header + abspath = os.path.dirname(os.path.abspath(__file__)) + text += "#include \"{}/doxygen_include.h\"\n".format(abspath) + + return text + + +def enumerate_anonymous(match): + global anonymous_struct_count + global anonymous_union_count + + if "struct" in match.group(1): + label = "anonymous_struct_%d" % anonymous_struct_count + anonymous_struct_count += 1 + else: + label = "anonymous_union_%d" % anonymous_union_count + anonymous_union_count += 1 + + return match.group(1) + " " + label + " {" + + +def manage_anonymous_structs_unions(text): + # Match anonymous unions/structs with this pattern: + # struct/union { + # [...] + # + # and substitute it in this way: + # + # struct anonymous_struct_# { + # [...] + # or + # union anonymous_union_# { + # [...] + # where # is a counter starting from zero, different between structs and + # unions + # The main limitation is that this script is called for each header and the + # counters are not global, so there can be anonymous_{struct/union}_# with + # the same name across headers. + # Doxygen will handle them correctly if they are part of another data + # structure because it will name them as + # upper_data_structure::anonymous_{struct/union}_#. + # + # We don't count anonymous union/struct that are part of a typedef because + # they don't create any issue for doxygen + text = re.sub( + "(? + * + * SPDX-License-Identifier: GPL-2.0 + */ + +#include "@XEN_BASE@/xen/include/xen/config.h" + +#if defined(CONFIG_X86_64) + +#define __x86_64__ 1 + +#elif defined(CONFIG_ARM_64) + +#define __aarch64__ 1 + +#elif defined(CONFIG_ARM_32) + +#define __arm__ 1 + +#else + +#error Architecture not supported/recognized. + +#endif