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

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

[Tsimbalist, Igor V]

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

Part#5. Add x86 CET documentation.

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

From b2361a3954cfd297896aa1f6926cdecc40ddce9e 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/9] Part#5. Add x86 CET documentation.

gcc/

	* doc/extend.texi: Add x86 specific to 'notrack' attribute.
	List CET intrinsics.
	* doc/invoke.texi: Add -mcet, -mibt, -mshstk.  Add x86 specific
	to -finstrument-control-flow.
---
 gcc/doc/extend.texi | 34 ++++++++++++++++++++++++++---
 gcc/doc/invoke.texi | 63 ++++++++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 84 insertions(+), 13 deletions(-)

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 80de8a7..96f4098 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -5641,14 +5641,24 @@ compiled with the @option{-finstrument-control-flow} option.  The
 compiler assumes that the function's address is a valid target for a
 control-flow transfer.
 
+@emph{x86 implementation:} For function bodies, which do not have
+the @code{notrack} attribute, the compiler insert an ENDBR
+instruction at function entry.  The instruction triggers
+the HW to check if a control-flow transfer to the function is valid.
+When compiled with the @option{-finstrument-control-flow} option
+the ENDBR instruction also inserted at addresses to which indirect
+control-flow trasfer can happen.
+
 The @code{notrack} 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
 @option{-finstrument-control-flow} option.  The compiler assumes
 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 as a save call thus direct calls will not be
-instrumented by the compiler.
+a control-flow transfer. For @emph{x86 implementation} the compiler
+insert a NOTRACK prefix before a indeirect call instruction.  A
+direct function call through a function name is assumed as a save
+call thus direct calls will not be instrumented by the compiler
+and no NOTRACK prefix is inserted before direct calls.
 
 The @code{notrack} attribute is applied to an object's type.  A
 The @code{notrack} attribute is transfered to a call instruction at
@@ -21079,6 +21089,24 @@ 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).
+All of them generate the machine instruction that is part of the 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 ff2ce92..a84c7b6 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1202,6 +1202,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
@@ -11289,7 +11290,7 @@ Enabled by default.
 @opindex finstrument-control-flow
 @opindex fno-instrument-control-flow
 Enable code instrumentation of control-flow transfers to increase
-a program security by checking a target address of control-flow
+a program security by checking target addresses of control-flow
 transfer instructions (i.e. routine call, routine return, jump)
 are valid targets.  This prevents diverting the control flow
 instructions from its original target address to a new undesigned
@@ -11297,14 +11298,30 @@ target.  This is intended to protect against such theats as
 Return-oriented Programming (ROP), and similarly call/jmp-oriented
 programming (COP/JOP).
 
-Each compiler, which will support the control-flow instrumentation,
-is supposed to have its own target specific implementation of the
-control-flow instrumentation and in case of absence of such
-implementation the @option{-finstrument-control-flow} will
-cause an error message.
+Each compiler, which supports the @option{-finstrument-control-flow}
+option, is supposed to have its own target specific implementation
+of the control-flow instrumentation and in case of absence of such
+implementation the @option{-finstrument-control-flow} results in
+an error message.
 
 A user has a control through the @code{notrack} attribute to identify
-which functions and calls should be skipped from instrumentation.
+which function addresses and calls should be skipped from
+instrumentation.
+
+Currently an implementation is available based on Intel Control-flow
+Enforcment Technology (CET), thus x86 GNU/Linux target and
+@option{-mcet} are required to enable this feature.  In order
+to get an application to be CET enabled the implementation requires
+all object files have to be compiled with
+@option{-finstrument-control-flow} and all linked in libraries have
+to be CET enabled.
+
+Instrumentation for x86 is controlled by target specific @option{-mcet},
+@option{-mibt} and @option{-mshstk} options and @code{notrack}
+attribute for function (@pxref{x86 Function Attributes}). The compiler
+also provides a number of built-in functions for fine-grained controll
+of CET-based implementation.  See @xref{x86 Built-in Functions},
+for more information.
 
 @item -fstack-protector
 @opindex fstack-protector
