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