Skip to contentSkip to conversation

docs: add documentation for SLUB cache kunit tests

PATCH In review [email protected] 3 participants 3 messages Jun 8, 2021 – Jun 9, 2021

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: add documentation for SLUB cache kunit tests

From: Oliver Glitta <[email protected]>

Add documentation for a KUnit test for SLUB debugging functionality.

---
 Documentation/vm/slub.rst | 104 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
Documentation/vm/slub.rst +104 -0
index 03f294a638bd..ca82fc1649ee 100644
@@ -384,5 +384,109 @@ c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the
       40,60`` range will plot only samples collected between 40th and
       60th seconds).
 
+KUnit tests for SLUB debugging functionality
+============================================
+
+These KUnit tests are used to test some of the SLUB debugging
+functionalities.
+
+KUnit tests are used for unit testing in Linux kernel and easy to run,
+so it is probably the best choice for this type of tests.
+
+There are tests, which corrupt redzone, the free objects and the freelist.
+Tests are corrupting specific bytes in cache and checking if validation
+finds expected number of bugs. Bug reports are silenced.
+
+Config option
+
+In order to built and then run this tests you need to switch
+option SLUB_KUNIT_TEST on. It is tristate option so it can also
+be built as a module. This option depends on SLUB_DEBUG and
+KUNIT options. By default it is on with all kunit tests.
+
+Error counting
+
+To get number of errors discovered in slub is used test API kunit_resource.
+In test_init the reference to the integer variable slab_errors is added
+to the resource of this tests.
+
+During slub cache checking always when bug should be reported or fixed function
+slab_add_kunit_errors() is called. This function find resource to kunit test
+and increment value of data in founded resource, which is slab_errors
+variable.
+
+Silence bug reports
+
+The function slab_add_kunit_errors() is returning bool, which is true if there is kunit test
+with correct kunit_resource running, to silence bug reports, so they are not printed.
+We do not want to correct errors we only want to know they occurred, so these reports
+are unnnecessary.
+
+KASAN option
+
+Only 2 out of 5 tests are runnig with KASAN option is on.
+The other three tests deliberately modifies non-allocated objects. And KASAN
+does not detect some errors in the same way as SLUB_DEBUG. So, these tests
+does not run when KASAN option is on.
+
+TESTS
+
+1. test_clobber_zone
+
+   SLUB cache with SLUB_REDZONE flag can detects writings after object. This
+   functionality is tested here on allocated memory.
+
+   First, there is allocated memory with SLAB_REDZONE and then the first byte
+   after allocated space is modified. Validation founds 2 errors, because of
+   the bug and the fix of the memory.
+
+
+2. test_next_pointer
+
+   SLUB have list of free objects and the address of the next free object
+   is always saved in free object at offset specified in variable offset
+   in struct kmem_cache. This test try to corrupt this freelist and
+   then correct it.
+
+   First, there is allocated and freed memory to get a pointer to free object.
+   After that, the pointer to next free object is corrupted. The first validation finds
+   3 errors. One for corrupted freechain, the second for the wrong count of objects
+   in use and the third for fixing the issue. This fix only set number of objects
+   in use to a number of all objects minus 1, because the first free object
+   was corrupted.
+
+   Then the free pointer is fixed to his previous value. The second validation finds
+   2 errors. One for the wrong count of objects in use and one for fixing this error.
+
+   Last validation is used to check if all errors were corrected so no error
+   is found.
+
+3. test_first_word
+
+   SLUB cache with SLAB_POISON flag can detect poisoning free objects. This
+   functionality is tested in this test. The test tries to corrupt
+   the first byte in freed memory.
+
+   First of all, memory is allocated and freed to get a pointer to a free object
+   and then the first byte is corrupted. After that, validation finds 2 errors,
+   one for the bug and the other one for the fix of the memory.
+
+4. test_clobber_50th_byte
+
+   In this test SLAB_POISON functionality is tested. The test tries to
+   corrupt the 50th byte in freed memory.
+
+   First, pointer to a free memory is acquired by allocating and freeing memory.
+   Then 50th byte is corrupted and validation finds 2 errors for the bug and
+   the fix of the memory.
+
+5. test_clobber_redzone_free
+
+   This test tests redzone functionality of SLUB cache on a freed object.
+
+   First, it gets pointer to the free object with allocating and freeing and
+   then corrupts the first byte after the freed object. Validation finds
+   2 errors for the bug and the fix of the memory.
+
 Christoph Lameter, May 30, 2007
 Sergey Senozhatsky, October 23, 2015

