entities.
</para>
<sect2>
- <title>Helper Functions</title>
- <itemizedlist>
- <listitem>
- <synopsis>int drm_crtc_helper_set_config(struct drm_mode_set *set);</synopsis>
- <para>
- The <function>drm_crtc_helper_set_config</function> helper function
- is a CRTC <methodname>set_config</methodname> implementation. It
- first tries to locate the best encoder for each connector by calling
- the connector <methodname>best_encoder</methodname> helper
- operation.
- </para>
- <para>
- After locating the appropriate encoders, the helper function will
- call the <methodname>mode_fixup</methodname> encoder and CRTC helper
- operations to adjust the requested mode, or reject it completely in
- which case an error will be returned to the application. If the new
- configuration after mode adjustment is identical to the current
- configuration the helper function will return without performing any
- other operation.
- </para>
- <para>
- If the adjusted mode is identical to the current mode but changes to
- the frame buffer need to be applied, the
- <function>drm_crtc_helper_set_config</function> function will call
- the CRTC <methodname>mode_set_base</methodname> helper operation. If
- the adjusted mode differs from the current mode, or if the
- <methodname>mode_set_base</methodname> helper operation is not
- provided, the helper function performs a full mode set sequence by
- calling the <methodname>prepare</methodname>,
- <methodname>mode_set</methodname> and
- <methodname>commit</methodname> CRTC and encoder helper operations,
- in that order.
- </para>
- </listitem>
- <listitem>
- <synopsis>void drm_helper_connector_dpms(struct drm_connector *connector, int mode);</synopsis>
- <para>
- The <function>drm_helper_connector_dpms</function> helper function
- is a connector <methodname>dpms</methodname> implementation that
- tracks power state of connectors. To use the function, drivers must
- provide <methodname>dpms</methodname> helper operations for CRTCs
- and encoders to apply the DPMS state to the device.
- </para>
- <para>
- The mid-layer doesn't track the power state of CRTCs and encoders.
- The <methodname>dpms</methodname> helper operations can thus be
- called with a mode identical to the currently active mode.
- </para>
- </listitem>
- <listitem>
- <synopsis>int drm_helper_probe_single_connector_modes(struct drm_connector *connector,
- uint32_t maxX, uint32_t maxY);</synopsis>
- <para>
- The <function>drm_helper_probe_single_connector_modes</function> helper
- function is a connector <methodname>fill_modes</methodname>
- implementation that updates the connection status for the connector
- and then retrieves a list of modes by calling the connector
- <methodname>get_modes</methodname> helper operation.
- </para>
- <para>
- If the helper operation returns no mode, and if the connector status
- is connector_status_connected, standard VESA DMT modes up to
- 1024x768 are automatically added to the modes list by a call to
- <function>drm_add_modes_noedid</function>.
- </para>
- <para>
- The function then filters out modes larger than
- <parameter>max_width</parameter> and <parameter>max_height</parameter>
- if specified. It finally calls the optional connector
- <methodname>mode_valid</methodname> helper operation for each mode in
- the probed list to check whether the mode is valid for the connector.
- </para>
- </listitem>
- </itemizedlist>
- </sect2>
- <sect2>
- <title>CRTC Helper Operations</title>
+ <title>Legacy CRTC Helper Operations</title>
<itemizedlist>
<listitem id="drm-helper-crtc-mode-fixup">
<synopsis>bool (*mode_fixup)(struct drm_crtc *crtc,
!Pinclude/drm/drm_modeset_helper_vtables.h overview
</sect2>
<sect2>
- <title>Modeset Helper Functions Reference</title>
+ <title>Legacy CRTC/Modeset Helper Functions Reference</title>
!Edrivers/gpu/drm/drm_crtc_helper.c
!Pdrivers/gpu/drm/drm_crtc_helper.c overview
</sect2>
* the same callbacks which drivers can use to e.g. restore the modeset
* configuration on resume with drm_helper_resume_force_mode().
*
+ * Note that this helper library doesn't track the current power state of CRTCs
+ * and encoders. It can call callbacks like ->dpms() even though the hardware is
+ * already in the desired state. This deficiency has been fixed in the atomic
+ * helpers.
+ *
* The driver callbacks are mostly compatible with the atomic modeset helpers,
* except for the handling of the primary plane: Atomic helpers require that the
* primary plane is implemented as a real standalone plane and not directly tied
* @dev: DRM device
*
* This function walks through the entire mode setting configuration of @dev. It
- * will remove any crtc links of unused encoders and encoder links of
- * disconnected connectors. Then it will disable all unused encoders and crtcs
+ * will remove any CRTC links of unused encoders and encoder links of
+ * disconnected connectors. Then it will disable all unused encoders and CRTCs
* either by calling their disable callback if available or by calling their
* dpms callback with DRM_MODE_DPMS_OFF.
*/
* drm_crtc_helper_set_config - set a new config from userspace
* @set: mode set configuration
*
- * Setup a new configuration, provided by the upper layers (either an ioctl call
- * from userspace or internally e.g. from the fbdev support 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.
+ * The drm_crtc_helper_set_config() helper function implements the set_config
+ * callback of struct &drm_crtc_funcs for drivers using the legacy CRTC helpers.
+ *
+ * It first tries to locate the best encoder for each connector by calling the
+ * connector ->best_encoder() (struct &drm_connector_helper_funcs) helper
+ * operation.
+ *
+ * After locating the appropriate encoders, the helper function will call the
+ * mode_fixup encoder and CRTC helper operations to adjust the requested mode,
+ * or reject it completely in which case an error will be returned to the
+ * application. If the new configuration after mode adjustment is identical to
+ * the current configuration the helper function will return without performing
+ * any other operation.
+ *
+ * If the adjusted mode is identical to the current mode but changes to the
+ * frame buffer need to be applied, the drm_crtc_helper_set_config() function
+ * will call the CRTC ->mode_set_base() (struct &drm_crtc_helper_funcs) helper
+ * operation.
+ *
+ * If the adjusted mode differs from the current mode, or if the
+ * ->mode_set_base() helper operation is not provided, the helper function
+ * performs a full mode set sequence by calling the ->prepare(), ->mode_set()
+ * and ->commit() CRTC and encoder helper operations, in that order.
+ * Alternatively it can also use the dpms and disable helper operations. For
+ * details see struct &drm_crtc_helper_funcs and struct
+ * &drm_encoder_helper_funcs.
+ *
+ * This function is deprecated. New drivers must implement atomic modeset
+ * support, for which this function is unsuitable. Instead drivers should use
+ * drm_atomic_helper_set_config().
*
* Returns:
* Returns 0 on success, negative errno numbers on failure.
* @connector: affected connector
* @mode: DPMS mode
*
- * This is the main helper function provided by the crtc helper framework for
+ * The drm_helper_connector_dpms() helper function implements the ->dpms()
+ * callback of struct &drm_connector_funcs for drivers using the legacy CRTC helpers.
+ *
+ * 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.
+ * state for all encoders and CRTCs in the output mesh and calls the ->dpms()
+ * callbacks provided by the driver in struct &drm_crtc_helper_funcs and struct
+ * &drm_encoder_helper_funcs appropriately.
+ *
+ * This function is deprecated. New drivers must implement atomic modeset
+ * support, for which this function is unsuitable. Instead drivers should use
+ * drm_atomic_helper_connector_dpms().
*
* Returns:
* Always returns 0.
* @old_fb: previous framebuffer
*
* This function implements a callback useable as the ->mode_set callback
- * required by the crtc helpers. Besides the atomic plane helper functions for
+ * required by the CRTC helpers. Besides the atomic plane helper functions for
* the primary plane the driver must also provide the ->mode_set_nofb callback
- * to set up the crtc.
+ * to set up the CRTC.
*
* This is a transitional helper useful for converting drivers to the atomic
* interfaces.
* @old_fb: previous framebuffer
*
* This function implements a callback useable as the ->mode_set_base used
- * required by the crtc helpers. The driver must provide the atomic plane helper
+ * required by the CRTC helpers. The driver must provide the atomic plane helper
* functions for the primary plane.
*
* This is a transitional helper useful for converting drivers to the atomic
* @maxX: max width for modes
* @maxY: max height for modes
*
- * 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.
+ * Based on the helper callbacks implemented by @connector in struct
+ * &drm_connector_helper_funcs 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.
*
- * Intended to be use as a generic implementation of the ->fill_modes()
- * @connector vfunc for drivers that use the crtc helpers for output mode
+ * Intended to be used as a generic implementation of the ->fill_modes()
+ * @connector vfunc for drivers that use the CRTC helpers for output mode
* filtering and detection.
*
+ * If the helper operation returns no mode, and if the connector status is
+ * connector_status_connected, standard VESA DMT modes up to 1024x768 are
+ * automatically added to the modes list by a call to
+ * drm_add_modes_noedid().
+ *
+ * The function then filters out modes larger than @maxX and maxY if specified.
+ * It finally calls the optional connector ->mode_valid() helper operation for each
+ * mode in the probed list to check whether the mode is valid for the connector.
+ *
+ * Compared to drm_helper_probe_single_connector_modes_nomerge() this function
+ * merged the mode bits for the preferred mode, as a hack to work around some
+ * quirky issues on funky hardware.
+ *
* Returns:
* The number of modes found on @connector.
*/
* @maxX: max width for modes
* @maxY: max height for modes
*
- * This operates like drm_hehlper_probe_single_connector_modes except it
+ * This operates like drm_hehlper_probe_single_connector_modes() except it
* replaces the mode bits instead of merging them for preferred modes.
+ *
+ * Returns:
+ * The number of modes found on @connector.
*/
int drm_helper_probe_single_connector_modes_nomerge(struct drm_connector *connector,
uint32_t maxX, uint32_t maxY)
projects / linux-beck.git / commitdiff