1agpgart_io(7I) Ioctl Requests agpgart_io(7I)
2
6 agpgart_io - Solaris agpgart driver I/O control operations
7
9 #include <sys/agpgart.h>
10
13 The Accelerated Graphics Port (AGP) is a PCI bus technology enhancement
14 that improves 3D graphics performance by using low-cost system memory.
15 AGP chipsets use the Graphics Address Remapping Table (GART) to map
16 discontiguous system memory into a contiguous PCI memory range (known
17 as the AGP Aperture), enabling the graphics card to utilize the mapped
18 aperture range as video memory.
19 The agpgart driver creates a pseudo device node at /dev/agpgart and
22 provides a set of ioctls for managing allocation/deallocation of sys‐
23 tem memory, setting mappings between system memory and aperture range,
24 and setting up AGP devices. The agpgart driver manages both pseudo and
25 real device nodes, but to initiate AGP-related operations you operate
26 only on the /dev/agpgart pseudo device node. To do this, open /dev/agp‐
27 gart. The macro defined for the pseudo device node name is:
28 #define AGP_DEVICE "/dev/agpgart"
30 The agpgart_io driver implementation is AGP architecture-dependent and
34 cannot be made generic. Currently, the agpgart_io driver only supports
35 specific AGP systems. To determine if a system is supported, run an
36 open(2) system call on the AGP_DEVICE node. (Note that open(2) fails
37 if a system is not supported). After the AGP_DEVICE is opened, you can
38 use kstat(1M) to read the system architecture type.
39 In addition to AGP system support, the agpgart ioctls can also be used
42 on Intel integrated graphics devices (IGD). IGD devices usually have no
43 dedicated video memory and must use system memory as video memory. IGD
44 devices contain translation tables (referred to as GTT tables) that are
45 similar to the GART translation table for address mapping purposes.
46 Processes must open the agpgart_io driver utilizing a GRAPHICS_ACCESS
49 privilege. Then all the ioctls can be called by this processes with
50 the saved file descriptor. With the exception of AGPIOC_INFO, the
51 AGPIOC_ACQUIRE ioctl must be called before any other ioctl. Once a
52 process has acquired GART, it cannot be acquired by another process
53 until the former process calls AGPIOC_RELEASE.
54 If the AGP_DEVICE fails to open, it may be due to one of the following
57 reasons:
58 EAGAIN
60 GART table allocation failed.
62 EIO
65 Internal hardware initialization failed.
67 ENXIO
70 Getting device soft state error. (This is unlikely to happen.)
72 EPERM
75 Without enough privilege.
77
80 With the exception of GPIOC_INFO, all ioctls shown in this section are
81 protected by GRAPHICS_ACCESS privilege. (Only processes with GRAPH‐
82 ICS_ACCESS privilege in its effective set can access the privileged
83 ioctls).
84 Common ioctl error codes are shown below. (Additional error codes may
87 be displayed by individual ioctls.)
88 ENXIO
90 Ioctl command not supported or getting device soft state error.
92 EPERM
95 Process not privileged.
97 AGPIOC_INFO
100 Get system wide AGP or IGD hardware information. This command can
102 be called by any process from user or kernel context.
103 The argument is a pointer to agp_info_t structure.
105 typedef struct _agp_info {
107 agp_version_t agpi_version; /* OUT: AGP version supported */
108 uint32_t agpi_devid; /* OUT: bridge vendor + device */
109 uint32_t agpi_mode; /* OUT: mode of bridge */
110 ulong_t agpi_aperbase; /* OUT: base of aperture */
111 size_t agpi_apersize; /* OUT: aperture size in MB */
112 uint32_t agpi_pgtotal; /* OUT: max aperture pages avail. */
113 uint32_t agpi_pgsystem; /* OUT: same as pg_total */
114 uint32_t agpi_pgused; /* OUT: no. of currently used pages */
115 } agp_info_t;
116 agpi_version The version of AGP protocol the bridge device is
118 compatible with, for example, major 3 and minor 0
119 means AGP version 3.0.
120 typedef struct _agp_version {
122 uint16_t agpv_major;
123 uint16_t agpv_minor;
124 } agp_version_t;
125 agpi_devid AGP bridge vendor and device ID.
127 agpi_mode Current AGP mode, read from AGP status register of
128 target device. The main bits are defined as below.
129 /* AGP status register bits definition */
130 #define AGPSTAT_RQ_MASK 0xff000000
132 #define AGPSTAT_SBA (0x1 << 9)
133 #define AGPSTAT_OVER4G (0x1 << 5)
134 #define AGPSTAT_FW (0x1 << 4)
135 #define AGPSTAT_RATE_MASK 0x7
136 /* AGP 3.0 only bits */
137 #define AGPSTAT_ARQSZ_MASK (0x7 << 13)
138 #define AGPSTAT_CAL_MASK (0x7 << 10)
139 #define AGPSTAT_GART64B (0x1 << 7)
140 #define AGPSTAT_MODE3 (0x1 << 3)
141 /* rate for 2.0 mode */
142 #define AGP2_RATE_1X 0x1
143 #define AGP2_RATE_2X 0x2
144 #define AGP2_RATE_4X 0x4
145 /* rate for 3.0 mode */
146 #define AGP3_RATE_4X 0x1
147 #define AGP3_RATE_8X 0x2
148 agpi_aperbase The base address of aperture in PCI memory space.
150 agpi_apersize The size of the aperture in megabytes.
151 agpi_pgtotal Represents the maximum memory
152 pages the system can allocate
153 according to aperture size and
154 system memory size (which may differ
155 from the maximum locked memory a process
156 can have. The latter is subject
157 to the memory resource limit imposed
158 by the resource_controls(5) for each
159 project(4)):
160 project.max-device-locked-memory
162 This value can be modified through system
164 utilities like prctl(1).
165 agpi_pgsystem Same as pg_total.
167 agpi_pgused System pages already allocated by the driver.
168 Return Values:
170 EFAULT Argument copy out error
172 EINVAL Command invalid
173 0 Success
174 AGPIOC_ACQUIRE
178 Acquire control of GART. With the exception of AGPIOC_INFO, a
180 process must acquire GART before can it call other agpgart ioctl
181 commands. Additionally, only processes with GRAPHICS_ACCESS privi‐
182 lege may access this ioctl. In the current agpgart implementation,
183 GART access is exclusive, meaning that only one process can perform
184 GART operations at a time. To release control over GART, call
185 AGPIOC_RELEASE. This command can be called from user or kernel con‐
186 text.
187 The argument should be NULL.
189 Return values:
191 EBUSY GART has been acquired
193 0 Success.
196 AGPIOC_RELEASE
200 Release GART control. If a process releases GART control, it cannot
202 perform additional GART operations until GART is reacquired. Note
203 that this command does not free allocated memory or clear GART
204 entries. (All clear jobs are done by direct calls or by closing the
205 device). When a process exits without making this ioctl, the final
206 close(2) performs this automatically. This command can be called
207 from user or kernel context.
208 The argument should be NULL.
210 Return values:
212 EPERM Not owner of GART.
214 0 Success.
217 AGPIOC_SETUP
221 Setup AGPCMD register. An AGPCMD register resides in both the AGP
223 master and target devices. The AGPCMD register controls the working
224 mode of the AGP master and target devices. Each device must be
225 configured using the same mode. This command can be called from
226 user or kernel context.
227 The argument is a pointer to agp_setup_t structure:
229 typedef struct _agp_setup {
231 uint32_t agps_mode; /* IN: value to be set for AGPCMD */
232 } agp_setup_t;
233 agps_mode Specifying the mode to be set. Each bit of the value may have
235 a specific meaning, please refer to AGP 2.0/3.0 specification
236 or hardware datasheets for details.
237 /* AGP command register bits definition */
239 #define AGPCMD_RQ_MASK 0xff000000
240 #define AGPCMD_SBAEN (0x1 << 9)
241 #define AGPCMD_AGPEN (0x1 << 8)
242 #define AGPCMD_OVER4GEN (0x1 << 5)
243 #define AGPCMD_FWEN (0x1 << 4)
244 #define AGPCMD_RATE_MASK 0x7
245 /* AGP 3.0 only bits */
246 #define AGP3_CMD_ARQSZ_MASK (0x7 << 13)
247 #define AGP3_CMD_CAL_MASK (0x7 << 10)
248 #define AGP3_CMD_GART64BEN (0x1 << 7)
249 The final values set to the AGPCMD register of the master/target
251 devices are decided by the agps_mode value and AGPSTAT of the mas‐
252 ter and target devices.
253 Return Values:
255 EPERM Not owner of GART.
257 EFAULT Argument copy in error.
260 EINVAL Command invalid for non-AGP system.
263 EIO Hardware setup error.
266 0 Success.
269 AGPIOC_ALLOCATE
273 Allocate system memory for graphics device. This command returns a
275 unique ID which can be used in subsequent operations to represent
276 the allocated memory. The memory is made up of discontiguous physi‐
277 cal pages. In rare cases, special memory types may be required. The
278 allocated memory must be bound to the GART table before it can be
279 used by graphics device. Graphics applications can also mmap(2) the
280 memory to userland for data storing. Memory should be freed when it
281 is no longer used by calling AGPIOC_DEALLOCATE or simply by closing
282 the device. This command can be called from user or kernel context.
283 The argument is a pointer to agp_allocate_t structure.
285 typedef struct _agp_allocate {
287 int32_t agpa_key; /* OUT:ID of allocated memory */
288 uint32_t agpa_pgcount;/* IN: no. of pages to be allocated */
289 uint32_t agpa_type;/* IN: type of memory to be allocated */
290 uint32_t agpa_physical; /* OUT: reserved */
291 } agp_allocate_t;
292 agpa_key Unique ID of the allocated memory.
295 agpa_pgcount Number of pages to be allocated. The driver
298 currently supports only 4K pages. The value
299 cannot exceed the agpi_pgtotal value returned
300 by AGPIOC_INFO ioct and is subject to the
301 limit of project.max-device-locked-memory. If
302 the memory needed is larger than the resource
303 limit but not larger than agpi_pgtotal, use
304 prctl(1) or other system utilities to change
305 the default value of memory resource limit
306 beforehand.
307 agpa_type Type of memory to be allocated. The valid
310 value of agpa_type should be AGP_NORMAL. It is
311 defined as:
312 #define AGP_NORMAL 0
314 Above, AGP_NORMAL represents the discontiguous
316 non-cachable physical memory which doesn't
317 consume kernel virtual space but can be mapped
318 to user space by mmap(2). This command may
319 support more type values in the future.
320 agpa_physical Reserved for special uses. In normal opera‐
323 tions, the value is undefined.
324 Return Values:
326 EPERM Not owner of GART.
328 EINVAL Argument not valid.
331 EFAULT Argument copy in/out error.
334 ENOMEM Memory allocation error.
337 0 Success.
340 AGPIOC_DEALLOCATE Deallocate the memory identified by a key
344 assigned in a previous allocation. If the mem‐
345 ory isn't unbound from GART, this command
346 unbinds it automatically. The memory should no
347 longer be used and those still in mapping to
348 userland cannot be deallocated. Always call
349 AGPIOC_DEALLOCATE explicitly (instead of deal‐
350 locating implicitly by closing the device),
351 as the system won't carry out the job until
352 the last reference to the device file is
353 dropped. This command from user or kernel con‐
354 text.
355 The input argument is a key of type int32_t,
357 no output argument.
358 Return Values:
360 EPERM Not owner of GART.
362 EINVAL Key not valid or memory in use.
365 0 Success.
368 AGPIOC_BIND Bind allocated memory. This command binds
372 the allocated memory identified by a key to
373 a specific offset of the GART table, which
374 enables GART to translate the aperture
375 range at the offset to system memory. Each
376 GART entry represents one physical page. If
377 the GART range is previously bound to other
378 system memory, it returns an error. Once the
379 memory is bound, it cannot be bound to other
380 offsets unless it is unbound. To unbind the
381 memory, call AGPIOC_UNBIND or deallocate the
382 memory. This command can be called from user
383 or kernel context.
384 The argument is a pointer to agp_bind_t structure:
386 typedef struct _agp_bind {
388 int32_t agpb_key; /* IN: ID of memory to be bound */
389 uint32_t agpb_pgstart; /* IN: offset in aperture */
390 } agp_bind_t;
391 agpb_key The unique ID of the mem‐
394 ory to be bound, which is
395 previously allocated by
396 calling AGPIOC_ALLOCATE.
397 agpb_pgstart The starting page offset
400 to be bound in aperture
401 space.
402 Return Values:
404 EPERM Not owner of GART.
406 EFAULT Argument copy in error.
409 EINVAL Argument not valid.
412 EIO Binding to the GTT table
415 of IGD devices failed.
416 0 Success.
419 AGPIOC_UNBIND Unbind memory identified by a key from the
423 GART. This command clears the corresponding
424 entries in the GART table. Only the memory not
425 in mapping to userland is allowed to be
426 unbound.
427 This ioctl command can be called from user or
429 kernel context.
430 The argument is a pointer to agp_unbind_t structure.
432 typedef struct _agp_unbind {
434 int32_t agpu_key; /* IN: key of memory to be unbound*/
435 uint32_t agpu_pri; /* Not used: for compat. with Xorg */
436 } agp_unbind_t;
437 agpu_key Unique ID of the memory to
440 be unbound which was pre‐
441 viously bound by calling
442 AGPIOC_BIND.
443 agpu_pri Reserved for compatibility
446 with X.org/XFree86, not
447 used.
448 Return Values:
450 EPERM Not owner of GART.
452 EFAULT Argument copy in error.
455 EINVAL Argument not valid or mem‐
458 ory in use.
459 EIO Unbinding from the GTT ta‐
462 ble of IGD devices failed.
463 0 Success
466
471 Below is an sample program showing how agpgart ioctls can be used:
472 #include <stdio.h>
474 #include <stdlib.h>
475 #include <unistd.h
476 #include <sys/ioccom.h>
477 #include <sys/types.h>
478 #include <fcntl.h>
479 #include <errno.h>
480 #include <sys/mman.h>
481 #include <sys/agpgart.h>
482 #define AGP_PAGE_SIZE 4096
484 int main(int argc, char *argv[])
486 {
487 int fd, ret;
488 agp_allocate_t alloc;
489 agp_bind_t bindinfo;
490 agp_info_t agpinfo;
491 agp_setup_t modesetup;
492 int *p = NULL;
493 off_t mapoff;
494 size_t maplen;
495 if((fd = open(AGP_DEVICE, O_RDWR))== -1) {
497 printf("open AGP_DEVICE error with %d\n", errno);\
498 exit(-1);
499 }
500 printf("device opened\n");
501 ret = ioctl(fd, AGPIOC_INFO, &agpinfo);
503 if(ret == -1) {
504 printf("Get info error %d0, errno);
505 exit(-1);
506 }
507 printf("AGPSTAT is %x\n", agpinfo.agpi_mode);
508 printf("APBASE is %x\n", agpinfo.agpi_aperbase);
509 printf("APSIZE is %dMB\n", agpinfo.agpi_apersize);
510 printf("pg_total is %d\n", agpinfo.agpi_pgtotal);
511 ret = ioctl(fd, AGPIOC_ACQUIRE);
513 if(ret == -1) {
514 printf(" Acquire GART error %d\n", errno);
515 exit(-1);
516 }
517 modesetup.agps_mode = agpinfo.agpi_mode;
519 ret = ioctl(fd, AGPIOC_SETUP, &modesetup);
520 if(ret == -1) {
521 printf("set up AGP mode error\n", errno);
522 exit(-1);
523 }
524 printf("Please input the number of pages you want to allocate\n");
526 scanf("%d", &alloc.agpa_pgcount);
527 alloc.agpa_type = AGP_NORMAL;
528 ret = ioctl(fd, AGPIOC_ALLOCATE, &alloc);
529 if(ret == -1) {
530 printf("Allocate memory error %d\n", errno);
531 exit(-1);
532 }
533 printf("Please input the aperture page offset to bind\n");
535 scanf("%d", &bindinfo.agpb_pgstart);
536 bindinfo.agpb_key = alloc.agpa_key;
537 ret = ioctl(fd, AGPIOC_BIND, &bindinfo);
538 if(ret == -1) {
539 printf("Bind error %d\n", errno);
540 exit(-1);
541 }
542 printf("Bind successful\n");
543 /*
545 * Now gart aperture space from (bindinfo.agpb_pgstart) to
546 * (bindinfo.agpb_pgstart + alloc.agpa_pgcount) can be used for
547 * AGP graphics transactions
548 */
549 ...
550 /*
552 * mmap can allow user processes to store graphics data
553 * to the aperture space
554 */
555 maplen = alloc.agpa_pgcount * AGP_PAGE_SIZE;
556 mapoff = bindinfo.agpb_pgstart * AGP_PAGE_SIZE;
557 p = (int *)mmap((caddr_t)0, maplen, (PROT_READ | PROT_WRITE),
558 MAP_SHARED, fd, mapoff);
559 if (p == MAP_FAILED) {
560 printf("Mmap error %d\n", errno);
561 exit(-1);
562 }
563 printf("Mmap successful\n");
564 ...
565 /*
567 * When user processes finish access to the aperture space,
568 * unmap the memory range
569 */
570 munmap((void *)p, maplen);
571 ...
572 /*
574 * After finishing AGP transactions, the resources can be freed
575 * step by step or simply by close device.
576 */
577 ret = ioctl(fd, AGPIOC_DEALLOCATE, alloc.agpa_key);
578 if(ret == -1) {
579 printf(" Deallocate memory error %d\n", errno);
580 exit(-1);
581 }
582 ret = ioctl(fd, AGPIOC_RELEASE);
584 if(ret == -1) {
585 printf(" Release GART error %d\n", errno);
586 exit(-1);
587 }
588 close(fd);
590 }
591
594 /dev/agpgart
595 Symbolic link to the pseudo agpgart device.
597 /platform/i86pc/kernel/drv/agpgart
600 agpgart pseudo driver.
602 /platform/i86pc/kernel/drv/agpgart.conf
605 Driver configuration file.
607
610 See attributes(5) for descriptions of the following attributes:
611 ┌────────────────────┬──────────────────────────────────────┐
616 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
617 ├────────────────────┼──────────────────────────────────────┤
618 │Architecture │X86 │
619 ├────────────────────┼──────────────────────────────────────┤
620 │Availability │SUNWagp, SUNWagph │
621 ├────────────────────┼──────────────────────────────────────┤
622 │Stability level │Unstable │
623 └────────────────────┴──────────────────────────────────────┘
624
626 prctl(1), kstat(1M), close(2), ioctl(2), open(2), mmap(2), project(4),
627 privileges(5), attributes(5), resource_controls(5)
628SunOS 5.11 25 Sep 2008 agpgart_io(7I)