summaryrefslogtreecommitdiff
path: root/linux/drm_dma.h
diff options
context:
space:
mode:
authorJose Fonseca <jrfonseca@users.sourceforge.net>2003-05-27 00:37:33 +0000
committerJose Fonseca <jrfonseca@users.sourceforge.net>2003-05-27 00:37:33 +0000
commitd2443b2186712dd7c977b47e06444396e1e493ff (patch)
treef007726cb80c70438834cb286e51b822ec70a76b /linux/drm_dma.h
parentaeb4bc3f5b991d7970dca9417e04df06c0bf008a (diff)
Merged DRM documentation.
Diffstat (limited to 'linux/drm_dma.h')
-rw-r--r--linux/drm_dma.h102
1 files changed, 96 insertions, 6 deletions
diff --git a/linux/drm_dma.h b/linux/drm_dma.h
index 34ab5322..8e0ec95e 100644
--- a/linux/drm_dma.h
+++ b/linux/drm_dma.h
@@ -1,4 +1,12 @@
-/* drm_dma.c -- DMA IOCTL and function support -*- linux-c -*-
+/**
+ * \file drm_dma.h
+ * DMA IOCTL and function support
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
* Created: Fri Mar 19 14:30:16 1999 by faith@valinux.com
*
* Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,10 +31,6 @@
* OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
- *
- * Authors:
- * Rickard E. (Rik) Faith <faith@valinux.com>
- * Gareth Hughes <gareth@valinux.com>
*/
#define __NO_VERSION__
@@ -52,6 +56,14 @@
#if __HAVE_DMA
+/**
+ * Initialize the DMA data.
+ *
+ * \param dev DRM device.
+ * \return zero on success or a negative value on failure.
+ *
+ * Allocate and initialize a drm_device_dma structure.
+ */
int DRM(dma_setup)( drm_device_t *dev )
{
int i;
@@ -68,6 +80,14 @@ int DRM(dma_setup)( drm_device_t *dev )
return 0;
}
+/**
+ * Cleanup the DMA resources.
+ *
+ * \param dev DRM device.
+ *
+ * Free all pages associated with DMA buffers, the buffers and pages lists, and
+ * finally the the drm_device::dma structure itself.
+ */
void DRM(dma_takedown)(drm_device_t *dev)
{
drm_device_dma_t *dma = dev->dma;
@@ -129,7 +149,14 @@ void DRM(dma_takedown)(drm_device_t *dev)
}
-
+/**
+ * Free a buffer.
+ *
+ * \param dev DRM device.
+ * \param buf buffer to free.
+ *
+ * Resets the fields of \p buf.
+ */
void DRM(free_buffer)(drm_device_t *dev, drm_buf_t *buf)
{
if (!buf) return;
@@ -155,6 +182,13 @@ void DRM(free_buffer)(drm_device_t *dev, drm_buf_t *buf)
}
#if !__HAVE_DMA_RECLAIM
+/**
+ * Reclaim the buffers.
+ *
+ * \param filp file pointer.
+ *
+ * Frees each buffer associated with \p filp not already on the hardware.
+ */
void DRM(reclaim_buffers)( struct file *filp )
{
drm_file_t *priv = filp->private_data;
@@ -186,6 +220,16 @@ void DRM(reclaim_buffers)( struct file *filp )
#if __HAVE_DMA_IRQ
+/**
+ * Install IRQ handler.
+ *
+ * \param dev DRM device.
+ * \param irq IRQ number.
+ *
+ * Initializes the IRQ related data, and setups drm_device::vbl_queue. Installs the handler, calling the driver
+ * \c DRM(driver_irq_preinstall)() and \c DRM(driver_irq_postinstall)() functions
+ * before and after the installation.
+ */
int DRM(irq_install)( drm_device_t *dev, int irq )
{
int ret;
@@ -258,6 +302,13 @@ int DRM(irq_install)( drm_device_t *dev, int irq )
return 0;
}
+/**
+ * Uninstall the IRQ handler.
+ *
+ * \param dev DRM device.
+ *
+ * Calls the driver's \c DRM(driver_irq_uninstall)() function, and stops the irq.
+ */
int DRM(irq_uninstall)( drm_device_t *dev )
{
int irq;
@@ -279,6 +330,17 @@ int DRM(irq_uninstall)( drm_device_t *dev )
return 0;
}
+/**
+ * IRQ control ioctl.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_control structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Calls irq_install() or irq_uninstall() according to \p arg.
+ */
int DRM(control)( struct inode *inode, struct file *filp,
unsigned int cmd, unsigned long arg )
{
@@ -301,6 +363,25 @@ int DRM(control)( struct inode *inode, struct file *filp,
#if __HAVE_VBL_IRQ
+/**
+ * Wait for VBLANK.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param data user argument, pointing to a drm_wait_vblank structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the IRQ is installed.
+ *
+ * If a signal is requested checks if this task has already scheduled the same signal
+ * for the same vblank sequence number - nothing to be done in
+ * that case. If the number of tasks waiting for the interrupt exceeds 100 the
+ * function fails. Otherwise adds a new entry to drm_device::vbl_sigs for this
+ * task.
+ *
+ * If a signal is not requested, then calls vblank_wait().
+ */
int DRM(wait_vblank)( DRM_IOCTL_ARGS )
{
drm_file_t *priv = filp->private_data;
@@ -389,6 +470,15 @@ done:
return ret;
}
+/**
+ * Send the VBLANK signals.
+ *
+ * \param dev DRM device.
+ *
+ * Sends a signal for each task in drm_device::vbl_sigs and empties the list.
+ *
+ * If a signal is not requested, then calls vblank_wait().
+ */
void DRM(vbl_send_signals)( drm_device_t *dev )
{
struct list_head *list, *tmp;