[docs] Document how to debug instruction scheduling model generation

[joelkevinjones]

Summary

Describe:

+ Exact tablegen command and how to get it
+ tablegen command debug option for subtarget generation
+ Use of schedcover.py on the debug output to determine coverage

[joelkevinjones]

Used complete file diff

[christof]

Good idea to add a little write-up on that utility. Might want to make it more clear that it is about the machine scheduler models. It does not do anything for the Itinerary based schedule models.

I tend not to use the make output to construct the TableGen command as it is easy enough to construct and it saves some digging into the make output to get the right command out. At the root of the source tree it is:

<build>/bin/llvm-tblgen -I include -I lib/Target/<target> lib/Target/<target>/<target>.td --gen-subtarget --debug-only=subtarget-emitter

Where <build> is the build directory and <target> the directory name of the target.

But a verbose make run does work as well if you prefer that. I don't hold a strong opinion on it.

[joelkevinjones]

If you know the command, I agree that digging through the verbose make output is unnecessary. I'll give the entire command and make your suggested change vis-a-vis distinguishing itinerary and machine scheduler model.

[joelkevinjones]

Describe distinction between sched model and itinerary vis-a-vis schedcover.py.
Give complete command for llvm-tblgen debug output

[christof]

Please make sure that the build directory is not assumed to be present in the root of the source tree. For the rest I'm happy to approve it.

docs/WritingAnLLVMBackend.rst

1038 ↗

(On Diff #106686)

This assumes the <build> directory is at the top of the source directory. That is not true in general.

1040 ↗

(On Diff #106686)

Any particular reason to write to the result there? I would go for -o /dev/null because we are not interested in the generated C output.

[joelkevinjones]

Remove assumption that the build directory is a subdirectory of the source directory.

llvm/trunk/docs/WritingAnLLVMBackend.rst

 Instruction Scheduling
 ----------------------
 
 Instruction itineraries can be queried using MCDesc::getSchedClass(). The
 value can be named by an enumemation in llvm::XXX::Sched namespace generated
 by TableGen in XXXGenInstrInfo.inc. The name of the schedule classes are
 the same as provided in XXXSchedule.td plus a default NoItinerary class.
 
+The schedule models are generated by TableGen by the SubtargetEmitter,
+using the ``CodeGenSchedModels`` class. This is distinct from the itinerary
+method of specifying machine resource use.  The tool ``utils/schedcover.py``
+can be used to determine which instructions have been covered by the
+schedule model description and which haven't. The first step is to use the
+instructions below to create an output file. Then run ``schedcover.py`` on the
+output file:
+
+.. code-block:: shell
+
+  $ <src>/utils/schedcover.py <build>/lib/Target/AArch64/tblGenSubtarget.with
+  instruction, default, CortexA53Model, CortexA57Model, CycloneModel, ExynosM1Model, FalkorModel, KryoModel, ThunderX2T99Model, ThunderXT8XModel
+  ABSv16i8, WriteV, , , CyWriteV3, M1WriteNMISC1, FalkorWr_2VXVY_2cyc, KryoWrite_2cyc_XY_XY_150ln, , 
+  ABSv1i64, WriteV, , , CyWriteV3, M1WriteNMISC1, FalkorWr_1VXVY_2cyc, KryoWrite_2cyc_XY_noRSV_67ln, , 
+  ...
+
+To capture the debug output from generating a schedule model, change to the
+appropriate target directory and use the following command:
+command with the ``subtarget-emitter`` debug option:
+
+.. code-block:: shell
+
+  $ <build>/bin/llvm-tblgen -debug-only=subtarget-emitter -gen-subtarget \
+    -I <src>/lib/Target/<target> -I <src>/include \
+    -I <src>/lib/Target <src>/lib/Target/<target>/<target>.td \
+    -o <build>/lib/Target/<target>/<target>GenSubtargetInfo.inc.tmp \
+    > tblGenSubtarget.dbg 2>&1
+
+Where ``<build>`` is the build directory, ``src`` is the source directory,
+and ``<target>`` is the name of the target.
+To double check that the above command is what is needed, one can capture the
+exact TableGen command from a build by using:
+
+.. code-block:: shell
+
+  $ VERBOSE=1 make ... 
+
+and search for ``llvm-tblgen`` commands in the output.
+
+
 Instruction Relation Mapping
 ----------------------------
 
 This TableGen feature is used to relate instructions with each other.  It is
 particularly useful when you have multiple instruction formats and need to
 switch between them after instruction selection.  This entire feature is driven
 by relation models which can be defined in ``XXXInstrInfo.td`` files
 according to the target-specific instruction set.  Relation models are defined