diff mbox series

docs/misra: document gcc-specific behavior with shifting signed integers

Message ID 20230819003303.1744466-1-sstabellini@kernel.org (mailing list archive)
State Superseded
Headers show
Series docs/misra: document gcc-specific behavior with shifting signed integers | expand

Commit Message

Stefano Stabellini Aug. 19, 2023, 12:33 a.m. UTC
From: Stefano Stabellini <stefano.stabellini@amd.com>

Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
---
Changes in v2:
- use "shift" instead of << or >>
- use All Architectures (I haven't changed all the other instances of
x86/arm in the file yet)
---
 docs/misra/C-language-toolchain.rst | 6 ++++++
 1 file changed, 6 insertions(+)

Comments

Jan Beulich Aug. 21, 2023, 7:17 a.m. UTC | #1
On 19.08.2023 02:33, Stefano Stabellini wrote:
> From: Stefano Stabellini <stefano.stabellini@amd.com>
> 
> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
> ---
> Changes in v2:
> - use "shift" instead of << or >>
> - use All Architectures (I haven't changed all the other instances of
> x86/arm in the file yet)
> ---
>  docs/misra/C-language-toolchain.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/docs/misra/C-language-toolchain.rst b/docs/misra/C-language-toolchain.rst
> index 785aed1eaf..f5ca7bd2c8 100644
> --- a/docs/misra/C-language-toolchain.rst
> +++ b/docs/misra/C-language-toolchain.rst
> @@ -200,6 +200,12 @@ The table columns are as follows:
>       - ARM64, X86_64
>       - See Section "6.29 Designated Initializers" of GCC_MANUAL
>  
> +   * - Signed shift acts on negative numbers by sign extension
> +     - All architectures
> +     - See Section "4.5 Integers" of GCC_MANUAL. As an extension to the
> +       C language, GCC does not use the latitude given in C99 and C11
> +       only to treat certain aspects of signed shift as undefined.

I'm sorry, but that's still not what the doc says. Replacing << and >> by
"shifts" was imo wrong. What's needed instead is that either this is split
into two top-level bullet points (one for << and one for >>), or the first
sub-bullet-point (which acts as kind of the title) be generalized, with
the << and >> details fully moved to the "explanatory" sub-bullet-point.

Jan
Stefano Stabellini Aug. 22, 2023, 1:02 a.m. UTC | #2
On Mon, 21 Aug 2023, Jan Beulich wrote:
> On 19.08.2023 02:33, Stefano Stabellini wrote:
> > From: Stefano Stabellini <stefano.stabellini@amd.com>
> > 
> > Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
> > ---
> > Changes in v2:
> > - use "shift" instead of << or >>
> > - use All Architectures (I haven't changed all the other instances of
> > x86/arm in the file yet)
> > ---
> >  docs/misra/C-language-toolchain.rst | 6 ++++++
> >  1 file changed, 6 insertions(+)
> > 
> > diff --git a/docs/misra/C-language-toolchain.rst b/docs/misra/C-language-toolchain.rst
> > index 785aed1eaf..f5ca7bd2c8 100644
> > --- a/docs/misra/C-language-toolchain.rst
> > +++ b/docs/misra/C-language-toolchain.rst
> > @@ -200,6 +200,12 @@ The table columns are as follows:
> >       - ARM64, X86_64
> >       - See Section "6.29 Designated Initializers" of GCC_MANUAL
> >  
> > +   * - Signed shift acts on negative numbers by sign extension
> > +     - All architectures
> > +     - See Section "4.5 Integers" of GCC_MANUAL. As an extension to the
> > +       C language, GCC does not use the latitude given in C99 and C11
> > +       only to treat certain aspects of signed shift as undefined.
> 
> I'm sorry, but that's still not what the doc says. Replacing << and >> by
> "shifts" was imo wrong. What's needed instead is that either this is split
> into two top-level bullet points (one for << and one for >>), or the first
> sub-bullet-point (which acts as kind of the title) be generalized, with
> the << and >> details fully moved to the "explanatory" sub-bullet-point.

I think I got your point now
diff mbox series

Patch

diff --git a/docs/misra/C-language-toolchain.rst b/docs/misra/C-language-toolchain.rst
index 785aed1eaf..f5ca7bd2c8 100644
--- a/docs/misra/C-language-toolchain.rst
+++ b/docs/misra/C-language-toolchain.rst
@@ -200,6 +200,12 @@  The table columns are as follows:
      - ARM64, X86_64
      - See Section "6.29 Designated Initializers" of GCC_MANUAL
 
+   * - Signed shift acts on negative numbers by sign extension
+     - All architectures
+     - See Section "4.5 Integers" of GCC_MANUAL. As an extension to the
+       C language, GCC does not use the latitude given in C99 and C11
+       only to treat certain aspects of signed shift as undefined.
+
 
 Translation Limits
 __________________