[xen staging] docs/sphinx: Start an FAQ, and add Kconfig/CET details

[patchbot@xxxxxxx]

commit 6f1b2808760874d3912d3b9a02aec9433d08f35c
Author:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
AuthorDate: Wed Feb 7 12:06:25 2024 +0000
Commit:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CommitDate: Mon Feb 26 18:20:27 2024 +0000

    docs/sphinx: Start an FAQ, and add Kconfig/CET details
    
    This is long overdue, and we need to start somewhere.
    
    Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
    Acked-by: Jan Beulich <jbeulich@xxxxxxxx>
---
 docs/faq.rst      | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/glossary.rst | 15 ++++++++++++
 docs/index.rst    |  1 +
 3 files changed, 87 insertions(+)

diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 0000000000..a56b607814
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,71 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Frequently Asked Questions
+==========================
+
+How do I...
+-----------
+
+... check whether a Kconfig option is active?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  Kconfig is a build time configuration system, combining inherent knowledge,
+  the capabilities of the toolchain, and explicit user choice to form a
+  configuration of a build of Xen.
+
+  A file, by default ``.config``, is produced by the build identifying the
+  configuration used.  Kconfig symbols all start with ``CONFIG_``, and come in
+  a variety of types including strings, integers and booleans.  Booleans are
+  the most common, and when active are expressed with ``...=y``.  e.g.::
+
+    xen.git/xen$ grep CONFIG_FOO .config
+    CONFIG_FOO_BOOLEAN=y
+    CONFIG_FOO_STRING="lorem ipsum"
+    CONFIG_FOO_INTEGER=42
+
+  Symbols which are either absent, or expressed as ``... is not set`` are
+  disabled.  e.g.::
+
+    xen.git/xen$ grep CONFIG_BAR .config
+    # CONFIG_BAR is not set
+
+  Builds of Xen configured with ``CONFIG_HYPFS_CONFIG=y`` embed their own
+  ``.config`` at build time, and can provide it to the :term:`control domain`
+  upon requested.  e.g.::
+
+    [root@host ~]# xenhypfs cat /buildinfo/config | grep -e FOO -e BAR
+    CONFIG_FOO=y
+    # CONFIG_BAR is not set
+
+
+... tell if CET is active?
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  Control-flow Enforcement Technology support was added to Xen 4.14.  It is
+  build time conditional, dependent on both having a new-enough toolchain and
+  an explicit Kconfig option, and also requires capable hardware.  See
+  :term:`CET`.
+
+  For CET-SS, Shadow Stacks, the minimum toolchain requirements are ``binutils
+  >= 2.29`` or ``LLVM >= 6``.  No specific compiler support is required.
+  Check for ``CONFIG_XEN_SHSTK`` being active.
+
+  For CET-IBT, Indirect Branch Tracking, the minimum toolchain requirements
+  are ``GCC >= 9`` and ``binutils >= 2.29``.  Xen relies on a compiler feature
+  which is specific to GCC at the time of writing.  Check for
+  ``CONFIG_XEN_IBT`` being active.
+
+  If a capable Xen is booted on capable hardware, and CET is not disabled by
+  command line option or errata, Xen will print some details early on boot
+  about which CET facilities have been turned on::
+
+    ...
+    (XEN) CPU Vendor: Intel, Family 6 (0x6), Model 143 (0x8f), Stepping 8 (raw 
000806f8)
+    (XEN) Enabling Supervisor Shadow Stacks
+    (XEN) Enabling Indirect Branch Tracking
+    (XEN)   - IBT disabled in UEFI Runtime Services
+    (XEN) EFI RAM map:
+    ...
+
+  This can be obtained from the control domain with ``xl dmesg``, but remember
+  to confirm that the console ring hasn't wrapped.
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 8ddbdab160..6adeec77e1 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -28,6 +28,21 @@ Glossary
      single instance of Xen, used as the identifier in various APIs, and is
      typically allocated sequentially from 0.
 
+   CET
+     Control-flow Enforcement Technology is a facility in x86 CPUs for
+     defending against memory safety vulnerabilities.  It is formed of two
+     independent features:
+
+     * CET-SS, Shadow Stacks, are designed to protect against Return Oriented
+       Programming (ROP) attacks.
+
+     * CET-IBT, Indirect Branch Tracking, is designed to protect against Call
+       or Jump Oriented Programming (COP/JOP) attacks.
+
+     Intel support CET-SS and CET-IBT from the Tiger Lake (Client, 2020) and
+     Sapphire Rapids (Server, 2023) CPUs.  AMD support only CET-SS, starting
+     with Zen3 (Both client and server, 2020) CPUs.
+
    guest
      The term 'guest' has two different meanings, depending on context, and
      should not be confused with :term:`domain`.
diff --git a/docs/index.rst b/docs/index.rst
index 22fdde8059..ab051a0f38 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -72,4 +72,5 @@ Miscellanea
 
 .. toctree::
 
+   faq
    glossary
--
generated by git-patchbot for /home/xen/git/xen.git#staging