MTRR(4) | Device Drivers Manual (amd64) | MTRR(4)

# NAME

`mtrr` — driver for CPU memory range attributes

# SYNOPSIS

`pseudo-device mtrr 1`

# DESCRIPTION

The `mtrr` device provides access to the memory range attributes supported by the MTRRs on AMD64 compatible CPUs.

## IOCTL INTERFACE

Several architectures allow attributes to be associated with ranges of physical memory. These attributes can be manipulated via `ioctl`() calls performed on /dev/mem or /dev/xf86. Declarations and data types are to be found in `<sys/memrange.h>`.

The specific attributes, and number of programmable ranges may vary between architectures. The full set of supported attributes is:

`MDF_UNCACHEABLE`
  The region is not cached.
`MDF_WRITECOMBINE`
  Writes to the region may be combined or performed out of order.
`MDF_WRITETHROUGH`
  Writes to the region are committed synchronously.
`MDF_WRITEBACK`
  Writes to the region are committed asynchronously.
`MDF_WRITEPROTECT`
  The region cannot be written to.

Memory ranges are described by

    struct mem_range_desc {
    	u_int64_t	mr_base;	/∗ physical base address ∗/
    	u_int64_t	mr_len;		/∗ physical length of region ∗/
    	int		mr_flags;	/∗ attributes of region ∗/
    	char		mr_owner[8];
    };

In addition to the region attributes listed above, the following flags may also be set in the mr_flags field:

`MDF_FIXBASE`
  The region's base address cannot be changed.
`MDF_FIXLEN`
  The region's length cannot be changed.
`MDF_FIRMWARE`
  The region is believed to have been established by the system firmware.
`MDF_ACTIVE`
  The region is currently active.
`MDF_BOGUS`
  We believe the region to be invalid or otherwise erroneous.
`MDF_FIXACTIVE`
  The region cannot be disabled.

Operations are performed using

    struct mem_range_op {
    	struct mem_range_desc	*mo_desc;
    	int			mo_arg[2];
    };

The MEMRANGE_GET ioctl is used to retrieve current memory range attributes. If mo_arg[0] is set to 0, it will be updated with the total number of memory range descriptors. If greater than 0, the array at mo_desc will be filled with a corresponding number of descriptor structures, or the maximum, whichever is less.

The MEMRANGE_SET ioctl is used to add, alter and remove memory range attributes. A range with the `MDF_FIXACTIVE` flag may not be removed.

mo_arg[0] should be set to MEMRANGE_SET_UPDATE to update an existing or establish a new range, or to MEMRANGE_SET_REMOVE to remove a range.

# ERRORS

On ioctl(2) failure, errno(2) will be set as follows:

[`EOPNOTSUPP`]
  Memory range operations are not supported on this architecture.
[`ENXIO`]
  No memory range descriptors are available (e.g., firmware has not enabled any).
[`EINVAL`]
  The memory range supplied as an argument is invalid or overlaps another range in a fashion not supported by this architecture.
[`EBUSY`]
  An attempt to remove or update a range failed because the range is busy.
[`ENOSPC`]
  An attempt to create a new range failed due to a shortage of hardware resources (e.g., descriptor slots).
[`ENOENT`]
  An attempt to remove a range failed because no range matches the descriptor base/length supplied.
[`EPERM`]
  An attempt to remove a range failed because the range is permanently enabled.

# SEE ALSO

ioctl(2), mem(4), pctr(4), xf86(4), memconfig(8)

# HISTORY

`mtrr` support was originally included in FreeBSD 3.3.

February 15, 2014 | Debian