1 ======================== 1 ========================
2 Multiplane Overlay (MPO) 2 Multiplane Overlay (MPO)
3 ======================== 3 ========================
4 4
5 .. note:: You will get more from this page if 5 .. note:: You will get more from this page if you have already read the
6 'Documentation/gpu/amdgpu/display/dcn-overv 6 'Documentation/gpu/amdgpu/display/dcn-overview.rst'.
7 7
8 8
9 Multiplane Overlay (MPO) allows for multiple f 9 Multiplane Overlay (MPO) allows for multiple framebuffers to be composited via
10 fixed-function hardware in the display control 10 fixed-function hardware in the display controller rather than using graphics or
11 compute shaders for composition. This can yiel 11 compute shaders for composition. This can yield some power savings if it means
12 the graphics/compute pipelines can be put into 12 the graphics/compute pipelines can be put into low-power states. In summary,
13 MPO can bring the following benefits: 13 MPO can bring the following benefits:
14 14
15 * Decreased GPU and CPU workload - no composit 15 * Decreased GPU and CPU workload - no composition shaders needed, no extra
16 buffer copy needed, GPU can remain idle. 16 buffer copy needed, GPU can remain idle.
17 * Plane independent page flips - No need to be 17 * Plane independent page flips - No need to be tied to global compositor
18 page-flip present rate, reduced latency, ind 18 page-flip present rate, reduced latency, independent timing.
19 19
20 .. note:: Keep in mind that MPO is all about p 20 .. note:: Keep in mind that MPO is all about power-saving; if you want to learn
21 more about power-save in the display contex 21 more about power-save in the display context, check the link:
22 `Power <https://gitlab.freedesktop.org/pq/c 22 `Power <https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/power.rst>`__.
23 23
24 Multiplane Overlay is only available using the 24 Multiplane Overlay is only available using the DRM atomic model. The atomic
25 model only uses a single userspace IOCTL for c 25 model only uses a single userspace IOCTL for configuring the display hardware
26 (modesetting, page-flipping, etc) - drmModeAto 26 (modesetting, page-flipping, etc) - drmModeAtomicCommit. To query hardware
27 resources and limitations userspace also calls 27 resources and limitations userspace also calls into drmModeGetResources which
28 reports back the number of planes, CRTCs, and 28 reports back the number of planes, CRTCs, and connectors. There are three types
29 of DRM planes that the driver can register and 29 of DRM planes that the driver can register and work with:
30 30
31 * ``DRM_PLANE_TYPE_PRIMARY``: Primary planes r 31 * ``DRM_PLANE_TYPE_PRIMARY``: Primary planes represent a "main" plane for a
32 CRTC, primary planes are the planes operated 32 CRTC, primary planes are the planes operated upon by CRTC modesetting and
33 flipping operations. 33 flipping operations.
34 * ``DRM_PLANE_TYPE_CURSOR``: Cursor planes rep 34 * ``DRM_PLANE_TYPE_CURSOR``: Cursor planes represent a "cursor" plane for a
35 CRTC. Cursor planes are the planes operated 35 CRTC. Cursor planes are the planes operated upon by the cursor IOCTLs
36 * ``DRM_PLANE_TYPE_OVERLAY``: Overlay planes r 36 * ``DRM_PLANE_TYPE_OVERLAY``: Overlay planes represent all non-primary,
37 non-cursor planes. Some drivers refer to the 37 non-cursor planes. Some drivers refer to these types of planes as "sprites"
38 internally. 38 internally.
39 39
40 To illustrate how it works, let's take a look 40 To illustrate how it works, let's take a look at a device that exposes the
41 following planes to userspace: 41 following planes to userspace:
42 42
43 * 4 Primary planes (1 per CRTC). 43 * 4 Primary planes (1 per CRTC).
44 * 4 Cursor planes (1 per CRTC). 44 * 4 Cursor planes (1 per CRTC).
45 * 1 Overlay plane (shared among CRTCs). 45 * 1 Overlay plane (shared among CRTCs).
46 46
47 .. note:: Keep in mind that different ASICs mi 47 .. note:: Keep in mind that different ASICs might expose other numbers of
48 planes. 48 planes.
49 49
50 For this hardware example, we have 4 pipes (if 50 For this hardware example, we have 4 pipes (if you don't know what AMD pipe
51 means, look at 'Documentation/gpu/amdgpu/displ 51 means, look at 'Documentation/gpu/amdgpu/display/dcn-overview.rst', section
52 "AMD Hardware Pipeline"). Typically most AMD d 52 "AMD Hardware Pipeline"). Typically most AMD devices operate in a pipe-split
53 configuration for optimal single display outpu 53 configuration for optimal single display output (e.g., 2 pipes per plane).
54 54
55 A typical MPO configuration from userspace - 1 55 A typical MPO configuration from userspace - 1 primary + 1 overlay on a single
56 display - will see 4 pipes in use, 2 per plane 56 display - will see 4 pipes in use, 2 per plane.
57 57
58 At least 1 pipe must be used per plane (primar 58 At least 1 pipe must be used per plane (primary and overlay), so for this
59 hypothetical hardware that we are using as an 59 hypothetical hardware that we are using as an example, we have an absolute
60 limit of 4 planes across all CRTCs. Atomic com 60 limit of 4 planes across all CRTCs. Atomic commits will be rejected for display
61 configurations using more than 4 planes. Again 61 configurations using more than 4 planes. Again, it is important to stress that
62 every DCN has different restrictions; here, we 62 every DCN has different restrictions; here, we are just trying to provide the
63 concept idea. 63 concept idea.
64 64
65 Plane Restrictions 65 Plane Restrictions
66 ================== 66 ==================
67 67
68 AMDGPU imposes restrictions on the use of DRM 68 AMDGPU imposes restrictions on the use of DRM planes in the driver.
69 69
70 Atomic commits will be rejected for commits wh 70 Atomic commits will be rejected for commits which do not follow these
71 restrictions: 71 restrictions:
72 72
73 * Overlay planes must be in ARGB8888 or XRGB88 73 * Overlay planes must be in ARGB8888 or XRGB8888 format
74 * Planes cannot be placed outside of the CRTC 74 * Planes cannot be placed outside of the CRTC destination rectangle
75 * Planes cannot be downscaled more than 1/4x o 75 * Planes cannot be downscaled more than 1/4x of their original size
76 * Planes cannot be upscaled more than 16x of t 76 * Planes cannot be upscaled more than 16x of their original size
77 77
78 Not every property is available on every plane 78 Not every property is available on every plane:
79 79
80 * Only primary planes have color-space and non 80 * Only primary planes have color-space and non-RGB format support
81 * Only overlay planes have alpha blending supp 81 * Only overlay planes have alpha blending support
82 82
83 Cursor Restrictions 83 Cursor Restrictions
84 =================== 84 ===================
85 85
86 Before we start to describe some restrictions 86 Before we start to describe some restrictions around cursor and MPO, see the
87 below image: 87 below image:
88 88
89 .. kernel-figure:: mpo-cursor.svg 89 .. kernel-figure:: mpo-cursor.svg
90 90
91 The image on the left side represents how DRM 91 The image on the left side represents how DRM expects the cursor and planes to
92 be blended. However, AMD hardware handles curs 92 be blended. However, AMD hardware handles cursors differently, as you can see
93 on the right side; basically, our cursor canno 93 on the right side; basically, our cursor cannot be drawn outside its associated
94 plane as it is being treated as part of the pl 94 plane as it is being treated as part of the plane. Another consequence of that
95 is that cursors inherit the color and scale fr 95 is that cursors inherit the color and scale from the plane.
96 96
97 As a result of the above behavior, do not use 97 As a result of the above behavior, do not use legacy API to set up the cursor
98 plane when working with MPO; otherwise, you mi 98 plane when working with MPO; otherwise, you might encounter unexpected
99 behavior. 99 behavior.
100 100
101 In short, AMD HW has no dedicated cursor plane 101 In short, AMD HW has no dedicated cursor planes. A cursor is attached to
102 another plane and therefore inherits any scali 102 another plane and therefore inherits any scaling or color processing from its
103 parent plane. 103 parent plane.
104 104
105 Use Cases 105 Use Cases
106 ========= 106 =========
107 107
108 Picture-in-Picture (PIP) playback - Underlay s 108 Picture-in-Picture (PIP) playback - Underlay strategy
109 ---------------------------------------------- 109 -----------------------------------------------------
110 110
111 Video playback should be done using the "prima 111 Video playback should be done using the "primary plane as underlay" MPO
112 strategy. This is a 2 planes configuration: 112 strategy. This is a 2 planes configuration:
113 113
114 * 1 YUV DRM Primary Plane (e.g. NV12 Video) 114 * 1 YUV DRM Primary Plane (e.g. NV12 Video)
115 * 1 RGBA DRM Overlay Plane (e.g. ARGB8888 desk 115 * 1 RGBA DRM Overlay Plane (e.g. ARGB8888 desktop). The compositor should
116 prepare the framebuffers for the planes as f 116 prepare the framebuffers for the planes as follows:
117 - The overlay plane contains general desktop 117 - The overlay plane contains general desktop UI, video player controls, and video subtitles
118 - Primary plane contains one or more videos 118 - Primary plane contains one or more videos
119 119
120 .. note:: Keep in mind that we could extend th 120 .. note:: Keep in mind that we could extend this configuration to more planes,
121 but that is currently not supported by our 121 but that is currently not supported by our driver yet (maybe if we have a
122 userspace request in the future, we can cha 122 userspace request in the future, we can change that).
123 123
124 See below a single-video example: 124 See below a single-video example:
125 125
126 .. kernel-figure:: single-display-mpo.svg 126 .. kernel-figure:: single-display-mpo.svg
127 127
128 .. note:: We could extend this behavior to mor 128 .. note:: We could extend this behavior to more planes, but that is currently
129 not supported by our driver. 129 not supported by our driver.
130 130
131 The video buffer should be used directly for t 131 The video buffer should be used directly for the primary plane. The video can
132 be scaled and positioned for the desktop using 132 be scaled and positioned for the desktop using the properties: CRTC_X, CRTC_Y,
133 CRTC_W, and CRTC_H. The primary plane should a 133 CRTC_W, and CRTC_H. The primary plane should also have the color encoding and
134 color range properties set based on the source 134 color range properties set based on the source content:
135 135
136 * ``COLOR_RANGE``, ``COLOR_ENCODING`` 136 * ``COLOR_RANGE``, ``COLOR_ENCODING``
137 137
138 The overlay plane should be the native size of 138 The overlay plane should be the native size of the CRTC. The compositor must
139 draw a transparent cutout for where the video 139 draw a transparent cutout for where the video should be placed on the desktop
140 (i.e., set the alpha to zero). The primary pla 140 (i.e., set the alpha to zero). The primary plane video will be visible through
141 the underlay. The overlay plane's buffer may r 141 the underlay. The overlay plane's buffer may remain static while the primary
142 plane's framebuffer is used for standard doubl 142 plane's framebuffer is used for standard double-buffered playback.
143 143
144 The compositor should create a YUV buffer matc 144 The compositor should create a YUV buffer matching the native size of the CRTC.
145 Each video buffer should be composited onto th 145 Each video buffer should be composited onto this YUV buffer for direct YUV
146 scanout. The primary plane should have the col 146 scanout. The primary plane should have the color encoding and color range
147 properties set based on the source content: `` 147 properties set based on the source content: ``COLOR_RANGE``,
148 ``COLOR_ENCODING``. However, be mindful that t 148 ``COLOR_ENCODING``. However, be mindful that the source color space and
149 encoding match for each video since it affect 149 encoding match for each video since it affect the entire plane.
150 150
151 The overlay plane should be the native size of 151 The overlay plane should be the native size of the CRTC. The compositor must
152 draw a transparent cutout for where each video 152 draw a transparent cutout for where each video should be placed on the desktop
153 (i.e., set the alpha to zero). The primary pla 153 (i.e., set the alpha to zero). The primary plane videos will be visible through
154 the underlay. The overlay plane's buffer may r 154 the underlay. The overlay plane's buffer may remain static while compositing
155 operations for video playback will be done on 155 operations for video playback will be done on the video buffer.
156 156
157 This kernel interface is validated using IGT G 157 This kernel interface is validated using IGT GPU Tools. The following tests can
158 be run to validate positioning, blending, scal 158 be run to validate positioning, blending, scaling under a variety of sequences
159 and interactions with operations such as DPMS 159 and interactions with operations such as DPMS and S3:
160 160
161 - ``kms_plane@plane-panning-bottom-right-pipe- 161 - ``kms_plane@plane-panning-bottom-right-pipe-*-planes``
162 - ``kms_plane@plane-panning-bottom-right-suspe 162 - ``kms_plane@plane-panning-bottom-right-suspend-pipe-*-``
163 - ``kms_plane@plane-panning-top-left-pipe-*-`` 163 - ``kms_plane@plane-panning-top-left-pipe-*-``
164 - ``kms_plane@plane-position-covered-pipe-*-`` 164 - ``kms_plane@plane-position-covered-pipe-*-``
165 - ``kms_plane@plane-position-hole-dpms-pipe-*- 165 - ``kms_plane@plane-position-hole-dpms-pipe-*-``
166 - ``kms_plane@plane-position-hole-pipe-*-`` 166 - ``kms_plane@plane-position-hole-pipe-*-``
167 - ``kms_plane_multiple@atomic-pipe-*-tiling-`` 167 - ``kms_plane_multiple@atomic-pipe-*-tiling-``
168 - ``kms_plane_scaling@pipe-*-plane-scaling`` 168 - ``kms_plane_scaling@pipe-*-plane-scaling``
169 - ``kms_plane_alpha_blend@pipe-*-alpha-basic`` 169 - ``kms_plane_alpha_blend@pipe-*-alpha-basic``
170 - ``kms_plane_alpha_blend@pipe-*-alpha-transpa 170 - ``kms_plane_alpha_blend@pipe-*-alpha-transparant-fb``
171 - ``kms_plane_alpha_blend@pipe-*-alpha-opaque- 171 - ``kms_plane_alpha_blend@pipe-*-alpha-opaque-fb``
172 - ``kms_plane_alpha_blend@pipe-*-constant-alph 172 - ``kms_plane_alpha_blend@pipe-*-constant-alpha-min``
173 - ``kms_plane_alpha_blend@pipe-*-constant-alph 173 - ``kms_plane_alpha_blend@pipe-*-constant-alpha-mid``
174 - ``kms_plane_alpha_blend@pipe-*-constant-alph 174 - ``kms_plane_alpha_blend@pipe-*-constant-alpha-max``
175 175
176 Multiple Display MPO 176 Multiple Display MPO
177 -------------------- 177 --------------------
178 178
179 AMDGPU supports display MPO when using multipl 179 AMDGPU supports display MPO when using multiple displays; however, this feature
180 behavior heavily relies on the compositor impl 180 behavior heavily relies on the compositor implementation. Keep in mind that
181 userspace can define different policies. For e 181 userspace can define different policies. For example, some OSes can use MPO to
182 protect the plane that handles the video playb 182 protect the plane that handles the video playback; notice that we don't have
183 many limitations for a single display. Nonethe 183 many limitations for a single display. Nonetheless, this manipulation can have
184 many more restrictions for a multi-display sce 184 many more restrictions for a multi-display scenario. The below example shows a
185 video playback in the middle of two displays, 185 video playback in the middle of two displays, and it is up to the compositor to
186 define a policy on how to handle it: 186 define a policy on how to handle it:
187 187
188 .. kernel-figure:: multi-display-hdcp-mpo.svg 188 .. kernel-figure:: multi-display-hdcp-mpo.svg
189 189
190 Let's discuss some of the hardware limitations 190 Let's discuss some of the hardware limitations we have when dealing with
191 multi-display with MPO. 191 multi-display with MPO.
192 192
193 Limitations 193 Limitations
194 ~~~~~~~~~~~ 194 ~~~~~~~~~~~
195 195
196 For simplicity's sake, for discussing the hard 196 For simplicity's sake, for discussing the hardware limitation, this
197 documentation supposes an example where we hav 197 documentation supposes an example where we have two displays and video playback
198 that will be moved around different displays. 198 that will be moved around different displays.
199 199
200 * **Hardware limitations** 200 * **Hardware limitations**
201 201
202 From the DCN overview page, each display requi 202 From the DCN overview page, each display requires at least one pipe and each
203 MPO plane needs another pipe. As a result, whe 203 MPO plane needs another pipe. As a result, when the video is in the middle of
204 the two displays, we need to use 2 pipes. See 204 the two displays, we need to use 2 pipes. See the example below where we avoid
205 pipe split: 205 pipe split:
206 206
207 - 1 display (1 pipe) + MPO (1 pipe), we will u 207 - 1 display (1 pipe) + MPO (1 pipe), we will use two pipes
208 - 2 displays (2 pipes) + MPO (1-2 pipes); we w 208 - 2 displays (2 pipes) + MPO (1-2 pipes); we will use 4 pipes. MPO in the
209 middle of both displays needs 2 pipes. 209 middle of both displays needs 2 pipes.
210 - 3 Displays (3 pipes) + MPO (1-2 pipes), we n 210 - 3 Displays (3 pipes) + MPO (1-2 pipes), we need 5 pipes.
211 211
212 If we use MPO with multiple displays, the user 212 If we use MPO with multiple displays, the userspace has to decide to enable
213 multiple MPO by the price of limiting the numb 213 multiple MPO by the price of limiting the number of external displays supported
214 or disable it in favor of multiple displays; i 214 or disable it in favor of multiple displays; it is a policy decision. For
215 example: 215 example:
216 216
217 * When ASIC has 3 pipes, AMD hardware can NOT 217 * When ASIC has 3 pipes, AMD hardware can NOT support 2 displays with MPO
218 * When ASIC has 4 pipes, AMD hardware can NOT 218 * When ASIC has 4 pipes, AMD hardware can NOT support 3 displays with MPO
219 219
220 Let's briefly explore how userspace can handle 220 Let's briefly explore how userspace can handle these two display configurations
221 on an ASIC that only supports three pipes. We 221 on an ASIC that only supports three pipes. We can have:
222 222
223 .. kernel-figure:: multi-display-hdcp-mpo-less 223 .. kernel-figure:: multi-display-hdcp-mpo-less-pipe-ex.svg
224 224
225 - Total pipes are 3 225 - Total pipes are 3
226 - User lights up 2 displays (2 out of 3 pipes 226 - User lights up 2 displays (2 out of 3 pipes are used)
227 - User launches video (1 pipe used for MPO) 227 - User launches video (1 pipe used for MPO)
228 - Now, if the user moves the video in the midd 228 - Now, if the user moves the video in the middle of 2 displays, one part of the
229 video won't be MPO since we have used 3/3 pi 229 video won't be MPO since we have used 3/3 pipes.
230 230
231 * **Scaling limitation** 231 * **Scaling limitation**
232 232
233 MPO cannot handle scaling less than 0.25 and m 233 MPO cannot handle scaling less than 0.25 and more than x16. For example:
234 234
235 If 4k video (3840x2160) is playing in windowed 235 If 4k video (3840x2160) is playing in windowed mode, the physical size of the
236 window cannot be smaller than (960x540). 236 window cannot be smaller than (960x540).
237 237
238 .. note:: These scaling limitations might vary 238 .. note:: These scaling limitations might vary from ASIC to ASIC.
239 239
240 * **Size Limitation** 240 * **Size Limitation**
241 241
242 The minimum MPO size is 12px. 242 The minimum MPO size is 12px.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.