diff options
author | Daniel Vetter <daniel.vetter@ffwll.ch> | 2014-05-08 10:41:51 -0400 |
---|---|---|
committer | Daniel Vetter <daniel.vetter@ffwll.ch> | 2014-05-21 05:31:06 -0400 |
commit | f5752b38970990fa1495839751aed64bd178b9e0 (patch) | |
tree | 944485caa11b7c3a1c6d4faf6a715cad798512ee /drivers | |
parent | 8edffbb933619d568ea98edd3b55ec7c30df9274 (diff) |
drm/irq: kerneldoc polish
- Integrate into the drm DocBook
- Disable kerneldoc for functions not exported to drivers.
- Properly document the new drm_vblank_on|off and add cautious
comments explaining when drm_vblank_pre|post_modesets shouldn't be
used.
- General polish and OCD.
v2: Polish as suggested by Thierry.
Cc: Thierry Reding <thierry.reding@gmail.com>
Reviewed-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Diffstat (limited to 'drivers')
-rw-r--r-- | drivers/gpu/drm/drm_irq.c | 165 |
1 files changed, 117 insertions, 48 deletions
diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c index dd786d84daab..f3dafccca456 100644 --- a/drivers/gpu/drm/drm_irq.c +++ b/drivers/gpu/drm/drm_irq.c | |||
@@ -1,6 +1,5 @@ | |||
1 | /** | 1 | /* |
2 | * \file drm_irq.c | 2 | * drm_irq.c IRQ and vblank support |
3 | * IRQ support | ||
4 | * | 3 | * |
5 | * \author Rickard E. (Rik) Faith <faith@valinux.com> | 4 | * \author Rickard E. (Rik) Faith <faith@valinux.com> |
6 | * \author Gareth Hughes <gareth@valinux.com> | 5 | * \author Gareth Hughes <gareth@valinux.com> |
@@ -156,6 +155,12 @@ static void vblank_disable_fn(unsigned long arg) | |||
156 | spin_unlock_irqrestore(&dev->vbl_lock, irqflags); | 155 | spin_unlock_irqrestore(&dev->vbl_lock, irqflags); |
157 | } | 156 | } |
158 | 157 | ||
158 | /** | ||
159 | * drm_vblank_cleanup - cleanup vblank support | ||
160 | * @dev: DRM device | ||
161 | * | ||
162 | * This function cleans up any resources allocated in drm_vblank_init. | ||
163 | */ | ||
159 | void drm_vblank_cleanup(struct drm_device *dev) | 164 | void drm_vblank_cleanup(struct drm_device *dev) |
160 | { | 165 | { |
161 | int crtc; | 166 | int crtc; |
@@ -175,6 +180,16 @@ void drm_vblank_cleanup(struct drm_device *dev) | |||
175 | } | 180 | } |
176 | EXPORT_SYMBOL(drm_vblank_cleanup); | 181 | EXPORT_SYMBOL(drm_vblank_cleanup); |
177 | 182 | ||
183 | /** | ||
184 | * drm_vblank_init - initialize vblank support | ||
185 | * @dev: drm_device | ||
186 | * @num_crtcs: number of crtcs supported by @dev | ||
187 | * | ||
188 | * This function initializes vblank support for @num_crtcs display pipelines. | ||
189 | * | ||
190 | * Returns: | ||
191 | * Zero on success or a negative error code on failure. | ||
192 | */ | ||
178 | int drm_vblank_init(struct drm_device *dev, int num_crtcs) | 193 | int drm_vblank_init(struct drm_device *dev, int num_crtcs) |
179 | { | 194 | { |
180 | int i, ret = -ENOMEM; | 195 | int i, ret = -ENOMEM; |
@@ -238,13 +253,21 @@ static void drm_irq_vgaarb_nokms(void *cookie, bool state) | |||
238 | } | 253 | } |
239 | 254 | ||
240 | /** | 255 | /** |
241 | * Install IRQ handler. | 256 | * drm_irq_install - install IRQ handler |
242 | * | 257 | * @dev: DRM device |
243 | * \param dev DRM device. | 258 | * @irq: IRQ number to install the handler for |
244 | * | 259 | * |
245 | * Initializes the IRQ related data. Installs the handler, calling the driver | 260 | * Initializes the IRQ related data. Installs the handler, calling the driver |
246 | * \c irq_preinstall() and \c irq_postinstall() functions | 261 | * irq_preinstall() and irq_postinstall() functions before and after the |
247 | * before and after the installation. | 262 | * installation. |
263 | * | ||
264 | * This is the simplified helper interface provided for drivers with no special | ||
265 | * needs. Drivers which need to install interrupt handlers for multiple | ||
266 | * interrupts must instead set drm_device->irq_enabled to signal the DRM core | ||
267 | * that vblank interrupts are available. | ||
268 | * | ||
269 | * Returns: | ||
270 | * Zero on success or a negative error code on failure. | ||
248 | */ | 271 | */ |
249 | int drm_irq_install(struct drm_device *dev, int irq) | 272 | int drm_irq_install(struct drm_device *dev, int irq) |
250 | { | 273 | { |
@@ -304,11 +327,20 @@ int drm_irq_install(struct drm_device *dev, int irq) | |||
304 | EXPORT_SYMBOL(drm_irq_install); | 327 | EXPORT_SYMBOL(drm_irq_install); |
305 | 328 | ||
306 | /** | 329 | /** |
307 | * Uninstall the IRQ handler. | 330 | * drm_irq_uninstall - uninstall the IRQ handler |
331 | * @dev: DRM device | ||
332 | * | ||
333 | * Calls the driver's irq_uninstall() function and unregisters the IRQ handler. | ||
334 | * This should only be called by drivers which used drm_irq_install() to set up | ||
335 | * their interrupt handler. Other drivers must only reset | ||
336 | * drm_device->irq_enabled to false. | ||
308 | * | 337 | * |
309 | * \param dev DRM device. | 338 | * Note that for kernel modesetting drivers it is a bug if this function fails. |
339 | * The sanity checks are only to catch buggy user modesetting drivers which call | ||
340 | * the same function through an ioctl. | ||
310 | * | 341 | * |
311 | * Calls the driver's \c irq_uninstall() function, and stops the irq. | 342 | * Returns: |
343 | * Zero on success or a negative error code on failure. | ||
312 | */ | 344 | */ |
313 | int drm_irq_uninstall(struct drm_device *dev) | 345 | int drm_irq_uninstall(struct drm_device *dev) |
314 | { | 346 | { |
@@ -353,7 +385,7 @@ int drm_irq_uninstall(struct drm_device *dev) | |||
353 | } | 385 | } |
354 | EXPORT_SYMBOL(drm_irq_uninstall); | 386 | EXPORT_SYMBOL(drm_irq_uninstall); |
355 | 387 | ||
356 | /** | 388 | /* |
357 | * IRQ control ioctl. | 389 | * IRQ control ioctl. |
358 | * | 390 | * |
359 | * \param inode device inode. | 391 | * \param inode device inode. |
@@ -406,15 +438,14 @@ int drm_control(struct drm_device *dev, void *data, | |||
406 | } | 438 | } |
407 | 439 | ||
408 | /** | 440 | /** |
409 | * drm_calc_timestamping_constants - Calculate vblank timestamp constants | 441 | * drm_calc_timestamping_constants - calculate vblank timestamp constants |
410 | * | 442 | * @crtc: drm_crtc whose timestamp constants should be updated. |
411 | * @crtc drm_crtc whose timestamp constants should be updated. | 443 | * @mode: display mode containing the scanout timings |
412 | * @mode display mode containing the scanout timings | ||
413 | * | 444 | * |
414 | * Calculate and store various constants which are later | 445 | * Calculate and store various constants which are later |
415 | * needed by vblank and swap-completion timestamping, e.g, | 446 | * needed by vblank and swap-completion timestamping, e.g, |
416 | * by drm_calc_vbltimestamp_from_scanoutpos(). They are | 447 | * by drm_calc_vbltimestamp_from_scanoutpos(). They are |
417 | * derived from crtc's true scanout timing, so they take | 448 | * derived from CRTC's true scanout timing, so they take |
418 | * things like panel scaling or other adjustments into account. | 449 | * things like panel scaling or other adjustments into account. |
419 | */ | 450 | */ |
420 | void drm_calc_timestamping_constants(struct drm_crtc *crtc, | 451 | void drm_calc_timestamping_constants(struct drm_crtc *crtc, |
@@ -459,11 +490,22 @@ void drm_calc_timestamping_constants(struct drm_crtc *crtc, | |||
459 | EXPORT_SYMBOL(drm_calc_timestamping_constants); | 490 | EXPORT_SYMBOL(drm_calc_timestamping_constants); |
460 | 491 | ||
461 | /** | 492 | /** |
462 | * drm_calc_vbltimestamp_from_scanoutpos - helper routine for kms | 493 | * drm_calc_vbltimestamp_from_scanoutpos - precise vblank timestamp helper |
463 | * drivers. Implements calculation of exact vblank timestamps from | 494 | * @dev: DRM device |
464 | * given drm_display_mode timings and current video scanout position | 495 | * @crtc: Which CRTC's vblank timestamp to retrieve |
465 | * of a crtc. This can be called from within get_vblank_timestamp() | 496 | * @max_error: Desired maximum allowable error in timestamps (nanosecs) |
466 | * implementation of a kms driver to implement the actual timestamping. | 497 | * On return contains true maximum error of timestamp |
498 | * @vblank_time: Pointer to struct timeval which should receive the timestamp | ||
499 | * @flags: Flags to pass to driver: | ||
500 | * 0 = Default, | ||
501 | * DRM_CALLED_FROM_VBLIRQ = If function is called from vbl IRQ handler | ||
502 | * @refcrtc: CRTC which defines scanout timing | ||
503 | * @mode: mode which defines the scanout timings | ||
504 | * | ||
505 | * Implements calculation of exact vblank timestamps from given drm_display_mode | ||
506 | * timings and current video scanout position of a CRTC. This can be called from | ||
507 | * within get_vblank_timestamp() implementation of a kms driver to implement the | ||
508 | * actual timestamping. | ||
467 | * | 509 | * |
468 | * Should return timestamps conforming to the OML_sync_control OpenML | 510 | * Should return timestamps conforming to the OML_sync_control OpenML |
469 | * extension specification. The timestamp corresponds to the end of | 511 | * extension specification. The timestamp corresponds to the end of |
@@ -478,21 +520,11 @@ EXPORT_SYMBOL(drm_calc_timestamping_constants); | |||
478 | * returns as no operation if a doublescan or interlaced video mode is | 520 | * returns as no operation if a doublescan or interlaced video mode is |
479 | * active. Higher level code is expected to handle this. | 521 | * active. Higher level code is expected to handle this. |
480 | * | 522 | * |
481 | * @dev: DRM device. | 523 | * Returns: |
482 | * @crtc: Which crtc's vblank timestamp to retrieve. | 524 | * Negative value on error, failure or if not supported in current |
483 | * @max_error: Desired maximum allowable error in timestamps (nanosecs). | ||
484 | * On return contains true maximum error of timestamp. | ||
485 | * @vblank_time: Pointer to struct timeval which should receive the timestamp. | ||
486 | * @flags: Flags to pass to driver: | ||
487 | * 0 = Default. | ||
488 | * DRM_CALLED_FROM_VBLIRQ = If function is called from vbl irq handler. | ||
489 | * @refcrtc: drm_crtc* of crtc which defines scanout timing. | ||
490 | * @mode: mode which defines the scanout timings | ||
491 | * | ||
492 | * Returns negative value on error, failure or if not supported in current | ||
493 | * video mode: | 525 | * video mode: |
494 | * | 526 | * |
495 | * -EINVAL - Invalid crtc. | 527 | * -EINVAL - Invalid CRTC. |
496 | * -EAGAIN - Temporary unavailable, e.g., called before initial modeset. | 528 | * -EAGAIN - Temporary unavailable, e.g., called before initial modeset. |
497 | * -ENOTSUPP - Function not supported in current display mode. | 529 | * -ENOTSUPP - Function not supported in current display mode. |
498 | * -EIO - Failed, e.g., due to failed scanout position query. | 530 | * -EIO - Failed, e.g., due to failed scanout position query. |
@@ -641,23 +673,23 @@ static struct timeval get_drm_timestamp(void) | |||
641 | 673 | ||
642 | /** | 674 | /** |
643 | * drm_get_last_vbltimestamp - retrieve raw timestamp for the most recent | 675 | * drm_get_last_vbltimestamp - retrieve raw timestamp for the most recent |
644 | * vblank interval. | 676 | * vblank interval |
645 | * | ||
646 | * @dev: DRM device | 677 | * @dev: DRM device |
647 | * @crtc: which crtc's vblank timestamp to retrieve | 678 | * @crtc: which CRTC's vblank timestamp to retrieve |
648 | * @tvblank: Pointer to target struct timeval which should receive the timestamp | 679 | * @tvblank: Pointer to target struct timeval which should receive the timestamp |
649 | * @flags: Flags to pass to driver: | 680 | * @flags: Flags to pass to driver: |
650 | * 0 = Default. | 681 | * 0 = Default, |
651 | * DRM_CALLED_FROM_VBLIRQ = If function is called from vbl irq handler. | 682 | * DRM_CALLED_FROM_VBLIRQ = If function is called from vbl IRQ handler |
652 | * | 683 | * |
653 | * Fetches the system timestamp corresponding to the time of the most recent | 684 | * Fetches the system timestamp corresponding to the time of the most recent |
654 | * vblank interval on specified crtc. May call into kms-driver to | 685 | * vblank interval on specified CRTC. May call into kms-driver to |
655 | * compute the timestamp with a high-precision GPU specific method. | 686 | * compute the timestamp with a high-precision GPU specific method. |
656 | * | 687 | * |
657 | * Returns zero if timestamp originates from uncorrected do_gettimeofday() | 688 | * Returns zero if timestamp originates from uncorrected do_gettimeofday() |
658 | * call, i.e., it isn't very precisely locked to the true vblank. | 689 | * call, i.e., it isn't very precisely locked to the true vblank. |
659 | * | 690 | * |
660 | * Returns non-zero if timestamp is considered to be very precise. | 691 | * Returns: |
692 | * Non-zero if timestamp is considered to be very precise, zero otherwise. | ||
661 | */ | 693 | */ |
662 | u32 drm_get_last_vbltimestamp(struct drm_device *dev, int crtc, | 694 | u32 drm_get_last_vbltimestamp(struct drm_device *dev, int crtc, |
663 | struct timeval *tvblank, unsigned flags) | 695 | struct timeval *tvblank, unsigned flags) |
@@ -692,6 +724,9 @@ EXPORT_SYMBOL(drm_get_last_vbltimestamp); | |||
692 | * Fetches the "cooked" vblank count value that represents the number of | 724 | * Fetches the "cooked" vblank count value that represents the number of |
693 | * vblank events since the system was booted, including lost events due to | 725 | * vblank events since the system was booted, including lost events due to |
694 | * modesetting activity. | 726 | * modesetting activity. |
727 | * | ||
728 | * Returns: | ||
729 | * The software vblank counter. | ||
695 | */ | 730 | */ |
696 | u32 drm_vblank_count(struct drm_device *dev, int crtc) | 731 | u32 drm_vblank_count(struct drm_device *dev, int crtc) |
697 | { | 732 | { |
@@ -710,8 +745,7 @@ EXPORT_SYMBOL(drm_vblank_count); | |||
710 | * Fetches the "cooked" vblank count value that represents the number of | 745 | * Fetches the "cooked" vblank count value that represents the number of |
711 | * vblank events since the system was booted, including lost events due to | 746 | * vblank events since the system was booted, including lost events due to |
712 | * modesetting activity. Returns corresponding system timestamp of the time | 747 | * modesetting activity. Returns corresponding system timestamp of the time |
713 | * of the vblank interval that corresponds to the current value vblank counter | 748 | * of the vblank interval that corresponds to the current vblank counter value. |
714 | * value. | ||
715 | */ | 749 | */ |
716 | u32 drm_vblank_count_and_time(struct drm_device *dev, int crtc, | 750 | u32 drm_vblank_count_and_time(struct drm_device *dev, int crtc, |
717 | struct timeval *vblanktime) | 751 | struct timeval *vblanktime) |
@@ -882,7 +916,7 @@ static int drm_vblank_enable(struct drm_device *dev, int crtc) | |||
882 | * Acquire a reference count on vblank events to avoid having them disabled | 916 | * Acquire a reference count on vblank events to avoid having them disabled |
883 | * while in use. | 917 | * while in use. |
884 | * | 918 | * |
885 | * RETURNS | 919 | * Returns: |
886 | * Zero on success, nonzero on failure. | 920 | * Zero on success, nonzero on failure. |
887 | */ | 921 | */ |
888 | int drm_vblank_get(struct drm_device *dev, int crtc) | 922 | int drm_vblank_get(struct drm_device *dev, int crtc) |
@@ -930,6 +964,13 @@ EXPORT_SYMBOL(drm_vblank_put); | |||
930 | * drm_vblank_off - disable vblank events on a CRTC | 964 | * drm_vblank_off - disable vblank events on a CRTC |
931 | * @dev: DRM device | 965 | * @dev: DRM device |
932 | * @crtc: CRTC in question | 966 | * @crtc: CRTC in question |
967 | * | ||
968 | * Drivers can use this function to shut down the vblank interrupt handling when | ||
969 | * disabling a crtc. This function ensures that the latest vblank frame count is | ||
970 | * stored so that drm_vblank_on() can restore it again. | ||
971 | * | ||
972 | * Drivers must use this function when the hardware vblank counter can get | ||
973 | * reset, e.g. when suspending. | ||
933 | */ | 974 | */ |
934 | void drm_vblank_off(struct drm_device *dev, int crtc) | 975 | void drm_vblank_off(struct drm_device *dev, int crtc) |
935 | { | 976 | { |
@@ -966,6 +1007,11 @@ EXPORT_SYMBOL(drm_vblank_off); | |||
966 | * drm_vblank_on - enable vblank events on a CRTC | 1007 | * drm_vblank_on - enable vblank events on a CRTC |
967 | * @dev: DRM device | 1008 | * @dev: DRM device |
968 | * @crtc: CRTC in question | 1009 | * @crtc: CRTC in question |
1010 | * | ||
1011 | * This functions restores the vblank interrupt state captured with | ||
1012 | * drm_vblank_off() again. Note that calls to drm_vblank_on() and | ||
1013 | * drm_vblank_off() can be unbalanced and so can also be unconditionaly called | ||
1014 | * in driver load code to reflect the current hardware state of the crtc. | ||
969 | */ | 1015 | */ |
970 | void drm_vblank_on(struct drm_device *dev, int crtc) | 1016 | void drm_vblank_on(struct drm_device *dev, int crtc) |
971 | { | 1017 | { |
@@ -986,6 +1032,21 @@ EXPORT_SYMBOL(drm_vblank_on); | |||
986 | * | 1032 | * |
987 | * Account for vblank events across mode setting events, which will likely | 1033 | * Account for vblank events across mode setting events, which will likely |
988 | * reset the hardware frame counter. | 1034 | * reset the hardware frame counter. |
1035 | * | ||
1036 | * This is done by grabbing a temporary vblank reference to ensure that the | ||
1037 | * vblank interrupt keeps running across the modeset sequence. With this the | ||
1038 | * software-side vblank frame counting will ensure that there are no jumps or | ||
1039 | * discontinuities. | ||
1040 | * | ||
1041 | * Unfortunately this approach is racy and also doesn't work when the vblank | ||
1042 | * interrupt stops running, e.g. across system suspend resume. It is therefore | ||
1043 | * highly recommended that drivers use the newer drm_vblank_off() and | ||
1044 | * drm_vblank_on() instead. drm_vblank_pre_modeset() only works correctly when | ||
1045 | * using "cooked" software vblank frame counters and not relying on any hardware | ||
1046 | * counters. | ||
1047 | * | ||
1048 | * Drivers must call drm_vblank_post_modeset() when re-enabling the same crtc | ||
1049 | * again. | ||
989 | */ | 1050 | */ |
990 | void drm_vblank_pre_modeset(struct drm_device *dev, int crtc) | 1051 | void drm_vblank_pre_modeset(struct drm_device *dev, int crtc) |
991 | { | 1052 | { |
@@ -1007,6 +1068,14 @@ void drm_vblank_pre_modeset(struct drm_device *dev, int crtc) | |||
1007 | } | 1068 | } |
1008 | EXPORT_SYMBOL(drm_vblank_pre_modeset); | 1069 | EXPORT_SYMBOL(drm_vblank_pre_modeset); |
1009 | 1070 | ||
1071 | /** | ||
1072 | * drm_vblank_post_modeset - undo drm_vblank_pre_modeset changes | ||
1073 | * @dev: DRM device | ||
1074 | * @crtc: CRTC in question | ||
1075 | * | ||
1076 | * This function again drops the temporary vblank reference acquired in | ||
1077 | * drm_vblank_pre_modeset. | ||
1078 | */ | ||
1010 | void drm_vblank_post_modeset(struct drm_device *dev, int crtc) | 1079 | void drm_vblank_post_modeset(struct drm_device *dev, int crtc) |
1011 | { | 1080 | { |
1012 | unsigned long irqflags; | 1081 | unsigned long irqflags; |
@@ -1028,7 +1097,7 @@ void drm_vblank_post_modeset(struct drm_device *dev, int crtc) | |||
1028 | } | 1097 | } |
1029 | EXPORT_SYMBOL(drm_vblank_post_modeset); | 1098 | EXPORT_SYMBOL(drm_vblank_post_modeset); |
1030 | 1099 | ||
1031 | /** | 1100 | /* |
1032 | * drm_modeset_ctl - handle vblank event counter changes across mode switch | 1101 | * drm_modeset_ctl - handle vblank event counter changes across mode switch |
1033 | * @DRM_IOCTL_ARGS: standard ioctl arguments | 1102 | * @DRM_IOCTL_ARGS: standard ioctl arguments |
1034 | * | 1103 | * |
@@ -1141,7 +1210,7 @@ err_put: | |||
1141 | return ret; | 1210 | return ret; |
1142 | } | 1211 | } |
1143 | 1212 | ||
1144 | /** | 1213 | /* |
1145 | * Wait for VBLANK. | 1214 | * Wait for VBLANK. |
1146 | * | 1215 | * |
1147 | * \param inode device inode. | 1216 | * \param inode device inode. |
@@ -1152,7 +1221,7 @@ err_put: | |||
1152 | * | 1221 | * |
1153 | * This function enables the vblank interrupt on the pipe requested, then | 1222 | * This function enables the vblank interrupt on the pipe requested, then |
1154 | * sleeps waiting for the requested sequence number to occur, and drops | 1223 | * sleeps waiting for the requested sequence number to occur, and drops |
1155 | * the vblank interrupt refcount afterwards. (vblank irq disable follows that | 1224 | * the vblank interrupt refcount afterwards. (vblank IRQ disable follows that |
1156 | * after a timeout with no further vblank waits scheduled). | 1225 | * after a timeout with no further vblank waits scheduled). |
1157 | */ | 1226 | */ |
1158 | int drm_wait_vblank(struct drm_device *dev, void *data, | 1227 | int drm_wait_vblank(struct drm_device *dev, void *data, |