1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Open/Close, File Operations and IOCTLs</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="API-drm-crtc-vblank-waitqueue.html" title="drm_crtc_vblank_waitqueue"><link rel="next" href="ch02s09.html" title="Legacy Support Code"></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">Open/Close, File Operations and IOCTLs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-drm-crtc-vblank-waitqueue.html">Prev</a> </td><th width="60%" align="center">Chapter 2. DRM Internals</th><td width="20%" align="right"> <a accesskey="n" href="ch02s09.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1127640100"></a>Open/Close, File Operations and IOCTLs</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ch02s08.html#idp1127640468">Open and Close</a></span></dt><dt><span class="sect2"><a href="ch02s08.html#idp1127648684">File Operations</a></span></dt><dt><span class="sect2"><a href="ch02s08.html#idp1127655516">IOCTLs</a></span></dt></dl></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1127640468"></a>Open and Close</h3></div></div></div><pre class="synopsis">int (*firstopen) (struct drm_device *); 2void (*lastclose) (struct drm_device *); 3int (*open) (struct drm_device *, struct drm_file *); 4void (*preclose) (struct drm_device *, struct drm_file *); 5void (*postclose) (struct drm_device *, struct drm_file *);</pre><div class="abstract"><p class="title"><b>Abstract</b></p>Open and close handlers. None of those methods are mandatory. 6 </div><p> 7 The <code class="methodname">firstopen</code> method is called by the DRM core 8 for legacy UMS (User Mode Setting) drivers only when an application 9 opens a device that has no other opened file handle. UMS drivers can 10 implement it to acquire device resources. KMS drivers can't use the 11 method and must acquire resources in the <code class="methodname">load</code> 12 method instead. 13 </p><p> 14 Similarly the <code class="methodname">lastclose</code> method is called when 15 the last application holding a file handle opened on the device closes 16 it, for both UMS and KMS drivers. Additionally, the method is also 17 called at module unload time or, for hot-pluggable devices, when the 18 device is unplugged. The <code class="methodname">firstopen</code> and 19 <code class="methodname">lastclose</code> calls can thus be unbalanced. 20 </p><p> 21 The <code class="methodname">open</code> method is called every time the device 22 is opened by an application. Drivers can allocate per-file private data 23 in this method and store them in the struct 24 <span class="structname">drm_file</span> <em class="structfield"><code>driver_priv</code></em> 25 field. Note that the <code class="methodname">open</code> method is called 26 before <code class="methodname">firstopen</code>. 27 </p><p> 28 The close operation is split into <code class="methodname">preclose</code> and 29 <code class="methodname">postclose</code> methods. Drivers must stop and 30 cleanup all per-file operations in the <code class="methodname">preclose</code> 31 method. For instance pending vertical blanking and page flip events must 32 be cancelled. No per-file operation is allowed on the file handle after 33 returning from the <code class="methodname">preclose</code> method. 34 </p><p> 35 Finally the <code class="methodname">postclose</code> method is called as the 36 last step of the close operation, right before calling the 37 <code class="methodname">lastclose</code> method if no other open file handle 38 exists for the device. Drivers that have allocated per-file private data 39 in the <code class="methodname">open</code> method should free it here. 40 </p><p> 41 The <code class="methodname">lastclose</code> method should restore CRTC and 42 plane properties to default value, so that a subsequent open of the 43 device will not inherit state from the previous user. It can also be 44 used to execute delayed power switching state changes, e.g. in 45 conjunction with the vga-switcheroo infrastructure. Beyond that KMS 46 drivers should not do any further cleanup. Only legacy UMS drivers might 47 need to clean up device state so that the vga console or an independent 48 fbdev driver could take over. 49 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1127648684"></a>File Operations</h3></div></div></div><pre class="synopsis">const struct file_operations *fops</pre><div class="abstract"><p class="title"><b>Abstract</b></p>File operations for the DRM device node.</div><p> 50 Drivers must define the file operations structure that forms the DRM 51 userspace API entry point, even though most of those operations are 52 implemented in the DRM core. The <code class="methodname">open</code>, 53 <code class="methodname">release</code> and <code class="methodname">ioctl</code> 54 operations are handled by 55 </p><pre class="programlisting"> 56 .owner = THIS_MODULE, 57 .open = drm_open, 58 .release = drm_release, 59 .unlocked_ioctl = drm_ioctl, 60 #ifdef CONFIG_COMPAT 61 .compat_ioctl = drm_compat_ioctl, 62 #endif 63 </pre><p> 64 </p><p> 65 Drivers that implement private ioctls that requires 32/64bit 66 compatibility support must provide their own 67 <code class="methodname">compat_ioctl</code> handler that processes private 68 ioctls and calls <code class="function">drm_compat_ioctl</code> for core ioctls. 69 </p><p> 70 The <code class="methodname">read</code> and <code class="methodname">poll</code> 71 operations provide support for reading DRM events and polling them. They 72 are implemented by 73 </p><pre class="programlisting"> 74 .poll = drm_poll, 75 .read = drm_read, 76 .llseek = no_llseek, 77 </pre><p> 78 </p><p> 79 The memory mapping implementation varies depending on how the driver 80 manages memory. Pre-GEM drivers will use <code class="function">drm_mmap</code>, 81 while GEM-aware drivers will use <code class="function">drm_gem_mmap</code>. See 82 <a class="xref" href="drm-memory-management.html#drm-gem" title="The Graphics Execution Manager (GEM)">the section called “The Graphics Execution Manager (GEM)”</a>. 83 </p><pre class="programlisting"> 84 .mmap = drm_gem_mmap, 85 </pre><p> 86 </p><p> 87 No other file operation is supported by the DRM API. 88 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1127655516"></a>IOCTLs</h3></div></div></div><pre class="synopsis">struct drm_ioctl_desc *ioctls; 89int num_ioctls;</pre><div class="abstract"><p class="title"><b>Abstract</b></p>Driver-specific ioctls descriptors table.</div><p> 90 Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls 91 descriptors table is indexed by the ioctl number offset from the base 92 value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the 93 table entries. 94 </p><p> 95 </p><pre class="programlisting">DRM_IOCTL_DEF_DRV(ioctl, func, flags)</pre><p> 96 </p><p> 97 <em class="parameter"><code>ioctl</code></em> is the ioctl name. Drivers must define 98 the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number 99 offset from DRM_COMMAND_BASE and the ioctl number respectively. The 100 first macro is private to the device while the second must be exposed 101 to userspace in a public header. 102 </p><p> 103 </p><p> 104 <em class="parameter"><code>func</code></em> is a pointer to the ioctl handler function 105 compatible with the <span class="type">drm_ioctl_t</span> type. 106 </p><pre class="programlisting">typedef int drm_ioctl_t(struct drm_device *dev, void *data, 107 struct drm_file *file_priv);</pre><p> 108 </p><p> 109 </p><p> 110 <em class="parameter"><code>flags</code></em> is a bitmask combination of the following 111 values. It restricts how the ioctl is allowed to be called. 112 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 113 DRM_AUTH - Only authenticated callers allowed 114 </p></li><li class="listitem"><p> 115 DRM_MASTER - The ioctl can only be called on the master file 116 handle 117 </p></li><li class="listitem"><p> 118 DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed 119 </p></li><li class="listitem"><p> 120 DRM_CONTROL_ALLOW - The ioctl can only be called on a control 121 device 122 </p></li><li class="listitem"><p> 123 DRM_UNLOCKED - The ioctl handler will be called without locking 124 the DRM global mutex 125 </p></li></ul></div><p> 126 </p><p> 127 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-drm-crtc-vblank-waitqueue.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="ch02s09.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">drm_crtc_vblank_waitqueue</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Legacy Support Code</td></tr></table></div></body></html> 128