[llvm] [Docs][DebugInfo][RemoveDIs] Document some debug-info transition info (PR #79167)

[J. Ryan Stinnett via llvm-commits]

================
@@ -0,0 +1,106 @@
+# What's all this then?
+
+We're planning on removing debug-info intrinsics from LLVM, as they're slow, unweildy and can confuse optimisation passes if they're not expecting them. Instead of having a sequence of instructions that looks like this:
+
+```text
+    %add = add i32 %foo, %bar
+    call void @llvm.dbg.value(metadata %add, ...
+    %sub = sub i32 %add, %tosub
+    call void @llvm.dbg.value(metadata %sub, ...
+    call void @a_normal_function()
+```
+
+with dbg.value intrinsics representing debug-info records, it would instead be printed as:
+
+```text
+    %add = add i32 %foo, %bar
+      #dbg_value(%add, ...
+    %sub = sub i32 %add, %tosub
+      #dbg_value(%sub, ...
+    call void @a_normal_function()
+```
+
+Where the debug records are not instructions, do not appear in the instruction list, and won't appear in your optimisation passes unless you go digging for them deliberately.
+
+# Great, what do I need to do!
+
+Approximately nothing -- we've already instrumented all of LLVM to handle these new records ("DPValues") and behave identically to past LLVM behaviour. We plan on turning this on by default some time soon, with IR converted to the intrinsic-form of debug-info at terminals (textual IR, Bitcode) for a short while, before then changing the textual IR and Bitcode formats.
+
+There are two significant changes to be aware of. Firstly, we're adding a single bit of debug-info relevant data to the BasicBlock::iterator class (it's so that we can determine whether ranges intend on including debug-info at the beginning of a block or not). That means when writing passes that insert LLVM-IR instructions, you need to identify positions with BasicBlock::iterator rather than just a bare Instruction *. Most of the time this means that after identifying where you intend on inserting something, you must also call getIterator on the instruction position -- however when inserting at the start of a block you _must_ use getFirstInsertionPt, getFirstNonPHIIt or begin and use that iterator to insert, rather than just fetching a pointer to the first instruction.
+
+The second matter is that if you transfer sequences of instructions from one place to another manually, i.e. repeatedly using moveBefore where you might have used splice, then you should instead use the method moveBeforePreserving. moveBeforePreserving will transfer debug-info records with the instruction they're attached to. This is something that happens automatically today -- if you use moveBefore on every element of an instruction sequence, then debug intrinsics will be moved in the normal course of your code, but we lose this behaviour with non-instruction debug-info.
----------------
jryans wrote:

Consider wrapping code identifiers in backticks:

```suggestion
The second matter is that if you transfer sequences of instructions from one place to another manually, i.e. repeatedly using `moveBefore` where you might have used splice, then you should instead use the method `moveBeforePreserving`. `moveBeforePreserving` will transfer debug-info records with the instruction they're attached to. This is something that happens automatically today -- if you use `moveBefore` on every element of an instruction sequence, then debug intrinsics will be moved in the normal course of your code, but we lose this behaviour with non-instruction debug-info.
```

https://github.com/llvm/llvm-project/pull/79167