docs: add documentation for SLUB cache kunit tests
Subsystems (3)
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
@@ -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
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.
Signed-off-by Oliver Glitta <[email protected]>
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@@ -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
-060th 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.
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_zoneDocumentation/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_pointerDocumentation/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