[PATCH 0/2] Documentation improvements

[PATCH 0/2] Documentation improvements

[Laurent Pinchart]

Hello,

Here are two patches that improve the DRM documentation by documenting the KMS
property API, and removing an outdated note about the i915 driver.

Laurent Pinchart (2):
  drm/doc: Remove outdated note about i915 driver not behaving properly
  drm/doc: Document the KMS property API

 Documentation/DocBook/drm.tmpl | 147 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 143 insertions(+), 4 deletions(-)

-- 
Regards,

Laurent Pinchart

[PATCH 1/2] drm/doc: Remove outdated note about i915 driver not behaving properly

[Laurent Pinchart]

From: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

The i915 driver has been fixed not to modify the mode argument of the
encoder mode_fixup operation. Remove the related comment from the
documentation.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 Documentation/DocBook/drm.tmpl | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index a608094..cea420d 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -1868,10 +1868,6 @@ void intel_crt_init(struct drm_device *dev)
           <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder,
                        const struct drm_display_mode *mode,
                        struct drm_display_mode *adjusted_mode);</synopsis>
-          <note><para>
-            FIXME: The mode argument be const, but the i915 driver modifies
-            mode-&gt;clock in <function>intel_dp_mode_fixup</function>.
-          </para></note>
           <para>
             Let encoders adjust the requested mode or reject it completely. This
             operation returns true if the mode is accepted (possibly after being
-- 
1.8.1.5

[PATCH 2/2] drm/doc: Document the KMS property API

[Laurent Pinchart]

Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@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
+            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
+            property minus one, and associate a free-formed string name to each
+            value. Application can retrieve the list of define 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>Blocb 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">
-- 
1.8.1.5

Re: [PATCH 0/2] Documentation improvements

[Alex Deucher]

On Sat, Jun 22, 2013 at 9:00 AM, Laurent Pinchart
<laurent.pinchart+renesas@ideasonboard.com> wrote:
> Hello,
>
> Here are two patches that improve the DRM documentation by documenting the KMS
> property API, and removing an outdated note about the i915 driver.
>
> Laurent Pinchart (2):
>   drm/doc: Remove outdated note about i915 driver not behaving properly
>   drm/doc: Document the KMS property API

Looks good.  For the series:

Reviewed-by: Alex Deucher <alexander.deucher@amd.com>

>
>  Documentation/DocBook/drm.tmpl | 147 +++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 143 insertions(+), 4 deletions(-)
>
> --
> Regards,
>
> Laurent Pinchart
>
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 2/2] drm/doc: Document the KMS property API

[Hans Verkuil]

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

Re: [PATCH 2/2] drm/doc: Document the KMS property API

[Laurent Pinchart]

Hi Hans,

Thanks for the review.

On Saturday 22 June 2013 15:32:43 Hans Verkuil wrote:
> Hi Laurent,
> 
> Is this a hint to me that V4L2 should have a property API as well? :-)

Honestly, not at all, but I'm of course willing to discuss the subject ;-)

> Anyway, I found some typos below:

Thank you. I'll fix them in v2.

-- 
Regards,

Laurent Pinchart