share/man/man4/agp.4

   1 .\"     $NetBSD: agp.4,v 1.11 2005/12/26 19:48:12 perry Exp $
   2 .\"
   3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Gregory McGarry.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd September 11, 2001
  31 .Dt AGP 4
  32 .Os
  33 .Sh NAME
  34 .Nm agp
  35 .Nd accelerated graphics port driver
  36 .Sh SYNOPSIS
  37 .Cd "agp* at pchb?"
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 driver provides machine-independent support for the accelerated
  42 graphics port (AGP) found on many PC-based and PCI systems.  The AGP
  43 specification was designed by Intel.
  44 .Pp
  45 The AGP chipset is positioned between the PCI-Host bridge and the
  46 graphics accelerator to provide a high-performance dedicated graphics
  47 bus for moving large amounts of data directly from host memory to the
  48 graphics accelerator.  The specification currently supports a peak
  49 bandwidth of 528 MB/s.  AGP uses a Graphics Address Remapping Table
  50 (GART) to provide a physically-contiguous view of scattered pages in
  51 host memory for DMA transfers.
  52 .Pp
  53 The
  54 .Nm
  55 driver supports the following chipsets:
  56 .Pp
  57 .Bl -dash -compact -offset indent
  58 .It
  59 ALI M1541 host-to-AGP bridge
  60 .It
  61 AMD 751 and 761 host-to-AGP bridges
  62 .It
  63 Intel 82810, 82810-DC100, 82810E, and 82815 SVGA controllers
  64 .It
  65 SiS 5591 host-to-AGP bridge
  66 .It
  67 VIA
  68 .El
  69 .Pp
  70 The
  71 .Nm
  72 driver also provides an interface to user processes for use by X
  73 servers.  A user process communicates to the device initially by means
  74 of
  75 .Xr ioctl 2
  76 calls.  The calls supported are:
  77 .Bl -tag -width indent
  78 .It Dv AGPIOC_INFO
  79 Get AGP information, setting the members in the
  80 .Em agp_info
  81 structure as defined in \*[Lt]sys/agpio.h\*[Gt]:
  82 .Bd -literal
  83 typedef struct _agp_info {
  84         agp_version version;    /* version of the driver        */
  85         uint32_t bridge_id;    /* bridge vendor/device         */
  86         uint32_t agp_mode;     /* mode info of bridge          */
  87         off_t aper_base;        /* base of aperture             */
  88         size_t aper_size;       /* size of aperture             */
  89         size_t pg_total;        /* max pages (swap + system)    */
  90         size_t pg_system;       /* max pages (system)           */
  91         size_t pg_used;         /* current pages used           */
  92 } agp_info;
  93 .Ed
  94 .It Dv AGPIOC_ACQUIRE
  95 Acquire AGP.
  96 .It Dv AGPIOC_RELEASE
  97 Release AGP.
  98 .It Dv AGPIOC_SETUP
  99 Set up AGP, using the members in the
 100 .Em agp_setup
 101 structure as defined in \*[Lt]sys/agpio.h\*[Gt]:
 102 .Bd -literal
 103 typedef struct _agp_setup {
 104         uint32_t agp_mode;     /* mode info of bridge          */
 105 } agp_setup;
 106 .Ed
 107 .It Dv AGPIOC_ALLOCATE
 108 Allocate AGP space, using and setting the members in the
 109 .Em agp_allocate
 110 structure as defined in \*[Lt]sys/agpio.h\*[Gt]:
 111 .Bd -literal
 112 typedef struct _agp_allocate {
 113         int key;                /* tag of allocation            */
 114         size_t pg_count;        /* number of pages              */
 115         uint32_t type;         /* 0 == normal, other devspec   */
 116         paddr_t physical;       /* device specific (some devices
 117                                  * need a phys address of the
 118                                  * actual page behind the gatt
 119                                  * table)                       */
 120 } agp_allocate;
 121 .Ed
 122 .It Dv AGPIOC_DEALLOCATE
 123 Deallocate AGP space.
 124 .It Dv AGPIOC_BIND
 125 Bind AGP space, using the members in the
 126 .Em agp_bind
 127 structure as defined in \*[Lt]sys/agpio.h\*[Gt]:
 128 .Bd -literal
 129 typedef struct _agp_bind {
 130         int key;                /* tag of allocation            */
 131         off_t pg_start;         /* starting page to populate    */
 132 } agp_bind;
 133 .Ed
 134 .It Dv AGPIOC_UNBIND
 135 Unbind AGP space, using the members in the
 136 .Em agp_unbind
 137 structure as defined in \*[Lt]sys/agpio.h\*[Gt]:
 138 .Bd -literal
 139 typedef struct _agp_unbind {
 140         int key;                /* tag of allocation            */
 141         uint32_t priority;     /* priority for paging out      */
 142 } agp_unbind;
 143 .Ed
 144 .El
 145 .Sh FILES
 146 .Bl -tag -width /dev/agpgart -compact
 147 .It Pa /dev/agp?
 148 AGP GART device special files
 149 .It Pa /dev/agpgart
 150 AGP GART device special file
 151 .El
 152 .Sh EXAMPLES
 153 This short code fragment is an example of opening the AGP device
 154 and performing some basic operations:
 155 .Bd -literal
 156 #include \*[Lt]sys/types.h\*[Gt]
 157 #include \*[Lt]sys/ioctl.h\*[Gt]
 158 #include \*[Lt]sys/agpio.h\*[Gt]
 159 #include \*[Lt]fcntl.h\*[Gt]
 160 #include \*[Lt]err.h\*[Gt]
 161
 162 int
 163 main(int argc, char **argv)
 164 {
 165         int fd;
 166         agp_info info;
 167         agp_allocate alloc;
 168         agp_setup setup;
 169         agp_bind bind;
 170         agp_unbind unbind;
 171
 172         fd = open("/dev/agp0", O_RDWR);
 173         if (fd \*[Lt] 0)
 174                 err(1, "open");
 175
 176         if (ioctl(fd, AGPIOC_INFO, \*[Am]info) \*[Lt] 0)
 177                 err(2, "ioctl AGPIOC_INFO");
 178
 179         printf("version:        %u.%u\\n", info.version.major,
 180             info.version.minor);
 181
 182         printf("id:             %x\\n", info.bridge_id);
 183         printf("mode:           %x\\n", info.agp_mode);
 184         printf("base:           %x\\n", info.aper_base);
 185         printf("size:           %uM\\n", info.aper_size);
 186         printf("total mem:      %u\\n", info.pg_total);
 187         printf("system mem:     %u\\n", info.pg_system);
 188         printf("used mem:       %u\\n\\n", info.pg_used);
 189
 190         setup.agp_mode = info.agp_mode;
 191
 192         if (ioctl(fd, AGPIOC_SETUP, \*[Am]setup) \*[Lt] 0)
 193                 err(3, "ioctl AGPIOC_SETUP");
 194
 195         if (ioctl(fd, AGPIOC_ACQUIRE, 0) \*[Lt] 0)
 196                 err(3, "ioctl AGPIOC_ACQUIRE");
 197
 198         alloc.type = 0;
 199         alloc.pg_count = 64;
 200
 201         if (ioctl(fd, AGPIOC_ALLOCATE, \*[Am]alloc) \*[Lt] 0)
 202                 err(4, "ioctl AGPIOC_ALLOCATE");
 203
 204         printf("alloc key %d, paddr %x\\n", alloc.key, alloc.physical);
 205         if (ioctl(fd, AGPIOC_INFO, \*[Am]info) \*[Lt] 0)
 206                 err(5, "ioctl AGPIOC_INFO");
 207
 208         bind.key = alloc.key;
 209         bind.pg_start = 0x1000;
 210
 211         if (ioctl(fd, AGPIOC_BIND, \*[Am]bind) \*[Lt] 0)
 212                 err(6, "ioctl AGPIOC_BIND");
 213
 214         printf("used mem now:   %u\\n\\n", info.pg_used);
 215
 216         unbind.key = alloc.key;
 217         unbind.priority = 0;
 218
 219         if (ioctl(fd, AGPIOC_UNBIND, \*[Am]unbind) \*[Lt] 0)
 220                 err(6, "ioctl AGPIOC_BIND");
 221
 222         if (ioctl(fd, AGPIOC_DEALLOCATE, \*[Am]alloc.key) \*[Lt] 0)
 223                 err(6, "ioctl AGPIOC_DEALLOCATE");
 224
 225         if (ioctl(fd, AGPIOC_RELEASE, 0) \*[Lt] 0)
 226                 err(7, "ioctl AGPIOC_RELEASE");
 227
 228         close(fd);
 229
 230         printf("agp test successful\\n");
 231
 232         return 0;
 233 }
 234 .Ed
 235 .Sh SEE ALSO
 236 .Xr ioctl 2 ,
 237 .Xr pci 4
 238 .Sh HISTORY
 239 The
 240 .Nm
 241 driver first appeared in
 242 .Fx 4.1 .
 243 It was adopted in
 244 .Nx 1.6 .