Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 421cda3e authored by Laurent Pinchart's avatar Laurent Pinchart Committed by Dave Airlie
Browse files

drm/doc: Document the KMS property API 



Signed-off-by: default avatarLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Reviewed-by: default avatarAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: default avatarDave Airlie <airlied@redhat.com>
parent 02c030a7

Documentation/DocBook/drm.tmpl

+143 −0
Original line number Diff line number Diff line
@@ -1235,6 +1235,15 @@ int max_width, max_height;</synopsis> 
        <sect4>

          <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>
@@ -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>
@@ -1593,6 +1611,15 @@ int max_width, max_height;</synopsis> 
        <sect4>

          <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>
@@ -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>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 -->



  <sect1 id="drm-vertical-blank">