Re: [RFC AFBC 03/12] drm/afbc: Add AFBC modifier usage documentation

[Liviu Dudau <Liviu.Dudau@arm.com>]

On Thu, Jan 03, 2019 at 05:44:26PM -0300, Ezequiel Garcia wrote:
> Hi Liviu,
> 
> On Mon, 2018-12-03 at 11:31 +0000, Ayan Halder wrote:
> > From: Brian Starkey <brian.starkey@arm.com>
> > 
> > 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 <brian.starkey@arm.com>
> > Reviewed-by: Liviu Dudau <liviu.dudau@arm.com>
> > ---
> 
> I can't find this commit anywhere. Did you decide to reject
> this or perhaps it just fell thru the cracks?

Cracks have opened wide enough to let this through, sorry about that!

I've now sent a pull request to get it merged.

Best regards,
Liviu

> 
> Thanks!
> Ezequiel
> 
> 
> >  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 0000000..922d955
> > --- /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 7c16721..c176b34 100644
> > --- a/Documentation/gpu/drivers.rst
> > +++ b/Documentation/gpu/drivers.rst
> > @@ -17,6 +17,7 @@ GPU Driver Documentation
> >     vkms
> >     bridge/dw-hdmi
> >     xen-front
> > +   afbc
> >  
> >  .. only::  subproject and html
> >  
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index 254b7b2..aef18e3 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -1131,6 +1131,7 @@ M:	Mali DP Maintainers <malidp@foss.arm.com>
> >  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 <spyro@f2s.com>
> > diff --git a/include/uapi/drm/drm_fourcc.h b/include/uapi/drm/drm_fourcc.h
> > index 75c4b5a..0adde4d 100644
> > --- a/include/uapi/drm/drm_fourcc.h
> > +++ b/include/uapi/drm/drm_fourcc.h
> > @@ -597,6 +597,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)
> >  
> 
> 

-- 
====================
| I would like to |
| fix the world,  |
| but they're not |
| giving me the   |
 \ source code!  /
  ---------------
    ¯\_(ツ)_/¯