Skip to content

L
linux
Commit df7d678b authored by Daniel Vetter's avatar Daniel Vetter
Browse files
Options

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

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@ideasonboard.com>
Cc: Thierry Reding <treding@nvidia.com>
Acked-by: default avatarThierry Reding <treding@nvidia.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
parent 4cba6850
Hide whitespace changes
Inline Side-by-side
Showing with 41 additions and 191 deletions
Documentation/DocBook/gpu.tmpl
View file @ df7d678b
......@@ -1578,194 +1578,6 @@ void intel_crt_init(struct drm_device *dev)
To use it, a driver must provide bottom functions for all of the three KMS
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-&gt;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-&gt;x</literal> and
<literal>crtc-&gt;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>
......
include/drm/drm_modeset_helper_vtables.h
View file @ df7d678b
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7