On Thu, 11 Mar 2021 at 22:37, Andrey Konovalov <andreyknvl@xxxxxxxxxx> 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@xxxxxxxxxx> > --- > 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 c9484f34da2a..343a683d0520 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 Clang 11+. Doesn't HW_TAGS mode work with GCC as well? While the sentence doesn't say "exclusively", the mention of Clang 11+ makes me think it's only Clang. > +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 >
