<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>KMS Properties</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Linux DRM Developer's Guide" /><link rel="up" href="drmInternals.html" title="Chapter 2. DRM Internals" /><link rel="prev" href="API-drm-rect-debug-print.html" title="drm_rect_debug_print" /><link rel="next" href="drm-vertical-blank.html" title="Vertical Blanking" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">KMS Properties</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-drm-rect-debug-print.html">Prev</a> </td><th width="60%" align="center">Chapter 2. DRM Internals</th><td width="20%" align="right"> <a accesskey="n" href="drm-vertical-blank.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="drm-kms-properties"></a>KMS Properties</h2></div></div></div><p>
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.
</p><p>
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.
</p><p>
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.
</p><p>
Every property is created with a type that influences how the KMS core
handles the property. Supported property types are
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">DRM_MODE_PROP_RANGE</span></dt><dd><p>Range properties report their minimum and maximum
admissible values. The KMS core verifies that values set by
application fit in that range.</p></dd><dt><span class="term">DRM_MODE_PROP_ENUM</span></dt><dd><p>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.
</p></dd><dt><span class="term">DRM_MODE_PROP_BITMASK</span></dt><dd><p>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.</p></dd><dt><span class="term">DRM_MODE_PROP_BLOB</span></dt><dd><p>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.</p><p>Blob properties are only used for the connector EDID property
and cannot be created by drivers.</p></dd></dl></div><p>
</p><p>
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.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><pre class="synopsis">struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
const char *name,
uint64_t min, uint64_t max);</pre><p>Create a range property with the given minimum and maximum
values.</p></li><li class="listitem"><pre class="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);</pre><p>Create an enumerated property. The <em class="parameter"><code>props</code></em>
argument points to an array of <em class="parameter"><code>num_values</code></em>
value-name pairs.</p></li><li class="listitem"><pre class="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);</pre><p>Create a bitmask property. The <em class="parameter"><code>props</code></em>
argument points to an array of <em class="parameter"><code>num_values</code></em>
value-name pairs.</p></li></ul></div><p>
</p><p>
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.
</p><p>
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 <code class="function">drm_property_create</code> function
and manually add enumeration value-name pairs by calling the
<code class="function">drm_property_add_enum</code> function. Care must be taken to
properly specify the property type through the <em class="parameter"><code>flags</code></em>
argument.
</p><p>
After creating properties drivers can attach property instances to CRTC,
connector and plane objects by calling the
<code class="function">drm_object_attach_property</code>. The function takes a
pointer to the target object, a pointer to the previously created property
and an initial instance value.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-drm-rect-debug-print.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="drmInternals.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="drm-vertical-blank.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">drm_rect_debug_print</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Vertical Blanking</td></tr></table></div></body></html>
distrib
>
Fedora
>
18
>
x86_64
>
media
>
updates
>
by-pkgid
>
1a595394b241504ff370a8d12ebfcea7
>
files
>
1811
