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
diff --git a/drivers/gpu/drm/drm_file.c b/drivers/gpu/drm/drm_file.c
index d9e63d7..92848fe 100644
--- a/drivers/gpu/drm/drm_file.c
+++ b/drivers/gpu/drm/drm_file.c
@@ -50,12 +50,14 @@ DEFINE_MUTEX(drm_global_mutex);
*
* Drivers must define the file operations structure that forms the DRM
* userspace API entry point, even though most of those operations are
- * implemented in the DRM core. The mandatory functions are drm_open(),
+ * implemented in the DRM core. The resulting &struct file_operations must be
+ * stored in the &drm_driver.fops field. The mandatory functions are drm_open(),
* drm_read(), drm_ioctl() and drm_compat_ioctl() if CONFIG_COMPAT is enabled
- * (note that drm_compat_ioctl will be NULL if CONFIG_COMPAT=n). Drivers which
- * implement private ioctls that require 32/64 bit compatibility support must
- * provide their own .compat_ioctl() handler that processes private ioctls and
- * calls drm_compat_ioctl() for core ioctls.
+ * Note that drm_compat_ioctl will be NULL if CONFIG_COMPAT=n, so there's no
+ * need to sprinkle #ifdef into the code. Drivers which implement private ioctls
+ * that require 32/64 bit compatibility support must provide their own
+ * &file_operations.compat_ioctl handler that processes private ioctls and calls
+ * drm_compat_ioctl() for core ioctls.
*
* In addition drm_read() and drm_poll() provide support for DRM events. DRM
* events are a generic and extensible means to send asynchronous events to
@@ -63,10 +65,14 @@ DEFINE_MUTEX(drm_global_mutex);
* page flip completions by the KMS API. But drivers can also use it for their
* own needs, e.g. to signal completion of rendering.
*
+ * For the driver-side event interface see drm_event_reserve_init() and
+ * drm_send_event() as the main starting points.
+ *
* The memory mapping implementation will vary depending on how the driver
* manages memory. Legacy drivers will use the deprecated drm_legacy_mmap()
* function, modern drivers should use one of the provided memory-manager
- * specific implementations. For GEM-based drivers this is drm_gem_mmap().
+ * specific implementations. For GEM-based drivers this is drm_gem_mmap(), and
+ * for drivers which use the CMA GEM helpers it's drm_gem_cma_mmap().
*
* No other file operations are supported by the DRM userspace API. Overall the
* following is an example #file_operations structure::
@@ -82,6 +88,9 @@ DEFINE_MUTEX(drm_global_mutex);
* .llseek = no_llseek,
* .mmap = drm_gem_mmap,
* };
+ *
+ * FIXME: We should have a macro for this (and the CMA version) so that drivers
+ * don't have to repeat it all the time.
*/
static int drm_open_helper(struct file *filp, struct drm_minor *minor);
@@ -111,9 +120,9 @@ static int drm_setup(struct drm_device * dev)
* @inode: device inode
* @filp: file pointer.
*
- * This function must be used by drivers as their .open() #file_operations
- * method. It looks up the correct DRM device and instantiates all the per-file
- * resources for it.
+ * This function must be used by drivers as their &file_operations.open method.
+ * It looks up the correct DRM device and instantiates all the per-file
+ * resources for it. It also calls the &drm_driver.open driver callback.
*
* RETURNS:
*
@@ -298,11 +307,6 @@ static void drm_events_release(struct drm_file *file_priv)
spin_unlock_irqrestore(&dev->event_lock, flags);
}
-/*
- * drm_legacy_dev_reinit
- *
- * Reinitializes a legacy/ums drm device in it's lastclose function.
- */
static void drm_legacy_dev_reinit(struct drm_device *dev)
{
if (dev->irq_enabled)
@@ -327,15 +331,6 @@ static void drm_legacy_dev_reinit(struct drm_device *dev)
DRM_DEBUG("lastclose completed\n");
}
-/*
- * Take down the DRM device.
- *
- * \param dev DRM device structure.
- *
- * Frees every resource in \p dev.
- *
- * \sa drm_device
- */
void drm_lastclose(struct drm_device * dev)
{
DRM_DEBUG("\n");
@@ -353,9 +348,11 @@ void drm_lastclose(struct drm_device * dev)
* @inode: device inode
* @filp: file pointer.
*
- * This function must be used by drivers as their .release() #file_operations
- * method. It frees any resources associated with the open file, and if this is
- * the last open file for the DRM device also proceeds to call drm_lastclose().
+ * This function must be used by drivers as their &file_operations.release
+ * method. It frees any resources associated with the open file, and calls the
+ * &drm_driver.preclose and &drm_driver.lastclose driver callbacks. If this is
+ * the last open file for the DRM device also proceeds to call the
+ * &drm_driver.lastclose driver callback.
*
* RETURNS:
*
@@ -443,13 +440,13 @@ EXPORT_SYMBOL(drm_release);
* @count: count in bytes to read
* @offset: offset to read
*
- * This function must be used by drivers as their .read() #file_operations
+ * This function must be used by drivers as their &file_operations.read
* method iff they use DRM events for asynchronous signalling to userspace.
* Since events are used by the KMS API for vblank and page flip completion this
* means all modern display drivers must use it.
*
- * @offset is ignore, DRM events are read like a pipe. Therefore drivers also
- * must set the .llseek() #file_operation to no_llseek(). Polling support is
+ * @offset is ignored, DRM events are read like a pipe. Therefore drivers also
+ * must set the &file_operation.llseek to no_llseek(). Polling support is
* provided by drm_poll().
*
* This function will only ever read a full event. Therefore userspace must
@@ -537,10 +534,10 @@ EXPORT_SYMBOL(drm_read);
* @filp: file pointer
* @wait: poll waiter table
*
- * This function must be used by drivers as their .read() #file_operations
- * method iff they use DRM events for asynchronous signalling to userspace.
- * Since events are used by the KMS API for vblank and page flip completion this
- * means all modern display drivers must use it.
+ * This function must be used by drivers as their &file_operations.read method
+ * iff they use DRM events for asynchronous signalling to userspace. Since
+ * events are used by the KMS API for vblank and page flip completion this means
+ * all modern display drivers must use it.
*
* See also drm_read().
*
@@ -650,7 +647,8 @@ EXPORT_SYMBOL(drm_event_reserve_init);
* @p: tracking structure for the pending event
*
* This function frees the event @p initialized with drm_event_reserve_init()
- * and releases any allocated space.
+ * and releases any allocated space. It is used to cancel an event when the
+ * nonblocking operation could not be submitted and needed to be aborted.
*/
void drm_event_cancel_free(struct drm_device *dev,
struct drm_pending_event *p)