[XEN PATCH v5 0/2] use the documentation for MISRA C:2012 Dir 4.1

[XEN PATCH v5 0/2] use the documentation for MISRA C:2012 Dir 4.1

[Nicola Vetrini]

This series addresses some concerns raised on patches 2 and 3 from [1].
Note that patch 1 from that series has already been applied.

Patch 1 comprises a modified version of patches 2 and 3 of the previous series.
Patch 2 is brand new, as it merely clarifies how to write such documentation.

[1] https://lore.kernel.org/xen-devel/cover.1696231870.git.nicola.vetrini@bugseng.com/

Nicola Vetrini (2):
  automation/eclair: make the docs for MISRA C:2012 Dir 4.1 visible to
    ECLAIR
  docs/misra: add guidance on the format of  Dir 4.1 docs for ECLAIR

 automation/eclair_analysis/build.sh   | 31 +++++++++++++++++++++++----
 automation/eclair_analysis/prepare.sh |  7 +++---
 docs/misra/C-runtime-failures.rst     |  8 +++++++
 3 files changed, 39 insertions(+), 7 deletions(-)

-- 
2.34.1

[XEN PATCH v5 1/2] automation/eclair: make the docs for MISRA C:2012 Dir 4.1 visible to ECLAIR

[Nicola Vetrini]

To be able to check for the existence of the necessary subsections in
the documentation for MISRA C:2012 Dir 4.1, ECLAIR needs to have a source
file that is built.

This file is generated from 'C-runtime-failures.rst' in docs/misra
and the configuration is updated accordingly.

Signed-off-by: Nicola Vetrini <nicola.vetrini@bugseng.com>
---
Changes from RFC:
- Dropped unused/useless code
- Revised the sed command
- Revised the clean target

Changes in v2:
- Added explanative comment to the makefile
- printf instead of echo

Changes in v3:
- Terminate the generated file with a newline
- Build it with -std=c99, so that the documentation
  for D1.1 applies.
Changes in v4:
- Transform and build the file directly in the eclair-specific directory
Changes in v5:
- Small improvements
---
 automation/eclair_analysis/build.sh   | 31 +++++++++++++++++++++++----
 automation/eclair_analysis/prepare.sh |  7 +++---
 2 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/automation/eclair_analysis/build.sh b/automation/eclair_analysis/build.sh
index ec087dd822fa..122b93b80581 100755
--- a/automation/eclair_analysis/build.sh
+++ b/automation/eclair_analysis/build.sh
@@ -33,12 +33,35 @@ else
   PROCESSORS=6
 fi
 
+# Variables driving the build
+CC=${CROSS_COMPILE}gcc-12
+CXX=${CROSS_COMPILE}g++-12
+
+runtime_failures_docs() {
+  doc="C-runtime-failures.rst"
+  builddir="automation/eclair_analysis"
+  
+  cd "${builddir}"
+  printf "/*\n\n" >"${doc}.c"
+  sed -e 's|\*/|*//*|g' "../../docs/misra/${doc}" >>"${doc}.c"
+  
+  # At least a dummy decl is needed to comply with the C standard.
+  printf "\n\n*/\ntypedef int dummy_typedef;\n" >>"${doc}.c"
+  
+  # The C language standard applicable to Xen is C99 (with extensions),
+  # therefore even this dummy file needs to be compiled with -std=c99.
+  # Cannot redirect to /dev/null because it would be excluded from the analysis
+  "${CC}" -std=c99 -c "${doc}.c" -o "${doc}.o"
+  cd -
+}
+
 (
-  cd xen
+  runtime_failures_docs
 
   make "-j${PROCESSORS}" "-l${PROCESSORS}.0"    \
        "CROSS_COMPILE=${CROSS_COMPILE}"         \
-       "CC=${CROSS_COMPILE}gcc-12"              \
-       "CXX=${CROSS_COMPILE}g++-12"             \
-       "XEN_TARGET_ARCH=${XEN_TARGET_ARCH}"
+       "CC=${CC}"                               \
+       "CXX=${CXX}"                             \
+       "XEN_TARGET_ARCH=${XEN_TARGET_ARCH}"     \
+       -C xen
 )
diff --git a/automation/eclair_analysis/prepare.sh b/automation/eclair_analysis/prepare.sh
index 0cac5eba00ae..fe9d16e48ecc 100755
--- a/automation/eclair_analysis/prepare.sh
+++ b/automation/eclair_analysis/prepare.sh
@@ -35,11 +35,12 @@ else
 fi
 
 (
-    cd xen
-    cp "${CONFIG_FILE}" .config
+    ./configure
+    cp "${CONFIG_FILE}" xen/.config
     make clean
     find . -type f -name "*.safparse" -print -delete
-    make -f ${script_dir}/Makefile.prepare prepare
+    cd xen
+    make -f "${script_dir}/Makefile.prepare" prepare
     # Translate the /* SAF-n-safe */ comments into ECLAIR CBTs
     scripts/xen-analysis.py --run-eclair --no-build --no-clean
 )
-- 
2.34.1

