drm: document better that drivers shouldn't use drm_minor directly

The documentation for struct drm_minor already states this, but that's
not always that easy to find.

Also due to historical reasons we still have the minor-centric
interfaces (like drm_debugfs_create_files), but since this is now
getting fixed we can put a few more pointers in place as to how this
should be done ideally. Note that debugfs isn't there yet for all
cases (debugfs files on kms objects like crtc/connector aren't
supported, neither debugfs files with full fops), so the debugfs side
of this is still rather aspirational and more for new users than
converting everything existing. todo.rst covers the additional work
needed already.

Motivated by some discussion with Rodrigo on irc about how drm/xe
should lay out its sysfs interfaces.

v2: Make the debugfs situation clearer in the commit message, but
don't elaborate more in the actual kerneldoc to avoid distracting from
the main message around sysfs (Jani)

Also fix some typos.

Acked-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Reviewed-by: Melissa Wen <mwen@igalia.com>
Reviewed-by: Maíra Canal <mcanal@igalia.com>
Acked-by: Maxime Ripard <maxime@cerno.tech>
Acked-by: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
Cc: Wambui Karuga <wambui.karugax@gmail.com>
Cc: Maíra Canal <mcanal@igalia.com>
Cc: Maxime Ripard <maxime@cerno.tech>
Cc: Melissa Wen <mwen@igalia.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20230109164604.3860862-1-daniel.vetter@ffwll.ch

diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h
index fa6af1d..282a171 100644 (file)
--- a/include/drm/drm_device.h
+++ b/include/drm/drm_device.h
@@ -87,10 +87,23 @@ struct drm_device {
         */
        void *dev_private;
 
-       /** @primary: Primary node */
+       /**
+        * @primary:
+        *
+        * Primary node. Drivers should not interact with this
+        * directly. debugfs interfaces can be registered with
+        * drm_debugfs_add_file(), and sysfs should be directly added on the
+        * hardware (and not character device node) struct device @dev.
+        */
        struct drm_minor *primary;
 
-       /** @render: Render node */
+       /**
+        * @render:
+        *
+        * Render node. Drivers should not interact with this directly ever.
+        * Drivers should not expose any additional interfaces in debugfs or
+        * sysfs on this node.
+        */
        struct drm_minor *render;
 
        /**