Mesa (main): zink: add some nice docs for batch usage and tracking

[GitLab Mirror]

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

Author: Mike Blumenkrantz <michael.blumenkrantz at gmail.com>
Date:   Thu Mar 17 11:44:58 2022 -0400

zink: add some nice docs for batch usage and tracking

Reviewed-by: Dave Airlie <airlied at redhat.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/15429>

---

 src/gallium/drivers/zink/zink_batch.h | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/src/gallium/drivers/zink/zink_batch.h b/src/gallium/drivers/zink/zink_batch.h
index 1e1b3f39329..364967a7b39 100644
--- a/src/gallium/drivers/zink/zink_batch.h
+++ b/src/gallium/drivers/zink/zink_batch.h
@@ -48,6 +48,36 @@ struct zink_resource;
 struct zink_sampler_view;
 struct zink_surface;
 
+/* zink_batch_usage concepts:
+ * - batch "usage" is an indicator of when and how a BO was accessed
+ * - batch "tracking" is the batch state(s) containing an extra ref for a BO
+ *
+ * - usage prevents a BO from being mapped while it has pending+conflicting access
+ * - usage affects pipeline barrier generation for synchronizing reads and writes
+ * - usage MUST be removed before context destruction to avoid crashing during BO
+ *   reclaiming in suballocator
+ *
+ * - tracking prevents a BO from being destroyed early
+ * - tracking enables usage to be pruned
+ *
+ *
+ * tracking is added:
+ * - any time a BO is used in a "one-off" operation (e.g., blit, index buffer, indirect buffer)
+ * - any time a descriptor is unbound
+ * - when a buffer is replaced (IFF: resource is bound as a descriptor or usage previously existed)
+ *
+ * tracking is removed:
+ * - in zink_reset_batch_state()
+ *
+ * usage is added:
+ * - any time a BO is used in a "one-off" operation (e.g., blit, index buffer, indirect buffer)
+ * - any time a descriptor is bound
+ * - any time a descriptor is unbound (IFF: usage previously existed)
+ * - for all bound descriptors on the first draw/dispatch after a flush (zink_update_descriptor_refs)
+ *
+ * usage is removed:
+ * - when tracking is removed (IFF: BO usage == tracking, i.e., this is the last batch that a BO was active on)
+ */
 struct zink_batch_usage {
    uint32_t usage;
    cnd_t flush;