12fa91d15SJani Nikula========================= 22fa91d15SJani NikulaKernel Mode Setting (KMS) 32fa91d15SJani Nikula========================= 42fa91d15SJani Nikula 52fa91d15SJani NikulaDrivers must initialize the mode setting core by calling 62fa91d15SJani Nikula:c:func:`drm_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>`, 592564d0b0SDaniel Vettersee `Frame Buffer Abstraction`_) feed into planes. One or more (or even no) 602564d0b0SDaniel Vetterplanes feed their pixel data into a CRTC (represented by :c:type:`struct 612564d0b0SDaniel Vetterdrm_crtc <drm_crtc>`, see `CRTC Abstraction`_) for blending. The precise 622564d0b0SDaniel Vetterblending step is explained in more detail in `Plane Composition Properties`_ and 632564d0b0SDaniel Vetterrelated chapters. 642564d0b0SDaniel Vetter 652564d0b0SDaniel VetterFor the output routing the first step is encoders (represented by 662564d0b0SDaniel Vetter:c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those 672564d0b0SDaniel Vetterare really just internal artifacts of the helper libraries used to implement KMS 682564d0b0SDaniel Vetterdrivers. Besides that they make it unecessarily more complicated for userspace 692564d0b0SDaniel Vetterto figure out which connections between a CRTC and a connector are possible, and 702564d0b0SDaniel Vetterwhat kind of cloning is supported, they serve no purpose in the userspace API. 712564d0b0SDaniel VetterUnfortunately encoders have been exposed to userspace, hence can't remove them 722564d0b0SDaniel Vetterat this point. Futhermore the exposed restrictions are often wrongly set by 732564d0b0SDaniel Vetterdrivers, and in many cases not powerful enough to express the real restrictions. 742564d0b0SDaniel VetterA CRTC can be connected to multiple encoders, and for an active CRTC there must 752564d0b0SDaniel Vetterbe at least one encoder. 762564d0b0SDaniel Vetter 772564d0b0SDaniel VetterThe final, and real, endpoint in the display chain is the connector (represented 782564d0b0SDaniel Vetterby :c:type:`struct drm_connector <drm_connector>`, see `Connector 792564d0b0SDaniel VetterAbstraction`_). Connectors can have different possible encoders, but the kernel 802564d0b0SDaniel Vetterdriver selects which encoder to use for each connector. The use case is DVI, 812564d0b0SDaniel Vetterwhich could switch between an analog and a digital encoder. Encoders can also 822564d0b0SDaniel Vetterdrive multiple different connectors. There is exactly one active connector for 832564d0b0SDaniel Vetterevery active encoder. 842564d0b0SDaniel Vetter 852564d0b0SDaniel VetterInternally the output pipeline is a bit more complex and matches today's 862564d0b0SDaniel Vetterhardware more closely: 872564d0b0SDaniel Vetter 882564d0b0SDaniel Vetter.. kernel-render:: DOT 892564d0b0SDaniel Vetter :alt: KMS Output Pipeline 902564d0b0SDaniel Vetter :caption: KMS Output Pipeline 912564d0b0SDaniel Vetter 922564d0b0SDaniel Vetter digraph "Output Pipeline" { 932564d0b0SDaniel Vetter node [shape=box] 942564d0b0SDaniel Vetter 952564d0b0SDaniel Vetter subgraph { 962564d0b0SDaniel Vetter "drm_crtc" [bgcolor=grey style=filled] 972564d0b0SDaniel Vetter } 982564d0b0SDaniel Vetter 992564d0b0SDaniel Vetter subgraph cluster_internal { 1002564d0b0SDaniel Vetter style=dashed 1012564d0b0SDaniel Vetter label="Internal Pipeline" 1022564d0b0SDaniel Vetter { 1032564d0b0SDaniel Vetter node [bgcolor=grey style=filled] 1042564d0b0SDaniel Vetter "drm_encoder A"; 1052564d0b0SDaniel Vetter "drm_encoder B"; 1062564d0b0SDaniel Vetter "drm_encoder C"; 1072564d0b0SDaniel Vetter } 1082564d0b0SDaniel Vetter 1092564d0b0SDaniel Vetter { 1102564d0b0SDaniel Vetter node [bgcolor=grey style=filled] 1112564d0b0SDaniel Vetter "drm_encoder B" -> "drm_bridge B" 1122564d0b0SDaniel Vetter "drm_encoder C" -> "drm_bridge C1" 1132564d0b0SDaniel Vetter "drm_bridge C1" -> "drm_bridge C2"; 1142564d0b0SDaniel Vetter } 1152564d0b0SDaniel Vetter } 1162564d0b0SDaniel Vetter 1172564d0b0SDaniel Vetter "drm_crtc" -> "drm_encoder A" 1182564d0b0SDaniel Vetter "drm_crtc" -> "drm_encoder B" 1192564d0b0SDaniel Vetter "drm_crtc" -> "drm_encoder C" 1202564d0b0SDaniel Vetter 1212564d0b0SDaniel Vetter 1222564d0b0SDaniel Vetter subgraph cluster_output { 1232564d0b0SDaniel Vetter style=dashed 1242564d0b0SDaniel Vetter label="Outputs" 1252564d0b0SDaniel Vetter 1262564d0b0SDaniel Vetter "drm_encoder A" -> "drm_connector A"; 1272564d0b0SDaniel Vetter "drm_bridge B" -> "drm_connector B"; 1282564d0b0SDaniel Vetter "drm_bridge C2" -> "drm_connector C"; 1292564d0b0SDaniel Vetter 1302564d0b0SDaniel Vetter "drm_panel" 1312564d0b0SDaniel Vetter } 1322564d0b0SDaniel Vetter } 1332564d0b0SDaniel Vetter 1342564d0b0SDaniel VetterInternally two additional helper objects come into play. First, to be able to 1352564d0b0SDaniel Vettershare code for encoders (sometimes on the same SoC, sometimes off-chip) one or 1362564d0b0SDaniel Vettermore :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge 1372564d0b0SDaniel Vetter<drm_bridge>`) can be linked to an encoder. This link is static and cannot be 1382564d0b0SDaniel Vetterchanged, which means the cross-bar (if there is any) needs to be mapped between 1392564d0b0SDaniel Vetterthe CRTC and any encoders. Often for drivers with bridges there's no code left 1402564d0b0SDaniel Vetterat the encoder level. Atomic drivers can leave out all the encoder callbacks to 1412564d0b0SDaniel Vetteressentially only leave a dummy routing object behind, which is needed for 1422564d0b0SDaniel Vetterbackwards compatibility since encoders are exposed to userspace. 1432564d0b0SDaniel Vetter 1442564d0b0SDaniel VetterThe second object is for panels, represented by :c:type:`struct drm_panel 1452564d0b0SDaniel Vetter<drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding 1462564d0b0SDaniel Vetterpoint, but are generally linked to the driver private structure that embeds 1472564d0b0SDaniel Vetter:c:type:`struct drm_connector <drm_connector>`. 1482564d0b0SDaniel Vetter 1492564d0b0SDaniel VetterNote that currently the bridge chaining and interactions with connectors and 1502564d0b0SDaniel Vetterpanels are still in-flux and not really fully sorted out yet. 15128575f16SDaniel Vetter 15228575f16SDaniel VetterKMS Core Structures and Functions 15328575f16SDaniel Vetter================================= 15428575f16SDaniel Vetter 15528575f16SDaniel Vetter.. kernel-doc:: include/drm/drm_mode_config.h 15628575f16SDaniel Vetter :internal: 15728575f16SDaniel Vetter 1581ea35768SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_mode_config.c 1591ea35768SDaniel Vetter :export: 1601ea35768SDaniel Vetter 161949619f3SDaniel VetterModeset Base Object Abstraction 162949619f3SDaniel Vetter=============================== 163949619f3SDaniel Vetter 164*b2b82c26SDaniel Vetter.. kernel-render:: DOT 165*b2b82c26SDaniel Vetter :alt: Mode Objects and Properties 166*b2b82c26SDaniel Vetter :caption: Mode Objects and Properties 167*b2b82c26SDaniel Vetter 168*b2b82c26SDaniel Vetter digraph { 169*b2b82c26SDaniel Vetter node [shape=box] 170*b2b82c26SDaniel Vetter 171*b2b82c26SDaniel Vetter "drm_property A" -> "drm_mode_object A" 172*b2b82c26SDaniel Vetter "drm_property A" -> "drm_mode_object B" 173*b2b82c26SDaniel Vetter "drm_property B" -> "drm_mode_object A" 174*b2b82c26SDaniel Vetter } 175*b2b82c26SDaniel Vetter 176*b2b82c26SDaniel VetterThe base structure for all KMS objects is :c:type:`struct drm_mode_object 177*b2b82c26SDaniel Vetter<drm_mode_object>`. One of the base services it provides is tracking properties, 178*b2b82c26SDaniel Vetterwhich are especially important for the atomic IOCTL (see `Atomic Mode 179*b2b82c26SDaniel VetterSetting`_). The somewhat surprising part here is that properties are not 180*b2b82c26SDaniel Vetterdirectly instantiated on each object, but free-standing mode objects themselves, 181*b2b82c26SDaniel Vetterrepresented by :c:type:`struct drm_property <drm_property>`, which only specify 182*b2b82c26SDaniel Vetterthe type and value range of a property. Any given property can be attached 183*b2b82c26SDaniel Vettermultiple times to different objects using :c:func:`drm_object_attach_property() 184*b2b82c26SDaniel Vetter<drm_object_attach_property>`. 185*b2b82c26SDaniel Vetter 186949619f3SDaniel Vetter.. kernel-doc:: include/drm/drm_mode_object.h 187949619f3SDaniel Vetter :internal: 188949619f3SDaniel Vetter 189949619f3SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c 190949619f3SDaniel Vetter :export: 191949619f3SDaniel Vetter 1922fa91d15SJani NikulaAtomic Mode Setting Function Reference 193311b62d9SDaniel Vetter====================================== 1942fa91d15SJani Nikula 1955d070be6SDaniel Vetter.. kernel-doc:: include/drm/drm_atomic.h 1962fa91d15SJani Nikula :internal: 1972fa91d15SJani Nikula 1981ea35768SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 1991ea35768SDaniel Vetter :export: 2001ea35768SDaniel Vetter 20128575f16SDaniel VetterCRTC Abstraction 20228575f16SDaniel Vetter================ 20328575f16SDaniel Vetter 20428575f16SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 205d5d487ebSDaniel Vetter :doc: overview 206d5d487ebSDaniel Vetter 207d5d487ebSDaniel VetterCRTC Functions Reference 208d5d487ebSDaniel Vetter-------------------------------- 20928575f16SDaniel Vetter 21028575f16SDaniel Vetter.. kernel-doc:: include/drm/drm_crtc.h 21128575f16SDaniel Vetter :internal: 21228575f16SDaniel Vetter 213d5d487ebSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 214d5d487ebSDaniel Vetter :export: 215d5d487ebSDaniel Vetter 2162fa91d15SJani NikulaFrame Buffer Abstraction 217311b62d9SDaniel Vetter======================== 2182fa91d15SJani Nikula 219750fb8c4SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 220750fb8c4SDaniel Vetter :doc: overview 2212fa91d15SJani Nikula 2227520a277SDaniel VetterFrame Buffer Functions Reference 2237520a277SDaniel Vetter-------------------------------- 2247520a277SDaniel Vetter 2257520a277SDaniel Vetter.. kernel-doc:: include/drm/drm_framebuffer.h 2267520a277SDaniel Vetter :internal: 2277520a277SDaniel Vetter 2281ea35768SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 2291ea35768SDaniel Vetter :export: 2301ea35768SDaniel Vetter 2312fa91d15SJani NikulaDRM Format Handling 232311b62d9SDaniel Vetter=================== 2332fa91d15SJani Nikula 23484770cc2SLaurent Pinchart.. kernel-doc:: include/drm/drm_fourcc.h 23584770cc2SLaurent Pinchart :internal: 23684770cc2SLaurent Pinchart 2372fa91d15SJani Nikula.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c 2382fa91d15SJani Nikula :export: 2392fa91d15SJani Nikula 2402fa91d15SJani NikulaDumb Buffer Objects 241311b62d9SDaniel Vetter=================== 2422fa91d15SJani Nikula 2434f93624eSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c 2444f93624eSDaniel Vetter :doc: overview 2452fa91d15SJani Nikula 24643968d7bSDaniel VetterPlane Abstraction 24743968d7bSDaniel Vetter================= 24843968d7bSDaniel Vetter 249532b3671SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_plane.c 250532b3671SDaniel Vetter :doc: overview 251532b3671SDaniel Vetter 25243968d7bSDaniel VetterPlane Functions Reference 25343968d7bSDaniel Vetter------------------------- 25443968d7bSDaniel Vetter 25543968d7bSDaniel Vetter.. kernel-doc:: include/drm/drm_plane.h 25643968d7bSDaniel Vetter :internal: 25743968d7bSDaniel Vetter 25843968d7bSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_plane.c 25943968d7bSDaniel Vetter :export: 26043968d7bSDaniel Vetter 261311b62d9SDaniel VetterDisplay Modes Function Reference 262311b62d9SDaniel Vetter================================ 2632fa91d15SJani Nikula 264311b62d9SDaniel Vetter.. kernel-doc:: include/drm/drm_modes.h 265311b62d9SDaniel Vetter :internal: 266311b62d9SDaniel Vetter 267311b62d9SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_modes.c 268311b62d9SDaniel Vetter :export: 2692fa91d15SJani Nikula 270ae2a6da8SDaniel VetterConnector Abstraction 271ae2a6da8SDaniel Vetter===================== 272ae2a6da8SDaniel Vetter 273ae2a6da8SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 274ae2a6da8SDaniel Vetter :doc: overview 275ae2a6da8SDaniel Vetter 276ae2a6da8SDaniel VetterConnector Functions Reference 277ae2a6da8SDaniel Vetter----------------------------- 27852217195SDaniel Vetter 27952217195SDaniel Vetter.. kernel-doc:: include/drm/drm_connector.h 28052217195SDaniel Vetter :internal: 28152217195SDaniel Vetter 28252217195SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 28352217195SDaniel Vetter :export: 28452217195SDaniel Vetter 285321a95aeSDaniel VetterEncoder Abstraction 286321a95aeSDaniel Vetter=================== 287321a95aeSDaniel Vetter 288e03e6de0SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 289e03e6de0SDaniel Vetter :doc: overview 290e03e6de0SDaniel Vetter 291e03e6de0SDaniel VetterEncoder Functions Reference 292e03e6de0SDaniel Vetter--------------------------- 293e03e6de0SDaniel Vetter 294321a95aeSDaniel Vetter.. kernel-doc:: include/drm/drm_encoder.h 295321a95aeSDaniel Vetter :internal: 296321a95aeSDaniel Vetter 297321a95aeSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 298321a95aeSDaniel Vetter :export: 299321a95aeSDaniel Vetter 3002fa91d15SJani NikulaKMS Initialization and Cleanup 3012fa91d15SJani Nikula============================== 3022fa91d15SJani Nikula 3032fa91d15SJani NikulaA KMS device is abstracted and exposed as a set of planes, CRTCs, 3042fa91d15SJani Nikulaencoders and connectors. KMS drivers must thus create and initialize all 3052fa91d15SJani Nikulathose objects at load time after initializing mode setting. 3062fa91d15SJani Nikula 3072fa91d15SJani NikulaCRTCs (:c:type:`struct drm_crtc <drm_crtc>`) 3082fa91d15SJani Nikula-------------------------------------------- 3092fa91d15SJani Nikula 3102fa91d15SJani NikulaA CRTC is an abstraction representing a part of the chip that contains a 3112fa91d15SJani Nikulapointer to a scanout buffer. Therefore, the number of CRTCs available 3122fa91d15SJani Nikuladetermines how many independent scanout buffers can be active at any 3132fa91d15SJani Nikulagiven time. The CRTC structure contains several fields to support this: 3142fa91d15SJani Nikulaa pointer to some video memory (abstracted as a frame buffer object), a 3152fa91d15SJani Nikuladisplay mode, and an (x, y) offset into the video memory to support 3162fa91d15SJani Nikulapanning or configurations where one piece of video memory spans multiple 3172fa91d15SJani NikulaCRTCs. 3182fa91d15SJani Nikula 3192fa91d15SJani NikulaCRTC Initialization 3202fa91d15SJani Nikula~~~~~~~~~~~~~~~~~~~ 3212fa91d15SJani Nikula 3222fa91d15SJani NikulaA KMS device must create and register at least one struct 3232fa91d15SJani Nikula:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is 3242fa91d15SJani Nikulaallocated and zeroed by the driver, possibly as part of a larger 3252fa91d15SJani Nikulastructure, and registered with a call to :c:func:`drm_crtc_init()` 3262fa91d15SJani Nikulawith a pointer to CRTC functions. 3272fa91d15SJani Nikula 3282fa91d15SJani Nikula 3292fa91d15SJani NikulaCleanup 3302fa91d15SJani Nikula------- 3312fa91d15SJani Nikula 3322fa91d15SJani NikulaThe DRM core manages its objects' lifetime. When an object is not needed 3332fa91d15SJani Nikulaanymore the core calls its destroy function, which must clean up and 3342fa91d15SJani Nikulafree every resource allocated for the object. Every 3352fa91d15SJani Nikula:c:func:`drm_\*_init()` call must be matched with a corresponding 3362fa91d15SJani Nikula:c:func:`drm_\*_cleanup()` call to cleanup CRTCs 3372fa91d15SJani Nikula(:c:func:`drm_crtc_cleanup()`), planes 3382fa91d15SJani Nikula(:c:func:`drm_plane_cleanup()`), encoders 3392fa91d15SJani Nikula(:c:func:`drm_encoder_cleanup()`) and connectors 3402fa91d15SJani Nikula(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that 3412fa91d15SJani Nikulahave been added to sysfs must be removed by a call to 3422fa91d15SJani Nikula:c:func:`drm_connector_unregister()` before calling 3432fa91d15SJani Nikula:c:func:`drm_connector_cleanup()`. 3442fa91d15SJani Nikula 3452fa91d15SJani NikulaConnectors state change detection must be cleanup up with a call to 3462fa91d15SJani Nikula:c:func:`drm_kms_helper_poll_fini()`. 3472fa91d15SJani Nikula 3482fa91d15SJani NikulaOutput discovery and initialization example 3492fa91d15SJani Nikula------------------------------------------- 3502fa91d15SJani Nikula 35129849a69SJani Nikula.. code-block:: c 3522fa91d15SJani Nikula 3532fa91d15SJani Nikula void intel_crt_init(struct drm_device *dev) 3542fa91d15SJani Nikula { 3552fa91d15SJani Nikula struct drm_connector *connector; 3562fa91d15SJani Nikula struct intel_output *intel_output; 3572fa91d15SJani Nikula 3582fa91d15SJani Nikula intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); 3592fa91d15SJani Nikula if (!intel_output) 3602fa91d15SJani Nikula return; 3612fa91d15SJani Nikula 3622fa91d15SJani Nikula connector = &intel_output->base; 3632fa91d15SJani Nikula drm_connector_init(dev, &intel_output->base, 3642fa91d15SJani Nikula &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); 3652fa91d15SJani Nikula 3662fa91d15SJani Nikula drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, 3672fa91d15SJani Nikula DRM_MODE_ENCODER_DAC); 3682fa91d15SJani Nikula 3692fa91d15SJani Nikula drm_mode_connector_attach_encoder(&intel_output->base, 3702fa91d15SJani Nikula &intel_output->enc); 3712fa91d15SJani Nikula 3722fa91d15SJani Nikula /* Set up the DDC bus. */ 3732fa91d15SJani Nikula intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); 3742fa91d15SJani Nikula if (!intel_output->ddc_bus) { 3752fa91d15SJani Nikula dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " 3762fa91d15SJani Nikula "failed.\n"); 3772fa91d15SJani Nikula return; 3782fa91d15SJani Nikula } 3792fa91d15SJani Nikula 3802fa91d15SJani Nikula intel_output->type = INTEL_OUTPUT_ANALOG; 3812fa91d15SJani Nikula connector->interlace_allowed = 0; 3822fa91d15SJani Nikula connector->doublescan_allowed = 0; 3832fa91d15SJani Nikula 3842fa91d15SJani Nikula drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); 3852fa91d15SJani Nikula drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); 3862fa91d15SJani Nikula 3872fa91d15SJani Nikula drm_connector_register(connector); 3882fa91d15SJani Nikula } 3892fa91d15SJani Nikula 3902fa91d15SJani NikulaIn the example above (taken from the i915 driver), a CRTC, connector and 3912fa91d15SJani Nikulaencoder combination is created. A device-specific i2c bus is also 3922fa91d15SJani Nikulacreated for fetching EDID data and performing monitor detection. Once 3932fa91d15SJani Nikulathe process is complete, the new connector is registered with sysfs to 3942fa91d15SJani Nikulamake its properties available to applications. 3952fa91d15SJani Nikula 3962fa91d15SJani NikulaKMS Locking 397311b62d9SDaniel Vetter=========== 3982fa91d15SJani Nikula 3992fa91d15SJani Nikula.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 4002fa91d15SJani Nikula :doc: kms locking 4012fa91d15SJani Nikula 4022fa91d15SJani Nikula.. kernel-doc:: include/drm/drm_modeset_lock.h 4032fa91d15SJani Nikula :internal: 4042fa91d15SJani Nikula 4052fa91d15SJani Nikula.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 4062fa91d15SJani Nikula :export: 4072fa91d15SJani Nikula 4082fa91d15SJani NikulaKMS Properties 4092fa91d15SJani Nikula============== 4102fa91d15SJani Nikula 41159e71ee7SDaniel VetterProperty Types and Blob Property Support 41259e71ee7SDaniel Vetter---------------------------------------- 41359e71ee7SDaniel Vetter 414c8458c7eSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_property.c 415c8458c7eSDaniel Vetter :doc: overview 416c8458c7eSDaniel Vetter 41759e71ee7SDaniel Vetter.. kernel-doc:: include/drm/drm_property.h 41859e71ee7SDaniel Vetter :internal: 41959e71ee7SDaniel Vetter 42059e71ee7SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_property.c 42159e71ee7SDaniel Vetter :export: 42259e71ee7SDaniel Vetter 4234ada6f22SDaniel VetterStandard Connector Properties 4244ada6f22SDaniel Vetter----------------------------- 4254ada6f22SDaniel Vetter 4264ada6f22SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 4274ada6f22SDaniel Vetter :doc: standard connector properties 4284ada6f22SDaniel Vetter 4291e4d84c6SDaniel VetterPlane Composition Properties 4301e4d84c6SDaniel Vetter---------------------------- 4311e4d84c6SDaniel Vetter 4321e4d84c6SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_blend.c 4331e4d84c6SDaniel Vetter :doc: overview 43452a9fcdaSDaniel Vetter 43552a9fcdaSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_blend.c 43652a9fcdaSDaniel Vetter :export: 43752a9fcdaSDaniel Vetter 438a6acccf8SDaniel VetterColor Management Properties 439a6acccf8SDaniel Vetter--------------------------- 440a6acccf8SDaniel Vetter 441a6acccf8SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 442a6acccf8SDaniel Vetter :doc: overview 443a6acccf8SDaniel Vetter 444a6acccf8SDaniel Vetter.. kernel-doc:: include/drm/drm_color_mgmt.h 445a6acccf8SDaniel Vetter :internal: 446a6acccf8SDaniel Vetter 447a6acccf8SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 448a6acccf8SDaniel Vetter :export: 449a6acccf8SDaniel Vetter 4509498c19bSDaniel VetterTile Group Property 4519498c19bSDaniel Vetter------------------- 4529498c19bSDaniel Vetter 4539498c19bSDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_connector.c 4549498c19bSDaniel Vetter :doc: Tile group 4559498c19bSDaniel Vetter 4569a83a71aSGustavo PadovanExplicit Fencing Properties 4579a83a71aSGustavo Padovan--------------------------- 4589a83a71aSGustavo Padovan 4599a83a71aSGustavo Padovan.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 4609a83a71aSGustavo Padovan :doc: explicit fencing properties 4619a83a71aSGustavo Padovan 4622fa91d15SJani NikulaExisting KMS Properties 4632fa91d15SJani Nikula----------------------- 4642fa91d15SJani Nikula 4652fa91d15SJani NikulaThe following table gives description of drm properties exposed by 4662fa91d15SJani Nikulavarious modules/drivers. 4672fa91d15SJani Nikula 4682fa91d15SJani Nikula.. csv-table:: 4692fa91d15SJani Nikula :header-rows: 1 4702fa91d15SJani Nikula :file: kms-properties.csv 4712fa91d15SJani Nikula 4722fa91d15SJani NikulaVertical Blanking 4732fa91d15SJani Nikula================= 4742fa91d15SJani Nikula 4752fa91d15SJani NikulaVertical blanking plays a major role in graphics rendering. To achieve 4762fa91d15SJani Nikulatear-free display, users must synchronize page flips and/or rendering to 4772fa91d15SJani Nikulavertical blanking. The DRM API offers ioctls to perform page flips 4782fa91d15SJani Nikulasynchronized to vertical blanking and wait for vertical blanking. 4792fa91d15SJani Nikula 4802fa91d15SJani NikulaThe DRM core handles most of the vertical blanking management logic, 4812fa91d15SJani Nikulawhich involves filtering out spurious interrupts, keeping race-free 4822fa91d15SJani Nikulablanking counters, coping with counter wrap-around and resets and 4832fa91d15SJani Nikulakeeping use counts. It relies on the driver to generate vertical 4842fa91d15SJani Nikulablanking interrupts and optionally provide a hardware vertical blanking 4852fa91d15SJani Nikulacounter. Drivers must implement the following operations. 4862fa91d15SJani Nikula 4872fa91d15SJani Nikula- int (\*enable_vblank) (struct drm_device \*dev, int crtc); void 4882fa91d15SJani Nikula (\*disable_vblank) (struct drm_device \*dev, int crtc); 4892fa91d15SJani Nikula Enable or disable vertical blanking interrupts for the given CRTC. 4902fa91d15SJani Nikula 4912fa91d15SJani Nikula- u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc); 4922fa91d15SJani Nikula Retrieve the value of the vertical blanking counter for the given 4932fa91d15SJani Nikula CRTC. If the hardware maintains a vertical blanking counter its value 4942fa91d15SJani Nikula should be returned. Otherwise drivers can use the 4952fa91d15SJani Nikula :c:func:`drm_vblank_count()` helper function to handle this 4962fa91d15SJani Nikula operation. 4972fa91d15SJani Nikula 4982fa91d15SJani NikulaDrivers must initialize the vertical blanking handling core with a call 4992fa91d15SJani Nikulato :c:func:`drm_vblank_init()` in their load operation. 5002fa91d15SJani Nikula 5012fa91d15SJani NikulaVertical blanking interrupts can be enabled by the DRM core or by 5022fa91d15SJani Nikuladrivers themselves (for instance to handle page flipping operations). 5032fa91d15SJani NikulaThe DRM core maintains a vertical blanking use count to ensure that the 5042fa91d15SJani Nikulainterrupts are not disabled while a user still needs them. To increment 5052fa91d15SJani Nikulathe use count, drivers call :c:func:`drm_vblank_get()`. Upon 5062fa91d15SJani Nikulareturn vertical blanking interrupts are guaranteed to be enabled. 5072fa91d15SJani Nikula 5082fa91d15SJani NikulaTo decrement the use count drivers call 5092fa91d15SJani Nikula:c:func:`drm_vblank_put()`. Only when the use count drops to zero 5102fa91d15SJani Nikulawill the DRM core disable the vertical blanking interrupts after a delay 5112fa91d15SJani Nikulaby scheduling a timer. The delay is accessible through the 5122fa91d15SJani Nikulavblankoffdelay module parameter or the ``drm_vblank_offdelay`` global 5132fa91d15SJani Nikulavariable and expressed in milliseconds. Its default value is 5000 ms. 5142fa91d15SJani NikulaZero means never disable, and a negative value means disable 5152fa91d15SJani Nikulaimmediately. Drivers may override the behaviour by setting the 5162fa91d15SJani Nikula:c:type:`struct drm_device <drm_device>` 5172fa91d15SJani Nikulavblank_disable_immediate flag, which when set causes vblank interrupts 5182fa91d15SJani Nikulato be disabled immediately regardless of the drm_vblank_offdelay 5192fa91d15SJani Nikulavalue. The flag should only be set if there's a properly working 5202fa91d15SJani Nikulahardware vblank counter present. 5212fa91d15SJani Nikula 5222fa91d15SJani NikulaWhen a vertical blanking interrupt occurs drivers only need to call the 5232fa91d15SJani Nikula:c:func:`drm_handle_vblank()` function to account for the 5242fa91d15SJani Nikulainterrupt. 5252fa91d15SJani Nikula 5262fa91d15SJani NikulaResources allocated by :c:func:`drm_vblank_init()` must be freed 5272fa91d15SJani Nikulawith a call to :c:func:`drm_vblank_cleanup()` in the driver unload 5282fa91d15SJani Nikulaoperation handler. 5292fa91d15SJani Nikula 5302fa91d15SJani NikulaVertical Blanking and Interrupt Handling Functions Reference 5312fa91d15SJani Nikula------------------------------------------------------------ 5322fa91d15SJani Nikula 53334a67dd7SDaniel Vetter.. kernel-doc:: include/drm/drm_irq.h 53434a67dd7SDaniel Vetter :internal: 5351ea35768SDaniel Vetter 5361ea35768SDaniel Vetter.. kernel-doc:: drivers/gpu/drm/drm_irq.c 5371ea35768SDaniel Vetter :export: 538