From patchwork Thu Jan 3 11:41:48 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: James Qian Wang X-Patchwork-Id: 10747221 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id E98B71575 for ; Thu, 3 Jan 2019 11:41:56 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D3E6A285A2 for ; Thu, 3 Jan 2019 11:41:56 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C53A3285B5; Thu, 3 Jan 2019 11:41:56 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-5.2 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id C0D4C285A2 for ; Thu, 3 Jan 2019 11:41:55 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id E6EE66EAC9; Thu, 3 Jan 2019 11:41:54 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from EUR02-HE1-obe.outbound.protection.outlook.com (mail-he1eur02on0629.outbound.protection.outlook.com [IPv6:2a01:111:f400:fe05::629]) by gabe.freedesktop.org (Postfix) with ESMTPS id A5BDC6EAC9 for ; Thu, 3 Jan 2019 11:41:52 +0000 (UTC) Received: from AM3PR08MB0611.eurprd08.prod.outlook.com (10.163.188.149) by AM3PR08MB0181.eurprd08.prod.outlook.com (10.161.35.145) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1495.6; Thu, 3 Jan 2019 11:41:48 +0000 Received: from AM3PR08MB0611.eurprd08.prod.outlook.com ([fe80::3c73:534c:9c6e:352d]) by AM3PR08MB0611.eurprd08.prod.outlook.com ([fe80::3c73:534c:9c6e:352d%2]) with mapi id 15.20.1495.005; Thu, 3 Jan 2019 11:41:48 +0000 From: "james qian wang (Arm Technology China)" To: Liviu Dudau , "daniel.vetter@ffwll.ch" , "rdunlap@infradead.org" , "robh+dt@kernel.org" Subject: [PATCH v4 8/9] drm/doc: Add initial komeda driver documentation Thread-Topic: [PATCH v4 8/9] drm/doc: Add initial komeda driver documentation Thread-Index: AQHUo1lP7e8825fCWUu9eB4BeBOaGg== Date: Thu, 3 Jan 2019 11:41:48 +0000 Message-ID: <20190103113841.15403-9-james.qian.wang@arm.com> References: <20190103113841.15403-1-james.qian.wang@arm.com> In-Reply-To: <20190103113841.15403-1-james.qian.wang@arm.com> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-originating-ip: [113.29.88.7] x-clientproxiedby: SY2PR01CA0046.ausprd01.prod.outlook.com (2603:10c6:1:15::34) To AM3PR08MB0611.eurprd08.prod.outlook.com (2a01:111:e400:c408::21) x-ms-exchange-messagesentrepresentingtype: 1 x-ms-publictraffictype: Email x-microsoft-exchange-diagnostics: 1; AM3PR08MB0181; 6:w8LwyXJWytNI7yjzmdYEp3qiMFEwd9AuUVaL8BLncnjFRCwmwFCG6MA3J1lds0Mi6ao42drddXb8I9H2duDlqvZhSXVlDZXUfi/6AFG8S4a9JGV2FbiQbGGjSkwlKS+ZVIKm/zwJhZdBgKQP9sd9iSpbBCvp3tKSurxQEVrdw1gkzMvsX5/yTAUIJ7le3QkqB5RBVM6ndQ5ffrD7wJ9w0cDYXqBnSvkLrEl6zQDthVWQLaMPil3h1bQEIWOoaXGMk/jFtiLIC84eMTFyx3FandZgQBkALkIvED+EfHnUDxmdT42vGVcnWmPj1PAKjjZXlTG6zqRtJM9wTynB1I6lV2szMzuOX5wl6pWdEniLqIXxAQtfumShOFW7YklyPlorh4XtwW6S+2uyy2F1LqMPYXHQexLuwusxZFRopil6eK+BsnbeV7j7Vz7Fr0bdi/bPi7oTUBce/gEkHVS0L6TEGw==; 5:gS9dpyewfOAFv/RrEcr2R3ZBl5bOKl8o4c9ni45cWljjSb8J28Ne07Ne/3VGsPOt2rn+0VBIE7Pv/382kLkfwpf9L8/s3bdyDA0YbjCq+xiWFpnPRywfZxKfDc14tIx8eu5pwm0F56xGFYr/PqYckivGlLdvbeZ5FJtQVEpXzlxn76Cyiio07ovt4w5orSoh+l2esfw+uOY+tWXvCAsBzg==; 7:8pXa41AcPizkbLFgNpmiuMHz6lxZ5PNOYnZLxh9h8hxMmAs+cWGSnHyRGNn0rjp8HxLjVE6neXz+W+gM5iV5ODjGeieTdineYATphkJqapP8t8FeNNlCI3UQaEIpqoSt2GFVSwMiSKYmqlkrJzB/Lw== x-ms-office365-filtering-correlation-id: 43930c4b-51f8-41d8-c033-08d671707143 x-ms-office365-filtering-ht: Tenant x-microsoft-antispam: BCL:0; PCL:0; RULEID:(2390118)(7020095)(4652040)(8989299)(4534185)(7168020)(4627221)(201703031133081)(201702281549075)(8990200)(5600109)(711020)(4618075)(2017052603328)(7153060)(7193020); SRVR:AM3PR08MB0181; x-ms-traffictypediagnostic: AM3PR08MB0181: nodisclaimer: True x-microsoft-antispam-prvs: x-exchange-antispam-report-cfa-test: BCL:0; PCL:0; RULEID:(8211001083)(3230021)(908002)(999002)(5005026)(6040522)(8220060)(2401047)(8121501046)(10201501046)(3002001)(3231475)(944501520)(52105112)(93006095)(93001095)(6055026)(6041310)(20161123562045)(20161123558120)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(20161123564045)(20161123560045)(201708071742011)(7699051)(76991095); SRVR:AM3PR08MB0181; BCL:0; PCL:0; RULEID:; SRVR:AM3PR08MB0181; x-forefront-prvs: 0906E83A25 x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(39860400002)(366004)(346002)(376002)(396003)(136003)(199004)(189003)(6436002)(6486002)(1076003)(68736007)(2501003)(66066001)(6512007)(103116003)(36756003)(106356001)(105586002)(11346002)(478600001)(97736004)(54075001)(53946003)(14454004)(486006)(476003)(4326008)(2616005)(14444005)(5024004)(256004)(386003)(86362001)(6506007)(7736002)(102836004)(316002)(446003)(2201001)(8936002)(26005)(7416002)(3846002)(81156014)(99286004)(2906002)(6116002)(81166006)(71200400001)(186003)(71190400001)(52116002)(76176011)(25786009)(5660300001)(8676002)(305945005)(54906003)(110136005)(53936002)(55236004)(4744004)(21314003); DIR:OUT; SFP:1101; SCL:1; SRVR:AM3PR08MB0181; H:AM3PR08MB0611.eurprd08.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; A:1; MX:1; received-spf: None (protection.outlook.com: arm.com does not designate permitted sender hosts) x-ms-exchange-senderadcheck: 1 x-microsoft-antispam-message-info: hVxCAzhlL2Y0wFs3ywP6ckUmPWDOB1p0y7NAz1JJv3ZeA5unlGnHXmCS1jsbnvXrQskfcjQq2kvii6EQGTLy9BYM25LTKSKqRYXUJWxaKHkh+qn1XyVsofEt+c2j3ibB7GAjdoAp8Df7bRG34OJjs0yjtixlnuxi0NSrMDJ9GNsJbYggg5PuIGzHnuHufN1RAVs1EuXQ41McXBVcLtqtYzaOeLGMHD1A4OUWI/osp8U/tBPh2U3bvCgiHoct1KV0jeQzrWO5iqoTcksg0T7+PO7BTZMtfcvQ0GZ4D7ygj2xqLvmTgDsjyF8PTbFFoN8q spamdiagnosticoutput: 1:99 spamdiagnosticmetadata: NSPM Content-ID: <9A92F65656AA5340866D630122ECBDB5@eurprd08.prod.outlook.com> MIME-Version: 1.0 X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-Network-Message-Id: 43930c4b-51f8-41d8-c033-08d671707143 X-MS-Exchange-CrossTenant-originalarrivaltime: 03 Jan 2019 11:41:48.0493 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: f34e5979-57d9-4aaa-ad4d-b122a662184d X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM3PR08MB0181 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Mark Rutland , "linux-doc@vger.kernel.org" , "maxime.ripard@bootlin.com" , "Jonathan Chai \(Arm Technology China\)" , Alexandru-Cosmin Gheorghe , "dri-devel@lists.freedesktop.org" , "linux-kernel@vger.kernel.org" , "yamada.masahiro@socionext.com" , "Yiqi Kang \(Arm Technology China\)" , "mchehab+samsung@kernel.org" , "Tiannan Zhu \(Arm Technology China\)" , "corbet@lwn.net" , "airlied@linux.ie" , "malidp@foss.arm.com" , "thomas Sun \(Arm Technology China\)" , Ayan Halder , "devicetree@vger.kernel.org" , "arnd@arndb.de" , "Jin Gao \(Arm Technology China\)" , nd , "sean@poorly.run" , "Lowry Li \(Arm Technology China\)" , "gregkh@linuxfoundation.org" , "nicolas.ferre@microchip.com" , "Julien Yin \(Arm Technology China\)" , "james qian wang \(Arm Technology China\)" , "akpm@linux-foundation.org" , "davem@davemloft.net" Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Virus-Scanned: ClamAV using ClamSMTP From: "james qian wang (Arm Technology China)" v2: Some editing changes according to Randy Dunlap's comments Signed-off-by: James Qian Wang (Arm Technology China) --- Documentation/gpu/drivers.rst | 1 + Documentation/gpu/komeda-kms.rst | 488 +++++++++++++++++++++++++++++++ 2 files changed, 489 insertions(+) create mode 100644 Documentation/gpu/komeda-kms.rst diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst index 7c1672118a73..978e6da9bbff 100644 --- a/Documentation/gpu/drivers.rst +++ b/Documentation/gpu/drivers.rst @@ -17,6 +17,7 @@ GPU Driver Documentation vkms bridge/dw-hdmi xen-front + komeda-kms .. only:: subproject and html diff --git a/Documentation/gpu/komeda-kms.rst b/Documentation/gpu/komeda-kms.rst new file mode 100644 index 000000000000..b08da1cffecc --- /dev/null +++ b/Documentation/gpu/komeda-kms.rst @@ -0,0 +1,488 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== + drm/komeda Arm display driver +============================== + +The drm/komeda driver supports the Arm display processor D71 and later products, +this document gives a brief overview of driver design: how it works and why +design it like that. + +Overview of D71 like display IPs +================================ + +From D71, Arm display IP begins to adopt a flexible and modularized +architecture. A display pipeline is made up of multiple individual and +functional pipeline stages called components, and every component has some +specific capabilities that can give the flowed pipeline pixel data a +particular processing. + +Typical D71 components: + +Layer +----- +Layer is the first pipeline stage, which prepares the pixel data for the next +stage. It fetches the pixel from memory, decodes it if it's AFBC, rotates the +source image, unpacks or converts YUV pixels to the device internal RGB pixels, +then adjusts the color_space of pixels if needed. + +Scaler +------ +As its name suggests, scaler takes responsibility for scaling, and D71 also +supports image enhancements by scaler. +The usage of scaler is very flexible and can be connected to layer output +for layer scaling, or connected to compositor and scale the whole display +frame and then feed the output data into wb_layer which will then write it +into memory. + +Compositor (compiz) +------------------- +Compositor blends multiple layers or pixel data flows into one single display +frame. its output frame can be fed into post image processor for showing it on +the monitor or fed into wb_layer and written to memory at the same time. +user can also insert a scaler between compositor and wb_layer to down scale +the display frame first and and then write to memory. + +Writeback Layer (wb_layer) +-------------------------- +Writeback layer does the opposite things of Layer, which connects to compiz +and writes the composition result to memory. + +Post image processor (improc) +----------------------------- +Post image processor adjusts frame data like gamma and color space to fit the +requirements of the monitor. + +Timing controller (timing_ctrlr) +-------------------------------- +Final stage of display pipeline, Timing controller is not for the pixel +handling, but only for controlling the display timing. + +Merger +------ +D71 scaler mostly only has the half horizontal input/output capabilities +compared with Layer, like if Layer supports 4K input size, the scaler only can +support 2K input/output in the same time. To achieve the ful frame scaling, D71 +introduces Layer Split, which splits the whole image to two half parts and feeds +them to two Layers A and B, and does the scaling independently. After scaling +the result need to be fed to merger to merge two part images together, and then +output merged result to compiz. + +Splitter +-------- +Similar to Layer Split, but Splitter is used for writeback, which splits the +compiz result to two parts and then feed them to two scalers. + +Possible D71 Pipeline usage +=========================== + +Benefitting from the modularized architecture, D71 pipelines can be easily +adjusted to fit different usages. And D71 has two pipelines, which support two +types of working mode: + +- Dual display mode + Two pipelines work independently and separately to drive two display outputs. + +- Single display mode + Two pipelines work together to drive only one display output. + + On this mode, pipeline_B doesn't work indenpendently, but outputs its + composition result into pipeline_A, and its pixel timing also derived from + pipeline_A.timing_ctrlr. The pipeline_B works just like a "slave" of + pipeline_A(master) + +Single pipeline data flow +------------------------- + +.. kernel-render:: DOT + :alt: Single pipeline digraph + :caption: Single pipeline data flow + + digraph single_ppl { + rankdir=LR; + + subgraph { + "Memory"; + "Monitor"; + } + + subgraph cluster_pipeline { + style=dashed + node [shape=box] + { + node [bgcolor=grey style=dashed] + "Scaler-0"; + "Scaler-1"; + "Scaler-0/1" + } + + node [bgcolor=grey style=filled] + "Layer-0" -> "Scaler-0" + "Layer-1" -> "Scaler-0" + "Layer-2" -> "Scaler-1" + "Layer-3" -> "Scaler-1" + + "Layer-0" -> "Compiz" + "Layer-1" -> "Compiz" + "Layer-2" -> "Compiz" + "Layer-3" -> "Compiz" + "Scaler-0" -> "Compiz" + "Scaler-1" -> "Compiz" + + "Compiz" -> "Scaler-0/1" -> "Wb_layer" + "Compiz" -> "Improc" -> "Timing Controller" + } + + "Wb_layer" -> "Memory" + "Timing Controller" -> "Monitor" + } + +Dual pipeline with Slave enabled +-------------------------------- + +.. kernel-render:: DOT + :alt: Slave pipeline digraph + :caption: Slave pipeline enabled data flow + + digraph slave_ppl { + rankdir=LR; + + subgraph { + "Memory"; + "Monitor"; + } + node [shape=box] + subgraph cluster_pipeline_slave { + style=dashed + label="Slave Pipeline_B" + node [shape=box] + { + node [bgcolor=grey style=dashed] + "Slave.Scaler-0"; + "Slave.Scaler-1"; + } + + node [bgcolor=grey style=filled] + "Slave.Layer-0" -> "Slave.Scaler-0" + "Slave.Layer-1" -> "Slave.Scaler-0" + "Slave.Layer-2" -> "Slave.Scaler-1" + "Slave.Layer-3" -> "Slave.Scaler-1" + + "Slave.Layer-0" -> "Slave.Compiz" + "Slave.Layer-1" -> "Slave.Compiz" + "Slave.Layer-2" -> "Slave.Compiz" + "Slave.Layer-3" -> "Slave.Compiz" + "Slave.Scaler-0" -> "Slave.Compiz" + "Slave.Scaler-1" -> "Slave.Compiz" + } + + subgraph cluster_pipeline_master { + style=dashed + label="Master Pipeline_A" + node [shape=box] + { + node [bgcolor=grey style=dashed] + "Scaler-0"; + "Scaler-1"; + "Scaler-0/1" + } + + node [bgcolor=grey style=filled] + "Layer-0" -> "Scaler-0" + "Layer-1" -> "Scaler-0" + "Layer-2" -> "Scaler-1" + "Layer-3" -> "Scaler-1" + + "Slave.Compiz" -> "Compiz" + "Layer-0" -> "Compiz" + "Layer-1" -> "Compiz" + "Layer-2" -> "Compiz" + "Layer-3" -> "Compiz" + "Scaler-0" -> "Compiz" + "Scaler-1" -> "Compiz" + + "Compiz" -> "Scaler-0/1" -> "Wb_layer" + "Compiz" -> "Improc" -> "Timing Controller" + } + + "Wb_layer" -> "Memory" + "Timing Controller" -> "Monitor" + } + +Sub-pipelines for input and output +---------------------------------- + +A complete display pipeline can be easily divided into three sub-pipelines +according to the in/out usage. + +Layer(input) pipeline +~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-render:: DOT + :alt: Layer data digraph + :caption: Layer (input) data flow + + digraph layer_data_flow { + rankdir=LR; + node [shape=box] + + { + node [bgcolor=grey style=dashed] + "Scaler-n"; + } + + "Layer-n" -> "Scaler-n" -> "Compiz" + } + +.. kernel-render:: DOT + :alt: Layer Split digraph + :caption: Layer Split pipeline + + digraph layer_data_flow { + rankdir=LR; + node [shape=box] + + "Layer-0/1" -> "Scaler-0" -> "Merger" + "Layer-2/3" -> "Scaler-1" -> "Merger" + "Merger" -> "Compiz" + } + +Writeback(output) pipeline +~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. kernel-render:: DOT + :alt: writeback digraph + :caption: Writeback(output) data flow + + digraph writeback_data_flow { + rankdir=LR; + node [shape=box] + + { + node [bgcolor=grey style=dashed] + "Scaler-n"; + } + + "Compiz" -> "Scaler-n" -> "Wb_layer" + } + +.. kernel-render:: DOT + :alt: split writeback digraph + :caption: Writeback(output) Split data flow + + digraph writeback_data_flow { + rankdir=LR; + node [shape=box] + + "Compiz" -> "Splitter" + "Splitter" -> "Scaler-0" -> "Merger" + "Splitter" -> "Scaler-1" -> "Merger" + "Merger" -> "Wb_layer" + } + +Display output pipeline +~~~~~~~~~~~~~~~~~~~~~~~ +.. kernel-render:: DOT + :alt: display digraph + :caption: display output data flow + + digraph single_ppl { + rankdir=LR; + node [shape=box] + + "Compiz" -> "Improc" -> "Timing Controller" + } + +In the following section we'll see these three sub-pipelines will be handled +by KMS-plane/wb_conn/crtc respectively. + +Komeda Resource abstraction +=========================== + +struct komeda_pipeline/component +-------------------------------- + +To fully utilize and easily access/configure the HW, the driver side also uses +a similar architecture: Pipeline/Component to describe the HW features and +capabilities, and a specific component includes two parts: + +- Data flow controlling. +- Specific component capabilities and features. + +So the driver defines a common header struct komeda_component to describe the +data flow control and all specific components are a subclass of this base +structure. + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h + :internal: + +Resource discovery and initialization +===================================== + +Pipeline and component are used to describe how to handle the pixel data. We +still need a @struct komeda_dev to describe the whole view of the device, and +the control-abilites of device. + +We have &komeda_dev, &komeda_pipeline, &komeda_component. Now fill devices with +pipelines. Since komeda is not for D71 only but also intended for later products, +of course we’d better share as much as possible between different products. To +achieve this, split the komeda device into two layers: CORE and CHIP. + +- CORE: for common features and capabilities handling. +- CHIP: for register programing and HW specific feature (limitation) handling. + +CORE can access CHIP by three chip function structures: + +- struct komeda_dev_funcs +- struct komeda_pipeline_funcs +- struct komeda_component_funcs + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_dev.h + :internal: + +Format handling +=============== + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_format_caps.h + :internal: +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h + :internal: + +Attach komeda_dev to DRM-KMS +============================ + +Komeda abstracts resources by pipeline/component, but DRM-KMS uses +crtc/plane/connector. One KMS-obj cannot represent only one single component, +since the requirements of a single KMS object cannot simply be achieved by a +single component, usually that needs multiple components to fit the requirement. +Like set mode, gamma, ctm for KMS all target on CRTC-obj, but komeda needs +compiz, improc and timing_ctrlr to work together to fit these requirements. +And a KMS-Plane may require multiple komeda resources: layer/scaler/compiz. + +So, one KMS-Obj represents a sub-pipeline of komeda resources. + +- Plane: `Layer(input) pipeline`_ +- Wb_connector: `Writeback(output) pipeline`_ +- Crtc: `Display output pipeline`_ + +So, for komeda, we treat KMS crtc/plane/connector as users of pipeline and +component, and at any one time a pipeline/component only can be used by one +user. And pipeline/component will be treated as private object of DRM-KMS; the +state will be managed by drm_atomic_state as well. + +How to map plane to Layer(input) pipeline +----------------------------------------- + +Komeda has multiple Layer input pipelines, see: +- `Single pipeline data flow`_ +- `Dual pipeline with Slave enabled`_ + +The easiest way is binding a plane to a fixed Layer pipeline, but consider the +komeda capabilities: + +- Layer Split, See `Layer(input) pipeline`_ + + Layer_Split is quite complicated feature, which splits a big image into two + parts and handles it by two layers and two scalers individually. But it + imports an edge problem or effect in the middle of the image after the split. + To avoid such a problem, it needs a complicated Split calculation and some + special configurations to the layer and scaler. We'd better hide such HW + related complexity to user mode. + +- Slave pipeline, See `Dual pipeline with Slave enabled`_ + + Since the compiz component doesn't output alpha value, the slave pipeline + only can be used for bottom layers composition. The komeda driver wants to + hide this limitation to the user. The way to do this is to pick a suitable + Layer according to plane_state->zpos. + +So for komeda, the KMS-plane doesn't represent a fixed komeda layer pipeline, +but multiple Layers with same capabilities. Komeda will select one or more +Layers to fit the requirement of one KMS-plane. + +Make component/pipeline to be drm_private_obj +--------------------------------------------- + +Add :c:type:`drm_private_obj` to :c:type:`komeda_component`, :c:type:`komeda_pipeline` + +.. code-block:: c + + struct komeda_component { + struct drm_private_obj obj; + ... + } + + struct komeda_pipeline { + struct drm_private_obj obj; + ... + } + +Tracking component_state/pipeline_state by drm_atomic_state +----------------------------------------------------------- + +Add :c:type:`drm_private_state` and user to :c:type:`komeda_component_state`, +:c:type:`komeda_pipeline_state` + +.. code-block:: c + + struct komeda_component_state { + struct drm_private_state obj; + void *binding_user; + ... + } + + struct komeda_pipeline_state { + struct drm_private_state obj; + struct drm_crtc *crtc; + ... + } + +komeda component validation +--------------------------- + +Komeda has multiple types of components, but the process of validation are +similar, usually including the following steps: + +.. code-block:: c + + int komeda_xxxx_validate(struct komeda_component_xxx xxx_comp, + struct komeda_component_output *input_dflow, + struct drm_plane/crtc/connector *user, + struct drm_plane/crtc/connector_state, *user_state) + { + setup 1: check if component is needed, like the scaler is optional depending + on the user_state; if unneeded, just return, and the caller will + put the data flow into next stage. + Setup 2: check user_state with component features and capabilities to see + if requirements can be met; if not, return fail. + Setup 3: get component_state from drm_atomic_state, and try set to set + user to component; fail if component has been assigned to another + user already. + Setup 3: configure the component_state, like set its input component, + convert user_state to component specific state. + Setup 4: adjust the input_dflow and prepare it for the next stage. + } + +komeda_kms Abstraction +---------------------- + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_kms.h + :internal: + +komde_kms Functions +------------------- +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_crtc.c + :internal: +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_plane.c + :internal: + +Build komeda to be a Linux module driver +======================================== + +Now we have two level devices: + +- komeda_dev: describes the real display hardware. +- komeda_kms_dev: attachs or connects komeda_dev to DRM-KMS. + +All komeda operations are supplied or operated by komeda_dev or komeda_kms_dev, +the module driver is only a simple wrapper to pass the Linux command +(probe/remove/pm) into komeda_dev or komeda_kms_dev.