[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [xen master] docs/sphinx: Start an FAQ, and add Kconfig/CET details
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#master
|
![]() |
Lists.xenproject.org is hosted with RackSpace, monitoring our |