-/* mach64_dma.c -- DMA support for mach64 (Rage Pro) driver -*- linux-c -*-
- * Created: Sun Dec 03 19:20:26 2000 by gareth@valinux.com
+/* mach64_dma.c -- DMA support for mach64 (Rage Pro) driver -*- linux-c -*- */
+/**
+ * \file mach64_dma.c
+ * DMA support for mach64 (Rage Pro) driver
*
+ * \author Gareth Hughes <gareth@valinux.com>
+ * \author Frank C. Earl <fearl@airmail.net>
+ * \author Leif Delgass <ldelgass@retinalburn.net>
+ * \author Jose Fonseca <j_r_fonseca@yahoo.co.uk>
+ */
+
+/*
* Copyright 2000 Gareth Hughes
* Copyright 2002 Frank C. Earl
* Copyright 2002-2003 Leif Delgass
* THE COPYRIGHT OWNER(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR 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:
- * Gareth Hughes <gareth@valinux.com>
- * Frank C. Earl <fearl@airmail.net>
- * Leif Delgass <ldelgass@retinalburn.net>
- * Jos�Fonseca <j_r_fonseca@yahoo.co.uk>
*/
#include "drmP.h"
#include "mach64_drm.h"
#include "mach64_drv.h"
-/* ================================================================
- * Engine, FIFO control
- */
+/*******************************************************************/
+/** \name Engine, FIFO control */
+/*@{*/
+/**
+ * Waits for free entries in the FIFO.
+ *
+ * \note Most writes to Mach64 registers are automatically routed through
+ * command FIFO which is 16 entry deep. Prior to writing to any draw engine
+ * register one has to ensure that enough FIFO entries are available by calling
+ * this function. Failure to do so may cause the engine to lock.
+ *
+ * \param dev_priv pointer to device private data structure.
+ * \param entries number of free entries in the FIFO to wait for.
+ *
+ * \returns zero on success, or -EBUSY if the timeout (specificed by
+ * drm_mach64_private::usec_timeout) occurs.
+ */
int mach64_do_wait_for_fifo(drm_mach64_private_t * dev_priv, int entries)
{
int slots = 0, i;
return DRM_ERR(EBUSY);
}
+/**
+ * Wait for the draw engine to be idle.
+ */
int mach64_do_wait_for_idle(drm_mach64_private_t * dev_priv)
{
int i, ret;
return DRM_ERR(EBUSY);
}
+/**
+ * Wait for free entries in the ring buffer.
+ *
+ * The Mach64 bus master can be configured to act as a virtual FIFO, using a
+ * circular buffer (commonly referred as "ring buffer" in other drivers) with
+ * pointers to engine commands. This allows the CPU to do other things while
+ * the graphics engine is busy, i.e., DMA mode.
+ *
+ * This function should be called before writing new entries to the ring
+ * buffer.
+ *
+ * \param dev_priv pointer to device private data structure.
+ * \param n number of free entries in the ring buffer to wait for.
+ *
+ * \returns zero on success, or -EBUSY if the timeout (specificed by
+ * drm_mach64_private_t::usec_timeout) occurs.
+ *
+ * \sa mach64_dump_ring_info()
+ */
int mach64_wait_ring(drm_mach64_private_t * dev_priv, int n)
{
drm_mach64_descriptor_ring_t *ring = &dev_priv->ring;
return DRM_ERR(EBUSY);
}
-/* Wait until all DMA requests have been processed... */
+/**
+ * Wait until all DMA requests have been processed...
+ *
+ * \sa mach64_wait_ring()
+ */
static int mach64_ring_idle(drm_mach64_private_t * dev_priv)
{
drm_mach64_descriptor_ring_t *ring = &dev_priv->ring;
return DRM_ERR(EBUSY);
}
+/**
+ * Reset the the ring buffer descriptors.
+ *
+ * \sa mach64_do_engine_reset()
+ */
static void mach64_ring_reset(drm_mach64_private_t * dev_priv)
{
drm_mach64_descriptor_ring_t *ring = &dev_priv->ring;
dev_priv->ring_running = 0;
}
+/**
+ * Ensure the all the queued commands will be processed.
+ */
int mach64_do_dma_flush(drm_mach64_private_t * dev_priv)
{
/* FIXME: It's not necessary to wait for idle when flushing
return mach64_ring_idle(dev_priv);
}
+/**
+ * Stop all DMA activity.
+ */
int mach64_do_dma_idle(drm_mach64_private_t * dev_priv)
{
int ret;
return 0;
}
-/* Reset the engine. This will stop the DMA if it is running.
+/**
+ * Reset the engine. This will stop the DMA if it is running.
*/
int mach64_do_engine_reset(drm_mach64_private_t * dev_priv)
{
return 0;
}
-/* ================================================================
- * Debugging output
- */
+/*@}*/
+
+/*******************************************************************/
+/** \name Debugging output */
+/*@{*/
+
+/**
+ * Dump engine registers values.
+ */
void mach64_dump_engine_info(drm_mach64_private_t * dev_priv)
{
DRM_INFO("\n");
#define MACH64_DUMP_CONTEXT 3
+/**
+ * Used by mach64_dump_ring_info() to dump the contents of the current buffer
+ * pointed by the ring head.
+ */
static void mach64_dump_buf_info(drm_mach64_private_t * dev_priv,
drm_buf_t * buf)
{
DRM_INFO("\n");
}
+/**
+ * Dump the ring state and contents, including the contents of the buffer being
+ * processed by the graphics engine.
+ */
void mach64_dump_ring_info(drm_mach64_private_t * dev_priv)
{
drm_mach64_descriptor_ring_t *ring = &dev_priv->ring;
MACH64_READ(MACH64_SRC_CNTL));
}
-/* ================================================================
- * DMA test and initialization
- */
+/*@}*/
+
+/*******************************************************************/
+/** \name DMA test and initialization */
+/*@{*/
+
+/**
+ * Perform a simple DMA operation using the pattern registers to test whether
+ * DMA works.
+ *
+ * \return zero if successful.
+ *
+ * \note This function was the testbed for many experiences regarding Mach64
+ * DMA operation. It is left here since it so tricky to get DMA operating
+ * properly in some architectures and hardware.
+ */
static int mach64_bm_dma_test(drm_device_t * dev)
{
drm_mach64_private_t *dev_priv = dev->dev_private;
return failed;
}
+/**
+ * Called during the DMA initialization ioctl to initialize all the necessary
+ * software and hardware state for DMA operation.
+ */
static int mach64_do_dma_init(drm_device_t * dev, drm_mach64_init_t * init)
{
drm_mach64_private_t *dev_priv;
return 0;
}
-/* ===================================================================
- * MMIO Pseudo-DMA (intended primarily for debugging, not performance)
+/*******************************************************************/
+/** MMIO Pseudo-DMA (intended primarily for debugging, not performance)
*/
int mach64_do_dispatch_pseudo_dma(drm_mach64_private_t * dev_priv)
return 0;
}
-/* ================================================================
- * DMA cleanup
- */
+/*@}*/
+
+
+/*******************************************************************/
+/** \name DMA cleanup */
+/*@{*/
int mach64_do_cleanup_dma(drm_device_t * dev)
{
return 0;
}
-/* ================================================================
- * IOCTL handlers
- */
+/*@}*/
+
+
+/*******************************************************************/
+/** \name IOCTL handlers */
+/*@{*/
int mach64_dma_init(DRM_IOCTL_ARGS)
{
return mach64_do_engine_reset(dev_priv);
}
-/* ================================================================
- * Freelist management
- */
+/*@}*/
+
+
+/*******************************************************************/
+/** \name Freelist management */
+/*@{*/
int mach64_init_freelist(drm_device_t * dev)
{
return entry->buf;
}
-/* ================================================================
- * DMA buffer request and submission IOCTL handler
- */
+/*@}*/
+
+
+/*******************************************************************/
+/** \name DMA buffer request and submission IOCTL handler */
+/*@{*/
static int mach64_dma_get_buffers(DRMFILE filp, drm_device_t * dev,
drm_dma_t * d)
{
mach64_do_cleanup_dma(dev);
}
+
+/*@}*/