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.