--
2.31.1.272.g89b43f80a5

#1 lore raw
Quoted 6 lines · On Tue, Jun 8, 2021 at 1:47 AM <[email protected]> wrote:

From: Oliver Glitta <[email protected]>

Add documentation for a KUnit test for SLUB debugging functionality.

I'm not in the intended audience for this documentation, so I've mainly just gone and pointed out some small spelling mistakes and some formatting suggestions.

Quoted 10 lines
---
 Documentation/vm/slub.rst | 104 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
Documentation/vm/slub.rst +0 -0
index 03f294a638bd..ca82fc1649ee 100644
@@ -384,5 +384,109 @@ c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the
       40,60`` range will plot only samples collected between 40th and

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 394

Quoted 10 lines
Documentation/vm/slub.rst +8 -0
       60th seconds).
 
+KUnit tests for SLUB debugging functionality
+============================================
+
+These KUnit tests are used to test some of the SLUB debugging
+functionalities.
+
+KUnit tests are used for unit testing in Linux kernel and easy to run,
+so it is probably the best choice for this type of tests.

Note: if we think KUnit is worth explaining here, perhaps it's also worth linking to KUnit documentation?

Something like
"KUnit (Documentation/dev-tools/kunit/index.rst) ..."

should work, or "See KUnit documentation (...) for more details", etc.

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 402

Quoted 8 lines
Documentation/vm/slub.rst +8 -0
+
+There are tests, which corrupt redzone, the free objects and the freelist.
+Tests are corrupting specific bytes in cache and checking if validation
+finds expected number of bugs. Bug reports are silenced.
+
+Config option
+
+In order to built and then run this tests you need to switch

nit: "to build"
nit: "run these tests"

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 403

Quoted 1 line
Documentation/vm/slub.rst +1 -0
+option SLUB_KUNIT_TEST on. It is tristate option so it can also

minor nit: s/is tristate/is a tristate

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 405

Quoted 2 lines
Documentation/vm/slub.rst +2 -0
+be built as a module. This option depends on SLUB_DEBUG and
+KUNIT options. By default it is on with all kunit tests.

I assume this last sentence is about CONFIG_KUNIT_ALL_TESTS. I don't think we need to document that here.

It could also mislead users as selecting CONFIG_KUNIT_ALL_TESTS=y will not be sufficient to make the test run on its own.

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 409

Quoted 4 lines
Documentation/vm/slub.rst +4 -0
+
+Error counting
+
+To get number of errors discovered in slub is used test API kunit_resource.

Nit: "To get the number"

Nit: can we use ``kunit_resource`` to format code-related terms?

Note: we can link to the API reference by including "test API (Documentation/dev-tools/kunit/api/test.rst)"

Not sure if you saw, but this is that page:
https://www.kernel.org/doc/html/latest/dev-tools/kunit/api/test.html
Coincidentally enough, kunit_resource is the first thing shown for now :)

Note: it'd be cool if we could link to a specific section, but I
haven't checked if that's actually possible with automarkup.py, e.g.
like https://www.kernel.org/doc/html/latest/dev-tools/kunit/api/test.html#c.kunit_resource

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 413

Quoted 4 lines
Documentation/vm/slub.rst +4 -0
+In test_init the reference to the integer variable slab_errors is added
+to the resource of this tests.
+
+During slub cache checking always when bug should be reported or fixed function

Nit: "when a bug"

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 423

Quoted 10 lines
Documentation/vm/slub.rst +10 -0
+slab_add_kunit_errors() is called. This function find resource to kunit test
+and increment value of data in founded resource, which is slab_errors
+variable.
+
+Silence bug reports
+
+The function slab_add_kunit_errors() is returning bool, which is true if there is kunit test
+with correct kunit_resource running, to silence bug reports, so they are not printed.
+We do not want to correct errors we only want to know they occurred, so these reports
+are unnnecessary.

nit: "unnecessary"

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 427

Quoted 4 lines
Documentation/vm/slub.rst +4 -0
+
+KASAN option
+
+Only 2 out of 5 tests are runnig with KASAN option is on.

nit: "running"

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 428

Quoted 1 line
Documentation/vm/slub.rst +1 -0
+The other three tests deliberately modifies non-allocated objects. And KASAN

nit: "other three tests ... modify"

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 432

Quoted 4 lines
Documentation/vm/slub.rst +4 -0
+does not detect some errors in the same way as SLUB_DEBUG. So, these tests
+does not run when KASAN option is on.
+
+TESTS

