From cdeec9a11c3c95f33a3e2be36ef3fabd60b8ebf2 Mon Sep 17 00:00:00 2001 From: Melissa Wen Date: Thu, 4 Aug 2022 14:01:04 -0100 Subject: Documentation/amdgpu_dm: Add DM color correction documentation AMDGPU DM maps DRM color management properties (degamma, ctm and gamma) to DC color correction entities. Part of this mapping is already documented as code comments and can be converted as kernel docs. v2: - rebase to amd-staging-drm-next - fix typos (Tales) - undo kernel-docs inside functions (Tales) Signed-off-by: Melissa Wen Reviewed-by: Harry Wentland Reviewed-by: Tales Aparecida Reviewed-by: Rodrigo Siqueira Signed-off-by: Alex Deucher --- Documentation/gpu/amdgpu/display/display-manager.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/amdgpu/display/display-manager.rst b/Documentation/gpu/amdgpu/display/display-manager.rst index 7ce31f89d9a0..b1b0f11aed83 100644 --- a/Documentation/gpu/amdgpu/display/display-manager.rst +++ b/Documentation/gpu/amdgpu/display/display-manager.rst @@ -40,3 +40,12 @@ Atomic Implementation .. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c :functions: amdgpu_dm_atomic_check amdgpu_dm_atomic_commit_tail + +Color Management Properties +=========================== + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c + :internal: -- cgit v1.2.3 From 78e16ac1e764def96f4c89b433d379acd68881c7 Mon Sep 17 00:00:00 2001 From: Melissa Wen Date: Thu, 4 Aug 2022 14:01:05 -0100 Subject: Documentation/amdgpu/display: add DC color caps info Add details about color correction capabilities and explain a bit about differences between DC hw generations and also how they are mapped between DRM and DC interface. Two schemas for DCN 2.0 and 3.0 (converted to svg from the original png) is included to illustrate it. They were obtained from a discussion[1] in the amd-gfx mailing list. [1] https://lore.kernel.org/amd-gfx/20220422142811.dm6vtk6v64jcwydk@mail.igalia.com/ v1: - remove redundant comments (Harry) - fix typos (Harry) v2: - reword introduction of color section - add co-dev tag for Harry - who provided most of the info - fix typos (Tales) - describe missing struct parameters (Tales and Siqueira) Co-developed-by: Harry Wentland Signed-off-by: Harry Wentland Signed-off-by: Melissa Wen Reviewed-by: Tales Aparecida Reviewed-by: Rodrigo Siqueira Signed-off-by: Alex Deucher --- .../gpu/amdgpu/display/dcn2_cm_drm_current.svg | 1370 ++++++++++++++++++ .../gpu/amdgpu/display/dcn3_cm_drm_current.svg | 1529 ++++++++++++++++++++ .../gpu/amdgpu/display/display-manager.rst | 34 + drivers/gpu/drm/amd/display/dc/dc.h | 77 +- 4 files changed, 2997 insertions(+), 13 deletions(-) create mode 100644 Documentation/gpu/amdgpu/display/dcn2_cm_drm_current.svg create mode 100644 Documentation/gpu/amdgpu/display/dcn3_cm_drm_current.svg (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/amdgpu/display/dcn2_cm_drm_current.svg b/Documentation/gpu/amdgpu/display/dcn2_cm_drm_current.svg new file mode 100644 index 000000000000..315ffc5a1a4b --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dcn2_cm_drm_current.svg @@ -0,0 +1,1370 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Matrix + 1D LUT + 3D LUT + Unpacking + Other + drm_framebuffer + format + drm_plane + drm_crtc + Stream + MPC + DPP + + Blender + Degamma + CTM + Gamma + format + bias_and_scale + color space matrix + input_csc_color_matrix + in_transfer_func + hdr_mult + gamut_remap_matrix + in_shaper_func + lut3d_func + blend_tf + Blender + gamut_remap_matrix + func_shaper + lut3d_func + out_transfer_func + csc_color_matrix + bit_depth_param + clamping + output_color_space + Plane + Legend + DCN 2.0 + DC Interface + DRM Interface + + CNVC + Input CSC + DeGammaRAM and ROM(sRGB, BT2020 + HDR Multiply + Gamut Remap + Shaper LUTRAM + 3D LUTRAM + Blend Gamma + Blender + GammaRAM + OCSC + + + color_encoding + + pixel_blend_mode + + color_range + + + + + + + + + + + + + + diff --git a/Documentation/gpu/amdgpu/display/dcn3_cm_drm_current.svg b/Documentation/gpu/amdgpu/display/dcn3_cm_drm_current.svg new file mode 100644 index 000000000000..7299ee9b6d64 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dcn3_cm_drm_current.svg @@ -0,0 +1,1529 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Matrix + 1D LUT + 3D LUT + Unpacking + Other + drm_framebuffer + format + drm_plane + drm_crtc + Stream + MPC + DPP + + Blender + Degamma + CTM + Gamma + format + bias_and_scale + color space matrix + input_csc_color_matrix + in_transfer_func + hdr_mult + gamut_remap_matrix + in_shaper_func + lut3d_func + blend_tf + Blender + gamut_remap_matrix + func_shaper + lut3d_func + out_transfer_func + csc_color_matrix + bit_depth_param + clamping + output_color_space + Plane + Legend + DCN 3.0 + DC Interface + DRM Interface + + CNVC + Input CSC + DeGammaROM(sRGB, BT2020, Gamma 2.2,PQ, HLG) + Post CSC + Gamma Correction + HDR Multiply + Gamut Remap + Shaper LUTRAM + 3D LUTRAM + Blend Gamma + Blender + Gamut Remap + Shaper LUTRAM + 3D LUTRAM + GammaRAM + OCSC + + + color_encoding + + pixel_blend_mode + + color_range + + + + + + + + + + + + + + + + + + diff --git a/Documentation/gpu/amdgpu/display/display-manager.rst b/Documentation/gpu/amdgpu/display/display-manager.rst index b1b0f11aed83..88e2c08c7014 100644 --- a/Documentation/gpu/amdgpu/display/display-manager.rst +++ b/Documentation/gpu/amdgpu/display/display-manager.rst @@ -49,3 +49,37 @@ Color Management Properties .. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c :internal: + + +DC Color Capabilities between DCN generations +--------------------------------------------- + +DRM/KMS framework defines three CRTC color correction properties: degamma, +color transformation matrix (CTM) and gamma, and two properties for degamma and +gamma LUT sizes. AMD DC programs some of the color correction features +pre-blending but DRM/KMS has not per-plane color correction properties. + +In general, the DRM CRTC color properties are programmed to DC, as follows: +CRTC gamma after blending, and CRTC degamma pre-blending. Although CTM is +programmed after blending, it is mapped to DPP hw blocks (pre-blending). Other +color caps available in the hw is not currently exposed by DRM interface and +are bypassed. + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/dc.h + :doc: color-management-caps + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/dc.h + :internal: + +The color pipeline has undergone major changes between DCN hardware +generations. What's possible to do before and after blending depends on +hardware capabilities, as illustrated below by the DCN 2.0 and DCN 3.0 families +schemas. + +**DCN 2.0 family color caps and mapping** + +.. kernel-figure:: dcn2_cm_drm_current.svg + +**DCN 3.0 family color caps and mapping** + +.. kernel-figure:: dcn3_cm_drm_current.svg diff --git a/drivers/gpu/drm/amd/display/dc/dc.h b/drivers/gpu/drm/amd/display/dc/dc.h index 8358a9b980af..cc2e9b572b87 100644 --- a/drivers/gpu/drm/amd/display/dc/dc.h +++ b/drivers/gpu/drm/amd/display/dc/dc.h @@ -118,7 +118,26 @@ struct dc_plane_cap { uint32_t min_height; }; -// Color management caps (DPP and MPC) +/** + * DOC: color-management-caps + * + * **Color management caps (DPP and MPC)** + * + * Modules/color calculates various color operations which are translated to + * abstracted HW. DCE 5-12 had almost no important changes, but starting with + * DCN1, every new generation comes with fairly major differences in color + * pipeline. Therefore, we abstract color pipe capabilities so modules/DM can + * decide mapping to HW block based on logical capabilities. + */ + +/** + * struct rom_curve_caps - predefined transfer function caps for degamma and regamma + * @srgb: RGB color space transfer func + * @bt2020: BT.2020 transfer func + * @gamma2_2: standard gamma + * @pq: perceptual quantizer transfer function + * @hlg: hybrid log–gamma transfer function + */ struct rom_curve_caps { uint16_t srgb : 1; uint16_t bt2020 : 1; @@ -127,36 +146,68 @@ struct rom_curve_caps { uint16_t hlg : 1; }; +/** + * struct dpp_color_caps - color pipeline capabilities for display pipe and + * plane blocks + * + * @dcn_arch: all DCE generations treated the same + * @input_lut_shared: shared with DGAM. Input LUT is different than most LUTs, + * just plain 256-entry lookup + * @icsc: input color space conversion + * @dgam_ram: programmable degamma LUT + * @post_csc: post color space conversion, before gamut remap + * @gamma_corr: degamma correction + * @hw_3d_lut: 3D LUT support. It implies a shaper LUT before. It may be shared + * with MPC by setting mpc:shared_3d_lut flag + * @ogam_ram: programmable out/blend gamma LUT + * @ocsc: output color space conversion + * @dgam_rom_for_yuv: pre-defined degamma LUT for YUV planes + * @dgam_rom_caps: pre-definied curve caps for degamma 1D LUT + * @ogam_rom_caps: pre-definied curve caps for regamma 1D LUT + * + * Note: hdr_mult and gamut remap (CTM) are always available in DPP (in that order) + */ struct dpp_color_caps { - uint16_t dcn_arch : 1; // all DCE generations treated the same - // input lut is different than most LUTs, just plain 256-entry lookup - uint16_t input_lut_shared : 1; // shared with DGAM + uint16_t dcn_arch : 1; + uint16_t input_lut_shared : 1; uint16_t icsc : 1; uint16_t dgam_ram : 1; - uint16_t post_csc : 1; // before gamut remap + uint16_t post_csc : 1; uint16_t gamma_corr : 1; - - // hdr_mult and gamut remap always available in DPP (in that order) - // 3d lut implies shaper LUT, - // it may be shared with MPC - check MPC:shared_3d_lut flag uint16_t hw_3d_lut : 1; - uint16_t ogam_ram : 1; // blnd gam + uint16_t ogam_ram : 1; uint16_t ocsc : 1; uint16_t dgam_rom_for_yuv : 1; struct rom_curve_caps dgam_rom_caps; struct rom_curve_caps ogam_rom_caps; }; +/** + * struct mpc_color_caps - color pipeline capabilities for multiple pipe and + * plane combined blocks + * + * @gamut_remap: color transformation matrix + * @ogam_ram: programmable out gamma LUT + * @ocsc: output color space conversion matrix + * @num_3dluts: MPC 3D LUT; always assumes a preceding shaper LUT + * @shared_3d_lut: shared 3D LUT flag. Can be either DPP or MPC, but single + * instance + * @ogam_rom_caps: pre-definied curve caps for regamma 1D LUT + */ struct mpc_color_caps { uint16_t gamut_remap : 1; uint16_t ogam_ram : 1; uint16_t ocsc : 1; - uint16_t num_3dluts : 3; //3d lut always assumes a preceding shaper LUT - uint16_t shared_3d_lut:1; //can be in either DPP or MPC, but single instance - + uint16_t num_3dluts : 3; + uint16_t shared_3d_lut:1; struct rom_curve_caps ogam_rom_caps; }; +/** + * struct dc_color_caps - color pipes capabilities for DPP and MPC hw blocks + * @dpp: color pipes caps for DPP + * @mpc: color pipes caps for MPC + */ struct dc_color_caps { struct dpp_color_caps dpp; struct mpc_color_caps mpc; -- cgit v1.2.3 From 43d61f6d8f4d2da7df116eac4f83106ab1a29090 Mon Sep 17 00:00:00 2001 From: Melissa Wen Date: Thu, 4 Aug 2022 14:01:06 -0100 Subject: drm/amd/display: add doc entries for MPC blending configuration Describe structs and enums used to set blend mode properties to MPC blocks. Some pieces of information are already available as code comments, and were just formatted. Others were collected and summarised from discussions on AMD issue tracker[1][2]. [1] https://gitlab.freedesktop.org/drm/amd/-/issues/1734 [2] https://gitlab.freedesktop.org/drm/amd/-/issues/1769 v2: - fix typos (Tales) - add MPCC to MPC entry in the glossary Signed-off-by: Melissa Wen Reviewed-by: Tales Aparecida Reviewed-by: Rodrigo Siqueira Signed-off-by: Alex Deucher --- Documentation/gpu/amdgpu/display/dc-glossary.rst | 2 +- drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h | 91 ++++++++++++++++++++---- 2 files changed, 78 insertions(+), 15 deletions(-) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/amdgpu/display/dc-glossary.rst b/Documentation/gpu/amdgpu/display/dc-glossary.rst index 116f5f0942fd..0b0ffd428dd2 100644 --- a/Documentation/gpu/amdgpu/display/dc-glossary.rst +++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst @@ -170,7 +170,7 @@ consider asking in the amdgfx and update this page. MC Memory Controller - MPC + MPC/MPCC Multiple pipes and plane combine MPO 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 5097037e3962..8d86159d9de0 100644 --- a/drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h +++ b/drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h @@ -22,6 +22,16 @@ * */ +/** + * DOC: mpc-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. + */ + #ifndef __DC_MPCC_H__ #define __DC_MPCC_H__ @@ -48,14 +58,39 @@ enum mpcc_blend_mode { MPCC_BLEND_MODE_TOP_BOT_BLENDING }; +/** + * enum mpcc_alpha_blend_mode - define the alpha blend mode regarding pixel + * alpha and plane alpha values + */ enum mpcc_alpha_blend_mode { + /** + * @MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA: per pixel alpha using DPP + * alpha value + */ MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA, + /** + * @MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA_COMBINED_GLOBAL_GAIN: per + * pixel alpha using DPP alpha value multiplied by a global gain (plane + * alpha) + */ MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA_COMBINED_GLOBAL_GAIN, + /** + * @MPCC_ALPHA_BLEND_MODE_GLOBAL_ALPHA: global alpha value, ignores + * pixel alpha and consider only plane alpha + */ MPCC_ALPHA_BLEND_MODE_GLOBAL_ALPHA }; -/* - * MPCC blending configuration +/** + * 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 */ struct mpcc_blnd_cfg { struct tg_color black_color; /* background color */ @@ -107,8 +142,15 @@ struct mpc_dwb_flow_control { int flow_ctrl_cnt1; }; -/* - * MPCC connection and blending configuration for a single MPCC instance. +/** + * 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 { @@ -120,8 +162,12 @@ struct mpcc { bool shared_bottom; /* TRUE if MPCC output to both OPP and DWB endpoints, else FALSE */ }; -/* - * MPC tree represents all MPCC connections for a pipe. +/** + * 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 */ @@ -149,13 +195,18 @@ struct mpcc_state { uint32_t busy; }; +/** + * struct mpc_funcs - funcs + */ struct mpc_funcs { void (*read_mpcc_state)( struct mpc *mpc, int mpcc_inst, struct mpcc_state *s); - /* + /** + * @insert_plane: + * * Insert DPP into MPC tree based on specified blending position. * Only used for planes that are part of blending chain for OPP output * @@ -180,7 +231,9 @@ struct mpc_funcs { int dpp_id, int mpcc_id); - /* + /** + * @remove_mpcc: + * * Remove a specified MPCC from the MPC tree. * * Parameters: @@ -195,7 +248,9 @@ struct mpc_funcs { struct mpc_tree *tree, struct mpcc *mpcc); - /* + /** + * @mpc_init: + * * Reset the MPCC HW status by disconnecting all muxes. * * Parameters: @@ -208,7 +263,9 @@ struct mpc_funcs { struct mpc *mpc, unsigned int mpcc_id); - /* + /** + * @update_blending: + * * Update the blending configuration for a specified MPCC. * * Parameters: @@ -223,7 +280,9 @@ struct mpc_funcs { struct mpcc_blnd_cfg *blnd_cfg, int mpcc_id); - /* + /** + * @cursor_lock: + * * Lock cursor updates for the specified OPP. * OPP defines the set of MPCC that are locked together for cursor. * @@ -239,8 +298,10 @@ struct mpc_funcs { int opp_id, bool lock); - /* - * Add DPP into 'secondary' MPC tree based on specified blending position. + /** + * @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 * * Parameters: @@ -264,7 +325,9 @@ struct mpc_funcs { int dpp_id, int mpcc_id); - /* + /** + * @remove_mpcc_from_secondary: + * * Remove a specified DPP from the 'secondary' MPC tree. * * Parameters: -- cgit v1.2.3 From 33fa4f1df53076d0078be091d5a88d457de54936 Mon Sep 17 00:00:00 2001 From: Melissa Wen Date: Thu, 4 Aug 2022 14:01:07 -0100 Subject: Documentation/gpu/amdgpu/amdgpu_dm: add DM docs for pixel blend mode AMD GPU display manager (DM) maps DRM pixel blend modes (None, Pre-multiplied, Coverage) to MPC hw blocks through blend configuration options. Describe relevant elements and how to set and test them to get the expected DRM blend mode on DCN hw. v2: - add ref tag (Tales) Signed-off-by: Melissa Wen Reviewed-by: Tales Aparecida Reviewed-by: Rodrigo Siqueira Signed-off-by: Alex Deucher --- .../gpu/amdgpu/display/display-manager.rst | 98 ++++++++++++++++++++++ Documentation/gpu/drm-kms.rst | 2 + 2 files changed, 100 insertions(+) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/amdgpu/display/display-manager.rst b/Documentation/gpu/amdgpu/display/display-manager.rst index 88e2c08c7014..b7abb18cfc82 100644 --- a/Documentation/gpu/amdgpu/display/display-manager.rst +++ b/Documentation/gpu/amdgpu/display/display-manager.rst @@ -83,3 +83,101 @@ schemas. **DCN 3.0 family color caps and mapping** .. kernel-figure:: dcn3_cm_drm_current.svg + +Blend Mode Properties +===================== + +Pixel blend mode is a DRM plane composition property of :c:type:`drm_plane` used to +describes how pixels from a foreground plane (fg) are composited with the +background plane (bg). Here, we present main concepts of DRM blend mode to help +to understand how this property is mapped to AMD DC interface. See more about +this DRM property and the alpha blending equations in :ref:`DRM Plane +Composition Properties `. + +Basically, a blend mode sets the alpha blending equation for plane +composition that fits the mode in which the alpha channel affects the state of +pixel color values and, therefore, the resulted pixel color. For +example, consider the following elements of the alpha blending equation: + +- *fg.rgb*: Each of the RGB component values from the foreground's pixel. +- *fg.alpha*: Alpha component value from the foreground's pixel. +- *bg.rgb*: Each of the RGB component values from the background. +- *plane_alpha*: Plane alpha value set by the **plane "alpha" property**, see + more in :ref:`DRM Plane Composition Properties `. + +in the basic alpha blending equation:: + + out.rgb = alpha * fg.rgb + (1 - alpha) * bg.rgb + +the alpha channel value of each pixel in a plane is ignored and only the plane +alpha affects the resulted pixel color values. + +DRM has three blend mode to define the blend formula in the plane composition: + +* **None**: Blend formula that ignores the pixel alpha. + +* **Pre-multiplied**: Blend formula that assumes the pixel color values in a + plane was already pre-multiplied by its own alpha channel before storage. + +* **Coverage**: Blend formula that assumes the pixel color values were not + pre-multiplied with the alpha channel values. + +and pre-multiplied is the default pixel blend mode, that means, when no blend +mode property is created or defined, DRM considers the plane's pixels has +pre-multiplied color values. On IGT GPU tools, the kms_plane_alpha_blend test +provides a set of subtests to verify plane alpha and blend mode properties. + +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 + +Therefore, the blending configuration for a single MPCC instance on the MPC +tree is defined by :c:type:`mpcc_blnd_cfg`, where +:c:type:`pre_multiplied_alpha` is the alpha pre-multiplied mode flag used to +set :c:type:`MPCC_ALPHA_MULTIPLIED_MODE`. It controls whether alpha is +multiplied (true/false), being only true for DRM pre-multiplied blend mode. +:c:type:`mpcc_alpha_blend_mode` defines the alpha blend mode regarding pixel +alpha and plane alpha values. It sets one of the three modes for +:c:type:`MPCC_ALPHA_BLND_MODE`, as described below. + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h + :functions: mpcc_alpha_blend_mode + +DM then maps the elements of `enum mpcc_alpha_blend_mode` to those in the DRM +blend formula, as follows: + +* *MPC pixel alpha* matches *DRM fg.alpha* as the alpha component value + from the plane's pixel +* *MPC global alpha* matches *DRM plane_alpha* when the pixel alpha should + be ignored and, therefore, pixel values are not pre-multiplied +* *MPC global gain* assumes *MPC global alpha* value when both *DRM + fg.alpha* and *DRM plane_alpha* participate in the blend equation + +In short, *fg.alpha* is ignored by selecting +:c:type:`MPCC_ALPHA_BLEND_MODE_GLOBAL_ALPHA`. On the other hand, (plane_alpha * +fg.alpha) component becomes available by selecting +:c:type:`MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA_COMBINED_GLOBAL_GAIN`. And the +:c:type:`MPCC_ALPHA_MULTIPLIED_MODE` defines if the pixel color values are +pre-multiplied by alpha or not. + +Blend configuration flow +------------------------ + +The alpha blending equation is configured from DRM to DC interface by the +following path: + +1. When updating a :c:type:`drm_plane_state `, DM calls + :c:type:`fill_blending_from_plane_state()` that maps + :c:type:`drm_plane_state ` attributes to + :c:type:`dc_plane_info ` struct to be handled in the + OS-agnostic component (DC). + +2. On DC interface, :c:type:`struct mpcc_blnd_cfg ` programs the + MPCC blend configuration considering the :c:type:`dc_plane_info + ` input from DPP. diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 6f9c064fd323..b4377a545425 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -532,6 +532,8 @@ Standard Plane Properties .. kernel-doc:: drivers/gpu/drm/drm_plane.c :doc: standard plane properties +.. _plane_composition_properties: + Plane Composition Properties ---------------------------- -- cgit v1.2.3 From e76115963be1700400405d300150eccf0e31cad0 Mon Sep 17 00:00:00 2001 From: André Almeida Date: Wed, 10 Aug 2022 20:28:57 -0300 Subject: Documentation/gpu: Document GFXOFF's count and residency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation explaining those two new files. While here, add a note about the value type. Signed-off-by: André Almeida Signed-off-by: Alex Deucher --- Documentation/gpu/amdgpu/thermal.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/amdgpu/thermal.rst b/Documentation/gpu/amdgpu/thermal.rst index 997231b6adcf..5e27e4eb3959 100644 --- a/Documentation/gpu/amdgpu/thermal.rst +++ b/Documentation/gpu/amdgpu/thermal.rst @@ -72,7 +72,8 @@ card's RLC (RunList Controller) firmware powers off the gfx engine dynamically when there is no workload on gfx or compute pipes. GFXOFF is on by default on supported GPUs. -Userspace can interact with GFXOFF through a debugfs interface: +Userspace can interact with GFXOFF through a debugfs interface (all values in +`uint32_t`, unless otherwise noted): ``amdgpu_gfxoff`` ----------------- @@ -104,3 +105,18 @@ Read it to check current GFXOFF's status of a GPU:: If GFXOFF is enabled, the value will be transitioning around [0, 3], always getting into 0 when possible. When it's disabled, it's always at 2. Returns ``-EINVAL`` if it's not supported. + +``amdgpu_gfxoff_count`` +----------------------- + +Read it to get the total GFXOFF entry count at the time of query since system +power-up. The value is an `uint64_t` type, however, due to firmware limitations, +it can currently overflow as an `uint32_t`. *Only supported in vangogh* + +``amdgpu_gfxoff_residency`` +--------------------------- + +Write 1 to amdgpu_gfxoff_residency to start logging, and 0 to stop. Read it to +get average GFXOFF residency % multiplied by 100 during the last logging +interval. E.g. a value of 7854 means 78.54% of the time in the last logging +interval the GPU was in GFXOFF mode. *Only supported in vangogh* -- cgit v1.2.3 From 9d9b217d52b41f6d99279211b83c26b2484a142b Mon Sep 17 00:00:00 2001 From: Rodrigo Siqueira Date: Thu, 11 Aug 2022 11:48:17 -0400 Subject: Documentation/gpu: Add info table for ASICs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Amdgpu driver is used in an extensive range of devices, and each ASIC has some specific configuration. As a result of this variety, sometimes it is hard to identify the correct block that might cause the issue. This commit expands the amdgpu kernel-doc to alleviate this issue by introducing one ASIC table that describes dGPU and another one that shares the APU info. Cc: Harry Wentland Cc: Nicholas Kazlauskas Cc: Bhawanpreet Lakha Cc: Hersen Wu Cc: Alex Hung Cc: Pierre-Eric Pelloux-Prayer Cc: Leo Li Cc: Simon Ser Cc: Pekka Paalanen Cc: Sean Paul Cc: Mark Yacoub Cc: Pierre-Loup Cc: Michel Dänzer Cc: Kent Russell Reviewed-by: Harry Wentland Signed-off-by: Rodrigo Siqueira Signed-off-by: Alex Deucher --- Documentation/gpu/amdgpu/apu-asic-info-table.csv | 8 ++++++++ Documentation/gpu/amdgpu/dgpu-asic-info-table.csv | 24 +++++++++++++++++++++++ Documentation/gpu/amdgpu/driver-misc.rst | 17 ++++++++++++++++ 3 files changed, 49 insertions(+) create mode 100644 Documentation/gpu/amdgpu/apu-asic-info-table.csv create mode 100644 Documentation/gpu/amdgpu/dgpu-asic-info-table.csv (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/amdgpu/apu-asic-info-table.csv b/Documentation/gpu/amdgpu/apu-asic-info-table.csv new file mode 100644 index 000000000000..98c6988e424e --- /dev/null +++ b/Documentation/gpu/amdgpu/apu-asic-info-table.csv @@ -0,0 +1,8 @@ +Product Name, Code Reference, DCN/DCE version, GC version, VCE/UVD/VCN version, SDMA version +Radeon R* Graphics, CARRIZO/STONEY, DCE 11, 8, VCE 3 / UVD 6, 3 +Ryzen 3000 series / AMD Ryzen Embedded V1*/R1* with Radeon Vega Gfx, RAVEN/PICASSO, DCN 1.0, 9.1.0, VCN 1.0, 4.1.0 +Ryzen 4000 series, RENOIR, DCN 2.1, 9.3, VCN 2.2, 4.1.2 +Ryzen 3000 series / AMD Ryzen Embedded V1*/R1* with Radeon Vega Gfx, RAVEN2, DCN 1.0, 9.2.2, VCN 1.0.1, 4.1.1 +SteamDeck, VANGOGH, DCN 3.0.1, 10.3.1, VCN 3.1.0, 5.2.1 +Ryzen 5000 series, GREEN SARDINE, DCN 2.1, 9.3, VCN 2.2, 4.1.1 +Ryzen 6000 Zen, YELLOW CARP, 3.1.2, 10.3.3, VCN 3.1.1, 5.2.3 diff --git a/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv b/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv new file mode 100644 index 000000000000..84617aa35dab --- /dev/null +++ b/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv @@ -0,0 +1,24 @@ +Product Name, Code Reference, DCN/DCE version, GC version, VCN version, SDMA version +AMD Radeon (TM) HD 8500M/ 8600M /M200 /M320 /M330 /M335 Series, HAINAN, --, 6, --, -- +AMD Radeon HD 7800 /7900 /FireGL Series, TAHITI, DCE 6, 6, VCE 1 / UVD 3, -- +AMD Radeon R7 (TM|HD) M265 /M370 /8500M /8600 /8700 /8700M, OLAND, DCE 6, 6, VCE 1 / UVD 3, -- +AMD Radeon (TM) (HD|R7) 7800 /7970 /8800 /8970 /370/ Series, PITCAIRN, DCE 6, 6, VCE 1 / UVD 3, -- +AMD Radeon (TM|R7|R9|HD) E8860 /M360 /7700 /7800 /8800 /9000(M) /W4100 Series, VERDE, DCE 6, 6, VCE 1 / UVD 3, -- +AMD Radeon HD M280X /M380 /7700 /8950 /W5100, BONAIRE, DCE 8, 7, VCE 2 / UVD 4.2, 1 +AMD Radeon (R9|TM) 200 /390 /W8100 /W9100 Series, HAWAII, DCE 8, 7, VCE 2 / UVD 4.2, 1 +AMD Radeon (TM) R(5|7) M315 /M340 /M360, TOPAZ, *, 8, --, 2 +AMD Radeon (TM) R9 200 /380 /W7100 /S7150 /M390 /M395 Series, TONGA, DCE 10, 8, VCE 3 / UVD 5, 3 +AMD Radeon (FirePro) (TM) R9 Fury Series, FIJI, DCE 10, 8, VCE 3 / UVD 6, 3 +Radeon RX 470 /480 /570 /580 /590 Series - AMD Radeon (TM) (Pro WX) 5100 /E9390 /E9560 /E9565 /V7350 /7100 /P30PH, POLARIS10, DCE 11.2, 8, VCE 3.4 / UVD 6.3, 3 +Radeon (TM) (RX|Pro WX) E9260 /460 /V5300X /550 /560(X) Series, POLARIS11, DCE 11.2, 8, VCE 3.4 / UVD 6.3, 3 +Radeon (RX/Pro) 500 /540(X) /550 /640 /WX2100 /WX3100 /WX200 Series, POLARIS12, DCE 11.2, 8, VCE 3.4 / UVD 6.3, 3 +Radeon (RX|TM) (PRO|WX) Vega /MI25 /V320 /V340L /8200 /9100 /SSG MxGPU, VEGA10, DCE 12, 9.0.1, VCE 4.0.0 / UVD 7.0.0, 4.0.0 +AMD Radeon (Pro) VII /MI50 /MI60, VEGA20, DCE 12, 9.4.0, VCE 4.1.0 / UVD 7.2.0, 4.2.0 +MI100, ARCTURUS, *, 9.4.1, VCN 2.5.0, 4.2.2 +MI200, ALDEBARAN, *, 9.4.2, VCN 2.6.0, 4.4.0 +AMD Radeon (RX|Pro) 5600(M|XT) /5700 (M|XT|XTB) /W5700, NAVI10, DCN 2.0.0, 10.1.10, VCN 2.0.0, 5.0.0 +AMD Radeon (Pro) 5300 /5500XTB/5500(XT|M) /W5500M /W5500, NAVI14, DCN 2.0.0, 10.1.1, VCN 2.0.2, 5.0.2 +AMD Radeon RX 6800(XT) /6900(XT) /W6800, SIENNA_CICHLID, DCN 3.0.0, 10.3.0, VCN 3.0.0, 5.2.0 +AMD Radeon RX 6700 XT / 6800M / 6700M, NAVY_FLOUNDER, DCN 3.0.0, 10.3.2, VCN 3.0.0, 5.2.2 +AMD Radeon RX 6600(XT) /6600M /W6600 /W6600M, DIMGREY_CAVEFISH, DCN 3.0.2, 10.3.4, VCN 3.0.16, 5.2.4 +AMD Radeon RX 6500M /6300M /W6500M /W6300M, BEIGE_GOBY, DCN 3.0.3, 10.3.5, VCN 3.0.33, 5.2.5 diff --git a/Documentation/gpu/amdgpu/driver-misc.rst b/Documentation/gpu/amdgpu/driver-misc.rst index e3d6b2fa2493..1800543d45f7 100644 --- a/Documentation/gpu/amdgpu/driver-misc.rst +++ b/Documentation/gpu/amdgpu/driver-misc.rst @@ -32,6 +32,23 @@ unique_id .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c :doc: unique_id +Accelerated Processing Units (APU) Info +--------------------------------------- + +.. csv-table:: + :header-rows: 1 + :widths: 3, 2, 2, 1, 1, 1 + :file: ./apu-asic-info-table.csv + +Discrete GPU Info +----------------- + +.. csv-table:: + :header-rows: 1 + :widths: 3, 2, 2, 1, 1, 1 + :file: ./dgpu-asic-info-table.csv + + GPU Memory Usage Information ============================ -- cgit v1.2.3 From 330d6da3d03cca592d2101d0f25f01a611c4405b Mon Sep 17 00:00:00 2001 From: Rodrigo Siqueira Date: Thu, 11 Aug 2022 11:48:18 -0400 Subject: Documentation/gpu: Add an explanation about the DCN pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In the DCN code, we constantly talk about hardware pipeline, pipeline, or even just pipes, which is a concept that is not obvious to everyone. For this reason, this commit expands the DCN overview explanation by adding a new section that describes what a pipeline is from the DCN perspective. Changes since V1: - Rewrite the first paragraph that describes AMD hardware pipeline. Cc: Harry Wentland Cc: Nicholas Kazlauskas Cc: Bhawanpreet Lakha Cc: Hersen Wu Cc: Alex Hung Cc: Pierre-Eric Pelloux-Prayer Cc: Leo Li Cc: Simon Ser Cc: Pekka Paalanen Cc: Sean Paul Cc: Mark Yacoub Cc: Pierre-Loup Cc: Michel Dänzer Reviewed-by: Harry Wentland Signed-off-by: Rodrigo Siqueira Signed-off-by: Alex Deucher --- Documentation/gpu/amdgpu/display/dcn-overview.rst | 59 ++ .../gpu/amdgpu/display/pipeline_4k_no_split.svg | 958 ++++++++++++++++++ .../gpu/amdgpu/display/pipeline_4k_split.svg | 1062 ++++++++++++++++++++ 3 files changed, 2079 insertions(+) create mode 100644 Documentation/gpu/amdgpu/display/pipeline_4k_no_split.svg create mode 100644 Documentation/gpu/amdgpu/display/pipeline_4k_split.svg (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/amdgpu/display/dcn-overview.rst b/Documentation/gpu/amdgpu/display/dcn-overview.rst index f98624d7828e..9fea6500448b 100644 --- a/Documentation/gpu/amdgpu/display/dcn-overview.rst +++ b/Documentation/gpu/amdgpu/display/dcn-overview.rst @@ -124,6 +124,65 @@ depth format), bit-depth reduction/dithering would kick in. In OPP, we would also apply a regamma function to introduce the gamma removed earlier back. Eventually, we output data in integer format at DIO. +AMD Hardware Pipeline +--------------------- + +When discussing graphics on Linux, the **pipeline** term can sometimes be +overloaded with multiple meanings, so it is important to define what we mean +when we say **pipeline**. In the DCN driver, we use the term **hardware +pipeline** or **pipeline** or just **pipe** as an abstraction to indicate a +sequence of DCN blocks instantiated to address some specific configuration. DC +core treats DCN blocks as individual resources, meaning we can build a pipeline +by taking resources for all individual hardware blocks to compose one pipeline. +In actuality, we can't connect an arbitrary block from one pipe to a block from +another pipe; they are routed linearly, except for DSC, which can be +arbitrarily assigned as needed. We have this pipeline concept for trying to +optimize bandwidth utilization. + +.. kernel-figure:: pipeline_4k_no_split.svg + +Additionally, let's take a look at parts of the DTN log (see +'Documentation/gpu/amdgpu/display/dc-debug.rst' for more information) since +this log can help us to see part of this pipeline behavior in real-time:: + + HUBP: format addr_hi width height ... + [ 0]: 8h 81h 3840 2160 + [ 1]: 0h 0h 0 0 + [ 2]: 0h 0h 0 0 + [ 3]: 0h 0h 0 0 + [ 4]: 0h 0h 0 0 + ... + MPCC: OPP DPP ... + [ 0]: 0h 0h ... + +The first thing to notice from the diagram and DTN log it is the fact that we +have different clock domains for each part of the DCN blocks. In this example, +we have just a single **pipeline** where the data flows from DCHUB to DIO, as +we intuitively expect. Nonetheless, DCN is flexible, as mentioned before, and +we can split this single pipe differently, as described in the below diagram: + +.. kernel-figure:: pipeline_4k_split.svg + +Now, if we inspect the DTN log again we can see some interesting changes:: + + HUBP: format addr_hi width height ... + [ 0]: 8h 81h 1920 2160 ... + ... + [ 4]: 0h 0h 0 0 ... + [ 5]: 8h 81h 1920 2160 ... + ... + MPCC: OPP DPP ... + [ 0]: 0h 0h ... + [ 5]: 0h 5h ... + +From the above example, we now split the display pipeline into two vertical +parts of 1920x2160 (i.e., 3440x2160), and as a result, we could reduce the +clock frequency in the DPP part. This is not only useful for saving power but +also to better handle the required throughput. The idea to keep in mind here is +that the pipe configuration can vary a lot according to the display +configuration, and it is the DML's responsibility to set up all required +configuration parameters for multiple scenarios supported by our hardware. + Global Sync ----------- diff --git a/Documentation/gpu/amdgpu/display/pipeline_4k_no_split.svg b/Documentation/gpu/amdgpu/display/pipeline_4k_no_split.svg new file mode 100644 index 000000000000..5fa289d99fcd --- /dev/null +++ b/Documentation/gpu/amdgpu/display/pipeline_4k_no_split.svg @@ -0,0 +1,958 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + DCHUB + + DPP(0) + + + + + HUBP(0) + + + + + + HUBP(1) + + + + + + HUBP(5) + + + + + ... + + ... + + + MPC(0) + + + + OPP(0) + + + ... + + + + OPTC + + + + ... + + SDP + + + + DPPCLK535.916Mhz + DISPCLK541.275 Mhz + DCFCLK506 Mhz + SymCLK + + DIO + + + + VirtualPCLK + + + diff --git a/Documentation/gpu/amdgpu/display/pipeline_4k_split.svg b/Documentation/gpu/amdgpu/display/pipeline_4k_split.svg new file mode 100644 index 000000000000..b43119e7eb8a --- /dev/null +++ b/Documentation/gpu/amdgpu/display/pipeline_4k_split.svg @@ -0,0 +1,1062 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + DCHUB + + DPP(0) + + + + + HUBP(0) + + + + + + HUBP(1) + + + + + + HUBP(5) + + + + + ... + + DPP(5) + + + + + ... + + + MPC(0) + + + + MPC(5) + + + + OPP(0) + + + ... + + + + + OPP(0) + + + + + OPTC + + + + + ... + + SDP + + + + DPPCLK267.958Mhz + DISPCLK541.275 Mhz + DCFCLK506 Mhz + SymCLK + + DIO + + + + VirtualPCLK + + + -- cgit v1.2.3 From 6c49df92faa2931ed7269e23a4c2740d3b8687e4 Mon Sep 17 00:00:00 2001 From: Rodrigo Siqueira Date: Thu, 11 Aug 2022 11:48:19 -0400 Subject: Documentation/gpu: Add Multiplane Overlay doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Multiple plane overlay is a feature supported by AMD hardware, but it has specific details that deserve proper documentation. This commit introduces a documentation that describes some of the features, limitations, and use cases for this feature. Part of this documentation came from some discussion in the public upstream [1][2]. [1]. https://lore.kernel.org/amd-gfx/3qY-QeukF_Q_MJeIXAuBjO4szbS4jRtqkTifXnbnN3bp88SxVodFQRpah3mIIVJq24DUkF6g0rOGdCmSqTvVxx9LCGEItmzLw8uWU44jtXE=@emersion.fr/ [2]. https://lore.kernel.org/amd-gfx/864e45d0-c14b-3b12-0f5b-9d26a9cb41bd@amd.com/ Cc: Harry Wentland Cc: Nicholas Kazlauskas Cc: Bhawanpreet Lakha Cc: Hersen Wu Cc: Alex Hung Cc: Pierre-Eric Pelloux-Prayer Cc: Simon Ser Cc: Pekka Paalanen Cc: Sean Paul Cc: Mark Yacoub Cc: Leo Li Cc: Pierre-Loup Cc: Michel Dänzer Reviewed-by: Harry Wentland Signed-off-by: Rodrigo Siqueira Signed-off-by: Alex Deucher --- Documentation/gpu/amdgpu/display/index.rst | 1 + Documentation/gpu/amdgpu/display/mpo-cursor.svg | 435 +++++++++++++++++++++ Documentation/gpu/amdgpu/display/mpo-overview.rst | 242 ++++++++++++ .../multi-display-hdcp-mpo-less-pipe-ex.svg | 220 +++++++++++ .../gpu/amdgpu/display/multi-display-hdcp-mpo.svg | 171 ++++++++ .../display/single-display-mpo-multi-video.svg | 339 ++++++++++++++++ .../gpu/amdgpu/display/single-display-mpo.svg | 266 +++++++++++++ 7 files changed, 1674 insertions(+) create mode 100644 Documentation/gpu/amdgpu/display/mpo-cursor.svg create mode 100644 Documentation/gpu/amdgpu/display/mpo-overview.rst create mode 100644 Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo-less-pipe-ex.svg create mode 100644 Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo.svg create mode 100644 Documentation/gpu/amdgpu/display/single-display-mpo-multi-video.svg create mode 100644 Documentation/gpu/amdgpu/display/single-display-mpo.svg (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst index c1fb2fb3c710..f8a4f53d70d8 100644 --- a/Documentation/gpu/amdgpu/display/index.rst +++ b/Documentation/gpu/amdgpu/display/index.rst @@ -28,4 +28,5 @@ table of content: display-manager.rst dc-debug.rst dcn-overview.rst + mpo-overview.rst dc-glossary.rst diff --git a/Documentation/gpu/amdgpu/display/mpo-cursor.svg b/Documentation/gpu/amdgpu/display/mpo-cursor.svg new file mode 100644 index 000000000000..9d9de76847c3 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/mpo-cursor.svg @@ -0,0 +1,435 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + Cursor + + + + Plane 1 + + + + Plane 2 + + + + + CRTC + + + + Cursor + + + + Plane 1 + + + + Plane 2 + + + + CRTC + + DRM + AMD Hardware + + + + + + + + + diff --git a/Documentation/gpu/amdgpu/display/mpo-overview.rst b/Documentation/gpu/amdgpu/display/mpo-overview.rst new file mode 100644 index 000000000000..0499aa92d08d --- /dev/null +++ b/Documentation/gpu/amdgpu/display/mpo-overview.rst @@ -0,0 +1,242 @@ +======================== +Multiplane Overlay (MPO) +======================== + +.. note:: You will get more from this page if you have already read the + 'Documentation/gpu/amdgpu/display/dcn-overview.rst'. + + +Multiplane Overlay (MPO) allows for multiple framebuffers to be composited via +fixed-function hardware in the display controller rather than using graphics or +compute shaders for composition. This can yield some power savings if it means +the graphics/compute pipelines can be put into low-power states. In summary, +MPO can bring the following benefits: + +* Decreased GPU and CPU workload - no composition shaders needed, no extra + buffer copy needed, GPU can remain idle. +* Plane independent page flips - No need to be tied to global compositor + page-flip present rate, reduced latency, independent timing. + +.. note:: Keep in mind that MPO is all about power-saving; if you want to learn + more about power-save in the display context, check the link: + `Power `__. + +Multiplane Overlay is only available using the DRM atomic model. The atomic +model only uses a single userspace IOCTL for configuring the display hardware +(modesetting, page-flipping, etc) - drmModeAtomicCommit. To query hardware +resources and limitations userspace also calls into drmModeGetResources which +reports back the number of planes, CRTCs, and connectors. There are three types +of DRM planes that the driver can register and work with: + +* ``DRM_PLANE_TYPE_PRIMARY``: Primary planes represent a "main" plane for a + CRTC, primary planes are the planes operated upon by CRTC modesetting and + flipping operations. +* ``DRM_PLANE_TYPE_CURSOR``: Cursor planes represent a "cursor" plane for a + CRTC. Cursor planes are the planes operated upon by the cursor IOCTLs +* ``DRM_PLANE_TYPE_OVERLAY``: Overlay planes represent all non-primary, + non-cursor planes. Some drivers refer to these types of planes as "sprites" + internally. + +To illustrate how it works, let's take a look at a device that exposes the +following planes to userspace: + +* 4 Primary planes (1 per CRTC). +* 4 Cursor planes (1 per CRTC). +* 1 Overlay plane (shared among CRTCs). + +.. note:: Keep in mind that different ASICs might expose other numbers of + planes. + +For this hardware example, we have 4 pipes (if you don't know what AMD pipe +means, look at 'Documentation/gpu/amdgpu/display/dcn-overview.rst', section +"AMD Hardware Pipeline"). Typically most AMD devices operate in a pipe-split +configuration for optimal single display output (e.g., 2 pipes per plane). + +A typical MPO configuration from userspace - 1 primary + 1 overlay on a single +display - will see 4 pipes in use, 2 per plane. + +At least 1 pipe must be used per plane (primary and overlay), so for this +hypothetical hardware that we are using as an example, we have an absolute +limit of 4 planes across all CRTCs. Atomic commits will be rejected for display +configurations using more than 4 planes. Again, it is important to stress that +every DCN has different restrictions; here, we are just trying to provide the +concept idea. + +Plane Restrictions +================== + +AMDGPU imposes restrictions on the use of DRM planes in the driver. + +Atomic commits will be rejected for commits which do not follow these +restrictions: + +* Overlay planes must be in ARGB8888 or XRGB8888 format +* Planes cannot be placed outside of the CRTC destination rectangle +* Planes cannot be downscaled more than 1/4x of their original size +* Planes cannot be upscaled more than 16x of their original size + +Not every property is available on every plane: + +* Only primary planes have color-space and non-RGB format support +* Only overlay planes have alpha blending support + +Cursor Restrictions +=================== + +Before we start to describe some restrictions around cursor and MPO, see the +below image: + +.. kernel-figure:: mpo-cursor.svg + +The image on the left side represents how DRM expects the cursor and planes to +be blended. However, AMD hardware handles cursors differently, as you can see +on the right side; basically, our cursor cannot be drawn outside its associated +plane as it is being treated as part of the plane. Another consequence of that +is that cursors inherit the color and scale from the plane. + +As a result of the above behavior, do not use legacy API to set up the cursor +plane when working with MPO; otherwise, you might encounter unexpected +behavior. + +In short, AMD HW has no dedicated cursor planes. A cursor is attached to +another plane and therefore inherits any scaling or color processing from its +parent plane. + +Use Cases +========= + +Picture-in-Picture (PIP) playback - Underlay strategy +----------------------------------------------------- + +Video playback should be done using the "primary plane as underlay" MPO +strategy. This is a 2 planes configuration: + +* 1 YUV DRM Primary Plane (e.g. NV12 Video) +* 1 RGBA DRM Overlay Plane (e.g. ARGB8888 desktop). The compositor should + prepare the framebuffers for the planes as follows: + - The overlay plane contains general desktop UI, video player controls, and video subtitles + - Primary plane contains one or more videos + +.. note:: Keep in mind that we could extend this configuration to more planes, + but that is currently not supported by our driver yet (maybe if we have a + userspace request in the future, we can change that). + +See below a single-video example: + +.. kernel-figure:: single-display-mpo.svg + +.. note:: We could extend this behavior to more planes, but that is currently + not supported by our driver. + +The video buffer should be used directly for the primary plane. The video can +be scaled and positioned for the desktop using the properties: CRTC_X, CRTC_Y, +CRTC_W, and CRTC_H. The primary plane should also have the color encoding and +color range properties set based on the source content: + +* ``COLOR_RANGE``, ``COLOR_ENCODING`` + +The overlay plane should be the native size of the CRTC. The compositor must +draw a transparent cutout for where the video should be placed on the desktop +(i.e., set the alpha to zero). The primary plane video will be visible through +the underlay. The overlay plane's buffer may remain static while the primary +plane's framebuffer is used for standard double-buffered playback. + +The compositor should create a YUV buffer matching the native size of the CRTC. +Each video buffer should be composited onto this YUV buffer for direct YUV +scanout. The primary plane should have the color encoding and color range +properties set based on the source content: ``COLOR_RANGE``, +``COLOR_ENCODING``. However, be mindful that the source color space and +encoding match for each video since it affect the entire plane. + +The overlay plane should be the native size of the CRTC. The compositor must +draw a transparent cutout for where each video should be placed on the desktop +(i.e., set the alpha to zero). The primary plane videos will be visible through +the underlay. The overlay plane's buffer may remain static while compositing +operations for video playback will be done on the video buffer. + +This kernel interface is validated using IGT GPU Tools. The following tests can +be run to validate positioning, blending, scaling under a variety of sequences +and interactions with operations such as DPMS and S3: + +- ``kms_plane@plane-panning-bottom-right-pipe-*-planes`` +- ``kms_plane@plane-panning-bottom-right-suspend-pipe-*-`` +- ``kms_plane@plane-panning-top-left-pipe-*-`` +- ``kms_plane@plane-position-covered-pipe-*-`` +- ``kms_plane@plane-position-hole-dpms-pipe-*-`` +- ``kms_plane@plane-position-hole-pipe-*-`` +- ``kms_plane_multiple@atomic-pipe-*-tiling-`` +- ``kms_plane_scaling@pipe-*-plane-scaling`` +- ``kms_plane_alpha_blend@pipe-*-alpha-basic`` +- ``kms_plane_alpha_blend@pipe-*-alpha-transparant-fb`` +- ``kms_plane_alpha_blend@pipe-*-alpha-opaque-fb`` +- ``kms_plane_alpha_blend@pipe-*-constant-alpha-min`` +- ``kms_plane_alpha_blend@pipe-*-constant-alpha-mid`` +- ``kms_plane_alpha_blend@pipe-*-constant-alpha-max`` + +Multiple Display MPO +-------------------- + +AMDGPU supports display MPO when using multiple displays; however, this feature +behavior heavily relies on the compositor implementation. Keep in mind that +usespace can define different policies. For example, some OSes can use MPO to +protect the plane that handles the video playback; notice that we don't have +many limitations for a single display. Nonetheless, this manipulation can have +many more restrictions for a multi-display scenario. The below example shows a +video playback in the middle of two displays, and it is up to the compositor to +define a policy on how to handle it: + +.. kernel-figure:: multi-display-hdcp-mpo.svg + +Let's discuss some of the hardware limitations we have when dealing with +multi-display with MPO. + +Limitations +~~~~~~~~~~~ + +For simplicity's sake, for discussing the hardware limitation, this +documentation supposes an example where we have two displays and video playback +that will be moved around different displays. + +* **Hardware limitations** + +From the DCN overview page, each display requires at least one pipe and each +MPO plane needs another pipe. As a result, when the video is in the middle of +the two displays, we need to use 2 pipes. See the example below where we avoid +pipe split: + +- 1 display (1 pipe) + MPO (1 pipe), we will use two pipes +- 2 displays (2 pipes) + MPO (1-2 pipes); we will use 4 pipes. MPO in the + middle of both displays needs 2 pipes. +- 3 Displays (3 pipes) + MPO (1-2 pipes), we need 5 pipes. + +If we use MPO with multiple displays, the userspace has to decide to enable +multiple MPO by the price of limiting the number of external displays supported +or disable it in favor of multiple displays; it is a policy decision. For +example: + +* When ASIC has 3 pipes, AMD hardware can NOT support 2 displays with MPO +* When ASIC has 4 pipes, AMD hardware can NOT support 3 displays with MPO + +Let's briefly explore how userspace can handle these two display configurations +on an ASIC that only supports three pipes. We can have: + +.. kernel-figure:: multi-display-hdcp-mpo-less-pipe-ex.svg + +- Total pipes are 3 +- User lights up 2 displays (2 out of 3 pipes are used) +- User launches video (1 pipe used for MPO) +- Now, if the user moves the video in the middle of 2 displays, one part of the + video won't be MPO since we have used 3/3 pipes. + +* **Scaling limitation** + +MPO cannot handle scaling less than 0.25 and more than x16. For example: + +If 4k video (3840x2160) is playing in windowed mode, the physical size of the +window cannot be smaller than (960x540). + +.. note:: These scaling limitations might vary from ASIC to ASIC. + +* **Size Limitation** + +The minimum MPO size is 12px. diff --git a/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo-less-pipe-ex.svg b/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo-less-pipe-ex.svg new file mode 100644 index 000000000000..6d06b39e83fa --- /dev/null +++ b/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo-less-pipe-ex.svg @@ -0,0 +1,220 @@ + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + ProtectedMPO plane + + + #1 + #2 + Desktop + Desktop + #3 + SoftwareComposited Video + Video will not be displayed + + diff --git a/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo.svg b/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo.svg new file mode 100644 index 000000000000..84d53a558b05 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/multi-display-hdcp-mpo.svg @@ -0,0 +1,171 @@ + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + ProtectedMPO plane + + + Desktop + Desktop + Video + + diff --git a/Documentation/gpu/amdgpu/display/single-display-mpo-multi-video.svg b/Documentation/gpu/amdgpu/display/single-display-mpo-multi-video.svg new file mode 100644 index 000000000000..fa807115cfe2 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/single-display-mpo-multi-video.svg @@ -0,0 +1,339 @@ + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + Video Buffer (YUV) + CRTC Output + + Hardware Composition + + + + + + + + + + + + + + + + + + + + + + + + + + + Desktop Buffer (ARGB) + + diff --git a/Documentation/gpu/amdgpu/display/single-display-mpo.svg b/Documentation/gpu/amdgpu/display/single-display-mpo.svg new file mode 100644 index 000000000000..fb53b0920c87 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/single-display-mpo.svg @@ -0,0 +1,266 @@ + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + Video Buffer (YUV)DRM PRIMARY PLANE + + Desktop Buffer (ARGB)DRM OVERLAY PLANE + + + + + + + + CRTC Output + + HardwareComposition + + + + -- cgit v1.2.3