lib/libarch/x86_64/x86_64_get_mtrr.2

   1 .\"     $NetBSD: x86_64_get_mtrr.2,v 1.7 2004/03/13 23:46:37 wiz 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 November 10, 2001
  31 .Dt X86_64_GET_MTRR 2 x86_64
  32 .Os
  33 .Sh NAME
  34 .Nm x86_64_get_mtrr ,
  35 .Nm x86_64_set_mtrr
  36 .Nd access Memory Type Range Registers
  37 .Sh LIBRARY
  38 .Lb libx86_64
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In machine/sysarch.h
  42 .In machine/mtrr.h
  43 .Ft int
  44 .Fn x86_64_get_mtrr "struct mtrr *mtrrp" "int *n"
  45 .Ft int
  46 .Fn x86_64_set_mtrr "struct mtrr *mtrrp" "int *n"
  47 .Sh DESCRIPTION
  48 These functions provide an interface to the MTRR registers found on
  49 686-class processors for controlling processor access to memory ranges.
  50 This is most useful for accessing devices such as video accelerators on
  51 .Xr pci 4
  52 and
  53 .Xr agp 4
  54 buses.
  55 For example, enabling write-combining allows bus-write transfers
  56 to be combined into a larger transfer before bursting over the bus.
  57 This can increase performance of write operations 2.5 times or more.
  58 .Pp
  59 .Fa mtrrp
  60 is a pointer to one or more mtrr structures, as described below.
  61 The
  62 .Fa n
  63 argument is a pointer to an integer containing the number of structures
  64 pointed to by
  65 .Fa mtrrp .
  66 For
  67 .Fn x86_64_set_mtrr
  68 the integer pointed to by
  69 .Fa n
  70 will be updated to reflect the actual number of MTRRs successfully set.
  71 For
  72 .Fn x86_64_get_mtrr
  73 no more than
  74 .Fa n
  75 structures will be copied out, and the integer value pointed to by
  76 .Fa n
  77 will be updated to reflect the actual number of valid structures retrieved.
  78 A
  79 .Dv NULL
  80 argument to
  81 .Fa mtrrp
  82 will result in just the number of MTRRs available being returned
  83 in the integer pointed to by
  84 .Fa n .
  85 .Pp
  86 The argument
  87 .Fa mtrrp
  88 has the following structure:
  89 .Bd -literal
  90 struct mtrr {
  91         uint64_t base;
  92         uint64_t len;
  93         uint8_t type;
  94         int flags;
  95         pid_t owner;
  96 };
  97 .Ed
  98 .Pp
  99 The location of the mapping is described by its physical base address
 100 .Em base
 101 and length
 102 .Em len .
 103 Valid values for
 104 .Em type
 105 are:
 106 .Pp
 107 .Bl -tag -offset indent -width MTRR_TYPE_UNDEF1 -compact
 108 .It MTRR_TYPE_UC
 109 uncached memory
 110 .It MTRR_TYPE_WC
 111 use write-combining
 112 .It MTRR_TYPE_WT
 113 use write-through caching
 114 .It MTRR_TYPE_WP
 115 write-protected memory
 116 .It MTRR_TYPE_WB
 117 use write-back caching
 118 .El
 119 .Pp
 120 Valid values for
 121 .Em flags
 122 are:
 123 .Pp
 124 .Bl -tag -offset indent -width MTRR_PRIVATE -compact
 125 .It MTRR_PRIVATE
 126 own range, reset the MTRR when the current process exits
 127 .It MTRR_FIXED
 128 use fixed range MTRR
 129 .It MTRR_VALID
 130 entry is valid
 131 .El
 132 .Pp
 133 The
 134 .Em owner
 135 member is the PID of the user process which claims the mapping.
 136 It is only valid if MTRR_PRIVATE is set in
 137 .Em flags .
 138 To clear/reset MTRRs, use a
 139 .Em flags
 140 field without MTRR_VALID set.
 141 .Sh RETURN VALUES
 142 Upon successful completion zero is returned, otherwise \-1 is returned
 143 on failure, and the global variable
 144 .Va errno
 145 is set to indicate the error.
 146 The integer value pointed to by
 147 .Fa n
 148 will contain the number of successfully processed mtrr structures
 149 in both cases.
 150 .Sh ERRORS
 151 .Bl -tag -width [EINVAL]
 152 .It Bq Er ENOSYS
 153 The currently running kernel or CPU has no MTRR support.
 154 .It Bq Er EINVAL
 155 The currently running kernel has no MTRR support, or one of the mtrr
 156 structures pointed to by
 157 .Fa mtrrp
 158 is invalid.
 159 .It Bq Er EBUSY
 160 No unused MTRRs are available.
 161 .El
 162 .Sh HISTORY
 163 The
 164 .Fn x86_64_get_mtrr
 165 and
 166 .Fn x86_64_set_mtrr
 167 were derived from their i386 counterparts, which appeared in
 168 .Nx 1.6 .