drm: Merge helper docbook into kerneldoc comments
Duplication is bad, luckily both help texts highlighted different issues so the kerneldoc gained quite a bit! While at it also sprinkle more references to the vtable structs around and make it clear that legacy CRTC helpers are deprecated and which functions to use instead. v2: Spelling fixes and polish (Thierry). Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-6-git-send-email-daniel.vetter@ffwll.ch Reviewed-by: Thierry Reding <treding@nvidia.com>
This commit is contained in:
Daniel Vetter
parent
4490d4c711
commit
2be94971c7
3 changed files with 76 additions and 98 deletions
|
|
@ -1830,83 +1830,7 @@ void intel_crt_init(struct drm_device *dev)
|
|||
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,
|
||||
|
|
@ -2308,7 +2232,7 @@ void intel_crt_init(struct drm_device *dev)
|
|||
!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>
|
||||
|
|
|
|||
|
|
@ -51,6 +51,11 @@
|
|||
* 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
|
||||
|
|
@ -211,8 +216,8 @@ static void __drm_helper_disable_unused_functions(struct drm_device *dev)
|
|||
* @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.
|
||||
*/
|
||||
|
|
@ -450,11 +455,36 @@ drm_crtc_helper_disable(struct drm_crtc *crtc)
|
|||
* 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.
|
||||
|
|
@ -763,10 +793,18 @@ static int drm_helper_choose_crtc_dpms(struct drm_crtc *crtc)
|
|||
* @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.
|
||||
|
|
@ -924,9 +962,9 @@ EXPORT_SYMBOL(drm_helper_resume_force_mode);
|
|||
* @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.
|
||||
|
|
@ -990,7 +1028,7 @@ EXPORT_SYMBOL(drm_helper_crtc_mode_set);
|
|||
* @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
|
||||
|
|
|
|||
|
|
@ -273,15 +273,28 @@ prune:
|
|||
* @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.
|
||||
*/
|
||||
|
|
@ -298,8 +311,11 @@ EXPORT_SYMBOL(drm_helper_probe_single_connector_modes);
|
|||
* @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)
|
||||
|
|
|
|||
Loading…
Reference in a new issue