Merge branch 'master' of ssh+git://git.freedesktop.org/git/mesa/drm into xgi-0-0-2

18 files changed, 189 insertions, 89 deletions

diff --git a/bsd-core/ati_pcigart.c b/bsd-core/ati_pcigart.c
index 682eace6..db19a75d 100644
--- a/bsd-core/ati_pcigart.c
+++ b/bsd-core/ati_pcigart.c
@@ -1,6 +1,3 @@
-/* ati_pcigart.h -- ATI PCI GART support -*- linux-c -*-
- * Created: Wed Dec 13 21:52:19 2000 by gareth@valinux.com
- */
 /*-
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
@@ -29,6 +26,11 @@
  *
  */
 
+/** @file ati_pcigart.c
+ * Implementation of ATI's PCIGART, which provides an aperture in card virtual
+ * address space with addresses remapped to system memory.
+ */
+
 #include "drmP.h"
 
 #define ATI_PCIGART_PAGE_SIZE		4096	/* PCI GART page size */
diff --git a/bsd-core/drmP.h b/bsd-core/drmP.h
index 73342d09..8a768f0c 100644
--- a/bsd-core/drmP.h
+++ b/bsd-core/drmP.h
@@ -377,6 +377,7 @@ do {									\
 } while (0)
 
 #if defined(__FreeBSD__) && __FreeBSD_version > 500000
