Final documentation to the AGPGART module.

8 files changed, 771 insertions, 180 deletions

diff --git a/src/kernel/agpgart/Doxyfile b/src/kernel/agpgart/Doxyfile
index 4ccae88dbf..3b21b8541c 100644
--- a/src/kernel/agpgart/Doxyfile
+++ b/src/kernel/agpgart/Doxyfile
@@ -377,7 +377,7 @@ EXCLUDE_SYMLINKS       = NO
 # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude 
 # certain files from those directories.
 
-EXCLUDE_PATTERNS       = 
+EXCLUDE_PATTERNS       = i810_agp.c
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or 
 # directories that contain example code fragments that are included (see 
@@ -809,7 +809,7 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled 
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES 
 # then the macro expansion is limited to the macros specified with the 
@@ -842,7 +842,19 @@ INCLUDE_FILE_PATTERNS  =
 # omitted =1 is assumed.
 
 PREDEFINED             = \
-			__KERNEL__
+			__KERNEL__ \
+			"__devinit=" \
+			"__init=" \
+			"__devinitdata=" \
+			"__initdata=" \
+			"MODULE_AUTHOR()=" \
+			"MODULE_LICENSE()=" \
+			"MODULE_DESCRIPTION()=" \
+			"MODULE_DEVICE_TABLE()=" \
+			"MODULE_PARM()=" \
+			"module_init()=" \
+			"module_exit()=" \
+			"EXPORT_SYMBOL()="
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 
diff --git a/src/kernel/agpgart/agp.c b/src/kernel/agpgart/agp.c
index 61e9ecd465..2345e6e0bf 100644
--- a/src/kernel/agpgart/agp.c
+++ b/src/kernel/agpgart/agp.c
@@ -1,6 +1,6 @@
 /**
  * \file agp.c
- * \brief AGPGART module generic backend
+ * AGPGART module generic backend
  * \version 0.99
  * 
  * \author Jeff Hartmann
@@ -60,16 +60,21 @@ EXPORT_SYMBOL(agp_enable);
 EXPORT_SYMBOL(agp_backend_acquire);
 EXPORT_SYMBOL(agp_backend_release);
 
+/** Global AGP bridge data structure */
 struct agp_bridge_data agp_bridge = { type: NOT_SUPPORTED };
+/** Whether to try the vendor \e generic bridge backend for unsupported
+ * devices. */
 static int agp_try_unsupported __initdata = 0;
 
 int agp_memory_reserved;
