From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 98477D2F7E9 for ; Thu, 17 Oct 2024 03:43:57 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 46D2B10E794; Thu, 17 Oct 2024 03:43:57 +0000 (UTC) Authentication-Results: gabe.freedesktop.org; dkim=pass (1024-bit key; unprotected) header.d=amd.com header.i=@amd.com header.b="0GFzGnWK"; dkim-atps=neutral Received: from NAM11-BN8-obe.outbound.protection.outlook.com (mail-bn8nam11on2086.outbound.protection.outlook.com [40.107.236.86]) by gabe.freedesktop.org (Postfix) with ESMTPS id 0F07510E2DF for ; Thu, 17 Oct 2024 03:43:55 +0000 (UTC) ARC-Seal: i=1; a=rsa-sha256; s=arcselector10001; d=microsoft.com; cv=none; b=N9cuylVsLy1uFuIHC9gfOCFwv2tVTM+KhZFiDTmF3fOE8NJ7l5WMbnmVC4E597Vr5YWD/mzy60U+Bt8RVtEoI64omjMFF9zjxB8DorzVcpQWDsGgkPKMAwFE6ky9a5syvMlDaCj4YlN/SlGaQv0TNdVbfTjHMJmkg7E619XY2ras/m8kAltPVRX0oF2M2Mq3vKlLdNBUJIV6VZzuyZn6uI9HybavFIY4JbnszHFM20hezYs75fMCaTZrdyUwgPDJ8qmBf2mBGQB02EdqJK6kVNZOdGoEE9kVxbunTMumAC0i1epUDx++kh5LmhE2/GEXLZUe0rOxZmZXk4AyKNEjhg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector10001; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=MSiU36H4B6JcKC2nsi0ktZAETzBM7D/YDCzFPp7BSso=; b=EtKBIuGzZ7kVMxCdrP131L1WCs5XcsRCtqbvwHrIsDt7PBwV82Wcuao+/MkS9Y4FgfouKnxq5qKSpTxw7/nDqXq74inkNSWpV42ydq9mweQmA6aIGFiIp0/Ef1H4bSoc+u3a6xBqLz9+M+uStEMX58bXT0wDjBxiJ52Rm6Hk13LUm6STpza1/NxoTclgTQmtO2LiKq/NFASGAF5oWmQxWIqLJt4DTF4c73dMh/vvDBc06oR5SrKjSRCTkz37bVpRqLm5Vn0tYmQHBiRiGI2AD83XWqqDExisrTLMEBi1+V8no1kbP59lZAtPFzO7kZoz4uqeWM7IfsG3Y8a076yt5Q== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=lists.freedesktop.org smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none (0) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=MSiU36H4B6JcKC2nsi0ktZAETzBM7D/YDCzFPp7BSso=; b=0GFzGnWKW37mL/6izUHHUVOP/to/ze6svdimXWjc1VSOxMWApHCUPUBUVQkMCnvw0Wqf6JXs1onjQXDo4UrBXUiesSz+N6kPKY78xWXkJhuHj/VVdZsIYlUe2X5BoPscdxL1ITY6FZX3swoTSK3g/XOitsIUu6ymOVdSLMpMLaQ= Received: from BN9PR03CA0451.namprd03.prod.outlook.com (2603:10b6:408:139::6) by DM3PR12MB9416.namprd12.prod.outlook.com (2603:10b6:0:4b::8) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.8069.17; Thu, 17 Oct 2024 03:43:48 +0000 Received: from BN3PEPF0000B371.namprd21.prod.outlook.com (2603:10b6:408:139:cafe::c7) by BN9PR03CA0451.outlook.office365.com (2603:10b6:408:139::6) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.8069.18 via Frontend Transport; Thu, 17 Oct 2024 03:43:48 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 165.204.84.17) smtp.mailfrom=amd.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=amd.com; Received-SPF: Pass (protection.outlook.com: domain of amd.com designates 165.204.84.17 as permitted sender) receiver=protection.outlook.com; client-ip=165.204.84.17; helo=SATLEXMB04.amd.com; pr=C Received: from SATLEXMB04.amd.com (165.204.84.17) by BN3PEPF0000B371.mail.protection.outlook.com (10.167.243.168) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.8093.1 via Frontend Transport; Thu, 17 Oct 2024 03:43:48 +0000 Received: from smtp.xilinx.com (10.180.168.240) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.39; Wed, 16 Oct 2024 22:43:45 -0500 From: Rodrigo Siqueira To: CC: Rodrigo Siqueira , Leo Li , Aurabindo Pillai , Hamza Mahfooz , Harry Wentland , "Mario Limonciello" , Christian Konig , Alex Deucher Subject: [PATCH 2/2] Documentation/gpu/amdgpu: Add programming model for DCN Date: Wed, 16 Oct 2024 21:34:27 -0600 Message-ID: <20241017034244.223993-3-Rodrigo.Siqueira@amd.com> X-Mailer: git-send-email 2.45.2 In-Reply-To: <20241017034244.223993-1-Rodrigo.Siqueira@amd.com> References: <20241017034244.223993-1-Rodrigo.Siqueira@amd.com> MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit X-Originating-IP: [10.180.168.240] X-ClientProxiedBy: SATLEXMB04.amd.com (10.181.40.145) To SATLEXMB04.amd.com (10.181.40.145) X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: BN3PEPF0000B371:EE_|DM3PR12MB9416:EE_ X-MS-Office365-Filtering-Correlation-Id: 6d082dd1-90b7-4e1b-5040-08dcee5de8a4 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; ARA:13230040|1800799024|376014|36860700013|82310400026; X-Microsoft-Antispam-Message-Info: =?utf-8?B?Z1o5REU1MDJmSUxrZ1NiNzQ0NCtJNnhRdkptS1lWeGpiNFE1VUJLK2plY1lu?= =?utf-8?B?Z0RUMFI4dEdKanlvOVdqTjJqRUdTQUMrWHE4SjRmdzVxZU04RUU5Z1FrWUx6?= =?utf-8?B?dU9QcTQ5dXB4S2dRNklzS1gvQlBpSkh3UkRCVDF3Y09sZEVIcFd6K0MxQjZD?= =?utf-8?B?c3NXRVI5WHhMa2RvU00rcXBFOVdoL3dnY2x2R0w2YnV4QXR0MDVyU25EMWJa?= =?utf-8?B?b1puSHJleC9XTU5VeUZBRWNwYUFyek5Mc2NDSTRGWm5WQ2g2Z2ZLbnJ0Q2ND?= =?utf-8?B?dE5aVkU5V0hTMXVwR1pmYWxJYUEwbTg2bHNIN1lsVHRaQVc3Z1lVckw3eElL?= =?utf-8?B?NmJoWVI3VTBWWVZSTkhHOGZEMG1uTjFKakRUTXhHdkFQY0F1U1ZoSkxja2Vq?= =?utf-8?B?VnVMVkk2dU91OTlPSWtWNFN3VEdORWViazBuMld2dmtxWUU2N3poUXN0c3o4?= =?utf-8?B?UHNydXdGYy9veDdpS1VyK3hwbkhYMCtkK2k5QnYrVkdTWFArUEgzbDZxdzhI?= =?utf-8?B?RnBwWWpJajd2ZmVGNHNIcVlzMXV0M0pJU2xrRlR3SXVrRUFydVlub0N0UzFh?= =?utf-8?B?dmxkMlh3ckdWS2dHdVZtTmpjZFJSTnNQaUNObG95YlgwUnhubEpHVTUvZWxY?= =?utf-8?B?TFpsRmthamYyemdvRHgrc01GbUJGU3h2cTk1a1NNc2RXRnJTbjN4anNjS1RT?= =?utf-8?B?dTBJYkJBdG1nbnhnQ2NrdWVOQ0w4dkNDY1VYKzV4UFRUQlJnYkFKVnpZZXM0?= =?utf-8?B?UFBGYjBqY0ZKZ2ZRbUYwNks4RWhsNGxvekpHd0M3YXQra0J4eDhjeWgrTksr?= =?utf-8?B?Q21qTTlUNXQvSTNpc3VPWXdVL0RPUU1xa3FQVW1ieitjY0ZUQ0RaZlBzUFow?= =?utf-8?B?T1ZIYWthVlA3bjJ5ZCszZDFpMkUxR0Z4Z2tON1FWM21oVUNrYjFLbVoyblRq?= =?utf-8?B?V1FHOEd4OXphUG9LVFppZGxYNU5VMCt5YjUrS1Vad2RXQXpudFRhd2FRam5N?= =?utf-8?B?RDUzTERYNXNNaXpCM3NqMERaa3hxdmwvVzJVcDBmZERNeXFzUmlJYzB2cnNq?= =?utf-8?B?NEZVdExkcVRGdlY3M3lFOXRxaVJPKzJoV3h2Q2c2R3NtV09TZ0JiQTc5SVd1?= =?utf-8?B?TVY4NWIyNk1ZcVMwRlhQSzNVQnl2VVlXdEdHd1hEYXF0Ylp2THNwNEllUUJT?= =?utf-8?B?Y2k1NFZYSlRxWHUrWE9vNmRsVG9DRjBzZkk2SjFlQWowaXAxNTN6Znc4Z2Yy?= =?utf-8?B?ckZwUW5CVnFGZGtxcXJaMGVTK1BkWWJpT1pNVkhXVHIrbkdnTG9SWU1Ub0Vu?= =?utf-8?B?TzdiTHdPbGxtZFFTdkU4UDFOTGNTRngwMmdxRGdpbmVXbGptbk9uQWN4cXp0?= =?utf-8?B?QXRQTTZaSWNmRmF4bHVUaEFBUUQ1OXdEb0c0Z1JiM28vM2hKTXUzSUV5bEta?= =?utf-8?B?dlg2c25iWG9QTlpSWWduUCtqeGkwQVpCV1pIOFgzOG4rUkdKdE9BSVp6cC93?= =?utf-8?B?djRTSlh3czZya2tpU2Y3Qkl6SmhYZnd1RUlQQVlnN2w5NllodUJnQzZJZzN2?= =?utf-8?B?VW8xRjN3Y2RRWGRvems2WGQ3VHRzcXp0VXR3THFwYXZmVTZNV25yWCszMWFD?= =?utf-8?B?SDZtNFpFMnlwYlNrMGJXMnR0TnNDa0xad3lMVVBDQWNKSHhpdzNuckU1NEhH?= =?utf-8?B?cUdEMlBiYWJUNHUwa3BWNmpXbmhIYmgzZnRTNHZpQURLMnRDSnRDdFlKRE04?= =?utf-8?B?dVhRK2l1SGErelltai9JbXZKbGlMZ0hmSktnSGUyWmNRc0tQQk5SNk5JK1hy?= =?utf-8?Q?V6RLA7wvrNyyvue3o+oMh6ut447hdqvEIEcFc=3D?= X-Forefront-Antispam-Report: CIP:165.204.84.17; CTRY:US; LANG:en; SCL:1; SRV:; IPV:CAL; SFV:NSPM; H:SATLEXMB04.amd.com; PTR:InfoDomainNonexistent; CAT:NONE; SFS:(13230040)(1800799024)(376014)(36860700013)(82310400026); DIR:OUT; SFP:1101; X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 17 Oct 2024 03:43:48.1438 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 6d082dd1-90b7-4e1b-5040-08dcee5de8a4 X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d; Ip=[165.204.84.17]; Helo=[SATLEXMB04.amd.com] X-MS-Exchange-CrossTenant-AuthSource: BN3PEPF0000B371.namprd21.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM3PR12MB9416 X-BeenThere: amd-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Discussion list for AMD gfx List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: amd-gfx-bounces@lists.freedesktop.org Sender: "amd-gfx" One of the challenges to contributing to the display code is the complexity of the DC component. This commit adds a documentation page that discusses the programming model used by DCN and an overview of how the display code is organized. Cc: Leo Li Cc: Aurabindo Pillai Cc: Hamza Mahfooz Cc: Harry Wentland Cc: Mario Limonciello Cc: Christian Konig Cc: Alex Deucher Signed-off-by: Rodrigo Siqueira --- .../gpu/amdgpu/display/dc-arch-overview.svg | 731 +++++++++++++++++ .../gpu/amdgpu/display/dc-components.svg | 732 ++++++++++++++++++ .../gpu/amdgpu/display/dcn-blocks.rst | 2 + .../gpu/amdgpu/display/dcn-overview.rst | 2 + Documentation/gpu/amdgpu/display/index.rst | 1 + .../amdgpu/display/programming-model-dcn.rst | 162 ++++ 6 files changed, 1630 insertions(+) create mode 100644 Documentation/gpu/amdgpu/display/dc-arch-overview.svg create mode 100644 Documentation/gpu/amdgpu/display/dc-components.svg create mode 100644 Documentation/gpu/amdgpu/display/programming-model-dcn.rst diff --git a/Documentation/gpu/amdgpu/display/dc-arch-overview.svg b/Documentation/gpu/amdgpu/display/dc-arch-overview.svg new file mode 100644 index 000000000000..23394931cf26 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dc-arch-overview.svg @@ -0,0 +1,731 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + Board/Platform + SoC + Component + DRAM + + dc_plane + + + + dc_plane + + + + + DC + + + + + dc_link + + + + + dc_link + + + + + + + dc_link + + + + + + + + + + + DCN + SoC + Board/Platform + Display + Connector + Connector + + diff --git a/Documentation/gpu/amdgpu/display/dc-components.svg b/Documentation/gpu/amdgpu/display/dc-components.svg new file mode 100644 index 000000000000..f84bb2a57c05 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dc-components.svg @@ -0,0 +1,732 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + Core + + + + + + + + + + Display Core API (dc/dc.h) + Link + Hardware Sequencer API(dc/inc/hw_sequence.h) + Hardware Sequencer + Block Level API (dc/inc/hw) + + + DCHUB + + + + HUBP + + + + DPP + + + + MPC + + + + ... + + Hardware Registers + DMUBBlock + DMUB Hardware API(dmub/dmub_srv.h) + DMUB Service + DMUB Service API(dc/dc_dmub_srv.h) + + diff --git a/Documentation/gpu/amdgpu/display/dcn-blocks.rst b/Documentation/gpu/amdgpu/display/dcn-blocks.rst index 5e34366f6dbe..756957128dad 100644 --- a/Documentation/gpu/amdgpu/display/dcn-blocks.rst +++ b/Documentation/gpu/amdgpu/display/dcn-blocks.rst @@ -1,3 +1,5 @@ +.. _dcn_blocks: + ========== DCN Blocks ========== diff --git a/Documentation/gpu/amdgpu/display/dcn-overview.rst b/Documentation/gpu/amdgpu/display/dcn-overview.rst index 9fea6500448b..eb54a6802e04 100644 --- a/Documentation/gpu/amdgpu/display/dcn-overview.rst +++ b/Documentation/gpu/amdgpu/display/dcn-overview.rst @@ -1,3 +1,5 @@ +.. _dcn_overview: + ======================= Display Core Next (DCN) ======================= diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst index f0c342e00a39..bd2d797c123e 100644 --- a/Documentation/gpu/amdgpu/display/index.rst +++ b/Documentation/gpu/amdgpu/display/index.rst @@ -90,6 +90,7 @@ table of content: display-manager.rst dcn-overview.rst dcn-blocks.rst + programming-model-dcn.rst mpo-overview.rst dc-debug.rst display-contributing.rst diff --git a/Documentation/gpu/amdgpu/display/programming-model-dcn.rst b/Documentation/gpu/amdgpu/display/programming-model-dcn.rst new file mode 100644 index 000000000000..c1b48d49fb0b --- /dev/null +++ b/Documentation/gpu/amdgpu/display/programming-model-dcn.rst @@ -0,0 +1,162 @@ +==================== +DC Programming Model +==================== + +In the :ref:`Display Core Next (DCN) ` and :ref:`DCN Block +` pages, you learned about the hardware components and how they +interact with each other. On this page, the focus is shifted to the display +code architecture. Hence, it is reasonable to remind the reader that the code +in DC is shared with other OSes; for this reason, DC provides a set of +abstractions and operations to connect different APIs with the hardware +configuration. See DC as a service available for a Display Manager (amdgpu_dm) +to access and configure DCN/DCE hardware (DCE is also part of DC, but for +simplicity's sake, this documentation only examines DCN). + +.. note:: + For this page, we will use the term GPU to refers to dGPU and APU. + +Overview +======== + +From the display hardware perspective, it is plausible to expect that if a +problem is well-defined, it will probably be implemented at the hardware level. +On the other hand, when there are multiple ways of achieving something without +a very well-defined scope, the solution is usually implemented as a policy at +the DC level. In other words, some policies are defined in the DC core +(resource management, power optimization, image quality, etc.), and the others +implemented in hardware are enabled via DC configuration. + +In terms of hardware management, DCN has multiple instances of the same block +(e.g., HUBP, DPP, MPC, etc), and during the driver execution, it might be +necessary to use some of these instances. The core has policies in place for +handling those instances. Regarding resource management, the DC objective is +quite simple: minimize the hardware shuffle when the driver performs some +actions. When the state changes from A to B, the transition is considered +easier to maneuver if the hardware resource is still used for the same set of +driver objects. Usually, adding and removing a resource to a `pipe_ctx` (more +details below) is not a problem; however, moving a resource from one `pipe_ctx` +to another should be avoided. + +Another area of influence for DC is power optimization, which has a myriad of +arrangement possibilities. In some way, just displaying an image via DCN should +be relatively straightforward; however, showing it with the best power +footprint is more desirable, but it has many associated challenges. +Unfortunately, there is no straight-forward analytic way to determine if a +configuration is the best one for the context due to the enormous variety of +variables related to this problem (e.g., many different DCN/DCE hardware +versions, different displays configurations, etc.) for this reason DC +implements a dedicated library for trying some configuration and verify if it +is possible to support it or not. This type of policy is extremely complex to +create and maintain, and amdgpu driver relies on Display Mode Library (DML) to +generate the best decisions. + +In summary, DC must deal with the complexity of handling multiple scenarios and +determine policies to manage them. All of the above information is conveyed to +give the reader some idea about the complexity of driving a display from the +driver's perspective. This page hopes to allow the reader to better navigate +over the amdgpu display code. + +Display Driver Architecture Overview +==================================== + +The diagram below provides an overview of the display driver architecture; +notice it illustrates the software layers adopted by DC: + +.. kernel-figure:: dc-components.svg + +The first layer of the diagram is the high-level DC API represented by the +`dc.h` file; below it are two big blocks represented by Core and Link. Next is +the hardware configuration block; the main file describing it is +the`hw_sequencer.h`, where the implementation of the callbacks can be found in +the hardware sequencer folder. Almost at the end, you can see the block level +API (`dc/inc/hw`), which represents each DCN low-level block, such as HUBP, +DPP, MPC, OPTC, etc. Notice on the left side of the diagram that we have a +different set of layers representing the interaction with the DMUB +microcontroller. + +Basic Objects +------------- + +The below diagram outlines the basic display objects. In particular, pay +attention to the names in the boxes since they represent a data structure in +the driver: + +.. kernel-figure:: dc-arch-overview.svg + +Let's start with the central block in the image, `dc`. The `dc` struct is +initialized per GPU; for example, one GPU has one `dc` instance, two GPUs have +two `dc` instances, and so forth. In other words we have one 'dc' per 'amdgpu' +instance. In some ways, this object behaves like the `Singleton` pattern. + +After the `dc` block in the diagram, you can see the `dc_link` component, which +is a low-level abstraction for the connector. One interesting aspect of the +image is that connectors are not part of the DCN block; they are defined by the +platform/board and not by the SoC. The `dc_link` struct is the high-level data +container with information such as connected sinks, connection status, signal +types, etc. After `dc_link`, there is the `dc_sink`, which is the object that +represents the connected display. + +.. note:: + For historical reasons, we used the name `dc_link`, which gives the + wrong impression that this abstraction only deals with physical connections + that the developer can easily manipulate. However, this also covers + conections like eDP or cases where the output is connected to other devices. + +There are two structs that are not represented in the diagram since they were +elaborated in the DCN overview page (check the DCN block diagram :ref:`Display +Core Next (DCN) `); still, it is worth bringing back for this +overview which is `dc_stream` and `dc_state`. The `dc_stream` stores many +properties associated with the data transmission, but most importantly, it +represents the data flow from the connector to the display. Next we have +`dc_state`, which represents the logic state within the hardware at the moment; +`dc_state` is composed of `dc_stream` and `dc_plane`. The `dc_stream` is the DC +version of `drm_crtc` and represents the post-blending pipeline. + +Speaking of the `dc_plane` data structure (first part of the diagram), you can +think about it as an abstraction similar to `drm_plane` that represents the +pre-blending portion of the pipeline. This image was probably processed by GFX +and is ready to be composited under a `dc_stream`. Normally, the driver may +have one or more `dc_plane` connected to the same `dc_stream`, which defines a +composition at the DC level. + +Basic Operations +---------------- + +Now that we have covered the basic objects, it is time to examine some of the +basic hardware/software operations. Let's start with the `dc_create()` +function, which directly works with the `dc` data struct; this function behaves +like a constructor responsible for the basic software initialization and +preparing for enabling other parts of the API. It is important to highlight +that this operation does not touch any hardware configuration; it is only a +software initialization. + +Next, we have the `dc_hardware_init()`, which also relies on the `dc` data +struct. Its main function is to put the hardware in a valid state. It is worth +highlighting that the hardware might initialize in an unknown state, and it is +a requirement to put it in a valid state; this function has multiple callbacks +for the hardware-specific initialization, whereas `dc_hardware_init` does the +hardware initialization and is the first point where we touch hardware. + +The `dc_get_link_at_index` is an operation that depends on the `dc_link` data +structure. This function retrieves and enumerates all the `dc_links` available +on the device; this is required since this information is not part of the SoC +definition but depends on the board configuration. As soon as the `dc_link` is +initialized, it is useful to figure out if any of them are already connected to +the display by using the `dc_link_detect()` function. After the driver figures +out if any display is connected to the device, the challenging phase starts: +configuring the monitor to show something. Nonetheless, dealing with the ideal +configuration is not a DC task since this is the Display Manager (`amdgpu_dm`) +responsibility which in turn is responsible for dealing with the atomic +commits. The only interface DC provides to the configuration phase is the +function `dc_validate_with_context` that receives the configuration information +and, based on that, validates whether the hardware can support it or not. It is +important to add that even if the display supports some specific configuration, +it does not mean the DCN hardware can support it. + +After the DM and DC agree upon the configuration, the stream configuration +phase starts. This task activates one or more `dc_stream` at this phase, and in +the best-case scenario, you might be able to turn the display on with a black +screen (it does not show anything yet since it does not have any plane +associated with it). The final step would be to call the +`dc_update_planes_and_stream,` which will add or remove planes. + -- 2.45.2