[PATCH] drm/docs: more leftovers from the big vtable documentation pile

Daniel Vetter daniel at ffwll.ch
Tue Jan 5 07:30:38 PST 2016


On Tue, Jan 05, 2016 at 04:22:15PM +0100, Daniel Vetter wrote:
> Another pile of vfuncs from the old gpu.tmpl xml documentation that
> I've forgotten to delete. I spotted a few more things to
> clarify/extend in the new kerneldoc while going through this once
> more.
> 
> v2: Spelling fixes (Thierry).
> 
> v3: More spelling fixes and use Thierry's proposal to clarify why
> drivers need to validate modes both in ->mode_fixup and ->mode_valid.
> 
> Cc: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> Cc: Thierry Reding <treding at nvidia.com>
> Acked-by: Thierry Reding <treding at nvidia.com>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>

... and pulled into drm-misc.
-Daniel

> ---
>  Documentation/DocBook/gpu.tmpl           | 188 -------------------------------
>  include/drm/drm_modeset_helper_vtables.h |  44 +++++++-
>  2 files changed, 41 insertions(+), 191 deletions(-)
> 
> diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
> index 225a246c5f53..faa5e0d4208d 100644
> --- a/Documentation/DocBook/gpu.tmpl
> +++ b/Documentation/DocBook/gpu.tmpl
> @@ -1579,194 +1579,6 @@ void intel_crt_init(struct drm_device *dev)
>        entities.
>      </para>
>      <sect2>
> -      <title>Legacy CRTC Helper Operations</title>
> -      <itemizedlist>
> -        <listitem id="drm-helper-crtc-mode-fixup">
> -          <synopsis>bool (*mode_fixup)(struct drm_crtc *crtc,
> -                       const struct drm_display_mode *mode,
> -                       struct drm_display_mode *adjusted_mode);</synopsis>
> -          <para>
> -            Let CRTCs adjust the requested mode or reject it completely. This
> -            operation returns true if the mode is accepted (possibly after being
> -            adjusted) or false if it is rejected.
> -          </para>
> -          <para>
> -            The <methodname>mode_fixup</methodname> operation should reject the
> -            mode if it can't reasonably use it. The definition of "reasonable"
> -            is currently fuzzy in this context. One possible behaviour would be
> -            to set the adjusted mode to the panel timings when a fixed-mode
> -            panel is used with hardware capable of scaling. Another behaviour
> -            would be to accept any input mode and adjust it to the closest mode
> -            supported by the hardware (FIXME: This needs to be clarified).
> -          </para>
> -        </listitem>
> -        <listitem>
> -          <synopsis>int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
> -                     struct drm_framebuffer *old_fb)</synopsis>
> -          <para>
> -            Move the CRTC on the current frame buffer (stored in
> -            <literal>crtc->fb</literal>) to position (x,y). Any of the frame
> -            buffer, x position or y position may have been modified.
> -          </para>
> -          <para>
> -            This helper operation is optional. If not provided, the
> -            <function>drm_crtc_helper_set_config</function> function will fall
> -            back to the <methodname>mode_set</methodname> helper operation.
> -          </para>
> -          <note><para>
> -            FIXME: Why are x and y passed as arguments, as they can be accessed
> -            through <literal>crtc->x</literal> and
> -            <literal>crtc->y</literal>?
> -          </para></note>
> -        </listitem>
> -        <listitem>
> -          <synopsis>void (*prepare)(struct drm_crtc *crtc);</synopsis>
> -          <para>
> -            Prepare the CRTC for mode setting. This operation is called after
> -            validating the requested mode. Drivers use it to perform
> -            device-specific operations required before setting the new mode.
> -          </para>
> -        </listitem>
> -        <listitem>
> -          <synopsis>int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode,
> -                struct drm_display_mode *adjusted_mode, int x, int y,
> -                struct drm_framebuffer *old_fb);</synopsis>
> -          <para>
> -            Set a new mode, position and frame buffer. Depending on the device
> -            requirements, the mode can be stored internally by the driver and
> -            applied in the <methodname>commit</methodname> operation, or
> -            programmed to the hardware immediately.
> -          </para>
> -          <para>
> -            The <methodname>mode_set</methodname> operation returns 0 on success
> -	    or a negative error code if an error occurs.
> -          </para>
> -        </listitem>
> -        <listitem>
> -          <synopsis>void (*commit)(struct drm_crtc *crtc);</synopsis>
> -          <para>
> -            Commit a mode. This operation is called after setting the new mode.
> -            Upon return the device must use the new mode and be fully
> -            operational.
> -          </para>
> -        </listitem>
> -      </itemizedlist>
> -    </sect2>
> -    <sect2>
> -      <title>Encoder Helper Operations</title>
> -      <itemizedlist>
> -        <listitem>
> -          <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder,
> -                       const struct drm_display_mode *mode,
> -                       struct drm_display_mode *adjusted_mode);</synopsis>
> -          <para>
> -            Let encoders adjust the requested mode or reject it completely. This
> -            operation returns true if the mode is accepted (possibly after being
> -            adjusted) or false if it is rejected. See the
> -            <link linkend="drm-helper-crtc-mode-fixup">mode_fixup CRTC helper
> -            operation</link> for an explanation of the allowed adjustments.
> -          </para>
> -        </listitem>
> -        <listitem>
> -          <synopsis>void (*prepare)(struct drm_encoder *encoder);</synopsis>
> -          <para>
> -            Prepare the encoder for mode setting. This operation is called after
> -            validating the requested mode. Drivers use it to perform
> -            device-specific operations required before setting the new mode.
> -          </para>
> -        </listitem>
> -        <listitem>
> -          <synopsis>void (*mode_set)(struct drm_encoder *encoder,
> -                 struct drm_display_mode *mode,
> -                 struct drm_display_mode *adjusted_mode);</synopsis>
> -          <para>
> -            Set a new mode. Depending on the device requirements, the mode can
> -            be stored internally by the driver and applied in the
> -            <methodname>commit</methodname> operation, or programmed to the
> -            hardware immediately.
> -          </para>
> -        </listitem>
> -        <listitem>
> -          <synopsis>void (*commit)(struct drm_encoder *encoder);</synopsis>
> -          <para>
> -            Commit a mode. This operation is called after setting the new mode.
> -            Upon return the device must use the new mode and be fully
> -            operational.
> -          </para>
> -        </listitem>
> -      </itemizedlist>
> -    </sect2>
> -    <sect2>
> -      <title>Connector Helper Operations</title>
> -      <itemizedlist>
> -        <listitem>
> -          <synopsis>struct drm_encoder *(*best_encoder)(struct drm_connector *connector);</synopsis>
> -          <para>
> -            Return a pointer to the best encoder for the connecter. Device that
> -            map connectors to encoders 1:1 simply return the pointer to the
> -            associated encoder. This operation is mandatory.
> -          </para>
> -        </listitem>
> -        <listitem>
> -          <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis>
> -          <para>
> -            Fill the connector's <structfield>probed_modes</structfield> list
> -            by parsing EDID data with <function>drm_add_edid_modes</function>,
> -            adding standard VESA DMT modes with <function>drm_add_modes_noedid</function>,
> -            or calling <function>drm_mode_probed_add</function> directly for every
> -            supported mode and return the number of modes it has detected. This
> -            operation is mandatory.
> -          </para>
> -          <para>
> -            Note that the caller function will automatically add standard VESA
> -            DMT modes up to 1024x768 if the <methodname>get_modes</methodname>
> -            helper operation returns no mode and if the connector status is
> -            connector_status_connected. There is no need to call
> -            <function>drm_add_edid_modes</function> manually in that case.
> -          </para>
> -          <para>
> -            The <structfield>vrefresh</structfield> value is computed by
> -            <function>drm_helper_probe_single_connector_modes</function>.
> -          </para>
> -          <para>
> -            When parsing EDID data, <function>drm_add_edid_modes</function> fills the
> -            connector <structfield>display_info</structfield>
> -            <structfield>width_mm</structfield> and
> -            <structfield>height_mm</structfield> fields. When creating modes
> -            manually the <methodname>get_modes</methodname> helper operation must
> -            set the <structfield>display_info</structfield>
> -            <structfield>width_mm</structfield> and
> -            <structfield>height_mm</structfield> fields if they haven't been set
> -            already (for instance at initialization time when a fixed-size panel is
> -            attached to the connector). The mode <structfield>width_mm</structfield>
> -            and <structfield>height_mm</structfield> fields are only used internally
> -            during EDID parsing and should not be set when creating modes manually.
> -          </para>
> -        </listitem>
> -        <listitem>
> -          <synopsis>int (*mode_valid)(struct drm_connector *connector,
> -		  struct drm_display_mode *mode);</synopsis>
> -          <para>
> -            Verify whether a mode is valid for the connector. Return MODE_OK for
> -            supported modes and one of the enum drm_mode_status values (MODE_*)
> -            for unsupported modes. This operation is optional.
> -          </para>
> -          <para>
> -            As the mode rejection reason is currently not used beside for
> -            immediately removing the unsupported mode, an implementation can
> -            return MODE_BAD regardless of the exact reason why the mode is not
> -            valid.
> -          </para>
> -          <note><para>
> -            Note that the <methodname>mode_valid</methodname> helper operation is
> -            only called for modes detected by the device, and
> -            <emphasis>not</emphasis> for modes set by the user through the CRTC
> -            <methodname>set_config</methodname> operation.
> -          </para></note>
> -        </listitem>
> -      </itemizedlist>
> -    </sect2>
> -    <sect2>
>        <title>Atomic Modeset Helper Functions Reference</title>
>        <sect3>
>  	<title>Overview</title>
> diff --git a/include/drm/drm_modeset_helper_vtables.h b/include/drm/drm_modeset_helper_vtables.h
> index 29e0dc50031d..a126a0d7aed4 100644
> --- a/include/drm/drm_modeset_helper_vtables.h
> +++ b/include/drm/drm_modeset_helper_vtables.h
> @@ -131,6 +131,20 @@ struct drm_crtc_helper_funcs {
>  	 * Atomic drivers which need to inspect and adjust more state should
>  	 * instead use the @atomic_check callback.
>  	 *
> +	 * Also beware that neither core nor helpers filter modes before
> +	 * passing them to the driver: While the list of modes that is
> +	 * advertised to userspace is filtered using the connector's
> +	 * ->mode_valid() callback, neither the core nor the helpers do any
> +	 * filtering on modes passed in from userspace when setting a mode. It
> +	 * is therefore possible for userspace to pass in a mode that was
> +	 * previously filtered out using ->mode_valid() or add a custom mode
> +	 * that wasn't probed from EDID or similar to begin with.  Even though
> +	 * this is an advanced feature and rarely used nowadays, some users rely
> +	 * on being able to specify modes manually so drivers must be prepared
> +	 * to deal with it. Specifically this means that all drivers need not
> +	 * only validate modes in ->mode_valid() but also in ->mode_fixup() to
> +	 * make sure invalid modes passed in from userspace are rejected.
> +	 *
>  	 * RETURNS:
>  	 *
>  	 * True if an acceptable configuration is possible, false if the modeset
> @@ -188,7 +202,9 @@ struct drm_crtc_helper_funcs {
>  	 * This callback is used by the legacy CRTC helpers to set a new
>  	 * framebuffer and scanout position. It is optional and used as an
>  	 * optimized fast-path instead of a full mode set operation with all the
> -	 * resulting flickering. Since it can't update other planes it's
> +	 * resulting flickering. If it is not present
> +	 * drm_crtc_helper_set_config() will fall back to a full modeset, using
> +	 * the ->mode_set() callback. Since it can't update other planes it's
>  	 * incompatible with atomic modeset support.
>  	 *
>  	 * This callback is only used by the CRTC helpers and deprecated.
> @@ -439,6 +455,20 @@ struct drm_encoder_helper_funcs {
>  	 * Atomic drivers which need to inspect and adjust more state should
>  	 * instead use the @atomic_check callback.
>  	 *
> +	 * Also beware that neither core nor helpers filter modes before
> +	 * passing them to the driver: While the list of modes that is
> +	 * advertised to userspace is filtered using the connector's
> +	 * ->mode_valid() callback, neither the core nor the helpers do any
> +	 * filtering on modes passed in from userspace when setting a mode. It
> +	 * is therefore possible for userspace to pass in a mode that was
> +	 * previously filtered out using ->mode_valid() or add a custom mode
> +	 * that wasn't probed from EDID or similar to begin with.  Even though
> +	 * this is an advanced feature and rarely used nowadays, some users rely
> +	 * on being able to specify modes manually so drivers must be prepared
> +	 * to deal with it. Specifically this means that all drivers need not
> +	 * only validate modes in ->mode_valid() but also in ->mode_fixup() to
> +	 * make sure invalid modes passed in from userspace are rejected.
> +	 *
>  	 * RETURNS:
>  	 *
>  	 * True if an acceptable configuration is possible, false if the modeset
> @@ -640,8 +670,16 @@ struct drm_connector_helper_funcs {
>  	 * In this function drivers then parse the modes in the EDID and add
>  	 * them by calling drm_add_edid_modes(). But connectors that driver a
>  	 * fixed panel can also manually add specific modes using
> -	 * drm_mode_probed_add(). Finally drivers that support audio probably
> -	 * want to update the ELD data, too, using drm_edid_to_eld().
> +	 * drm_mode_probed_add(). Drivers which manually add modes should also
> +	 * make sure that the @display_info, @width_mm and @height_mm fields of the
> +	 * struct #drm_connector are filled in.
> +	 *
> +	 * Virtual drivers that just want some standard VESA mode with a given
> +	 * resolution can call drm_add_modes_noedid(), and mark the preferred
> +	 * one using drm_set_preferred_mode().
> +	 *
> +	 * Finally drivers that support audio probably want to update the ELD
> +	 * data, too, using drm_edid_to_eld().
>  	 *
>  	 * This function is only called after the ->detect() hook has indicated
>  	 * that a sink is connected and when the EDID isn't overridden through
> -- 
> 2.6.4
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch


More information about the dri-devel mailing list