[llvm] [RemoveDIs] Add documentation for IR debug records (PR #81156)

[Stephen Tozer via llvm-commits]

https://github.com/SLTozer updated https://github.com/llvm/llvm-project/pull/81156

>From 56a27880b21e3f09e138ab5def71997c135dcfa8 Mon Sep 17 00:00:00 2001
From: Stephen Tozer <Stephen.Tozer at Sony.com>
Date: Thu, 8 Feb 2024 15:39:15 +0000
Subject: [PATCH 1/2] Add documentation for debug records

---
 llvm/docs/LangRef.rst              | 31 +++++++++++++-
 llvm/docs/SourceLevelDebugging.rst | 65 ++++++++++++++++++++++++++++++
 2 files changed, 94 insertions(+), 2 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index fd2e3aacd0169c..61778caec61b76 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -877,7 +877,8 @@ Syntax::
 
 A function definition contains a list of basic blocks, forming the CFG (Control
 Flow Graph) for the function. Each basic block may optionally start with a label
-(giving the basic block a symbol table entry), contains a list of instructions,
+(giving the basic block a symbol table entry), contains a list of instructions
+and :ref:`debug records <debugrecords>`,
 and ends with a :ref:`terminator <terminators>` instruction (such as a branch or
 function return). If an explicit label name is not provided, a block is assigned
 an implicit numbered label, using the next value from the same counter as used
@@ -8510,7 +8511,10 @@ The LLVM instruction set consists of several different classifications
 of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary
 instructions <binaryops>`, :ref:`bitwise binary
 instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and
-:ref:`other instructions <otherops>`.
+:ref:`other instructions <otherops>`. There are also :ref:`debug records
+<debugrecords>`, which are not true instructions themselves but are printed
+interleaved with instructions to describe changes in the state of the program's
+debug information at each position in the program's execution.
 
 .. _terminators:
 
@@ -12664,6 +12668,29 @@ Example:
 
       %tok = cleanuppad within %cs []
 
+.. _debugrecords:
+
+Debug Records
+-----------------------
+
+Debug records appear interleaved with instructions, but are not instructions;
+they are used only to define debug information, and have no effect on generated
+code. They are distinguished from instructions by the use of a leading `#` and
+an extra level of indentation. As an example:
+
+.. code-block:: llvm
+
+  %inst1 = op1 %a, %b
+    #dbg_value(%inst1, !10, !DIExpression(), !11)
+  %inst2 = op2 %inst1, %c
+
+These debug records are an optional replacement for
+:ref:`debug intrinsics<dbg_intrinsics>`, which will be output if the
+``--write-experimental-debuginfo`` flag is passed to LLVM; it is an error for both
+records and intrinsics to appear in the same module. More information about the
+meaning of debug records can be found in the `LLVM Source Level Debugging
+<SourceLevelDebugging.html#format-common-intrinsics>`_ document.
+
 .. _intrinsics:
 
 Intrinsic Functions
diff --git a/llvm/docs/SourceLevelDebugging.rst b/llvm/docs/SourceLevelDebugging.rst
index e1df7c355ee092..8fe61340c1761b 100644
--- a/llvm/docs/SourceLevelDebugging.rst
+++ b/llvm/docs/SourceLevelDebugging.rst
@@ -167,6 +167,17 @@ conventions used by the C and C++ front-ends.
 Debug information descriptors are `specialized metadata nodes
 <LangRef.html#specialized-metadata>`_, first-class subclasses of ``Metadata``.
 
+There are two models for defining the values of source variables at different
+states of the program and tracking these values through optimization and code
+generation: :ref:`intrinsic function calls <format_common_intrinsics>`, the
+current default, and :ref:`debug records <debug_records>`, which are a new
+non-instruction-based model
+(for an explanation of how this works and why it is desirable, see the
+`RemoveDIs <RemoveDIsDebugInfo.html>`_ document). Each module must use one or
+the other; they may never be mixed within an IR module. To enable writing debug
+records instead of intrinsic calls, use the flag
+``--write-experimental-debuginfo``.
+
 .. _format_common_intrinsics:
 
 Debugger intrinsic functions
@@ -268,6 +279,60 @@ The formal LLVM-IR signature is:
 
 See :doc:`AssignmentTracking` for more info.
 
+.. _debug_records:
+
+Debug Records
+----------------------------
+
+LLVM also has an alternative to intrinsic functions, debug records, which
+function similarly but are not instructions. The basic syntax for debug records
+is:
+
+.. code-block:: llvm
+
+  call void llvm.dbg.<type>([metadata <arg>, ]*), !dbg <DILocation> ; Intrinsic model
+    #dbg_<type>([<arg>, ]*, <DILocation>)                           ; Record model
+
+A debug intrinsic function can therefore be converted to a debug record with the
+following steps:
+
+1. Add an extra level of indentation.
+2. Replace everything prior to the intrinsic type (declare/value/assign) with
+   ``#dbg_``.
+3. Remove the leading ``metadata`` from the intrinsic's arguments.
+4. Transfer the ``!dbg`` attachment to be an argument, dropping the leading
+   ``!dbg``.
+
+For each variety of intrinsic function, there is an equivalent debug record.
+
+``#dbg_declare``
+^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+    #dbg_declare(Value, DILocalVariable, DIExpression, DILocation)
+
+Equivalent to the ``llvm.dbg.declare`` intrinsic.
+
+``#dbg_value``
+^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+    #dbg_value([Value|DIArgList], DILocalVariable, DIExpression, DILocation)
+
+Equivalent to the ``llvm.dbg.value`` intrinsic.
+
+``#dbg_assign``
+^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+    #dbg_assign([Value|DIArgList], DILocalVariable, DIExpression, DIAssignID,
+                Value, DIExpression, DILocation)
+
+Equivalent to the ``llvm.dbg.assign`` intrinsic.
+
 Object lifetimes and scoping
 ============================
 