I'm not the intended target for this doc, so feel free to ignore this comment entirely.

Hmm, I'm not really a fan of the docs listing out each test case and what they do.
I feel like this will get out of sync and you now are expected to read another file to understand what the tests do.
I can see the benefit of a high-level explanation, especially if we started having more tests scattered across multiple files, but I think we should wait until that time comes.

So I'd personally prefer it if we converted these sections into comments on the test cases themselves.

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 436

Quoted 4 lines
Documentation/vm/slub.rst +4 -0
+
+1. test_clobber_zone
+
+   SLUB cache with SLUB_REDZONE flag can detects writings after object. This

nit: is there a missing word after "after object.", perhaps "deallocation"? Perhaps then: "can detect writes after objection deallocation", or more simply "can detect write-after-free errors" ?

Quoted 63 lines
Documentation/vm/slub.rst +54 -1
+   functionality is tested here on allocated memory.
+
+   First, there is allocated memory with SLAB_REDZONE and then the first byte
+   after allocated space is modified. Validation founds 2 errors, because of
+   the bug and the fix of the memory.
+
+
+2. test_next_pointer
+
+   SLUB have list of free objects and the address of the next free object
+   is always saved in free object at offset specified in variable offset
+   in struct kmem_cache. This test try to corrupt this freelist and
+   then correct it.
+
+   First, there is allocated and freed memory to get a pointer to free object.
+   After that, the pointer to next free object is corrupted. The first validation finds
+   3 errors. One for corrupted freechain, the second for the wrong count of objects
+   in use and the third for fixing the issue. This fix only set number of objects
+   in use to a number of all objects minus 1, because the first free object
+   was corrupted.
+
+   Then the free pointer is fixed to his previous value. The second validation finds
+   2 errors. One for the wrong count of objects in use and one for fixing this error.
+
+   Last validation is used to check if all errors were corrected so no error
+   is found.
+
+3. test_first_word
+
+   SLUB cache with SLAB_POISON flag can detect poisoning free objects. This
+   functionality is tested in this test. The test tries to corrupt
+   the first byte in freed memory.
+
+   First of all, memory is allocated and freed to get a pointer to a free object
+   and then the first byte is corrupted. After that, validation finds 2 errors,
+   one for the bug and the other one for the fix of the memory.
+
+4. test_clobber_50th_byte
+
+   In this test SLAB_POISON functionality is tested. The test tries to
+   corrupt the 50th byte in freed memory.
+
+   First, pointer to a free memory is acquired by allocating and freeing memory.
+   Then 50th byte is corrupted and validation finds 2 errors for the bug and
+   the fix of the memory.
+
+5. test_clobber_redzone_free
+
+   This test tests redzone functionality of SLUB cache on a freed object.
+
+   First, it gets pointer to the free object with allocating and freeing and
+   then corrupts the first byte after the freed object. Validation finds
+   2 errors for the bug and the fix of the memory.
+
 Christoph Lameter, May 30, 2007
 Sergey Senozhatsky, October 23, 2015
--

2.31.1.272.g89b43f80a5

--
You received this message because you are subscribed to the Google Groups "KUnit Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/20210608084740.6282-1-glittao%40gmail.com.

#2 lore raw
In reply to [email protected]

Some spelling fixes below but it got a bit much when looking through this. Maybe rewrite this again for clarity?

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 391

Quoted 5 lines · On Tue, 8 Jun 2021, [email protected] wrote:
Documentation/vm/slub.rst +5 -0
+KUnit tests for SLUB debugging functionality
+============================================
+
+These KUnit tests are used to test some of the SLUB debugging
+functionalities.

functionality.

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 398

Quoted 7 lines
Documentation/vm/slub.rst +7 -0
+
+KUnit tests are used for unit testing in Linux kernel and easy to run,
+so it is probably the best choice for this type of tests.
+
+There are tests, which corrupt redzone, the free objects and the freelist.
+Tests are corrupting specific bytes in cache and checking if validation
+finds expected number of bugs. Bug reports are silenced.

"in a SLUB cache" .... or "in a cache"

finds *the* expected number of ...

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 403

Quoted 2 lines
Documentation/vm/slub.rst +2 -0
+In order to built and then run this tests you need to switch
+option SLUB_KUNIT_TEST on. It is tristate option so it can also

*the* option
*a* tristate option

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 409

