[PATCH v3 2/4] drm: Add device registration documentation
Daniel Vetter
daniel at ffwll.ch
Thu May 22 15:47:55 PDT 2014
On Thu, May 22, 2014 at 12:21:22PM +0200, Thierry Reding wrote:
> From: Thierry Reding <treding at nvidia.com>
>
> Describe how devices are registered using the drm_*_init() functions.
> Adding this to docbook requires a largish set of changes to the comments
> in drm_{pci,usb,platform}.c since they are doxygen-style rather than
> proper kernel-doc and therefore mess with the docbook generation.
>
> While at it, mark usage of drm_put_dev() as discouraged in favour of
> calling drm_dev_unregister() and drm_dev_unref() directly.
>
> Signed-off-by: Thierry Reding <treding at nvidia.com>
tbh not sure how much value this really provides, since most of these
should either be ripped out, moved somewhere else (e.g. the pcie speed cap
thing) or deprecated. Otoh pretty docs rarely hurt, so
Acked-by: Daniel Vetter <daniel.vetter at ffwll.ch>
since I didn't bother to review in-depth.
-Daniel
> ---
> Changes in v3:
> - add note that drm_put_dev() should not be used in new drivers
> - use !E to include all exported functions in DocBook
>
> Documentation/DocBook/drm.tmpl | 10 ++++++
> drivers/gpu/drm/drm_pci.c | 80 ++++++++++++++++++++----------------------
> drivers/gpu/drm/drm_platform.c | 15 ++++----
> drivers/gpu/drm/drm_stub.c | 22 ++++++------
> drivers/gpu/drm/drm_usb.c | 20 ++++++++++-
> 5 files changed, 85 insertions(+), 62 deletions(-)
>
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index ec81c20a17db..438edcd566b5 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -282,6 +282,16 @@ char *date;</synopsis>
> </sect3>
> </sect2>
> <sect2>
> + <title>Device Registration</title>
> + <para>
> + A number of functions are provided to help with device registration.
> + The functions deal with PCI, USB and platform devices, respectively.
> + </para>
> +!Edrivers/gpu/drm/drm_pci.c
> +!Edrivers/gpu/drm/drm_usb.c
> +!Edrivers/gpu/drm/drm_platform.c
> + </sect2>
> + <sect2>
> <title>Driver Load</title>
> <para>
> The <methodname>load</methodname> method is the driver and device
> diff --git a/drivers/gpu/drm/drm_pci.c b/drivers/gpu/drm/drm_pci.c
> index d237de36a07a..020cfd934854 100644
> --- a/drivers/gpu/drm/drm_pci.c
> +++ b/drivers/gpu/drm/drm_pci.c
> @@ -1,17 +1,3 @@
> -/* drm_pci.h -- PCI DMA memory management wrappers for DRM -*- linux-c -*- */
> -/**
> - * \file drm_pci.c
> - * \brief Functions and ioctls to manage PCI memory
> - *
> - * \warning These interfaces aren't stable yet.
> - *
> - * \todo Implement the remaining ioctl's for the PCI pools.
> - * \todo The wrappers here are so thin that they would be better off inlined..
> - *
> - * \author José Fonseca <jrfonseca at tungstengraphics.com>
> - * \author Leif Delgass <ldelgass at retinalburn.net>
> - */
> -
> /*
> * Copyright 2003 José Fonseca.
> * Copyright 2003 Leif Delgass.
> @@ -42,12 +28,14 @@
> #include <linux/export.h>
> #include <drm/drmP.h>
>
> -/**********************************************************************/
> -/** \name PCI memory */
> -/*@{*/
> -
> /**
> - * \brief Allocate a PCI consistent memory block, for DMA.
> + * drm_pci_alloc - Allocate a PCI consistent memory block, for DMA.
> + * @dev: DRM device
> + * @size: size of block to allocate
> + * @align: alignment of block
> + *
> + * Return: A handle to the allocated memory block on success or NULL on
> + * failure.
> */
> drm_dma_handle_t *drm_pci_alloc(struct drm_device * dev, size_t size, size_t align)
> {
> @@ -88,8 +76,8 @@ drm_dma_handle_t *drm_pci_alloc(struct drm_device * dev, size_t size, size_t ali
>
> EXPORT_SYMBOL(drm_pci_alloc);
>
> -/**
> - * \brief Free a PCI consistent memory block without freeing its descriptor.
> +/*
> + * Free a PCI consistent memory block without freeing its descriptor.
> *
> * This function is for internal use in the Linux-specific DRM core code.
> */
> @@ -111,7 +99,9 @@ void __drm_pci_free(struct drm_device * dev, drm_dma_handle_t * dmah)
> }
>
> /**
> - * \brief Free a PCI consistent memory block
> + * drm_pci_free - Free a PCI consistent memory block
> + * @dev: DRM device
> + * @dmah: handle to memory block
> */
> void drm_pci_free(struct drm_device * dev, drm_dma_handle_t * dmah)
> {
> @@ -226,17 +216,16 @@ static int drm_pci_irq_by_busid(struct drm_device *dev, struct drm_irq_busid *p)
> }
>
> /**
> - * Get interrupt from bus id.
> - *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument, pointing to a drm_irq_busid structure.
> - * \return zero on success or a negative number on failure.
> + * drm_irq_by_busid - Get interrupt from bus ID
> + * @dev: DRM device
> + * @data: IOCTL parameter pointing to a drm_irq_busid structure
> + * @file_priv: DRM file private.
> *
> * Finds the PCI device with the specified bus id and gets its IRQ number.
> * This IOCTL is deprecated, and will now return EINVAL for any busid not equal
> * to that of the device that this DRM instance attached to.
> + *
> + * Return: 0 on success or a negative error code on failure.
> */
> int drm_irq_by_busid(struct drm_device *dev, void *data,
> struct drm_file *file_priv)
> @@ -285,15 +274,16 @@ static struct drm_bus drm_pci_bus = {
> };
>
> /**
> - * Register.
> - *
> - * \param pdev - PCI device structure
> - * \param ent entry from the PCI ID table with device type flags
> - * \return zero on success or a negative number on failure.
> + * drm_get_pci_dev - Register a PCI device with the DRM subsystem
> + * @pdev: PCI device
> + * @ent: entry from the PCI ID table that matches @pdev
> + * @driver: DRM device driver
> *
> * Attempt to gets inter module "drm" information. If we are first
> * then register the character device and inter module information.
> * Try and register, if we fail to register, backout previous work.
> + *
> + * Return: 0 on success or a negative error code on failure.
> */
> int drm_get_pci_dev(struct pci_dev *pdev, const struct pci_device_id *ent,
> struct drm_driver *driver)
> @@ -346,15 +336,14 @@ err_free:
> EXPORT_SYMBOL(drm_get_pci_dev);
>
> /**
> - * PCI device initialization. Called direct from modules at load time.
> + * drm_pci_init - Register matching PCI devices with the DRM subsystem
> + * @driver: DRM device driver
> + * @pdriver: PCI device driver
> *
> - * \return zero on success or a negative number on failure.
> + * Initializes a drm_device structures, registering the stubs and initializing
> + * the AGP device.
> *
> - * Initializes a drm_device structures,registering the
> - * stubs and initializing the AGP device.
> - *
> - * Expands the \c DRIVER_PREINIT and \c DRIVER_POST_INIT macros before and
> - * after the initialization for driver customization.
> + * Return: 0 on success or a negative error code on failure.
> */
> int drm_pci_init(struct drm_driver *driver, struct pci_driver *pdriver)
> {
> @@ -458,7 +447,14 @@ int drm_pci_set_unique(struct drm_device *dev,
>
> EXPORT_SYMBOL(drm_pci_init);
>
> -/*@}*/
> +/**
> + * drm_pci_exit - Unregister matching PCI devices from the DRM subsystem
> + * @driver: DRM device driver
> + * @pdriver: PCI device driver
> + *
> + * Unregisters one or more devices matched by a PCI driver from the DRM
> + * subsystem.
> + */
> void drm_pci_exit(struct drm_driver *driver, struct pci_driver *pdriver)
> {
> struct drm_device *dev, *tmp;
> diff --git a/drivers/gpu/drm/drm_platform.c b/drivers/gpu/drm/drm_platform.c
> index 234e0bc1ae51..d5b76f148c12 100644
> --- a/drivers/gpu/drm/drm_platform.c
> +++ b/drivers/gpu/drm/drm_platform.c
> @@ -106,17 +106,16 @@ static struct drm_bus drm_platform_bus = {
> };
>
> /**
> - * Platform device initialization. Called direct from modules.
> + * drm_platform_init - Register a platform device with the DRM subsystem
> + * @driver: DRM device driver
> + * @platform_device: platform device to register
> *
> - * \return zero on success or a negative number on failure.
> - *
> - * Initializes a drm_device structures,registering the
> - * stubs
> + * Registers the specified DRM device driver and platform device with the DRM
> + * subsystem, initializing a drm_device structure and calling the driver's
> + * .load() function.
> *
> - * Expands the \c DRIVER_PREINIT and \c DRIVER_POST_INIT macros before and
> - * after the initialization for driver customization.
> + * Return: 0 on success or a negative error code on failure.
> */
> -
> int drm_platform_init(struct drm_driver *driver, struct platform_device *platform_device)
> {
> DRM_DEBUG("\n");
> diff --git a/drivers/gpu/drm/drm_stub.c b/drivers/gpu/drm/drm_stub.c
> index 6d55392376dd..14d16464000a 100644
> --- a/drivers/gpu/drm/drm_stub.c
> +++ b/drivers/gpu/drm/drm_stub.c
> @@ -1,16 +1,11 @@
> -/**
> - * \file drm_stub.h
> - * Stub support
> - *
> - * \author Rickard E. (Rik) Faith <faith at valinux.com>
> - */
> -
> /*
> * Created: Fri Jan 19 10:48:35 2001 by faith at acm.org
> *
> * Copyright 2001 VA Linux Systems, Inc., Sunnyvale, California.
> * All Rights Reserved.
> *
> + * Author Rickard E. (Rik) Faith <faith at valinux.com>
> + *
> * Permission is hereby granted, free of charge, to any person obtaining a
> * copy of this software and associated documentation files (the "Software"),
> * to deal in the Software without restriction, including without limitation
> @@ -425,11 +420,15 @@ void drm_minor_release(struct drm_minor *minor)
> }
>
> /**
> - * Called via drm_exit() at module unload time or when pci device is
> - * unplugged.
> + * drm_put_dev - Unregister and release a DRM device
> + * @dev: DRM device
> *
> - * Cleans up all DRM device, calling drm_lastclose().
> + * Called at module unload time or when a PCI device is unplugged.
> *
> + * Use of this function is discouraged. It will eventually go away completely.
> + * Please use drm_dev_unregister() and drm_dev_unref() explicitly instead.
> + *
> + * Cleans up all DRM device, calling drm_lastclose().
> */
> void drm_put_dev(struct drm_device *dev)
> {
> @@ -536,7 +535,7 @@ static void drm_fs_inode_free(struct inode *inode)
> }
>
> /**
> - * drm_dev_alloc - Allocate new drm device
> + * drm_dev_alloc - Allocate new DRM device
> * @driver: DRM driver to allocate device for
> * @parent: Parent device object
> *
> @@ -690,6 +689,7 @@ EXPORT_SYMBOL(drm_dev_unref);
> /**
> * drm_dev_register - Register DRM device
> * @dev: Device to register
> + * @flags: Flags passed to the driver's .load() function
> *
> * Register the DRM device @dev with the system, advertise device to user-space
> * and start normal device operation. @dev must be allocated via drm_dev_alloc()
> diff --git a/drivers/gpu/drm/drm_usb.c b/drivers/gpu/drm/drm_usb.c
> index c6c7c29ad46f..f2fe94aab901 100644
> --- a/drivers/gpu/drm/drm_usb.c
> +++ b/drivers/gpu/drm/drm_usb.c
> @@ -45,7 +45,17 @@ static int drm_usb_set_busid(struct drm_device *dev,
> static struct drm_bus drm_usb_bus = {
> .set_busid = drm_usb_set_busid,
> };
> -
> +
> +/**
> + * drm_usb_init - Register matching USB devices with the DRM subsystem
> + * @driver: DRM device driver
> + * @udriver: USB device driver
> + *
> + * Registers one or more devices matched by a USB driver with the DRM
> + * subsystem.
> + *
> + * Return: 0 on success or a negative error code on failure.
> + */
> int drm_usb_init(struct drm_driver *driver, struct usb_driver *udriver)
> {
> int res;
> @@ -58,6 +68,14 @@ int drm_usb_init(struct drm_driver *driver, struct usb_driver *udriver)
> }
> EXPORT_SYMBOL(drm_usb_init);
>
> +/**
> + * drm_usb_exit - Unregister matching USB devices from the DRM subsystem
> + * @driver: DRM device driver
> + * @udriver: USB device driver
> + *
> + * Unregisters one or more devices matched by a USB driver from the DRM
> + * subsystem.
> + */
> void drm_usb_exit(struct drm_driver *driver,
> struct usb_driver *udriver)
> {
> --
> 1.9.2
>
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
More information about the dri-devel
mailing list