linux-dev/Documentation/dev-tools/kunit, branch linus/master

Merge tag 'linux-kselftest-kunit-5.19-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest

2022-05-25T18:32:53Z

Pull KUnit updates from Shuah Khan: "Several fixes, cleanups, and enhancements to tests and framework: - introduce _NULL and _NOT_NULL macros to pointer error checks - rework kunit_resource allocation policy to fix memory leaks when caller doesn't specify free() function to be used when allocating memory using kunit_add_resource() and kunit_alloc_resource() funcs. - add ability to specify suite-level init and exit functions" * tag 'linux-kselftest-kunit-5.19-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest: (41 commits) kunit: tool: Use qemu-system-i386 for i386 runs kunit: fix executor OOM error handling logic on non-UML kunit: tool: update riscv QEMU config with new serial dependency kcsan: test: use new suite_{init,exit} support kunit: tool: Add list of all valid test configs on UML kunit: take `kunit_assert` as `const` kunit: tool: misc cleanups kunit: tool: minor cosmetic cleanups in kunit_parser.py kunit: tool: make parser stop overwriting status of suites w/ no_tests kunit: tool: remove dead parse_crash_in_log() logic kunit: tool: print clearer error message when there's no TAP output kunit: tool: stop using a shell to run kernel under QEMU kunit: tool: update test counts summary line format kunit: bail out of test filtering logic quicker if OOM lib/Kconfig.debug: change KUnit tests to default to KUNIT_ALL_TESTS kunit: Rework kunit_resource allocation policy kunit: fix debugfs code to use enum kunit_status, not bool kfence: test: use new suite_{init/exit} support, add .kunitconfig kunit: add ability to specify suite-level init and exit functions kunit: rename print_subtest_{start,end} for clarity (s/subtest/suite) ...

Merge tag 'docs-5.19' of git://git.lwn.net/linux

2022-05-25T18:17:41Z

Pull documentation updates from Jonathan Corbet: "It was a moderately busy cycle for documentation; highlights include: - After a long period of inactivity, the Japanese translations are seeing some much-needed maintenance and updating. - Reworked IOMMU documentation - Some new documentation for static-analysis tools - A new overall structure for the memory-management documentation. This is an LSFMM outcome that, it is hoped, will help encourage developers to fill in the many gaps. Optimism is eternal...but hopefully it will work. - More Chinese translations. Plus the usual typo fixes, updates, etc" * tag 'docs-5.19' of git://git.lwn.net/linux: (70 commits) docs: pdfdocs: Add space for chapter counts >= 100 in TOC docs/zh_CN: Add dev-tools/gdb-kernel-debugging.rst Chinese translation input: Docs: correct ntrig.rst typo input: Docs: correct atarikbd.rst typos MAINTAINERS: Become the docs/zh_CN maintainer docs/zh_CN: fix devicetree usage-model translation mm,doc: Add new documentation structure Documentation: drop more IDE boot options and ide-cd.rst Documentation/process: use scripts/get_maintainer.pl on patches MAINTAINERS: Add entry for DOCUMENTATION/JAPANESE docs/trans/ja_JP/howto: Don't mention specific kernel versions docs/ja_JP/SubmittingPatches: Request summaries for commit references docs/ja_JP/SubmittingPatches: Add Suggested-by as a standard signature docs/ja_JP/SubmittingPatches: Randy has moved docs/ja_JP/SubmittingPatches: Suggest the use of scripts/get_maintainer.pl docs/ja_JP/SubmittingPatches: Update GregKH links Documentation/sysctl: document max_rcu_stall_to_panic Documentation: add missing angle bracket in cgroup-v2 doc Documentation: dev-tools: use literal block instead of code-block docs/zh_CN: add vm numa translation ...

kunit: add ability to specify suite-level init and exit functions

2022-05-02T18:35:51Z

KUnit has support for setup/cleanup logic for each test case in a suite. But it lacks the ability to specify setup/cleanup for the entire suite itself. This can be used to do setup that is too expensive or cumbersome to do for each test. Or it can be used to do simpler things like log debug information after the suite completes. It's a fairly common feature, so the lack of it is noticeable. Some examples in other frameworks and languages: * https://docs.python.org/3/library/unittest.html#setupclass-and-teardownclass * https://google.github.io/googletest/reference/testing.html#Test::SetUpTestSuite Meta: This is very similar to this patch here: https://lore.kernel.org/linux-kselftest/20210805043503.20252-3-bvanassche@acm.org/ The changes from that patch: * pass in `struct kunit *` so users can do stuff like `kunit_info(suite, "debug message")` * makes sure the init failure is bubbled up as a failure * updates kunit-example-test.c to use a suite init * Updates kunit/usage.rst to mention the new support * some minor cosmetic things * use `suite_{init,exit}` instead of `{init/exit}_suite` * make suite init error message more consistent w/ test init * etc. Signed-off-by: Daniel Latypov Reviewed-by: David Gow Reviewed-by: Brendan Higgins Signed-off-by: Shuah Khan

Documentation: kunit: change complete_and_exit to kthread_complete_and_exit

2022-04-22T15:47:25Z

Commit cead18552660 ("exit: Rename complete_and_exit to kthread_complete_and_exit") renamed complete_and_exit to kthread_complete_and_exit. Signed-off-by: Andreas-Christian Hagau Reviewed-by: Brendan Higgins Signed-off-by: Jonathan Corbet

