[PATCH 1/4] drm/doc: Helpers are not a Midlayer!

[PATCH 1/4] drm/doc: Helpers are not a Midlayer!

[Daniel Vetter]

I'm devoting all my wrath to that fight, so don't misname it ;-)

v2: Make it clear that this section talks about kms helpers.

Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 Documentation/DocBook/drm.tmpl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index b030052..270bc12 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -1621,10 +1621,10 @@ void intel_crt_init(struct drm_device *dev)
     </sect2>
   </sect1>
 
-  <!-- Internals: mid-layer helper functions -->
+  <!-- Internals: kms helper functions -->
 
   <sect1>
-    <title>Mid-layer Helper Functions</title>
+    <title>Mode Setting Helper Functions</title>
     <para>
       The CRTC, encoder and connector functions provided by the drivers
       implement the DRM API. They're called by the DRM core and ioctl handlers
-- 
1.7.11.7

[PATCH 2/4] drm/doc: integrate crtc helper api into docbook

[Daniel Vetter]

- Add the missing doc for drm_helper_move_panel_connectors_to_head.
- Fixup any outdated stuff in existing sections. I've only looked at
  those kerneldoc headers that actually resulted in a complaint from
  the kerneldoc parser tool.

v2:
- Actually include the docbook snippet in the right patch.
- Fix spelling fail.

v3: It's now called drm_crtc_helper_set_mode, spotted by Laurent
Pinchart.

Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 Documentation/DocBook/drm.tmpl    |  4 +++
 drivers/gpu/drm/drm_crtc_helper.c | 66 +++++++++++++++++++++++++--------------
 2 files changed, 46 insertions(+), 24 deletions(-)

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 270bc12..c2b31b9 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -2106,6 +2106,10 @@ void intel_crt_init(struct drm_device *dev)
         </listitem>
       </itemizedlist>
     </sect2>
+    <sect2>
+      <title>Modeset Helper Functions Reference</title>
+!Edrivers/gpu/drm/drm_crtc_helper.c
+    </sect2>
   </sect1>
 
   <!-- Internals: vertical blanking -->
diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c
index 7105168..2a7a886 100644
--- a/drivers/gpu/drm/drm_crtc_helper.c
+++ b/drivers/gpu/drm/drm_crtc_helper.c
@@ -39,6 +39,17 @@
 #include <drm/drm_fb_helper.h>
 #include <drm/drm_edid.h>
 
