RE: 0005-Part-5.-Add-x86-CET-documentation

["Tsimbalist, Igor V" <igor.v.tsimbalist@intel.com>]

[-- Attachment #1: Type: text/plain, Size: 7492 bytes --]

Updated version #3.

> -----Original Message-----
> From: Sandra Loosemore [mailto:sandra@codesourcery.com]
> Sent: Wednesday, September 27, 2017 5:41 AM
> To: Tsimbalist, Igor V <igor.v.tsimbalist@intel.com>; Uros Bizjak
> <ubizjak@gmail.com>
> Cc: gcc-patches@gcc.gnu.org
> Subject: Re: 0005-Part-5.-Add-x86-CET-documentation
> 
> On 09/26/2017 07:47 AM, Tsimbalist, Igor V wrote:
> > Here is a new version of the patch.
> >
> > diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index
> > a374890..a900ed1 100644
> > --- a/gcc/doc/extend.texi
> > +++ b/gcc/doc/extend.texi
> > @@ -5655,6 +5655,13 @@ compiled with the
> > @option{-fcf-protection=branch} option.  The  compiler assumes that
> > the function's address is a valid target for a  control-flow transfer.
> >
> > +@emph{x86 implementation:} when @option{-fcf-protection} option is
> > +specified the compiler inserts an ENDBR instruction at function's
> > +prologue if the function's type does not have the @code{nocf_check}
> > +attribute and addresses to which indirect control-flow transfer can
> > +happen.  The instruction triggers the HW check if a control-flow
> > +transfer to the address of ENDBR instruction is valid.
> 
> Implementation details like this should be comments in the code, not
> included in the user-facing documentation.
> 
> > @@ -5662,7 +5669,8 @@ not be instrumented when compiled with the
> that
> > the function's address from the pointer is a valid target for  a
> > control-flow transfer.  A direct function call through a function
> > name is assumed to be a safe call thus direct calls are not
> > -instrumented by the compiler.
> > +instrumented by the compiler.  For @emph{x86 implementation} the
> > +compiler inserts a NOTRACK prefix before an indirect call instruction.
> 
> Likewise here.

For this comment and above could you please let me know what is the right place
To move the description? Also I enclosed ENDBR and NOTRACK in @code{} and
wrote it in lower case.

> > @@ -21217,6 +21225,25 @@ void __builtin_ia32_wrpkru (unsigned int)
> > unsigned int __builtin_ia32_rdpkru ()  @end smallexample
> >
> > +The following built-in functions are available when @option{-mcet} is
> used.
> > +They are used to support Intel Control-flow Enforcment Technology (CET).
> > +Each built-in function generate a machine instruction that is part of
> > +the
> 
> s/generate a/generates the/

Fixed.

> > @@ -11378,6 +11379,20 @@ You can also use the @code{nocf_check}
> > attribute to identify  which functions and calls should be skipped
> > from instrumentation  (@pxref{Function Attributes}).
> >
> > +Currently x86 GNU/Linux target provides an implementation based on
> 
> s/x86/the x86/

Fixed.

> > +Intel Control-flow Enforcement Technology (CET), thus @option{-mcet}
> 
> s/@option/the @option/

Fixed.

> > +option is required to enable this feature.
> 
> I think you should put a cross-reference to the x86 options node here, and
> move all the following x86-specific discussion to that section.

Put cross-reference.

> > In order to get an
> > +application to be CET compatible the x86 implementation requires all
> > +object files have to be compiled with @option{-fcf-protection} option
> > +and all linked in libraries have to be CET compatible.
> 
> I'm having difficulty parsing this.  What does "CET compatible" mean?
> Is this an ABI compatibility issue, so that all objects linked into the executable
> have to be compiled with the (same?) @option{-fcf-protection} option if any
> of them do?  Or do you just lose checking on code in uninstrumented
> objects?

I re-wrote the paragraph and removed "compatibility topic".

> > +Instrumentation for x86 is controlled by target specific options
> 
> hyphenate target-specific here

Fixed.

> > +@option{-mcet}, @option{-mibt} and @option{-mshstk}. The compiler
> > +also provides a number of built-in functions for fine-grained control
> > +of CET-based implementation.  See @xref{x86 Built-in Functions}, for
> > +more information.
> > +
> >  @item -fstack-protector
> >  @opindex fstack-protector
> >  Emit extra code to check for buffer overflows, such as stack smashing
> > @@ -25755,15 +25770,19 @@ preferred alignment to @option{-
> mpreferred-stack-boundary=2}.
> >  @need 200
> >  @itemx -mclzero
> >  @opindex mclzero
> > +@need 200
> >  @itemx -mpku
> >  @opindex mpku
> > +@need 200
> > +@itemx -mcet
> > +@opindex mcet
> >  These switches enable the use of instructions in the MMX, SSE,  SSE2,
> > SSE3, SSSE3, SSE4.1, AVX, AVX2, AVX512F, AVX512PF, AVX512ER,
> AVX512CD,
> > SHA, AES, PCLMUL, FSGSBASE, RDRND, F16C, FMA, SSE4A, FMA4, XOP,
> LWP,
> > ABM,  AVX512VL, AVX512BW, AVX512DQ, AVX512IFMA AVX512VBMI, BMI,
> BMI2,
> > FXSR, -XSAVE, XSAVEOPT, LZCNT, RTM, MPX, MWAITX, PKU, 3DNow!@: or
> enhanced 3DNow!@:
> > -extended instruction sets.  Each has a corresponding @option{-mno-}
> > option -to disable use of these instructions.
> > +XSAVE, XSAVEOPT, LZCNT, RTM, MPX, MWAITX, PKU, IBT, SHSTK,
> > +3DNow!@: or enhanced 3DNow!@: extended instruction sets.  Each has a
> > +corresponding @option{-mno-} option to disable use of these
> instructions.
> >
> >  These extensions are also available as built-in functions: see
> >  @ref{x86 Built-in Functions}, for details of the functions enabled
> > and @@ -25783,6 +25802,11 @@ supported architecture, using the
> > appropriate flags.  In particular,  the file containing the CPU
> > detection code should be compiled without  these options.
> >
> > +The @option{-mcet} option turns on @option{-mibt} and
> > +@option{-mshstk}
> 
> s/turns on/turns on the/

Fixed.

> > +options.  @option{-mibt} option enables idirect branch tracking
> > +support
> 
> s/@option/The @option/
> s/idirect/indirect/

Fixed.

> > +and @option{-mshstk} option enables shadow stack support from
> 
> s/@option/the @option/

Fixed.

> > +Intel Control-flow Enforcement Technology (CET).
> > +
> >  @item -mdump-tune-features
> >  @opindex mdump-tune-features
> >  This option instructs GCC to dump the names of the x86 performance @@
> > -25856,6 +25880,24 @@ see @ref{Other Builtins} for details.
> >  This option enables use of the @code{movbe} instruction to implement
> > @code{__builtin_bswap32} and @code{__builtin_bswap64}.
> >
> > +@item -mibt
> > +@opindex mibt
> > +This option tells the compiler to use indirect branch tracking
> > +support (for indirect calls and jumps) from x86 Control-flow
> > +Enforcement Technology (CET).  The option has effect only if
> > +@option{-fcf-protection=full} or @option{-fcf-protection=branch}
> > +option is specified. The option @option{-mibt} is on by default when
> > +@code{-mcet}
> 
> s/@code{-mcet}/the @option{-mcet}/

Fixed.

Thanks,
Igor

> > +option is specified.
> > +
> > +@item -mshstk
> > +@opindex mshstk
> > +This option tells the compiler to use shadow stack support (return
> > +address tracking) from x86 Control-flow Enforcement Technology (CET).
> > +The option has effect only if @option{-fcf-protection=full} or
> > +@option{-fcf-protection=return} option is specified.  The option
> > +@option{-mshstk} is on by default when @option{-mcet} option is
> > +specified.
> > +
> >  @item -mcrc32
> >  @opindex mcrc32
> >  This option enables built-in functions @code{__builtin_ia32_crc32qi},
> 
> -Sandra
> 


[-- Attachment #2: 0005-Add-x86-CET-documentation.patch --]
[-- Type: application/octet-stream, Size: 7252 bytes --]

From dda22b06a3a5bde9b0dc57585d878db520769510 Mon Sep 17 00:00:00 2001
From: Igor Tsimbalist <igor.v.tsimbalist@intel.com>
Date: Tue, 4 Jul 2017 13:55:03 +0300
Subject: [PATCH 5/6] Add x86 CET documentation.

gcc/
	* doc/extend.texi: Add x86 specific to 'nocf_check' attribute.
	List CET intrinsics.
	* doc/invoke.texi: Add -mcet, -mibt, -mshstk options.  Add x86
	specific to -fcf-protection option.
---
 gcc/doc/extend.texi | 31 ++++++++++++++++++++++++++++++-
 gcc/doc/invoke.texi | 42 +++++++++++++++++++++++++++++++++++++++---
 2 files changed, 69 insertions(+), 4 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index e52a1ea..accba40 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -5655,6 +5655,14 @@ compiled with the @option{-fcf-protection=branch} option.  The
 compiler assumes that the function's address is a valid target for a
 control-flow transfer.
 
+@emph{x86 implementation:} when @option{-fcf-protection} option is
+specified the compiler inserts an @code{endbr} instruction at function's
+prologue if the function's type does not have the @code{nocf_check}
+attribute and addresses to which indirect control-flow transfer can
+happen.  The instruction triggers the HW check if a control-flow
+transfer to the address where @code{endbr} instruction was inserted
+is valid.
+
 The @code{nocf_check} attribute on a type of pointer to function is
 used to inform the compiler that a call through the pointer should
 not be instrumented when compiled with the
@@ -5662,7 +5670,9 @@ not be instrumented when compiled with the
 that the function's address from the pointer is a valid target for
 a control-flow transfer.  A direct function call through a function
 name is assumed to be a safe call thus direct calls are not
-instrumented by the compiler.
+instrumented by the compiler.  For @emph{x86 implementation} the
+compiler inserts a @code{notrack} prefix before an indirect call
+instruction.
 
 The @code{nocf_check} attribute is applied to an object's type.
 In case of assignment of a function address or a function pointer to
@@ -21217,6 +21227,25 @@ void __builtin_ia32_wrpkru (unsigned int)
 unsigned int __builtin_ia32_rdpkru ()
 @end smallexample
 
+The following built-in functions are available when @option{-mcet} is used.
+They are used to support Intel Control-flow Enforcment Technology (CET).
+Each built-in function generates the  machine instruction that is part of the
+function's name.
+@smallexample
+unsigned int __builtin_ia32_rdsspd (unsigned int)
+unsigned long long __builtin_ia32_rdsspq (unsigned long long)
+void __builtin_ia32_incsspd (unsigned int)
+void __builtin_ia32_incsspq (unsigned long long)
+void __builtin_ia32_saveprevssp(void);
+void __builtin_ia32_rstorssp(void *);
+void __builtin_ia32_wrssd(unsigned int, void *);
+void __builtin_ia32_wrssq(unsigned long long, void *);
+void __builtin_ia32_wrussd(unsigned int, void *);
+void __builtin_ia32_wrussq(unsigned long long, void *);
+void __builtin_ia32_setssbsy(void);
+void __builtin_ia32_clrssbsy(void *);
+@end smallexample
+
 @node x86 transactional memory intrinsics
 @subsection x86 Transactional Memory Intrinsics
 
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index c4faa23..189130b 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1203,6 +1203,7 @@ See RS/6000 and PowerPC Options.
 -msse4a  -m3dnow  -m3dnowa  -mpopcnt  -mabm  -mbmi  -mtbm  -mfma4  -mxop @gol
 -mlzcnt  -mbmi2  -mfxsr  -mxsave  -mxsaveopt  -mrtm  -mlwp  -mmpx  @gol
 -mmwaitx  -mclzero  -mpku  -mthreads @gol
+-mcet -mibt -mshstk @gol
 -mms-bitfields  -mno-align-stringops  -minline-all-stringops @gol
 -minline-stringops-dynamically  -mstringop-strategy=@var{alg} @gol
 -mmemcpy-strategy=@var{strategy}  -mmemset-strategy=@var{strategy} @gol
@@ -11374,6 +11375,14 @@ You can also use the @code{nocf_check} attribute to identify
 which functions and calls should be skipped from instrumentation
 (@pxref{Function Attributes}).
 
+Currently the x86 GNU/Linux target provides an implementation based
+on Intel Control-flow Enforcement Technology (CET).  Instrumentation
+for x86 is controlled by target-specific options @option{-mcet},
+@option{-mibt} and @option{-mshstk} (@pxref{x86 Options}).
+The compiler also provides a number of built-in functions for
+fine-grained control in a CET-based application.
+See @xref{x86 Built-in Functions}, for more information.
+
 @item -fstack-protector
 @opindex fstack-protector
 Emit extra code to check for buffer overflows, such as stack smashing
@@ -25751,15 +25760,19 @@ preferred alignment to @option{-mpreferred-stack-boundary=2}.
 @need 200
 @itemx -mclzero
 @opindex mclzero
+@need 200
 @itemx -mpku
 @opindex mpku
+@need 200
+@itemx -mcet
+@opindex mcet
 These switches enable the use of instructions in the MMX, SSE,
 SSE2, SSE3, SSSE3, SSE4.1, AVX, AVX2, AVX512F, AVX512PF, AVX512ER, AVX512CD,
 SHA, AES, PCLMUL, FSGSBASE, RDRND, F16C, FMA, SSE4A, FMA4, XOP, LWP, ABM,
 AVX512VL, AVX512BW, AVX512DQ, AVX512IFMA AVX512VBMI, BMI, BMI2, FXSR,
-XSAVE, XSAVEOPT, LZCNT, RTM, MPX, MWAITX, PKU, 3DNow!@: or enhanced 3DNow!@:
-extended instruction sets.  Each has a corresponding @option{-mno-} option
-to disable use of these instructions.
+XSAVE, XSAVEOPT, LZCNT, RTM, MPX, MWAITX, PKU, IBT, SHSTK,
+3DNow!@: or enhanced 3DNow!@: extended instruction sets.  Each has a
+corresponding @option{-mno-} option to disable use of these instructions.
 
 These extensions are also available as built-in functions: see
 @ref{x86 Built-in Functions}, for details of the functions enabled and
@@ -25779,6 +25792,11 @@ supported architecture, using the appropriate flags.  In particular,
 the file containing the CPU detection code should be compiled without
 these options.
 
+The @option{-mcet} option turns on the @option{-mibt} and @option{-mshstk}
+options.  The @option{-mibt} option enables indirect branch tracking support
+and the @option{-mshstk} option enables shadow stack support from
+Intel Control-flow Enforcement Technology (CET).
+
 @item -mdump-tune-features
 @opindex mdump-tune-features
 This option instructs GCC to dump the names of the x86 performance 
@@ -25852,6 +25870,24 @@ see @ref{Other Builtins} for details.
 This option enables use of the @code{movbe} instruction to implement
 @code{__builtin_bswap32} and @code{__builtin_bswap64}.
 
+@item -mibt
+@opindex mibt
+This option tells the compiler to use indirect branch tracking support
+(for indirect calls and jumps) from x86 Control-flow Enforcement
+Technology (CET).  The option has effect only if the
+@option{-fcf-protection=full} or @option{-fcf-protection=branch} option
+is specified. The option @option{-mibt} is on by default when the
+@code{-mcet} option is specified.
+
+@item -mshstk
+@opindex mshstk
+This option tells the compiler to use shadow stack support (return
+address tracking) from x86 Control-flow Enforcement Technology (CET).
+The option has effect only if the @option{-fcf-protection=full} or
+@option{-fcf-protection=return} option is specified.  The option
+@option{-mshstk} is on by default when the @option{-mcet} option is
+specified.
+
 @item -mcrc32
 @opindex mcrc32
 This option enables built-in functions @code{__builtin_ia32_crc32qi},
-- 
1.8.3.1