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

(On Diff #102595)

Does it attach to the call instruction?

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

5220 ↗

(On Diff #102595)

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 ↗

(On Diff #102595)

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

[tejohnson]

docs/LangRef.rst

5210 ↗

(On Diff #102595)

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 ↗

(On Diff #102595)

will update.

5231 ↗

(On Diff #102595)

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

[tejohnson]

• Address comments

[davidxl]

docs/LangRef.rst

5210 ↗

(On Diff #102595)

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 ↗

(On Diff #102602)

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 ↗

(On Diff #102602)

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 ↗

(On Diff #102602)

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 ↗

(On Diff #102602)

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

llvm/trunk/docs/BranchWeightMetadata.rst

 .. code-block:: none
 
   !0 = metadata !{
     metadata !"branch_weights",
     i32 <LABEL_BRANCH_WEIGHT>
     [ , i32 <LABEL_BRANCH_WEIGHT> ... ]
   }
 
+``CallInst``
+^^^^^^^^^^^^^^^^^^
+
+Calls may have branch weight metadata, containing the execution count of
+the call. It is currently used in SamplePGO mode only, to augment the
+block and entry counts which may not be accurate with sampling.
+
+.. 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

llvm/trunk/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.
+
+Note that the value counts do not need to add up to the total count
+listed in the third operand (in practice only the top hottest values
+are tracked and reported).
+
+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