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

Commit Message

Daniel Vetter Jan. 9, 2023, 4:46 p.m. UTC

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 (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 <[e-mail]>
Reviewed-by: Melissa Wen <[e-mail]>
Reviewed-by: Maíra Canal <[e-mail]>
Acked-by: Maxime Ripard <[e-mail]>
Acked-by: Jani Nikula <[e-mail]>
Cc: Rodrigo Vivi <[e-mail]>
Cc: Wambui Karuga <[e-mail]>
Cc: Maíra Canal <[e-mail]>
Cc: Maxime Ripard <[e-mail]>
Cc: Melissa Wen <[e-mail]>
Signed-off-by: Daniel Vetter <[e-mail]>
---
 include/drm/drm_device.h | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

Patch

diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h
index a68c6a312b46..7cf4afae2e79 100644
--- 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;
 
 	/** @accel: Compute Acceleration node */