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

Commit Message

Daniel Vetter Oct. 31, 2012, 9:11 a.m. UTC

- 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 <[e-mail]>
---
 Documentation/DocBook/drm.tmpl    |  4 +++
 drivers/gpu/drm/drm_crtc_helper.c | 54 ++++++++++++++++++++++-----------------
 2 files changed, 34 insertions(+), 24 deletions(-)

Comments

Laurent Pinchart Nov. 1, 2012, 11:44 a.m. UTC | #1

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 <[e-mail]>

After fixing the small mistake below,

Acked-by: Laurent Pinchart <[e-mail]>

> ---
>  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)
>  {

Patch

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)
 {