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