From 58cc2c6f336528182f12942a35f7ce08da7e1df2 Mon Sep 17 00:00:00 2001 From: Jose Fonseca Date: Thu, 1 May 2003 00:56:11 +0000 Subject: Final documentation to the AGPGART module. --- src/kernel/agpgart/Doxyfile | 18 +- src/kernel/agpgart/agp.c | 109 ++++++++-- src/kernel/agpgart/agp.h | 75 +++++-- src/kernel/agpgart/agp_backend.h | 103 +-------- src/kernel/agpgart/agpgart.h | 55 +++-- src/kernel/agpgart/frontend.c | 451 +++++++++++++++++++++++++++++++++++++-- src/kernel/agpgart/i810_agp.c | 2 +- src/kernel/agpgart/i8x0_agp.c | 138 +++++++++++- 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 + * \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 - * \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; -- cgit v1.2.3