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

[Jakob Bornecrantz <wallbraker@gmail.com>]

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.