Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit c6a1af8a authored by Thierry Reding's avatar Thierry Reding
Browse files

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

Documentation/DocBook/drm.tmpl

+10 −0
Original line number Diff line number Diff line
@@ -281,6 +281,16 @@ char *date;</synopsis> 
        </para>

      </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>

drivers/gpu/drm/drm_pci.c

+38 −42
Original line number Diff line number Diff line 
/* 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 @@ int drm_get_pci_dev(struct pci_dev *pdev, const struct pci_device_id *ent, 
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;

drivers/gpu/drm/drm_platform.c

+7 −8
Original line number Diff line number Diff line
@@ -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");

drivers/gpu/drm/drm_stub.c

+11 −11
Original line number Diff line number Diff line 
/**

 * \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
@@ -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()

drivers/gpu/drm/drm_usb.c

+19 −1
Original line number Diff line number Diff line
@@ -46,6 +46,16 @@ 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)

{