NAME
i386_get_mtrr,
i386_set_mtrr —
access Memory Type Range Registers
LIBRARY
i386 Architecture Library (libi386, -li386)
SYNOPSIS
#include <sys/types.h>
#include <machine/sysarch.h>
#include <machine/mtrr.h>
int
i386_get_mtrr(
struct
mtrr *mtrrp,
int *n);
int
i386_set_mtrr(
struct
mtrr *mtrrp,
int *n);
DESCRIPTION
These functions provide an interface to the MTRR registers found on 686-class
processors for controlling processor access to memory ranges. This is most
useful for accessing devices such as video accelerators on
pci(4) and
agp(4) buses. For example, enabling
write-combining allows bus-write transfers to be combined into a larger
transfer before bursting over the bus. This can increase performance of write
operations 2.5 times or more.
mtrrp is a pointer to one or more mtrr structures, as
described below. The
n argument is a pointer to an
integer containing the number of structures pointed to by
mtrrp. For
i386_set_mtrr() the integer
pointed to by
n will be updated to reflect the actual
number of MTRRs successfully set. For
i386_get_mtrr() no
more than
n structures will be copied out, and the
integer value pointed to by
n will be updated to reflect
the actual number of valid structures retrieved. A
NULL
argument to
mtrrp will
result in just the number of MTRRs available being returned in the integer
pointed to by
n.
The argument
mtrrp has the following structure:
struct mtrr {
uint64_t base;
uint64_t len;
uint8_t type;
int flags;
pid_t owner;
};
The location of the mapping is described by its physical base address
base and length
len. Valid values for
type are:
- MTRR_TYPE_UC
- uncached memory
- MTRR_TYPE_WC
- use write-combining
- MTRR_TYPE_WT
- use write-through caching
- MTRR_TYPE_WP
- write-protected memory
- MTRR_TYPE_WB
- use write-back caching
Valid values for
flags are:
- MTRR_PRIVATE
- own range, reset the MTRR when the current process
exits
- MTRR_FIXED
- use fixed range MTRR
- MTRR_VALID
- entry is valid
The
owner member is the PID of the user process which claims
the mapping. It is only valid if MTRR_PRIVATE is set in
flags. To clear/reset MTRRs, use a
flags
field without MTRR_VALID set.
RETURN VALUES
Upon successful completion zero is returned, otherwise -1 is returned on
failure, and the global variable
errno is set to
indicate the error. The integer value pointed to by
n
will contain the number of successfully processed mtrr structures in both
cases.
ERRORS
-
-
- [
ENOSYS
]
- The currently running kernel or CPU has no MTRR
support.
-
-
- [
EINVAL
]
- The currently running kernel has no MTRR support, or one of
the mtrr structures pointed to by mtrrp is
invalid.
-
-
- [
EBUSY
]
- No unused MTRRs are available.
HISTORY
The
i386_get_mtrr() and
i386_set_mtrr()
functions appeared in
NetBSD 1.6.