Message ID | 20240226162527.1247421-1-andrew.cooper3@citrix.com (mailing list archive) |
---|---|
State | New |
Headers | show |
Series | docs/sphinx: Start an FAQ, and add Kconfig/CET details | expand |
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> 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
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
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 base-commit: 60e00f77a5cc671d30c5ef3318f5b8e9b74e4aa3