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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Wed, 25 May 2022, Andrew Cooper wrote:
> 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.)

Thanks I did that and I can see that the layout needs a lot of
improvements.


> 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 ?

I would keep the actual MISRA files in their own top-level directory
under docs/ but we can certainly link to them from docs/index.rst or
from hypervisor guide. What about the following added to docs/index.rst:

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



> >  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".

Yep, I can do that


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

Ah yes, thank you



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

It looks like that patch didn't make it upstream? But I can just use the
following format and it works with make -C docs sphinx-html:


   * - `Dir 2.1 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_02_01.c>`_
     - Required
     - All source files shall compile without any compilation errors
     -

the format is `description <link>`_