November 10, 2001 X86_64_GET_MTRR 2 x86_64

### NAME

x86_64_get_mtrr, x86_64_set_mtrr - access Memory Type Range Registers

### LIBRARY

### SYNOPSIS

```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 NetBSD1.6.