intel/isl: Add an enum for describing auxiliary compression state

This enum describes all of the states that a auxiliary compressed
surface can have.  All of the states as well as normative language for
referring to each of the compression operations is provided in the
truly colossal comment for the new isl_aux_state enum.  There is also
a diagram showing how surfaces move between the different states.

Reviewed-by: Topi Pohjolainen <topi.pohjolainen@intel.com>
Reviewed-by: Nanley Chery <nanley.g.chery@intel.com>
Reviewed-by: Chad Versace <chadversary@chromium.org>

1 files changed, 169 insertions, 0 deletions

diff --git a/src/intel/isl/isl.h b/src/intel/isl/isl.h
index 658f67e4ae..95ecaf90d8 100644
--- a/src/intel/isl/isl.h
+++ b/src/intel/isl/isl.h
@@ -600,6 +600,175 @@ enum isl_aux_usage {
    ISL_AUX_USAGE_CCS_E,
 };
 
+/**
+ * Enum for keeping track of the state an auxiliary compressed surface.
+ *
+ * For any given auxiliary surface compression format (HiZ, CCS, or MCS), any
+ * given slice (lod + array layer) can be in one of the six states described
+ * by this enum.  Draw and resolve operations may cause the slice to change
+ * from one state to another.  The six valid states are:
+ *
+ *    1) Clear:  In this state, each block in the auxiliary surface contains a
+ *       magic value that indicates that the block is in the clear state.  If
+ *       a block is in the clear state, it's values in the primary surface are
+ *       ignored and the color of the samples in the block is taken either the
+ *       RENDER_SURFACE_STATE packet for color or 3DSTATE_CLEAR_PARAMS for
+ *       depth.  Since neither the primary surface nor the auxiliary surface
+ *       contains the clear value, the surface can be cleared to a different
+ *       color by simply changing the clear color without modifying either
+ *       surface.
+ *
+ *    2) Compressed w/ Clear:  In this state, neither the auxiliary surface
+ *       nor the primary surface has a complete representation of the data.
+ *       Instead, both surfaces must be used together or else rendering
+ *       corruption may occur.  Depending on the auxiliary compression format
+ *       and the data, any given block in the primary surface may contain all,
+ *       some, or none of the data required to reconstruct the actual sample
+ *       values.  Blocks may also be in the clear state (see Clear) and have
+ *       their value taken from outside the surface.
+ *
+ *    3) Compressed w/o Clear:  This state is identical to the state above
+ *       except that no blocks are in the clear state.  In this state, all of
+ *       the data required to reconstruct the final sample values is contained
+ *       in the auxiliary and primary surface and the clear value is not
+ *       considered.
+ *
+ *    4) Resolved:  In this state, the primary surface contains 100% of the
+ *       data.  The auxiliary surface is also valid so the surface can be
+ *       validly used with or without aux enabled.  The auxiliary surface may,
+ *       however, contain non-trivial data and any update to the primary
+ *       surface with aux disabled will cause the two to get out of sync.
+ *
+ *    5) Pass-through:  In this state, the primary surface contains 100% of the
+ *       data and every block in the auxiliary surface contains a magic value
+ *       which indicates that the auxiliary surface should be ignored and the
+ *       only the primary surface should be considered.  Updating the primary
+ *       surface without aux works fine and can be done repeatedly in this
+ *       mode.  Writing to a surface in pass-through mode with aux enabled may
+ *       cause the auxiliary buffer to contain non-trivial data and no longer
+ *       be in the pass-through state.
+ *
+ *    5) Aux Invalid:  In this state, the primary surface contains 100% of the
+ *       data and the auxiliary surface is completely bogus.  Any attempt to
+ *       use the auxiliary surface is liable to result in rendering
+ *       corruption.  The only thing that one can do to re-enable aux once
+ *       this state is reached is to use an ambiguate pass to transition into
+ *       the pass-through state.
+ *
+ * Drawing with or without aux enabled may implicitly cause the surface to
+ * transition between these states.  There are also four types of auxiliary
+ * compression operations which cause an explicit transition:
+ *
+ *    1) Fast Clear:  This operation writes the magic "clear" value to the
+ *       auxiliary surface.  This operation will safely transition any slice
+ *       of a surface from any state to the clear state so long as the entire
+ *       slice is fast cleared at once.
+ *
+ *    2) Full Resolve:  This operation combines the auxiliary surface data
+ *       with the primary surface data and writes the result to the primary.
+ *       For HiZ, the docs call this a depth resolve.  For CCS, the hardware
+ *       full resolve operation does both a full resolve and an ambiguate so
+ *       it actually takes you all the way to the pass-through state.
+ *
+ *    3) Partial Resolve:  This operation considers blocks which are in the
+ *       "clear" state and writes the clear value directly into the primary or
+ *       auxiliary surface.  Once this operation completes, the surface is
+ *       still compressed but no longer references the clear color.  This
+ *       operation is only available for CCS.
+ *
+ *    4) Ambiguate:  This operation throws away the current auxiliary data and
+ *       replaces it with the magic pass-through value.  If an ambiguate
+ *       operation is performed when the primary surface does not contain 100%
+ *       of the data, data will be lost.  This operation is only implemented
+ *       in hardware for depth where it is called a HiZ resolve.
+ *
+ * Not all operations are valid or useful in all states.  The diagram below
+ * contains a complete description of the states and all valid and useful
+ * transitions except clear.
+ *
+ *   Draw w/ Aux
+ *   +----------+
+ *   |          |
+ *   |       +-------------+     Draw w/ Aux      +-------------+
+ *   +------>| Compressed  |<---------------------|    Clear    |
+ *           |  w/ Clear   |                      |             |
+ *           +-------------+                      +-------------+
+ *                  |   |                                |
+ *          Partial |   |                                |
+ *          Resolve |   |        Full Resolve            |
+ *                  |   +----------------------------+   |  Full
+ *                  |                                |   | Resolve
+ *   Draw w/ aux    |                                |   |
+ *   +----------+   |                                |   |
+ *   |          |  \|/                              \|/ \|/
+ *   |       +-------------+     Full Resolve     +-------------+
+ *   +------>| Compressed  |--------------------->|  Resolved   |
+ *           |  w/o Clear  |<---------------------|             |
+ *           +-------------+     Draw w/ Aux      +-------------+
+ *                 /|\                               |   |
+ *                  |  Draw                          |   |  Draw
+ *                  | w/ Aux                         |   | w/o Aux
+ *                  |             Ambiguate          |   |
+ *                  |   +----------------------------+   |
+ *   Draw w/o Aux   |   |                                |   Draw w/o Aux
+ *   +----------+   |   |                                |   +----------+
+ *   |          |   |  \|/                              \|/  |          |
+ *   |       +-------------+      Ambiguate       +-------------+       |
+ *   +------>|    Pass-    |<---------------------|     Aux     |<------+
+ *           |   through   |                      |   Invalid   |
+ *           +-------------+                      +-------------+
+ *
+ *
+ * While the above general theory applies to all forms of auxiliary
+ * compression on Intel hardware, not all states and operations are available
+ * on all compression types.  However, each of the auxiliary states and
+ * operations can be fairly easily mapped onto the above diagram:
+ *
+ * HiZ:     Hierarchical depth compression is capable of being in any of the
+ *          states above.  Hardware provides three HiZ operations: "Depth
+ *          Clear", "Depth Resolve", and "HiZ Resolve" which map to "Fast
+ *          Clear", "Full Resolve", and "Ambiguate" respectively.  The
+ *          hardware provides no HiZ partial resolve operation so the only way
+ *          to get into the "Compressed w/o Clear" state is to render with HiZ
+ *          when the surface is in the resolved or pass-through states.
+ *
+ * MCS:     Multisample compression is technically capable of being in any of
+ *          the states above except that most of them aren't useful.  Both the
+ *          render engine and the sampler support MCS compression and, apart
+ *          from clear color, MCS is format-unaware so we leave the surface
+ *          compressed 100% of the time.  The hardware provides no MCS
+ *          operations.
+ *
+ * CCS_D:   Single-sample fast-clears (also called CCS_D in ISL) are one of
+ *          the simplest forms of compression since they don't do anything
+ *          beyond clear color tracking.  They really only support three of
+ *          the six states: Clear, Compressed w/ Clear, and Pass-through.  The
+ *          only CCS_D operation is "Resolve" which maps to a full resolve
+ *          followed by an ambiguate.
+ *
+ * CCS_E:   Single-sample render target compression (also called CCS_E in ISL)
+ *          is capable of being in almost all of the above states.  THe only
+ *          exception is that it does not have separate resolved and pass-
+ *          through states.  Instead, the CCS_E full resolve operation does
+ *          both a resolve and an ambiguate so it goes directly into the
+ *          pass-through state.  CCS_E also provides fast clear and partial
+ *          resolve operations which work as described above.
+ *
+ *          While it is technically possible to perform a CCS_E ambiguate, it
+ *          is not provided by Sky Lake hardware so we choose to avoid the aux
+ *          invalid state.  If the aux invalid state were determined to be
+ *          useful, a CCS ambiguate could be done by carefully rendering to
+ *          the CCS and filling it with zeros.
+ */
+enum isl_aux_state {
+   ISL_AUX_STATE_CLEAR = 0,
+   ISL_AUX_STATE_COMPRESSED_CLEAR,
+   ISL_AUX_STATE_COMPRESSED_NO_CLEAR,
+   ISL_AUX_STATE_RESOLVED,
+   ISL_AUX_STATE_PASS_THROUGH,
+   ISL_AUX_STATE_AUX_INVALID,
+};
+
 /* TODO(chadv): Explain */
 enum isl_array_pitch_span {
    ISL_ARRAY_PITCH_SPAN_FULL,