diff options
Diffstat (limited to 'Documentation/gpu/drm-kms.rst')
| -rw-r--r-- | Documentation/gpu/drm-kms.rst | 281 |
1 files changed, 163 insertions, 118 deletions
diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 75c882e09fee..2292e65f044c 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -3,7 +3,7 @@ Kernel Mode Setting (KMS) ========================= Drivers must initialize the mode setting core by calling -:c:func:`drm_mode_config_init()` on the DRM device. The function +drmm_mode_config_init() on the DRM device. The function initializes the :c:type:`struct drm_device <drm_device>` mode_config field and never fails. Once done, mode configuration must be setup by initializing the following fields. @@ -66,11 +66,11 @@ Composition Properties`_ and related chapters. For the output routing the first step is encoders (represented by :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those are really just internal artifacts of the helper libraries used to implement KMS -drivers. Besides that they make it unecessarily more complicated for userspace +drivers. Besides that they make it unnecessarily more complicated for userspace to figure out which connections between a CRTC and a connector are possible, and what kind of cloning is supported, they serve no purpose in the userspace API. Unfortunately encoders have been exposed to userspace, hence can't remove them -at this point. Futhermore the exposed restrictions are often wrongly set by +at this point. Furthermore the exposed restrictions are often wrongly set by drivers, and in many cases not powerful enough to express the real restrictions. A CRTC can be connected to multiple encoders, and for an active CRTC there must be at least one encoder. @@ -159,6 +159,8 @@ KMS Core Structures and Functions .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c :export: +.. _kms_base_object_abstraction: + Modeset Base Object Abstraction =============================== @@ -181,8 +183,7 @@ Setting`_). The somewhat surprising part here is that properties are not directly instantiated on each object, but free-standing mode objects themselves, represented by :c:type:`struct drm_property <drm_property>`, which only specify the type and value range of a property. Any given property can be attached -multiple times to different objects using :c:func:`drm_object_attach_property() -<drm_object_attach_property>`. +multiple times to different objects using drm_object_attach_property(). .. kernel-doc:: include/drm/drm_mode_object.h :internal: @@ -259,8 +260,9 @@ Taken all together there's two consequences for the atomic design: drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct drm_connector_state <drm_connector_state>` for connectors. These are the only objects with userspace-visible and settable state. For internal state drivers - can subclass these structures through embeddeding, or add entirely new state - structures for their globally shared hardware functions. + can subclass these structures through embedding, or add entirely new state + structures for their globally shared hardware functions, see :c:type:`struct + drm_private_state<drm_private_state>`. - An atomic update is assembled and validated as an entirely free-standing pile of structures within the :c:type:`drm_atomic_state <drm_atomic_state>` @@ -269,6 +271,14 @@ Taken all together there's two consequences for the atomic design: to the driver and modeset objects. This way rolling back an update boils down to releasing memory and unreferencing objects like framebuffers. +Locking of atomic state structures is internally using :c:type:`struct +drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be +exposed to drivers, instead the right locks should be automatically acquired by +any function that duplicates or peeks into a state, like e.g. +drm_atomic_get_crtc_state(). Locking only protects the software data +structure, ordering of committing state changes to hardware is sequenced using +:c:type:`struct drm_crtc_commit <drm_crtc_commit>`. + Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed coverage of specific topics. @@ -311,6 +321,15 @@ CRTC Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_crtc.c :export: +Color Management Functions Reference +------------------------------------ + +.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c + :export: + +.. kernel-doc:: include/drm/drm_color_mgmt.h + :internal: + Frame Buffer Abstraction ======================== @@ -341,6 +360,8 @@ Format Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c :export: +.. _kms_dumb_buffer_objects: + Dumb Buffer Objects =================== @@ -362,6 +383,51 @@ Plane Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_plane.c :export: +Plane Composition Functions Reference +------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_blend.c + :export: + +Plane Damage Tracking Functions Reference +----------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c + :export: + +.. kernel-doc:: include/drm/drm_damage_helper.h + :internal: + +Plane Panic Feature +------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_panic.c + :doc: overview + +Plane Panic Functions Reference +------------------------------- + +.. kernel-doc:: include/drm/drm_panic.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_panic.c + :export: + +Colorop Abstraction +=================== + +.. kernel-doc:: drivers/gpu/drm/drm_colorop.c + :doc: overview + +Colorop Functions Reference +--------------------------- + +.. kernel-doc:: include/drm/drm_colorop.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_colorop.c + :export: + Display Modes Function Reference ================================ @@ -392,6 +458,9 @@ Writeback Connectors .. kernel-doc:: drivers/gpu/drm/drm_writeback.c :doc: overview +.. kernel-doc:: include/drm/drm_writeback.h + :internal: + .. kernel-doc:: drivers/gpu/drm/drm_writeback.c :export: @@ -410,102 +479,6 @@ Encoder Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_encoder.c :export: -KMS Initialization and Cleanup -============================== - -A KMS device is abstracted and exposed as a set of planes, CRTCs, -encoders and connectors. KMS drivers must thus create and initialize all -those objects at load time after initializing mode setting. - -CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) --------------------------------------------- - -A CRTC is an abstraction representing a part of the chip that contains a -pointer to a scanout buffer. Therefore, the number of CRTCs available -determines how many independent scanout buffers can be active at any -given time. The CRTC structure contains several fields to support this: -a pointer to some video memory (abstracted as a frame buffer object), a -display mode, and an (x, y) offset into the video memory to support -panning or configurations where one piece of video memory spans multiple -CRTCs. - -CRTC Initialization -~~~~~~~~~~~~~~~~~~~ - -A KMS device must create and register at least one struct -:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is -allocated and zeroed by the driver, possibly as part of a larger -structure, and registered with a call to :c:func:`drm_crtc_init()` -with a pointer to CRTC functions. - - -Cleanup -------- - -The DRM core manages its objects' lifetime. When an object is not needed -anymore the core calls its destroy function, which must clean up and -free every resource allocated for the object. Every -:c:func:`drm_\*_init()` call must be matched with a corresponding -:c:func:`drm_\*_cleanup()` call to cleanup CRTCs -(:c:func:`drm_crtc_cleanup()`), planes -(:c:func:`drm_plane_cleanup()`), encoders -(:c:func:`drm_encoder_cleanup()`) and connectors -(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that -have been added to sysfs must be removed by a call to -:c:func:`drm_connector_unregister()` before calling -:c:func:`drm_connector_cleanup()`. - -Connectors state change detection must be cleanup up with a call to -:c:func:`drm_kms_helper_poll_fini()`. - -Output discovery and initialization example -------------------------------------------- - -.. code-block:: c - - void intel_crt_init(struct drm_device *dev) - { - struct drm_connector *connector; - struct intel_output *intel_output; - - intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); - if (!intel_output) - return; - - connector = &intel_output->base; - drm_connector_init(dev, &intel_output->base, - &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); - - drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, - DRM_MODE_ENCODER_DAC); - - drm_connector_attach_encoder(&intel_output->base, - &intel_output->enc); - - /* Set up the DDC bus. */ - intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); - if (!intel_output->ddc_bus) { - dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " - "failed.\n"); - return; - } - - intel_output->type = INTEL_OUTPUT_ANALOG; - connector->interlace_allowed = 0; - connector->doublescan_allowed = 0; - - drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); - drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); - - drm_connector_register(connector); - } - -In the example above (taken from the i915 driver), a CRTC, connector and -encoder combination is created. A device-specific i2c bus is also -created for fetching EDID data and performing monitor detection. Once -the process is complete, the new connector is registered with sysfs to -make its properties available to applications. - KMS Locking =========== @@ -521,6 +494,45 @@ KMS Locking KMS Properties ============== +This section of the documentation is primarily aimed at user-space developers. +For the driver APIs, see the other sections. + +Requirements +------------ + +KMS drivers might need to add extra properties to support new features. Each +new property introduced in a driver needs to meet a few requirements, in +addition to the one mentioned above: + +* It must be standardized, documenting: + + * The full, exact, name string; + * If the property is an enum, all the valid value name strings; + * What values are accepted, and what these values mean; + * What the property does and how it can be used; + * How the property might interact with other, existing properties. + +* It must provide a generic helper in the core code to register that + property on the object it attaches to. + +* Its content must be decoded by the core and provided in the object's + associated state structure. That includes anything drivers might want + to precompute, like struct drm_clip_rect for planes. + +* Its initial state must match the behavior prior to the property + introduction. This might be a fixed value matching what the hardware + does, or it may be inherited from the state the firmware left the + system in during boot. + +* An IGT test must be submitted where reasonable. + +For historical reasons, non-standard, driver-specific properties exist. If a KMS +driver wants to add support for one of those properties, the requirements for +new properties apply where possible. Additionally, the documented behavior must +match the de facto semantics of the existing property to ensure compatibility. +Developers of the driver that first added the property should help with those +tasks and must ACK the documented behavior if possible. + Property Types and Blob Property Support ---------------------------------------- @@ -533,6 +545,8 @@ Property Types and Blob Property Support .. kernel-doc:: drivers/gpu/drm/drm_property.c :export: +.. _standard_connector_properties: + Standard Connector Properties ----------------------------- @@ -545,26 +559,39 @@ HDMI Specific Connector Properties .. kernel-doc:: drivers/gpu/drm/drm_connector.c :doc: HDMI connector properties +Analog TV Specific Connector Properties +--------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_connector.c + :doc: Analog TV Connector Properties + +Standard CRTC Properties +------------------------ + +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c + :doc: standard CRTC properties + +Standard Plane Properties +------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_plane.c + :doc: standard plane properties + +.. _plane_composition_properties: + Plane Composition Properties ---------------------------- .. kernel-doc:: drivers/gpu/drm/drm_blend.c :doc: overview -.. kernel-doc:: drivers/gpu/drm/drm_blend.c - :export: - -FB_DAMAGE_CLIPS -~~~~~~~~~~~~~~~ +.. _damage_tracking_properties: -.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c - :doc: overview - -.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c - :export: +Damage Tracking Properties +-------------------------- -.. kernel-doc:: include/drm/drm_damage_helper.h - :internal: +.. kernel-doc:: drivers/gpu/drm/drm_plane.c + :doc: damage tracking Color Management Properties --------------------------- @@ -572,9 +599,6 @@ Color Management Properties .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c :doc: overview -.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c - :export: - Tile Group Property ------------------- @@ -594,6 +618,12 @@ Variable Refresh Properties .. kernel-doc:: drivers/gpu/drm/drm_connector.c :doc: Variable refresh properties +Cursor Hotspot Properties +--------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_plane.c + :doc: hotspot properties + Existing KMS Properties ----------------------- @@ -619,3 +649,18 @@ Vertical Blanking and Interrupt Handling Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_vblank.c :export: + +Vertical Blank Work +=================== + +.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c + :doc: vblank works + +Vertical Blank Work Functions Reference +--------------------------------------- + +.. kernel-doc:: include/drm/drm_vblank_work.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c + :export: |