malhuda/msm-4.14
1
0
Fork 0
mirror of https://github.com/rd-stuffs/msm-4.14.git synced 2025-02-20 11:45:48 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

drm: Merge helper docbook into kerneldoc comments

Browse Source 
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 2015-12-04 09:45:46 +01:00
parent 4490d4c711
commit 2be94971c7
3 changed files with 76 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
Documentation/DocBook/gpu.tmpl
View File

@ -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>

64
drivers/gpu/drm/drm_crtc_helper.c
View File

@ -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

30
drivers/gpu/drm/drm_probe_helper.c
View File

@ -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)