[Doc] Document prof metadata in LangRef

[tejohnson]

Summary

Points to existing documentation for branch_weights and
function_entry_count, and adds an example for VP value profile metadata.

[davidxl]

docs/LangRef.rst

5210

Does it attach to the call instruction?

It can be attached to SELECT instruction which should be mentioned.

5220

to record the number of times the function is called. Used with BFI information, it is also used to derive basic block profile count.

5231

memcpy -- mempy like calls (including memset, etc)

[tejohnson]

docs/LangRef.rst

5210

It attached to direct call instructions in SamplePGO mode. And according to the linked older documentation I found (http://llvm.org/docs/BranchWeightMetadata.html#indirectbrinst) it attaches to indirect calls, although I wonder if that is stale since we now have VP metadata for indirect calls?

Will add "select" to the list of instruction types here.

5220

will update.

5231

will change to "memory intrinsics such as memcpy, memmove and memset"

[tejohnson]

• Address comments

[davidxl]

docs/LangRef.rst

5210

Need to document the direct call usage. indirectbr is not for indirect call, but computed gotos. So may be expand branch into conditional branch or indirect branches? Unconditional direct branch does not need this meta data.

[tejohnson]

• Document branch_weight metadata on direct calls with SamplePGO

[reames]

Thank you for acting on this quickly. Comments inline, but nothing here should prevent this landing. We can iterate on the documentation once there's *something* in place.

docs/BranchWeightMetadata.rst

70

Please describe the semantics of the metadata separately from the usage. I have an alternate profiling source and need to know how the metadata is used, not just where you assume it comes from.

docs/LangRef.rst

5237

It would have been more clear to represent the types as strings in the metadata. Document what's there for the moment, but might be worth changing this.

Clarification: Is it legal for the sum of the pairs to not add up to the total? (It should be.)

Clarification: Is it *required* that the counts be exact executio counts? Or are they solely relative weightings? (Should be the later.)

[tejohnson]

In D34218#780743, @reames wrote:

Thank you for acting on this quickly. Comments inline, but nothing here should prevent this landing. We can iterate on the documentation once there's *something* in place.

Sure. Can you or David LGTM the patch if this looks good for now?

docs/BranchWeightMetadata.rst

70

Right now it is only used in SamplePGO mode (used to detect hot calls since profile counts on the function entry etc may not be accurate in sampling mode). I've updated the wording to indicate this.

docs/LangRef.rst

5237

It would have been more clear to represent the types as strings in the metadata. Document what's there for the moment, but might be worth changing this.

David may be able to give some context on why it is an int and not a string. But as a user I agree a string would be clearer.

Clarification: Is it legal for the sum of the pairs to not add up to the total? (It should be.)

Yes. In fact, we only profile the top N (N is configurable, default is 8), so the value counts often don't add up to the total. I have clarified this.

Clarification: Is it *required* that the counts be exact execution counts? Or are they solely relative weightings (Should be the later.)

Relative weightings should work fine. In fact, the total may not be equal to the BB execution count in a multi-threaded profile collection environment since counter updates are non-atomic.

[tejohnson]

• Address comments

[davidxl]

lgtm

docs/BranchWeightMetadata.rst

 .. code-block:: none
 
   !0 = metadata !{
     metadata !"branch_weights",
     i32 <LABEL_BRANCH_WEIGHT>
     [ , i32 <LABEL_BRANCH_WEIGHT> ... ]
   }
 
+``CallInst``
+^^^^^^^^^^^^^^^^^^
+
+In SamplePGO mode, direct calls only have branch weight metadata,
+containing the execution count of the call.
+
+.. code-block:: none
+
+  !0 = metadata !{
+    metadata !"branch_weights",
+    i32 <CALL_BRANCH_WEIGHT>
+  }
+
 Other
 ^^^^^
 
 Other terminator instructions are not allowed to contain Branch Weight Metadata.
 
 .. _\__builtin_expect:
 
 Built-in ``expect`` Instructions

docs/LangRef.rst

 .. code-block:: llvm
 
     $a = comdat any
     @a = global i32 1, comdat $a
     @b = internal global i32 2, comdat $a, section "abc", !associated !0
     !0 = !{i32* @a}
 
 
+'``prof``' Metadata
+^^^^^^^^^^^^^^^^^^^
+
+The ``prof`` metadata is used to record profile data in the IR.
+The first operand of the metadata node indicates the profile metadata
+type. There are currently 3 types:
+:ref:`branch_weights<prof_node_branch_weights>`,
+:ref:`function_entry_count<prof_node_function_entry_count>`, and
+:ref:`VP<prof_node_VP>`.
+
+.. _prof_node_branch_weights:
+
+branch_weights
+""""""""""""""
+
+Branch weight metadata attached to a branch, select, switch or call instruction
+represents the likeliness of the associated branch being taken.
+For more information, see :doc:`BranchWeightMetadata`.
+
+.. _prof_node_function_entry_count:
+
+function_entry_count
+""""""""""""""""""""
+
+Function entry count metadata can be attached to function definitions
+to record the number of times the function is called. Used with BFI
+information, it is also used to derive the basic block profile count.
+For more information, see :doc:`BranchWeightMetadata`.
+
+.. _prof_node_VP:
+
+VP
+""
+
+VP (value profile) metadata can be attached to instructions that have
+value profile information. Currently this is indirect calls (where it
+records the hottest callees) and calls to memory intrinsics such as memcpy,
+memmove, and memset (where it records the hottest byte lengths).
+
+Each VP metadata node contains "VP" string, then a uint32_t value for the value
+profiling kind, a uint64_t value for the total number of times the instruction
+is executed, followed by uint64_t value and execution count pairs.
+The value profiling kind is 0 for indirect call targets and 1 for memory
+operations. For indirect call targets, each profile value is a hash
+of the callee function name, and for memory operations each value is the
+byte length.
+
+Indirect call example:
+
+.. code-block:: llvm
+
+    call void %f(), !prof !1
+    !1 = !{!"VP", i32 0, i64 1600, i64 7651369219802541373, i64 1030, i64 -4377547752858689819, i64 410}
+
+Note that the VP type is 0 (the second operand), which indicates this is
+an indirect call value profile data. The third operand indicates that the
+indirect call executed 1600 times. The 4th and 6th operands give the
+hashes of the 2 hottest target functions' names (this is the same hash used
+to represent function names in the profile database), and the 5th and 7th
+operands give the execution count that each of the respective prior target
+functions was called.
+
 Module Flags Metadata
 =====================
 
 Information about the module as a whole is difficult to convey to LLVM's
 subsystems. The LLVM IR isn't sufficient to transmit this information.
 The ``llvm.module.flags`` named metadata exists in order to facilitate
 this. These flags are in the form of key / value pairs --- much like a
 dictionary --- making it easy for any subsystem who cares about a flag to