1.\" $OpenBSD: mtrr.4,v 1.8 2014/02/15 23:41:19 schwarze Exp $ 2.\" 3.\" MTRR driver for OpenBSD. 4.\" Copyright 1999 Matthieu Herrb <matthieu@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.Dd $Mdocdate: February 15 2014 $ 11.Dt MTRR 4 amd64 12.Os 13.Sh NAME 14.Nm mtrr 15.Nd driver for CPU memory range attributes 16.Sh SYNOPSIS 17.Cd "pseudo-device mtrr 1" 18.Sh DESCRIPTION 19The 20.Nm 21device provides access to the memory range attributes supported by the 22MTRRs on AMD64 compatible CPUs. 23.Ss IOCTL INTERFACE 24Several architectures allow attributes to be associated with ranges of physical 25memory. 26These attributes can be manipulated via 27.Fn ioctl 28calls performed on 29.Pa /dev/mem 30or 31.Pa /dev/xf86 . 32Declarations and data types are to be found in 33.In sys/memrange.h . 34.Pp 35The specific attributes, and number of programmable ranges may vary between 36architectures. 37The full set of supported attributes is: 38.Bl -tag -width MDF_WRITECOMBINE 39.It Dv MDF_UNCACHEABLE 40The region is not cached. 41.It Dv MDF_WRITECOMBINE 42Writes to the region may be combined or performed out of order. 43.It Dv MDF_WRITETHROUGH 44Writes to the region are committed synchronously. 45.It Dv MDF_WRITEBACK 46Writes to the region are committed asynchronously. 47.It Dv MDF_WRITEPROTECT 48The region cannot be written to. 49.El 50.Pp 51Memory ranges are described by 52.Bd -literal -offset xxxx 53struct mem_range_desc { 54 u_int64_t mr_base; /\(** physical base address \(**/ 55 u_int64_t mr_len; /\(** physical length of region \(**/ 56 int mr_flags; /\(** attributes of region \(**/ 57 char mr_owner[8]; 58}; 59.Ed 60.Pp 61In addition to the region attributes listed above, the following flags 62may also be set in the 63.Fa mr_flags 64field: 65.Bl -tag -width MDF_FIXACTIVE 66.It Dv MDF_FIXBASE 67The region's base address cannot be changed. 68.It Dv MDF_FIXLEN 69The region's length cannot be changed. 70.It Dv MDF_FIRMWARE 71The region is believed to have been established by the system firmware. 72.It Dv MDF_ACTIVE 73The region is currently active. 74.It Dv MDF_BOGUS 75We believe the region to be invalid or otherwise erroneous. 76.It Dv MDF_FIXACTIVE 77The region cannot be disabled. 78.El 79.Pp 80Operations are performed using 81.Bd -literal -offset xxxx 82struct mem_range_op { 83 struct mem_range_desc *mo_desc; 84 int mo_arg[2]; 85}; 86.Ed 87.Pp 88The 89.Fa MEMRANGE_GET 90ioctl is used to retrieve current memory range attributes. 91If 92.Fa mo_arg[0] 93is set to 0, it will be updated with the total number of memory range 94descriptors. 95If greater than 0, the array at 96.Fa mo_desc 97will be filled with a corresponding number of descriptor structures, 98or the maximum, whichever is less. 99.Pp 100The 101.Fa MEMRANGE_SET 102ioctl is used to add, alter and remove memory range attributes. 103A range with the 104.Dv MDF_FIXACTIVE 105flag may not be removed. 106.Pp 107.Fa mo_arg[0] 108should be set to MEMRANGE_SET_UPDATE to update an existing 109or establish a new range, or to MEMRANGE_SET_REMOVE to remove a range. 110.Sh ERRORS 111On 112.Xr ioctl 2 113failure, 114.Xr errno 2 115will be set as follows: 116.Bl -tag -width Er 117.It Bq Er EOPNOTSUPP 118Memory range operations are not supported on this architecture. 119.It Bq Er ENXIO 120No memory range descriptors are available (e.g., firmware has not enabled 121any). 122.It Bq Er EINVAL 123The memory range supplied as an argument is invalid or overlaps another 124range in a fashion not supported by this architecture. 125.It Bq Er EBUSY 126An attempt to remove or update a range failed because the range is busy. 127.It Bq Er ENOSPC 128An attempt to create a new range failed due to a shortage of hardware 129resources (e.g., descriptor slots). 130.It Bq Er ENOENT 131An attempt to remove a range failed because no range matches the descriptor 132base/length supplied. 133.It Bq Er EPERM 134An attempt to remove a range failed because the range is permanently 135enabled. 136.El 137.Sh SEE ALSO 138.Xr ioctl 2 , 139.Xr mem 4 , 140.Xr pctr 4 , 141.Xr xf86 4 , 142.Xr memconfig 8 143.Sh HISTORY 144.Nm 145support was originally included in 146.Fx 3.3 . 147