>From 73f75735baf9d78ca8c70a6db13ae49feae4719f Mon Sep 17 00:00:00 2001
From: Stephen Tozer <Stephen.Tozer at Sony.com>
Date: Thu, 8 Feb 2024 18:04:48 +0000
Subject: [PATCH 2/2] Use 'kind' consistently, remove unnecessary words

---
 llvm/docs/LangRef.rst              |  8 ++++----
 llvm/docs/SourceLevelDebugging.rst | 11 ++++++-----
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 61778caec61b76..f2204670ec4e84 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -8512,7 +8512,7 @@ of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary
 instructions <binaryops>`, :ref:`bitwise binary
 instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and
 :ref:`other instructions <otherops>`. There are also :ref:`debug records
-<debugrecords>`, which are not true instructions themselves but are printed
+<debugrecords>`, which are not instructions themselves but are printed
 interleaved with instructions to describe changes in the state of the program's
 debug information at each position in the program's execution.
 
@@ -12685,10 +12685,10 @@ an extra level of indentation. As an example:
   %inst2 = op2 %inst1, %c
 
 These debug records are an optional replacement for
-:ref:`debug intrinsics<dbg_intrinsics>`, which will be output if the
+:ref:`debug intrinsics<dbg_intrinsics>`. Debug records will be output iff the
 ``--write-experimental-debuginfo`` flag is passed to LLVM; it is an error for both
-records and intrinsics to appear in the same module. More information about the
-meaning of debug records can be found in the `LLVM Source Level Debugging
+records and intrinsics to appear in the same module. More information about
+debug records can be found in the `LLVM Source Level Debugging
 <SourceLevelDebugging.html#format-common-intrinsics>`_ document.
 
 .. _intrinsics:
diff --git a/llvm/docs/SourceLevelDebugging.rst b/llvm/docs/SourceLevelDebugging.rst
index 8fe61340c1761b..ab6963e381296e 100644
--- a/llvm/docs/SourceLevelDebugging.rst
+++ b/llvm/docs/SourceLevelDebugging.rst
@@ -290,20 +290,21 @@ is:
 
 .. code-block:: llvm
 
-  call void llvm.dbg.<type>([metadata <arg>, ]*), !dbg <DILocation> ; Intrinsic model
-    #dbg_<type>([<arg>, ]*, <DILocation>)                           ; Record model
+    #dbg_<kind>([<arg>, ]*, <DILocation>)
+  ; Using the intrinsic model, the above is equivalent to:
+  call void llvm.dbg.<kind>([metadata <arg>, ]*), !dbg <DILocation>
 
-A debug intrinsic function can therefore be converted to a debug record with the
+A debug intrinsic function can be converted to a debug record with the
 following steps:
 
 1. Add an extra level of indentation.
-2. Replace everything prior to the intrinsic type (declare/value/assign) with
+2. Replace everything prior to the intrinsic kind (declare/value/assign) with
    ``#dbg_``.
 3. Remove the leading ``metadata`` from the intrinsic's arguments.
 4. Transfer the ``!dbg`` attachment to be an argument, dropping the leading
    ``!dbg``.
 
-For each variety of intrinsic function, there is an equivalent debug record.
+For each kind of intrinsic function, there is an equivalent debug record.
 
 ``#dbg_declare``
 ^^^^^^^^^^^^^^^^