| Message ID | 3531e8fe6972cf39d1954e3643237b19eb21227e.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 "Error reports" section in KASAN documentation: > > - Mention that bug titles are best-effort. > - Move and reword the part about auxiliary stacks from > "Implementation details". > - Punctuation, readability, and other minor clean-ups. > > Signed-off-by: Andrey Konovalov <andreyknvl@google.com> Reviewed-by: Marco Elver <elver@google.com> > --- > Documentation/dev-tools/kasan.rst | 46 +++++++++++++++++-------------- > 1 file changed, 26 insertions(+), 20 deletions(-) > > diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst > index 46f4e9680805..cd12c890b888 100644 > --- a/Documentation/dev-tools/kasan.rst > +++ b/Documentation/dev-tools/kasan.rst > @@ -60,7 +60,7 @@ physical pages, enable ``CONFIG_PAGE_OWNER`` and boot with ``page_owner=on``. > Error reports > ~~~~~~~~~~~~~ > > -A typical out-of-bounds access generic KASAN report looks like this:: > +A typical KASAN report looks like this:: > > ================================================================== > BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] > @@ -133,33 +133,43 @@ A typical out-of-bounds access generic KASAN report looks like this:: > ffff8801f44ec400: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc > ================================================================== > > -The header of the report provides a short summary of what kind of bug happened > -and what kind of access caused it. It's followed by a stack trace of the bad > -access, a stack trace of where the accessed memory was allocated (in case bad > -access happens on a slab object), and a stack trace of where the object was > -freed (in case of a use-after-free bug report). Next comes a description of > -the accessed slab object and information about the accessed memory page. > +The report header summarizes what kind of bug happened and what kind of access > +caused it. It is followed by a stack trace of the bad access, a stack trace of > +where the accessed memory was allocated (in case a slab object was accessed), > +and a stack trace of where the object was freed (in case of a use-after-free > +bug report). Next comes a description of the accessed slab object and the > +information about the accessed memory page. > > -In the last section the report shows memory state around the accessed address. > -Internally KASAN tracks memory state separately for each memory granule, which > +In the end, the report shows the memory state around the accessed address. > +Internally, KASAN tracks memory state separately for each memory granule, which > is either 8 or 16 aligned bytes depending on KASAN mode. Each number in the > memory state section of the report shows the state of one of the memory > granules that surround the accessed address. > > -For generic KASAN the size of each memory granule is 8. The state of each > +For generic KASAN, the size of each memory granule is 8. The state of each > granule is encoded in one shadow byte. Those 8 bytes can be accessible, > -partially accessible, freed or be a part of a redzone. KASAN uses the following > -encoding for each shadow byte: 0 means that all 8 bytes of the corresponding > +partially accessible, freed, or be a part of a redzone. KASAN uses the following > +encoding for each shadow byte: 00 means that all 8 bytes of the corresponding > memory region are accessible; number N (1 <= N <= 7) means that the first N > bytes are accessible, and other (8 - N) bytes are not; any negative value > indicates that the entire 8-byte word is inaccessible. KASAN uses different > negative values to distinguish between different kinds of inaccessible memory > like redzones or freed memory (see mm/kasan/kasan.h). > > -In the report above the arrows point to the shadow byte 03, which means that > -the accessed address is partially accessible. For tag-based KASAN modes this > -last report section shows the memory tags around the accessed address > -(see the `Implementation details`_ section). > +In the report above, the arrow points to the shadow byte ``03``, which means > +that the accessed address is partially accessible. > + > +For tag-based KASAN modes, this last report section shows the memory tags around > +the accessed address (see the `Implementation details`_ section). > + > +Note that KASAN bug titles (like ``slab-out-of-bounds`` or ``use-after-free``) > +are best-effort: KASAN prints the most probable bug type based on the limited > +information it has. The actual type of the bug might be different. > + > +Generic KASAN also reports up to two auxiliary call stack traces. These stack > +traces point to places in code that interacted with the object but that are not > +directly present in the bad access stack trace. Currently, this includes > +call_rcu() and workqueue queuing. > > Boot parameters > ~~~~~~~~~~~~~~~ > @@ -214,10 +224,6 @@ function calls GCC directly inserts the code to check the shadow memory. > This option significantly enlarges kernel but it gives x1.1-x2 performance > boost over outline instrumented kernel. > > -Generic KASAN also reports the last 2 call stacks to creation of work that > -potentially has access to an object. Call stacks for the following are shown: > -call_rcu() and workqueue queuing. > - > Generic KASAN is the only mode that delays the reuse of freed object via > quarantine (see mm/kasan/quarantine.c for implementation). > > -- > 2.31.0.rc2.261.g7f71774620-goog >
diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index 46f4e9680805..cd12c890b888 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -60,7 +60,7 @@ physical pages, enable ``CONFIG_PAGE_OWNER`` and boot with ``page_owner=on``. Error reports ~~~~~~~~~~~~~ -A typical out-of-bounds access generic KASAN report looks like this:: +A typical KASAN report looks like this:: ================================================================== BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] @@ -133,33 +133,43 @@ A typical out-of-bounds access generic KASAN report looks like this:: ffff8801f44ec400: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc ================================================================== -The header of the report provides a short summary of what kind of bug happened -and what kind of access caused it. It's followed by a stack trace of the bad -access, a stack trace of where the accessed memory was allocated (in case bad -access happens on a slab object), and a stack trace of where the object was -freed (in case of a use-after-free bug report). Next comes a description of -the accessed slab object and information about the accessed memory page. +The report header summarizes what kind of bug happened and what kind of access +caused it. It is followed by a stack trace of the bad access, a stack trace of +where the accessed memory was allocated (in case a slab object was accessed), +and a stack trace of where the object was freed (in case of a use-after-free +bug report). Next comes a description of the accessed slab object and the +information about the accessed memory page. -In the last section the report shows memory state around the accessed address. -Internally KASAN tracks memory state separately for each memory granule, which +In the end, the report shows the memory state around the accessed address. +Internally, KASAN tracks memory state separately for each memory granule, which is either 8 or 16 aligned bytes depending on KASAN mode. Each number in the memory state section of the report shows the state of one of the memory granules that surround the accessed address. -For generic KASAN the size of each memory granule is 8. The state of each +For generic KASAN, the size of each memory granule is 8. The state of each granule is encoded in one shadow byte. Those 8 bytes can be accessible, -partially accessible, freed or be a part of a redzone. KASAN uses the following -encoding for each shadow byte: 0 means that all 8 bytes of the corresponding +partially accessible, freed, or be a part of a redzone. KASAN uses the following +encoding for each shadow byte: 00 means that all 8 bytes of the corresponding memory region are accessible; number N (1 <= N <= 7) means that the first N bytes are accessible, and other (8 - N) bytes are not; any negative value indicates that the entire 8-byte word is inaccessible. KASAN uses different negative values to distinguish between different kinds of inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h). -In the report above the arrows point to the shadow byte 03, which means that -the accessed address is partially accessible. For tag-based KASAN modes this -last report section shows the memory tags around the accessed address -(see the `Implementation details`_ section). +In the report above, the arrow points to the shadow byte ``03``, which means +that the accessed address is partially accessible. + +For tag-based KASAN modes, this last report section shows the memory tags around +the accessed address (see the `Implementation details`_ section). + +Note that KASAN bug titles (like ``slab-out-of-bounds`` or ``use-after-free``) +are best-effort: KASAN prints the most probable bug type based on the limited +information it has. The actual type of the bug might be different. + +Generic KASAN also reports up to two auxiliary call stack traces. These stack +traces point to places in code that interacted with the object but that are not +directly present in the bad access stack trace. Currently, this includes +call_rcu() and workqueue queuing. Boot parameters ~~~~~~~~~~~~~~~ @@ -214,10 +224,6 @@ function calls GCC directly inserts the code to check the shadow memory. This option significantly enlarges kernel but it gives x1.1-x2 performance boost over outline instrumented kernel. -Generic KASAN also reports the last 2 call stacks to creation of work that -potentially has access to an object. Call stacks for the following are shown: -call_rcu() and workqueue queuing. - Generic KASAN is the only mode that delays the reuse of freed object via quarantine (see mm/kasan/quarantine.c for implementation).
Update the "Error reports" section in KASAN documentation: - Mention that bug titles are best-effort. - Move and reword the part about auxiliary stacks from "Implementation details". - Punctuation, readability, and other minor clean-ups. Signed-off-by: Andrey Konovalov <andreyknvl@google.com> --- Documentation/dev-tools/kasan.rst | 46 +++++++++++++++++-------------- 1 file changed, 26 insertions(+), 20 deletions(-)