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

[Andrew Cooper <andrew.cooper3@citrix.com>]

This is long overdue, and we need to start somewhere.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: George Dunlap <George.Dunlap@citrix.com>
CC: Jan Beulich <JBeulich@suse.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Wei Liu <wl@xen.org>
CC: Julien Grall <julien@xen.org>
---
 docs/faq.rst      | 71 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/glossary.rst | 15 ++++++++++
 docs/index.rst    |  1 +
 3 files changed, 87 insertions(+)
 create mode 100644 docs/faq.rst

diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 000000000000..75cd70328a5c
--- /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 with 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 8ddbdab160a1..6adeec77e14c 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 22fdde80590c..ab051a0f3833 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -72,4 +72,5 @@ Miscellanea
 
 .. toctree::
 
+   faq
    glossary

base-commit: 60e00f77a5cc671d30c5ef3318f5b8e9b74e4aa3
-- 
2.30.2