Update docs to mention SamplePGO debug info usage.

Author: Snehasish Kumar

llvm/docs/HowToUpdateDebugInfo.rst

@@ -9,7 +9,8 @@ Introduction
 ============
 
 Certain kinds of code transformations can inadvertently result in a loss of
-debug info, or worse, make debug info misrepresent the state of a program.
+debug info, or worse, make debug info misrepresent the state of a program. Debug
+info availability is also essential for SamplePGO.
 
 This document specifies how to correctly update debug info in various kinds of
 code transformations, and offers suggestions for how to create targeted debug
@@ -89,9 +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. This rule is also meant to assist SamplePGO by banning
-scenarios in which a sample of a block containing a merged instruction is
-misattributed to a block containing one of the instructions-to-be-merged.
+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. 
 
 Examples of transformations that should follow this rule include:
 

llvm/docs/SourceLevelDebugging.rst

@@ -55,6 +55,8 @@ the stored debug information into source-language specific information.  As
 such, a debugger must be aware of the source-language, and is thus tied to a
 specific language or family of languages.
 
+.. _intro_consumers:
+
 Debug information consumers
 ---------------------------
 
@@ -71,6 +73,12 @@ as Visual Studio and WinDBG. LLVM's debug information format is mostly derived
 from and inspired by DWARF, but it is feasible to translate into other target
 debug info formats such as STABS.
 
+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 to 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.
+
 It would also be reasonable to use debug information to feed profiling tools
 for analysis of generated code, or, tools for reconstructing the original
 source from generated code.