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
This commit is contained in:
Daniel Vetter 2017-05-31 11:20:45 +02:00
parent 10631d724d
commit bb2eaba645
5 changed files with 32 additions and 2 deletions

View File

@ -198,6 +198,8 @@ drivers.
Open/Close, File Operations and IOCTLs
======================================
.. _drm_driver_fops:
File Operations
---------------

View File

@ -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
=============================

View File

@ -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);

View File

@ -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.
*/
/**

View File

@ -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! */