[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH 1/2] docs/misra: introduce rules.rst


  • To: Stefano Stabellini <sstabellini@xxxxxxxxxx>, "xen-devel@xxxxxxxxxxxxxxxxxxxx" <xen-devel@xxxxxxxxxxxxxxxxxxxx>
  • From: Andrew Cooper <Andrew.Cooper3@xxxxxxxxxx>
  • Date: Wed, 25 May 2022 12:21:14 +0000
  • Accept-language: en-GB, en-US
  • Arc-authentication-results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=citrix.com; dmarc=pass action=none header.from=citrix.com; dkim=pass header.d=citrix.com; arc=none
  • Arc-message-signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=LRKICtsLLPt+yG34fs/Zlwu61EhRNr9vBmK9Wjs05gE=; b=RTNr54eurAwegZawLv3gvy56U/00+Wdm/79QL7Y3FHQGO7cQTFOrwf+imCmSUQtu+tPSwXm9r+NOTxg/M+E6GZdtwyz1EG59nBu2EACfuxGyd/WP+pqKYMD+5RrXa9/rZK62JfqhYKsk+hYvyQ6tx7hePKUZ3tYO+EXUpGKAWXLVaFiMY6QnxDHUZMjnR9vig0iHVqEoxEkrWv2Qv7QDBhq74XAPIX7pJKsq0CKubTB0ZBZn7RP5h4cx0VNh3fzO4zNHas/XksQ0edxfrXcWNQdcUahcGNvVx0y20jqdmttDejfxNs4gZVPqpNyaKWX3UFg1kx/kw48SoTeBWZcQhQ==
  • Arc-seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Mptxkxz1c58ML8TZymVqYOhd1URt7X8AkqaWPOZuh0SfcMIkvKJEHFqXkuo5rh6p3E5B3EBWRDD81aYUeIC5ujtcgRv5WzZgwRSl5kMYDJXpvW7sKc/ThF0suG4NheL95InuDyEJI2slwwo6CLVJzgxjQpujNaY+nzEBfBaQt75GWsr5QR6wIK+esj3Ecub4EvDxmuRHF+f3HujC8cIPQYjRIDS8Ykkdgx1TKuKi3GzUwLpcUARyOtqWEKHusr03rztURDBBbK80KgbX5n9Nk+Sy5vox+5WmYlglZUDhjOQAeiE1bhc3/LTao+ny4Fbr0pISt5w6lwsmYkCGkOckWA==
  • Authentication-results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=citrix.com;
  • Cc: "jbeulich@xxxxxxxx" <jbeulich@xxxxxxxx>, Roger Pau Monne <roger.pau@xxxxxxxxxx>, "julien@xxxxxxx" <julien@xxxxxxx>, "Bertrand.Marquis@xxxxxxx" <Bertrand.Marquis@xxxxxxx>, George Dunlap <George.Dunlap@xxxxxxxxxx>, Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>
  • Delivery-date: Wed, 25 May 2022 12:21:45 +0000
  • Ironport-data: A9a23:02Yiyqhn5qKuiu22cVdZD11/X161rxEKZh0ujC45NGQN5FlHY01je htvWmmPOK6LZGD1L95wbIux8BxUsJTVzt5lSABrqiFnQygb9cadCdqndUqhZCn6wu8v7a5EA 2fyTvGacajYm1eF/k/F3oDJ9CU6jefSLlbFILas1hpZHGeIcw98z0M68wIFqtQw24LhXlnQ4 YqaT/D3YzdJ5RYlagr41IrbwP9flKyaVOQw5wFWiVhj5TcyplFNZH4tDfjZw0jQG+G4KtWSV efbpIxVy0uCl/sb5nFJpZ6gGqECaua60QFjERO6UYD66vRJjnRaPqrWqJPwwKqY4tmEt4kZ9 TlDiXC/YVciIafpx/Y6bzAbShxDO/dh/Ib3L3fq5KR/z2WeG5ft69NHKRlseKE9oaNwC2wI8 uEEIjcQaBzFn/ix3L+wVuhrgIIkMdXvO4Qc/HpnyFk1D95/GcyFH/qMuIEegGxYasNmRJ4yY +IwbzZ1YQuGSBpIIloNU7o1nfuyh2m5eDpdwL6QjfVtvjSKlV0puFTrGMuPa4GgGspop2yRv 2fJ9VzyLDMwbuXKnFJp9Vrp3IcjhxjTQ5kOHbe18vprhly7xWEJDhASE1yhrpGRmkO4Ht5SN UEQ0i4vtrQpslymSMHnWB+1q2LCuQQTM/JSGeAn7ACGyoLP/h2UQGMDS1ZpasEitcIwbSwn0 BmOhdyBLRZiqqGPQHSRsJKdtyqvODM9JHUHIyQDSGMt+MXurog1iVTUUt9pHaqxj9v0MSHxx zGMvG41gLB7sCIQ/6Cy/FSCjzf3oJHMFlEx/l+PAjnj6R5lbom4YYDu8ULc8ftLMIeeSB+Go WQAnM+dqusJCPlhiRCwfQnEJ5nxj97tDdEWqQUH80UJn9h1x0OeQA==
  • Ironport-hdrordr: A9a23:nEEHZ6+yn3PiHEV6Yzpuk+G5dr1zdoMgy1knxilNoENuH/Bwxv rFoB1E73TJYW4qKQMdcBW7Sd+9qADnhOtICOgqTPaftWzd1FdAQ7sSk7fK7wfJIjb5/OJGz6 tsGpIOUeEYYWIK9voSpTPIYOrIo+P3sJxA592uvkuFJDsCA84PnmQJaHfjYzVLqRF9ZabRVq DslvavzwDQO0j/Bf7Le0XtKtKz2OEj46iWHSLuaSRXkjVmuQnYrYLSIly1zx0aWzNKzawC93 LZnwHC5qulu+ym0RPHk0ve9Y5fltfZ0d1ICNaXhsV9EESIti+YIKhxUbiLvDQ4u8Gq8U0rl8 TlqQohOcMb0QK2QkiF5Tf90Qzp0DIj8F/n0ESZhmbHqdH0QzgrYvAx4r5xQ1/0+kAktNF53L lzxGSJp79eEB/GljSV3amta/gmrDvvnZLs+dRjwUB3YM87Uvt8vIYf9ERaHNMpGz/70pkuFK 1UAMTV9J9tAB6nhySyhAhS6e3pek52MgaNQ0AEtMDQ+SNRhmpFw0wRw9Fatmsc9bomIqM0tN jsA+BNrvVjX8UWZaVyCKMqWs2sEFHARhrKLSa7PUnnLqcaIHjAwqSHsInd3NvaKqDg8aFCxq gpEWko6lLaQnieVfFmCac7oywkQw2GLH7QI49lltsJ74EVgtLQQGm+oRsV4r+dSs4kc4Tmsy zaAuMRPxbSFxqoJW8A5XyIZ3BzEwhHbCRHgKdhZ7p5yvi7ZbEDiITgAb3uzE2EK0dpZoq4OA pfYNHaHrQJ0nyW
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>
  • Thread-index: AQHYb89OVlMbfNQEIke7o99YDeB9D60vhDsA
  • Thread-topic: [PATCH 1/2] docs/misra: introduce rules.rst

