[AGPGART] Move function description comments from headers to the code they document.

drivers/char/agp/backend.c

@@ -48,6 +48,14 @@ struct agp_bridge_data agp_bridge_dummy = { .type = NOT_SUPPORTED };
 struct agp_bridge_data *agp_bridge = &agp_bridge_dummy;
 EXPORT_SYMBOL(agp_bridge);
 
+/*
+ * agp_backend_acquire :
+ * 
+ * This Function attempts to acquire the agp backend.
+ * 
+ * returns -EBUSY if agp is in use,
+ * returns 0 if the caller owns the agp backend
+ */
 int agp_backend_acquire(void)
 {
 	if (agp_bridge->type == NOT_SUPPORTED)
@@ -60,6 +68,14 @@ int agp_backend_acquire(void)
 	return 0;
 }
 
+/*
+ * agp_backend_release :
+ * 
+ * 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.)
+ */
 void agp_backend_release(void)
 {
 	if (agp_bridge->type == NOT_SUPPORTED)

drivers/char/agp/generic.c

@@ -98,7 +98,15 @@ agp_memory *agp_create_memory(int scratch_pages)
 }
 EXPORT_SYMBOL(agp_create_memory);
 
-
+/*
+ * agp_free_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.)
+ * 
+ * It takes an agp_memory pointer as an argument.
+ */
 void agp_free_memory(agp_memory * curr)
 {
 	size_t i;
@@ -126,7 +134,18 @@ EXPORT_SYMBOL(agp_free_memory);
 
 #define ENTRIES_PER_PAGE		(PAGE_SIZE / sizeof(unsigned long))
 
-
+/*
+ * agp_allocate_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 dependent.
+ * 
+ * It returns NULL whenever memory is unavailable. 
+ */
 agp_memory *agp_allocate_memory(size_t page_count, u32 type)
 {
 	int scratch_pages;
@@ -243,7 +262,15 @@ int agp_num_entries(void)
 EXPORT_SYMBOL_GPL(agp_num_entries);
 
 
-/* Routine to copy over information structure */
+/*
+ * agp_copy_info :
+ * 
+ * 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. 
+ */
 int agp_copy_info(agp_kern_info * info)
 {
 	memset(info, 0, sizeof(agp_kern_info));
@@ -277,6 +304,18 @@ EXPORT_SYMBOL(agp_copy_info);
  * They call device specific routines to actually write to the GATT.
  */
 
+/*
+ * agp_bind_memory :
+ * 
+ * This function binds an agp_memory structure into the graphics aperture
+ * translation table (GATT).
+ * 
+ * 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.
+ */
 int agp_bind_memory(agp_memory * curr, off_t pg_start)
 {
 	int ret_val;
@@ -301,6 +340,17 @@ int agp_bind_memory(agp_memory * curr, off_t pg_start)
 EXPORT_SYMBOL(agp_bind_memory);
 
 
+/* 
+ * agp_unbind_memory :
+ * 
+ * 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
+ */
 int agp_unbind_memory(agp_memory * curr)
 {
 	int ret_val;
@@ -608,8 +658,7 @@ int agp_generic_free_gatt_table(void)
 
 	/* Do not worry about freeing memory, because if this is
 	 * called, then all agp memory is deallocated and removed
-	 * from the table.
-	 */
+	 * from the table. */
 
 	iounmap(agp_bridge->gatt_table);
 	table = (char *) agp_bridge->gatt_table_real;
@@ -732,10 +781,8 @@ EXPORT_SYMBOL(agp_generic_free_by_type);
 
 /* 
  * Basic Page Allocation Routines -
- * These routines handle page allocation
- * and by default they reserve the allocated 
- * memory.  They also handle incrementing the
- * current_memory_agp value, Which is checked
+ * These routines handle page allocation and by default they reserve the allocated 
+ * memory.  They also handle incrementing the current_memory_agp value, Which is checked
  * against a maximum value.
  */
 
@@ -775,6 +822,14 @@ EXPORT_SYMBOL(agp_generic_destroy_page);
 
 /* End Basic Page Allocation Routines */
 
+
+/* 
+ * agp_enable :
+ * 
+ * This function initializes the agp point-to-point connection.
+ * 
+ * It takes an agp mode register as an argument
+ */
 void agp_enable(u32 mode)
 {
 	if (agp_bridge->type == NOT_SUPPORTED)

include/linux/agp_backend.h

 /*
- * AGPGART module version 0.99
+ * AGPGART module version 0.100
+ * Copyright (C) 2002-2003 Dave Jones
  * Copyright (C) 1999 Jeff Hartmann
  * Copyright (C) 1999 Precision Insight, Inc.
  * Copyright (C) 1999 Xi Graphics, Inc.
@@ -71,16 +72,11 @@ typedef struct _agp_kern_info {
 } agp_kern_info;
 
 /* 
- * The agp_memory structure has information
- * about the block of agp memory allocated.
- * A caller may manipulate the next and prev
- * pointers to link each allocated item into
- * a list.  These pointers are ignored by the 
- * backend.  Everything else should never be
- * written to, but the caller may read any of
- * the items to detrimine the status of this
- * block of agp memory.
- * 
+ * The agp_memory structure has information about the block of agp memory
+ * allocated.  A caller may manipulate the next and prev pointers to link
+ * each allocated item into a list.  These pointers are ignored by the backend.
+ * Everything else should never be written to, but the caller may read any of
+ * the items to detrimine the status of this block of agp memory. 
  */
 
 typedef struct _agp_memory {
@@ -100,126 +96,19 @@ typedef struct _agp_memory {
 #define AGP_NORMAL_MEMORY 0
 
 extern void agp_free_memory(agp_memory *);
-
-/*
- * agp_free_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.)
- * 
- * It takes an agp_memory pointer as an argument.
- * 
- */
-
 extern agp_memory *agp_allocate_memory(size_t, u32);
-
-/*
- * agp_allocate_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 dependent.
- * 
- * It returns NULL whenever memory is unavailable.
- * 
- */
-
 extern int agp_copy_info(agp_kern_info *);
-
-/*
- * agp_copy_info :
- * 
- * 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_bind_memory(agp_memory *, off_t);
-
-/*
- * agp_bind_memory :
- * 
- * 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_unbind_memory(agp_memory *);
-
-/* 
- * agp_unbind_memory :
- * 
- * 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 void agp_enable(u32);
-
-/* 
- * agp_enable :
- * 
- * This function initializes the agp point-to-point
- * connection.
- * 
- * It takes an agp mode register as an argument
- * 
- */
-
 extern int agp_backend_acquire(void);
-
-/*
- * agp_backend_acquire :
- * 
- * 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 void agp_backend_release(void);
 
 /*
- * agp_backend_release :
- * 
- * 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.)
- * 
+ * Interface between drm and agp code.  When agp initializes, it makes
+ * the below structure available via inter_module_register(), drm might
+ * use it.  Keith Owens <kaos@ocs.com.au> 28 Oct 2000.
  */
-
 typedef struct {
 	void       (*free_memory)(agp_memory *);
 	agp_memory *(*allocate_memory)(size_t, u32);
@@ -233,10 +122,4 @@ typedef struct {
 
 extern const drm_agp_t *drm_agp_p;
 
-/*
- * Interface between drm and agp code.  When agp initializes, it makes
- * the above structure available via inter_module_register(), drm might
- * use it.  Keith Owens <kaos@ocs.com.au> 28 Oct 2000.
- */
-
 #endif				/* _AGP_BACKEND_H */