1.\" $OpenBSD: mtrr.4,v 1.12 2003/07/09 13:26:20 jmc 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 November 15, 1999 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.Aq Pa 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.It Dv MDF_BUSY 80The region is currently owned by another process and may not be 81altered. 82.El 83.Pp 84Operations are performed using 85.Bd -literal -offset xxxx 86struct mem_range_op { 87 struct mem_range_desc *mo_desc; 88 int mo_arg[2]; 89}; 90.Ed 91.Pp 92The 93.Fa MEMRANGE_GET 94ioctl is used to retrieve current memory range attributes. 95If 96.Fa mo_arg[0] 97is set to 0, it will be updated with the total number of memory range 98descriptors. 99If greater than 0, the array at 100.Fa mo_desc 101will be filled with a corresponding number of descriptor structures, 102or the maximum, whichever is less. 103.Pp 104The 105.Fa MEMRANGE_SET 106ioctl is used to add, alter and remove memory range attributes. 107A range with the 108.Dv MDF_FIXACTIVE 109flag may not be removed; a range with the 110.Dv MDF_BUSY 111flag may not be removed or updated. 112.Pp 113.Fa mo_arg[0] 114should be set to MEMRANGE_SET_UPDATE to update an existing 115or establish a new range, or to MEMRANGE_SET_REMOVE to remove a range. 116.Sh RETURN VALUES 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