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: Alex Deucher <alexander.deucher@amd.com> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
This commit is contained in:
Daniel Vetter
parent
00d762cbd1
commit
3fcc42e07c
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue