Merged DRM documentation.

48 files changed, 5048 insertions, 1198 deletions

diff --git a/libdrm/xf86drm.c b/libdrm/xf86drm.c
index a5bb8050..75a90825 100644
--- a/libdrm/xf86drm.c
+++ b/libdrm/xf86drm.c
@@ -1,6 +1,12 @@
-/* xf86drm.c -- User-level interface to DRM device
- * Created: Tue Jan  5 08:16:21 1999 by faith@precisioninsight.com
+/**
+ * \file xf86drm.c 
+ * User-level interface to DRM device
  *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Kevin E. Martin <martin@valinux.com>
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
@@ -23,14 +29,10 @@
  * 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>
- *	    Kevin E. Martin <martin@valinux.com>
- *
- * $XFree86: xc/programs/Xserver/hw/xfree86/os-support/linux/drm/xf86drm.c,v 1.31 2003/02/04 03:01:59 dawes Exp $
- *
  */
 
+/* $XFree86: xc/programs/Xserver/hw/xfree86/os-support/linux/drm/xf86drm.c,v 1.31 2003/02/04 03:01:59 dawes Exp $ */
+
 #ifdef XFree86Server
 # include "xf86.h"
 # include "xf86_OSproc.h"
@@ -114,6 +116,14 @@ extern unsigned long _bus_base(void);
 
 #define DRM_MSG_VERBOSITY 3
 
+/**
+ * Output a message to stderr.
+ *
+ * \param format printf() like format string.
+ *
+ * \internal
+ * This function is a wrapper around vfprintf().
+ */
 static void
 drmMsg(const char *format, ...)
 {
@@ -196,6 +206,19 @@ static drmHashEntry *drmGetEntry(int fd)
     return entry;
 }
 
+/**
+ * Open the DRM device, creating it if necessary.
+ *
+ * \param dev major and minor numbers of the device.
+ * \param minor minor number of the device.
+ * 
+ * \return a file descriptor on success, or a negative value on error.
+ *
+ * \internal
+ * Assembles the device name from \p minor and opens it, creating the device
+ * special file node with the major and minor numbers specified by \p dev and
+ * parent directory if necessary and was called by root.
+ */
 static int drmOpenDevice(long dev, int minor)
 {
     stat_t          st;
@@ -255,6 +278,19 @@ static int drmOpenDevice(long dev, int minor)
     return -errno;
 }
 
+
+/**
+ * Open the DRM device
+ *
+ * \param minor device minor number.
+ * \param create allow to create the device if set.
+ *
+ * \return a file descriptor on success, or a negative value on error.
+ * 
+ * \internal
+ * Calls drmOpenDevice() if \p create is set, otherwise assembles the device
+ * name from \p minor and opens it.
+ */
 static int drmOpenMinor(int minor, int create)
 {
     int  fd;
@@ -267,10 +303,17 @@ static int drmOpenMinor(int minor, int create)
     return -errno;
 }
 
-/* drmAvailable looks for (DRM_MAJOR, 0) and returns 1 if it returns
-   information for DRM_IOCTL_VERSION.  For backward compatibility with
-   older Linux implementations, /proc/dri is also checked. */
 
+/**
+ * Determine whether the DRM kernel driver has been loaded.
+ * 
+ * \return 1 if the DRM driver is loaded, 0 otherwise.
+ *
+ * \internal 
+ * Determine the presence of the kernel driver by attempting to open the 0
+ * minor and get version information.  For backward compatibility with older
+ * Linux implementations, /proc/dri is also checked.
+ */
 int drmAvailable(void)
 {
     drmVersionPtr version;
@@ -292,6 +335,20 @@ int drmAvailable(void)
     return retval;
 }
 
+
+/**
+ * Open the device by bus ID.
+ *
+ * \param busid bus ID.
+ *
+ * \return a file descriptor on success, or a negative value on error.
+ *
+ * \internal
+ * This function attempts to open every possible minor (up to DRM_MAX_MINOR),
+ * comparing the device bus ID with the one supplied.
+ *
+ * \sa drmOpenMinor() and drmGetBusid().
+ */
 static int drmOpenByBusid(const char *busid)
 {
     int        i;
@@ -316,6 +373,21 @@ static int drmOpenByBusid(const char *busid)
     return -1;
 }
 
+
+/**
+ * Open the device by name.
+ *
+ * \param name driver name.
+ * 
+ * \return a file descriptor on success, or a negative value on error.
+ * 
+ * \internal
+ * This function opens the first minor number that matches the driver name and
+ * isn't already in use.  If it's in use it then it will already have a bus ID
+ * assigned.
+ * 
+ * \sa drmOpenMinor(), drmGetVersion() and drmGetBusid().
+ */
 static int drmOpenByName(const char *name)
 {
     int           i;
@@ -398,11 +470,22 @@ static int drmOpenByName(const char *name)
     return -1;
 }
 
-/* drmOpen looks up the specified name and busid, and opens the device
-   found.  The entry in /dev/dri is created if necessary (and if root).
-   A file descriptor is returned.  On error, the return value is
-   negative. */
 
+/**
+ * Open the DRM device.
+ *
+ * Looks up the specified name and bus ID, and opens the device found.  The
+ * entry in /dev/dri is created if necessary and if called by root.
+ *
+ * \param name driver name. Not referenced if bus ID is supplied.
+ * \param busid bus ID. Zero if not known.
+ * 
+ * \return a file descriptor on success, or a negative value on error.
+ * 
+ * \internal
+ * It calls drmOpenByBusid() if \p busid is specified or drmOpenByName()
+ * otherwise.
+ */
 int drmOpen(const char *name, const char *busid)
 {
 
@@ -410,6 +493,16 @@ int drmOpen(const char *name, const char *busid)
     return drmOpenByName(name);
 }
 
+
+/**
+ * Free the version information returned by drmGetVersion().
+ *
+ * \param v pointer to the version information.
+ *
+ * \internal
+ * It frees the memory pointed by \p %v as well as all the non-null strings
+ * pointers in it.
+ */
 void drmFreeVersion(drmVersionPtr v)
 {
     if (!v) return;
@@ -419,6 +512,16 @@ void drmFreeVersion(drmVersionPtr v)
     drmFree(v);
 }
 
+
+/**
+ * Free the non-public version information returned by the kernel.
+ *
+ * \param v pointer to the version information.
+ *
+ * \internal
+ * Used by drmGetVersion() to free the memory pointed by \p %v as well as all
+ * the non-null strings pointers in it.
+ */
 static void drmFreeKernelVersion(drm_version_t *v)
 {
     if (!v) return;
@@ -428,6 +531,17 @@ static void drmFreeKernelVersion(drm_version_t *v)
     drmFree(v);
 }
 
+
+/**
+ * Copy version information.
+ * 
+ * \param d destination pointer.
+ * \param s source pointer.
+ * 
+ * \internal
+ * Used by drmGetVersion() to translate the information returned by the ioctl
+ * interface in a private structure into the public structure counterpart.
+ */
 static void drmCopyVersion(drmVersionPtr d, const drm_version_t *s)
 {
     d->version_major      = s->version_major;
@@ -441,9 +555,22 @@ static void drmCopyVersion(drmVersionPtr d, const drm_version_t *s)
     d->desc               = drmStrdup(s->desc);
 }
 
-/* drmGet Version obtains the driver version information via an ioctl.  Similar
- * information is available via /proc/dri. */
 
+/**
+ * Query the driver version information.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return pointer to a drmVersion structure which should be freed with
+ * drmFreeVersion().
+ * 
+ * \note Similar information is available via /proc/dri.
+ * 
+ * \internal
+ * It gets the version information via successive DRM_IOCTL_VERSION ioctls,
+ * first with zeros to get the string lengths, and then the actually strings.
+ * It also null-terminates them since they might not be already.
+ */
 drmVersionPtr drmGetVersion(int fd)
 {
     drmVersionPtr retval;
@@ -490,9 +617,20 @@ drmVersionPtr drmGetVersion(int fd)
     return retval;
 }
 
-/* drmGetLibVersion set version information for the drm user space library.
- * this version number is driver indepedent */
 
+/**
+ * Get version information for the DRM user space library.
+ * 
+ * This version number is driver independent.
+ * 
+ * \param fd file descriptor.
+ *
+ * \return version information.
+ * 
+ * \internal
+ * This function allocates and fills a drm_version structure with a hard coded
+ * version number.
+ */
 drmVersionPtr drmGetLibVersion(int fd)
 {
     drm_version_t *version = drmMalloc(sizeof(*version));
@@ -510,11 +648,33 @@ drmVersionPtr drmGetLibVersion(int fd)
     return (drmVersionPtr)version;
 }
 
+
+/**
+ * Free the bus ID information.
+ *
+ * \param busid bus ID information string as given by drmGetBusid().
+ *
+ * \internal
+ * This function is just frees the memory pointed by \p busid.
+ */
 void drmFreeBusid(const char *busid)
 {
     drmFree((void *)busid);
 }
 
+
+/**
+ * Get the bus ID of the device.
+ *
+ * \param fd file descriptor.
+ *
+ * \return bus ID string.
+ *
+ * \internal
+ * This function gets the bus ID via successive DRM_IOCTL_GET_UNIQUE ioctls to
+ * get the string length and data, passing the arguments in a drm_unique
+ * structure.
+ */
 char *drmGetBusid(int fd)
 {
     drm_unique_t u;
@@ -529,6 +689,19 @@ char *drmGetBusid(int fd)
     return u.unique;
 }
 
+
+/**
+ * Set the bus ID of the device.
+ *
+ * \param fd file descriptor.
+ * \param busid bus ID string.
+ *
+ * \return zero on success, negative on failure.
+ *
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_SET_UNIQUE ioctl, passing
+ * the arguments in a drm_unique structure.
+ */
 int drmSetBusid(int fd, const char *busid)
 {
     drm_unique_t u;
@@ -561,6 +734,56 @@ int drmAuthMagic(int fd, drmMagic magic)
     return 0;
 }
 
+/**
+ * Specifies a range of memory that is available for mapping by a
+ * non-root process.
+ *
+ * \param fd file descriptor.
+ * \param offset usually the physical address. The actual meaning depends of
+ * the \p type parameter. See below.
+ * \param size of the memory in bytes.
+ * \param type type of the memory to be mapped.
+ * \param flags combination of several flags to modify the function actions.
+ * \param handle will be set to a value that may be used as the offset
+ * parameter for mmap().
+ * 
+ * \return zero on success or a negative value on error.
+ *
+ * \par Mapping the frame buffer
+ * For the frame buffer
+ * - \p offset will be the physical address of the start of the frame buffer,
+ * - \p size will be the size of the frame buffer in bytes, and
+ * - \p type will be DRM_FRAME_BUFFER.
+ *
+ * \par
+ * The area mapped will be uncached. If MTRR support is available in the
+ * kernel, the frame buffer area will be set to write combining. 
+ *
+ * \par Mapping the MMIO register area
+ * For the MMIO register area,
+ * - \p offset will be the physical address of the start of the register area,
+ * - \p size will be the size of the register area bytes, and
+ * - \p type will be DRM_REGISTERS.
+ * \par
+ * The area mapped will be uncached. 
+ * 
+ * \par Mapping the SAREA
+ * For the SAREA,
+ * - \p offset will be ignored and should be set to zero,
+ * - \p size will be the desired size of the SAREA in bytes,
+ * - \p type will be DRM_SHM.
+ * 
+ * \par
+ * A shared memory area of the requested size will be created and locked in
+ * kernel memory. This area may be mapped into client-space by using the handle
+ * returned. 
+ * 
+ * \note May only be called by root.
+ *
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_ADD_MAP ioctl, passing
+ * the arguments in a drm_map structure.
+ */
 int drmAddMap(int fd,
 	      drmHandle offset,
 	      drmSize size,
@@ -596,6 +819,22 @@ int drmRmMap(int fd, drmHandle handle)
     return 0;
 }
 
+/**
+ * Make buffers available for DMA transfers.
+ * 
+ * \param fd file descriptor.
+ * \param count number of buffers.
+ * \param size size of each buffer.
+ * \param flags buffer allocation flags.
+ * \param agp_offset offset in the AGP aperture 
+ *
+ * \return number of buffers allocated, negative on error.
+ *
+ * \internal
+ * This function is a wrapper around DRM_IOCTL_ADD_BUFS ioctl.
+ *
+ * \sa drm_buf_desc.
+ */
 int drmAddBufs(int fd, int count, int size, drmBufDescFlags flags,
 	       int agp_offset)
 {
@@ -647,6 +886,21 @@ int drmMarkBufs(int fd, double low, double high)
     return 0;
 }
 
+/**
+ * Free buffers.
+ *
+ * \param fd file descriptor.
+ * \param count number of buffers to free.
+ * \param list list of buffers to be freed.
+ *
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \note This function is primarily used for debugging.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_FREE_BUFS ioctl, passing
+ * the arguments in a drm_buf_free structure.
+ */
 int drmFreeBufs(int fd, int count, int *list)
 {
     drm_buf_free_t request;
@@ -657,6 +911,15 @@ int drmFreeBufs(int fd, int count, int *list)
     return 0;
 }
 
+
+/**
+ * Close the device.
+ *
+ * \param fd file descriptor.
+ *
+ * \internal
+ * This function closes the file descriptor.
+ */
 int drmClose(int fd)
 {
     unsigned long key    = drmGetKeyFromFd(fd);
@@ -673,6 +936,21 @@ int drmClose(int fd)
     return close(fd);
 }
 
+
+/**
+ * Map a region of memory.
+ *
+ * \param fd file descriptor.
+ * \param handle handle returned by drmAddMap().
+ * \param size size in bytes. Must match the size used by drmAddMap().
+ * \param address will contain the user-space virtual address where the mapping
+ * begins.
+ *
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper for mmap().
+ */
 int drmMap(int fd,
 	   drmHandle handle,
 	   drmSize size,
@@ -692,6 +970,18 @@ int drmMap(int fd,
     return 0;
 }
 
+
+/**
+ * Unmap mappings obtained with drmMap().
+ *
+ * \param address address as given by drmMap().
+ * \param size size in bytes. Must match the size used by drmMap().
+ * 
+ * \return zero on success, or a negative value on failure.
+ *
+ * \internal
+ * This function is a wrapper for unmap().
+ */
 int drmUnmap(drmAddress address, drmSize size)
 {
     return munmap(address, size);
@@ -733,6 +1023,21 @@ drmBufInfoPtr drmGetBufInfo(int fd)
     return NULL;
 }
 
+/**
+ * Map all DMA buffers into client-virtual space.
+ *
+ * \param fd file descriptor.
+ *
+ * \return a pointer to a ::drmBufMap structure.
+ *
+ * \note The client may not use these buffers until obtaining buffer indices
+ * with drmDMA().
+ * 
+ * \internal
+ * This function calls the DRM_IOCTL_MAP_BUFS ioctl and copies the returned
+ * information about the buffers in a drm_buf_map structure into the
+ * client-visible data structures.
+ */ 
 drmBufMapPtr drmMapBufs(int fd)
 {
     drm_buf_map_t bufs;
@@ -767,6 +1072,15 @@ drmBufMapPtr drmMapBufs(int fd)
     return NULL;
 }
 
+
+/**
+ * Unmap buffers allocated with drmMapBufs().
+ *
+ * \return zero on success, or negative value on failure.
+ *
+ * \internal
+ * Calls munmap() for every buffer stored in \p bufs.
+ */
 int drmUnmapBufs(drmBufMapPtr bufs)
 {
     int i;
@@ -777,8 +1091,21 @@ int drmUnmapBufs(drmBufMapPtr bufs)
     return 0;
 }
 
+
 #define DRM_DMA_RETRY		16
 
+/**
+ * Reserve DMA buffers.
+ *
+ * \param fd file descriptor.
+ * \param request 
+ * 
+ * \return zero on success, or a negative value on failure.
+ *
+ * \internal
+ * Assemble the arguments into a drm_dma structure and keeps issuing the
+ * DRM_IOCTL_DMA ioctl until success or until maximum number of retries.
+ */
 int drmDMA(int fd, drmDMAReqPtr request)
 {
     drm_dma_t dma;
@@ -807,6 +1134,21 @@ int drmDMA(int fd, drmDMAReqPtr request)
     }
 }
 
+
+/**
+ * Obtain heavyweight hardware lock.
+ *
+ * \param fd file descriptor.
+ * \param context context.
+ * \param flags flags that determine the sate of the hardware when the function
+ * returns.
+ * 
+ * \return always zero.
+ * 
+ * \internal
+ * This function translates the arguments into a drm_lock structure and issue
+ * the DRM_IOCTL_LOCK ioctl until the lock is successfully acquired.
+ */
 int drmGetLock(int fd, drmContext context, drmLockFlags flags)
 {
     drm_lock_t lock;
@@ -825,6 +1167,20 @@ int drmGetLock(int fd, drmContext context, drmLockFlags flags)
     return 0;
 }
 
+static void (*drm_unlock_callback)( void ) = 0;
+
+/**
+ * Release the hardware lock.
+ *
+ * \param fd file descriptor.
+ * \param context context.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_UNLOCK ioctl, passing the
+ * argument in a drm_lock structure.
+ */
 int drmUnlock(int fd, drmContext context)
 {
     drm_lock_t lock;
@@ -868,6 +1224,24 @@ void drmFreeReservedContextList(drmContextPtr pt)
     drmFree(pt);
 }
 
+/**
+ * Create context.
+ *
+ * Used by the X server during GLXContext initialization. This causes
+ * per-context kernel-level resources to be allocated.
+ *
+ * \param fd file descriptor.
+ * \param handle is set on success. To be used by the client when requesting DMA
+ * dispatch with drmDMA().
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \note May only be called by root.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_ADD_CTX ioctl, passing the
+ * argument in a drm_ctx structure.
+ */
 int drmCreateContext(int fd, drmContextPtr handle)
 {
     drm_ctx_t ctx;
@@ -919,6 +1293,23 @@ int drmGetContextFlags(int fd, drmContext context, drmContextFlagsPtr flags)
     return 0;
 }
 
+/**
+ * Destroy context.
+ *
+ * Free any kernel-level resources allocated with drmCreateContext() associated
+ * with the context.
+ * 
+ * \param fd file descriptor.
+ * \param handle handle given by drmCreateContext().
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \note May only be called by root.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_RM_CTX ioctl, passing the
+ * argument in a drm_ctx structure.
+ */
 int drmDestroyContext(int fd, drmContext handle)
 {
     drm_ctx_t ctx;
@@ -943,18 +1334,54 @@ int drmDestroyDrawable(int fd, drmDrawable handle)
     return 0;
 }
 
+/**
+ * Acquire the AGP device.
+ *
+ * Must be called before any of the other AGP related calls.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_ACQUIRE ioctl.
+ */
 int drmAgpAcquire(int fd)
 {
     if (ioctl(fd, DRM_IOCTL_AGP_ACQUIRE, NULL)) return -errno;
     return 0;
 }
 
+
+/**
+ * Release the AGP device.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_RELEASE ioctl.
+ */
 int drmAgpRelease(int fd)
 {
     if (ioctl(fd, DRM_IOCTL_AGP_RELEASE, NULL)) return -errno;
     return 0;
 }
 
+
+/**
+ * Set the AGP mode.
+ *
+ * \param fd file descriptor.
+ * \param mode AGP mode.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_ENABLE ioctl, passing the
+ * argument in a drm_agp_mode structure.
+ */
 int drmAgpEnable(int fd, unsigned long mode)
 {
     drm_agp_mode_t m;
@@ -964,6 +1391,23 @@ int drmAgpEnable(int fd, unsigned long mode)
     return 0;
 }
 
+
+/**
+ * Allocate a chunk of AGP memory.
+ *
+ * \param fd file descriptor.
+ * \param size requested memory size in bytes. Will be rounded to page boundary.
+ * \param type type of memory to allocate.
+ * \param address if not zero, will be set to the physical address of the
+ * allocated memory.
+ * \param handle on success will be set to a handle of the allocated memory.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_ALLOC ioctl, passing the
+ * arguments in a drm_agp_buffer structure.
+ */
 int drmAgpAlloc(int fd, unsigned long size, unsigned long type,
 		unsigned long *address, unsigned long *handle)
 {
@@ -978,6 +1422,19 @@ int drmAgpAlloc(int fd, unsigned long size, unsigned long type,
     return 0;
 }
 
+
+/**
+ * Free a chunk of AGP memory.
+ *
+ * \param fd file descriptor.
+ * \param handle handle to the allocated memory, as given by drmAgpAllocate().
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_FREE ioctl, passing the
+ * argument in a drm_agp_buffer structure.
+ */
 int drmAgpFree(int fd, unsigned long handle)
 {
     drm_agp_buffer_t b;
@@ -988,6 +1445,20 @@ int drmAgpFree(int fd, unsigned long handle)
     return 0;
 }
 
+
+/**
+ * Bind a chunk of AGP memory.
+ *
+ * \param fd file descriptor.
+ * \param handle handle to the allocated memory, as given by drmAgpAllocate().
+ * \param offset offset in bytes. It will round to page boundary.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_BIND ioctl, passing the
+ * argument in a drm_agp_binding structure.
+ */
 int drmAgpBind(int fd, unsigned long handle, unsigned long offset)
 {
     drm_agp_binding_t b;
@@ -998,6 +1469,19 @@ int drmAgpBind(int fd, unsigned long handle, unsigned long offset)
     return 0;
 }
 
+
+/**
+ * Unbind a chunk of AGP memory.
+ *
+ * \param fd file descriptor.
+ * \param handle handle to the allocated memory, as given by drmAgpAllocate().
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_UNBIND ioctl, passing
+ * the argument in a drm_agp_binding structure.
+ */
 int drmAgpUnbind(int fd, unsigned long handle)
 {
     drm_agp_binding_t b;
@@ -1008,6 +1492,18 @@ int drmAgpUnbind(int fd, unsigned long handle)
     return 0;
 }
 
+
+/**
+ * Get AGP driver major version number.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return major version number on success, or a negative value on failure..
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_INFO ioctl, getting the
+ * necessary information in a drm_agp_info structure.
+ */
 int drmAgpVersionMajor(int fd)
 {
     drm_agp_info_t i;
@@ -1016,6 +1512,18 @@ int drmAgpVersionMajor(int fd)
     return i.agp_version_major;
 }
 
+
+/**
+ * Get AGP driver minor version number.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return minor version number on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_INFO ioctl, getting the
+ * necessary information in a drm_agp_info structure.
+ */
 int drmAgpVersionMinor(int fd)
 {
     drm_agp_info_t i;
@@ -1024,6 +1532,18 @@ int drmAgpVersionMinor(int fd)
     return i.agp_version_minor;
 }
 
+
+/**
+ * Get AGP mode.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return mode on success, or zero on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_INFO ioctl, getting the
+ * necessary information in a drm_agp_info structure.
+ */
 unsigned long drmAgpGetMode(int fd)
 {
     drm_agp_info_t i;
@@ -1032,6 +1552,18 @@ unsigned long drmAgpGetMode(int fd)
     return i.mode;
 }
 
+
+/**
+ * Get AGP aperture base.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return aperture base on success, zero on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_INFO ioctl, getting the
+ * necessary information in a drm_agp_info structure.
+ */
 unsigned long drmAgpBase(int fd)
 {
     drm_agp_info_t i;
@@ -1040,6 +1572,18 @@ unsigned long drmAgpBase(int fd)
     return i.aperture_base;
 }
 
+
+/**
+ * Get AGP aperture size.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return aperture size on success, zero on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_INFO ioctl, getting the
+ * necessary information in a drm_agp_info structure.
+ */
 unsigned long drmAgpSize(int fd)
 {
     drm_agp_info_t i;
@@ -1048,6 +1592,18 @@ unsigned long drmAgpSize(int fd)
     return i.aperture_size;
 }
 
+
+/**
+ * Get used AGP memory.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return memory used on success, or zero on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_INFO ioctl, getting the
+ * necessary information in a drm_agp_info structure.
+ */
 unsigned long drmAgpMemoryUsed(int fd)
 {
     drm_agp_info_t i;
@@ -1056,6 +1612,18 @@ unsigned long drmAgpMemoryUsed(int fd)
     return i.memory_used;
 }
 
+
+/**
+ * Get available AGP memory.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return memory available on success, or zero on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_INFO ioctl, getting the
+ * necessary information in a drm_agp_info structure.
+ */
 unsigned long drmAgpMemoryAvail(int fd)
 {
     drm_agp_info_t i;
@@ -1064,6 +1632,18 @@ unsigned long drmAgpMemoryAvail(int fd)
     return i.memory_allowed;
 }
 
+
+/**
+ * Get hardware vendor ID.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return vendor ID on success, or zero on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_INFO ioctl, getting the
+ * necessary information in a drm_agp_info structure.
+ */
 unsigned int drmAgpVendorId(int fd)
 {
     drm_agp_info_t i;
@@ -1072,6 +1652,18 @@ unsigned int drmAgpVendorId(int fd)
     return i.id_vendor;
 }
 
+
+/**
+ * Get hardware device ID.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return zero on success, or zero on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_AGP_INFO ioctl, getting the
+ * necessary information in a drm_agp_info structure.
+ */
 unsigned int drmAgpDeviceId(int fd)
 {
     drm_agp_info_t i;
@@ -1102,6 +1694,17 @@ int drmScatterGatherFree(int fd, unsigned long handle)
     return 0;
 }
 
+/**
+ * Wait for VBLANK.
+ *
+ * \param fd file descriptor.
+ * \param vbl pointer to a drmVBlank structure.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_WAIT_VBLANK ioctl.
+ */
 int drmWaitVBlank(int fd, drmVBlankPtr vbl)
 {
     int ret;
@@ -1130,6 +1733,18 @@ int drmError(int err, const char *label)
     return 1;
 }
 
+/**
+ * Install IRQ handler.
+ *
+ * \param fd file descriptor.
+ * \param irq IRQ number.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_CONTROL ioctl, passing the
+ * argument in a drm_control structure.
+ */
 int drmCtlInstHandler(int fd, int irq)
 {
     drm_control_t ctl;
@@ -1140,6 +1755,18 @@ int drmCtlInstHandler(int fd, int irq)
     return 0;
 }
 
+
+/**
+ * Uninstall IRQ handler.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_CONTROL ioctl, passing the
+ * argument in a drm_control structure.
+ */
 int drmCtlUninstHandler(int fd)
 {
     drm_control_t ctl;
@@ -1166,6 +1793,20 @@ int drmFinish(int fd, int context, drmLockFlags flags)
     return 0;
 }
 
+/**
+ * Get IRQ from bus ID.
+ *
+ * \param fd file descriptor.
+ * \param busnum bus number.
+ * \param devnum device number.
+ * \param funcnum function number.
+ * 
+ * \return IRQ number on success, or a negative value on failure.
+ * 
+ * \internal
+ * This function is a wrapper around the DRM_IOCTL_IRQ_BUSID ioctl, passing the
+ * arguments in a drm_irq_busid structure.
+ */
 int drmGetInterruptFromBusID(int fd, int busnum, int devnum, int funcnum)
 {
     drm_irq_busid_t p;
@@ -1382,6 +2023,18 @@ int drmGetStats(int fd, drmStatsT *stats)
     return 0;
 }
 
+/**
+ * Send a device-specific command.
+ *
+ * \param fd file descriptor.
+ * \param drmCommandIndex command index 
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * It issues a ioctl given by 
+ * \code DRM_COMMAND_BASE + drmCommandIndex \endcode.
+ */
 int drmCommandNone(int fd, unsigned long drmCommandIndex)
 {
     void *data = NULL; /* dummy */
@@ -1395,6 +2048,21 @@ int drmCommandNone(int fd, unsigned long drmCommandIndex)
     return 0;
 }
 
+
+/**
+ * Send a device-specific read command.
+ *
+ * \param fd file descriptor.
+ * \param drmCommandIndex command index 
+ * \param data destination pointer of the data to be read.
+ * \param size size of the data to be read.
+ * 
+ * \return zero on success, or a negative value on failure.
+ *
+ * \internal
+ * It issues a read ioctl given by 
+ * \code DRM_COMMAND_BASE + drmCommandIndex \endcode.
+ */
 int drmCommandRead(int fd, unsigned long drmCommandIndex,
                    void *data, unsigned long size )
 {
@@ -1409,6 +2077,21 @@ int drmCommandRead(int fd, unsigned long drmCommandIndex,
     return 0;
 }
 
+
+/**
+ * Send a device-specific write command.
+ *
+ * \param fd file descriptor.
+ * \param drmCommandIndex command index 
+ * \param data source pointer of the data to be written.
+ * \param size size of the data to be written.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * It issues a write ioctl given by 
+ * \code DRM_COMMAND_BASE + drmCommandIndex \endcode.
+ */
 int drmCommandWrite(int fd, unsigned long drmCommandIndex,
                    void *data, unsigned long size )
 {
@@ -1423,6 +2106,21 @@ int drmCommandWrite(int fd, unsigned long drmCommandIndex,
     return 0;
 }
 
+
+/**
+ * Send a device-specific read-write command.
+ *
+ * \param fd file descriptor.
+ * \param drmCommandIndex command index 
+ * \param data source pointer of the data to be read and written.
+ * \param size size of the data to be read and written.
+ * 
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * It issues a read-write ioctl given by 
+ * \code DRM_COMMAND_BASE + drmCommandIndex \endcode.
+ */
 int drmCommandWriteRead(int fd, unsigned long drmCommandIndex,
                    void *data, unsigned long size )
 {
diff --git a/linux-core/ati_pcigart.c b/linux-core/ati_pcigart.c
index a259edb5..42233ff9 100644
--- a/linux-core/ati_pcigart.c
+++ b/linux-core/ati_pcigart.c
@@ -1,4 +1,11 @@
-/* ati_pcigart.h -- ATI PCI GART support -*- linux-c -*-
+/**
+ * \file ati_pcigart.h 
+ * ATI PCI GART support
+ *
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Wed Dec 13 21:52:19 2000 by gareth@valinux.com
  *
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -22,9 +29,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:
- *   Gareth Hughes <gareth@valinux.com>
  */
 
 #define __NO_VERSION__
@@ -46,8 +50,8 @@
 # error - PAGE_SIZE not 64K, 16K, 8K or 4K
 #endif
 
-# define ATI_MAX_PCIGART_PAGES		8192	/* 32 MB aperture, 4K pages */
-# define ATI_PCIGART_PAGE_SIZE		4096	/* PCI GART page size */
+# define ATI_MAX_PCIGART_PAGES		8192	/**< 32 MB aperture, 4K pages */
+# define ATI_PCIGART_PAGE_SIZE		4096	/**< PCI GART page size */
 
 static unsigned long DRM(ati_alloc_pcigart_table)( void )
 {
diff --git a/linux-core/drmP.h b/linux-core/drmP.h
index 1f0ef128..5626e4ff 100644
--- a/linux-core/drmP.h
+++ b/linux-core/drmP.h
@@ -1,6 +1,12 @@
-/* drmP.h -- Private header for Direct Rendering Manager -*- linux-c -*-
- * Created: Mon Jan  4 10:05:05 1999 by faith@precisioninsight.com
- *
+/**
+ * \file drmP.h 
+ * Private header for Direct Rendering Manager
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All rights reserved.
@@ -23,15 +29,12 @@
  * 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>
  */
 
 #ifndef _DRM_P_H_
 #define _DRM_P_H_
 
+
 #ifdef __KERNEL__
 #ifdef __alpha__
 /* add include of current.h so that "current" is defined
@@ -83,8 +86,11 @@
 
 #include "drm_os_linux.h"
 
-/* DRM template customization defaults
- */
+
+/***********************************************************************/
+/** \name DRM template customization defaults */
+/*@{*/
+
 #ifndef __HAVE_AGP
 #define __HAVE_AGP		0
 #endif
@@ -112,19 +118,23 @@
 #define __REALLY_HAVE_MTRR	(__HAVE_MTRR && defined(CONFIG_MTRR))
 #define __REALLY_HAVE_SG	(__HAVE_SG)
 
-/* Begin the DRM...
- */
+/*@}*/
+
 
-#define DRM_DEBUG_CODE 2	  /* Include debugging code (if > 1, then
+/***********************************************************************/
+/** \name Begin the DRM... */
+/*@{*/
+
+#define DRM_DEBUG_CODE 2	  /**< Include debugging code if > 1, then
 				     also include looping detection. */
 
-#define DRM_HASH_SIZE	      16 /* Size of key hash table		  */
-#define DRM_KERNEL_CONTEXT    0	 /* Change drm_resctx if changed	  */
-#define DRM_RESERVED_CONTEXTS 1	 /* Change drm_resctx if changed	  */
+#define DRM_HASH_SIZE	      16 /**< Size of key hash table. Must be power of 2. */
+#define DRM_KERNEL_CONTEXT    0	 /**< Change drm_resctx if changed */
+#define DRM_RESERVED_CONTEXTS 1	 /**< Change drm_resctx if changed */
 #define DRM_LOOPING_LIMIT     5000000
-#define DRM_BSZ		      1024 /* Buffer size for /dev/drm? output	  */
-#define DRM_TIME_SLICE	      (HZ/20)  /* Time slice for GLXContexts	  */
-#define DRM_LOCK_SLICE	      1	/* Time slice for lock, in jiffies	  */
+#define DRM_BSZ		      1024 /**< Buffer size for /dev/drm? output */
+#define DRM_TIME_SLICE	      (HZ/20)  /**< Time slice for GLXContexts */
+#define DRM_LOCK_SLICE	      1	/**< Time slice for lock, in jiffies */
 
 #define DRM_FLAG_DEBUG	  0x01
 
@@ -151,8 +161,14 @@
 #define DRM_MEM_SGLISTS   20
 
 #define DRM_MAX_CTXBITMAP (PAGE_SIZE * 8)
+	
+/*@}*/
+
+
+/***********************************************************************/
+/** \name Backward compatibility section */
+/*@{*/
 
-				/* Backward compatibility section */
 #ifndef minor
 #define minor(x) MINOR((x))
 #endif
@@ -217,17 +233,42 @@ static inline struct page * vmalloc_to_page(void * vmalloc_addr)
 #define DRM_RPR_ARG(vma) vma,
 #endif
 
-
 #define VM_OFFSET(vma) ((vma)->vm_pgoff << PAGE_SHIFT)
 
-				/* Macros to make printk easier */
+/*@}*/
+
+
+/***********************************************************************/
+/** \name Macros to make printk easier */
+/*@{*/
+
+/**
+ * Error output.
+ *
+ * \param fmt printf() like format string.
+ * \param arg arguments
+ */
 #define DRM_ERROR(fmt, arg...) \
 	printk(KERN_ERR "[" DRM_NAME ":%s] *ERROR* " fmt , __FUNCTION__ , ##arg)
+
+/**
+ * Memory error output.
+ *
+ * \param area memory area where the error occurred.
+ * \param fmt printf() like format string.
+ * \param arg arguments
+ */
 #define DRM_MEM_ERROR(area, fmt, arg...) \
 	printk(KERN_ERR "[" DRM_NAME ":%s:%s] *ERROR* " fmt , __FUNCTION__, \
 	       DRM(mem_stats)[area].name , ##arg)
 #define DRM_INFO(fmt, arg...)  printk(KERN_INFO "[" DRM_NAME "] " fmt , ##arg)
 
+/**
+ * Debug output.
+ * 
+ * \param fmt printf() like format string.
+ * \param arg arguments
+ */
 #if DRM_DEBUG_CODE
 #define DRM_DEBUG(fmt, arg...)						\
 	do {								\
@@ -250,7 +291,13 @@ static inline struct page * vmalloc_to_page(void * vmalloc_addr)
    len += sprintf(&buf[len], fmt , ##arg);				\
    if (len > DRM_PROC_LIMIT) { ret; *eof = 1; return len - offset; }
 
-				/* Mapping helper macros */
+/*@}*/
+
+
+/***********************************************************************/
+/** \name Mapping helper macros */
+/*@{*/
+
 #define DRM_IOREMAP(map, dev)							\
 	(map)->handle = DRM(ioremap)( (map)->offset, (map)->size, (dev) )
 
@@ -263,6 +310,15 @@ static inline struct page * vmalloc_to_page(void * vmalloc_addr)
 			DRM(ioremapfree)( (map)->handle, (map)->size, (dev) );	\
 	} while (0)
 
+/**
+ * Find mapping.
+ *
+ * \param _map matching mapping if found, untouched otherwise.
+ * \param _o offset.
+ *
+ * Expects the existence of a local variable named \p dev pointing to the
+ * drm_device structure.
+ */
 #define DRM_FIND_MAP(_map, _o)								\
 do {											\
 	struct list_head *_list;							\
@@ -275,9 +331,21 @@ do {											\
  		}									\
 	}										\
 } while(0)
+
+/**
+ * Drop mapping.
+ *
+ * \sa #DRM_FIND_MAP.
+ */
 #define DRM_DROP_MAP(_map)
 
-				/* Internal types and structures */
+/*@}*/
+
+
+/***********************************************************************/
+/** \name Internal types and structures */
+/*@{*/
+
 #define DRM_ARRAY_SIZE(x) (sizeof(x)/sizeof(x[0]))
 #define DRM_MIN(a,b) ((a)<(b)?(a):(b))
 #define DRM_MAX(a,b) ((a)>(b)?(a):(b))
@@ -286,10 +354,23 @@ do {											\
 #define DRM_BUFCOUNT(x) ((x)->count - DRM_LEFTCOUNT(x))
 #define DRM_WAITCOUNT(dev,idx) DRM_BUFCOUNT(&dev->queuelist[idx]->waitlist)
 
+/**
+ * Get the private SAREA mapping.
+ *
+ * \param _dev DRM device.
+ * \param _ctx context number.
+ * \param _map output mapping.
+ */
 #define DRM_GET_PRIV_SAREA(_dev, _ctx, _map) do {	\
 	(_map) = (_dev)->context_sareas[_ctx];		\
 } while(0)
 
+/**
+ * Test that the hardware lock is held by the caller, returning otherwise.
+ *
+ * \param dev DRM device.
+ * \param filp file pointer of the caller.
+ */
 #define LOCK_TEST_WITH_RETURN( dev, filp )				\
 do {									\
 	if ( !_DRM_LOCK_IS_HELD( dev->lock.hw_lock->lock ) ||		\
@@ -300,7 +381,14 @@ do {									\
 	}								\
 } while (0)
 
-
+/**
+ * Ioctl function type.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg argument.
+ */
 typedef int drm_ioctl_t( struct inode *inode, struct file *filp,
 			 unsigned int cmd, unsigned long arg );
 
@@ -316,8 +404,7 @@ typedef struct drm_ioctl_desc {
 } drm_ioctl_desc_t;
 
 typedef struct drm_devstate {
-	pid_t		  owner;	/* X server pid holding x_lock */
-
+	pid_t		  owner;	/**< X server pid holding x_lock */
 } drm_devstate_t;
 
 typedef struct drm_magic_entry {
@@ -337,21 +424,24 @@ typedef struct drm_vma_entry {
 	pid_t		      pid;
 } drm_vma_entry_t;
 
+/**
+ * DMA buffer.
+ */
 typedef struct drm_buf {
-	int		  idx;	       /* Index into master buflist	     */
-	int		  total;       /* Buffer size			     */
-	int		  order;       /* log-base-2(total)		     */
-	int		  used;	       /* Amount of buffer in use (for DMA)  */
-	unsigned long	  offset;      /* Byte offset (used internally)	     */
-	void		  *address;    /* Address of buffer		     */
-	unsigned long	  bus_address; /* Bus address of buffer		     */
-	struct drm_buf	  *next;       /* Kernel-only: used for free list    */
-	__volatile__ int  waiting;     /* On kernel DMA queue		     */
-	__volatile__ int  pending;     /* On hardware DMA queue		     */
-	wait_queue_head_t dma_wait;    /* Processes waiting		     */
-	struct file       *filp;       /* Pointer to holding file descr	     */
-	int		  context;     /* Kernel queue for this buffer	     */
-	int		  while_locked;/* Dispatch this buffer while locked  */
+	int		  idx;	       /**< Index into master buflist */
+	int		  total;       /**< Buffer size */
+	int		  order;       /**< log-base-2(total) */
+	int		  used;	       /**< Amount of buffer in use (for DMA) */
+	unsigned long	  offset;      /**< Byte offset (used internally) */
+	void		  *address;    /**< Address of buffer */
+	unsigned long	  bus_address; /**< Bus address of buffer */
+	struct drm_buf	  *next;       /**< Kernel-only: used for free list */
+	__volatile__ int  waiting;     /**< On kernel DMA queue */
+	__volatile__ int  pending;     /**< On hardware DMA queue */
+	wait_queue_head_t dma_wait;    /**< Processes waiting */
+	struct file       *filp;       /**< Pointer to holding file descr */
+	int		  context;     /**< Kernel queue for this buffer */
+	int		  while_locked;/**< Dispatch this buffer while locked */
 	enum {
 		DRM_LIST_NONE	 = 0,
 		DRM_LIST_FREE	 = 1,
@@ -359,41 +449,43 @@ typedef struct drm_buf {
 		DRM_LIST_PEND	 = 3,
 		DRM_LIST_PRIO	 = 4,
 		DRM_LIST_RECLAIM = 5
-	}		  list;	       /* Which list we're on		     */
-
+	}		  list;	       /**< Which list we're on */
 
-	int		  dev_priv_size; /* Size of buffer private stoarge   */
-	void		  *dev_private;  /* Per-buffer private storage       */
+	int		  dev_priv_size; /**< Size of buffer private storage */
+	void		  *dev_private;  /**< Per-buffer private storage */
 } drm_buf_t;
 
 
-				/* bufs is one longer than it has to be */
+/** bufs is one longer than it has to be */
 typedef struct drm_waitlist {
-	int		  count;	/* Number of possible buffers	   */
-	drm_buf_t	  **bufs;	/* List of pointers to buffers	   */
-	drm_buf_t	  **rp;		/* Read pointer			   */
-	drm_buf_t	  **wp;		/* Write pointer		   */
-	drm_buf_t	  **end;	/* End pointer			   */
+	int		  count;	/**< Number of possible buffers */
+	drm_buf_t	  **bufs;	/**< List of pointers to buffers */
+	drm_buf_t	  **rp;		/**< Read pointer */
+	drm_buf_t	  **wp;		/**< Write pointer */
+	drm_buf_t	  **end;	/**< End pointer */
 	spinlock_t	  read_lock;
 	spinlock_t	  write_lock;
 } drm_waitlist_t;
 
 typedef struct drm_freelist {
-	int		  initialized; /* Freelist in use		   */
-	atomic_t	  count;       /* Number of free buffers	   */
-	drm_buf_t	  *next;       /* End pointer			   */
-
-	wait_queue_head_t waiting;     /* Processes waiting on free bufs   */
-	int		  low_mark;    /* Low water mark		   */
-	int		  high_mark;   /* High water mark		   */
-	atomic_t	  wfh;	       /* If waiting for high mark	   */
+	int		  initialized; /**< Freelist in use */
+	atomic_t	  count;       /**< Number of free buffers */
+	drm_buf_t	  *next;       /**< End pointer */
+
+	wait_queue_head_t waiting;     /**< Processes waiting on free bufs */
+	int		  low_mark;    /**< Low water mark */
+	int		  high_mark;   /**< High water mark */
+	atomic_t	  wfh;	       /**< If waiting for high mark */
 	spinlock_t        lock;
 } drm_freelist_t;
 
+/**
+ * Buffer entry.  There is one of this for each buffer size order.
+ */
 typedef struct drm_buf_entry {
-	int		  buf_size;
-	int		  buf_count;
-	drm_buf_t	  *buflist;
+	int		  buf_size;	/**< size */
+	int		  buf_count;	/**< number of buffers */
+	drm_buf_t	  *buflist;	/**< buffer list */
 	int		  seg_count;
 	int		  page_order;
 	unsigned long	  *seglist;
@@ -401,11 +493,19 @@ typedef struct drm_buf_entry {
 	drm_freelist_t	  freelist;
 } drm_buf_entry_t;
 
+/**
+ * Hardware lock.
+ *
+ * The lock structure is a simple cache-line aligned integer.  To avoid
+ * processor bus contention on a multiprocessor system, there should not be any
+ * other data stored in the same cache line.
+ */
 typedef struct drm_hw_lock {
-	__volatile__ unsigned int lock;
-	char			  padding[60]; /* Pad to cache line */
+	__volatile__ unsigned int lock;		/**< lock variable */
+	char			  padding[60];	/**< Pad to cache line */
 } drm_hw_lock_t;
 
+/** File private data */
 typedef struct drm_file {
 	int		  authenticated;
 	int		  minor;
@@ -420,69 +520,85 @@ typedef struct drm_file {
 	unsigned long     lock_count;
 } drm_file_t;
 
-
+/** Wait queue */
 typedef struct drm_queue {
-	atomic_t	  use_count;	/* Outstanding uses (+1)	    */
-	atomic_t	  finalization;	/* Finalization in progress	    */
-	atomic_t	  block_count;	/* Count of processes waiting	    */
-	atomic_t	  block_read;	/* Queue blocked for reads	    */
-	wait_queue_head_t read_queue;	/* Processes waiting on block_read  */
-	atomic_t	  block_write;	/* Queue blocked for writes	    */
-	wait_queue_head_t write_queue;	/* Processes waiting on block_write */
+	atomic_t	  use_count;	/**< Outstanding uses (+1) */
+	atomic_t	  finalization;	/**< Finalization in progress */
+	atomic_t	  block_count;	/**< Count of processes waiting */
+	atomic_t	  block_read;	/**< Queue blocked for reads */
+	wait_queue_head_t read_queue;	/**< Processes waiting on block_read */
+	atomic_t	  block_write;	/**< Queue blocked for writes */
+	wait_queue_head_t write_queue;	/**< Processes waiting on block_write */
 #if 1
-	atomic_t	  total_queued;	/* Total queued statistic	    */
-	atomic_t	  total_flushed;/* Total flushes statistic	    */
-	atomic_t	  total_locks;	/* Total locks statistics	    */
+	atomic_t	  total_queued;	/**< Total queued statistic */
+	atomic_t	  total_flushed;/**< Total flushes statistic */
+	atomic_t	  total_locks;	/**< Total locks statistics */
 #endif
-	drm_ctx_flags_t	  flags;	/* Context preserving and 2D-only   */
-	drm_waitlist_t	  waitlist;	/* Pending buffers		    */
-	wait_queue_head_t flush_queue;	/* Processes waiting until flush    */
+	drm_ctx_flags_t	  flags;	/**< Context preserving and 2D-only */
+	drm_waitlist_t	  waitlist;	/**< Pending buffers */
+	wait_queue_head_t flush_queue;	/**< Processes waiting until flush */
 } drm_queue_t;
 
+/**
+ * Lock data.
+ */
 typedef struct drm_lock_data {
-	drm_hw_lock_t	  *hw_lock;	/* Hardware lock		   */
-	struct file       *filp;	/* File descr of lock holder (0=kernel)   */
-	wait_queue_head_t lock_queue;	/* Queue of blocked processes	   */
-	unsigned long	  lock_time;	/* Time of last lock in jiffies	   */
+	drm_hw_lock_t	  *hw_lock;	/**< Hardware lock */
+	struct file       *filp;	/**< File descr of lock holder (0=kernel) */
+	wait_queue_head_t lock_queue;	/**< Queue of blocked processes */
+	unsigned long	  lock_time;	/**< Time of last lock in jiffies */
 } drm_lock_data_t;
 
+/**
+ * DMA data.
+ */
 typedef struct drm_device_dma {
 
-	drm_buf_entry_t	  bufs[DRM_MAX_ORDER+1];
-	int		  buf_count;
-	drm_buf_t	  **buflist;	/* Vector of pointers info bufs	   */
+	drm_buf_entry_t	  bufs[DRM_MAX_ORDER+1];	/**< buffers, grouped by their size order */
+	int		  buf_count;	/**< total number of buffers */
+	drm_buf_t	  **buflist;	/**< Vector of pointers into drm_device_dma::bufs */
 	int		  seg_count;
-	int		  page_count;
-	unsigned long	  *pagelist;
+	int		  page_count;	/**< number of pages */
+	unsigned long	  *pagelist;	/**< page list */
 	unsigned long	  byte_count;
 	enum {
 		_DRM_DMA_USE_AGP = 0x01,
 		_DRM_DMA_USE_SG  = 0x02
 	} flags;
 
-				/* DMA support */
-	drm_buf_t	  *this_buffer;	/* Buffer being sent		   */
-	drm_buf_t	  *next_buffer; /* Selected buffer to send	   */
-	drm_queue_t	  *next_queue;	/* Queue from which buffer selected*/
-	wait_queue_head_t waiting;	/* Processes waiting on free bufs  */
+	/** \name DMA support */
+	/*@{*/
+	drm_buf_t	  *this_buffer;	/**< Buffer being sent */
+	drm_buf_t	  *next_buffer; /**< Selected buffer to send */
+	drm_queue_t	  *next_queue;	/**< Queue from which buffer selected*/
+	wait_queue_head_t waiting;	/**< Processes waiting on free bufs */
+	/*@}*/
 } drm_device_dma_t;
 
 #if __REALLY_HAVE_AGP
+/** 
+ * AGP memory entry.  Stored as a doubly linked list.
+ */
 typedef struct drm_agp_mem {
-	unsigned long      handle;
-	agp_memory         *memory;
-	unsigned long      bound; /* address */
+	unsigned long      handle;	/**< handle */
+	agp_memory         *memory;	
+	unsigned long      bound;	/**< address */
 	int                pages;
-	struct drm_agp_mem *prev;
-	struct drm_agp_mem *next;
+	struct drm_agp_mem *prev;	/**< previous entry */
+	struct drm_agp_mem *next;	/**< next entry */
 } drm_agp_mem_t;
 
+/**
+ * AGP data.
+ *
+ * \sa DRM(agp_init)() and drm_device::agp.
+ */
 typedef struct drm_agp_head {
-	agp_kern_info      agp_info;
-	drm_agp_mem_t      *memory;
-	unsigned long      mode;
-	int                enabled;
-	int                acquired;
+	agp_kern_info      agp_info;	/**< AGP device information */
+	drm_agp_mem_t      *memory;	/**< memory entries */
+	unsigned long      mode;	/**< AGP mode */
+	int                enabled;	/**< whether the AGP bus as been enabled */
+	int                acquired;	/**< whether the AGP device has been acquired */
 	unsigned long      base;
    	int 		   agp_mtrr;
 	int		   cant_use_aperture;
@@ -490,6 +606,9 @@ typedef struct drm_agp_head {
 } drm_agp_head_t;
 #endif
 
+/**
+ * Scatter-gather memory.
+ */
 typedef struct drm_sg_mem {
 	unsigned long   handle;
 	void            *virtual;
@@ -503,9 +622,12 @@ typedef struct drm_sigdata {
 	drm_hw_lock_t *lock;
 } drm_sigdata_t;
 
+/**
+ * Mappings list
+ */
 typedef struct drm_map_list {
-	struct list_head	head;
-	drm_map_t		*map;
+	struct list_head	head;	/**< list head */
+	drm_map_t		*map;	/**< mapping */
 } drm_map_list_t;
 
 typedef drm_map_t drm_local_map_t;
@@ -521,92 +643,112 @@ typedef struct drm_vbl_sig {
 
 #endif
 
+/**
+ * DRM device structure.
+ */
 typedef struct drm_device {
-	const char	  *name;	/* Simple driver name		   */
-	char		  *unique;	/* Unique identifier: e.g., busid  */
-	int		  unique_len;	/* Length of unique field	   */
-	dev_t		  device;	/* Device number for mknod	   */
-	char		  *devname;	/* For /proc/interrupts		   */
-
-	int		  blocked;	/* Blocked due to VC switch?	   */
-	struct proc_dir_entry *root;	/* Root for this device's entries  */
-
-				/* Locks */
-	spinlock_t	  count_lock;	/* For inuse, open_count, buf_use  */
-	struct semaphore  struct_sem;	/* For others			   */
-
-				/* Usage Counters */
-	int		  open_count;	/* Outstanding files open	   */
-	atomic_t	  ioctl_count;	/* Outstanding IOCTLs pending	   */
-	atomic_t	  vma_count;	/* Outstanding vma areas open	   */
-	int		  buf_use;	/* Buffers in use -- cannot alloc  */
-	atomic_t	  buf_alloc;	/* Buffer allocation in progress   */
-
-				/* Performance counters */
+	const char	  *name;	/**< Simple driver name */
+	char		  *unique;	/**< Unique identifier: e.g., busid */
+	int		  unique_len;	/**< Length of unique field */
+	dev_t		  device;	/**< Device number for mknod */
+	char		  *devname;	/**< For /proc/interrupts */
+
+	int		  blocked;	/**< Blocked due to VC switch? */
+	struct proc_dir_entry *root;	/**< Root for this device's entries */
+
+	/** \name Locks */
+	/*@{*/
+	spinlock_t	  count_lock;	/**< For inuse, drm_device::open_count, drm_device::buf_use */
+	struct semaphore  struct_sem;	/**< For others */
+	/*@}*/
+
+	/** \name Usage Counters */
+	/*@{*/
+	int		  open_count;	/**< Outstanding files open */
+	atomic_t	  ioctl_count;	/**< Outstanding IOCTLs pending */
+	atomic_t	  vma_count;	/**< Outstanding vma areas open */
+	int		  buf_use;	/**< Buffers in use -- cannot alloc */
+	atomic_t	  buf_alloc;	/**< Buffer allocation in progress */
+	/*@}*/
+
+	/** \name Performance counters */
+	/*@{*/
 	unsigned long     counters;
 	drm_stat_type_t   types[15];
 	atomic_t          counts[15];
+	/*@}*/
 
-				/* Authentication */
-	drm_file_t	  *file_first;
-	drm_file_t	  *file_last;
-	drm_magic_head_t  magiclist[DRM_HASH_SIZE];
+	/** \name Authentication */
+	/*@{*/
+	drm_file_t	  *file_first;	/**< file list head */
+	drm_file_t	  *file_last;	/**< file list tail */
+	drm_magic_head_t  magiclist[DRM_HASH_SIZE];	/**< magic hash table */
+	/*@}*/
 
-				/* Memory management */
-	drm_map_list_t	  *maplist;	/* Linked list of regions	   */
+	/** \name Memory management */
+	/*@{*/
+	drm_map_list_t	  *maplist;	/**< Linked list of regions */
+	int		  map_count;	/**< Number of mappable regions */
 
-	drm_map_t	  **context_sareas;
+	drm_map_t	  **context_sareas; /**< per-context SAREA's */
 	int		  max_context;
 
-	drm_vma_entry_t	  *vmalist;	/* List of vmas (for debugging)	   */
-	drm_lock_data_t	  lock;		/* Information on hardware lock	   */
-
-				/* DMA queues (contexts) */
-	int		  queue_count;	/* Number of active DMA queues	   */
-	int		  queue_reserved; /* Number of reserved DMA queues */
-	int		  queue_slots;	/* Actual length of queuelist	   */
-	drm_queue_t	  **queuelist;	/* Vector of pointers to DMA queues */
-	drm_device_dma_t  *dma;		/* Optional pointer for DMA support */
-
-				/* Context support */
-	int		  irq;		/* Interrupt used by board	   */
-	__volatile__ long context_flag;	/* Context swapping flag	   */
-	__volatile__ long interrupt_flag; /* Interruption handler flag	   */
-	__volatile__ long dma_flag;	/* DMA dispatch flag		   */
-	struct timer_list timer;	/* Timer for delaying ctx switch   */
-	wait_queue_head_t context_wait; /* Processes waiting on ctx switch */
-	int		  last_checked;	/* Last context checked for DMA	   */
-	int		  last_context;	/* Last current context		   */
-	unsigned long	  last_switch;	/* jiffies at last context switch  */
+	drm_vma_entry_t	  *vmalist;	/**< List of vmas (for debugging) */
+	drm_lock_data_t	  lock;		/**< Information on hardware lock */
+	/*@}*/
+
+	/** \name DMA queues (contexts) */
+	/*@{*/
+	int		  queue_count;	/**< Number of active DMA queues */
+	int		  queue_reserved; /**< Number of reserved DMA queues */
+	int		  queue_slots;	/**< Actual length of queuelist */
+	drm_queue_t	  **queuelist;	/**< Vector of pointers to DMA queues */
+	drm_device_dma_t  *dma;		/**< Optional pointer for DMA support */
+	/*@}*/
+
+	/** \name Context support */
+	/*@{*/
+	int		  irq;		/**< Interrupt used by board */
+	__volatile__ long context_flag;	/**< Context swapping flag */
+	__volatile__ long interrupt_flag; /**< Interruption handler flag */
+	__volatile__ long dma_flag;	/**< DMA dispatch flag */
+	struct timer_list timer;	/**< Timer for delaying ctx switch */
+	wait_queue_head_t context_wait; /**< Processes waiting on ctx switch */
+	int		  last_checked;	/**< Last context checked for DMA */
+	int		  last_context;	/**< Last current context */
+	unsigned long	  last_switch;	/**< jiffies at last context switch */
+	/*@}*/
+	
 #if !HAS_WORKQUEUE
 	struct tq_struct  tq;
 #else
 	struct work_struct	work;
 #endif
+	/** \name VBLANK IRQ support */
+	/*@{*/
 #if __HAVE_VBL_IRQ
-   	wait_queue_head_t vbl_queue;
+   	wait_queue_head_t vbl_queue;	/**< VBLANK wait queue */
    	atomic_t          vbl_received;
 	spinlock_t        vbl_lock;
-	drm_vbl_sig_t     vbl_sigs;
+	drm_vbl_sig_t     vbl_sigs;	/**< signal list to send on VBLANK */
 	unsigned int      vbl_pending;
 #endif
+	/*@}*/
 	cycles_t	  ctx_start;
 	cycles_t	  lck_start;
 
-				/* Callback to X server for context switch
-				   and for heavy-handed reset. */
-	char		  buf[DRM_BSZ]; /* Output buffer		   */
-	char		  *buf_rp;	/* Read pointer			   */
-	char		  *buf_wp;	/* Write pointer		   */
-	char		  *buf_end;	/* End pointer			   */
-	struct fasync_struct *buf_async;/* Processes waiting for SIGIO	   */
-	wait_queue_head_t buf_readers;	/* Processes waiting to read	   */
-	wait_queue_head_t buf_writers;	/* Processes waiting to ctx switch */
+	char		  buf[DRM_BSZ]; /**< Output buffer */
+	char		  *buf_rp;	/**< Read pointer */
+	char		  *buf_wp;	/**< Write pointer */
+	char		  *buf_end;	/**< End pointer */
+	struct fasync_struct *buf_async;/**< Processes waiting for SIGIO */
+	wait_queue_head_t buf_readers;	/**< Processes waiting to read */
+	wait_queue_head_t buf_writers;	/**< Processes waiting to ctx switch */
 
 #if __REALLY_HAVE_AGP
-	drm_agp_head_t    *agp;
+	drm_agp_head_t    *agp;	/**< AGP data */
 #endif
-	struct pci_dev *pdev;
+	struct pci_dev *pdev;		/**< PCI device structure */
 #ifdef __alpha__
 #if LINUX_VERSION_CODE < KERNEL_VERSION(2,4,3)
 	struct pci_controler *hose;
@@ -614,17 +756,17 @@ typedef struct drm_device {
 	struct pci_controller *hose;
 #endif
 #endif
-	drm_sg_mem_t      *sg;  /* Scatter gather memory */
-	unsigned long     *ctx_bitmap;
-	void		  *dev_private;
-	drm_sigdata_t     sigdata; /* For block_all_signals */
+	drm_sg_mem_t      *sg;  /**< Scatter gather memory */
+	unsigned long     *ctx_bitmap;	/**< context bitmap */
+	void		  *dev_private; /**< device private data */
+	drm_sigdata_t     sigdata; /**< For block_all_signals */
 	sigset_t          sigmask;
 } drm_device_t;
 
 
-/* ================================================================
- * Internal function definitions
- */
+/******************************************************************/
+/** \name Internal function definitions */
+/*@{*/
 
 				/* Misc. support (drm_init.h) */
 extern int	     DRM(flags);
@@ -873,5 +1015,7 @@ extern int            DRM(ati_pcigart_cleanup)(drm_device_t *dev,
 					       unsigned long addr,
 					       dma_addr_t bus_addr);
 
+/*@}*/
+
 #endif /* __KERNEL__ */
 #endif
diff --git a/linux-core/drm_agpsupport.c b/linux-core/drm_agpsupport.c
index 22790900..81850593 100644
--- a/linux-core/drm_agpsupport.c
+++ b/linux-core/drm_agpsupport.c
@@ -1,6 +1,12 @@
-/* drm_agpsupport.h -- DRM support for AGP/GART backend -*- linux-c -*-
- * Created: Mon Dec 13 09:56:45 1999 by faith@precisioninsight.com
- *
+/**
+ * \file drm_agpsupport.h 
+ * DRM support for AGP/GART backend
+ *    
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
@@ -23,10 +29,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.
- *
- * Author:
- *    Rickard E. (Rik) Faith <faith@valinux.com>
- *    Gareth Hughes <gareth@valinux.com>
  */
 
 #define __NO_VERSION__
@@ -35,11 +37,27 @@
 
 #if __REALLY_HAVE_AGP
 
+
 #define DRM_AGP_GET (drm_agp_t *)inter_module_get("drm_agp")
 #define DRM_AGP_PUT inter_module_put("drm_agp")
 
+/**
+ * Pointer to the drm_agp_t structure made available by the agpgart module.
+ */
 static const drm_agp_t *drm_agp = NULL;
 
+/**
+ * AGP information ioctl.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a (output) drm_agp_info structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device has been initialized and acquired and fills in the
+ * drm_agp_info structure with the information in drm_agp_head::agp_info.
+ */
 int DRM(agp_info)(struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg)
 {
@@ -67,6 +85,18 @@ int DRM(agp_info)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Acquire the AGP device (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument.
+ * \return zero on success or a negative number on failure. 
+ *
+ * Verifies the AGP device hasn't been acquired before and calls
+ * drm_agp->acquire().
+ */
 int DRM(agp_acquire)(struct inode *inode, struct file *filp,
 		     unsigned int cmd, unsigned long arg)
 {
@@ -81,6 +111,17 @@ int DRM(agp_acquire)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Release the AGP device (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device has been acquired and calls drm_agp->release().
+ */
 int DRM(agp_release)(struct inode *inode, struct file *filp,
 		     unsigned int cmd, unsigned long arg)
 {
@@ -95,11 +136,28 @@ int DRM(agp_release)(struct inode *inode, struct file *filp,
 
 }
 
+/**
+ * Release the AGP device.
+ *
+ * Calls drm_agp->release().
+ */
 void DRM(agp_do_release)(void)
 {
 	if (drm_agp->release) drm_agp->release();
 }
 
+/**
+ * Enable the AGP bus.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_mode structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device has been acquired but not enabled, and calls
+ * drm_agp->enable().
+ */
 int DRM(agp_enable)(struct inode *inode, struct file *filp,
 		    unsigned int cmd, unsigned long arg)
 {
@@ -120,6 +178,18 @@ int DRM(agp_enable)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Allocate AGP memory.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_buffer structure.
+ * \return zero on success or a negative number on failure.
+ * 
+ * Verifies the AGP device is present and has been acquired, allocates the
+ * memory via alloc_agp() and creates a drm_agp_mem entry for it.
+ */
 int DRM(agp_alloc)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
@@ -169,6 +239,15 @@ int DRM(agp_alloc)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Search for the AGP memory entry associated with a handle.
+ *
+ * \param dev DRM device structure.
+ * \param handle AGP memory handle.
+ * \return pointer to the drm_agp_mem structure associated with \p handle.
+ * 
+ * Walks through drm_agp_head::memory until finding a matching handle.
+ */
 static drm_agp_mem_t *DRM(agp_lookup_entry)(drm_device_t *dev,
 					    unsigned long handle)
 {
@@ -180,6 +259,18 @@ static drm_agp_mem_t *DRM(agp_lookup_entry)(drm_device_t *dev,
 	return NULL;
 }
 
+/**
+ * Unbind AGP memory from the GATT (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_binding structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device is present and acquired, looks-up the AGP memory
+ * entry and passes it to the unbind_agp() function.
+ */
 int DRM(agp_unbind)(struct inode *inode, struct file *filp,
 		    unsigned int cmd, unsigned long arg)
 {
@@ -201,6 +292,19 @@ int DRM(agp_unbind)(struct inode *inode, struct file *filp,
 	return ret;
 }
 
+/**
+ * Bind AGP memory into the GATT (ioctl)
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_binding structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device is present and has been acquired and that no memory
+ * is currently bound into the GATT. Looks-up the AGP memory entry and passes
+ * it to bind_agp() function.
+ */
 int DRM(agp_bind)(struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg)
 {
@@ -226,6 +330,20 @@ int DRM(agp_bind)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Free AGP memory (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_buffer structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device is present and has been acquired and looks up the
+ * AGP memory entry. If the memory it's currently bound, unbind it via
+ * unbind_agp(). Frees it via free_agp() as well as the entry itself
+ * and unlinks from the doubly linked list it's inserted in.
+ */
 int DRM(agp_free)(struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg)
 {
@@ -249,6 +367,15 @@ int DRM(agp_free)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Initialize the AGP resources.
+ *
+ * \return pointer to a drm_agp_head structure.
+ *
+ * Gets the drm_agp_t structure which is made available by the agpgart module
+ * via the inter_module_* functions. Creates and initializes a drm_agp_head
+ * structure.
+ */
 drm_agp_head_t *DRM(agp_init)(void)
 {
 	drm_agp_head_t *head         = NULL;
@@ -281,18 +408,25 @@ drm_agp_head_t *DRM(agp_init)(void)
 	return head;
 }
 
+/**
+ * Free the AGP resources.
+ *
+ * Releases the pointer in ::drm_agp.
+ */
 void DRM(agp_uninit)(void)
 {
 	DRM_AGP_PUT;
 	drm_agp = NULL;
 }
 
+/** Calls drm_agp->allocate_memory() */
 agp_memory *DRM(agp_allocate_memory)(size_t pages, u32 type)
 {
 	if (!drm_agp->allocate_memory) return NULL;
 	return drm_agp->allocate_memory(pages, type);
 }
 
+/** Calls drm_agp->free_memory() */
 int DRM(agp_free_memory)(agp_memory *handle)
 {
 	if (!handle || !drm_agp->free_memory) return 0;
@@ -300,12 +434,14 @@ int DRM(agp_free_memory)(agp_memory *handle)
 	return 1;
 }
 
+/** Calls drm_agp->bind_memory() */
 int DRM(agp_bind_memory)(agp_memory *handle, off_t start)
 {
 	if (!handle || !drm_agp->bind_memory) return -EINVAL;
 	return drm_agp->bind_memory(handle, start);
 }
 
+/** Calls drm_agp->unbind_memory() */
 int DRM(agp_unbind_memory)(agp_memory *handle)
 {
 	if (!handle || !drm_agp->unbind_memory) return -EINVAL;
diff --git a/linux-core/drm_auth.c b/linux-core/drm_auth.c
index 8fce6dfc..e027303a 100644
--- a/linux-core/drm_auth.c
+++ b/linux-core/drm_auth.c
@@ -1,4 +1,12 @@
-/* drm_auth.h -- IOCTLs for authentication -*- linux-c -*-
+/**
+ * \file drm_auth.h 
+ * IOCTLs for authentication
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Tue Feb  2 08:37:54 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,20 +31,35 @@
  * 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__
 #include "drmP.h"
 
+/**
+ * Generate a hash key from a magic.
+ *
+ * \param magic magic.
+ * \return hash key.
+ *
+ * The key is the modulus of the hash table size, #DRM_HASH_SIZE, which must be
+ * a power of 2.
+ */
 static int DRM(hash_magic)(drm_magic_t magic)
 {
 	return magic & (DRM_HASH_SIZE-1);
 }
 
+/**
+ * Find the file with the given magic number.
+ *
+ * \param dev DRM device.
+ * \param magic magic number.
+ *
+ * Searches in drm_device::magiclist within all files with the same hash key
+ * the one with matching magic number, while holding the drm_device::struct_sem
+ * lock.
+ */
 static drm_file_t *DRM(find_file)(drm_device_t *dev, drm_magic_t magic)
 {
 	drm_file_t	  *retval = NULL;
@@ -54,6 +77,17 @@ static drm_file_t *DRM(find_file)(drm_device_t *dev, drm_magic_t magic)
 	return retval;
 }
 
+/**
+ * Adds a magic number.
+ * 
+ * \param dev DRM device.
+ * \param priv file private data.
+ * \param magic magic number.
+ *
+ * Creates a drm_magic_entry structure and appends to the linked list
+ * associated the magic number hash key in drm_device::magiclist, while holding
+ * the drm_device::struct_sem lock.
+ */
 int DRM(add_magic)(drm_device_t *dev, drm_file_t *priv, drm_magic_t magic)
 {
 	int		  hash;
@@ -82,12 +116,22 @@ int DRM(add_magic)(drm_device_t *dev, drm_file_t *priv, drm_magic_t magic)
 	return 0;
 }
 
+/**
+ * Remove a magic number.
+ * 
+ * \param dev DRM device.
+ * \param magic magic number.
+ *
+ * Searches and unlinks the entry in drm_device::magiclist with the magic
+ * number hash key, while holding the drm_device::struct_sem lock.
+ */
 int DRM(remove_magic)(drm_device_t *dev, drm_magic_t magic)
 {
 	drm_magic_entry_t *prev = NULL;
 	drm_magic_entry_t *pt;
 	int		  hash;
 
+
 	DRM_DEBUG("%d\n", magic);
 	hash = DRM(hash_magic)(magic);
 
@@ -114,6 +158,19 @@ int DRM(remove_magic)(drm_device_t *dev, drm_magic_t magic)
 	return -EINVAL;
 }
 
+/**
+ * Get a unique magic number (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a resulting drm_auth structure.
+ * \return zero on success, or a negative number on failure.
+ *
+ * If there is a magic number in drm_file::magic then use it, otherwise
+ * searches an unique non-zero magic number and add it associating it with \p
+ * filp.
+ */
 int DRM(getmagic)(struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg)
 {
@@ -143,6 +200,17 @@ int DRM(getmagic)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Authenticate with a magic.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_auth structure.
+ * \return zero if authentication successed, or a negative number otherwise.
+ *
+ * Checks if \p filp is associated with the magic number passed in \arg.
+ */
 int DRM(authmagic)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
diff --git a/linux-core/drm_bufs.c b/linux-core/drm_bufs.c
index 6943eb3d..77573709 100644
--- a/linux-core/drm_bufs.c
+++ b/linux-core/drm_bufs.c
@@ -1,4 +1,12 @@
-/* drm_bufs.h -- Generic buffer template -*- linux-c -*-
+/**
+ * \file drm_bufs.h 
+ * Generic buffer template
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Thu Nov 23 03:10:50 2000 by gareth@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,8 +56,15 @@
 #endif
 #endif
 
-/*
- * Compute order.  Can be made faster.
+
+/**
+ * Compute size order.  Returns the exponent of the smaller power of two which
+ * is greater or equal to given number.
+ * 
+ * \param size size.
+ * \return order.
+ *
+ * \todo Can be made faster.
  */
 int DRM(order)( unsigned long size )
 {
@@ -68,6 +79,19 @@ int DRM(order)( unsigned long size )
 	return order;
 }
 
+/**
+ * Ioctl to specify a range of memory that is available for mapping by a non-root process.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_map structure.
+ * \return zero on success or a negative value on error.
+ *
+ * Adjusts the memory offset to its absolute value according to the mapping
+ * type.  Adds the map to the map list drm_device::maplist. Adds MTRR's where
+ * applicable and if supported by the kernel.
+ */
 int DRM(addmap)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -187,10 +211,22 @@ int DRM(addmap)( struct inode *inode, struct file *filp,
 }
 
 
-/* Remove a map private from list and deallocate resources if the mapping
+/**
+ * Remove a map private from list and deallocate resources if the mapping
  * isn't in use.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_map_t structure.
+ * \return zero on success or a negative value on error.
+ *
+ * Searches the map on drm_device::maplist, removes it from the list, see if
+ * its being used, and free any associate resource (such as MTRR's) if it's not
+ * being on use.
+ *
+ * \sa addmap().
  */
-
 int DRM(rmmap)(struct inode *inode, struct file *filp,
 	       unsigned int cmd, unsigned long arg)
 {
@@ -263,7 +299,13 @@ int DRM(rmmap)(struct inode *inode, struct file *filp,
 
 #if __HAVE_DMA
 
-
+/**
+ * Cleanup after an error on one of the addbufs() functions.
+ *
+ * \param entry buffer entry where the error occurred.
+ *
+ * Frees any pages and buffers associated with the given entry.
+ */
 static void DRM(cleanup_buf_error)(drm_buf_entry_t *entry)
 {
 	int i;
@@ -306,6 +348,19 @@ static void DRM(cleanup_buf_error)(drm_buf_entry_t *entry)
 }
 
 #if __REALLY_HAVE_AGP
+/**
+ * Add AGP buffers for DMA transfers (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_desc_t request.
+ * \return zero on success or a negative number on failure.
+ * 
+ * After some sanity checks creates a drm_buf structure for each buffer and
+ * reallocates the buffer list of the same size order to accommodate the new
+ * buffers.
+ */
 int DRM(addbufs_agp)( struct inode *inode, struct file *filp,
 		      unsigned int cmd, unsigned long arg )
 {
@@ -713,7 +768,7 @@ int DRM(addbufs_pci)( struct inode *inode, struct file *filp,
 }
 #endif /* __HAVE_PCI_DMA */
 
-#ifdef __HAVE_SG
+#if __HAVE_SG
 int DRM(addbufs_sg)( struct inode *inode, struct file *filp,
                      unsigned int cmd, unsigned long arg )
 {
@@ -885,6 +940,20 @@ int DRM(addbufs_sg)( struct inode *inode, struct file *filp,
 }
 #endif /* __HAVE_SG */
 
+/**
+ * Add buffers for DMA transfers (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_desc_t request.
+ * \return zero on success or a negative number on failure.
+ *
+ * According with the memory type specified in drm_buf_desc::flags and the
+ * build options, it dispatches the call either to addbufs_agp(),
+ * addbufs_sg() or addbufs_pci() for AGP, scatter-gather or consistent
+ * PCI memory respectively.
+ */
 int DRM(addbufs)( struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg )
 {
@@ -911,6 +980,24 @@ int DRM(addbufs)( struct inode *inode, struct file *filp,
 #endif
 }
 
+
+/**
+ * Get information about the buffer mappings.
+ *
+ * This was originally mean for debugging purposes, or by a sophisticated
+ * client library to determine how best to use the available buffers (e.g.,
+ * large buffers can be used for image transfer).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_info structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Increments drm_device::buf_use while holding the drm_device::count_lock
+ * lock, preventing of allocating more buffers after this call. Information
+ * about each requested buffer is then copied into user space.
+ */
 int DRM(infobufs)( struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg )
 {
@@ -982,6 +1069,20 @@ int DRM(infobufs)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Specifies a low and high water mark for buffer allocation
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg a pointer to a drm_buf_desc structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies that the size order is bounded between the admissible orders and
+ * updates the respective drm_device_dma::bufs entry low and high water mark.
+ *
+ * \note This ioctl is deprecated and mostly never used.
+ */
 int DRM(markbufs)( struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg )
 {
@@ -1016,6 +1117,18 @@ int DRM(markbufs)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Unreserve the buffers in list, previously reserved using drmDMA. 
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_free structure.
+ * \return zero on success or a negative number on failure.
+ * 
+ * Calls free_buffer() for each used buffer.
+ * This function is primarily used for debugging.
+ */
 int DRM(freebufs)( struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg )
 {
@@ -1057,6 +1170,19 @@ int DRM(freebufs)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Maps all of the DMA buffers into client-virtual space (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_map structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Maps the AGP or SG buffer region with do_mmap(), and copies information
+ * about each buffer into user space. The PCI buffers are already mapped on the
+ * addbufs_pci() call.
+ */
 int DRM(mapbufs)( struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg )
 {
diff --git a/linux-core/drm_context.c b/linux-core/drm_context.c
index 3853a7c6..82e90bcc 100644
--- a/linux-core/drm_context.c
+++ b/linux-core/drm_context.c
@@ -1,4 +1,12 @@
-/* drm_context.h -- IOCTLs for generic contexts -*- linux-c -*-
+/**
+ * \file drm_context.h 
+ * IOCTLs for generic contexts
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Fri Nov 24 18:31:37 2000 by gareth@valinux.com
  *
  * Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,10 +31,9 @@
  * 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>
+ */
+
+/*
  * ChangeLog:
  *  2001-11-16	Torsten Duwe <duwe@caldera.de>
  *		added context constructor/destructor hooks,
@@ -41,10 +48,20 @@
 #endif
 
 
-/* ================================================================
- * Context bitmap support
- */
+/******************************************************************/
+/** \name Context bitmap support */
+/*@{*/
 
+/**
+ * Free a handle from the context bitmap.
+ *
+ * \param dev DRM device.
+ * \param ctx_handle context handle.
+ *
+ * Clears the bit specified by \p ctx_handle in drm_device::ctx_bitmap and the entry
+ * in drm_device::context_sareas, while holding the drm_device::struct_sem
+ * lock.
+ */
 void DRM(ctxbitmap_free)( drm_device_t *dev, int ctx_handle )
 {
 	if ( ctx_handle < 0 ) goto failed;
@@ -63,6 +80,16 @@ failed:
        	return;
 }
 
+/** 
+ * Context bitmap allocation.
+ *
+ * \param dev DRM device.
+ * \return (non-negative) context handle on success or a negative number on failure.
+ *
+ * Find the first zero bit in drm_device::ctx_bitmap and (re)allocates
+ * drm_device::context_sareas to accommodate the new entry while holding the
+ * drm_device::struct_sem lock.
+ */
 int DRM(ctxbitmap_next)( drm_device_t *dev )
 {
 	int bit;
@@ -113,6 +140,14 @@ int DRM(ctxbitmap_next)( drm_device_t *dev )
 	return -1;
 }
 
+/**
+ * Context bitmap initialization.
+ *
+ * \param dev DRM device.
+ *
+ * Allocates and initialize drm_device::ctx_bitmap and drm_device::context_sareas, while holding
+ * the drm_device::struct_sem lock.
+ */
 int DRM(ctxbitmap_init)( drm_device_t *dev )
 {
 	int i;
@@ -138,6 +173,14 @@ int DRM(ctxbitmap_init)( drm_device_t *dev )
 	return 0;
 }
 
+/**
+ * Context bitmap cleanup.
+ *
+ * \param dev DRM device.
+ *
+ * Frees drm_device::ctx_bitmap and drm_device::context_sareas, while holding
+ * the drm_device::struct_sem lock.
+ */
 void DRM(ctxbitmap_cleanup)( drm_device_t *dev )
 {
 	down(&dev->struct_sem);
@@ -149,10 +192,24 @@ void DRM(ctxbitmap_cleanup)( drm_device_t *dev )
 	up(&dev->struct_sem);
 }
 
-/* ================================================================
- * Per Context SAREA Support
- */
+/*@}*/
+
+/******************************************************************/
+/** \name Per Context SAREA Support */
+/*@{*/
 
+/**
+ * Get per-context SAREA.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx_priv_map structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Gets the map from drm_device::context_sareas with the handle specified and
+ * returns its handle.
+ */
 int DRM(getsareactx)(struct inode *inode, struct file *filp,
 		     unsigned int cmd, unsigned long arg)
 {
@@ -181,6 +238,18 @@ int DRM(getsareactx)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Set per-context SAREA.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx_priv_map structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Searches the mapping specified in \p arg and update the entry in
+ * drm_device::context_sareas with it.
+ */
 int DRM(setsareactx)(struct inode *inode, struct file *filp,
 		     unsigned int cmd, unsigned long arg)
 {
@@ -219,10 +288,22 @@ found:
 	return 0;
 }
 
-/* ================================================================
- * The actual DRM context handling routines
- */
+/*@}*/
+
+/******************************************************************/
+/** \name The actual DRM context handling routines */
+/*@{*/
 
+/**
+ * Switch context.
+ *
+ * \param dev DRM device.
+ * \param old old context handle.
+ * \param new new context handle.
+ * \return zero on success or a negative number on failure.
+ *
+ * Attempt to set drm_device::context_flag.
+ */
 int DRM(context_switch)( drm_device_t *dev, int old, int new )
 {
         if ( test_and_set_bit( 0, &dev->context_flag ) ) {
@@ -241,6 +322,17 @@ int DRM(context_switch)( drm_device_t *dev, int old, int new )
         return 0;
 }
 
+/**
+ * Complete context switch.
+ *
+ * \param dev DRM device.
+ * \param new new context handle.
+ * \return zero on success or a negative number on failure.
+ *
+ * Updates drm_device::last_context and drm_device::last_switch. Verifies the
+ * hardware lock is held, clears the drm_device::context_flag and wakes up
+ * drm_device::context_wait.
+ */
 int DRM(context_switch_complete)( drm_device_t *dev, int new )
 {
         dev->last_context = new;  /* PRE/POST: This is the _only_ writer. */
@@ -259,6 +351,15 @@ int DRM(context_switch_complete)( drm_device_t *dev, int new )
         return 0;
 }
 
+/**
+ * Reserve contexts.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx_res structure.
+ * \return zero on success or a negative number on failure.
+ */
 int DRM(resctx)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -285,6 +386,17 @@ int DRM(resctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Add context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Get a new handle for the context and copy to userspace.
+ */
 int DRM(addctx)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -323,6 +435,15 @@ int DRM(modctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Get context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ */
 int DRM(getctx)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -339,6 +460,17 @@ int DRM(getctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Switch context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Calls context_switch().
+ */
 int DRM(switchctx)( struct inode *inode, struct file *filp,
 		    unsigned int cmd, unsigned long arg )
 {
@@ -353,6 +485,17 @@ int DRM(switchctx)( struct inode *inode, struct file *filp,
 	return DRM(context_switch)( dev, dev->last_context, ctx.handle );
 }
 
+/**
+ * New context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Calls context_switch_complete().
+ */
 int DRM(newctx)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -369,6 +512,17 @@ int DRM(newctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Remove context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * If not the special kernel context, calls ctxbitmap_free() to free the specified context.
+ */
 int DRM(rmctx)( struct inode *inode, struct file *filp,
 		unsigned int cmd, unsigned long arg )
 {
@@ -393,3 +547,4 @@ int DRM(rmctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/*@}*/
diff --git a/linux-core/drm_dma.c b/linux-core/drm_dma.c
index 34ab5322..8e0ec95e 100644
--- a/linux-core/drm_dma.c
+++ b/linux-core/drm_dma.c
@@ -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;
diff --git a/linux-core/drm_drawable.c b/linux-core/drm_drawable.c
index 13e46b9f..892ae4e0 100644
--- a/linux-core/drm_drawable.c
+++ b/linux-core/drm_drawable.c
@@ -1,4 +1,12 @@
-/* drm_drawable.h -- IOCTLs for drawables -*- linux-c -*-
+/**
+ * \file drm_drawable.h 
+ * IOCTLs for drawables
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Tue Feb  2 08:37:54 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,15 +31,12 @@
  * 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__
 #include "drmP.h"
 
+/** No-op. */
 int DRM(adddraw)(struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg)
 {
@@ -44,6 +49,7 @@ int DRM(adddraw)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/** No-op. */
 int DRM(rmdraw)(struct inode *inode, struct file *filp,
 		unsigned int cmd, unsigned long arg)
 {
diff --git a/linux-core/drm_drv.c b/linux-core/drm_drv.c
index 0a4390d3..90c2d18b 100644
--- a/linux-core/drm_drv.c
+++ b/linux-core/drm_drv.c
@@ -1,4 +1,31 @@
-/* drm_drv.h -- Generic driver template -*- linux-c -*-
+/**
+ * \file drm_drv.h 
+ * Generic driver template
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ *
+ * To use this template, you must at least define the following (samples
+ * given for the MGA driver):
+ *
+ * \code
+ * #define DRIVER_AUTHOR	"VA Linux Systems, Inc."
+ *
+ * #define DRIVER_NAME		"mga"
+ * #define DRIVER_DESC		"Matrox G200/G400"
+ * #define DRIVER_DATE		"20001127"
+ *
+ * #define DRIVER_MAJOR		2
+ * #define DRIVER_MINOR		0
+ * #define DRIVER_PATCHLEVEL	2
+ *
+ * #define DRIVER_IOCTL_COUNT	DRM_ARRAY_SIZE( mga_ioctls )
+ *
+ * #define DRM(x)		mga_##x
+ * \endcode
+ */
+
+/*
  * Created: Thu Nov 23 03:10:50 2000 by gareth@valinux.com
  *
  * Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,29 +50,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>
- */
-
-/*
- * To use this template, you must at least define the following (samples
- * given for the MGA driver):
- *
- * #define DRIVER_AUTHOR	"VA Linux Systems, Inc."
- *
- * #define DRIVER_NAME		"mga"
- * #define DRIVER_DESC		"Matrox G200/G400"
- * #define DRIVER_DATE		"20001127"
- *
- * #define DRIVER_MAJOR		2
- * #define DRIVER_MINOR		0
- * #define DRIVER_PATCHLEVEL	2
- *
- * #define DRIVER_IOCTL_COUNT	DRM_ARRAY_SIZE( mga_ioctls )
- *
- * #define DRM(x)		mga_##x
  */
 
 #ifndef __MUST_HAVE_AGP
@@ -134,12 +138,13 @@ static struct file_operations	DRM(fops) = {	\
 #endif
 
 #ifndef MODULE
-/* DRM(options) is called by the kernel to parse command-line options
- * passed via the boot-loader (e.g., LILO).  It calls the insmod option
- * routine, drm_parse_drm.
- */
-/* Use an additional macro to avoid preprocessor troubles */
+/** Use an additional macro to avoid preprocessor troubles */
 #define DRM_OPTIONS_FUNC DRM(options)
+/**
+ * Called by the kernel to parse command-line options passed via the
+ * boot-loader (e.g., LILO).  It calls the insmod option routine,
+ * parse_options().
+ */
 static int __init DRM(options)( char *str )
 {
 	DRM(parse_options)( str );
@@ -150,7 +155,7 @@ __setup( DRIVER_NAME "=", DRM_OPTIONS_FUNC );
 #undef DRM_OPTIONS_FUNC
 #endif
 
-/*
+/**
  * The default number of instances (minor numbers) to initialize.
  */
 #ifndef DRIVER_NUM_CARDS
@@ -163,6 +168,7 @@ static int		DRM(numdevs) = 0;
 
 DRIVER_FOPS;
 
+/** Ioctl table */
 static drm_ioctl_desc_t		  DRM(ioctls)[] = {
 	[DRM_IOCTL_NR(DRM_IOCTL_VERSION)]       = { DRM(version),     0, 0 },
 	[DRM_IOCTL_NR(DRM_IOCTL_GET_UNIQUE)]    = { DRM(getunique),   0, 0 },
@@ -349,7 +355,8 @@ static int DRM(setup)( drm_device_t *dev )
 
 	DRM_DEBUG( "\n" );
 
-	/* The kernel's context could be created here, but is now created
+	/*
+	 * The kernel's context could be created here, but is now created
 	 * in drm_dma_enqueue.	This is more resource-efficient for
 	 * hardware that does not do DMA, but may mean that
 	 * drm_select_queue fails between the time the interrupt is
@@ -360,6 +367,15 @@ static int DRM(setup)( drm_device_t *dev )
 }
 
 
+/**
+ * Take down the DRM device.
+ *
+ * \param dev DRM device structure.
+ *
+ * Frees every resource in \p dev.
+ *
+ * \sa drm_device and setup().
+ */
 static int DRM(takedown)( drm_device_t *dev )
 {
 	drm_magic_entry_t *pt, *next;
@@ -517,8 +533,12 @@ static int DRM(takedown)( drm_device_t *dev )
 	return 0;
 }
 
-/*
+/**
  * Figure out how many instances to initialize.
+ *
+ * \return number of cards found.
+ *
+ * Searches for every PCI card in \c DRIVER_CARD_LIST with matching vendor and device ids.
  */
 static int drm_count_cards(void)
 {
@@ -552,8 +572,18 @@ static int drm_count_cards(void)
 	return num;
 }
 
-/* drm_init is called via init_module at module load time, or via
+/**
+ * Module initialization. Called via init_module at module load time, or via
  * linux/init/main.c (this is not currently supported).
+ *
+ * \return zero on success or a negative number on failure.
+ *
+ * Allocates and initialize an array of drm_device structures, and attempts to
+ * initialize all available devices, using consecutive minors, 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.
  */
 static int __init drm_init( void )
 {
@@ -641,7 +671,12 @@ static int __init drm_init( void )
 	return 0;
 }
 
-/* drm_cleanup is called via cleanup_module at module unload time.
+/**
+ * Called via cleanup_module() at module unload time.
+ *
+ * Cleans up all DRM device, calling takedown().
+ * 
+ * \sa drm_init().
  */
 static void __exit drm_cleanup( void )
 {
@@ -694,6 +729,17 @@ module_init( drm_init );
 module_exit( drm_cleanup );
 
 
+/**
+ * Get version information
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_version structure.
+ * \return zero on success or negative number on failure.
+ *
+ * Fills in the version information in \p arg.
+ */
 int DRM(version)( struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg )
 {
@@ -729,6 +775,17 @@ int DRM(version)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Open file.
+ * 
+ * \param inode device inode
+ * \param filp file pointer.
+ * \return zero on success or a negative number on failure.
+ *
+ * Searches the DRM device with the same minor number, calls open_helper(), and
+ * increments the device open count. If the open count was previous at zero,
+ * i.e., it's the first that the device is open, then calls setup().
+ */
 int DRM(open)( struct inode *inode, struct file *filp )
 {
 	drm_device_t *dev = NULL;
@@ -759,6 +816,18 @@ int DRM(open)( struct inode *inode, struct file *filp )
 	return retcode;
 }
 
+/**
+ * Release file.
+ *
+ * \param inode device inode
+ * \param filp file pointer.
+ * \return zero on success or a negative number on failure.
+ *
+ * If the hardware lock is held then free it, and take it again for the kernel
+ * context since it's necessary to reclaim buffers. Unlink the file private
+ * data from its list and free it. Decreases the open count and if it reaches
+ * zero calls takedown().
+ */
 int DRM(release)( struct inode *inode, struct file *filp )
 {
 	drm_file_t *priv = filp->private_data;
@@ -885,7 +954,17 @@ int DRM(release)( struct inode *inode, struct file *filp )
 	return retcode;
 }
 
-/* DRM(ioctl) is called whenever a process performs an ioctl on /dev/drm.
+/** 
+ * Called whenever a process performs an ioctl on /dev/drm.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument.
+ * \return zero on success or negative number on failure.
+ *
+ * Looks up the ioctl function in the ::ioctls table, checking for root
+ * previleges if so required, and dispatches to the respective function.
  */
 int DRM(ioctl)( struct inode *inode, struct file *filp,
 		unsigned int cmd, unsigned long arg )
@@ -926,6 +1005,17 @@ int DRM(ioctl)( struct inode *inode, struct file *filp,
 	return retcode;
 }
 
+/** 
+ * Lock ioctl.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_lock structure.
+ * \return zero on success or negative number on failure.
+ *
+ * Add the current task to the lock wait queue, and attempt to take to lock.
+ */
 int DRM(lock)( struct inode *inode, struct file *filp,
 	       unsigned int cmd, unsigned long arg )
 {
@@ -1031,7 +1121,17 @@ int DRM(lock)( struct inode *inode, struct file *filp,
         return ret;
 }
 
-
+/** 
+ * Unlock ioctl.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_lock structure.
+ * \return zero on success or negative number on failure.
+ *
+ * Transfer and free the lock.
+ */
 int DRM(unlock)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
diff --git a/linux-core/drm_fops.c b/linux-core/drm_fops.c
index fc8618e1..f4841ae8 100644
--- a/linux-core/drm_fops.c
+++ b/linux-core/drm_fops.c
@@ -1,4 +1,13 @@
-/* drm_fops.h -- File operations for DRM -*- linux-c -*-
+/**
+ * \file drm_fops.h 
+ * File operations for DRM
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Daryll Strauss <daryll@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Mon Jan  4 08:58:31 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,19 +32,24 @@
  * 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>
- *    Daryll Strauss <daryll@valinux.com>
- *    Gareth Hughes <gareth@valinux.com>
  */
 
 #define __NO_VERSION__
 #include "drmP.h"
 #include <linux/poll.h>
 
-/* drm_open is called whenever a process opens /dev/drm. */
 
+/**
+ * Called whenever a process opens /dev/drm. 
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param dev device.
+ * \return zero on success or a negative number on failure.
+ * 
+ * Creates and initializes a drm_file structure for the file private data in \p
+ * filp and add it into the double linked list in \p dev.
+ */
 int DRM(open_helper)(struct inode *inode, struct file *filp, drm_device_t *dev)
 {
 	int	     minor = minor(inode->i_rdev);
@@ -91,6 +105,7 @@ int DRM(open_helper)(struct inode *inode, struct file *filp, drm_device_t *dev)
 	return 0;
 }
 
+/** No-op. */
 int DRM(flush)(struct file *filp)
 {
 	drm_file_t    *priv   = filp->private_data;
@@ -101,6 +116,7 @@ int DRM(flush)(struct file *filp)
 	return 0;
 }
 
+/** No-op. */
 int DRM(fasync)(int fd, struct file *filp, int on)
 {
 	drm_file_t    *priv   = filp->private_data;
@@ -114,6 +130,7 @@ int DRM(fasync)(int fd, struct file *filp, int on)
 }
 
 #if !__HAVE_DRIVER_FOPS_POLL
+/** No-op. */
 unsigned int DRM(poll)(struct file *filp, struct poll_table_struct *wait)
 {
 	return 0;
@@ -122,6 +139,7 @@ unsigned int DRM(poll)(struct file *filp, struct poll_table_struct *wait)
 
 
 #if !__HAVE_DRIVER_FOPS_READ
+/** No-op. */
 ssize_t DRM(read)(struct file *filp, char *buf, size_t count, loff_t *off)
 {
 	return 0;
diff --git a/linux-core/drm_init.c b/linux-core/drm_init.c
index 3aa4ad59..509e6841 100644
--- a/linux-core/drm_init.c
+++ b/linux-core/drm_init.c
@@ -1,4 +1,12 @@
-/* drm_init.h -- Setup/Cleanup for DRM -*- linux-c -*-
+/**
+ * \file drm_init.h 
+ * Setup/Cleanup for DRM
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Mon Jan  4 08:58:31 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,23 +31,24 @@
  * 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__
 #include "drmP.h"
 
+/** Debug flags.  Set by parse_option(). */
 #if 0
 int DRM(flags) = DRM_FLAG_DEBUG;
 #else
 int DRM(flags) = 0;
 #endif
 
-/* drm_parse_option parses a single option.  See description for
- * drm_parse_options for details.
+/**
+ * Parse a single option.
+ *
+ * \param s option string.
+ *
+ * \sa See parse_options() for details.
  */
 static void DRM(parse_option)(char *s)
 {
@@ -59,26 +68,33 @@ static void DRM(parse_option)(char *s)
 	return;
 }
 
-/* drm_parse_options parse the insmod "drm_opts=" options, or the command-line
- * options passed to the kernel via LILO.  The grammar of the format is as
+/**
+ * Parse the insmod "drm_opts=" options, or the command-line
+ * options passed to the kernel via LILO.  
+ *
+ * \param s contains option_list without the 'drm_opts=' part.
+ *
+ * The grammar of the format is as
  * follows:
  *
+ * \code
  * drm		::= 'drm_opts=' option_list
  * option_list	::= option [ ';' option_list ]
  * option	::= 'device:' major
  *		|   'debug'
  *		|   'noctx'
  * major	::= INTEGER
+ * \endcode
  *
- * Note that 's' contains option_list without the 'drm_opts=' part.
- *
- * device=major,minor specifies the device number used for /dev/drm
- *	  if major == 0 then the misc device is used
- *	  if major == 0 and minor == 0 then dynamic misc allocation is used
- * debug=on specifies that debugging messages will be printk'd
- * debug=trace specifies that each function call will be logged via printk
- * debug=off turns off all debugging options
+ * - device=major,minor specifies the device number used for /dev/drm
+ *   - if major == 0 then the misc device is used
+ *   - if major == 0 and minor == 0 then dynamic misc allocation is used
+ * - debug=on specifies that debugging messages will be printk'd
+ * - debug=trace specifies that each function call will be logged via printk
+ * - debug=off turns off all debugging options
  *
+ * \todo Actually only the \e presence of the 'debug' option is currently
+ * checked.
  */
 
 void DRM(parse_options)(char *s)
@@ -96,8 +112,10 @@ void DRM(parse_options)(char *s)
 	}
 }
 
-/* drm_cpu_valid returns non-zero if the DRI will run on this CPU, and 0
- * otherwise.
+/**
+ * Check whether DRI will run on this CPU.
+ *
+ * \return non-zero if the DRI will run on this CPU, or zero otherwise.
  */
 int DRM(cpu_valid)(void)
 {
diff --git a/linux-core/drm_ioctl.c b/linux-core/drm_ioctl.c
index 62d5a6e4..8d98000f 100644
--- a/linux-core/drm_ioctl.c
+++ b/linux-core/drm_ioctl.c
@@ -1,4 +1,12 @@
-/* drm_ioctl.h -- IOCTL processing for DRM -*- linux-c -*-
+/**
+ * \file drm_ioctl.h 
+ * IOCTL processing for DRM
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Fri Jan  8 09:01:26 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,16 +31,23 @@
  * 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__
 #include "drmP.h"
 
 
+/**
+ * Get interrupt from bus id.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \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.
+ */
 int DRM(irq_busid)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
@@ -85,6 +100,17 @@ int DRM(irq_busid)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Get the bus id.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_unique structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Copies the bus id from drm_device::unique into user space.
+ */
 int DRM(getunique)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
@@ -104,6 +130,18 @@ int DRM(getunique)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Set the bus id.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_unique structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Copies the bus id from userspace into drm_device::unique, and searches for
+ * the respective PCI device, updating drm_device::pdev.
+ */
 int DRM(setunique)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
@@ -181,6 +219,19 @@ int DRM(setunique)(struct inode *inode, struct file *filp,
 }
 
 
+/**
+ * Get a mapping information.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_map structure.
+ * 
+ * \return zero on success or a negative number on failure.
+ *
+ * Searches for the mapping with the specified offset and copies its information
+ * into userspace
+ */
 int DRM(getmap)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -227,6 +278,19 @@ int DRM(getmap)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Get client information.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_client structure.
+ * 
+ * \return zero on success or a negative number on failure.
+ *
+ * Searches for the client with the specified index and copies its information
+ * into userspace
+ */
 int DRM(getclient)( struct inode *inode, struct file *filp,
 		    unsigned int cmd, unsigned long arg )
 {
@@ -260,6 +324,16 @@ int DRM(getclient)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/** 
+ * Get statistics information. 
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_stats structure.
+ * 
+ * \return zero on success or a negative number on failure.
+ */
 int DRM(getstats)( struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg )
 {
diff --git a/linux-core/drm_lock.c b/linux-core/drm_lock.c
index cc9571ed..29db1079 100644
--- a/linux-core/drm_lock.c
+++ b/linux-core/drm_lock.c
@@ -1,4 +1,12 @@
-/* lock.c -- IOCTLs for locking -*- linux-c -*-
+/**
+ * \file drm_lock.h 
+ * IOCTLs for locking
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Tue Feb  2 08:37:54 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,15 +31,12 @@
  * 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__
 #include "drmP.h"
 
+/** No-op ioctl. */
 int DRM(noop)(struct inode *inode, struct file *filp, unsigned int cmd,
 	       unsigned long arg)
 {
@@ -39,7 +44,15 @@ int DRM(noop)(struct inode *inode, struct file *filp, unsigned int cmd,
 	return 0;
 }
 
-
+/**
+ * Take the heavyweight lock.
+ *
+ * \param lock lock pointer.
+ * \param context locking context.
+ * \return one if the lock is held, or zero otherwise.
+ *
+ * Attempt to mark the lock as held by the given context, via the \p cmpxchg instruction.
+ */
 int DRM(lock_take)(__volatile__ unsigned int *lock, unsigned int context)
 {
 	unsigned int old, new, prev;
@@ -66,8 +79,18 @@ int DRM(lock_take)(__volatile__ unsigned int *lock, unsigned int context)
 	return 0;
 }
 
-/* This takes a lock forcibly and hands it to context.	Should ONLY be used
-   inside *_unlock to give lock to kernel before calling *_dma_schedule. */
+/**
+ * This takes a lock forcibly and hands it to context.	Should ONLY be used
+ * inside *_unlock to give lock to kernel before calling *_dma_schedule. 
+ * 
+ * \param dev DRM device.
+ * \param lock lock pointer.
+ * \param context locking context.
+ * \return always one.
+ *
+ * Resets the lock file pointer.
+ * Marks the lock as held by the given context, via the \p cmpxchg instruction.
+ */
 int DRM(lock_transfer)(drm_device_t *dev,
 		       __volatile__ unsigned int *lock, unsigned int context)
 {
@@ -82,6 +105,17 @@ int DRM(lock_transfer)(drm_device_t *dev,
 	return 1;
 }
 
+/**
+ * Free lock.
+ * 
+ * \param dev DRM device.
+ * \param lock lock.
+ * \param context context.
+ * 
+ * Resets the lock file pointer.
+ * Marks the lock as not held, via the \p cmpxchg instruction. Wakes any task
+ * waiting on the lock queue.
+ */
 int DRM(lock_free)(drm_device_t *dev,
 		   __volatile__ unsigned int *lock, unsigned int context)
 {
@@ -103,18 +137,17 @@ int DRM(lock_free)(drm_device_t *dev,
 	return 0;
 }
 
-/* If we get here, it means that the process has called DRM_IOCTL_LOCK
-   without calling DRM_IOCTL_UNLOCK.
-
-   If the lock is not held, then let the signal proceed as usual.
-
-   If the lock is held, then set the contended flag and keep the signal
-   blocked.
-
-
-   Return 1 if the signal should be delivered normally.
-   Return 0 if the signal should be blocked.  */
-
+/**
+ * If we get here, it means that the process has called DRM_IOCTL_LOCK
+ * without calling DRM_IOCTL_UNLOCK.
+ *
+ * If the lock is not held, then let the signal proceed as usual.  If the lock
+ * is held, then set the contended flag and keep the signal blocked.
+ *
+ * \param priv pointer to a drm_sigdata structure.
+ * \return one if the signal should be delivered normally, or zero if the
+ * signal should be blocked.
+ */
 int DRM(notifier)(void *priv)
 {
 	drm_sigdata_t *s = (drm_sigdata_t *)priv;
diff --git a/linux-core/drm_memory.h b/linux-core/drm_memory.h
index 5f111459..2a969fcd 100644
--- a/linux-core/drm_memory.h
+++ b/linux-core/drm_memory.h
@@ -1,4 +1,12 @@
-/* drm_memory.h -- Memory management wrappers for DRM -*- linux-c -*-
+/** 
+ * \file drm_memory.h 
+ * Memory management wrappers for DRM
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/* 
  * Created: Thu Feb  4 14:00:34 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,17 +31,14 @@
  * 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__
 #include <linux/config.h>
 #include "drmP.h"
 
-/* Cut down version of drm_memory_debug.h, which used to be called
+/**
+ * Cut down version of drm_memory_debug.h, which used to be called
  * drm_memory.h.  If you want the debug functionality, change 0 to 1
  * below.
  */
@@ -196,22 +201,38 @@ static inline void drm_ioremapfree(void *pt, unsigned long size, drm_device_t *d
 #if DEBUG_MEMORY
 #include "drm_memory_debug.h"
 #else
+
+/** No-op. */
 void DRM(mem_init)(void)
 {
 }
 
-/* drm_mem_info is called whenever a process reads /dev/drm/mem. */
+/**
+ * Called when "/proc/dri/%dev%/mem" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param len requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ *
+ * No-op. 
+ */
 int DRM(mem_info)(char *buf, char **start, off_t offset,
 		  int len, int *eof, void *data)
 {
 	return 0;
 }
 
+/** Wrapper around kmalloc() */
 void *DRM(alloc)(size_t size, int area)
 {
 	return kmalloc(size, GFP_KERNEL);
 }
 
+/** Wrapper around kmalloc() and kfree() */
 void *DRM(realloc)(void *oldpt, size_t oldsize, size_t size, int area)
 {
 	void *pt;
@@ -224,11 +245,21 @@ void *DRM(realloc)(void *oldpt, size_t oldsize, size_t size, int area)
 	return pt;
 }
 
+/** Wrapper around kfree() */
 void DRM(free)(void *pt, size_t size, int area)
 {
 	kfree(pt);
 }
 
+/**
+ * Allocate pages.
+ *
+ * \param order size order.
+ * \param area memory area. (Not used.)
+ * \return page address on success, or zero on failure.
+ *
+ * Allocate and reserve free pages.
+ */
 unsigned long DRM(alloc_pages)(int order, int area)
 {
 	unsigned long address;
@@ -253,6 +284,15 @@ unsigned long DRM(alloc_pages)(int order, int area)
 	return address;
 }
 
+/**
+ * Free pages.
+ * 
+ * \param address address of the pages to free.
+ * \param order size order.
+ * \param area memory area. (Not used.)
+ *
+ * Unreserve and free pages allocated by alloc_pages().
+ */
 void DRM(free_pages)(unsigned long address, int order, int area)
 {
 	unsigned long bytes = PAGE_SIZE << order;
@@ -272,37 +312,44 @@ void DRM(free_pages)(unsigned long address, int order, int area)
 	free_pages(address, order);
 }
 
+/** Wrapper around drm_ioremap() */
 void *DRM(ioremap)(unsigned long offset, unsigned long size, drm_device_t *dev)
 {
 	return drm_ioremap(offset, size, dev);
 }
 
+/** Wrapper around drm_ioremap_nocache() */
 void *DRM(ioremap_nocache)(unsigned long offset, unsigned long size, drm_device_t *dev)
 {
 	return drm_ioremap_nocache(offset, size, dev);
 }
 
+/** Wrapper around drm_iounmap() */
 void DRM(ioremapfree)(void *pt, unsigned long size, drm_device_t *dev)
 {
 	drm_ioremapfree(pt, size, dev);
 }
 
 #if __REALLY_HAVE_AGP
+/** Wrapper around agp_allocate_memory() */
 agp_memory *DRM(alloc_agp)(int pages, u32 type)
 {
 	return DRM(agp_allocate_memory)(pages, type);
 }
 
+/** Wrapper around agp_free_memory() */
 int DRM(free_agp)(agp_memory *handle, int pages)
 {
 	return DRM(agp_free_memory)(handle) ? 0 : -EINVAL;
 }
 
+/** Wrapper around agp_bind_memory() */
 int DRM(bind_agp)(agp_memory *handle, unsigned int start)
 {
 	return DRM(agp_bind_memory)(handle, start);
 }
 
+/** Wrapper around agp_unbind_memory() */
 int DRM(unbind_agp)(agp_memory *handle)
 {
 	return DRM(agp_unbind_memory)(handle);
diff --git a/linux-core/drm_memory_debug.h b/linux-core/drm_memory_debug.h
index d74267fb..5cfff83a 100644
--- a/linux-core/drm_memory_debug.h
+++ b/linux-core/drm_memory_debug.h
@@ -1,6 +1,12 @@
-/* drm_memory.h -- Memory management wrappers for DRM -*- linux-c -*-
- * Created: Thu Feb  4 14:00:34 1999 by faith@valinux.com
+/**
+ * \file drm_memory.h 
+ * Memory management wrappers for DRM.
  *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
@@ -23,10 +29,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__
diff --git a/linux-core/drm_os_linux.h b/linux-core/drm_os_linux.h
index e804399a..c5cb65f1 100644
--- a/linux-core/drm_os_linux.h
+++ b/linux-core/drm_os_linux.h
@@ -1,36 +1,56 @@
+/**
+ * \file drm_os_linux.h
+ * OS abstraction macros.
+ */
+
 #define __NO_VERSION__
 
 #include <linux/interrupt.h>	/* For task queue support */
 #include <linux/delay.h>
 
+/** File pointer type */
 #define DRMFILE                         struct file *
+/** Ioctl arguments */
 #define DRM_IOCTL_ARGS			struct inode *inode, struct file *filp, unsigned int cmd, unsigned long data
 #define DRM_ERR(d)			-(d)
+/** Current process ID */
 #define DRM_CURRENTPID			current->pid
 #define DRM_UDELAY(d)			udelay(d)
+/** Read a byte from a MMIO region */
 #define DRM_READ8(map, offset)		readb(((unsigned long)(map)->handle) + (offset))
+/** Read a dword from a MMIO region */
 #define DRM_READ32(map, offset)		readl(((unsigned long)(map)->handle) + (offset))
+/** Write a byte into a MMIO region */
 #define DRM_WRITE8(map, offset, val)	writeb(val, ((unsigned long)(map)->handle) + (offset))
+/** Write a dword into a MMIO region */
 #define DRM_WRITE32(map, offset, val)	writel(val, ((unsigned long)(map)->handle) + (offset))
-#define DRM_READMEMORYBARRIER()		rmb()
-#define DRM_WRITEMEMORYBARRIER()	wmb()
-#define DRM_MEMORYBARRIER()		mb()
+/** Read memory barrier */
+#define DRM_READMEMORYBARRIER(map)	rmb()
+/** Write memory barrier */
+#define DRM_WRITEMEMORYBARRIER(map)	wmb()
+/** Read/write memory barrier */
+#define DRM_MEMORYBARRIER(map)	mb()
+/** DRM device local declaration */
 #define DRM_DEVICE	drm_file_t	*priv	= filp->private_data; \
 			drm_device_t	*dev	= priv->dev
-
+			
+/** IRQ handler arguments */
 #define DRM_IRQ_ARGS	        int irq, void *arg, struct pt_regs *regs
+/** Task queue handler arguments */
 #define DRM_TASKQUEUE_ARGS	void *arg
 
-/* For data going from/to the kernel through the ioctl argument */
+/** For data going into the kernel through the ioctl argument */
 #define DRM_COPY_FROM_USER_IOCTL(arg1, arg2, arg3)	\
 	if ( copy_from_user(&arg1, arg2, arg3) )	\
 		return -EFAULT
+/** For data going from the kernel through the ioctl argument */
 #define DRM_COPY_TO_USER_IOCTL(arg1, arg2, arg3)	\
 	if ( copy_to_user(arg1, &arg2, arg3) )		\
 		return -EFAULT
-/* Other copying of data from/to kernel space */
+/** Other copying of data to kernel space */
 #define DRM_COPY_FROM_USER(arg1, arg2, arg3)		\
 	copy_from_user(arg1, arg2, arg3)
+/** Other copying of data from kernel space */
 #define DRM_COPY_TO_USER(arg1, arg2, arg3)		\
 	copy_to_user(arg1, arg2, arg3)
 /* Macros for copyfrom user, but checking readability only once */
@@ -42,10 +62,16 @@
 	__get_user(val, uaddr)
 
 
-/* malloc/free without the overhead of DRM(alloc) */
+/** 'malloc' without the overhead of DRM(alloc)() */
 #define DRM_MALLOC(x) kmalloc(x, GFP_KERNEL)
+/** 'free' without the overhead of DRM(free)() */
 #define DRM_FREE(x,size) kfree(x)
 
+/** 
+ * Get the pointer to the SAREA.
+ *
+ * Searches the SAREA on the mapping lists and points drm_device::sarea to it.
+ */
 #define DRM_GETSAREA()							 \
 do { 									 \
 	drm_map_list_t *entry;						 \
diff --git a/linux-core/drm_proc.c b/linux-core/drm_proc.c
index f73b7ccd..e1313125 100644
--- a/linux-core/drm_proc.c
+++ b/linux-core/drm_proc.c
@@ -1,4 +1,16 @@
-/* drm_proc.h -- /proc support for DRM -*- linux-c -*-
+/**
+ * \file drm_proc.h 
+ * /proc support for DRM
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ *
+ * \par Acknowledgements:
+ *    Matthew J Sottek <matthew.j.sottek@intel.com> sent in a patch to fix
+ *    the problem with the proc files not outputting all their information.
+ */
+
+/*
  * Created: Mon Jan 11 09:48:47 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,14 +35,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>
- *
- * Acknowledgements:
- *    Matthew J Sottek <matthew.j.sottek@intel.com> sent in a patch to fix
- *    the problem with the proc files not outputting all their information.
  */
 
 #define __NO_VERSION__
@@ -51,9 +55,12 @@ static int	   DRM(vma_info)(char *buf, char **start, off_t offset,
 				 int request, int *eof, void *data);
 #endif
 
+/**
+ * Proc file list.
+ */
 struct drm_proc_list {
-	const char *name;
-	int	   (*f)(char *, char **, off_t, int, int *, void *);
+	const char *name;	/**< file name */
+	int	   (*f)(char *, char **, off_t, int, int *, void *);	/**< proc callback*/
 } DRM(proc_list)[] = {
 	{ "name",    DRM(name_info)    },
 	{ "mem",     DRM(mem_info)     },
@@ -67,6 +74,19 @@ struct drm_proc_list {
 };
 #define DRM_PROC_ENTRIES (sizeof(DRM(proc_list))/sizeof(DRM(proc_list)[0]))
 
+/**
+ * Initialize the DRI proc filesystem for a device.
+ *
+ * \param dev DRM device.
+ * \param minor device minor number.
+ * \param root DRI proc dir entry.
+ * \param dev_root resulting DRI device proc dir entry.
+ * \return root entry pointer on success, or NULL on failure.
+ * 
+ * Create the DRI proc root entry "/proc/dri", the device proc root entry
+ * "/proc/dri/%minor%/", and each entry in proc_list as
+ * "/proc/dri/%minor%/%name%".
+ */
 struct proc_dir_entry *DRM(proc_init)(drm_device_t *dev, int minor,
 				      struct proc_dir_entry *root,
 				      struct proc_dir_entry **dev_root)
@@ -84,7 +104,7 @@ struct proc_dir_entry *DRM(proc_init)(drm_device_t *dev, int minor,
 	sprintf(name, "%d", minor);
 	*dev_root = create_proc_entry(name, S_IFDIR, root);
 	if (!*dev_root) {
-		DRM_ERROR("Cannot create /proc/%s\n", name);
+		DRM_ERROR("Cannot create /proc/dri/%s\n", name);
 		return NULL;
 	}
 
@@ -109,6 +129,17 @@ struct proc_dir_entry *DRM(proc_init)(drm_device_t *dev, int minor,
 }
 
 
+/**
+ * Cleanup the proc filesystem resources.
+ *
+ * \param dev DRM device.
+ * \param minor device minor number.
+ * \param root DRI proc dir entry.
+ * \param dev_root DRI device proc dir entry.
+ * \return always zero.
+ *
+ * Remove all proc entries created by proc_init().
+ */
 int DRM(proc_cleanup)(int minor, struct proc_dir_entry *root,
 		      struct proc_dir_entry *dev_root)
 {
@@ -126,6 +157,19 @@ int DRM(proc_cleanup)(int minor, struct proc_dir_entry *root,
 	return 0;
 }
 
+/**
+ * Called when "/proc/dri/<dev>/name" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ * 
+ * Prints the device name together with the bus id if available.
+ */
 static int DRM(name_info)(char *buf, char **start, off_t offset, int request,
 			  int *eof, void *data)
 {
@@ -152,6 +196,19 @@ static int DRM(name_info)(char *buf, char **start, off_t offset, int request,
 	return len - offset;
 }
 
+/**
+ * Called when "/proc/dri/<dev>/vm" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ * 
+ * Prints information about all mappings in drm_device::maplist.
+ */
 static int DRM(_vm_info)(char *buf, char **start, off_t offset, int request,
 			 int *eof, void *data)
 {
@@ -205,6 +262,9 @@ static int DRM(_vm_info)(char *buf, char **start, off_t offset, int request,
 	return len - offset;
 }
 
+/**
+ * Simply calls _vm_info() while holding the drm_device::struct_sem lock.
+ */
 static int DRM(vm_info)(char *buf, char **start, off_t offset, int request,
 			int *eof, void *data)
 {
@@ -217,7 +277,17 @@ static int DRM(vm_info)(char *buf, char **start, off_t offset, int request,
 	return ret;
 }
 
-
+/**
+ * Called when "/proc/dri/<dev>/queues" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ */
 static int DRM(_queues_info)(char *buf, char **start, off_t offset,
 			     int request, int *eof, void *data)
 {
@@ -262,6 +332,9 @@ static int DRM(_queues_info)(char *buf, char **start, off_t offset,
 	return len - offset;
 }
 
+/**
+ * Simply calls _queues_info() while holding the drm_device::struct_sem lock.
+ */
 static int DRM(queues_info)(char *buf, char **start, off_t offset, int request,
 			    int *eof, void *data)
 {
@@ -274,9 +347,17 @@ static int DRM(queues_info)(char *buf, char **start, off_t offset, int request,
 	return ret;
 }
 
-/* drm_bufs_info is called whenever a process reads
-   /dev/dri/<dev>/bufs. */
-
+/**
+ * Called when "/proc/dri/<dev>/bufs" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ */
 static int DRM(_bufs_info)(char *buf, char **start, off_t offset, int request,
 			   int *eof, void *data)
 {
@@ -321,6 +402,9 @@ static int DRM(_bufs_info)(char *buf, char **start, off_t offset, int request,
 	return len - offset;
 }
 
+/**
+ * Simply calls _bufs_info() while holding the drm_device::struct_sem lock.
+ */
 static int DRM(bufs_info)(char *buf, char **start, off_t offset, int request,
 			  int *eof, void *data)
 {
@@ -333,7 +417,17 @@ static int DRM(bufs_info)(char *buf, char **start, off_t offset, int request,
 	return ret;
 }
 
-
+/**
+ * Called when "/proc/dri/<dev>/clients" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ */
 static int DRM(_clients_info)(char *buf, char **start, off_t offset,
 			      int request, int *eof, void *data)
 {
@@ -365,6 +459,9 @@ static int DRM(_clients_info)(char *buf, char **start, off_t offset,
 	return len - offset;
 }
 
+/**
+ * Simply calls _clients_info() while holding the drm_device::struct_sem lock.
+ */
 static int DRM(clients_info)(char *buf, char **start, off_t offset,
 			     int request, int *eof, void *data)
 {
diff --git a/linux-core/drm_scatter.c b/linux-core/drm_scatter.c
index 1aedb403..45a30fc3 100644
--- a/linux-core/drm_scatter.c
+++ b/linux-core/drm_scatter.c
@@ -1,4 +1,11 @@
-/* drm_scatter.h -- IOCTLs to manage scatter/gather memory -*- linux-c -*-
+/**
+ * \file drm_scatter.h 
+ * IOCTLs to manage scatter/gather memory
+ *
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Mon Dec 18 23:20:54 2000 by gareth@valinux.com
  *
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -22,9 +29,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:
- *   Gareth Hughes <gareth@valinux.com>
  */
 
 #define __NO_VERSION__
diff --git a/linux-core/drm_stub.c b/linux-core/drm_stub.c
index 3c9c69eb..c5fdf15a 100644
--- a/linux-core/drm_stub.c
+++ b/linux-core/drm_stub.c
@@ -1,4 +1,11 @@
-/* drm_stub.h -- -*- linux-c -*-
+/**
+ * \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.
@@ -22,10 +29,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>
- *
  */
 
 #define __NO_VERSION__
@@ -33,20 +36,31 @@
 
 #define DRM_STUB_MAXCARDS 16	/* Enough for one machine */
 
+/** Stub list. One for each minor. */
 static struct drm_stub_list {
 	const char             *name;
-	struct file_operations *fops;
-	struct proc_dir_entry  *dev_root;
+	struct file_operations *fops;	/**< file operations */
+	struct proc_dir_entry  *dev_root;	/**< proc directory entry */
 } *DRM(stub_list);
 
 static struct proc_dir_entry *DRM(stub_root);
 
+/** Stub information */
 static struct drm_stub_info {
 	int (*info_register)(const char *name, struct file_operations *fops,
 			     drm_device_t *dev);
 	int (*info_unregister)(int minor);
 } DRM(stub_info);
 
+/**
+ * File \c open operation.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ *
+ * Puts the drm_stub_list::fops corresponding to the device minor number into
+ * \p filp, call the \c open method, and restore the file operations.
+ */
 static int DRM(stub_open)(struct inode *inode, struct file *filp)
 {
 	int                    minor = minor(inode->i_rdev);
@@ -65,11 +79,24 @@ static int DRM(stub_open)(struct inode *inode, struct file *filp)
 	return err;
 }
 
+/** File operations structure */
 static struct file_operations DRM(stub_fops) = {
 	.owner = THIS_MODULE,
 	.open  = DRM(stub_open)
 };
 
+/**
+ * Get a device minor number.
+ *
+ * \param name driver name.
+ * \param fops file operations.
+ * \param dev DRM device.
+ * \return minor number on success, or a negative number on failure.
+ *
+ * Allocate and initialize ::stub_list if one doesn't exist already.  Search an
+ * empty entry and initialize it to the given parameters, and create the proc
+ * init entry via proc_init().
+ */
 static int DRM(stub_getminor)(const char *name, struct file_operations *fops,
 			      drm_device_t *dev)
 {
@@ -97,6 +124,16 @@ static int DRM(stub_getminor)(const char *name, struct file_operations *fops,
 	return -1;
 }
 
+/**
+ * Put a device minor number.
+ *
+ * \param minor minor number.
+ * \return always zero.
+ *
+ * Cleans up the proc resources. If a minor is zero then release the foreign
+ * "drm" data, otherwise unregisters the "drm" data, frees the stub list and
+ * unregisters the character device. 
+ */
 static int DRM(stub_putminor)(int minor)
 {
 	if (minor < 0 || minor >= DRM_STUB_MAXCARDS) return -1;
@@ -116,7 +153,20 @@ static int DRM(stub_putminor)(int minor)
 	return 0;
 }
 
-
+/**
+ * Register.
+ *
+ * \param name driver name.
+ * \param fops file operations
+ * \param dev DRM device.
+ * \return zero on success or a negative number on failure.
+ *
+ * Attempt to register the char device and get the foreign "drm" data. If
+ * successful then another module already registered so gets the stub info,
+ * otherwise use this module stub info and make it available for other modules.
+ *
+ * Finally calls stub_info::info_register.
+ */
 int DRM(stub_register)(const char *name, struct file_operations *fops,
 		       drm_device_t *dev)
 {
@@ -142,6 +192,13 @@ int DRM(stub_register)(const char *name, struct file_operations *fops,
 	return -1;
 }
 
+/**
+ * Unregister.
+ *
+ * \param minor
+ *
+ * Calls drm_stub_info::unregister.
+ */
 int DRM(stub_unregister)(int minor)
 {
 	DRM_DEBUG("%d\n", minor);
diff --git a/linux-core/drm_vm.c b/linux-core/drm_vm.c
index f9c1e356..c1dfb377 100644
--- a/linux-core/drm_vm.c
+++ b/linux-core/drm_vm.c
@@ -1,4 +1,12 @@
-/* drm_vm.h -- Memory mapping for DRM -*- linux-c -*-
+/**
+ * \file drm_vm.h
+ * Memory mapping for DRM
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Mon Jan  4 08:58:31 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,39 +31,50 @@
  * 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__
 #include "drmP.h"
 
+/** AGP virtual memory operations */
 struct vm_operations_struct   DRM(vm_ops) = {
 	.nopage = DRM(vm_nopage),
 	.open	= DRM(vm_open),
 	.close	= DRM(vm_close),
 };
 
+/** Shared virtual memory operations */
 struct vm_operations_struct   DRM(vm_shm_ops) = {
 	.nopage = DRM(vm_shm_nopage),
 	.open	= DRM(vm_open),
 	.close	= DRM(vm_shm_close),
 };
 
+/** DMA virtual memory operations */
 struct vm_operations_struct   DRM(vm_dma_ops) = {
 	.nopage = DRM(vm_dma_nopage),
 	.open	= DRM(vm_open),
 	.close	= DRM(vm_close),
 };
 
+/** Scatter-gather virtual memory operations */
 struct vm_operations_struct   DRM(vm_sg_ops) = {
 	.nopage = DRM(vm_sg_nopage),
 	.open   = DRM(vm_open),
 	.close  = DRM(vm_close),
 };
 
+/**
+ * \c nopage method for AGP virtual memory.
+ *
+ * \param vma virtual memory area.
+ * \param address access address.
+ * \param write_access sharing.
+ * \return pointer to the page structure.
+ * 
+ * Find the right map and if it's AGP memory find the real physical page to
+ * map, get the page, increment the use count and return it.
+ */
 struct page *DRM(vm_nopage)(struct vm_area_struct *vma,
 			    unsigned long address,
 			    int write_access)
@@ -123,6 +142,17 @@ vm_nopage_error:
 	return NOPAGE_SIGBUS;		/* Disallow mremap */
 }
 
+/**
+ * \c nopage method for shared virtual memory.
+ *
+ * \param vma virtual memory area.
+ * \param address access address.
+ * \param write_access sharing.
+ * \return pointer to the page structure.
+ * 
+ * Get the the mapping, find the real physical page to map, get the page, and
+ * return it.
+ */
 struct page *DRM(vm_shm_nopage)(struct vm_area_struct *vma,
 				unsigned long address,
 				int write_access)
@@ -146,10 +176,15 @@ struct page *DRM(vm_shm_nopage)(struct vm_area_struct *vma,
 	return page;
 }
 
-/* Special close routine which deletes map information if we are the last
+
+/**
+ * \c close method for shared virtual memory.
+ * 
+ * \param vma virtual memory area.
+ * 
+ * Deletes map information if we are the last
  * person to close a mapping and it's not in the global maplist.
  */
-
 void DRM(vm_shm_close)(struct vm_area_struct *vma)
 {
 	drm_file_t	*priv	= vma->vm_file->private_data;
@@ -222,6 +257,16 @@ void DRM(vm_shm_close)(struct vm_area_struct *vma)
 	up(&dev->struct_sem);
 }
 
+/**
+ * \c nopage method for DMA virtual memory.
+ *
+ * \param vma virtual memory area.
+ * \param address access address.
+ * \param write_access sharing.
+ * \return pointer to the page structure.
+ * 
+ * Determine the page number from the page offset and get it from drm_device_dma::pagelist.
+ */
 struct page *DRM(vm_dma_nopage)(struct vm_area_struct *vma,
 				unsigned long address,
 				int write_access)
@@ -248,6 +293,16 @@ struct page *DRM(vm_dma_nopage)(struct vm_area_struct *vma,
 	return page;
 }
 
+/**
+ * \c nopage method for scatter-gather virtual memory.
+ *
+ * \param vma virtual memory area.
+ * \param address access address.
+ * \param write_access sharing.
+ * \return pointer to the page structure.
+ * 
+ * Determine the map offset from the page offset and get it from drm_sg_mem::pagelist.
+ */
 struct page *DRM(vm_sg_nopage)(struct vm_area_struct *vma,
 			       unsigned long address,
 			       int write_access)
@@ -275,6 +330,14 @@ struct page *DRM(vm_sg_nopage)(struct vm_area_struct *vma,
 	return page;
 }
 
+/**
+ * \c open method for shared virtual memory.
+ * 
+ * \param vma virtual memory area.
+ * 
+ * Create a new drm_vma_entry structure as the \p vma private data entry and
+ * add it to drm_device::vmalist.
+ */
 void DRM(vm_open)(struct vm_area_struct *vma)
 {
 	drm_file_t	*priv	= vma->vm_file->private_data;
@@ -296,6 +359,14 @@ void DRM(vm_open)(struct vm_area_struct *vma)
 	}
 }
 
+/**
+ * \c close method for all virtual memory types.
+ * 
+ * \param vma virtual memory area.
+ * 
+ * Search the \p vma private data entry in drm_device::vmalist, unlink it, and
+ * free it.
+ */
 void DRM(vm_close)(struct vm_area_struct *vma)
 {
 	drm_file_t	*priv	= vma->vm_file->private_data;
@@ -321,6 +392,16 @@ void DRM(vm_close)(struct vm_area_struct *vma)
 	up(&dev->struct_sem);
 }
 
+/**
+ * mmap DMA memory.
+ *
+ * \param filp file pointer.
+ * \param vma virtual memory area.
+ * \return zero on success or a negative number on failure.
+ * 
+ * Sets the virtual memory area operations structure to vm_dma_ops, the file
+ * pointer, and calls vm_open().
+ */
 int DRM(mmap_dma)(struct file *filp, struct vm_area_struct *vma)
 {
 	drm_file_t	 *priv	 = filp->private_data;
@@ -367,6 +448,19 @@ int DRM(mmap_dma)(struct file *filp, struct vm_area_struct *vma)
 #endif
 #endif
 
+/**
+ * mmap DMA memory.
+ *
+ * \param filp file pointer.
+ * \param vma virtual memory area.
+ * \return zero on success or a negative number on failure.
+ * 
+ * If the virtual memory area has no offset associated with it then it's a DMA
+ * area, so calls mmap_dma(). Otherwise searches the map in drm_device::maplist,
+ * checks that the restricted flag is not set, sets the virtual memory operations
+ * according to the mapping type and remaps the pages. Finally sets the file
+ * pointer and calls vm_open().
+ */
 int DRM(mmap)(struct file *filp, struct vm_area_struct *vma)
 {
 	drm_file_t	*priv	= filp->private_data;
diff --git a/linux-core/radeon_drv.c b/linux-core/radeon_drv.c
index df859360..6152b8a5 100644
--- a/linux-core/radeon_drv.c
+++ b/linux-core/radeon_drv.c
@@ -1,6 +1,11 @@
-/* radeon_drv.c -- ATI Radeon driver -*- linux-c -*-
- * Created: Wed Feb 14 17:10:04 2001 by gareth@valinux.com
+/**
+ * \file radeon_drv.c
+ * ATI Radeon driver
  *
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
  *
@@ -22,11 +27,9 @@
  * 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>
  */
 
+
 #include <linux/config.h>
 #include "radeon.h"
 #include "drmP.h"
diff --git a/linux/ati_pcigart.h b/linux/ati_pcigart.h
index a259edb5..42233ff9 100644
--- a/linux/ati_pcigart.h
+++ b/linux/ati_pcigart.h
@@ -1,4 +1,11 @@
-/* ati_pcigart.h -- ATI PCI GART support -*- linux-c -*-
+/**
+ * \file ati_pcigart.h 
+ * ATI PCI GART support
+ *
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Wed Dec 13 21:52:19 2000 by gareth@valinux.com
  *
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -22,9 +29,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:
- *   Gareth Hughes <gareth@valinux.com>
  */
 
 #define __NO_VERSION__
@@ -46,8 +50,8 @@
 # error - PAGE_SIZE not 64K, 16K, 8K or 4K
 #endif
 
-# define ATI_MAX_PCIGART_PAGES		8192	/* 32 MB aperture, 4K pages */
-# define ATI_PCIGART_PAGE_SIZE		4096	/* PCI GART page size */
+# define ATI_MAX_PCIGART_PAGES		8192	/**< 32 MB aperture, 4K pages */
+# define ATI_PCIGART_PAGE_SIZE		4096	/**< PCI GART page size */
 
 static unsigned long DRM(ati_alloc_pcigart_table)( void )
 {
diff --git a/linux/drm.h b/linux/drm.h
index f987c422..008a300b 100644
--- a/linux/drm.h
+++ b/linux/drm.h
@@ -1,6 +1,14 @@
-/* drm.h -- Header for Direct Rendering Manager -*- linux-c -*-
- * Created: Mon Jan  4 10:05:05 1999 by faith@precisioninsight.com
+/**
+ * \file drm.h 
+ * Header for the Direct Rendering Manager
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
  *
+ * \par Acknowledgments:
+ * Dec 1999, Richard Henderson <rth@twiddle.net>, move to generic \c cmpxchg.
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All rights reserved.
@@ -23,15 +31,9 @@
  * 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>
- *
- * Acknowledgements:
- * Dec 1999, Richard Henderson <rth@twiddle.net>, move to generic cmpxchg.
- *
  */
 
+
 #ifndef _DRM_H_
 #define _DRM_H_
 
@@ -86,29 +88,33 @@
 #endif
 #define DRM_MAX_MINOR   15
 #endif
-#define DRM_NAME	"drm"	  /* Name in kernel, /dev, and /proc	    */
-#define DRM_MIN_ORDER	5	  /* At least 2^5 bytes = 32 bytes	    */
-#define DRM_MAX_ORDER	22	  /* Up to 2^22 bytes = 4MB		    */
-#define DRM_RAM_PERCENT 10	  /* How much system ram can we lock?	    */
+#define DRM_NAME	"drm"	  /**< Name in kernel, /dev, and /proc */
+#define DRM_MIN_ORDER	5	  /**< At least 2^5 bytes = 32 bytes */
+#define DRM_MAX_ORDER	22	  /**< Up to 2^22 bytes = 4MB */
+#define DRM_RAM_PERCENT 10	  /**< How much system ram can we lock? */
 
-#define _DRM_LOCK_HELD	0x80000000 /* Hardware lock is held		    */
-#define _DRM_LOCK_CONT	0x40000000 /* Hardware lock is contended	    */
+#define _DRM_LOCK_HELD	0x80000000 /**< Hardware lock is held */
+#define _DRM_LOCK_CONT	0x40000000 /**< Hardware lock is contended */
 #define _DRM_LOCK_IS_HELD(lock)	   ((lock) & _DRM_LOCK_HELD)
 #define _DRM_LOCK_IS_CONT(lock)	   ((lock) & _DRM_LOCK_CONT)
 #define _DRM_LOCKING_CONTEXT(lock) ((lock) & ~(_DRM_LOCK_HELD|_DRM_LOCK_CONT))
 
+
 typedef unsigned long drm_handle_t;
 typedef unsigned int  drm_context_t;
 typedef unsigned int  drm_drawable_t;
 typedef unsigned int  drm_magic_t;
 
-/* Warning: If you change this structure, make sure you change
- * XF86DRIClipRectRec in the server as well */
 
-/* KW: Actually it's illegal to change either for
+/**
+ * Cliprect.
+ * 
+ * \warning: If you change this structure, make sure you change
+ * XF86DRIClipRectRec in the server as well
+ *
+ * \note KW: Actually it's illegal to change either for
  * backwards-compatibility reasons.
  */
-
 typedef struct drm_clip_rect {
 	unsigned short	x1;
 	unsigned short	y1;
@@ -116,6 +122,10 @@ typedef struct drm_clip_rect {
 	unsigned short	y2;
 } drm_clip_rect_t;
 
+
+/**
+ * Texture region,
+ */
 typedef struct drm_tex_region {
 	unsigned char	next;
 	unsigned char	prev;
@@ -124,32 +134,52 @@ typedef struct drm_tex_region {
 	unsigned int	age;
 } drm_tex_region_t;
 
+
+/**
+ * DRM_IOCTL_VERSION ioctl argument type.
+ * 
+ * \sa drmGetVersion().
+ */
 typedef struct drm_version {
-	int    version_major;	  /* Major version			    */
-	int    version_minor;	  /* Minor version			    */
-	int    version_patchlevel;/* Patch level			    */
-	size_t name_len;	  /* Length of name buffer		    */
-	char   *name;		  /* Name of driver			    */
-	size_t date_len;	  /* Length of date buffer		    */
-	char   *date;		  /* User-space buffer to hold date	    */
-	size_t desc_len;	  /* Length of desc buffer		    */
-	char   *desc;		  /* User-space buffer to hold desc	    */
+	int    version_major;	  /**< Major version */
+	int    version_minor;	  /**< Minor version */
+	int    version_patchlevel;/**< Patch level */
+	size_t name_len;	  /**< Length of name buffer */
+	char   *name;		  /**< Name of driver */
+	size_t date_len;	  /**< Length of date buffer */
+	char   *date;		  /**< User-space buffer to hold date */
+	size_t desc_len;	  /**< Length of desc buffer */
+	char   *desc;		  /**< User-space buffer to hold desc */
 } drm_version_t;
 
+
+/**
+ * DRM_IOCTL_GET_UNIQUE ioctl argument type.
+ *
+ * \sa drmGetBusid() and drmSetBusId().
+ */
 typedef struct drm_unique {
-	size_t unique_len;	  /* Length of unique			    */
-	char   *unique;		  /* Unique name for driver instantiation   */
+	size_t unique_len;	  /**< Length of unique */
+	char   *unique;		  /**< Unique name for driver instantiation */
 } drm_unique_t;
 
+
 typedef struct drm_list {
-	int		 count;	  /* Length of user-space structures	    */
+	int		 count;	  /**< Length of user-space structures */
 	drm_version_t	 *version;
 } drm_list_t;
 
+
 typedef struct drm_block {
 	int		 unused;
 } drm_block_t;
 
+
+/**
+ * DRM_IOCTL_CONTROL ioctl argument type.
+ *
+ * \sa drmCtlInstHandler() and drmCtlUninstHandler().
+ */
 typedef struct drm_control {
 	enum {
 		DRM_ADD_COMMAND,
@@ -160,49 +190,70 @@ typedef struct drm_control {
 	int		 irq;
 } drm_control_t;
 
+
+/**
+ * Type of memory to map.
+ */
 typedef enum drm_map_type {
-	_DRM_FRAME_BUFFER   = 0,  /* WC (no caching), no core dump	    */
-	_DRM_REGISTERS	    = 1,  /* no caching, no core dump		    */
-	_DRM_SHM	    = 2,  /* shared, cached			    */
-	_DRM_AGP            = 3,  /* AGP/GART                               */
-	_DRM_SCATTER_GATHER = 4	  /* Scatter/gather memory for PCI DMA      */
+	_DRM_FRAME_BUFFER   = 0,  /**< WC (no caching), no core dump */
+	_DRM_REGISTERS	    = 1,  /**< no caching, no core dump */
+	_DRM_SHM	    = 2,  /**< shared, cached */
+	_DRM_AGP            = 3,  /**< AGP/GART */
+	_DRM_SCATTER_GATHER = 4	  /**< Scatter/gather memory for PCI DMA */
 } drm_map_type_t;
 
+
+/**
+ * Memory mapping flags.
+ */
 typedef enum drm_map_flags {
-	_DRM_RESTRICTED	     = 0x01, /* Cannot be mapped to user-virtual    */
+	_DRM_RESTRICTED	     = 0x01, /**< Cannot be mapped to user-virtual */
 	_DRM_READ_ONLY	     = 0x02,
-	_DRM_LOCKED	     = 0x04, /* shared, cached, locked		    */
-	_DRM_KERNEL	     = 0x08, /* kernel requires access		    */
-	_DRM_WRITE_COMBINING = 0x10, /* use write-combining if available    */
-	_DRM_CONTAINS_LOCK   = 0x20, /* SHM page that contains lock	    */
-	_DRM_REMOVABLE	     = 0x40  /* Removable mapping		    */
+	_DRM_LOCKED	     = 0x04, /**< shared, cached, locked */
+	_DRM_KERNEL	     = 0x08, /**< kernel requires access */
+	_DRM_WRITE_COMBINING = 0x10, /**< use write-combining if available */
+	_DRM_CONTAINS_LOCK   = 0x20, /**< SHM page that contains lock */
+	_DRM_REMOVABLE	     = 0x40  /**< Removable mapping */
 } drm_map_flags_t;
 
+
 typedef struct drm_ctx_priv_map {
-	unsigned int	ctx_id;  /* Context requesting private mapping */
-	void		*handle; /* Handle of map */
+	unsigned int	ctx_id;  /**< Context requesting private mapping */
+	void		*handle; /**< Handle of map */
 } drm_ctx_priv_map_t;
 
+
+/**
+ * DRM_IOCTL_GET_MAP, DRM_IOCTL_ADD_MAP and DRM_IOCTL_RM_MAP ioctls
+ * argument type.
+ *
+ * \sa drmAddMap().
+ */
 typedef struct drm_map {
-	unsigned long	offset;	 /* Requested physical address (0 for SAREA)*/
-	unsigned long	size;	 /* Requested physical size (bytes)	    */
-	drm_map_type_t	type;	 /* Type of memory to map		    */
-	drm_map_flags_t flags;	 /* Flags				    */
-	void		*handle; /* User-space: "Handle" to pass to mmap    */
-				 /* Kernel-space: kernel-virtual address    */
-	int		mtrr;	 /* MTRR slot used			    */
-				 /* Private data			    */
+	unsigned long	offset;	 /**< Requested physical address (0 for SAREA)*/
+	unsigned long	size;	 /**< Requested physical size (bytes) */
+	drm_map_type_t	type;	 /**< Type of memory to map */
+	drm_map_flags_t flags;	 /**< Flags */
+	void		*handle; /**< User-space: "Handle" to pass to mmap() */
+				 /**< Kernel-space: kernel-virtual address */
+	int		mtrr;	 /**< MTRR slot used */
+				 /*   Private data */
 } drm_map_t;
 
+
+/**
+ * DRM_IOCTL_GET_CLIENT ioctl argument type.
+ */
 typedef struct drm_client {
-	int		idx;	/* Which client desired?                    */
-	int		auth;	/* Is client authenticated?                 */
-	unsigned long	pid;	/* Process id                               */
-	unsigned long	uid;	/* User id                                  */
-	unsigned long	magic;	/* Magic                                    */
-	unsigned long	iocs;	/* Ioctl count                              */
+	int		idx;	/**< Which client desired? */
+	int		auth;	/**< Is client authenticated? */
+	unsigned long	pid;	/**< Process ID */
+	unsigned long	uid;	/**< User ID */
+	unsigned long	magic;	/**< Magic */
+	unsigned long	iocs;	/**< Ioctl count */
 } drm_client_t;
 
+
 typedef enum {
 	_DRM_STAT_LOCK,
 	_DRM_STAT_OPENS,
@@ -210,20 +261,24 @@ typedef enum {
 	_DRM_STAT_IOCTLS,
 	_DRM_STAT_LOCKS,
 	_DRM_STAT_UNLOCKS,
-	_DRM_STAT_VALUE,	/* Generic value                      */
-	_DRM_STAT_BYTE,		/* Generic byte counter (1024bytes/K) */
-	_DRM_STAT_COUNT,	/* Generic non-byte counter (1000/k)  */
+	_DRM_STAT_VALUE,	/**< Generic value */
+	_DRM_STAT_BYTE,		/**< Generic byte counter (1024bytes/K) */
+	_DRM_STAT_COUNT,	/**< Generic non-byte counter (1000/k) */
 
-	_DRM_STAT_IRQ,		/* IRQ */
-	_DRM_STAT_PRIMARY,	/* Primary DMA bytes */
-	_DRM_STAT_SECONDARY,	/* Secondary DMA bytes */
-	_DRM_STAT_DMA,		/* DMA */
-	_DRM_STAT_SPECIAL,	/* Special DMA (e.g., priority or polled) */
-	_DRM_STAT_MISSED	/* Missed DMA opportunity */
+	_DRM_STAT_IRQ,		/**< IRQ */
+	_DRM_STAT_PRIMARY,	/**< Primary DMA bytes */
+	_DRM_STAT_SECONDARY,	/**< Secondary DMA bytes */
+	_DRM_STAT_DMA,		/**< DMA */
+	_DRM_STAT_SPECIAL,	/**< Special DMA (e.g., priority or polled) */
+	_DRM_STAT_MISSED	/**< Missed DMA opportunity */
 
 				/* Add to the *END* of the list */
 } drm_stat_type_t;
 
+
+/**
+ * DRM_IOCTL_GET_STATS ioctl argument type.
+ */
 typedef struct drm_stats {
 	unsigned long count;
 	struct {
@@ -232,137 +287,220 @@ typedef struct drm_stats {
 	} data[15];
 } drm_stats_t;
 
+
+/**
+ * Hardware locking flags.
+ */
 typedef enum drm_lock_flags {
-	_DRM_LOCK_READY	     = 0x01, /* Wait until hardware is ready for DMA */
-	_DRM_LOCK_QUIESCENT  = 0x02, /* Wait until hardware quiescent	     */
-	_DRM_LOCK_FLUSH	     = 0x04, /* Flush this context's DMA queue first */
-	_DRM_LOCK_FLUSH_ALL  = 0x08, /* Flush all DMA queues first	     */
+	_DRM_LOCK_READY	     = 0x01, /**< Wait until hardware is ready for DMA */
+	_DRM_LOCK_QUIESCENT  = 0x02, /**< Wait until hardware quiescent */
+	_DRM_LOCK_FLUSH	     = 0x04, /**< Flush this context's DMA queue first */
+	_DRM_LOCK_FLUSH_ALL  = 0x08, /**< Flush all DMA queues first */
 				/* These *HALT* flags aren't supported yet
 				   -- they will be used to support the
 				   full-screen DGA-like mode. */
-	_DRM_HALT_ALL_QUEUES = 0x10, /* Halt all current and future queues   */
-	_DRM_HALT_CUR_QUEUES = 0x20  /* Halt all current queues		     */
+	_DRM_HALT_ALL_QUEUES = 0x10, /**< Halt all current and future queues */
+	_DRM_HALT_CUR_QUEUES = 0x20  /**< Halt all current queues */
 } drm_lock_flags_t;
 
+
+/**
+ * DRM_IOCTL_LOCK, DRM_IOCTL_UNLOCK and DRM_IOCTL_FINISH ioctl argument type.
+ * 
+ * \sa drmGetLock() and drmUnlock().
+ */
 typedef struct drm_lock {
 	int		 context;
 	drm_lock_flags_t flags;
 } drm_lock_t;
 
-typedef enum drm_dma_flags {	      /* These values *MUST* match xf86drm.h */
-				      /* Flags for DMA buffer dispatch	     */
-	_DRM_DMA_BLOCK	      = 0x01, /* Block until buffer dispatched.
-					 Note, the buffer may not yet have
-					 been processed by the hardware --
-					 getting a hardware lock with the
-					 hardware quiescent will ensure
-					 that the buffer has been
-					 processed.			     */
-	_DRM_DMA_WHILE_LOCKED = 0x02, /* Dispatch while lock held	     */
-	_DRM_DMA_PRIORITY     = 0x04, /* High priority dispatch		     */
-
-				      /* Flags for DMA buffer request	     */
-	_DRM_DMA_WAIT	      = 0x10, /* Wait for free buffers		     */
-	_DRM_DMA_SMALLER_OK   = 0x20, /* Smaller-than-requested buffers ok   */
-	_DRM_DMA_LARGER_OK    = 0x40  /* Larger-than-requested buffers ok    */
+
+/**
+ * DMA flags
+ *
+ * \warning 
+ * These values \e must match xf86drm.h.
+ *
+ * \sa drm_dma.
+ */
+typedef enum drm_dma_flags {	      
+				      /* Flags for DMA buffer dispatch */
+	_DRM_DMA_BLOCK	      = 0x01, /**<
+				       * Block until buffer dispatched.
+				       * 
+				       * \note The buffer may not yet have
+				       * been processed by the hardware --
+				       * getting a hardware lock with the
+				       * hardware quiescent will ensure
+				       * that the buffer has been
+				       * processed.
+				       */
+	_DRM_DMA_WHILE_LOCKED = 0x02, /**< Dispatch while lock held */
+	_DRM_DMA_PRIORITY     = 0x04, /**< High priority dispatch */
+
+				      /* Flags for DMA buffer request */
+	_DRM_DMA_WAIT	      = 0x10, /**< Wait for free buffers */
+	_DRM_DMA_SMALLER_OK   = 0x20, /**< Smaller-than-requested buffers OK */
+	_DRM_DMA_LARGER_OK    = 0x40  /**< Larger-than-requested buffers OK */
 } drm_dma_flags_t;
 
+
+/**
+ * DRM_IOCTL_ADD_BUFS and DRM_IOCTL_MARK_BUFS ioctl argument type.
+ *
+ * \sa drmAddBufs().
+ */
 typedef struct drm_buf_desc {
-	int	      count;	 /* Number of buffers of this size	     */
-	int	      size;	 /* Size in bytes			     */
-	int	      low_mark;	 /* Low water mark			     */
-	int	      high_mark; /* High water mark			     */
+	int	      count;	 /**< Number of buffers of this size */
+	int	      size;	 /**< Size in bytes */
+	int	      low_mark;	 /**< Low water mark */
+	int	      high_mark; /**< High water mark */
 	enum {
-		_DRM_PAGE_ALIGN = 0x01, /* Align on page boundaries for DMA  */
-		_DRM_AGP_BUFFER = 0x02, /* Buffer is in agp space            */
-		_DRM_SG_BUFFER  = 0x04  /* Scatter/gather memory buffer      */
+		_DRM_PAGE_ALIGN = 0x01, /**< Align on page boundaries for DMA */
+		_DRM_AGP_BUFFER = 0x02, /**< Buffer is in AGP space */
+		_DRM_SG_BUFFER  = 0x04  /**< Scatter/gather memory buffer */
 	}	      flags;
-	unsigned long agp_start; /* Start address of where the agp buffers
-				  * are in the agp aperture */
+	unsigned long agp_start; /**< 
+				  * Start address of where the AGP buffers are
+				  * in the AGP aperture
+				  */
 } drm_buf_desc_t;
 
+
+/**
+ * DRM_IOCTL_INFO_BUFS ioctl argument type.
+ */
 typedef struct drm_buf_info {
-	int	       count;	/* Entries in list			     */
+	int	       count;	/**< Entries in list */
 	drm_buf_desc_t *list;
 } drm_buf_info_t;
 
+
+/**
+ * DRM_IOCTL_FREE_BUFS ioctl argument type.
+ */
 typedef struct drm_buf_free {
 	int	       count;
 	int	       *list;
 } drm_buf_free_t;
 
+
+/**
+ * Buffer information
+ *
+ * \sa drm_buf_map.
+ */
 typedef struct drm_buf_pub {
-	int		  idx;	       /* Index into master buflist	     */
-	int		  total;       /* Buffer size			     */
-	int		  used;	       /* Amount of buffer in use (for DMA)  */
-	void		  *address;    /* Address of buffer		     */
+	int		  idx;	       /**< Index into the master buffer list */
+	int		  total;       /**< Buffer size */
+	int		  used;	       /**< Amount of buffer in use (for DMA) */
+	void		  *address;    /**< Address of buffer */
 } drm_buf_pub_t;
 
+
+/**
+ * DRM_IOCTL_MAP_BUFS ioctl argument type.
+ */
 typedef struct drm_buf_map {
-	int	      count;	/* Length of buflist			    */
-	void	      *virtual;	/* Mmaped area in user-virtual		    */
-	drm_buf_pub_t *list;	/* Buffer information			    */
+	int	      count;	/**< Length of the buffer list */
+	void	      *virtual;	/**< Mmap'd area in user-virtual */
+	drm_buf_pub_t *list;	/**< Buffer information */
 } drm_buf_map_t;
 
+
+/**
+ * DRM_IOCTL_DMA ioctl argument type.
+ *
+ * Indices here refer to the offset into the buffer list in drm_buf_get.
+ *
+ * \sa drmDMA().
+ */
 typedef struct drm_dma {
-				/* Indices here refer to the offset into
-				   buflist in drm_buf_get_t.  */
-	int		context;	  /* Context handle		    */
-	int		send_count;	  /* Number of buffers to send	    */
-	int		*send_indices;	  /* List of handles to buffers	    */
-	int		*send_sizes;	  /* Lengths of data to send	    */
-	drm_dma_flags_t flags;		  /* Flags			    */
-	int		request_count;	  /* Number of buffers requested    */
-	int		request_size;	  /* Desired size for buffers	    */
-	int		*request_indices; /* Buffer information		    */
+	int		context;	  /**< Context handle */
+	int		send_count;	  /**< Number of buffers to send */
+	int		*send_indices;	  /**< List of handles to buffers */
+	int		*send_sizes;	  /**< Lengths of data to send */
+	drm_dma_flags_t flags;		  /**< Flags */
+	int		request_count;	  /**< Number of buffers requested */
+	int		request_size;	  /**< Desired size for buffers */
+	int		*request_indices; /**< Buffer information */
 	int		*request_sizes;
-	int		granted_count;	  /* Number of buffers granted	    */
+	int		granted_count;	  /**< Number of buffers granted */
 } drm_dma_t;
 
+
 typedef enum {
 	_DRM_CONTEXT_PRESERVED = 0x01,
 	_DRM_CONTEXT_2DONLY    = 0x02
 } drm_ctx_flags_t;
 
+
+/**
+ * DRM_IOCTL_ADD_CTX ioctl argument type.
+ *
+ * \sa drmCreateContext() and drmDestroyContext().
+ */
 typedef struct drm_ctx {
 	drm_context_t	handle;
 	drm_ctx_flags_t flags;
 } drm_ctx_t;
 
+
+/**
+ * DRM_IOCTL_RES_CTX ioctl argument type.
+ */
 typedef struct drm_ctx_res {
 	int		count;
 	drm_ctx_t	*contexts;
 } drm_ctx_res_t;
 
+
+/**
+ * DRM_IOCTL_ADD_DRAW and DRM_IOCTL_RM_DRAW ioctl argument type.
+ */
 typedef struct drm_draw {
 	drm_drawable_t	handle;
 } drm_draw_t;
 
+
+/**
+ * DRM_IOCTL_GET_MAGIC and DRM_IOCTL_AUTH_MAGIC ioctl argument type.
+ */
 typedef struct drm_auth {
 	drm_magic_t	magic;
 } drm_auth_t;
 
+
+/**
+ * DRM_IOCTL_IRQ_BUSID ioctl argument type.
+ *
+ * \sa drmGetInterruptFromBusID().
+ */
 typedef struct drm_irq_busid {
-	int irq;
-	int busnum;
-	int devnum;
-	int funcnum;
+	int irq;	/**< IRQ number */
+	int busnum;	/**< bus number */
+	int devnum;	/**< device number */
+	int funcnum;	/**< function number */
 } drm_irq_busid_t;
 
+
 typedef enum {
-    _DRM_VBLANK_ABSOLUTE = 0x0,		/* Wait for specific vblank sequence number */
-    _DRM_VBLANK_RELATIVE = 0x1,		/* Wait for given number of vblanks */
-    _DRM_VBLANK_SIGNAL   = 0x40000000	/* Send signal instead of blocking */
+    _DRM_VBLANK_ABSOLUTE = 0x0,		/**< Wait for specific vblank sequence number */
+    _DRM_VBLANK_RELATIVE = 0x1,		/**< Wait for given number of vblanks */
+    _DRM_VBLANK_SIGNAL   = 0x80000000	/**< Send signal instead of blocking */
 } drm_vblank_seq_type_t;
 
+
 #define _DRM_VBLANK_FLAGS_MASK _DRM_VBLANK_SIGNAL
 
+
 struct drm_wait_vblank_request {
 	drm_vblank_seq_type_t type;
 	unsigned int sequence;
 	unsigned long signal;
 };
 
+
 struct drm_wait_vblank_reply {
 	drm_vblank_seq_type_t type;
 	unsigned int sequence;
@@ -370,29 +508,59 @@ struct drm_wait_vblank_reply {
 	long tval_usec;
 };
 
+
+/**
+ * DRM_IOCTL_WAIT_VBLANK ioctl argument type.
+ *
+ * \sa drmWaitVBlank().
+ */
 typedef union drm_wait_vblank {
 	struct drm_wait_vblank_request request;
 	struct drm_wait_vblank_reply reply;
 } drm_wait_vblank_t;
 
+
+/**
+ * DRM_IOCTL_AGP_ENABLE ioctl argument type.
+ *
+ * \sa drmAgpEnable().
+ */
 typedef struct drm_agp_mode {
-	unsigned long mode;
+	unsigned long mode;	/**< AGP mode */
 } drm_agp_mode_t;
 
-				/* For drm_agp_alloc -- allocated a buffer */
+
+/**
+ * DRM_IOCTL_AGP_ALLOC and DRM_IOCTL_AGP_FREE ioctls argument type.
+ *
+ * \sa drmAgpAlloc() and drmAgpFree().
+ */
 typedef struct drm_agp_buffer {
-	unsigned long size;	/* In bytes -- will round to page boundary */
-	unsigned long handle;	/* Used for BIND/UNBIND ioctls */
-	unsigned long type;     /* Type of memory to allocate  */
-        unsigned long physical; /* Physical used by i810       */
+	unsigned long size;	/**< In bytes -- will round to page boundary */
+	unsigned long handle;	/**< Used for binding / unbinding */
+	unsigned long type;     /**< Type of memory to allocate */
+        unsigned long physical; /**< Physical used by i810 */
 } drm_agp_buffer_t;
 
-				/* For drm_agp_bind */
+
+/**
+ * DRM_IOCTL_AGP_BIND and DRM_IOCTL_AGP_UNBIND ioctls argument type.
+ *
+ * \sa drmAgpBind() and drmAgpUnbind().
+ */
 typedef struct drm_agp_binding {
-	unsigned long handle;   /* From drm_agp_buffer */
-	unsigned long offset;	/* In bytes -- will round to page boundary */
+	unsigned long handle;   /**< From drm_agp_buffer */
+	unsigned long offset;	/**< In bytes -- will round to page boundary */
 } drm_agp_binding_t;
 
+
+/**
+ * DRM_IOCTL_AGP_INFO ioctl argument type.
+ *
+ * \sa drmAgpVersionMajor(), drmAgpVersionMinor(), drmAgpGetMode(),
+ * drmAgpBase(), drmAgpSize(), drmAgpMemoryUsed(), drmAgpMemoryAvail(),
+ * drmAgpVendorId() and drmAgpDeviceId().
+ */
 typedef struct drm_agp_info {
 	int            agp_version_major;
 	int            agp_version_minor;
@@ -407,11 +575,16 @@ typedef struct drm_agp_info {
 	unsigned short id_device;
 } drm_agp_info_t;
 
+
+/**
+ * DRM_IOCTL_SG_ALLOC ioctl argument type.
+ */
 typedef struct drm_scatter_gather {
-	unsigned long size;	/* In bytes -- will round to page boundary */
-	unsigned long handle;	/* Used for mapping / unmapping */
+	unsigned long size;	/**< In bytes -- will round to page boundary */
+	unsigned long handle;	/**< Used for mapping / unmapping */
 } drm_scatter_gather_t;
 
+
 #define DRM_IOCTL_BASE			'd'
 #define DRM_IO(nr)			_IO(DRM_IOCTL_BASE,nr)
 #define DRM_IOR(nr,type)		_IOR(DRM_IOCTL_BASE,nr,type)
@@ -471,8 +644,13 @@ typedef struct drm_scatter_gather {
 
 #define DRM_IOCTL_WAIT_VBLANK		DRM_IOWR(0x3a, drm_wait_vblank_t)
 
-/* Device specfic ioctls should only be in their respective headers
- * The device specific ioctl range is 0x40 to 0x79.                  */
+/**
+ * Device specific ioctls should only be in their respective headers
+ * The device specific ioctl range is from 0x40 to 0x79.
+ *
+ * \sa drmCommandNone(), drmCommandRead(), drmCommandWrite(), and
+ * drmCommandReadWrite().
+ */
 #define DRM_COMMAND_BASE                0x40
 
 #endif
diff --git a/linux/drmP.h b/linux/drmP.h
index 1f0ef128..5626e4ff 100644
--- a/linux/drmP.h
+++ b/linux/drmP.h
@@ -1,6 +1,12 @@
-/* drmP.h -- Private header for Direct Rendering Manager -*- linux-c -*-
- * Created: Mon Jan  4 10:05:05 1999 by faith@precisioninsight.com
- *
+/**
+ * \file drmP.h 
+ * Private header for Direct Rendering Manager
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All rights reserved.
@@ -23,15 +29,12 @@
  * 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>
  */
 
 #ifndef _DRM_P_H_
 #define _DRM_P_H_
 
+
 #ifdef __KERNEL__
 #ifdef __alpha__
 /* add include of current.h so that "current" is defined
@@ -83,8 +86,11 @@
 
 #include "drm_os_linux.h"
 
-/* DRM template customization defaults
- */
+
+/***********************************************************************/
+/** \name DRM template customization defaults */
+/*@{*/
+
 #ifndef __HAVE_AGP
 #define __HAVE_AGP		0
 #endif
@@ -112,19 +118,23 @@
 #define __REALLY_HAVE_MTRR	(__HAVE_MTRR && defined(CONFIG_MTRR))
 #define __REALLY_HAVE_SG	(__HAVE_SG)
 
-/* Begin the DRM...
- */
+/*@}*/
+
 
-#define DRM_DEBUG_CODE 2	  /* Include debugging code (if > 1, then
+/***********************************************************************/
+/** \name Begin the DRM... */
+/*@{*/
+
+#define DRM_DEBUG_CODE 2	  /**< Include debugging code if > 1, then
 				     also include looping detection. */
 
-#define DRM_HASH_SIZE	      16 /* Size of key hash table		  */
-#define DRM_KERNEL_CONTEXT    0	 /* Change drm_resctx if changed	  */
-#define DRM_RESERVED_CONTEXTS 1	 /* Change drm_resctx if changed	  */
+#define DRM_HASH_SIZE	      16 /**< Size of key hash table. Must be power of 2. */
+#define DRM_KERNEL_CONTEXT    0	 /**< Change drm_resctx if changed */
+#define DRM_RESERVED_CONTEXTS 1	 /**< Change drm_resctx if changed */
 #define DRM_LOOPING_LIMIT     5000000
-#define DRM_BSZ		      1024 /* Buffer size for /dev/drm? output	  */
-#define DRM_TIME_SLICE	      (HZ/20)  /* Time slice for GLXContexts	  */
-#define DRM_LOCK_SLICE	      1	/* Time slice for lock, in jiffies	  */
+#define DRM_BSZ		      1024 /**< Buffer size for /dev/drm? output */
+#define DRM_TIME_SLICE	      (HZ/20)  /**< Time slice for GLXContexts */
+#define DRM_LOCK_SLICE	      1	/**< Time slice for lock, in jiffies */
 
 #define DRM_FLAG_DEBUG	  0x01
 
@@ -151,8 +161,14 @@
 #define DRM_MEM_SGLISTS   20
 
 #define DRM_MAX_CTXBITMAP (PAGE_SIZE * 8)
+	
+/*@}*/
+
+
+/***********************************************************************/
+/** \name Backward compatibility section */
+/*@{*/
 
-				/* Backward compatibility section */
 #ifndef minor
 #define minor(x) MINOR((x))
 #endif
@@ -217,17 +233,42 @@ static inline struct page * vmalloc_to_page(void * vmalloc_addr)
 #define DRM_RPR_ARG(vma) vma,
 #endif
 
-
 #define VM_OFFSET(vma) ((vma)->vm_pgoff << PAGE_SHIFT)
 
-				/* Macros to make printk easier */
+/*@}*/
+
+
+/***********************************************************************/
+/** \name Macros to make printk easier */
+/*@{*/
+
+/**
+ * Error output.
+ *
+ * \param fmt printf() like format string.
+ * \param arg arguments
+ */
 #define DRM_ERROR(fmt, arg...) \
 	printk(KERN_ERR "[" DRM_NAME ":%s] *ERROR* " fmt , __FUNCTION__ , ##arg)
+
+/**
+ * Memory error output.
+ *
+ * \param area memory area where the error occurred.
+ * \param fmt printf() like format string.
+ * \param arg arguments
+ */
 #define DRM_MEM_ERROR(area, fmt, arg...) \
 	printk(KERN_ERR "[" DRM_NAME ":%s:%s] *ERROR* " fmt , __FUNCTION__, \
 	       DRM(mem_stats)[area].name , ##arg)
 #define DRM_INFO(fmt, arg...)  printk(KERN_INFO "[" DRM_NAME "] " fmt , ##arg)
 
+/**
+ * Debug output.
+ * 
+ * \param fmt printf() like format string.
+ * \param arg arguments
+ */
 #if DRM_DEBUG_CODE
 #define DRM_DEBUG(fmt, arg...)						\
 	do {								\
@@ -250,7 +291,13 @@ static inline struct page * vmalloc_to_page(void * vmalloc_addr)
    len += sprintf(&buf[len], fmt , ##arg);				\
    if (len > DRM_PROC_LIMIT) { ret; *eof = 1; return len - offset; }
 
-				/* Mapping helper macros */
+/*@}*/
+
+
+/***********************************************************************/
+/** \name Mapping helper macros */
+/*@{*/
+
 #define DRM_IOREMAP(map, dev)							\
 	(map)->handle = DRM(ioremap)( (map)->offset, (map)->size, (dev) )
 
@@ -263,6 +310,15 @@ static inline struct page * vmalloc_to_page(void * vmalloc_addr)
 			DRM(ioremapfree)( (map)->handle, (map)->size, (dev) );	\
 	} while (0)
 
+/**
+ * Find mapping.
+ *
+ * \param _map matching mapping if found, untouched otherwise.
+ * \param _o offset.
+ *
+ * Expects the existence of a local variable named \p dev pointing to the
+ * drm_device structure.
+ */
 #define DRM_FIND_MAP(_map, _o)								\
 do {											\
 	struct list_head *_list;							\
@@ -275,9 +331,21 @@ do {											\
  		}									\
 	}										\
 } while(0)
+
+/**
+ * Drop mapping.
+ *
+ * \sa #DRM_FIND_MAP.
+ */
 #define DRM_DROP_MAP(_map)
 
-				/* Internal types and structures */
+/*@}*/
+
+
+/***********************************************************************/
+/** \name Internal types and structures */
+/*@{*/
+
 #define DRM_ARRAY_SIZE(x) (sizeof(x)/sizeof(x[0]))
 #define DRM_MIN(a,b) ((a)<(b)?(a):(b))
 #define DRM_MAX(a,b) ((a)>(b)?(a):(b))
@@ -286,10 +354,23 @@ do {											\
 #define DRM_BUFCOUNT(x) ((x)->count - DRM_LEFTCOUNT(x))
 #define DRM_WAITCOUNT(dev,idx) DRM_BUFCOUNT(&dev->queuelist[idx]->waitlist)
 
+/**
+ * Get the private SAREA mapping.
+ *
+ * \param _dev DRM device.
+ * \param _ctx context number.
+ * \param _map output mapping.
+ */
 #define DRM_GET_PRIV_SAREA(_dev, _ctx, _map) do {	\
 	(_map) = (_dev)->context_sareas[_ctx];		\
 } while(0)
 
+/**
+ * Test that the hardware lock is held by the caller, returning otherwise.
+ *
+ * \param dev DRM device.
+ * \param filp file pointer of the caller.
+ */
 #define LOCK_TEST_WITH_RETURN( dev, filp )				\
 do {									\
 	if ( !_DRM_LOCK_IS_HELD( dev->lock.hw_lock->lock ) ||		\
@@ -300,7 +381,14 @@ do {									\
 	}								\
 } while (0)
 
-
+/**
+ * Ioctl function type.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg argument.
+ */
 typedef int drm_ioctl_t( struct inode *inode, struct file *filp,
 			 unsigned int cmd, unsigned long arg );
 
@@ -316,8 +404,7 @@ typedef struct drm_ioctl_desc {
 } drm_ioctl_desc_t;
 
 typedef struct drm_devstate {
-	pid_t		  owner;	/* X server pid holding x_lock */
-
+	pid_t		  owner;	/**< X server pid holding x_lock */
 } drm_devstate_t;
 
 typedef struct drm_magic_entry {
@@ -337,21 +424,24 @@ typedef struct drm_vma_entry {
 	pid_t		      pid;
 } drm_vma_entry_t;
 
+/**
+ * DMA buffer.
+ */
 typedef struct drm_buf {
-	int		  idx;	       /* Index into master buflist	     */
-	int		  total;       /* Buffer size			     */
-	int		  order;       /* log-base-2(total)		     */
-	int		  used;	       /* Amount of buffer in use (for DMA)  */
-	unsigned long	  offset;      /* Byte offset (used internally)	     */
-	void		  *address;    /* Address of buffer		     */
-	unsigned long	  bus_address; /* Bus address of buffer		     */
-	struct drm_buf	  *next;       /* Kernel-only: used for free list    */
-	__volatile__ int  waiting;     /* On kernel DMA queue		     */
-	__volatile__ int  pending;     /* On hardware DMA queue		     */
-	wait_queue_head_t dma_wait;    /* Processes waiting		     */
-	struct file       *filp;       /* Pointer to holding file descr	     */
-	int		  context;     /* Kernel queue for this buffer	     */
-	int		  while_locked;/* Dispatch this buffer while locked  */
+	int		  idx;	       /**< Index into master buflist */
+	int		  total;       /**< Buffer size */
+	int		  order;       /**< log-base-2(total) */
+	int		  used;	       /**< Amount of buffer in use (for DMA) */
+	unsigned long	  offset;      /**< Byte offset (used internally) */
+	void		  *address;    /**< Address of buffer */
+	unsigned long	  bus_address; /**< Bus address of buffer */
+	struct drm_buf	  *next;       /**< Kernel-only: used for free list */
+	__volatile__ int  waiting;     /**< On kernel DMA queue */
+	__volatile__ int  pending;     /**< On hardware DMA queue */
+	wait_queue_head_t dma_wait;    /**< Processes waiting */
+	struct file       *filp;       /**< Pointer to holding file descr */
+	int		  context;     /**< Kernel queue for this buffer */
+	int		  while_locked;/**< Dispatch this buffer while locked */
 	enum {
 		DRM_LIST_NONE	 = 0,
 		DRM_LIST_FREE	 = 1,
@@ -359,41 +449,43 @@ typedef struct drm_buf {
 		DRM_LIST_PEND	 = 3,
 		DRM_LIST_PRIO	 = 4,
 		DRM_LIST_RECLAIM = 5
-	}		  list;	       /* Which list we're on		     */
-
+	}		  list;	       /**< Which list we're on */
 
-	int		  dev_priv_size; /* Size of buffer private stoarge   */
-	void		  *dev_private;  /* Per-buffer private storage       */
+	int		  dev_priv_size; /**< Size of buffer private storage */
+	void		  *dev_private;  /**< Per-buffer private storage */
 } drm_buf_t;
 
 
-				/* bufs is one longer than it has to be */
+/** bufs is one longer than it has to be */
 typedef struct drm_waitlist {
-	int		  count;	/* Number of possible buffers	   */
-	drm_buf_t	  **bufs;	/* List of pointers to buffers	   */
-	drm_buf_t	  **rp;		/* Read pointer			   */
-	drm_buf_t	  **wp;		/* Write pointer		   */
-	drm_buf_t	  **end;	/* End pointer			   */
+	int		  count;	/**< Number of possible buffers */
+	drm_buf_t	  **bufs;	/**< List of pointers to buffers */
+	drm_buf_t	  **rp;		/**< Read pointer */
+	drm_buf_t	  **wp;		/**< Write pointer */
+	drm_buf_t	  **end;	/**< End pointer */
 	spinlock_t	  read_lock;
 	spinlock_t	  write_lock;
 } drm_waitlist_t;
 
 typedef struct drm_freelist {
-	int		  initialized; /* Freelist in use		   */
-	atomic_t	  count;       /* Number of free buffers	   */
-	drm_buf_t	  *next;       /* End pointer			   */
-
-	wait_queue_head_t waiting;     /* Processes waiting on free bufs   */
-	int		  low_mark;    /* Low water mark		   */
-	int		  high_mark;   /* High water mark		   */
-	atomic_t	  wfh;	       /* If waiting for high mark	   */
+	int		  initialized; /**< Freelist in use */
+	atomic_t	  count;       /**< Number of free buffers */
+	drm_buf_t	  *next;       /**< End pointer */
+
+	wait_queue_head_t waiting;     /**< Processes waiting on free bufs */
+	int		  low_mark;    /**< Low water mark */
+	int		  high_mark;   /**< High water mark */
+	atomic_t	  wfh;	       /**< If waiting for high mark */
 	spinlock_t        lock;
 } drm_freelist_t;
 
+/**
+ * Buffer entry.  There is one of this for each buffer size order.
+ */
 typedef struct drm_buf_entry {
-	int		  buf_size;
-	int		  buf_count;
-	drm_buf_t	  *buflist;
+	int		  buf_size;	/**< size */
+	int		  buf_count;	/**< number of buffers */
+	drm_buf_t	  *buflist;	/**< buffer list */
 	int		  seg_count;
 	int		  page_order;
 	unsigned long	  *seglist;
@@ -401,11 +493,19 @@ typedef struct drm_buf_entry {
 	drm_freelist_t	  freelist;
 } drm_buf_entry_t;
 
+/**
+ * Hardware lock.
+ *
+ * The lock structure is a simple cache-line aligned integer.  To avoid
+ * processor bus contention on a multiprocessor system, there should not be any
+ * other data stored in the same cache line.
+ */
 typedef struct drm_hw_lock {
-	__volatile__ unsigned int lock;
-	char			  padding[60]; /* Pad to cache line */
+	__volatile__ unsigned int lock;		/**< lock variable */
+	char			  padding[60];	/**< Pad to cache line */
 } drm_hw_lock_t;
 
+/** File private data */
 typedef struct drm_file {
 	int		  authenticated;
 	int		  minor;
@@ -420,69 +520,85 @@ typedef struct drm_file {
 	unsigned long     lock_count;
 } drm_file_t;
 
-
+/** Wait queue */
 typedef struct drm_queue {
-	atomic_t	  use_count;	/* Outstanding uses (+1)	    */
-	atomic_t	  finalization;	/* Finalization in progress	    */
-	atomic_t	  block_count;	/* Count of processes waiting	    */
-	atomic_t	  block_read;	/* Queue blocked for reads	    */
-	wait_queue_head_t read_queue;	/* Processes waiting on block_read  */
-	atomic_t	  block_write;	/* Queue blocked for writes	    */
-	wait_queue_head_t write_queue;	/* Processes waiting on block_write */
+	atomic_t	  use_count;	/**< Outstanding uses (+1) */
+	atomic_t	  finalization;	/**< Finalization in progress */
+	atomic_t	  block_count;	/**< Count of processes waiting */
+	atomic_t	  block_read;	/**< Queue blocked for reads */
+	wait_queue_head_t read_queue;	/**< Processes waiting on block_read */
+	atomic_t	  block_write;	/**< Queue blocked for writes */
+	wait_queue_head_t write_queue;	/**< Processes waiting on block_write */
 #if 1
-	atomic_t	  total_queued;	/* Total queued statistic	    */
-	atomic_t	  total_flushed;/* Total flushes statistic	    */
-	atomic_t	  total_locks;	/* Total locks statistics	    */
+	atomic_t	  total_queued;	/**< Total queued statistic */
+	atomic_t	  total_flushed;/**< Total flushes statistic */
+	atomic_t	  total_locks;	/**< Total locks statistics */
 #endif
-	drm_ctx_flags_t	  flags;	/* Context preserving and 2D-only   */
-	drm_waitlist_t	  waitlist;	/* Pending buffers		    */
-	wait_queue_head_t flush_queue;	/* Processes waiting until flush    */
+	drm_ctx_flags_t	  flags;	/**< Context preserving and 2D-only */
+	drm_waitlist_t	  waitlist;	/**< Pending buffers */
+	wait_queue_head_t flush_queue;	/**< Processes waiting until flush */
 } drm_queue_t;
 
+/**
+ * Lock data.
+ */
 typedef struct drm_lock_data {
-	drm_hw_lock_t	  *hw_lock;	/* Hardware lock		   */
-	struct file       *filp;	/* File descr of lock holder (0=kernel)   */
-	wait_queue_head_t lock_queue;	/* Queue of blocked processes	   */
-	unsigned long	  lock_time;	/* Time of last lock in jiffies	   */
+	drm_hw_lock_t	  *hw_lock;	/**< Hardware lock */
+	struct file       *filp;	/**< File descr of lock holder (0=kernel) */
+	wait_queue_head_t lock_queue;	/**< Queue of blocked processes */
+	unsigned long	  lock_time;	/**< Time of last lock in jiffies */
 } drm_lock_data_t;
 
+/**
+ * DMA data.
+ */
 typedef struct drm_device_dma {
 
-	drm_buf_entry_t	  bufs[DRM_MAX_ORDER+1];
-	int		  buf_count;
-	drm_buf_t	  **buflist;	/* Vector of pointers info bufs	   */
+	drm_buf_entry_t	  bufs[DRM_MAX_ORDER+1];	/**< buffers, grouped by their size order */
+	int		  buf_count;	/**< total number of buffers */
+	drm_buf_t	  **buflist;	/**< Vector of pointers into drm_device_dma::bufs */
 	int		  seg_count;
-	int		  page_count;
-	unsigned long	  *pagelist;
+	int		  page_count;	/**< number of pages */
+	unsigned long	  *pagelist;	/**< page list */
 	unsigned long	  byte_count;
 	enum {
 		_DRM_DMA_USE_AGP = 0x01,
 		_DRM_DMA_USE_SG  = 0x02
 	} flags;
 
-				/* DMA support */
-	drm_buf_t	  *this_buffer;	/* Buffer being sent		   */
-	drm_buf_t	  *next_buffer; /* Selected buffer to send	   */
-	drm_queue_t	  *next_queue;	/* Queue from which buffer selected*/
-	wait_queue_head_t waiting;	/* Processes waiting on free bufs  */
+	/** \name DMA support */
+	/*@{*/
+	drm_buf_t	  *this_buffer;	/**< Buffer being sent */
+	drm_buf_t	  *next_buffer; /**< Selected buffer to send */
+	drm_queue_t	  *next_queue;	/**< Queue from which buffer selected*/
+	wait_queue_head_t waiting;	/**< Processes waiting on free bufs */
+	/*@}*/
 } drm_device_dma_t;
 
 #if __REALLY_HAVE_AGP
+/** 
+ * AGP memory entry.  Stored as a doubly linked list.
+ */
 typedef struct drm_agp_mem {
-	unsigned long      handle;
-	agp_memory         *memory;
-	unsigned long      bound; /* address */
+	unsigned long      handle;	/**< handle */
+	agp_memory         *memory;	
+	unsigned long      bound;	/**< address */
 	int                pages;
-	struct drm_agp_mem *prev;
-	struct drm_agp_mem *next;
+	struct drm_agp_mem *prev;	/**< previous entry */
+	struct drm_agp_mem *next;	/**< next entry */
 } drm_agp_mem_t;
 
+/**
+ * AGP data.
+ *
+ * \sa DRM(agp_init)() and drm_device::agp.
+ */
 typedef struct drm_agp_head {
-	agp_kern_info      agp_info;
-	drm_agp_mem_t      *memory;
-	unsigned long      mode;
-	int                enabled;
-	int                acquired;
+	agp_kern_info      agp_info;	/**< AGP device information */
+	drm_agp_mem_t      *memory;	/**< memory entries */
+	unsigned long      mode;	/**< AGP mode */
+	int                enabled;	/**< whether the AGP bus as been enabled */
+	int                acquired;	/**< whether the AGP device has been acquired */
 	unsigned long      base;
    	int 		   agp_mtrr;
 	int		   cant_use_aperture;
@@ -490,6 +606,9 @@ typedef struct drm_agp_head {
 } drm_agp_head_t;
 #endif
 
+/**
+ * Scatter-gather memory.
+ */
 typedef struct drm_sg_mem {
 	unsigned long   handle;
 	void            *virtual;
@@ -503,9 +622,12 @@ typedef struct drm_sigdata {
 	drm_hw_lock_t *lock;
 } drm_sigdata_t;
 
+/**
+ * Mappings list
+ */
 typedef struct drm_map_list {
-	struct list_head	head;
-	drm_map_t		*map;
+	struct list_head	head;	/**< list head */
+	drm_map_t		*map;	/**< mapping */
 } drm_map_list_t;
 
 typedef drm_map_t drm_local_map_t;
@@ -521,92 +643,112 @@ typedef struct drm_vbl_sig {
 
 #endif
 
+/**
+ * DRM device structure.
+ */
 typedef struct drm_device {
-	const char	  *name;	/* Simple driver name		   */
-	char		  *unique;	/* Unique identifier: e.g., busid  */
-	int		  unique_len;	/* Length of unique field	   */
-	dev_t		  device;	/* Device number for mknod	   */
-	char		  *devname;	/* For /proc/interrupts		   */
-
-	int		  blocked;	/* Blocked due to VC switch?	   */
-	struct proc_dir_entry *root;	/* Root for this device's entries  */
-
-				/* Locks */
-	spinlock_t	  count_lock;	/* For inuse, open_count, buf_use  */
-	struct semaphore  struct_sem;	/* For others			   */
-
-				/* Usage Counters */
-	int		  open_count;	/* Outstanding files open	   */
-	atomic_t	  ioctl_count;	/* Outstanding IOCTLs pending	   */
-	atomic_t	  vma_count;	/* Outstanding vma areas open	   */
-	int		  buf_use;	/* Buffers in use -- cannot alloc  */
-	atomic_t	  buf_alloc;	/* Buffer allocation in progress   */
-
-				/* Performance counters */
+	const char	  *name;	/**< Simple driver name */
+	char		  *unique;	/**< Unique identifier: e.g., busid */
+	int		  unique_len;	/**< Length of unique field */
+	dev_t		  device;	/**< Device number for mknod */
+	char		  *devname;	/**< For /proc/interrupts */
+
+	int		  blocked;	/**< Blocked due to VC switch? */
+	struct proc_dir_entry *root;	/**< Root for this device's entries */
+
+	/** \name Locks */
+	/*@{*/
+	spinlock_t	  count_lock;	/**< For inuse, drm_device::open_count, drm_device::buf_use */
+	struct semaphore  struct_sem;	/**< For others */
+	/*@}*/
+
+	/** \name Usage Counters */
+	/*@{*/
+	int		  open_count;	/**< Outstanding files open */
+	atomic_t	  ioctl_count;	/**< Outstanding IOCTLs pending */
+	atomic_t	  vma_count;	/**< Outstanding vma areas open */
+	int		  buf_use;	/**< Buffers in use -- cannot alloc */
+	atomic_t	  buf_alloc;	/**< Buffer allocation in progress */
+	/*@}*/
+
+	/** \name Performance counters */
+	/*@{*/
 	unsigned long     counters;
 	drm_stat_type_t   types[15];
 	atomic_t          counts[15];
+	/*@}*/
 
-				/* Authentication */
-	drm_file_t	  *file_first;
-	drm_file_t	  *file_last;
-	drm_magic_head_t  magiclist[DRM_HASH_SIZE];
+	/** \name Authentication */
+	/*@{*/
+	drm_file_t	  *file_first;	/**< file list head */
+	drm_file_t	  *file_last;	/**< file list tail */
+	drm_magic_head_t  magiclist[DRM_HASH_SIZE];	/**< magic hash table */
+	/*@}*/
 
-				/* Memory management */
-	drm_map_list_t	  *maplist;	/* Linked list of regions	   */
+	/** \name Memory management */
+	/*@{*/
+	drm_map_list_t	  *maplist;	/**< Linked list of regions */
+	int		  map_count;	/**< Number of mappable regions */
 
-	drm_map_t	  **context_sareas;
+	drm_map_t	  **context_sareas; /**< per-context SAREA's */
 	int		  max_context;
 
-	drm_vma_entry_t	  *vmalist;	/* List of vmas (for debugging)	   */
-	drm_lock_data_t	  lock;		/* Information on hardware lock	   */
-
-				/* DMA queues (contexts) */
-	int		  queue_count;	/* Number of active DMA queues	   */
-	int		  queue_reserved; /* Number of reserved DMA queues */
-	int		  queue_slots;	/* Actual length of queuelist	   */
-	drm_queue_t	  **queuelist;	/* Vector of pointers to DMA queues */
-	drm_device_dma_t  *dma;		/* Optional pointer for DMA support */
-
-				/* Context support */
-	int		  irq;		/* Interrupt used by board	   */
-	__volatile__ long context_flag;	/* Context swapping flag	   */
-	__volatile__ long interrupt_flag; /* Interruption handler flag	   */
-	__volatile__ long dma_flag;	/* DMA dispatch flag		   */
-	struct timer_list timer;	/* Timer for delaying ctx switch   */
-	wait_queue_head_t context_wait; /* Processes waiting on ctx switch */
-	int		  last_checked;	/* Last context checked for DMA	   */
-	int		  last_context;	/* Last current context		   */
-	unsigned long	  last_switch;	/* jiffies at last context switch  */
+	drm_vma_entry_t	  *vmalist;	/**< List of vmas (for debugging) */
+	drm_lock_data_t	  lock;		/**< Information on hardware lock */
+	/*@}*/
+
+	/** \name DMA queues (contexts) */
+	/*@{*/
+	int		  queue_count;	/**< Number of active DMA queues */
+	int		  queue_reserved; /**< Number of reserved DMA queues */
+	int		  queue_slots;	/**< Actual length of queuelist */
+	drm_queue_t	  **queuelist;	/**< Vector of pointers to DMA queues */
+	drm_device_dma_t  *dma;		/**< Optional pointer for DMA support */
+	/*@}*/
+
+	/** \name Context support */
+	/*@{*/
+	int		  irq;		/**< Interrupt used by board */
+	__volatile__ long context_flag;	/**< Context swapping flag */
+	__volatile__ long interrupt_flag; /**< Interruption handler flag */
+	__volatile__ long dma_flag;	/**< DMA dispatch flag */
+	struct timer_list timer;	/**< Timer for delaying ctx switch */
+	wait_queue_head_t context_wait; /**< Processes waiting on ctx switch */
+	int		  last_checked;	/**< Last context checked for DMA */
+	int		  last_context;	/**< Last current context */
+	unsigned long	  last_switch;	/**< jiffies at last context switch */
+	/*@}*/
+	
 #if !HAS_WORKQUEUE
 	struct tq_struct  tq;
 #else
 	struct work_struct	work;
 #endif
+	/** \name VBLANK IRQ support */
+	/*@{*/
 #if __HAVE_VBL_IRQ
-   	wait_queue_head_t vbl_queue;
+   	wait_queue_head_t vbl_queue;	/**< VBLANK wait queue */
    	atomic_t          vbl_received;
 	spinlock_t        vbl_lock;
-	drm_vbl_sig_t     vbl_sigs;
+	drm_vbl_sig_t     vbl_sigs;	/**< signal list to send on VBLANK */
 	unsigned int      vbl_pending;
 #endif
+	/*@}*/
 	cycles_t	  ctx_start;
 	cycles_t	  lck_start;
 
-				/* Callback to X server for context switch
-				   and for heavy-handed reset. */
-	char		  buf[DRM_BSZ]; /* Output buffer		   */
-	char		  *buf_rp;	/* Read pointer			   */
-	char		  *buf_wp;	/* Write pointer		   */
-	char		  *buf_end;	/* End pointer			   */
-	struct fasync_struct *buf_async;/* Processes waiting for SIGIO	   */
-	wait_queue_head_t buf_readers;	/* Processes waiting to read	   */
-	wait_queue_head_t buf_writers;	/* Processes waiting to ctx switch */
+	char		  buf[DRM_BSZ]; /**< Output buffer */
+	char		  *buf_rp;	/**< Read pointer */
+	char		  *buf_wp;	/**< Write pointer */
+	char		  *buf_end;	/**< End pointer */
+	struct fasync_struct *buf_async;/**< Processes waiting for SIGIO */
+	wait_queue_head_t buf_readers;	/**< Processes waiting to read */
+	wait_queue_head_t buf_writers;	/**< Processes waiting to ctx switch */
 
 #if __REALLY_HAVE_AGP
-	drm_agp_head_t    *agp;
+	drm_agp_head_t    *agp;	/**< AGP data */
 #endif
-	struct pci_dev *pdev;
+	struct pci_dev *pdev;		/**< PCI device structure */
 #ifdef __alpha__
 #if LINUX_VERSION_CODE < KERNEL_VERSION(2,4,3)
 	struct pci_controler *hose;
@@ -614,17 +756,17 @@ typedef struct drm_device {
 	struct pci_controller *hose;
 #endif
 #endif
-	drm_sg_mem_t      *sg;  /* Scatter gather memory */
-	unsigned long     *ctx_bitmap;
-	void		  *dev_private;
-	drm_sigdata_t     sigdata; /* For block_all_signals */
+	drm_sg_mem_t      *sg;  /**< Scatter gather memory */
+	unsigned long     *ctx_bitmap;	/**< context bitmap */
+	void		  *dev_private; /**< device private data */
+	drm_sigdata_t     sigdata; /**< For block_all_signals */
 	sigset_t          sigmask;
 } drm_device_t;
 
 
-/* ================================================================
- * Internal function definitions
- */
+/******************************************************************/
+/** \name Internal function definitions */
+/*@{*/
 
 				/* Misc. support (drm_init.h) */
 extern int	     DRM(flags);
@@ -873,5 +1015,7 @@ extern int            DRM(ati_pcigart_cleanup)(drm_device_t *dev,
 					       unsigned long addr,
 					       dma_addr_t bus_addr);
 
+/*@}*/
+
 #endif /* __KERNEL__ */
 #endif
diff --git a/linux/drm_agpsupport.h b/linux/drm_agpsupport.h
index 22790900..81850593 100644
--- a/linux/drm_agpsupport.h
+++ b/linux/drm_agpsupport.h
@@ -1,6 +1,12 @@
-/* drm_agpsupport.h -- DRM support for AGP/GART backend -*- linux-c -*-
- * Created: Mon Dec 13 09:56:45 1999 by faith@precisioninsight.com
- *
+/**
+ * \file drm_agpsupport.h 
+ * DRM support for AGP/GART backend
+ *    
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
@@ -23,10 +29,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.
- *
- * Author:
- *    Rickard E. (Rik) Faith <faith@valinux.com>
- *    Gareth Hughes <gareth@valinux.com>
  */
 
 #define __NO_VERSION__
@@ -35,11 +37,27 @@
 
 #if __REALLY_HAVE_AGP
 
+
 #define DRM_AGP_GET (drm_agp_t *)inter_module_get("drm_agp")
 #define DRM_AGP_PUT inter_module_put("drm_agp")
 
+/**
+ * Pointer to the drm_agp_t structure made available by the agpgart module.
+ */
 static const drm_agp_t *drm_agp = NULL;
 
+/**
+ * AGP information ioctl.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a (output) drm_agp_info structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device has been initialized and acquired and fills in the
+ * drm_agp_info structure with the information in drm_agp_head::agp_info.
+ */
 int DRM(agp_info)(struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg)
 {
@@ -67,6 +85,18 @@ int DRM(agp_info)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Acquire the AGP device (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument.
+ * \return zero on success or a negative number on failure. 
+ *
+ * Verifies the AGP device hasn't been acquired before and calls
+ * drm_agp->acquire().
+ */
 int DRM(agp_acquire)(struct inode *inode, struct file *filp,
 		     unsigned int cmd, unsigned long arg)
 {
@@ -81,6 +111,17 @@ int DRM(agp_acquire)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Release the AGP device (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device has been acquired and calls drm_agp->release().
+ */
 int DRM(agp_release)(struct inode *inode, struct file *filp,
 		     unsigned int cmd, unsigned long arg)
 {
@@ -95,11 +136,28 @@ int DRM(agp_release)(struct inode *inode, struct file *filp,
 
 }
 
+/**
+ * Release the AGP device.
+ *
+ * Calls drm_agp->release().
+ */
 void DRM(agp_do_release)(void)
 {
 	if (drm_agp->release) drm_agp->release();
 }
 
+/**
+ * Enable the AGP bus.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_mode structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device has been acquired but not enabled, and calls
+ * drm_agp->enable().
+ */
 int DRM(agp_enable)(struct inode *inode, struct file *filp,
 		    unsigned int cmd, unsigned long arg)
 {
@@ -120,6 +178,18 @@ int DRM(agp_enable)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Allocate AGP memory.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_buffer structure.
+ * \return zero on success or a negative number on failure.
+ * 
+ * Verifies the AGP device is present and has been acquired, allocates the
+ * memory via alloc_agp() and creates a drm_agp_mem entry for it.
+ */
 int DRM(agp_alloc)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
@@ -169,6 +239,15 @@ int DRM(agp_alloc)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Search for the AGP memory entry associated with a handle.
+ *
+ * \param dev DRM device structure.
+ * \param handle AGP memory handle.
+ * \return pointer to the drm_agp_mem structure associated with \p handle.
+ * 
+ * Walks through drm_agp_head::memory until finding a matching handle.
+ */
 static drm_agp_mem_t *DRM(agp_lookup_entry)(drm_device_t *dev,
 					    unsigned long handle)
 {
@@ -180,6 +259,18 @@ static drm_agp_mem_t *DRM(agp_lookup_entry)(drm_device_t *dev,
 	return NULL;
 }
 
+/**
+ * Unbind AGP memory from the GATT (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_binding structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device is present and acquired, looks-up the AGP memory
+ * entry and passes it to the unbind_agp() function.
+ */
 int DRM(agp_unbind)(struct inode *inode, struct file *filp,
 		    unsigned int cmd, unsigned long arg)
 {
@@ -201,6 +292,19 @@ int DRM(agp_unbind)(struct inode *inode, struct file *filp,
 	return ret;
 }
 
+/**
+ * Bind AGP memory into the GATT (ioctl)
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_binding structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device is present and has been acquired and that no memory
+ * is currently bound into the GATT. Looks-up the AGP memory entry and passes
+ * it to bind_agp() function.
+ */
 int DRM(agp_bind)(struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg)
 {
@@ -226,6 +330,20 @@ int DRM(agp_bind)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Free AGP memory (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_agp_buffer structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the AGP device is present and has been acquired and looks up the
+ * AGP memory entry. If the memory it's currently bound, unbind it via
+ * unbind_agp(). Frees it via free_agp() as well as the entry itself
+ * and unlinks from the doubly linked list it's inserted in.
+ */
 int DRM(agp_free)(struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg)
 {
@@ -249,6 +367,15 @@ int DRM(agp_free)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Initialize the AGP resources.
+ *
+ * \return pointer to a drm_agp_head structure.
+ *
+ * Gets the drm_agp_t structure which is made available by the agpgart module
+ * via the inter_module_* functions. Creates and initializes a drm_agp_head
+ * structure.
+ */
 drm_agp_head_t *DRM(agp_init)(void)
 {
 	drm_agp_head_t *head         = NULL;
@@ -281,18 +408,25 @@ drm_agp_head_t *DRM(agp_init)(void)
 	return head;
 }
 
+/**
+ * Free the AGP resources.
+ *
+ * Releases the pointer in ::drm_agp.
+ */
 void DRM(agp_uninit)(void)
 {
 	DRM_AGP_PUT;
 	drm_agp = NULL;
 }
 
+/** Calls drm_agp->allocate_memory() */
 agp_memory *DRM(agp_allocate_memory)(size_t pages, u32 type)
 {
 	if (!drm_agp->allocate_memory) return NULL;
 	return drm_agp->allocate_memory(pages, type);
 }
 
+/** Calls drm_agp->free_memory() */
 int DRM(agp_free_memory)(agp_memory *handle)
 {
 	if (!handle || !drm_agp->free_memory) return 0;
@@ -300,12 +434,14 @@ int DRM(agp_free_memory)(agp_memory *handle)
 	return 1;
 }
 
+/** Calls drm_agp->bind_memory() */
 int DRM(agp_bind_memory)(agp_memory *handle, off_t start)
 {
 	if (!handle || !drm_agp->bind_memory) return -EINVAL;
 	return drm_agp->bind_memory(handle, start);
 }
 
+/** Calls drm_agp->unbind_memory() */
 int DRM(agp_unbind_memory)(agp_memory *handle)
 {
 	if (!handle || !drm_agp->unbind_memory) return -EINVAL;
diff --git a/linux/drm_auth.h b/linux/drm_auth.h
index 8fce6dfc..e027303a 100644
--- a/linux/drm_auth.h
+++ b/linux/drm_auth.h
@@ -1,4 +1,12 @@
-/* drm_auth.h -- IOCTLs for authentication -*- linux-c -*-
+/**
+ * \file drm_auth.h 
+ * IOCTLs for authentication
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Tue Feb  2 08:37:54 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,20 +31,35 @@
  * 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__
 #include "drmP.h"
 
+/**
+ * Generate a hash key from a magic.
+ *
+ * \param magic magic.
+ * \return hash key.
+ *
+ * The key is the modulus of the hash table size, #DRM_HASH_SIZE, which must be
+ * a power of 2.
+ */
 static int DRM(hash_magic)(drm_magic_t magic)
 {
 	return magic & (DRM_HASH_SIZE-1);
 }
 
+/**
+ * Find the file with the given magic number.
+ *
+ * \param dev DRM device.
+ * \param magic magic number.
+ *
+ * Searches in drm_device::magiclist within all files with the same hash key
+ * the one with matching magic number, while holding the drm_device::struct_sem
+ * lock.
+ */
 static drm_file_t *DRM(find_file)(drm_device_t *dev, drm_magic_t magic)
 {
 	drm_file_t	  *retval = NULL;
@@ -54,6 +77,17 @@ static drm_file_t *DRM(find_file)(drm_device_t *dev, drm_magic_t magic)
 	return retval;
 }
 
+/**
+ * Adds a magic number.
+ * 
+ * \param dev DRM device.
+ * \param priv file private data.
+ * \param magic magic number.
+ *
+ * Creates a drm_magic_entry structure and appends to the linked list
+ * associated the magic number hash key in drm_device::magiclist, while holding
+ * the drm_device::struct_sem lock.
+ */
 int DRM(add_magic)(drm_device_t *dev, drm_file_t *priv, drm_magic_t magic)
 {
 	int		  hash;
@@ -82,12 +116,22 @@ int DRM(add_magic)(drm_device_t *dev, drm_file_t *priv, drm_magic_t magic)
 	return 0;
 }
 
+/**
+ * Remove a magic number.
+ * 
+ * \param dev DRM device.
+ * \param magic magic number.
+ *
+ * Searches and unlinks the entry in drm_device::magiclist with the magic
+ * number hash key, while holding the drm_device::struct_sem lock.
+ */
 int DRM(remove_magic)(drm_device_t *dev, drm_magic_t magic)
 {
 	drm_magic_entry_t *prev = NULL;
 	drm_magic_entry_t *pt;
 	int		  hash;
 
+
 	DRM_DEBUG("%d\n", magic);
 	hash = DRM(hash_magic)(magic);
 
@@ -114,6 +158,19 @@ int DRM(remove_magic)(drm_device_t *dev, drm_magic_t magic)
 	return -EINVAL;
 }
 
+/**
+ * Get a unique magic number (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a resulting drm_auth structure.
+ * \return zero on success, or a negative number on failure.
+ *
+ * If there is a magic number in drm_file::magic then use it, otherwise
+ * searches an unique non-zero magic number and add it associating it with \p
+ * filp.
+ */
 int DRM(getmagic)(struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg)
 {
@@ -143,6 +200,17 @@ int DRM(getmagic)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Authenticate with a magic.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_auth structure.
+ * \return zero if authentication successed, or a negative number otherwise.
+ *
+ * Checks if \p filp is associated with the magic number passed in \arg.
+ */
 int DRM(authmagic)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
diff --git a/linux/drm_bufs.h b/linux/drm_bufs.h
index 6943eb3d..77573709 100644
--- a/linux/drm_bufs.h
+++ b/linux/drm_bufs.h
@@ -1,4 +1,12 @@
-/* drm_bufs.h -- Generic buffer template -*- linux-c -*-
+/**
+ * \file drm_bufs.h 
+ * Generic buffer template
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Thu Nov 23 03:10:50 2000 by gareth@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,8 +56,15 @@
 #endif
 #endif
 
-/*
- * Compute order.  Can be made faster.
+
+/**
+ * Compute size order.  Returns the exponent of the smaller power of two which
+ * is greater or equal to given number.
+ * 
+ * \param size size.
+ * \return order.
+ *
+ * \todo Can be made faster.
  */
 int DRM(order)( unsigned long size )
 {
@@ -68,6 +79,19 @@ int DRM(order)( unsigned long size )
 	return order;
 }
 
+/**
+ * Ioctl to specify a range of memory that is available for mapping by a non-root process.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_map structure.
+ * \return zero on success or a negative value on error.
+ *
+ * Adjusts the memory offset to its absolute value according to the mapping
+ * type.  Adds the map to the map list drm_device::maplist. Adds MTRR's where
+ * applicable and if supported by the kernel.
+ */
 int DRM(addmap)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -187,10 +211,22 @@ int DRM(addmap)( struct inode *inode, struct file *filp,
 }
 
 
-/* Remove a map private from list and deallocate resources if the mapping
+/**
+ * Remove a map private from list and deallocate resources if the mapping
  * isn't in use.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_map_t structure.
+ * \return zero on success or a negative value on error.
+ *
+ * Searches the map on drm_device::maplist, removes it from the list, see if
+ * its being used, and free any associate resource (such as MTRR's) if it's not
+ * being on use.
+ *
+ * \sa addmap().
  */
-
 int DRM(rmmap)(struct inode *inode, struct file *filp,
 	       unsigned int cmd, unsigned long arg)
 {
@@ -263,7 +299,13 @@ int DRM(rmmap)(struct inode *inode, struct file *filp,
 
 #if __HAVE_DMA
 
-
+/**
+ * Cleanup after an error on one of the addbufs() functions.
+ *
+ * \param entry buffer entry where the error occurred.
+ *
+ * Frees any pages and buffers associated with the given entry.
+ */
 static void DRM(cleanup_buf_error)(drm_buf_entry_t *entry)
 {
 	int i;
@@ -306,6 +348,19 @@ static void DRM(cleanup_buf_error)(drm_buf_entry_t *entry)
 }
 
 #if __REALLY_HAVE_AGP
+/**
+ * Add AGP buffers for DMA transfers (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_desc_t request.
+ * \return zero on success or a negative number on failure.
+ * 
+ * After some sanity checks creates a drm_buf structure for each buffer and
+ * reallocates the buffer list of the same size order to accommodate the new
+ * buffers.
+ */
 int DRM(addbufs_agp)( struct inode *inode, struct file *filp,
 		      unsigned int cmd, unsigned long arg )
 {
@@ -713,7 +768,7 @@ int DRM(addbufs_pci)( struct inode *inode, struct file *filp,
 }
 #endif /* __HAVE_PCI_DMA */
 
-#ifdef __HAVE_SG
+#if __HAVE_SG
 int DRM(addbufs_sg)( struct inode *inode, struct file *filp,
                      unsigned int cmd, unsigned long arg )
 {
@@ -885,6 +940,20 @@ int DRM(addbufs_sg)( struct inode *inode, struct file *filp,
 }
 #endif /* __HAVE_SG */
 
+/**
+ * Add buffers for DMA transfers (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_desc_t request.
+ * \return zero on success or a negative number on failure.
+ *
+ * According with the memory type specified in drm_buf_desc::flags and the
+ * build options, it dispatches the call either to addbufs_agp(),
+ * addbufs_sg() or addbufs_pci() for AGP, scatter-gather or consistent
+ * PCI memory respectively.
+ */
 int DRM(addbufs)( struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg )
 {
@@ -911,6 +980,24 @@ int DRM(addbufs)( struct inode *inode, struct file *filp,
 #endif
 }
 
+
+/**
+ * Get information about the buffer mappings.
+ *
+ * This was originally mean for debugging purposes, or by a sophisticated
+ * client library to determine how best to use the available buffers (e.g.,
+ * large buffers can be used for image transfer).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_info structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Increments drm_device::buf_use while holding the drm_device::count_lock
+ * lock, preventing of allocating more buffers after this call. Information
+ * about each requested buffer is then copied into user space.
+ */
 int DRM(infobufs)( struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg )
 {
@@ -982,6 +1069,20 @@ int DRM(infobufs)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Specifies a low and high water mark for buffer allocation
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg a pointer to a drm_buf_desc structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies that the size order is bounded between the admissible orders and
+ * updates the respective drm_device_dma::bufs entry low and high water mark.
+ *
+ * \note This ioctl is deprecated and mostly never used.
+ */
 int DRM(markbufs)( struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg )
 {
@@ -1016,6 +1117,18 @@ int DRM(markbufs)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Unreserve the buffers in list, previously reserved using drmDMA. 
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_free structure.
+ * \return zero on success or a negative number on failure.
+ * 
+ * Calls free_buffer() for each used buffer.
+ * This function is primarily used for debugging.
+ */
 int DRM(freebufs)( struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg )
 {
@@ -1057,6 +1170,19 @@ int DRM(freebufs)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Maps all of the DMA buffers into client-virtual space (ioctl).
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg pointer to a drm_buf_map structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Maps the AGP or SG buffer region with do_mmap(), and copies information
+ * about each buffer into user space. The PCI buffers are already mapped on the
+ * addbufs_pci() call.
+ */
 int DRM(mapbufs)( struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg )
 {
diff --git a/linux/drm_context.h b/linux/drm_context.h
index 3853a7c6..82e90bcc 100644
--- a/linux/drm_context.h
+++ b/linux/drm_context.h
@@ -1,4 +1,12 @@
-/* drm_context.h -- IOCTLs for generic contexts -*- linux-c -*-
+/**
+ * \file drm_context.h 
+ * IOCTLs for generic contexts
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Fri Nov 24 18:31:37 2000 by gareth@valinux.com
  *
  * Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,10 +31,9 @@
  * 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>
+ */
+
+/*
  * ChangeLog:
  *  2001-11-16	Torsten Duwe <duwe@caldera.de>
  *		added context constructor/destructor hooks,
@@ -41,10 +48,20 @@
 #endif
 
 
-/* ================================================================
- * Context bitmap support
- */
+/******************************************************************/
+/** \name Context bitmap support */
+/*@{*/
 
+/**
+ * Free a handle from the context bitmap.
+ *
+ * \param dev DRM device.
+ * \param ctx_handle context handle.
+ *
+ * Clears the bit specified by \p ctx_handle in drm_device::ctx_bitmap and the entry
+ * in drm_device::context_sareas, while holding the drm_device::struct_sem
+ * lock.
+ */
 void DRM(ctxbitmap_free)( drm_device_t *dev, int ctx_handle )
 {
 	if ( ctx_handle < 0 ) goto failed;
@@ -63,6 +80,16 @@ failed:
        	return;
 }
 
+/** 
+ * Context bitmap allocation.
+ *
+ * \param dev DRM device.
+ * \return (non-negative) context handle on success or a negative number on failure.
+ *
+ * Find the first zero bit in drm_device::ctx_bitmap and (re)allocates
+ * drm_device::context_sareas to accommodate the new entry while holding the
+ * drm_device::struct_sem lock.
+ */
 int DRM(ctxbitmap_next)( drm_device_t *dev )
 {
 	int bit;
@@ -113,6 +140,14 @@ int DRM(ctxbitmap_next)( drm_device_t *dev )
 	return -1;
 }
 
+/**
+ * Context bitmap initialization.
+ *
+ * \param dev DRM device.
+ *
+ * Allocates and initialize drm_device::ctx_bitmap and drm_device::context_sareas, while holding
+ * the drm_device::struct_sem lock.
+ */
 int DRM(ctxbitmap_init)( drm_device_t *dev )
 {
 	int i;
@@ -138,6 +173,14 @@ int DRM(ctxbitmap_init)( drm_device_t *dev )
 	return 0;
 }
 
+/**
+ * Context bitmap cleanup.
+ *
+ * \param dev DRM device.
+ *
+ * Frees drm_device::ctx_bitmap and drm_device::context_sareas, while holding
+ * the drm_device::struct_sem lock.
+ */
 void DRM(ctxbitmap_cleanup)( drm_device_t *dev )
 {
 	down(&dev->struct_sem);
@@ -149,10 +192,24 @@ void DRM(ctxbitmap_cleanup)( drm_device_t *dev )
 	up(&dev->struct_sem);
 }
 
-/* ================================================================
- * Per Context SAREA Support
- */
+/*@}*/
+
+/******************************************************************/
+/** \name Per Context SAREA Support */
+/*@{*/
 
+/**
+ * Get per-context SAREA.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx_priv_map structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Gets the map from drm_device::context_sareas with the handle specified and
+ * returns its handle.
+ */
 int DRM(getsareactx)(struct inode *inode, struct file *filp,
 		     unsigned int cmd, unsigned long arg)
 {
@@ -181,6 +238,18 @@ int DRM(getsareactx)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Set per-context SAREA.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx_priv_map structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Searches the mapping specified in \p arg and update the entry in
+ * drm_device::context_sareas with it.
+ */
 int DRM(setsareactx)(struct inode *inode, struct file *filp,
 		     unsigned int cmd, unsigned long arg)
 {
@@ -219,10 +288,22 @@ found:
 	return 0;
 }
 
-/* ================================================================
- * The actual DRM context handling routines
- */
+/*@}*/
+
+/******************************************************************/
+/** \name The actual DRM context handling routines */
+/*@{*/
 
+/**
+ * Switch context.
+ *
+ * \param dev DRM device.
+ * \param old old context handle.
+ * \param new new context handle.
+ * \return zero on success or a negative number on failure.
+ *
+ * Attempt to set drm_device::context_flag.
+ */
 int DRM(context_switch)( drm_device_t *dev, int old, int new )
 {
         if ( test_and_set_bit( 0, &dev->context_flag ) ) {
@@ -241,6 +322,17 @@ int DRM(context_switch)( drm_device_t *dev, int old, int new )
         return 0;
 }
 
+/**
+ * Complete context switch.
+ *
+ * \param dev DRM device.
+ * \param new new context handle.
+ * \return zero on success or a negative number on failure.
+ *
+ * Updates drm_device::last_context and drm_device::last_switch. Verifies the
+ * hardware lock is held, clears the drm_device::context_flag and wakes up
+ * drm_device::context_wait.
+ */
 int DRM(context_switch_complete)( drm_device_t *dev, int new )
 {
         dev->last_context = new;  /* PRE/POST: This is the _only_ writer. */
@@ -259,6 +351,15 @@ int DRM(context_switch_complete)( drm_device_t *dev, int new )
         return 0;
 }
 
+/**
+ * Reserve contexts.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx_res structure.
+ * \return zero on success or a negative number on failure.
+ */
 int DRM(resctx)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -285,6 +386,17 @@ int DRM(resctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Add context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Get a new handle for the context and copy to userspace.
+ */
 int DRM(addctx)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -323,6 +435,15 @@ int DRM(modctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Get context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ */
 int DRM(getctx)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -339,6 +460,17 @@ int DRM(getctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Switch context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Calls context_switch().
+ */
 int DRM(switchctx)( struct inode *inode, struct file *filp,
 		    unsigned int cmd, unsigned long arg )
 {
@@ -353,6 +485,17 @@ int DRM(switchctx)( struct inode *inode, struct file *filp,
 	return DRM(context_switch)( dev, dev->last_context, ctx.handle );
 }
 
+/**
+ * New context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Calls context_switch_complete().
+ */
 int DRM(newctx)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -369,6 +512,17 @@ int DRM(newctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Remove context.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument pointing to a drm_ctx structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * If not the special kernel context, calls ctxbitmap_free() to free the specified context.
+ */
 int DRM(rmctx)( struct inode *inode, struct file *filp,
 		unsigned int cmd, unsigned long arg )
 {
@@ -393,3 +547,4 @@ int DRM(rmctx)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/*@}*/
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;
diff --git a/linux/drm_drawable.h b/linux/drm_drawable.h
index 13e46b9f..892ae4e0 100644
--- a/linux/drm_drawable.h
+++ b/linux/drm_drawable.h
@@ -1,4 +1,12 @@
-/* drm_drawable.h -- IOCTLs for drawables -*- linux-c -*-
+/**
+ * \file drm_drawable.h 
+ * IOCTLs for drawables
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Tue Feb  2 08:37:54 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,15 +31,12 @@
  * 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__
 #include "drmP.h"
 
+/** No-op. */
 int DRM(adddraw)(struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg)
 {
@@ -44,6 +49,7 @@ int DRM(adddraw)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/** No-op. */
 int DRM(rmdraw)(struct inode *inode, struct file *filp,
 		unsigned int cmd, unsigned long arg)
 {
diff --git a/linux/drm_drv.h b/linux/drm_drv.h
index 0a4390d3..90c2d18b 100644
--- a/linux/drm_drv.h
+++ b/linux/drm_drv.h
@@ -1,4 +1,31 @@
-/* drm_drv.h -- Generic driver template -*- linux-c -*-
+/**
+ * \file drm_drv.h 
+ * Generic driver template
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ *
+ * To use this template, you must at least define the following (samples
+ * given for the MGA driver):
+ *
+ * \code
+ * #define DRIVER_AUTHOR	"VA Linux Systems, Inc."
+ *
+ * #define DRIVER_NAME		"mga"
+ * #define DRIVER_DESC		"Matrox G200/G400"
+ * #define DRIVER_DATE		"20001127"
+ *
+ * #define DRIVER_MAJOR		2
+ * #define DRIVER_MINOR		0
+ * #define DRIVER_PATCHLEVEL	2
+ *
+ * #define DRIVER_IOCTL_COUNT	DRM_ARRAY_SIZE( mga_ioctls )
+ *
+ * #define DRM(x)		mga_##x
+ * \endcode
+ */
+
+/*
  * Created: Thu Nov 23 03:10:50 2000 by gareth@valinux.com
  *
  * Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,29 +50,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>
- */
-
-/*
- * To use this template, you must at least define the following (samples
- * given for the MGA driver):
- *
- * #define DRIVER_AUTHOR	"VA Linux Systems, Inc."
- *
- * #define DRIVER_NAME		"mga"
- * #define DRIVER_DESC		"Matrox G200/G400"
- * #define DRIVER_DATE		"20001127"
- *
- * #define DRIVER_MAJOR		2
- * #define DRIVER_MINOR		0
- * #define DRIVER_PATCHLEVEL	2
- *
- * #define DRIVER_IOCTL_COUNT	DRM_ARRAY_SIZE( mga_ioctls )
- *
- * #define DRM(x)		mga_##x
  */
 
 #ifndef __MUST_HAVE_AGP
@@ -134,12 +138,13 @@ static struct file_operations	DRM(fops) = {	\
 #endif
 
 #ifndef MODULE
-/* DRM(options) is called by the kernel to parse command-line options
- * passed via the boot-loader (e.g., LILO).  It calls the insmod option
- * routine, drm_parse_drm.
- */
-/* Use an additional macro to avoid preprocessor troubles */
+/** Use an additional macro to avoid preprocessor troubles */
 #define DRM_OPTIONS_FUNC DRM(options)
+/**
+ * Called by the kernel to parse command-line options passed via the
+ * boot-loader (e.g., LILO).  It calls the insmod option routine,
+ * parse_options().
+ */
 static int __init DRM(options)( char *str )
 {
 	DRM(parse_options)( str );
@@ -150,7 +155,7 @@ __setup( DRIVER_NAME "=", DRM_OPTIONS_FUNC );
 #undef DRM_OPTIONS_FUNC
 #endif
 
-/*
+/**
  * The default number of instances (minor numbers) to initialize.
  */
 #ifndef DRIVER_NUM_CARDS
@@ -163,6 +168,7 @@ static int		DRM(numdevs) = 0;
 
 DRIVER_FOPS;
 
+/** Ioctl table */
 static drm_ioctl_desc_t		  DRM(ioctls)[] = {
 	[DRM_IOCTL_NR(DRM_IOCTL_VERSION)]       = { DRM(version),     0, 0 },
 	[DRM_IOCTL_NR(DRM_IOCTL_GET_UNIQUE)]    = { DRM(getunique),   0, 0 },
@@ -349,7 +355,8 @@ static int DRM(setup)( drm_device_t *dev )
 
 	DRM_DEBUG( "\n" );
 
-	/* The kernel's context could be created here, but is now created
+	/*
+	 * The kernel's context could be created here, but is now created
 	 * in drm_dma_enqueue.	This is more resource-efficient for
 	 * hardware that does not do DMA, but may mean that
 	 * drm_select_queue fails between the time the interrupt is
@@ -360,6 +367,15 @@ static int DRM(setup)( drm_device_t *dev )
 }
 
 
+/**
+ * Take down the DRM device.
+ *
+ * \param dev DRM device structure.
+ *
+ * Frees every resource in \p dev.
+ *
+ * \sa drm_device and setup().
+ */
 static int DRM(takedown)( drm_device_t *dev )
 {
 	drm_magic_entry_t *pt, *next;
@@ -517,8 +533,12 @@ static int DRM(takedown)( drm_device_t *dev )
 	return 0;
 }
 
-/*
+/**
  * Figure out how many instances to initialize.
+ *
+ * \return number of cards found.
+ *
+ * Searches for every PCI card in \c DRIVER_CARD_LIST with matching vendor and device ids.
  */
 static int drm_count_cards(void)
 {
@@ -552,8 +572,18 @@ static int drm_count_cards(void)
 	return num;
 }
 
-/* drm_init is called via init_module at module load time, or via
+/**
+ * Module initialization. Called via init_module at module load time, or via
  * linux/init/main.c (this is not currently supported).
+ *
+ * \return zero on success or a negative number on failure.
+ *
+ * Allocates and initialize an array of drm_device structures, and attempts to
+ * initialize all available devices, using consecutive minors, 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.
  */
 static int __init drm_init( void )
 {
@@ -641,7 +671,12 @@ static int __init drm_init( void )
 	return 0;
 }
 
-/* drm_cleanup is called via cleanup_module at module unload time.
+/**
+ * Called via cleanup_module() at module unload time.
+ *
+ * Cleans up all DRM device, calling takedown().
+ * 
+ * \sa drm_init().
  */
 static void __exit drm_cleanup( void )
 {
@@ -694,6 +729,17 @@ module_init( drm_init );
 module_exit( drm_cleanup );
 
 
+/**
+ * Get version information
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_version structure.
+ * \return zero on success or negative number on failure.
+ *
+ * Fills in the version information in \p arg.
+ */
 int DRM(version)( struct inode *inode, struct file *filp,
 		  unsigned int cmd, unsigned long arg )
 {
@@ -729,6 +775,17 @@ int DRM(version)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Open file.
+ * 
+ * \param inode device inode
+ * \param filp file pointer.
+ * \return zero on success or a negative number on failure.
+ *
+ * Searches the DRM device with the same minor number, calls open_helper(), and
+ * increments the device open count. If the open count was previous at zero,
+ * i.e., it's the first that the device is open, then calls setup().
+ */
 int DRM(open)( struct inode *inode, struct file *filp )
 {
 	drm_device_t *dev = NULL;
@@ -759,6 +816,18 @@ int DRM(open)( struct inode *inode, struct file *filp )
 	return retcode;
 }
 
+/**
+ * Release file.
+ *
+ * \param inode device inode
+ * \param filp file pointer.
+ * \return zero on success or a negative number on failure.
+ *
+ * If the hardware lock is held then free it, and take it again for the kernel
+ * context since it's necessary to reclaim buffers. Unlink the file private
+ * data from its list and free it. Decreases the open count and if it reaches
+ * zero calls takedown().
+ */
 int DRM(release)( struct inode *inode, struct file *filp )
 {
 	drm_file_t *priv = filp->private_data;
@@ -885,7 +954,17 @@ int DRM(release)( struct inode *inode, struct file *filp )
 	return retcode;
 }
 
-/* DRM(ioctl) is called whenever a process performs an ioctl on /dev/drm.
+/** 
+ * Called whenever a process performs an ioctl on /dev/drm.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument.
+ * \return zero on success or negative number on failure.
+ *
+ * Looks up the ioctl function in the ::ioctls table, checking for root
+ * previleges if so required, and dispatches to the respective function.
  */
 int DRM(ioctl)( struct inode *inode, struct file *filp,
 		unsigned int cmd, unsigned long arg )
@@ -926,6 +1005,17 @@ int DRM(ioctl)( struct inode *inode, struct file *filp,
 	return retcode;
 }
 
+/** 
+ * Lock ioctl.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_lock structure.
+ * \return zero on success or negative number on failure.
+ *
+ * Add the current task to the lock wait queue, and attempt to take to lock.
+ */
 int DRM(lock)( struct inode *inode, struct file *filp,
 	       unsigned int cmd, unsigned long arg )
 {
@@ -1031,7 +1121,17 @@ int DRM(lock)( struct inode *inode, struct file *filp,
         return ret;
 }
 
-
+/** 
+ * Unlock ioctl.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_lock structure.
+ * \return zero on success or negative number on failure.
+ *
+ * Transfer and free the lock.
+ */
 int DRM(unlock)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
diff --git a/linux/drm_fops.h b/linux/drm_fops.h
index fc8618e1..f4841ae8 100644
--- a/linux/drm_fops.h
+++ b/linux/drm_fops.h
@@ -1,4 +1,13 @@
-/* drm_fops.h -- File operations for DRM -*- linux-c -*-
+/**
+ * \file drm_fops.h 
+ * File operations for DRM
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Daryll Strauss <daryll@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Mon Jan  4 08:58:31 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,19 +32,24 @@
  * 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>
- *    Daryll Strauss <daryll@valinux.com>
- *    Gareth Hughes <gareth@valinux.com>
  */
 
 #define __NO_VERSION__
 #include "drmP.h"
 #include <linux/poll.h>
 
-/* drm_open is called whenever a process opens /dev/drm. */
 
+/**
+ * Called whenever a process opens /dev/drm. 
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param dev device.
+ * \return zero on success or a negative number on failure.
+ * 
+ * Creates and initializes a drm_file structure for the file private data in \p
+ * filp and add it into the double linked list in \p dev.
+ */
 int DRM(open_helper)(struct inode *inode, struct file *filp, drm_device_t *dev)
 {
 	int	     minor = minor(inode->i_rdev);
@@ -91,6 +105,7 @@ int DRM(open_helper)(struct inode *inode, struct file *filp, drm_device_t *dev)
 	return 0;
 }
 
+/** No-op. */
 int DRM(flush)(struct file *filp)
 {
 	drm_file_t    *priv   = filp->private_data;
@@ -101,6 +116,7 @@ int DRM(flush)(struct file *filp)
 	return 0;
 }
 
+/** No-op. */
 int DRM(fasync)(int fd, struct file *filp, int on)
 {
 	drm_file_t    *priv   = filp->private_data;
@@ -114,6 +130,7 @@ int DRM(fasync)(int fd, struct file *filp, int on)
 }
 
 #if !__HAVE_DRIVER_FOPS_POLL
+/** No-op. */
 unsigned int DRM(poll)(struct file *filp, struct poll_table_struct *wait)
 {
 	return 0;
@@ -122,6 +139,7 @@ unsigned int DRM(poll)(struct file *filp, struct poll_table_struct *wait)
 
 
 #if !__HAVE_DRIVER_FOPS_READ
+/** No-op. */
 ssize_t DRM(read)(struct file *filp, char *buf, size_t count, loff_t *off)
 {
 	return 0;
diff --git a/linux/drm_init.h b/linux/drm_init.h
index 3aa4ad59..509e6841 100644
--- a/linux/drm_init.h
+++ b/linux/drm_init.h
@@ -1,4 +1,12 @@
-/* drm_init.h -- Setup/Cleanup for DRM -*- linux-c -*-
+/**
+ * \file drm_init.h 
+ * Setup/Cleanup for DRM
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Mon Jan  4 08:58:31 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,23 +31,24 @@
  * 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__
 #include "drmP.h"
 
+/** Debug flags.  Set by parse_option(). */
 #if 0
 int DRM(flags) = DRM_FLAG_DEBUG;
 #else
 int DRM(flags) = 0;
 #endif
 
-/* drm_parse_option parses a single option.  See description for
- * drm_parse_options for details.
+/**
+ * Parse a single option.
+ *
+ * \param s option string.
+ *
+ * \sa See parse_options() for details.
  */
 static void DRM(parse_option)(char *s)
 {
@@ -59,26 +68,33 @@ static void DRM(parse_option)(char *s)
 	return;
 }
 
-/* drm_parse_options parse the insmod "drm_opts=" options, or the command-line
- * options passed to the kernel via LILO.  The grammar of the format is as
+/**
+ * Parse the insmod "drm_opts=" options, or the command-line
+ * options passed to the kernel via LILO.  
+ *
+ * \param s contains option_list without the 'drm_opts=' part.
+ *
+ * The grammar of the format is as
  * follows:
  *
+ * \code
  * drm		::= 'drm_opts=' option_list
  * option_list	::= option [ ';' option_list ]
  * option	::= 'device:' major
  *		|   'debug'
  *		|   'noctx'
  * major	::= INTEGER
+ * \endcode
  *
- * Note that 's' contains option_list without the 'drm_opts=' part.
- *
- * device=major,minor specifies the device number used for /dev/drm
- *	  if major == 0 then the misc device is used
- *	  if major == 0 and minor == 0 then dynamic misc allocation is used
- * debug=on specifies that debugging messages will be printk'd
- * debug=trace specifies that each function call will be logged via printk
- * debug=off turns off all debugging options
+ * - device=major,minor specifies the device number used for /dev/drm
+ *   - if major == 0 then the misc device is used
+ *   - if major == 0 and minor == 0 then dynamic misc allocation is used
+ * - debug=on specifies that debugging messages will be printk'd
+ * - debug=trace specifies that each function call will be logged via printk
+ * - debug=off turns off all debugging options
  *
+ * \todo Actually only the \e presence of the 'debug' option is currently
+ * checked.
  */
 
 void DRM(parse_options)(char *s)
@@ -96,8 +112,10 @@ void DRM(parse_options)(char *s)
 	}
 }
 
-/* drm_cpu_valid returns non-zero if the DRI will run on this CPU, and 0
- * otherwise.
+/**
+ * Check whether DRI will run on this CPU.
+ *
+ * \return non-zero if the DRI will run on this CPU, or zero otherwise.
  */
 int DRM(cpu_valid)(void)
 {
diff --git a/linux/drm_ioctl.h b/linux/drm_ioctl.h
index 62d5a6e4..8d98000f 100644
--- a/linux/drm_ioctl.h
+++ b/linux/drm_ioctl.h
@@ -1,4 +1,12 @@
-/* drm_ioctl.h -- IOCTL processing for DRM -*- linux-c -*-
+/**
+ * \file drm_ioctl.h 
+ * IOCTL processing for DRM
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Fri Jan  8 09:01:26 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,16 +31,23 @@
  * 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__
 #include "drmP.h"
 
 
+/**
+ * Get interrupt from bus id.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \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.
+ */
 int DRM(irq_busid)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
@@ -85,6 +100,17 @@ int DRM(irq_busid)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Get the bus id.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_unique structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Copies the bus id from drm_device::unique into user space.
+ */
 int DRM(getunique)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
@@ -104,6 +130,18 @@ int DRM(getunique)(struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Set the bus id.
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_unique structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Copies the bus id from userspace into drm_device::unique, and searches for
+ * the respective PCI device, updating drm_device::pdev.
+ */
 int DRM(setunique)(struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg)
 {
@@ -181,6 +219,19 @@ int DRM(setunique)(struct inode *inode, struct file *filp,
 }
 
 
+/**
+ * Get a mapping information.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_map structure.
+ * 
+ * \return zero on success or a negative number on failure.
+ *
+ * Searches for the mapping with the specified offset and copies its information
+ * into userspace
+ */
 int DRM(getmap)( struct inode *inode, struct file *filp,
 		 unsigned int cmd, unsigned long arg )
 {
@@ -227,6 +278,19 @@ int DRM(getmap)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/**
+ * Get client information.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_client structure.
+ * 
+ * \return zero on success or a negative number on failure.
+ *
+ * Searches for the client with the specified index and copies its information
+ * into userspace
+ */
 int DRM(getclient)( struct inode *inode, struct file *filp,
 		    unsigned int cmd, unsigned long arg )
 {
@@ -260,6 +324,16 @@ int DRM(getclient)( struct inode *inode, struct file *filp,
 	return 0;
 }
 
+/** 
+ * Get statistics information. 
+ * 
+ * \param inode device inode.
+ * \param filp file pointer.
+ * \param cmd command.
+ * \param arg user argument, pointing to a drm_stats structure.
+ * 
+ * \return zero on success or a negative number on failure.
+ */
 int DRM(getstats)( struct inode *inode, struct file *filp,
 		   unsigned int cmd, unsigned long arg )
 {
diff --git a/linux/drm_lock.h b/linux/drm_lock.h
index cc9571ed..29db1079 100644
--- a/linux/drm_lock.h
+++ b/linux/drm_lock.h
@@ -1,4 +1,12 @@
-/* lock.c -- IOCTLs for locking -*- linux-c -*-
+/**
+ * \file drm_lock.h 
+ * IOCTLs for locking
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Tue Feb  2 08:37:54 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,15 +31,12 @@
  * 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__
 #include "drmP.h"
 
+/** No-op ioctl. */
 int DRM(noop)(struct inode *inode, struct file *filp, unsigned int cmd,
 	       unsigned long arg)
 {
@@ -39,7 +44,15 @@ int DRM(noop)(struct inode *inode, struct file *filp, unsigned int cmd,
 	return 0;
 }
 
-
+/**
+ * Take the heavyweight lock.
+ *
+ * \param lock lock pointer.
+ * \param context locking context.
+ * \return one if the lock is held, or zero otherwise.
+ *
+ * Attempt to mark the lock as held by the given context, via the \p cmpxchg instruction.
+ */
 int DRM(lock_take)(__volatile__ unsigned int *lock, unsigned int context)
 {
 	unsigned int old, new, prev;
@@ -66,8 +79,18 @@ int DRM(lock_take)(__volatile__ unsigned int *lock, unsigned int context)
 	return 0;
 }
 
-/* This takes a lock forcibly and hands it to context.	Should ONLY be used
-   inside *_unlock to give lock to kernel before calling *_dma_schedule. */
+/**
+ * This takes a lock forcibly and hands it to context.	Should ONLY be used
+ * inside *_unlock to give lock to kernel before calling *_dma_schedule. 
+ * 
+ * \param dev DRM device.
+ * \param lock lock pointer.
+ * \param context locking context.
+ * \return always one.
+ *
+ * Resets the lock file pointer.
+ * Marks the lock as held by the given context, via the \p cmpxchg instruction.
+ */
 int DRM(lock_transfer)(drm_device_t *dev,
 		       __volatile__ unsigned int *lock, unsigned int context)
 {
@@ -82,6 +105,17 @@ int DRM(lock_transfer)(drm_device_t *dev,
 	return 1;
 }
 
+/**
+ * Free lock.
+ * 
+ * \param dev DRM device.
+ * \param lock lock.
+ * \param context context.
+ * 
+ * Resets the lock file pointer.
+ * Marks the lock as not held, via the \p cmpxchg instruction. Wakes any task
+ * waiting on the lock queue.
+ */
 int DRM(lock_free)(drm_device_t *dev,
 		   __volatile__ unsigned int *lock, unsigned int context)
 {
@@ -103,18 +137,17 @@ int DRM(lock_free)(drm_device_t *dev,
 	return 0;
 }
 
-/* If we get here, it means that the process has called DRM_IOCTL_LOCK
-   without calling DRM_IOCTL_UNLOCK.
-
-   If the lock is not held, then let the signal proceed as usual.
-
-   If the lock is held, then set the contended flag and keep the signal
-   blocked.
-
-
-   Return 1 if the signal should be delivered normally.
-   Return 0 if the signal should be blocked.  */
-
+/**
+ * If we get here, it means that the process has called DRM_IOCTL_LOCK
+ * without calling DRM_IOCTL_UNLOCK.
+ *
+ * If the lock is not held, then let the signal proceed as usual.  If the lock
+ * is held, then set the contended flag and keep the signal blocked.
+ *
+ * \param priv pointer to a drm_sigdata structure.
+ * \return one if the signal should be delivered normally, or zero if the
+ * signal should be blocked.
+ */
 int DRM(notifier)(void *priv)
 {
 	drm_sigdata_t *s = (drm_sigdata_t *)priv;
diff --git a/linux/drm_memory.h b/linux/drm_memory.h
index 5f111459..2a969fcd 100644
--- a/linux/drm_memory.h
+++ b/linux/drm_memory.h
@@ -1,4 +1,12 @@
-/* drm_memory.h -- Memory management wrappers for DRM -*- linux-c -*-
+/** 
+ * \file drm_memory.h 
+ * Memory management wrappers for DRM
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/* 
  * Created: Thu Feb  4 14:00:34 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,17 +31,14 @@
  * 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__
 #include <linux/config.h>
 #include "drmP.h"
 
-/* Cut down version of drm_memory_debug.h, which used to be called
+/**
+ * Cut down version of drm_memory_debug.h, which used to be called
  * drm_memory.h.  If you want the debug functionality, change 0 to 1
  * below.
  */
@@ -196,22 +201,38 @@ static inline void drm_ioremapfree(void *pt, unsigned long size, drm_device_t *d
 #if DEBUG_MEMORY
 #include "drm_memory_debug.h"
 #else
+
+/** No-op. */
 void DRM(mem_init)(void)
 {
 }
 
-/* drm_mem_info is called whenever a process reads /dev/drm/mem. */
+/**
+ * Called when "/proc/dri/%dev%/mem" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param len requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ *
+ * No-op. 
+ */
 int DRM(mem_info)(char *buf, char **start, off_t offset,
 		  int len, int *eof, void *data)
 {
 	return 0;
 }
 
+/** Wrapper around kmalloc() */
 void *DRM(alloc)(size_t size, int area)
 {
 	return kmalloc(size, GFP_KERNEL);
 }
 
+/** Wrapper around kmalloc() and kfree() */
 void *DRM(realloc)(void *oldpt, size_t oldsize, size_t size, int area)
 {
 	void *pt;
@@ -224,11 +245,21 @@ void *DRM(realloc)(void *oldpt, size_t oldsize, size_t size, int area)
 	return pt;
 }
 
+/** Wrapper around kfree() */
 void DRM(free)(void *pt, size_t size, int area)
 {
 	kfree(pt);
 }
 
+/**
+ * Allocate pages.
+ *
+ * \param order size order.
+ * \param area memory area. (Not used.)
+ * \return page address on success, or zero on failure.
+ *
+ * Allocate and reserve free pages.
+ */
 unsigned long DRM(alloc_pages)(int order, int area)
 {
 	unsigned long address;
@@ -253,6 +284,15 @@ unsigned long DRM(alloc_pages)(int order, int area)
 	return address;
 }
 
+/**
+ * Free pages.
+ * 
+ * \param address address of the pages to free.
+ * \param order size order.
+ * \param area memory area. (Not used.)
+ *
+ * Unreserve and free pages allocated by alloc_pages().
+ */
 void DRM(free_pages)(unsigned long address, int order, int area)
 {
 	unsigned long bytes = PAGE_SIZE << order;
@@ -272,37 +312,44 @@ void DRM(free_pages)(unsigned long address, int order, int area)
 	free_pages(address, order);
 }
 
+/** Wrapper around drm_ioremap() */
 void *DRM(ioremap)(unsigned long offset, unsigned long size, drm_device_t *dev)
 {
 	return drm_ioremap(offset, size, dev);
 }
 
+/** Wrapper around drm_ioremap_nocache() */
 void *DRM(ioremap_nocache)(unsigned long offset, unsigned long size, drm_device_t *dev)
 {
 	return drm_ioremap_nocache(offset, size, dev);
 }
 
+/** Wrapper around drm_iounmap() */
 void DRM(ioremapfree)(void *pt, unsigned long size, drm_device_t *dev)
 {
 	drm_ioremapfree(pt, size, dev);
 }
 
 #if __REALLY_HAVE_AGP
+/** Wrapper around agp_allocate_memory() */
 agp_memory *DRM(alloc_agp)(int pages, u32 type)
 {
 	return DRM(agp_allocate_memory)(pages, type);
 }
 
+/** Wrapper around agp_free_memory() */
 int DRM(free_agp)(agp_memory *handle, int pages)
 {
 	return DRM(agp_free_memory)(handle) ? 0 : -EINVAL;
 }
 
+/** Wrapper around agp_bind_memory() */
 int DRM(bind_agp)(agp_memory *handle, unsigned int start)
 {
 	return DRM(agp_bind_memory)(handle, start);
 }
 
+/** Wrapper around agp_unbind_memory() */
 int DRM(unbind_agp)(agp_memory *handle)
 {
 	return DRM(agp_unbind_memory)(handle);
diff --git a/linux/drm_memory_debug.h b/linux/drm_memory_debug.h
index d74267fb..5cfff83a 100644
--- a/linux/drm_memory_debug.h
+++ b/linux/drm_memory_debug.h
@@ -1,6 +1,12 @@
-/* drm_memory.h -- Memory management wrappers for DRM -*- linux-c -*-
- * Created: Thu Feb  4 14:00:34 1999 by faith@valinux.com
+/**
+ * \file drm_memory.h 
+ * Memory management wrappers for DRM.
  *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
@@ -23,10 +29,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__
diff --git a/linux/drm_os_linux.h b/linux/drm_os_linux.h
index e804399a..c5cb65f1 100644
--- a/linux/drm_os_linux.h
+++ b/linux/drm_os_linux.h
@@ -1,36 +1,56 @@
+/**
+ * \file drm_os_linux.h
+ * OS abstraction macros.
+ */
+
 #define __NO_VERSION__
 
 #include <linux/interrupt.h>	/* For task queue support */
 #include <linux/delay.h>
 
+/** File pointer type */
 #define DRMFILE                         struct file *
+/** Ioctl arguments */
 #define DRM_IOCTL_ARGS			struct inode *inode, struct file *filp, unsigned int cmd, unsigned long data
 #define DRM_ERR(d)			-(d)
+/** Current process ID */
 #define DRM_CURRENTPID			current->pid
 #define DRM_UDELAY(d)			udelay(d)
+/** Read a byte from a MMIO region */
 #define DRM_READ8(map, offset)		readb(((unsigned long)(map)->handle) + (offset))
+/** Read a dword from a MMIO region */
 #define DRM_READ32(map, offset)		readl(((unsigned long)(map)->handle) + (offset))
+/** Write a byte into a MMIO region */
 #define DRM_WRITE8(map, offset, val)	writeb(val, ((unsigned long)(map)->handle) + (offset))
+/** Write a dword into a MMIO region */
 #define DRM_WRITE32(map, offset, val)	writel(val, ((unsigned long)(map)->handle) + (offset))
-#define DRM_READMEMORYBARRIER()		rmb()
-#define DRM_WRITEMEMORYBARRIER()	wmb()
-#define DRM_MEMORYBARRIER()		mb()
+/** Read memory barrier */
+#define DRM_READMEMORYBARRIER(map)	rmb()
+/** Write memory barrier */
+#define DRM_WRITEMEMORYBARRIER(map)	wmb()
+/** Read/write memory barrier */
+#define DRM_MEMORYBARRIER(map)	mb()
+/** DRM device local declaration */
 #define DRM_DEVICE	drm_file_t	*priv	= filp->private_data; \
 			drm_device_t	*dev	= priv->dev
-
+			
+/** IRQ handler arguments */
 #define DRM_IRQ_ARGS	        int irq, void *arg, struct pt_regs *regs
+/** Task queue handler arguments */
 #define DRM_TASKQUEUE_ARGS	void *arg
 
-/* For data going from/to the kernel through the ioctl argument */
+/** For data going into the kernel through the ioctl argument */
 #define DRM_COPY_FROM_USER_IOCTL(arg1, arg2, arg3)	\
 	if ( copy_from_user(&arg1, arg2, arg3) )	\
 		return -EFAULT
+/** For data going from the kernel through the ioctl argument */
 #define DRM_COPY_TO_USER_IOCTL(arg1, arg2, arg3)	\
 	if ( copy_to_user(arg1, &arg2, arg3) )		\
 		return -EFAULT
-/* Other copying of data from/to kernel space */
+/** Other copying of data to kernel space */
 #define DRM_COPY_FROM_USER(arg1, arg2, arg3)		\
 	copy_from_user(arg1, arg2, arg3)
+/** Other copying of data from kernel space */
 #define DRM_COPY_TO_USER(arg1, arg2, arg3)		\
 	copy_to_user(arg1, arg2, arg3)
 /* Macros for copyfrom user, but checking readability only once */
@@ -42,10 +62,16 @@
 	__get_user(val, uaddr)
 
 
-/* malloc/free without the overhead of DRM(alloc) */
+/** 'malloc' without the overhead of DRM(alloc)() */
 #define DRM_MALLOC(x) kmalloc(x, GFP_KERNEL)
+/** 'free' without the overhead of DRM(free)() */
 #define DRM_FREE(x,size) kfree(x)
 
+/** 
+ * Get the pointer to the SAREA.
+ *
+ * Searches the SAREA on the mapping lists and points drm_device::sarea to it.
+ */
 #define DRM_GETSAREA()							 \
 do { 									 \
 	drm_map_list_t *entry;						 \
diff --git a/linux/drm_proc.h b/linux/drm_proc.h
index f73b7ccd..e1313125 100644
--- a/linux/drm_proc.h
+++ b/linux/drm_proc.h
@@ -1,4 +1,16 @@
-/* drm_proc.h -- /proc support for DRM -*- linux-c -*-
+/**
+ * \file drm_proc.h 
+ * /proc support for DRM
+ *
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ *
+ * \par Acknowledgements:
+ *    Matthew J Sottek <matthew.j.sottek@intel.com> sent in a patch to fix
+ *    the problem with the proc files not outputting all their information.
+ */
+
+/*
  * Created: Mon Jan 11 09:48:47 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,14 +35,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>
- *
- * Acknowledgements:
- *    Matthew J Sottek <matthew.j.sottek@intel.com> sent in a patch to fix
- *    the problem with the proc files not outputting all their information.
  */
 
 #define __NO_VERSION__
@@ -51,9 +55,12 @@ static int	   DRM(vma_info)(char *buf, char **start, off_t offset,
 				 int request, int *eof, void *data);
 #endif
 
+/**
+ * Proc file list.
+ */
 struct drm_proc_list {
-	const char *name;
-	int	   (*f)(char *, char **, off_t, int, int *, void *);
+	const char *name;	/**< file name */
+	int	   (*f)(char *, char **, off_t, int, int *, void *);	/**< proc callback*/
 } DRM(proc_list)[] = {
 	{ "name",    DRM(name_info)    },
 	{ "mem",     DRM(mem_info)     },
@@ -67,6 +74,19 @@ struct drm_proc_list {
 };
 #define DRM_PROC_ENTRIES (sizeof(DRM(proc_list))/sizeof(DRM(proc_list)[0]))
 
+/**
+ * Initialize the DRI proc filesystem for a device.
+ *
+ * \param dev DRM device.
+ * \param minor device minor number.
+ * \param root DRI proc dir entry.
+ * \param dev_root resulting DRI device proc dir entry.
+ * \return root entry pointer on success, or NULL on failure.
+ * 
+ * Create the DRI proc root entry "/proc/dri", the device proc root entry
+ * "/proc/dri/%minor%/", and each entry in proc_list as
+ * "/proc/dri/%minor%/%name%".
+ */
 struct proc_dir_entry *DRM(proc_init)(drm_device_t *dev, int minor,
 				      struct proc_dir_entry *root,
 				      struct proc_dir_entry **dev_root)
@@ -84,7 +104,7 @@ struct proc_dir_entry *DRM(proc_init)(drm_device_t *dev, int minor,
 	sprintf(name, "%d", minor);
 	*dev_root = create_proc_entry(name, S_IFDIR, root);
 	if (!*dev_root) {
-		DRM_ERROR("Cannot create /proc/%s\n", name);
+		DRM_ERROR("Cannot create /proc/dri/%s\n", name);
 		return NULL;
 	}
 
@@ -109,6 +129,17 @@ struct proc_dir_entry *DRM(proc_init)(drm_device_t *dev, int minor,
 }
 
 
+/**
+ * Cleanup the proc filesystem resources.
+ *
+ * \param dev DRM device.
+ * \param minor device minor number.
+ * \param root DRI proc dir entry.
+ * \param dev_root DRI device proc dir entry.
+ * \return always zero.
+ *
+ * Remove all proc entries created by proc_init().
+ */
 int DRM(proc_cleanup)(int minor, struct proc_dir_entry *root,
 		      struct proc_dir_entry *dev_root)
 {
@@ -126,6 +157,19 @@ int DRM(proc_cleanup)(int minor, struct proc_dir_entry *root,
 	return 0;
 }
 
+/**
+ * Called when "/proc/dri/<dev>/name" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ * 
+ * Prints the device name together with the bus id if available.
+ */
 static int DRM(name_info)(char *buf, char **start, off_t offset, int request,
 			  int *eof, void *data)
 {
@@ -152,6 +196,19 @@ static int DRM(name_info)(char *buf, char **start, off_t offset, int request,
 	return len - offset;
 }
 
+/**
+ * Called when "/proc/dri/<dev>/vm" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ * 
+ * Prints information about all mappings in drm_device::maplist.
+ */
 static int DRM(_vm_info)(char *buf, char **start, off_t offset, int request,
 			 int *eof, void *data)
 {
@@ -205,6 +262,9 @@ static int DRM(_vm_info)(char *buf, char **start, off_t offset, int request,
 	return len - offset;
 }
 
+/**
+ * Simply calls _vm_info() while holding the drm_device::struct_sem lock.
+ */
 static int DRM(vm_info)(char *buf, char **start, off_t offset, int request,
 			int *eof, void *data)
 {
@@ -217,7 +277,17 @@ static int DRM(vm_info)(char *buf, char **start, off_t offset, int request,
 	return ret;
 }
 
-
+/**
+ * Called when "/proc/dri/<dev>/queues" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ */
 static int DRM(_queues_info)(char *buf, char **start, off_t offset,
 			     int request, int *eof, void *data)
 {
@@ -262,6 +332,9 @@ static int DRM(_queues_info)(char *buf, char **start, off_t offset,
 	return len - offset;
 }
 
+/**
+ * Simply calls _queues_info() while holding the drm_device::struct_sem lock.
+ */
 static int DRM(queues_info)(char *buf, char **start, off_t offset, int request,
 			    int *eof, void *data)
 {
@@ -274,9 +347,17 @@ static int DRM(queues_info)(char *buf, char **start, off_t offset, int request,
 	return ret;
 }
 
-/* drm_bufs_info is called whenever a process reads
-   /dev/dri/<dev>/bufs. */
-
+/**
+ * Called when "/proc/dri/<dev>/bufs" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ */
 static int DRM(_bufs_info)(char *buf, char **start, off_t offset, int request,
 			   int *eof, void *data)
 {
@@ -321,6 +402,9 @@ static int DRM(_bufs_info)(char *buf, char **start, off_t offset, int request,
 	return len - offset;
 }
 
+/**
+ * Simply calls _bufs_info() while holding the drm_device::struct_sem lock.
+ */
 static int DRM(bufs_info)(char *buf, char **start, off_t offset, int request,
 			  int *eof, void *data)
 {
@@ -333,7 +417,17 @@ static int DRM(bufs_info)(char *buf, char **start, off_t offset, int request,
 	return ret;
 }
 
-
+/**
+ * Called when "/proc/dri/<dev>/clients" is read.
+ * 
+ * \param buf output buffer.
+ * \param start start of output data.
+ * \param offset requested start offset.
+ * \param request requested number of bytes.
+ * \param eof whether there is no more data to return.
+ * \param data private data.
+ * \return number of written bytes.
+ */
 static int DRM(_clients_info)(char *buf, char **start, off_t offset,
 			      int request, int *eof, void *data)
 {
@@ -365,6 +459,9 @@ static int DRM(_clients_info)(char *buf, char **start, off_t offset,
 	return len - offset;
 }
 
+/**
+ * Simply calls _clients_info() while holding the drm_device::struct_sem lock.
+ */
 static int DRM(clients_info)(char *buf, char **start, off_t offset,
 			     int request, int *eof, void *data)
 {
diff --git a/linux/drm_scatter.h b/linux/drm_scatter.h
index 1aedb403..45a30fc3 100644
--- a/linux/drm_scatter.h
+++ b/linux/drm_scatter.h
@@ -1,4 +1,11 @@
-/* drm_scatter.h -- IOCTLs to manage scatter/gather memory -*- linux-c -*-
+/**
+ * \file drm_scatter.h 
+ * IOCTLs to manage scatter/gather memory
+ *
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Mon Dec 18 23:20:54 2000 by gareth@valinux.com
  *
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -22,9 +29,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:
- *   Gareth Hughes <gareth@valinux.com>
  */
 
 #define __NO_VERSION__
diff --git a/linux/drm_stub.h b/linux/drm_stub.h
index 3c9c69eb..c5fdf15a 100644
--- a/linux/drm_stub.h
+++ b/linux/drm_stub.h
@@ -1,4 +1,11 @@
-/* drm_stub.h -- -*- linux-c -*-
+/**
+ * \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.
@@ -22,10 +29,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>
- *
  */
 
 #define __NO_VERSION__
@@ -33,20 +36,31 @@
 
 #define DRM_STUB_MAXCARDS 16	/* Enough for one machine */
 
+/** Stub list. One for each minor. */
 static struct drm_stub_list {
 	const char             *name;
-	struct file_operations *fops;
-	struct proc_dir_entry  *dev_root;
+	struct file_operations *fops;	/**< file operations */
+	struct proc_dir_entry  *dev_root;	/**< proc directory entry */
 } *DRM(stub_list);
 
 static struct proc_dir_entry *DRM(stub_root);
 
+/** Stub information */
 static struct drm_stub_info {
 	int (*info_register)(const char *name, struct file_operations *fops,
 			     drm_device_t *dev);
 	int (*info_unregister)(int minor);
 } DRM(stub_info);
 
+/**
+ * File \c open operation.
+ *
+ * \param inode device inode.
+ * \param filp file pointer.
+ *
+ * Puts the drm_stub_list::fops corresponding to the device minor number into
+ * \p filp, call the \c open method, and restore the file operations.
+ */
 static int DRM(stub_open)(struct inode *inode, struct file *filp)
 {
 	int                    minor = minor(inode->i_rdev);
@@ -65,11 +79,24 @@ static int DRM(stub_open)(struct inode *inode, struct file *filp)
 	return err;
 }
 
+/** File operations structure */
 static struct file_operations DRM(stub_fops) = {
 	.owner = THIS_MODULE,
 	.open  = DRM(stub_open)
 };
 
+/**
+ * Get a device minor number.
+ *
+ * \param name driver name.
+ * \param fops file operations.
+ * \param dev DRM device.
+ * \return minor number on success, or a negative number on failure.
+ *
+ * Allocate and initialize ::stub_list if one doesn't exist already.  Search an
+ * empty entry and initialize it to the given parameters, and create the proc
+ * init entry via proc_init().
+ */
 static int DRM(stub_getminor)(const char *name, struct file_operations *fops,
 			      drm_device_t *dev)
 {
@@ -97,6 +124,16 @@ static int DRM(stub_getminor)(const char *name, struct file_operations *fops,
 	return -1;
 }
 
+/**
+ * Put a device minor number.
+ *
+ * \param minor minor number.
+ * \return always zero.
+ *
+ * Cleans up the proc resources. If a minor is zero then release the foreign
+ * "drm" data, otherwise unregisters the "drm" data, frees the stub list and
+ * unregisters the character device. 
+ */
 static int DRM(stub_putminor)(int minor)
 {
 	if (minor < 0 || minor >= DRM_STUB_MAXCARDS) return -1;
@@ -116,7 +153,20 @@ static int DRM(stub_putminor)(int minor)
 	return 0;
 }
 
-
+/**
+ * Register.
+ *
+ * \param name driver name.
+ * \param fops file operations
+ * \param dev DRM device.
+ * \return zero on success or a negative number on failure.
+ *
+ * Attempt to register the char device and get the foreign "drm" data. If
+ * successful then another module already registered so gets the stub info,
+ * otherwise use this module stub info and make it available for other modules.
+ *
+ * Finally calls stub_info::info_register.
+ */
 int DRM(stub_register)(const char *name, struct file_operations *fops,
 		       drm_device_t *dev)
 {
@@ -142,6 +192,13 @@ int DRM(stub_register)(const char *name, struct file_operations *fops,
 	return -1;
 }
 
+/**
+ * Unregister.
+ *
+ * \param minor
+ *
+ * Calls drm_stub_info::unregister.
+ */
 int DRM(stub_unregister)(int minor)
 {
 	DRM_DEBUG("%d\n", minor);
diff --git a/linux/drm_vm.h b/linux/drm_vm.h
index f9c1e356..c1dfb377 100644
--- a/linux/drm_vm.h
+++ b/linux/drm_vm.h
@@ -1,4 +1,12 @@
-/* drm_vm.h -- Memory mapping for DRM -*- linux-c -*-
+/**
+ * \file drm_vm.h
+ * Memory mapping for DRM
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Created: Mon Jan  4 08:58:31 1999 by faith@valinux.com
  *
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
@@ -23,39 +31,50 @@
  * 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__
 #include "drmP.h"
 
+/** AGP virtual memory operations */
 struct vm_operations_struct   DRM(vm_ops) = {
 	.nopage = DRM(vm_nopage),
 	.open	= DRM(vm_open),
 	.close	= DRM(vm_close),
 };
 
+/** Shared virtual memory operations */
 struct vm_operations_struct   DRM(vm_shm_ops) = {
 	.nopage = DRM(vm_shm_nopage),
 	.open	= DRM(vm_open),
 	.close	= DRM(vm_shm_close),
 };
 
+/** DMA virtual memory operations */
 struct vm_operations_struct   DRM(vm_dma_ops) = {
 	.nopage = DRM(vm_dma_nopage),
 	.open	= DRM(vm_open),
 	.close	= DRM(vm_close),
 };
 
+/** Scatter-gather virtual memory operations */
 struct vm_operations_struct   DRM(vm_sg_ops) = {
 	.nopage = DRM(vm_sg_nopage),
 	.open   = DRM(vm_open),
 	.close  = DRM(vm_close),
 };
 
+/**
+ * \c nopage method for AGP virtual memory.
+ *
+ * \param vma virtual memory area.
+ * \param address access address.
+ * \param write_access sharing.
+ * \return pointer to the page structure.
+ * 
+ * Find the right map and if it's AGP memory find the real physical page to
+ * map, get the page, increment the use count and return it.
+ */
 struct page *DRM(vm_nopage)(struct vm_area_struct *vma,
 			    unsigned long address,
 			    int write_access)
@@ -123,6 +142,17 @@ vm_nopage_error:
 	return NOPAGE_SIGBUS;		/* Disallow mremap */
 }
 
+/**
+ * \c nopage method for shared virtual memory.
+ *
+ * \param vma virtual memory area.
+ * \param address access address.
+ * \param write_access sharing.
+ * \return pointer to the page structure.
+ * 
+ * Get the the mapping, find the real physical page to map, get the page, and
+ * return it.
+ */
 struct page *DRM(vm_shm_nopage)(struct vm_area_struct *vma,
 				unsigned long address,
 				int write_access)
@@ -146,10 +176,15 @@ struct page *DRM(vm_shm_nopage)(struct vm_area_struct *vma,
 	return page;
 }
 
-/* Special close routine which deletes map information if we are the last
+
+/**
+ * \c close method for shared virtual memory.
+ * 
+ * \param vma virtual memory area.
+ * 
+ * Deletes map information if we are the last
  * person to close a mapping and it's not in the global maplist.
  */
-
 void DRM(vm_shm_close)(struct vm_area_struct *vma)
 {
 	drm_file_t	*priv	= vma->vm_file->private_data;
@@ -222,6 +257,16 @@ void DRM(vm_shm_close)(struct vm_area_struct *vma)
 	up(&dev->struct_sem);
 }
 
+/**
+ * \c nopage method for DMA virtual memory.
+ *
+ * \param vma virtual memory area.
+ * \param address access address.
+ * \param write_access sharing.
+ * \return pointer to the page structure.
+ * 
+ * Determine the page number from the page offset and get it from drm_device_dma::pagelist.
+ */
 struct page *DRM(vm_dma_nopage)(struct vm_area_struct *vma,
 				unsigned long address,
 				int write_access)
@@ -248,6 +293,16 @@ struct page *DRM(vm_dma_nopage)(struct vm_area_struct *vma,
 	return page;
 }
 
+/**
+ * \c nopage method for scatter-gather virtual memory.
+ *
+ * \param vma virtual memory area.
+ * \param address access address.
+ * \param write_access sharing.
+ * \return pointer to the page structure.
+ * 
+ * Determine the map offset from the page offset and get it from drm_sg_mem::pagelist.
+ */
 struct page *DRM(vm_sg_nopage)(struct vm_area_struct *vma,
 			       unsigned long address,
 			       int write_access)
@@ -275,6 +330,14 @@ struct page *DRM(vm_sg_nopage)(struct vm_area_struct *vma,
 	return page;
 }
 
+/**
+ * \c open method for shared virtual memory.
+ * 
+ * \param vma virtual memory area.
+ * 
+ * Create a new drm_vma_entry structure as the \p vma private data entry and
+ * add it to drm_device::vmalist.
+ */
 void DRM(vm_open)(struct vm_area_struct *vma)
 {
 	drm_file_t	*priv	= vma->vm_file->private_data;
@@ -296,6 +359,14 @@ void DRM(vm_open)(struct vm_area_struct *vma)
 	}
 }
 
+/**
+ * \c close method for all virtual memory types.
+ * 
+ * \param vma virtual memory area.
+ * 
+ * Search the \p vma private data entry in drm_device::vmalist, unlink it, and
+ * free it.
+ */
 void DRM(vm_close)(struct vm_area_struct *vma)
 {
 	drm_file_t	*priv	= vma->vm_file->private_data;
@@ -321,6 +392,16 @@ void DRM(vm_close)(struct vm_area_struct *vma)
 	up(&dev->struct_sem);
 }
 
+/**
+ * mmap DMA memory.
+ *
+ * \param filp file pointer.
+ * \param vma virtual memory area.
+ * \return zero on success or a negative number on failure.
+ * 
+ * Sets the virtual memory area operations structure to vm_dma_ops, the file
+ * pointer, and calls vm_open().
+ */
 int DRM(mmap_dma)(struct file *filp, struct vm_area_struct *vma)
 {
 	drm_file_t	 *priv	 = filp->private_data;
@@ -367,6 +448,19 @@ int DRM(mmap_dma)(struct file *filp, struct vm_area_struct *vma)
 #endif
 #endif
 
+/**
+ * mmap DMA memory.
+ *
+ * \param filp file pointer.
+ * \param vma virtual memory area.
+ * \return zero on success or a negative number on failure.
+ * 
+ * If the virtual memory area has no offset associated with it then it's a DMA
+ * area, so calls mmap_dma(). Otherwise searches the map in drm_device::maplist,
+ * checks that the restricted flag is not set, sets the virtual memory operations
+ * according to the mapping type and remaps the pages. Finally sets the file
+ * pointer and calls vm_open().
+ */
 int DRM(mmap)(struct file *filp, struct vm_area_struct *vma)
 {
 	drm_file_t	*priv	= filp->private_data;
diff --git a/linux/radeon_drv.c b/linux/radeon_drv.c
index df859360..6152b8a5 100644
--- a/linux/radeon_drv.c
+++ b/linux/radeon_drv.c
@@ -1,6 +1,11 @@
-/* radeon_drv.c -- ATI Radeon driver -*- linux-c -*-
- * Created: Wed Feb 14 17:10:04 2001 by gareth@valinux.com
+/**
+ * \file radeon_drv.c
+ * ATI Radeon driver
  *
+ * \author Gareth Hughes <gareth@valinux.com>
+ */
+
+/*
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
  *
@@ -22,11 +27,9 @@
  * 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>
  */
 
+
 #include <linux/config.h>
 #include "radeon.h"
 #include "drmP.h"
diff --git a/shared-core/drm.h b/shared-core/drm.h
index f987c422..008a300b 100644
--- a/shared-core/drm.h
+++ b/shared-core/drm.h
@@ -1,6 +1,14 @@
-/* drm.h -- Header for Direct Rendering Manager -*- linux-c -*-
- * Created: Mon Jan  4 10:05:05 1999 by faith@precisioninsight.com
+/**
+ * \file drm.h 
+ * Header for the Direct Rendering Manager
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
  *
+ * \par Acknowledgments:
+ * Dec 1999, Richard Henderson <rth@twiddle.net>, move to generic \c cmpxchg.
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All rights reserved.
@@ -23,15 +31,9 @@
  * 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>
- *
- * Acknowledgements:
- * Dec 1999, Richard Henderson <rth@twiddle.net>, move to generic cmpxchg.
- *
  */
 
+
 #ifndef _DRM_H_
 #define _DRM_H_
 
@@ -86,29 +88,33 @@
 #endif
 #define DRM_MAX_MINOR   15
 #endif
-#define DRM_NAME	"drm"	  /* Name in kernel, /dev, and /proc	    */
-#define DRM_MIN_ORDER	5	  /* At least 2^5 bytes = 32 bytes	    */
-#define DRM_MAX_ORDER	22	  /* Up to 2^22 bytes = 4MB		    */
-#define DRM_RAM_PERCENT 10	  /* How much system ram can we lock?	    */
+#define DRM_NAME	"drm"	  /**< Name in kernel, /dev, and /proc */
+#define DRM_MIN_ORDER	5	  /**< At least 2^5 bytes = 32 bytes */
+#define DRM_MAX_ORDER	22	  /**< Up to 2^22 bytes = 4MB */
+#define DRM_RAM_PERCENT 10	  /**< How much system ram can we lock? */
 
-#define _DRM_LOCK_HELD	0x80000000 /* Hardware lock is held		    */
-#define _DRM_LOCK_CONT	0x40000000 /* Hardware lock is contended	    */
+#define _DRM_LOCK_HELD	0x80000000 /**< Hardware lock is held */
+#define _DRM_LOCK_CONT	0x40000000 /**< Hardware lock is contended */
 #define _DRM_LOCK_IS_HELD(lock)	   ((lock) & _DRM_LOCK_HELD)
 #define _DRM_LOCK_IS_CONT(lock)	   ((lock) & _DRM_LOCK_CONT)
 #define _DRM_LOCKING_CONTEXT(lock) ((lock) & ~(_DRM_LOCK_HELD|_DRM_LOCK_CONT))
 
+
 typedef unsigned long drm_handle_t;
 typedef unsigned int  drm_context_t;
 typedef unsigned int  drm_drawable_t;
 typedef unsigned int  drm_magic_t;
 
-/* Warning: If you change this structure, make sure you change
- * XF86DRIClipRectRec in the server as well */
 
-/* KW: Actually it's illegal to change either for
+/**
+ * Cliprect.
+ * 
+ * \warning: If you change this structure, make sure you change
+ * XF86DRIClipRectRec in the server as well
+ *
+ * \note KW: Actually it's illegal to change either for
  * backwards-compatibility reasons.
  */
-
 typedef struct drm_clip_rect {
 	unsigned short	x1;
 	unsigned short	y1;
@@ -116,6 +122,10 @@ typedef struct drm_clip_rect {
 	unsigned short	y2;
 } drm_clip_rect_t;
 
+
+/**
+ * Texture region,
+ */
 typedef struct drm_tex_region {
 	unsigned char	next;
 	unsigned char	prev;
@@ -124,32 +134,52 @@ typedef struct drm_tex_region {
 	unsigned int	age;
 } drm_tex_region_t;
 
+
+/**
+ * DRM_IOCTL_VERSION ioctl argument type.
+ * 
+ * \sa drmGetVersion().
+ */
 typedef struct drm_version {
-	int    version_major;	  /* Major version			    */
-	int    version_minor;	  /* Minor version			    */
-	int    version_patchlevel;/* Patch level			    */
-	size_t name_len;	  /* Length of name buffer		    */
-	char   *name;		  /* Name of driver			    */
-	size_t date_len;	  /* Length of date buffer		    */
-	char   *date;		  /* User-space buffer to hold date	    */
-	size_t desc_len;	  /* Length of desc buffer		    */
-	char   *desc;		  /* User-space buffer to hold desc	    */
+	int    version_major;	  /**< Major version */
+	int    version_minor;	  /**< Minor version */
+	int    version_patchlevel;/**< Patch level */
+	size_t name_len;	  /**< Length of name buffer */
+	char   *name;		  /**< Name of driver */
+	size_t date_len;	  /**< Length of date buffer */
+	char   *date;		  /**< User-space buffer to hold date */
+	size_t desc_len;	  /**< Length of desc buffer */
+	char   *desc;		  /**< User-space buffer to hold desc */
 } drm_version_t;
 
+
+/**
+ * DRM_IOCTL_GET_UNIQUE ioctl argument type.
+ *
+ * \sa drmGetBusid() and drmSetBusId().
+ */
 typedef struct drm_unique {
-	size_t unique_len;	  /* Length of unique			    */
-	char   *unique;		  /* Unique name for driver instantiation   */
+	size_t unique_len;	  /**< Length of unique */
+	char   *unique;		  /**< Unique name for driver instantiation */
 } drm_unique_t;
 
+
 typedef struct drm_list {
-	int		 count;	  /* Length of user-space structures	    */
+	int		 count;	  /**< Length of user-space structures */
 	drm_version_t	 *version;
 } drm_list_t;
 
+
 typedef struct drm_block {
 	int		 unused;
 } drm_block_t;
 
+
+/**
+ * DRM_IOCTL_CONTROL ioctl argument type.
+ *
+ * \sa drmCtlInstHandler() and drmCtlUninstHandler().
+ */
 typedef struct drm_control {
 	enum {
 		DRM_ADD_COMMAND,
@@ -160,49 +190,70 @@ typedef struct drm_control {
 	int		 irq;
 } drm_control_t;
 
+
+/**
+ * Type of memory to map.
+ */
 typedef enum drm_map_type {
-	_DRM_FRAME_BUFFER   = 0,  /* WC (no caching), no core dump	    */
-	_DRM_REGISTERS	    = 1,  /* no caching, no core dump		    */
-	_DRM_SHM	    = 2,  /* shared, cached			    */
-	_DRM_AGP            = 3,  /* AGP/GART                               */
-	_DRM_SCATTER_GATHER = 4	  /* Scatter/gather memory for PCI DMA      */
+	_DRM_FRAME_BUFFER   = 0,  /**< WC (no caching), no core dump */
+	_DRM_REGISTERS	    = 1,  /**< no caching, no core dump */
+	_DRM_SHM	    = 2,  /**< shared, cached */
+	_DRM_AGP            = 3,  /**< AGP/GART */
+	_DRM_SCATTER_GATHER = 4	  /**< Scatter/gather memory for PCI DMA */
 } drm_map_type_t;
 
+
+/**
+ * Memory mapping flags.
+ */
 typedef enum drm_map_flags {
-	_DRM_RESTRICTED	     = 0x01, /* Cannot be mapped to user-virtual    */
+	_DRM_RESTRICTED	     = 0x01, /**< Cannot be mapped to user-virtual */
 	_DRM_READ_ONLY	     = 0x02,
-	_DRM_LOCKED	     = 0x04, /* shared, cached, locked		    */
-	_DRM_KERNEL	     = 0x08, /* kernel requires access		    */
-	_DRM_WRITE_COMBINING = 0x10, /* use write-combining if available    */
-	_DRM_CONTAINS_LOCK   = 0x20, /* SHM page that contains lock	    */
-	_DRM_REMOVABLE	     = 0x40  /* Removable mapping		    */
+	_DRM_LOCKED	     = 0x04, /**< shared, cached, locked */
+	_DRM_KERNEL	     = 0x08, /**< kernel requires access */
+	_DRM_WRITE_COMBINING = 0x10, /**< use write-combining if available */
+	_DRM_CONTAINS_LOCK   = 0x20, /**< SHM page that contains lock */
+	_DRM_REMOVABLE	     = 0x40  /**< Removable mapping */
 } drm_map_flags_t;
 
+
 typedef struct drm_ctx_priv_map {
-	unsigned int	ctx_id;  /* Context requesting private mapping */
-	void		*handle; /* Handle of map */
+	unsigned int	ctx_id;  /**< Context requesting private mapping */
+	void		*handle; /**< Handle of map */
 } drm_ctx_priv_map_t;
 
+
+/**
+ * DRM_IOCTL_GET_MAP, DRM_IOCTL_ADD_MAP and DRM_IOCTL_RM_MAP ioctls
+ * argument type.
+ *
+ * \sa drmAddMap().
+ */
 typedef struct drm_map {
-	unsigned long	offset;	 /* Requested physical address (0 for SAREA)*/
-	unsigned long	size;	 /* Requested physical size (bytes)	    */
-	drm_map_type_t	type;	 /* Type of memory to map		    */
-	drm_map_flags_t flags;	 /* Flags				    */
-	void		*handle; /* User-space: "Handle" to pass to mmap    */
-				 /* Kernel-space: kernel-virtual address    */
-	int		mtrr;	 /* MTRR slot used			    */
-				 /* Private data			    */
+	unsigned long	offset;	 /**< Requested physical address (0 for SAREA)*/
+	unsigned long	size;	 /**< Requested physical size (bytes) */
+	drm_map_type_t	type;	 /**< Type of memory to map */
+	drm_map_flags_t flags;	 /**< Flags */
+	void		*handle; /**< User-space: "Handle" to pass to mmap() */
+				 /**< Kernel-space: kernel-virtual address */
+	int		mtrr;	 /**< MTRR slot used */
+				 /*   Private data */
 } drm_map_t;
 
+
+/**
+ * DRM_IOCTL_GET_CLIENT ioctl argument type.
+ */
 typedef struct drm_client {
-	int		idx;	/* Which client desired?                    */
-	int		auth;	/* Is client authenticated?                 */
-	unsigned long	pid;	/* Process id                               */
-	unsigned long	uid;	/* User id                                  */
-	unsigned long	magic;	/* Magic                                    */
-	unsigned long	iocs;	/* Ioctl count                              */
+	int		idx;	/**< Which client desired? */
+	int		auth;	/**< Is client authenticated? */
+	unsigned long	pid;	/**< Process ID */
+	unsigned long	uid;	/**< User ID */
+	unsigned long	magic;	/**< Magic */
+	unsigned long	iocs;	/**< Ioctl count */
 } drm_client_t;
 
+
 typedef enum {
 	_DRM_STAT_LOCK,
 	_DRM_STAT_OPENS,
@@ -210,20 +261,24 @@ typedef enum {
 	_DRM_STAT_IOCTLS,
 	_DRM_STAT_LOCKS,
 	_DRM_STAT_UNLOCKS,
-	_DRM_STAT_VALUE,	/* Generic value                      */
-	_DRM_STAT_BYTE,		/* Generic byte counter (1024bytes/K) */
-	_DRM_STAT_COUNT,	/* Generic non-byte counter (1000/k)  */
+	_DRM_STAT_VALUE,	/**< Generic value */
+	_DRM_STAT_BYTE,		/**< Generic byte counter (1024bytes/K) */
+	_DRM_STAT_COUNT,	/**< Generic non-byte counter (1000/k) */
 
-	_DRM_STAT_IRQ,		/* IRQ */
-	_DRM_STAT_PRIMARY,	/* Primary DMA bytes */
-	_DRM_STAT_SECONDARY,	/* Secondary DMA bytes */
-	_DRM_STAT_DMA,		/* DMA */
-	_DRM_STAT_SPECIAL,	/* Special DMA (e.g., priority or polled) */
-	_DRM_STAT_MISSED	/* Missed DMA opportunity */
+	_DRM_STAT_IRQ,		/**< IRQ */
+	_DRM_STAT_PRIMARY,	/**< Primary DMA bytes */
+	_DRM_STAT_SECONDARY,	/**< Secondary DMA bytes */
+	_DRM_STAT_DMA,		/**< DMA */
+	_DRM_STAT_SPECIAL,	/**< Special DMA (e.g., priority or polled) */
+	_DRM_STAT_MISSED	/**< Missed DMA opportunity */
 
 				/* Add to the *END* of the list */
 } drm_stat_type_t;
 
+
+/**
+ * DRM_IOCTL_GET_STATS ioctl argument type.
+ */
 typedef struct drm_stats {
 	unsigned long count;
 	struct {
@@ -232,137 +287,220 @@ typedef struct drm_stats {
 	} data[15];
 } drm_stats_t;
 
+
+/**
+ * Hardware locking flags.
+ */
 typedef enum drm_lock_flags {
-	_DRM_LOCK_READY	     = 0x01, /* Wait until hardware is ready for DMA */
-	_DRM_LOCK_QUIESCENT  = 0x02, /* Wait until hardware quiescent	     */
-	_DRM_LOCK_FLUSH	     = 0x04, /* Flush this context's DMA queue first */
-	_DRM_LOCK_FLUSH_ALL  = 0x08, /* Flush all DMA queues first	     */
+	_DRM_LOCK_READY	     = 0x01, /**< Wait until hardware is ready for DMA */
+	_DRM_LOCK_QUIESCENT  = 0x02, /**< Wait until hardware quiescent */
+	_DRM_LOCK_FLUSH	     = 0x04, /**< Flush this context's DMA queue first */
+	_DRM_LOCK_FLUSH_ALL  = 0x08, /**< Flush all DMA queues first */
 				/* These *HALT* flags aren't supported yet
 				   -- they will be used to support the
 				   full-screen DGA-like mode. */
-	_DRM_HALT_ALL_QUEUES = 0x10, /* Halt all current and future queues   */
-	_DRM_HALT_CUR_QUEUES = 0x20  /* Halt all current queues		     */
+	_DRM_HALT_ALL_QUEUES = 0x10, /**< Halt all current and future queues */
+	_DRM_HALT_CUR_QUEUES = 0x20  /**< Halt all current queues */
 } drm_lock_flags_t;
 
+
+/**
+ * DRM_IOCTL_LOCK, DRM_IOCTL_UNLOCK and DRM_IOCTL_FINISH ioctl argument type.
+ * 
+ * \sa drmGetLock() and drmUnlock().
+ */
 typedef struct drm_lock {
 	int		 context;
 	drm_lock_flags_t flags;
 } drm_lock_t;
 
-typedef enum drm_dma_flags {	      /* These values *MUST* match xf86drm.h */
-				      /* Flags for DMA buffer dispatch	     */
-	_DRM_DMA_BLOCK	      = 0x01, /* Block until buffer dispatched.
-					 Note, the buffer may not yet have
-					 been processed by the hardware --
-					 getting a hardware lock with the
-					 hardware quiescent will ensure
-					 that the buffer has been
-					 processed.			     */
-	_DRM_DMA_WHILE_LOCKED = 0x02, /* Dispatch while lock held	     */
-	_DRM_DMA_PRIORITY     = 0x04, /* High priority dispatch		     */
-
-				      /* Flags for DMA buffer request	     */
-	_DRM_DMA_WAIT	      = 0x10, /* Wait for free buffers		     */
-	_DRM_DMA_SMALLER_OK   = 0x20, /* Smaller-than-requested buffers ok   */
-	_DRM_DMA_LARGER_OK    = 0x40  /* Larger-than-requested buffers ok    */
+
+/**
+ * DMA flags
+ *
+ * \warning 
+ * These values \e must match xf86drm.h.
+ *
+ * \sa drm_dma.
+ */
+typedef enum drm_dma_flags {	      
+				      /* Flags for DMA buffer dispatch */
+	_DRM_DMA_BLOCK	      = 0x01, /**<
+				       * Block until buffer dispatched.
+				       * 
+				       * \note The buffer may not yet have
+				       * been processed by the hardware --
+				       * getting a hardware lock with the
+				       * hardware quiescent will ensure
+				       * that the buffer has been
+				       * processed.
+				       */
+	_DRM_DMA_WHILE_LOCKED = 0x02, /**< Dispatch while lock held */
+	_DRM_DMA_PRIORITY     = 0x04, /**< High priority dispatch */
+
+				      /* Flags for DMA buffer request */
+	_DRM_DMA_WAIT	      = 0x10, /**< Wait for free buffers */
+	_DRM_DMA_SMALLER_OK   = 0x20, /**< Smaller-than-requested buffers OK */
+	_DRM_DMA_LARGER_OK    = 0x40  /**< Larger-than-requested buffers OK */
 } drm_dma_flags_t;
 
+
+/**
+ * DRM_IOCTL_ADD_BUFS and DRM_IOCTL_MARK_BUFS ioctl argument type.
+ *
+ * \sa drmAddBufs().
+ */
 typedef struct drm_buf_desc {
-	int	      count;	 /* Number of buffers of this size	     */
-	int	      size;	 /* Size in bytes			     */
-	int	      low_mark;	 /* Low water mark			     */
-	int	      high_mark; /* High water mark			     */
+	int	      count;	 /**< Number of buffers of this size */
+	int	      size;	 /**< Size in bytes */
+	int	      low_mark;	 /**< Low water mark */
+	int	      high_mark; /**< High water mark */
 	enum {
-		_DRM_PAGE_ALIGN = 0x01, /* Align on page boundaries for DMA  */
-		_DRM_AGP_BUFFER = 0x02, /* Buffer is in agp space            */
-		_DRM_SG_BUFFER  = 0x04  /* Scatter/gather memory buffer      */
+		_DRM_PAGE_ALIGN = 0x01, /**< Align on page boundaries for DMA */
+		_DRM_AGP_BUFFER = 0x02, /**< Buffer is in AGP space */
+		_DRM_SG_BUFFER  = 0x04  /**< Scatter/gather memory buffer */
 	}	      flags;
-	unsigned long agp_start; /* Start address of where the agp buffers
-				  * are in the agp aperture */
+	unsigned long agp_start; /**< 
+				  * Start address of where the AGP buffers are
+				  * in the AGP aperture
+				  */
 } drm_buf_desc_t;
 
+
+/**
+ * DRM_IOCTL_INFO_BUFS ioctl argument type.
+ */
 typedef struct drm_buf_info {
-	int	       count;	/* Entries in list			     */
+	int	       count;	/**< Entries in list */
 	drm_buf_desc_t *list;
 } drm_buf_info_t;
 
+
+/**
+ * DRM_IOCTL_FREE_BUFS ioctl argument type.
+ */
 typedef struct drm_buf_free {
 	int	       count;
 	int	       *list;
 } drm_buf_free_t;
 
+
+/**
+ * Buffer information
+ *
+ * \sa drm_buf_map.
+ */
 typedef struct drm_buf_pub {
-	int		  idx;	       /* Index into master buflist	     */
-	int		  total;       /* Buffer size			     */
-	int		  used;	       /* Amount of buffer in use (for DMA)  */
-	void		  *address;    /* Address of buffer		     */
+	int		  idx;	       /**< Index into the master buffer list */
+	int		  total;       /**< Buffer size */
+	int		  used;	       /**< Amount of buffer in use (for DMA) */
+	void		  *address;    /**< Address of buffer */
 } drm_buf_pub_t;
 
+
+/**
+ * DRM_IOCTL_MAP_BUFS ioctl argument type.
+ */
 typedef struct drm_buf_map {
-	int	      count;	/* Length of buflist			    */
-	void	      *virtual;	/* Mmaped area in user-virtual		    */
-	drm_buf_pub_t *list;	/* Buffer information			    */
+	int	      count;	/**< Length of the buffer list */
+	void	      *virtual;	/**< Mmap'd area in user-virtual */
+	drm_buf_pub_t *list;	/**< Buffer information */
 } drm_buf_map_t;
 
+
+/**
+ * DRM_IOCTL_DMA ioctl argument type.
+ *
+ * Indices here refer to the offset into the buffer list in drm_buf_get.
+ *
+ * \sa drmDMA().
+ */
 typedef struct drm_dma {
-				/* Indices here refer to the offset into
-				   buflist in drm_buf_get_t.  */
-	int		context;	  /* Context handle		    */
-	int		send_count;	  /* Number of buffers to send	    */
-	int		*send_indices;	  /* List of handles to buffers	    */
-	int		*send_sizes;	  /* Lengths of data to send	    */
-	drm_dma_flags_t flags;		  /* Flags			    */
-	int		request_count;	  /* Number of buffers requested    */
-	int		request_size;	  /* Desired size for buffers	    */
-	int		*request_indices; /* Buffer information		    */
+	int		context;	  /**< Context handle */
+	int		send_count;	  /**< Number of buffers to send */
+	int		*send_indices;	  /**< List of handles to buffers */
+	int		*send_sizes;	  /**< Lengths of data to send */
+	drm_dma_flags_t flags;		  /**< Flags */
+	int		request_count;	  /**< Number of buffers requested */
+	int		request_size;	  /**< Desired size for buffers */
+	int		*request_indices; /**< Buffer information */
 	int		*request_sizes;
-	int		granted_count;	  /* Number of buffers granted	    */
+	int		granted_count;	  /**< Number of buffers granted */
 } drm_dma_t;
 
+
 typedef enum {
 	_DRM_CONTEXT_PRESERVED = 0x01,
 	_DRM_CONTEXT_2DONLY    = 0x02
 } drm_ctx_flags_t;
 
+
+/**
+ * DRM_IOCTL_ADD_CTX ioctl argument type.
+ *
+ * \sa drmCreateContext() and drmDestroyContext().
+ */
 typedef struct drm_ctx {
 	drm_context_t	handle;
 	drm_ctx_flags_t flags;
 } drm_ctx_t;
 
+
+/**
+ * DRM_IOCTL_RES_CTX ioctl argument type.
+ */
 typedef struct drm_ctx_res {
 	int		count;
 	drm_ctx_t	*contexts;
 } drm_ctx_res_t;
 
+
+/**
+ * DRM_IOCTL_ADD_DRAW and DRM_IOCTL_RM_DRAW ioctl argument type.
+ */
 typedef struct drm_draw {
 	drm_drawable_t	handle;
 } drm_draw_t;
 
+
+/**
+ * DRM_IOCTL_GET_MAGIC and DRM_IOCTL_AUTH_MAGIC ioctl argument type.
+ */
 typedef struct drm_auth {
 	drm_magic_t	magic;
 } drm_auth_t;
 
+
+/**
+ * DRM_IOCTL_IRQ_BUSID ioctl argument type.
+ *
+ * \sa drmGetInterruptFromBusID().
+ */
 typedef struct drm_irq_busid {
-	int irq;
-	int busnum;
-	int devnum;
-	int funcnum;
+	int irq;	/**< IRQ number */
+	int busnum;	/**< bus number */
+	int devnum;	/**< device number */
+	int funcnum;	/**< function number */
 } drm_irq_busid_t;
 
+
 typedef enum {
-    _DRM_VBLANK_ABSOLUTE = 0x0,		/* Wait for specific vblank sequence number */
-    _DRM_VBLANK_RELATIVE = 0x1,		/* Wait for given number of vblanks */
-    _DRM_VBLANK_SIGNAL   = 0x40000000	/* Send signal instead of blocking */
+    _DRM_VBLANK_ABSOLUTE = 0x0,		/**< Wait for specific vblank sequence number */
+    _DRM_VBLANK_RELATIVE = 0x1,		/**< Wait for given number of vblanks */
+    _DRM_VBLANK_SIGNAL   = 0x80000000	/**< Send signal instead of blocking */
 } drm_vblank_seq_type_t;
 
+
 #define _DRM_VBLANK_FLAGS_MASK _DRM_VBLANK_SIGNAL
 
+
 struct drm_wait_vblank_request {
 	drm_vblank_seq_type_t type;
 	unsigned int sequence;
 	unsigned long signal;
 };
 
+
 struct drm_wait_vblank_reply {
 	drm_vblank_seq_type_t type;
 	unsigned int sequence;
@@ -370,29 +508,59 @@ struct drm_wait_vblank_reply {
 	long tval_usec;
 };
 
+
+/**
+ * DRM_IOCTL_WAIT_VBLANK ioctl argument type.
+ *
+ * \sa drmWaitVBlank().
+ */
 typedef union drm_wait_vblank {
 	struct drm_wait_vblank_request request;
 	struct drm_wait_vblank_reply reply;
 } drm_wait_vblank_t;
 
+
+/**
+ * DRM_IOCTL_AGP_ENABLE ioctl argument type.
+ *
+ * \sa drmAgpEnable().
+ */
 typedef struct drm_agp_mode {
-	unsigned long mode;
+	unsigned long mode;	/**< AGP mode */
 } drm_agp_mode_t;
 
-				/* For drm_agp_alloc -- allocated a buffer */
+
+/**
+ * DRM_IOCTL_AGP_ALLOC and DRM_IOCTL_AGP_FREE ioctls argument type.
+ *
+ * \sa drmAgpAlloc() and drmAgpFree().
+ */
 typedef struct drm_agp_buffer {
-	unsigned long size;	/* In bytes -- will round to page boundary */
-	unsigned long handle;	/* Used for BIND/UNBIND ioctls */
-	unsigned long type;     /* Type of memory to allocate  */
-        unsigned long physical; /* Physical used by i810       */
+	unsigned long size;	/**< In bytes -- will round to page boundary */
+	unsigned long handle;	/**< Used for binding / unbinding */
+	unsigned long type;     /**< Type of memory to allocate */
+        unsigned long physical; /**< Physical used by i810 */
 } drm_agp_buffer_t;
 
-				/* For drm_agp_bind */
+
+/**
+ * DRM_IOCTL_AGP_BIND and DRM_IOCTL_AGP_UNBIND ioctls argument type.
+ *
+ * \sa drmAgpBind() and drmAgpUnbind().
+ */
 typedef struct drm_agp_binding {
-	unsigned long handle;   /* From drm_agp_buffer */
-	unsigned long offset;	/* In bytes -- will round to page boundary */
+	unsigned long handle;   /**< From drm_agp_buffer */
+	unsigned long offset;	/**< In bytes -- will round to page boundary */
 } drm_agp_binding_t;
 
+
+/**
+ * DRM_IOCTL_AGP_INFO ioctl argument type.
+ *
+ * \sa drmAgpVersionMajor(), drmAgpVersionMinor(), drmAgpGetMode(),
+ * drmAgpBase(), drmAgpSize(), drmAgpMemoryUsed(), drmAgpMemoryAvail(),
+ * drmAgpVendorId() and drmAgpDeviceId().
+ */
 typedef struct drm_agp_info {
 	int            agp_version_major;
 	int            agp_version_minor;
@@ -407,11 +575,16 @@ typedef struct drm_agp_info {
 	unsigned short id_device;
 } drm_agp_info_t;
 
+
+/**
+ * DRM_IOCTL_SG_ALLOC ioctl argument type.
+ */
 typedef struct drm_scatter_gather {
-	unsigned long size;	/* In bytes -- will round to page boundary */
-	unsigned long handle;	/* Used for mapping / unmapping */
+	unsigned long size;	/**< In bytes -- will round to page boundary */
+	unsigned long handle;	/**< Used for mapping / unmapping */
 } drm_scatter_gather_t;
 
+
 #define DRM_IOCTL_BASE			'd'
 #define DRM_IO(nr)			_IO(DRM_IOCTL_BASE,nr)
 #define DRM_IOR(nr,type)		_IOR(DRM_IOCTL_BASE,nr,type)
@@ -471,8 +644,13 @@ typedef struct drm_scatter_gather {
 
 #define DRM_IOCTL_WAIT_VBLANK		DRM_IOWR(0x3a, drm_wait_vblank_t)
 
-/* Device specfic ioctls should only be in their respective headers
- * The device specific ioctl range is 0x40 to 0x79.                  */
+/**
+ * Device specific ioctls should only be in their respective headers
+ * The device specific ioctl range is from 0x40 to 0x79.
+ *
+ * \sa drmCommandNone(), drmCommandRead(), drmCommandWrite(), and
+ * drmCommandReadWrite().
+ */
 #define DRM_COMMAND_BASE                0x40
 
 #endif
diff --git a/shared-core/drm_sarea.h b/shared-core/drm_sarea.h
index cee48eee..dd3f617a 100644
--- a/shared-core/drm_sarea.h
+++ b/shared-core/drm_sarea.h
@@ -1,5 +1,11 @@
-/* sarea.h -- SAREA definitions -*- linux-c -*-
+/**
+ * \file drm_sarea.h 
+ * \brief SAREA definitions
  *
+ * \author Michel Dänzer <michel@daenzer.net>
+ */
+
+/*
  * Copyright 2002 Tungsten Graphics, Inc., Cedar Park, Texas.
  * All Rights Reserved.
  *
@@ -21,22 +27,22 @@
  * 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:
- *    Michel Dänzer <michel@daenzer.net>
  */
 
 #ifndef _DRM_SAREA_H_
 #define _DRM_SAREA_H_
 
+/** Maximum number of drawables in the SAREA */
 #define SAREA_MAX_DRAWABLES 		256
 
-typedef struct _drm_sarea_drawable_t {
+/** SAREA drawable */
+typedef struct drm_sarea_drawable {
     unsigned int	stamp;
     unsigned int	flags;
 } drm_sarea_drawable_t;
 
-typedef struct _dri_sarea_frame_t {
+/** SAREA frame */
+typedef struct drm_sarea_frame {
     unsigned int        x;
     unsigned int        y;
     unsigned int        width;
@@ -44,13 +50,14 @@ typedef struct _dri_sarea_frame_t {
     unsigned int        fullscreen;
 } drm_sarea_frame_t;
 
-typedef struct _drm_sarea_t {
-    /* first thing is always the drm locking structure */
+/** SAREA */
+typedef struct drm_sarea {
+    /** first thing is always the DRM locking structure */
     drm_hw_lock_t		lock;
-		/* NOT_DONE: Use readers/writer lock for drawable_lock */
+    /** \todo Use readers/writer lock for drm_sarea::drawable_lock */
     drm_hw_lock_t		drawable_lock;
-    drm_sarea_drawable_t	drawableTable[SAREA_MAX_DRAWABLES];
-    drm_sarea_frame_t		frame;
+    drm_sarea_drawable_t	drawableTable[SAREA_MAX_DRAWABLES];	/**< drawables */
+    drm_sarea_frame_t		frame;	/**< frame */
     drm_context_t		dummy_context;
 } drm_sarea_t;
 
diff --git a/shared/drm.h b/shared/drm.h
index f987c422..008a300b 100644
--- a/shared/drm.h
+++ b/shared/drm.h
@@ -1,6 +1,14 @@
-/* drm.h -- Header for Direct Rendering Manager -*- linux-c -*-
- * Created: Mon Jan  4 10:05:05 1999 by faith@precisioninsight.com
+/**
+ * \file drm.h 
+ * Header for the Direct Rendering Manager
+ * 
+ * \author Rickard E. (Rik) Faith <faith@valinux.com>
  *
+ * \par Acknowledgments:
+ * Dec 1999, Richard Henderson <rth@twiddle.net>, move to generic \c cmpxchg.
+ */
+
+/*
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All rights reserved.
@@ -23,15 +31,9 @@
  * 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>
- *
- * Acknowledgements:
- * Dec 1999, Richard Henderson <rth@twiddle.net>, move to generic cmpxchg.
- *
  */
 
+
 #ifndef _DRM_H_
 #define _DRM_H_
 
@@ -86,29 +88,33 @@
 #endif
 #define DRM_MAX_MINOR   15
 #endif
-#define DRM_NAME	"drm"	  /* Name in kernel, /dev, and /proc	    */
-#define DRM_MIN_ORDER	5	  /* At least 2^5 bytes = 32 bytes	    */
-#define DRM_MAX_ORDER	22	  /* Up to 2^22 bytes = 4MB		    */
-#define DRM_RAM_PERCENT 10	  /* How much system ram can we lock?	    */
+#define DRM_NAME	"drm"	  /**< Name in kernel, /dev, and /proc */
+#define DRM_MIN_ORDER	5	  /**< At least 2^5 bytes = 32 bytes */
+#define DRM_MAX_ORDER	22	  /**< Up to 2^22 bytes = 4MB */
+#define DRM_RAM_PERCENT 10	  /**< How much system ram can we lock? */
 
-#define _DRM_LOCK_HELD	0x80000000 /* Hardware lock is held		    */
-#define _DRM_LOCK_CONT	0x40000000 /* Hardware lock is contended	    */
+#define _DRM_LOCK_HELD	0x80000000 /**< Hardware lock is held */
+#define _DRM_LOCK_CONT	0x40000000 /**< Hardware lock is contended */
 #define _DRM_LOCK_IS_HELD(lock)	   ((lock) & _DRM_LOCK_HELD)
 #define _DRM_LOCK_IS_CONT(lock)	   ((lock) & _DRM_LOCK_CONT)
 #define _DRM_LOCKING_CONTEXT(lock) ((lock) & ~(_DRM_LOCK_HELD|_DRM_LOCK_CONT))
 
+
 typedef unsigned long drm_handle_t;
 typedef unsigned int  drm_context_t;
 typedef unsigned int  drm_drawable_t;
 typedef unsigned int  drm_magic_t;
 
-/* Warning: If you change this structure, make sure you change
- * XF86DRIClipRectRec in the server as well */
 
-/* KW: Actually it's illegal to change either for
+/**
+ * Cliprect.
+ * 
+ * \warning: If you change this structure, make sure you change
+ * XF86DRIClipRectRec in the server as well
+ *
+ * \note KW: Actually it's illegal to change either for
  * backwards-compatibility reasons.
  */
-
 typedef struct drm_clip_rect {
 	unsigned short	x1;
 	unsigned short	y1;
@@ -116,6 +122,10 @@ typedef struct drm_clip_rect {
 	unsigned short	y2;
 } drm_clip_rect_t;
 
+
+/**
+ * Texture region,
+ */
 typedef struct drm_tex_region {
 	unsigned char	next;
 	unsigned char	prev;
@@ -124,32 +134,52 @@ typedef struct drm_tex_region {
 	unsigned int	age;
 } drm_tex_region_t;
 
+
+/**
+ * DRM_IOCTL_VERSION ioctl argument type.
+ * 
+ * \sa drmGetVersion().
+ */
 typedef struct drm_version {
-	int    version_major;	  /* Major version			    */
-	int    version_minor;	  /* Minor version			    */
-	int    version_patchlevel;/* Patch level			    */
-	size_t name_len;	  /* Length of name buffer		    */
-	char   *name;		  /* Name of driver			    */
-	size_t date_len;	  /* Length of date buffer		    */
-	char   *date;		  /* User-space buffer to hold date	    */
-	size_t desc_len;	  /* Length of desc buffer		    */
-	char   *desc;		  /* User-space buffer to hold desc	    */
+	int    version_major;	  /**< Major version */
+	int    version_minor;	  /**< Minor version */
+	int    version_patchlevel;/**< Patch level */
+	size_t name_len;	  /**< Length of name buffer */
+	char   *name;		  /**< Name of driver */
+	size_t date_len;	  /**< Length of date buffer */
+	char   *date;		  /**< User-space buffer to hold date */
+	size_t desc_len;	  /**< Length of desc buffer */
+	char   *desc;		  /**< User-space buffer to hold desc */
 } drm_version_t;
 
+
+/**
+ * DRM_IOCTL_GET_UNIQUE ioctl argument type.
+ *
+ * \sa drmGetBusid() and drmSetBusId().
+ */
 typedef struct drm_unique {
-	size_t unique_len;	  /* Length of unique			    */
-	char   *unique;		  /* Unique name for driver instantiation   */
+	size_t unique_len;	  /**< Length of unique */
+	char   *unique;		  /**< Unique name for driver instantiation */
 } drm_unique_t;
 
+
 typedef struct drm_list {
-	int		 count;	  /* Length of user-space structures	    */
+	int		 count;	  /**< Length of user-space structures */
 	drm_version_t	 *version;
 } drm_list_t;
 
+
 typedef struct drm_block {
 	int		 unused;
 } drm_block_t;
 
+
+/**
+ * DRM_IOCTL_CONTROL ioctl argument type.
+ *
+ * \sa drmCtlInstHandler() and drmCtlUninstHandler().
+ */
 typedef struct drm_control {
 	enum {
 		DRM_ADD_COMMAND,
@@ -160,49 +190,70 @@ typedef struct drm_control {
 	int		 irq;
 } drm_control_t;
 
+
+/**
+ * Type of memory to map.
+ */
 typedef enum drm_map_type {
-	_DRM_FRAME_BUFFER   = 0,  /* WC (no caching), no core dump	    */
-	_DRM_REGISTERS	    = 1,  /* no caching, no core dump		    */
-	_DRM_SHM	    = 2,  /* shared, cached			    */
-	_DRM_AGP            = 3,  /* AGP/GART                               */
-	_DRM_SCATTER_GATHER = 4	  /* Scatter/gather memory for PCI DMA      */
+	_DRM_FRAME_BUFFER   = 0,  /**< WC (no caching), no core dump */
+	_DRM_REGISTERS	    = 1,  /**< no caching, no core dump */
+	_DRM_SHM	    = 2,  /**< shared, cached */
+	_DRM_AGP            = 3,  /**< AGP/GART */
+	_DRM_SCATTER_GATHER = 4	  /**< Scatter/gather memory for PCI DMA */
 } drm_map_type_t;
 
+
+/**
+ * Memory mapping flags.
+ */
 typedef enum drm_map_flags {
-	_DRM_RESTRICTED	     = 0x01, /* Cannot be mapped to user-virtual    */
+	_DRM_RESTRICTED	     = 0x01, /**< Cannot be mapped to user-virtual */
 	_DRM_READ_ONLY	     = 0x02,
-	_DRM_LOCKED	     = 0x04, /* shared, cached, locked		    */
-	_DRM_KERNEL	     = 0x08, /* kernel requires access		    */
-	_DRM_WRITE_COMBINING = 0x10, /* use write-combining if available    */
-	_DRM_CONTAINS_LOCK   = 0x20, /* SHM page that contains lock	    */
-	_DRM_REMOVABLE	     = 0x40  /* Removable mapping		    */
+	_DRM_LOCKED	     = 0x04, /**< shared, cached, locked */
+	_DRM_KERNEL	     = 0x08, /**< kernel requires access */
+	_DRM_WRITE_COMBINING = 0x10, /**< use write-combining if available */
+	_DRM_CONTAINS_LOCK   = 0x20, /**< SHM page that contains lock */
+	_DRM_REMOVABLE	     = 0x40  /**< Removable mapping */
 } drm_map_flags_t;
 
+
 typedef struct drm_ctx_priv_map {
-	unsigned int	ctx_id;  /* Context requesting private mapping */
-	void		*handle; /* Handle of map */
+	unsigned int	ctx_id;  /**< Context requesting private mapping */
+	void		*handle; /**< Handle of map */
 } drm_ctx_priv_map_t;
 
+
+/**
+ * DRM_IOCTL_GET_MAP, DRM_IOCTL_ADD_MAP and DRM_IOCTL_RM_MAP ioctls
+ * argument type.
+ *
+ * \sa drmAddMap().
+ */
 typedef struct drm_map {
-	unsigned long	offset;	 /* Requested physical address (0 for SAREA)*/
-	unsigned long	size;	 /* Requested physical size (bytes)	    */
-	drm_map_type_t	type;	 /* Type of memory to map		    */
-	drm_map_flags_t flags;	 /* Flags				    */
-	void		*handle; /* User-space: "Handle" to pass to mmap    */
-				 /* Kernel-space: kernel-virtual address    */
-	int		mtrr;	 /* MTRR slot used			    */
-				 /* Private data			    */
+	unsigned long	offset;	 /**< Requested physical address (0 for SAREA)*/
+	unsigned long	size;	 /**< Requested physical size (bytes) */
+	drm_map_type_t	type;	 /**< Type of memory to map */
+	drm_map_flags_t flags;	 /**< Flags */
+	void		*handle; /**< User-space: "Handle" to pass to mmap() */
+				 /**< Kernel-space: kernel-virtual address */
+	int		mtrr;	 /**< MTRR slot used */
+				 /*   Private data */
 } drm_map_t;
 
+
+/**
+ * DRM_IOCTL_GET_CLIENT ioctl argument type.
+ */
 typedef struct drm_client {
-	int		idx;	/* Which client desired?                    */
-	int		auth;	/* Is client authenticated?                 */
-	unsigned long	pid;	/* Process id                               */
-	unsigned long	uid;	/* User id                                  */
-	unsigned long	magic;	/* Magic                                    */
-	unsigned long	iocs;	/* Ioctl count                              */
+	int		idx;	/**< Which client desired? */
+	int		auth;	/**< Is client authenticated? */
+	unsigned long	pid;	/**< Process ID */
+	unsigned long	uid;	/**< User ID */
+	unsigned long	magic;	/**< Magic */
+	unsigned long	iocs;	/**< Ioctl count */
 } drm_client_t;
 
+
 typedef enum {
 	_DRM_STAT_LOCK,
 	_DRM_STAT_OPENS,
@@ -210,20 +261,24 @@ typedef enum {
 	_DRM_STAT_IOCTLS,
 	_DRM_STAT_LOCKS,
 	_DRM_STAT_UNLOCKS,
-	_DRM_STAT_VALUE,	/* Generic value                      */
-	_DRM_STAT_BYTE,		/* Generic byte counter (1024bytes/K) */
-	_DRM_STAT_COUNT,	/* Generic non-byte counter (1000/k)  */
+	_DRM_STAT_VALUE,	/**< Generic value */
+	_DRM_STAT_BYTE,		/**< Generic byte counter (1024bytes/K) */
+	_DRM_STAT_COUNT,	/**< Generic non-byte counter (1000/k) */
 
-	_DRM_STAT_IRQ,		/* IRQ */
-	_DRM_STAT_PRIMARY,	/* Primary DMA bytes */
-	_DRM_STAT_SECONDARY,	/* Secondary DMA bytes */
-	_DRM_STAT_DMA,		/* DMA */
-	_DRM_STAT_SPECIAL,	/* Special DMA (e.g., priority or polled) */
-	_DRM_STAT_MISSED	/* Missed DMA opportunity */
+	_DRM_STAT_IRQ,		/**< IRQ */
+	_DRM_STAT_PRIMARY,	/**< Primary DMA bytes */
+	_DRM_STAT_SECONDARY,	/**< Secondary DMA bytes */
+	_DRM_STAT_DMA,		/**< DMA */
+	_DRM_STAT_SPECIAL,	/**< Special DMA (e.g., priority or polled) */
+	_DRM_STAT_MISSED	/**< Missed DMA opportunity */
 
 				/* Add to the *END* of the list */
 } drm_stat_type_t;
 
+
+/**
+ * DRM_IOCTL_GET_STATS ioctl argument type.
+ */
 typedef struct drm_stats {
 	unsigned long count;
 	struct {
@@ -232,137 +287,220 @@ typedef struct drm_stats {
 	} data[15];
 } drm_stats_t;
 
+
+/**
+ * Hardware locking flags.
+ */
 typedef enum drm_lock_flags {
-	_DRM_LOCK_READY	     = 0x01, /* Wait until hardware is ready for DMA */
-	_DRM_LOCK_QUIESCENT  = 0x02, /* Wait until hardware quiescent	     */
-	_DRM_LOCK_FLUSH	     = 0x04, /* Flush this context's DMA queue first */
-	_DRM_LOCK_FLUSH_ALL  = 0x08, /* Flush all DMA queues first	     */
+	_DRM_LOCK_READY	     = 0x01, /**< Wait until hardware is ready for DMA */
+	_DRM_LOCK_QUIESCENT  = 0x02, /**< Wait until hardware quiescent */
+	_DRM_LOCK_FLUSH	     = 0x04, /**< Flush this context's DMA queue first */
+	_DRM_LOCK_FLUSH_ALL  = 0x08, /**< Flush all DMA queues first */
 				/* These *HALT* flags aren't supported yet
 				   -- they will be used to support the
 				   full-screen DGA-like mode. */
-	_DRM_HALT_ALL_QUEUES = 0x10, /* Halt all current and future queues   */
-	_DRM_HALT_CUR_QUEUES = 0x20  /* Halt all current queues		     */
+	_DRM_HALT_ALL_QUEUES = 0x10, /**< Halt all current and future queues */
+	_DRM_HALT_CUR_QUEUES = 0x20  /**< Halt all current queues */
 } drm_lock_flags_t;
 
+
+/**
+ * DRM_IOCTL_LOCK, DRM_IOCTL_UNLOCK and DRM_IOCTL_FINISH ioctl argument type.
+ * 
+ * \sa drmGetLock() and drmUnlock().
+ */
 typedef struct drm_lock {
 	int		 context;
 	drm_lock_flags_t flags;
 } drm_lock_t;
 
-typedef enum drm_dma_flags {	      /* These values *MUST* match xf86drm.h */
-				      /* Flags for DMA buffer dispatch	     */
-	_DRM_DMA_BLOCK	      = 0x01, /* Block until buffer dispatched.
-					 Note, the buffer may not yet have
-					 been processed by the hardware --
-					 getting a hardware lock with the
-					 hardware quiescent will ensure
-					 that the buffer has been
-					 processed.			     */
-	_DRM_DMA_WHILE_LOCKED = 0x02, /* Dispatch while lock held	     */
-	_DRM_DMA_PRIORITY     = 0x04, /* High priority dispatch		     */
-
-				      /* Flags for DMA buffer request	     */
-	_DRM_DMA_WAIT	      = 0x10, /* Wait for free buffers		     */
-	_DRM_DMA_SMALLER_OK   = 0x20, /* Smaller-than-requested buffers ok   */
-	_DRM_DMA_LARGER_OK    = 0x40  /* Larger-than-requested buffers ok    */
+
+/**
+ * DMA flags
+ *
+ * \warning 
+ * These values \e must match xf86drm.h.
+ *
+ * \sa drm_dma.
+ */
+typedef enum drm_dma_flags {	      
+				      /* Flags for DMA buffer dispatch */
+	_DRM_DMA_BLOCK	      = 0x01, /**<
+				       * Block until buffer dispatched.
+				       * 
+				       * \note The buffer may not yet have
+				       * been processed by the hardware --
+				       * getting a hardware lock with the
+				       * hardware quiescent will ensure
+				       * that the buffer has been
+				       * processed.
+				       */
+	_DRM_DMA_WHILE_LOCKED = 0x02, /**< Dispatch while lock held */
+	_DRM_DMA_PRIORITY     = 0x04, /**< High priority dispatch */
+
+				      /* Flags for DMA buffer request */
+	_DRM_DMA_WAIT	      = 0x10, /**< Wait for free buffers */
+	_DRM_DMA_SMALLER_OK   = 0x20, /**< Smaller-than-requested buffers OK */
+	_DRM_DMA_LARGER_OK    = 0x40  /**< Larger-than-requested buffers OK */
 } drm_dma_flags_t;
 
+
+/**
+ * DRM_IOCTL_ADD_BUFS and DRM_IOCTL_MARK_BUFS ioctl argument type.
+ *
+ * \sa drmAddBufs().
+ */
 typedef struct drm_buf_desc {
-	int	      count;	 /* Number of buffers of this size	     */
-	int	      size;	 /* Size in bytes			     */
-	int	      low_mark;	 /* Low water mark			     */
-	int	      high_mark; /* High water mark			     */
+	int	      count;	 /**< Number of buffers of this size */
+	int	      size;	 /**< Size in bytes */
+	int	      low_mark;	 /**< Low water mark */
+	int	      high_mark; /**< High water mark */
 	enum {
-		_DRM_PAGE_ALIGN = 0x01, /* Align on page boundaries for DMA  */
-		_DRM_AGP_BUFFER = 0x02, /* Buffer is in agp space            */
-		_DRM_SG_BUFFER  = 0x04  /* Scatter/gather memory buffer      */
+		_DRM_PAGE_ALIGN = 0x01, /**< Align on page boundaries for DMA */
+		_DRM_AGP_BUFFER = 0x02, /**< Buffer is in AGP space */
+		_DRM_SG_BUFFER  = 0x04  /**< Scatter/gather memory buffer */
 	}	      flags;
-	unsigned long agp_start; /* Start address of where the agp buffers
-				  * are in the agp aperture */
+	unsigned long agp_start; /**< 
+				  * Start address of where the AGP buffers are
+				  * in the AGP aperture
+				  */
 } drm_buf_desc_t;
 
+
+/**
+ * DRM_IOCTL_INFO_BUFS ioctl argument type.
+ */
 typedef struct drm_buf_info {
-	int	       count;	/* Entries in list			     */
+	int	       count;	/**< Entries in list */
 	drm_buf_desc_t *list;
 } drm_buf_info_t;
 
+
+/**
+ * DRM_IOCTL_FREE_BUFS ioctl argument type.
+ */
 typedef struct drm_buf_free {
 	int	       count;
 	int	       *list;
 } drm_buf_free_t;
 
+
+/**
+ * Buffer information
+ *
+ * \sa drm_buf_map.
+ */
 typedef struct drm_buf_pub {
-	int		  idx;	       /* Index into master buflist	     */
-	int		  total;       /* Buffer size			     */
-	int		  used;	       /* Amount of buffer in use (for DMA)  */
-	void		  *address;    /* Address of buffer		     */
+	int		  idx;	       /**< Index into the master buffer list */
+	int		  total;       /**< Buffer size */
+	int		  used;	       /**< Amount of buffer in use (for DMA) */
+	void		  *address;    /**< Address of buffer */
 } drm_buf_pub_t;
 
+
+/**
+ * DRM_IOCTL_MAP_BUFS ioctl argument type.
+ */
 typedef struct drm_buf_map {
-	int	      count;	/* Length of buflist			    */
-	void	      *virtual;	/* Mmaped area in user-virtual		    */
-	drm_buf_pub_t *list;	/* Buffer information			    */
+	int	      count;	/**< Length of the buffer list */
+	void	      *virtual;	/**< Mmap'd area in user-virtual */
+	drm_buf_pub_t *list;	/**< Buffer information */
 } drm_buf_map_t;
 
+
+/**
+ * DRM_IOCTL_DMA ioctl argument type.
+ *
+ * Indices here refer to the offset into the buffer list in drm_buf_get.
+ *
+ * \sa drmDMA().
+ */
 typedef struct drm_dma {
-				/* Indices here refer to the offset into
-				   buflist in drm_buf_get_t.  */
-	int		context;	  /* Context handle		    */
-	int		send_count;	  /* Number of buffers to send	    */
-	int		*send_indices;	  /* List of handles to buffers	    */
-	int		*send_sizes;	  /* Lengths of data to send	    */
-	drm_dma_flags_t flags;		  /* Flags			    */
-	int		request_count;	  /* Number of buffers requested    */
-	int		request_size;	  /* Desired size for buffers	    */
-	int		*request_indices; /* Buffer information		    */
+	int		context;	  /**< Context handle */
+	int		send_count;	  /**< Number of buffers to send */
+	int		*send_indices;	  /**< List of handles to buffers */
+	int		*send_sizes;	  /**< Lengths of data to send */
+	drm_dma_flags_t flags;		  /**< Flags */
+	int		request_count;	  /**< Number of buffers requested */
+	int		request_size;	  /**< Desired size for buffers */
+	int		*request_indices; /**< Buffer information */
 	int		*request_sizes;
-	int		granted_count;	  /* Number of buffers granted	    */
+	int		granted_count;	  /**< Number of buffers granted */
 } drm_dma_t;
 
+
 typedef enum {
 	_DRM_CONTEXT_PRESERVED = 0x01,
 	_DRM_CONTEXT_2DONLY    = 0x02
 } drm_ctx_flags_t;
 
+
+/**
+ * DRM_IOCTL_ADD_CTX ioctl argument type.
+ *
+ * \sa drmCreateContext() and drmDestroyContext().
+ */
 typedef struct drm_ctx {
 	drm_context_t	handle;
 	drm_ctx_flags_t flags;
 } drm_ctx_t;
 
+
+/**
+ * DRM_IOCTL_RES_CTX ioctl argument type.
+ */
 typedef struct drm_ctx_res {
 	int		count;
 	drm_ctx_t	*contexts;
 } drm_ctx_res_t;
 
+
+/**
+ * DRM_IOCTL_ADD_DRAW and DRM_IOCTL_RM_DRAW ioctl argument type.
+ */
 typedef struct drm_draw {
 	drm_drawable_t	handle;
 } drm_draw_t;
 
+
+/**
+ * DRM_IOCTL_GET_MAGIC and DRM_IOCTL_AUTH_MAGIC ioctl argument type.
+ */
 typedef struct drm_auth {
 	drm_magic_t	magic;
 } drm_auth_t;
 
+
+/**
+ * DRM_IOCTL_IRQ_BUSID ioctl argument type.
+ *
+ * \sa drmGetInterruptFromBusID().
+ */
 typedef struct drm_irq_busid {
-	int irq;
-	int busnum;
-	int devnum;
-	int funcnum;
+	int irq;	/**< IRQ number */
+	int busnum;	/**< bus number */
+	int devnum;	/**< device number */
+	int funcnum;	/**< function number */
 } drm_irq_busid_t;
 
+
 typedef enum {
-    _DRM_VBLANK_ABSOLUTE = 0x0,		/* Wait for specific vblank sequence number */
-    _DRM_VBLANK_RELATIVE = 0x1,		/* Wait for given number of vblanks */
-    _DRM_VBLANK_SIGNAL   = 0x40000000	/* Send signal instead of blocking */
+    _DRM_VBLANK_ABSOLUTE = 0x0,		/**< Wait for specific vblank sequence number */
+    _DRM_VBLANK_RELATIVE = 0x1,		/**< Wait for given number of vblanks */
+    _DRM_VBLANK_SIGNAL   = 0x80000000	/**< Send signal instead of blocking */
 } drm_vblank_seq_type_t;
 
+
 #define _DRM_VBLANK_FLAGS_MASK _DRM_VBLANK_SIGNAL
 
+
 struct drm_wait_vblank_request {
 	drm_vblank_seq_type_t type;
 	unsigned int sequence;
 	unsigned long signal;
 };
 
+
 struct drm_wait_vblank_reply {
 	drm_vblank_seq_type_t type;
 	unsigned int sequence;
@@ -370,29 +508,59 @@ struct drm_wait_vblank_reply {
 	long tval_usec;
 };
 
+
+/**
+ * DRM_IOCTL_WAIT_VBLANK ioctl argument type.
+ *
+ * \sa drmWaitVBlank().
+ */
 typedef union drm_wait_vblank {
 	struct drm_wait_vblank_request request;
 	struct drm_wait_vblank_reply reply;
 } drm_wait_vblank_t;
 
+
+/**
+ * DRM_IOCTL_AGP_ENABLE ioctl argument type.
+ *
+ * \sa drmAgpEnable().
+ */
 typedef struct drm_agp_mode {
-	unsigned long mode;
+	unsigned long mode;	/**< AGP mode */
 } drm_agp_mode_t;
 
-				/* For drm_agp_alloc -- allocated a buffer */
+
+/**
+ * DRM_IOCTL_AGP_ALLOC and DRM_IOCTL_AGP_FREE ioctls argument type.
+ *
+ * \sa drmAgpAlloc() and drmAgpFree().
+ */
 typedef struct drm_agp_buffer {
-	unsigned long size;	/* In bytes -- will round to page boundary */
-	unsigned long handle;	/* Used for BIND/UNBIND ioctls */
-	unsigned long type;     /* Type of memory to allocate  */
-        unsigned long physical; /* Physical used by i810       */
+	unsigned long size;	/**< In bytes -- will round to page boundary */
+	unsigned long handle;	/**< Used for binding / unbinding */
+	unsigned long type;     /**< Type of memory to allocate */
+        unsigned long physical; /**< Physical used by i810 */
 } drm_agp_buffer_t;
 
-				/* For drm_agp_bind */
+
+/**
+ * DRM_IOCTL_AGP_BIND and DRM_IOCTL_AGP_UNBIND ioctls argument type.
+ *
+ * \sa drmAgpBind() and drmAgpUnbind().
+ */
 typedef struct drm_agp_binding {
-	unsigned long handle;   /* From drm_agp_buffer */
-	unsigned long offset;	/* In bytes -- will round to page boundary */
+	unsigned long handle;   /**< From drm_agp_buffer */
+	unsigned long offset;	/**< In bytes -- will round to page boundary */
 } drm_agp_binding_t;
 
+
+/**
+ * DRM_IOCTL_AGP_INFO ioctl argument type.
+ *
+ * \sa drmAgpVersionMajor(), drmAgpVersionMinor(), drmAgpGetMode(),
+ * drmAgpBase(), drmAgpSize(), drmAgpMemoryUsed(), drmAgpMemoryAvail(),
+ * drmAgpVendorId() and drmAgpDeviceId().
+ */
 typedef struct drm_agp_info {
 	int            agp_version_major;
 	int            agp_version_minor;
@@ -407,11 +575,16 @@ typedef struct drm_agp_info {
 	unsigned short id_device;
 } drm_agp_info_t;
 
+
+/**
+ * DRM_IOCTL_SG_ALLOC ioctl argument type.
+ */
 typedef struct drm_scatter_gather {
-	unsigned long size;	/* In bytes -- will round to page boundary */
-	unsigned long handle;	/* Used for mapping / unmapping */
+	unsigned long size;	/**< In bytes -- will round to page boundary */
+	unsigned long handle;	/**< Used for mapping / unmapping */
 } drm_scatter_gather_t;
 
+
 #define DRM_IOCTL_BASE			'd'
 #define DRM_IO(nr)			_IO(DRM_IOCTL_BASE,nr)
 #define DRM_IOR(nr,type)		_IOR(DRM_IOCTL_BASE,nr,type)
@@ -471,8 +644,13 @@ typedef struct drm_scatter_gather {
 
 #define DRM_IOCTL_WAIT_VBLANK		DRM_IOWR(0x3a, drm_wait_vblank_t)
 
-/* Device specfic ioctls should only be in their respective headers
- * The device specific ioctl range is 0x40 to 0x79.                  */
+/**
+ * Device specific ioctls should only be in their respective headers
+ * The device specific ioctl range is from 0x40 to 0x79.
+ *
+ * \sa drmCommandNone(), drmCommandRead(), drmCommandWrite(), and
+ * drmCommandReadWrite().
+ */
 #define DRM_COMMAND_BASE                0x40
 
 #endif
diff --git a/shared/drm_sarea.h b/shared/drm_sarea.h
index cee48eee..dd3f617a 100644
--- a/shared/drm_sarea.h
+++ b/shared/drm_sarea.h
@@ -1,5 +1,11 @@
-/* sarea.h -- SAREA definitions -*- linux-c -*-
+/**
+ * \file drm_sarea.h 
+ * \brief SAREA definitions
  *
+ * \author Michel Dänzer <michel@daenzer.net>
+ */
+
+/*
  * Copyright 2002 Tungsten Graphics, Inc., Cedar Park, Texas.
  * All Rights Reserved.
  *
@@ -21,22 +27,22 @@
  * 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:
- *    Michel Dänzer <michel@daenzer.net>
  */
 
 #ifndef _DRM_SAREA_H_
 #define _DRM_SAREA_H_
 
+/** Maximum number of drawables in the SAREA */
 #define SAREA_MAX_DRAWABLES 		256
 
-typedef struct _drm_sarea_drawable_t {
+/** SAREA drawable */
+typedef struct drm_sarea_drawable {
     unsigned int	stamp;
     unsigned int	flags;
 } drm_sarea_drawable_t;
 
-typedef struct _dri_sarea_frame_t {
+/** SAREA frame */
+typedef struct drm_sarea_frame {
     unsigned int        x;
     unsigned int        y;
     unsigned int        width;
@@ -44,13 +50,14 @@ typedef struct _dri_sarea_frame_t {
     unsigned int        fullscreen;
 } drm_sarea_frame_t;
 
-typedef struct _drm_sarea_t {
-    /* first thing is always the drm locking structure */
+/** SAREA */
+typedef struct drm_sarea {
+    /** first thing is always the DRM locking structure */
     drm_hw_lock_t		lock;
-		/* NOT_DONE: Use readers/writer lock for drawable_lock */
+    /** \todo Use readers/writer lock for drm_sarea::drawable_lock */
     drm_hw_lock_t		drawable_lock;
-    drm_sarea_drawable_t	drawableTable[SAREA_MAX_DRAWABLES];
-    drm_sarea_frame_t		frame;
+    drm_sarea_drawable_t	drawableTable[SAREA_MAX_DRAWABLES];	/**< drawables */
+    drm_sarea_frame_t		frame;	/**< frame */
     drm_context_t		dummy_context;
 } drm_sarea_t;