+/** GATT table */
 __u32 *agp_gatt_table; 
 
 /** 
  * Acquire the AGP backend. 
  *
- * \return zero on success or a negative number on failure.
+ * \return zero if the caller owns the AGP backend, or -EBUSY if the AGP is in
+ * use.
  *
  * If the AGP bridge type is supported tries to atomically set the
  * agp_bridge_data::agp_in_use in agp_bridge.
@@ -94,10 +99,13 @@ int agp_backend_acquire(void)
 /** 
  * Release the AGP backend. 
  *
+ * The caller must insure that the graphics
+ * aperture translation table is read for use
+ * by another entity.  (Ensure that all memory
+ * it bound is unbound.)
+ *
  * If the AGP bridge type is supported atomically resets the
  * agp_bridge_data::agp_in_use.
- *
- * \sa agp_backend_release().
  */
 void agp_backend_release(void)
 {
@@ -192,6 +200,12 @@ agp_memory *agp_create_memory(int scratch_pages)
 /**
  * Free AGP memory.
  *
+ * This function frees memory associated with
+ * an agp_memory pointer.  It is the only function
+ * that can be called when the backend is not owned
+ * by the caller.  (So it can free memory on client
+ * death.)
+ *
  * \param curr pointer to the agp_memory resource to free.
  *
  * Unbinds the memory if currently bound. If agp_memory::type is not zero then
@@ -231,8 +245,13 @@ void agp_free_memory(agp_memory * curr)
 /**
  * Allocate AGP memory.
  *
+ * This function allocates a group of pages of
+ * a certain type.
+ * 
  * \param page_count number of pages to allocate.
- * \param type type.
+ * \param type type of memory to be allocated.  Every agp bridge device will
+ * allow you to allocate AGP_NORMAL_MEMORY which maps to physical ram.  Any
+ * other type is device dependant.
  * \return pointer to a agp_memory structure on success, or NULL on failure.
  *
  * If \p type is not zero then the call is dispatched to the
@@ -335,7 +354,12 @@ static int agp_return_size(void)
 /**
  * Routine to copy over information structure.
  *
- * \param info information structure.
+ * This function copies information about the
+ * agp bridge device and the state of the agp
+ * backend into an agp_kern_info pointer.
+ * 
+ * \param info agp_kern_info pointer.  The caller should insure that
+ * this pointer is valid.
  * \return zero on success, or a negative number on failure (bridge type not supported).
  * 
  * Copies over the information from agp_bridge into \p info.
@@ -379,10 +403,13 @@ int agp_copy_info(agp_kern_info * info)
 /**
  * Bind AGP memory.
  *
- * \param curr AGP memory to bind.
- * \param pg_start start page.
- *
- * \return zero on success or a negative number on failure.
+ * This function binds an agp_memory structure
+ * into the graphics aperture translation table.
+ * 
+ * \param curr agp_memory pointer.
+ * \param pg_start offset into the graphics aperture translation table.
+ * \return zero on success, -EINVAL if the pointer is NULL, or -EBUSY if the
+ * area of the table requested is already in use.
  *
  * Flushes the cache if not done before and calls the
  * agp_bridge_data::insert_memory() method to insert it into the GATT.
@@ -412,9 +439,13 @@ int agp_bind_memory(agp_memory * curr, off_t pg_start)
 /**
  * Unbind AGP memory.
  *
- * \param curr AGP memory to unbind.
- *
- * \return zero on success or a negative number on failure.
+ * This function removes an agp_memory structure
+ * from the graphics aperture translation table.
+ * 
+ * \param curr agp_memory pointer.
+ * \return zero on success, -EINVAL if this piece of agp_memory is not
+ * currently bound to the graphics aperture translation table or if the
+ * agp_memory pointer is NULL.
  *
  * Calls the agp_bridge_data::remove_memory() method to remove the memory from
  * the GATT.
@@ -871,7 +902,7 @@ void agp_generic_free_by_type(agp_memory * curr)
 /*@{*/
 
 /**
- * \sa agp_bridge_data::alloc_page.
+ * \sa agp_bridge_data::agp_alloc_page.
  */
 void *agp_generic_alloc_page(void)
 {
@@ -890,7 +921,7 @@ void *agp_generic_alloc_page(void)
 }
 
 /**
- * \sa agp_bridge_data::destroy_page.
+ * \sa agp_bridge_data::agp_destroy_page.
  */
 void agp_generic_destroy_page(void *addr)
 {
@@ -910,9 +941,10 @@ void agp_generic_destroy_page(void *addr)
 /*@}*/
 
 /**
- * Enable the AGP bus.
- *
- * \param mode AGP mode.
+ * This function initializes the agp point-to-point
+ * connection.
+ * 
+ * \param mode AGP mode register.
  *
  * Calls agp_bridge_data::agp_enable().
  */
@@ -929,7 +961,7 @@ void agp_enable(u32 mode)
  * 
  * \note All chipsets for a single vendor MUST be grouped together
  */
-static struct {
+static struct _agp_bridge_info {
 	unsigned short device_id;	/**< device id (first, to make table easier to read) */
 	unsigned short vendor_id;	/**< vendor ID */
 	enum chipset_type chipset;	/**< chipset */
@@ -1367,6 +1399,10 @@ static struct {
  * \param pdev PCI device.
  * \return zero on success, or a negative number on failure.
  * 
+ * Searches agp_bridge_info for a matching vendor and device ID's and calls the
+ * function in _agp_bridge_info::chipset_setup field. If the user requested
+ * (agp_try_unsupported is set) and there is a \e generic bridge entry (zero
+ * device ID) try it.
  */
 static int __init agp_lookup_host_bridge (struct pci_dev *pdev)
 {
@@ -1783,6 +1819,17 @@ static void agp_backend_cleanup(void)
 	}
 }
 
+/**
+ * Power management callback.
+ * 
+ * \param dev power management device structure.
+ * \param rq request.
+ * \param data auxiliary data. (Not referenced.)
+ * \return zero on success or a negative number on failure.
+ *
+ * Calls agp_bridge_data::suspend or agp_bridge_data::resume according with the
+ * request.
+ */
 static int agp_power(struct pm_dev *dev, pm_request_t rq, void *data)
 {
 	switch(rq)
@@ -1799,6 +1846,9 @@ static int agp_power(struct pm_dev *dev, pm_request_t rq, void *data)
 extern int agp_frontend_initialize(void);
 extern void agp_frontend_cleanup(void);
 
+/**
+ * \copydoc drm_agp_t
+ */
 static const drm_agp_t drm_agp = {
 	&agp_free_memory,
 	&agp_allocate_memory,
@@ -1837,6 +1887,9 @@ static int agp_probe (struct pci_dev *dev, const struct pci_device_id *ent)
 	return 0;
 }
 
+/**
+ * PCI device table.  Has a single entry matching any PCI device.
+ */
 static struct pci_device_id agp_pci_table[] __initdata = {
 	{
 	.class		= (PCI_CLASS_BRIDGE_HOST << 8),
@@ -1851,12 +1904,23 @@ static struct pci_device_id agp_pci_table[] __initdata = {
 
 MODULE_DEVICE_TABLE(pci, agp_pci_table);
 
+/**
+ * PCI driver structure.
+ */
 static struct pci_driver agp_pci_driver = {
 	.name		= "agpgart",
 	.id_table	= agp_pci_table,
 	.probe		= agp_probe,
 };
 
+/**
+ * Module initialization.
+ *
+ * \return zero on success or a negative number on failure.
+ *
+ * Calls pci_module_init() with agp_pci_driver, and on failure sets
+ * agp_bridge_data::type as not supported.
+ */
 int __init agp_init(void)
 {
 	int ret_val;
@@ -1872,6 +1936,13 @@ int __init agp_init(void)
 	return 0;
 }
 
+/**
+ * Module exit.
+ *
+ * Unregisters the PCI device and, for supported chips, unregister the power
+ * management callback function, calls the frontend and backend cleanup
+ * routines and unregister the inter module symbol drm_agp.
+ */
 static void __exit agp_cleanup(void)
 {
 	pci_unregister_driver(&agp_pci_driver);
diff --git a/src/kernel/agpgart/agp.h b/src/kernel/agpgart/agp.h
index 443dd8c5e3..22d4cbfa70 100644
--- a/src/kernel/agpgart/agp.h
+++ b/src/kernel/agpgart/agp.h
@@ -1,6 +1,6 @@
 /**
  * \file agp.h
- * \brief AGPGART module generic backend
+ * AGPGART module generic backend
  * \version 0.99
  * 
  * \author Jeff Hartmann
@@ -55,7 +55,7 @@ void agp_generic_resume(void);
 void agp_free_key(int key);
 /*@}*/
 
-/** \name chipset specific init routines. */
+/** \name Chipset specific initialization routines */
 /*@{*/
 int __init ali_generic_setup (struct pci_dev *pdev);
 int __init amd_irongate_setup (struct pci_dev *pdev);
@@ -81,6 +81,10 @@ int __init via_generic_setup (struct pci_dev *pdev);
 #define PFX			AGPGART_MODULE_NAME ": "
 
 
+/**
+ * \fn global_cache_flush
+ * Calls flush_agp_cache() on all processors. 
+ */
 #ifdef CONFIG_SMP
 static void ipi_handler(void *null)
 {
@@ -161,30 +165,32 @@ struct aper_size_info_fixed {
 
 /**
  * AGP bridge data.
- *
- * \sa agp_bridge.
  */
 struct agp_bridge_data {
 	struct agp_version *version;
 	void *aperture_sizes;	/**< All aperture sizes. \sa agp_bridge_data::size_type */
 	void *previous_size;	/**< Previous aperture size. \sa agp_bridge_data::size_type */
-	void *current_size;	/**< Current aperture size. One of agp_bridge_data::aperture_sizes. \sa agp_bridge_data::size_type */
+	void *current_size;	/**< Current aperture size. One of
+				  agp_bridge_data::aperture_sizes. \sa
+				  agp_bridge_data::size_type */
 	void *dev_private_data;
-	struct pci_dev *dev;
+	struct pci_dev *dev;	/**< PCI device */
 	struct gatt_mask *masks;
 	unsigned long *gatt_table;
 	unsigned long *gatt_table_real;
-	unsigned long scratch_page;	/**< scratch page used as initial value in the free GATT entries */
+	unsigned long scratch_page;	/**< scratch page used as default value
+					  in empty GATT entries */
 	unsigned long gart_bus_addr;
 	unsigned long gatt_bus_addr;
 	u32 mode;	/**< bus mode */
 	enum chipset_type type;
 	enum aper_size_type size_type;	/**< type of agp_bridge_data::aperture_sizes */
-	unsigned long *key_list;
+	unsigned long *key_list;	/**< bit array for the keys */
 	atomic_t current_memory_agp;
-	atomic_t agp_in_use;
+	atomic_t agp_in_use;	/**< whether the AGP device has been acquired */
 	int max_memory_agp;	/**< maximum AGP memory in number of pages */
-	int needs_scratch_page; /**< whether to allocate a scratch page in agp_bridge_data::scratch_page */
+	int needs_scratch_page; /**< whether to allocate a scratch page in
+				  agp_bridge_data::scratch_page */
 	int aperture_size_idx;
 	int num_aperture_sizes;
 	int num_of_masks;
@@ -205,8 +211,12 @@ struct agp_bridge_data {
 	void (*agp_enable) (u32 mode);
 
 	void (*cleanup) (void);
+
+	/** Flush the table */
 	void (*tlb_flush) (agp_memory *);
+	
 	unsigned long (*mask_memory) (unsigned long, int);
+
 	void (*cache_flush) (void);
 
 	/** 
@@ -283,14 +293,22 @@ struct agp_bridge_data {
 	/*@}*/
 };
 
+/** Write a 64 bit register */
 #define OUTREG64(mmap, addr, val)	__raw_writeq((val), (mmap)+(addr))
+/** Write a 32 bit register */
 #define OUTREG32(mmap, addr, val)	__raw_writel((val), (mmap)+(addr))
+/** Write a 16 bit register */
 #define OUTREG16(mmap, addr, val)	__raw_writew((val), (mmap)+(addr))
+/** Write a 8 bit register */
 #define OUTREG8(mmap, addr, val)	__raw_writeb((val), (mmap)+(addr))
 
+/** Read a 64 bit register */
 #define INREG64(mmap, addr)		__raw_readq((mmap)+(addr))
+/** Read a 32 bit register */
 #define INREG32(mmap, addr)		__raw_readl((mmap)+(addr))
+/** Read a 16 bit register */
 #define INREG16(mmap, addr)		__raw_readw((mmap)+(addr))
+/** Read a 8 bit register */
 #define INREG8(mmap, addr)		__raw_readb((mmap)+(addr))
 
 #define KB(x)	((x) * 1024)
@@ -298,20 +316,41 @@ struct agp_bridge_data {
 #define GB(x)	(MB (KB (x)))
 
 #define CACHE_FLUSH	agp_bridge.cache_flush
+/** Aperture size cast -- u8 */
 #define A_SIZE_8(x)	((struct aper_size_info_8 *) x)
+/** Aperture size cast -- u16 */
 #define A_SIZE_16(x)	((struct aper_size_info_16 *) x)
+/** Aperture size cast -- u32 */
 #define A_SIZE_32(x)	((struct aper_size_info_32 *) x)
+/** Aperture size cast -- 2 level */
 #define A_SIZE_LVL2(x)	((struct aper_size_info_lvl2 *) x)
+/** Aperture size cast -- fixed */
 #define A_SIZE_FIX(x)	((struct aper_size_info_fixed *) x)
+/** Indexing of agp_bridge_data::aperture_sizes -- u8 */
 #define A_IDX8()	(A_SIZE_8(agp_bridge.aperture_sizes) + i)
+/** Indexing of agp_bridge_data::aperture_sizes -- u16 */
 #define A_IDX16()	(A_SIZE_16(agp_bridge.aperture_sizes) + i)
+/** Indexing of agp_bridge_data::aperture_sizes -- u32 */
 #define A_IDX32()	(A_SIZE_32(agp_bridge.aperture_sizes) + i)
+/** Indexing of agp_bridge_data::aperture_sizes -- 2 level */
 #define A_IDXLVL2()	(A_SIZE_LVL2(agp_bridge.aperture_sizes) + i)
+/** Indexing of agp_bridge_data::aperture_sizes -- fixed */
 #define A_IDXFIX()	(A_SIZE_FIX(agp_bridge.aperture_sizes) + i)
+
 #define MAXKEY		(4096 * 32)
 
+/** 
+ * Check for an empty page. 
+ *
+ * \param p page.
+ * \return non-zero if \p p is empty, or zero otherwise.
+ *
+ * A page is empty if it's zero or points to the scratch page,
+ * agp_bridge_data::scratch_page.
+ */
 #define PGE_EMPTY(p)	(!(p) || (p) == (unsigned long) agp_bridge.scratch_page)
 
+
 /** \name Intel registers */
 /*@{*/
 #define INTEL_APBASE	0x10
@@ -333,7 +372,7 @@ struct agp_bridge_data {
 #define INTEL_I460_GATT_COHERENT	(1UL << 25)
 /*@}*/
 
-/** \name  Intel i830 registers */
+/** \name Intel i830 registers */
 /*@{*/
 #define I830_GMCH_CTRL			0x52
 #define I830_GMCH_ENABLED		0x4
@@ -350,11 +389,11 @@ struct agp_bridge_data {
 #define I830_RDRAM_ND(x)		(((x) & 0x20) >> 5)
 #define I830_RDRAM_DDT(x)		(((x) & 0x18) >> 3)
 
-/* This one is for I830MP w. an external graphic card */
+/** This one is for I830MP with an external graphic card */
 #define INTEL_I830_ERRSTS	0x92
 /*@}*/
 
-/** \name Intel 815 register */
+/** \name Intel 815 registers */
 /*@{*/
 #define INTEL_815_APCONT	0x51
 #define INTEL_815_ATTBASE_MASK	~0x1FFFFFFF
@@ -412,7 +451,7 @@ struct agp_bridge_data {
 
 
 
-/** \name VIA register */
+/** \name VIA registers */
 /*@{*/
 #define VIA_APBASE	0x10
 #define VIA_GARTCTRL	0x80
@@ -478,16 +517,12 @@ struct agp_bridge_data {
 #define SVWRKS_MMBASE		0x14
 #define SVWRKS_CACHING		0x4b
 #define SVWRKS_FEATURE		0x68
-/*@}*/
 
-/** \name func 1 registers */
-/*@{*/
+/* func 1 registers */
 #define SVWRKS_AGP_ENABLE	0x60
 #define SVWRKS_COMMAND		0x04
-/*@}*/
 
-/** \name Memory mapped registers */
-/*@{*/
+/* Memory mapped registers */
 #define SVWRKS_GART_CACHE	0x02
 #define SVWRKS_GATTBASE		0x04
 #define SVWRKS_TLBFLUSH		0x10
diff --git a/src/kernel/agpgart/agp_backend.h b/src/kernel/agpgart/agp_backend.h
index 65390109ec..fb8203b311 100644
--- a/src/kernel/agpgart/agp_backend.h
+++ b/src/kernel/agpgart/agp_backend.h
@@ -1,6 +1,6 @@
 /**
  * \file agp_backend.h
- * \brief AGPGART module backend
+ * AGPGART module backend
  * \version 0.99
  * 
  * \author Jeff Hartmann
@@ -121,7 +121,7 @@ typedef struct _agp_kern_info {
  * block of agp memory.
  */
 typedef struct _agp_memory {
-	int key;
+	int key;	/** hash key */
 	struct _agp_memory *next;
 	struct _agp_memory *prev;
 	size_t page_count;
@@ -136,99 +136,25 @@ typedef struct _agp_memory {
 
 #define AGP_NORMAL_MEMORY 0
 
-/**
- * This function frees memory associated with
- * an agp_memory pointer.  It is the only function
- * that can be called when the backend is not owned
- * by the caller.  (So it can free memory on client
- * death.)
- * 
- * It takes an agp_memory pointer as an argument.
- */
 extern void agp_free_memory(agp_memory *);
-
-/**
- * This function allocates a group of pages of
- * a certain type.
- * 
- * It takes a size_t argument of the number of pages, and
- * an u32 argument of the type of memory to be allocated.  
- * Every agp bridge device will allow you to allocate 
- * AGP_NORMAL_MEMORY which maps to physical ram.  Any other
- * type is device dependant.
- * 
- * \return NULL whenever memory is unavailable.
- * 
- */
 extern agp_memory *agp_allocate_memory(size_t, u32);
-
-/**
- * This function copies information about the
- * agp bridge device and the state of the agp
- * backend into an agp_kern_info pointer.
- * 
- * It takes an agp_kern_info pointer as an
- * argument.  The caller should insure that
- * this pointer is valid.
- */
 extern int agp_copy_info(agp_kern_info *);
-
-/**
- * This function binds an agp_memory structure
- * into the graphics aperture translation table.
- * 
- * It takes an agp_memory pointer and an offset into
- * the graphics aperture translation table as arguments
- * 
- * It returns -EINVAL if the pointer == NULL.
- * It returns -EBUSY if the area of the table
- * requested is already in use.
- */
 extern int agp_bind_memory(agp_memory *, off_t);
-
-/**
- * This function removes an agp_memory structure
- * from the graphics aperture translation table.
- * 
- * It takes an agp_memory pointer as an argument.
- * 
- * It returns -EINVAL if this piece of agp_memory
- * is not currently bound to the graphics aperture
- * translation table or if the agp_memory 
- * pointer == NULL
- */
 extern int agp_unbind_memory(agp_memory *);
-
-/* 
- * This function initializes the agp point-to-point
- * connection.
- * 
- * It takes an agp mode register as an argument
- */
 extern void agp_enable(u32);
-
-/**
- * This function attempts to acquire the agp
- * backend.
- * 
- * returns -EBUSY if agp is in use,
- * returns 0 if the caller owns the agp backend
- */
 extern int agp_backend_acquire(void);
 
-/**
- * This function releases the lock on the agp
- * backend.
- * 
- * The caller must insure that the graphics
- * aperture translation table is read for use
- * by another entity.  (Ensure that all memory
- * it bound is unbound.)
- * 
- */
 extern void agp_backend_release(void);
 
 
+/**
+ * Interface between DRM and AGP code.  When AGP initializes, it makes
+ * this structure available via inter_module_register(), DRM might
+ * use it.
+ * 
+ * \author Keith Owens <kaos@ocs.com.au> 
+ * \date 28 Oct 2000.
+ */
 typedef struct {
 	void       (*free_memory)(agp_memory *);
 	agp_memory *(*allocate_memory)(size_t, u32);
@@ -240,15 +166,6 @@ typedef struct {
 	int        (*copy_info)(agp_kern_info *);
 } drm_agp_t;
 
-
-/**
- * Interface between DRM and AGP code.  When AGP initializes, it makes
- * the above structure available via inter_module_register(), DRM might
- * use it.
- * 
- * \author Keith Owens <kaos@ocs.com.au> 
- * \date 28 Oct 2000.
- */
 extern const drm_agp_t *drm_agp_p;
 
 #endif				/* _AGP_BACKEND_H */
diff --git a/src/kernel/agpgart/agpgart.h b/src/kernel/agpgart/agpgart.h
index 45f10dc178..6819e228fa 100644
--- a/src/kernel/agpgart/agpgart.h
+++ b/src/kernel/agpgart/agpgart.h
@@ -1,6 +1,6 @@
 /**
  * \file agpgart.h
- * \brief AGPGART module
+ * AGPGART module
  * \version 0.99
  * 
  * \author Jeff Hartmann
@@ -119,8 +119,11 @@ typedef struct _agp_unbind {
 
 #define AGPGART_MINOR 175
 
+/** Unlocks the AGP device */
 #define AGP_UNLOCK()      	up(&(agp_fe.agp_mutex));
+/** Locks the AGP device */
 #define AGP_LOCK()    		down(&(agp_fe.agp_mutex));
+/** Initializes the AGP device lock */
 #define AGP_LOCK_INIT() 	sema_init(&(agp_fe.agp_mutex), 1)
 
 #ifndef _AGP_BACKEND_H
@@ -131,6 +134,7 @@ struct _agp_version {
 
 #endif
 
+/** Information ioctl argument */
 typedef struct _agp_info {
 	struct agp_version version;	/**< version of the driver        */
 	u32 bridge_id;		/**< bridge vendor/device         */
@@ -142,31 +146,35 @@ typedef struct _agp_info {
 	size_t pg_used;		/**< current pages used           */
 } agp_info;
 
+/** Setup ioctl argument */
 typedef struct _agp_setup {
 	u32 agp_mode;		/**< mode info of bridge          */
 } agp_setup;
 
-/*
- * The "prot" down below needs still a "sleep" flag somehow ...
- */
+/** Segment (user). */
 typedef struct _agp_segment {
 	off_t pg_start;		/**< starting page to populate    */
 	size_t pg_count;	/**< number of pages              */
-	int prot;		/**< prot flags for mmap          */
+	int prot;		/**< prot flags for mmap.
+				 * \todo still needs a "sleep" flag somehow...
+				 * */
 } agp_segment;
 
+/** Segment (private) */
 typedef struct _agp_segment_priv {
-	off_t pg_start;
-	size_t pg_count;
-	pgprot_t prot;
+	off_t pg_start;		/**< starting page to populate    */
+	size_t pg_count;	/**< number of pages              */
+	pgprot_t prot;		/**< memory protection flags      */
 } agp_segment_priv;
 
+/** Reserve ioctl argument */
 typedef struct _agp_region {
 	pid_t pid;		/**< pid of process               */
 	size_t seg_count;	/**< number of segments           */
 	struct _agp_segment *seg_list;
 } agp_region;
 
+/** Allocate ioctl argument */
 typedef struct _agp_allocate {
 	int key;		/**< tag of allocation            */
 	size_t pg_count;	/**< number of pages              */
@@ -177,51 +185,60 @@ typedef struct _agp_allocate {
 				 * table)                        */
 } agp_allocate;
 
+/** Bind ioctl argument */
 typedef struct _agp_bind {
 	int key;		/**< tag of allocation            */
 	off_t pg_start;		/**< starting page to populate    */
 } agp_bind;
 
+/** Unbind ioctl argument */
 typedef struct _agp_unbind {
 	int key;		/**< tag of allocation            */
 	u32 priority;		/**< priority for paging out      */
 } agp_unbind;
 
+/** AGP client */
 typedef struct _agp_client {
 	struct _agp_client *next;
 	struct _agp_client *prev;
-	pid_t pid;
-	int num_segments;
-	agp_segment_priv **segments;
+	pid_t pid;		/**< process id */
+	int num_segments;	/**< number of segments */
+	agp_segment_priv **segments;	/**< segment array */
 } agp_client;
 
+/** AGP controller. */
 typedef struct _agp_controller {
 	struct _agp_controller *next;
 	struct _agp_controller *prev;
-	pid_t pid;
-	int num_clients;
-	agp_memory *pool;
-	agp_client *clients;
+	pid_t pid;		/**< process id */
+	int num_clients;	/**< number of clients */
+	agp_memory *pool;	/**< doubly linked memory pool */
+	agp_client *clients;	/**< doubly linked client list */
 } agp_controller;
 
+/** \name File flags */
+/*@{*/
 #define AGP_FF_ALLOW_CLIENT		0
 #define AGP_FF_ALLOW_CONTROLLER 	1
 #define AGP_FF_IS_CLIENT		2
 #define AGP_FF_IS_CONTROLLER		3
 #define AGP_FF_IS_VALID 		4
+/*@}*/
 
+/** File private data. */
 typedef struct _agp_file_private {
 	struct _agp_file_private *next;
 	struct _agp_file_private *prev;
-	pid_t my_pid;
-	long access_flags;	/**< long req'd for set_bit --RR */
+	pid_t my_pid;		/**< process id */
+	long access_flags;	/**< long required for set_bit --RR */
 } agp_file_private;
 
+/** Frontend data. */
 struct agp_front_data {
-	struct semaphore agp_mutex;
+	struct semaphore agp_mutex;	/**< device mutex. \sa #AGP_INIT, #AGP_LOCK and #AGP_UNLOCK */
 	agp_controller *current_controller;
 	agp_controller *controllers;
-	agp_file_private *file_priv_list;
+	agp_file_private *file_priv_list;	/**< file private data doubly linked list */
 	u8 used_by_controller;
 	u8 backend_acquired;
 };
diff --git a/src/kernel/agpgart/frontend.c b/src/kernel/agpgart/frontend.c
index e84cc0f34c..f11da4b95a 100644
--- a/src/kernel/agpgart/frontend.c
+++ b/src/kernel/agpgart/frontend.c
@@ -1,6 +1,6 @@
 /**
  * \file frontend.c
- * \brief AGPGART module frontend
+ * AGPGART module frontend
  * \version 0.99
  * 
  * \author Jeff Hartmann
@@ -44,8 +44,17 @@
 
 #include "agp.h"
 
+/** Global AGP frontend data. */
 static struct agp_front_data agp_fe;
 
+/**
+ * Find a agp_memory by its allocation tag.
+ *
+ * \param key allocation tag.
+ * \return pointer to the agp_memory on success or NULL on failure.
+ *
+ * Walks trhough the agp_controller::pool list until finding a matching key.
+ */
 static agp_memory *agp_find_mem_by_key(int key)
 {
 	agp_memory *curr;
@@ -65,6 +74,13 @@ static agp_memory *agp_find_mem_by_key(int key)
 	return NULL;
 }
 
+/**
+ * Removes a entry from its memory pool.
+ *
+ * \param temp pointer to the agp_memory structure.
+ * 
+ * Unlinks the entry from the doubly linked list.
+ */
 static void agp_remove_from_pool(agp_memory * temp)
 {
 	agp_memory *prev;
@@ -91,12 +107,26 @@ static void agp_remove_from_pool(agp_memory * temp)
 	}
 }
 
-/*
- * Routines for managing each client's segment list -
- * These routines handle adding and removing segments
- * to each auth'ed client.
+/**
+ * \name Routines for managing each client's segment list
+ *
+ * These routines handle adding and removing segments to each authorized
+ * client.
  */
+/*@{*/
 
+/**
+ * Find a segment in the client information.
+ *
+ * \param client client information.
+ * \param offset offset.
+ * \param size size.
+ * \param page_prot memory protection flags .
+ * \return pointer to the segment private data on success or NULL on failure.
+ *
+ * Walks through every segment in \p client until find one with a macthing
+ * offset, size and memory protection flags.
+ */
 static agp_segment_priv *agp_find_seg_in_client(const agp_client * client,
 						unsigned long offset,
 					    int size, pgprot_t page_prot)
@@ -120,6 +150,13 @@ static agp_segment_priv *agp_find_seg_in_client(const agp_client * client,
 	return NULL;
 }
 
+/**
+ * Remove the segment list from the client data.
+ *
+ * \param client client information.
+ *
+ * Frees the agp_client::segments and its  first entry if not null.
+ */
 static void agp_remove_seg_from_client(agp_client * client)
 {
 	if (client->segments != NULL) {
@@ -130,6 +167,16 @@ static void agp_remove_seg_from_client(agp_client * client)
 	}
 }
 
+/**
+ * Add a segment list to the client data.
+ *
+ * \param client client information.
+ * \param seg segment list.
+ * \param num_segments number of segments in the list.
+ *
+ * Updates agp_client::segments, calling agp_remove_seg_from_client() if there
+ * is a previous value.
+ */
 static void agp_add_seg_to_client(agp_client * client,
 			       agp_segment_priv ** seg, int num_segments)
 {
@@ -144,18 +191,25 @@ static void agp_add_seg_to_client(agp_client * client,
 	client->segments = seg;
 }
 
-/* Originally taken from linux/mm/mmap.c from the array
+/**
+ * Originally taken from linux/mm/mmap.c from the array
  * protection_map.
+ * 
  * The original really should be exported to modules, or 
  * some routine which does the conversion for you 
  */
-
 static const pgprot_t my_protect_map[16] =
 {
 	__P000, __P001, __P010, __P011, __P100, __P101, __P110, __P111,
 	__S000, __S001, __S010, __S011, __S100, __S101, __S110, __S111
 };
 
+/** 
+ * Convert the mmap() memory protection flags into a pgprot_t.
+ * 
+ * \param prot memory protection flags as used by mmap().
+ * \return a pgprot_t structure.
+ */
 static pgprot_t agp_convert_mmap_flags(int prot)
 {
 #define _trans(x,bit1,bit2) \
@@ -175,6 +229,16 @@ static pgprot_t agp_convert_mmap_flags(int prot)
 	return temp;
 }
 
+/** 
+ * Create a segment.
+ * 
+ * \param client client information.
+ * \param region memory region.
+ * \return zero on success or a negative number on failure.
+ *
+ * Allocates a new segment list to hold the segments in \p region, copies the
+ * segments, and adds it to the client via agp_add_seg_to_client().
+ */
 static int agp_create_segment(agp_client * client, agp_region * region)
 {
 	agp_segment_priv **ret_seg;
@@ -208,9 +272,18 @@ static int agp_create_segment(agp_client * client, agp_region * region)
 	return 0;
 }
 
-/* End - Routines for managing each client's segment list */
+/*@}*/
+
 
-/* This function must only be called when current_controller != NULL */
+/**
+ * Insert memory in the current controller pool.
+ * 
+ * This function must only be called when current_controller != NULL 
+ * 
+ * \param temp memory to insert.
+ * 
+ * Links \p temp into agp_front_data::pool.
+ */
 static void agp_insert_into_pool(agp_memory * temp)
 {
 	agp_memory *prev;
@@ -225,8 +298,17 @@ static void agp_insert_into_pool(agp_memory * temp)
 }
 
 
-/* File private list routines */
+/** \name File private list routines */
+/*@{*/
 
+/**
+ * Find the file private data for the given process id.
+ *
+ * \param pid process id.
+ * \return pointer to the file private data on success or NULL on failure.
+ * 
+ * Searches for the given process id on the agp_front_data::file_priv_list.
+ */
 agp_file_private *agp_find_private(pid_t pid)
 {
 	agp_file_private *curr;
@@ -243,6 +325,13 @@ agp_file_private *agp_find_private(pid_t pid)
 	return NULL;
 }
 
+/** 
+ * Insert the file private data.
+ *
+ * \param priv file private data.
+ *
+ * Inserts \p priv into agp_front_data::file_priv_list.
+ */
 void agp_insert_file_private(agp_file_private * priv)
 {
 	agp_file_private *prev;
@@ -256,6 +345,13 @@ void agp_insert_file_private(agp_file_private * priv)
 	agp_fe.file_priv_list = priv;
 }
 
+/** 
+ * Remove the file private data.
+ *
+ * \param priv file private data.
+ *
+ * Removes \p priv from agp_front_data::file_priv_list.
+ */
 void agp_remove_file_private(agp_file_private * priv)
 {
 	agp_file_private *next;
@@ -278,11 +374,19 @@ void agp_remove_file_private(agp_file_private * priv)
 	}
 }
 
-/* End - File flag list routines */
+/*@}*/
+
+
+/**
+ * \name Wrappers for agp_free_memory() and agp_allocate_memory()
+ */
+/*@{*/
 
-/* 
- * Wrappers for agp_free_memory & agp_allocate_memory 
- * These make sure that internal lists are kept updated.
+/**
+ * Wrappers for agp_free_memory().
+ *
+ * Makes sure that internal lists are kept updated by calling
+ * agp_remove_from_pool().
  */
 static void agp_free_memory_wrap(agp_memory * memory)
 {
@@ -290,6 +394,12 @@ static void agp_free_memory_wrap(agp_memory * memory)
 	agp_free_memory(memory);
 }
 
+/**
+ * Wrappers for agp_allocate_memory().
+ *
+ * Makes sure that internal lists are kept updated by calling
+ * agp_insert_into_pool().
+ */
 static agp_memory *agp_allocate_memory_wrap(size_t pg_count, u32 type)
 {
 	agp_memory *memory;
@@ -303,11 +413,22 @@ static agp_memory *agp_allocate_memory_wrap(size_t pg_count, u32 type)
 	return memory;
 }
 
-/* Routines for managing the list of controllers -
- * These routines manage the current controller, and the list of
- * controllers
+/*@}*/
+
+/**
+ * \name Routines for managing the list of controllers
+ * 
+ * These routines manage the current controller, and the list of controllers
  */
 
+/**
+ * Find controller by process id.
+ *
+ * \param id process id of the controller.Insert
+ * \return pointer to the controller on success or NULL on failure.
+ *
+ * Searches for the given process id in agp_front_data:controllers list.
+ */
 static agp_controller *agp_find_controller_by_pid(pid_t id)
 {
 	agp_controller *controller;
@@ -324,6 +445,14 @@ static agp_controller *agp_find_controller_by_pid(pid_t id)
 	return NULL;
 }
 
+/**
+ * Create a controller structure.
+ *
+ * \param id process id of the new controller.
+ * \return pointer to the agp_controller structure on success, or NULL on failure.
+ * 
+ * Allocate and initialize a agp_controller structure.
+ */
 static agp_controller *agp_create_controller(pid_t id)
 {
 	agp_controller *controller;
@@ -339,6 +468,14 @@ static agp_controller *agp_create_controller(pid_t id)
 	return controller;
 }
 
+/** 
+ * Insert a controller into the frontend data.
+ *
+ * \param controller controller information.
+ * \return always zero.
+ *
+ * Inserts \p controller into agp_front_data::controllers.
+ */
 static int agp_insert_controller(agp_controller * controller)
 {
 	agp_controller *prev_controller;
@@ -354,6 +491,13 @@ static int agp_insert_controller(agp_controller * controller)
 	return 0;
 }
 
+/**
+ * Remove all clients associated with a given controller.
+ *
+ * For each client in \p controller removes its segments, clears the valid and
+ * client flags from the file private data, and frees the client structure
+ * itself.
+ */ 
 static void agp_remove_all_clients(agp_controller * controller)
 {
 	agp_client *client;
@@ -377,6 +521,11 @@ static void agp_remove_all_clients(agp_controller * controller)
 	}
 }
 
+/**
+ * Remove all memory associated with a given controller.
+ *
+ * Calls agp_free_memory_wrap() for each memory entry in agp_controller::pool.
+ */
 static void agp_remove_all_memory(agp_controller * controller)
 {
 	agp_memory *memory;
@@ -391,6 +540,16 @@ static void agp_remove_all_memory(agp_controller * controller)
 	}
 }
 
+/**
+ * Remove a controller.
+ *
+ * \param controller controller to remove.
+ * \return always zero.
+ * 
+ * Unlinks the controller from agp_front_data::controllers and frees the
+ * controller structure. If removing the current controller additionally
+ * releases the backend and unsets the current controller.
+ */
 static int agp_remove_controller(agp_controller * controller)
 {
 	agp_controller *prev_controller;
@@ -423,6 +582,14 @@ static int agp_remove_controller(agp_controller * controller)
 	return 0;
 }
 
+/**
+ * Make a controller current.
+ *
+ * \param controller controller to make current.
+ *
+ * Sets the valid and client flags for each client file and points the current
+ * controller, agp_front_data::current_controller, to \p controller.
+ */
 static void agp_controller_make_current(agp_controller * controller)
 {
 	agp_client *clients;
@@ -444,6 +611,15 @@ static void agp_controller_make_current(agp_controller * controller)
 	agp_fe.current_controller = controller;
 }
 
+/** 
+ * Release the current controller.
+ *
+ * \param controller controller.
+ * \param controller_priv controller file private data.
+ *
+ * Clears the valid flags in the controller file and in each client file.
+ * Unsets the current controller and releases the backend.
+ */
 static void agp_controller_release_current(agp_controller * controller,
 				      agp_file_private * controller_priv)
 {
@@ -468,11 +644,25 @@ static void agp_controller_release_current(agp_controller * controller,
 	agp_backend_release();
 }
 
-/* 
- * Routines for managing client lists -
- * These routines are for managing the list of auth'ed clients.
+/*@}*/
+
+
+/**
+ * \name Routines for managing client lists
+ *
+ * These routines are for managing the list of authorized clients.
  */
+/*@{*/
 
+/**
+ * Find a client in a controller with a given process id.
+ *
+ * \param controller controller to search the client on.
+ * \param id clinet process id.
+ * \return pointer to the client structure on success or NULL otherwise.
+ * 
+ * Search the given process id in agp_contoller::clients.
+ */
 static agp_client *agp_find_client_in_controller(agp_controller * controller,
 						 pid_t id)
 {
@@ -493,6 +683,15 @@ static agp_client *agp_find_client_in_controller(agp_controller * controller,
 	return NULL;
 }
 
+/**
+ * Find the controller to which the client belongs.
+ *
+ * \param id client process id.
+ * \return pointer to the controller structure associated with the client on success, or NULL on failure.
+ *
+ * Search the controller by successive calls to agp_find_client_in_controller()
+ * for each controller until a match is found.
+ */
 static agp_controller *agp_find_controller_for_client(pid_t id)
 {
 	agp_controller *controller;
@@ -509,6 +708,14 @@ static agp_controller *agp_find_controller_for_client(pid_t id)
 	return NULL;
 }
 
+/**
+ * Find the client with the given process id.
+ *
+ * \param id client process id.
+ * \return pointer to the client structure on success or NULL on failure.
+ * 
+ * Search the client in the current controller.
+ */
 static agp_client *agp_find_client_by_pid(pid_t id)
 {
 	agp_client *temp;
@@ -520,6 +727,14 @@ static agp_client *agp_find_client_by_pid(pid_t id)
 	return temp;
 }
 
+/**
+ * Insert client into the current controller.
+ *
+ * \param client client information.
+ * 
+ * Insert \p client into the agp_controller::clients list of the current
+ * controller.
+ */
 static void agp_insert_client(agp_client * client)
 {
 	agp_client *prev_client;
@@ -534,6 +749,15 @@ static void agp_insert_client(agp_client * client)
 	agp_fe.current_controller->num_clients++;
 }
 
+/**
+ * Create a client structure.
+ *
+ * \param id client process id.
+ * \return a pointer to an agp_client structure.
+ *
+ * Allocate and initialze an agp_client structure and inserts into the current
+ * controller.
+ */
 static agp_client *agp_create_client(pid_t id)
 {
 	agp_client *new_client;
@@ -549,6 +773,15 @@ static agp_client *agp_create_client(pid_t id)
 	return new_client;
 }
 
+/**
+ * Remove client.
+ *
+ * \param id client process id.
+ *
+ * Find the controller to which the client belongs, then the client data, and
+ * unlinks it from its list. Removes the segments from the client and finally
+ * frees the client structure itself.
+ */
 static int agp_remove_client(pid_t id)
 {
 	agp_client *client;
@@ -587,10 +820,27 @@ static int agp_remove_client(pid_t id)
 	return 0;
 }
 
-/* End - Routines for managing client lists */
+/*@}*/
 
-/* File Operations */
 
+/** \name File Operations */
+/*@{*/
+
+/**
+ * Memory mapping.
+ *
+ * \param file file pointer.
+ * \param vma virtual memory area.
+ *
+ * Holds the AGP lock and tests that the valid flag is set on the file private
+ * data.
+ * 
+ * If it's a client then verifies the area fits the current aperture, finds the
+ * segment matching the given area and remaps it.
+ *
+ * If it's a controller then verifies the area size matches the aperture size
+ * and remaps it.
+ */
 static int agp_mmap(struct file *file, struct vm_area_struct *vma)
 {
 	int size;
@@ -658,6 +908,22 @@ static int agp_mmap(struct file *file, struct vm_area_struct *vma)
 	return -EPERM;
 }
 
+/**
+ * Release the device.
+ *
+ * \param inode device inode.
+ * \param file file pointer.
+ * \return zero on success or a negative number on failure.
+ * 
+ * If it's a controller then find its data structure, and removes it. If it's
+ * the current controller then additionally calls
+ * agp_controller_release_current().
+ * 
+ * If it's a client then simply remove the client.
+ *
+ * The AGP lock is held during the function call and the file private data is
+ * free before returning.
+ */
 static int agp_release(struct inode *inode, struct file *file)
 {
 	agp_file_private *priv = (agp_file_private *) file->private_data;
@@ -686,6 +952,22 @@ static int agp_release(struct inode *inode, struct file *file)
 	return 0;
 }
 
+/**
+ * Open the device.
+ *
+ * \param inode device inode.
+ * \param file file pointer.
+ * \return zero on success or a negative number on failure.
+ * 
+ * Allocate and create a agp_file_private structure for the file private data,
+ * and sets the client allow flag. If the user or the suid is zero then set the
+ * controller allow flag too.
+ *
+ * If there is a client with the current proccess id then set the client and
+ * valid flags.
+ * 
+ * The AGP lock is held during the function call.
+ */
 static int agp_open(struct inode *inode, struct file *file)
 {
 	int minor = minor(inode->i_rdev);
@@ -728,19 +1010,31 @@ err_out:
 	return rc;
 }
 
-
+/** No-op. */
 static ssize_t agp_read(struct file *file, char *buf,
 			size_t count, loff_t * ppos)
 {
 	return -EINVAL;
 }
 
+/** No-op. */
 static ssize_t agp_write(struct file *file, const char *buf,
 			 size_t count, loff_t * ppos)
 {
 	return -EINVAL;
 }
 
+/**
+ * Information ioctl.
+ *
+ * \param priv file private data.
+ * \param arg user argument pointing to an agp_info structure where the AGP
+ * information will be copied.
+ * \return zero on success or a negative number on failure.
+ *
+ * Calls agp_copy_info(), transfers the information into a agp_info structure
+ * and copies into user space.
+ */
 static int agpioc_info_wrap(agp_file_private * priv, unsigned long arg)
 {
 	agp_info userinfo;
@@ -764,6 +1058,20 @@ static int agpioc_info_wrap(agp_file_private * priv, unsigned long arg)
 	return 0;
 }
 
+/**
+ * AGP acquire ioctl.
+ *
+ * \param priv file private data.
+ * \param arg user argument. Not referenced.
+ * \return zero on success or a negative number on failure.
+ *
+ * Verifies the allow controller flag is set and that no other controller has
+ * acquired the device, and acquires it. 
+ *
+ * If there is a controller with a given process id the make it current,
+ * otherwsie create a new controller, insert it, and make it current. Sets the
+ * controller and valid flags.
+ */
 static int agpioc_acquire_wrap(agp_file_private * priv, unsigned long arg)
 {
 	agp_controller *controller;
@@ -800,12 +1108,30 @@ static int agpioc_acquire_wrap(agp_file_private * priv, unsigned long arg)
 	return 0;
 }
 
+/**
+ * AGP release ioctl.
+ *
+ * \param priv file private data.
+ * \param arg user argument. Not referenced.
+ * \return zero on success or a negative number on failure.
+ *
+ * Wrapper around agp_controller_release_current().
+ */
 static int agpioc_release_wrap(agp_file_private * priv, unsigned long arg)
 {
 	agp_controller_release_current(agp_fe.current_controller, priv);
 	return 0;
 }
 
+/**
+ * AGP setup ioctl.
+ *
+ * \param priv file private data.
+ * \param arg user argument, pointing to an agp_setup structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Wrapper around agp_enable().
+ */
 static int agpioc_setup_wrap(agp_file_private * priv, unsigned long arg)
 {
 	agp_setup mode;
@@ -817,6 +1143,18 @@ static int agpioc_setup_wrap(agp_file_private * priv, unsigned long arg)
 	return 0;
 }
 
+/**
+ * AGP reserve ioctl.
+ *
+ * \param priv file private data.
+ * \param arg user argument, pointing to an agp_region structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Find the client with the given process id. If agp_region::seg_count is zero
+ * then remove the client if any, after setting the client and the valid flags.
+ * Otherwise create a new segment via agp_create_segment(), creating a new
+ * client if necessary.
+ */
 static int agpioc_reserve_wrap(agp_file_private * priv, unsigned long arg)
 {
 	agp_region reserve;
@@ -891,12 +1229,22 @@ static int agpioc_reserve_wrap(agp_file_private * priv, unsigned long arg)
 	return -EINVAL;
 }
 
+/** No-op. This function is not currently implemented */
 static int agpioc_protect_wrap(agp_file_private * priv, unsigned long arg)
 {
 	/* This function is not currently implemented */
 	return -EINVAL;
 }
 
+/**
+ * Memory allocation ioctl.
+ *
+ * \param priv file private data.
+ * \param arg user argument, pointing to an agp_allocate structure.
+ * \return zero on success or a negative number on failure.
+ *
+ * Wrapper around agp_allocate_memory_wrap().
+ */
 static int agpioc_allocate_wrap(agp_file_private * priv, unsigned long arg)
 {
 	agp_memory *memory;
@@ -920,6 +1268,16 @@ static int agpioc_allocate_wrap(agp_file_private * priv, unsigned long arg)
 	return 0;
 }
 
+/**
+ * Memory deallocation ioctl.
+ *
+ * \param priv file private data.
+ * \param arg allocation tag.
+ * \return zero on success or a negative number on failure.
+ *
+ * Wrapper around agp_deallocate_memory_wrap(), using the allocation tag as
+ * reference.
+ */
 static int agpioc_deallocate_wrap(agp_file_private * priv, unsigned long arg)
 {
 	agp_memory *memory;
@@ -933,6 +1291,16 @@ static int agpioc_deallocate_wrap(agp_file_private * priv, unsigned long arg)
 	return 0;
 }
 
+/**
+ * Memory binding ioctl.
+ *
+ * \param priv file private data.
+ * \param arg allocation tag.
+ * \return zero on success or a negative number on failure.
+ *
+ * Wrapper around agp_bind_memory(), using the allocation tag as
+ * reference.
+ */
 static int agpioc_bind_wrap(agp_file_private * priv, unsigned long arg)
 {
 	agp_bind bind_info;
@@ -949,6 +1317,16 @@ static int agpioc_bind_wrap(agp_file_private * priv, unsigned long arg)
 	return agp_bind_memory(memory, bind_info.pg_start);
 }
 
+/**
+ * Memory unbinding ioctl.
+ *
+ * \param priv file private data.
+ * \param arg allocation tag.
+ * \return zero on success or a negative number on failure.
+ *
+ * Wrapper around agp_unbind_memory(), using the allocation tag as
+ * reference.
+ */
 static int agpioc_unbind_wrap(agp_file_private * priv, unsigned long arg)
 {
 	agp_memory *memory;
@@ -965,6 +1343,19 @@ static int agpioc_unbind_wrap(agp_file_private * priv, unsigned long arg)
 	return agp_unbind_memory(memory);
 }
 
+
+/**
+ * Ioctl handler.
+ *
+ * \param inode device inode.
+ * \param file file pointer.
+ * \param cmd command.
+ * \param arg allocation tag.
+ * \return zero on success or a negative number on failure.
+ *
+ * Locks the AGP device, makes some sanity checks, and dispatches to one of the
+ * agpioc_* functions above according with the value of \p cmd.
+ */
 static int agp_ioctl(struct inode *inode, struct file *file,
 		     unsigned int cmd, unsigned long arg)
 {
@@ -1055,6 +1446,7 @@ ioctl_out:
 	return ret_val;
 }
 
+/** File operations structure. */
 static struct file_operations agp_fops =
 {
 	.owner		= THIS_MODULE,
@@ -1067,6 +1459,9 @@ static struct file_operations agp_fops =
 	.release	= agp_release,
 };
 
+/*@}*/
+
+/** Misc device structure. */
 static struct miscdevice agp_miscdev =
 {
 	AGPGART_MINOR,
@@ -1074,6 +1469,11 @@ static struct miscdevice agp_miscdev =
 	&agp_fops
 };
 
+/** 
+ * Frontend initialization. 
+ *
+ * Registers agp_miscdev.
+ */
 int __init agp_frontend_initialize(void)
 {
 	memset(&agp_fe, 0, sizeof(struct agp_front_data));
@@ -1086,6 +1486,11 @@ int __init agp_frontend_initialize(void)
 	return 0;
 }
 
+/** 
+ * Frontend cleanup. 
+ * 
+ * Unregisters agp_miscdev.
+ */
 void __exit agp_frontend_cleanup(void)
 {
 	misc_deregister(&agp_miscdev);
diff --git a/src/kernel/agpgart/i810_agp.c b/src/kernel/agpgart/i810_agp.c
index 0df2cff18a..613bb15239 100644
--- a/src/kernel/agpgart/i810_agp.c
+++ b/src/kernel/agpgart/i810_agp.c
@@ -1,6 +1,6 @@
 /**
  * \file i810_agp.c
- * \brief AGPGART module i810 backend
+ * AGPGART module i810 backend
  * \version 0.99
  * 
  * \author Jeff Hartmann
diff --git a/src/kernel/agpgart/i8x0_agp.c b/src/kernel/agpgart/i8x0_agp.c
index fe803618f6..c453abca7a 100644
--- a/src/kernel/agpgart/i8x0_agp.c
+++ b/src/kernel/agpgart/i8x0_agp.c
@@ -1,6 +1,6 @@
 /**
  * \file i8x0_agp.c
- * \brief AGPGART module i8x0 backend
+ * AGPGART module i8x0 backend
  * \version 0.99
  * 
  * \author Jeff Hartmann
@@ -39,6 +39,15 @@
 #include "agp.h"
 
 
+/**
+ * Fetch aperture size -- Intel generic.
+ *
+ * \return always zero.
+ *
+ * Reads the aperture size and points agp_bridge_data::previous_size and
+ * agp_bridge_data::current_size to the agp_bridge_data::aperture_sizes entry
+ * with the matching aperture size.
+ */
 static int intel_fetch_size(void)
 {
 	int i;
@@ -60,6 +69,14 @@ static int intel_fetch_size(void)
 	return 0;
 }
 
+/**
+ * Fetch aperture size -- Intel i8xx.
+ *
+ * \return always zero.
+ *
+ * Same as for intel_fetch_size() but with special care for Intel 815 chipsets
+ * which have only one non-reserved bit on the APSIZE register.
+ */
 static int intel_8xx_fetch_size(void)
 {
 	int i;
@@ -87,6 +104,9 @@ static int intel_8xx_fetch_size(void)
 }
 
 
+/**
+ * Flush the table -- Intel generic.
+ */
 static void intel_tlbflush(agp_memory * mem)
 {
 	pci_write_config_dword(agp_bridge.dev, INTEL_AGPCTRL, 0x2200);
@@ -94,6 +114,9 @@ static void intel_tlbflush(agp_memory * mem)
 }
 
 
+/**
+ * Flush the table -- Intel i8xx.
+ */
 static void intel_8xx_tlbflush(agp_memory * mem)
 {
   u32 temp;
@@ -104,6 +127,11 @@ static void intel_8xx_tlbflush(agp_memory * mem)
 }
 
 
+/** 
+ * Backend cleanup -- Intel generic.
+ *
+ * Sets the previous aperture size.
+ */
 static void intel_cleanup(void)
 {
 	u16 temp;
@@ -117,6 +145,11 @@ static void intel_cleanup(void)
 }
 
 
+/** 
+ * Backend cleanup -- Intel i8xx.
+ *
+ * Same as intel_cleanup().
+ */
 static void intel_8xx_cleanup(void)
 {
 	u16 temp;
@@ -130,6 +163,13 @@ static void intel_8xx_cleanup(void)
 }
 
 
+/**
+ * Configure -- Intel generic.
+ *
+ * \return always zero.
+ *
+ * Sets the hardware registers with the information in agp_bridge_data.
+ */
 static int intel_configure(void)
 {
 	u32 temp;
@@ -162,6 +202,11 @@ static int intel_configure(void)
 	return 0;
 }
 
+/**
+ * Configure -- Intel i815.
+ *
+ * Similar to intel_configure()
+ */
 static int intel_815_configure(void)
 {
 	u32 temp, addr;
@@ -200,11 +245,17 @@ static int intel_815_configure(void)
 	return 0;
 }
 
+/** No-op. */
 static void intel_820_tlbflush(agp_memory * mem)
 {
   return;
 }
 
+/** 
+ * Backend cleanup -- Intel i8xx.
+ *
+ * Similar to as intel_cleanup().
+ */
 static void intel_820_cleanup(void)
 {
 	u8 temp;
@@ -219,6 +270,11 @@ static void intel_820_cleanup(void)
 }
 
 
+/**
+ * Configure -- Intel i820.
+ *
+ * Similar to intel_configure()
+ */
 static int intel_820_configure(void)
 {
 	u32 temp;
@@ -253,6 +309,11 @@ static int intel_820_configure(void)
 	return 0;
 }
 
+/**
+ * Configure -- Intel i840.
+ *
+ * Similar to intel_configure()
+ */
 static int intel_840_configure(void)
 {
 	u32 temp;
@@ -285,6 +346,11 @@ static int intel_840_configure(void)
 	return 0;
 }
 
+/**
+ * Configure -- Intel i845.
+ *
+ * Similar to intel_configure()
+ */
 static int intel_845_configure(void)
 {
 	u32 temp;
@@ -317,11 +383,17 @@ static int intel_845_configure(void)
 	return 0;
 }
 
+/** Calls intel_845_configure() */
 static void intel_845_resume(void)
 {
 	intel_845_configure();
 }
 
+/**
+ * Configure -- Intel i850.
+ *
+ * Similar to intel_configure()
+ */
 static int intel_850_configure(void)
 {
 	u32 temp;
@@ -354,6 +426,11 @@ static int intel_850_configure(void)
 	return 0;
 }
 
+/**
+ * Configure -- Intel i860.
+ *
+ * Similar to intel_configure()
+ */
 static int intel_860_configure(void)
 {
 	u32 temp;
@@ -386,6 +463,11 @@ static int intel_860_configure(void)
 	return 0;
 }
 
+/**
+ * Configure -- Intel i830mp.
+ *
+ * Similar to intel_configure()
+ */
 static int intel_830mp_configure(void)
 {
 	u32 temp;
@@ -418,6 +500,9 @@ static int intel_830mp_configure(void)
 	return 0;
 }
 
+/** 
+ * Masks against the first mask in agp_bridge_data::masks.
+ */
 static unsigned long intel_mask_memory(unsigned long addr, int type)
 {
 	/* Memory type is ignored */
@@ -425,23 +510,26 @@ static unsigned long intel_mask_memory(unsigned long addr, int type)
 	return addr | agp_bridge.masks[0].mask;
 }
 
+/** Calls intel_configure() */
 static void intel_resume(void)
 {
 	intel_configure();
 }
 
-/* Setup function */
+/** Setup function */
 static struct gatt_mask intel_generic_masks[] =
 {
 	{mask: 0x00000017, type: 0}
 };
 
+/** Aperture sizes -- Intel i815 */
 static struct aper_size_info_8 intel_815_sizes[2] =
 {
 	{64, 16384, 4, 0},
 	{32, 8192, 3, 8},
 };
 	
+/** Aperture sizes -- Intel i8xx */
 static struct aper_size_info_8 intel_8xx_sizes[7] =
 {
 	{256, 65536, 6, 0},
@@ -453,6 +541,7 @@ static struct aper_size_info_8 intel_8xx_sizes[7] =
 	{4, 1024, 0, 63}
 };
 
+/** Aperture sizes -- Intel generic */
 static struct aper_size_info_16 intel_generic_sizes[7] =
 {
 	{256, 65536, 6, 0},
@@ -464,6 +553,7 @@ static struct aper_size_info_16 intel_generic_sizes[7] =
 	{4, 1024, 0, 63}
 };
 
+/** Aperture sizes -- Intel i830mp */
 static struct aper_size_info_8 intel_830mp_sizes[4] = 
 {
   {256, 65536, 6, 0},
@@ -472,6 +562,15 @@ static struct aper_size_info_8 intel_830mp_sizes[4] =
   {32, 8192, 3, 56}
 };
 
+/**
+ * Setup -- Intel generic.
+ *
+ * \param pdev not referenced.
+ * \return always zero.
+ * 
+ * Initializes the device dependent part agp_bride_data structure in agp_bride,
+ * using the the functions above for the driver callbacks.
+ */
 int __init intel_generic_setup (struct pci_dev *pdev)
 {
 	agp_bridge.masks = intel_generic_masks;
@@ -505,6 +604,11 @@ int __init intel_generic_setup (struct pci_dev *pdev)
 	(void) pdev; /* unused */
 }
 
+/**
+ * Setup -- Intel i815.
+ *
+ * Similar to intel_generic_setup().
+ */
 int __init intel_815_setup (struct pci_dev *pdev)
 {
 	agp_bridge.masks = intel_generic_masks;
@@ -537,6 +641,11 @@ int __init intel_815_setup (struct pci_dev *pdev)
 }
 
 
+/**
+ * Setup -- Intel i820.
+ *
+ * Similar to intel_generic_setup().
+ */
 int __init intel_820_setup (struct pci_dev *pdev)
 {
        agp_bridge.masks = intel_generic_masks;
@@ -570,6 +679,11 @@ int __init intel_820_setup (struct pci_dev *pdev)
        (void) pdev; /* unused */
 }
 
+/**
+ * Setup -- Intel i830mp.
+ *
+ * Similar to intel_generic_setup().
+ */
 int __init intel_830mp_setup (struct pci_dev *pdev)
 {
        agp_bridge.masks = intel_generic_masks;
@@ -603,6 +717,11 @@ int __init intel_830mp_setup (struct pci_dev *pdev)
        (void) pdev; /* unused */
 }
 
+/**
+ * Setup -- Intel i840.
+ *
+ * Similar to intel_generic_setup().
+ */
 int __init intel_840_setup (struct pci_dev *pdev)
 {
 	agp_bridge.masks = intel_generic_masks;
@@ -636,6 +755,11 @@ int __init intel_840_setup (struct pci_dev *pdev)
 	(void) pdev; /* unused */
 }
 
+/**
+ * Setup -- Intel i845.
+ *
+ * Similar to intel_generic_setup().
+ */
 int __init intel_845_setup (struct pci_dev *pdev)
 {
 	agp_bridge.masks = intel_generic_masks;
@@ -669,6 +793,11 @@ int __init intel_845_setup (struct pci_dev *pdev)
 	(void) pdev; /* unused */
 }
 
+/**
+ * Setup -- Intel i850.
+ *
+ * Similar to intel_generic_setup().
+ */
 int __init intel_850_setup (struct pci_dev *pdev)
 {
 	agp_bridge.masks = intel_generic_masks;
@@ -702,6 +831,11 @@ int __init intel_850_setup (struct pci_dev *pdev)
 	(void) pdev; /* unused */
 }
 
+/**
+ * Setup -- Intel i860.
+ *
+ * Similar to intel_generic_setup().
+ */
 int __init intel_860_setup (struct pci_dev *pdev)
 {
 	agp_bridge.masks = intel_generic_masks;