diff options
Diffstat (limited to 'src/glsl/nir/docs/source/metadata.rst')
| -rw-r--r-- | src/glsl/nir/docs/source/metadata.rst | 34 |
1 files changed, 34 insertions, 0 deletions
diff --git a/src/glsl/nir/docs/source/metadata.rst b/src/glsl/nir/docs/source/metadata.rst new file mode 100644 index 0000000000..9dc1b8700c --- /dev/null +++ b/src/glsl/nir/docs/source/metadata.rst @@ -0,0 +1,34 @@ +Metadata +======== + +Many of the optimization/lowering passes in NIR require different bits of +metadata that are provided by different analysis passes. Currently, this +metadata includes: + +* dominance information +* SSA value liveness +* source-order block indices + +and it's expected that there will be more in the future. The metadata itself +is currently directly embedded inside the IR datastructures (for example, each +basic block contains information about its parent and children in the +dominance tree), but we still need a way to calculate the metadata only when +actually required. In order to do this, there's a simple API made of two +functions: + +* ``nir_metadata_require()``: Declares that the given metadata (an OR of enum + values) is required. The function automatically calls all of the required + analysis passes for you and, upon its return, the requested metadata is + available and current. +* ``nir_metadata_preserve()``: Called to declare what metadata (if any) was + preserved by the given pass. If the pass didn't touch anything, it doesn't + need to call this function. However, if it adds/removes instructions or + modifies the CFG in any way, it needs to call ``nir_metadata_preserve()``. + The ``nir_metadata_preserve()`` function takes an OR of all of the bits of + metadata that are preserved. That way as new metadata gets added, we don't + have to update every optimization pass to dirty it. + +Unfortunately, there's no way to guarantee that you actually call +``nir_metadata_preserve()`` if you change the shader, so if you don't... +shame on you. + |