summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJose Fonseca <j_r_fonseca@yahoo.co.uk>2003-05-01 00:56:11 +0000
committerJose Fonseca <j_r_fonseca@yahoo.co.uk>2003-05-01 00:56:11 +0000
commit58cc2c6f336528182f12942a35f7ce08da7e1df2 (patch)
tree1e5b6cf711a29b33f54f785710dab5c685694100
parent88acbfbe18e6aa6e10f68b65db89a994d9310618 (diff)
Final documentation to the AGPGART module.
-rw-r--r--src/kernel/agpgart/Doxyfile18
-rw-r--r--src/kernel/agpgart/agp.c109
-rw-r--r--src/kernel/agpgart/agp.h75
-rw-r--r--src/kernel/agpgart/agp_backend.h103
-rw-r--r--src/kernel/agpgart/agpgart.h55
-rw-r--r--src/kernel/agpgart/frontend.c451
-rw-r--r--src/kernel/agpgart/i810_agp.c2
-rw-r--r--src/kernel/agpgart/i8x0_agp.c138
8 files changed, 771 insertions, 180 deletions
diff --git a/src/kernel/agpgart/Doxyfile b/src/kernel/agpgart/Doxyfile
index 4ccae88dbfa..3b21b8541ce 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 61e9ecd465f..2345e6e0bf8 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 443dd8c5e3e..22d4cbfa709 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 65390109ece..fb8203b3117 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 45f10dc1788..6819e228fa2 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 e84cc0f34cb..f11da4b95a0 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 0df2cff18a1..613bb152392 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 fe803618f69..c453abca7a1 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;