Message ID | 1399995050-28435-7-git-send-email-thierry.reding@gmail.com (mailing list archive) |
---|---|
State | New, archived |
Headers | show |
On Tue, May 13, 2014 at 05:30:49PM +0200, Thierry Reding wrote: > From: Thierry Reding <treding@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. > > Signed-off-by: Thierry Reding <treding@nvidia.com> > --- > Documentation/DocBook/drm.tmpl | 9 +++++ > drivers/gpu/drm/drm_pci.c | 80 ++++++++++++++++++++---------------------- > drivers/gpu/drm/drm_platform.c | 15 ++++---- > drivers/gpu/drm/drm_stub.c | 19 +++++----- > drivers/gpu/drm/drm_usb.c | 20 ++++++++++- > 5 files changed, 81 insertions(+), 62 deletions(-) > > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl > index f4028c3a28a2..f26a8e4fbe47 100644 > --- a/Documentation/DocBook/drm.tmpl > +++ b/Documentation/DocBook/drm.tmpl > @@ -282,6 +282,15 @@ 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> > +!Fdrivers/gpu/drm/drm_pci.c drm_pci_init drm_pci_exit > +!Fdrivers/gpu/drm/drm_usb.c drm_usb_init drm_usb_exit > +!Fdrivers/gpu/drm/drm_platform.c drm_platform_init Generally I prefer to use !E to pull in all exported functions - those are the ones driver authors care about. And using this has the upside that if anyone renames them or adds/removes some it will be kept in sync automatically. Same for the next patch. -Daniel > + <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@tungstengraphics.com> > - * \author Leif Delgass <ldelgass@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 64cf97dc4ce4..88bada850b71 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@valinux.com> > - */ > - > /* > * Created: Fri Jan 19 10:48:35 2001 by faith@acm.org > * > * Copyright 2001 VA Linux Systems, Inc., Sunnyvale, California. > * All Rights Reserved. > * > + * Author Rickard E. (Rik) Faith <faith@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 > @@ -424,11 +419,12 @@ 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. > * > + * Cleans up all DRM device, calling drm_lastclose(). > */ > void drm_put_dev(struct drm_device *dev) > { > @@ -558,7 +554,7 @@ int drm_set_unique(struct drm_device *dev, const char *fmt, ...) > EXPORT_SYMBOL(drm_set_unique); > > /** > - * 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 > * > @@ -712,6 +708,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 >
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index f4028c3a28a2..f26a8e4fbe47 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -282,6 +282,15 @@ 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> +!Fdrivers/gpu/drm/drm_pci.c drm_pci_init drm_pci_exit +!Fdrivers/gpu/drm/drm_usb.c drm_usb_init drm_usb_exit +!Fdrivers/gpu/drm/drm_platform.c drm_platform_init + <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@tungstengraphics.com> - * \author Leif Delgass <ldelgass@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 64cf97dc4ce4..88bada850b71 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@valinux.com> - */ - /* * Created: Fri Jan 19 10:48:35 2001 by faith@acm.org * * Copyright 2001 VA Linux Systems, Inc., Sunnyvale, California. * All Rights Reserved. * + * Author Rickard E. (Rik) Faith <faith@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 @@ -424,11 +419,12 @@ 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. * + * Cleans up all DRM device, calling drm_lastclose(). */ void drm_put_dev(struct drm_device *dev) { @@ -558,7 +554,7 @@ int drm_set_unique(struct drm_device *dev, const char *fmt, ...) EXPORT_SYMBOL(drm_set_unique); /** - * 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 * @@ -712,6 +708,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) {