Add docs for function attributes hot/cold

[OfekShilon]

Summary

Following this, add docs for the hot/cold function attributes

[aaron.ballman]

Thank you for adding the docs! I'm not well-versed enough in hot/cold behavior and PGO to comment on the documentation accuracy, so I'm hopeful someone can sign off on that bit.

clang/include/clang/Basic/Attr.td

1077

I think the change on this line was unintentional.

1523

I think the change on this line was unintentional.

clang/include/clang/Basic/AttrDocs.td

5248

5255–5256

[davidxl]

LGTM from the content point of view. Please also address aaron's comment.

[OfekShilon]

Addressed Aaron's comments (thanks!). Hope I got the update-diff procedure right.
I don't have commit permissions, would appreciate if someone could push this.

[aaron.ballman]

In D130933#3710682, @OfekShilon wrote:

Addressed Aaron's comments (thanks!). Hope I got the update-diff procedure right.

It looks like something might have gone wrong because the diff looks like it's now a diff against something other than the main branch (it looks like it's adding the SimpleHandler lines in Attr.td, but those lines already exist in main).

I don't have commit permissions, would appreciate if someone could push this.

Once we get the patch fixed up, I'm happy to land on your behalf. What name and email address would you like me to use for patch attribution?

[OfekShilon]

This comment was removed by OfekShilon.

[aaron.ballman]

I'm not a git expert by any means, but you might be able to address the patch issues with git diff -U999 main > foo.patch from the root llvm-project directory so that you're getting a diff with 999 lines of context and the differences are against the main branch.

[OfekShilon]

My apologies for the mess, hopefully the diff I just uploaded includes all the right fixes.

[aaron.ballman]

In D130933#3713277, @OfekShilon wrote:

My apologies for the mess, hopefully the diff I just uploaded includes all the right fixes.

No worries! If I had a nickel for every time I've been confused by git... I'd have a lot of nickels.

This version LGTM! I can land it for you, but what name and email address would you like me to use for patch attribution?

[OfekShilon]

@aaron.ballman 'Ofek Shilon', [e-mail] is fine.
Thanks!

[aaron.ballman]

In D130933#3713437, @OfekShilon wrote:

@aaron.ballman 'Ofek Shilon', [e-mail] is fine.
Thanks!

Thank you! I've landed on your behalf.

clang/include/clang/Basic/Attr.td

   let Spellings = [GNU<"cmse_nonsecure_call">];
   let LangOpts = [Cmse];
   let Documentation = [ArmCmseNSCallDocs];
 }
 
 def Cold : InheritableAttr {
   let Spellings = [GCC<"cold">];
   let Subjects = SubjectList<[Function]>;
-  let Documentation = [Undocumented];
+  let Documentation = [ColdFunctionEntryDocs];
   let SimpleHandler = 1;
 }
 
 def Common : InheritableAttr {
   let Spellings = [GCC<"common">];
   let Subjects = SubjectList<[Var]>;
   let Documentation = [Undocumented];
 }
 

   let Spellings = [GCC<"gnu_inline">];
   let Subjects = SubjectList<[Function]>;
   let Documentation = [GnuInlineDocs];
 }
 
 def Hot : InheritableAttr {
   let Spellings = [GCC<"hot">];
   let Subjects = SubjectList<[Function]>;
-  let Documentation = [Undocumented];
+  let Documentation = [HotFunctionEntryDocs];
   let SimpleHandler = 1;
 }
 def : MutualExclusions<[Hot, Cold]>;
 
 def IBAction : InheritableAttr {
   let Spellings = [Clang<"ibaction">];
   let Subjects = SubjectList<[ObjCInstanceMethod]>;
   // An AST node is created for this attribute, but is not used by other parts
   // of the compiler. However, this node needs to exist in the AST because

clang/include/clang/Basic/AttrDocs.td

 takes precedence over the command line option ``-fpatchable-function-entry=N,M``.
 ``M`` defaults to 0 if omitted.
 
 This attribute is only supported on
 aarch64/aarch64-be/riscv32/riscv64/i386/x86-64 targets.
 }];
 }
 
+def HotFunctionEntryDocs : Documentation {
+  let Category = DocCatFunction;
+  let Content = [{
+``__attribute__((hot))`` marks a function as hot, as a manual alternative to PGO hotness data.
+If PGO data is available, the annotation ``__attribute__((hot))`` overrides the profile count based hotness (unlike ``__attribute__((cold))``).
+}];
+}
+
+def ColdFunctionEntryDocs : Documentation {
+  let Category = DocCatFunction;
+  let Content = [{
+``__attribute__((cold))`` marks a function as cold, as a manual alternative to PGO hotness data.
+If PGO data is available, the profile count based hotness overrides the ``__attribute__((cold))`` annotation (unlike ``__attribute__((hot))``).
+}];
+}
 def TransparentUnionDocs : Documentation {
   let Category = DocCatDecl;
   let Content = [{
 This attribute can be applied to a union to change the behavior of calls to
 functions that have an argument with a transparent union type. The compiler
 behavior is changed in the following manner:
 
 - A value whose type is any member of the transparent union can be passed as an