+/* Returns -errno to shared code */
 #define DRM_WAIT_ON( ret, queue, timeout, condition )		\
 for ( ret = 0 ; !ret && !(condition) ; ) {			\
 	DRM_UNLOCK();						\
@@ -388,11 +389,12 @@ for ( ret = 0 ; !ret && !(condition) ; ) {			\
 	DRM_LOCK();						\
 }
 #else
+/* Returns -errno to shared code */
 #define DRM_WAIT_ON( ret, queue, timeout, condition )	\
 for ( ret = 0 ; !ret && !(condition) ; ) {		\
         int s = spldrm();				\
 	if (!(condition))				\
-	   ret = tsleep( &(queue), PZERO | PCATCH, 	\
+	   ret = -tsleep( &(queue), PZERO | PCATCH, 	\
 			 "drmwtq", (timeout) );		\
 	splx(s);					\
 }
diff --git a/bsd-core/drm_agpsupport.c b/bsd-core/drm_agpsupport.c
index e8e162de..6f963b9c 100644
--- a/bsd-core/drm_agpsupport.c
+++ b/bsd-core/drm_agpsupport.c
@@ -1,6 +1,3 @@
-/* drm_agpsupport.h -- DRM support for AGP/GART backend -*- linux-c -*-
- * Created: Mon Dec 13 09:56:45 1999 by faith@precisioninsight.com
- */
 /*-
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,11 @@
  *
  */
 
+/** @file drm_agpsupport.c
+ * Support code for tying the kernel AGP support to DRM drivers and
+ * the DRM's AGP ioctls.
+ */
+
 #include "drmP.h"
 
 #ifdef __FreeBSD__
@@ -182,7 +184,6 @@ int drm_agp_enable(drm_device_t *dev, drm_agp_mode_t mode)
 	
 	dev->agp->mode    = mode.mode;
 	agp_enable(dev->agp->agpdev, mode.mode);
-	dev->agp->base    = dev->agp->info.ai_aperture_base;
 	dev->agp->enabled = 1;
 	return 0;
 }
@@ -403,6 +404,7 @@ drm_agp_head_t *drm_agp_init(void)
 			return NULL;
 		head->agpdev = agpdev;
 		agp_get_info(agpdev, &head->info);
+		head->base = head->info.ai_aperture_base;
 		head->memory = NULL;
 		DRM_INFO("AGP at 0x%08lx %dMB\n",
 			 (long)head->info.ai_aperture_base,
diff --git a/bsd-core/drm_auth.c b/bsd-core/drm_auth.c
index 964f9a42..aa8238c4 100644
--- a/bsd-core/drm_auth.c
+++ b/bsd-core/drm_auth.c
@@ -1,6 +1,3 @@
-/* drm_auth.h -- IOCTLs for authentication -*- linux-c -*-
- * Created: Tue Feb  2 08:37:54 1999 by faith@valinux.com
- */
 /*-
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,11 @@
  *
  */
 
+/** @file drm_auth.c
+ * Implementation of the get/authmagic ioctls implementing the authentication
+ * scheme between the master and clients.
+ */
+
 #include "drmP.h"
 
 static int drm_hash_magic(drm_magic_t magic)
@@ -38,11 +40,16 @@ static int drm_hash_magic(drm_magic_t magic)
 	return magic & (DRM_HASH_SIZE-1);
 }
 
+/**
+ * Returns the file private associated with the given magic number.
+ */
 static drm_file_t *drm_find_file(drm_device_t *dev, drm_magic_t magic)
 {
 	drm_magic_entry_t *pt;
 	int hash = drm_hash_magic(magic);
 
+	DRM_SPINLOCK_ASSERT(&dev->dev_lock);
+
 	for (pt = dev->magiclist[hash].head; pt; pt = pt->next) {
 		if (pt->magic == magic) {
 			return pt->priv;
@@ -52,6 +59,10 @@ static drm_file_t *drm_find_file(drm_device_t *dev, drm_magic_t magic)
 	return NULL;
 }
 
+/**
+ * Inserts the given magic number into the hash table of used magic number
+ * lists.
+ */
 static int drm_add_magic(drm_device_t *dev, drm_file_t *priv, drm_magic_t magic)
 {
 	int		  hash;
@@ -59,6 +70,8 @@ static int drm_add_magic(drm_device_t *dev, drm_file_t *priv, drm_magic_t magic)
 
 	DRM_DEBUG("%d\n", magic);
 
+	DRM_SPINLOCK_ASSERT(&dev->dev_lock);
+
 	hash = drm_hash_magic(magic);
 	entry = malloc(sizeof(*entry), M_DRM, M_ZERO | M_NOWAIT);
 	if (!entry) return ENOMEM;
@@ -79,16 +92,21 @@ static int drm_add_magic(drm_device_t *dev, drm_file_t *priv, drm_magic_t magic)
 	return 0;
 }
 
+/**
+ * Removes the given magic number from the hash table of used magic number
+ * lists.
+ */
 static 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_SPINLOCK_ASSERT(&dev->dev_lock);
+
 	DRM_DEBUG("%d\n", magic);
 	hash = drm_hash_magic(magic);
 
-	DRM_LOCK();
 	for (pt = dev->magiclist[hash].head; pt; prev = pt, pt = pt->next) {
 		if (pt->magic == magic) {
 			if (dev->magiclist[hash].head == pt) {
@@ -100,16 +118,22 @@ static int drm_remove_magic(drm_device_t *dev, drm_magic_t magic)
 			if (prev) {
 				prev->next = pt->next;
 			}
-			DRM_UNLOCK();
 			return 0;
 		}
 	}
-	DRM_UNLOCK();
 
 	free(pt, M_DRM);
 	return EINVAL;
 }
 
+/**
+ * Called by the client, this returns a unique magic number to be authorized
+ * by the master.
+ *
+ * The master may use its own knowledge of the client (such as the X
+ * connection that the magic is passed over) to determine if the magic number
+ * should be authenticated.
+ */
 int drm_getmagic(drm_device_t *dev, void *data, struct drm_file *file_priv)
 {
 	static drm_magic_t sequence = 0;
@@ -122,15 +146,15 @@ int drm_getmagic(drm_device_t *dev, void *data, struct drm_file *file_priv)
 		DRM_LOCK();
 		do {
 			int old = sequence;
-			
+
 			auth->magic = old+1;
-			
+
 			if (!atomic_cmpset_int(&sequence, old, auth->magic))
 				continue;
 		} while (drm_find_file(dev, auth->magic));
 		file_priv->magic = auth->magic;
-		DRM_UNLOCK();
 		drm_add_magic(dev, file_priv, auth->magic);
+		DRM_UNLOCK();
 	}
 
 	DRM_DEBUG("%u\n", auth->magic);
@@ -138,6 +162,9 @@ int drm_getmagic(drm_device_t *dev, void *data, struct drm_file *file_priv)
 	return 0;
 }
 
+/**
+ * Marks the client associated with the given magic number as authenticated.
+ */
 int drm_authmagic(drm_device_t *dev, void *data, struct drm_file *file_priv)
 {
 	drm_auth_t *auth = data;
diff --git a/bsd-core/drm_bufs.c b/bsd-core/drm_bufs.c
index a0a3fc73..9b58c593 100644
--- a/bsd-core/drm_bufs.c
+++ b/bsd-core/drm_bufs.c
@@ -1,6 +1,3 @@
-/* drm_bufs.h -- Generic buffer template -*- linux-c -*-
- * Created: Thu Nov 23 03:10:50 2000 by gareth@valinux.com
- */
 /*-
  * Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,10 @@
  *
  */
 
+/** @file drm_bufs.c
+ * Implementation of the ioctls for setup of DRM mappings and DMA buffers.
+ */
+
 #include "dev/pci/pcireg.h"
 
 #include "drmP.h"
@@ -190,7 +191,17 @@ int drm_addmap(drm_device_t * dev, unsigned long offset, unsigned long size,
 		break;
 	case _DRM_AGP:
 		/*valid = 0;*/
-		map->offset += dev->agp->base;
+		/* In some cases (i810 driver), user space may have already
+		 * added the AGP base itself, because dev->agp->base previously
+		 * only got set during AGP enable.  So, only add the base
+		 * address if the map's offset isn't already within the
+		 * aperture.
+		 */
+		if (map->offset < dev->agp->base ||
+		    map->offset > dev->agp->base +
+		    dev->agp->info.ai_aperture_size - 1) {
+			map->offset += dev->agp->base;
+		}
 		map->mtrr   = dev->agp->mtrr; /* for getmap */
 		/*for (entry = dev->agp->memory; entry; entry = entry->next) {
 			if ((map->offset >= entry->bound) &&
diff --git a/bsd-core/drm_context.c b/bsd-core/drm_context.c
index e34e8759..4155ee92 100644
--- a/bsd-core/drm_context.c
+++ b/bsd-core/drm_context.c
@@ -1,6 +1,3 @@
-/* drm_context.h -- IOCTLs for generic contexts -*- linux-c -*-
- * Created: Fri Nov 24 18:31:37 2000 by gareth@valinux.com
- */
 /*-
  * Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,10 @@
  *
  */
 
+/** @file drm_context.c
+ * Implementation of the context management ioctls.
+ */
+
 #include "drmP.h"
 
 /* ================================================================
diff --git a/bsd-core/drm_dma.c b/bsd-core/drm_dma.c
index fc1e1250..71ef845b 100644
--- a/bsd-core/drm_dma.c
+++ b/bsd-core/drm_dma.c
@@ -1,6 +1,3 @@
-/* drm_dma.c -- DMA IOCTL and function support -*- linux-c -*-
- * Created: Fri Mar 19 14:30:16 1999 by faith@valinux.com
- */
 /*-
  * Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,14 @@
  *
  */
 
+/** @file drm_dma.c
+ * Support code for DMA buffer management.
+ *
+ * The implementation used to be significantly more complicated, but the
+ * complexity has been moved into the drivers as different buffer management
+ * schemes evolved.
+ */
+
 #include "drmP.h"
 
 int drm_dma_setup(drm_device_t *dev)
@@ -121,6 +126,7 @@ int drm_dma(drm_device_t *dev, void *data, struct drm_file *file_priv)
 {
 
 	if (dev->driver.dma_ioctl) {
+		/* shared code returns -errno */
 		return -dev->driver.dma_ioctl(dev, data, file_priv);
 	} else {
 		DRM_DEBUG("DMA ioctl on driver with no dma handler\n");
diff --git a/bsd-core/drm_drawable.c b/bsd-core/drm_drawable.c
index 7e038ab9..fb318d47 100644
--- a/bsd-core/drm_drawable.c
+++ b/bsd-core/drm_drawable.c
@@ -1,6 +1,3 @@
-/* drm_drawable.h -- IOCTLs for drawables -*- linux-c -*-
- * Created: Tue Feb  2 08:37:54 1999 by faith@valinux.com
- */
 /*-
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,11 @@
  *
  */
 
+/** @file drm_drawable.c
+ * This file implements ioctls to store information along with DRM drawables,
+ * such as the current set of cliprects for vblank-synced buffer swaps.
+ */
+
 #include "drmP.h"
 
 struct bsd_drm_drawable_info {
diff --git a/bsd-core/drm_drv.c b/bsd-core/drm_drv.c
index a978f50f..afd90351 100644
--- a/bsd-core/drm_drv.c
+++ b/bsd-core/drm_drv.c
@@ -1,6 +1,3 @@
-/* drm_drv.h -- Generic driver template -*- linux-c -*-
- * Created: Thu Nov 23 03:10:50 2000 by gareth@valinux.com
- */
 /*-
  * Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,12 @@
  *
  */
 
+/** @file drm_drv.c
+ * The catch-all file for DRM device support, including module setup/teardown,
+ * open/close, and ioctl dispatch.
+ */
+
+
 #include <sys/limits.h>
 #include "drmP.h"
 #include "drm.h"
@@ -818,14 +821,7 @@ int drm_close(struct cdev *kdev, int flags, int fmt, DRM_STRUCTPROC *p)
 int drm_ioctl(struct cdev *kdev, u_long cmd, caddr_t data, int flags, 
     DRM_STRUCTPROC *p)
 {
-#ifdef __FreeBSD__
-	drm_device_t *dev = kdev->si_drv1;
-#elif defined(__NetBSD__)
-	drm_device_t *dev = device_lookup(&drm_cd, minor(kdev));
-#else
-	drm_device_t *dev = device_lookup(&drm_cd,
-            minor(kdev)))->dv_cfdata->cf_driver->cd_devs[minor(kdev)];
-#endif
+	drm_device_t *dev = drm_get_device_from_kdev(kdev);
 	int retcode = 0;
 	drm_ioctl_desc_t *ioctl;
 	int (*func)(drm_device_t *dev, void *data, struct drm_file *file_priv);
@@ -912,15 +908,13 @@ int drm_ioctl(struct cdev *kdev, u_long cmd, caddr_t data, int flags,
 	    ((ioctl->flags & DRM_MASTER) && !file_priv->master))
 		return EACCES;
 
-	if (is_driver_ioctl)
-		DRM_LOCK();
-	retcode = func(dev, data, file_priv);
 	if (is_driver_ioctl) {
+		DRM_LOCK();
+		/* shared code returns -errno */
+		retcode = -func(dev, data, file_priv);
 		DRM_UNLOCK();
-		/* Driver ioctls in shared code follow the linux convention of
-		 * returning -errno instead of errno.
-		 */
-		retcode = -retcode;
+	} else {
+		retcode = func(dev, data, file_priv);
 	}
 
 	if (retcode != 0)
diff --git a/bsd-core/drm_fops.c b/bsd-core/drm_fops.c
index 870e4d29..20bae8d7 100644
--- a/bsd-core/drm_fops.c
+++ b/bsd-core/drm_fops.c
@@ -1,6 +1,3 @@
-/* drm_fops.h -- File operations for DRM -*- linux-c -*-
- * Created: Mon Jan  4 08:58:31 1999 by faith@valinux.com
- */
 /*-
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -32,6 +29,11 @@
  *
  */
 
+/** @file drm_fops.c
+ * Support code for dealing with the file privates associated with each
+ * open of the DRM device.
+ */
+
 #include "drmP.h"
 
 drm_file_t *drm_find_file_by_proc(drm_device_t *dev, DRM_STRUCTPROC *p)
@@ -93,6 +95,7 @@ int drm_open_helper(struct cdev *kdev, int flags, int fmt, DRM_STRUCTPROC *p,
 		priv->authenticated	= DRM_SUSER(p);
 
 		if (dev->driver.open) {
+			/* shared code returns -errno */
 			retcode = -dev->driver.open(dev, priv);
 			if (retcode != 0) {
 				free(priv, M_DRM);
diff --git a/bsd-core/drm_ioctl.c b/bsd-core/drm_ioctl.c
index ebdb2140..ce78bb8f 100644
--- a/bsd-core/drm_ioctl.c
+++ b/bsd-core/drm_ioctl.c
@@ -1,6 +1,3 @@
-/* drm_ioctl.h -- IOCTL processing for DRM -*- linux-c -*-
- * Created: Fri Jan  8 09:01:26 1999 by faith@valinux.com
- */
 /*-
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,11 @@
  *
  */
 
+/** @file drm_ioctl.c
+ * Varios minor DRM ioctls not applicable to other files, such as versioning
+ * information and reporting DRM information to userland.
+ */
+
 #include "drmP.h"
 
 /*
@@ -203,7 +205,7 @@ int drm_getstats(drm_device_t *dev, void *data, struct drm_file *file_priv)
 	drm_stats_t  *stats = data;
 	int          i;
 
-	memset(&stats, 0, sizeof(stats));
+	memset(stats, 0, sizeof(drm_stats_t));
 	
 	DRM_LOCK();
 
@@ -230,23 +232,27 @@ int drm_getstats(drm_device_t *dev, void *data, struct drm_file *file_priv)
 int drm_setversion(drm_device_t *dev, void *data, struct drm_file *file_priv)
 {
 	drm_set_version_t *sv = data;
-	drm_set_version_t retv;
+	drm_set_version_t ver;
 	int if_version;
 
-	retv.drm_di_major = DRM_IF_MAJOR;
-	retv.drm_di_minor = DRM_IF_MINOR;
-	retv.drm_dd_major = dev->driver.major;
-	retv.drm_dd_minor = dev->driver.minor;
-
-	if (sv->drm_di_major != -1) {
-		if (sv->drm_di_major != DRM_IF_MAJOR ||
-		    sv->drm_di_minor < 0 || sv->drm_di_minor > DRM_IF_MINOR) {
+	/* Save the incoming data, and set the response before continuing
+	 * any further.
+	 */
+	ver = *sv;
+	sv->drm_di_major = DRM_IF_MAJOR;
+	sv->drm_di_minor = DRM_IF_MINOR;
+	sv->drm_dd_major = dev->driver.major;
+	sv->drm_dd_minor = dev->driver.minor;
+
+	if (ver.drm_di_major != -1) {
+		if (ver.drm_di_major != DRM_IF_MAJOR ||
+		    ver.drm_di_minor < 0 || ver.drm_di_minor > DRM_IF_MINOR) {
 			return EINVAL;
 		}
-		if_version = DRM_IF_VERSION(sv->drm_di_major,
-		    sv->drm_dd_minor);
+		if_version = DRM_IF_VERSION(ver.drm_di_major,
+		    ver.drm_dd_minor);
 		dev->if_version = DRM_MAX(if_version, dev->if_version);
-		if (sv->drm_di_minor >= 1) {
+		if (ver.drm_di_minor >= 1) {
 			/*
 			 * Version 1.1 includes tying of DRM to specific device
 			 */
@@ -254,10 +260,10 @@ int drm_setversion(drm_device_t *dev, void *data, struct drm_file *file_priv)
 		}
 	}
 
-	if (sv->drm_dd_major != -1) {
-		if (sv->drm_dd_major != dev->driver.major ||
-		    sv->drm_dd_minor < 0 ||
-		    sv->drm_dd_minor > dev->driver.minor)
+	if (ver.drm_dd_major != -1) {
+		if (ver.drm_dd_major != dev->driver.major ||
+		    ver.drm_dd_minor < 0 ||
+		    ver.drm_dd_minor > dev->driver.minor)
 		{
 			return EINVAL;
 		}
diff --git a/bsd-core/drm_irq.c b/bsd-core/drm_irq.c
index 1ab532fe..0772445a 100644
--- a/bsd-core/drm_irq.c
+++ b/bsd-core/drm_irq.c
@@ -1,6 +1,3 @@
-/* drm_irq.c -- IRQ IOCTL and function support
- * Created: Fri Oct 18 2003 by anholt@FreeBSD.org
- */
 /*-
  * Copyright 2003 Eric Anholt
  * All Rights Reserved.
@@ -28,6 +25,11 @@
  *
  */
 
+/** @file drm_irq.c
+ * Support code for handling setup/teardown of interrupt handlers and
+ * handing interrupt handlers off to the drivers.
+ */
+
 #include "drmP.h"
 #include "drm.h"
 
@@ -241,6 +243,7 @@ int drm_wait_vblank(drm_device_t *dev, void *data, struct drm_file *file_priv)
 		ret = EINVAL;
 	} else {
 		DRM_LOCK();
+		/* shared code returns -errno */
 		ret = -dev->driver.vblank_wait(dev,
 		    &vblwait->request.sequence);
 		DRM_UNLOCK();
diff --git a/bsd-core/drm_lock.c b/bsd-core/drm_lock.c
index 5acb13d3..fb86fc68 100644
--- a/bsd-core/drm_lock.c
+++ b/bsd-core/drm_lock.c
@@ -1,6 +1,3 @@
-/* lock.c -- IOCTLs for locking -*- linux-c -*-
- * Created: Tue Feb  2 08:37:54 1999 by faith@valinux.com
- */
 /*-
  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,25 @@
  *
  */
 
+/** @file drm_lock.c
+ * Implementation of the ioctls and other support code for dealing with the
+ * hardware lock.
+ *
+ * The DRM hardware lock is a shared structure between the kernel and userland.
+ *
+ * On uncontended access where the new context was the last context, the
+ * client may take the lock without dropping down into the kernel, using atomic
+ * compare-and-set.
+ *
+ * If the client finds during compare-and-set that it was not the last owner
+ * of the lock, it calls the DRM lock ioctl, which may sleep waiting for the
+ * lock, and may have side-effects of kernel-managed context switching.
+ *
+ * When the client releases the lock, if the lock is marked as being contended
+ * by another client, then the DRM unlock ioctl is called so that the
+ * contending client may be woken up.
+ */
+
 #include "drmP.h"
 
 int drm_lock_take(__volatile__ unsigned int *lock, unsigned int context)
@@ -157,6 +173,12 @@ int drm_unlock(drm_device_t *dev, void *data, struct drm_file *file_priv)
 		    DRM_CURRENTPID, lock->context);
 		return EINVAL;
 	}
+	/* Check that the context unlock being requested actually matches
+	 * who currently holds the lock.
+	 */
+	if (!_DRM_LOCK_IS_HELD(dev->lock.hw_lock->lock) ||
+	    _DRM_LOCKING_CONTEXT(dev->lock.hw_lock->lock) != lock->context)
+		return EINVAL;
 
 	atomic_inc(&dev->counts[_DRM_STAT_UNLOCKS]);
 
diff --git a/bsd-core/drm_memory.c b/bsd-core/drm_memory.c
index 6d467e98..1f1f7f4b 100644
--- a/bsd-core/drm_memory.c
+++ b/bsd-core/drm_memory.c
@@ -1,6 +1,3 @@
-/* drm_memory.h -- Memory management wrappers for DRM -*- linux-c -*-
- * Created: Thu Feb  4 14:00:34 1999 by faith@valinux.com
- */
 /*-
  *Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
@@ -31,6 +28,14 @@
  *
  */
 
+/** @file drm_memory.c
+ * Wrappers for kernel memory allocation routines, and MTRR management support.
+ *
+ * This file previously implemented a memory consumption tracking system using
+ * the "area" argument for various different types of allocations, but that
+ * has been stripped out for now.
+ */
+
 #include "drmP.h"
 
 MALLOC_DEFINE(M_DRM, "drm", "DRM Data Structures");
diff --git a/bsd-core/drm_pci.c b/bsd-core/drm_pci.c
index a33f5f9c..6ec6b983 100644
--- a/bsd-core/drm_pci.c
+++ b/bsd-core/drm_pci.c
@@ -1,10 +1,3 @@
-/**
- * \file drm_pci.h
- * \brief PCI consistent, DMA-accessible memory functions.
- *
- * \author Eric Anholt <anholt@FreeBSD.org>
- */
-
 /*-
  * Copyright 2003 Eric Anholt.
  * All Rights Reserved.
@@ -28,6 +21,13 @@
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * \file drm_pci.h
+ * \brief PCI consistent, DMA-accessible memory allocation.
+ *
+ * \author Eric Anholt <anholt@FreeBSD.org>
+ */
+
 #include "drmP.h"
 
 /**********************************************************************/
diff --git a/bsd-core/drm_scatter.c b/bsd-core/drm_scatter.c
index 91c3c6c5..92e715e0 100644
--- a/bsd-core/drm_scatter.c
+++ b/bsd-core/drm_scatter.c
@@ -1,5 +1,3 @@
-/* drm_scatter.h -- IOCTLs to manage scatter/gather memory -*- linux-c -*-
- * Created: Mon Dec 18 23:20:54 2000 by gareth@valinux.com */
 /*-
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
@@ -29,6 +27,13 @@
  *
  */
 
+/** @file drm_scatter.c
+ * Allocation of memory for scatter-gather mappings by the graphics chip.
+ *
+ * The memory allocated here is then made into an aperture in the card
+ * by drm_ati_pcigart_init().
+ */
+
 #include "drmP.h"
 
 #define DEBUG_SCATTER 0
diff --git a/bsd-core/drm_sysctl.c b/bsd-core/drm_sysctl.c
index b2d0cc0c..3de5b8ae 100644
--- a/bsd-core/drm_sysctl.c
+++ b/bsd-core/drm_sysctl.c
@@ -21,6 +21,11 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/** @file drm_sysctl.c
+ * Implementation of various sysctls for controlling DRM behavior and reporting
+ * debug information.
+ */
+
 #include "drmP.h"
 #include "drm.h"
 
diff --git a/bsd-core/drm_vm.c b/bsd-core/drm_vm.c
index af1dbaa8..fea31f52 100644
--- a/bsd-core/drm_vm.c
+++ b/bsd-core/drm_vm.c
@@ -21,6 +21,10 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/** @file drm_vm.c
+ * Support code for mmaping of DRM maps.
+ */
+
 #include "drmP.h"
 #include "drm.h"