Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 3fcc42e0 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm: kerneldoc polish for drm_crtc_helper.c 



Most of this is newly added kerneldoc for the hotplug and output
polling code. But I've also thrown in a bit lesser polish, most of it
is tuning down the shouting RETURN: headers.

Overview documentation for the output probing and mode setting support
code will be added in later patches.

Reviewed-by: default avatarAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
parent 00d762cb

drivers/gpu/drm/drm_crtc_helper.c

+111 −14
Original line number Diff line number Diff line
@@ -114,8 +114,8 @@ static void drm_mode_validate_flag(struct drm_connector *connector, 
 * @connector vfunc for drivers that use the crtc helpers for output mode

 * filtering and detection.

 *

 * RETURNS:

 * Number of modes found on @connector.

 * Returns:

 * The number of modes found on @connector.

 */

int drm_helper_probe_single_connector_modes(struct drm_connector *connector,

					    uint32_t maxX, uint32_t maxY)
@@ -217,10 +217,12 @@ EXPORT_SYMBOL(drm_helper_probe_single_connector_modes); 
 * drm_helper_encoder_in_use - check if a given encoder is in use

 * @encoder: encoder to check

 *

 * Walk @encoders's DRM device's mode_config and see if it's in use.

 * Checks whether @encoder is with the current mode setting output configuration

 * in use by any connector. This doesn't mean that it is actually enabled since

 * the DPMS state is tracked separately.

 *

 * RETURNS:

 * True if @encoder is part of the mode_config, false otherwise.

 * Returns:

 * True if @encoder is used, false otherwise.

 */

bool drm_helper_encoder_in_use(struct drm_encoder *encoder)

{
@@ -239,10 +241,12 @@ EXPORT_SYMBOL(drm_helper_encoder_in_use); 
 * drm_helper_crtc_in_use - check if a given CRTC is in a mode_config

 * @crtc: CRTC to check

 *

 * Walk @crtc's DRM device's mode_config and see if it's in use.

 * Checks whether @crtc is with the current mode setting output configuration

 * in use by any connector. This doesn't mean that it is actually enabled since

 * the DPMS state is tracked separately.

 *

 * RETURNS:

 * True if @crtc is part of the mode_config, false otherwise.

 * Returns:

 * True if @crtc is used, false otherwise.

 */

bool drm_helper_crtc_in_use(struct drm_crtc *crtc)

{
@@ -278,8 +282,11 @@ drm_encoder_disable(struct drm_encoder *encoder) 
 * drm_helper_disable_unused_functions - disable unused objects

 * @dev: DRM device

 *

 * If an connector or CRTC isn't part of @dev's mode_config, it can be disabled

 * by calling its dpms function, which should power it off.

 * 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

 * either by calling their disable callback if available or by calling their

 * dpms callback with DRM_MODE_DPMS_OFF.

 */

void drm_helper_disable_unused_functions(struct drm_device *dev)

{
@@ -358,8 +365,8 @@ drm_crtc_prepare_encoders(struct drm_device *dev) 
 * drm_crtc_helper_set_config() helper function to drive the mode setting

 * sequence.

 *

 * RETURNS:

 * True if the mode was set successfully, or false otherwise.

 * Returns:

 * True if the mode was set successfully, false otherwise.

 */

bool drm_crtc_helper_set_mode(struct drm_crtc *crtc,

			      struct drm_display_mode *mode,
@@ -559,8 +566,8 @@ drm_crtc_helper_disable(struct drm_crtc *crtc) 
 * kernel mode setting with the crtc helper functions and the assorted

 * ->prepare(), ->modeset() and ->commit() helper callbacks.

 *

 * RETURNS:

 * Returns 0 on success, -ERRNO on failure.

 * Returns:

 * Returns 0 on success, negative errno numbers on failure.

 */

int drm_crtc_helper_set_config(struct drm_mode_set *set)

{
@@ -916,6 +923,14 @@ void drm_helper_connector_dpms(struct drm_connector *connector, int mode) 
}

EXPORT_SYMBOL(drm_helper_connector_dpms);



/**

 * drm_helper_mode_fill_fb_struct - fill out framebuffer metadata

 * @fb: drm_framebuffer object to fill out

 * @mode_cmd: metadata from the userspace fb creation request

 *

 * This helper can be used in a drivers fb_create callback to pre-fill the fb's

 * metadata fields.

 */

void drm_helper_mode_fill_fb_struct(struct drm_framebuffer *fb,

				    struct drm_mode_fb_cmd2 *mode_cmd)

{
@@ -998,6 +1013,22 @@ void drm_helper_resume_force_mode(struct drm_device *dev) 
}

EXPORT_SYMBOL(drm_helper_resume_force_mode);



/**

 * drm_kms_helper_hotplug_event - fire off KMS hotplug events

 * @dev: drm_device whose connector state changed

 *

 * This function fires off the uevent for userspace and also calls the

 * output_poll_changed function, which is most commonly used to inform the fbdev

 * emulation code and allow it to update the fbcon output configuration.

 *

 * Drivers should call this from their hotplug handling code when a change is

 * detected. Note that this function does not do any output detection of its

 * own, like drm_helper_hpd_irq_event() does - this is assumed to be done by the

 * driver already.

 *

 * This function must be called from process context with no mode

 * setting locks held.

 */

void drm_kms_helper_hotplug_event(struct drm_device *dev)

{

	/* send a uevent + call fbdev */
@@ -1066,6 +1097,16 @@ static void output_poll_execute(struct work_struct *work) 
		schedule_delayed_work(delayed_work, DRM_OUTPUT_POLL_PERIOD);

}



/**

 * drm_kms_helper_poll_disable - disable output polling

 * @dev: drm_device

 *

 * This function disables the output polling work.

 *

 * Drivers can call this helper from their device suspend implementation. It is

 * not an error to call this even when output polling isn't enabled or arlready

 * disabled.

 */

void drm_kms_helper_poll_disable(struct drm_device *dev)

{

	if (!dev->mode_config.poll_enabled)
@@ -1074,6 +1115,16 @@ void drm_kms_helper_poll_disable(struct drm_device *dev) 
}

EXPORT_SYMBOL(drm_kms_helper_poll_disable);



/**

 * drm_kms_helper_poll_enable - re-enable output polling.

 * @dev: drm_device

 *

 * This function re-enables the output polling work.

 *

 * Drivers can call this helper from their device resume implementation. It is

 * an error to call this when the output polling support has not yet been set

 * up.

 */

void drm_kms_helper_poll_enable(struct drm_device *dev)

{

	bool poll = false;
@@ -1093,6 +1144,25 @@ void drm_kms_helper_poll_enable(struct drm_device *dev) 
}

EXPORT_SYMBOL(drm_kms_helper_poll_enable);



/**

 * drm_kms_helper_poll_init - initialize and enable output polling

 * @dev: drm_device

 *

 * This function intializes and then also enables output polling support for

 * @dev. Drivers which do not have reliable hotplug support in hardware can use

 * this helper infrastructure to regularly poll such connectors for changes in

 * their connection state.

 *

 * Drivers can control which connectors are polled by setting the

 * DRM_CONNECTOR_POLL_CONNECT and DRM_CONNECTOR_POLL_DISCONNECT flags. On

 * connectors where probing live outputs can result in visual distortion drivers

 * should not set the DRM_CONNECTOR_POLL_DISCONNECT flag to avoid this.

 * Connectors which have no flag or only DRM_CONNECTOR_POLL_HPD set are

 * completely ignored by the polling logic.

 *

 * Note that a connector can be both polled and probed from the hotplug handler,

 * in case the hotplug interrupt is known to be unreliable.

 */

void drm_kms_helper_poll_init(struct drm_device *dev)

{

	INIT_DELAYED_WORK(&dev->mode_config.output_poll_work, output_poll_execute);
@@ -1102,12 +1172,39 @@ void drm_kms_helper_poll_init(struct drm_device *dev) 
}

EXPORT_SYMBOL(drm_kms_helper_poll_init);



/**

 * drm_kms_helper_poll_fini - disable output polling and clean it up

 * @dev: drm_device

 */

void drm_kms_helper_poll_fini(struct drm_device *dev)

{

	drm_kms_helper_poll_disable(dev);

}

EXPORT_SYMBOL(drm_kms_helper_poll_fini);



/**

 * drm_helper_hpd_irq_event - hotplug processing

 * @dev: drm_device

 *

 * Drivers can use this helper function to run a detect cycle on all connectors

 * which have the DRM_CONNECTOR_POLL_HPD flag set in their &polled member. All

 * other connectors are ignored, which is useful to avoid reprobing fixed

 * panels.

 *

 * This helper function is useful for drivers which can't or don't track hotplug

 * interrupts for each connector.

 *

 * Drivers which support hotplug interrupts for each connector individually and

 * which have a more fine-grained detect logic should bypass this code and

 * directly call drm_kms_helper_hotplug_event() in case the connector state

 * changed.

 *

 * This function must be called from process context with no mode

 * setting locks held.

 *

 * Note that a connector can be both polled and probed from the hotplug handler,

 * in case the hotplug interrupt is known to be unreliable.

 */

bool drm_helper_hpd_irq_event(struct drm_device *dev)

{

	struct drm_connector *connector;