Documentation: kunit: update kconfig options needed for UML coverage

2022-04-04T22:42:38Z

Recent changes have made it so the current set is not sufficient. Namely, CONFIG_DEBUG_INFO is not being set even when explicitly asked. Specifying a version of the debug info fixes this. Pick CONFIG_DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT as an option that's hopefully less fragile (esp. given we're tied to GCC 6 and lower). Signed-off-by: Daniel Latypov Reviewed-by: David Gow Tested-by: Maxime Ripard Reviewed-by: Brendan Higgins Signed-off-by: Shuah Khan

kunit: split resource API from test.h into new resource.h

2022-04-04T22:23:08Z

Background: Currently, a reader looking at kunit/test.h will find the file is quite long, and the first meaty comment is a doc comment about struct kunit_resource. Most users will not ever use the KUnit resource API directly. They'll use kunit_kmalloc() and friends, or decide it's simpler to do cleanups via labels (it often can be) instead of figuring out how to use the API. It's also logically separate from everything else in test.h. Removing it from the file doesn't cause any compilation errors (since struct kunit has `struct list_head resources` to store them). This commit: Let's move it into a kunit/resource.h file and give it a separate page in the docs, kunit/api/resource.rst. We include resource.h at the bottom of test.h since * don't want to force existing users to add a new include if they use the API * it accesses `lock` inside `struct kunit` in a inline func * so we can't just forward declare, and the alternatives require uninlining the func, adding hepers to lock/unlock, or other more invasive changes. Now the first big comment in test.h is about kunit_case, which is a lot more relevant to what a new user wants to know. A side effect of this is git blame won't properly track history by default, users need to run $ git blame -L ,1 -C17 include/kunit/resource.h Signed-off-by: Daniel Latypov Reviewed-by: David Gow Reviewed-by: Brendan Higgins Signed-off-by: Shuah Khan

Documentation: kunit: fix path to .kunitconfig in start.rst

2022-04-04T18:02:44Z

Commit ddbd60c779b4 ("kunit: use --build_dir=.kunit as default") changed the default --build_dir, which had the side effect of making `.kunitconfig` move to `.kunit/.kunitconfig`. However, the first few lines of kunit/start.rst never got updated, oops. Fix this by telling people to run kunit.py first, which will automatically generate the .kunit directory and .kunitconfig file, and then edit the file manually as desired. Reported-by: Yifan Yuan Signed-off-by: Daniel Latypov Reviewed-by: David Gow Reviewed-by: Brendan Higgins Signed-off-by: Shuah Khan

Merge tag 'docs-5.18-2' of git://git.lwn.net/linux

2022-03-31T19:10:42Z

Pull more documentation updates from Jonathan Corbet: "Some late-arriving documentation improvements. This is mostly build-system fixes from Mauro and Akira; I also took the liberty of dropping in my 'messy diffstat' document" * tag 'docs-5.18-2' of git://git.lwn.net/linux: docs: Add a document on how to fix a messy diffstat docs: sphinx/requirements: Limit jinja2<3.1 Documentation: kunit: Fix cross-referencing warnings scripts/kernel-doc: change the line number meta info scripts/get_abi: change the file/line number meta info docs: kernel_include.py: add sphinx build dependencies docs: kernel_abi.py: add sphinx build dependencies docs: kernel_feat.py: add build dependencies scripts/get_feat.pl: allow output the parsed file names docs: kfigure.py: Don't warn of missing PDF converter in 'make htmldocs' Documentation: Fix duplicate statement about raw_spinlock_t type

Documentation: kunit: Fix cross-referencing warnings

2022-03-28T21:36:41Z

The Architecture chapter of the KUnit documentation tried to include copies of the kernel-doc for a couple of things, despite these already existing in the API documentation. This lead to some warnings: architecture:31: ./include/kunit/test.h:3: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:66. Declaration is '.. c:struct:: kunit_case'. architecture:163: ./include/kunit/test.h:1217: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:1217. Declaration is '.. c:macro:: KUNIT_ARRAY_PARAM'. architecture.rst:3: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:66. Declaration is '.. c:struct:: kunit_case'. architecture.rst:1217: WARNING: Duplicate C declaration, also defined at dev-tools/kunit/api/test:1217. Declaration is '.. c:macro:: KUNIT_ARRAY_PARAM'. Get rid of these, and cleanup the mentions of the struct and macro in question so that sphinx generates a link to the existing copy of the documentation in the api/test document. Fixes: bc145b370c11 ("Documentation: KUnit: Added KUnit Architecture") Signed-off-by: David Gow Reviewed-by: Brendan Higgins Tested-by: Brendan Higgins Link: https://lore.kernel.org/r/20220326054414.637293-1-davidgow@google.com Signed-off-by: Jonathan Corbet

Documentation: KUnit: Fix usage bug

2022-02-08T20:16:20Z

Fix a bug of kunit documentation. Link: https://bugzilla.kernel.org/show_bug.cgi?id=205773 : Quoting Steve Pfetsch: : : kunit documentation is incorrect: : https://kunit.dev/third_party/stable_kernel/docs/usage.html : struct rectangle *self = container_of(this, struct shape, parent); : : : Shouldn't it be: : struct rectangle *self = container_of(this, struct rectangle, parent); : ? Signed-off-by: Akira Kawata Reviewed-by: Brendan Higgins Signed-off-by: Shuah Khan