[spirv] Update mapping manual w.r.t. debugging and options (#1475)

docs/SPIR-V.rst

@@ -348,13 +348,14 @@ Optimization
 Optimization is also delegated to SPIRV-Tools. Right now there are no difference
 between optimization levels greater than zero; they will all invoke the same
 optimization recipe. That is, the recipe behind ``spirv-opt -O``.  If you want to
-run a custom optimization recipe, you can do so using the command line option ``-Oconfig=``
-and specifying a comma-separated list of your desired passes. The passes are invoked in the 
-specified order.
+run a custom optimization recipe, you can do so using the command line option
+``-Oconfig=`` and specifying a comma-separated list of your desired passes.
+The passes are invoked in the specified order.
 
 For example, you can specify ``-Oconfig=--loop-unroll,--scalar-replacement=300,--eliminate-dead-code-aggressive``
-to firstly invoke loop unrolling, then invoke scalar replacement of aggregates, lastly invoke aggressive dead code elimination.
-All valid options to ``spirv-opt`` are accepted as components to the comma-separated list.
+to firstly invoke loop unrolling, then invoke scalar replacement of aggregates,
+lastly invoke aggressive dead code elimination. All valid options to
+``spirv-opt`` are accepted as components to the comma-separated list.
 
 Here are the typical passes in alphabetical order:
 
@@ -391,17 +392,20 @@ Here are the typical passes in alphabetical order:
 * ``--vector-dce``
 
 
-Besides, there are two special batch options; each stands for a recommended recipe by itself:
+Besides, there are two special batch options; each stands for a recommended
+recipe by itself:
 
-* ``-O``: A bunch of passes in an appropriate order that attempt to improve performance of generated code. Same as ``spirv-opt -O``. Also same as SPIR-V CodeGen's default recipe.
+* ``-O``: A bunch of passes in an appropriate order that attempt to improve
+  performance of generated code. Same as ``spirv-opt -O``. Also same as SPIR-V
+  CodeGen's default recipe.
+* ``-Os``: A bunch of passes in an appropriate order that attempt to reduce the
+  size of the generated code. Same as ``spirv-opt -Os``.
 
-* ``-Os``: A bunch of passes in an appropriate order that attempt to reduce the size of the generated code. Same as ``spirv-opt -Os``.
+So if you want to run loop unrolling additionally after the default optimization
+recipe, you can specify ``-Oconfig=-O,--loop-unroll``.
 
-So if you want to run loop unrolling additionally after the default optimization recipe, you can specify
-``-Oconfig=-O,--loop-unroll``.
-
-For the whole list of accepted passes and details about each one, please see ``spirv-opt``'s help manual (``spirv-opt --help``),
-or the SPIRV-Tools `optimizer header file <https://github.com/KhronosGroup/SPIRV-Tools/blob/master/include/spirv-tools/optimizer.hpp>`_.
+For the whole list of accepted passes and details about each one, please see
+``spirv-opt``'s help manual (``spirv-opt --help``), or the SPIRV-Tools `optimizer header file <https://github.com/KhronosGroup/SPIRV-Tools/blob/master/include/spirv-tools/optimizer.hpp>`_.
 
 Validation
 ~~~~~~~~~~
@@ -410,6 +414,29 @@ Validation is turned on by default as the last stage of SPIR-V CodeGen. Failing
 validation, which indicates there is a CodeGen bug, will trigger a fatal error.
 Please file an issue if you see that.
 
+Debugging
+---------
+
+By default, the compiler will only emit names for types and variables as debug
+information, to aid reading of the generated SPIR-V. The ``-Zi`` option will
+let the compiler emit the following additional debug information:
+
+* Full path of the main source file using ``OpSource``
+* Preprocessed source code using ``OpSource`` and ``OpSourceContinued``
+* Line information for certain instructions using ``OpLine`` (WIP)
+
+We chose to embed preprocessed source code instead of original source code to
+avoid pulling in lots of contents unrelated to the current entry point, and
+boilerplate contents generated by engines. We may add a mode for selecting
+between preprocessed single source code and original separated source code in
+the future.
+
+One thing to note is that to keep the line numbers in consistent with the
+embedded source, the compiler is invoked twice; the first time is for
+preprocessing the source code, and the second time is for feeding the
+preprocessed source code as input for a whole compilation. So using ``-Zi``
+means performance penality.
+
 Reflection
 ----------
 
@@ -2750,8 +2777,41 @@ Quad          ``QuadReadAcrossDiagonal()`` ``OpGroupNonUniformQuadSwap``
 Quad          ``QuadReadLaneAt()``         ``OpGroupNonUniformQuadBroadcast``
 ============= ============================ =================================== ======================
 
-Vulkan Command-line Options
-===========================
+Supported Command-line Options
+==============================
+
+Command-line options supported by SPIR-V CodeGen are listed below. They are
+also recognized by the library API calls.
+
+General options
+---------------
+
+- ``-T``: specifies shader profile
+- ``-E``: specifies entry point
+- ``-D``: Defines macro
+- ``-I``: Adds directory to include search path
+- ``-O{|0|1|2|3}``: Specifies optimization level
+- ``-enable-16bit-types``: enables 16-bit types and disables min precision types
+- ``-Zpc``: Packs matrices in column-major order by deafult
+- ``-Zpr``: Packs matrices in row-major order by deafult
+- ``-Fc``: outputs SPIR-V disassembly to the given file
+- ``-Fe``: outputs warnings and errors to the given file
+- ``-Fo``: outputs SPIR-V code to the given file
+- ``-Fh``: outputs SPIR-V code as a header file
+- ``-Vn``: specifies the variable name for SPIR-V code in generated header file
+- ``-Zi``: Emits more debug information (see `Debugging`_)
+- ``-Cc``: colorizes SPIR-V disassembly
+- ``-No``: adds instruction byte offsets to SPIR-V disassembly
+- ``-H``:  Shows header includes and nesting depth
+- ``-Vi``: Shows details about the include process
+- ``-Vd``: Disables SPIR-V verification
+- ``-WX``: Treats warnings as errors
+- ``-no-warnings``: Suppresses all warnings
+- ``-flegacy-macro-expansion``: expands the operands before performing
+  token-pasting operation (fxc behavior)
+
+Vulkan-specific options
+-----------------------
 
 The following command line options are added into ``dxc`` to support SPIR-V
 codegen for Vulkan:

include/dxc/Support/HLSLOptions.td

@@ -263,7 +263,7 @@ def fspv_target_env_EQ : Joined<["-"], "fspv-target-env=">, Group<spirv_Group>,
 def Wno_vk_ignored_features : Joined<["-"], "Wno-vk-ignored-features">, Group<spirv_Group>, Flags<[CoreOption, DriverOption, HelpHidden]>,
   HelpText<"Do not emit warnings for ingored features resulting from no Vulkan support">;
 def Oconfig : CommaJoined<["-"], "Oconfig=">, Group<spirv_Group>, Flags<[CoreOption]>,
-  HelpText<"Specify a comma-separated list of SPIRV-Tools passes to customize optimization configuration">;
+  HelpText<"Specify a comma-separated list of SPIRV-Tools passes to customize optimization configuration (see http://khr.io/hlsl2spirv#optimization)">;
 // SPIRV Change Ends
 
 //////////////////////////////////////////////////////////////////////////////