|
|
@@ -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:
|
Lei Zhang