1ANV
2===
3
4Debugging
5---------
6
7Here are a few environment variable debug environment variables
8specific to Anv:
9
10:envvar:`ANV_ENABLE_PIPELINE_CACHE`
11   If defined to ``0`` or ``false``, this will disable pipeline
12   caching, forcing Anv to reparse and recompile any VkShaderModule
13   (SPIRV) it is given.
14:envvar:`ANV_DISABLE_SECONDARY_CMD_BUFFER_CALLS`
15   If defined to ``1`` or ``true``, this will prevent usage of self
16   modifying command buffers to implement ``vkCmdExecuteCommands``. As
17   a result of this, it will also disable ``VK_KHR_performance_query``.
18:envvar:`ANV_ALWAYS_BINDLESS`
19   If defined to ``1`` or ``true``, this forces all descriptor sets to
20   use the internal `Bindless model`_.
21:envvar:`ANV_QUEUE_THREAD_DISABLE`
22   If defined to ``1`` or ``true``, this disables support for timeline
23   semaphores.
24:envvar:`ANV_USERSPACE_RELOCS`
25   If defined to ``1`` or ``true``, this forces Anv to always do
26   kernel relocations in command buffers. This should only have an
27   effect on hardware that doesn't support soft-pinning (Ivybridge,
28   Haswell, Cherryview).
29:envvar:`ANV_PRIMITIVE_REPLICATION_MAX_VIEWS`
30   Specifies up to how many view shaders can be lowered to handle
31   VK_KHR_multiview. Beyond this number, multiview is implemented
32   using instanced rendering. If unspecified, the value default to
33   ``2``.
34
35
36Experimental features
37---------------------
38
39:envvar:`ANV_EXPERIMENTAL_NV_MESH_SHADER`
40   If defined to ``1`` or ``true``, this advertise support for
41   VK_NV_mesh_shader extension for platforms that have hardware
42   support for it.
43
44
45.. _`Bindless model`:
46
47Binding Model
48-------------
49
50Here is the Anv bindless binding model that was implemented for the
51descriptor indexing feature of Vulkan 1.2 :
52
53.. graphviz::
54
55  digraph G {
56    fontcolor="black";
57    compound=true;
58
59    subgraph cluster_1 {
60      label = "Binding Table (HW)";
61
62      bgcolor="cornflowerblue";
63
64      node [ style=filled,shape="record",fillcolor="white",
65             label="RT0"    ] n0;
66      node [ label="RT1"    ] n1;
67      node [ label="dynbuf0"] n2;
68      node [ label="set0"   ] n3;
69      node [ label="set1"   ] n4;
70      node [ label="set2"   ] n5;
71
72      n0 -> n1 -> n2 -> n3 -> n4 -> n5 [style=invis];
73    }
74    subgraph cluster_2 {
75      label = "Descriptor Set 0";
76
77      bgcolor="burlywood3";
78      fixedsize = true;
79
80      node [ style=filled,shape="record",fillcolor="white", fixedsize = true, width=4,
81             label="binding 0 - STORAGE_IMAGE\n anv_storage_image_descriptor"          ] n8;
82      node [ label="binding 1 - COMBINED_IMAGE_SAMPLER\n anv_sampled_image_descriptor" ] n9;
83      node [ label="binding 2 - UNIFORM_BUFFER\n anv_address_range_descriptor"         ] n10;
84      node [ label="binding 3 - UNIFORM_TEXEL_BUFFER\n anv_storage_image_descriptor"   ] n11;
85
86      n8 -> n9 -> n10 -> n11 [style=invis];
87    }
88    subgraph cluster_5 {
89      label = "Vulkan Objects"
90
91      fontcolor="black";
92      bgcolor="darkolivegreen4";
93
94      subgraph cluster_6 {
95        label = "VkImageView";
96
97        bgcolor=darkolivegreen3;
98        node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
99               label="surface_state" ] n12;
100      }
101      subgraph cluster_7 {
102        label = "VkSampler";
103
104        bgcolor=darkolivegreen3;
105        node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
106               label="sample_state" ] n13;
107      }
108      subgraph cluster_8 {
109        label = "VkImageView";
110        bgcolor="darkolivegreen3";
111
112        node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
113               label="surface_state" ] n14;
114      }
115      subgraph cluster_9 {
116        label = "VkBuffer";
117        bgcolor=darkolivegreen3;
118
119        node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
120               label="address" ] n15;
121      }
122      subgraph cluster_10 {
123        label = "VkBufferView";
124
125        bgcolor=darkolivegreen3;
126        node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
127               label="surface_state" ] n16;
128      }
129
130      n12 -> n13 -> n14 -> n15 -> n16 [style=invis];
131    }
132
133    subgraph cluster_11 {
134      subgraph cluster_12 {
135        label = "CommandBuffer state stream";
136
137        bgcolor="gold3";
138        node [ style=filled,shape="box",fillcolor="white", fixedsize = true, width=2,
139               label="surface_state" ] n17;
140        node [ label="surface_state" ] n18;
141        node [ label="surface_state" ] n19;
142
143        n17 -> n18 -> n19 [style=invis];
144      }
145    }
146
147    n3  -> n8 [lhead=cluster_2];
148
149    n8  -> n12;
150    n9  -> n13;
151    n9  -> n14;
152    n10 -> n15;
153    n11 -> n16;
154
155    n0 -> n17;
156    n1 -> n18;
157    n2 -> n19;
158  }
159
160
161
162The HW binding table is generated when the draw or dispatch commands
163are emitted. Here are the types of entries one can find in the binding
164table :
165
166- The currently bound descriptor sets, one entry per descriptor set
167  (our limit is 8).
168
169- For dynamic buffers, one entry per dynamic buffer.
170
171- For draw commands, render target entries if needed.
172
173The entries of the HW binding table for descriptor sets are
174RENDER_SURFACE_STATE similar to what you would have for a normal
175uniform buffer. The shader will emit reads this buffer first to get
176the information it needs to access a surface/sampler/etc... and then
177emits the appropriate message using the information gathered from the
178descriptor set buffer.
179
180Each binding type entry gets an associated structure in memory
181(``anv_storage_image_descriptor``, ``anv_sampled_image_descriptor``,
182``anv_address_range_descriptor``, ``anv_storage_image_descriptor``).
183This is the information read by the shader.
184
185
186.. _`Descriptor Set Memory Layout`:
187
188Descriptor Set Memory Layout
189----------------------------
190
191Here is a representation of how the descriptor set bindings, with each
192elements in each binding is mapped to a the descriptor set memory :
193
194.. graphviz::
195
196  digraph structs {
197    node [shape=record];
198    rankdir=LR;
199
200    struct1 [label="Descriptor Set | \
201                    <b0> binding 0\n STORAGE_IMAGE \n (array_length=3) | \
202                    <b1> binding 1\n COMBINED_IMAGE_SAMPLER \n (array_length=2) | \
203                    <b2> binding 2\n UNIFORM_BUFFER \n (array_length=1) | \
204                    <b3> binding 3\n UNIFORM_TEXEL_BUFFER \n (array_length=1)"];
205    struct2 [label="Descriptor Set Memory | \
206                    <b0e0> anv_storage_image_descriptor|\
207                    <b0e1> anv_storage_image_descriptor|\
208                    <b0e2> anv_storage_image_descriptor|\
209                    <b1e0> anv_sampled_image_descriptor|\
210                    <b1e1> anv_sampled_image_descriptor|\
211                    <b2e0> anv_address_range_descriptor|\
212                    <b3e0> anv_storage_image_descriptor"];
213
214    struct1:b0 -> struct2:b0e0;
215    struct1:b0 -> struct2:b0e1;
216    struct1:b0 -> struct2:b0e2;
217    struct1:b1 -> struct2:b1e0;
218    struct1:b1 -> struct2:b1e1;
219    struct1:b2 -> struct2:b2e0;
220    struct1:b3 -> struct2:b3e0;
221  }
222
223Each Binding in the descriptor set is allocated an array of
224``anv_*_descriptor`` data structure. The type of ``anv_*_descriptor``
225used for a binding is selected based on the ``VkDescriptorType`` of
226the bindings.
227
228The value of ``anv_descriptor_set_binding_layout::descriptor_offset``
229is a byte offset from the descriptor set memory to the associated
230binding. ``anv_descriptor_set_binding_layout::array_size`` is the
231number of ``anv_*_descriptor`` elements in the descriptor set memory
232from that offset for the binding.
233