| Message ID | 1486fba8514de3d7db2f47df2192db59228b0a7b.1615559068.git.andreyknvl@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2,01/11] kasan: docs: clean up sections | expand |
On Fri, Mar 12, 2021 at 03:24PM +0100, Andrey Konovalov wrote: > Update the "Overview" section in KASAN documentation: > > - Outline main use cases for each mode. > - Mention that HW_TAGS mode need compiler support too. > - Move the part about SLUB/SLAB support from "Usage" to "Overview". > - Punctuation, readability, and other minor clean-ups. > > Signed-off-by: Andrey Konovalov <andreyknvl@google.com> Reviewed-by: Marco Elver <elver@google.com> > --- > > Changes v1->v2: > - Mention GCC support for HW_TAGS. > --- > Documentation/dev-tools/kasan.rst | 27 +++++++++++++++++++-------- > 1 file changed, 19 insertions(+), 8 deletions(-) > > diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst > index b3b2c517db55..2f2697b290d5 100644 > --- a/Documentation/dev-tools/kasan.rst > +++ b/Documentation/dev-tools/kasan.rst > @@ -11,17 +11,31 @@ designed to find out-of-bound and use-after-free bugs. KASAN has three modes: > 2. software tag-based KASAN (similar to userspace HWASan), > 3. hardware tag-based KASAN (based on hardware memory tagging). > > -Software KASAN modes (1 and 2) use compile-time instrumentation to insert > -validity checks before every memory access, and therefore require a compiler > +Generic KASAN is mainly used for debugging due to a large memory overhead. > +Software tag-based KASAN can be used for dogfood testing as it has a lower > +memory overhead that allows using it with real workloads. Hardware tag-based > +KASAN comes with low memory and performance overheads and, therefore, can be > +used in production. Either as an in-field memory bug detector or as a security > +mitigation. > + > +Software KASAN modes (#1 and #2) use compile-time instrumentation to insert > +validity checks before every memory access and, therefore, require a compiler > version that supports that. > > -Generic KASAN is supported in both GCC and Clang. With GCC it requires version > +Generic KASAN is supported in GCC and Clang. With GCC, it requires version > 8.3.0 or later. Any supported Clang version is compatible, but detection of > out-of-bounds accesses for global variables is only supported since Clang 11. > > -Tag-based KASAN is only supported in Clang. > +Software tag-based KASAN mode is only supported in Clang. > > -Currently generic KASAN is supported for the x86_64, arm, arm64, xtensa, s390 > +The hardware KASAN mode (#3) relies on hardware to perform the checks but > +still requires a compiler version that supports memory tagging instructions. > +This mode is supported in GCC 10+ and Clang 11+. > + > +Both software KASAN modes work with SLUB and SLAB memory allocators, > +while the hardware tag-based KASAN currently only supports SLUB. > + > +Currently, generic KASAN is supported for the x86_64, arm, arm64, xtensa, s390, > and riscv architectures, and tag-based KASAN modes are supported only for arm64. > > Usage > @@ -39,9 +53,6 @@ For software modes, you also need to choose between CONFIG_KASAN_OUTLINE and > CONFIG_KASAN_INLINE. Outline and inline are compiler instrumentation types. > The former produces smaller binary while the latter is 1.1 - 2 times faster. > > -Both software KASAN modes work with both SLUB and SLAB memory allocators, > -while the hardware tag-based KASAN currently only support SLUB. > - > For better error reports that include stack traces, enable CONFIG_STACKTRACE. > > To augment reports with last allocation and freeing stack of the physical page, > -- > 2.31.0.rc2.261.g7f71774620-goog >
diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index b3b2c517db55..2f2697b290d5 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -11,17 +11,31 @@ designed to find out-of-bound and use-after-free bugs. KASAN has three modes: 2. software tag-based KASAN (similar to userspace HWASan), 3. hardware tag-based KASAN (based on hardware memory tagging). -Software KASAN modes (1 and 2) use compile-time instrumentation to insert -validity checks before every memory access, and therefore require a compiler +Generic KASAN is mainly used for debugging due to a large memory overhead. +Software tag-based KASAN can be used for dogfood testing as it has a lower +memory overhead that allows using it with real workloads. Hardware tag-based +KASAN comes with low memory and performance overheads and, therefore, can be +used in production. Either as an in-field memory bug detector or as a security +mitigation. + +Software KASAN modes (#1 and #2) use compile-time instrumentation to insert +validity checks before every memory access and, therefore, require a compiler version that supports that. -Generic KASAN is supported in both GCC and Clang. With GCC it requires version +Generic KASAN is supported in GCC and Clang. With GCC, it requires version 8.3.0 or later. Any supported Clang version is compatible, but detection of out-of-bounds accesses for global variables is only supported since Clang 11. -Tag-based KASAN is only supported in Clang. +Software tag-based KASAN mode is only supported in Clang. -Currently generic KASAN is supported for the x86_64, arm, arm64, xtensa, s390 +The hardware KASAN mode (#3) relies on hardware to perform the checks but +still requires a compiler version that supports memory tagging instructions. +This mode is supported in GCC 10+ and Clang 11+. + +Both software KASAN modes work with SLUB and SLAB memory allocators, +while the hardware tag-based KASAN currently only supports SLUB. + +Currently, generic KASAN is supported for the x86_64, arm, arm64, xtensa, s390, and riscv architectures, and tag-based KASAN modes are supported only for arm64. Usage @@ -39,9 +53,6 @@ For software modes, you also need to choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and inline are compiler instrumentation types. The former produces smaller binary while the latter is 1.1 - 2 times faster. -Both software KASAN modes work with both SLUB and SLAB memory allocators, -while the hardware tag-based KASAN currently only support SLUB. - For better error reports that include stack traces, enable CONFIG_STACKTRACE. To augment reports with last allocation and freeing stack of the physical page,
Update the "Overview" section in KASAN documentation: - Outline main use cases for each mode. - Mention that HW_TAGS mode need compiler support too. - Move the part about SLUB/SLAB support from "Usage" to "Overview". - Punctuation, readability, and other minor clean-ups. Signed-off-by: Andrey Konovalov <andreyknvl@google.com> --- Changes v1->v2: - Mention GCC support for HW_TAGS. --- Documentation/dev-tools/kasan.rst | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-)