From patchwork Mon Oct 29 17:14:41 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alexandru-Cosmin Gheorghe X-Patchwork-Id: 10659821 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 6E63A13B5 for ; Mon, 29 Oct 2018 17:14:52 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 622F629D7C for ; Mon, 29 Oct 2018 17:14:52 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 553A329D7E; Mon, 29 Oct 2018 17:14:52 +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 9AF4929D7C for ; Mon, 29 Oct 2018 17:14:51 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 3E0FF6E057; Mon, 29 Oct 2018 17:14:46 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from EUR02-VE1-obe.outbound.protection.outlook.com (mail-eopbgr20084.outbound.protection.outlook.com [40.107.2.84]) by gabe.freedesktop.org (Postfix) with ESMTPS id BAB5A6E059 for ; Mon, 29 Oct 2018 17:14:43 +0000 (UTC) Received: from DB6PR0802MB2551.eurprd08.prod.outlook.com (10.172.251.149) by DB6PR0802MB2248.eurprd08.prod.outlook.com (10.172.227.145) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1273.19; Mon, 29 Oct 2018 17:14:41 +0000 Received: from DB6PR0802MB2551.eurprd08.prod.outlook.com ([fe80::19ca:93bb:bc0:985a]) by DB6PR0802MB2551.eurprd08.prod.outlook.com ([fe80::19ca:93bb:bc0:985a%7]) with mapi id 15.20.1273.027; Mon, 29 Oct 2018 17:14:41 +0000 From: Alexandru-Cosmin Gheorghe To: "seanpaul@chromium.org" , "airlied@linux.ie" , "dri-devel@lists.freedesktop.org" , Liviu Dudau , Brian Starkey , "malidp@foss.arm.com" , "maxime.ripard@bootlin.com" , "maarten.lankhorst@linux.intel.com" , Ayan Halder , "daniel.vetter@ffwll.ch" , Raymond Smith , David Garbett , Lisa Wu , Matt Szczesiak , Charles Xu , "james qian wang (Arm Technology China)" Subject: [PATCH v6 6/9] drm/afbc: Add AFBC modifier usage documentation Thread-Topic: [PATCH v6 6/9] drm/afbc: Add AFBC modifier usage documentation Thread-Index: AQHUb6rgpREjPdzp40qSkUhBFZfdjQ== Date: Mon, 29 Oct 2018 17:14:41 +0000 Message-ID: <20181029171419.4512-7-alexandru-cosmin.gheorghe@arm.com> References: <20181029171419.4512-1-alexandru-cosmin.gheorghe@arm.com> In-Reply-To: <20181029171419.4512-1-alexandru-cosmin.gheorghe@arm.com> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-clientproxiedby: LO2P265CA0032.GBRP265.PROD.OUTLOOK.COM (2603:10a6:600:61::20) To DB6PR0802MB2551.eurprd08.prod.outlook.com (2603:10a6:4:a1::21) x-ms-exchange-messagesentrepresentingtype: 1 x-originating-ip: [217.140.106.54] x-ms-publictraffictype: Email x-microsoft-exchange-diagnostics: 1; DB6PR0802MB2248; 6:JI7XiKLt1uCuAO/Vo8JWtSEAh6yXOQQ8tiMyHsRNo1MqbPfIC4USDggU7xsOliagNTV9dmyK93lDOzJe8RhvpYhtFcYm79MXO7TlOW3bLn8L2KZJxW9Z8FlzJoQXXmUAjwnLEVy5S1y4sr3Bu2bMP9esfCzKT8BgJijn7HRnSyxOkMqn1kEUi3fHMcbKR1H/AkQ3Tvjn8IpT8npoW4LAWdy3FPXTmUfFiTLvQgff3qeL0cAD9e073jFGhmd0jLy/0n9yWKVO+cH3B/gruCclcPUmZE9L+zjOVQokWtlI3ikp+lNvVi8PMWrtxHxbXgRVMhnwM1aUjznLTUliUN9rIISVf0nwyrguyiyE14MijTXKvSEZL5qe7TX/vx0oqL6ZZkT3DjGy4o3aHF9w7IlWzt3EIgU5A8KKTUEj11+s7utuRl+B4PWnnLVQzmj4SvQZAsCgUK3NPfQKhVMZIFSpAw==; 5:tA0iXjlXbIKOt/1S3K2hDBgOvvp9LMkw6LfpjnPTmXBTK6N9kofC3b3blrlFMpykYYBy4xPVIDQtw619Cp+NhudQEnoV5u8UG77diD6SCyFI5Vw8aUFLSDsmJJhhQYrdC18X+K6B3bYVURqgpaXsv/doOZNfYV3AeZKAkavby8A=; 7:iM54haCFrCqGJSUQYQQsw6fngcsermNZ9QlHRpJYw/h8S2X8Ws6P3+ViRsQx+qw9GU6IHFlVH3l8rFCIW+c2a9dSuylSd03rO98wY9wip5B84bSQwYLHQnSrM7xnbC1k2FqCvLl3Fhs8iSr5MSK93Q== x-ms-office365-filtering-correlation-id: 4bdda5f1-adf8-4077-7480-08d63dc20338 x-ms-office365-filtering-ht: Tenant x-microsoft-antispam: BCL:0; PCL:0; RULEID:(7020095)(4652040)(8989299)(4534185)(4627221)(201703031133081)(201702281549075)(8990200)(5600074)(711020)(4618075)(2017052603328)(7153060)(7193020); SRVR:DB6PR0802MB2248; x-ms-traffictypediagnostic: DB6PR0802MB2248: nodisclaimer: True x-microsoft-antispam-prvs: x-exchange-antispam-report-test: UriScan:(180628864354917); x-ms-exchange-senderadcheck: 1 x-exchange-antispam-report-cfa-test: BCL:0; PCL:0; RULEID:(8211001083)(6040522)(2401047)(5005006)(8121501046)(3231382)(944501410)(52105095)(93006095)(93001095)(3002001)(10201501046)(6055026)(148016)(149066)(150057)(6041310)(20161123560045)(20161123564045)(20161123562045)(20161123558120)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(201708071742011)(7699051)(76991095); SRVR:DB6PR0802MB2248; BCL:0; PCL:0; RULEID:; SRVR:DB6PR0802MB2248; x-forefront-prvs: 084080FC15 x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(396003)(39860400002)(376002)(366004)(346002)(136003)(189003)(199004)(86362001)(186003)(8676002)(81156014)(25786009)(106356001)(6512007)(6636002)(6436002)(5660300001)(81166006)(446003)(36756003)(110136005)(71200400001)(71190400001)(105586002)(486006)(53936002)(476003)(316002)(2900100001)(2616005)(11346002)(305945005)(72206003)(4326008)(2201001)(66066001)(5250100002)(478600001)(8936002)(7736002)(68736007)(2501003)(6506007)(386003)(99286004)(256004)(26005)(102836004)(97736004)(6486002)(14454004)(3846002)(14444005)(6116002)(2906002)(52116002)(76176011)(1076002)(921003)(1121003); DIR:OUT; SFP:1101; SCL:1; SRVR:DB6PR0802MB2248; H:DB6PR0802MB2551.eurprd08.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; MX:1; A:1; received-spf: None (protection.outlook.com: arm.com does not designate permitted sender hosts) x-microsoft-antispam-message-info: MkzuZw9EusNEgLKnc/f0DiJ6re1OnXcZJU+Gzie/f3crb+WXQvskV2820S7SdXwDRZeT05SjLTZS8MnA2zuBvenxDzr06WJEgHVNEqalbeAU7qmUfZWg//EB53UGtTWIhkR7/r00nT4lHqOjBKqFbNvLy6MLTYj0DYfVwGpOtOOfYxr988GiDFIl2UsyH4LXLa8FJPeva5MaCukxYvkAEguNKgtoYJlJ5IyW4xsOVQqLAuvuVQfBtUvZON+AJARhrzyQyl0cm17TfB15kFAgrJi4abtYeI7Qc9MOFLfU/udwq7HF3TWlcC5EAL3uLSWE8x1ZrmA9eHF/mpqejYDoQ25SqOvxtJBBCsaVwnU5Ldk= spamdiagnosticoutput: 1:99 spamdiagnosticmetadata: NSPM MIME-Version: 1.0 X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-Network-Message-Id: 4bdda5f1-adf8-4077-7480-08d63dc20338 X-MS-Exchange-CrossTenant-originalarrivaltime: 29 Oct 2018 17:14:41.1549 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: f34e5979-57d9-4aaa-ad4d-b122a662184d X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB6PR0802MB2248 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: nd Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Virus-Scanned: ClamAV using ClamSMTP From: Brian Starkey AFBC is a flexible, proprietary, lossless compression protocol and format, with a number of defined DRM format modifiers. To facilitate consistency and compatibility between different AFBC producers and consumers, document the expectations for usage of the AFBC DRM format modifiers in a new .rst chapter. Signed-off-by: Brian Starkey Reviewed-by: Liviu Dudau --- Documentation/gpu/afbc.rst | 233 ++++++++++++++++++++++++++++++++++ Documentation/gpu/drivers.rst | 1 + MAINTAINERS | 1 + include/uapi/drm/drm_fourcc.h | 3 + 4 files changed, 238 insertions(+) create mode 100644 Documentation/gpu/afbc.rst diff --git a/Documentation/gpu/afbc.rst b/Documentation/gpu/afbc.rst new file mode 100644 index 000000000000..922d955da192 --- /dev/null +++ b/Documentation/gpu/afbc.rst @@ -0,0 +1,233 @@ +=================================== + Arm Framebuffer Compression (AFBC) +=================================== + +AFBC is a proprietary lossless image compression protocol and format. +It provides fine-grained random access and minimizes the amount of +data transferred between IP blocks. + +AFBC can be enabled on drivers which support it via use of the AFBC +format modifiers defined in drm_fourcc.h. See DRM_FORMAT_MOD_ARM_AFBC(*). + +All users of the AFBC modifiers must follow the usage guidelines laid +out in this document, to ensure compatibility across different AFBC +producers and consumers. + +Components and Ordering +======================= + +AFBC streams can contain several components - where a component +corresponds to a color channel (i.e. R, G, B, X, A, Y, Cb, Cr). +The assignment of input/output color channels must be consistent +between the encoder and the decoder for correct operation, otherwise +the consumer will interpret the decoded data incorrectly. + +Furthermore, when the lossless colorspace transform is used +(AFBC_FORMAT_MOD_YTR, which should be enabled for RGB buffers for +maximum compression efficiency), the component order must be: + + * Component 0: R + * Component 1: G + * Component 2: B + +The component ordering is communicated via the fourcc code in the +fourcc:modifier pair. In general, component '0' is considered to +reside in the least-significant bits of the corresponding linear +format. For example, COMP(bits): + + * DRM_FORMAT_ABGR8888 + + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + * Component 3: A(8) + + * DRM_FORMAT_BGR888 + + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + + * DRM_FORMAT_YUYV + + * Component 0: Y(8) + * Component 1: Cb(8, 2x1 subsampled) + * Component 2: Cr(8, 2x1 subsampled) + +In AFBC, 'X' components are not treated any differently from any other +component. Therefore, an AFBC buffer with fourcc DRM_FORMAT_XBGR8888 +encodes with 4 components, like so: + + * DRM_FORMAT_XBGR8888 + + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + * Component 3: X(8) + +Please note, however, that the inclusion of a "wasted" 'X' channel is +bad for compression efficiency, and so it's recommended to avoid +formats containing 'X' bits. If a fourth component is +required/expected by the encoder/decoder, then it is recommended to +instead use an equivalent format with alpha, setting all alpha bits to +'1'. If there is no requirement for a fourth component, then a format +which doesn't include alpha can be used, e.g. DRM_FORMAT_BGR888. + +Number of Planes +================ + +Formats which are typically multi-planar in linear layouts (e.g. YUV +420), can be encoded into one, or multiple, AFBC planes. As with +component order, the encoder and decoder must agree about the number +of planes in order to correctly decode the buffer. The fourcc code is +used to determine the number of encoded planes in an AFBC buffer, +matching the number of planes for the linear (unmodified) format. +Within each plane, the component ordering also follows the fourcc +code: + +For example: + + * DRM_FORMAT_YUYV: nplanes = 1 + + * Plane 0: + + * Component 0: Y(8) + * Component 1: Cb(8, 2x1 subsampled) + * Component 2: Cr(8, 2x1 subsampled) + + * DRM_FORMAT_NV12: nplanes = 2 + + * Plane 0: + + * Component 0: Y(8) + + * Plane 1: + + * Component 0: Cb(8, 2x1 subsampled) + * Component 1: Cr(8, 2x1 subsampled) + +Cross-device interoperability +============================= + +For maximum compatibility across devices, the table below defines +canonical formats for use between AFBC-enabled devices. Formats which +are listed here must be used exactly as specified when using the AFBC +modifiers. Formats which are not listed should be avoided. + +.. flat-table:: AFBC formats + + * - Fourcc code + - Description + - Planes/Components + + * - DRM_FORMAT_ABGR2101010 + - 10-bit per component RGB, with 2-bit alpha + - Plane 0: 4 components + * Component 0: R(10) + * Component 1: G(10) + * Component 2: B(10) + * Component 3: A(2) + + * - DRM_FORMAT_ABGR8888 + - 8-bit per component RGB, with 8-bit alpha + - Plane 0: 4 components + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + * Component 3: A(8) + + * - DRM_FORMAT_BGR888 + - 8-bit per component RGB + - Plane 0: 3 components + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + + * - DRM_FORMAT_BGR565 + - 5/6-bit per component RGB + - Plane 0: 3 components + * Component 0: R(5) + * Component 1: G(6) + * Component 2: B(5) + + * - DRM_FORMAT_ABGR1555 + - 5-bit per component RGB, with 1-bit alpha + - Plane 0: 4 components + * Component 0: R(5) + * Component 1: G(5) + * Component 2: B(5) + * Component 3: A(1) + + * - DRM_FORMAT_VUY888 + - 8-bit per component YCbCr 444, single plane + - Plane 0: 3 components + * Component 0: Y(8) + * Component 1: Cb(8) + * Component 2: Cr(8) + + * - DRM_FORMAT_VUY101010 + - 10-bit per component YCbCr 444, single plane + - Plane 0: 3 components + * Component 0: Y(10) + * Component 1: Cb(10) + * Component 2: Cr(10) + + * - DRM_FORMAT_YUYV + - 8-bit per component YCbCr 422, single plane + - Plane 0: 3 components + * Component 0: Y(8) + * Component 1: Cb(8, 2x1 subsampled) + * Component 2: Cr(8, 2x1 subsampled) + + * - DRM_FORMAT_NV16 + - 8-bit per component YCbCr 422, two plane + - Plane 0: 1 component + * Component 0: Y(8) + Plane 1: 2 components + * Component 0: Cb(8, 2x1 subsampled) + * Component 1: Cr(8, 2x1 subsampled) + + * - DRM_FORMAT_Y210 + - 10-bit per component YCbCr 422, single plane + - Plane 0: 3 components + * Component 0: Y(10) + * Component 1: Cb(10, 2x1 subsampled) + * Component 2: Cr(10, 2x1 subsampled) + + * - DRM_FORMAT_P210 + - 10-bit per component YCbCr 422, two plane + - Plane 0: 1 component + * Component 0: Y(10) + Plane 1: 2 components + * Component 0: Cb(10, 2x1 subsampled) + * Component 1: Cr(10, 2x1 subsampled) + + * - DRM_FORMAT_YUV420_8BIT + - 8-bit per component YCbCr 420, single plane + - Plane 0: 3 components + * Component 0: Y(8) + * Component 1: Cb(8, 2x2 subsampled) + * Component 2: Cr(8, 2x2 subsampled) + + * - DRM_FORMAT_YUV420_10BIT + - 10-bit per component YCbCr 420, single plane + - Plane 0: 3 components + * Component 0: Y(10) + * Component 1: Cb(10, 2x2 subsampled) + * Component 2: Cr(10, 2x2 subsampled) + + * - DRM_FORMAT_NV12 + - 8-bit per component YCbCr 420, two plane + - Plane 0: 1 component + * Component 0: Y(8) + Plane 1: 2 components + * Component 0: Cb(8, 2x2 subsampled) + * Component 1: Cr(8, 2x2 subsampled) + + * - DRM_FORMAT_P010 + - 10-bit per component YCbCr 420, two plane + - Plane 0: 1 component + * Component 0: Y(10) + Plane 1: 2 components + * Component 0: Cb(10, 2x2 subsampled) + * Component 1: Cr(10, 2x2 subsampled) diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst index 7d2d3875ff1a..8ec755024390 100644 --- a/Documentation/gpu/drivers.rst +++ b/Documentation/gpu/drivers.rst @@ -16,6 +16,7 @@ GPU Driver Documentation vkms bridge/dw-hdmi xen-front + afbc .. only:: subproject and html diff --git a/MAINTAINERS b/MAINTAINERS index 1fa3432e9e33..7cce284f01c9 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1091,6 +1091,7 @@ M: Mali DP Maintainers S: Supported F: drivers/gpu/drm/arm/ F: Documentation/devicetree/bindings/display/arm,malidp.txt +F: Documentation/gpu/afbc.rst ARM MFM AND FLOPPY DRIVERS M: Ian Molton diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h index 0156d33f7dab..bd4554950387 100644 --- a/include/uapi/drm/drm_fourcc.h +++ b/include/uapi/drm/drm_fourcc.h @@ -595,6 +595,9 @@ extern "C" { * AFBC has several features which may be supported and/or used, which are * represented using bits in the modifier. Not all combinations are valid, * and different devices or use-cases may support different combinations. + * + * Further information on the use of AFBC modifiers can be found in + * Documentation/gpu/afbc.rst */ #define DRM_FORMAT_MOD_ARM_AFBC(__afbc_mode) fourcc_mod_code(ARM, __afbc_mode)