* [PATCH 0/2] Documentation improvements
@ 2013-06-22 13:00 Laurent Pinchart
2013-06-22 13:00 ` [PATCH 1/2] drm/doc: Remove outdated note about i915 driver not behaving properly Laurent Pinchart
` (2 more replies)
0 siblings, 3 replies; 6+ messages in thread
From: Laurent Pinchart @ 2013-06-22 13:00 UTC (permalink / raw)
To: dri-devel
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
^ permalink raw reply [flat|nested] 6+ messages in thread* [PATCH 1/2] drm/doc: Remove outdated note about i915 driver not behaving properly 2013-06-22 13:00 [PATCH 0/2] Documentation improvements Laurent Pinchart @ 2013-06-22 13:00 ` Laurent Pinchart 2013-06-22 13:00 ` [PATCH 2/2] drm/doc: Document the KMS property API Laurent Pinchart 2013-06-22 13:16 ` [PATCH 0/2] Documentation improvements Alex Deucher 2 siblings, 0 replies; 6+ messages in thread From: Laurent Pinchart @ 2013-06-22 13:00 UTC (permalink / raw) To: dri-devel 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->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 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 2/2] drm/doc: Document the KMS property API 2013-06-22 13:00 [PATCH 0/2] Documentation improvements Laurent Pinchart 2013-06-22 13:00 ` [PATCH 1/2] drm/doc: Remove outdated note about i915 driver not behaving properly Laurent Pinchart @ 2013-06-22 13:00 ` Laurent Pinchart 2013-06-22 13:32 ` Hans Verkuil 2013-06-22 13:16 ` [PATCH 0/2] Documentation improvements Alex Deucher 2 siblings, 1 reply; 6+ messages in thread From: Laurent Pinchart @ 2013-06-22 13:00 UTC (permalink / raw) To: dri-devel 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 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 2/2] drm/doc: Document the KMS property API 2013-06-22 13:00 ` [PATCH 2/2] drm/doc: Document the KMS property API Laurent Pinchart @ 2013-06-22 13:32 ` Hans Verkuil 2013-06-22 14:10 ` Laurent Pinchart 0 siblings, 1 reply; 6+ messages in thread From: Hans Verkuil @ 2013-06-22 13:32 UTC (permalink / raw) To: dri-devel; +Cc: Laurent Pinchart 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 2/2] drm/doc: Document the KMS property API 2013-06-22 13:32 ` Hans Verkuil @ 2013-06-22 14:10 ` Laurent Pinchart 0 siblings, 0 replies; 6+ messages in thread From: Laurent Pinchart @ 2013-06-22 14:10 UTC (permalink / raw) To: Hans Verkuil; +Cc: Laurent Pinchart, dri-devel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 0/2] Documentation improvements 2013-06-22 13:00 [PATCH 0/2] Documentation improvements Laurent Pinchart 2013-06-22 13:00 ` [PATCH 1/2] drm/doc: Remove outdated note about i915 driver not behaving properly Laurent Pinchart 2013-06-22 13:00 ` [PATCH 2/2] drm/doc: Document the KMS property API Laurent Pinchart @ 2013-06-22 13:16 ` Alex Deucher 2 siblings, 0 replies; 6+ messages in thread From: Alex Deucher @ 2013-06-22 13:16 UTC (permalink / raw) To: Laurent Pinchart; +Cc: dri-devel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2013-06-22 14:10 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2013-06-22 13:00 [PATCH 0/2] Documentation improvements Laurent Pinchart 2013-06-22 13:00 ` [PATCH 1/2] drm/doc: Remove outdated note about i915 driver not behaving properly Laurent Pinchart 2013-06-22 13:00 ` [PATCH 2/2] drm/doc: Document the KMS property API Laurent Pinchart 2013-06-22 13:32 ` Hans Verkuil 2013-06-22 14:10 ` Laurent Pinchart 2013-06-22 13:16 ` [PATCH 0/2] Documentation improvements Alex Deucher
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).