[PATCH 2/2] drm/doc: Document the KMS property API
Hans Verkuil
hverkuil at xs4all.nl
Sat Jun 22 06:32:43 PDT 2013
Hi Laurent,
Is this a hint to me that V4L2 should have a property API as well? :-)
Anyway, I found some typos below:
On Sat June 22 2013 15:00:27 Laurent Pinchart wrote:
> Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas at ideasonboard.com>
> ---
> Documentation/DocBook/drm.tmpl | 143 +++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 143 insertions(+)
>
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index cea420d..9d4bb06 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -1236,6 +1236,15 @@ int max_width, max_height;</synopsis>
> <title>Miscellaneous</title>
> <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>
> <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
> uint32_t start, uint32_t size);</synopsis>
> <para>
> @@ -1385,6 +1394,15 @@ int max_width, max_height;</synopsis>
> <xref linkend="drm-kms-init"/>.
> </para>
> </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>
> </sect3>
> </sect2>
> @@ -1594,6 +1612,15 @@ int max_width, max_height;</synopsis>
> <title>Miscellaneous</title>
> <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>
> <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis>
> <para>
> Destroy the connector when not needed anymore. See
> @@ -2187,6 +2214,122 @@ void intel_crt_init(struct drm_device *dev)
> </sect2>
> </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>Ranges properties report their minimum and maximum
s/Ranges/Range/
> + 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 enumered values defined by the
s/enumered/enumerated/
> + property minus one, and associate a free-formed string name to each
> + value. Application can retrieve the list of define value-name pairs
s/Application/Applications/
s/define/defined/
> + 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>Blocb properties are only used for the connector EDID property
s/Blocb/Blob/
> + 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 -->
>
> <sect1 id="drm-vertical-blank">
>
Regards,
Hans
More information about the dri-devel
mailing list