Commit bb2eaba6 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

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: default avatarThierry Reding <treding@nvidia.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170531092045.3950-1-daniel.vetter@ffwll.ch
parent 10631d72

Documentation/gpu/drm-internals.rst

+2 −0
Original line number Diff line number Diff line
@@ -198,6 +198,8 @@ drivers. 
Open/Close, File Operations and IOCTLs

======================================



.. _drm_driver_fops:



File Operations

---------------

Documentation/gpu/drm-uapi.rst

+2 −0
Original line number Diff line number Diff line
@@ -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

=============================

drivers/gpu/drm/drm_file.c

+6 −1
Original line number Diff line number Diff line
@@ -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);

drivers/gpu/drm/drm_ioctl.c

+4 −1
Original line number Diff line number Diff line
@@ -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.

 */



/**

include/drm/drm_drv.h

+18 −0
Original line number Diff line number Diff line
@@ -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! */

CRA Git | Maintained and supported by SUSTech CRA and CCSE