@@ -25648,15 +25665,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
@@ -25676,6 +25697,10 @@ 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} options.  Each of these options enables coresponding
+support from x86 Control-flow Enforcment Technology (CET) implementation.
+
 @item -mdump-tune-features
 @opindex mdump-tune-features
 This option instructs GCC to dump the names of the x86 performance 
@@ -25749,6 +25774,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 instructs the compiler to use only indirect branch tracking
+(indirect calls and jumps) support from x86 Control-flow Enforcment
+Technology (CET) implementation, see also @code{-mcet} option.  The
+option has effect only if @code{-finstrument-control-flow} option is
+specified. The option @code{-mibt} is on by default when @code{-mcet}
+option is specified.
+
+@item -mshstk
+@opindex mshstk
+This option instructs compiler to use only shadow stack (return address
+tracking) support from x86 Control-flow Enforcment Technology (CET)
+implementation, see also @code{-mcet} option.  The option has effect
+only if @code{-finstrument-control-flow} option is specified.  The
+option @code{-mshstk} is on by default when @code{-mcet} option is
+specified.
+
 @item -mcrc32
 @opindex mcrc32
 This option enables built-in functions @code{__builtin_ia32_crc32qi},
-- 
1.8.3.1

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

[Tsimbalist, Igor V]

Uros, could you please review this patch as it's a part of x86 specific changes you have reviewed already.

Thanks,
Igor


> -----Original Message-----
> From: Tsimbalist, Igor V
> Sent: Tuesday, August 1, 2017 10:57 AM
> To: 'gcc-patches@gcc.gnu.org' <gcc-patches@gcc.gnu.org>
> Cc: Tsimbalist, Igor V <igor.v.tsimbalist@intel.com>
> Subject: 0005-Part-5.-Add-x86-CET-documentation
> 
> Part#5. Add x86 CET documentation.

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

[Uros Bizjak]

On Wed, Sep 20, 2017 at 11:20 AM, Tsimbalist, Igor V
<igor.v.tsimbalist@intel.com> wrote:
> Uros, could you please review this patch as it's a part of x86 specific changes you have reviewed already.

Please proofread and spell-check the text. There are grammatical errors, e.g.:

+When compiled with the @option{-finstrument-control-flow} option
+the ENDBR instruction also inserted at addresses to which indirect

and typos, such as:

+control-flow trasfer can happen.

English is not my tongue, but these two popped out immediately.

Other than that,

-a program security by checking a target address of control-flow
+a program security by checking target addresses of control-flow

Spurious change.

+@option{mshstk} options.  Each of these options enables coresponding

Missing dash, and a typo.

+This option instructs the compiler to use only indirect branch tracking
+(indirect calls and jumps) support from x86 Control-flow Enforcment

Typo.

+Technology (CET) implementation, see also @code{-mcet} option.  The
+option has effect only if @code{-finstrument-control-flow} option is
+specified. The option @code{-mibt} is on by default when @code{-mcet}
+option is specified.

Please use @option{} for options.

+This option instructs compiler to use only shadow stack (return address
+tracking) support from x86 Control-flow Enforcment Technology (CET)
+implementation, see also @code{-mcet} option.  The option has effect
+only if @code{-finstrument-control-flow} option is specified.  The
+option @code{-mshstk} is on by default when @code{-mcet} option is
+specified.

Also in the above text.

Uros.

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

[Sandra Loosemore]

On 09/20/2017 08:13 AM, Uros Bizjak wrote:
> On Wed, Sep 20, 2017 at 11:20 AM, Tsimbalist, Igor V
> <igor.v.tsimbalist@intel.com> wrote:
>> Uros, could you please review this patch as it's a part of x86 specific changes you have reviewed already.
>
> Please proofread and spell-check the text. There are grammatical errors, e.g.:
> [snip]

If/when there is a newer version of this patch, cc it to me and I will 
also make a pass through it.

-Sandra

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

[Tsimbalist, Igor V]

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

Here is a new version of the patch.

Igor


> -----Original Message-----
> From: Sandra Loosemore [mailto:sandra@codesourcery.com]
> Sent: Monday, September 25, 2017 5:43 AM
> To: Uros Bizjak <ubizjak@gmail.com>; Tsimbalist, Igor V
> <igor.v.tsimbalist@intel.com>
> Cc: gcc-patches@gcc.gnu.org
> Subject: Re: 0005-Part-5.-Add-x86-CET-documentation
> 
> On 09/20/2017 08:13 AM, Uros Bizjak wrote:
> > On Wed, Sep 20, 2017 at 11:20 AM, Tsimbalist, Igor V
> > <igor.v.tsimbalist@intel.com> wrote:
> >> Uros, could you please review this patch as it's a part of x86 specific
> changes you have reviewed already.
> >
> > Please proofread and spell-check the text. There are grammatical errors,
> e.g.:
> > [snip]
> 
> If/when there is a newer version of this patch, cc it to me and I will also make
> a pass through it.
> 
> -Sandra


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

From 9c54433e9a03fce0d85d64fb75d7f9d9538f966a 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] Part#5. 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 | 29 ++++++++++++++++++++++++++++-
 gcc/doc/invoke.texi | 48 +++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 73 insertions(+), 4 deletions(-)

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.
+
 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 +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.
 
 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 +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
+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 a0a65bd..e65e127 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
@@ -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
+Intel Control-flow Enforcement Technology (CET), thus @option{-mcet}
+option is required to enable this feature.  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.
+
+Instrumentation for x86 is controlled by target specific options
+@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}
+options.  @option{-mibt} option enables idirect branch tracking support
+and @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 
@@ -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}
+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},
-- 
1.8.3.1

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

[Sandra Loosemore]

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.

> @@ -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/

> @@ -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/

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

s/@option/the @option/

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

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

> +Instrumentation for x86 is controlled by target specific options

hyphenate target-specific here

> +@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/

> +options.  @option{-mibt} option enables idirect branch tracking support

s/@option/The @option/
s/idirect/indirect/

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

s/@option/the @option/

> +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}/

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

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

[Florian Weimer]

On 09/27/2017 05:40 AM, Sandra Loosemore wrote:
>>
>> +@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.

This is part of the ABI GCC implements, so it has to be documented 
somewhere, and not just as part of the GCC source code.

CET is not properly described in the ABI supplement and I don't think 
this will change, so detailed documentation in the GCC manual is very 
much desirable.

That being said, the implementation notes above need some clarification. 
  It's not clear to me what the conditions are under which the ENDBR 
instruction is emitted (and we probably should use @code{endbr} in the 
manual), what it is trying to achieve, and how the x86 calling 
convention changes.  I assume it is somehow related to what we call 
internally “the suffix problem”: without control flow integrity, an 
attacker might skip over precondition/hardening checks, directly to the 
critical changes we want to protect, executing only the suffix of a 
function (hence the name).

Thanks,
Florian

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

[Tsimbalist, Igor V]

> -----Original Message-----
> From: Florian Weimer [mailto:fweimer@redhat.com]
> Sent: Wednesday, September 27, 2017 10:52 AM
> To: Sandra Loosemore <sandra@codesourcery.com>; 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/27/2017 05:40 AM, Sandra Loosemore wrote:
> >>
> >> +@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.
> 
> This is part of the ABI GCC implements, so it has to be documented
> somewhere, and not just as part of the GCC source code.

A question for both Sandra and Florian - What is your suggestion where the text should go?

> CET is not properly described in the ABI supplement and I don't think this will
> change, so detailed documentation in the GCC manual is very much
> desirable.
> 
> That being said, the implementation notes above need some clarification.
>   It's not clear to me what the conditions are under which the ENDBR
> instruction is emitted (and we probably should use @code{endbr} in the
> manual), what it is trying to achieve, and how the x86 calling convention
> changes.  I assume it is somehow related to what we call internally “the suffix

We are diving into implementation details but it's simple enough.

- endbr is generated for every function, which does not have nocf_check attribute.
   Optimization can be done later to exclude functions, whose address was not taken.
- there is no change in calling convention

Thanks,
Igor

> problem”: without control flow integrity, an attacker might skip over
> precondition/hardening checks, directly to the critical changes we want to
> protect, executing only the suffix of a function (hence the name).
> 
> Thanks,
> Florian

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

