xref: /openbmc/linux/Documentation/gpu/afbc.rst (revision 3affaa5a) 
1.. SPDX-License-Identifier: GPL-2.0+
2
3===================================
4 Arm Framebuffer Compression (AFBC)
5===================================
6
7AFBC is a proprietary lossless image compression protocol and format.
8It provides fine-grained random access and minimizes the amount of
9data transferred between IP blocks.
10
11AFBC can be enabled on drivers which support it via use of the AFBC
12format modifiers defined in drm_fourcc.h. See DRM_FORMAT_MOD_ARM_AFBC(*).
13
14All users of the AFBC modifiers must follow the usage guidelines laid
15out in this document, to ensure compatibility across different AFBC
16producers and consumers.
17
18Components and Ordering
19=======================
20
21AFBC streams can contain several components - where a component
22corresponds to a color channel (i.e. R, G, B, X, A, Y, Cb, Cr).
23The assignment of input/output color channels must be consistent
24between the encoder and the decoder for correct operation, otherwise
25the consumer will interpret the decoded data incorrectly.
26
27Furthermore, when the lossless colorspace transform is used
28(AFBC_FORMAT_MOD_YTR, which should be enabled for RGB buffers for
29maximum compression efficiency), the component order must be:
30
31 * Component 0: R
32 * Component 1: G
33 * Component 2: B
34
35The component ordering is communicated via the fourcc code in the
36fourcc:modifier pair. In general, component '0' is considered to
37reside in the least-significant bits of the corresponding linear
38format. 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
59In AFBC, 'X' components are not treated any differently from any other
60component. Therefore, an AFBC buffer with fourcc DRM_FORMAT_XBGR8888
61encodes 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
70Please note, however, that the inclusion of a "wasted" 'X' channel is
71bad for compression efficiency, and so it's recommended to avoid
72formats containing 'X' bits. If a fourth component is
73required/expected by the encoder/decoder, then it is recommended to
74instead 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
76which doesn't include alpha can be used, e.g. DRM_FORMAT_BGR888.
77
78Number of Planes
79================
80
81Formats which are typically multi-planar in linear layouts (e.g. YUV
82420), can be encoded into one, or multiple, AFBC planes. As with
83component order, the encoder and decoder must agree about the number
84of planes in order to correctly decode the buffer. The fourcc code is
85used to determine the number of encoded planes in an AFBC buffer,
86matching the number of planes for the linear (unmodified) format.
87Within each plane, the component ordering also follows the fourcc
88code:
89
90For 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
111Cross-device interoperability
112=============================
113
114For maximum compatibility across devices, the table below defines
115canonical formats for use between AFBC-enabled devices. Formats which
116are listed here must be used exactly as specified when using the AFBC
117modifiers. 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)
236