12fa91d15SJani Nikula========================= 22fa91d15SJani NikulaKernel Mode Setting (KMS) 32fa91d15SJani Nikula========================= 42fa91d15SJani Nikula 52fa91d15SJani NikulaDrivers must initialize the mode setting core by calling 6c3b790eaSDaniel Vetterdrmm_mode_config_init() on the DRM device. The function 72fa91d15SJani Nikulainitializes the :c:type:`struct drm_device <drm_device>` 82fa91d15SJani Nikulamode_config field and never fails. Once done, mode configuration must 92fa91d15SJani Nikulabe setup by initializing the following fields. 102fa91d15SJani Nikula 112fa91d15SJani Nikula- int min_width, min_height; int max_width, max_height; 122fa91d15SJani Nikula Minimum and maximum width and height of the frame buffers in pixel 132fa91d15SJani Nikula units. 142fa91d15SJani Nikula 152fa91d15SJani Nikula- struct drm_mode_config_funcs \*funcs; 162fa91d15SJani Nikula Mode setting functions. 172fa91d15SJani Nikula 182564d0b0SDaniel VetterOverview 192564d0b0SDaniel Vetter======== 202564d0b0SDaniel Vetter 212564d0b0SDaniel Vetter.. kernel-render:: DOT 222564d0b0SDaniel Vetter :alt: KMS Display Pipeline 232564d0b0SDaniel Vetter :caption: KMS Display Pipeline Overview 242564d0b0SDaniel Vetter 252564d0b0SDaniel Vetter digraph "KMS" { 262564d0b0SDaniel Vetter node [shape=box] 272564d0b0SDaniel Vetter 282564d0b0SDaniel Vetter subgraph cluster_static { 292564d0b0SDaniel Vetter style=dashed 302564d0b0SDaniel Vetter label="Static Objects" 312564d0b0SDaniel Vetter 322564d0b0SDaniel Vetter node [bgcolor=grey style=filled] 332564d0b0SDaniel Vetter "drm_plane A" -> "drm_crtc" 342564d0b0SDaniel Vetter "drm_plane B" -> "drm_crtc" 352564d0b0SDaniel Vetter "drm_crtc" -> "drm_encoder A" 362564d0b0SDaniel Vetter "drm_crtc" -> "drm_encoder B" 372564d0b0SDaniel Vetter } 382564d0b0SDaniel Vetter 392564d0b0SDaniel Vetter subgraph cluster_user_created { 402564d0b0SDaniel Vetter style=dashed 412564d0b0SDaniel Vetter label="Userspace-Created" 422564d0b0SDaniel Vetter 432564d0b0SDaniel Vetter node [shape=oval] 442564d0b0SDaniel Vetter "drm_framebuffer 1" -> "drm_plane A" 452564d0b0SDaniel Vetter "drm_framebuffer 2" -> "drm_plane B" 462564d0b0SDaniel Vetter } 472564d0b0SDaniel Vetter 482564d0b0SDaniel Vetter subgraph cluster_connector { 492564d0b0SDaniel Vetter style=dashed 502564d0b0SDaniel Vetter label="Hotpluggable" 512564d0b0SDaniel Vetter 522564d0b0SDaniel Vetter "drm_encoder A" -> "drm_connector A" 532564d0b0SDaniel Vetter "drm_encoder B" -> "drm_connector B" 542564d0b0SDaniel Vetter } 552564d0b0SDaniel Vetter } 562564d0b0SDaniel Vetter 572564d0b0SDaniel VetterThe basic object structure KMS presents to userspace is fairly simple. 582564d0b0SDaniel VetterFramebuffers (represented by :c:type:`struct drm_framebuffer <drm_framebuffer>`, 59268bc24eSDaniel Vettersee `Frame Buffer Abstraction`_) feed into planes. Planes are represented by 60268bc24eSDaniel Vetter:c:type:`struct drm_plane <drm_plane>`, see `Plane Abstraction`_ for more 61268bc24eSDaniel Vetterdetails. One or more (or even no) planes feed their pixel data into a CRTC 62268bc24eSDaniel Vetter(represented by :c:type:`struct drm_crtc <drm_crtc>`, see `CRTC Abstraction`_) 63268bc24eSDaniel Vetterfor blending. The precise blending step is explained in more detail in `Plane 64268bc24eSDaniel VetterComposition Properties`_ and related chapters. 652564d0b0SDaniel Vetter 662564d0b0SDaniel VetterFor the output routing the first step is encoders (represented by 672564d0b0SDaniel Vetter:c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those 682564d0b0SDaniel Vetterare really just internal artifacts of the helper libraries used to implement KMS 69d56b699dSBjorn Helgaasdrivers. Besides that they make it unnecessarily more complicated for userspace 702564d0b0SDaniel Vetterto figure out which connections between a CRTC and a connector are possible, and 712564d0b0SDaniel Vetterwhat kind of cloning is supported, they serve no purpose in the userspace API. 722564d0b0SDaniel VetterUnfortunately encoders have been exposed to userspace, hence can't remove them 73d56b699dSBjorn Helgaasat this point. Furthermore the exposed restrictions are often wrongly set by 742564d0b0SDaniel Vetterdrivers, and in many cases not powerful enough to express the real restrictions. 752564d0b0SDaniel VetterA CRTC can be connected to multiple encoders, and for an active CRTC there must 762564d0b0SDaniel Vetterbe at least one encoder. 772564d0b0SDaniel Vetter 782564d0b0SDaniel VetterThe final, and real, endpoint in the display chain is the connector (represented 792564d0b0SDaniel Vetterby :c:type:`struct drm_connector <drm_connector>`, see `Connector 802564d0b0SDaniel VetterAbstraction`_). Connectors can have different possible encoders, but the kernel 812564d0b0SDaniel Vetterdriver selects which encoder to use for each connector. The use case is DVI, 822564d0b0SDaniel Vetterwhich could switch between an analog and a digital encoder. Encoders can also 832564d0b0SDaniel Vetterdrive multiple different connectors. There is exactly one active connector for 842564d0b0SDaniel Vetterevery active encoder. 852564d0b0SDaniel Vetter 862564d0b0SDaniel VetterInternally the output pipeline is a bit more complex and matches today's 872564d0b0SDaniel Vetterhardware more closely: 882564d0b0SDaniel Vetter 892564d0b0SDaniel Vetter.. kernel-render:: DOT 902564d0b0SDaniel Vetter :alt: KMS Output Pipeline 912564d0b0SDaniel Vetter :caption: KMS Output Pipeline 922564d0b0SDaniel Vetter 932564d0b0SDaniel Vetter digraph "Output Pipeline" { 942564d0b0SDaniel Vetter node [shape=box] 952564d0b0SDaniel Vetter 962564d0b0SDaniel Vetter subgraph { 972564d0b0SDaniel Vetter "drm_crtc" [bgcolor=grey style=filled] 982564d0b0SDaniel Vetter } 992564d0b0SDaniel Vetter 1002564d0b0SDaniel Vetter subgraph cluster_internal { 1012564d0b0SDaniel Vetter style=dashed 1022564d0b0SDaniel Vetter label="Internal Pipeline" 1032564d0b0SDaniel Vetter { 1042564d0b0SDaniel Vetter node [bgcolor=grey style=filled] 1052564d0b0SDaniel Vetter "drm_encoder A"; 1062564d0b0SDaniel Vetter "drm_encoder B"; 1072564d0b0SDaniel Vetter "drm_encoder C"; 1082564d0b0SDaniel Vetter } 1092564d0b0SDaniel Vetter 1102564d0b0SDaniel Vetter { 1112564d0b0SDaniel Vetter node [bgcolor=grey style=filled] 1122564d0b0SDaniel Vetter "drm_encoder B" -> "drm_bridge B" 1132564d0b0SDaniel Vetter "drm_encoder C" -> "drm_bridge C1" 1142564d0b0SDaniel Vetter "drm_bridge C1" -> "drm_bridge C2"; 1152564d0b0SDaniel Vetter } 1162564d0b0SDaniel Vetter } 1172564d0b0SDaniel Vetter 1182564d0b0SDaniel Vetter "drm_crtc" -> "drm_encoder A" 1192564d0b0SDaniel Vetter "drm_crtc" -> "drm_encoder B" 1202564d0b0SDaniel Vetter "drm_crtc" -> "drm_encoder C" 1212564d0b0SDaniel Vetter 1222564d0b0SDaniel Vetter 1232564d0b0SDaniel Vetter subgraph cluster_output { 1242564d0b0SDaniel Vetter style=dashed 1252564d0b0SDaniel Vetter label="Outputs" 1262564d0b0SDaniel Vetter 1272564d0b0SDaniel Vetter "drm_encoder A" -> "drm_connector A"; 1282564d0b0SDaniel Vetter "drm_bridge B" -> "drm_connector B"; 1292564d0b0SDaniel Vetter "drm_bridge C2" -> "drm_connector C"; 1302564d0b0SDaniel Vetter 1312564d0b0SDaniel Vetter "drm_panel" 1322564d0b0SDaniel Vetter } 1332564d0b0SDaniel Vetter } 1342564d0b0SDaniel Vetter 1352564d0b0SDaniel VetterInternally two additional helper objects come into play. First, to be able to 1362564d0b0SDaniel Vettershare code for encoders (sometimes on the same SoC, sometimes off-chip) one or 1372564d0b0SDaniel Vettermore :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge 1382564d0b0SDaniel Vetter<drm_bridge>`) can be linked to an encoder. This link is static and cannot be 1392564d0b0SDaniel Vetterchanged, which means the cross-bar (if there is any) needs to be mapped between 1402564d0b0SDaniel Vetterthe CRTC and any encoders. Often for drivers with bridges there's no code left 1412564d0b0SDaniel Vetterat the encoder level. Atomic drivers can leave out all the encoder callbacks to 1422564d0b0SDaniel Vetteressentially only leave a dummy routing object behind, which is needed for 1432564d0b0SDaniel Vetterbackwards compatibility since encoders are exposed to userspace. 1442564d0b0SDaniel Vetter 1452564d0b0SDaniel VetterThe second object is for panels, represented by :c:type:`struct drm_panel 1462564d0b0SDaniel Vetter<drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding 1472564d0b0SDaniel Vetterpoint, but are generally linked to the driver private structure that embeds 1482564d0b0SDaniel Vetter:c:type:`struct drm_connector <drm_connector>`. 1492564d0b0SDaniel Vetter 1502564d0b0SDaniel VetterNote that currently the bridge chaining and interactions with connectors and 1512564d0b0SDaniel Vetterpanels are still in-flux and not really fully sorted out yet. 15228575f16SDaniel Vetter 15328575f16SDaniel VetterKMS Core Structures and Functions 15428575f16SDaniel Vetter================================= 15528575f16SDaniel Vetter 15628575f16SDaniel Vetter.. kernel-doc:: include/drm/drm_mode_config.h 15728575f16SDaniel Vetter :internal: 15828575f16SDaniel Vetter 1591ea35768SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_mode_config.c 1601ea35768SDaniel Vetter :export: 1611ea35768SDaniel Vetter 1626e5b47a4SSimon Ser.. _kms_base_object_abstraction: 1636e5b47a4SSimon Ser 164949619f3SDaniel VetterModeset Base Object Abstraction 165949619f3SDaniel Vetter=============================== 166949619f3SDaniel Vetter 167b2b82c26SDaniel Vetter.. kernel-render:: DOT 168b2b82c26SDaniel Vetter :alt: Mode Objects and Properties 169b2b82c26SDaniel Vetter :caption: Mode Objects and Properties 170b2b82c26SDaniel Vetter 171b2b82c26SDaniel Vetter digraph { 172b2b82c26SDaniel Vetter node [shape=box] 173b2b82c26SDaniel Vetter 174b2b82c26SDaniel Vetter "drm_property A" -> "drm_mode_object A" 175b2b82c26SDaniel Vetter "drm_property A" -> "drm_mode_object B" 176b2b82c26SDaniel Vetter "drm_property B" -> "drm_mode_object A" 177b2b82c26SDaniel Vetter } 178b2b82c26SDaniel Vetter 179b2b82c26SDaniel VetterThe base structure for all KMS objects is :c:type:`struct drm_mode_object 180b2b82c26SDaniel Vetter<drm_mode_object>`. One of the base services it provides is tracking properties, 181b2b82c26SDaniel Vetterwhich are especially important for the atomic IOCTL (see `Atomic Mode 182b2b82c26SDaniel VetterSetting`_). The somewhat surprising part here is that properties are not 183b2b82c26SDaniel Vetterdirectly instantiated on each object, but free-standing mode objects themselves, 184b2b82c26SDaniel Vetterrepresented by :c:type:`struct drm_property <drm_property>`, which only specify 185b2b82c26SDaniel Vetterthe type and value range of a property. Any given property can be attached 1866acc942cSDaniel Vettermultiple times to different objects using drm_object_attach_property(). 187b2b82c26SDaniel Vetter 188949619f3SDaniel Vetter.. kernel-doc:: include/drm/drm_mode_object.h 189949619f3SDaniel Vetter :internal: 190949619f3SDaniel Vetter 191949619f3SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c 192949619f3SDaniel Vetter :export: 193949619f3SDaniel Vetter 1944a8e2292SDaniel VetterAtomic Mode Setting 1954a8e2292SDaniel Vetter=================== 1964a8e2292SDaniel Vetter 1974a8e2292SDaniel Vetter 1984a8e2292SDaniel Vetter.. kernel-render:: DOT 1994a8e2292SDaniel Vetter :alt: Mode Objects and Properties 2004a8e2292SDaniel Vetter :caption: Mode Objects and Properties 2014a8e2292SDaniel Vetter 2024a8e2292SDaniel Vetter digraph { 2034a8e2292SDaniel Vetter node [shape=box] 2044a8e2292SDaniel Vetter 2054a8e2292SDaniel Vetter subgraph cluster_state { 2064a8e2292SDaniel Vetter style=dashed 2074a8e2292SDaniel Vetter label="Free-standing state" 2084a8e2292SDaniel Vetter 2094a8e2292SDaniel Vetter "drm_atomic_state" -> "duplicated drm_plane_state A" 2104a8e2292SDaniel Vetter "drm_atomic_state" -> "duplicated drm_plane_state B" 2114a8e2292SDaniel Vetter "drm_atomic_state" -> "duplicated drm_crtc_state" 2124a8e2292SDaniel Vetter "drm_atomic_state" -> "duplicated drm_connector_state" 2134a8e2292SDaniel Vetter "drm_atomic_state" -> "duplicated driver private state" 2144a8e2292SDaniel Vetter } 2154a8e2292SDaniel Vetter 2164a8e2292SDaniel Vetter subgraph cluster_current { 2174a8e2292SDaniel Vetter style=dashed 2184a8e2292SDaniel Vetter label="Current state" 2194a8e2292SDaniel Vetter 2204a8e2292SDaniel Vetter "drm_device" -> "drm_plane A" 2214a8e2292SDaniel Vetter "drm_device" -> "drm_plane B" 2224a8e2292SDaniel Vetter "drm_device" -> "drm_crtc" 2234a8e2292SDaniel Vetter "drm_device" -> "drm_connector" 2244a8e2292SDaniel Vetter "drm_device" -> "driver private object" 2254a8e2292SDaniel Vetter 2264a8e2292SDaniel Vetter "drm_plane A" -> "drm_plane_state A" 2274a8e2292SDaniel Vetter "drm_plane B" -> "drm_plane_state B" 2284a8e2292SDaniel Vetter "drm_crtc" -> "drm_crtc_state" 2294a8e2292SDaniel Vetter "drm_connector" -> "drm_connector_state" 2304a8e2292SDaniel Vetter "driver private object" -> "driver private state" 2314a8e2292SDaniel Vetter } 2324a8e2292SDaniel Vetter 2334a8e2292SDaniel Vetter "drm_atomic_state" -> "drm_device" [label="atomic_commit"] 2344a8e2292SDaniel Vetter "duplicated drm_plane_state A" -> "drm_device"[style=invis] 2354a8e2292SDaniel Vetter } 2364a8e2292SDaniel Vetter 2374a8e2292SDaniel VetterAtomic provides transactional modeset (including planes) updates, but a 2384a8e2292SDaniel Vetterbit differently from the usual transactional approach of try-commit and 2394a8e2292SDaniel Vetterrollback: 2404a8e2292SDaniel Vetter 2414a8e2292SDaniel Vetter- Firstly, no hardware changes are allowed when the commit would fail. This 2424a8e2292SDaniel Vetter allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows 2434a8e2292SDaniel Vetter userspace to explore whether certain configurations would work or not. 2444a8e2292SDaniel Vetter 2454a8e2292SDaniel Vetter- This would still allow setting and rollback of just the software state, 2464a8e2292SDaniel Vetter simplifying conversion of existing drivers. But auditing drivers for 2474a8e2292SDaniel Vetter correctness of the atomic_check code becomes really hard with that: Rolling 2484a8e2292SDaniel Vetter back changes in data structures all over the place is hard to get right. 2494a8e2292SDaniel Vetter 2504a8e2292SDaniel Vetter- Lastly, for backwards compatibility and to support all use-cases, atomic 2514a8e2292SDaniel Vetter updates need to be incremental and be able to execute in parallel. Hardware 2524a8e2292SDaniel Vetter doesn't always allow it, but where possible plane updates on different CRTCs 2534a8e2292SDaniel Vetter should not interfere, and not get stalled due to output routing changing on 2544a8e2292SDaniel Vetter different CRTCs. 2554a8e2292SDaniel Vetter 2564a8e2292SDaniel VetterTaken all together there's two consequences for the atomic design: 2574a8e2292SDaniel Vetter 2584a8e2292SDaniel Vetter- The overall state is split up into per-object state structures: 2594a8e2292SDaniel Vetter :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct 2604a8e2292SDaniel Vetter drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct 2614a8e2292SDaniel Vetter drm_connector_state <drm_connector_state>` for connectors. These are the only 2624a8e2292SDaniel Vetter objects with userspace-visible and settable state. For internal state drivers 263d56b699dSBjorn Helgaas can subclass these structures through embedding, or add entirely new state 2640380c684SDaniel Vetter structures for their globally shared hardware functions, see :c:type:`struct 2650380c684SDaniel Vetter drm_private_state<drm_private_state>`. 2664a8e2292SDaniel Vetter 2674a8e2292SDaniel Vetter- An atomic update is assembled and validated as an entirely free-standing pile 2684a8e2292SDaniel Vetter of structures within the :c:type:`drm_atomic_state <drm_atomic_state>` 2695fca5eceSDaniel Vetter container. Driver private state structures are also tracked in the same 2705fca5eceSDaniel Vetter structure; see the next chapter. Only when a state is committed is it applied 2715fca5eceSDaniel Vetter to the driver and modeset objects. This way rolling back an update boils down 2725fca5eceSDaniel Vetter to releasing memory and unreferencing objects like framebuffers. 2734a8e2292SDaniel Vetter 2740380c684SDaniel VetterLocking of atomic state structures is internally using :c:type:`struct 2750380c684SDaniel Vetterdrm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be 2760380c684SDaniel Vetterexposed to drivers, instead the right locks should be automatically acquired by 2770380c684SDaniel Vetterany function that duplicates or peeks into a state, like e.g. 2786acc942cSDaniel Vetterdrm_atomic_get_crtc_state(). Locking only protects the software data 2790380c684SDaniel Vetterstructure, ordering of committing state changes to hardware is sequenced using 2800380c684SDaniel Vetter:c:type:`struct drm_crtc_commit <drm_crtc_commit>`. 2810380c684SDaniel Vetter 2824a8e2292SDaniel VetterRead on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed 2834a8e2292SDaniel Vettercoverage of specific topics. 2844a8e2292SDaniel Vetter 285da6c0596SDaniel VetterHandling Driver Private State 286da6c0596SDaniel Vetter----------------------------- 287da6c0596SDaniel Vetter 288da6c0596SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 289da6c0596SDaniel Vetter :doc: handling driver private state 290da6c0596SDaniel Vetter 2912fa91d15SJani NikulaAtomic Mode Setting Function Reference 2924a8e2292SDaniel Vetter-------------------------------------- 2932fa91d15SJani Nikula 2945d070be6SDaniel Vetter.. kernel-doc:: include/drm/drm_atomic.h 2952fa91d15SJani Nikula :internal: 2962fa91d15SJani Nikula 2971ea35768SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 2981ea35768SDaniel Vetter :export: 2991ea35768SDaniel Vetter 30072fdb40cSDaniel VetterAtomic Mode Setting IOCTL and UAPI Functions 30172fdb40cSDaniel Vetter-------------------------------------------- 30272fdb40cSDaniel Vetter 30372fdb40cSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 30472fdb40cSDaniel Vetter :doc: overview 30572fdb40cSDaniel Vetter 30672fdb40cSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 30772fdb40cSDaniel Vetter :export: 30872fdb40cSDaniel Vetter 30928575f16SDaniel VetterCRTC Abstraction 31028575f16SDaniel Vetter================ 31128575f16SDaniel Vetter 31228575f16SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 313d5d487ebSDaniel Vetter :doc: overview 314d5d487ebSDaniel Vetter 315d5d487ebSDaniel VetterCRTC Functions Reference 316d5d487ebSDaniel Vetter-------------------------------- 31728575f16SDaniel Vetter 31828575f16SDaniel Vetter.. kernel-doc:: include/drm/drm_crtc.h 31928575f16SDaniel Vetter :internal: 32028575f16SDaniel Vetter 321d5d487ebSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 322d5d487ebSDaniel Vetter :export: 323d5d487ebSDaniel Vetter 3242189100cSSimon SerColor Management Functions Reference 3252189100cSSimon Ser------------------------------------ 3262189100cSSimon Ser 3272189100cSSimon Ser.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 3282189100cSSimon Ser :export: 3292189100cSSimon Ser 3302189100cSSimon Ser.. kernel-doc:: include/drm/drm_color_mgmt.h 3312189100cSSimon Ser :internal: 3322189100cSSimon Ser 3332fa91d15SJani NikulaFrame Buffer Abstraction 334311b62d9SDaniel Vetter======================== 3352fa91d15SJani Nikula 336750fb8c4SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 337750fb8c4SDaniel Vetter :doc: overview 3382fa91d15SJani Nikula 3397520a277SDaniel VetterFrame Buffer Functions Reference 3407520a277SDaniel Vetter-------------------------------- 3417520a277SDaniel Vetter 3427520a277SDaniel Vetter.. kernel-doc:: include/drm/drm_framebuffer.h 3437520a277SDaniel Vetter :internal: 3447520a277SDaniel Vetter 3451ea35768SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 3461ea35768SDaniel Vetter :export: 3471ea35768SDaniel Vetter 3482fa91d15SJani NikulaDRM Format Handling 349311b62d9SDaniel Vetter=================== 3502fa91d15SJani Nikula 3517e7b68efSBrian Starkey.. kernel-doc:: include/uapi/drm/drm_fourcc.h 3527e7b68efSBrian Starkey :doc: overview 3537e7b68efSBrian Starkey 3547e7b68efSBrian StarkeyFormat Functions Reference 3557e7b68efSBrian Starkey-------------------------- 3567e7b68efSBrian Starkey 35784770cc2SLaurent Pinchart.. kernel-doc:: include/drm/drm_fourcc.h 35884770cc2SLaurent Pinchart :internal: 35984770cc2SLaurent Pinchart 3602fa91d15SJani Nikula.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c 3612fa91d15SJani Nikula :export: 3622fa91d15SJani Nikula 363b8644c4aSSimon Ser.. _kms_dumb_buffer_objects: 364b8644c4aSSimon Ser 3652fa91d15SJani NikulaDumb Buffer Objects 366311b62d9SDaniel Vetter=================== 3672fa91d15SJani Nikula 3684f93624eSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c 3694f93624eSDaniel Vetter :doc: overview 3702fa91d15SJani Nikula 37143968d7bSDaniel VetterPlane Abstraction 37243968d7bSDaniel Vetter================= 37343968d7bSDaniel Vetter 374532b3671SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_plane.c 375532b3671SDaniel Vetter :doc: overview 376532b3671SDaniel Vetter 37743968d7bSDaniel VetterPlane Functions Reference 37843968d7bSDaniel Vetter------------------------- 37943968d7bSDaniel Vetter 38043968d7bSDaniel Vetter.. kernel-doc:: include/drm/drm_plane.h 38143968d7bSDaniel Vetter :internal: 38243968d7bSDaniel Vetter 38343968d7bSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_plane.c 38443968d7bSDaniel Vetter :export: 38543968d7bSDaniel Vetter 3869d8f78f6SSimon SerPlane Composition Functions Reference 3879d8f78f6SSimon Ser------------------------------------- 3889d8f78f6SSimon Ser 3899d8f78f6SSimon Ser.. kernel-doc:: drivers/gpu/drm/drm_blend.c 3909d8f78f6SSimon Ser :export: 3919d8f78f6SSimon Ser 39231c558f4SSimon SerPlane Damage Tracking Functions Reference 39331c558f4SSimon Ser----------------------------------------- 39431c558f4SSimon Ser 39531c558f4SSimon Ser.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c 39631c558f4SSimon Ser :export: 39731c558f4SSimon Ser 39831c558f4SSimon Ser.. kernel-doc:: include/drm/drm_damage_helper.h 39931c558f4SSimon Ser :internal: 40031c558f4SSimon Ser 401*bf9fb17cSJocelyn FalempePlane Panic Feature 402*bf9fb17cSJocelyn Falempe------------------- 403*bf9fb17cSJocelyn Falempe 404*bf9fb17cSJocelyn Falempe.. kernel-doc:: drivers/gpu/drm/drm_panic.c 405*bf9fb17cSJocelyn Falempe :doc: overview 406*bf9fb17cSJocelyn Falempe 407*bf9fb17cSJocelyn FalempePlane Panic Functions Reference 408*bf9fb17cSJocelyn Falempe------------------------------- 409*bf9fb17cSJocelyn Falempe 410*bf9fb17cSJocelyn Falempe.. kernel-doc:: include/drm/drm_panic.h 411*bf9fb17cSJocelyn Falempe :internal: 412*bf9fb17cSJocelyn Falempe 413*bf9fb17cSJocelyn Falempe.. kernel-doc:: drivers/gpu/drm/drm_panic.c 414*bf9fb17cSJocelyn Falempe :export: 415*bf9fb17cSJocelyn Falempe 416311b62d9SDaniel VetterDisplay Modes Function Reference 417311b62d9SDaniel Vetter================================ 4182fa91d15SJani Nikula 419311b62d9SDaniel Vetter.. kernel-doc:: include/drm/drm_modes.h 420311b62d9SDaniel Vetter :internal: 421311b62d9SDaniel Vetter 422311b62d9SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_modes.c 423311b62d9SDaniel Vetter :export: 4242fa91d15SJani Nikula 425ae2a6da8SDaniel VetterConnector Abstraction 426ae2a6da8SDaniel Vetter===================== 427ae2a6da8SDaniel Vetter 428ae2a6da8SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 429ae2a6da8SDaniel Vetter :doc: overview 430ae2a6da8SDaniel Vetter 431ae2a6da8SDaniel VetterConnector Functions Reference 432ae2a6da8SDaniel Vetter----------------------------- 43352217195SDaniel Vetter 43452217195SDaniel Vetter.. kernel-doc:: include/drm/drm_connector.h 43552217195SDaniel Vetter :internal: 43652217195SDaniel Vetter 43752217195SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 43852217195SDaniel Vetter :export: 43952217195SDaniel Vetter 440935774cdSBrian StarkeyWriteback Connectors 441935774cdSBrian Starkey-------------------- 442935774cdSBrian Starkey 443935774cdSBrian Starkey.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 444935774cdSBrian Starkey :doc: overview 445935774cdSBrian Starkey 446d1f5a6d9SDaniel Vetter.. kernel-doc:: include/drm/drm_writeback.h 447d1f5a6d9SDaniel Vetter :internal: 448d1f5a6d9SDaniel Vetter 449935774cdSBrian Starkey.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 450935774cdSBrian Starkey :export: 451935774cdSBrian Starkey 452321a95aeSDaniel VetterEncoder Abstraction 453321a95aeSDaniel Vetter=================== 454321a95aeSDaniel Vetter 455e03e6de0SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 456e03e6de0SDaniel Vetter :doc: overview 457e03e6de0SDaniel Vetter 458e03e6de0SDaniel VetterEncoder Functions Reference 459e03e6de0SDaniel Vetter--------------------------- 460e03e6de0SDaniel Vetter 461321a95aeSDaniel Vetter.. kernel-doc:: include/drm/drm_encoder.h 462321a95aeSDaniel Vetter :internal: 463321a95aeSDaniel Vetter 464321a95aeSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 465321a95aeSDaniel Vetter :export: 466321a95aeSDaniel Vetter 4672fa91d15SJani NikulaKMS Locking 468311b62d9SDaniel Vetter=========== 4692fa91d15SJani Nikula 4702fa91d15SJani Nikula.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 4712fa91d15SJani Nikula :doc: kms locking 4722fa91d15SJani Nikula 4732fa91d15SJani Nikula.. kernel-doc:: include/drm/drm_modeset_lock.h 4742fa91d15SJani Nikula :internal: 4752fa91d15SJani Nikula 4762fa91d15SJani Nikula.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 4772fa91d15SJani Nikula :export: 4782fa91d15SJani Nikula 4792fa91d15SJani NikulaKMS Properties 4802fa91d15SJani Nikula============== 4812fa91d15SJani Nikula 48246f9be4cSSimon SerThis section of the documentation is primarily aimed at user-space developers. 48346f9be4cSSimon SerFor the driver APIs, see the other sections. 48446f9be4cSSimon Ser 485c18c36dcSMaxime RipardRequirements 486c18c36dcSMaxime Ripard------------ 487c18c36dcSMaxime Ripard 488c18c36dcSMaxime RipardKMS drivers might need to add extra properties to support new features. Each 489c18c36dcSMaxime Ripardnew property introduced in a driver needs to meet a few requirements, in 490c18c36dcSMaxime Ripardaddition to the one mentioned above: 491c18c36dcSMaxime Ripard 492c18c36dcSMaxime Ripard* It must be standardized, documenting: 493c18c36dcSMaxime Ripard 494c18c36dcSMaxime Ripard * The full, exact, name string; 495c18c36dcSMaxime Ripard * If the property is an enum, all the valid value name strings; 496c18c36dcSMaxime Ripard * What values are accepted, and what these values mean; 497c18c36dcSMaxime Ripard * What the property does and how it can be used; 498c18c36dcSMaxime Ripard * How the property might interact with other, existing properties. 499c18c36dcSMaxime Ripard 500c18c36dcSMaxime Ripard* It must provide a generic helper in the core code to register that 501c18c36dcSMaxime Ripard property on the object it attaches to. 502c18c36dcSMaxime Ripard 503c18c36dcSMaxime Ripard* Its content must be decoded by the core and provided in the object's 504c18c36dcSMaxime Ripard associated state structure. That includes anything drivers might want 505c18c36dcSMaxime Ripard to precompute, like struct drm_clip_rect for planes. 506c18c36dcSMaxime Ripard 507c18c36dcSMaxime Ripard* Its initial state must match the behavior prior to the property 508c18c36dcSMaxime Ripard introduction. This might be a fixed value matching what the hardware 509c18c36dcSMaxime Ripard does, or it may be inherited from the state the firmware left the 510c18c36dcSMaxime Ripard system in during boot. 511c18c36dcSMaxime Ripard 512c18c36dcSMaxime Ripard* An IGT test must be submitted where reasonable. 513c18c36dcSMaxime Ripard 514f99885b1SSebastian WickFor historical reasons, non-standard, driver-specific properties exist. If a KMS 515f99885b1SSebastian Wickdriver wants to add support for one of those properties, the requirements for 516f99885b1SSebastian Wicknew properties apply where possible. Additionally, the documented behavior must 517f99885b1SSebastian Wickmatch the de facto semantics of the existing property to ensure compatibility. 518f99885b1SSebastian WickDevelopers of the driver that first added the property should help with those 519f99885b1SSebastian Wicktasks and must ACK the documented behavior if possible. 520f99885b1SSebastian Wick 52159e71ee7SDaniel VetterProperty Types and Blob Property Support 52259e71ee7SDaniel Vetter---------------------------------------- 52359e71ee7SDaniel Vetter 524c8458c7eSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_property.c 525c8458c7eSDaniel Vetter :doc: overview 526c8458c7eSDaniel Vetter 52759e71ee7SDaniel Vetter.. kernel-doc:: include/drm/drm_property.h 52859e71ee7SDaniel Vetter :internal: 52959e71ee7SDaniel Vetter 53059e71ee7SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_property.c 53159e71ee7SDaniel Vetter :export: 53259e71ee7SDaniel Vetter 533107fe904SRajat Jain.. _standard_connector_properties: 534107fe904SRajat Jain 5354ada6f22SDaniel VetterStandard Connector Properties 5364ada6f22SDaniel Vetter----------------------------- 5374ada6f22SDaniel Vetter 5384ada6f22SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 5394ada6f22SDaniel Vetter :doc: standard connector properties 5404ada6f22SDaniel Vetter 54150525c33SStanislav LisovskiyHDMI Specific Connector Properties 542ba609631SDaniel Vetter---------------------------------- 54350525c33SStanislav Lisovskiy 54450525c33SStanislav Lisovskiy.. kernel-doc:: drivers/gpu/drm/drm_connector.c 54550525c33SStanislav Lisovskiy :doc: HDMI connector properties 54650525c33SStanislav Lisovskiy 5477d63cd85SMaxime RipardAnalog TV Specific Connector Properties 548b99070c0SMaxime Ripard--------------------------------------- 5497d63cd85SMaxime Ripard 5507d63cd85SMaxime Ripard.. kernel-doc:: drivers/gpu/drm/drm_connector.c 5517d63cd85SMaxime Ripard :doc: Analog TV Connector Properties 5527d63cd85SMaxime Ripard 553e954f77fSSimon SerStandard CRTC Properties 554e954f77fSSimon Ser------------------------ 555e954f77fSSimon Ser 556e954f77fSSimon Ser.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 557e954f77fSSimon Ser :doc: standard CRTC properties 558e954f77fSSimon Ser 55977a71abbSSimon SerStandard Plane Properties 56077a71abbSSimon Ser------------------------- 56177a71abbSSimon Ser 56277a71abbSSimon Ser.. kernel-doc:: drivers/gpu/drm/drm_plane.c 56377a71abbSSimon Ser :doc: standard plane properties 56477a71abbSSimon Ser 56533fa4f1dSMelissa Wen.. _plane_composition_properties: 56633fa4f1dSMelissa Wen 5671e4d84c6SDaniel VetterPlane Composition Properties 5681e4d84c6SDaniel Vetter---------------------------- 5691e4d84c6SDaniel Vetter 5701e4d84c6SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_blend.c 5711e4d84c6SDaniel Vetter :doc: overview 57252a9fcdaSDaniel Vetter 57335ed38d5SJavier Martinez Canillas.. _damage_tracking_properties: 57435ed38d5SJavier Martinez Canillas 575e07f001cSSimon SerDamage Tracking Properties 576e07f001cSSimon Ser-------------------------- 577d3b21767SLukasz Spintzyk 578ba6cd766SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_plane.c 579ba6cd766SDaniel Vetter :doc: damage tracking 580d3b21767SLukasz Spintzyk 581a6acccf8SDaniel VetterColor Management Properties 582a6acccf8SDaniel Vetter--------------------------- 583a6acccf8SDaniel Vetter 584a6acccf8SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 585a6acccf8SDaniel Vetter :doc: overview 586a6acccf8SDaniel Vetter 5879498c19bSDaniel VetterTile Group Property 5889498c19bSDaniel Vetter------------------- 5899498c19bSDaniel Vetter 5909498c19bSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 5919498c19bSDaniel Vetter :doc: Tile group 5929498c19bSDaniel Vetter 5939a83a71aSGustavo PadovanExplicit Fencing Properties 5949a83a71aSGustavo Padovan--------------------------- 5959a83a71aSGustavo Padovan 59672fdb40cSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 5979a83a71aSGustavo Padovan :doc: explicit fencing properties 5989a83a71aSGustavo Padovan 599ab7a664fSNicholas Kazlauskas 600ab7a664fSNicholas KazlauskasVariable Refresh Properties 601ab7a664fSNicholas Kazlauskas--------------------------- 602ab7a664fSNicholas Kazlauskas 603ab7a664fSNicholas Kazlauskas.. kernel-doc:: drivers/gpu/drm/drm_connector.c 604ab7a664fSNicholas Kazlauskas :doc: Variable refresh properties 605ab7a664fSNicholas Kazlauskas 6064653f9d0SMichael BanackCursor Hotspot Properties 6074653f9d0SMichael Banack--------------------------- 6084653f9d0SMichael Banack 6094653f9d0SMichael Banack.. kernel-doc:: drivers/gpu/drm/drm_plane.c 6104653f9d0SMichael Banack :doc: hotspot properties 6114653f9d0SMichael Banack 6122fa91d15SJani NikulaExisting KMS Properties 6132fa91d15SJani Nikula----------------------- 6142fa91d15SJani Nikula 6153f0df756SDaniel VetterThe following table gives description of drm properties exposed by various 6163f0df756SDaniel Vettermodules/drivers. Because this table is very unwieldy, do not add any new 6173f0df756SDaniel Vetterproperties here. Instead document them in a section above. 6182fa91d15SJani Nikula 6192fa91d15SJani Nikula.. csv-table:: 6202fa91d15SJani Nikula :header-rows: 1 6212fa91d15SJani Nikula :file: kms-properties.csv 6222fa91d15SJani Nikula 6232fa91d15SJani NikulaVertical Blanking 6242fa91d15SJani Nikula================= 6252fa91d15SJani Nikula 62657d30230SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 62757d30230SDaniel Vetter :doc: vblank handling 6282fa91d15SJani Nikula 6292fa91d15SJani NikulaVertical Blanking and Interrupt Handling Functions Reference 6302fa91d15SJani Nikula------------------------------------------------------------ 6312fa91d15SJani Nikula 6323ed4351aSDaniel Vetter.. kernel-doc:: include/drm/drm_vblank.h 63334a67dd7SDaniel Vetter :internal: 6341ea35768SDaniel Vetter 6353ed4351aSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 6361ea35768SDaniel Vetter :export: 6375e6c2b4fSLyude Paul 6385e6c2b4fSLyude PaulVertical Blank Work 6395e6c2b4fSLyude Paul=================== 6405e6c2b4fSLyude Paul 6415e6c2b4fSLyude Paul.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c 6425e6c2b4fSLyude Paul :doc: vblank works 6435e6c2b4fSLyude Paul 6445e6c2b4fSLyude PaulVertical Blank Work Functions Reference 6455e6c2b4fSLyude Paul--------------------------------------- 6465e6c2b4fSLyude Paul 6475e6c2b4fSLyude Paul.. kernel-doc:: include/drm/drm_vblank_work.h 6485e6c2b4fSLyude Paul :internal: 6495e6c2b4fSLyude Paul 6505e6c2b4fSLyude Paul.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c 6515e6c2b4fSLyude Paul :export: 652