share/man/man4/agp.4

   1 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to The NetBSD Foundation
   5 .\" by Gregory McGarry.
   6 .\"
   7 .\" Copyright (c) 2001 Yar Tikhiy
   8 .\" All rights reserved.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"        This product includes software developed by the NetBSD
  21 .\"        Foundation, Inc. and its contributors.
  22 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  23 .\"    contributors may be used to endorse or promote products derived
  24 .\"    from this software without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  29 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  36 .\" POSSIBILITY OF SUCH DAMAGE.
  37 .\"
  38 .\" $NetBSD: agp.4,v 1.10 2003/05/14 07:59:00 wiz Exp $
  39 .\" $DragonFly: src/share/man/man4/agp.4,v 1.5 2007/09/12 09:26:32 hasso Exp $
  40 .\"
  41 .Dd September 12, 2007
  42 .Dt AGP 4
  43 .Os
  44 .Sh NAME
  45 .Nm agp
  46 .Nd accelerated graphics port driver
  47 .Sh SYNOPSIS
  48 To compile this driver into the kernel,
  49 place the following lines in your
  50 kernel configuration file:
  51 .Bd -ragged -offset indent
  52 .Cd "device agp"
  53 .Ed
  54 .Pp
  55 Alternatively, to load the driver as a
  56 module at boot time, place the following line in
  57 .Xr loader.conf 5 :
  58 .Bd -literal -offset indent
  59 agp_load="YES"
  60 .Ed
  61 .Sh DESCRIPTION
  62 The
  63 .Nm
  64 driver provides machine-independent support for the accelerated
  65 graphics port (AGP) found on many PC-based and PCI systems.  The AGP
  66 specification was designed by Intel.
  67 .Pp
  68 The AGP chipset is positioned between the PCI-Host bridge and the
  69 graphics accelerator to provide a high-performance dedicated graphics
  70 bus for moving large amounts of data directly from host memory to the
  71 graphics accelerator.  The specification currently supports a peak
  72 bandwidth of 528 MB/s.  AGP uses a Graphics Address Remapping Table
  73 (GART) to provide a physically-contiguous view of scattered pages in
  74 host memory for DMA transfers.
  75 .Pp
  76 The
  77 .Nm
  78 driver supports the following chipsets:
  79 .Pp
  80 .Bl -dash -compact -offset indent
  81 .It
  82 ALI M1541, M1621 and M1671 host to AGP bridges
  83 .It
  84 AMD 751, 761 and 762 host to AGP bridges
  85 .It
  86 AMD 8151 AGP graphics tunnel
  87 .It
  88 ATI RS100, RS200, RS250 and RS300 AGP bridges
  89 .It
  90 Intel i810, i815, i830, 845, 852, 855, 865, 915, 945, 946 and 965
  91 series SVGA controllers
  92 .It
  93 Intel 82443LX, 82443BX, 82443GX, i820, i840, i845, i845G, i850, i855,
  94 i855GM, i860, i865, i875P, E7205 and E7505 host to AGP bridges
  95 .It
  96 Nvidia nForce, nForce2 and nForce3 AGP controllers
  97 .It
  98 SiS 530, 540, 550, 620, 630, 645, 645DX, 648, 650, 651, 655, 661, 730,
  99 735, 740, 741, 745, 746, 755, 760 and 5591 host to AGP bridges
 100 .It
 101 ULi M1689 AGP controller
 102 .It
 103 VIa 3238, 3296, 82C597, 82C598, 82C691, 82C694X, 82C8363, 8235, 8237,
 104 8361, 8367, 8371, 8377, 8380, 8385, 8501, 8601, 862x, 8633, 8653, 8703,
 105 8753, 8754, 8763, 8783, KT880, K8T800Pro, PM800, PM880, PN800, PN880,
 106 PT880, XM266 and XN266 host to PCI bridges
 107 .El
 108 .Pp
 109 The
 110 .Nm
 111 driver also provides an interface to user processes for use by X
 112 servers.  A user process communicates to the device initially by means
 113 of
 114 .Xr ioctl 2
 115 calls performed on
 116 .Pa /dev/agpgart .
 117 All calls and related structures are defined in
 118 .In sys/agpio.h .
 119 The calls supported are:
 120 .Bl -tag -width indent
 121 .It Dv AGPIOC_INFO
 122 Returns state of the
 123 .Nm
 124 system.
 125 The result is a pointer to the following structure:
 126 .Bd -literal
 127 typedef struct _agp_info {
 128         agp_version version;    /* version of the driver       */
 129         uint32_t bridge_id;     /* bridge vendor/device        */
 130         uint32_t agp_mode;      /* mode info of bridge         */
 131         off_t aper_base;        /* base of aperture            */
 132         size_t aper_size;       /* size of aperture            */
 133         size_t pg_total;        /* max pages (swap + system)   */
 134         size_t pg_system;       /* max pages (system)          */
 135         size_t pg_used;         /* current pages used          */
 136 } agp_info;
 137 .Ed
 138 .It Dv AGPIOC_ACQUIRE
 139 Acquire control of the AGP chipset for use by this client.
 140 Returns
 141 .Er EBUSY
 142 if the AGP chipset is already acquired by another client.
 143 .It Dv AGPIOC_RELEASE
 144 Release control of the AGP chipset.
 145 This does not unbind or free any allocated memory, which is the
 146 responsibility of the client to handle if necessary.
 147 .It Dv AGPIOC_SETUP
 148 Enable the AGP hardware with the relevant mode.
 149 This
 150 .Xr ioctl 2
 151 takes the following structure:
 152 .Bd -literal
 153 typedef struct _agp_setup {
 154         uint32_t agp_mode;     /* mode info of bridge          */
 155 } agp_setup;
 156 .Ed
 157 .Pp
 158 The mode bits are defined in
 159 .In sys/agpio.h .
 160 .It Dv AGPIOC_ALLOCATE
 161 Allocate physical memory suitable for mapping into the AGP aperture.
 162 This
 163 .Xr ioctl 2
 164 takes the following structure:
 165 .Bd -literal
 166 typedef struct _agp_allocate {
 167         int key;               /* tag of allocation            */
 168         size_t pg_count;       /* number of pages              */
 169         uint32_t type;         /* 0 == normal, other devspec   */
 170         paddr_t physical;      /* device specific (some devices
 171                                 * need a phys address of the
 172                                 * actual page behind the gatt
 173                                 * table)                       */
 174 } agp_allocate;
 175 .Ed
 176 .Pp
 177 Returns a handle to the allocated memory.
 178 .It Dv AGPIOC_DEALLOCATE
 179 Free the previously allocated memory associated with the handle passed.
 180 .It Dv AGPIOC_BIND
 181 Bind the allocated memory at given offset with the AGP aperture.
 182 Returns
 183 .Er EINVAL
 184 if the memory is already bound or the offset is not at AGP page boundary.
 185 This
 186 .Xr ioctl 2
 187 takes the following structure:
 188 .Bd -literal
 189 typedef struct _agp_bind {
 190         int key;               /* tag of allocation            */
 191         off_t pg_start;        /* starting page to populate    */
 192 } agp_bind;
 193 .Ed
 194 .Pp
 195 The tag of allocation is the handle returned by
 196 .Dv AGPIOC_ALLOCATE .
 197 .It Dv AGPIOC_UNBIND
 198 Unbind memory from the AGP aperture.
 199 Returns
 200 .Er EINVAL
 201 if the memory is not bound.
 202 This
 203 .Xr ioctl 2
 204 takes the following structure:
 205 .Bd -literal
 206 typedef struct _agp_unbind {
 207         int key;               /* tag of allocation            */
 208         uint32_t priority;     /* priority for paging out      */
 209 } agp_unbind;
 210 .Ed
 211 .El
 212 .Sh FILES
 213 .Bl -tag -width ".Pa /dev/agpgart" -compact
 214 .It Pa /dev/agpgart
 215 AGP GART device special file
 216 .El
 217 .Sh EXAMPLES
 218 This short code fragment is an example of opening the AGP device
 219 and performing some basic operations:
 220 .Bd -literal
 221 #include \*[Lt]stdio.h\*[Gt]
 222 #include \*[Lt]sys/types.h\*[Gt]
 223 #include \*[Lt]sys/ioctl.h\*[Gt]
 224 #include \*[Lt]sys/agpio.h\*[Gt]
 225 #include \*[Lt]fcntl.h\*[Gt]
 226 #include \*[Lt]err.h\*[Gt]
 227
 228 int
 229 main(int argc, char **argv)
 230 {
 231         int fd;
 232         agp_info info;
 233         agp_allocate alloc;
 234         agp_setup setup;
 235         agp_bind bind;
 236         agp_unbind unbind;
 237
 238         fd = open("/dev/agpgart", O_RDWR);
 239         if (fd \*[Lt] 0)
 240                 err(1, "open");
 241
 242         if (ioctl(fd, AGPIOC_INFO, \*[Am]info) \*[Lt] 0)
 243                 err(2, "ioctl AGPIOC_INFO");
 244
 245         printf("version:        %u.%u\\n", info.version.major,
 246             info.version.minor);
 247
 248         printf("id:             %x\\n", info.bridge_id);
 249         printf("mode:           %x\\n", info.agp_mode);
 250         printf("base:           %x\\n", info.aper_base);
 251         printf("size:           %uM\\n", info.aper_size);
 252         printf("total mem:      %u\\n", info.pg_total);
 253         printf("system mem:     %u\\n", info.pg_system);
 254         printf("used mem:       %u\\n\\n", info.pg_used);
 255
 256         setup.agp_mode = info.agp_mode;
 257
 258         if (ioctl(fd, AGPIOC_SETUP, \*[Am]setup) \*[Lt] 0)
 259                 err(3, "ioctl AGPIOC_SETUP");
 260
 261         if (ioctl(fd, AGPIOC_ACQUIRE, 0) \*[Lt] 0)
 262                 err(3, "ioctl AGPIOC_ACQUIRE");
 263
 264         alloc.type = 0;
 265         alloc.pg_count = 64;
 266
 267         if (ioctl(fd, AGPIOC_ALLOCATE, \*[Am]alloc) \*[Lt] 0)
 268                 err(4, "ioctl AGPIOC_ALLOCATE");
 269
 270         printf("alloc key %d, paddr %x\\n", alloc.key, alloc.physical);
 271         if (ioctl(fd, AGPIOC_INFO, \*[Am]info) \*[Lt] 0)
 272                 err(5, "ioctl AGPIOC_INFO");
 273
 274         bind.key = alloc.key;
 275         bind.pg_start = 0x1000;
 276
 277         if (ioctl(fd, AGPIOC_BIND, \*[Am]bind) \*[Lt] 0)
 278                 err(6, "ioctl AGPIOC_BIND");
 279
 280         printf("used mem now:   %u\\n\\n", info.pg_used);
 281
 282         unbind.key = alloc.key;
 283         unbind.priority = 0;
 284
 285         if (ioctl(fd, AGPIOC_UNBIND, \*[Am]unbind) \*[Lt] 0)
 286                 err(6, "ioctl AGPIOC_BIND");
 287
 288         if (ioctl(fd, AGPIOC_DEALLOCATE, \*[Am]alloc.key) \*[Lt] 0)
 289                 err(6, "ioctl AGPIOC_DEALLOCATE");
 290
 291         if (ioctl(fd, AGPIOC_RELEASE, 0) \*[Lt] 0)
 292                 err(7, "ioctl AGPIOC_RELEASE");
 293
 294         close(fd);
 295
 296         printf("agp test successful\\n");
 297
 298         return 0;
 299 }
 300 .Ed
 301 .Sh SEE ALSO
 302 .Xr ioctl 2
 303 .Sh HISTORY
 304 The
 305 .Nm
 306 driver first appeared in
 307 .Fx 4.1 .