forked from ~ljy/RK356X_SDK_RELEASE
blame | history | patch | commit | commitdiff
hc
2024-01-31 f70575805708cabdedea7498aaa3f710fde4d920 
 kernel/Documentation/gpu/drm-kms.rst
....@@ -3,7 +3,7 @@
33 =========================
44 
55 Drivers must initialize the mode setting core by calling
6
-:c:func:`drm_mode_config_init()` on the DRM device. The function
6
+drmm_mode_config_init() on the DRM device. The function
77 initializes the :c:type:`struct drm_device <drm_device>`
88 mode_config field and never fails. Once done, mode configuration must
99 be setup by initializing the following fields.
....@@ -181,8 +181,7 @@
181181 directly instantiated on each object, but free-standing mode objects themselves,
182182 represented by :c:type:`struct drm_property <drm_property>`, which only specify
183183 the type and value range of a property. Any given property can be attached
184
-multiple times to different objects using :c:func:`drm_object_attach_property()
185
-<drm_object_attach_property>`.
184
+multiple times to different objects using drm_object_attach_property().
186185 
187186 .. kernel-doc:: include/drm/drm_mode_object.h
188187    :internal:
....@@ -260,7 +259,8 @@
260259   drm_connector_state <drm_connector_state>` for connectors. These are the only
261260   objects with userspace-visible and settable state. For internal state drivers
262261   can subclass these structures through embeddeding, or add entirely new state
263
-  structures for their globally shared hardware functions.
262
+  structures for their globally shared hardware functions, see :c:type:`struct
263
+  drm_private_state<drm_private_state>`.
264264 
265265 - An atomic update is assembled and validated as an entirely free-standing pile
266266   of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
....@@ -268,6 +268,14 @@
268268   structure; see the next chapter.  Only when a state is committed is it applied
269269   to the driver and modeset objects. This way rolling back an update boils down
270270   to releasing memory and unreferencing objects like framebuffers.
271
+
272
+Locking of atomic state structures is internally using :c:type:`struct
273
+drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be
274
+exposed to drivers, instead the right locks should be automatically acquired by
275
+any function that duplicates or peeks into a state, like e.g.
276
+drm_atomic_get_crtc_state().  Locking only protects the software data
277
+structure, ordering of committing state changes to hardware is sequenced using
278
+:c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
271279 
272280 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
273281 coverage of specific topics.
....@@ -287,8 +295,14 @@
287295 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
288296    :export:
289297 
290
-.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
291
-   :internal:
298
+Atomic Mode Setting IOCTL and UAPI Functions
299
+--------------------------------------------
300
+
301
+.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
302
+   :doc: overview
303
+
304
+.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
305
+   :export:
292306 
293307 CRTC Abstraction
294308 ================
....@@ -322,6 +336,12 @@
322336 
323337 DRM Format Handling
324338 ===================
339
+
340
+.. kernel-doc:: include/uapi/drm/drm_fourcc.h
341
+   :doc: overview
342
+
343
+Format Functions Reference
344
+--------------------------
325345 
326346 .. kernel-doc:: include/drm/drm_fourcc.h
327347    :internal:
....@@ -377,6 +397,9 @@
377397 Writeback Connectors
378398 --------------------
379399 
400
+.. kernel-doc:: include/drm/drm_writeback.h
401
+  :internal:
402
+
380403 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
381404   :doc: overview
382405 
....@@ -397,102 +420,6 @@
397420 
398421 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
399422    :export:
400
-
401
-KMS Initialization and Cleanup
402
-==============================
403
-
404
-A KMS device is abstracted and exposed as a set of planes, CRTCs,
405
-encoders and connectors. KMS drivers must thus create and initialize all
406
-those objects at load time after initializing mode setting.
407
-
408
-CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
409
---------------------------------------------
410
-
411
-A CRTC is an abstraction representing a part of the chip that contains a
412
-pointer to a scanout buffer. Therefore, the number of CRTCs available
413
-determines how many independent scanout buffers can be active at any
414
-given time. The CRTC structure contains several fields to support this:
415
-a pointer to some video memory (abstracted as a frame buffer object), a
416
-display mode, and an (x, y) offset into the video memory to support
417
-panning or configurations where one piece of video memory spans multiple
418
-CRTCs.
419
-
420
-CRTC Initialization
421
-~~~~~~~~~~~~~~~~~~~
422
-
423
-A KMS device must create and register at least one struct
424
-:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
425
-allocated and zeroed by the driver, possibly as part of a larger
426
-structure, and registered with a call to :c:func:`drm_crtc_init()`
427
-with a pointer to CRTC functions.
428
-
429
-
430
-Cleanup
431
--------
432
-
433
-The DRM core manages its objects' lifetime. When an object is not needed
434
-anymore the core calls its destroy function, which must clean up and
435
-free every resource allocated for the object. Every
436
-:c:func:`drm_\*_init()` call must be matched with a corresponding
437
-:c:func:`drm_\*_cleanup()` call to cleanup CRTCs
438
-(:c:func:`drm_crtc_cleanup()`), planes
439
-(:c:func:`drm_plane_cleanup()`), encoders
440
-(:c:func:`drm_encoder_cleanup()`) and connectors
441
-(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
442
-have been added to sysfs must be removed by a call to
443
-:c:func:`drm_connector_unregister()` before calling
444
-:c:func:`drm_connector_cleanup()`.
445
-
446
-Connectors state change detection must be cleanup up with a call to
447
-:c:func:`drm_kms_helper_poll_fini()`.
448
-
449
-Output discovery and initialization example
450
--------------------------------------------
451
-
452
-.. code-block:: c
453
-
454
-    void intel_crt_init(struct drm_device *dev)
455
-    {
456
-        struct drm_connector *connector;
457
-        struct intel_output *intel_output;
458
-
459
-        intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
460
-        if (!intel_output)
461
-            return;
462
-
463
-        connector = &intel_output->base;
464
-        drm_connector_init(dev, &intel_output->base,
465
-                   &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
466
-
467
-        drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
468
-                 DRM_MODE_ENCODER_DAC);
469
-
470
-        drm_connector_attach_encoder(&intel_output->base,
471
-                          &intel_output->enc);
472
-
473
-        /* Set up the DDC bus. */
474
-        intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
475
-        if (!intel_output->ddc_bus) {
476
-            dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
477
-                   "failed.\n");
478
-            return;
479
-        }
480
-
481
-        intel_output->type = INTEL_OUTPUT_ANALOG;
482
-        connector->interlace_allowed = 0;
483
-        connector->doublescan_allowed = 0;
484
-
485
-        drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
486
-        drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
487
-
488
-        drm_connector_register(connector);
489
-    }
490
-
491
-In the example above (taken from the i915 driver), a CRTC, connector and
492
-encoder combination is created. A device-specific i2c bus is also
493
-created for fetching EDID data and performing monitor detection. Once
494
-the process is complete, the new connector is registered with sysfs to
495
-make its properties available to applications.
496423 
497424 KMS Locking
498425 ===========
....@@ -533,6 +460,12 @@
533460 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
534461    :doc: HDMI connector properties
535462 
463
+Standard CRTC Properties
464
+------------------------
465
+
466
+.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
467
+   :doc: standard CRTC properties
468
+
536469 Plane Composition Properties
537470 ----------------------------
538471 
....@@ -541,6 +474,18 @@
541474 
542475 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
543476    :export:
477
+
478
+FB_DAMAGE_CLIPS
479
+~~~~~~~~~~~~~~~
480
+
481
+.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
482
+   :doc: overview
483
+
484
+.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
485
+   :export:
486
+
487
+.. kernel-doc:: include/drm/drm_damage_helper.h
488
+   :internal:
544489 
545490 Color Management Properties
546491 ---------------------------
....@@ -551,6 +496,9 @@
551496 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
552497    :export:
553498 
499
+.. kernel-doc:: include/drm/drm_color_mgmt.h
500
+   :internal:
501
+
554502 Tile Group Property
555503 -------------------
556504 
....@@ -560,8 +508,15 @@
560508 Explicit Fencing Properties
561509 ---------------------------
562510 
563
-.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
511
+.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
564512    :doc: explicit fencing properties
513
+
514
+
515
+Variable Refresh Properties
516
+---------------------------
517
+
518
+.. kernel-doc:: drivers/gpu/drm/drm_connector.c
519
+   :doc: Variable refresh properties
565520 
566521 Existing KMS Properties
567522 -----------------------
....@@ -588,3 +543,18 @@
588543 
589544 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
590545    :export:
546
+
547
+Vertical Blank Work
548
+===================
549
+
550
+.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
551
+   :doc: vblank works
552
+
553
+Vertical Blank Work Functions Reference
554
+---------------------------------------
555
+
556
+.. kernel-doc:: include/drm/drm_vblank_work.h
557
+   :internal:
558
+
559
+.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
560
+   :export: