drm/amdgpu: Add documentation associated with CSB

Add a description for the get_csb_buffer callback, update the glossary,
and add some extra information about RB, which is associated with CSB
configuration.

Signed-off-by: Rodrigo Siqueira <siqueira@igalia.com>
Signed-off-by: Alex Deucher <alexander.deucher@amd.com>

diff --git a/Documentation/gpu/amdgpu/amdgpu-glossary.rst b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
index 080c3f2250d1814436650be14cd4463247c0c9c7..8e6af7cc76c28c392d14facf4e5c1cc4446299c1 100644 (file)
--- a/Documentation/gpu/amdgpu/amdgpu-glossary.rst
+++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
@@ -33,6 +33,9 @@ we have a dedicated glossary for Display Core at
     CS
       Command Submission
 
+    CSB
+      Clear State Indirect Buffer
+
     CU
       Compute Unit
 
@@ -134,6 +137,9 @@ we have a dedicated glossary for Display Core at
     PSP
         Platform Security Processor
 
+    RB
+      Render Backends. Some people called it ROPs.
+
     RLC
       RunList Controller. This name is a remnant of past ages and doesn't have
       much meaning today. It's a group of general-purpose helper engines for

diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_gfx.h b/drivers/gpu/drm/amd/amdgpu/amdgpu_gfx.h
index 9187b0b3bff6b3267e26031a541bda1796e5c506..08f268dab8f517de09f975534b2d83ec6245b05d 100644 (file)
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_gfx.h
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_gfx.h
@@ -170,10 +170,46 @@ struct amdgpu_kiq {
 #define AMDGPU_GFX_MAX_SE 4
 #define AMDGPU_GFX_MAX_SH_PER_SE 2
 
+/**
+ * amdgpu_rb_config - Configure a single Render Backend (RB)
+ *
+ * Bad RBs are fused off and there is a harvest register the driver reads to
+ * determine which RB(s) are fused off so that the driver can configure the
+ * hardware state so that nothing gets sent to them. There are also user
+ * harvest registers that the driver can program to disable additional RBs,
+ * etc., for testing purposes.
+ */
 struct amdgpu_rb_config {
+       /**
+        * @rb_backend_disable:
+        *
+        * The value captured from register RB_BACKEND_DISABLE indicates if the
+        * RB backend is disabled or not.
+        */
        uint32_t rb_backend_disable;
+
+       /**
+        * @user_rb_backend_disable:
+        *
+        * The value captured from register USER_RB_BACKEND_DISABLE indicates
+        * if the User RB backend is disabled or not.
+        */
        uint32_t user_rb_backend_disable;
+
+       /**
+        * @raster_config:
+        *
+        * To set up all of the states, it is necessary to have two registers
+        * to keep all of the states. This field holds the first register.
+        */
        uint32_t raster_config;
+
+       /**
+        * @raster_config_1:
+        *
+        * To set up all of the states, it is necessary to have two registers
+        * to keep all of the states. This field holds the second register.
+        */
        uint32_t raster_config_1;
 };
 
@@ -221,6 +257,13 @@ struct amdgpu_gfx_config {
        uint32_t macrotile_mode_array[16];
 
        struct gb_addr_config gb_addr_config_fields;
+
+       /**
+        * @rb_config:
+        *
+        * Matrix that keeps all the Render Backend (color and depth buffer
+        * handling) configuration on the 3D engine.
+        */
        struct amdgpu_rb_config rb_config[AMDGPU_GFX_MAX_SE][AMDGPU_GFX_MAX_SH_PER_SE];
 
        /* gfx configure feature */

diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_rlc.h b/drivers/gpu/drm/amd/amdgpu/amdgpu_rlc.h
index fce22d3f816b2409564fb2466f70ea057564ab8a..c210625be220005d99ff479da35b6931412db418 100644 (file)
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_rlc.h
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_rlc.h
@@ -237,6 +237,20 @@ struct amdgpu_rlc_funcs {
        void (*unset_safe_mode)(struct amdgpu_device *adev, int xcc_id);
        int  (*init)(struct amdgpu_device *adev);
        u32  (*get_csb_size)(struct amdgpu_device *adev);
+
+       /**
+        * @get_csb_buffer: Get the clear state to be put into the hardware.
+        *
+        * The parameter adev is used to get the CS data and other gfx info,
+        * and buffer is the RLC CS pointer
+        *
+        * Sometimes, the user space puts a request to clear the state in the
+        * command buffer; this function provides the clear state that gets put
+        * into the hardware. Note that the driver programs Clear State
+        * Indirect Buffer (CSB) explicitly when it sets up the kernel rings,
+        * and it also provides a pointer to it which is used by the firmware
+        * to load the clear state in some cases.
+        */
        void (*get_csb_buffer)(struct amdgpu_device *adev, volatile u32 *buffer);
        int  (*get_cp_table_num)(struct amdgpu_device *adev);
        int  (*resume)(struct amdgpu_device *adev);