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.