drm/doc: Document the KMS property API
Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> Reviewed-by: Alex Deucher <alexander.deucher@amd.com> Signed-off-by: Dave Airlie <airlied@redhat.com>
This commit is contained in:
Laurent Pinchart
committed by
Dave Airlie
Dave Airlie
parent
02c030a718
commit
421cda3e32
@@ -1235,6 +1235,15 @@ int max_width, max_height;</synopsis>
|
|||||||
<sect4>
|
<sect4>
|
||||||
<title>Miscellaneous</title>
|
<title>Miscellaneous</title>
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<synopsis>void (*set_property)(struct drm_crtc *crtc,
|
||||||
|
struct drm_property *property, uint64_t value);</synopsis>
|
||||||
|
<para>
|
||||||
|
Set the value of the given CRTC property to
|
||||||
|
<parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
|
||||||
|
for more information about properties.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
|
<synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
|
||||||
uint32_t start, uint32_t size);</synopsis>
|
uint32_t start, uint32_t size);</synopsis>
|
||||||
@@ -1385,6 +1394,15 @@ int max_width, max_height;</synopsis>
|
|||||||
<xref linkend="drm-kms-init"/>.
|
<xref linkend="drm-kms-init"/>.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<synopsis>void (*set_property)(struct drm_plane *plane,
|
||||||
|
struct drm_property *property, uint64_t value);</synopsis>
|
||||||
|
<para>
|
||||||
|
Set the value of the given plane property to
|
||||||
|
<parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
|
||||||
|
for more information about properties.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</sect3>
|
</sect3>
|
||||||
</sect2>
|
</sect2>
|
||||||
@@ -1593,6 +1611,15 @@ int max_width, max_height;</synopsis>
|
|||||||
<sect4>
|
<sect4>
|
||||||
<title>Miscellaneous</title>
|
<title>Miscellaneous</title>
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<synopsis>void (*set_property)(struct drm_connector *connector,
|
||||||
|
struct drm_property *property, uint64_t value);</synopsis>
|
||||||
|
<para>
|
||||||
|
Set the value of the given connector property to
|
||||||
|
<parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
|
||||||
|
for more information about properties.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<synopsis>void (*destroy)(struct drm_connector *connector);</synopsis>
|
<synopsis>void (*destroy)(struct drm_connector *connector);</synopsis>
|
||||||
<para>
|
<para>
|
||||||
@@ -2187,6 +2214,122 @@ void intel_crt_init(struct drm_device *dev)
|
|||||||
</sect2>
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
<!-- Internals: kms properties -->
|
||||||
|
|
||||||
|
<sect1 id="drm-kms-properties">
|
||||||
|
<title>KMS Properties</title>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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 propery
|
||||||
|
and shared between all instances of the property.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Every property is created with a type that influences how the KMS core
|
||||||
|
handles the property. Supported property types are
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term>DRM_MODE_PROP_RANGE</term>
|
||||||
|
<listitem><para>Range properties report their minimum and maximum
|
||||||
|
admissible values. The KMS core verifies that values set by
|
||||||
|
application fit in that range.</para></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>DRM_MODE_PROP_ENUM</term>
|
||||||
|
<listitem><para>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.
|
||||||
|
</para></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>DRM_MODE_PROP_BITMASK</term>
|
||||||
|
<listitem><para>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.</para></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>DRM_MODE_PROP_BLOB</term>
|
||||||
|
<listitem><para>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.</para>
|
||||||
|
<para>Blob properties are only used for the connector EDID property
|
||||||
|
and cannot be created by drivers.</para></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<synopsis>struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
|
||||||
|
const char *name,
|
||||||
|
uint64_t min, uint64_t max);</synopsis>
|
||||||
|
<para>Create a range property with the given minimum and maximum
|
||||||
|
values.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<synopsis>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);</synopsis>
|
||||||
|
<para>Create an enumerated property. The <parameter>props</parameter>
|
||||||
|
argument points to an array of <parameter>num_values</parameter>
|
||||||
|
value-name pairs.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<synopsis>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);</synopsis>
|
||||||
|
<para>Create a bitmask property. The <parameter>props</parameter>
|
||||||
|
argument points to an array of <parameter>num_values</parameter>
|
||||||
|
value-name pairs.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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 <function>drm_property_create</function> function
|
||||||
|
and manually add enumeration value-name pairs by calling the
|
||||||
|
<function>drm_property_add_enum</function> function. Care must be taken to
|
||||||
|
properly specify the property type through the <parameter>flags</parameter>
|
||||||
|
argument.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
After creating properties drivers can attach property instances to CRTC,
|
||||||
|
connector and plane objects by calling the
|
||||||
|
<function>drm_object_attach_property</function>. The function takes a
|
||||||
|
pointer to the target object, a pointer to the previously created property
|
||||||
|
and an initial instance value.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
<!-- Internals: vertical blanking -->
|
<!-- Internals: vertical blanking -->
|
||||||
|
|
||||||
<sect1 id="drm-vertical-blank">
|
<sect1 id="drm-vertical-blank">
|
||||||
|
|||||||
Reference in New Issue
Block a user