Ioctl Requests agpgartio(7I)
NAME
agpgartio - Solaris agpgart driver I/O control operations
SYNOPSIS
#include
DESCRIPTION
The Accelerated Graphics Port (AGP) is a PCI bus technology
enhancement that improves 3D graphics performance by using
low-cost system memory. AGP chipsets use the Graphics
Address Remapping Table (GART) to map discontiguous system
memory into a contiguous PCI memory range (known as the AGP
Aperture), enabling the graphics card to utilize the mapped
aperture range as video memory.
The agpgart driver creates a pseudo device node at
/dev/agpgart and provides a set of ioctls for managing
allocation/deallocation of system memory, setting mappings
between system memory and aperture range, and setting up AGP
devices. The agpgart driver manages both pseudo and real
device nodes, but to initiate AGP-related operations you
operate only on the /dev/agpgart pseudo device node. To do
this, open /dev/agpgart. The macro defined for the pseudo
device node name is:
#define AGPDEVICE "/dev/agpgart"
The agpgartio driver implementation is AGP architecture-
dependent and cannot be made generic. Currently, the
agpgartio driver only supports specific AGP systems. To
determine if a system is supported, run an open(2) system
call on the AGPDEVICE node. (Note that open(2) fails if a
system is not supported). After the AGPDEVICE is opened,
you can use kstat(1M) to read the system architecture
type.
In addition to AGP system support, the agpgart ioctls can
also be used on Intel integrated graphics devices (IGD). IGD
devices usually have no dedicated video memory and must use
system memory as video memory. IGD devices contain transla-
tion tables (referred to as GT tables) that are similar to
the GART translation table for address mapping purposes.
Processes must open the agpgartio driver utilizing a
GRAPHICSACES privilege. Then all the ioctls can be
called by this processes with the saved file descriptor.
SunOS 5.11 Last change: 25 Sep 2008 1
Ioctl Requests agpgartio(7I)
With the exception of AGPIOCINFO, the AGPIOCACQUIRE ioctl
must be called before any other ioctl. Once a process has
acquired GART, it cannot be acquired by another process
until the former process calls AGPIOCRELEASE.
If the AGPDEVICE fails to open, it may be due to one of the
following reasons:
EAGAIN
GART table allocation failed.
EIO
Internal hardware initialization failed.
ENXIO
Getting device soft state error. (This is unlikely to
happen.)
EPERM
Without enough privilege.
IOCTLS
With the exception of GPIOCINFO, all ioctls shown in this
section are protected by GRAPHICSACES privilege. (Only
processes with GRAPHICSACES privilege in its effective
set can access the privileged ioctls).
Common ioctl error codes are shown below. (Additional error
codes may be displayed by individual ioctls.)
ENXIO
Ioctl command not supported or getting device soft state
error.
EPERM
Process not privileged.
SunOS 5.11 Last change: 25 Sep 2008 2
Ioctl Requests agpgartio(7I)
AGPIOCINFO
Get system wide AGP or IGD hardware information. This
command can be called by any process from user or kernel
context.
The argument is a pointer to agpinfot structure.
typedef struct agpinfo {
agpversiont agpiversion; /* OUT: AGP version supported */
uint32t agpidevid; /* OUT: bridge vendor ] device */
uint32t agpimode; /* OUT: mode of bridge */
ulongt agpiaperbase; /* OUT: base of aperture */
sizet agpiapersize; /* OUT: aperture size in MB */
uint32t agpipgtotal; /* OUT: max aperture pages avail. */
uint32t agpipgsystem; /* OUT: same as pgtotal */
uint32t agpipgused; /* OUT: no. of currently used pages */
} agpinfot;
agpiversion The version of AGP protocol the bridge device is
compatible with, for example, major 3 and minor 0
means AGP version 3.0.
typedef struct agpversion {
uint16t agpvmajor;
uint16t agpvminor;
} agpversiont;
agpidevid AGP bridge vendor and device ID.
agpimode Current AGP mode, read from AGP status register of
target device. The main bits are defined as below.
/* AGP status register bits definition */
#define AGPSTATRQMASK 0xff000000
#define AGPSTATSBA (0x1 << 9)
#define AGPSTATOVER4G (0x1 << 5)
#define AGPSTATFW (0x1 << 4)
#define AGPSTATRATEMASK 0x7
/* AGP 3.0 only bits */
#define AGPSTATARQSZMASK (0x7 << 13)
#define AGPSTATCALMASK (0x7 << 10)
#define AGPSTATGART64B (0x1 << 7)
#define AGPSTATMODE3 (0x1 << 3)
/* rate for 2.0 mode */
#define AGP2RATE1X 0x1
#define AGP2RATE2X 0x2
#define AGP2RATE4X 0x4
/* rate for 3.0 mode */
#define AGP3RATE4X 0x1
#define AGP3RATE8X 0x2
agpiaperbase The base address of aperture in PCI memory space.
SunOS 5.11 Last change: 25 Sep 2008 3
Ioctl Requests agpgartio(7I)
agpiapersize The size of the aperture in megabytes.
agpipgtotal Represents the maximum memory
pages the system can allocate
according to aperture size and
system memory size (which may differ
from the maximum locked memory a process
can have. The latter is subject
to the memory resource limit imposed
by the resourcecontrols(5) for each
project(4)):
project.max-device-locked-memory
This value can be modified through system
utilities like prctl(1).
agpipgsystem Same as pgtotal.
agpipgused System pages already allocated by the driver.
Return Values:
EFAULT Argument copy out error
EINVAL Command invalid
0 Success
AGPIOCACQUIRE
Acquire control of GART. With the exception of
AGPIOCINFO, a process must acquire GART before can it
call other agpgart ioctl commands. Additionally, only
processes with GRAPHICSACES privilege may access this
ioctl. In the current agpgart implementation, GART
access is exclusive, meaning that only one process can
perform GART operations at a time. To release control
over GART, call AGPIOCRELEASE. This command can be
called from user or kernel context.
The argument should be NUL.
Return values:
EBUSY GART has been acquired
0 Success.
AGPIOCRELEASE
SunOS 5.11 Last change: 25 Sep 2008 4
Ioctl Requests agpgartio(7I)
Release GART control. If a process releases GART con-
trol, it cannot perform additional GART operations until
GART is reacquired. Note that this command does not free
allocated memory or clear GART entries. (All clear jobs
are done by direct calls or by closing the device). When
a process exits without making this ioctl, the final
close(2) performs this automatically. This command can
be called from user or kernel context.
The argument should be NUL.
Return values:
EPERM Not owner of GART.
0 Success.
AGPIOCSETUP
Setup AGPCMD register. An AGPCMD register resides in
both the AGP master and target devices. The AGPCMD
register controls the working mode of the AGP master and
target devices. Each device must be configured using
the same mode. This command can be called from user or
kernel context.
The argument is a pointer to agpsetupt structure:
typedef struct agpsetup {
uint32t agpsmode; /* IN: value to be set for AGPCMD */
} agpsetupt;
agpsmode Specifying the mode to be set. Each bit of the value may have
a specific meaning, please refer to AGP 2.0/3.0 specification
or hardware datasheets for details.
/* AGP command register bits definition */
#define AGPCMDRQMASK 0xff000000
#define AGPCMDSBAEN (0x1 << 9)
#define AGPCMDAGPEN (0x1 << 8)
#define AGPCMDOVER4GEN (0x1 << 5)
#define AGPCMDFWEN (0x1 << 4)
#define AGPCMDRATEMASK 0x7
/* AGP 3.0 only bits */
#define AGP3CMDARQSZMASK (0x7 << 13)
#define AGP3CMDCALMASK (0x7 << 10)
#define AGP3CMDGART64BEN (0x1 << 7)
The final values set to the AGPCMD register of the
SunOS 5.11 Last change: 25 Sep 2008 5
Ioctl Requests agpgartio(7I)
master/target devices are decided by the agpsmode value
and AGPSTAT of the master and target devices.
Return Values:
EPERM Not owner of GART.
EFAULT Argument copy in error.
EINVAL Command invalid for non-AGP system.
EIO Hardware setup error.
0 Success.
AGPIOCALOCATE
Allocate system memory for graphics device. This command
returns a unique ID which can be used in subsequent
operations to represent the allocated memory. The memory
is made up of discontiguous physical pages. In rare
cases, special memory types may be required. The allo-
cated memory must be bound to the GART table before it
can be used by graphics device. Graphics applications
can also mmap(2) the memory to userland for data stor-
ing. Memory should be freed when it is no longer used by
calling AGPIOCDEALOCATE or simply by closing the dev-
ice. This command can be called from user or kernel con-
text.
The argument is a pointer to agpallocatet structure.
typedef struct agpallocate {
int32t agpakey; /* OUT:ID of allocated memory */
uint32t agpapgcount;/* IN: no. of pages to be allocated */
uint32t agpatype;/* IN: type of memory to be allocated */
uint32t agpaphysical; /* OUT: reserved */
} agpallocatet;
agpakey Unique ID of the allocated memory.
agpapgcount Number of pages to be allocated.
The driver currently supports only
4K pages. The value cannot exceed
SunOS 5.11 Last change: 25 Sep 2008 6
Ioctl Requests agpgartio(7I)
the agpipgtotal value returned by
AGPIOCINFO ioct and is subject to
the limit of project.max-device-
locked-memory. If the memory needed
is larger than the resource limit
but not larger than agpipgtotal,
use prctl(1) or other system utili-
ties to change the default value of
memory resource limit beforehand.
agpatype Type of memory to be allocated. The
valid value of agpatype should be
AGPNORMAL. It is defined as:
#define AGPNORMAL 0
Above, AGPNORMAL represents the
discontiguous non-cachable physical
memory which doesn't consume kernel
virtual space but can be mapped to
user space by mmap(2). This command
may support more type values in the
future.
agpaphysical Reserved for special uses. In nor-
mal operations, the value is unde-
fined.
Return Values:
EPERM Not owner of GART.
EINVAL Argument not valid.
EFAULT Argument copy in/out
error.
ENOMEM Memory allocation error.
0 Success.
AGPIOCDEALOCATE Deallocate the memory identified by
a key assigned in a previous allo-
cation. If the memory isn't unbound
SunOS 5.11 Last change: 25 Sep 2008 7
Ioctl Requests agpgartio(7I)
from GART, this command unbinds it
automatically. The memory should no
longer be used and those still in
mapping to userland cannot be deal-
located. Always call
AGPIOCDEALOCATE explicitly
(instead of deallocating impli-
citly by closing the device), as
the system won't carry out the job
until the last reference to the
device file is dropped. This com-
mand from user or kernel context.
The input argument is a key of type
int32t, no output argument.
Return Values:
EPERM Not owner of GART.
EINVAL Key not valid or memory
in use.
0 Success.
AGPIOCBIND Bind allocated memory. This com-
mand binds the allocated memory
identified by a key to a specific
offset of the GART table, which
enables GART to translate the
aperture range at the offset to
system memory. Each GART entry
represents one physical page. If
the GART range is previously bound
to other system memory, it returns
an error. Once the memory is bound,
it cannot be bound to other offsets
unless it is unbound. To unbind the
memory, call AGPIOCUNBIND or deal-
locate the memory. This command can
be called from user or kernel con-
text.
The argument is a pointer to agpbindt structure:
typedef struct agpbind {
int32t agpbkey; /* IN: ID of memory to be bound */
uint32t agpbpgstart; /* IN: offset in aperture */
SunOS 5.11 Last change: 25 Sep 2008 8
Ioctl Requests agpgartio(7I)
} agpbindt;
agpbkey The unique ID
of the memory
to be bound,
which is previ-
ously allocated
by calling
AGPIOCALOCATE.
agpbpgstart The starting
page offset to
be bound in
aperture space.
Return Values:
EPERM Not owner of
GART.
EFAULT Argument copy
in error.
EINVAL Argument not
valid.
EIO Binding to the
GT table of
IGD devices
failed.
0 Success.
AGPIOCUNBIND Unbind memory identified by a key
from the GART. This command clears
the corresponding entries in the
GART table. Only the memory not in
mapping to userland is allowed to
be unbound.
This ioctl command can be called
from user or kernel context.
The argument is a pointer to agpunbindt structure.
SunOS 5.11 Last change: 25 Sep 2008 9
Ioctl Requests agpgartio(7I)
typedef struct agpunbind {
int32t agpukey; /* IN: key of memory to be unbound*/
uint32t agpupri; /* Not used: for compat. with Xorg */
} agpunbindt;
agpukey Unique ID of
the memory to
be unbound
which was pre-
viously bound
by calling
AGPIOCBIND.
agpupri Reserved for
compatibility
with
X.org/XFree86,
not used.
Return Values:
EPERM Not owner of
GART.
EFAULT Argument copy
in error.
EINVAL Argument not
valid or memory
in use.
EIO Unbinding from
the GT table
of IGD devices
failed.
0 Success
EXAMPLE
Below is an sample program showing how agpgart ioctls can be
used:
#include
SunOS 5.11 Last change: 25 Sep 2008 10
Ioctl Requests agpgartio(7I)
#include
#include
#include
#include
#include
#include
#include
#define AGPAGESIZE 4096
int main(int argc, char *argv[])
{
int fd, ret;
agpallocatet alloc;
agpbindt bindinfo;
agpinfot agpinfo;
agpsetupt modesetup;
int *p = NUL;
offt mapoff;
sizet maplen;
if((fd = open(AGPDEVICE, ORDWR))== -1) {
printf("open AGPDEVICE error with %d\n", errno);\
exit(-1);
}
printf("device opened\n");
ret = ioctl(fd, AGPIOCINFO, &agpinfo);
if(ret == -1) {
printf("Get info error %d0, errno);
exit(-1);
}
printf("AGPSTAT is %x\n", agpinfo.agpimode);
printf("APBASE is %x\n", agpinfo.agpiaperbase);
printf("APSIZE is %dMB\n", agpinfo.agpiapersize);
printf("pgtotal is %d\n", agpinfo.agpipgtotal);
ret = ioctl(fd, AGPIOCACQUIRE);
if(ret == -1) {
printf(" Acquire GART error %d\n", errno);
exit(-1);
}
modesetup.agpsmode = agpinfo.agpimode;
ret = ioctl(fd, AGPIOCSETUP, &modesetup);
if(ret == -1) {
printf("set up AGP mode error\n", errno);
exit(-1);
}
printf("Please input the number of pages you want to allocate\n");
SunOS 5.11 Last change: 25 Sep 2008 11
Ioctl Requests agpgartio(7I)
scanf("%d", &alloc.agpapgcount);
alloc.agpatype = AGPNORMAL;
ret = ioctl(fd, AGPIOCALOCATE, &alloc);
if(ret == -1) {
printf("Allocate memory error %d\n", errno);
exit(-1);
}
printf("Please input the aperture page offset to bind\n");
scanf("%d", &bindinfo.agpbpgstart);
bindinfo.agpbkey = alloc.agpakey;
ret = ioctl(fd, AGPIOCBIND, &bindinfo);
if(ret == -1) {
printf("Bind error %d\n", errno);
exit(-1);
}
printf("Bind successful\n");
/*
* Now gart aperture space from (bindinfo.agpbpgstart) to
* (bindinfo.agpbpgstart ] alloc.agpapgcount) can be used for
* AGP graphics transactions
*/
...
/*
* mmap can allow user processes to store graphics data
* to the aperture space
*/
maplen = alloc.agpapgcount * AGPAGESIZE;
mapoff = bindinfo.agpbpgstart * AGPAGESIZE;
p = (int *)mmap((caddrt)0, maplen, (PROTREAD PROTWRITE),
MAPSHARED, fd, mapoff);
if (p == MAPFAILED) {
printf("Mmap error %d\n", errno);
exit(-1);
}
printf("Mmap successful\n");
...
/*
* When user processes finish access to the aperture space,
* unmap the memory range
*/
munmap((void *)p, maplen);
...
/*
* After finishing AGP transactions, the resources can be freed
* step by step or simply by close device.
*/
ret = ioctl(fd, AGPIOCDEALOCATE, alloc.agpakey);
SunOS 5.11 Last change: 25 Sep 2008 12
Ioctl Requests agpgartio(7I)
if(ret == -1) {
printf(" Deallocate memory error %d\n", errno);
exit(-1);
}
ret = ioctl(fd, AGPIOCRELEASE);
if(ret == -1) {
printf(" Release GART error %d\n", errno);
exit(-1);
}
close(fd);
}
FILES
/dev/agpgart
Symbolic link to the pseudo agpgart device.
/platform/i86pc/kernel/drv/agpgart
agpgart pseudo driver.
/platform/i86pc/kernel/drv/agpgart.conf
Driver configuration file.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 25 Sep 2008 13
Ioctl Requests agpgartio(7I)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture X86
Availability SUNWagp, SUNWagph
Stability level Unstable
SEE ALSO
prctl(1), kstat(1M), close(2), ioctl(2), open(2), mmap(2),
project(4), privileges(5), attributes(5),
resourcecontrols(5)
SunOS 5.11 Last change: 25 Sep 2008 14
|
