* [PATCH v2 0/8] Expand and improve AMDGPU documentation
@ 2024-01-22 21:24 Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 1/8] Documentation/gpu: Add basic page for HUBP Rodrigo Siqueira
` (10 more replies)
0 siblings, 11 replies; 13+ messages in thread
From: Rodrigo Siqueira @ 2024-01-22 21:24 UTC (permalink / raw
To: Alex Deucher, Christian König, Mario Limonciello,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: Rodrigo Siqueira, amd-gfx, linux-doc
This patchset improves how the AMDGPU display documentation is
organized, expands the kernel-doc to extract information from the
source, and adds more context about DC workflow. Finally, at the end of
this series, we also introduce a contribution section for those
interested in contributing to the display code.
Changes since V1:
- Remove unprecise information about the DC process.
- Expand the contribution list.
- Rebase.
Thanks
Siqueira
Rodrigo Siqueira (8):
Documentation/gpu: Add basic page for HUBP
Documentation/gpu: Add simple doc page for DCHUBBUB
Documentation/gpu: Add kernel doc entry for DPP
Documentation/gpu: Add kernel doc entry for MPC
Documentation/gpu: Add entry for OPP in the kernel doc
Documentation/gpu: Add entry for the DIO component
Documentation/gpu: Add an explanation about the DC weekly patches
Documentation/gpu: Introduce a simple contribution list for display
code
.../gpu/amdgpu/display/dcn-blocks.rst | 78 ++++++
.../amdgpu/display/display-contributing.rst | 168 ++++++++++++
.../gpu/amdgpu/display/display-manager.rst | 3 -
Documentation/gpu/amdgpu/display/index.rst | 78 +++++-
drivers/gpu/drm/amd/display/TODO | 110 --------
.../gpu/drm/amd/display/dc/inc/hw/dchubbub.h | 6 +
drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h | 26 ++
drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h | 13 +-
drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h | 250 ++++++++++++------
drivers/gpu/drm/amd/display/dc/inc/hw/opp.h | 16 ++
.../amd/display/dc/link/hwss/link_hwss_dio.h | 10 +
11 files changed, 560 insertions(+), 198 deletions(-)
create mode 100644 Documentation/gpu/amdgpu/display/dcn-blocks.rst
create mode 100644 Documentation/gpu/amdgpu/display/display-contributing.rst
delete mode 100644 drivers/gpu/drm/amd/display/TODO
--
2.43.0
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH v2 1/8] Documentation/gpu: Add basic page for HUBP
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
@ 2024-01-22 21:24 ` Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 2/8] Documentation/gpu: Add simple doc page for DCHUBBUB Rodrigo Siqueira
` (9 subsequent siblings)
10 siblings, 0 replies; 13+ messages in thread
From: Rodrigo Siqueira @ 2024-01-22 21:24 UTC (permalink / raw
To: Alex Deucher, Christian König, Mario Limonciello,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: Harry Wentland, Rodrigo Siqueira, amd-gfx, linux-doc
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>
Cc: Christian König <christian.koenig@amd.com>
Cc: Aurabindo Pillai <aurabindo.pillai@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.43.0
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH v2 2/8] Documentation/gpu: Add simple doc page for DCHUBBUB
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 1/8] Documentation/gpu: Add basic page for HUBP Rodrigo Siqueira
@ 2024-01-22 21:24 ` Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 3/8] Documentation/gpu: Add kernel doc entry for DPP Rodrigo Siqueira
` (8 subsequent siblings)
10 siblings, 0 replies; 13+ messages in thread
From: Rodrigo Siqueira @ 2024-01-22 21:24 UTC (permalink / raw
To: Alex Deucher, Christian König, Mario Limonciello,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: Harry Wentland, Rodrigo Siqueira, amd-gfx, linux-doc
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>
Cc: Christian König <christian.koenig@amd.com>
Cc: Aurabindo Pillai <aurabindo.pillai@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 901891316dfb..2ae7484d18af 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.43.0
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH v2 3/8] Documentation/gpu: Add kernel doc entry for DPP
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 1/8] Documentation/gpu: Add basic page for HUBP Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 2/8] Documentation/gpu: Add simple doc page for DCHUBBUB Rodrigo Siqueira
@ 2024-01-22 21:24 ` Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 4/8] Documentation/gpu: Add kernel doc entry for MPC Rodrigo Siqueira
` (7 subsequent siblings)
10 siblings, 0 replies; 13+ messages in thread
From: Rodrigo Siqueira @ 2024-01-22 21:24 UTC (permalink / raw
To: Alex Deucher, Christian König, Mario Limonciello,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: Harry Wentland, Rodrigo Siqueira, amd-gfx, linux-doc
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>
Cc: Christian König <christian.koenig@amd.com>
Cc: Aurabindo Pillai <aurabindo.pillai@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 4e604bf24f51..a962a9f36845 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.43.0
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH v2 4/8] Documentation/gpu: Add kernel doc entry for MPC
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (2 preceding siblings ...)
2024-01-22 21:24 ` [PATCH v2 3/8] Documentation/gpu: Add kernel doc entry for DPP Rodrigo Siqueira
@ 2024-01-22 21:24 ` Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 5/8] Documentation/gpu: Add entry for OPP in the kernel doc Rodrigo Siqueira
` (6 subsequent siblings)
10 siblings, 0 replies; 13+ messages in thread
From: Rodrigo Siqueira @ 2024-01-22 21:24 UTC (permalink / raw
To: Alex Deucher, Christian König, Mario Limonciello,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: Harry Wentland, Rodrigo Siqueira, amd-gfx, linux-doc
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>
Cc: Christian König <christian.koenig@amd.com>
Cc: Aurabindo Pillai <aurabindo.pillai@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
.../gpu/amdgpu/display/dcn-blocks.rst | 12 +
.../gpu/amdgpu/display/display-manager.rst | 3 -
drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h | 250 ++++++++++++------
3 files changed, 185 insertions(+), 80 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/Documentation/gpu/amdgpu/display/display-manager.rst b/Documentation/gpu/amdgpu/display/display-manager.rst
index be2651ecdd7f..67a811e6891f 100644
--- a/Documentation/gpu/amdgpu/display/display-manager.rst
+++ b/Documentation/gpu/amdgpu/display/display-manager.rst
@@ -131,9 +131,6 @@ The DRM blend mode and its elements are then mapped by AMDGPU display manager
(DM) to program the blending configuration of the Multiple Pipe/Plane Combined
(MPC), as follows:
-.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
- :doc: mpc-overview
-
.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
:functions: mpcc_blnd_cfg
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 a11e40fddc44..ba9b942ce09f 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
+ * Multiple Pipe/Plane Combiner (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 {
@@ -224,16 +295,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,
@@ -250,11 +325,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,
@@ -267,9 +345,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)(
@@ -282,11 +363,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,
@@ -296,15 +380,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,
@@ -314,20 +401,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,
@@ -344,10 +436,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.43.0
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH v2 5/8] Documentation/gpu: Add entry for OPP in the kernel doc
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (3 preceding siblings ...)
2024-01-22 21:24 ` [PATCH v2 4/8] Documentation/gpu: Add kernel doc entry for MPC Rodrigo Siqueira
@ 2024-01-22 21:24 ` Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 6/8] Documentation/gpu: Add entry for the DIO component Rodrigo Siqueira
` (5 subsequent siblings)
10 siblings, 0 replies; 13+ messages in thread
From: Rodrigo Siqueira @ 2024-01-22 21:24 UTC (permalink / raw
To: Alex Deucher, Christian König, Mario Limonciello,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: Harry Wentland, Rodrigo Siqueira, amd-gfx, linux-doc
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>
Cc: Christian König <christian.koenig@amd.com>
Cc: Aurabindo Pillai <aurabindo.pillai@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.43.0
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH v2 6/8] Documentation/gpu: Add entry for the DIO component
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (4 preceding siblings ...)
2024-01-22 21:24 ` [PATCH v2 5/8] Documentation/gpu: Add entry for OPP in the kernel doc Rodrigo Siqueira
@ 2024-01-22 21:24 ` Rodrigo Siqueira
2024-01-22 21:25 ` [PATCH v2 7/8] Documentation/gpu: Add an explanation about the DC weekly patches Rodrigo Siqueira
` (4 subsequent siblings)
10 siblings, 0 replies; 13+ messages in thread
From: Rodrigo Siqueira @ 2024-01-22 21:24 UTC (permalink / raw
To: Alex Deucher, Christian König, Mario Limonciello,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: Harry Wentland, Rodrigo Siqueira, amd-gfx, linux-doc
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>
Cc: Christian König <christian.koenig@amd.com>
Cc: Aurabindo Pillai <aurabindo.pillai@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.43.0
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH v2 7/8] Documentation/gpu: Add an explanation about the DC weekly patches
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (5 preceding siblings ...)
2024-01-22 21:24 ` [PATCH v2 6/8] Documentation/gpu: Add entry for the DIO component Rodrigo Siqueira
@ 2024-01-22 21:25 ` Rodrigo Siqueira
2024-01-22 21:25 ` [PATCH v2 8/8] Documentation/gpu: Introduce a simple contribution list for display code Rodrigo Siqueira
` (3 subsequent siblings)
10 siblings, 0 replies; 13+ messages in thread
From: Rodrigo Siqueira @ 2024-01-22 21:25 UTC (permalink / raw
To: Alex Deucher, Christian König, Mario Limonciello,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: Harry Wentland, Rodrigo Siqueira, amd-gfx, linux-doc
This commit introduces some explanation about the display team
validation.
Changes since V1:
- Remove unprecise information about the DC process for now, can be
added later on.
- Jani: Fix bullets
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>
Cc: Christian König <christian.koenig@amd.com>
Cc: Aurabindo Pillai <aurabindo.pillai@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
Documentation/gpu/amdgpu/display/index.rst | 76 ++++++++++++++++++++--
1 file changed, 69 insertions(+), 7 deletions(-)
diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst
index b09d1434754d..aa89e8f9ab89 100644
--- a/Documentation/gpu/amdgpu/display/index.rst
+++ b/Documentation/gpu/amdgpu/display/index.rst
@@ -7,18 +7,80 @@ drm/amd/display - Display Core (DC)
AMD display engine is partially shared with other operating systems; for this
reason, our Display Core Driver is divided into two pieces:
-1. **Display Core (DC)** contains the OS-agnostic components. Things like
+#. **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.
+#. **Display Manager (DM)** contains the OS-dependent components. Hooks to the
+ amdgpu base driver and DRM are implemented here. For example, you can check
+ display/amdgpu_dm/ folder.
+
+------------------
+DC Code validation
+------------------
+
+Maintaining the same code base across multiple OSes requires a lot of
+synchronization effort between repositories and exhaustive validation. In the
+DC case, we maintain a tree to centralize code from different parts. The shared
+repository has integration tests with our Internal Linux CI farm, and we run a
+comprehensive set of IGT tests in various AMD GPUs/APUs (mostly recent dGPUs
+and APUs). Our CI also checks ARM64/32, PPC64/32, and x86_64/32 compilation
+with DCN enabled and disabled.
+
+When we upstream a new feature or some patches, we pack them in a patchset with
+the prefix **DC Patches for <DATE>**, which is created based on the latest
+`amd-staging-drm-next <https://gitlab.freedesktop.org/agd5f/linux>`_. All of
+those patches are under a DC version tested as follows:
+
+* Ensure that every patch compiles and the entire series pass our set of IGT
+ test in different hardware.
+* Prepare a branch with those patches for our validation team. If there is an
+ error, a developer will debug as fast as possible; usually, a simple bisect
+ in the series is enough to point to a bad change, and two possible actions
+ emerge: fix the issue or drop the patch. If it is not an easy fix, the bad
+ patch is dropped.
+* Finally, developers wait a few days for community feedback before we merge
+ the series.
+
+It is good to stress that the test phase is something that we take extremely
+seriously, and we never merge anything that fails our validation. Follows an
+overview of our test set:
+
+#. 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.
+ * Validate FPO.
+ * Check MST.
+#. 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.
+
+In terms of test setup for CI and manual tests, we usually use:
+
+#. The latest Ubuntu LTS.
+#. In terms of userspace, we only use fully updated open-source components
+ provided by the distribution official package manager.
+#. Regarding IGT, we use the latest code from the upstream.
+#. Most of the manual tests are conducted in the GNome but we also use KDE.
+
+Notice that someone from our test team will always reply to the cover letter
+with the test report.
+
+--------------
+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,
it would:
-1. Read frame information from memory;
-2. Perform required transformation;
-3. Send pixel data to sink devices.
+#. Read frame information from memory;
+#. Perform required transformation;
+#. Send pixel data to sink devices.
If you want to learn more about our driver details, take a look at the below
table of content:
@@ -26,8 +88,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.43.0
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH v2 8/8] Documentation/gpu: Introduce a simple contribution list for display code
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (6 preceding siblings ...)
2024-01-22 21:25 ` [PATCH v2 7/8] Documentation/gpu: Add an explanation about the DC weekly patches Rodrigo Siqueira
@ 2024-01-22 21:25 ` Rodrigo Siqueira
2024-01-22 22:48 ` [PATCH v2 0/8] Expand and improve AMDGPU documentation Mario Limonciello
` (2 subsequent siblings)
10 siblings, 0 replies; 13+ messages in thread
From: Rodrigo Siqueira @ 2024-01-22 21:25 UTC (permalink / raw
To: Alex Deucher, Christian König, Mario Limonciello,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: Harry Wentland, Rodrigo Siqueira, amd-gfx, linux-doc
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>
Cc: Christian König <christian.koenig@amd.com>
Cc: Aurabindo Pillai <aurabindo.pillai@amd.com>
Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
.../amdgpu/display/display-contributing.rst | 168 ++++++++++++++++++
Documentation/gpu/amdgpu/display/index.rst | 1 +
drivers/gpu/drm/amd/display/TODO | 110 ------------
3 files changed, 169 insertions(+), 110 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..fdb2bea01d53
--- /dev/null
+++ b/Documentation/gpu/amdgpu/display/display-contributing.rst
@@ -0,0 +1,168 @@
+.. _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; keep in mind that
+this is a static page, and it is always a good idea to try to reach developers
+in the amdgfx or some of the maintainers. Finally, 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
+
+Fix compilation issues when using um architecture
+-------------------------------------------------
+
+Linux has a User-mode Linux (UML) feature, and the kernel can be compiled to
+the **um** architecture. Compiling for **um** can bring multiple advantages
+from the test perspective. We currently have some compilation issues in this
+area that we need to fix.
+
+Level: Intermediate
+
+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 try to make sense of a
+bug. Ftrace provides 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 functions has a proper prefix, it becomes easy to create a good
+filter. Additionally, prefixes can improve stack trace readability.
+
+The DC code does not follow some prefix rules, which makes the Ftrace filter
+more complicated and reduces the readability of the stack trace. 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. However, we
+strongly advise not to send huge patches changing these prefixes; otherwise, it
+will be hard to review and test, which can generate second thoughts from
+maintainers. Try small steps; in case of double, you can ask before you put in
+effort. We recommend first looking at folders like dceXYZ, dcnXYZ, basics,
+bios, core, clk_mgr, hwss, resource, and irq.
+
+Level: Starter
+
+Reduce code duplication
+-----------------------
+
+AMD has an extensive portfolio with various dGPUs and APUs that amdgpu
+supports. To maintain the new hardware release cadence, DCE/DCN was designed in
+a modular design, making the bring-up for new hardware fast. Over the years,
+amdgpu accumulated some technical debt in the code duplication area. For this
+task, it would be a good idea to find a tool that can discover code duplication
+(including patterns) and use it as guidance to reduce duplications.
+
+Level: Intermediate
+
+Make atomic_commit_[check|tail] more readable
+---------------------------------------------
+
+The functions responsible for atomic commit and tail are intricate and
+extensive. In particular `amdgpu_dm_atomic_commit_tail` is a long function and
+could benefit from being split into smaller helpers. Improvements in this area
+are more than welcome, but keep in mind that changes in this area will affect
+all ASICs, meaning that refactoring requires a comprehensive verification; in
+other words, this effort can take some time for validation.
+
+Level: Advanced
+
+Documentation
+=============
+
+Expand kernel-doc
+-----------------
+
+Many DC functions do not have a proper kernel-doc; understanding a function and
+adding documentation is a great way to learn more about the amdgpu driver and
+also leave an outstanding contribution to the entire community.
+
+Level: Starter
+
+Beyond AMDGPU
+=============
+
+AMDGPU provides features that are not yet enabled in the userspace. This
+section highlights some of the coolest display features, which could be enabled
+with the userspace developer helper.
+
+Enable underlay
+---------------
+
+AMD display has this feature called underlay (which you can read more about at
+'Documentation/GPU/amdgpu/display/mpo-overview.rst') which is intended to
+save power when playing a video. The basic idea is to put a video in the
+underlay plane at the bottom and the desktop in the plane above it with a hole
+in the video area. This feature is enabled in ChromeOS, and from our data
+measurement, it can save power.
+
+Level: Unknown
+
+Adaptive Backlight Modulation (ABM)
+-----------------------------------
+
+ABM is a feature that adjusts the display panel's backlight level and pixel
+values depending on the displayed image. This power-saving feature can be very
+useful when the system starts to run off battery; since this will impact the
+display output fidelity, it would be good if this option was something that
+users could turn on or off.
+
+Level: Unknown
+
+
+HDR & Color management & VRR
+----------------------------
+
+HDR, Color Management, and VRR are huge topics and it's hard to put these into
+concise ToDos. If you are interested in this topic, we recommend checking some
+blog posts from the community developers to better understand some of the
+specific challenges and people working on the subject. If anyone wants to work
+on some particular part, we can try to help with some basic guidance. Finally,
+keep in mind that we already have some kernel-doc in place for those areas.
+
+Level: Unknown
diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst
index aa89e8f9ab89..f0c342e00a39 100644
--- a/Documentation/gpu/amdgpu/display/index.rst
+++ b/Documentation/gpu/amdgpu/display/index.rst
@@ -92,4 +92,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.43.0
^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: [PATCH v2 0/8] Expand and improve AMDGPU documentation
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (7 preceding siblings ...)
2024-01-22 21:25 ` [PATCH v2 8/8] Documentation/gpu: Introduce a simple contribution list for display code Rodrigo Siqueira
@ 2024-01-22 22:48 ` Mario Limonciello
2024-01-23 9:28 ` Christian König
2024-01-23 16:19 ` Hamza Mahfooz
10 siblings, 0 replies; 13+ messages in thread
From: Mario Limonciello @ 2024-01-22 22:48 UTC (permalink / raw
To: Rodrigo Siqueira, Alex Deucher, Christian König,
Harry Wentland, Leo Li, Hamza Mahfooz, Aurabindo Pillai,
Jani Nikula
Cc: amd-gfx, linux-doc
On 1/22/2024 15:24, Rodrigo Siqueira wrote:
> This patchset improves how the AMDGPU display documentation is
> organized, expands the kernel-doc to extract information from the
> source, and adds more context about DC workflow. Finally, at the end of
> this series, we also introduce a contribution section for those
> interested in contributing to the display code.
>
> Changes since V1:
> - Remove unprecise information about the DC process.
> - Expand the contribution list.
> - Rebase.
>
> Thanks
> Siqueira
>
> Rodrigo Siqueira (8):
> Documentation/gpu: Add basic page for HUBP
> Documentation/gpu: Add simple doc page for DCHUBBUB
> Documentation/gpu: Add kernel doc entry for DPP
> Documentation/gpu: Add kernel doc entry for MPC
> Documentation/gpu: Add entry for OPP in the kernel doc
> Documentation/gpu: Add entry for the DIO component
> Documentation/gpu: Add an explanation about the DC weekly patches
> Documentation/gpu: Introduce a simple contribution list for display
> code
>
> .../gpu/amdgpu/display/dcn-blocks.rst | 78 ++++++
> .../amdgpu/display/display-contributing.rst | 168 ++++++++++++
> .../gpu/amdgpu/display/display-manager.rst | 3 -
> Documentation/gpu/amdgpu/display/index.rst | 78 +++++-
> drivers/gpu/drm/amd/display/TODO | 110 --------
> .../gpu/drm/amd/display/dc/inc/hw/dchubbub.h | 6 +
> drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h | 26 ++
> drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h | 13 +-
> drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h | 250 ++++++++++++------
> drivers/gpu/drm/amd/display/dc/inc/hw/opp.h | 16 ++
> .../amd/display/dc/link/hwss/link_hwss_dio.h | 10 +
> 11 files changed, 560 insertions(+), 198 deletions(-)
> create mode 100644 Documentation/gpu/amdgpu/display/dcn-blocks.rst
> create mode 100644 Documentation/gpu/amdgpu/display/display-contributing.rst
> delete mode 100644 drivers/gpu/drm/amd/display/TODO
>
Reviewed-by: Mario Limonciello <mario.limonciello@amd.com>
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH v2 0/8] Expand and improve AMDGPU documentation
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (8 preceding siblings ...)
2024-01-22 22:48 ` [PATCH v2 0/8] Expand and improve AMDGPU documentation Mario Limonciello
@ 2024-01-23 9:28 ` Christian König
2024-01-23 16:19 ` Hamza Mahfooz
10 siblings, 0 replies; 13+ messages in thread
From: Christian König @ 2024-01-23 9:28 UTC (permalink / raw
To: Rodrigo Siqueira, Alex Deucher, Christian König,
Mario Limonciello, Harry Wentland, Leo Li, Hamza Mahfooz,
Aurabindo Pillai, Jani Nikula
Cc: amd-gfx, linux-doc
Am 22.01.24 um 22:24 schrieb Rodrigo Siqueira:
> This patchset improves how the AMDGPU display documentation is
> organized, expands the kernel-doc to extract information from the
> source, and adds more context about DC workflow. Finally, at the end of
> this series, we also introduce a contribution section for those
> interested in contributing to the display code.
>
> Changes since V1:
> - Remove unprecise information about the DC process.
> - Expand the contribution list.
> - Rebase.
Acked-by: Christian König <christian.koenig@amd.com> for the whole series.
>
> Thanks
> Siqueira
>
> Rodrigo Siqueira (8):
> Documentation/gpu: Add basic page for HUBP
> Documentation/gpu: Add simple doc page for DCHUBBUB
> Documentation/gpu: Add kernel doc entry for DPP
> Documentation/gpu: Add kernel doc entry for MPC
> Documentation/gpu: Add entry for OPP in the kernel doc
> Documentation/gpu: Add entry for the DIO component
> Documentation/gpu: Add an explanation about the DC weekly patches
> Documentation/gpu: Introduce a simple contribution list for display
> code
>
> .../gpu/amdgpu/display/dcn-blocks.rst | 78 ++++++
> .../amdgpu/display/display-contributing.rst | 168 ++++++++++++
> .../gpu/amdgpu/display/display-manager.rst | 3 -
> Documentation/gpu/amdgpu/display/index.rst | 78 +++++-
> drivers/gpu/drm/amd/display/TODO | 110 --------
> .../gpu/drm/amd/display/dc/inc/hw/dchubbub.h | 6 +
> drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h | 26 ++
> drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h | 13 +-
> drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h | 250 ++++++++++++------
> drivers/gpu/drm/amd/display/dc/inc/hw/opp.h | 16 ++
> .../amd/display/dc/link/hwss/link_hwss_dio.h | 10 +
> 11 files changed, 560 insertions(+), 198 deletions(-)
> create mode 100644 Documentation/gpu/amdgpu/display/dcn-blocks.rst
> create mode 100644 Documentation/gpu/amdgpu/display/display-contributing.rst
> delete mode 100644 drivers/gpu/drm/amd/display/TODO
>
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH v2 0/8] Expand and improve AMDGPU documentation
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
` (9 preceding siblings ...)
2024-01-23 9:28 ` Christian König
@ 2024-01-23 16:19 ` Hamza Mahfooz
2024-01-25 18:49 ` Rodrigo Siqueira Jordao
10 siblings, 1 reply; 13+ messages in thread
From: Hamza Mahfooz @ 2024-01-23 16:19 UTC (permalink / raw
To: Rodrigo Siqueira, Alex Deucher, Christian König,
Mario Limonciello, Harry Wentland, Leo Li, Aurabindo Pillai,
Jani Nikula
Cc: amd-gfx, linux-doc
On 1/22/24 16:24, Rodrigo Siqueira wrote:
> This patchset improves how the AMDGPU display documentation is
> organized, expands the kernel-doc to extract information from the
> source, and adds more context about DC workflow. Finally, at the end of
> this series, we also introduce a contribution section for those
> interested in contributing to the display code.
>
> Changes since V1:
> - Remove unprecise information about the DC process.
> - Expand the contribution list.
> - Rebase.
>
> Thanks
> Siqueira
Series is:
Acked-by: Hamza Mahfooz <hamza.mahfooz@amd.com>
>
> Rodrigo Siqueira (8):
> Documentation/gpu: Add basic page for HUBP
> Documentation/gpu: Add simple doc page for DCHUBBUB
> Documentation/gpu: Add kernel doc entry for DPP
> Documentation/gpu: Add kernel doc entry for MPC
> Documentation/gpu: Add entry for OPP in the kernel doc
> Documentation/gpu: Add entry for the DIO component
> Documentation/gpu: Add an explanation about the DC weekly patches
> Documentation/gpu: Introduce a simple contribution list for display
> code
>
> .../gpu/amdgpu/display/dcn-blocks.rst | 78 ++++++
> .../amdgpu/display/display-contributing.rst | 168 ++++++++++++
> .../gpu/amdgpu/display/display-manager.rst | 3 -
> Documentation/gpu/amdgpu/display/index.rst | 78 +++++-
> drivers/gpu/drm/amd/display/TODO | 110 --------
> .../gpu/drm/amd/display/dc/inc/hw/dchubbub.h | 6 +
> drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h | 26 ++
> drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h | 13 +-
> drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h | 250 ++++++++++++------
> drivers/gpu/drm/amd/display/dc/inc/hw/opp.h | 16 ++
> .../amd/display/dc/link/hwss/link_hwss_dio.h | 10 +
> 11 files changed, 560 insertions(+), 198 deletions(-)
> create mode 100644 Documentation/gpu/amdgpu/display/dcn-blocks.rst
> create mode 100644 Documentation/gpu/amdgpu/display/display-contributing.rst
> delete mode 100644 drivers/gpu/drm/amd/display/TODO
>
--
Hamza
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH v2 0/8] Expand and improve AMDGPU documentation
2024-01-23 16:19 ` Hamza Mahfooz
@ 2024-01-25 18:49 ` Rodrigo Siqueira Jordao
0 siblings, 0 replies; 13+ messages in thread
From: Rodrigo Siqueira Jordao @ 2024-01-25 18:49 UTC (permalink / raw
To: Hamza Mahfooz, Alex Deucher, Christian König,
Mario Limonciello, Harry Wentland, Leo Li, Aurabindo Pillai,
Jani Nikula
Cc: amd-gfx, linux-doc
On 1/23/24 09:19, Hamza Mahfooz wrote:
> On 1/22/24 16:24, Rodrigo Siqueira wrote:
>> This patchset improves how the AMDGPU display documentation is
>> organized, expands the kernel-doc to extract information from the
>> source, and adds more context about DC workflow. Finally, at the end of
>> this series, we also introduce a contribution section for those
>> interested in contributing to the display code.
>>
>> Changes since V1:
>> - Remove unprecise information about the DC process.
>> - Expand the contribution list.
>> - Rebase.
>>
>> Thanks
>> Siqueira
>
> Series is:
> Acked-by: Hamza Mahfooz <hamza.mahfooz@amd.com>
>
>>
>> Rodrigo Siqueira (8):
>> Documentation/gpu: Add basic page for HUBP
>> Documentation/gpu: Add simple doc page for DCHUBBUB
>> Documentation/gpu: Add kernel doc entry for DPP
>> Documentation/gpu: Add kernel doc entry for MPC
>> Documentation/gpu: Add entry for OPP in the kernel doc
>> Documentation/gpu: Add entry for the DIO component
>> Documentation/gpu: Add an explanation about the DC weekly patches
>> Documentation/gpu: Introduce a simple contribution list for display
>> code
>>
>> .../gpu/amdgpu/display/dcn-blocks.rst | 78 ++++++
>> .../amdgpu/display/display-contributing.rst | 168 ++++++++++++
>> .../gpu/amdgpu/display/display-manager.rst | 3 -
>> Documentation/gpu/amdgpu/display/index.rst | 78 +++++-
>> drivers/gpu/drm/amd/display/TODO | 110 --------
>> .../gpu/drm/amd/display/dc/inc/hw/dchubbub.h | 6 +
>> drivers/gpu/drm/amd/display/dc/inc/hw/dpp.h | 26 ++
>> drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h | 13 +-
>> drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h | 250 ++++++++++++------
>> drivers/gpu/drm/amd/display/dc/inc/hw/opp.h | 16 ++
>> .../amd/display/dc/link/hwss/link_hwss_dio.h | 10 +
>> 11 files changed, 560 insertions(+), 198 deletions(-)
>> create mode 100644 Documentation/gpu/amdgpu/display/dcn-blocks.rst
>> create mode 100644
>> Documentation/gpu/amdgpu/display/display-contributing.rst
>> delete mode 100644 drivers/gpu/drm/amd/display/TODO
>>
Thanks!
Change pushed to amd-staging-drm-next.
^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2024-01-25 18:49 UTC | newest]
Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-01-22 21:24 [PATCH v2 0/8] Expand and improve AMDGPU documentation Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 1/8] Documentation/gpu: Add basic page for HUBP Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 2/8] Documentation/gpu: Add simple doc page for DCHUBBUB Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 3/8] Documentation/gpu: Add kernel doc entry for DPP Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 4/8] Documentation/gpu: Add kernel doc entry for MPC Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 5/8] Documentation/gpu: Add entry for OPP in the kernel doc Rodrigo Siqueira
2024-01-22 21:24 ` [PATCH v2 6/8] Documentation/gpu: Add entry for the DIO component Rodrigo Siqueira
2024-01-22 21:25 ` [PATCH v2 7/8] Documentation/gpu: Add an explanation about the DC weekly patches Rodrigo Siqueira
2024-01-22 21:25 ` [PATCH v2 8/8] Documentation/gpu: Introduce a simple contribution list for display code Rodrigo Siqueira
2024-01-22 22:48 ` [PATCH v2 0/8] Expand and improve AMDGPU documentation Mario Limonciello
2024-01-23 9:28 ` Christian König
2024-01-23 16:19 ` Hamza Mahfooz
2024-01-25 18:49 ` Rodrigo Siqueira Jordao
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).