Mesa (main): docs: explain state emission in Anv

[GitLab Mirror]

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

Author: Lionel Landwerlin <lionel.g.landwerlin at intel.com>
Date:   Sat Apr 30 00:16:20 2022 +0300

docs: explain state emission in Anv

Signed-off-by: Lionel Landwerlin <lionel.g.landwerlin at intel.com>
Reviewed-by: Tapani Pälli <tapani.palli at intel.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/16220>

---

 docs/drivers/anv.rst | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/drivers/anv.rst b/docs/drivers/anv.rst
index f808cc4d62e..84189964ed9 100644
--- a/docs/drivers/anv.rst
+++ b/docs/drivers/anv.rst
@@ -230,3 +230,45 @@ is a byte offset from the descriptor set memory to the associated
 binding. ``anv_descriptor_set_binding_layout::array_size`` is the
 number of ``anv_*_descriptor`` elements in the descriptor set memory
 from that offset for the binding.
+
+
+Pipeline state emission
+-----------------------
+
+Vulkan initially started by baking as much state as possible in
+pipelines. But extension after extension, more and more state has
+become potentially dynamic.
+
+Anv tries to limit the amount of time an instruction has to be packed
+to reprogram part of the 3D pipeline state. The packing is happening
+in 2 places :
+
+- ``genX_pipeline.c`` where the non dynamic state is emitted in the
+  pipeline batch. This batch is copied into the command buffer batch
+  when calling ``vkCmdBindPipeline()``
+
+- ``genX_cmd_buffer.c`` in the ``cmd_buffer_flush_state`` function
+  which ends up calling into ``gfx8_cmd_buffer.c`` &
+  ``gfx7_cmd_buffer.c``
+
+The rule to know where to emit an instruction programming the 3D
+pipeline is as follow :
+
+- If any field of the instruction can be made dynamic, it should be
+  emitted in ``genX_cmd_buffer.c``, ``gfx8_cmd_buffer.c`` or
+  ``gfx7_cmd_buffer.c``
+
+- Otherwise, the instruction can be emitted in ``genX_pipeline.c``
+
+When a piece of state programming is dynamic, it should have a
+corresponding field in ``anv_dynamic_state`` and the
+``anv_dynamic_state_copy()`` function should be updated to ensure we
+minimize the amount of time an instruction should be emitted. Each
+instruction should have a associated ``ANV_CMD_DIRTY_*`` mask so that
+the dynamic emission code can tell when to re-emit an instruction.
+
+An instruction can also be re-emitted when a pipeline changes by
+checking for ``ANV_CMD_DIRTY_PIPELINE``. It should only do so if it
+requires to know some value that is coming from the
+``anv_graphics_pipeline`` object that is not available from
+``anv_dynamic_state``.