Re: [XEN PATCH v5 1/2] automation/eclair: make the docs for MISRA C:2012 Dir 4.1 visible to ECLAIR

[Stefano Stabellini]

On Fri, 17 Nov 2023, Nicola Vetrini wrote:
> To be able to check for the existence of the necessary subsections in
> the documentation for MISRA C:2012 Dir 4.1, ECLAIR needs to have a source
> file that is built.
> 
> This file is generated from 'C-runtime-failures.rst' in docs/misra
> and the configuration is updated accordingly.
> 
> Signed-off-by: Nicola Vetrini <nicola.vetrini@bugseng.com>

It looks like you also addressed all Julien's comments appropriately

Re: [XEN PATCH v5 1/2] automation/eclair: make the docs for MISRA C:2012 Dir 4.1 visible to ECLAIR

[Stefano Stabellini]

On Tue, 28 Nov 2023, Stefano Stabellini wrote:
> On Fri, 17 Nov 2023, Nicola Vetrini wrote:
> > To be able to check for the existence of the necessary subsections in
> > the documentation for MISRA C:2012 Dir 4.1, ECLAIR needs to have a source
> > file that is built.
> > 
> > This file is generated from 'C-runtime-failures.rst' in docs/misra
> > and the configuration is updated accordingly.
> > 
> > Signed-off-by: Nicola Vetrini <nicola.vetrini@bugseng.com>
> 
> It looks like you also addressed all Julien's comments appropriately

I meant to add my reviewed-by

Reviewed-by: Stefano Stabellini <sstabellini@kernel.org>

Re: [XEN PATCH v5 1/2] automation/eclair: make the docs for MISRA C:2012 Dir 4.1 visible to ECLAIR

[Julien Grall]

Hi,

On 29/11/2023 04:16, Stefano Stabellini wrote:
> On Fri, 17 Nov 2023, Nicola Vetrini wrote:
>> To be able to check for the existence of the necessary subsections in
>> the documentation for MISRA C:2012 Dir 4.1, ECLAIR needs to have a source
>> file that is built.
>>
>> This file is generated from 'C-runtime-failures.rst' in docs/misra
>> and the configuration is updated accordingly.
>>
>> Signed-off-by: Nicola Vetrini <nicola.vetrini@bugseng.com>
> 
> It looks like you also addressed all Julien's comments appropriately

They are indeed. So I have committed the series.

Cheers,

-- 
Julien Grall

[XEN PATCH v5 2/2] docs/misra: add guidance on the format of Dir 4.1 docs for ECLAIR

[Nicola Vetrini]

Additional guidance on the formatting of the document for ECLAIR
is supplied.

Signed-off-by: Nicola Vetrini <nicola.vetrini@bugseng.com>
Reviewed-by: Stefano Stabellini <sstabellini@kernel.org>
Acked-by: Julien Grall <jgrall@amazon.com>
---
 docs/misra/C-runtime-failures.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/misra/C-runtime-failures.rst b/docs/misra/C-runtime-failures.rst
index 1052b2afca13..cac51d6b2596 100644
--- a/docs/misra/C-runtime-failures.rst
+++ b/docs/misra/C-runtime-failures.rst
@@ -12,6 +12,14 @@ built-in checks that are present in the language.
 The presence of such documentation is requested by MISRA C:2012 Directive 4.1,
 whose headline states: "Run-time failures shall be minimized".
 
+The ECLAIR checker for MISRA C:2012 Directive 4.1 requires the documentation
+to be supplied using the following format:
+
+``Documentation for MISRA C:2012 Dir 4.1: <category> <description>``
+
+The matched categories are the ones listed below (e.g., ``overflow`` and
+``unexpected wrapping``). The content of the description is not checked and can
+span multiple lines.
 
 Documentation for MISRA C:2012 Dir 4.1: overflow
 ________________________________________________
-- 
2.34.1

Re: [XEN PATCH v5 0/2] use the documentation for MISRA C:2012 Dir 4.1

[Nicola Vetrini]

On 2023-11-17 09:53, Nicola Vetrini wrote:
> This series addresses some concerns raised on patches 2 and 3 from [1].
> Note that patch 1 from that series has already been applied.
> 
> Patch 1 comprises a modified version of patches 2 and 3 of the previous 
> series.
> Patch 2 is brand new, as it merely clarifies how to write such 
> documentation.
> 
> [1] 
> https://lore.kernel.org/xen-devel/cover.1696231870.git.nicola.vetrini@bugseng.com/
> 
> Nicola Vetrini (2):
>   automation/eclair: make the docs for MISRA C:2012 Dir 4.1 visible to
>     ECLAIR
>   docs/misra: add guidance on the format of  Dir 4.1 docs for ECLAIR
> 
>  automation/eclair_analysis/build.sh   | 31 +++++++++++++++++++++++----
>  automation/eclair_analysis/prepare.sh |  7 +++---
>  docs/misra/C-runtime-failures.rst     |  8 +++++++
>  3 files changed, 39 insertions(+), 7 deletions(-)

I think all outstanding comments on this series have been addressed, so 
I think it could be committed.

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