From 57d30230c573e3f1a49ae7e0f7f8b73b17881415 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 24 May 2017 16:51:45 +0200 Subject: [PATCH] drm/doc: vblank cleanup Git-commit: 57d30230c573e3f1a49ae7e0f7f8b73b17881415 Patch-mainline: v4.14-rc1 References: FATE#322643 bsc#1055900 Unify and review everything, plus make sure it's all correct markup. Drop the kernel-doc for internal functions. Also rework the overview section, it's become rather outdated. Unfortuantely the kernel-doc in drm_driver isn't rendered yet, but that will change as soon as drm_driver is kernel-docified properly. Also document properly that drm_vblank_cleanup is optional, the core calls this already. V2: Make it clear that cleanup happens in drm_dev_fini for drivers with their own ->release callback (Thierry). Acked-by: Thierry Reding Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/20170524145212.27837-11-daniel.vetter@ffwll.ch Acked-by: Takashi Iwai --- Documentation/gpu/drm-kms.rst | 56 -------------- drivers/gpu/drm/drm_vblank.c | 160 ++++++++++++++++++++---------------------- include/drm/drmP.h | 37 ++++++++- include/drm/drm_crtc.h | 3 4 files changed, 114 insertions(+), 142 deletions(-) --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -554,60 +554,8 @@ various modules/drivers. Vertical Blanking ================= -Vertical blanking plays a major role in graphics rendering. To achieve -tear-free display, users must synchronize page flips and/or rendering to -vertical blanking. The DRM API offers ioctls to perform page flips -synchronized to vertical blanking and wait for vertical blanking. - -The DRM core handles most of the vertical blanking management logic, -which involves filtering out spurious interrupts, keeping race-free -blanking counters, coping with counter wrap-around and resets and -keeping use counts. It relies on the driver to generate vertical -blanking interrupts and optionally provide a hardware vertical blanking -counter. Drivers must implement the following operations. - -- int (\*enable_vblank) (struct drm_device \*dev, int crtc); void - (\*disable_vblank) (struct drm_device \*dev, int crtc); - Enable or disable vertical blanking interrupts for the given CRTC. - -- u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc); - Retrieve the value of the vertical blanking counter for the given - CRTC. If the hardware maintains a vertical blanking counter its value - should be returned. Otherwise drivers can use the - :c:func:`drm_vblank_count()` helper function to handle this - operation. - -Drivers must initialize the vertical blanking handling core with a call -to :c:func:`drm_vblank_init()` in their load operation. - -Vertical blanking interrupts can be enabled by the DRM core or by -drivers themselves (for instance to handle page flipping operations). -The DRM core maintains a vertical blanking use count to ensure that the -interrupts are not disabled while a user still needs them. To increment -the use count, drivers call :c:func:`drm_vblank_get()`. Upon -return vertical blanking interrupts are guaranteed to be enabled. - -To decrement the use count drivers call -:c:func:`drm_vblank_put()`. Only when the use count drops to zero -will the DRM core disable the vertical blanking interrupts after a delay -by scheduling a timer. The delay is accessible through the -vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global -variable and expressed in milliseconds. Its default value is 5000 ms. -Zero means never disable, and a negative value means disable -immediately. Drivers may override the behaviour by setting the -:c:type:`struct drm_device ` -vblank_disable_immediate flag, which when set causes vblank interrupts -to be disabled immediately regardless of the drm_vblank_offdelay -value. The flag should only be set if there's a properly working -hardware vblank counter present. - -When a vertical blanking interrupt occurs drivers only need to call the -:c:func:`drm_handle_vblank()` function to account for the -interrupt. - -Resources allocated by :c:func:`drm_vblank_init()` must be freed -with a call to :c:func:`drm_vblank_cleanup()` in the driver unload -operation handler. +.. kernel-doc:: drivers/gpu/drm/drm_vblank.c + :doc: vblank handling Vertical Blanking and Interrupt Handling Functions Reference ------------------------------------------------------------ --- a/drivers/gpu/drm/drm_vblank.c +++ b/drivers/gpu/drm/drm_vblank.c @@ -31,6 +31,41 @@ #include "drm_trace.h" #include "drm_internal.h" +/** + * DOC: vblank handling + * + * Vertical blanking plays a major role in graphics rendering. To achieve + * tear-free display, users must synchronize page flips and/or rendering to + * vertical blanking. The DRM API offers ioctls to perform page flips + * synchronized to vertical blanking and wait for vertical blanking. + * + * The DRM core handles most of the vertical blanking management logic, which + * involves filtering out spurious interrupts, keeping race-free blanking + * counters, coping with counter wrap-around and resets and keeping use counts. + * It relies on the driver to generate vertical blanking interrupts and + * optionally provide a hardware vertical blanking counter. + * + * Drivers must initialize the vertical blanking handling core with a call to + * drm_vblank_init(). Minimally, a driver needs to implement + * &drm_crtc_funcs.enable_vblank and &drm_crtc_funcs.disable_vblank plus call + * drm_crtc_handle_vblank() in it's vblank interrupt handler for working vblank + * support. + * + * Vertical blanking interrupts can be enabled by the DRM core or by drivers + * themselves (for instance to handle page flipping operations). The DRM core + * maintains a vertical blanking use count to ensure that the interrupts are not + * disabled while a user still needs them. To increment the use count, drivers + * call drm_crtc_vblank_get() and release the vblank reference again with + * drm_crtc_vblank_put(). In between these two calls vblank interrupts are + * guaranteed to be enabled. + * + * On many hardware disabling the vblank interrupt cannot be done in a race-free + * manner, see &drm_driver.vblank_disable_immediate and + * &drm_driver.max_vblank_count. In that case the vblank core only disables the + * vblanks after a timer has expired, which can be configured through the + * ``vblankoffdelay`` module parameter. + */ + /* Retry timestamp calculation up to 3 times to satisfy * drm_timestamp_precision before giving up. */ @@ -262,11 +297,12 @@ static u32 drm_vblank_count(struct drm_d * drm_accurate_vblank_count - retrieve the master vblank counter * @crtc: which counter to retrieve * - * This function is similar to @drm_crtc_vblank_count but this - * function interpolates to handle a race with vblank irq's. + * This function is similar to drm_crtc_vblank_count() but this function + * interpolates to handle a race with vblank interrupts using the high precision + * timestamping support. * - * This is mostly useful for hardware that can obtain the scanout - * position, but doesn't have a frame counter. + * This is mostly useful for hardware that can obtain the scanout position, but + * doesn't have a hardware frame counter. */ u32 drm_accurate_vblank_count(struct drm_crtc *crtc) { @@ -362,10 +398,14 @@ static void vblank_disable_fn(unsigned l * drm_vblank_cleanup - cleanup vblank support * @dev: DRM device * - * This function cleans up any resources allocated in drm_vblank_init. + * This function cleans up any resources allocated in drm_vblank_init(). It is + * called by the DRM core when @dev is finalized. + * + * Drivers can call drm_vblank_cleanup() if they need to quiescent the vblank + * interrupt in their unload code. But in general this should be handled by + * disabling all active &drm_crtc through e.g. drm_atomic_helper_shutdown, which + * should end up calling drm_crtc_vblank_off(). * - * Drivers which don't use drm_irq_install() need to set &drm_device.irq_enabled - * themselves, to signal to the DRM core that vblank interrupts are enabled. */ void drm_vblank_cleanup(struct drm_device *dev) { @@ -396,6 +436,9 @@ EXPORT_SYMBOL(drm_vblank_cleanup); * @num_crtcs: number of CRTCs supported by @dev * * This function initializes vblank support for @num_crtcs display pipelines. + * Drivers do not need to call drm_vblank_cleanup(), cleanup is already handled + * by the DRM core, or through calling drm_dev_fini() for drivers with a + * &drm_driver.release callback. * * Returns: * Zero on success or a negative error code on failure. @@ -468,11 +511,11 @@ EXPORT_SYMBOL(drm_crtc_vblank_waitqueue) * @crtc: drm_crtc whose timestamp constants should be updated. * @mode: display mode containing the scanout timings * - * Calculate and store various constants which are later - * needed by vblank and swap-completion timestamping, e.g, - * by drm_calc_vbltimestamp_from_scanoutpos(). They are - * derived from CRTC's true scanout timing, so they take - * things like panel scaling or other adjustments into account. + * Calculate and store various constants which are later needed by vblank and + * swap-completion timestamping, e.g, by + * drm_calc_vbltimestamp_from_scanoutpos(). They are derived from CRTC's true + * scanout timing, so they take things like panel scaling or other adjustments + * into account. */ void drm_calc_timestamping_constants(struct drm_crtc *crtc, const struct drm_display_mode *mode) @@ -535,25 +578,14 @@ EXPORT_SYMBOL(drm_calc_timestamping_cons * if flag is set. * * Implements calculation of exact vblank timestamps from given drm_display_mode - * timings and current video scanout position of a CRTC. This can be called from - * within get_vblank_timestamp() implementation of a kms driver to implement the - * actual timestamping. - * - * Should return timestamps conforming to the OML_sync_control OpenML - * extension specification. The timestamp corresponds to the end of - * the vblank interval, aka start of scanout of topmost-leftmost display - * pixel in the following video frame. - * - * Requires support for optional dev->driver->get_scanout_position() - * in kms driver, plus a bit of setup code to provide a drm_display_mode - * that corresponds to the true scanout timing. - * - * The current implementation only handles standard video modes. It - * returns as no operation if a doublescan or interlaced video mode is - * active. Higher level code is expected to handle this. - * - * This function can be used to implement the &drm_driver.get_vblank_timestamp - * directly, if the driver implements the &drm_driver.get_scanout_position hook. + * timings and current video scanout position of a CRTC. This can be directly + * used as the &drm_driver.get_vblank_timestamp implementation of a kms driver + * if &drm_driver.get_scanout_position is implemented. + * + * The current implementation only handles standard video modes. For double scan + * and interlaced modes the driver is supposed to adjust the hardware mode + * (taken from &drm_crtc_state.adjusted mode for atomic modeset drivers) to + * match the scanout position reported. * * Note that atomic drivers must call drm_calc_timestamping_constants() before * enabling a CRTC. The atomic helpers already take care of that in @@ -738,7 +770,9 @@ drm_get_last_vbltimestamp(struct drm_dev * * Fetches the "cooked" vblank count value that represents the number of * vblank events since the system was booted, including lost events due to - * modesetting activity. + * modesetting activity. Note that this timer isn't correct against a racing + * vblank interrupt (since it only reports the software vblank counter), see + * drm_accurate_vblank_count() for such use-cases. * * Returns: * The software vblank counter. @@ -749,20 +783,6 @@ u32 drm_crtc_vblank_count(struct drm_crt } EXPORT_SYMBOL(drm_crtc_vblank_count); -/** - * drm_vblank_count_and_time - retrieve "cooked" vblank counter value and the - * system timestamp corresponding to that vblank counter value. - * @dev: DRM device - * @pipe: index of CRTC whose counter to retrieve - * @vblanktime: Pointer to struct timeval to receive the vblank timestamp. - * - * Fetches the "cooked" vblank count value that represents the number of - * vblank events since the system was booted, including lost events due to - * modesetting activity. Returns corresponding system timestamp of the time - * of the vblank interval that corresponds to the current vblank counter value. - * - * This is the legacy version of drm_crtc_vblank_count_and_time(). - */ static u32 drm_vblank_count_and_time(struct drm_device *dev, unsigned int pipe, struct timeval *vblanktime) { @@ -852,8 +872,8 @@ static void send_vblank_event(struct drm * handler by calling drm_crtc_send_vblank_event() and make sure that there's no * possible race with the hardware committing the atomic update. * - * Caller must hold event lock. Caller must also hold a vblank reference for - * the event @e, which will be dropped when the next vblank arrives. + * Caller must hold a vblank reference for the event @e, which will be dropped + * when the next vblank arrives. */ void drm_crtc_arm_vblank_event(struct drm_crtc *crtc, struct drm_pending_vblank_event *e) @@ -913,14 +933,6 @@ static int __enable_vblank(struct drm_de return dev->driver->enable_vblank(dev, pipe); } -/** - * drm_vblank_enable - enable the vblank interrupt on a CRTC - * @dev: DRM device - * @pipe: CRTC index - * - * Returns: - * Zero on success or a negative error code on failure. - */ static int drm_vblank_enable(struct drm_device *dev, unsigned int pipe) { struct drm_vblank_crtc *vblank = &dev->vblank[pipe]; @@ -958,19 +970,6 @@ static int drm_vblank_enable(struct drm_ return ret; } -/** - * drm_vblank_get - get a reference count on vblank events - * @dev: DRM device - * @pipe: index of CRTC to own - * - * Acquire a reference count on vblank events to avoid having them disabled - * while in use. - * - * This is the legacy version of drm_crtc_vblank_get(). - * - * Returns: - * Zero on success or a negative error code on failure. - */ static int drm_vblank_get(struct drm_device *dev, unsigned int pipe) { struct drm_vblank_crtc *vblank = &dev->vblank[pipe]; @@ -1014,16 +1013,6 @@ int drm_crtc_vblank_get(struct drm_crtc } EXPORT_SYMBOL(drm_crtc_vblank_get); -/** - * drm_vblank_put - release ownership of vblank events - * @dev: DRM device - * @pipe: index of CRTC to release - * - * Release ownership of a given vblank counter, turning off interrupts - * if possible. Disable interrupts after drm_vblank_offdelay milliseconds. - * - * This is the legacy version of drm_crtc_vblank_put(). - */ static void drm_vblank_put(struct drm_device *dev, unsigned int pipe) { struct drm_vblank_crtc *vblank = &dev->vblank[pipe]; @@ -1067,6 +1056,8 @@ EXPORT_SYMBOL(drm_crtc_vblank_put); * This waits for one vblank to pass on @pipe, using the irq driver interfaces. * It is a failure to call this when the vblank irq for @pipe is disabled, e.g. * due to lack of driver support or because the crtc is off. + * + * This is the legacy version of drm_crtc_wait_one_vblank(). */ void drm_wait_one_vblank(struct drm_device *dev, unsigned int pipe) { @@ -1116,7 +1107,7 @@ EXPORT_SYMBOL(drm_crtc_wait_one_vblank); * stored so that drm_vblank_on can restore it again. * * Drivers must use this function when the hardware vblank counter can get - * reset, e.g. when suspending. + * reset, e.g. when suspending or disabling the @crtc in general. */ void drm_crtc_vblank_off(struct drm_crtc *crtc) { @@ -1184,6 +1175,8 @@ EXPORT_SYMBOL(drm_crtc_vblank_off); * drm_crtc_vblank_on() functions. The difference compared to * drm_crtc_vblank_off() is that this function doesn't save the vblank counter * and hence doesn't need to call any driver hooks. + * + * This is useful for recovering driver state e.g. on driver load, or on resume. */ void drm_crtc_vblank_reset(struct drm_crtc *crtc) { @@ -1212,9 +1205,10 @@ EXPORT_SYMBOL(drm_crtc_vblank_reset); * @crtc: CRTC in question * * This functions restores the vblank interrupt state captured with - * drm_crtc_vblank_off() again. Note that calls to drm_crtc_vblank_on() and - * drm_crtc_vblank_off() can be unbalanced and so can also be unconditionally called - * in driver load code to reflect the current hardware state of the crtc. + * drm_crtc_vblank_off() again and is generally called when enabling @crtc. Note + * that calls to drm_crtc_vblank_on() and drm_crtc_vblank_off() can be + * unbalanced and so can also be unconditionally called in driver load code to + * reflect the current hardware state of the crtc. */ void drm_crtc_vblank_on(struct drm_crtc *crtc) { --- a/include/drm/drmP.h +++ b/include/drm/drmP.h @@ -387,22 +387,49 @@ struct drm_device { bool irq_enabled; int irq; - /* + /** + * @vblank_disable_immediate: + * * If true, vblank interrupt will be disabled immediately when the * refcount drops to zero, as opposed to via the vblank disable * timer. - * This can be set to true it the hardware has a working vblank - * counter and the driver uses drm_vblank_on() and drm_vblank_off() - * appropriately. + * + * This can be set to true it the hardware has a working vblank counter + * with high-precision timestamping (otherwise there are races) and the + * driver uses drm_crtc_vblank_on() and drm_crtc_vblank_off() + * appropriately. See also @max_vblank_count and + * &drm_crtc_funcs.get_vblank_counter. */ bool vblank_disable_immediate; - /* array of size num_crtcs */ + /** + * @vblank: + * + * Array of vblank tracking structures, one per &struct drm_crtc. For + * historical reasons (vblank support predates kernel modesetting) this + * is free-standing and not part of &struct drm_crtc itself. It must be + * initialized explicitly by calling drm_vblank_init(). + */ struct drm_vblank_crtc *vblank; spinlock_t vblank_time_lock; /**< Protects vblank count and time updates during vblank enable/disable */ spinlock_t vbl_lock; + /** + * @max_vblank_count: + * + * Maximum value of the vblank registers. This value +1 will result in a + * wrap-around of the vblank register. It is used by the vblank core to + * handle wrap-arounds. + * + * If set to zero the vblank core will try to guess the elapsed vblanks + * between times when the vblank interrupt is disabled through + * high-precision timestamps. That approach is suffering from small + * races and imprecision over longer time periods, hence exposing a + * hardware vblank counter is always recommended. + * + * If non-zeor, &drm_crtc_funcs.get_vblank_counter must be set. + */ u32 max_vblank_count; /**< size of vblank counter register */ /** --- a/include/drm/drm_crtc.h +++ b/include/drm/drm_crtc.h @@ -685,6 +685,9 @@ struct drm_crtc_funcs { * drm_crtc_vblank_off() and drm_crtc_vblank_on() when disabling or * enabling a CRTC. * + * See also &drm_device.vblank_disable_immediate and + * &drm_device.max_vblank_count. + * * Returns: * * Raw vblank counter value.