Add documentation for force_align_arg_pointer function attribute

[anatol.pomozov]

include/clang/Basic/AttrDocs.td

2809

Feel free to reword the documentation (English is not my native language).

Let me know if something is not clear about force_align_arg_pointer functionality, I'll provide more info.

[erichkeane]

Aaron should have final say, but I've included my 2 cents.

include/clang/Basic/AttrDocs.td

2816

that the x86_64 ABI..

"call site" instead of "caller side".

2817

Instead of "Taking it into account", perhaps, "Because of this,"

2818

align the stack correctly

[erichkeane]

Looks good to me, but I want to give @aaron.ballman a chance to take a look before this gets accepted.

[aaron.ballman]

include/clang/Basic/AttrDocs.td

2812

work with stack -> work with the stack

2813

realigns stack -> realigns the stack

2817

at x86_64 except rare cases when caller -> on x86_64, except in rare cases where the caller

[aaron.ballman]

LGTM! Thank you for working on this!

[erichkeane]

In D37312#858108, @aaron.ballman wrote:

LGTM! Thank you for working on this!

Did you want to land this, or should I?

[anatol.pomozov]

Thank you folks for your work.

By the way when these changes are going to be released? clang 6.0?

[erichkeane]

In D37312#858217, @anatol.pomozov wrote:

Thank you folks for your work.

By the way when these changes are going to be released? clang 6.0?

Most likely. Its too late to get into 5.0, and 6.0 hasn't been branched yet.

include/clang/Basic/Attr.td

 
 def AnyX86NoCallerSavedRegisters : InheritableAttr,
                                    TargetSpecificAttr<TargetAnyX86> {
   let Spellings = [GCC<"no_caller_saved_registers">];
   let Documentation = [AnyX86NoCallerSavedRegistersDocs];
 }
 
 def X86ForceAlignArgPointer : InheritableAttr, TargetSpecificAttr<TargetAnyX86> {
-  let Spellings = [GNU<"force_align_arg_pointer">];
+  let Spellings = [GCC<"force_align_arg_pointer">];
   // Technically, this appertains to a FunctionDecl, but the target-specific
   // code silently allows anything function-like (such as typedefs or function
   // pointers), but does not apply the attribute to them.
-  let Documentation = [Undocumented];
+  let Documentation = [X86ForceAlignArgPointerDocs];
 }
 
 def NoSanitize : InheritableAttr {
   let Spellings = [GNU<"no_sanitize">, CXX11<"clang", "no_sanitize">];
   let Args = [VariadicStringArgument<"Sanitizers">];
   let Subjects = SubjectList<[Function, ObjCMethod, GlobalVar], ErrorDiag,
     "ExpectedFunctionMethodOrGlobalVar">;
   let Documentation = [NoSanitizeDocs];

include/clang/Basic/AttrDocs.td

For example:
 
   In this case parameters 'arg1' and 'arg2' will be passed in registers.
   In this case, on 32-bit x86 targets, the function 'f' will use ECX and EDX as
   register parameters. However, it will not assume any scratch registers and
   should save and restore any modified registers except for ECX and EDX.
   }];
 }
 
+def X86ForceAlignArgPointerDocs : Documentation {
+  let Category = DocCatFunction;
+  let Content = [{
+Use this attribute to force stack alignment.
+
+Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
+(like 'movaps') that work with the stack require operands to be 16-byte aligned.
+This attribute realigns the stack in the function prologue to make sure the
+stack can be used with SSE instructions.
+
+Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
+Because of this, 'force_align_arg_pointer' is not needed on x86_64, except in
+rare cases where the caller does not align the stack properly (e.g. flow
+jumps from i386 arch code).
+
+  .. code-block:: c
+
+    __attribute__ ((force_align_arg_pointer))
+    void f () {
+      ...
+    }
+
+  }];
+}
+
 def SwiftCallDocs : Documentation {
   let Category = DocCatVariable;
   let Content = [{
 The ``swiftcall`` attribute indicates that a function should be called
 using the Swift calling convention for a function or function pointer.
 
 The lowering for the Swift calling convention, as described by the Swift
 ABI documentation, occurs in multiple phases.  The first, "high-level"