Agpgart 2.0 API Document
Copyright(C) 2003 Tungsten Graphics
Copyright(C) Jeff Hartmann
One of the things that was always missing from the original agpgart release was some decent documentation of the API's. This is document is an attempt to rectify that situation. Both the original 0.99 module API and the new 2.0 API will be discussed. This document is quite technical in nature and assumes that the reader has some general knowledge of C programming and some basic system knowledge as to how the AGP port functions.
Purpose of the Agpgart interface
The Linux agpgart interface was conceived so that several projects at the time could setup device independent regions of system memory to perform DMA on. The AGP specification outlines a system for performing such a task using a GART, or Graphics Aperture Remapping Table. The agpgart kernel and user interfaces provide a device independent method for graphics drivers to perform various tasks on the GART. Also included in the Linux kernel module are several device specific implementations which provide access to the GART on those devices. To avoid programming these various devices directly in the graphics driver, the interfaces are designed in such a way that the programmer needs no knowledge as to how the GART is actually implemented.
Agpgart Ioctl Interface
The first interface that I will describe is the general ioctl interface exposed by /dev/agpgart. The original interface exposed 10 ioctl's to the user and agpgart 2.0 adds 7 more. They provide a user level driver with the ability to swap sets of pages in and out of the agp aperture. By its very nature the agpgart interface is only accessible by one entity at a time, called the controlling process. This might change as time goes on since we now store enough information in agpgart to provide a general system allocator. However this is not addressed in the current agpgart implementations. This controlling process can authenticate other clients to map the agp aperture into their process space by telling agpgart through one of the ioctl's to allow this to happen.
Note on ioctl return values:
Unless otherwise stated the ioctl's all return 0 on successful completion of the ioctl, and -1 to indicate an error occurred. The errno variable is set to indicate the nature of the error that occurred.
AGPIOC_INFO
This ioctl provides a method for the user land driver to query several settings from the agpgart kernel module. It is one of the first things that user drivers will want to do with the agpgart interface so they know how to program their graphics devices to access the agp aperture. It takes a pointer to an agp_info structure, which is laid out as follows:
typedef struct _agp_version {
__u16 major;
__u16 minor;
} agp_version;
typedef struct _agp_info {
agp_version version;
__u32 bridge_id;
__u32 agp_mode;
off_t aper_base;
size_t aper_size;
size_t pg_total;
size_t pg_system;
size_t pg_used;
} agp_info;
The first part of the structure the agp_version structure defines the interface version provided by the agpgart interface. It is considered to be a version number where increases in the minor version indicate backwards compatible changes and bumps to the major number are considered to be backwards incompatible changes to the interface.
The field bridge_id contains the packed id of the pci vendor and device id of the agp bridge. The top 16-bits are the device and the bottom 16-bits are the vendor id.
The field agp_mode contains the current AGPSTAT register that the bridge reports. If you require a definition of the AGPSTAT register please see the AGP 2.0 or 3.0 interface specifications available on Intel's website.
The field aper_base contains the bus relative offset for the agp aperture. It is this value that is used to program the graphics device so that it can utilize the agp aperture.
The field aper_size contains the size in megabytes of the agp aperture window from the aper_base address. This is just the size of the agp aperture window, not necessarily the amount of memory backing the aperture.
The field pg_total is the total number of system pages which can be used to back the agp aperture.
The field pg_system represents the number of system pages which will be used from main memory before the system starts swapping pages. In the current agpgart implementation this field is equal to the pg_total field.
The field pg_used is the current number of system pages used by agpgart.
AGPIOC_ACQUIRE
This ioctl provides a method for a root privledged process to become the current system wide controlling process of the agpgart kernel module. It takes no arguments and returns 0 upon success. This is the only ioctl that can be used without being the controlling process. It should be the first thing that an application does with the agpgart interface.
AGPIOC_RELEASE
This ioctl should be called when the controlling process no longer needs control of the agpgart interface. It is the responsibility of the controlling process to leave the GART table in a state where other processes can use it. This usually involves unbinding all page sets from the agp aperture. It takes no arguments and returns 0 upon success.
AGPIOC_SETUP
This ioctl is called by the controlling process to set the AGPCMD register on all agp devices controlled by the agp bridge as described in the agp_info structure. It takes a pointer an agp_setup structure which is laid out as follows:
typedef struct _agp_setup {
__u32 agp_mode;
} agp_setup;
The agp_mode field is the value used to decide on the setting of the AGPCMD register. If we want certain agp modes to be excluded from the final setting of the AGPCMD register, then we do not put them in the agp_mode field. For a complete description of the AGPCMD register please see the AGP 2.0 or 3.0 Interface specification.
AGPIOC_RESERVE
This ioctl is called by the controlling process to setup a region of the agp aperture to be mapped by a client process. If the graphics driver requires other non root privledged processes to use the agp aperture, then this ioctl needs to be called to configure the agpgart kernel module to provide this ability to that client process. It takes a pointer to an agp_region structure, which is laid out as follows:
typedef struct _agp_segment {
off_t pg_start;
size_t pg_count;
int prot;
} agp_segment;
typedef struct _agp_region {
pid_t pid;
size_t seg_count;
agp_segment *seg_list;
} agp_region;
The agp_segment structure provides a description of the region of the agp aperture that we want to allow the client to be able to map. The field pg_start is the starting agp page offset that we want to allow the client to map, while the field pg_count is the number of agp pages to allow. The field prot is of the exact same form as the prot argument to the mmap system call.
The agp_region structure describes the client fully to the agpgart kernel interface.
The pid field is the process identification number that the system knows the process by, it is up to the controlling process to determine this information in a secure way. It is beyond the scope of the agpgart interface to provide a secure way of authenticating a process.
The seg_count field is the number of agp_segment structures that we are passing into the kernel at this time.
The seg_list field is a pointer to an array of agp_segment structures in the controlling processes address space. It is the list of regions in the agp aperture that we want to allow this client to map.
AGPIOC_PROTECT
This ioctl provides a method for the controlling process to revoke map permission from a client process. It is currently unimplemented in the agpgart kernel module, however the interface will be described since it might be implemented in the future. This ioctl takes a pointer to an agp_region structure which contains a list of regions we want to change the protection on. This ioctl if implemented should walk the proper vma's and change their vm_page_prot and the actual pte values in their page tables. Because of the limited utility of this function as a locking mechanism it is not implemented currently. It was the original intention of this ioctl to provide a locking mechanism using page faults in a client.
AGPIOC_ALLOCATE
This ioctl provides a method for the controlling process to allocate a set of pages with which it can back the agp aperture. The ioctl takes a pointer to an agp_allocate structure which is laid out as follows:
typedef struct _agp_allocate {
int key;
size_t pg_count;
__u32 type;
__u32 physical;
} agp_allocate;
The key field in this structure is copied back by the agpgart kernel module upon successful completion of this ioctl. It is the “tag” of the allocation which will be used in subsequent ioctl's referring to this set of pages.
The pg_count field in this structure is the number of agp pages we want in this allocation. Note that the size of an agp page does not necessarily have to match the system page size. This is a detail that most users of the agpgart interface make, and it is non portable behavior.
The type field is an value which encodes the type of agp memory that we want to allocate. In general this will be either the tokens AGP_NORMAL_MEMORY or AGP_CACHED_MEMORY, however some devices provide extended types of agp memory allocation. Currently the tokens AGP_INTEL_DCACHE_MEMORY and AGP_INTEL_PHYS_MEMORY are the only other values for this field. In general only the token AGP_NORMAL_MEMORY is accepted by this ioctl. However in agpgart version 2.0 there is a method to query to see if AGP_CACHED_MEMORY is accepted. AGP_CACHED_MEMORY is an extension to the AGP interface for AGP version 3.0 devices. It provides a method for someone to allocate cachable memory for use in the agp aperture. It should be noted that agp memory is general either mapped uncachable or write combined.
The physical field is a 32-bit pci visible bus address with which to program the device for the AGP_INTEL_PHYS_MEMORY type. It is not used currently for any other purpose and can be considered a device specific field.
AGPIOC_DEALLOCATE
This ioctl provides a method for a controlling process to free a region of agp memory. If this memory is currently visible in the agp aperture it is first removed from the aperture before the memory is freed. It is the responsibility of the controlling process to insure that no device dma will refer to this piece of agp memory before this call is executed. It takes an integer parameter which represents the “tag” of this agp allocation, which was previously obtained by the AGPIOC_ALLOCATE ioctl.
AGPIOC_BIND
This ioctl provides a method to map a collection of pages into the agp aperture. It takes a pointer to an agp_bind structure as an argument. This agp_bind structure is laid out as follows:
typedef struct _agp_bind {
int key;
off_t pg_start;
} agp_bind;
The key field is the “tag” previously obtained by the AGPIOC_ALLOCATE ioctl which refers the collection of agp pages we want to insert into the agp aperture.
The pg_start field is the offset in agp pages that we want to insert into the agp aperture. As mentioned previously the agp page size does not have to match the system page size. Previous to the AGP 3.0 specification, it was a general assumption that the agp page size would be fixed at 4096 KB. The AGP 3.0 specification however states that the agp page size doesn't have to be 4096 KB, so agpgart 2.0 provides a method for querying the agp page size.
AGPIOC_UNBIND
This ioctl provides a method for a controlling process to remove a collection of pages which was previously inserted into the agp aperture. It takes a pointer to an agp_unbind structure which is laid out as follows:
typedef struct _agp_unbind {
int key;
__u32 priority;
} agp_unbind;
The key field in the agp_unbind structure represents the “tag” of the collection of pages which we want to be removed from the agp aperture.
The priority field is currently unused in the Linux kernel agpgart implementation. It represents the priority we want to use to decide which unbound regions of agp memory we want to swap out to disk first. The higher the number, the higher the priority. To test if an implementation of agpgart would use this field check to see if the pg_system and pg_total fields of the agp_info structure match. If they do not, you can utilize this field.
AGPIOC_GETMAP
This ioctl and all that follows are only available on agpgart 2.0 or above. Currently the easiest way to test for support for agpgart 2.0 ioctl's is to try this ioctl and check for a success value. If it is not supported, errno will be set to ENOTTY.
This ioctl takes a pointer to an agp_map structure as an argument. It provides a method for a controller to discover some information about a current piece of agp memory. It is generally useful to figure out if an agp driver has memory allocated during its initialization. It is described as follows:
typedef struct _agp_map {
int key;
int is_bound;
off_t pg_start;
size_t page_count;
__u32 type;
__u32 physical;
} agp_map;
The key field in the agp_map structure is the “tag” of the allocation which was previously allocated by the AGPIOC_ALLOCATE call by some controller in the system. It does not have to be owned by the currently active controller. Also this ioctl can accept the token AGP_RESERVED_MEMORY to query the agp drivers reserved memory block.
The is_bound field is an integer value representing a truth value if this block of agp memory is currently bound in the agp aperture. A value of one indicates true, while a value of zero indicates false.
The pg_start field is the offset in agp pages where this block of memory begins if the is_bound field is true. It should generally be ignored if is_bound is false, however the current implementation returns a value of zero in this field upon successful ioctl completion.
The page_count field is the number of agp pages in this memory block.
The type field is the value understood by the agp driver as to what kind of memory this block represents. Currently it is only going to be one of the values outlined previously in this document, but future agp drivers might utilise new values.
The physical field is a 32-bit pci visible bus address with which to program the device for the AGP_INTEL_PHYS_MEMORY type. It is not used currently for any other purpose and can be considered a device specific field.
AGPIOC_MAP
This ioctl provides a method for a controller to directly map a piece of agp memory, even if it is not bound in the agp aperture. Right now this ioctl is not available to clients, but that functionality will be added in the future. The performance of this mapping is dependent on the support of setting write combining on a per page basis. The AGPIOC_QUERY_CTX function provides a method to determine if unbound agp mappings are fast. It is recommended that new software attempt to use this new ioctl instead of utilising the mmap system call. This ioctl does the right thing if the agp aperture is not allowed to be mapped. It takes a pointer to an agp_map_request structure, which is laid out as follows:
typedef struct _agp_map_request {
int key;
off_t pg_start;
size_t page_count;
unsigned long prot;
unsigned long flags;
unsigned long addr;
} agp_map_request;
The key field is the “tag” of this piece of agp memory as returned by the AGPIOC_ALLOCATE ioctl.
The pg_start field is the offset into this block of agp memory in agp pages which we want mapped. Please be warned, if you want to provide some sort of security by only mapping a portion of agp memory if the agp page size and system page size don't match you might get adjacent pages of memory in this mapping.
The page_count field represents the number of agp pages we want in this mapping. Please note that if it does not match the size of the block of agp memory and the system and agp page sizes don't match we might include more pages in this mapping then is asked by the caller.
The prot field is of the same format as the mmap system calls prot argument.
The flags field is of the same format as the mmap system calls flags argument.
The addr field is copied back upon successful ioctl completion by the agpgart kernel driver with the address in the processes address space where this piece of agp memory was mapped into.
AGPIOC_UNMAP
This ioctl provides a way to unmap a piece of agp memory that was previously mapped using the AGPIOC_MAP ioctl. It takes a pointer to an agp_map_request structure as an argument. Only the key and addr fields are utilise to find the proper agp mapping to tear down.
AGPIOC_QUERY_SIZE
This ioctl provides a method for the controlling process to determine the size required for the buffer used in the AGPIOC_QUERY_CTX ioctl. This ioctl takes an agp_query_request pointer as an argument. The agp_query_request structure is laid out as follows:
typedef struct _agp_query_request {
int ctx;
int size;
void *buffer;
} agp_query_request;
The ctx field represents the agp context that you want to query, where 0 would be the first agp context in the system. The controlling process should determine the number of supported contexts by calling first calling the AGPIOC_NUM_CTXS ioctl.
The size field is copied back upon successful completion of this ioctl, it represents the size required by the kernel to store an AGPIOC_QUERY_CTX request for this context.
The buffer field is unused in this ioctl, but it represents the address where we want to place the information returned from the AGPIOC_QUERY_CTX ioctl.
AGPIOC_QUERY_CTX
This ioctl provides a method for the controlling process to query some general information about each of the agp contexts available on the system. It accepts a pointer to an agp_query_request pointer as an argument. It copies an agp_driver_info structure back to the address pointed to by the buffer field in agp_query_request. It has the following layout and field definitions:
typedef struct _agp_master {
int agp_major_version;
int agp_minor_version;
__u32 master_pci_id;
int num_requests_enqueue;
int calibration_cycle_ms;
int max_bandwidth_bpp;
int num_trans_per_period;
int max_requests;
int payload_size;
__u32 flags;
} agp_master;
typedef struct _agp_driver_info {
char *driver_name;
int agp_major_version;
int agp_minor_version;
int num_requests_enqueue;
int calibration_cycle_ms;
int optimum_request_size;
int max_bandwidth_bpp;
int iso_latency_in_periods;
int num_trans_per_period;
int payload_size;
__u32 target_pci_id;
__u32 target_flags;
__u32 driver_flags;
off_t aper_base;
size_t aper_size;
int agp_page_shift;
int alloc_page_shift;
unsigned long agp_page_mask;
unsigned long alloc_page_mask;
int max_system_pages;
int current_memory;
int context_id;
int num_masters;
agp_master *masters;
} agp_driver_info;
The driver_name field is a c-type string representing the name of the agpgart driver for this context. It points to an empty string if no driver is currently available.
The agp_major_version field is an integer value of the major agp version supported by this device.
The agp_minor_version field is an integer value of the minor agp version supported by this device.
The num_requests_enqueue field is the value RQDEPTH from this bridge devices AGPSTAT register. For those unfamiliar with the agp interface specification it is the number of agp bus requests that can be buffered on this device at a time.
The calibration_cycle_ms field is the integer value of how long agp io buffer calibration takes on this device, in milliseconds. It is only valid for agp 3.0 devices and higher.
The optimum_request_size field is the value in bytes of the optimum request size for an agp master to generate to this target. It is only valid for agp 3.0 devices and higher.
The max_bandwidth_bpp field is the maximum isochronous bandwidth in bytes per isochronous period. It is only valid if the device supports isochronous transfer mode.
The iso_latency_in_periods is the latency of this device in in isochronous transfer mode. According to the agp 3.0 specification an isochronous period is defined as 1 millisecond. It is only valid if the device supports isochronous transfer mode.
The num_trans_per_period field is the number of isochronous transactions per period this bridge device is able to generate. It is only valid if this device reports that it supports isochronous transfer mode.
The payload_size field is the number of bytes in currently selected per isochronous transaction on this bridge. It is only valid if the device reports that it supports isochronous transfer mode.
The target_pci_id field is the packed value of this agp contexts pci id. The upper 16-bits are the vendor id, while the lower 16-bits are the device id.
The target_flags field contains a bitfield representing this agp bridge devices capability. The following set of tokens or bit values can be used:
Bit 0: AGP_SUPPORTS_ISOCHRONOUS
If this bit is set, the device supports isochronous mode.
Bit 1: AGP_SUPPORTS_SBA
If this bit is set, this device supports side band addressing operation mode.
Bit 2: AGP_SUPPORTS_AGP_3_0_ENABLED
If this bit is set, this device is operating in AGP 3.0 electrical mode, thus disabling the usage of 1X and 2X transfer rates, while enabling 8X transfer rates.
Bit 3: AGP_SUPPORTS_OVER4G_ADDR
If this bit is set, this device supports over 4 gigabyte addressing mode.
Bit 4: AGP_SUPPORTS_FAST_WRITE
If this bit is set, this device supports fast write transactions on the agp bus.
Bit 5: AGP_SUPPORTS_SPEED_1X
If this bit is set, this device supports the AGP 1X transfer rate.
Bit 6: AGP_SUPPORTS_SPEED_2X
If this bit is set, this device supports the AGP 2X transfer rate.
Bit 7: AGP_SUPPORTS_SPEED_4X
If this bit is set, this device supports the AGP 4X transfer rate.
Bit 8: AGP_SUPPORTS_SPEED_8X
If this bit is set, this device supports the AGP 8X transfer rate.
Bit 9: AGP_SUPPORTS_ISO_PAYLOAD_32_B
If this bit is set, this device supports an isochronous payload size of 32 bytes.
Bit 10: AGP_SUPPORTS_ISO_PAYLOAD_64_B
If this bit is set, this device supports an isochronous payload size of 64 bytes.
Bit 11: AGP_SUPPORTS_ISO_PAYLOAD_128_B
If this bit is set, this device supports an isochronous payload size of 128 bytes.
Bit 12: AGP_SUPPORTS_ISO_PAYLOAD_256_B
If this bit is set, this device supports an isochronous payload size of 256 bytes.
Bit 13: AGP_SUPPORTS_CACHED_MEMORY
If this bit is set, this device supports cached memory. This bit field value is only valid for agp targets. Even if this bit is set, the agp driver might choose to not support allocation of agp cached memory.
Bit 14: AGP_SUPPORTS_APER_MMAP
If this bit is set, this device does support directly mapping the agp aperture. If it is clear, this device doesn't support using the agp aperture directly at all.
The driver_flags field is a bitfield that can take on the following tokens and bit values:
Bit 0: AGP_USE_AGP_3_0_MODES
If this bit is set, software should use the values for 4X and 8X in the AGPCMD register as defined in the AGP 3.0 interface specification. Otherwise software should use the AGP 2.0 accepted values.
Bit 1: AGP_CAN_MAP_APERTURE
If this bit is set, software is allowed to directly map the agp aperture from the CPU side.
Bit 2: AGP_MAPS_USE_CACHE_ATTRS
If this bit is set, software should assume that maps of unbound agp memory are mapped write combined or some other system architecture specific caching policy which is fast.
Bit 3: AGP_CAN_DO_CACHED
If this bit is set, software is allowed to allocate AGP_CACHED_MEMORY through the AGPIOC_ALLOCATE ioctl.
Bit 4: AGP_DRIVER_ACTIVE
If this bit is set, this agp bridge has an active driver currently. If it is not set, it can be assumed that the other ioctl's will probably not work on this agp context.
The aper_base field is the bus relative address of the agp aperture.
The aper_size field is the size of the agp aperture in megabytes.
The agp_page_shift is the number of places the value of 1 should be shifted to the left to obtain the size of one agp page.
The alloc_page_shift is the number of places the value of 1 should be shifted to the left to obtain the size of one system page.
The agp_page_mask field is the AND mask which will round an address to an agp page boundary.
The alloc_page_mask field is the AND mask which will round an address to an system page boundary.
The max_system_pages field is the integer value of the number of system pages that the agpgart device will allow to be allocated.
The current_memory field is the integer value representing the current number of pages that the agpgart device has allocated.
The context_id field is the integer representation of this agp bridges context id in the system.
The num_masters field is the number of agp masters that are owned by this context.
The masters field is an array of agp_master structures in turn describing each agp master device. If there are no masters on this device, this points to null. The fields in the agp_master structure have the same meaning as the ones in the driver structure, with the addition of the max_requests field. This field is the maximum number of isochronous requests required for this device to work in isochronous mode. If the device doesn't report itself as supporting isochronous transfers, ignore this field.
AGPIOC_NUM_CTXS
This ioctl provides the controlling process with a method of determining the number of contexts currently supported in the system. It takes no arguments and returns the integer value of the number of contexts available in the system.
AGPIOC_CHG_CTX
This ioctl provides the controlling process with a method of changing the context that the agpgart device driver is currently using. Currently only one agpgart device is allowed, so this function will only succeed if you attempt to change to the first agp context on the system (context zero). It will fail otherwise, or if no context such context exists. Future implementations of multiheaded agp systems will allow this ioctl to work.
Agpgart kernel interface
The agpgart ioctl interface is useful for user land drivers that need GART functionality, however some kernel drivers need this functionality as well. While it might be feasible for kernel drivers to do their own GART manipulations, this is not very portable, and would duplicate a lot of common code. Thus there is a common kernel interface into the Linux agpgart kernel driver for other modules to use. In fact the agpgart kernel driver uses this interface to provide its ioctl functionality. It is fully capable of providing kernel drivers with the abilities that they require. Some knowledge of Linux system programming and operating systems in general would be helpful, but hopefully not required for you to understand this section.
To use this interface in your kernel module you must include the header file <Linux/agp_backend.h>. A full description of the data structures and functions in this header file follows.
Bitfield: flags in agp_info_master and agp_info_target
Bit 0: AGP_SUPPORTS_ISOCHRONOUS
If this bit is set, the device supports isochronous mode.
Bit 1: AGP_SUPPORTS_SBA
If this bit is set, this device supports side band addressing operation mode.
Bit 2: AGP_SUPPORTS_AGP_3_0_ENABLED
If this bit is set, this device is operating in AGP 3.0 electrical mode, thus disabling the usage of 1X and 2X transfer rates, while enabling 8X transfer rates.
Bit 3: AGP_SUPPORTS_OVER4G_ADDR
If this bit is set, this device supports over 4 gigabyte addressing mode.
Bit 4: AGP_SUPPORTS_FAST_WRITE
If this bit is set, this device supports fast write transactions on the agp bus.
Bit 5: AGP_SUPPORTS_SPEED_1X
If this bit is set, this device supports the AGP 1X transfer rate.
Bit 6: AGP_SUPPORTS_SPEED_2X
If this bit is set, this device supports the AGP 2X transfer rate.
Bit 7: AGP_SUPPORTS_SPEED_4X
If this bit is set, this device supports the AGP 4X transfer rate.
Bit 8: AGP_SUPPORTS_SPEED_8X
If this bit is set, this device supports the AGP 8X transfer rate.
Bit 9: AGP_SUPPORTS_ISO_PAYLOAD_32_B
If this bit is set, this device supports an isochronous payload size of 32 bytes.
Bit 10: AGP_SUPPORTS_ISO_PAYLOAD_64_B
If this bit is set, this device supports an isochronous payload size of 64 bytes.
Bit 11: AGP_SUPPORTS_ISO_PAYLOAD_128_B
If this bit is set, this device supports an isochronous payload size of 128 bytes.
Bit 12: AGP_SUPPORTS_ISO_PAYLOAD_256_B
If this bit is set, this device supports an isochronous payload size of 256 bytes.
Bit 13: AGP_SUPPORTS_CACHED_MEMORY
If this bit is set, this device supports cached memory. This bit field value is only valid for agp targets. Even if this bit is set, the agp driver might choose to not support allocation of agp cached memory.
Bit 14: AGP_SUPPORTS_APER_MMAP
If this bit is set, this device does support directly mapping the agp aperture. If it is clear, this device doesn't support using the agp aperture directly at all.
Bitfield: driver_flags in agp_extended_info structure
Bit 0: AGP_USE_AGP_3_0_MODES
If this bit is set, software should use the values for 4X and 8X in the AGPCMD register as defined in the AGP 3.0 interface specification. Otherwise software should use the AGP 2.0 accepted values.
Bit 1: AGP_CAN_MAP_APERTURE
If this bit is set, software is allowed to directly map the agp aperture from the CPU side.
Bit 2: AGP_MAPS_USE_CACHE_ATTRS
If this bit is set, software should assume that maps of unbound agp memory are mapped write combined or some other system architecture specific caching policy which is fast.
Bit 3: AGP_CAN_DO_CACHED
If this bit is set, software is allowed to allocate AGP_CACHED_MEMORY through the AGPIOC_ALLOCATE ioctl or agp_allocate_memory kernel function.
Bit 4: AGP_DRIVER_ACTIVE
If this bit is set, this agp bridge has an active driver currently. If it is not set, it can be assumed that the other ioctl's will probably not work on this agp context.
Structure: agp_info_master
Layout:
typedef struct _agp_info_master {
struct list_head masters;
u8 agp_major_version;
u8 agp_minor_version;
u8 cap_ptr;
struct pci_dev *device;
int num_requests_enqueue;
int calibration_cycle_ms;
int max_bandwidth_bpp;
int num_trans_per_period;
int max_requests;
int payload_size;
u32 flags;
} agp_info_master;
Description:
This structure is much the same as the agp_master structure defined in the ioctl interface. As to not clutter this document to much, only the differences will be enumerated. The only addition here is the masters field, which is a linked list pointer which can be traversed, its head is located in agp_extended_info as master_list.
Structure: agp_info_target
Layout:
typedef struct _agp_info_target {
u8 agp_major_version;
u8 agp_minor_version;
u8 cap_ptr;
struct pci_dev *device;
int num_requests_enqueue;
int optimum_request_size;
int calibration_cycle_ms;
int max_bandwidth_bpp;
int iso_latency_in_periods;
int num_trans_per_period;
int payload_size;
u32 flags;
} agp_info_target;
Description:
This structure contains all the target information that was encapsulated in the agp_driver_info ioctl structure. Please refer to it for field descriptions.
Structure: agp_extended_info
Layout:
typedef struct _agp_extended_info {
struct list_head info_list;
int agp_ctxt_idx;
agp_info_target *bridge;
struct list_head master_list;
int num_masters;
char *driver_name;
u32 driver_flags;
off_t aper_base;
size_t aper_size;
int agp_page_shift;
unsigned long agp_page_mask;
int alloc_page_shift;
unsigned long alloc_page_mask;
int max_system_pages;
int current_memory;
} agp_extended_info;
Description:
This structure encapsulates all the driver information stored in the agp_driver_info ioctl structure, for a complete description of each field please refer to the previous definitions. Here are the deltas from that structure.
The info_list field stores the linked list traversal information for all agp contexts.
The bridge field contains the information about the agp bridge on this context.
The driver_name field will point to NULL when empty, not to an empty string.
Structure: agp_memory
Layout:
typedef struct _agp_memory {
int key;
struct _agp_memory *next;
struct _agp_memory *prev;
size_t page_count;
int num_scratch_pages;
unsigned long *memory;
off_t pg_start;
u32 type;
u32 physical;
u8 is_bound;
u8 is_flushed;
} agp_memory;
Description:
The key field is the “tag” of this allocation as used by the ioctl interface.
The next and prev fields are used internally by the agpgart ioctl interface and shouldn't be used elsewhere.
The page_count field is the number of agp pages this memory structure contains.
The num_scratch_pages field is how many vmalloc'ed pages back the memory field.
The memory field is an array describing each entry into the GART so that software can just copy over the entries when inserting the memory. It is completely device specific and should NEVER be used by portable software.
The pg_start field is the offset in agp pages this memory is currently bound into, if the memory is unbound this field should be ignored.
The type and physical field has the same meaning as the type field in the AGPIOC_ALLOCATE ioctl.
The is_bound field is an integer truth value which indicates if this piece of memory is currently bound into the agp aperture. The value of 1 is considered true, while 0 is considered to be false.
The is_flushed field is an integer truth value which indicates if this agp memory structure has caused the system to flush its caches yet, it is unimportant for users outside agpgart.
Structure: agp_kern_info
Layout:
typedef struct _agp_kern_info {
agp_version version;
struct pci_dev *device;
enum chipset_type chipset;
unsigned long mode;
off_t aper_base;
size_t aper_size;
int max_memory;
int current_memory;
int cant_use_aperture;
unsigned long page_mask;
} agp_kern_info;
Description:
The version field describes the current Interface version of the agpgart interface. Increments in major numbers are considered backwards incompatible, while increments in minor numbers are considered backwards compatible.
The device field contains a kernel pci data structure describing the agp bridge.
The chipset field contains an enumeration as to what chipset this driver represents. Use of this field for anything other then to check for the NOT_SUPPORTED token is depreciated.
The mode field contains the AGPSTAT register from the agp bridge.
The aper_base field contains the offset in pci address space where the agp aperture is located.
The aper_size field contains the size of the agp aperture in megabytes.
The max_memory field contains a integer value representing the maximum number of system pages the agpgart kernel module can use.
The current_memory field contains the number of system pages currently in use by the agpgart interface.
The cant_use_aperture field contains an integer truth value where a value of true means that this agp driver can't map the agp aperture.
The page_mask field represents the value which one needs to AND with an entry in the memory field in the agp_memory structure to get an address back out of it. Since packed entries can never have this sort of behavior, its use is strongly discouraged.
Structure: agp_version
Layout:
typedef struct _agp_version {
u16 major;
u16 minor;
} agp_version;
Description:
The major field represents the current major interface number of the agpgart interface. It is currently equal to zero and will only change if a backwards compatible change to the agpgart interface occurs.
The minor field represents the current minor interface number of the agpgart interface. Anything about 99 should work for the old interface, while anything above 101 should work for the newer interfaces.
Function: agp_backend_acquire
C Prototype:
int agp_backend_acquire(void);
Return values:
returns 0 on success, -EBUSY if the backend is already in use.
Description:
This function provides the caller to become the controlling entity of the agpgart kernel module. While it is the controlling entity it is guaranteed that no one else will use the GART remapping hardware. Do not call any other kernel functions without first calling this one.
Function: agp_backend_release
C Prototype:
void agp_backend_release(void);
Return values:
This function has not return values.
Description:
It is the responsibility of the caller to insure it was truly the owner of the agp backend when it calls this function. It will release the backend for use by others entities in the system.
Function: agp_free_memory
C Prototype:
void agp_free_memory(agp_memory *);
Return values:
This function has no return values.
Description:
This function frees a block of agp memory previously allocated by the function agp_allocate_memory. It takes this as its first argument. It is the responsibility of the caller to insure the argument does not point to a null pointer.
Function: agp_allocate_memory
C Prototype:
agp_memory *agp_allocate_memory(size_t, u32);
Return values:
This function returns an agp_memory structure describing this allocation.
Description:
This function provides a method by which you can allocate a block of agp memory to back the agp aperture with. Its first argument is the value in agp pages you want to back this block of memory, and the second argument is an agp type token. Typically you use the token AGP_NORMAL_MEMORY, however any of the previous values outlined in the ioctl specification are valid.
Function: agp_copy_info
C Prototype:
int agp_copy_info(agp_kern_info *);
Return values:
This function returns a value of -1 if there is no agp bridge, and a value of 0 upon success.
Description:
This function copies over several bits of information about the current agp bridge to the pointer passed into the first argument.
Function: agp_bind_memory
C Prototype:
int agp_bind_memory(agp_memory *, off_t);
Return values:
This function returns 0 upon success, the value -EINVAL if the pointer in the first argument was NULL, and the value of -EBUSY if the requested region in the agp aperture was already bound with another block of agp memory.
Description:
The first argument to this function is an agp_memory structure previously returned by the agp_allocate_memory function. The second argument is the agp page offset into the agp aperture we want this block of agp memory to begin.
Function: agp_unbind_memory
C Prototype:
int agp_unbind_memory(agp_memory *);
Return values:
This function returns a value of 0 upon success and a value of -EINVAL if this piece of agp memory is not currently bound into the agp aperture.
Description:
The agp_unbind_memory function removes a block of memory previously bound into the agp aperture by the agp_bind_memory function. It takes an agp_memory structure as its only argument.
Function: agp_enable
C Prototype:
void agp_enable(u32);
Return values:
This function has no return values.
Description:
This function will enable the agp point to point connection between this target and any masters that are subordinate to it. While the current implementation does not address isochronous mode setting, it the device supports isochronous mode it will attempt to initialize isochronous mode as well. The only argument to this function is the AGPSTAT register you want to use for command decisions. For a full definition of the AGPSTAT register please see the AGP 2.0 or 3.0 interface specification.
Function: agp_get_map
C Prototype:
int agp_get_map(int, agp_memory **);
Return values:
This function returns 0 upon success and the value -EINVAL if it doesn't find the block of memory in this contexts memory list.
Description:
This function attempts to lookup the memory block associated with the key passed in as the first argument. The second argument is a pointer to a pointer where we can place the agp_memory block that we find.
Function: agp_kmap
C Prototype:
void *agp_kmap(agp_memory *, unsigned long, unsigned long);
Return values:
This function returns the pointer to the mapped region in kernel address space or NULL to indicate an error occurred.
Description:
This function takes an agp_memory pointer as its first argument, the byte offset into the agp memory block as its second, and the size of the requested region in bytes as its third argument. It will attempt to map this block described by the agp memory structure into kernel address space and return its address. If the block is currently unbound, the mapping provided might be slow, and the user should check the values in the structure returned by the agp_get_extended_info function to determine the speed of unbound mappings.
Function: agp_kunmap
C Prototype:
void agp_kunmap(agp_memory *, void *);
Return values:
This function has no return values.
Description:
This function will teardown a mapping in kernel space which was previously obtained by calling agp_kmap. The first argument is a pointer to the agp_memory structure which the second argument maps. The second argument is the address previously returned by agp_kmap.
Function: agp_vma_map_memory
C Prototype:
int agp_vma_map_memory(struct vm_area_struct *, agp_memory *, unsigned long);
Return values:
This function returns -ENOMEM on error, or the value 0 upon success.
Description:
This function maps a currently active vma up with a given agp_memory structure. The first argument is the vma we want to map into, the second argument the agp_memory structure we want to map there, the third is the byte offset into the agp memory structure we want to map into the vma. That offset is required to be on a system page boundary.
Function: agp_usermap
C Prototype:
unsigned long agp_usermap(struct file *, agp_memory *, unsigned long, unsigned long, unsigned long, unsigned long);
Return values:
This function returns 0 upon error, or the address into the current process's address space of the mapping.
Description:
This function takes a kernel file structure as its first argument, an pointer to the block of agp memory we want to map, the offset into the agp memory structure in bytes as its third, the prot argument mmap would require as its fourth, and the flags argument that mmap would require as its fifth. It will perform a mapping of a region of agp memory into the current process's address space.
Function: agp_userunmap
C Prototype:
void agp_userunmap(agp_memory *, void *);
Return values:
This function has no return values.
Description:
This function will tear down a mapping previously created by calling agp_usermap. It takes an agp memory structure as its first argument and the process address that we want to remove.
Function: agp_get_num_contexts
C Prototype:
int agp_get_num_contexts(void);
Return values:
This function returns the number of agp contexts registered in the agpgart module.
Description:
Software should call this function to determine the number of contexts during initialization.
Function: agp_get_extended_info
C Prototype:
struct list_head *agp_get_extended_info(void);
Return values:
A struct list_head pointer describing the targets, drivers, and masters the
agpgart module knows about.
Description:
Software should call this function during initialization and whenever it wants to query updated information about the agpgart kernel module. See the description of the agp_extended_info structure for details on accessing this information.
Function: agp_ctx_free_memory
Function: agp_ctx_allocate_memory
Function: agp_ctx_copy_info
Function: agp_ctx_bind_memory
Function: agp_ctx_unbind_memory
Function: agp_ctx_backend_acquire
Function: agp_ctx_get_map
Function: agp_ctx_backend_release
Function: agp_ctx_kmap
Function: agp_ctx_kunmap
Function: agp_ctx_vma_map_memory
Function: agp_ctx_userunmap
Function: agp_ctx_usermap
Description:
This whole family of functions are identical to their context unaware siblings except they take an integer argument of the context they want to manipulate
as their first argument.
Inter Module Interface Token: “drm_agp”
Layout:
typedef struct {
void (*free_memory)(agp_memory *);
agp_memory *(*allocate_memory)(size_t, u32);
int (*bind_memory)(agp_memory *, off_t);
int (*unbind_memory)(agp_memory *);
void (*enable)(u32);
int (*acquire)(void);
void (*release)(void);
int (*copy_info)(agp_kern_info *);
} drm_agp_t;
Description:
All the agpgart 0.99 kernel functions inside a structure which can be looked up by inter_module_get. Used when a module needs access to the agp interface via a module. Legacy software should query for this structure if it doesn't find the newer one.
Inter Module Interface Token: “drm_agp_3_0”
Layout:
typedef struct {
int (*get_num_contexts)(void);
struct list_head *(*get_info_list)(void);
void (*free_memory)(int, agp_memory *);
agp_memory *(*allocate_memory)(int, size_t, u32);
int (*bind_memory)(int, agp_memory *, off_t);
int (*unbind_memory)(int, agp_memory *);
void (*enable)(int, u32);
int (*acquire)(int);
void (*release)(int);
int (*copy_info)(int, agp_kern_info *);
int (*get_map)(int, int, agp_memory **);
void *(*kmap)(int, agp_memory *, unsigned long, unsigned long);
int (*vma_map_memory)(int, struct vm_area_struct *, agp_memory *, unsigned long);
unsigned long (*usermap)(int, struct file *, agp_memory *, unsigned long, unsigned long,
unsigned long, unsigned long);
void (*userunmap)(int, agp_memory *, void *);
void (*kunmap)(int, agp_memory *, void *);
} drm_agp_3_0_t;
Description:
All the agpgart 2.0 kernel functions inside a structure which can be looked up by inter_module_get. Used when a module needs access to the agp interface via a module. All the provided functions are the context aware versions.
@