The headline of Directive 4.1 states: "Run-time failures shall be minimized".
Thus, it requires the project to supply documentation that pertains the measures
and techinques used to prevent run-time failures from happening. For ease of
reading, the documentation is in RST format, but since ECLAIR needs a source file
to check that the needed subsections and their format is the one expected, the
Makefiles for the docs/ are amended to generate such a file.

The format and categories of the subsections in the .rst file can be
customized based on feedback from the community: the one provided is just a
basic skeleton that should be tailored to the project.

CC-ing also Henry Wang, as these are just documentation and CI changes

Nicola Vetrini (3):
  docs/misra: add documentation skeleton for MISRA C:2012 Dir 4.1
  docs: make the docs for MISRA C:2012 Dir 4.1 visible to ECLAIR
  automation/eclair: build docs/misra to address MISRA C:2012 Dir 4.1

 automation/eclair_analysis/build.sh   |   6 +-
 automation/eclair_analysis/prepare.sh |   4 +-
 docs/Makefile                         |   7 +-
 docs/misra/C-runtime-failures.rst     | 200 ++++++++++++++++++++++++++
 docs/misra/Makefile                   |  22 +++
 docs/misra/rules.rst                  |   8 +-
 6 files changed, 240 insertions(+), 7 deletions(-)
 create mode 100644 docs/misra/C-runtime-failures.rst
 create mode 100644 docs/misra/Makefile

--
2.34.1

On 27/09/2023 11:52, Nicola Vetrini wrote:
> The headline of Directive 4.1 states: "Run-time failures shall be 
> minimized".
> Thus, it requires the project to supply documentation that pertains the 
> measures
> and techinques used to prevent run-time failures from happening. For 
> ease of
> reading, the documentation is in RST format, but since ECLAIR needs a
> source file
> to check that the needed subsections and their format is the one 
> expected, the
> Makefiles for the docs/ are amended to generate such a file.
> 
> The format and categories of the subsections in the .rst file can be
> customized based on feedback from the community: the one provided is 
> just a
> basic skeleton that should be tailored to the project.
> 
> CC-ing also Henry Wang, as these are just documentation and CI changes
> 
> Nicola Vetrini (3):
>   docs/misra: add documentation skeleton for MISRA C:2012 Dir 4.1
>   docs: make the docs for MISRA C:2012 Dir 4.1 visible to ECLAIR
>   automation/eclair: build docs/misra to address MISRA C:2012 Dir 4.1
> 
>  automation/eclair_analysis/build.sh   |   6 +-
>  automation/eclair_analysis/prepare.sh |   4 +-
>  docs/Makefile                         |   7 +-
>  docs/misra/C-runtime-failures.rst     | 200 ++++++++++++++++++++++++++
>  docs/misra/Makefile                   |  22 +++
>  docs/misra/rules.rst                  |   8 +-
>  6 files changed, 240 insertions(+), 7 deletions(-)
>  create mode 100644 docs/misra/C-runtime-failures.rst
>  create mode 100644 docs/misra/Makefile
> 
> --
> 2.34.1

CC-ing Luca as well:
I'm testing the next version of this series, and I'm seeing a failure on 
cppcheck
containers on this pipeline [1]. I'm not sure about what is causing that 
conversion script
to fail. Any pointer in debugging this would be greatly appreciated.

[1] 
https://gitlab.com/xen-project/people/bugseng/xen/-/pipelines/1020917280

-- 
Nicola Vetrini, BSc
Software Engineer, BUGSENG srl (https://bugseng.com)

> 
> CC-ing Luca as well:
> I'm testing the next version of this series, and I'm seeing a failure on cppcheck
> containers on this pipeline [1]. I'm not sure about what is causing that conversion script
> to fail. Any pointer in debugging this would be greatly appreciated.
> 
> [1] https://gitlab.com/xen-project/people/bugseng/xen/-/pipelines/1020917280

Hi Nicola,

In the logs I can see:

+ xen/scripts/xen-analysis.py --run-cppcheck --cppcheck-misra -- -j80
No notes for rule 2.1
WARNING: Can't open /builds/xen-project/people/bugseng/xen/xen/drivers/video/font_8x14.c: 'utf-8' codec can't decode byte 0x9f in position 7228: invalid start byte
WARNING: Can't open /builds/xen-project/people/bugseng/xen/xen/drivers/video/font_8x16.c: 'utf-8' codec can't decode byte 0x80 in position 5436: invalid start byte
WARNING: Can't open /builds/xen-project/people/bugseng/xen/xen/drivers/video/font_8x8.c: 'utf-8' codec can't decode byte 0x80 in position 4410: invalid start byte
ERROR: An error occured when running:
/builds/xen-project/people/bugseng/xen/xen/tools/convert_misra_doc.py -i /builds/xen-project/people/bugseng/xen/docs/misra/rules.rst -o /builds/xen-project/people/bugseng/xen/xen/cppcheck-misra.txt -j /builds/xen-project/people/bugseng/xen/xen/cppcheck-misra.json

So I think that the rules.rst doesn’t have the expected syntax, on patch 1 try to leave the third ‘-‘ on the rule 2.1:

* - `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
-

Cheers,
Luca

Hi Nicola,

> On Sep 27, 2023, at 17:52, Nicola Vetrini <nicola.vetrini@bugseng.com> wrote:
> 
> The headline of Directive 4.1 states: "Run-time failures shall be minimized".
> Thus, it requires the project to supply documentation that pertains the measures
> and techinques used to prevent run-time failures from happening. For ease of
> reading, the documentation is in RST format, but since ECLAIR needs a source file
> to check that the needed subsections and their format is the one expected, the
> Makefiles for the docs/ are amended to generate such a file.
> 
> The format and categories of the subsections in the .rst file can be
> customized based on feedback from the community: the one provided is just a
> basic skeleton that should be tailored to the project.
> 
> CC-ing also Henry Wang, as these are just documentation and CI changes

Indeed, so technically it is safe to include this series to 4.18, if this series can
be properly reviewed, I am ok to add my release-ack tag for each patch:

Release-acked-by: Henry Wang <Henry.Wang@arm.com>

Kind regards,
Henry


> 
> Nicola Vetrini (3):
>  docs/misra: add documentation skeleton for MISRA C:2012 Dir 4.1
>  docs: make the docs for MISRA C:2012 Dir 4.1 visible to ECLAIR
>  automation/eclair: build docs/misra to address MISRA C:2012 Dir 4.1
> 
> automation/eclair_analysis/build.sh   |   6 +-
> automation/eclair_analysis/prepare.sh |   4 +-
> docs/Makefile                         |   7 +-
> docs/misra/C-runtime-failures.rst     | 200 ++++++++++++++++++++++++++
> docs/misra/Makefile                   |  22 +++
> docs/misra/rules.rst                  |   8 +-
> 6 files changed, 240 insertions(+), 7 deletions(-)
> create mode 100644 docs/misra/C-runtime-failures.rst
> create mode 100644 docs/misra/Makefile
> 
> --
> 2.34.1