From nobody Sat May 18 09:01:25 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass(p=none dis=none) header.from=kernel.org ARC-Seal: i=1; a=rsa-sha256; t=1654047869; cv=none; d=zohomail.com; s=zohoarc; b=AQr7WkmhTNsVn02ZUyY/9Tm3nH/jp/d6+93tYmEnlE81K6oEGYjjvSSVLUFcvmbOaA/ZOBcGrxoSGFpjRcJYXCfX9VTMfmrLUFlv631B7oN9FpLG8C0vmlEoVFANPgSiWnOuMz2bKnl/jwWDsMV1A7vhX/hWMss5DT7addh1daI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1654047869; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=3UwVzOXZHrOLzP/SCV2mjmTSjKtOZHjB6aX26tO2mUo=; b=kxvu+g4i+jSwURVPOGRVn8g8X0zHA5btbkjMWqw9t/nwoDjrXbUNHnkbUB7X9kZuYT71/xw/AJLcc5vK51hgLGL9SL7wwoaQBvS3cND+h5w2Lrs17oYErhuFQayhxRmdjKAmIMvoKPUkveLmFDWLt/baWrJbb54tzudJEu3KnpM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1654047869847874.8508114826526; Tue, 31 May 2022 18:44:29 -0700 (PDT) Received: from list by lists.xenproject.org with outflank-mailman.340157.565129 (Exim 4.92) (envelope-from ) id 1nwDP7-0000Qw-FY; Wed, 01 Jun 2022 01:44:09 +0000 Received: by outflank-mailman (output) from mailman id 340157.565129; Wed, 01 Jun 2022 01:44:09 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nwDP7-0000Q8-6a; Wed, 01 Jun 2022 01:44:09 +0000 Received: by outflank-mailman (input) for mailman id 340157; Wed, 01 Jun 2022 01:44:08 +0000 Received: from se1-gles-sth1-in.inumbo.com ([159.253.27.254] helo=se1-gles-sth1.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nwDP6-0000M1-GA for xen-devel@lists.xenproject.org; Wed, 01 Jun 2022 01:44:08 +0000 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by se1-gles-sth1.inumbo.com (Halon) with ESMTPS id 529f00ac-e14c-11ec-bd2c-47488cf2e6aa; Wed, 01 Jun 2022 03:44:07 +0200 (CEST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 82066614F0; Wed, 1 Jun 2022 01:44:05 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 68A72C385A9; Wed, 1 Jun 2022 01:44:04 +0000 (UTC) X-Outflank-Mailman: Message body and most headers restored to incoming version 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: 529f00ac-e14c-11ec-bd2c-47488cf2e6aa DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1654047844; bh=3LNFb9eaJ6ljtq7k9YOeH/I4pjqCITnxKzvBBuGvkIo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uM65ol6KI7QKERi++wgwRfjAUZrM3IZs0C6dDBVZpfO80Is7zlNwU/jTF9A3bmvOm vPDBoIXF2wJiv/ivYry7+RGr2dng5td+EMG0yOJGEs5jDCziEWFLq8KQEAdcSfx05O hwcpFG2I045gwvq//B8ol3JIl7MUuBK2/nLkRX/lCfi6uboERzn/v8XEPkXDf//fWf nzBlryIiN4rFhdUq4LZh2ByfR2sCbyy3J+y/uP3ZMIqbAdRDVLF1jmQGnLjuih0BTm r64vqeBrv21ug9tgX92sAA3qzHYmDxpyDZlt99LUHjOy+xJCrtQDQ6jZVoOt1hAAHZ ZnFEhXva3Peew== From: Stefano Stabellini To: xen-devel@lists.xenproject.org Cc: sstabellini@kernel.org, andrew.cooper3@citrix.com, jbeulich@suse.com, roger.pau@citrix.com, julien@xen.org, Bertrand.Marquis@arm.com, George.Dunlap@citrix.com, Stefano Stabellini , Bertrand Marquis Subject: [PATCH v2 1/2] docs/misra: introduce rules.rst Date: Tue, 31 May 2022 18:44:01 -0700 Message-Id: <20220601014402.2293524-1-sstabellini@kernel.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @kernel.org) X-ZM-MESSAGEID: 1654047872001100003 Content-Type: text/plain; charset="utf-8" From: Stefano Stabellini Introduce a list of MISRA C rules that apply to the Xen hypervisor. The list is in RST format. Specify that rules deviations need to be documented. Introduce a documentation tag for in-code comments to mark them as deviations. Also mention that other documentation mechanisms are work-in-progress. Add a mention of the new list to CODING_STYLE. Signed-off-by: Stefano Stabellini Signed-off-by: Bertrand Marquis Acked-by: Julien Grall --- Note that I don't feel strongly about the deviations format. At this stage anything is OK in my view. We'll need to improve it as we go along and as we start to integrate better with MISRA C checkers. That said, certainly an in-code comment with a special tag is a safe bet in terms of tools integration (easy to parse, easy to convert.) We'll need other mechanisms too and that's why I kept the sentence about "Other documentation mechanisms are work-in-progress." Changes in v2: - clarify that deviations are permitted - introduce an in-code tag for deviations - improve the document format, make it proper reStructuredText - improve commit message --- CODING_STYLE | 6 +++ docs/index.rst | 12 +++++ docs/misra/rules.rst | 123 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 141 insertions(+) create mode 100644 docs/misra/rules.rst diff --git a/CODING_STYLE b/CODING_STYLE index 9f50d9cec4..3386ee1d90 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -14,6 +14,12 @@ explicitly (e.g. tools/libxl/CODING_STYLE) but often imp= licitly (Linux coding style is fairly common). In general you should copy the style of the surrounding code. If you are unsure please ask. =20 +MISRA C +------- + +The Xen Hypervisor follows some MISRA C coding rules. See +docs/misra/rules.rst for details. + Indentation ----------- =20 diff --git a/docs/index.rst b/docs/index.rst index b75487a05d..2c47cfa999 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -53,6 +53,18 @@ kind of development environment. hypervisor-guide/index =20 =20 +MISRA C coding guidelines +------------------------- + +MISRA C rules and directive to be used as coding guidelines when writing +Xen hypervisor code. + +.. toctree:: + :maxdepth: 2 + + misra/rules + + Miscellanea ----------- =20 diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst new file mode 100644 index 0000000000..7d6a9fe063 --- /dev/null +++ b/docs/misra/rules.rst @@ -0,0 +1,123 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +MISRA C rules for Xen +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. note:: + + **IMPORTANT** All MISRA C rules, text, and examples are copyrighted + by the MISRA Consortium Limited and used with permission. + + Please refer to https://www.misra.org.uk/ to obtain a copy of MISRA + C, or for licensing options for other use of the rules. + +The following is the list of MISRA C rules that apply to the Xen +hypervisor. + +It is possible that in specific circumstances it is best not to follow a +rule because it is not possible or because the alternative leads to +better code quality. Those cases are called "deviations". They are +permissible as long as they are documented as an in-code comment using +the following format:: + + /* + * MISRA_DEV: Rule ID + * Justification text. + */ + +Other documentation mechanisms are work-in-progress. + +The existing codebase is not 100% compliant with the rules. Some of the +violations are meant to be documented as deviations, while some others +should be fixed. Both compliance and documenting deviations on the +existing codebase are work-in-progress. + +.. list-table:: + :header-rows: 1 + + * - Dir number + - Severity + - Summary + - Notes + + * - `Dir 2.1 `_ + - Required + - All source files shall compile without any compilation errors + - + + * - `Dir 4.7 `_ + - Required + - If a function returns error information then that error + information shall be tested + - + + * - `Dir 4.10 `_ + - Required + - Precautions shall be taken in order to prevent the contents of a + header file being included more than once + - + + * - `Dir 4.14 `_ + - Required + - The validity of values received from external sources shall be + checked + - + +.. list-table:: + :header-rows: 1 + + * - Rule number + - Severity + - Summary + - Notes + + * - `Rule 1.3 `_ + - Required + - There shall be no occurrence of undefined or critical unspecified + behaviour + - + + * - `Rule 3.2 `_ + - Required + - Line-splicing shall not be used in // comments + - + + * - `Rule 6.2 `_ + - Required + - Single-bit named bit fields shall not be of a signed type + - + + * - `Rule 8.1 `_ + - Required + - Types shall be explicitly specified + - + + * - `Rule 8.4 `_ + - Required + - A compatible declaration shall be visible when an object or + function with external linkage is defined + - + + * - `Rule 8.5 `_ + - Required + - An external object or function shall be declared once in one and on= ly one file + - + + * - `Rule 8.6 `_ + - Required + - An identifier with external linkage shall have exactly one + external definition + - Declarations without definitions are allowed (specifically when + the definition is compiled-out or optimized-out by the compiler) + + * - `Rule 8.8 `_ + - Required + - The static storage class specifier shall be used in all + declarations of objects and functions that have internal linkage + - + + * - `Rule 8.12 `_ + - Required + - Within an enumerator list the value of an implicitly-specified + enumeration constant shall be unique + - --=20 2.25.1 From nobody Sat May 18 09:01:25 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass(p=none dis=none) header.from=kernel.org ARC-Seal: i=1; a=rsa-sha256; t=1654047870; cv=none; d=zohomail.com; s=zohoarc; b=GGrRTD+NtYs8Dy/tcg5vAM5meVM0XYlyVsBfiUhUFX+OninVtryPjq7JCZfhbrwMyUP9J42d3GgQ9B4Poud1VR6IqjKl2hoCkBSVxCkZ0yIPNLBwvZHVdqkCn6CFGdDqSGUnXNPKDYAfRpa4vn60LDIETVLN38mJkt2asfuPqSU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1654047870; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=uafhN965OFTjkELraCRrzP6Sahgjga0nWPhLW279R60=; b=Viy1afYPQI9du1HC26SSxeao/x+WJ4so8v5i3S+tfDG5o1SZXzE0c6sS/6yS8FtS8ep/pBTfwlytJmk6WoHczASUQmZYPd/3blyeeIeiuYwGjnxc1pLvSQoycqUO12zKSm8QPjkY/tSHABgChNDeCAdHQHrv6fIU75GJlb6+SIY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1654047870694955.9725795254196; Tue, 31 May 2022 18:44:30 -0700 (PDT) Received: from list by lists.xenproject.org with outflank-mailman.340156.565123 (Exim 4.92) (envelope-from ) id 1nwDP6-0000Mh-W5; Wed, 01 Jun 2022 01:44:08 +0000 Received: by outflank-mailman (output) from mailman id 340156.565123; Wed, 01 Jun 2022 01:44:08 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nwDP6-0000MY-Sg; Wed, 01 Jun 2022 01:44:08 +0000 Received: by outflank-mailman (input) for mailman id 340156; Wed, 01 Jun 2022 01:44:07 +0000 Received: from se1-gles-flk1-in.inumbo.com ([94.247.172.50] helo=se1-gles-flk1.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nwDP5-0008Ua-N7 for xen-devel@lists.xenproject.org; Wed, 01 Jun 2022 01:44:07 +0000 Received: from ams.source.kernel.org (ams.source.kernel.org [145.40.68.75]) by se1-gles-flk1.inumbo.com (Halon) with ESMTPS id 5319790f-e14c-11ec-837f-e5687231ffcc; Wed, 01 Jun 2022 03:44:07 +0200 (CEST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id BBAE8B8175B; Wed, 1 Jun 2022 01:44:06 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 17BBFC3411C; Wed, 1 Jun 2022 01:44:05 +0000 (UTC) X-Outflank-Mailman: Message body and most headers restored to incoming version 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: 5319790f-e14c-11ec-837f-e5687231ffcc DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1654047845; bh=WcTGrMPln2r4PN7xO0mKkWVF8X4wWkx3gFpXJmHXKEQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nRGVkIGNwipP5Hv6OA8LFhVgl711eabBTutfxMp3T56F/51EHJHXBupb6vQqC0Xph Ndy95yMWel2pcgn9/g/aS7hyrXIQrPUVoF7Sd8p7prUUbpEAfE9AkXcbfpm2fXARm1 fgInc9I+f5DVW9fBxsYdyC8aOA2GcQtXQMbInYf8fBO4N9SfgQJlF4q1gCjSYfWNFm E7VTkieOtkk1E7QnF0EiWddNxxdAL4qvZZKL1qcLRHnyf46cPtV/zNSlCqshnOZKRv M4O8ylTJnobKO6XeLTDM5g/kOxOv40oY7667zNxJ/AvIOtXKuJU2cO3Zb1csnwPHGL 29SrcaD2YAH6w== From: Stefano Stabellini To: xen-devel@lists.xenproject.org Cc: sstabellini@kernel.org, andrew.cooper3@citrix.com, jbeulich@suse.com, roger.pau@citrix.com, julien@xen.org, Bertrand.Marquis@arm.com, George.Dunlap@citrix.com, Stefano Stabellini Subject: [PATCH v2 2/2] docs/misra: add Rule 5.1 Date: Tue, 31 May 2022 18:44:02 -0700 Message-Id: <20220601014402.2293524-2-sstabellini@kernel.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @kernel.org) X-ZM-MESSAGEID: 1654047871937100001 Content-Type: text/plain; charset="utf-8" From: Stefano Stabellini Add Rule 5.1, with the additional note that the character limit for Xen is 40 characters. The max length identifiers found by ECLAIR are: __mitigate_spectre_bhb_clear_insn_start domain_pause_by_systemcontroller_nosync Both of them are 40 characters long. Explicitly mention that public headers might have longer identifiers. Signed-off-by: Stefano Stabellini Acked-by: Julien Grall --- Changes in v2: - lower the limit to 40 - mention public headers - improve commit message --- docs/misra/rules.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst index 7d6a9fe063..6ccff07765 100644 --- a/docs/misra/rules.rst +++ b/docs/misra/rules.rst @@ -82,6 +82,13 @@ existing codebase are work-in-progress. - Line-splicing shall not be used in // comments - =20 + * - `Rule 5.1 `_ + - Required + - External identifiers shall be distinct + - The Xen characters limit for identifiers is 40. Public headers + (xen/include/public/) are allowed to retain longer identifiers + for backward compatibility. + * - `Rule 6.2 `_ - Required - Single-bit named bit fields shall not be of a signed type --=20 2.25.1