1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Vertical Blanking</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Linux DRM Developer's Guide"><link rel="up" href="drmInternals.html" title="Chapter 2. DRM Internals"><link rel="prev" href="drm-kms-properties.html" title="KMS Properties"><link rel="next" href="API-drm-vblank-cleanup.html" title="drm_vblank_cleanup"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Vertical Blanking</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="drm-kms-properties.html">Prev</a> </td><th width="60%" align="center">Chapter 2. DRM Internals</th><td width="20%" align="right"> <a accesskey="n" href="API-drm-vblank-cleanup.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="drm-vertical-blank"></a>Vertical Blanking</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="drm-vertical-blank.html#idp1127382092">Vertical Blanking and Interrupt Handling Functions Reference</a></span></dt></dl></div><p> 2 Vertical blanking plays a major role in graphics rendering. To achieve 3 tear-free display, users must synchronize page flips and/or rendering to 4 vertical blanking. The DRM API offers ioctls to perform page flips 5 synchronized to vertical blanking and wait for vertical blanking. 6 </p><p> 7 The DRM core handles most of the vertical blanking management logic, which 8 involves filtering out spurious interrupts, keeping race-free blanking 9 counters, coping with counter wrap-around and resets and keeping use 10 counts. It relies on the driver to generate vertical blanking interrupts 11 and optionally provide a hardware vertical blanking counter. Drivers must 12 implement the following operations. 13 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><pre class="synopsis">int (*enable_vblank) (struct drm_device *dev, int crtc); 14void (*disable_vblank) (struct drm_device *dev, int crtc);</pre><p> 15 Enable or disable vertical blanking interrupts for the given CRTC. 16 </p></li><li class="listitem"><pre class="synopsis">u32 (*get_vblank_counter) (struct drm_device *dev, int crtc);</pre><p> 17 Retrieve the value of the vertical blanking counter for the given 18 CRTC. If the hardware maintains a vertical blanking counter its value 19 should be returned. Otherwise drivers can use the 20 <code class="function">drm_vblank_count</code> helper function to handle this 21 operation. 22 </p></li></ul></div><p> 23 Drivers must initialize the vertical blanking handling core with a call to 24 <code class="function">drm_vblank_init</code> in their 25 <code class="methodname">load</code> operation. The function will set the struct 26 <span class="structname">drm_device</span> 27 <em class="structfield"><code>vblank_disable_allowed</code></em> field to 0. This will 28 keep vertical blanking interrupts enabled permanently until the first mode 29 set operation, where <em class="structfield"><code>vblank_disable_allowed</code></em> is 30 set to 1. The reason behind this is not clear. Drivers can set the field 31 to 1 after <code class="function">calling drm_vblank_init</code> to make vertical 32 blanking interrupts dynamically managed from the beginning. 33 </p><p> 34 Vertical blanking interrupts can be enabled by the DRM core or by drivers 35 themselves (for instance to handle page flipping operations). The DRM core 36 maintains a vertical blanking use count to ensure that the interrupts are 37 not disabled while a user still needs them. To increment the use count, 38 drivers call <code class="function">drm_vblank_get</code>. Upon return vertical 39 blanking interrupts are guaranteed to be enabled. 40 </p><p> 41 To decrement the use count drivers call 42 <code class="function">drm_vblank_put</code>. Only when the use count drops to zero 43 will the DRM core disable the vertical blanking interrupts after a delay 44 by scheduling a timer. The delay is accessible through the vblankoffdelay 45 module parameter or the <code class="varname">drm_vblank_offdelay</code> global 46 variable and expressed in milliseconds. Its default value is 5000 ms. 47 Zero means never disable, and a negative value means disable immediately. 48 Drivers may override the behaviour by setting the 49 <span class="structname">drm_device</span> 50 <em class="structfield"><code>vblank_disable_immediate</code></em> flag, which when set 51 causes vblank interrupts to be disabled immediately regardless of the 52 drm_vblank_offdelay value. The flag should only be set if there's a 53 properly working hardware vblank counter present. 54 </p><p> 55 When a vertical blanking interrupt occurs drivers only need to call the 56 <code class="function">drm_handle_vblank</code> function to account for the 57 interrupt. 58 </p><p> 59 Resources allocated by <code class="function">drm_vblank_init</code> must be freed 60 with a call to <code class="function">drm_vblank_cleanup</code> in the driver 61 <code class="methodname">unload</code> operation handler. 62 </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1127382092"></a>Vertical Blanking and Interrupt Handling Functions Reference</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-drm-vblank-cleanup.html"><span class="phrase">drm_vblank_cleanup</span></a></span><span class="refpurpose"> — 63 cleanup vblank support 64 </span></dt><dt><span class="refentrytitle"><a href="API-drm-vblank-init.html"><span class="phrase">drm_vblank_init</span></a></span><span class="refpurpose"> — 65 initialize vblank support 66 </span></dt><dt><span class="refentrytitle"><a href="API-drm-irq-install.html"><span class="phrase">drm_irq_install</span></a></span><span class="refpurpose"> — 67 install IRQ handler 68 </span></dt><dt><span class="refentrytitle"><a href="API-drm-irq-uninstall.html"><span class="phrase">drm_irq_uninstall</span></a></span><span class="refpurpose"> — 69 uninstall the IRQ handler 70 </span></dt><dt><span class="refentrytitle"><a href="API-drm-calc-timestamping-constants.html"><span class="phrase">drm_calc_timestamping_constants</span></a></span><span class="refpurpose"> — 71 calculate vblank timestamp constants 72 </span></dt><dt><span class="refentrytitle"><a href="API-drm-calc-vbltimestamp-from-scanoutpos.html"><span class="phrase">drm_calc_vbltimestamp_from_scanoutpos</span></a></span><span class="refpurpose"> — 73 precise vblank timestamp helper 74 </span></dt><dt><span class="refentrytitle"><a href="API-drm-vblank-count.html"><span class="phrase">drm_vblank_count</span></a></span><span class="refpurpose"> — 75 retrieve <span class="quote">“<span class="quote">cooked</span>”</span> vblank counter value 76 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-vblank-count.html"><span class="phrase">drm_crtc_vblank_count</span></a></span><span class="refpurpose"> — 77 retrieve <span class="quote">“<span class="quote">cooked</span>”</span> vblank counter value 78 </span></dt><dt><span class="refentrytitle"><a href="API-drm-vblank-count-and-time.html"><span class="phrase">drm_vblank_count_and_time</span></a></span><span class="refpurpose"> — 79 retrieve <span class="quote">“<span class="quote">cooked</span>”</span> vblank counter value and the system timestamp corresponding to that vblank counter value. 80 </span></dt><dt><span class="refentrytitle"><a href="API-drm-send-vblank-event.html"><span class="phrase">drm_send_vblank_event</span></a></span><span class="refpurpose"> — 81 helper to send vblank event after pageflip 82 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-send-vblank-event.html"><span class="phrase">drm_crtc_send_vblank_event</span></a></span><span class="refpurpose"> — 83 helper to send vblank event after pageflip 84 </span></dt><dt><span class="refentrytitle"><a href="API-drm-vblank-get.html"><span class="phrase">drm_vblank_get</span></a></span><span class="refpurpose"> — 85 get a reference count on vblank events 86 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-vblank-get.html"><span class="phrase">drm_crtc_vblank_get</span></a></span><span class="refpurpose"> — 87 get a reference count on vblank events 88 </span></dt><dt><span class="refentrytitle"><a href="API-drm-vblank-put.html"><span class="phrase">drm_vblank_put</span></a></span><span class="refpurpose"> — 89 give up ownership of vblank events 90 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-vblank-put.html"><span class="phrase">drm_crtc_vblank_put</span></a></span><span class="refpurpose"> — 91 give up ownership of vblank events 92 </span></dt><dt><span class="refentrytitle"><a href="API-drm-wait-one-vblank.html"><span class="phrase">drm_wait_one_vblank</span></a></span><span class="refpurpose"> — 93 wait for one vblank 94 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-wait-one-vblank.html"><span class="phrase">drm_crtc_wait_one_vblank</span></a></span><span class="refpurpose"> — 95 wait for one vblank 96 </span></dt><dt><span class="refentrytitle"><a href="API-drm-vblank-off.html"><span class="phrase">drm_vblank_off</span></a></span><span class="refpurpose"> — 97 disable vblank events on a CRTC 98 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-vblank-off.html"><span class="phrase">drm_crtc_vblank_off</span></a></span><span class="refpurpose"> — 99 disable vblank events on a CRTC 100 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-vblank-reset.html"><span class="phrase">drm_crtc_vblank_reset</span></a></span><span class="refpurpose"> — 101 reset vblank state to off on a CRTC 102 </span></dt><dt><span class="refentrytitle"><a href="API-drm-vblank-on.html"><span class="phrase">drm_vblank_on</span></a></span><span class="refpurpose"> — 103 enable vblank events on a CRTC 104 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-vblank-on.html"><span class="phrase">drm_crtc_vblank_on</span></a></span><span class="refpurpose"> — 105 enable vblank events on a CRTC 106 </span></dt><dt><span class="refentrytitle"><a href="API-drm-vblank-pre-modeset.html"><span class="phrase">drm_vblank_pre_modeset</span></a></span><span class="refpurpose"> — 107 account for vblanks across mode sets 108 </span></dt><dt><span class="refentrytitle"><a href="API-drm-vblank-post-modeset.html"><span class="phrase">drm_vblank_post_modeset</span></a></span><span class="refpurpose"> — 109 undo drm_vblank_pre_modeset changes 110 </span></dt><dt><span class="refentrytitle"><a href="API-drm-handle-vblank.html"><span class="phrase">drm_handle_vblank</span></a></span><span class="refpurpose"> — 111 handle a vblank event 112 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-handle-vblank.html"><span class="phrase">drm_crtc_handle_vblank</span></a></span><span class="refpurpose"> — 113 handle a vblank event 114 </span></dt><dt><span class="refentrytitle"><a href="API-drm-crtc-vblank-waitqueue.html"><span class="phrase">drm_crtc_vblank_waitqueue</span></a></span><span class="refpurpose"> — 115 get vblank waitqueue for the CRTC 116 </span></dt></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="drm-kms-properties.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="drmInternals.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-drm-vblank-cleanup.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">KMS Properties </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">drm_vblank_cleanup</span></td></tr></table></div></body></html> 117