Enhance the documentation for SamplePGO.

Author: Snehasish Kumar

llvm/docs/HowToUpdateDebugInfo.rst

@@ -90,14 +90,14 @@ has a location with an accurate scope attached, and b) to prevent misleading
 single-stepping (or breakpoint) behavior. Often, merged instructions are memory
 accesses which can trap: having an accurate scope attached greatly assists in
 crash triage by identifying the (possibly inlined) function where the bad
-memory access occurred. 
-
-For SamplePGO, it is often beneficial to retain an arbitrary but deterministic
-location instead of discarding line and column information as part of merging.
-In particular, loss of location information for calls inhibit optimizations 
-such as indirect call promotion. This behavior can be optionally enabled until
-support for accurately representing merged instructions in the line table is
-implemented. 
+memory access occurred.
+
+To maintain distinct source locations for SamplePGO, it is often beneficial to
+retain an arbitrary but deterministic location instead of discarding line and
+column information as part of merging. In particular, loss of location
+information for calls inhibit optimizations such as indirect call promotion.
+This behavior can be optionally enabled until support for accurately
+representing merged instructions in the line table is implemented.
 
 Examples of transformations that should follow this rule include:
 

llvm/docs/SourceLevelDebugging.rst

@@ -77,7 +77,12 @@ SamplePGO (also known as `AutoFDO <https://gcc.gnu.org/wiki/AutoFDO>`_)
 is a variant of profile guided optimizations which uses hardware sampling based
 profilers to collect branch frequency data with low overhead in production
 environments. It relies on debug information to associate profile information
-to LLVM IR which is then used to guide optimization heuristics.
+to LLVM IR which is then used to guide optimization heuristics. Maintaining
+deterministic and distinct source locations is necessary to maximize the
+accuracy of mapping hardware sample counts to LLVM IR. For example, DWARF
+`discriminators <https://wiki.dwarfstd.org/Path_Discriminators.md>`_ allow
+SamplePGO to distinguish between multiple paths of execution which map to the
+same source line.
 
 It would also be reasonable to use debug information to feed profiling tools
 for analysis of generated code, or, tools for reconstructing the original