summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2017-03-08 17:12:44 +0300
committerDaniel Vetter <daniel.vetter@ffwll.ch>2017-03-14 16:38:33 +0300
commitb93658f83fa7f89cde5cfba7158da2be8cac42b2 (patch)
treefd39bd7cc02e2d6f40734b252474c0265af3ab81 /Documentation
parent7d52cb88c9ca20c32288de6ed62b32410c936ccc (diff)
downloadlinux-b93658f83fa7f89cde5cfba7158da2be8cac42b2.tar.xz
drm/doc: Document drm_file.[hc]
Well, mostly drm_file.h, and clean up all related things: - I didnt' figure out the difference between preclose and postclose. The existing explanation in drm-internals.rst didn't convince me, since it's also really outdated - we clean up pending DRM events in the core nowadays. I put a FIXME in for the future. - Another FIXME is to have a macro for default fops. - Lots of links all around, main areas are to tie the overview in drm_file.c more into the callbacks in struct drm_device, and the other is to link render/primary node code to the right sections in drm-uapi.rst. - Also moved the open/close stuff to drm_drv.h from drm-internals.rst, seems like the better place for that information. Since that section was rather outdated this amounted to full-on rewrite. A big missing piece here is some overview graph, but I think better to wait with that one until drm_device and drm_driver are also fully documented. v2: Nits from Sean. Reviewed-by: Sean Paul <seanpaul@chromium.org> Reviewed-by: Liviu Dudau <Liviu.Dudau@arm.com> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Link: http://patchwork.freedesktop.org/patch/msgid/20170308141257.12119-12-daniel.vetter@ffwll.ch
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/gpu/drm-internals.rst52
-rw-r--r--Documentation/gpu/drm-uapi.rst4
2 files changed, 7 insertions, 49 deletions
diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst
index 3bb4d937cdfe..cbf8e52cd9bb 100644
--- a/Documentation/gpu/drm-internals.rst
+++ b/Documentation/gpu/drm-internals.rst
@@ -243,61 +243,15 @@ drivers.
Open/Close, File Operations and IOCTLs
======================================
-Open and Close
---------------
-
-Open and close handlers. None of those methods are mandatory::
-
- int (*firstopen) (struct drm_device *);
- void (*lastclose) (struct drm_device *);
- int (*open) (struct drm_device *, struct drm_file *);
- void (*preclose) (struct drm_device *, struct drm_file *);
- void (*postclose) (struct drm_device *, struct drm_file *);
-
-The firstopen method is called by the DRM core for legacy UMS (User Mode
-Setting) drivers only when an application opens a device that has no
-other opened file handle. UMS drivers can implement it to acquire device
-resources. KMS drivers can't use the method and must acquire resources
-in the load method instead.
-
-Similarly the lastclose method is called when the last application
-holding a file handle opened on the device closes it, for both UMS and
-KMS drivers. Additionally, the method is also called at module unload
-time or, for hot-pluggable devices, when the device is unplugged. The
-firstopen and lastclose calls can thus be unbalanced.
-
-The open method is called every time the device is opened by an
-application. Drivers can allocate per-file private data in this method
-and store them in the struct :c:type:`struct drm_file
-<drm_file>` driver_priv field. Note that the open method is
-called before firstopen.
-
-The close operation is split into preclose and postclose methods.
-Drivers must stop and cleanup all per-file operations in the preclose
-method. For instance pending vertical blanking and page flip events must
-be cancelled. No per-file operation is allowed on the file handle after
-returning from the preclose method.
-
-Finally the postclose method is called as the last step of the close
-operation, right before calling the lastclose method if no other open
-file handle exists for the device. Drivers that have allocated per-file
-private data in the open method should free it here.
-
-The lastclose method should restore CRTC and plane properties to default
-value, so that a subsequent open of the device will not inherit state
-from the previous user. It can also be used to execute delayed power
-switching state changes, e.g. in conjunction with the :ref:`vga_switcheroo`
-infrastructure. Beyond that KMS drivers should not do any
-further cleanup. Only legacy UMS drivers might need to clean up device
-state so that the vga console or an independent fbdev driver could take
-over.
-
File Operations
---------------
.. kernel-doc:: drivers/gpu/drm/drm_file.c
:doc: file operations
+.. kernel-doc:: include/drm/drm_file.h
+ :internal:
+
.. kernel-doc:: drivers/gpu/drm/drm_file.c
:export:
diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index fcc228ef5bc4..352652810dab 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -21,6 +21,8 @@ libdrm Device Lookup
:doc: getunique and setversion story
+.. _drm_primary_node:
+
Primary Nodes, DRM Master and Authentication
============================================
@@ -103,6 +105,8 @@ is already rather painful for the DRM subsystem, with multiple different uAPIs
for the same thing co-existing. If we add a few more complete mistakes into the
mix every year it would be entirely unmanageable.
+.. _drm_render_node:
+
Render nodes
============