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