* [PATCH 1/8] Documentation/gpu: Add basic page for HUBP
2023-10-20 22:05 [PATCH 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
@ 2023-10-20 22:05 ` Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 2/8] Documentation/gpu: Add simple doc page for DCHUBBUB Rodrigo Siqueira
` (6 subsequent siblings)
7 siblings, 0 replies; 10+ messages in thread
From: Rodrigo Siqueira @ 2023-10-20 22:05 UTC (permalink / raw)
To: amd-gfx, linux-doc
Cc: Rodrigo Siqueira, Mario Limonciello, Alex Deucher, Harry Wentland,
Hamza Mahfooz
Create the HUBP documentation page and add the doc references to extract
the HUBP code documentation.
Cc: Mario Limonciello <mario.limonciello@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Harry Wentland <Harry.Wentland@amd.com>
Cc: Hamza Mahfooz <hamza.mahfooz@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
.../gpu/amdgpu/display/dcn-blocks.rst | 18 ++++++++++++++++++
Documentation/gpu/amdgpu/display/index.rst | 1 +
drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h | 13 ++++++++++++-
3 files changed, 31 insertions(+), 1 deletion(-)
create mode 100644 Documentation/gpu/amdgpu/display/dcn-blocks.rst
diff --git a/Documentation/gpu/amdgpu/display/dcn-blocks.rst b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
new file mode 100644
index 000000000000..5da34d5b73d8
--- /dev/null
+++ b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
@@ -0,0 +1,18 @@
+==========
+DCN Blocks
+==========
+
+In this section, you will find some extra details about some of the DCN blocks
+and the code documentation when it is automatically generated.
+
+HUBP
+----
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+ :doc: overview
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+ :export:
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+ :internal:
diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst
index f8a4f53d70d8..b09d1434754d 100644
--- a/Documentation/gpu/amdgpu/display/index.rst
+++ b/Documentation/gpu/amdgpu/display/index.rst
@@ -28,5 +28,6 @@ table of content:
display-manager.rst
dc-debug.rst
dcn-overview.rst
+ dcn-blocks.rst
mpo-overview.rst
dc-glossary.rst
diff --git a/drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h b/drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
index 7f3f9b69e903..dedc5370023e 100644
--- a/drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+++ b/drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
@@ -26,13 +26,24 @@
#ifndef __DAL_HUBP_H__
#define __DAL_HUBP_H__
+/**
+ * DOC: overview
+ *
+ * Display Controller Hub (DCHUB) is the gateway between the Scalable Data Port
+ * (SDP) and DCN. This component has multiple features, such as memory
+ * arbitration, rotation, and cursor manipulation.
+ *
+ * There is one HUBP allocated per pipe, which fetches data and converts
+ * different pixel formats (i.e. ARGB8888, NV12, etc) into linear, interleaved
+ * and fixed-depth streams of pixel data.
+ */
+
#include "mem_input.h"
#include "cursor_reg_cache.h"
#define OPP_ID_INVALID 0xf
#define MAX_TTU 0xffffff
-
enum cursor_pitch {
CURSOR_PITCH_64_PIXELS = 0,
CURSOR_PITCH_128_PIXELS,
--
2.42.0
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH 2/8] Documentation/gpu: Add simple doc page for DCHUBBUB
2023-10-20 22:05 [PATCH 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 1/8] Documentation/gpu: Add basic page for HUBP Rodrigo Siqueira
@ 2023-10-20 22:05 ` Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 3/8] Documentation/gpu: Add kernel doc entry for DPP Rodrigo Siqueira
` (5 subsequent siblings)
7 siblings, 0 replies; 10+ messages in thread
From: Rodrigo Siqueira @ 2023-10-20 22:05 UTC (permalink / raw)
To: amd-gfx, linux-doc
Cc: Rodrigo Siqueira, Mario Limonciello, Alex Deucher, Harry Wentland,
Hamza Mahfooz
Enable the documentation to extract code documentation from dchubbub.h
file.
Cc: Mario Limonciello <mario.limonciello@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Harry Wentland <Harry.Wentland@amd.com>
Cc: Hamza Mahfooz <hamza.mahfooz@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
Documentation/gpu/amdgpu/display/dcn-blocks.rst | 12 ++++++++++++
drivers/gpu/drm/amd/display/dc/inc/hw/dchubbub.h | 6 ++++++
2 files changed, 18 insertions(+)
diff --git a/Documentation/gpu/amdgpu/display/dcn-blocks.rst b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
index 5da34d5b73d8..e4e0a4ddca4e 100644
--- a/Documentation/gpu/amdgpu/display/dcn-blocks.rst
+++ b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
@@ -5,6 +5,18 @@ DCN Blocks
In this section, you will find some extra details about some of the DCN blocks
and the code documentation when it is automatically generated.
+DCHUBBUB
+--------
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+ :doc: overview
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+ :export:
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+ :internal:
+
HUBP
----
diff --git a/drivers/gpu/drm/amd/display/dc/inc/hw/dchubbub.h b/drivers/gpu/drm/amd/display/dc/inc/hw/dchubbub.h
index cea05843990c..580a9f3f07c0 100644
--- a/drivers/gpu/drm/amd/display/dc/inc/hw/dchubbub.h
+++ b/drivers/gpu/drm/amd/display/dc/inc/hw/dchubbub.h
@@ -26,6 +26,12 @@
#ifndef __DAL_DCHUBBUB_H__
#define __DAL_DCHUBBUB_H__
+/**
+ * DOC: overview
+ *
+ * There is only one common DCHUBBUB. It contains the common request and return
+ * blocks for the Data Fabric Interface that are not clock/power gated.
+ */
enum dcc_control {
dcc_control__256_256_xxx,
--
2.42.0
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH 3/8] Documentation/gpu: Add kernel doc entry for DPP
2023-10-20 22:05 [PATCH 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 1/8] Documentation/gpu: Add basic page for HUBP Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 2/8] Documentation/gpu: Add simple doc page for DCHUBBUB Rodrigo Siqueira
@ 2023-10-20 22:05 ` Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 4/8] Documentation/gpu: Add kernel doc entry for MPC Rodrigo Siqueira
` (4 subsequent siblings)
7 siblings, 0 replies; 10+ messages in thread
From: Rodrigo Siqueira @ 2023-10-20 22:05 UTC (permalink / raw)
To: amd-gfx, linux-doc
Cc: Rodrigo Siqueira, Mario Limonciello, Alex Deucher, Harry Wentland,
Hamza Mahfooz
This commit introduces basic DPP information and the struct scan for
code documentation.
Cc: Mario Limonciello <mario.limonciello@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Harry Wentland <Harry.Wentland@amd.com>
Cc: Hamza Mahfooz <hamza.mahfooz@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
.../gpu/amdgpu/display/dcn-blocks.rst | 12 +++++++++
drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h | 26 +++++++++++++++++++
2 files changed, 38 insertions(+)
diff --git a/Documentation/gpu/amdgpu/display/dcn-blocks.rst b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
index e4e0a4ddca4e..83fc4a03113e 100644
--- a/Documentation/gpu/amdgpu/display/dcn-blocks.rst
+++ b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
@@ -28,3 +28,15 @@ HUBP
.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
:internal:
+
+DPP
+---
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+ :doc: overview
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+ :export:
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
+ :internal:
diff --git a/drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h b/drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h
index f4aa76e02518..2c40e253b14e 100644
--- a/drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h
+++ b/drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h
@@ -27,6 +27,32 @@
#ifndef __DAL_DPP_H__
#define __DAL_DPP_H__
+/**
+ * DOC: overview
+ *
+ * The DPP (Display Pipe and Plane) block is the unified display data
+ * processing engine in DCN for processing graphic or video data on per DPP
+ * rectangle base. This rectangle can be a part of SLS (Single Large Surface),
+ * or a layer to be blended with other DPP, or a rectangle associated with a
+ * display tile.
+ *
+ * It provides various functions including:
+ * - graphic color keyer
+ * - graphic cursor compositing
+ * - graphic or video image source to destination scaling
+ * - image sharping
+ * - video format conversion from 4:2:0 or 4:2:2 to 4:4:4
+ * - Color Space Conversion
+ * - Host LUT gamma adjustment
+ * - Color Gamut Remap
+ * - brightness and contrast adjustment.
+ *
+ * DPP pipe consists of Converter and Cursor (CNVC), Scaler (DSCL), Color
+ * Management (CM), Output Buffer (OBUF) and Digital Bypass (DPB) module
+ * connected in a video/graphics pipeline.
+ */
+
+
#include "transform.h"
#include "cursor_reg_cache.h"
--
2.42.0
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH 4/8] Documentation/gpu: Add kernel doc entry for MPC
2023-10-20 22:05 [PATCH 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (2 preceding siblings ...)
2023-10-20 22:05 ` [PATCH 3/8] Documentation/gpu: Add kernel doc entry for DPP Rodrigo Siqueira
@ 2023-10-20 22:05 ` Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 5/8] Documentation/gpu: Add entry for OPP in the kernel doc Rodrigo Siqueira
` (3 subsequent siblings)
7 siblings, 0 replies; 10+ messages in thread
From: Rodrigo Siqueira @ 2023-10-20 22:05 UTC (permalink / raw)
To: amd-gfx, linux-doc
Cc: Rodrigo Siqueira, Mario Limonciello, Alex Deucher, Harry Wentland,
Hamza Mahfooz
This commit adds a kernel-doc entry for the MPC block. Since it enabled
the kernel-doc to parse some of the documentation in the mpc.h file,
fixing some of the comments was required.
Cc: Mario Limonciello <mario.limonciello@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Harry Wentland <Harry.Wentland@amd.com>
Cc: Hamza Mahfooz <hamza.mahfooz@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
.../gpu/amdgpu/display/dcn-blocks.rst | 12 +
drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h | 248 ++++++++++++------
2 files changed, 184 insertions(+), 76 deletions(-)
diff --git a/Documentation/gpu/amdgpu/display/dcn-blocks.rst b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
index 83fc4a03113e..1a223f33202e 100644
--- a/Documentation/gpu/amdgpu/display/dcn-blocks.rst
+++ b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
@@ -40,3 +40,15 @@ DPP
.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h
:internal:
+
+MPC
+---
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
+ :doc: overview
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
+ :export:
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
+ :internal:
diff --git a/drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h b/drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
index 61a2406dcc53..ae336c066f13 100644
--- a/drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
+++ b/drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
@@ -23,13 +23,28 @@
*/
/**
- * DOC: mpc-overview
+ * DOC: overview
*
* Multiple Pipe/Plane Combined (MPC) is a component in the hardware pipeline
* that performs blending of multiple planes, using global and per-pixel alpha.
* It also performs post-blending color correction operations according to the
* hardware capabilities, such as color transformation matrix and gamma 1D and
* 3D LUT.
+ *
+ * MPC receives output from all DPP pipes and combines them to multiple outputs
+ * supporting "M MPC inputs -> N MPC outputs" flexible composition
+ * architecture. It features:
+ *
+ * - Programmable blending structure to allow software controlled blending and
+ * cascading;
+ * - Programmable window location of each DPP in active region of display;
+ * - Combining multiple DPP pipes in one active region when a single DPP pipe
+ * cannot process very large surface;
+ * - Combining multiple DPP from different SLS with blending;
+ * - Stereo formats from single DPP in top-bottom or side-by-side modes;
+ * - Stereo formats from 2 DPPs;
+ * - Alpha blending of multiple layers from different DPP pipes;
+ * - Programmable background color;
*/
#ifndef __DC_MPCC_H__
@@ -83,34 +98,66 @@ enum mpcc_alpha_blend_mode {
/**
* struct mpcc_blnd_cfg - MPCC blending configuration
- *
- * @black_color: background color
- * @alpha_mode: alpha blend mode (MPCC_ALPHA_BLND_MODE)
- * @pre_multiplied_alpha: whether pixel color values were pre-multiplied by the
- * alpha channel (MPCC_ALPHA_MULTIPLIED_MODE)
- * @global_gain: used when blend mode considers both pixel alpha and plane
- * alpha value and assumes the global alpha value.
- * @global_alpha: plane alpha value
- * @overlap_only: whether overlapping of different planes is allowed
- * @bottom_gain_mode: blend mode for bottom gain setting
- * @background_color_bpc: background color for bpc
- * @top_gain: top gain setting
- * @bottom_inside_gain: blend mode for bottom inside
- * @bottom_outside_gain: blend mode for bottom outside
*/
struct mpcc_blnd_cfg {
- struct tg_color black_color; /* background color */
- enum mpcc_alpha_blend_mode alpha_mode; /* alpha blend mode */
- bool pre_multiplied_alpha; /* alpha pre-multiplied mode flag */
+ /**
+ * @black_color: background color.
+ */
+ struct tg_color black_color;
+
+ /**
+ * @alpha_mode: alpha blend mode (MPCC_ALPHA_BLND_MODE).
+ */
+ enum mpcc_alpha_blend_mode alpha_mode;
+
+ /***
+ * @@pre_multiplied_alpha:
+ *
+ * Whether pixel color values were pre-multiplied by the alpha channel
+ * (MPCC_ALPHA_MULTIPLIED_MODE).
+ */
+ bool pre_multiplied_alpha;
+
+ /**
+ * @global_gain: Used when blend mode considers both pixel alpha and plane.
+ */
int global_gain;
+
+ /**
+ * @global_alpha: Plane alpha value.
+ */
int global_alpha;
+
+ /**
+ * @@overlap_only: Whether overlapping of different planes is allowed.
+ */
bool overlap_only;
/* MPCC top/bottom gain settings */
+
+ /**
+ * @bottom_gain_mode: Blend mode for bottom gain setting.
+ */
int bottom_gain_mode;
+
+ /**
+ * @background_color_bpc: Background color for bpc.
+ */
int background_color_bpc;
+
+ /**
+ * @top_gain: Top gain setting.
+ */
int top_gain;
+
+ /**
+ * @bottom_inside_gain: Blend mode for bottom inside.
+ */
int bottom_inside_gain;
+
+ /**
+ * @bottom_outside_gain: Blend mode for bottom outside.
+ */
int bottom_outside_gain;
};
@@ -150,34 +197,58 @@ struct mpc_dwb_flow_control {
/**
* struct mpcc - MPCC connection and blending configuration for a single MPCC instance.
- * @mpcc_id: MPCC physical instance
- * @dpp_id: DPP input to this MPCC
- * @mpcc_bot: pointer to bottom layer MPCC. NULL when not connected.
- * @blnd_cfg: the blending configuration for this MPCC
- * @sm_cfg: stereo mix setting for this MPCC
- * @shared_bottom: if MPCC output to both OPP and DWB endpoints, true. Otherwise, false.
*
* This struct is used as a node in an MPC tree.
*/
struct mpcc {
- int mpcc_id; /* MPCC physical instance */
- int dpp_id; /* DPP input to this MPCC */
- struct mpcc *mpcc_bot; /* pointer to bottom layer MPCC. NULL when not connected */
- struct mpcc_blnd_cfg blnd_cfg; /* The blending configuration for this MPCC */
- struct mpcc_sm_cfg sm_cfg; /* stereo mix setting for this MPCC */
- bool shared_bottom; /* TRUE if MPCC output to both OPP and DWB endpoints, else FALSE */
+ /**
+ * @mpcc_id: MPCC physical instance.
+ */
+ int mpcc_id;
+
+ /**
+ * @dpp_id: DPP input to this MPCC
+ */
+ int dpp_id;
+
+ /**
+ * @mpcc_bot: Pointer to bottom layer MPCC. NULL when not connected.
+ */
+ struct mpcc *mpcc_bot;
+
+ /**
+ * @blnd_cfg: The blending configuration for this MPCC.
+ */
+ struct mpcc_blnd_cfg blnd_cfg;
+
+ /**
+ * @sm_cfg: stereo mix setting for this MPCC
+ */
+ struct mpcc_sm_cfg sm_cfg;
+
+ /**
+ * @shared_bottom:
+ *
+ * If MPCC output to both OPP and DWB endpoints, true. Otherwise, false.
+ */
+ bool shared_bottom;
};
/**
* struct mpc_tree - MPC tree represents all MPCC connections for a pipe.
*
- * @opp_id: the OPP instance that owns this MPC tree
- * @opp_list: the top MPCC layer of the MPC tree that outputs to OPP endpoint
*
*/
struct mpc_tree {
- int opp_id; /* The OPP instance that owns this MPC tree */
- struct mpcc *opp_list; /* The top MPCC layer of the MPC tree that outputs to OPP endpoint */
+ /**
+ * @opp_id: The OPP instance that owns this MPC tree.
+ */
+ int opp_id;
+
+ /**
+ * @opp_list: the top MPCC layer of the MPC tree that outputs to OPP endpoint
+ */
+ struct mpcc *opp_list;
};
struct mpc {
@@ -217,16 +288,20 @@ struct mpc_funcs {
* Only used for planes that are part of blending chain for OPP output
*
* Parameters:
- * [in/out] mpc - MPC context.
- * [in/out] tree - MPC tree structure that plane will be added to.
- * [in] blnd_cfg - MPCC blending configuration for the new blending layer.
- * [in] sm_cfg - MPCC stereo mix configuration for the new blending layer.
- * stereo mix must disable for the very bottom layer of the tree config.
- * [in] insert_above_mpcc - Insert new plane above this MPCC. If NULL, insert as bottom plane.
- * [in] dpp_id - DPP instance for the plane to be added.
- * [in] mpcc_id - The MPCC physical instance to use for blending.
- *
- * Return: struct mpcc* - MPCC that was added.
+ *
+ * - [in/out] mpc - MPC context.
+ * - [in/out] tree - MPC tree structure that plane will be added to.
+ * - [in] blnd_cfg - MPCC blending configuration for the new blending layer.
+ * - [in] sm_cfg - MPCC stereo mix configuration for the new blending layer.
+ * stereo mix must disable for the very bottom layer of the tree config.
+ * - [in] insert_above_mpcc - Insert new plane above this MPCC.
+ * If NULL, insert as bottom plane.
+ * - [in] dpp_id - DPP instance for the plane to be added.
+ * - [in] mpcc_id - The MPCC physical instance to use for blending.
+ *
+ * Return:
+ *
+ * struct mpcc* - MPCC that was added.
*/
struct mpcc* (*insert_plane)(
struct mpc *mpc,
@@ -243,11 +318,14 @@ struct mpc_funcs {
* Remove a specified MPCC from the MPC tree.
*
* Parameters:
- * [in/out] mpc - MPC context.
- * [in/out] tree - MPC tree structure that plane will be removed from.
- * [in/out] mpcc - MPCC to be removed from tree.
*
- * Return: void
+ * - [in/out] mpc - MPC context.
+ * - [in/out] tree - MPC tree structure that plane will be removed from.
+ * - [in/out] mpcc - MPCC to be removed from tree.
+ *
+ * Return:
+ *
+ * void
*/
void (*remove_mpcc)(
struct mpc *mpc,
@@ -260,9 +338,12 @@ struct mpc_funcs {
* Reset the MPCC HW status by disconnecting all muxes.
*
* Parameters:
- * [in/out] mpc - MPC context.
*
- * Return: void
+ * - [in/out] mpc - MPC context.
+ *
+ * Return:
+ *
+ * void
*/
void (*mpc_init)(struct mpc *mpc);
void (*mpc_init_single_inst)(
@@ -275,11 +356,14 @@ struct mpc_funcs {
* Update the blending configuration for a specified MPCC.
*
* Parameters:
- * [in/out] mpc - MPC context.
- * [in] blnd_cfg - MPCC blending configuration.
- * [in] mpcc_id - The MPCC physical instance.
*
- * Return: void
+ * - [in/out] mpc - MPC context.
+ * - [in] blnd_cfg - MPCC blending configuration.
+ * - [in] mpcc_id - The MPCC physical instance.
+ *
+ * Return:
+ *
+ * void
*/
void (*update_blending)(
struct mpc *mpc,
@@ -289,15 +373,18 @@ struct mpc_funcs {
/**
* @cursor_lock:
*
- * Lock cursor updates for the specified OPP.
- * OPP defines the set of MPCC that are locked together for cursor.
+ * Lock cursor updates for the specified OPP. OPP defines the set of
+ * MPCC that are locked together for cursor.
*
* Parameters:
- * [in] mpc - MPC context.
- * [in] opp_id - The OPP to lock cursor updates on
- * [in] lock - lock/unlock the OPP
*
- * Return: void
+ * - [in] mpc - MPC context.
+ * - [in] opp_id - The OPP to lock cursor updates on
+ * - [in] lock - lock/unlock the OPP
+ *
+ * Return:
+ *
+ * void
*/
void (*cursor_lock)(
struct mpc *mpc,
@@ -307,20 +394,25 @@ struct mpc_funcs {
/**
* @insert_plane_to_secondary:
*
- * Add DPP into secondary MPC tree based on specified blending position.
- * Only used for planes that are part of blending chain for DWB output
+ * Add DPP into secondary MPC tree based on specified blending
+ * position. Only used for planes that are part of blending chain for
+ * DWB output
*
* Parameters:
- * [in/out] mpc - MPC context.
- * [in/out] tree - MPC tree structure that plane will be added to.
- * [in] blnd_cfg - MPCC blending configuration for the new blending layer.
- * [in] sm_cfg - MPCC stereo mix configuration for the new blending layer.
- * stereo mix must disable for the very bottom layer of the tree config.
- * [in] insert_above_mpcc - Insert new plane above this MPCC. If NULL, insert as bottom plane.
- * [in] dpp_id - DPP instance for the plane to be added.
- * [in] mpcc_id - The MPCC physical instance to use for blending.
- *
- * Return: struct mpcc* - MPCC that was added.
+ *
+ * - [in/out] mpc - MPC context.
+ * - [in/out] tree - MPC tree structure that plane will be added to.
+ * - [in] blnd_cfg - MPCC blending configuration for the new blending layer.
+ * - [in] sm_cfg - MPCC stereo mix configuration for the new blending layer.
+ * stereo mix must disable for the very bottom layer of the tree config.
+ * - [in] insert_above_mpcc - Insert new plane above this MPCC. If
+ * NULL, insert as bottom plane.
+ * - [in] dpp_id - DPP instance for the plane to be added.
+ * - [in] mpcc_id - The MPCC physical instance to use for blending.
+ *
+ * Return:
+ *
+ * struct mpcc* - MPCC that was added.
*/
struct mpcc* (*insert_plane_to_secondary)(
struct mpc *mpc,
@@ -337,10 +429,14 @@ struct mpc_funcs {
* Remove a specified DPP from the 'secondary' MPC tree.
*
* Parameters:
- * [in/out] mpc - MPC context.
- * [in/out] tree - MPC tree structure that plane will be removed from.
- * [in] mpcc - MPCC to be removed from tree.
- * Return: void
+ *
+ * - [in/out] mpc - MPC context.
+ * - [in/out] tree - MPC tree structure that plane will be removed from.
+ * - [in] mpcc - MPCC to be removed from tree.
+ *
+ * Return:
+ *
+ * void
*/
void (*remove_mpcc_from_secondary)(
struct mpc *mpc,
--
2.42.0
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH 5/8] Documentation/gpu: Add entry for OPP in the kernel doc
2023-10-20 22:05 [PATCH 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (3 preceding siblings ...)
2023-10-20 22:05 ` [PATCH 4/8] Documentation/gpu: Add kernel doc entry for MPC Rodrigo Siqueira
@ 2023-10-20 22:05 ` Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 6/8] Documentation/gpu: Add entry for the DIO component Rodrigo Siqueira
` (2 subsequent siblings)
7 siblings, 0 replies; 10+ messages in thread
From: Rodrigo Siqueira @ 2023-10-20 22:05 UTC (permalink / raw)
To: amd-gfx, linux-doc
Cc: Rodrigo Siqueira, Mario Limonciello, Alex Deucher, Harry Wentland,
Hamza Mahfooz
Introduce OPP as part of the kernel documentation.
Cc: Mario Limonciello <mario.limonciello@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Harry Wentland <Harry.Wentland@amd.com>
Cc: Hamza Mahfooz <hamza.mahfooz@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
Documentation/gpu/amdgpu/display/dcn-blocks.rst | 12 ++++++++++++
drivers/gpu/drm/amd/display/dc/inc/hw/opp.h | 16 ++++++++++++++++
2 files changed, 28 insertions(+)
diff --git a/Documentation/gpu/amdgpu/display/dcn-blocks.rst b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
index 1a223f33202e..5ba3c04c1db0 100644
--- a/Documentation/gpu/amdgpu/display/dcn-blocks.rst
+++ b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
@@ -52,3 +52,15 @@ MPC
.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
:internal:
+
+OPP
+---
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
+ :doc: overview
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
+ :export:
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
+ :internal:
diff --git a/drivers/gpu/drm/amd/display/dc/inc/hw/opp.h b/drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
index 7617fabbd16e..aee5372e292c 100644
--- a/drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
+++ b/drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
@@ -23,6 +23,22 @@
*
*/
+/**
+ * DOC: overview
+ *
+ * The Output Plane Processor (OPP) block groups have functions that format
+ * pixel streams such that they are suitable for display at the display device.
+ * The key functions contained in the OPP are:
+ *
+ * - Adaptive Backlight Modulation (ABM)
+ * - Formatter (FMT) which provide pixel-by-pixel operations for format the
+ * incoming pixel stream.
+ * - Output Buffer that provide pixel replication, and overlapping.
+ * - Interface between MPC and OPTC.
+ * - Clock and reset generation.
+ * - CRC generation.
+ */
+
#ifndef __DAL_OPP_H__
#define __DAL_OPP_H__
--
2.42.0
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH 6/8] Documentation/gpu: Add entry for the DIO component
2023-10-20 22:05 [PATCH 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (4 preceding siblings ...)
2023-10-20 22:05 ` [PATCH 5/8] Documentation/gpu: Add entry for OPP in the kernel doc Rodrigo Siqueira
@ 2023-10-20 22:05 ` Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 7/8] Documentation/gpu: Add an explanation about the DC weekly patches Rodrigo Siqueira
2023-10-20 22:05 ` [PATCH 8/8] Documentation/gpu: Introduce a simple contribution list for display code Rodrigo Siqueira
7 siblings, 0 replies; 10+ messages in thread
From: Rodrigo Siqueira @ 2023-10-20 22:05 UTC (permalink / raw)
To: amd-gfx, linux-doc
Cc: Rodrigo Siqueira, Mario Limonciello, Alex Deucher, Harry Wentland,
Hamza Mahfooz
Cc: Mario Limonciello <mario.limonciello@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Harry Wentland <Harry.Wentland@amd.com>
Cc: Hamza Mahfooz <hamza.mahfooz@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
Documentation/gpu/amdgpu/display/dcn-blocks.rst | 12 ++++++++++++
.../gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h | 10 ++++++++++
2 files changed, 22 insertions(+)
diff --git a/Documentation/gpu/amdgpu/display/dcn-blocks.rst b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
index 5ba3c04c1db0..a3fbd3ea028b 100644
--- a/Documentation/gpu/amdgpu/display/dcn-blocks.rst
+++ b/Documentation/gpu/amdgpu/display/dcn-blocks.rst
@@ -64,3 +64,15 @@ OPP
.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h
:internal:
+
+DIO
+---
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h
+ :doc: overview
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h
+ :export:
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h
+ :internal:
diff --git a/drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h b/drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h
index f4633d3cf9b9..a1f72fe378ee 100644
--- a/drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h
+++ b/drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h
@@ -22,6 +22,16 @@
* Authors: AMD
*
*/
+
+/**
+ * DOC: overview
+ *
+ * Display Input Output (DIO), is the display input and output unit in DCN. It
+ * includes output encoders to support different display output, like
+ * DisplayPort, HDMI, DVI interface, and others. It also includes the control
+ * and status channels for these interfaces.
+ */
+
#ifndef __LINK_HWSS_DIO_H__
#define __LINK_HWSS_DIO_H__
--
2.42.0
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH 7/8] Documentation/gpu: Add an explanation about the DC weekly patches
2023-10-20 22:05 [PATCH 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (5 preceding siblings ...)
2023-10-20 22:05 ` [PATCH 6/8] Documentation/gpu: Add entry for the DIO component Rodrigo Siqueira
@ 2023-10-20 22:05 ` Rodrigo Siqueira
2023-10-23 11:17 ` Jani Nikula
2023-10-20 22:05 ` [PATCH 8/8] Documentation/gpu: Introduce a simple contribution list for display code Rodrigo Siqueira
7 siblings, 1 reply; 10+ messages in thread
From: Rodrigo Siqueira @ 2023-10-20 22:05 UTC (permalink / raw)
To: amd-gfx, linux-doc
Cc: Rodrigo Siqueira, Mario Limonciello, Alex Deucher, Harry Wentland,
Hamza Mahfooz
Sharing code with other OSes is confusing and raises some questions.
This patch introduces some explanation about our upstream process with
the shared code.
Cc: Mario Limonciello <mario.limonciello@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Harry Wentland <Harry.Wentland@amd.com>
Cc: Hamza Mahfooz <hamza.mahfooz@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
Documentation/gpu/amdgpu/display/index.rst | 111 ++++++++++++++++++++-
1 file changed, 109 insertions(+), 2 deletions(-)
diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst
index b09d1434754d..9d53a42c5339 100644
--- a/Documentation/gpu/amdgpu/display/index.rst
+++ b/Documentation/gpu/amdgpu/display/index.rst
@@ -10,7 +10,114 @@ reason, our Display Core Driver is divided into two pieces:
1. **Display Core (DC)** contains the OS-agnostic components. Things like
hardware programming and resource management are handled here.
2. **Display Manager (DM)** contains the OS-dependent components. Hooks to the
- amdgpu base driver and DRM are implemented here.
+ amdgpu base driver and DRM are implemented here. For example, you can check
+ display/amdgpu_dm/ folder.
+
+--------------------
+How AMD shares code?
+--------------------
+
+Maintaining the same code-base across multiple OSes requires a lot of
+synchronization effort between repositories. In the DC case, we maintain a
+central repository where everyone who works from other OSes can put their
+change in this centralized repository. In a simple way, this shared repository
+is identical to all code that you can see in the display folder. The shared
+repo has integration tests with our Linux CI farm, and we run an exhaustive set
+of IGT tests in various AMD GPUs/APUs. Our CI also checks ARM64/32, PPC64/32,
+and x86_64/32 compilation with DCN enabled and disabled. After all tests pass
+and the developer gets reviewed by someone else, the change gets merged into
+the shared repository.
+
+To maintain this shared code working properly, we run two activities every
+week:
+
+1. **Weekly backport**: We bring changes from Linux to the other shared
+ repositories. This work gets massive support from our CI tools, which can
+ detect new changes and send them to internal maintainers.
+2. **Weekly promotion**: Every week, we get changes from other teams in the
+ shared repo that have yet to be made public. For this reason, at the
+ beginning of each week, a developer will review that internal repo and
+ prepare a series of patches that can be sent to the public upstream
+ (promotion).
+
+For the context of this documentation, promotion is the essential part that
+deserves a good elaboration here.
+
+Weekly promotion
+----------------
+
+As described in the previous sections, the display folder has its equivalent as
+an internal repository shared with multiple teams. The promotion activity is
+the task of 'promoting' those internal changes to the upstream; this is
+possible thanks to numerous tools that help us manage the code-sharing
+challenges. The weekly promotion usually takes one week, sliced like this:
+
+1. Extract all merged patches from the previous week that can be sent to the
+ upstream. In other words, we check the week's time frame.
+2. Evaluate if any potential new patches make sense to the upstream.
+3. Create a branch candidate with the latest amd-staging-drm-next code together
+ with the new patches. At this step, we must ensure that every patch compiles
+ and the entire series pass our set of IGT test in different hardware (i.e.,
+ it has to pass to our CI).
+4. Send the new candidate branch for an internal quality test and extra CI
+ validation.
+5. Send patches to amd-gfx for reviews. We wait a few days for community
+ feedback after sending a series to the public mailing list. 6. If there is
+ an error, we debug as fast as possible; usually, a simple bisect in the
+ weekly promotion patches points to a bad change, and we can take two
+ possible actions: fix the issue or drop the patch. If we cannot identify the
+ problem in the week interval, we drop the promotion and start over the
+ following week; in this case, the following promotion will have the previous
+ patches plus the new ones.
+
+We usually rotate the above process with many display developers to keep the
+workload manageable for everybody. It is good to highlight that the test phase
+is something that we take extremely seriously, and we never merge anything that
+fails our validation. Just to give an overview:
+
+1. Manual test
+ - Multiple Hotplugs with DP and HDMI.
+ - Stress test with multiple display configuration changes via the user
+ interface.
+ - Validate VRR behaviour.
+ - Check PSR.
+ - Validate MPO when playing video.
+ - Test more than two displays connected at the same time.
+ - Check suspend/resume.
+2. Automated test
+ - IGT tests in a farm with GPUs and APUs that support DCN and DCE.
+ - Compilation validation with the latest GCC and Clang from LTS distro.
+ - Cross-compilation for PowerPC 64/32, ARM 64/32, and x86 32.
+
+Notice that all of the above tests happen in various AMD devices.
+
+Contributions to the weekly promotion
+-------------------------------------
+
+If you have a patch and are unsure if it can cause regressions in other ASICs
+and want some validation, you can ask us to include your patches in the weekly
+promotion for validation. Just keep in mind that your patch will be included in
+the next promotion cycle and re-submitted on your behalf (without changing your
+authorship) by some of the display developers.
+
+The weekly promotion process is a very organic initiative that has changed
+significantly over the years, thanks to numerous feedbacks. We are all ears if
+you have any suggestions on how we can improve this process; just keep in mind
+that this is a very challenging task, and implementing some ideas can take time
+if possible.
+
+DC Workflow for a new feature
+-----------------------------
+
+When we enable a new feature in the DC, the entire development workflow happens
+on the amd-gfx mailing list. For example, when we enabled the PSR or the Replay
+feature, all the development happened on amd-gfx. When enabling a new feature,
+we just use promotion for extra validation in the latest patches by asking the
+quality team to test the current promotion together with the new patches.
+
+--------------
+DC Information
+--------------
The display pipe is responsible for "scanning out" a rendered frame from the
GPU memory (also called VRAM, FrameBuffer, etc.) to a display. In other words,
@@ -26,8 +133,8 @@ table of content:
.. toctree::
display-manager.rst
- dc-debug.rst
dcn-overview.rst
dcn-blocks.rst
mpo-overview.rst
+ dc-debug.rst
dc-glossary.rst
--
2.42.0
^ permalink raw reply related [flat|nested] 10+ messages in thread* Re: [PATCH 7/8] Documentation/gpu: Add an explanation about the DC weekly patches
2023-10-20 22:05 ` [PATCH 7/8] Documentation/gpu: Add an explanation about the DC weekly patches Rodrigo Siqueira
@ 2023-10-23 11:17 ` Jani Nikula
0 siblings, 0 replies; 10+ messages in thread
From: Jani Nikula @ 2023-10-23 11:17 UTC (permalink / raw)
To: Rodrigo Siqueira, amd-gfx, linux-doc
Cc: Rodrigo Siqueira, Mario Limonciello, Alex Deucher, Harry Wentland,
Hamza Mahfooz, Dave Airlie, Daniel Vetter
On Fri, 20 Oct 2023, Rodrigo Siqueira <Rodrigo.Siqueira@amd.com> wrote:
> Sharing code with other OSes is confusing and raises some questions.
> This patch introduces some explanation about our upstream process with
> the shared code.
Thanks for writing this! It does help with the transparency.
Please find a comment inline.
>
> Cc: Mario Limonciello <mario.limonciello@amd.com>
> Cc: Alex Deucher <alexander.deucher@amd.com>
> Cc: Harry Wentland <Harry.Wentland@amd.com>
> Cc: Hamza Mahfooz <hamza.mahfooz@amd.com>
> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> ---
> Documentation/gpu/amdgpu/display/index.rst | 111 ++++++++++++++++++++-
> 1 file changed, 109 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst
> index b09d1434754d..9d53a42c5339 100644
> --- a/Documentation/gpu/amdgpu/display/index.rst
> +++ b/Documentation/gpu/amdgpu/display/index.rst
> @@ -10,7 +10,114 @@ reason, our Display Core Driver is divided into two pieces:
> 1. **Display Core (DC)** contains the OS-agnostic components. Things like
> hardware programming and resource management are handled here.
> 2. **Display Manager (DM)** contains the OS-dependent components. Hooks to the
> - amdgpu base driver and DRM are implemented here.
> + amdgpu base driver and DRM are implemented here. For example, you can check
> + display/amdgpu_dm/ folder.
> +
> +--------------------
> +How AMD shares code?
> +--------------------
> +
> +Maintaining the same code-base across multiple OSes requires a lot of
> +synchronization effort between repositories. In the DC case, we maintain a
> +central repository where everyone who works from other OSes can put their
> +change in this centralized repository. In a simple way, this shared repository
> +is identical to all code that you can see in the display folder. The shared
> +repo has integration tests with our Linux CI farm, and we run an exhaustive set
> +of IGT tests in various AMD GPUs/APUs. Our CI also checks ARM64/32, PPC64/32,
> +and x86_64/32 compilation with DCN enabled and disabled. After all tests pass
> +and the developer gets reviewed by someone else, the change gets merged into
> +the shared repository.
> +
> +To maintain this shared code working properly, we run two activities every
> +week:
> +
> +1. **Weekly backport**: We bring changes from Linux to the other shared
> + repositories. This work gets massive support from our CI tools, which can
> + detect new changes and send them to internal maintainers.
> +2. **Weekly promotion**: Every week, we get changes from other teams in the
> + shared repo that have yet to be made public. For this reason, at the
> + beginning of each week, a developer will review that internal repo and
> + prepare a series of patches that can be sent to the public upstream
> + (promotion).
> +
> +For the context of this documentation, promotion is the essential part that
> +deserves a good elaboration here.
> +
> +Weekly promotion
> +----------------
> +
> +As described in the previous sections, the display folder has its equivalent as
> +an internal repository shared with multiple teams. The promotion activity is
> +the task of 'promoting' those internal changes to the upstream; this is
> +possible thanks to numerous tools that help us manage the code-sharing
> +challenges. The weekly promotion usually takes one week, sliced like this:
> +
> +1. Extract all merged patches from the previous week that can be sent to the
> + upstream. In other words, we check the week's time frame.
> +2. Evaluate if any potential new patches make sense to the upstream.
> +3. Create a branch candidate with the latest amd-staging-drm-next code together
> + with the new patches. At this step, we must ensure that every patch compiles
> + and the entire series pass our set of IGT test in different hardware (i.e.,
> + it has to pass to our CI).
> +4. Send the new candidate branch for an internal quality test and extra CI
> + validation.
> +5. Send patches to amd-gfx for reviews. We wait a few days for community
> + feedback after sending a series to the public mailing list.
So we've debated this one before. :)
Again, I applaud the transparency in writing the document, but I can't
help feeling the weekly promotions are code drops that will generally be
merged unchanged, with no comments. They have all been reviewed
internally, get posted with Reviewed-by tags pre-filled, we have no
visibility to the review. Since the code has already been merged
internally and the batch has passed CI, feels like the bar for changing
anything at this point is pretty high.
Just my two cents.
BR,
Jani.
(Side note, there should be a \n before 6.)
6. If there is
> + an error, we debug as fast as possible; usually, a simple bisect in the
> + weekly promotion patches points to a bad change, and we can take two
> + possible actions: fix the issue or drop the patch. If we cannot identify the
> + problem in the week interval, we drop the promotion and start over the
> + following week; in this case, the following promotion will have the previous
> + patches plus the new ones.
> +
> +We usually rotate the above process with many display developers to keep the
> +workload manageable for everybody. It is good to highlight that the test phase
> +is something that we take extremely seriously, and we never merge anything that
> +fails our validation. Just to give an overview:
> +
> +1. Manual test
> + - Multiple Hotplugs with DP and HDMI.
> + - Stress test with multiple display configuration changes via the user
> + interface.
> + - Validate VRR behaviour.
> + - Check PSR.
> + - Validate MPO when playing video.
> + - Test more than two displays connected at the same time.
> + - Check suspend/resume.
> +2. Automated test
> + - IGT tests in a farm with GPUs and APUs that support DCN and DCE.
> + - Compilation validation with the latest GCC and Clang from LTS distro.
> + - Cross-compilation for PowerPC 64/32, ARM 64/32, and x86 32.
> +
> +Notice that all of the above tests happen in various AMD devices.
> +
> +Contributions to the weekly promotion
> +-------------------------------------
> +
> +If you have a patch and are unsure if it can cause regressions in other ASICs
> +and want some validation, you can ask us to include your patches in the weekly
> +promotion for validation. Just keep in mind that your patch will be included in
> +the next promotion cycle and re-submitted on your behalf (without changing your
> +authorship) by some of the display developers.
> +
> +The weekly promotion process is a very organic initiative that has changed
> +significantly over the years, thanks to numerous feedbacks. We are all ears if
> +you have any suggestions on how we can improve this process; just keep in mind
> +that this is a very challenging task, and implementing some ideas can take time
> +if possible.
> +
> +DC Workflow for a new feature
> +-----------------------------
> +
> +When we enable a new feature in the DC, the entire development workflow happens
> +on the amd-gfx mailing list. For example, when we enabled the PSR or the Replay
> +feature, all the development happened on amd-gfx. When enabling a new feature,
> +we just use promotion for extra validation in the latest patches by asking the
> +quality team to test the current promotion together with the new patches.
> +
> +--------------
> +DC Information
> +--------------
>
> The display pipe is responsible for "scanning out" a rendered frame from the
> GPU memory (also called VRAM, FrameBuffer, etc.) to a display. In other words,
> @@ -26,8 +133,8 @@ table of content:
> .. toctree::
>
> display-manager.rst
> - dc-debug.rst
> dcn-overview.rst
> dcn-blocks.rst
> mpo-overview.rst
> + dc-debug.rst
> dc-glossary.rst
--
Jani Nikula, Intel
^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH 8/8] Documentation/gpu: Introduce a simple contribution list for display code
2023-10-20 22:05 [PATCH 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (6 preceding siblings ...)
2023-10-20 22:05 ` [PATCH 7/8] Documentation/gpu: Add an explanation about the DC weekly patches Rodrigo Siqueira
@ 2023-10-20 22:05 ` Rodrigo Siqueira
7 siblings, 0 replies; 10+ messages in thread
From: Rodrigo Siqueira @ 2023-10-20 22:05 UTC (permalink / raw)
To: amd-gfx, linux-doc
Cc: Rodrigo Siqueira, Mario Limonciello, Alex Deucher, Harry Wentland,
Hamza Mahfooz
This commit adds a contribution list for display under the kernel
documentation with some first suggestions. It also drops an old TODO
list from the display folder.
Cc: Mario Limonciello <mario.limonciello@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Harry Wentland <Harry.Wentland@amd.com>
Cc: Hamza Mahfooz <hamza.mahfooz@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
.../amdgpu/display/display-contributing.rst | 88 ++++++++++++++
Documentation/gpu/amdgpu/display/index.rst | 12 +-
drivers/gpu/drm/amd/display/TODO | 110 ------------------
3 files changed, 95 insertions(+), 115 deletions(-)
create mode 100644 Documentation/gpu/amdgpu/display/display-contributing.rst
delete mode 100644 drivers/gpu/drm/amd/display/TODO
diff --git a/Documentation/gpu/amdgpu/display/display-contributing.rst b/Documentation/gpu/amdgpu/display/display-contributing.rst
new file mode 100644
index 000000000000..0247e0579fd4
--- /dev/null
+++ b/Documentation/gpu/amdgpu/display/display-contributing.rst
@@ -0,0 +1,88 @@
+.. _display_todos:
+
+==============================
+AMDGPU - Display Contributions
+==============================
+
+First of all, if you are here, you probably want to give some technical
+contribution to the display code, and for that, we say thank you :)
+
+This page summarizes some of the issues you can help with. This page follows
+the DRM way of creating a TODO list; for more information, check
+'Documentation/gpu/todo.rst'.
+
+Gitlab issues
+=============
+
+Users can report issues associated with AMD GPUs at:
+
+- https://gitlab.freedesktop.org/drm/amd
+
+Usually, we try to add a proper label to all new tickets to make it easy to
+filter issues. If you can reproduce any problem, you could help by adding more
+information or fixing the issue.
+
+Level: diverse
+
+IGT
+===
+
+`IGT`_ provides many integration tests that can be run on your GPU. We always
+want to pass a large set of tests to increase the test coverage in our CI. If
+you wish to contribute to the display code but are unsure where a good place
+is, we recommend you run all IGT tests and try to fix any failure you see in
+your hardware. Keep in mind that this failure can be an IGT problem or a kernel
+issue; it is necessary to analyze case-by-case.
+
+Level: diverse
+
+.. _IGT: https://gitlab.freedesktop.org/drm/igt-gpu-tools
+
+Compilation
+===========
+
+Fix compilation warnings
+------------------------
+
+Enable the W1 or W2 warning level in the kernel compilation and try to fix the
+issues on the display side.
+
+Level: Starter
+
+Code Refactor
+=============
+
+Add prefix to DC functions to improve the debug with ftrace
+-----------------------------------------------------------
+
+The Ftrace debug feature (check 'Documentation/trace/ftrace.rst') is a
+fantastic way to check the code path when developers are trying to make sense
+of a bug. Ftrace provide a filter mechanism that can be useful when the
+developer has some hunch of which part of the code can cause the issue; for
+this reason, if a set of function has a proper prefix, it becomes easy to
+create a good filter. The DC code does not follow some prefix rules, which
+makes the Ftrace filter more complicated. If you want something simple to start
+contributing to the display, you can make patches for adding prefixes to DC
+functions. To create those prefixes, use part of the file name as a prefix for
+all functions in the target file. Check the 'amdgpu_dm_crtc.c` and
+`amdgpu_dm_plane.c` for some references.
+
+Level: Starter
+
+
+Try to move some of the sink handling code to DRM
+-------------------------------------------------
+
+When amdgpu was upstream for the first time, developers discussed how AMD
+display handles sink. From the conversation, developers concluded that we
+should move some of those codes to the DRM helpers/core in the long term.
+
+Level: Advanced
+
+Simplify DDC
+------------
+
+We can probably remove vector.c from dc/basics. It's used in DDC code which can
+probably be simplified enough to no longer need a vector implementation.
+
+Level: Advanced
diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst
index 9d53a42c5339..25445a50121e 100644
--- a/Documentation/gpu/amdgpu/display/index.rst
+++ b/Documentation/gpu/amdgpu/display/index.rst
@@ -109,11 +109,12 @@ if possible.
DC Workflow for a new feature
-----------------------------
-When we enable a new feature in the DC, the entire development workflow happens
-on the amd-gfx mailing list. For example, when we enabled the PSR or the Replay
-feature, all the development happened on amd-gfx. When enabling a new feature,
-we just use promotion for extra validation in the latest patches by asking the
-quality team to test the current promotion together with the new patches.
+When an AMD developer enables a new feature in the DC, the entire development
+workflow happens on the amd-gfx mailing list. For example, when we enabled the
+PSR or the Replay feature, all the development happened on amd-gfx. When
+enabling a new feature, we just use promotion for extra validation in the
+latest patches by asking the quality team to test the current promotion
+together with the new patches.
--------------
DC Information
@@ -137,4 +138,5 @@ table of content:
dcn-blocks.rst
mpo-overview.rst
dc-debug.rst
+ display-contributing.rst
dc-glossary.rst
diff --git a/drivers/gpu/drm/amd/display/TODO b/drivers/gpu/drm/amd/display/TODO
deleted file mode 100644
index a8a6c106e8c7..000000000000
--- a/drivers/gpu/drm/amd/display/TODO
+++ /dev/null
@@ -1,110 +0,0 @@
-===============================================================================
-TODOs
-===============================================================================
-
-1. Base this on drm-next - WIP
-
-
-2. Cleanup commit history
-
-
-3. WIP - Drop page flip helper and use DRM's version
-
-
-4. DONE - Flatten all DC objects
- * dc_stream/core_stream/stream should just be dc_stream
- * Same for other DC objects
-
- "Is there any major reason to keep all those abstractions?
-
- Could you collapse everything into struct dc_stream?
-
- I haven't looked recently but I didn't get the impression there was a
- lot of design around what was public/protected, more whatever needed
- to be used by someone else was in public."
- ~ Dave Airlie
-
-
-5. DONE - Rename DC objects to align more with DRM
- * dc_surface -> dc_plane_state
- * dc_stream -> dc_stream_state
-
-
-6. DONE - Per-plane and per-stream validation
-
-
-7. WIP - Per-plane and per-stream commit
-
-
-8. WIP - Split pipe_ctx into plane and stream resource structs
-
-
-9. Attach plane and stream reources to state object instead of validate_context
-
-
-10. Remove dc_edid_caps and drm_helpers_parse_edid_caps
- * Use drm_display_info instead
- * Remove DC's edid quirks and rely on DRM's quirks (add quirks if needed)
-
- "Making sure you use the sink-specific helper libraries and kernel
- subsystems, since there's really no good reason to have 2nd
- implementation of those in the kernel. Looks likes that's done for mst
- and edid parsing. There's still a bit a midlayer feeling to the edid
- parsing side (e.g. dc_edid_caps and dm_helpers_parse_edid_caps, I
- think it'd be much better if you convert that over to reading stuff
- from drm_display_info and if needed, push stuff into the core). Also,
- I can't come up with a good reason why DC needs all this (except to
- reimplement half of our edid quirk table, which really isn't a good
- idea). Might be good if you put this onto the list of things to fix
- long-term, but imo not a blocker. Definitely make sure new stuff
- doesn't slip in (i.e. if you start adding edid quirks to DC instead of
- the drm core, refactoring to use the core edid stuff was pointless)."
- ~ Daniel Vetter
-
-
-11. Remove dc/i2caux. This folder can be somewhat misleading. It's basically an
-overy complicated HW programming function for sendind and receiving i2c/aux
-commands. We can greatly simplify that and move it into dc/dceXYZ like other
-HW blocks.
-
-12. drm_modeset_lock in MST should no longer be needed in recent kernels
- * Adopt appropriate locking scheme
-
-13. get_modes and best_encoder callbacks look a bit funny. Can probably rip out
-a few indirections, and consider removing entirely and using the
-drm_atomic_helper_best_encoder default behaviour.
-
-14. core/dc_debug.c, consider switching to the atomic state debug helpers and
-moving all your driver state printing into the various atomic_print_state
-callbacks. There's also plans to expose this stuff in a standard way across all
-drivers, to make debugging userspace compositors easier across different hw.
-
-15. Move DP/HDMI dual mode adaptors to drm_dp_dual_mode_helper.c. See
-dal_ddc_service_i2c_query_dp_dual_mode_adaptor.
-
-16. Move to core SCDC helpers (I think those are new since initial DC review).
-
-17. There's still a pretty massive layer cake around dp aux and DPCD handling,
-with like 3 levels of abstraction and using your own structures instead of the
-stuff in drm_dp_helper.h. drm_dp_helper.h isn't really great and already has 2
-incompatible styles, just means more reasons not to add a third (or well third
-one gets to do the cleanup refactor).
-
-18. There's a pile of sink handling code, both for DP and HDMI where I didn't
-immediately recognize the standard. I think long term it'd be best for the drm
-subsystem if we try to move as much of that into helpers/core as possible, and
-share it with drivers. But that's a very long term goal, and by far not just an
-issue with DC - other drivers, especially around DP sink handling, are equally
-guilty.
-
-19. DONE - The DC logger is still a rather sore thing, but I know that the
-DRM_DEBUG stuff just isn't up to the challenges either. We need to figure out
-something that integrates better with DRM and linux debug printing, while not
-being useless with filtering output. dynamic debug printing might be an option.
-
-20. Use kernel i2c device to program HDMI retimer. Some boards have an HDMI
-retimer that we need to program to pass PHY compliance. Currently that's
-bypassing the i2c device and goes directly to HW. This should be changed.
-
-21. Remove vector.c from dc/basics. It's used in DDC code which can probably
-be simplified enough to no longer need a vector implementation.
--
2.42.0
^ permalink raw reply related [flat|nested] 10+ messages in thread