[PATCH v5 04/46] x86: mtrr: Add documentation
Simon Glass
sjg at chromium.org
Sun Jul 16 05:38:37 CEST 2023
Add documention for the x86 'mtrr' command.
Signed-off-by: Simon Glass <sjg at chromium.org>
Reviewed-by: Bin Meng <bmeng.cn at gmail.com>
Suggested-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
---
Changes in v5:
- Fix 'abrievated' typo
- Drop extra space in penultimate example
Changes in v2:
- Add new patch with docs for mtrr command
doc/usage/cmd/mtrr.rst | 151 +++++++++++++++++++++++++++++++++++++++++
doc/usage/index.rst | 1 +
2 files changed, 152 insertions(+)
create mode 100644 doc/usage/cmd/mtrr.rst
diff --git a/doc/usage/cmd/mtrr.rst b/doc/usage/cmd/mtrr.rst
new file mode 100644
index 000000000000..531153bb3e23
--- /dev/null
+++ b/doc/usage/cmd/mtrr.rst
@@ -0,0 +1,151 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+mtrr command
+============
+
+Synopis
+-------
+
+ mtrr [list]
+ mtrr set <reg> <type> <start> <size>
+ mtrr disable <reg>
+ mtrr enable
+
+
+Description
+-----------
+
+The *mtrr* command is used to dump the Memory Type Range Registers (MTRRs) on
+an x86 machine. These register control cache behaviour in selected memory
+ranges.
+
+Note that the number of registers can vary between CPUs.
+
+
+mtrr [list]
+~~~~~~~~~~~
+
+List the MTRRs. The table shows the following information:
+
+Reg
+ Register number (the first is register 0)
+
+Valid
+ Shows Y if the register is valid (has bit 11 set), N if not
+
+Write-type
+ Shows the behaviour when writing to the memory region. The types are
+ abbreviated to fit a reasonable line length. Valid types shown below.
+
+ ====== ============== ====================================================
+ Value Type Meaning
+ ====== ============== ====================================================
+ 0 Uncacheable Skip cache and write directly to memory
+ 1 Combine Multiple writes can be combined into one transaction
+ 4 Through Update cache and also write to memory
+ 5 Protect Writes are prohibited
+ 6 Back Update cache but don't write to memory
+ ====== ============== ====================================================
+
+Base
+ Base memory address from which the register controls behaviour
+
+Mask
+ Mask value, which also indicates the size
+
+Size
+ Length of memory region within which the register controls behaviour
+
+
+mtrr set
+~~~~~~~~
+
+This sets the value of a particular MTRR. Parameters are:
+
+reg
+ Register number to set, with 0 being the first
+
+type
+ Access type to set. See Write-type above for valid types. This uses the name
+ rather than its numeric value.
+
+start
+ Base memory address from which the register should control behaviour
+
+size
+ Length of memory region within which the register controls behaviour
+
+
+mtrr disable
+~~~~~~~~~~~~
+
+This disables a particular register, by clearing its `valid` bit (11).
+
+
+mtrr enable
+~~~~~~~~~~~
+
+This enables a particular register, by setting its `valid` bit (11).
+
+
+Example
+-------
+
+This shows disabling and enabling an MTRR, as well as setting its type::
+
+ => mtrr
+ CPU 0:
+ Reg Valid Write-type Base || Mask || Size ||
+ 0 Y Back 0000000000000000 0000000f80000000 0000000080000000
+ 1 Y Back 0000000080000000 0000000fe0000000 0000000020000000
+ 2 Y Back 00000000a0000000 0000000ff0000000 0000000010000000
+ 3 Y Uncacheable 00000000ad000000 0000000fff000000 0000000001000000
+ 4 Y Uncacheable 00000000ae000000 0000000ffe000000 0000000002000000
+ 5 Y Combine 00000000d0000000 0000000ff0000000 0000000010000000
+ 6 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 7 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 8 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 9 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ => mtrr d 5
+ => mtrr
+ CPU 0:
+ Reg Valid Write-type Base || Mask || Size ||
+ 0 Y Back 0000000000000000 0000000f80000000 0000000080000000
+ 1 Y Back 0000000080000000 0000000fe0000000 0000000020000000
+ 2 Y Back 00000000a0000000 0000000ff0000000 0000000010000000
+ 3 Y Uncacheable 00000000ad000000 0000000fff000000 0000000001000000
+ 4 Y Uncacheable 00000000ae000000 0000000ffe000000 0000000002000000
+ 5 N Combine 00000000d0000000 0000000ff0000000 0000000010000000
+ 6 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 7 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 8 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 9 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ => mtrr e 5
+ => mtrr
+ CPU 0:
+ Reg Valid Write-type Base || Mask || Size ||
+ 0 Y Back 0000000000000000 0000000f80000000 0000000080000000
+ 1 Y Back 0000000080000000 0000000fe0000000 0000000020000000
+ 2 Y Back 00000000a0000000 0000000ff0000000 0000000010000000
+ 3 Y Uncacheable 00000000ad000000 0000000fff000000 0000000001000000
+ 4 Y Uncacheable 00000000ae000000 0000000ffe000000 0000000002000000
+ 5 Y Combine 00000000d0000000 0000000ff0000000 0000000010000000
+ 6 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 7 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 8 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 9 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ => mtrr set 5 Uncacheable d0000000 10000000
+ => mtrr
+ CPU 0:
+ Reg Valid Write-type Base || Mask || Size ||
+ 0 Y Back 0000000000000000 0000000f80000000 0000000080000000
+ 1 Y Back 0000000080000000 0000000fe0000000 0000000020000000
+ 2 Y Back 00000000a0000000 0000000ff0000000 0000000010000000
+ 3 Y Uncacheable 00000000ad000000 0000000fff000000 0000000001000000
+ 4 Y Uncacheable 00000000ae000000 0000000ffe000000 0000000002000000
+ 5 Y Uncacheable 00000000d0000000 0000000ff0000000 0000000010000000
+ 6 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 7 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 8 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ 9 N Uncacheable 0000000000000000 0000000000000000 0000001000000000
+ =>
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index f2ffd2787aa8..072db53614c5 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -76,6 +76,7 @@ Shell commands
cmd/md
cmd/mmc
cmd/mtest
+ cmd/mtrr
cmd/panic
cmd/part
cmd/pause
--
2.41.0.455.g037347b96a-goog
More information about the U-Boot
mailing list