[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

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

1040

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.

docs/WritingAnLLVMBackend.rst

 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. 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
+
+  $ 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, capture the
+exact TableGen command from a build by using:
+
+.. code-block:: shell
+
+  $ VERBOSE=1 make ...
+
+Then change to the appropriate target directory and re-issue the TableGen
+command with the ``subtarget-emitter`` debug option:
+
+.. code-block:: shell
+
+  $ ../../../bin/llvm-tblgen -debug-only=subtarget-emitter -gen-subtarget ...
+
 Instruction Relation Mapping
 ----------------------------