Manual browser: x86_64_get_mtrr(2)

Section:
Page:
X86_64_GET_MTRR(2) System Calls Manual (x86_64) X86_64_GET_MTRR(2)

NAME

x86_64_get_mtrr, x86_64_set_mtrraccess Memory Type Range Registers

LIBRARY

x86_64 Architecture Library (libx86_64, -lx86_64)

SYNOPSIS

#include <sys/types.h>
#include <machine/sysarch.h>
#include <machine/mtrr.h>

int
x86_64_get_mtrr(struct mtrr *mtrrp, int *n);

int
x86_64_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 x86_64_set_mtrr() the integer pointed to by n will be updated to reflect the actual number of MTRRs successfully set. For x86_64_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 x86_64_get_mtrr() and x86_64_set_mtrr() were derived from their i386 counterparts, which appeared in NetBSD 1.6.
November 10, 2001 NetBSD 7.0