Quoted 6 lines
Documentation/vm/slub.rst +6 -0
+be built as a module. This option depends on SLUB_DEBUG and
+KUNIT options. By default it is on with all kunit tests.
+
+Error counting
+
+To get number of errors discovered in slub is used test API kunit_resource.

What does that mean?

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 416

Quoted 7 lines
Documentation/vm/slub.rst +7 -0
+In test_init the reference to the integer variable slab_errors is added
+to the resource of this tests.
+
+During slub cache checking always when bug should be reported or fixed function
+slab_add_kunit_errors() is called. This function find resource to kunit test
+and increment value of data in founded resource, which is slab_errors
+variable.

??

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 423

Quoted 7 lines
Documentation/vm/slub.rst +7 -0
+
+Silence bug reports
+
+The function slab_add_kunit_errors() is returning bool, which is true if there is kunit test
+with correct kunit_resource running, to silence bug reports, so they are not printed.
+We do not want to correct errors we only want to know they occurred, so these reports
+are unnnecessary.

These reports are unnecessary because we do not want to correct errors. We only want to know that they occurred.

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 427

Quoted 4 lines
Documentation/vm/slub.rst +4 -0
+
+KASAN option
+
+Only 2 out of 5 tests are runnig with KASAN option is on.

running

Quoted 1 line

+The other three tests deliberately modifies non-allocated objects. And KASAN

modify

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 430

Quoted 2 lines
Documentation/vm/slub.rst +2 -0
+does not detect some errors in the same way as SLUB_DEBUG. So, these tests
+does not run when KASAN option is on.

do

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 437

Quoted 4 lines

+1. test_clobber_zone

Documentation/vm/slub.rst +3 -0
+
+   SLUB cache with SLUB_REDZONE flag can detects writings after object. This
+   functionality is tested here on allocated memory.

... can detect modifying memory locations after the object.

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 441

Quoted 4 lines
Documentation/vm/slub.rst +4 -0
+
+   First, there is allocated memory with SLAB_REDZONE and then the first byte
+   after allocated space is modified. Validation founds 2 errors, because of
+   the bug and the fix of the memory.

after *the* allocated space. The validation finds 2 errors. One is the fact that there is a corrupted redzone and the second due to the repair of the redzone.

Documentation/vm/slub.rst c) Execute ``slabinfo-gnuplot.sh`` in '-t' mode, passing all of the · line 449

Quoted 6 lines

+2. test_next_pointer

Documentation/vm/slub.rst +5 -0
+
+   SLUB have list of free objects and the address of the next free object
+   is always saved in free object at offset specified in variable offset
+   in struct kmem_cache. This test try to corrupt this freelist and
+   then correct it.

SLUB *has a* .... is ** saved in a *freed object* at *the* offset ...

Quoted 46 lines
Documentation/vm/slub.rst +41 -1
+
+   First, there is allocated and freed memory to get a pointer to free object.
+   After that, the pointer to next free object is corrupted. The first validation finds
+   3 errors. One for corrupted freechain, the second for the wrong count of objects
+   in use and the third for fixing the issue. This fix only set number of objects
+   in use to a number of all objects minus 1, because the first free object
+   was corrupted.
+
+   Then the free pointer is fixed to his previous value. The second validation finds
+   2 errors. One for the wrong count of objects in use and one for fixing this error.
+
+   Last validation is used to check if all errors were corrected so no error
+   is found.
+
+3. test_first_word
+
+   SLUB cache with SLAB_POISON flag can detect poisoning free objects. This
+   functionality is tested in this test. The test tries to corrupt
+   the first byte in freed memory.
+
+   First of all, memory is allocated and freed to get a pointer to a free object
+   and then the first byte is corrupted. After that, validation finds 2 errors,
+   one for the bug and the other one for the fix of the memory.
+
+4. test_clobber_50th_byte
+
+   In this test SLAB_POISON functionality is tested. The test tries to
+   corrupt the 50th byte in freed memory.
+
+   First, pointer to a free memory is acquired by allocating and freeing memory.
+   Then 50th byte is corrupted and validation finds 2 errors for the bug and
+   the fix of the memory.
+
+5. test_clobber_redzone_free
+
+   This test tests redzone functionality of SLUB cache on a freed object.
+
+   First, it gets pointer to the free object with allocating and freeing and
+   then corrupts the first byte after the freed object. Validation finds
+   2 errors for the bug and the fix of the memory.
+
 Christoph Lameter, May 30, 2007
 Sergey Senozhatsky, October 23, 2015
--

2.31.1.272.g89b43f80a5