On 25/05/2022 01:35, Stefano Stabellini wrote:
> From: Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>
>
> Introduce a list of MISRA C rules that apply to the Xen hypervisor. The
> list is in RST format.
>
> Add a mention of the new list to CODING_STYLE.
>
> Signed-off-by: Bertrand Marquis <bertrand.marquis@xxxxxxx>
> Signed-off-by: Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>

Some comments on syntax/layout, unrelated to the specific content.

You can check the rendered content with either `make -C docs
sphinx-html` locally, or by pointing readthedocs at your repo.  (e.g.
https://andrewcoop-xen.readthedocs.io/en/docs-devel/ is a very out of
date WIP branch of some in-development content.)

Whatever gets committed will be rendered at
https://xenbits.xen.org/docs/latest/ once the cronjob catches up.

> ---
>  CODING_STYLE         |  6 ++++
>  docs/misra/rules.rst | 65 ++++++++++++++++++++++++++++++++++++++++++++

At minimum there needs to be an addition to a toctree directive in on of
the existing index.rst's

But  this looks like it ought to be part of the hypervisor guide ?

>  2 files changed, 71 insertions(+)
>  create mode 100644 docs/misra/rules.rst
>
> diff --git a/CODING_STYLE b/CODING_STYLE
> index 9f50d9cec4..1ef35ee8d0 100644
> --- a/CODING_STYLE
> +++ b/CODING_STYLE
> @@ -235,3 +235,9 @@ callstack between the initial function call and the 
> failure, no error
>  is returned.  Using domain_crash() requires careful inspection and
>  documentation of the code to make sure all callers at the stack handle
>  a newly-dead domain gracefully.
> +
> +MISRA C
> +-------
> +
> +The Xen Project hypervisor follows the MISRA C coding rules and
> +directives listed under docs/misra/rules.rst.

I think this would be clearer to follow as:

"The Xen Hypervisor follows some MISRA C coding rules.  See ... for
details."

because otherwise there is an implication that we follow all rules. 
Also, "Xen Project" might be the name of our legal entity name, but the
hypervisor's name is Xen, not "Xen Project".

> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> new file mode 100644
> index 0000000000..c0ee58ab25
> --- /dev/null
> +++ b/docs/misra/rules.rst
> @@ -0,0 +1,65 @@

All Sphinx content needs to be

.. SPDX-License-Identifier: CC-BY-4.0

so it specifically can be vendored/tailored by downstream entities.

> +=====================
> +MISRA C rules for Xen
> +=====================

And the prevailing style is without the === overline.

> +
> +**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.

.. note::

and then with the two paragraphs indented to be a part of the note block.

> +
> +The following is the list of MISRA C rules that apply to the Xen Project
> +hypervisor.
> +
> +- Rule: Dir 2.1
> +  - Severity:  Required
> +  - Summary:  All source files shall compile without any compilation errors
> +  - Link:  
> https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_02_01.c

This wants to be .. list-table::  See
docs/guest-guide/x86/hypercall-abi.rst for an example.

Also, the URL wants to use the ext-links plugin.  See
https://lore.kernel.org/xen-devel/20191003205623.20839-4-andrew.cooper3@xxxxxxxxxx/

~Andrew

 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.