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

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)