diff options
author | Daniel Vetter <daniel.vetter@ffwll.ch> | 2015-12-04 09:45:46 +0100 |
---|---|---|
committer | Daniel Vetter <daniel.vetter@ffwll.ch> | 2015-12-08 16:07:52 +0100 |
commit | 2be94971c759da872efce99fa823ea17cdb7cc8b (patch) | |
tree | 65a4dff301386b3d5610d5b0409aee7d5df832fe /drivers/gpu/drm | |
parent | 4490d4c7111e1ebf748ea2c3e1e64d103d73bae7 (diff) | |
download | linux-2be94971c759da872efce99fa823ea17cdb7cc8b.tar.bz2 |
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>
Diffstat (limited to 'drivers/gpu/drm')
-rw-r--r-- | drivers/gpu/drm/drm_crtc_helper.c | 64 | ||||
-rw-r--r-- | drivers/gpu/drm/drm_probe_helper.c | 30 |
2 files changed, 74 insertions, 20 deletions
diff --git a/drivers/gpu/drm/drm_crtc_helper.c b/drivers/gpu/drm/drm_crtc_helper.c index 5dc92b66e07e..fadbdb33bdcc 100644 --- a/drivers/gpu/drm/drm_crtc_helper.c +++ b/drivers/gpu/drm/drm_crtc_helper.c @@ -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 diff --git a/drivers/gpu/drm/drm_probe_helper.c b/drivers/gpu/drm/drm_probe_helper.c index b59acad83644..d65def42f4b5 100644 --- a/drivers/gpu/drm/drm_probe_helper.c +++ b/drivers/gpu/drm/drm_probe_helper.c @@ -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) |