1<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><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 GPU Driver 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="API-drm-noop.html" title="drm_noop"></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="API-drm-noop.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id-1.3.4.12"></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#id-1.3.4.12.2">Open and Close</a></span></dt><dt><span class="sect2"><a href="ch02s08.html#id-1.3.4.12.3">File Operations</a></span></dt><dt><span class="sect2"><a href="ch02s08.html#id-1.3.4.12.4">IOCTLs</a></span></dt></dl></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="id-1.3.4.12.2"></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 (see 46 <a class="xref" href="vga_switcheroo.html" title="Part III. vga_switcheroo">Part III, “vga_switcheroo”</a>). Beyond that KMS drivers should not 47 do any further cleanup. Only legacy UMS drivers might need to clean up 48 device state so that the vga console or an independent fbdev driver 49 could take over. 50 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="id-1.3.4.12.3"></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> 51 Drivers must define the file operations structure that forms the DRM 52 userspace API entry point, even though most of those operations are 53 implemented in the DRM core. The <code class="methodname">open</code>, 54 <code class="methodname">release</code> and <code class="methodname">ioctl</code> 55 operations are handled by 56 </p><pre class="programlisting"> 57 .owner = THIS_MODULE, 58 .open = drm_open, 59 .release = drm_release, 60 .unlocked_ioctl = drm_ioctl, 61 #ifdef CONFIG_COMPAT 62 .compat_ioctl = drm_compat_ioctl, 63 #endif 64 </pre><p> 65 </p><p> 66 Drivers that implement private ioctls that requires 32/64bit 67 compatibility support must provide their own 68 <code class="methodname">compat_ioctl</code> handler that processes private 69 ioctls and calls <code class="function">drm_compat_ioctl</code> for core ioctls. 70 </p><p> 71 The <code class="methodname">read</code> and <code class="methodname">poll</code> 72 operations provide support for reading DRM events and polling them. They 73 are implemented by 74 </p><pre class="programlisting"> 75 .poll = drm_poll, 76 .read = drm_read, 77 .llseek = no_llseek, 78 </pre><p> 79 </p><p> 80 The memory mapping implementation varies depending on how the driver 81 manages memory. Pre-GEM drivers will use <code class="function">drm_mmap</code>, 82 while GEM-aware drivers will use <code class="function"><a class="link" href="API-drm-gem-mmap.html" title="drm_gem_mmap">drm_gem_mmap</a></code>. See 83 <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>. 84 </p><pre class="programlisting"> 85 .mmap = drm_gem_mmap, 86 </pre><p> 87 </p><p> 88 No other file operation is supported by the DRM API. 89 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="id-1.3.4.12.4"></a>IOCTLs</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-drm-noop.html"><span class="phrase">drm_noop</span></a></span><span class="refpurpose"> — 90 DRM no-op ioctl implemntation 91 </span></dt><dt><span class="refentrytitle"><a href="API-drm-invalid-op.html"><span class="phrase">drm_invalid_op</span></a></span><span class="refpurpose"> — 92 DRM invalid ioctl implemntation 93 </span></dt><dt><span class="refentrytitle"><a href="API-drm-ioctl.html"><span class="phrase">drm_ioctl</span></a></span><span class="refpurpose"> — 94 ioctl callback implementation for DRM drivers 95 </span></dt><dt><span class="refentrytitle"><a href="API-drm-ioctl-flags.html"><span class="phrase">drm_ioctl_flags</span></a></span><span class="refpurpose"> — 96 Check for core ioctl and return ioctl permission flags 97 </span></dt></dl></div><pre class="synopsis">struct drm_ioctl_desc *ioctls; 98int num_ioctls;</pre><div class="abstract"><p class="title"><b>Abstract</b></p>Driver-specific ioctls descriptors table.</div><p> 99 Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls 100 descriptors table is indexed by the ioctl number offset from the base 101 value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the 102 table entries. 103 </p><p> 104 </p><pre class="programlisting">DRM_IOCTL_DEF_DRV(ioctl, func, flags)</pre><p> 105 </p><p> 106 <em class="parameter"><code>ioctl</code></em> is the ioctl name. Drivers must define 107 the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number 108 offset from DRM_COMMAND_BASE and the ioctl number respectively. The 109 first macro is private to the device while the second must be exposed 110 to userspace in a public header. 111 </p><p> 112 </p><p> 113 <em class="parameter"><code>func</code></em> is a pointer to the ioctl handler function 114 compatible with the <span class="type">drm_ioctl_t</span> type. 115 </p><pre class="programlisting">typedef int drm_ioctl_t(struct drm_device *dev, void *data, 116 struct drm_file *file_priv);</pre><p> 117 </p><p> 118 </p><p> 119 <em class="parameter"><code>flags</code></em> is a bitmask combination of the following 120 values. It restricts how the ioctl is allowed to be called. 121 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 122 DRM_AUTH - Only authenticated callers allowed 123 </p></li><li class="listitem"><p> 124 DRM_MASTER - The ioctl can only be called on the master file 125 handle 126 </p></li><li class="listitem"><p> 127 DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed 128 </p></li><li class="listitem"><p> 129 DRM_CONTROL_ALLOW - The ioctl can only be called on a control 130 device 131 </p></li><li class="listitem"><p> 132 DRM_UNLOCKED - The ioctl handler will be called without locking 133 the DRM global mutex. This is the enforced default for kms drivers 134 (i.e. using the DRIVER_MODESET flag) and hence shouldn't be used 135 any more for new drivers. 136 </p></li></ul></div><p> 137 </p><p> 138 </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="API-drm-noop.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"> <span class="phrase">drm_noop</span></td></tr></table></div></body></html> 139