blob: dc3e703913ac261ca6d54bc89777266f22d986ab [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001MTRR (Memory Type Range Register) control
Luis R. Rodriguez2f9e8972015-05-26 10:28:12 +02002
3Richard Gooch <rgooch@atnf.csiro.au> - 3 Jun 1999
4Luis R. Rodriguez <mcgrof@do-not-panic.com> - April 9, 2015
5
6===============================================================================
7Phasing out MTRR use
8
Luis R. Rodriguez2baa8912015-08-24 12:13:33 -07009MTRR use is replaced on modern x86 hardware with PAT. Direct MTRR use by
10drivers on Linux is now completely phased out, device drivers should use
11arch_phys_wc_add() in combination with ioremap_wc() to make MTRR effective on
12non-PAT systems while a no-op but equally effective on PAT enabled systems.
13
14Even if Linux does not use MTRRs directly, some x86 platform firmware may still
15set up MTRRs early before booting the OS. They do this as some platform
16firmware may still have implemented access to MTRRs which would be controlled
17and handled by the platform firmware directly. An example of platform use of
18MTRRs is through the use of SMI handlers, one case could be for fan control,
19the platform code would need uncachable access to some of its fan control
20registers. Such platform access does not need any Operating System MTRR code in
21place other than mtrr_type_lookup() to ensure any OS specific mapping requests
22are aligned with platform MTRR setup. If MTRRs are only set up by the platform
23firmware code though and the OS does not make any specific MTRR mapping
24requests mtrr_type_lookup() should always return MTRR_TYPE_INVALID.
Luis R. Rodriguez2f9e8972015-05-26 10:28:12 +020025
26For details refer to Documentation/x86/pat.txt.
27
28===============================================================================
Linus Torvalds1da177e2005-04-16 15:20:36 -070029
30 On Intel P6 family processors (Pentium Pro, Pentium II and later)
31 the Memory Type Range Registers (MTRRs) may be used to control
32 processor access to memory ranges. This is most useful when you have
33 a video (VGA) card on a PCI or AGP bus. Enabling write-combining
34 allows bus write transfers to be combined into a larger transfer
35 before bursting over the PCI/AGP bus. This can increase performance
36 of image write operations 2.5 times or more.
37
38 The Cyrix 6x86, 6x86MX and M II processors have Address Range
39 Registers (ARRs) which provide a similar functionality to MTRRs. For
40 these, the ARRs are used to emulate the MTRRs.
41
42 The AMD K6-2 (stepping 8 and above) and K6-3 processors have two
43 MTRRs. These are supported. The AMD Athlon family provide 8 Intel
44 style MTRRs.
Randy Dunlap7225e752008-07-26 17:54:22 -070045
Linus Torvalds1da177e2005-04-16 15:20:36 -070046 The Centaur C6 (WinChip) has 8 MCRs, allowing write-combining. These
47 are supported.
48
49 The VIA Cyrix III and VIA C3 CPUs offer 8 Intel style MTRRs.
50
51 The CONFIG_MTRR option creates a /proc/mtrr file which may be used
52 to manipulate your MTRRs. Typically the X server should use
53 this. This should have a reasonably generic interface so that
54 similar control registers on other processors can be easily
55 supported.
56
57
58There are two interfaces to /proc/mtrr: one is an ASCII interface
59which allows you to read and write. The other is an ioctl()
60interface. The ASCII interface is meant for administration. The
61ioctl() interface is meant for C programs (i.e. the X server). The
62interfaces are described below, with sample commands and C code.
63
64===============================================================================
65Reading MTRRs from the shell:
66
67% cat /proc/mtrr
68reg00: base=0x00000000 ( 0MB), size= 128MB: write-back, count=1
69reg01: base=0x08000000 ( 128MB), size= 64MB: write-back, count=1
70===============================================================================
71Creating MTRRs from the C-shell:
72# echo "base=0xf8000000 size=0x400000 type=write-combining" >! /proc/mtrr
73or if you use bash:
74# echo "base=0xf8000000 size=0x400000 type=write-combining" >| /proc/mtrr
75
76And the result thereof:
77% cat /proc/mtrr
78reg00: base=0x00000000 ( 0MB), size= 128MB: write-back, count=1
79reg01: base=0x08000000 ( 128MB), size= 64MB: write-back, count=1
80reg02: base=0xf8000000 (3968MB), size= 4MB: write-combining, count=1
81
82This is for video RAM at base address 0xf8000000 and size 4 megabytes. To
83find out your base address, you need to look at the output of your X
84server, which tells you where the linear framebuffer address is. A
85typical line that you may get is:
86
87(--) S3: PCI: 968 rev 0, Linear FB @ 0xf8000000
88
89Note that you should only use the value from the X server, as it may
90move the framebuffer base address, so the only value you can trust is
91that reported by the X server.
92
93To find out the size of your framebuffer (what, you don't actually
94know?), the following line will tell you:
95
96(--) S3: videoram: 4096k
97
98That's 4 megabytes, which is 0x400000 bytes (in hexadecimal).
99A patch is being written for XFree86 which will make this automatic:
100in other words the X server will manipulate /proc/mtrr using the
101ioctl() interface, so users won't have to do anything. If you use a
102commercial X server, lobby your vendor to add support for MTRRs.
103===============================================================================
104Creating overlapping MTRRs:
105
106%echo "base=0xfb000000 size=0x1000000 type=write-combining" >/proc/mtrr
107%echo "base=0xfb000000 size=0x1000 type=uncachable" >/proc/mtrr
108
109And the results: cat /proc/mtrr
110reg00: base=0x00000000 ( 0MB), size= 64MB: write-back, count=1
111reg01: base=0xfb000000 (4016MB), size= 16MB: write-combining, count=1
112reg02: base=0xfb000000 (4016MB), size= 4kB: uncachable, count=1
113
Randy Dunlap7225e752008-07-26 17:54:22 -0700114Some cards (especially Voodoo Graphics boards) need this 4 kB area
Linus Torvalds1da177e2005-04-16 15:20:36 -0700115excluded from the beginning of the region because it is used for
116registers.
117
118NOTE: You can only create type=uncachable region, if the first
119region that you created is type=write-combining.
120===============================================================================
121Removing MTRRs from the C-shell:
122% echo "disable=2" >! /proc/mtrr
123or using bash:
124% echo "disable=2" >| /proc/mtrr
125===============================================================================
126Reading MTRRs from a C program using ioctl()'s:
127
128/* mtrr-show.c
129
130 Source file for mtrr-show (example program to show MTRRs using ioctl()'s)
131
132 Copyright (C) 1997-1998 Richard Gooch
133
134 This program is free software; you can redistribute it and/or modify
135 it under the terms of the GNU General Public License as published by
136 the Free Software Foundation; either version 2 of the License, or
137 (at your option) any later version.
138
139 This program is distributed in the hope that it will be useful,
140 but WITHOUT ANY WARRANTY; without even the implied warranty of
141 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
142 GNU General Public License for more details.
143
144 You should have received a copy of the GNU General Public License
145 along with this program; if not, write to the Free Software
146 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
147
148 Richard Gooch may be reached by email at rgooch@atnf.csiro.au
149 The postal address is:
150 Richard Gooch, c/o ATNF, P. O. Box 76, Epping, N.S.W., 2121, Australia.
151*/
152
153/*
154 This program will use an ioctl() on /proc/mtrr to show the current MTRR
155 settings. This is an alternative to reading /proc/mtrr.
156
157
158 Written by Richard Gooch 17-DEC-1997
159
160 Last updated by Richard Gooch 2-MAY-1998
161
162
163*/
164#include <stdio.h>
Randy Dunlap235963b2006-04-10 22:54:22 -0700165#include <stdlib.h>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700166#include <string.h>
167#include <sys/types.h>
168#include <sys/stat.h>
169#include <fcntl.h>
170#include <sys/ioctl.h>
171#include <errno.h>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700172#include <asm/mtrr.h>
173
174#define TRUE 1
175#define FALSE 0
176#define ERRSTRING strerror (errno)
177
Randy Dunlap235963b2006-04-10 22:54:22 -0700178static char *mtrr_strings[MTRR_NUM_TYPES] =
179{
180 "uncachable", /* 0 */
181 "write-combining", /* 1 */
182 "?", /* 2 */
183 "?", /* 3 */
184 "write-through", /* 4 */
185 "write-protect", /* 5 */
186 "write-back", /* 6 */
187};
Linus Torvalds1da177e2005-04-16 15:20:36 -0700188
189int main ()
190{
191 int fd;
192 struct mtrr_gentry gentry;
193
194 if ( ( fd = open ("/proc/mtrr", O_RDONLY, 0) ) == -1 )
195 {
196 if (errno == ENOENT)
197 {
198 fputs ("/proc/mtrr not found: not supported or you don't have a PPro?\n",
199 stderr);
200 exit (1);
201 }
202 fprintf (stderr, "Error opening /proc/mtrr\t%s\n", ERRSTRING);
203 exit (2);
204 }
205 for (gentry.regnum = 0; ioctl (fd, MTRRIOC_GET_ENTRY, &gentry) == 0;
206 ++gentry.regnum)
207 {
208 if (gentry.size < 1)
209 {
210 fprintf (stderr, "Register: %u disabled\n", gentry.regnum);
211 continue;
212 }
213 fprintf (stderr, "Register: %u base: 0x%lx size: 0x%lx type: %s\n",
214 gentry.regnum, gentry.base, gentry.size,
215 mtrr_strings[gentry.type]);
216 }
217 if (errno == EINVAL) exit (0);
218 fprintf (stderr, "Error doing ioctl(2) on /dev/mtrr\t%s\n", ERRSTRING);
219 exit (3);
220} /* End Function main */
221===============================================================================
222Creating MTRRs from a C programme using ioctl()'s:
223
224/* mtrr-add.c
225
226 Source file for mtrr-add (example programme to add an MTRRs using ioctl())
227
228 Copyright (C) 1997-1998 Richard Gooch
229
230 This program is free software; you can redistribute it and/or modify
231 it under the terms of the GNU General Public License as published by
232 the Free Software Foundation; either version 2 of the License, or
233 (at your option) any later version.
234
235 This program is distributed in the hope that it will be useful,
236 but WITHOUT ANY WARRANTY; without even the implied warranty of
237 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
238 GNU General Public License for more details.
239
240 You should have received a copy of the GNU General Public License
241 along with this program; if not, write to the Free Software
242 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
243
244 Richard Gooch may be reached by email at rgooch@atnf.csiro.au
245 The postal address is:
246 Richard Gooch, c/o ATNF, P. O. Box 76, Epping, N.S.W., 2121, Australia.
247*/
248
249/*
250 This programme will use an ioctl() on /proc/mtrr to add an entry. The first
251 available mtrr is used. This is an alternative to writing /proc/mtrr.
252
253
254 Written by Richard Gooch 17-DEC-1997
255
256 Last updated by Richard Gooch 2-MAY-1998
257
258
259*/
260#include <stdio.h>
261#include <string.h>
262#include <stdlib.h>
263#include <unistd.h>
264#include <sys/types.h>
265#include <sys/stat.h>
266#include <fcntl.h>
267#include <sys/ioctl.h>
268#include <errno.h>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700269#include <asm/mtrr.h>
270
271#define TRUE 1
272#define FALSE 0
273#define ERRSTRING strerror (errno)
274
Randy Dunlap235963b2006-04-10 22:54:22 -0700275static char *mtrr_strings[MTRR_NUM_TYPES] =
276{
277 "uncachable", /* 0 */
278 "write-combining", /* 1 */
279 "?", /* 2 */
280 "?", /* 3 */
281 "write-through", /* 4 */
282 "write-protect", /* 5 */
283 "write-back", /* 6 */
284};
Linus Torvalds1da177e2005-04-16 15:20:36 -0700285
286int main (int argc, char **argv)
287{
288 int fd;
289 struct mtrr_sentry sentry;
290
291 if (argc != 4)
292 {
293 fprintf (stderr, "Usage:\tmtrr-add base size type\n");
294 exit (1);
295 }
296 sentry.base = strtoul (argv[1], NULL, 0);
297 sentry.size = strtoul (argv[2], NULL, 0);
298 for (sentry.type = 0; sentry.type < MTRR_NUM_TYPES; ++sentry.type)
299 {
300 if (strcmp (argv[3], mtrr_strings[sentry.type]) == 0) break;
301 }
302 if (sentry.type >= MTRR_NUM_TYPES)
303 {
304 fprintf (stderr, "Illegal type: \"%s\"\n", argv[3]);
305 exit (2);
306 }
307 if ( ( fd = open ("/proc/mtrr", O_WRONLY, 0) ) == -1 )
308 {
309 if (errno == ENOENT)
310 {
311 fputs ("/proc/mtrr not found: not supported or you don't have a PPro?\n",
312 stderr);
313 exit (3);
314 }
315 fprintf (stderr, "Error opening /proc/mtrr\t%s\n", ERRSTRING);
316 exit (4);
317 }
318 if (ioctl (fd, MTRRIOC_ADD_ENTRY, &sentry) == -1)
319 {
320 fprintf (stderr, "Error doing ioctl(2) on /dev/mtrr\t%s\n", ERRSTRING);
321 exit (5);
322 }
323 fprintf (stderr, "Sleeping for 5 seconds so you can see the new entry\n");
324 sleep (5);
325 close (fd);
326 fputs ("I've just closed /proc/mtrr so now the new entry should be gone\n",
327 stderr);
328} /* End Function main */
329===============================================================================