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 363*b8644c4aSSimon Ser.. _kms_dumb_buffer_objects: 364*b8644c4aSSimon 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 401311b62d9SDaniel VetterDisplay Modes Function Reference 402311b62d9SDaniel Vetter================================ 4032fa91d15SJani Nikula 404311b62d9SDaniel Vetter.. kernel-doc:: include/drm/drm_modes.h 405311b62d9SDaniel Vetter :internal: 406311b62d9SDaniel Vetter 407311b62d9SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_modes.c 408311b62d9SDaniel Vetter :export: 4092fa91d15SJani Nikula 410ae2a6da8SDaniel VetterConnector Abstraction 411ae2a6da8SDaniel Vetter===================== 412ae2a6da8SDaniel Vetter 413ae2a6da8SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 414ae2a6da8SDaniel Vetter :doc: overview 415ae2a6da8SDaniel Vetter 416ae2a6da8SDaniel VetterConnector Functions Reference 417ae2a6da8SDaniel Vetter----------------------------- 41852217195SDaniel Vetter 41952217195SDaniel Vetter.. kernel-doc:: include/drm/drm_connector.h 42052217195SDaniel Vetter :internal: 42152217195SDaniel Vetter 42252217195SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 42352217195SDaniel Vetter :export: 42452217195SDaniel Vetter 425935774cdSBrian StarkeyWriteback Connectors 426935774cdSBrian Starkey-------------------- 427935774cdSBrian Starkey 428935774cdSBrian Starkey.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 429935774cdSBrian Starkey :doc: overview 430935774cdSBrian Starkey 431d1f5a6d9SDaniel Vetter.. kernel-doc:: include/drm/drm_writeback.h 432d1f5a6d9SDaniel Vetter :internal: 433d1f5a6d9SDaniel Vetter 434935774cdSBrian Starkey.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 435935774cdSBrian Starkey :export: 436935774cdSBrian Starkey 437321a95aeSDaniel VetterEncoder Abstraction 438321a95aeSDaniel Vetter=================== 439321a95aeSDaniel Vetter 440e03e6de0SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 441e03e6de0SDaniel Vetter :doc: overview 442e03e6de0SDaniel Vetter 443e03e6de0SDaniel VetterEncoder Functions Reference 444e03e6de0SDaniel Vetter--------------------------- 445e03e6de0SDaniel Vetter 446321a95aeSDaniel Vetter.. kernel-doc:: include/drm/drm_encoder.h 447321a95aeSDaniel Vetter :internal: 448321a95aeSDaniel Vetter 449321a95aeSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 450321a95aeSDaniel Vetter :export: 451321a95aeSDaniel Vetter 4522fa91d15SJani NikulaKMS Locking 453311b62d9SDaniel Vetter=========== 4542fa91d15SJani Nikula 4552fa91d15SJani Nikula.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 4562fa91d15SJani Nikula :doc: kms locking 4572fa91d15SJani Nikula 4582fa91d15SJani Nikula.. kernel-doc:: include/drm/drm_modeset_lock.h 4592fa91d15SJani Nikula :internal: 4602fa91d15SJani Nikula 4612fa91d15SJani Nikula.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 4622fa91d15SJani Nikula :export: 4632fa91d15SJani Nikula 4642fa91d15SJani NikulaKMS Properties 4652fa91d15SJani Nikula============== 4662fa91d15SJani Nikula 46746f9be4cSSimon SerThis section of the documentation is primarily aimed at user-space developers. 46846f9be4cSSimon SerFor the driver APIs, see the other sections. 46946f9be4cSSimon Ser 470c18c36dcSMaxime RipardRequirements 471c18c36dcSMaxime Ripard------------ 472c18c36dcSMaxime Ripard 473c18c36dcSMaxime RipardKMS drivers might need to add extra properties to support new features. Each 474c18c36dcSMaxime Ripardnew property introduced in a driver needs to meet a few requirements, in 475c18c36dcSMaxime Ripardaddition to the one mentioned above: 476c18c36dcSMaxime Ripard 477c18c36dcSMaxime Ripard* It must be standardized, documenting: 478c18c36dcSMaxime Ripard 479c18c36dcSMaxime Ripard * The full, exact, name string; 480c18c36dcSMaxime Ripard * If the property is an enum, all the valid value name strings; 481c18c36dcSMaxime Ripard * What values are accepted, and what these values mean; 482c18c36dcSMaxime Ripard * What the property does and how it can be used; 483c18c36dcSMaxime Ripard * How the property might interact with other, existing properties. 484c18c36dcSMaxime Ripard 485c18c36dcSMaxime Ripard* It must provide a generic helper in the core code to register that 486c18c36dcSMaxime Ripard property on the object it attaches to. 487c18c36dcSMaxime Ripard 488c18c36dcSMaxime Ripard* Its content must be decoded by the core and provided in the object's 489c18c36dcSMaxime Ripard associated state structure. That includes anything drivers might want 490c18c36dcSMaxime Ripard to precompute, like struct drm_clip_rect for planes. 491c18c36dcSMaxime Ripard 492c18c36dcSMaxime Ripard* Its initial state must match the behavior prior to the property 493c18c36dcSMaxime Ripard introduction. This might be a fixed value matching what the hardware 494c18c36dcSMaxime Ripard does, or it may be inherited from the state the firmware left the 495c18c36dcSMaxime Ripard system in during boot. 496c18c36dcSMaxime Ripard 497c18c36dcSMaxime Ripard* An IGT test must be submitted where reasonable. 498c18c36dcSMaxime Ripard 49959e71ee7SDaniel VetterProperty Types and Blob Property Support 50059e71ee7SDaniel Vetter---------------------------------------- 50159e71ee7SDaniel Vetter 502c8458c7eSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_property.c 503c8458c7eSDaniel Vetter :doc: overview 504c8458c7eSDaniel Vetter 50559e71ee7SDaniel Vetter.. kernel-doc:: include/drm/drm_property.h 50659e71ee7SDaniel Vetter :internal: 50759e71ee7SDaniel Vetter 50859e71ee7SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_property.c 50959e71ee7SDaniel Vetter :export: 51059e71ee7SDaniel Vetter 511107fe904SRajat Jain.. _standard_connector_properties: 512107fe904SRajat Jain 5134ada6f22SDaniel VetterStandard Connector Properties 5144ada6f22SDaniel Vetter----------------------------- 5154ada6f22SDaniel Vetter 5164ada6f22SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 5174ada6f22SDaniel Vetter :doc: standard connector properties 5184ada6f22SDaniel Vetter 51950525c33SStanislav LisovskiyHDMI Specific Connector Properties 520ba609631SDaniel Vetter---------------------------------- 52150525c33SStanislav Lisovskiy 52250525c33SStanislav Lisovskiy.. kernel-doc:: drivers/gpu/drm/drm_connector.c 52350525c33SStanislav Lisovskiy :doc: HDMI connector properties 52450525c33SStanislav Lisovskiy 5257d63cd85SMaxime RipardAnalog TV Specific Connector Properties 526b99070c0SMaxime Ripard--------------------------------------- 5277d63cd85SMaxime Ripard 5287d63cd85SMaxime Ripard.. kernel-doc:: drivers/gpu/drm/drm_connector.c 5297d63cd85SMaxime Ripard :doc: Analog TV Connector Properties 5307d63cd85SMaxime Ripard 531e954f77fSSimon SerStandard CRTC Properties 532e954f77fSSimon Ser------------------------ 533e954f77fSSimon Ser 534e954f77fSSimon Ser.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 535e954f77fSSimon Ser :doc: standard CRTC properties 536e954f77fSSimon Ser 53777a71abbSSimon SerStandard Plane Properties 53877a71abbSSimon Ser------------------------- 53977a71abbSSimon Ser 54077a71abbSSimon Ser.. kernel-doc:: drivers/gpu/drm/drm_plane.c 54177a71abbSSimon Ser :doc: standard plane properties 54277a71abbSSimon Ser 54333fa4f1dSMelissa Wen.. _plane_composition_properties: 54433fa4f1dSMelissa Wen 5451e4d84c6SDaniel VetterPlane Composition Properties 5461e4d84c6SDaniel Vetter---------------------------- 5471e4d84c6SDaniel Vetter 5481e4d84c6SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_blend.c 5491e4d84c6SDaniel Vetter :doc: overview 55052a9fcdaSDaniel Vetter 551e07f001cSSimon SerDamage Tracking Properties 552e07f001cSSimon Ser-------------------------- 553d3b21767SLukasz Spintzyk 554ba6cd766SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_plane.c 555ba6cd766SDaniel Vetter :doc: damage tracking 556d3b21767SLukasz Spintzyk 557a6acccf8SDaniel VetterColor Management Properties 558a6acccf8SDaniel Vetter--------------------------- 559a6acccf8SDaniel Vetter 560a6acccf8SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 561a6acccf8SDaniel Vetter :doc: overview 562a6acccf8SDaniel Vetter 5639498c19bSDaniel VetterTile Group Property 5649498c19bSDaniel Vetter------------------- 5659498c19bSDaniel Vetter 5669498c19bSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 5679498c19bSDaniel Vetter :doc: Tile group 5689498c19bSDaniel Vetter 5699a83a71aSGustavo PadovanExplicit Fencing Properties 5709a83a71aSGustavo Padovan--------------------------- 5719a83a71aSGustavo Padovan 57272fdb40cSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 5739a83a71aSGustavo Padovan :doc: explicit fencing properties 5749a83a71aSGustavo Padovan 575ab7a664fSNicholas Kazlauskas 576ab7a664fSNicholas KazlauskasVariable Refresh Properties 577ab7a664fSNicholas Kazlauskas--------------------------- 578ab7a664fSNicholas Kazlauskas 579ab7a664fSNicholas Kazlauskas.. kernel-doc:: drivers/gpu/drm/drm_connector.c 580ab7a664fSNicholas Kazlauskas :doc: Variable refresh properties 581ab7a664fSNicholas Kazlauskas 5822fa91d15SJani NikulaExisting KMS Properties 5832fa91d15SJani Nikula----------------------- 5842fa91d15SJani Nikula 5853f0df756SDaniel VetterThe following table gives description of drm properties exposed by various 5863f0df756SDaniel Vettermodules/drivers. Because this table is very unwieldy, do not add any new 5873f0df756SDaniel Vetterproperties here. Instead document them in a section above. 5882fa91d15SJani Nikula 5892fa91d15SJani Nikula.. csv-table:: 5902fa91d15SJani Nikula :header-rows: 1 5912fa91d15SJani Nikula :file: kms-properties.csv 5922fa91d15SJani Nikula 5932fa91d15SJani NikulaVertical Blanking 5942fa91d15SJani Nikula================= 5952fa91d15SJani Nikula 59657d30230SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 59757d30230SDaniel Vetter :doc: vblank handling 5982fa91d15SJani Nikula 5992fa91d15SJani NikulaVertical Blanking and Interrupt Handling Functions Reference 6002fa91d15SJani Nikula------------------------------------------------------------ 6012fa91d15SJani Nikula 6023ed4351aSDaniel Vetter.. kernel-doc:: include/drm/drm_vblank.h 60334a67dd7SDaniel Vetter :internal: 6041ea35768SDaniel Vetter 6053ed4351aSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 6061ea35768SDaniel Vetter :export: 6075e6c2b4fSLyude Paul 6085e6c2b4fSLyude PaulVertical Blank Work 6095e6c2b4fSLyude Paul=================== 6105e6c2b4fSLyude Paul 6115e6c2b4fSLyude Paul.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c 6125e6c2b4fSLyude Paul :doc: vblank works 6135e6c2b4fSLyude Paul 6145e6c2b4fSLyude PaulVertical Blank Work Functions Reference 6155e6c2b4fSLyude Paul--------------------------------------- 6165e6c2b4fSLyude Paul 6175e6c2b4fSLyude Paul.. kernel-doc:: include/drm/drm_vblank_work.h 6185e6c2b4fSLyude Paul :internal: 6195e6c2b4fSLyude Paul 6205e6c2b4fSLyude Paul.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c 6215e6c2b4fSLyude Paul :export: 622