drm/doc: Improve ioctl/fops docs a bit more

I spotted a markup issue, plus adding the descriptions in drm_driver.
Plus a few more links while at it.

I'm still mildly unhappy with the split between fops and ioctls, but I
still think having the ioctls in the uapi chapter makes more sense. Oh
well ...

v2: Rebase.

v3: Move misplace hunk to the right patch.

Cc: Stefan Agner <stefan@agner.ch>
Acked-by: Thierry Reding <treding@nvidia.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170531092045.3950-1-daniel.vetter@ffwll.ch

diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst
index f6882ad0b3c39ddbc992b3e814a541ef932ba768..bece92258647d1139f544126b238915bf565eb77 100644 (file)
--- a/Documentation/gpu/drm-internals.rst
+++ b/Documentation/gpu/drm-internals.rst
@@ -198,6 +198,8 @@ drivers.
 Open/Close, File Operations and IOCTLs
 ======================================
 
+.. _drm_driver_fops:
+
 File Operations
 ---------------
 

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 858457567d3df7460ab7074de88d82e24b8fab8e..679373b4a03f2189e14cce4c30686bdc947eb5a1 100644 (file)
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -160,6 +160,8 @@ other hand, a driver requires shared state between clients which is
 visible to user-space and accessible beyond open-file boundaries, they
 cannot support render nodes.
 
+.. _drm_driver_ioctl:
+
 IOCTL Support on Device Nodes
 =============================
 

diff --git a/drivers/gpu/drm/drm_file.c b/drivers/gpu/drm/drm_file.c
index caad93dab54bb3c72c9105af2025220aea47e1b1..6631f61b66ca78c1642b333832aff2eea2c277b0 100644 (file)
--- a/drivers/gpu/drm/drm_file.c
+++ b/drivers/gpu/drm/drm_file.c
@@ -75,7 +75,7 @@ DEFINE_MUTEX(drm_global_mutex);
  * 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::
+ * following is an example &file_operations structure::
  *
  *     static const example_drm_fops = {
  *             .owner = THIS_MODULE,
@@ -92,6 +92,11 @@ DEFINE_MUTEX(drm_global_mutex);
  * For plain GEM based drivers there is the DEFINE_DRM_GEM_FOPS() macro, and for
  * CMA based drivers there is the DEFINE_DRM_GEM_CMA_FOPS() macro to make this
  * simpler.
+ *
+ * The driver's &file_operations must be stored in &drm_driver.fops.
+ *
+ * For driver-private IOCTL handling see the more detailed discussion in
+ * :ref:`IOCTL support in the userland interfaces chapter<drm_driver_ioctl>`.
  */
 
 static int drm_open_helper(struct file *filp, struct drm_minor *minor);

diff --git a/drivers/gpu/drm/drm_ioctl.c b/drivers/gpu/drm/drm_ioctl.c
index aa49a2241404b328db1ae5e5d4a457718606289a..3a36b3717c2808a34cf0fde46c2bffe3f0e705e9 100644 (file)
--- a/drivers/gpu/drm/drm_ioctl.c
+++ b/drivers/gpu/drm/drm_ioctl.c
@@ -683,7 +683,7 @@ static const struct drm_ioctl_desc drm_ioctls[] = {
  * 
  * DRM driver private IOCTL must be in the range from DRM_COMMAND_BASE to
  * DRM_COMMAND_END. Finally you need an array of &struct drm_ioctl_desc to wire
- * up the handlers and set the access rights:
+ * up the handlers and set the access rights::
  *
  *     static const struct drm_ioctl_desc my_driver_ioctls[] = {
  *         DRM_IOCTL_DEF_DRV(MY_DRIVER_OPERATION, my_driver_operation,
@@ -692,6 +692,9 @@ static const struct drm_ioctl_desc drm_ioctls[] = {
  *
  * And then assign this to the &drm_driver.ioctls field in your driver
  * structure.
+ *
+ * See the separate chapter on :ref:`file operations<drm_driver_fops>` for how
+ * the driver-specific IOCTLs are wired up.
  */
 
 /**

diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
index e4de59bc52c8f6aa8094beb6453733d8472c5793..f495eee013029850fe0f54825d2466586e3d60bc 100644 (file)
--- a/include/drm/drm_drv.h
+++ b/include/drm/drm_drv.h
@@ -515,8 +515,26 @@ struct drm_driver {
        char *date;
 
        u32 driver_features;
+
+       /**
+        * @ioctls:
+        *
+        * Array of driver-private IOCTL description entries. See the chapter on
+        * :ref:`IOCTL support in the userland interfaces
+        * chapter<drm_driver_ioctl>` for the full details.
+        */
+
        const struct drm_ioctl_desc *ioctls;
+       /** @num_ioctls: Number of entries in @ioctls. */
        int num_ioctls;
+
+       /**
+        * @fops:
+        *
+        * File operations for the DRM device node. See the discussion in
+        * :ref:`file operations<drm_driver_fops>` for in-depth coverage and
+        * some examples.
+        */
        const struct file_operations *fops;
 
        /* Everything below here is for legacy driver, never use! */