There are a lot of RAS topic to document, and there are a lot of details
for each topic.
Prep for this by adding an index for the RAS directory. This will
provide a top-level document and table of contents. It also provides the
option to build the RAS directory individually using "make SPHINXDIRS=".
Start a section on address translation. This will be expanded with
details for future translation methods and how they're used in the
kernel.
Move the error decoding topic to its own section. Links to other error
decoding kernel docs will be added.
Signed-off-by: Yazen Ghannam <[email protected]>
---
Link:
https://lore.kernel.org/r/[email protected]
v3->v4:
* Replace "CS" with "COH_ST" in glossary.
v2->v3:
* New in v3.
* Move term glossary to Documentation.
v1->v2:
* N/A
Documentation/RAS/address-translation.rst | 24 +++++++++++++++++++
.../RAS/{ras.rst => error-decoding.rst} | 11 +++------
Documentation/RAS/index.rst | 14 +++++++++++
Documentation/index.rst | 2 +-
MAINTAINERS | 1 +
5 files changed, 43 insertions(+), 9 deletions(-)
create mode 100644 Documentation/RAS/address-translation.rst
rename Documentation/RAS/{ras.rst => error-decoding.rst} (73%)
create mode 100644 Documentation/RAS/index.rst
diff --git a/Documentation/RAS/address-translation.rst b/Documentation/RAS/address-translation.rst
new file mode 100644
index 000000000000..f0ca17b43cd3
--- /dev/null
+++ b/Documentation/RAS/address-translation.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Address translation
+===================
+
+x86 AMD
+-------
+
+Zen-based AMD systems include a Data Fabric that manages the layout of
+physical memory. Devices attached to the Fabric, like memory controllers,
+I/O, etc., may not have a complete view of the system physical memory map.
+These devices may provide a "normalized", i.e. device physical, address
+when reporting memory errors. Normalized addresses must be translated to
+a system physical address for the kernel to action on the memory.
+
+AMD Address Translation Library (CONFIG_AMD_ATL) provides translation for
+this case.
+
+Glossary of acronyms used in address translation for Zen-based systems
+
+* CCM = Cache Coherent Moderator
+* COD = Cluster-on-Die
+* COH_ST = Coherent Station
+* DF = Data Fabric
diff --git a/Documentation/RAS/ras.rst b/Documentation/RAS/error-decoding.rst
similarity index 73%
rename from Documentation/RAS/ras.rst
rename to Documentation/RAS/error-decoding.rst
index 2556b397cd27..26a72f3fe5de 100644
--- a/Documentation/RAS/ras.rst
+++ b/Documentation/RAS/error-decoding.rst
@@ -1,15 +1,10 @@
.. SPDX-License-Identifier: GPL-2.0
-Reliability, Availability and Serviceability features
-=====================================================
-
-This documents different aspects of the RAS functionality present in the
-kernel.
-
Error decoding
----------------
+==============
-* x86
+x86
+---
Error decoding on AMD systems should be done using the rasdaemon tool:
https://github.com/mchehab/rasdaemon/
diff --git a/Documentation/RAS/index.rst b/Documentation/RAS/index.rst
new file mode 100644
index 000000000000..2794c1816e90
--- /dev/null
+++ b/Documentation/RAS/index.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================================================
+Reliability, Availability and Serviceability (RAS) features
+===========================================================
+
+This documents different aspects of the RAS functionality present in the
+kernel.
+
+.. toctree::
+ :maxdepth: 2
+
+ error-decoding
+ address-translation
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 36e61783437c..07f2aa07f0fa 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -113,7 +113,7 @@ to ReStructured Text format, or are simply too old.
:maxdepth: 1
staging/index
- RAS/ras
+ RAS/index
Translations
diff --git a/MAINTAINERS b/MAINTAINERS
index 9db88a691bdf..c566cd9654ef 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -18106,6 +18106,7 @@ M: Tony Luck <[email protected]>
M: Borislav Petkov <[email protected]>
L: [email protected]
S: Maintained
+F: Documentation/RAS/
F: Documentation/admin-guide/ras.rst
F: drivers/ras/
F: include/linux/ras.h
--
2.34.1
The following commit has been merged into the ras/core branch of tip:
Commit-ID: d48d30d8c358004c7b1cb2e16969a569d45953b3
Gitweb: https://git.kernel.org/tip/d48d30d8c358004c7b1cb2e16969a569d45953b3
Author: Yazen Ghannam <[email protected]>
AuthorDate: Mon, 18 Dec 2023 13:04:06 -06:00
Committer: Borislav Petkov (AMD) <[email protected]>
CommitterDate: Wed, 03 Jan 2024 12:29:42 +01:00
Documentation: RAS: Add index and address translation section
There are a lot of RAS topic to document, and there are a lot of details
for each topic.
Prep for this by adding an index for the RAS directory. This will
provide a top-level document and table of contents. It also provides the
option to build the RAS directory individually using "make SPHINXDIRS=".
Start a section on address translation. This will be expanded with
details for future translation methods and how they're used in the
kernel.
Move the error decoding topic to its own section. Links to other error
decoding kernel docs will be added.
Signed-off-by: Yazen Ghannam <[email protected]>
Signed-off-by: Borislav Petkov (AMD) <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
---
Documentation/RAS/address-translation.rst | 24 ++++++++++++++++++++-
Documentation/RAS/error-decoding.rst | 21 ++++++++++++++++++-
Documentation/RAS/index.rst | 14 ++++++++++++-
Documentation/RAS/ras.rst | 26 +----------------------
Documentation/index.rst | 2 +-
MAINTAINERS | 1 +-
6 files changed, 61 insertions(+), 27 deletions(-)
create mode 100644 Documentation/RAS/address-translation.rst
create mode 100644 Documentation/RAS/error-decoding.rst
create mode 100644 Documentation/RAS/index.rst
delete mode 100644 Documentation/RAS/ras.rst
diff --git a/Documentation/RAS/address-translation.rst b/Documentation/RAS/address-translation.rst
new file mode 100644
index 0000000..f0ca17b
--- /dev/null
+++ b/Documentation/RAS/address-translation.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Address translation
+===================
+
+x86 AMD
+-------
+
+Zen-based AMD systems include a Data Fabric that manages the layout of
+physical memory. Devices attached to the Fabric, like memory controllers,
+I/O, etc., may not have a complete view of the system physical memory map.
+These devices may provide a "normalized", i.e. device physical, address
+when reporting memory errors. Normalized addresses must be translated to
+a system physical address for the kernel to action on the memory.
+
+AMD Address Translation Library (CONFIG_AMD_ATL) provides translation for
+this case.
+
+Glossary of acronyms used in address translation for Zen-based systems
+
+* CCM = Cache Coherent Moderator
+* COD = Cluster-on-Die
+* COH_ST = Coherent Station
+* DF = Data Fabric
diff --git a/Documentation/RAS/error-decoding.rst b/Documentation/RAS/error-decoding.rst
new file mode 100644
index 0000000..26a72f3
--- /dev/null
+++ b/Documentation/RAS/error-decoding.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Error decoding
+==============
+
+x86
+---
+
+Error decoding on AMD systems should be done using the rasdaemon tool:
+https://github.com/mchehab/rasdaemon/
+
+While the daemon is running, it would automatically log and decode
+errors. If not, one can still decode such errors by supplying the
+hardware information from the error::
+
+ $ rasdaemon -p --status <STATUS> --ipid <IPID> --smca
+
+Also, the user can pass particular family and model to decode the error
+string::
+
+ $ rasdaemon -p --status <STATUS> --ipid <IPID> --smca --family <CPU Family> --model <CPU Model> --bank <BANK_NUM>
diff --git a/Documentation/RAS/index.rst b/Documentation/RAS/index.rst
new file mode 100644
index 0000000..2794c18
--- /dev/null
+++ b/Documentation/RAS/index.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================================================
+Reliability, Availability and Serviceability (RAS) features
+===========================================================
+
+This documents different aspects of the RAS functionality present in the
+kernel.
+
+.. toctree::
+ :maxdepth: 2
+
+ error-decoding
+ address-translation
diff --git a/Documentation/RAS/ras.rst b/Documentation/RAS/ras.rst
deleted file mode 100644
index 2556b39..0000000
--- a/Documentation/RAS/ras.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-Reliability, Availability and Serviceability features
-=====================================================
-
-This documents different aspects of the RAS functionality present in the
-kernel.
-
-Error decoding
----------------
-
-* x86
-
-Error decoding on AMD systems should be done using the rasdaemon tool:
-https://github.com/mchehab/rasdaemon/
-
-While the daemon is running, it would automatically log and decode
-errors. If not, one can still decode such errors by supplying the
-hardware information from the error::
-
- $ rasdaemon -p --status <STATUS> --ipid <IPID> --smca
-
-Also, the user can pass particular family and model to decode the error
-string::
-
- $ rasdaemon -p --status <STATUS> --ipid <IPID> --smca --family <CPU Family> --model <CPU Model> --bank <BANK_NUM>
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 36e6178..07f2aa0 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -113,7 +113,7 @@ to ReStructured Text format, or are simply too old.
:maxdepth: 1
staging/index
- RAS/ras
+ RAS/index
Translations
diff --git a/MAINTAINERS b/MAINTAINERS
index 87a5a61..39ecc16 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -18170,6 +18170,7 @@ M: Tony Luck <[email protected]>
M: Borislav Petkov <[email protected]>
L: [email protected]
S: Maintained
+F: Documentation/RAS/
F: Documentation/admin-guide/ras.rst
F: drivers/ras/
F: include/linux/ras.h