Commit c6a1af8a authored by Thierry Reding's avatar Thierry Reding

drm: Add device registration documentation

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.
Acked-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: default avatarThierry Reding <treding@nvidia.com>
parent ca8e2ad7
...@@ -281,6 +281,16 @@ char *date;</synopsis> ...@@ -281,6 +281,16 @@ char *date;</synopsis>
</para> </para>
</sect3> </sect3>
</sect2> </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> <sect2>
<title>Driver Load</title> <title>Driver Load</title>
<para> <para>
......
/* 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 José Fonseca.
* Copyright 2003 Leif Delgass. * Copyright 2003 Leif Delgass.
...@@ -42,12 +28,14 @@ ...@@ -42,12 +28,14 @@
#include <linux/export.h> #include <linux/export.h>
#include <drm/drmP.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) 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 ...@@ -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); 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. * 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) ...@@ -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) 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) ...@@ -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. * drm_irq_by_busid - Get interrupt from bus ID
* * @dev: DRM device
* \param inode device inode. * @data: IOCTL parameter pointing to a drm_irq_busid structure
* \param file_priv DRM file private. * @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.
* *
* Finds the PCI device with the specified bus id and gets its IRQ number. * 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 * 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. * 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, int drm_irq_by_busid(struct drm_device *dev, void *data,
struct drm_file *file_priv) struct drm_file *file_priv)
...@@ -285,15 +274,16 @@ static struct drm_bus drm_pci_bus = { ...@@ -285,15 +274,16 @@ static struct drm_bus drm_pci_bus = {
}; };
/** /**
* Register. * drm_get_pci_dev - Register a PCI device with the DRM subsystem
* * @pdev: PCI device
* \param pdev - PCI device structure * @ent: entry from the PCI ID table that matches @pdev
* \param ent entry from the PCI ID table with device type flags * @driver: DRM device driver
* \return zero on success or a negative number on failure.
* *
* Attempt to gets inter module "drm" information. If we are first * Attempt to gets inter module "drm" information. If we are first
* then register the character device and inter module information. * then register the character device and inter module information.
* Try and register, if we fail to register, backout previous work. * 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, int drm_get_pci_dev(struct pci_dev *pdev, const struct pci_device_id *ent,
struct drm_driver *driver) struct drm_driver *driver)
...@@ -346,15 +336,14 @@ int drm_get_pci_dev(struct pci_dev *pdev, const struct pci_device_id *ent, ...@@ -346,15 +336,14 @@ int drm_get_pci_dev(struct pci_dev *pdev, const struct pci_device_id *ent,
EXPORT_SYMBOL(drm_get_pci_dev); 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 * Return: 0 on success or a negative error code on failure.
* 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.
*/ */
int drm_pci_init(struct drm_driver *driver, struct pci_driver *pdriver) 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, ...@@ -458,7 +447,14 @@ int drm_pci_set_unique(struct drm_device *dev,
EXPORT_SYMBOL(drm_pci_init); 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) void drm_pci_exit(struct drm_driver *driver, struct pci_driver *pdriver)
{ {
struct drm_device *dev, *tmp; struct drm_device *dev, *tmp;
......
...@@ -106,17 +106,16 @@ static struct drm_bus drm_platform_bus = { ...@@ -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. * Registers the specified DRM device driver and platform device with the DRM
* * subsystem, initializing a drm_device structure and calling the driver's
* Initializes a drm_device structures,registering the * .load() function.
* stubs
* *
* Expands the \c DRIVER_PREINIT and \c DRIVER_POST_INIT macros before and * Return: 0 on success or a negative error code on failure.
* after the initialization for driver customization.
*/ */
int drm_platform_init(struct drm_driver *driver, struct platform_device *platform_device) int drm_platform_init(struct drm_driver *driver, struct platform_device *platform_device)
{ {
DRM_DEBUG("\n"); DRM_DEBUG("\n");
......
/**
* \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 * Created: Fri Jan 19 10:48:35 2001 by faith@acm.org
* *
* Copyright 2001 VA Linux Systems, Inc., Sunnyvale, California. * Copyright 2001 VA Linux Systems, Inc., Sunnyvale, California.
* All Rights Reserved. * All Rights Reserved.
* *
* Author Rickard E. (Rik) Faith <faith@valinux.com>
*
* Permission is hereby granted, free of charge, to any person obtaining a * Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"), * copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation * to deal in the Software without restriction, including without limitation
...@@ -425,11 +420,15 @@ void drm_minor_release(struct drm_minor *minor) ...@@ -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 * drm_put_dev - Unregister and release a DRM device
* unplugged. * @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) void drm_put_dev(struct drm_device *dev)
{ {
...@@ -536,7 +535,7 @@ static void drm_fs_inode_free(struct inode *inode) ...@@ -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 * @driver: DRM driver to allocate device for
* @parent: Parent device object * @parent: Parent device object
* *
...@@ -690,6 +689,7 @@ EXPORT_SYMBOL(drm_dev_unref); ...@@ -690,6 +689,7 @@ EXPORT_SYMBOL(drm_dev_unref);
/** /**
* drm_dev_register - Register DRM device * drm_dev_register - Register DRM device
* @dev: Device to register * @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 * 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() * and start normal device operation. @dev must be allocated via drm_dev_alloc()
......
...@@ -46,6 +46,16 @@ static struct drm_bus drm_usb_bus = { ...@@ -46,6 +46,16 @@ static struct drm_bus drm_usb_bus = {
.set_busid = drm_usb_set_busid, .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 drm_usb_init(struct drm_driver *driver, struct usb_driver *udriver)
{ {
int res; int res;
...@@ -58,6 +68,14 @@ int drm_usb_init(struct drm_driver *driver, struct usb_driver *udriver) ...@@ -58,6 +68,14 @@ int drm_usb_init(struct drm_driver *driver, struct usb_driver *udriver)
} }
EXPORT_SYMBOL(drm_usb_init); 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, void drm_usb_exit(struct drm_driver *driver,
struct usb_driver *udriver) struct usb_driver *udriver)
{ {
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment