Kernel Mode Setting (KMS)
=========================
-Mode Setting
-============
-
Drivers must initialize the mode setting core by calling
:c:func:`drm_mode_config_init()` on the DRM device. The function
initializes the :c:type:`struct drm_device <drm_device>`
- struct drm_mode_config_funcs \*funcs;
Mode setting functions.
-Display Modes Function Reference
---------------------------------
+Modeset Base Object Abstraction
+===============================
-.. kernel-doc:: include/drm/drm_modes.h
+.. kernel-doc:: include/drm/drm_mode_object.h
:internal:
-.. kernel-doc:: drivers/gpu/drm/drm_modes.c
+.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
+ :export:
+
+KMS Data Structures
+===================
+
+.. kernel-doc:: include/drm/drm_crtc.h
+ :internal:
+
+KMS API Functions
+=================
+
+.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
:export:
Atomic Mode Setting Function Reference
---------------------------------------
+======================================
.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
:export:
-.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
+.. kernel-doc:: include/drm/drm_atomic.h
:internal:
Frame Buffer Abstraction
-------------------------
-
-Frame buffers are abstract memory objects that provide a source of
-pixels to scanout to a CRTC. Applications explicitly request the
-creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls
-and receive an opaque handle that can be passed to the KMS CRTC control,
-plane configuration and page flip functions.
-
-Frame buffers rely on the underneath memory manager for low-level memory
-operations. When creating a frame buffer applications pass a memory
-handle (or a list of memory handles for multi-planar formats) through
-the ``drm_mode_fb_cmd2`` argument. For drivers using GEM as their
-userspace buffer management interface this would be a GEM handle.
-Drivers are however free to use their own backing storage object
-handles, e.g. vmwgfx directly exposes special TTM handles to userspace
-and so expects TTM handles in the create ioctl and not GEM handles.
-
-The lifetime of a drm framebuffer is controlled with a reference count,
-drivers can grab additional references with
-:c:func:`drm_framebuffer_reference()`and drop them again with
-:c:func:`drm_framebuffer_unreference()`. For driver-private
-framebuffers for which the last reference is never dropped (e.g. for the
-fbdev framebuffer when the struct :c:type:`struct drm_framebuffer
-<drm_framebuffer>` is embedded into the fbdev helper struct)
-drivers can manually clean up a framebuffer at module unload time with
-:c:func:`drm_framebuffer_unregister_private()`.
+========================
+
+.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
+ :doc: overview
+
+Frame Buffer Functions Reference
+--------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
+ :export:
+
+.. kernel-doc:: include/drm/drm_framebuffer.h
+ :internal:
DRM Format Handling
--------------------
+===================
.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
:export:
Dumb Buffer Objects
--------------------
+===================
The KMS API doesn't standardize backing storage object creation and
leaves it to driver-specific ioctls. Furthermore actually creating a
attempted on some ARM embedded platforms. Such drivers really must have
a hardware-specific ioctl to allocate suitable buffer objects.
-Output Polling
---------------
+Plane Abstraction
+=================
+
+.. kernel-doc:: drivers/gpu/drm/drm_plane.c
+ :doc: overview
+
+Plane Functions Reference
+-------------------------
+
+.. kernel-doc:: include/drm/drm_plane.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_plane.c
+ :export:
+
+Display Modes Function Reference
+================================
+
+.. kernel-doc:: include/drm/drm_modes.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_modes.c
+ :export:
-void (\*output_poll_changed)(struct drm_device \*dev);
-This operation notifies the driver that the status of one or more
-connectors has changed. Drivers that use the fb helper can just call the
-:c:func:`drm_fb_helper_hotplug_event()` function to handle this
-operation.
+Connector Abstraction
+=====================
+
+.. kernel-doc:: drivers/gpu/drm/drm_connector.c
+ :doc: overview
+
+Connector Functions Reference
+-----------------------------
+
+.. kernel-doc:: include/drm/drm_connector.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_connector.c
+ :export:
+
+Encoder Abstraction
+===================
+
+.. kernel-doc:: drivers/gpu/drm/drm_encoder.c
+ :doc: overview
+
+Encoder Functions Reference
+---------------------------
+
+.. kernel-doc:: include/drm/drm_encoder.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_encoder.c
+ :export:
KMS Initialization and Cleanup
==============================
structure, and registered with a call to :c:func:`drm_crtc_init()`
with a pointer to CRTC functions.
-Planes (:c:type:`struct drm_plane <drm_plane>`)
------------------------------------------------
-
-A plane represents an image source that can be blended with or overlayed
-on top of a CRTC during the scanout process. Planes are associated with
-a frame buffer to crop a portion of the image memory (source) and
-optionally scale it to a destination size. The result is then blended
-with or overlayed on top of a CRTC.
-
-The DRM core recognizes three types of planes:
-
-- DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC.
- Primary planes are the planes operated upon by CRTC modesetting and
- flipping operations described in the page_flip hook in
- :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>`.
-- DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC.
- Cursor planes are the planes operated upon by the
- DRM_IOCTL_MODE_CURSOR and DRM_IOCTL_MODE_CURSOR2 ioctls.
-- DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor
- planes. Some drivers refer to these types of planes as "sprites"
- internally.
-
-For compatibility with legacy userspace, only overlay planes are made
-available to userspace by default. Userspace clients may set the
-DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate
-that they wish to receive a universal plane list containing all plane
-types.
-
-Plane Initialization
-~~~~~~~~~~~~~~~~~~~~
-
-To create a plane, a KMS drivers allocates and zeroes an instances of
-:c:type:`struct drm_plane <drm_plane>` (possibly as part of a
-larger structure) and registers it with a call to
-:c:func:`drm_universal_plane_init()`. The function takes a
-bitmask of the CRTCs that can be associated with the plane, a pointer to
-the plane functions, a list of format supported formats, and the type of
-plane (primary, cursor, or overlay) being initialized.
-
-Cursor and overlay planes are optional. All drivers should provide one
-primary plane per CRTC (although this requirement may change in the
-future); drivers that do not wish to provide special handling for
-primary planes may make use of the helper functions described in ? to
-create and register a primary plane with standard capabilities.
-
-Encoders (:c:type:`struct drm_encoder <drm_encoder>`)
------------------------------------------------------
-
-An encoder takes pixel data from a CRTC and converts it to a format
-suitable for any attached connectors. On some devices, it may be
-possible to have a CRTC send data to more than one encoder. In that
-case, both encoders would receive data from the same scanout buffer,
-resulting in a "cloned" display configuration across the connectors
-attached to each encoder.
-
-Encoder Initialization
-~~~~~~~~~~~~~~~~~~~~~~
-
-As for CRTCs, a KMS driver must create, initialize and register at least
-one :c:type:`struct drm_encoder <drm_encoder>` instance. The
-instance is allocated and zeroed by the driver, possibly as part of a
-larger structure.
-
-Drivers must initialize the :c:type:`struct drm_encoder
-<drm_encoder>` possible_crtcs and possible_clones fields before
-registering the encoder. Both fields are bitmasks of respectively the
-CRTCs that the encoder can be connected to, and sibling encoders
-candidate for cloning.
-
-After being initialized, the encoder must be registered with a call to
-:c:func:`drm_encoder_init()`. The function takes a pointer to the
-encoder functions and an encoder type. Supported types are
-
-- DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A
-- DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort
-- DRM_MODE_ENCODER_LVDS for display panels
-- DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video,
- Component, SCART)
-- DRM_MODE_ENCODER_VIRTUAL for virtual machine displays
-
-Encoders must be attached to a CRTC to be used. DRM drivers leave
-encoders unattached at initialization time. Applications (or the fbdev
-compatibility layer when implemented) are responsible for attaching the
-encoders they want to use to a CRTC.
-
-Connectors (:c:type:`struct drm_connector <drm_connector>`)
------------------------------------------------------------
-
-A connector is the final destination for pixel data on a device, and
-usually connects directly to an external display device like a monitor
-or laptop panel. A connector can only be attached to one encoder at a
-time. The connector is also the structure where information about the
-attached display is kept, so it contains fields for display data, EDID
-data, DPMS & connection status, and information about modes supported on
-the attached displays.
-
-Connector Initialization
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Finally a KMS driver must create, initialize, register and attach at
-least one :c:type:`struct drm_connector <drm_connector>`
-instance. The instance is created as other KMS objects and initialized
-by setting the following fields.
-
-interlace_allowed
- Whether the connector can handle interlaced modes.
-
-doublescan_allowed
- Whether the connector can handle doublescan.
-
-display_info
- Display information is filled from EDID information when a display
- is detected. For non hot-pluggable displays such as flat panels in
- embedded systems, the driver should initialize the
- display_info.width_mm and display_info.height_mm fields with the
- physical size of the display.
-
-polled
- Connector polling mode, a combination of
-
- DRM_CONNECTOR_POLL_HPD
- The connector generates hotplug events and doesn't need to be
- periodically polled. The CONNECT and DISCONNECT flags must not
- be set together with the HPD flag.
-
- DRM_CONNECTOR_POLL_CONNECT
- Periodically poll the connector for connection.
-
- DRM_CONNECTOR_POLL_DISCONNECT
- Periodically poll the connector for disconnection.
-
- Set to 0 for connectors that don't support connection status
- discovery.
-
-The connector is then registered with a call to
-:c:func:`drm_connector_init()` with a pointer to the connector
-functions and a connector type, and exposed through sysfs with a call to
-:c:func:`drm_connector_register()`.
-
-Supported connector types are
-
-- DRM_MODE_CONNECTOR_VGA
-- DRM_MODE_CONNECTOR_DVII
-- DRM_MODE_CONNECTOR_DVID
-- DRM_MODE_CONNECTOR_DVIA
-- DRM_MODE_CONNECTOR_Composite
-- DRM_MODE_CONNECTOR_SVIDEO
-- DRM_MODE_CONNECTOR_LVDS
-- DRM_MODE_CONNECTOR_Component
-- DRM_MODE_CONNECTOR_9PinDIN
-- DRM_MODE_CONNECTOR_DisplayPort
-- DRM_MODE_CONNECTOR_HDMIA
-- DRM_MODE_CONNECTOR_HDMIB
-- DRM_MODE_CONNECTOR_TV
-- DRM_MODE_CONNECTOR_eDP
-- DRM_MODE_CONNECTOR_VIRTUAL
-
-Connectors must be attached to an encoder to be used. For devices that
-map connectors to encoders 1:1, the connector should be attached at
-initialization time with a call to
-:c:func:`drm_mode_connector_attach_encoder()`. The driver must
-also set the :c:type:`struct drm_connector <drm_connector>`
-encoder field to point to the attached encoder.
-
-Finally, drivers must initialize the connectors state change detection
-with a call to :c:func:`drm_kms_helper_poll_init()`. If at least
-one connector is pollable but can't generate hotplug interrupts
-(indicated by the DRM_CONNECTOR_POLL_CONNECT and
-DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will
-automatically be queued to periodically poll for changes. Connectors
-that can generate hotplug interrupts must be marked with the
-DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must
-call :c:func:`drm_helper_hpd_irq_event()`. The function will
-queue a delayed work to check the state of all connectors, but no
-periodic polling will be done.
-
-Connector Operations
-~~~~~~~~~~~~~~~~~~~~
-
- **Note**
-
- Unless otherwise state, all operations are mandatory.
-
-DPMS
-''''
-
-void (\*dpms)(struct drm_connector \*connector, int mode);
-The DPMS operation sets the power state of a connector. The mode
-argument is one of
-
-- DRM_MODE_DPMS_ON
-
-- DRM_MODE_DPMS_STANDBY
-
-- DRM_MODE_DPMS_SUSPEND
-
-- DRM_MODE_DPMS_OFF
-
-In all but DPMS_ON mode the encoder to which the connector is attached
-should put the display in low-power mode by driving its signals
-appropriately. If more than one connector is attached to the encoder
-care should be taken not to change the power state of other displays as
-a side effect. Low-power mode should be propagated to the encoders and
-CRTCs when all related connectors are put in low-power mode.
-
-Modes
-'''''
-
-int (\*fill_modes)(struct drm_connector \*connector, uint32_t
-max_width, uint32_t max_height);
-Fill the mode list with all supported modes for the connector. If the
-``max_width`` and ``max_height`` arguments are non-zero, the
-implementation must ignore all modes wider than ``max_width`` or higher
-than ``max_height``.
-
-The connector must also fill in this operation its display_info
-width_mm and height_mm fields with the connected display physical size
-in millimeters. The fields should be set to 0 if the value isn't known
-or is not applicable (for instance for projector devices).
-
-Connection Status
-'''''''''''''''''
-
-The connection status is updated through polling or hotplug events when
-supported (see ?). The status value is reported to userspace through
-ioctls and must not be used inside the driver, as it only gets
-initialized by a call to :c:func:`drm_mode_getconnector()` from
-userspace.
-
-enum drm_connector_status (\*detect)(struct drm_connector
-\*connector, bool force);
-Check to see if anything is attached to the connector. The ``force``
-parameter is set to false whilst polling or to true when checking the
-connector due to user request. ``force`` can be used by the driver to
-avoid expensive, destructive operations during automated probing.
-
-Return connector_status_connected if something is connected to the
-connector, connector_status_disconnected if nothing is connected and
-connector_status_unknown if the connection state isn't known.
-
-Drivers should only return connector_status_connected if the
-connection status has really been probed as connected. Connectors that
-can't detect the connection status, or failed connection status probes,
-should return connector_status_unknown.
Cleanup
-------
the process is complete, the new connector is registered with sysfs to
make its properties available to applications.
-KMS API Functions
------------------
-
-.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
- :export:
-
-KMS Data Structures
--------------------
-
-.. kernel-doc:: include/drm/drm_crtc.h
- :internal:
-
KMS Locking
------------
+===========
.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
:doc: kms locking
KMS Properties
==============
-Drivers may need to expose additional parameters to applications than
-those described in the previous sections. KMS supports attaching
-properties to CRTCs, connectors and planes and offers a userspace API to
-list, get and set the property values.
-
-Properties are identified by a name that uniquely defines the property
-purpose, and store an associated value. For all property types except
-blob properties the value is a 64-bit unsigned integer.
-
-KMS differentiates between properties and property instances. Drivers
-first create properties and then create and associate individual
-instances of those properties to objects. A property can be instantiated
-multiple times and associated with different objects. Values are stored
-in property instances, and all other property information are stored in
-the property and shared between all instances of the property.
-
-Every property is created with a type that influences how the KMS core
-handles the property. Supported property types are
-
-DRM_MODE_PROP_RANGE
- Range properties report their minimum and maximum admissible values.
- The KMS core verifies that values set by application fit in that
- range.
-
-DRM_MODE_PROP_ENUM
- Enumerated properties take a numerical value that ranges from 0 to
- the number of enumerated values defined by the property minus one,
- and associate a free-formed string name to each value. Applications
- can retrieve the list of defined value-name pairs and use the
- numerical value to get and set property instance values.
-
-DRM_MODE_PROP_BITMASK
- Bitmask properties are enumeration properties that additionally
- restrict all enumerated values to the 0..63 range. Bitmask property
- instance values combine one or more of the enumerated bits defined
- by the property.
-
-DRM_MODE_PROP_BLOB
- Blob properties store a binary blob without any format restriction.
- The binary blobs are created as KMS standalone objects, and blob
- property instance values store the ID of their associated blob
- object.
-
- Blob properties are only used for the connector EDID property and
- cannot be created by drivers.
-
-To create a property drivers call one of the following functions
-depending on the property type. All property creation functions take
-property flags and name, as well as type-specific arguments.
-
-- struct drm_property \*drm_property_create_range(struct
- drm_device \*dev, int flags, const char \*name, uint64_t min,
- uint64_t max);
- Create a range property with the given minimum and maximum values.
-
-- struct drm_property \*drm_property_create_enum(struct drm_device
- \*dev, int flags, const char \*name, const struct
- drm_prop_enum_list \*props, int num_values);
- Create an enumerated property. The ``props`` argument points to an
- array of ``num_values`` value-name pairs.
-
-- struct drm_property \*drm_property_create_bitmask(struct
- drm_device \*dev, int flags, const char \*name, const struct
- drm_prop_enum_list \*props, int num_values);
- Create a bitmask property. The ``props`` argument points to an array
- of ``num_values`` value-name pairs.
-
-Properties can additionally be created as immutable, in which case they
-will be read-only for applications but can be modified by the driver. To
-create an immutable property drivers must set the
-DRM_MODE_PROP_IMMUTABLE flag at property creation time.
-
-When no array of value-name pairs is readily available at property
-creation time for enumerated or range properties, drivers can create the
-property using the :c:func:`drm_property_create()` function and
-manually add enumeration value-name pairs by calling the
-:c:func:`drm_property_add_enum()` function. Care must be taken to
-properly specify the property type through the ``flags`` argument.
-
-After creating properties drivers can attach property instances to CRTC,
-connector and plane objects by calling the
-:c:func:`drm_object_attach_property()`. The function takes a
-pointer to the target object, a pointer to the previously created
-property and an initial instance value.
+Property Types and Blob Property Support
+----------------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_property.c
+ :doc: overview
+
+.. kernel-doc:: include/drm/drm_property.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_property.c
+ :export:
+
+Plane Composition Properties
+----------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_blend.c
+ :doc: overview
+
+.. kernel-doc:: drivers/gpu/drm/drm_blend.c
+ :export:
+
+Color Management Properties
+---------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
+ :doc: overview
+
+.. kernel-doc:: include/drm/drm_color_mgmt.h
+ :internal:
+
+.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
+ :export:
Existing KMS Properties
-----------------------
projects / cascardo / linux.git / blobdiff