summaryrefslogtreecommitdiff
path: root/include/drm/drm_drv.h
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2017-03-08 15:12:44 +0100
committerDaniel Vetter <daniel.vetter@ffwll.ch>2017-03-14 14:38:33 +0100
commitb93658f83fa7f89cde5cfba7158da2be8cac42b2 (patch)
treefd39bd7cc02e2d6f40734b252474c0265af3ab81 /include/drm/drm_drv.h
parent7d52cb88c9ca20c32288de6ed62b32410c936ccc (diff)
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 'include/drm/drm_drv.h')
-rw-r--r--include/drm/drm_drv.h81
1 files changed, 80 insertions, 1 deletions
diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
index 4321d012c4ba..8f900fb30275 100644
--- a/include/drm/drm_drv.h
+++ b/include/drm/drm_drv.h
@@ -64,7 +64,6 @@ struct drm_mode_create_dumb;
* structure for GEM drivers.
*/
struct drm_driver {
-
/**
* @load:
*
@@ -76,14 +75,94 @@ struct drm_driver {
* See drm_dev_init() and drm_dev_register() for proper and
* race-free way to set up a &struct drm_device.
*
+ * This is deprecated, do not use!
+ *
* Returns:
*
* Zero on success, non-zero value on failure.
*/
int (*load) (struct drm_device *, unsigned long flags);
+
+ /**
+ * @open:
+ *
+ * Driver callback when a new &struct drm_file is opened. Useful for
+ * setting up driver-private data structures like buffer allocators,
+ * execution contexts or similar things. Such driver-private resources
+ * must be released again in @postclose.
+ *
+ * Since the display/modeset side of DRM can only be owned by exactly
+ * one &struct drm_file (see &drm_file.is_master and &drm_device.master)
+ * there should never be a need to set up any modeset related resources
+ * in this callback. Doing so would be a driver design bug.
+ *
+ * Returns:
+ *
+ * 0 on success, a negative error code on failure, which will be
+ * promoted to userspace as the result of the open() system call.
+ */
int (*open) (struct drm_device *, struct drm_file *);
+
+ /**
+ * @preclose:
+ *
+ * One of the driver callbacks when a new &struct drm_file is closed.
+ * Useful for tearing down driver-private data structures allocated in
+ * @open like buffer allocators, execution contexts or similar things.
+ *
+ * Since the display/modeset side of DRM can only be owned by exactly
+ * one &struct drm_file (see &drm_file.is_master and &drm_device.master)
+ * there should never be a need to tear down any modeset related
+ * resources in this callback. Doing so would be a driver design bug.
+ *
+ * FIXME: It is not really clear why there's both @preclose and
+ * @postclose. Without a really good reason, use @postclose only.
+ */
void (*preclose) (struct drm_device *, struct drm_file *file_priv);
+
+ /**
+ * @postclose:
+ *
+ * One of the driver callbacks when a new &struct drm_file is closed.
+ * Useful for tearing down driver-private data structures allocated in
+ * @open like buffer allocators, execution contexts or similar things.
+ *
+ * Since the display/modeset side of DRM can only be owned by exactly
+ * one &struct drm_file (see &drm_file.is_master and &drm_device.master)
+ * there should never be a need to tear down any modeset related
+ * resources in this callback. Doing so would be a driver design bug.
+ *
+ * FIXME: It is not really clear why there's both @preclose and
+ * @postclose. Without a really good reason, use @postclose only.
+ */
void (*postclose) (struct drm_device *, struct drm_file *);
+
+ /**
+ * @lastclose:
+ *
+ * Called when the last &struct drm_file has been closed and there's
+ * currently no userspace client for the &struct drm_device.
+ *
+ * Modern drivers should only use this to force-restore the fbdev
+ * framebuffer using drm_fb_helper_restore_fbdev_mode_unlocked().
+ * Anything else would indicate there's something seriously wrong.
+ * Modern drivers can also use this to execute delayed power switching
+ * state changes, e.g. in conjunction with the :ref:`vga_switcheroo`
+ * infrastructure.
+ *
+ * This is called after @preclose and @postclose have been called.
+ *
+ * NOTE:
+ *
+ * All legacy drivers use this callback to de-initialize the hardware.
+ * This is purely because of the shadow-attach model, where the DRM
+ * kernel driver does not really own the hardware. Instead ownershipe is
+ * handled with the help of userspace through an inheritedly racy dance
+ * to set/unset the VT into raw mode.
+ *
+ * Legacy drivers initialize the hardware in the @firstopen callback,
+ * which isn't even called for modern drivers.
+ */
void (*lastclose) (struct drm_device *);
/**