Received: by 2002:ac0:a5a7:0:0:0:0:0 with SMTP id m36-v6csp5354454imm; Tue, 21 Aug 2018 10:15:48 -0700 (PDT) X-Google-Smtp-Source: AA+uWPxn0c8l4vSuKVLejB+zoq65afOeG++xy3HFfmi2VTztOqjC8op8VqkYc2NNmqI5b90dbDWV X-Received: by 2002:a63:9841:: with SMTP id l1-v6mr6966688pgo.228.1534871748793; Tue, 21 Aug 2018 10:15:48 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1534871748; cv=none; d=google.com; s=arc-20160816; b=T12Cny+3Au1kKUbYvZwvibpR1nGnnqzyMzCecfMwdU09EFl9dC2FKnWimPBlpQ9bL+ U3ULbo9GPVFu+N2LcNjmoMId57qU1yYbc9oj+3p4y4K5EZZmWO7eAane1j0008CTdHPo yTXFYv3XoSEd3Jvyih+l11R2RTEbZmnnqLj0In/J9wJjjT8qSIuU0bjEX3dVkKJlSy8d f6VbzBPZmr6F3Tzi7kDbKwp1WPatG+jYr1LOgvGjk6mMUhnAWAtspOYDo79ApdGt2bmt Vn2PePUjHTTGqTTUP30xOjG0lupyWl5qnIqYNh87fc8Ds0h7VBhtaamWa1TNQytydCzL 1GlA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:message-id:date:subject:cc:to:from :arc-authentication-results; bh=BYR1wmL+8n0AOPkm0jnjfHTEuMmfKzl/0zeMU+pazVU=; b=UVJbVkOJ/2WIILpl/aYb4HUJinvotVnDnD87qJr1jp1QrraI6c/iqtrh7wPPdNGmdL KuuHMHZN1gpJUS1Bo3Taw8OtfrUj8jJ+qvFRCwGflJi0+1VRWMNSz7kfn3sr3dQxyFm9 m8lDb/wCG7RawrPbBfAJ8IdxhBaaSjahI75BW2uEHnnJ/P+CuL/LmlvAgatNom73kHX7 Gqv9WwxbfUB2x6glO48Havz13NdOrOK6iFhdRJ840P9Mze1Q7oG3q+ipYnoTcfJ4zkfJ Z5j14wa+d3q70CvbKjzmxAZdJw3tzHitq1Fv7nw4wer6iVveJGe4NOewEEBfYZ0d1Hbr HWFQ== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id m86-v6si13280339pfj.48.2018.08.21.10.15.32; Tue, 21 Aug 2018 10:15:48 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728324AbeHUThG (ORCPT + 99 others); Tue, 21 Aug 2018 15:37:06 -0400 Received: from usa-sjc-mx-foss1.foss.arm.com ([217.140.101.70]:51754 "EHLO foss.arm.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726935AbeHUThG (ORCPT ); Tue, 21 Aug 2018 15:37:06 -0400 Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 338E87A9; Tue, 21 Aug 2018 09:16:20 -0700 (PDT) Received: from e107564-lin.cambridge.arm.com (e107564-lin.cambridge.arm.com [10.2.131.9]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id EF6673F5BC; Tue, 21 Aug 2018 09:16:17 -0700 (PDT) From: Brian Starkey To: dri-devel@lists.freedesktop.org, daniel.vetter@ffwll.ch, airlied@linux.ie, gustavo@padovan.org, maarten.lankhorst@linux.intel.com, seanpaul@chromium.org Cc: corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, alexandru-cosmin.gheorghe@arm.com, liviu.dudau@arm.com, ayan.halder@arm.com Subject: [PATCH] drm/fourcc: Add DOC: overview comment Date: Tue, 21 Aug 2018 17:16:11 +0100 Message-Id: <20180821161611.10424-1-brian.starkey@arm.com> X-Mailer: git-send-email 2.16.1 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org There's a number of things which haven't previously been documented around the usage of format modifiers. Capture the current understanding in an overview comment and add it to the rst documentation. Ideally, the generated documentation would also include documentation of all of the #defines, but the kernel-doc system doesn't currently support kernel-doc comments on #define constants. Suggested-by: Daniel Vetter Signed-off-by: Brian Starkey --- Documentation/gpu/drm-kms.rst | 6 ++++++ include/uapi/drm/drm_fourcc.h | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 1dffd1ac4cd4..1dd9f4824d3b 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -322,6 +322,12 @@ Frame Buffer Functions Reference DRM Format Handling =================== +.. kernel-doc:: include/uapi/drm/drm_fourcc.h + :doc: overview + +Format Functions Reference +-------------------------- + .. kernel-doc:: include/drm/drm_fourcc.h :internal: diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h index 894fa2da32fd..3f6c0b499323 100644 --- a/include/uapi/drm/drm_fourcc.h +++ b/include/uapi/drm/drm_fourcc.h @@ -30,6 +30,42 @@ extern "C" { #endif +/** + * DOC: overview + * + * In the DRM subsystem, framebuffer pixel formats are described using the + * fourcc codes defined in `include/uapi/drm/drm_fourcc.h`. In addition to the + * fourcc code, a Format Modifier may optionally be provided, in order to + * further describe the buffer's format - for example tiling or compression. + * + * Format Modifiers + * ---------------- + * + * Format modifiers are used in conjunction with a fourcc code, forming a + * unique fourcc:modifier pair. This format:modifier pair must fully define the + * format and data layout of the buffer, and should be the only way to describe + * that particular buffer. + * + * Having multiple fourcc:modifier pairs which describe the same layout should + * be avoided, as such aliases run the risk of different drivers exposing + * different names for the same data format, forcing userspace to understand + * that they are aliases. + * + * Format modifiers may change any property of the buffer, including the number + * of planes and/or the required allocation size. Format modifiers are + * vendor-namespaced, and as such the relationship between a fourcc code and a + * modifier is specific to the modifer being used. For example, some modifiers + * may preserve meaning - such as number of planes - from the fourcc code, + * whereas others may not. + * + * Vendors are encouraged to document their modifier usage in as much detail as + * possible, to ensure maximum compatibility across devices, drivers and + * applications. + * + * The authoritative list of format modifier codes is found in + * `include/uapi/drm/drm_fourcc.h` + */ + #define fourcc_code(a, b, c, d) ((__u32)(a) | ((__u32)(b) << 8) | \ ((__u32)(c) << 16) | ((__u32)(d) << 24)) -- 2.16.1