Mesa (main): docs,isl: Document Sandy Bridge HiZ/stencil

[GitLab Mirror]

Module: Mesa
Branch: main
Commit: d3ea8f519eab95f4911143814b412ffbbd05f2d8
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=d3ea8f519eab95f4911143814b412ffbbd05f2d8

Author: Jason Ekstrand <jason at jlekstrand.net>
Date:   Mon Jun 21 10:25:41 2021 -0500

docs,isl: Document Sandy Bridge HiZ/stencil

This is annoying and tricky and we don't have all the gory details
written down in one central place anywhere.  Add a docs section on it.

Reviewed-by: Emma Anholt <emma at anholt.net>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/11500>

---

 docs/isl/hiz.rst   | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/isl/index.rst |  1 +
 2 files changed, 75 insertions(+)

diff --git a/docs/isl/hiz.rst b/docs/isl/hiz.rst
new file mode 100644
index 00000000000..748eec249c6
--- /dev/null
+++ b/docs/isl/hiz.rst
@@ -0,0 +1,74 @@
+Hierarchical Depth (HiZ)
+========================
+
+TODO: Add detailed docs like we have for CCS
+
+HiZ/stencil on Sandy Bridge
+---------------------------
+
+Properly enabling HiZ on Sandy Bridge requires certain special considerations.
+From the Sandy Bridge PRM Vol. 2, Pt. 1, 7.5.3 "Hierarchical Depth Buffer" (p.
+312):
+
+    The hierarchical depth buffer does not support the LOD field, it is assumed
+    by hardware to be zero. A separate hierarachical depth buffer is required
+    for each LOD used, and the corresponding buffer’s state delivered to
+    hardware each time a new depth buffer state with modified LOD is delivered.
+
+The ``3DSTATE_STENCIL_BUFFER`` packet for separate stencil (required for HiZ)
+on sandy bridge also lacks an LOD field.  Empirically, the hardware doesn't
+pull the stencil LOD from ``3DSTATE_DEPTH_BUFFER``, it's just always 0 like
+with HiZ.
+
+As stated in the PRM, this means we need a separate HiZ or stencil buffer for
+each LOD.  However, it's not quite as simple as that.  If you ignore layered
+rendering, things are pretty straightforward: you need one HiZ surface for each
+main surface slice With layered, rendering, however, we have to be a bit more
+clever because we need a "real" array surface at each LOD.  ISL solves this
+with a special miptree layout for layered rendering
+:cpp:enumerator:`isl_dim_layout::ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` which lays
+out the surface as a miptree of layered images instead of an array of miptrees.
+See the docs for
+:cpp:enumerator:`isl_dim_layout::ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` for a nice
+description along with an ASCII art diagram of the layout.
+
+Also, neither ``3DSTATE_STENCIL_BUFFER`` nor ``3DSTATE_HIER_DEPTH_BUFFER`` have
+their own surface dimensions or layout information on Sandy Bridge.  They're
+just an address and a surface pitch.  Instead, all that other information is
+pulled from ``3DSTATE_DEPTH_BUFFER``.  When you combine this with the lack of
+LOD, this means that, technically, we have a full-sized single-LOD stencil or
+HiZ surface at each miplevel of which only the upper left-hand corner of each
+array slice ever gets used.  The net effect of this is that, in
+:cpp:enumerator:`isl_dim_layout::ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ`, all LODs
+share the same QPitch even though it's horribly wasteful.  This is actually
+pretty convenient for ISL because we only have the one
+:cpp:member:`isl_surf::array_pitch_el_rows` field.
+
+Due to difficulties with plumbing relocation deltas through ISL's
+depth/stencil/hiz emit interface, we can't handle this all automatically in
+ISL.  Instead, it's left up to the driver to do this offsetting.  ISL does
+provide helpers for computing the offsets and they work fine with
+:cpp:enumerator:`isl_dim_layout::ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` so all that's
+really required is to call the ISL helper and add the computed offset to the
+HiZ or stencil buffer address.  The following is an excerpt from BLORP where we
+do this as an example:
+
+.. code-block:: c
+
+    struct blorp_address hiz_address = params->depth.aux_addr;
+    #if GFX_VER == 6
+    /* Sandy bridge hardware does not technically support mipmapped HiZ.
+     * However, we have a special layout that allows us to make it work
+     * anyway by manually offsetting to the specified miplevel.
+     */
+    assert(info.hiz_surf->dim_layout == ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ);
+    uint32_t offset_B;
+    isl_surf_get_image_offset_B_tile_sa(info.hiz_surf,
+                                        info.view->base_level, 0, 0,
+                                        &offset_B, NULL, NULL);
+    hiz_address.offset += offset_B;
+    #endif
+
+    info.hiz_address =
+       blorp_emit_reloc(batch, dw + isl_dev->ds.hiz_offset / 4,
+                        hiz_address, 0);
diff --git a/docs/isl/index.rst b/docs/isl/index.rst
index d91508d6689..8ebf7ddbac8 100644
--- a/docs/isl/index.rst
+++ b/docs/isl/index.rst
@@ -13,6 +13,7 @@ Chery.
    formats
    tiling
    ccs
+   hiz
 
 The core representation of a surface in ISL is :cpp:struct:`isl_surf`.