Documentation/gpu/afbc.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 ===================================
   4  Arm Framebuffer Compression (AFBC)
   5 ===================================
   6
   7 AFBC is a proprietary lossless image compression protocol and format.
   8 It provides fine-grained random access and minimizes the amount of
   9 data transferred between IP blocks.
  10
  11 AFBC can be enabled on drivers which support it via use of the AFBC
  12 format modifiers defined in drm_fourcc.h. See DRM_FORMAT_MOD_ARM_AFBC(*).
  13
  14 All users of the AFBC modifiers must follow the usage guidelines laid
  15 out in this document, to ensure compatibility across different AFBC
  16 producers and consumers.
  17
  18 Components and Ordering
  19 =======================
  20
  21 AFBC streams can contain several components - where a component
  22 corresponds to a color channel (i.e. R, G, B, X, A, Y, Cb, Cr).
  23 The assignment of input/output color channels must be consistent
  24 between the encoder and the decoder for correct operation, otherwise
  25 the consumer will interpret the decoded data incorrectly.
  26
  27 Furthermore, when the lossless colorspace transform is used
  28 (AFBC_FORMAT_MOD_YTR, which should be enabled for RGB buffers for
  29 maximum compression efficiency), the component order must be:
  30
  31  * Component 0: R
  32  * Component 1: G
  33  * Component 2: B
  34
  35 The component ordering is communicated via the fourcc code in the
  36 fourcc:modifier pair. In general, component '0' is considered to
  37 reside in the least-significant bits of the corresponding linear
  38 format. For example, COMP(bits):
  39
  40  * DRM_FORMAT_ABGR8888
  41
  42    * Component 0: R(8)
  43    * Component 1: G(8)
  44    * Component 2: B(8)
  45    * Component 3: A(8)
  46
  47  * DRM_FORMAT_BGR888
  48
  49    * Component 0: R(8)
  50    * Component 1: G(8)
  51    * Component 2: B(8)
  52
  53  * DRM_FORMAT_YUYV
  54
  55    * Component 0: Y(8)
  56    * Component 1: Cb(8, 2x1 subsampled)
  57    * Component 2: Cr(8, 2x1 subsampled)
  58
  59 In AFBC, 'X' components are not treated any differently from any other
  60 component. Therefore, an AFBC buffer with fourcc DRM_FORMAT_XBGR8888
  61 encodes with 4 components, like so:
  62
  63  * DRM_FORMAT_XBGR8888
  64
  65    * Component 0: R(8)
  66    * Component 1: G(8)
  67    * Component 2: B(8)
  68    * Component 3: X(8)
  69
  70 Please note, however, that the inclusion of a "wasted" 'X' channel is
  71 bad for compression efficiency, and so it's recommended to avoid
  72 formats containing 'X' bits. If a fourth component is
  73 required/expected by the encoder/decoder, then it is recommended to
  74 instead use an equivalent format with alpha, setting all alpha bits to
  75 '1'. If there is no requirement for a fourth component, then a format
  76 which doesn't include alpha can be used, e.g. DRM_FORMAT_BGR888.
  77
  78 Number of Planes
  79 ================
  80
  81 Formats which are typically multi-planar in linear layouts (e.g. YUV
  82 420), can be encoded into one, or multiple, AFBC planes. As with
  83 component order, the encoder and decoder must agree about the number
  84 of planes in order to correctly decode the buffer. The fourcc code is
  85 used to determine the number of encoded planes in an AFBC buffer,
  86 matching the number of planes for the linear (unmodified) format.
  87 Within each plane, the component ordering also follows the fourcc
  88 code:
  89
  90 For example:
  91
  92  * DRM_FORMAT_YUYV: nplanes = 1
  93
  94    * Plane 0:
  95
  96      * Component 0: Y(8)
  97      * Component 1: Cb(8, 2x1 subsampled)
  98      * Component 2: Cr(8, 2x1 subsampled)
  99
 100  * DRM_FORMAT_NV12: nplanes = 2
 101
 102    * Plane 0:
 103
 104      * Component 0: Y(8)
 105
 106    * Plane 1:
 107
 108      * Component 0: Cb(8, 2x1 subsampled)
 109      * Component 1: Cr(8, 2x1 subsampled)
 110
 111 Cross-device interoperability
 112 =============================
 113
 114 For maximum compatibility across devices, the table below defines
 115 canonical formats for use between AFBC-enabled devices. Formats which
 116 are listed here must be used exactly as specified when using the AFBC
 117 modifiers. Formats which are not listed should be avoided.
 118
 119 .. flat-table:: AFBC formats
 120
 121    * - Fourcc code
 122      - Description
 123      - Planes/Components
 124
 125    * - DRM_FORMAT_ABGR2101010
 126      - 10-bit per component RGB, with 2-bit alpha
 127      - Plane 0: 4 components
 128               * Component 0: R(10)
 129               * Component 1: G(10)
 130               * Component 2: B(10)
 131               * Component 3: A(2)
 132
 133    * - DRM_FORMAT_ABGR8888
 134      - 8-bit per component RGB, with 8-bit alpha
 135      - Plane 0: 4 components
 136               * Component 0: R(8)
 137               * Component 1: G(8)
 138               * Component 2: B(8)
 139               * Component 3: A(8)
 140
 141    * - DRM_FORMAT_BGR888
 142      - 8-bit per component RGB
 143      - Plane 0: 3 components
 144               * Component 0: R(8)
 145               * Component 1: G(8)
 146               * Component 2: B(8)
 147
 148    * - DRM_FORMAT_BGR565
 149      - 5/6-bit per component RGB
 150      - Plane 0: 3 components
 151               * Component 0: R(5)
 152               * Component 1: G(6)
 153               * Component 2: B(5)
 154
 155    * - DRM_FORMAT_ABGR1555
 156      - 5-bit per component RGB, with 1-bit alpha
 157      - Plane 0: 4 components
 158               * Component 0: R(5)
 159               * Component 1: G(5)
 160               * Component 2: B(5)
 161               * Component 3: A(1)
 162
 163    * - DRM_FORMAT_VUY888
 164      - 8-bit per component YCbCr 444, single plane
 165      - Plane 0: 3 components
 166               * Component 0: Y(8)
 167               * Component 1: Cb(8)
 168               * Component 2: Cr(8)
 169
 170    * - DRM_FORMAT_VUY101010
 171      - 10-bit per component YCbCr 444, single plane
 172      - Plane 0: 3 components
 173               * Component 0: Y(10)
 174               * Component 1: Cb(10)
 175               * Component 2: Cr(10)
 176
 177    * - DRM_FORMAT_YUYV
 178      - 8-bit per component YCbCr 422, single plane
 179      - Plane 0: 3 components
 180               * Component 0: Y(8)
 181               * Component 1: Cb(8, 2x1 subsampled)
 182               * Component 2: Cr(8, 2x1 subsampled)
 183
 184    * - DRM_FORMAT_NV16
 185      - 8-bit per component YCbCr 422, two plane
 186      - Plane 0: 1 component
 187               * Component 0: Y(8)
 188        Plane 1: 2 components
 189               * Component 0: Cb(8, 2x1 subsampled)
 190               * Component 1: Cr(8, 2x1 subsampled)
 191
 192    * - DRM_FORMAT_Y210
 193      - 10-bit per component YCbCr 422, single plane
 194      - Plane 0: 3 components
 195               * Component 0: Y(10)
 196               * Component 1: Cb(10, 2x1 subsampled)
 197               * Component 2: Cr(10, 2x1 subsampled)
 198
 199    * - DRM_FORMAT_P210
 200      - 10-bit per component YCbCr 422, two plane
 201      - Plane 0: 1 component
 202               * Component 0: Y(10)
 203        Plane 1: 2 components
 204               * Component 0: Cb(10, 2x1 subsampled)
 205               * Component 1: Cr(10, 2x1 subsampled)
 206
 207    * - DRM_FORMAT_YUV420_8BIT
 208      - 8-bit per component YCbCr 420, single plane
 209      - Plane 0: 3 components
 210               * Component 0: Y(8)
 211               * Component 1: Cb(8, 2x2 subsampled)
 212               * Component 2: Cr(8, 2x2 subsampled)
 213
 214    * - DRM_FORMAT_YUV420_10BIT
 215      - 10-bit per component YCbCr 420, single plane
 216      - Plane 0: 3 components
 217               * Component 0: Y(10)
 218               * Component 1: Cb(10, 2x2 subsampled)
 219               * Component 2: Cr(10, 2x2 subsampled)
 220
 221    * - DRM_FORMAT_NV12
 222      - 8-bit per component YCbCr 420, two plane
 223      - Plane 0: 1 component
 224               * Component 0: Y(8)
 225        Plane 1: 2 components
 226               * Component 0: Cb(8, 2x2 subsampled)
 227               * Component 1: Cr(8, 2x2 subsampled)
 228
 229    * - DRM_FORMAT_P010
 230      - 10-bit per component YCbCr 420, two plane
 231      - Plane 0: 1 component
 232               * Component 0: Y(10)
 233        Plane 1: 2 components
 234               * Component 0: Cb(10, 2x2 subsampled)
 235               * Component 1: Cr(10, 2x2 subsampled)