tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
drm/afbc: Add AFBC modifier usage documentation
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>
[Updated MAINTAINERS entry to show that "Mali DP Maintainers" is
actually a mailing list and added an SPDX-License-Identifier to
the documentation]
Signed-off-by: Liviu Dudau <liviu.dudau@arm.com>
authored by
Brian Starkey
and committed by
Liviu Dudau
3affaa5a
bfeffd15
+241
-1
+235
Documentation/gpu/afbc.rst
+235
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)
+1
Documentation/gpu/drivers.rst
+1
Documentation/gpu/drivers.rst
+2
-1
MAINTAINERS
+2
-1
MAINTAINERS
···
1136
1136
ARM MALI-DP DRM DRIVER
1137
1137
M: Liviu Dudau <liviu.dudau@arm.com>
1138
1138
M: Brian Starkey <brian.starkey@arm.com>
1139
-
M: Mali DP Maintainers <malidp@foss.arm.com>
1139
+
L: Mali DP Maintainers <malidp@foss.arm.com>
1140
1140
S: Supported
1141
1141
F: drivers/gpu/drm/arm/
1142
1142
F: Documentation/devicetree/bindings/display/arm,malidp.txt
1143
+
F: Documentation/gpu/afbc.rst
1143
1144
1144
1145
ARM MFM AND FLOPPY DRIVERS
1145
1146
M: Ian Molton <spyro@f2s.com>
+3
include/uapi/drm/drm_fourcc.h
+3
include/uapi/drm/drm_fourcc.h
···
572
572
* AFBC has several features which may be supported and/or used, which are
573
573
* represented using bits in the modifier. Not all combinations are valid,
574
574
* and different devices or use-cases may support different combinations.
575
+
*
576
+
* Further information on the use of AFBC modifiers can be found in
577
+
* Documentation/gpu/afbc.rst
575
578
*/
576
579
#define DRM_FORMAT_MOD_ARM_AFBC(__afbc_mode) fourcc_mod_code(ARM, __afbc_mode)
577
580