From bb2eaba6458ace16f7e3504de8788374cb42b43d Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 31 May 2017 11:20:45 +0200 Subject: 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 Acked-by: Thierry Reding Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/20170531092045.3950-1-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-internals.rst | 2 ++ Documentation/gpu/drm-uapi.rst | 2 ++ drivers/gpu/drm/drm_file.c | 7 ++++++- drivers/gpu/drm/drm_ioctl.c | 5 ++++- include/drm/drm_drv.h | 18 ++++++++++++++++++ 5 files changed, 32 insertions(+), 2 deletions(-) diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index f6882ad0b3c3..bece92258647 100644 --- 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 858457567d3d..679373b4a03f 100644 --- 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 caad93dab54b..6631f61b66ca 100644 --- 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`. */ 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 aa49a2241404..3a36b3717c28 100644 --- 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` for how + * the driver-specific IOCTLs are wired up. */ /** diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h index e4de59bc52c8..f495eee01302 100644 --- 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` 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` for in-depth coverage and + * some examples. + */ const struct file_operations *fops; /* Everything below here is for legacy driver, never use! */ -- cgit v1.2.3