[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [PATCH] 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> --- CC: George Dunlap <George.Dunlap@xxxxxxxxxx> CC: Jan Beulich <JBeulich@xxxxxxxx> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx> CC: Wei Liu <wl@xxxxxxx> CC: Julien Grall <julien@xxxxxxx> --- 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
|
![]() |
Lists.xenproject.org is hosted with RackSpace, monitoring our |