freedreno/registers: Add some docs for PM4 events.

Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/19733>

diff --git a/src/freedreno/registers/adreno/adreno_pm4.xml b/src/freedreno/registers/adreno/adreno_pm4.xml
index e59a841..7557127 100644 (file)
--- a/src/freedreno/registers/adreno/adreno_pm4.xml
+++ b/src/freedreno/registers/adreno/adreno_pm4.xml
@@ -8,6 +8,10 @@ xsi:schemaLocation="http://nouveau.freedesktop.org/ rules-ng.xsd">
        <value name="PS_DEALLOC" value="1"/>
        <value name="VS_DONE_TS" value="2"/>
        <value name="PS_DONE_TS" value="3"/>
+       <doc>
+               Flushes dirty data from UCHE, and also writes a GPU timestamp to
+               the address if one is provided.
+       </doc>
        <value name="CACHE_FLUSH_TS" value="4"/>
        <value name="CONTEXT_DONE" value="5"/>
        <value name="CACHE_FLUSH" value="6" variants="A2XX-A4XX"/>
@@ -24,9 +28,20 @@ xsi:schemaLocation="http://nouveau.freedesktop.org/ rules-ng.xsd">
        <value name="TILE_FLUSH" value="15" variants="A2XX-A4XX"/>
        <value name="STAT_EVENT" value="16" variants="A2XX-A4XX"/>
        <value name="CACHE_FLUSH_AND_INV_TS_EVENT" value="20" variants="A2XX-A4XX"/>
+       <doc>
+               If A6XX_RB_SAMPLE_COUNT_CONTROL.copy is true, writes OQ Z passed
+               sample counts to RB_SAMPLE_COUNT_ADDR.  This writes to main
+               memory, skipping UCHE.
+       </doc>
        <value name="ZPASS_DONE" value="21"/>
        <value name="CACHE_FLUSH_AND_INV_EVENT" value="22" variants="A2XX"/>
+
+       <doc>
+               Writes the GPU timestamp to the address that follows, once RB
+               access and flushes are complete.
+       </doc>
        <value name="RB_DONE_TS" value="22" variants="A3XX-"/>
+
        <value name="PERFCOUNTER_START" value="23" variants="A2XX-A4XX"/>
        <value name="PERFCOUNTER_STOP" value="24" variants="A2XX-A4XX"/>
        <value name="VS_FETCH_DONE" value="27"/>
@@ -42,12 +57,44 @@ xsi:schemaLocation="http://nouveau.freedesktop.org/ rules-ng.xsd">
        <value name="FLUSH_SO_1" value="18" variants="A5XX-"/>
        <value name="FLUSH_SO_2" value="19" variants="A5XX-"/>
        <value name="FLUSH_SO_3" value="20" variants="A5XX-"/>
+
+       <doc>
+               Invalidates depth attachment data from the CCU.  We assume this
+               happens in the last stage.
+       </doc>
        <value name="PC_CCU_INVALIDATE_DEPTH" value="24" variants="A5XX-"/>
+
+       <doc>
+               Invalidates color attachment data from the CCU.  We assume this
+               happens in the last stage.
+       </doc>
        <value name="PC_CCU_INVALIDATE_COLOR" value="25" variants="A5XX-"/>
+
+       <doc>
+               Flushes the small cache used by CP_EVENT_WRITE::BLIT (which,
+               along with its registers, would be better named RESOLVE).
+       </doc>
        <value name="PC_CCU_RESOLVE_TS" value="26" variants="A6XX"/>
+
+       <doc>
+               Flushes depth attachment data from the CCU.  We assume this
+               happens in the last stage.
+       </doc>
        <value name="PC_CCU_FLUSH_DEPTH_TS" value="28" variants="A5XX-"/>
+
+       <doc>
+               Flushes color attachment data from the CCU.  We assume this
+               happens in the last stage.
+       </doc>
        <value name="PC_CCU_FLUSH_COLOR_TS" value="29" variants="A5XX-"/>
+
+       <doc>
+               2D blit to resolve GMEM to system memory (skipping CCU) at the
+               end of a render pass.  Compare to CP_BLIT's BLIT_OP_SCALE for
+               more general blitting.
+       </doc>
        <value name="BLIT" value="30" variants="A5XX-"/>
+
        <doc>
                Clears based on GRAS_LRZ_CNTL configuration, could clear
                fast-clear buffer or LRZ direction.
@@ -60,6 +107,7 @@ xsi:schemaLocation="http://nouveau.freedesktop.org/ rules-ng.xsd">
                Clear of direction means setting the direction to CUR_DIR_UNSET.
        </doc>
        <value name="LRZ_CLEAR" value="37" variants="A5XX-"/>
+
        <value name="LRZ_FLUSH" value="38" variants="A5XX-"/>
        <value name="BLIT_OP_FILL_2D" value="39" variants="A5XX-"/>
        <value name="BLIT_OP_COPY_2D" value="40" variants="A5XX-"/>
@@ -69,7 +117,11 @@ xsi:schemaLocation="http://nouveau.freedesktop.org/ rules-ng.xsd">
        <value name="UNK_2D" value="45" variants="A5XX-"/>
 
        <!-- a6xx events -->
+       <doc>
+               Invalidates UCHE.
+       </doc>
        <value name="CACHE_INVALIDATE" value="49" variants="A6XX"/>
+
        <value name="LABEL" value="63" variants="A6XX-"/>
 
        <!-- note, some of these are the same as a6xx, just named differently -->
@@ -205,7 +257,10 @@ xsi:schemaLocation="http://nouveau.freedesktop.org/ rules-ng.xsd">
        <value name="CP_INDIRECT_BUFFER_CHAIN" value="0x57" variants="A5XX-"/>
        <doc>indirect buffer dispatch.  same as IB, but init is pipelined</doc>
        <value name="CP_INDIRECT_BUFFER_PFD" value="0x37"/>
-       <doc>wait for the IDLE state of the engine</doc>
+       <doc>
+               Waits for the IDLE state of the engine before further drawing.
+               This is pipelined, so the CP may continue.
+       </doc>
        <value name="CP_WAIT_FOR_IDLE" value="0x26"/>
        <doc>wait until a register or memory location is a specific value</doc>
        <value name="CP_WAIT_REG_MEM" value="0x3c"/>
@@ -435,6 +490,12 @@ xsi:schemaLocation="http://nouveau.freedesktop.org/ rules-ng.xsd">
        <value name="CP_COMPUTE_CHECKPOINT" value="0x6e" variants="A5XX"/>
        <!-- check if this works on earlier.. -->
        <value name="CP_MEM_TO_MEM" value="0x73" variants="A5XX-"/>
+
+       <doc>
+               General purpose 2D blit engine for image transfers and mipmap
+               generation.  Reads through UCHE, writes through the CCU cache in
+               the PS stage.
+       </doc>
        <value name="CP_BLIT" value="0x2c" variants="A5XX-"/>
 
        <!-- Test specified bit in specified register and set predicate -->