[docs] Document the lost variables statistics option

docs/DebuggingTheCompiler.md

@@ -302,6 +302,13 @@ with the proper attributes to ensure they'll be available in the debugger. In
 particular, if you see `SWIFT_DEBUG_DUMP` in a class declaration, that class
 has a `dump()` method you can call.
 
+### Pass statistics
+
+There are options to output a lot of different statistics, including about
+SIL passes. More information is available in
+[Compiler Performance](CompilerPerformance.md) for the unified statistics, and
+[Optimizer Counter Analysis](OptimizerCountersAnalysis.md) for pass counters.
+
 ## Debugging and Profiling on SIL level
 
 ### SIL source level profiling

docs/HowToUpdateDebugInfo.md

@@ -255,7 +255,8 @@ debug_value %1 : $Int, var, name "pair", type $Pair, expr op_fragment:#Pair.a //
 
 ## Rules of thumb
 - Optimization passes may never drop a variable entirely. If a variable is
-  entirely optimized away, an `undef` debug value should still be kept.
+  entirely optimized away, an `undef` debug value should still be kept. The only
+  exception is an unreachable function or scope, which is entirely removed.
 - A `debug_value` must always describe a correct value for that source variable
   at that source location. If a value is only correct on some paths through that
   instruction, it must be replaced with `undef`. Debug info never speculates.
@@ -263,3 +264,9 @@ debug_value %1 : $Int, var, name "pair", type $Pair, expr op_fragment:#Pair.a //
   capture the effect of the deleted instruction in a debug expression, so the
   location can be preserved. You can also use an `InstructionDeleter` which will
   automatically call `salvageDebugInfo`.
+
+> [!Tip]
+> To detect when a pass drops a variable, you can use the
+> `-Xllvm -sil-stats-lost-variables` to print when a variable is lost by a pass.
+> More information about this option is available in
+> [Optimizer Counter Analysis](OptimizerCountersAnalysis.md)

docs/OptimizerCountersAnalysis.md

@@ -54,7 +54,8 @@ The following statistics can be recorded:
 
   * For SILFunctions: the number of SIL basic blocks for each SILFunction, the
     number of SIL instructions, the number of SILInstructions of a specific
-    kind (e.g. a number of alloc_ref instructions)
+    kind (e.g. a number of alloc_ref instructions), the number of debug
+    variables
 
   * For SILModules: the number of SIL basic blocks in the SILModule, the number
     of SIL instructions, the number of SILFunctions, the number of
@@ -118,6 +119,16 @@ e.g. `-Xllvm -sil-stats-only-instructions=alloc_ref,alloc_stack`. If you need to
 collect stats about all kinds of SIL instructions, you can use this syntax: 
 `-Xllvm -sil-stats-only-instructions=all`.
 
+### Debug variable level counters
+A different type of counter is the lost debug variables counter. It is enabled
+by using the `-Xllvm -sil-stats-lost-variables` command-line option. It only
+tracks statistics about lost variables in SILFunctions. It is not enabled by
+any other command-line option, but can be combined with the others. It is not
+compatible with thresholds, it always counts lost variables. Note that it does
+not track the number of debug variables: it counts the number of debug variables
+that were present, but aren't anymore. If a variable changes location or scope,
+which is not allowed, it will be counted as lost.
+
 ## Configuring which counters changes should be recorded
 
 The user has a possibility to configure a number of thresholds, which control
@@ -181,9 +192,9 @@ And for counter stats it looks like this:
   * `function_history` corresponds to the verbose mode of function
     counters collection, when changes to the SILFunction counters are logged 
     unconditionally, without any on-line filtering.
-* `CounterName` is typically one of `block`, `inst`, `function`, `memory`, 
-   or `inst_instruction_name` if you collect counters for specific kinds of SIL
-   instructions.
+* `CounterName` is typically one of `block`, `inst`, `function`, `memory`,
+   `lostvars`, or `inst_instruction_name` if you collect counters for specific
+   kinds of SIL instructions.
 * `Symbol` is e.g. the name of a function
 * `StageName` is the name of the current optimizer pipeline stage
 * `TransformName` is the name of the current optimizer transformation/pass
@@ -192,6 +203,14 @@ And for counter stats it looks like this:
    want to reproduce the result later using 
    `-Xllvm -sil-opt-pass-count -Xllvm TransformPassNumber`
 
+## Extract Lost Variables per Pass
+
+For lost variables, there is a script to output a CSV with only the amount of
+lost variables per pass. You can then easily open the resulting CSV in Numbers
+to make graphs.
+
+`utils/process-stats-lost-variables csv_file_with_counters > csv_aggregate`
+
 ## Storing the produced statistics into a database
 
 To store the set of produced counters into a database, you can use the
@@ -345,4 +364,3 @@ from Counters C where C.counter = 'inst' and C.kind = 'module'
 group by Stage
 order by sum(C.Delta);
 ```
-