diff options
Diffstat (limited to 'Documentation/gpu')
| -rw-r--r-- | Documentation/gpu/afbc.rst | 235 | ||||
| -rw-r--r-- | Documentation/gpu/amdgpu.rst | 24 | ||||
| -rw-r--r-- | Documentation/gpu/dp-mst/topology-figure-1.dot | 52 | ||||
| -rw-r--r-- | Documentation/gpu/dp-mst/topology-figure-2.dot | 56 | ||||
| -rw-r--r-- | Documentation/gpu/dp-mst/topology-figure-3.dot | 59 | ||||
| -rw-r--r-- | Documentation/gpu/drivers.rst | 3 | ||||
| -rw-r--r-- | Documentation/gpu/drm-client.rst | 3 | ||||
| -rw-r--r-- | Documentation/gpu/drm-internals.rst | 79 | ||||
| -rw-r--r-- | Documentation/gpu/drm-kms-helpers.rst | 87 | ||||
| -rw-r--r-- | Documentation/gpu/drm-kms.rst | 96 | ||||
| -rw-r--r-- | Documentation/gpu/drm-mm.rst | 34 | ||||
| -rw-r--r-- | Documentation/gpu/drm-uapi.rst | 27 | ||||
| -rw-r--r-- | Documentation/gpu/i915.rst | 87 | ||||
| -rw-r--r-- | Documentation/gpu/kms-properties.csv | 1 | ||||
| -rw-r--r-- | Documentation/gpu/komeda-kms.rst | 488 | ||||
| -rw-r--r-- | Documentation/gpu/mcde.rst | 8 | ||||
| -rw-r--r-- | Documentation/gpu/meson.rst | 6 | ||||
| -rw-r--r-- | Documentation/gpu/msm-crash-dump.rst | 2 | ||||
| -rw-r--r-- | Documentation/gpu/tinydrm.rst | 30 | ||||
| -rw-r--r-- | Documentation/gpu/todo.rst | 177 | ||||
| -rw-r--r-- | Documentation/gpu/vkms.rst | 11 |
21 files changed, 1228 insertions, 337 deletions
diff --git a/Documentation/gpu/afbc.rst b/Documentation/gpu/afbc.rst new file mode 100644 index 000000000000..4d38dc49d105 --- /dev/null +++ b/Documentation/gpu/afbc.rst @@ -0,0 +1,235 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +=================================== + Arm Framebuffer Compression (AFBC) +=================================== + +AFBC is a proprietary lossless image compression protocol and format. +It provides fine-grained random access and minimizes the amount of +data transferred between IP blocks. + +AFBC can be enabled on drivers which support it via use of the AFBC +format modifiers defined in drm_fourcc.h. See DRM_FORMAT_MOD_ARM_AFBC(*). + +All users of the AFBC modifiers must follow the usage guidelines laid +out in this document, to ensure compatibility across different AFBC +producers and consumers. + +Components and Ordering +======================= + +AFBC streams can contain several components - where a component +corresponds to a color channel (i.e. R, G, B, X, A, Y, Cb, Cr). +The assignment of input/output color channels must be consistent +between the encoder and the decoder for correct operation, otherwise +the consumer will interpret the decoded data incorrectly. + +Furthermore, when the lossless colorspace transform is used +(AFBC_FORMAT_MOD_YTR, which should be enabled for RGB buffers for +maximum compression efficiency), the component order must be: + + * Component 0: R + * Component 1: G + * Component 2: B + +The component ordering is communicated via the fourcc code in the +fourcc:modifier pair. In general, component '0' is considered to +reside in the least-significant bits of the corresponding linear +format. For example, COMP(bits): + + * DRM_FORMAT_ABGR8888 + + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + * Component 3: A(8) + + * DRM_FORMAT_BGR888 + + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + + * DRM_FORMAT_YUYV + + * Component 0: Y(8) + * Component 1: Cb(8, 2x1 subsampled) + * Component 2: Cr(8, 2x1 subsampled) + +In AFBC, 'X' components are not treated any differently from any other +component. Therefore, an AFBC buffer with fourcc DRM_FORMAT_XBGR8888 +encodes with 4 components, like so: + + * DRM_FORMAT_XBGR8888 + + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + * Component 3: X(8) + +Please note, however, that the inclusion of a "wasted" 'X' channel is +bad for compression efficiency, and so it's recommended to avoid +formats containing 'X' bits. If a fourth component is +required/expected by the encoder/decoder, then it is recommended to +instead use an equivalent format with alpha, setting all alpha bits to +'1'. If there is no requirement for a fourth component, then a format +which doesn't include alpha can be used, e.g. DRM_FORMAT_BGR888. + +Number of Planes +================ + +Formats which are typically multi-planar in linear layouts (e.g. YUV +420), can be encoded into one, or multiple, AFBC planes. As with +component order, the encoder and decoder must agree about the number +of planes in order to correctly decode the buffer. The fourcc code is +used to determine the number of encoded planes in an AFBC buffer, +matching the number of planes for the linear (unmodified) format. +Within each plane, the component ordering also follows the fourcc +code: + +For example: + + * DRM_FORMAT_YUYV: nplanes = 1 + + * Plane 0: + + * Component 0: Y(8) + * Component 1: Cb(8, 2x1 subsampled) + * Component 2: Cr(8, 2x1 subsampled) + + * DRM_FORMAT_NV12: nplanes = 2 + + * Plane 0: + + * Component 0: Y(8) + + * Plane 1: + + * Component 0: Cb(8, 2x1 subsampled) + * Component 1: Cr(8, 2x1 subsampled) + +Cross-device interoperability +============================= + +For maximum compatibility across devices, the table below defines +canonical formats for use between AFBC-enabled devices. Formats which +are listed here must be used exactly as specified when using the AFBC +modifiers. Formats which are not listed should be avoided. + +.. flat-table:: AFBC formats + + * - Fourcc code + - Description + - Planes/Components + + * - DRM_FORMAT_ABGR2101010 + - 10-bit per component RGB, with 2-bit alpha + - Plane 0: 4 components + * Component 0: R(10) + * Component 1: G(10) + * Component 2: B(10) + * Component 3: A(2) + + * - DRM_FORMAT_ABGR8888 + - 8-bit per component RGB, with 8-bit alpha + - Plane 0: 4 components + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + * Component 3: A(8) + + * - DRM_FORMAT_BGR888 + - 8-bit per component RGB + - Plane 0: 3 components + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + + * - DRM_FORMAT_BGR565 + - 5/6-bit per component RGB + - Plane 0: 3 components + * Component 0: R(5) + * Component 1: G(6) + * Component 2: B(5) + + * - DRM_FORMAT_ABGR1555 + - 5-bit per component RGB, with 1-bit alpha + - Plane 0: 4 components + * Component 0: R(5) + * Component 1: G(5) + * Component 2: B(5) + * Component 3: A(1) + + * - DRM_FORMAT_VUY888 + - 8-bit per component YCbCr 444, single plane + - Plane 0: 3 components + * Component 0: Y(8) + * Component 1: Cb(8) + * Component 2: Cr(8) + + * - DRM_FORMAT_VUY101010 + - 10-bit per component YCbCr 444, single plane + - Plane 0: 3 components + * Component 0: Y(10) + * Component 1: Cb(10) + * Component 2: Cr(10) + + * - DRM_FORMAT_YUYV + - 8-bit per component YCbCr 422, single plane + - Plane 0: 3 components + * Component 0: Y(8) + * Component 1: Cb(8, 2x1 subsampled) + * Component 2: Cr(8, 2x1 subsampled) + + * - DRM_FORMAT_NV16 + - 8-bit per component YCbCr 422, two plane + - Plane 0: 1 component + * Component 0: Y(8) + Plane 1: 2 components + * Component 0: Cb(8, 2x1 subsampled) + * Component 1: Cr(8, 2x1 subsampled) + + * - DRM_FORMAT_Y210 + - 10-bit per component YCbCr 422, single plane + - Plane 0: 3 components + * Component 0: Y(10) + * Component 1: Cb(10, 2x1 subsampled) + * Component 2: Cr(10, 2x1 subsampled) + + * - DRM_FORMAT_P210 + - 10-bit per component YCbCr 422, two plane + - Plane 0: 1 component + * Component 0: Y(10) + Plane 1: 2 components + * Component 0: Cb(10, 2x1 subsampled) + * Component 1: Cr(10, 2x1 subsampled) + + * - DRM_FORMAT_YUV420_8BIT + - 8-bit per component YCbCr 420, single plane + - Plane 0: 3 components + * Component 0: Y(8) + * Component 1: Cb(8, 2x2 subsampled) + * Component 2: Cr(8, 2x2 subsampled) + + * - DRM_FORMAT_YUV420_10BIT + - 10-bit per component YCbCr 420, single plane + - Plane 0: 3 components + * Component 0: Y(10) + * Component 1: Cb(10, 2x2 subsampled) + * Component 2: Cr(10, 2x2 subsampled) + + * - DRM_FORMAT_NV12 + - 8-bit per component YCbCr 420, two plane + - Plane 0: 1 component + * Component 0: Y(8) + Plane 1: 2 components + * Component 0: Cb(8, 2x2 subsampled) + * Component 1: Cr(8, 2x2 subsampled) + + * - DRM_FORMAT_P010 + - 10-bit per component YCbCr 420, two plane + - Plane 0: 1 component + * Component 0: Y(10) + Plane 1: 2 components + * Component 0: Cb(10, 2x2 subsampled) + * Component 1: Cr(10, 2x2 subsampled) diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst index a740e491dfcc..5acdd1842ea2 100644 --- a/Documentation/gpu/amdgpu.rst +++ b/Documentation/gpu/amdgpu.rst @@ -37,10 +37,10 @@ Buffer Objects PRIME Buffer Sharing -------------------- -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c :doc: PRIME Buffer Sharing -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c :internal: MMU Notifier @@ -70,6 +70,26 @@ Interrupt Handling .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c :internal: +AMDGPU XGMI Support +=================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c + :doc: AMDGPU XGMI Support + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c + :internal: + +AMDGPU RAS debugfs control interface +==================================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS debugfs control interface + + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :internal: + + GPU Power/Thermal Controls and Monitoring ========================================= diff --git a/Documentation/gpu/dp-mst/topology-figure-1.dot b/Documentation/gpu/dp-mst/topology-figure-1.dot new file mode 100644 index 000000000000..157e17c7e0b0 --- /dev/null +++ b/Documentation/gpu/dp-mst/topology-figure-1.dot @@ -0,0 +1,52 @@ +digraph T { + /* Make sure our payloads are always drawn below the driver node */ + subgraph cluster_driver { + fillcolor = grey; + style = filled; + driver -> {payload1, payload2} [dir=none]; + } + + /* Driver malloc references */ + edge [style=dashed]; + driver -> port1; + driver -> port2; + driver -> port3:e; + driver -> port4; + + payload1:s -> port1:e; + payload2:s -> port3:e; + edge [style=""]; + + subgraph cluster_topology { + label="Topology Manager"; + labelloc=bottom; + + /* Topology references */ + mstb1 -> {port1, port2}; + port1 -> mstb2; + port2 -> mstb3 -> {port3, port4}; + port3 -> mstb4; + + /* Malloc references */ + edge [style=dashed;dir=back]; + mstb1 -> {port1, port2}; + port1 -> mstb2; + port2 -> mstb3 -> {port3, port4}; + port3 -> mstb4; + } + + driver [label="DRM driver";style=filled;shape=box;fillcolor=lightblue]; + + payload1 [label="Payload #1";style=filled;shape=box;fillcolor=lightblue]; + payload2 [label="Payload #2";style=filled;shape=box;fillcolor=lightblue]; + + mstb1 [label="MSTB #1";style=filled;fillcolor=palegreen;shape=oval]; + mstb2 [label="MSTB #2";style=filled;fillcolor=palegreen;shape=oval]; + mstb3 [label="MSTB #3";style=filled;fillcolor=palegreen;shape=oval]; + mstb4 [label="MSTB #4";style=filled;fillcolor=palegreen;shape=oval]; + + port1 [label="Port #1";shape=oval]; + port2 [label="Port #2";shape=oval]; + port3 [label="Port #3";shape=oval]; + port4 [label="Port #4";shape=oval]; +} diff --git a/Documentation/gpu/dp-mst/topology-figure-2.dot b/Documentation/gpu/dp-mst/topology-figure-2.dot new file mode 100644 index 000000000000..4243dd1737cb --- /dev/null +++ b/Documentation/gpu/dp-mst/topology-figure-2.dot @@ -0,0 +1,56 @@ +digraph T { + /* Make sure our payloads are always drawn below the driver node */ + subgraph cluster_driver { + fillcolor = grey; + style = filled; + driver -> {payload1, payload2} [dir=none]; + } + + /* Driver malloc references */ + edge [style=dashed]; + driver -> port1; + driver -> port2; + driver -> port3:e; + driver -> port4 [color=red]; + + payload1:s -> port1:e; + payload2:s -> port3:e; + edge [style=""]; + + subgraph cluster_topology { + label="Topology Manager"; + labelloc=bottom; + + /* Topology references */ + mstb1 -> {port1, port2}; + port1 -> mstb2; + edge [color=red]; + port2 -> mstb3 -> {port3, port4}; + port3 -> mstb4; + edge [color=""]; + + /* Malloc references */ + edge [style=dashed;dir=back]; + mstb1 -> {port1, port2}; + port1 -> mstb2; + port2 -> mstb3 -> port3; + edge [color=red]; + mstb3 -> port4; + port3 -> mstb4; + } + + mstb1 [label="MSTB #1";style=filled;fillcolor=palegreen]; + mstb2 [label="MSTB #2";style=filled;fillcolor=palegreen]; + mstb3 [label="MSTB #3";style=filled;fillcolor=palegreen]; + mstb4 [label="MSTB #4";style=filled;fillcolor=grey]; + + port1 [label="Port #1"]; + port2 [label="Port #2"]; + port3 [label="Port #3"]; + port4 [label="Port #4";style=filled;fillcolor=grey]; + + driver [label="DRM driver";style=filled;shape=box;fillcolor=lightblue]; + + payload1 [label="Payload #1";style=filled;shape=box;fillcolor=lightblue]; + payload2 [label="Payload #2";style=filled;shape=box;fillcolor=lightblue]; +} diff --git a/Documentation/gpu/dp-mst/topology-figure-3.dot b/Documentation/gpu/dp-mst/topology-figure-3.dot new file mode 100644 index 000000000000..6cd78d06778b --- /dev/null +++ b/Documentation/gpu/dp-mst/topology-figure-3.dot @@ -0,0 +1,59 @@ +digraph T { + /* Make sure our payloads are always drawn below the driver node */ + subgraph cluster_driver { + fillcolor = grey; + style = filled; + edge [dir=none]; + driver -> payload1; + driver -> payload2 [penwidth=3]; + edge [dir=""]; + } + + /* Driver malloc references */ + edge [style=dashed]; + driver -> port1; + driver -> port2; + driver -> port3:e; + driver -> port4 [color=grey]; + payload1:s -> port1:e; + payload2:s -> port3:e [penwidth=3]; + edge [style=""]; + + subgraph cluster_topology { + label="Topology Manager"; + labelloc=bottom; + + /* Topology references */ + mstb1 -> {port1, port2}; + port1 -> mstb2; + edge [color=grey]; + port2 -> mstb3 -> {port3, port4}; + port3 -> mstb4; + edge [color=""]; + + /* Malloc references */ + edge [style=dashed;dir=back]; + mstb1 -> {port1, port2}; + port1 -> mstb2; + port2 -> mstb3 [penwidth=3]; + mstb3 -> port3 [penwidth=3]; + edge [color=grey]; + mstb3 -> port4; + port3 -> mstb4; + } + + mstb1 [label="MSTB #1";style=filled;fillcolor=palegreen]; + mstb2 [label="MSTB #2";style=filled;fillcolor=palegreen]; + mstb3 [label="MSTB #3";style=filled;fillcolor=palegreen;penwidth=3]; + mstb4 [label="MSTB #4";style=filled;fillcolor=grey]; + + port1 [label="Port #1"]; + port2 [label="Port #2";penwidth=5]; + port3 [label="Port #3";penwidth=3]; + port4 [label="Port #4";style=filled;fillcolor=grey]; + + driver [label="DRM driver";style=filled;shape=box;fillcolor=lightblue]; + + payload1 [label="Payload #1";style=filled;shape=box;fillcolor=lightblue]; + payload2 [label="Payload #2";style=filled;shape=box;fillcolor=lightblue;penwidth=3]; +} diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst index 7c1672118a73..4bfb7068e9f7 100644 --- a/Documentation/gpu/drivers.rst +++ b/Documentation/gpu/drivers.rst @@ -7,6 +7,7 @@ GPU Driver Documentation amdgpu amdgpu-dc i915 + mcde meson pl111 tegra @@ -17,6 +18,8 @@ GPU Driver Documentation vkms bridge/dw-hdmi xen-front + afbc + komeda-kms .. only:: subproject and html diff --git a/Documentation/gpu/drm-client.rst b/Documentation/gpu/drm-client.rst index 7e672063e7eb..58b5a1d1219d 100644 --- a/Documentation/gpu/drm-client.rst +++ b/Documentation/gpu/drm-client.rst @@ -10,3 +10,6 @@ Kernel clients .. kernel-doc:: drivers/gpu/drm/drm_client.c :export: + +.. kernel-doc:: drivers/gpu/drm/drm_client_modeset.c + :export: diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 5ee9674fb9e9..966bd2d9f0cc 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -39,68 +39,6 @@ sections. Driver Information ------------------ -Driver Features -~~~~~~~~~~~~~~~ - -Drivers inform the DRM core about their requirements and supported -features by setting appropriate flags in the driver_features field. -Since those flags influence the DRM core behaviour since registration -time, most of them must be set to registering the :c:type:`struct -drm_driver <drm_driver>` instance. - -u32 driver_features; - -DRIVER_USE_AGP - Driver uses AGP interface, the DRM core will manage AGP resources. - -DRIVER_LEGACY - Denote a legacy driver using shadow attach. Don't use. - -DRIVER_KMS_LEGACY_CONTEXT - Used only by nouveau for backwards compatibility with existing userspace. - Don't use. - -DRIVER_PCI_DMA - Driver is capable of PCI DMA, mapping of PCI DMA buffers to - userspace will be enabled. Deprecated. - -DRIVER_SG - Driver can perform scatter/gather DMA, allocation and mapping of - scatter/gather buffers will be enabled. Deprecated. - -DRIVER_HAVE_DMA - Driver supports DMA, the userspace DMA API will be supported. - Deprecated. - -DRIVER_HAVE_IRQ; DRIVER_IRQ_SHARED - DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler - managed by the DRM Core. The core will support simple IRQ handler - installation when the flag is set. The installation process is - described in ?. - - DRIVER_IRQ_SHARED indicates whether the device & handler support - shared IRQs (note that this is required of PCI drivers). - -DRIVER_GEM - Driver use the GEM memory manager. - -DRIVER_MODESET - Driver supports mode setting interfaces (KMS). - -DRIVER_PRIME - Driver implements DRM PRIME buffer sharing. - -DRIVER_RENDER - Driver supports dedicated render nodes. - -DRIVER_ATOMIC - Driver supports atomic properties. In this case the driver must - implement appropriate obj->atomic_get_property() vfuncs for any - modeset objects with driver specific properties. - -DRIVER_SYNCOBJ - Driver support drm sync objects. - Major, Minor and Patchlevel ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -143,6 +81,9 @@ Device Instance and Driver Handling .. kernel-doc:: drivers/gpu/drm/drm_drv.c :doc: driver instance overview +.. kernel-doc:: include/drm/drm_device.h + :internal: + .. kernel-doc:: include/drm/drm_drv.h :internal: @@ -152,6 +93,11 @@ Device Instance and Driver Handling Driver Load ----------- +Component Helper Usage +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/gpu/drm/drm_drv.c + :doc: component helper usage recommendations IRQ Helper Library ~~~~~~~~~~~~~~~~~~ @@ -230,6 +176,15 @@ Printer .. kernel-doc:: drivers/gpu/drm/drm_print.c :export: +Utilities +--------- + +.. kernel-doc:: include/drm/drm_util.h + :doc: drm utils + +.. kernel-doc:: include/drm/drm_util.h + :internal: + Legacy Support Code =================== diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index b422eb8edf16..b327bbc11182 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -107,6 +107,12 @@ fbdev Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c :export: +format Helper Functions Reference +================================= + +.. kernel-doc:: drivers/gpu/drm/drm_format_helper.c + :export: + Framebuffer CMA Helper Functions Reference ========================================== @@ -116,8 +122,6 @@ Framebuffer CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c :export: -.. _drm_bridges: - Framebuffer GEM Helper Reference ================================ @@ -127,6 +131,8 @@ Framebuffer GEM Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c :export: +.. _drm_bridges: + Bridges ======= @@ -175,6 +181,21 @@ Panel Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c :export: +Panel Self Refresh Helper Reference +=================================== + +.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c + :export: + +HDCP Helper Functions Reference +=============================== + +.. kernel-doc:: drivers/gpu/drm/drm_hdcp.c + :export: + Display Port Helper Functions Reference ======================================= @@ -208,18 +229,40 @@ Display Port Dual Mode Adaptor Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_dp_dual_mode_helper.c :export: -Display Port MST Helper Functions Reference -=========================================== +Display Port MST Helpers +======================== + +Overview +-------- .. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c :doc: dp mst helper +.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c + :doc: Branch device and port refcounting + +Functions Reference +------------------- + .. kernel-doc:: include/drm/drm_dp_mst_helper.h :internal: .. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c :export: +Topology Lifetime Internals +--------------------------- + +These functions aren't exported to drivers, but are documented here to help make +the MST topology helpers easier to understand + +.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c + :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb + drm_dp_mst_topology_put_mstb + drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port + drm_dp_mst_topology_put_port + drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc + MIPI DSI Helper Functions Reference =================================== @@ -274,18 +317,6 @@ SCDC Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c :export: -Rectangle Utilities Reference -============================= - -.. kernel-doc:: include/drm/drm_rect.h - :doc: rect utils - -.. kernel-doc:: include/drm/drm_rect.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/drm_rect.c - :export: - HDMI Infoframes Helper Reference ================================ @@ -300,6 +331,18 @@ libraries and hence is also included here. .. kernel-doc:: drivers/video/hdmi.c :export: +Rectangle Utilities Reference +============================= + +.. kernel-doc:: include/drm/drm_rect.h + :doc: rect utils + +.. kernel-doc:: include/drm/drm_rect.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_rect.c + :export: + Flip-work Helper Reference ========================== @@ -347,3 +390,15 @@ Legacy CRTC/Modeset Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c :export: + +SHMEM GEM Helper Reference +========================== + +.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c + :doc: overview + +.. kernel-doc:: include/drm/drm_gem_shmem_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c + :export: diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 75c882e09fee..23a3c986ef6d 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -410,102 +410,6 @@ Encoder Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_encoder.c :export: -KMS Initialization and Cleanup -============================== - -A KMS device is abstracted and exposed as a set of planes, CRTCs, -encoders and connectors. KMS drivers must thus create and initialize all -those objects at load time after initializing mode setting. - -CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) --------------------------------------------- - -A CRTC is an abstraction representing a part of the chip that contains a -pointer to a scanout buffer. Therefore, the number of CRTCs available -determines how many independent scanout buffers can be active at any -given time. The CRTC structure contains several fields to support this: -a pointer to some video memory (abstracted as a frame buffer object), a -display mode, and an (x, y) offset into the video memory to support -panning or configurations where one piece of video memory spans multiple -CRTCs. - -CRTC Initialization -~~~~~~~~~~~~~~~~~~~ - -A KMS device must create and register at least one struct -:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is -allocated and zeroed by the driver, possibly as part of a larger -structure, and registered with a call to :c:func:`drm_crtc_init()` -with a pointer to CRTC functions. - - -Cleanup -------- - -The DRM core manages its objects' lifetime. When an object is not needed -anymore the core calls its destroy function, which must clean up and -free every resource allocated for the object. Every -:c:func:`drm_\*_init()` call must be matched with a corresponding -:c:func:`drm_\*_cleanup()` call to cleanup CRTCs -(:c:func:`drm_crtc_cleanup()`), planes -(:c:func:`drm_plane_cleanup()`), encoders -(:c:func:`drm_encoder_cleanup()`) and connectors -(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that -have been added to sysfs must be removed by a call to -:c:func:`drm_connector_unregister()` before calling -:c:func:`drm_connector_cleanup()`. - -Connectors state change detection must be cleanup up with a call to -:c:func:`drm_kms_helper_poll_fini()`. - -Output discovery and initialization example -------------------------------------------- - -.. code-block:: c - - void intel_crt_init(struct drm_device *dev) - { - struct drm_connector *connector; - struct intel_output *intel_output; - - intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); - if (!intel_output) - return; - - connector = &intel_output->base; - drm_connector_init(dev, &intel_output->base, - &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); - - drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, - DRM_MODE_ENCODER_DAC); - - drm_connector_attach_encoder(&intel_output->base, - &intel_output->enc); - - /* Set up the DDC bus. */ - intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); - if (!intel_output->ddc_bus) { - dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " - "failed.\n"); - return; - } - - intel_output->type = INTEL_OUTPUT_ANALOG; - connector->interlace_allowed = 0; - connector->doublescan_allowed = 0; - - drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); - drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); - - drm_connector_register(connector); - } - -In the example above (taken from the i915 driver), a CRTC, connector and -encoder combination is created. A device-specific i2c bus is also -created for fetching EDID data and performing monitor detection. Once -the process is complete, the new connector is registered with sysfs to -make its properties available to applications. - KMS Locking =========== diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 54a696d961a7..c8ebd4f66a6a 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -79,7 +79,6 @@ count for the TTM, which will call your initialization function. See the radeon_ttm.c file for an example of usage. - The Graphics Execution Manager (GEM) ==================================== @@ -380,6 +379,39 @@ GEM CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c :export: +VRAM Helper Function Reference +============================== + +.. kernel-doc:: drivers/gpu/drm/drm_vram_helper_common.c + :doc: overview + +.. kernel-doc:: include/drm/drm_gem_vram_helper.h + :internal: + +GEM VRAM Helper Functions Reference +----------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_gem_vram_helper.c + :doc: overview + +.. kernel-doc:: include/drm/drm_gem_vram_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_gem_vram_helper.c + :export: + +VRAM MM Helper Functions Reference +---------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_vram_mm_helper.c + :doc: overview + +.. kernel-doc:: include/drm/drm_vram_mm_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_vram_mm_helper.c + :export: + VMA Offset Manager ================== diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index a752aa561ea4..94f90521f58c 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -85,16 +85,18 @@ leads to a few additional requirements: - The userspace side must be fully reviewed and tested to the standards of that userspace project. For e.g. mesa this means piglit testcases and review on the mailing list. This is again to ensure that the new interface actually gets the - job done. + job done. The userspace-side reviewer should also provide an Acked-by on the + kernel uAPI patch indicating that they believe the proposed uAPI is sound and + sufficiently documented and validated for userspace's consumption. - The userspace patches must be against the canonical upstream, not some vendor fork. This is to make sure that no one cheats on the review and testing requirements by doing a quick fork. - The kernel patch can only be merged after all the above requirements are met, - but it **must** be merged **before** the userspace patches land. uAPI always flows - from the kernel, doing things the other way round risks divergence of the uAPI - definitions and header files. + but it **must** be merged to either drm-next or drm-misc-next **before** the + userspace patches land. uAPI always flows from the kernel, doing things the + other way round risks divergence of the uAPI definitions and header files. These are fairly steep requirements, but have grown out from years of shared pain and experience with uAPI added hastily, and almost always regretted about @@ -238,6 +240,14 @@ DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of Testing and validation ====================== +Testing Requirements for userspace API +-------------------------------------- + +New cross-driver userspace interface extensions, like new IOCTL, new KMS +properties, new files in sysfs or anything else that constitutes an API change +should have driver-agnostic testcases in IGT for that feature, if such a test +can be reasonably made using IGT for the target hardware. + Validating changes with IGT --------------------------- @@ -319,3 +329,12 @@ DRM_IOCTL_MODESET_CTL mode setting, since on many devices the vertical blank counter is reset to 0 at some point during modeset. Modern drivers should not call this any more since with kernel mode setting it is a no-op. + +Userspace API Structures +======================== + +.. kernel-doc:: include/uapi/drm/drm_mode.h + :doc: overview + +.. kernel-doc:: include/uapi/drm/drm_mode.h + :internal: diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 055df45596c1..c38ef0dda605 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -61,7 +61,7 @@ Intel GVT-g Host Support(vGPU device model) Workarounds ----------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_workarounds.c +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c :doc: Hardware workarounds Display Hardware Handling @@ -82,13 +82,13 @@ change. Frontbuffer Tracking -------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c :doc: frontbuffer tracking -.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.h +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.h :internal: -.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c :internal: .. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c @@ -97,10 +97,10 @@ Frontbuffer Tracking Display FIFO Underrun Reporting ------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c :doc: fifo underrun handling -.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c :internal: Plane Configuration @@ -115,10 +115,10 @@ panel self refresh. Atomic Plane Helpers -------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c :doc: atomic plane helpers -.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c :internal: Output Probing @@ -132,19 +132,19 @@ probing, so those sections fully apply. Hotplug ------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c :doc: Hotplug -.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c :internal: High Definition Audio --------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c :doc: High Definition Audio over HDMI and Display Port -.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c :internal: .. kernel-doc:: include/drm/i915_component.h @@ -153,58 +153,58 @@ High Definition Audio Intel HDMI LPE Audio Support ---------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c :doc: LPE Audio integration for HDMI or DP playback -.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c :internal: Panel Self Refresh PSR (PSR/SRD) -------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c :doc: Panel Self Refresh (PSR/SRD) -.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c :internal: Frame Buffer Compression (FBC) ------------------------------ -.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c :doc: Frame Buffer Compression (FBC) -.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c :internal: Display Refresh Rate Switching (DRRS) ------------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :doc: Display Refresh Rate Switching (DRRS) -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_dp_set_drrs_state -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_edp_drrs_enable -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_edp_drrs_disable -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_edp_drrs_invalidate -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_edp_drrs_flush -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_dp_drrs_init DPIO ---- -.. kernel-doc:: drivers/gpu/drm/i915/intel_dpio_phy.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c :doc: DPIO CSR firmware support for DMC @@ -219,34 +219,34 @@ CSR firmware support for DMC Video BIOS Table (VBT) ---------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c :doc: Video BIOS Table (VBT) -.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c :internal: -.. kernel-doc:: drivers/gpu/drm/i915/intel_vbt_defs.h +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_vbt_defs.h :internal: Display clocks -------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c :doc: CDCLK / RAWCLK -.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c :internal: Display PLLs ------------ -.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c :doc: Display PLLs -.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c :internal: -.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.h +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h :internal: Memory Management and Command Submission @@ -349,7 +349,7 @@ of buffer object caches. Shrinking is used to make main memory available. Note that this is mostly orthogonal to evicting buffer objects, which has the goal to make space in gpu virtual address spaces. -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_shrinker.c +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c :internal: Batchbuffer Parsing @@ -373,18 +373,15 @@ Batchbuffer Pools User Batchbuffer Execution -------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_execbuffer.c +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c :doc: User command execution Logical Rings, Logical Ring Contexts and Execlists -------------------------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_lrc.c :doc: Logical Rings, Logical Ring Contexts and Execlists -.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c - :internal: - Global GTT views ---------------- @@ -415,10 +412,10 @@ Hardware Tiling and Swizzling Details Object Tiling IOCTLs -------------------- -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c :internal: -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c :doc: buffer object tiling WOPCM @@ -478,12 +475,6 @@ i915_context_create and i915_context_free .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h :doc: i915_context_create and i915_context_free tracepoints -switch_mm ---------- - -.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h - :doc: switch_mm tracepoint - Perf ==== diff --git a/Documentation/gpu/kms-properties.csv b/Documentation/gpu/kms-properties.csv index bfde04eddd14..07ed22ea3bd6 100644 --- a/Documentation/gpu/kms-properties.csv +++ b/Documentation/gpu/kms-properties.csv @@ -17,7 +17,6 @@ Owner Module/Drivers,Group,Property Name,Type,Property Values,Object attached,De ,Virtual GPU,“suggested X”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an X offset for a connector ,,“suggested Y”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an Y offset for a connector ,Optional,"""aspect ratio""",ENUM,"{ ""None"", ""4:3"", ""16:9"" }",Connector,TDB -,Optional,"""content type""",ENUM,"{ ""No Data"", ""Graphics"", ""Photo"", ""Cinema"", ""Game"" }",Connector,TBD i915,Generic,"""Broadcast RGB""",ENUM,"{ ""Automatic"", ""Full"", ""Limited 16:235"" }",Connector,"When this property is set to Limited 16:235 and CTM is set, the hardware will be programmed with the result of the multiplication of CTM by the limited range matrix to ensure the pixels normaly in the range 0..1.0 are remapped to the range 16/255..235/255." ,,“audio”,ENUM,"{ ""force-dvi"", ""off"", ""auto"", ""on"" }",Connector,TBD ,SDVO-TV,“mode”,ENUM,"{ ""NTSC_M"", ""NTSC_J"", ""NTSC_443"", ""PAL_B"" } etc.",Connector,TBD diff --git a/Documentation/gpu/komeda-kms.rst b/Documentation/gpu/komeda-kms.rst new file mode 100644 index 000000000000..b08da1cffecc --- /dev/null +++ b/Documentation/gpu/komeda-kms.rst @@ -0,0 +1,488 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== + drm/komeda Arm display driver +============================== + +The drm/komeda driver supports the Arm display processor D71 and later products, +this document gives a brief overview of driver design: how it works and why +design it like that. + +Overview of D71 like display IPs +================================ + +From D71, Arm display IP begins to adopt a flexible and modularized +architecture. A display pipeline is made up of multiple individual and +functional pipeline stages called components, and every component has some +specific capabilities that can give the flowed pipeline pixel data a +particular processing. + +Typical D71 components: + +Layer +----- +Layer is the first pipeline stage, which prepares the pixel data for the next +stage. It fetches the pixel from memory, decodes it if it's AFBC, rotates the +source image, unpacks or converts YUV pixels to the device internal RGB pixels, +then adjusts the color_space of pixels if needed. + +Scaler +------ +As its name suggests, scaler takes responsibility for scaling, and D71 also +supports image enhancements by scaler. +The usage of scaler is very flexible and can be connected to layer output +for layer scaling, or connected to compositor and scale the whole display +frame and then feed the output data into wb_layer which will then write it +into memory. + +Compositor (compiz) +------------------- +Compositor blends multiple layers or pixel data flows into one single display +frame. its output frame can be fed into post image processor for showing it on +the monitor or fed into wb_layer and written to memory at the same time. +user can also insert a scaler between compositor and wb_layer to down scale +the display frame first and and then write to memory. + +Writeback Layer (wb_layer) +-------------------------- +Writeback layer does the opposite things of Layer, which connects to compiz +and writes the composition result to memory. + +Post image processor (improc) +----------------------------- +Post image processor adjusts frame data like gamma and color space to fit the +requirements of the monitor. + +Timing controller (timing_ctrlr) +-------------------------------- +Final stage of display pipeline, Timing controller is not for the pixel +handling, but only for controlling the display timing. + +Merger +------ +D71 scaler mostly only has the half horizontal input/output capabilities +compared with Layer, like if Layer supports 4K input size, the scaler only can +support 2K input/output in the same time. To achieve the ful frame scaling, D71 +introduces Layer Split, which splits the whole image to two half parts and feeds +them to two Layers A and B, and does the scaling independently. After scaling +the result need to be fed to merger to merge two part images together, and then +output merged result to compiz. + +Splitter +-------- +Similar to Layer Split, but Splitter is used for writeback, which splits the +compiz result to two parts and then feed them to two scalers. + +Possible D71 Pipeline usage +=========================== + +Benefitting from the modularized architecture, D71 pipelines can be easily +adjusted to fit different usages. And D71 has two pipelines, which support two +types of working mode: + +- Dual display mode + Two pipelines work independently and separately to drive two display outputs. + +- Single display mode + Two pipelines work together to drive only one display output. + + On this mode, pipeline_B doesn't work indenpendently, but outputs its + composition result into pipeline_A, and its pixel timing also derived from + pipeline_A.timing_ctrlr. The pipeline_B works just like a "slave" of + pipeline_A(master) + +Single pipeline data flow +------------------------- + +.. kernel-render:: DOT + :alt: Single pipeline digraph + :caption: Single pipeline data flow + + digraph single_ppl { + rankdir=LR; + + subgraph { + "Memory"; + "Monitor"; + } + + subgraph cluster_pipeline { + style=dashed + node [shape=box] + { + node [bgcolor=grey style=dashed] + "Scaler-0"; + "Scaler-1"; + "Scaler-0/1" + } + + node [bgcolor=grey style=filled] + "Layer-0" -> "Scaler-0" + "Layer-1" -> "Scaler-0" + "Layer-2" -> "Scaler-1" + "Layer-3" -> "Scaler-1" + + "Layer-0" -> "Compiz" + "Layer-1" -> "Compiz" + "Layer-2" -> "Compiz" + "Layer-3" -> "Compiz" + "Scaler-0" -> "Compiz" + "Scaler-1" -> "Compiz" + + "Compiz" -> "Scaler-0/1" -> "Wb_layer" + "Compiz" -> "Improc" -> "Timing Controller" + } + + "Wb_layer" -> "Memory" + "Timing Controller" -> "Monitor" + } + +Dual pipeline with Slave enabled +-------------------------------- + +.. kernel-render:: DOT + :alt: Slave pipeline digraph + :caption: Slave pipeline enabled data flow + + digraph slave_ppl { + rankdir=LR; + + subgraph { + "Memory"; + "Monitor"; + } + node [shape=box] + subgraph cluster_pipeline_slave { + style=dashed + label="Slave Pipeline_B" + node [shape=box] + { + node [bgcolor=grey style=dashed] + "Slave.Scaler-0"; + "Slave.Scaler-1"; + } + + node [bgcolor=grey style=filled] + "Slave.Layer-0" -> "Slave.Scaler-0" + "Slave.Layer-1" -> "Slave.Scaler-0" + "Slave.Layer-2" -> "Slave.Scaler-1" + "Slave.Layer-3" -> "Slave.Scaler-1" + + "Slave.Layer-0" -> "Slave.Compiz" + "Slave.Layer-1" -> "Slave.Compiz" + "Slave.Layer-2" -> "Slave.Compiz" + "Slave.Layer-3" -> "Slave.Compiz" + "Slave.Scaler-0" -> "Slave.Compiz" + "Slave.Scaler-1" -> "Slave.Compiz" + } + + subgraph cluster_pipeline_master { + style=dashed + label="Master Pipeline_A" + node [shape=box] + { + node [bgcolor=grey style=dashed] + "Scaler-0"; + "Scaler-1"; + "Scaler-0/1" + } + + node [bgcolor=grey style=filled] + "Layer-0" -> "Scaler-0" + "Layer-1" -> "Scaler-0" + "Layer-2" -> "Scaler-1" + "Layer-3" -> "Scaler-1" + + "Slave.Compiz" -> "Compiz" + "Layer-0" -> "Compiz" + "Layer-1" -> "Compiz" + "Layer-2" -> "Compiz" + "Layer-3" -> "Compiz" + "Scaler-0" -> "Compiz" + "Scaler-1" -> "Compiz" + + "Compiz" -> "Scaler-0/1" -> "Wb_layer" + "Compiz" -> "Improc" -> "Timing Controller" + } + + "Wb_layer" -> "Memory" + "Timing Controller" -> "Monitor" + } + +Sub-pipelines for input and output +---------------------------------- + +A complete display pipeline can be easily divided into three sub-pipelines +according to the in/out usage. + +Layer(input) pipeline +~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-render:: DOT + :alt: Layer data digraph + :caption: Layer (input) data flow + + digraph layer_data_flow { + rankdir=LR; + node [shape=box] + + { + node [bgcolor=grey style=dashed] + "Scaler-n"; + } + + "Layer-n" -> "Scaler-n" -> "Compiz" + } + +.. kernel-render:: DOT + :alt: Layer Split digraph + :caption: Layer Split pipeline + + digraph layer_data_flow { + rankdir=LR; + node [shape=box] + + "Layer-0/1" -> "Scaler-0" -> "Merger" + "Layer-2/3" -> "Scaler-1" -> "Merger" + "Merger" -> "Compiz" + } + +Writeback(output) pipeline +~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. kernel-render:: DOT + :alt: writeback digraph + :caption: Writeback(output) data flow + + digraph writeback_data_flow { + rankdir=LR; + node [shape=box] + + { + node [bgcolor=grey style=dashed] + "Scaler-n"; + } + + "Compiz" -> "Scaler-n" -> "Wb_layer" + } + +.. kernel-render:: DOT + :alt: split writeback digraph + :caption: Writeback(output) Split data flow + + digraph writeback_data_flow { + rankdir=LR; + node [shape=box] + + "Compiz" -> "Splitter" + "Splitter" -> "Scaler-0" -> "Merger" + "Splitter" -> "Scaler-1" -> "Merger" + "Merger" -> "Wb_layer" + } + +Display output pipeline +~~~~~~~~~~~~~~~~~~~~~~~ +.. kernel-render:: DOT + :alt: display digraph + :caption: display output data flow + + digraph single_ppl { + rankdir=LR; + node [shape=box] + + "Compiz" -> "Improc" -> "Timing Controller" + } + +In the following section we'll see these three sub-pipelines will be handled +by KMS-plane/wb_conn/crtc respectively. + +Komeda Resource abstraction +=========================== + +struct komeda_pipeline/component +-------------------------------- + +To fully utilize and easily access/configure the HW, the driver side also uses +a similar architecture: Pipeline/Component to describe the HW features and +capabilities, and a specific component includes two parts: + +- Data flow controlling. +- Specific component capabilities and features. + +So the driver defines a common header struct komeda_component to describe the +data flow control and all specific components are a subclass of this base +structure. + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h + :internal: + +Resource discovery and initialization +===================================== + +Pipeline and component are used to describe how to handle the pixel data. We +still need a @struct komeda_dev to describe the whole view of the device, and +the control-abilites of device. + +We have &komeda_dev, &komeda_pipeline, &komeda_component. Now fill devices with +pipelines. Since komeda is not for D71 only but also intended for later products, +of course we’d better share as much as possible between different products. To +achieve this, split the komeda device into two layers: CORE and CHIP. + +- CORE: for common features and capabilities handling. +- CHIP: for register programing and HW specific feature (limitation) handling. + +CORE can access CHIP by three chip function structures: + +- struct komeda_dev_funcs +- struct komeda_pipeline_funcs +- struct komeda_component_funcs + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_dev.h + :internal: + +Format handling +=============== + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_format_caps.h + :internal: +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h + :internal: + +Attach komeda_dev to DRM-KMS +============================ + +Komeda abstracts resources by pipeline/component, but DRM-KMS uses +crtc/plane/connector. One KMS-obj cannot represent only one single component, +since the requirements of a single KMS object cannot simply be achieved by a +single component, usually that needs multiple components to fit the requirement. +Like set mode, gamma, ctm for KMS all target on CRTC-obj, but komeda needs +compiz, improc and timing_ctrlr to work together to fit these requirements. +And a KMS-Plane may require multiple komeda resources: layer/scaler/compiz. + +So, one KMS-Obj represents a sub-pipeline of komeda resources. + +- Plane: `Layer(input) pipeline`_ +- Wb_connector: `Writeback(output) pipeline`_ +- Crtc: `Display output pipeline`_ + +So, for komeda, we treat KMS crtc/plane/connector as users of pipeline and +component, and at any one time a pipeline/component only can be used by one +user. And pipeline/component will be treated as private object of DRM-KMS; the +state will be managed by drm_atomic_state as well. + +How to map plane to Layer(input) pipeline +----------------------------------------- + +Komeda has multiple Layer input pipelines, see: +- `Single pipeline data flow`_ +- `Dual pipeline with Slave enabled`_ + +The easiest way is binding a plane to a fixed Layer pipeline, but consider the +komeda capabilities: + +- Layer Split, See `Layer(input) pipeline`_ + + Layer_Split is quite complicated feature, which splits a big image into two + parts and handles it by two layers and two scalers individually. But it + imports an edge problem or effect in the middle of the image after the split. + To avoid such a problem, it needs a complicated Split calculation and some + special configurations to the layer and scaler. We'd better hide such HW + related complexity to user mode. + +- Slave pipeline, See `Dual pipeline with Slave enabled`_ + + Since the compiz component doesn't output alpha value, the slave pipeline + only can be used for bottom layers composition. The komeda driver wants to + hide this limitation to the user. The way to do this is to pick a suitable + Layer according to plane_state->zpos. + +So for komeda, the KMS-plane doesn't represent a fixed komeda layer pipeline, +but multiple Layers with same capabilities. Komeda will select one or more +Layers to fit the requirement of one KMS-plane. + +Make component/pipeline to be drm_private_obj +--------------------------------------------- + +Add :c:type:`drm_private_obj` to :c:type:`komeda_component`, :c:type:`komeda_pipeline` + +.. code-block:: c + + struct komeda_component { + struct drm_private_obj obj; + ... + } + + struct komeda_pipeline { + struct drm_private_obj obj; + ... + } + +Tracking component_state/pipeline_state by drm_atomic_state +----------------------------------------------------------- + +Add :c:type:`drm_private_state` and user to :c:type:`komeda_component_state`, +:c:type:`komeda_pipeline_state` + +.. code-block:: c + + struct komeda_component_state { + struct drm_private_state obj; + void *binding_user; + ... + } + + struct komeda_pipeline_state { + struct drm_private_state obj; + struct drm_crtc *crtc; + ... + } + +komeda component validation +--------------------------- + +Komeda has multiple types of components, but the process of validation are +similar, usually including the following steps: + +.. code-block:: c + + int komeda_xxxx_validate(struct komeda_component_xxx xxx_comp, + struct komeda_component_output *input_dflow, + struct drm_plane/crtc/connector *user, + struct drm_plane/crtc/connector_state, *user_state) + { + setup 1: check if component is needed, like the scaler is optional depending + on the user_state; if unneeded, just return, and the caller will + put the data flow into next stage. + Setup 2: check user_state with component features and capabilities to see + if requirements can be met; if not, return fail. + Setup 3: get component_state from drm_atomic_state, and try set to set + user to component; fail if component has been assigned to another + user already. + Setup 3: configure the component_state, like set its input component, + convert user_state to component specific state. + Setup 4: adjust the input_dflow and prepare it for the next stage. + } + +komeda_kms Abstraction +---------------------- + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_kms.h + :internal: + +komde_kms Functions +------------------- +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_crtc.c + :internal: +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_plane.c + :internal: + +Build komeda to be a Linux module driver +======================================== + +Now we have two level devices: + +- komeda_dev: describes the real display hardware. +- komeda_kms_dev: attachs or connects komeda_dev to DRM-KMS. + +All komeda operations are supplied or operated by komeda_dev or komeda_kms_dev, +the module driver is only a simple wrapper to pass the Linux command +(probe/remove/pm) into komeda_dev or komeda_kms_dev. diff --git a/Documentation/gpu/mcde.rst b/Documentation/gpu/mcde.rst new file mode 100644 index 000000000000..c69e977defda --- /dev/null +++ b/Documentation/gpu/mcde.rst @@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================================= + drm/mcde ST-Ericsson MCDE Multi-channel display engine +======================================================= + +.. kernel-doc:: drivers/gpu/drm/mcde/mcde_drv.c + :doc: ST-Ericsson MCDE DRM Driver diff --git a/Documentation/gpu/meson.rst b/Documentation/gpu/meson.rst index 479f6f51a13b..b9e2f9aa3bd8 100644 --- a/Documentation/gpu/meson.rst +++ b/Documentation/gpu/meson.rst @@ -42,12 +42,6 @@ Video Encoder .. kernel-doc:: drivers/gpu/drm/meson/meson_venc.c :doc: Video Encoder -Video Canvas Management -======================= - -.. kernel-doc:: drivers/gpu/drm/meson/meson_canvas.c - :doc: Canvas - Video Clocks ============ diff --git a/Documentation/gpu/msm-crash-dump.rst b/Documentation/gpu/msm-crash-dump.rst index 757cd257e0d8..240ef200f76c 100644 --- a/Documentation/gpu/msm-crash-dump.rst +++ b/Documentation/gpu/msm-crash-dump.rst @@ -1,3 +1,5 @@ +:orphan: + ===================== MSM Crash Dump Format ===================== diff --git a/Documentation/gpu/tinydrm.rst b/Documentation/gpu/tinydrm.rst index a913644bfc19..33a41544f659 100644 --- a/Documentation/gpu/tinydrm.rst +++ b/Documentation/gpu/tinydrm.rst @@ -1,34 +1,22 @@ -========================== -drm/tinydrm Driver library -========================== +============================ +drm/tinydrm Tiny DRM drivers +============================ -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c - :doc: overview - -Core functionality -================== +tinydrm is a collection of DRM drivers that are so small they can fit in a +single source file. -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c - :doc: core +Helpers +======= -.. kernel-doc:: include/drm/tinydrm/tinydrm.h +.. kernel-doc:: include/drm/tinydrm/tinydrm-helpers.h :internal: -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c +.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-helpers.c :export: .. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-pipe.c :export: -Additional helpers -================== - -.. kernel-doc:: include/drm/tinydrm/tinydrm-helpers.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-helpers.c - :export: - MIPI DBI Compatible Controllers =============================== diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 14191b64446d..0a49c5a1d9ce 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -10,25 +10,6 @@ graphics subsystem useful as newbie projects. Or for slow rainy days. Subsystem-wide refactorings =========================== -De-midlayer drivers -------------------- - -With the recent ``drm_bus`` cleanup patches for 3.17 it is no longer required -to have a ``drm_bus`` structure set up. Drivers can directly set up the -``drm_device`` structure instead of relying on bus methods in ``drm_usb.c`` -and ``drm_pci.c``. The goal is to get rid of the driver's ``->load`` / -``->unload`` callbacks and open-code the load/unload sequence properly, using -the new two-stage ``drm_device`` setup/teardown. - -Once all existing drivers are converted we can also remove those bus support -files for USB and platform devices. - -All you need is a GPU for a non-converted driver (currently almost all of -them, but also all the virtual ones used by KVM, so everyone qualifies). - -Contact: Daniel Vetter, Thierry Reding, respective driver maintainers - - Remove custom dumb_map_offset implementations --------------------------------------------- @@ -82,30 +63,6 @@ events for atomic commits correctly. But fixing these bugs is good anyway. Contact: Daniel Vetter, respective driver maintainers -Better manual-upload support for atomic ---------------------------------------- - -This would be especially useful for tinydrm: - -- Add a struct drm_rect dirty_clip to drm_crtc_state. When duplicating the - crtc state, clear that to the max values, x/y = 0 and w/h = MAX_INT, in - __drm_atomic_helper_crtc_duplicate_state(). - -- Move tinydrm_merge_clips into drm_framebuffer.c, dropping the tinydrm\_ - prefix ofc and using drm_fb\_. drm_framebuffer.c makes sense since this - is a function useful to implement the fb->dirty function. - -- Create a new drm_fb_dirty function which does essentially what e.g. - mipi_dbi_fb_dirty does. You can use e.g. drm_atomic_helper_update_plane as the - template. But instead of doing a simple full-screen plane update, this new - helper also sets crtc_state->dirty_clip to the right coordinates. And of - course it needs to check whether the fb is actually active (and maybe where), - so there's some book-keeping involved. There's also some good fun involved in - scaling things appropriately. For that case we might simply give up and - declare the entire area covered by the plane as dirty. - -Contact: Noralf Trønnes, Daniel Vetter - Fallout from atomic KMS ----------------------- @@ -209,12 +166,42 @@ Would be great to refactor this all into a set of small common helpers. Contact: Daniel Vetter -Put a reservation_object into drm_gem_object +Generic fbdev defio support +--------------------------- + +The defio support code in the fbdev core has some very specific requirements, +which means drivers need to have a special framebuffer for fbdev. Which prevents +us from using the generic fbdev emulation code everywhere. The main issue is +that it uses some fields in struct page itself, which breaks shmem gem objects +(and other things). + +Possible solution would be to write our own defio mmap code in the drm fbdev +emulation. It would need to fully wrap the existing mmap ops, forwarding +everything after it has done the write-protect/mkwrite trickery: + +- In the drm_fbdev_fb_mmap helper, if we need defio, change the + default page prots to write-protected with something like this:: + + vma->vm_page_prot = pgprot_wrprotect(vma->vm_page_prot); + +- Set the mkwrite and fsync callbacks with similar implementions to the core + fbdev defio stuff. These should all work on plain ptes, they don't actually + require a struct page. uff. These should all work on plain ptes, they don't + actually require a struct page. + +- Track the dirty pages in a separate structure (bitfield with one bit per page + should work) to avoid clobbering struct page. + +Might be good to also have some igt testcases for this. + +Contact: Daniel Vetter, Noralf Tronnes + +Remove the ->gem_prime_res_obj callback -------------------------------------------- -This would remove the need for the ->gem_prime_res_obj callback. It would also -allow us to implement generic helpers for waiting for a bo, allowing for quite a -bit of refactoring in the various wait ioctl implementations. +The ->gem_prime_res_obj callback can be removed from drivers by using the +reservation_object in the drm_gem_object. It may also be possible to use the +generic drm_gem_reservation_object_wait helper for waiting for a bo. Contact: Daniel Vetter @@ -241,6 +228,12 @@ struct drm_gem_object_funcs GEM objects can now have a function table instead of having the callbacks on the DRM driver struct. This is now the preferred way and drivers can be moved over. +DRM_GEM_CMA_VMAP_DRIVER_OPS, DRM_GEM_SHMEM_DRIVER_OPS already support this, but +DRM_GEM_VRAM_DRIVER_PRIME does not yet and needs to be aligned with the previous +two. We also need a 2nd version of the CMA define that doesn't require the +vmapping to be present (different hook for prime importing). Plus this needs to +be rolled out to all drivers using their own implementations, too. + Use DRM_MODESET_LOCK_ALL_* helpers instead of boilerplate --------------------------------------------------------- @@ -256,6 +249,59 @@ As a reference, take a look at the conversions already completed in drm core. Contact: Sean Paul, respective driver maintainers +Rename CMA helpers to DMA helpers +--------------------------------- + +CMA (standing for contiguous memory allocator) is really a bit an accident of +what these were used for first, a much better name would be DMA helpers. In the +text these should even be called coherent DMA memory helpers (so maybe CDM, but +no one knows what that means) since underneath they just use dma_alloc_coherent. + +Contact: Laurent Pinchart, Daniel Vetter + +Convert direct mode.vrefresh accesses to use drm_mode_vrefresh() +---------------------------------------------------------------- + +drm_display_mode.vrefresh isn't guaranteed to be populated. As such, using it +is risky and has been known to cause div-by-zero bugs. Fortunately, drm core +has helper which will use mode.vrefresh if it's !0 and will calculate it from +the timings when it's 0. + +Use simple search/replace, or (more fun) cocci to replace instances of direct +vrefresh access with a call to the helper. Check out +https://lists.freedesktop.org/archives/dri-devel/2019-January/205186.html for +inspiration. + +Once all instances of vrefresh have been converted, remove vrefresh from +drm_display_mode to avoid future use. + +Contact: Sean Paul + +Remove drm_display_mode.hsync +----------------------------- + +We have drm_mode_hsync() to calculate this from hsync_start/end, since drivers +shouldn't/don't use this, remove this member to avoid any temptations to use it +in the future. If there is any debug code using drm_display_mode.hsync, convert +it to use drm_mode_hsync() instead. + +Contact: Sean Paul + +drm_fb_helper tasks +------------------- + +- drm_fb_helper_restore_fbdev_mode_unlocked() should call restore_fbdev_mode() + not the _force variant so it can bail out if there is a master. But first + these igt tests need to be fixed: kms_fbcon_fbt@psr and + kms_fbcon_fbt@psr-suspend. + +- The max connector argument for drm_fb_helper_init() and + drm_fb_helper_fbdev_setup() isn't used anymore and can be removed. + +- The helper doesn't keep an array of connectors anymore so these can be + removed: drm_fb_helper_single_add_all_connectors(), + drm_fb_helper_add_one_connector() and drm_fb_helper_remove_one_connector(). + Core refactorings ================= @@ -354,13 +400,6 @@ KMS cleanups Some of these date from the very introduction of KMS in 2008 ... -- drm_mode_config.crtc_idr is misnamed, since it contains all KMS object. Should - be renamed to drm_mode_config.object_idr. - -- drm_display_mode doesn't need to be derived from drm_mode_object. That's - leftovers from older (never merged into upstream) KMS designs where modes - where set using their ID, including support to add/remove modes. - - Make ->funcs and ->helper_private vtables optional. There's a bunch of empty function tables in drivers, but before we can remove them we need to make sure that all the users in helpers and drivers do correctly check for a NULL @@ -432,21 +471,6 @@ those drivers as simple as possible, so lots of room for refactoring: one of the ideas for having a shared dsi/dbi helper, abstracting away the transport details more. -- tinydrm_gem_cma_prime_import_sg_table should probably go into the cma - helpers, as a _vmapped variant (since not every driver needs the vmap). - And tinydrm_gem_cma_free_object could the be merged into - drm_gem_cma_free_object(). - -- tinydrm_fb_create we could move into drm_simple_pipe, only need to add - the fb_create hook to drm_simple_pipe_funcs, which would again simplify a - bunch of things (since it gives you a one-stop vfunc for simple drivers). - -- Quick aside: The unregister devm stuff is kinda getting the lifetimes of - a drm_device wrong. Doesn't matter, since everyone else gets it wrong - too :-) - -- also rework the drm_framebuffer_funcs->dirty hook wire-up, see above. - Contact: Noralf Trønnes, Daniel Vetter AMD DC Display Driver @@ -466,5 +490,20 @@ i915 device_link_add to model the dependency between i915 and snd_had. See https://dri.freedesktop.org/docs/drm/driver-api/device_link.html +Bootsplash +========== + +There is support in place now for writing internal DRM clients making it +possible to pick up the bootsplash work that was rejected because it was written +for fbdev. + +- [v6,8/8] drm/client: Hack: Add bootsplash example + https://patchwork.freedesktop.org/patch/306579/ + +- [RFC PATCH v2 00/13] Kernel based bootsplash + https://lkml.org/lkml/2017/12/13/764 + +Contact: Sam Ravnborg + Outside DRM =========== diff --git a/Documentation/gpu/vkms.rst b/Documentation/gpu/vkms.rst index 7dfc349a4508..61586fc861bb 100644 --- a/Documentation/gpu/vkms.rst +++ b/Documentation/gpu/vkms.rst @@ -23,17 +23,6 @@ CRC API Improvements - Add igt test to check extreme alpha values i.e. fully opaque and fully transparent (intermediate values are affected by hw-specific rounding modes). -Vblank issues -------------- - -Some IGT test cases are failing. Need to analyze why and fix the issues: - -- plain-flip-fb-recreate -- plain-flip-ts-check -- flip-vs-blocking-wf-vblank -- plain-flip-fb-recreate-interruptible -- flip-vs-wf_vblank-interruptible - Runtime Configuration --------------------- |