Documentation/gpu/amdgpu/display/mpo-overview.rst

   1 ========================
   2 Multiplane 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
   9 Multiplane Overlay (MPO) allows for multiple framebuffers to be composited via
  10 fixed-function hardware in the display controller rather than using graphics or
  11 compute shaders for composition. This can yield some power savings if it means
  12 the graphics/compute pipelines can be put into low-power states. In summary,
  13 MPO 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
  24 Multiplane Overlay is only available using the DRM atomic model. The atomic
  25 model only uses a single userspace IOCTL for configuring the display hardware
  26 (modesetting, page-flipping, etc) - drmModeAtomicCommit. To query hardware
  27 resources and limitations userspace also calls into drmModeGetResources which
  28 reports back the number of planes, CRTCs, and connectors. There are three types
  29 of 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
  40 To illustrate how it works, let's take a look at a device that exposes the
  41 following 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
  50 For this hardware example, we have 4 pipes (if you don't know what AMD pipe
  51 means, look at 'Documentation/gpu/amdgpu/display/dcn-overview.rst', section
  52 "AMD Hardware Pipeline"). Typically most AMD devices operate in a pipe-split
  53 configuration for optimal single display output (e.g., 2 pipes per plane).
  54
  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.
  57
  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 example, we have an absolute
  60 limit of 4 planes across all CRTCs. Atomic commits will be rejected for display
  61 configurations using more than 4 planes. Again, it is important to stress that
  62 every DCN has different restrictions; here, we are just trying to provide the
  63 concept idea.
  64
  65 Plane Restrictions
  66 ==================
  67
  68 AMDGPU imposes restrictions on the use of DRM planes in the driver.
  69
  70 Atomic commits will be rejected for commits which do not follow these
  71 restrictions:
  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
  78 Not 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
  83 Cursor Restrictions
  84 ===================
  85
  86 Before we start to describe some restrictions around cursor and MPO, see the
  87 below image:
  88
  89 .. kernel-figure:: mpo-cursor.svg
  90
  91 The image on the left side represents how DRM expects the cursor and planes to
  92 be blended. However, AMD hardware handles cursors differently, as you can see
  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 plane. Another consequence of that
  95 is that cursors inherit the color and scale from the plane.
  96
  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 might encounter unexpected
  99 behavior.
 100
 101 In short, AMD HW has no dedicated cursor planes. A cursor is attached to
 102 another plane and therefore inherits any scaling or color processing from its
 103 parent plane.
 104
 105 Use Cases
 106 =========
 107
 108 Picture-in-Picture (PIP) playback - Underlay strategy
 109 -----------------------------------------------------
 110
 111 Video playback should be done using the "primary plane as underlay" MPO
 112 strategy. 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
 124 See 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
 131 The video buffer should be used directly for the primary plane. The video can
 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 also have the color encoding and
 134 color range properties set based on the source content:
 135
 136 * ``COLOR_RANGE``, ``COLOR_ENCODING``
 137
 138 The overlay plane should be the native size of the CRTC. The compositor must
 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 plane video will be visible through
 141 the underlay. The overlay plane's buffer may remain static while the primary
 142 plane's framebuffer is used for standard double-buffered playback.
 143
 144 The compositor should create a YUV buffer matching the native size of the CRTC.
 145 Each video buffer should be composited onto this YUV buffer for direct YUV
 146 scanout. The primary plane should have the color encoding and color range
 147 properties set based on the source content: ``COLOR_RANGE``,
 148 ``COLOR_ENCODING``. However, be mindful that the source color space and
 149 encoding match for each video since it affect the entire plane.
 150
 151 The overlay plane should be the native size of the CRTC. The compositor must
 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 plane videos will be visible through
 154 the underlay. The overlay plane's buffer may remain static while compositing
 155 operations for video playback will be done on the video buffer.
 156
 157 This kernel interface is validated using IGT GPU Tools. The following tests can
 158 be run to validate positioning, blending, scaling under a variety of sequences
 159 and 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
 176 Multiple Display MPO
 177 --------------------
 178
 179 AMDGPU supports display MPO when using multiple displays; however, this feature
 180 behavior heavily relies on the compositor implementation. Keep in mind that
 181 userspace can define different policies. For example, some OSes can use MPO to
 182 protect the plane that handles the video playback; notice that we don't have
 183 many limitations for a single display. Nonetheless, this manipulation can have
 184 many more restrictions for a multi-display scenario. The below example shows a
 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:
 187
 188 .. kernel-figure:: multi-display-hdcp-mpo.svg
 189
 190 Let's discuss some of the hardware limitations we have when dealing with
 191 multi-display with MPO.
 192
 193 Limitations
 194 ~~~~~~~~~~~
 195
 196 For simplicity's sake, for discussing the hardware limitation, this
 197 documentation supposes an example where we have two displays and video playback
 198 that will be moved around different displays.
 199
 200 * **Hardware limitations**
 201
 202 From the DCN overview page, each display requires at least one pipe and each
 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 the example below where we avoid
 205 pipe 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
 212 If we use MPO with multiple displays, the userspace has to decide to enable
 213 multiple MPO by the price of limiting the number of external displays supported
 214 or disable it in favor of multiple displays; it is a policy decision. For
 215 example:
 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
 220 Let's briefly explore how userspace can handle these two display configurations
 221 on 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
 233 MPO cannot handle scaling less than 0.25 and more than x16. For example:
 234
 235 If 4k video (3840x2160) is playing in windowed mode, the physical size of the
 236 window cannot be smaller than (960x540).
 237
 238 .. note:: These scaling limitations might vary from ASIC to ASIC.
 239
 240 * **Size Limitation**
 241
 242 The minimum MPO size is 12px.