+/**
+ * drm_helper_move_panel_connectors_to_head() - move panels to the front in the
+ * 						connector list
+ * @dev: drm device to operate on
+ *
+ * Some userspace presumes that the first connected connector is the main
+ * display, where it's supposed to display e.g. the login screen. For
+ * laptops, this should be the main panel. Use this function to sort all
+ * (eDP/LVDS) panels to the front of the connector list, instead of
+ * painstakingly trying to initialize them in the right order.
+ */
 void drm_helper_move_panel_connectors_to_head(struct drm_device *dev)
 {
 	struct drm_connector *connector, *tmp;
@@ -82,22 +93,21 @@ static void drm_mode_validate_flag(struct drm_connector *connector,
 
 /**
  * drm_helper_probe_single_connector_modes - get complete set of display modes
- * @dev: DRM device
+ * @connector: connector to probe
  * @maxX: max width for modes
  * @maxY: max height for modes
  *
  * LOCKING:
  * Caller must hold mode config lock.
  *
- * Based on @dev's mode_config layout, scan all the connectors and try to detect
- * modes on them.  Modes will first be added to the connector's probed_modes
- * list, then culled (based on validity and the @maxX, @maxY parameters) and
- * put into the normal modes list.
- *
- * Intended to be used either at bootup time or when major configuration
- * changes have occurred.
+ * Based on the helper callbacks implemented by @connector try to detect all
+ * valid modes.  Modes will first be added to the connector's probed_modes list,
+ * then culled (based on validity and the @maxX, @maxY parameters) and put into
+ * the normal modes list.
  *
- * FIXME: take into account monitor limits
+ * Intended to be use as a generic implementation of the ->probe() @connector
+ * callback for drivers that use the crtc helpers for output mode filtering and
+ * detection.
  *
  * RETURNS:
  * Number of modes found on @connector.
@@ -343,17 +353,24 @@ drm_crtc_prepare_encoders(struct drm_device *dev)
 }
 
 /**
- * drm_crtc_set_mode - set a mode
+ * drm_crtc_helper_set_mode - internal helper to set a mode
  * @crtc: CRTC to program
  * @mode: mode to use
  * @x: width of mode
  * @y: height of mode
+ * @old_fb: old framebuffer, for cleanup
  *
  * LOCKING:
  * Caller must hold mode config lock.
  *
  * Try to set @mode on @crtc.  Give @crtc and its associated connectors a chance
- * to fixup or reject the mode prior to trying to set it.
+ * to fixup or reject the mode prior to trying to set it. This is an internal
+ * helper that drivers could e.g. use to update properties that require the
+ * entire output pipe to be disabled and re-enabled in a new configuration. For
+ * example for changing whether audio is enabled on a hdmi link or for changing
+ * panel fitter or dither attributes. It is also called by the
+ * drm_crtc_helper_set_config() helper function to drive the mode setting
+ * sequence.
  *
  * RETURNS:
  * True if the mode was set successfully, or false otherwise.
@@ -509,20 +526,19 @@ drm_crtc_helper_disable(struct drm_crtc *crtc)
 
 /**
  * drm_crtc_helper_set_config - set a new config from userspace
- * @crtc: CRTC to setup
- * @crtc_info: user provided configuration
- * @new_mode: new mode to set
- * @connector_set: set of connectors for the new config
- * @fb: new framebuffer
+ * @set: mode set configuration
  *
  * LOCKING:
  * Caller must hold mode config lock.
  *
- * Setup a new configuration, provided by the user in @crtc_info, and enable
- * it.
+ * Setup a new configuration, provided by the upper layers (either an ioctl call
+ * from userspace or internally e.g. from the fbdev suppport code) in @set, and
+ * enable it. This is the main helper functions for drivers that implement
+ * kernel mode setting with the crtc helper functions and the assorted
+ * ->prepare(), ->modeset() and ->commit() helper callbacks.
  *
  * RETURNS:
- * Zero. (FIXME)
+ * Returns 0 on success, -ERRNO on failure.
  */
 int drm_crtc_helper_set_config(struct drm_mode_set *set)
 {
@@ -818,12 +834,14 @@ static int drm_helper_choose_crtc_dpms(struct drm_crtc *crtc)
 }
 
 /**
- * drm_helper_connector_dpms
- * @connector affected connector
- * @mode DPMS mode
+ * drm_helper_connector_dpms() - connector dpms helper implementation
+ * @connector: affected connector
+ * @mode: DPMS mode
  *
- * Calls the low-level connector DPMS function, then
- * calls appropriate encoder and crtc DPMS functions as well
+ * This is the main helper function provided by the crtc helper framework for
+ * implementing the DPMS connector attribute. It computes the new desired DPMS
+ * state for all encoders and crtcs in the output mesh and calls the ->dpms()
+ * callback provided by the driver appropriately.
  */
 void drm_helper_connector_dpms(struct drm_connector *connector, int mode)
 {
-- 
1.7.11.7

[PATCH 3/4] drm/doc: integrate fb helper reference into docs

[Daniel Vetter]

Again only minimal changes to make kerneldoc no longer shout. Plus a
little introduction in the form of a inline DOC: section to quickly
explain what this is all about.

v2: Fixup spelling fail.

Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 Documentation/DocBook/drm.tmpl  |  5 +++++
 drivers/gpu/drm/drm_fb_helper.c | 19 ++++++++++++++-----
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index c2b31b9..fadc48b 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -2110,6 +2110,11 @@ void intel_crt_init(struct drm_device *dev)
       <title>Modeset Helper Functions Reference</title>
 !Edrivers/gpu/drm/drm_crtc_helper.c
     </sect2>
+    <sect2>
+      <title>fbdev Helper Functions Reference</title>
+!Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers
+!Edrivers/gpu/drm/drm_fb_helper.c
+    </sect2>
   </sect1>
 
   <!-- Internals: vertical blanking -->
diff --git a/drivers/gpu/drm/drm_fb_helper.c b/drivers/gpu/drm/drm_fb_helper.c
index 4d58d7e..320dcbc 100644
--- a/drivers/gpu/drm/drm_fb_helper.c
+++ b/drivers/gpu/drm/drm_fb_helper.c
@@ -41,7 +41,14 @@ MODULE_AUTHOR("David Airlie, Jesse Barnes");
 MODULE_DESCRIPTION("DRM KMS helper");
 MODULE_LICENSE("GPL and additional rights");
 
-static LIST_HEAD(kernel_fb_helper_list);
+/**
+ * DOC: fbdev helpers
+ *
+ * The fb helper functions are useful to provide an fbdev on top of a drm kernel
+ * mode setting driver. They can be used mostly independantely from the crtc
+ * helper functions used by many drivers to implement the kernel mode setting
+ * interfaces.
+ */
 
 /* simple single crtc case helper function */
 int drm_fb_helper_single_add_all_connectors(struct drm_fb_helper *fb_helper)
@@ -1291,12 +1298,14 @@ static void drm_setup_crtcs(struct drm_fb_helper *fb_helper)
 
 /**
  * drm_helper_initial_config - setup a sane initial connector configuration
- * @dev: DRM device
+ * @fb_helper: fb_helper device struct
+ * @bpp_sel: bpp value to use for the framebuffer configuration
  *
  * LOCKING:
- * Called at init time, must take mode config lock.
+ * Called at init time by the driver to set up the @fb_helper initial
+ * configuration, must take the mode config lock.
  *
- * Scan the CRTCs and connectors and try to put together an initial setup.
+ * Scans the CRTCs and connectors and tries to put together an initial setup.
  * At the moment, this is a cloned configuration across all heads with
  * a new framebuffer object as the backing store.
  *
@@ -1330,7 +1339,7 @@ EXPORT_SYMBOL(drm_fb_helper_initial_config);
 
 /**
  * drm_fb_helper_hotplug_event - respond to a hotplug notification by
- *                               probing all the outputs attached to the fb.
+ *                               probing all the outputs attached to the fb
  * @fb_helper: the drm_fb_helper
  *
  * LOCKING:
-- 
1.7.11.7

[PATCH 4/4] drm/doc: add new dp helpers into drm DocBook

[Daniel Vetter]

I didn't bother with documenting the really trivial new "extract
something from dpcd" helpers, but the i2c over aux ch is now
documented a bit.

v2: Clarify the comment for i2c_dp_aux_add_bus a bit.

v3: Fix more spelling fail spotted by Laurent Pinchart.

Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 Documentation/DocBook/drm.tmpl  |  6 ++++++
 drivers/gpu/drm/drm_dp_helper.c | 21 +++++++++++++++++++++
 include/drm/drm_dp_helper.h     |  8 ++++++++
 3 files changed, 35 insertions(+)

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index fadc48b..6948bad 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -2115,6 +2115,12 @@ void intel_crt_init(struct drm_device *dev)
 !Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers
 !Edrivers/gpu/drm/drm_fb_helper.c
     </sect2>
+    <sect2>
+      <title>Display Port Helper Functions Reference</title>
+!Pdrivers/gpu/drm/drm_dp_helper.c dp helpers
+!Iinclude/drm/drm_dp_helper.h
+!Edrivers/gpu/drm/drm_dp_helper.c
+    </sect2>
   </sect1>
 
   <!-- Internals: vertical blanking -->
diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index 3c4cccd..89e1966 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -30,6 +30,15 @@
 #include <drm/drm_dp_helper.h>
 #include <drm/drmP.h>
 
+/**
+ * DOC: dp helpers
+ *
+ * These functions contain some common logic and helpers at various abstraction
+ * levels to deal with Display Port sink devices and related things like DP aux
+ * channel transfers, EDID reading over DP aux channels, decoding certain DPCD
+ * blocks, ...
+ */
+
 /* Run a single AUX_CH I2C transaction, writing/reading data as necessary */
 static int
 i2c_algo_dp_aux_transaction(struct i2c_adapter *adapter, int mode,
@@ -193,6 +202,18 @@ i2c_dp_aux_prepare_bus(struct i2c_adapter *adapter)
 	return 0;
 }
 
+/**
+ * i2c_dp_aux_add_bus() - register an i2c adapter using the aux ch helper
+ * @adapter: i2c adapter to register
+ *
+ * This registers an i2c adapater that uses dp aux channel as it's underlaying
+ * transport. The driver needs to fill out the &i2c_algo_dp_aux_data structure
+ * and store it in the algo_data member of the @adapter argument. This will be
+ * used by the i2c over dp aux algorithm to drive the hardware.
+ *
+ * RETURNS:
+ * 0 on success, -ERRNO on failure.
+ */
 int
 i2c_dp_aux_add_bus(struct i2c_adapter *adapter)
 {
diff --git a/include/drm/drm_dp_helper.h b/include/drm/drm_dp_helper.h
index c09d367..e8e1417 100644
--- a/include/drm/drm_dp_helper.h
+++ b/include/drm/drm_dp_helper.h
@@ -312,6 +312,14 @@
 #define MODE_I2C_READ	4
 #define MODE_I2C_STOP	8
 
+/**
+ * struct i2c_algo_dp_aux_data - driver interface structure for i2c over dp
+ * 				 aux algorithm
+ * @running: set by the algo indicating whether an i2c is ongoing or whether
+ * 	     the i2c bus is quiescent
+ * @address: i2c target address for the currently ongoing transfer
+ * @aux_ch: driver callback to transfer a single byte of the i2c payload
+ */
 struct i2c_algo_dp_aux_data {
 	bool running;
 	u16 address;
-- 
1.7.11.7

Re: [PATCH 2/4] drm/doc: integrate crtc helper api into docbook

[Jakob Bornecrantz]

On Thu, Nov 1, 2012 at 2:45 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> - Add the missing doc for drm_helper_move_panel_connectors_to_head.
> - Fixup any outdated stuff in existing sections. I've only looked at
>   those kerneldoc headers that actually resulted in a complaint from
>   the kerneldoc parser tool.
>
> v2:
> - Actually include the docbook snippet in the right patch.
> - Fix spelling fail.
>
> v3: It's now called drm_crtc_helper_set_mode, spotted by Laurent
> Pinchart.
>
> Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> ---
>  Documentation/DocBook/drm.tmpl    |  4 +++
>  drivers/gpu/drm/drm_crtc_helper.c | 66 +++++++++++++++++++++++++--------------
>  2 files changed, 46 insertions(+), 24 deletions(-)
>
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 270bc12..c2b31b9 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -2106,6 +2106,10 @@ void intel_crt_init(struct drm_device *dev)
>          </listitem>
>        </itemizedlist>
>      </sect2>
> +    <sect2>
> +      <title>Modeset Helper Functions Reference</title>
> +!Edrivers/gpu/drm/drm_crtc_helper.c
> +    </sect2>
>    </sect1>
>
>    <!-- Internals: vertical blanking -->
> diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c
> index 7105168..2a7a886 100644
> --- a/drivers/gpu/drm/drm_crtc_helper.c
> +++ b/drivers/gpu/drm/drm_crtc_helper.c
> @@ -39,6 +39,17 @@
>  #include <drm/drm_fb_helper.h>
>  #include <drm/drm_edid.h>
>
> +/**
> + * drm_helper_move_panel_connectors_to_head() - move panels to the front in the
> + *                                             connector list
> + * @dev: drm device to operate on
> + *
> + * Some userspace presumes that the first connected connector is the main
> + * display, where it's supposed to display e.g. the login screen. For
> + * laptops, this should be the main panel. Use this function to sort all
> + * (eDP/LVDS) panels to the front of the connector list, instead of
> + * painstakingly trying to initialize them in the right order.
> + */
>  void drm_helper_move_panel_connectors_to_head(struct drm_device *dev)
>  {
>         struct drm_connector *connector, *tmp;
> @@ -82,22 +93,21 @@ static void drm_mode_validate_flag(struct drm_connector *connector,
>
>  /**
>   * drm_helper_probe_single_connector_modes - get complete set of display modes
> - * @dev: DRM device
> + * @connector: connector to probe
>   * @maxX: max width for modes
>   * @maxY: max height for modes
>   *
>   * LOCKING:
>   * Caller must hold mode config lock.
>   *
> - * Based on @dev's mode_config layout, scan all the connectors and try to detect
> - * modes on them.  Modes will first be added to the connector's probed_modes
> - * list, then culled (based on validity and the @maxX, @maxY parameters) and
> - * put into the normal modes list.
> - *
> - * Intended to be used either at bootup time or when major configuration
> - * changes have occurred.
> + * Based on the helper callbacks implemented by @connector try to detect all
> + * valid modes.  Modes will first be added to the connector's probed_modes list,
> + * then culled (based on validity and the @maxX, @maxY parameters) and put into
> + * the normal modes list.
>   *
> - * FIXME: take into account monitor limits

Should this really be removed? I'm guess it has been fixed or is not
really needed anymore but just making sure it shouldn't live somewhere
else.

Cheers, Jakob.

Re: [PATCH 2/4] drm/doc: integrate crtc helper api into docbook

[Chris Wilson]

On Thu, 1 Nov 2012 15:49:16 +0100, Jakob Bornecrantz <wallbraker@gmail.com> wrote:
> On Thu, Nov 1, 2012 at 2:45 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> > - Add the missing doc for drm_helper_move_panel_connectors_to_head.
> > - Fixup any outdated stuff in existing sections. I've only looked at
> >   those kerneldoc headers that actually resulted in a complaint from
> >   the kerneldoc parser tool.
> >
> > v2:
> > - Actually include the docbook snippet in the right patch.
> > - Fix spelling fail.
> >
> > v3: It's now called drm_crtc_helper_set_mode, spotted by Laurent
> > Pinchart.
> >
> > Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > ---
> >  Documentation/DocBook/drm.tmpl    |  4 +++
> >  drivers/gpu/drm/drm_crtc_helper.c | 66 +++++++++++++++++++++++++--------------
> >  2 files changed, 46 insertions(+), 24 deletions(-)
> >
> > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> > index 270bc12..c2b31b9 100644
> > --- a/Documentation/DocBook/drm.tmpl
> > +++ b/Documentation/DocBook/drm.tmpl
> > @@ -2106,6 +2106,10 @@ void intel_crt_init(struct drm_device *dev)
> >          </listitem>
> >        </itemizedlist>
> >      </sect2>
> > +    <sect2>
> > +      <title>Modeset Helper Functions Reference</title>
> > +!Edrivers/gpu/drm/drm_crtc_helper.c
> > +    </sect2>
> >    </sect1>
> >
> >    <!-- Internals: vertical blanking -->
> > diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c
> > index 7105168..2a7a886 100644
> > --- a/drivers/gpu/drm/drm_crtc_helper.c
> > +++ b/drivers/gpu/drm/drm_crtc_helper.c
> > @@ -39,6 +39,17 @@
> >  #include <drm/drm_fb_helper.h>
> >  #include <drm/drm_edid.h>
> >
> > +/**
> > + * drm_helper_move_panel_connectors_to_head() - move panels to the front in the
> > + *                                             connector list
> > + * @dev: drm device to operate on
> > + *
> > + * Some userspace presumes that the first connected connector is the main
> > + * display, where it's supposed to display e.g. the login screen. For
> > + * laptops, this should be the main panel. Use this function to sort all
> > + * (eDP/LVDS) panels to the front of the connector list, instead of
> > + * painstakingly trying to initialize them in the right order.
> > + */
> >  void drm_helper_move_panel_connectors_to_head(struct drm_device *dev)
> >  {
> >         struct drm_connector *connector, *tmp;
> > @@ -82,22 +93,21 @@ static void drm_mode_validate_flag(struct drm_connector *connector,
> >
> >  /**
> >   * drm_helper_probe_single_connector_modes - get complete set of display modes
> > - * @dev: DRM device
> > + * @connector: connector to probe
> >   * @maxX: max width for modes
> >   * @maxY: max height for modes
> >   *
> >   * LOCKING:
> >   * Caller must hold mode config lock.
> >   *
> > - * Based on @dev's mode_config layout, scan all the connectors and try to detect
> > - * modes on them.  Modes will first be added to the connector's probed_modes
> > - * list, then culled (based on validity and the @maxX, @maxY parameters) and
> > - * put into the normal modes list.
> > - *
> > - * Intended to be used either at bootup time or when major configuration
> > - * changes have occurred.
> > + * Based on the helper callbacks implemented by @connector try to detect all
> > + * valid modes.  Modes will first be added to the connector's probed_modes list,
> > + * then culled (based on validity and the @maxX, @maxY parameters) and put into
> > + * the normal modes list.
> >   *
> > - * FIXME: take into account monitor limits
> 
> Should this really be removed? I'm guess it has been fixed or is not
> really needed anymore but just making sure it shouldn't live somewhere
> else.

Yes, the modes from an EDID are validated against the limits given by the
EDID, which is as much information as we have. Higher levels can filter
the modes based on alternate sources, ofc.

Granted removing a FIXME should be a separate commit giving good reason
why it can be considered fixed. (i.e. treat it like the bug it warns
about of its own right.)
-Chris

-- 
Chris Wilson, Intel Open Source Technology Centre

Re: [PATCH 2/4] drm/doc: integrate crtc helper api into docbook

[Daniel Vetter]

On Thu, Nov 01, 2012 at 03:06:44PM +0000, Chris Wilson wrote:
> On Thu, 1 Nov 2012 15:49:16 +0100, Jakob Bornecrantz <wallbraker@gmail.com> wrote:
> > On Thu, Nov 1, 2012 at 2:45 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> > > - Add the missing doc for drm_helper_move_panel_connectors_to_head.
> > > - Fixup any outdated stuff in existing sections. I've only looked at
> > >   those kerneldoc headers that actually resulted in a complaint from
> > >   the kerneldoc parser tool.
> > >
> > > v2:
> > > - Actually include the docbook snippet in the right patch.
> > > - Fix spelling fail.
> > >
> > > v3: It's now called drm_crtc_helper_set_mode, spotted by Laurent
> > > Pinchart.
> > >
> > > Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > > ---
> > >  Documentation/DocBook/drm.tmpl    |  4 +++
> > >  drivers/gpu/drm/drm_crtc_helper.c | 66 +++++++++++++++++++++++++--------------
> > >  2 files changed, 46 insertions(+), 24 deletions(-)
> > >
> > > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> > > index 270bc12..c2b31b9 100644
> > > --- a/Documentation/DocBook/drm.tmpl
> > > +++ b/Documentation/DocBook/drm.tmpl
> > > @@ -2106,6 +2106,10 @@ void intel_crt_init(struct drm_device *dev)
> > >          </listitem>
> > >        </itemizedlist>
> > >      </sect2>
> > > +    <sect2>
> > > +      <title>Modeset Helper Functions Reference</title>
> > > +!Edrivers/gpu/drm/drm_crtc_helper.c
> > > +    </sect2>
> > >    </sect1>
> > >
> > >    <!-- Internals: vertical blanking -->
> > > diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c
> > > index 7105168..2a7a886 100644
> > > --- a/drivers/gpu/drm/drm_crtc_helper.c
> > > +++ b/drivers/gpu/drm/drm_crtc_helper.c
> > > @@ -39,6 +39,17 @@
> > >  #include <drm/drm_fb_helper.h>
> > >  #include <drm/drm_edid.h>
> > >
> > > +/**
> > > + * drm_helper_move_panel_connectors_to_head() - move panels to the front in the
> > > + *                                             connector list
> > > + * @dev: drm device to operate on
> > > + *
> > > + * Some userspace presumes that the first connected connector is the main
> > > + * display, where it's supposed to display e.g. the login screen. For
> > > + * laptops, this should be the main panel. Use this function to sort all
> > > + * (eDP/LVDS) panels to the front of the connector list, instead of
> > > + * painstakingly trying to initialize them in the right order.
> > > + */
> > >  void drm_helper_move_panel_connectors_to_head(struct drm_device *dev)
> > >  {
> > >         struct drm_connector *connector, *tmp;
> > > @@ -82,22 +93,21 @@ static void drm_mode_validate_flag(struct drm_connector *connector,
> > >
> > >  /**
> > >   * drm_helper_probe_single_connector_modes - get complete set of display modes
> > > - * @dev: DRM device
> > > + * @connector: connector to probe
> > >   * @maxX: max width for modes
> > >   * @maxY: max height for modes
> > >   *
> > >   * LOCKING:
> > >   * Caller must hold mode config lock.
> > >   *
> > > - * Based on @dev's mode_config layout, scan all the connectors and try to detect
> > > - * modes on them.  Modes will first be added to the connector's probed_modes
> > > - * list, then culled (based on validity and the @maxX, @maxY parameters) and
> > > - * put into the normal modes list.
> > > - *
> > > - * Intended to be used either at bootup time or when major configuration
> > > - * changes have occurred.
> > > + * Based on the helper callbacks implemented by @connector try to detect all
> > > + * valid modes.  Modes will first be added to the connector's probed_modes list,
> > > + * then culled (based on validity and the @maxX, @maxY parameters) and put into
> > > + * the normal modes list.
> > >   *
> > > - * FIXME: take into account monitor limits
> > 
> > Should this really be removed? I'm guess it has been fixed or is not
> > really needed anymore but just making sure it shouldn't live somewhere
> > else.
> 
> Yes, the modes from an EDID are validated against the limits given by the
> EDID, which is as much information as we have. Higher levels can filter
> the modes based on alternate sources, ofc.
> 
> Granted removing a FIXME should be a separate commit giving good reason
> why it can be considered fixed. (i.e. treat it like the bug it warns
> about of its own right.)

We now call down into the connectors ->mode_valid callback. I've figured
that's about as much checking the helper function here should concern
itself with. Now ofc, most drivers don't bother to trouble themselves with
dotclock limits, but imo that's not a FIXME for the helper code.

And no, adding another common check is imo not the solution, since doing
the full mode checking requires the global configuration anyway ...

I guess I get bad marks for failing to mention that in the commit message
;-)

Cheers, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

Re: [PATCH 3/4] drm/doc: integrate fb helper reference into docs

[Dave Airlie]

On Thu, Nov 1, 2012 at 11:45 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> Again only minimal changes to make kerneldoc no longer shout. Plus a
> little introduction in the form of a inline DOC: section to quickly
> explain what this is all about.

Did someone build these?

> diff --git a/drivers/gpu/drm/drm_fb_helper.c b/drivers/gpu/drm/drm_fb_helper.c
> index 4d58d7e..320dcbc 100644
> --- a/drivers/gpu/drm/drm_fb_helper.c
> +++ b/drivers/gpu/drm/drm_fb_helper.c
> @@ -41,7 +41,14 @@ MODULE_AUTHOR("David Airlie, Jesse Barnes");
>  MODULE_DESCRIPTION("DRM KMS helper");
>  MODULE_LICENSE("GPL and additional rights");
>
> -static LIST_HEAD(kernel_fb_helper_list);

because that one liner seriously harshes my buzz.

Do better next time!

Dave.

Re: [PATCH 2/4] drm/doc: integrate crtc helper api into docbook

[Laurent Pinchart]

Hi Daniel,

Thanks for the patch.

(text reflowed for review purpose to fit the e-mail line length limit)

On Wednesday 31 October 2012 10:11:48 Daniel Vetter wrote:
> - Add the missing doc for drm_helper_move_panel_connectors_to_head.
> - Fixup any outdated stuff in existing sections. I've only looked at
>   those kerneldoc headers that actually resulted in a complaint from
>   the kerneldoc parser tool.
> 
> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

After fixing the small mistake below,

Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

> ---
>  Documentation/DocBook/drm.tmpl    |  4 +++
>  drivers/gpu/drm/drm_crtc_helper.c | 54 ++++++++++++++++++++----------------
>  2 files changed, 34 insertions(+), 24 deletions(-)
> 
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index ca45155..43e706e 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -2106,6 +2106,10 @@ void intel_crt_init(struct drm_device *dev)
>          </listitem>
>        </itemizedlist>
>      </sect2>
> +    <sect2>
> +      <title>Modeset Helper Functions Reference</title>
> +!Edrivers/gpu/drm/drm_crtc_helper.c
> +    </sect2>
>    </sect1>
> 
>    <!-- Internals: vertical blanking -->
> diff --git a/drivers/gpu/drm/drm_crtc_helper.c
> b/drivers/gpu/drm/drm_crtc_helper.c index 1021f505..e2e19ef 100644
> --- a/drivers/gpu/drm/drm_crtc_helper.c
> +++ b/drivers/gpu/drm/drm_crtc_helper.c
> @@ -92,22 +92,21 @@ static void drm_mode_validate_flag(struct drm_connector
> *connector,
> 
>  /**
>   * drm_helper_probe_single_connector_modes - get complete set of display
>   * modes
> - * @dev: DRM device
> + * @connector: connector to probe
>   * @maxX: max width for modes
>   * @maxY: max height for modes
>   *
>   * LOCKING:
>   * Caller must hold mode config lock.
>   *
> - * Based on @dev's mode_config layout, scan all the connectors and try to
> - * detect modes on them.  Modes will first be added to the connector's
> - * probed_modes list, then culled (based on validity and the @maxX, @maxY
> - * parameters) and put into the normal modes list.
> - *
> - * Intended to be used either at bootup time or when major configuration
> - * changes have occurred.
> + * Based on the helper callbacks implemented by @connector try to detect
> + * all valid modes.  Modes will first be added to the connector's
> + * probed_modes list, then culled (based on validity and the @maxX, @maxY
> + * parameters) and put into the normal modes list.
>   *
> - * FIXME: take into account monitor limits
> + * Intended to be use as a generic implementation of the ->probe()
> + * @connector callback for drivers that use the crtc helpers for output
> + * mode filtering and conector detection.
>   *
>   * RETURNS:
>   * Number of modes found on @connector.
> @@ -353,17 +352,23 @@ drm_crtc_prepare_encoders(struct drm_device *dev)
>  }
> 
>  /**
> - * drm_crtc_set_mode - set a mode
> + * drm_crtc_set_mode - internal helper to set a mode

The function is actually now called drm_crtc_helper_set_mode.

>   * @crtc: CRTC to program
>   * @mode: mode to use
>   * @x: width of mode
>   * @y: height of mode
> + * @old_fb: old framebuffer, for cleanup
>   *
>   * LOCKING:
>   * Caller must hold mode config lock.
>   *
>   * Try to set @mode on @crtc.  Give @crtc and its associated connectors a
> - * chance to fixup or reject the mode prior to trying to set it.
> + * chance to fixup or reject the mode prior to trying to set it. This is an
> + * internal helper that drivers could e.g. use to update properties that
> + * require the entire output pipe to be disabled and re-enabled in a new
> + * configuration. For example for changing whether audio is enabled on a
> + * hdmi link or for changing panel fitter or dither attributes. It is also
> + * called by the drm_crtc_helper_set_config() helper function.
>   *
>   * RETURNS:
>   * True if the mode was set successfully, or false otherwise.
> @@ -519,20 +524,19 @@ drm_crtc_helper_disable(struct drm_crtc *crtc)
> 
>  /**
>   * drm_crtc_helper_set_config - set a new config from userspace
> - * @crtc: CRTC to setup
> - * @crtc_info: user provided configuration
> - * @new_mode: new mode to set
> - * @connector_set: set of connectors for the new config
> - * @fb: new framebuffer
> + * @set: mode set configuration
>   *
>   * LOCKING:
>   * Caller must hold mode config lock.
>   *
> - * Setup a new configuration, provided by the user in @crtc_info, and
> - * enable it.
> + * Setup a new configuration, provided by the upper layers (either an ioctl
> + * call from userspace or internally e.g. from the fbdev suppport code) in
> + * @set, and enable it. This is the main helper functions for drivers that
> + * implement kernel mode setting with the crtc helper functions and the
> + * assorted ->prepare(), ->modeset() and ->commit() interfaces.
>   *
>   * RETURNS:
> - * Zero. (FIXME)
> + * Returns 0 on success, -ERRNO on failure.
>   */
>  int drm_crtc_helper_set_config(struct drm_mode_set *set)
>  {
> @@ -828,12 +832,14 @@ static int drm_helper_choose_crtc_dpms(struct drm_crtc
> *crtc) }
> 
>  /**
> - * drm_helper_connector_dpms
> - * @connector affected connector
> - * @mode DPMS mode
> + * drm_helper_connector_dpms() - connector dpms helper implementation
> + * @connector: affected connector
> + * @mode: DPMS mode
>   *
> - * Calls the low-level connector DPMS function, then
> - * calls appropriate encoder and crtc DPMS functions as well
> + * This is the main helper function provided by the crtc helper framework
> + * for implementing the DPMS connector attribute. It computes the new
> + * desired DPMS state for all encoders and crtcs in the output mesh and
> + * calls the ->dpsm() callback provided by the driver appropriately.
>   */
>  void drm_helper_connector_dpms(struct drm_connector *connector, int mode)
>  {
-- 
Regards,

Laurent Pinchart

[PATCH 2/4] drm/doc: integrate crtc helper api into docbook

[Daniel Vetter]

- Add the missing doc for drm_helper_move_panel_connectors_to_head.
- Fixup any outdated stuff in existing sections. I've only looked at
  those kerneldoc headers that actually resulted in a complaint from
  the kerneldoc parser tool.

Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
 Documentation/DocBook/drm.tmpl    |  4 +++
 drivers/gpu/drm/drm_crtc_helper.c | 54 ++++++++++++++++++++++-----------------
 2 files changed, 34 insertions(+), 24 deletions(-)

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index ca45155..43e706e 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -2106,6 +2106,10 @@ void intel_crt_init(struct drm_device *dev)
         </listitem>
       </itemizedlist>
     </sect2>
+    <sect2>
+      <title>Modeset Helper Functions Reference</title>
+!Edrivers/gpu/drm/drm_crtc_helper.c
+    </sect2>
   </sect1>
 
   <!-- Internals: vertical blanking -->
diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c
index 1021f505..e2e19ef 100644
--- a/drivers/gpu/drm/drm_crtc_helper.c
+++ b/drivers/gpu/drm/drm_crtc_helper.c
@@ -92,22 +92,21 @@ static void drm_mode_validate_flag(struct drm_connector *connector,
 
 /**
  * drm_helper_probe_single_connector_modes - get complete set of display modes
- * @dev: DRM device
+ * @connector: connector to probe
  * @maxX: max width for modes
  * @maxY: max height for modes
  *
  * LOCKING:
  * Caller must hold mode config lock.
  *
- * Based on @dev's mode_config layout, scan all the connectors and try to detect
- * modes on them.  Modes will first be added to the connector's probed_modes
- * list, then culled (based on validity and the @maxX, @maxY parameters) and
- * put into the normal modes list.
- *
- * Intended to be used either at bootup time or when major configuration
- * changes have occurred.
+ * Based on the helper callbacks implemented by @connector try to detect all
+ * valid modes.  Modes will first be added to the connector's probed_modes list,
+ * then culled (based on validity and the @maxX, @maxY parameters) and put into
+ * the normal modes list.
  *
- * FIXME: take into account monitor limits
+ * Intended to be use as a generic implementation of the ->probe() @connector
+ * callback for drivers that use the crtc helpers for output mode filtering and
+ * conector detection.
  *
  * RETURNS:
  * Number of modes found on @connector.
@@ -353,17 +352,23 @@ drm_crtc_prepare_encoders(struct drm_device *dev)
 }
 
 /**
- * drm_crtc_set_mode - set a mode
+ * drm_crtc_set_mode - internal helper to set a mode
  * @crtc: CRTC to program
  * @mode: mode to use
  * @x: width of mode
  * @y: height of mode
+ * @old_fb: old framebuffer, for cleanup
  *
  * LOCKING:
  * Caller must hold mode config lock.
  *
  * Try to set @mode on @crtc.  Give @crtc and its associated connectors a chance
- * to fixup or reject the mode prior to trying to set it.
+ * to fixup or reject the mode prior to trying to set it. This is an internal
+ * helper that drivers could e.g. use to update properties that require the
+ * entire output pipe to be disabled and re-enabled in a new configuration. For
+ * example for changing whether audio is enabled on a hdmi link or for changing
+ * panel fitter or dither attributes. It is also called by the
+ * drm_crtc_helper_set_config() helper function.
  *
  * RETURNS:
  * True if the mode was set successfully, or false otherwise.
@@ -519,20 +524,19 @@ drm_crtc_helper_disable(struct drm_crtc *crtc)
 
 /**
  * drm_crtc_helper_set_config - set a new config from userspace
- * @crtc: CRTC to setup
- * @crtc_info: user provided configuration
- * @new_mode: new mode to set
- * @connector_set: set of connectors for the new config
- * @fb: new framebuffer
+ * @set: mode set configuration
  *
  * LOCKING:
  * Caller must hold mode config lock.
  *
- * Setup a new configuration, provided by the user in @crtc_info, and enable
- * it.
+ * Setup a new configuration, provided by the upper layers (either an ioctl call
+ * from userspace or internally e.g. from the fbdev suppport code) in @set, and
+ * enable it. This is the main helper functions for drivers that implement
+ * kernel mode setting with the crtc helper functions and the assorted
+ * ->prepare(), ->modeset() and ->commit() interfaces.
  *
  * RETURNS:
- * Zero. (FIXME)
+ * Returns 0 on success, -ERRNO on failure.
  */
 int drm_crtc_helper_set_config(struct drm_mode_set *set)
 {
@@ -828,12 +832,14 @@ static int drm_helper_choose_crtc_dpms(struct drm_crtc *crtc)
 }
 
 /**
- * drm_helper_connector_dpms
- * @connector affected connector
- * @mode DPMS mode
+ * drm_helper_connector_dpms() - connector dpms helper implementation
+ * @connector: affected connector
+ * @mode: DPMS mode
  *
- * Calls the low-level connector DPMS function, then
- * calls appropriate encoder and crtc DPMS functions as well
+ * This is the main helper function provided by the crtc helper framework for
+ * implementing the DPMS connector attribute. It computes the new desired DPMS
+ * state for all encoders and crtcs in the output mesh and calls the ->dpsm()
+ * callback provided by the driver appropriately.
  */
 void drm_helper_connector_dpms(struct drm_connector *connector, int mode)
 {
-- 
1.7.11.7