attempted on some ARM embedded platforms. Such drivers really must have
a hardware-specific ioctl to allocate suitable buffer objects.
+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
================================
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.
Cleanup
-------
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.
-
-Blending and Z-Position properties
-----------------------------------
+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