docs/faq.rst | 71 +++++++++++++++++++++++++++++++++++++++++++++++ docs/glossary.rst | 15 ++++++++++ docs/index.rst | 1 + 3 files changed, 87 insertions(+) create mode 100644 docs/faq.rst
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.2On 26.02.2024 17:25, Andrew Cooper wrote: > This is long overdue, and we need to start somewhere. > > Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com> Acked-by: Jan Beulich <jbeulich@suse.com> perhaps (nit) with ... > --- /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 ... s/with/is/ (or "was"). Jan
On 26/02/2024 4:52 pm, Jan Beulich wrote: > On 26.02.2024 17:25, Andrew Cooper wrote: >> This is long overdue, and we need to start somewhere. >> >> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com> > Acked-by: Jan Beulich <jbeulich@suse.com> Thanks. > perhaps (nit) with ... > >> --- /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 > ... s/with/is/ (or "was"). Oops yes. Will fix. ~Andrew
© 2016 - 2024 Red Hat, Inc.