[Tsimbalist, Igor V]

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

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

[Sandra Loosemore]

On 09/27/2017 02:52 AM, Florian Weimer wrote:
> On 09/27/2017 05:40 AM, Sandra Loosemore wrote:
>>>
>>> +@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.
>
> This is part of the ABI GCC implements, so it has to be documented
> somewhere, and not just as part of the GCC source code.
>
> CET is not properly described in the ABI supplement and I don't think
> this will change, so detailed documentation in the GCC manual is very
> much desirable.
>

Not if you're a documentation maintainer.  :-(  Generally speaking, 
user-facing manuals like the GCC manual should document user-visible GCC 
features, not internal implementation details.  Especially the 
target-independent parts of the manual are not the right place to 
discuss target-specific code generation patterns or conventions that 
should be in the ABI supplement or some other non-GCC documentation.

I don't have so much objection to expanding the discussion of the 
target-specific -mcet option in the x86 options section, as long as the 
documentation is there because it helps people *use* the feature and not 
to explain things that are only interesting to compiler implementors.

-Sandra

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

[Joseph Myers]

On Wed, 27 Sep 2017, Florian Weimer wrote:

> This is part of the ABI GCC implements, so it has to be documented somewhere,
> and not just as part of the GCC source code.
> 
> CET is not properly described in the ABI supplement and I don't think this
> will change, so detailed documentation in the GCC manual is very much
> desirable.

Isn't this a matter to take up further in the thread HJ started on the ABI 
mailing lists, or a new such thread (possibly e.g. sending pull requests 
that build further on his wording, or propose alternative wording, to 
clarify them things left unclear there, with a goal of getting it clearly 
defined in the master sources for x86_64 and x86)?  Clearly the best 
result would be proper documentation in the ABI and the GCC manual 
cross-referencing the relevant ABI documents.

-- 
Joseph S. Myers
joseph@codesourcery.com

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

[Jeff Law]

On 09/27/2017 11:01 AM, Joseph Myers wrote:
> On Wed, 27 Sep 2017, Florian Weimer wrote:
> 
>> This is part of the ABI GCC implements, so it has to be documented somewhere,
>> and not just as part of the GCC source code.
>>
>> CET is not properly described in the ABI supplement and I don't think this
>> will change, so detailed documentation in the GCC manual is very much
>> desirable.
> 
> Isn't this a matter to take up further in the thread HJ started on the ABI 
> mailing lists, or a new such thread (possibly e.g. sending pull requests 
> that build further on his wording, or propose alternative wording, to 
> clarify them things left unclear there, with a goal of getting it clearly 
> defined in the master sources for x86_64 and x86)?  Clearly the best 
> result would be proper documentation in the ABI and the GCC manual 
> cross-referencing the relevant ABI documents.


The documentation should be AFAICT independent of the compiler in use --
ie, gcc, llvm and icc all should agree on where/when these new
instructions should be inserted.  Which argues that the documentation
belongs in the ABI docs, not the GCC docs.  *users* aren't really going
to care about these kinds of details.

So I think the summary is that I agree with Joseph on this.  Let's push
it into the ABI docs.  HJ can and should play a central role in making
that happen.

jeff

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

[Jeff Law]

On 09/27/2017 09:17 AM, Tsimbalist, Igor V wrote:

>>
> 
> 0005-Add-x86-CET-documentation.patch
> 
> 
> 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.
Once Sandra has OK'd the doc patches, they should be considered OK for
the trunk.

jeff

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

[Sandra Loosemore]

On 09/27/2017 09:17 AM, Tsimbalist, Igor V wrote:
> Updated version #3.
>
> 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.
> +

I think the consensus among Joseph, Jeff, and I is that this doesn't 
belong in the GCC manual at all, but in the ABI documentation.  So 
please delete the implementation note.

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

Ditto with this implementation note.

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

This part is OK.

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

I think these builtins emit instructions in the CET extension explicitly 
and don't affect the GCC's code generation for the -fcf-protection 
option.  So please move this to the discussion of -mcet in the x86 
options section instead....

> @@ -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).
> +

...here.

The patch is OK with those changes.

-Sandra