Update kunit doc and tool with tips to build errors

PATCH In review Shuah Khan 5 participants 12 messages Apr 29, 2025 – May 1, 2025

Subsystems (4)

Documentation Kselftest Documentation process KUnit

lore

Share & tools

lore

Shuah Khan

author maintainer

2025-04-29 22:27 UTC #0 lore raw

cover Update kunit doc and tool with tips to build errors

kunit kernel build could fail if there are ny build artifacts from a prior kernel build. These can be hard to debug if the build artifact happens to be generated header file. It took me a while to debug kunit build fail on ARCH=x86_64 in a tree which had a generated header file arch/x86/realmode/rm/pasyms.h

make ARCH=um mrproper will not clean the tree. It is necessary to run make ARCH=x86_64 mrproper

Example work-flow that could lead to this:

        make allmodconfig (x86_64)
        make
        ./tools/testing/kunit/kunit.py run

Add this to the documentation and kunit.py build help message.

Shuah Khan (2):
doc: kunit: add information about cleaning source trees
kunit: add tips to clean source tree to build help message

 Documentation/dev-tools/kunit/start.rst | 12 ++++++++++++
 tools/testing/kunit/kunit.py            |  2 +-
 2 files changed, 13 insertions(+), 1 deletion(-)

Signature · 1 line

2.47.2

Shuah Khan

author maintainer

2025-04-29 22:27 UTC #1 lore raw

PATCH 1/2 doc: kunit: add information about cleaning source trees

If kunit run happens in a tree in which a x86_64 kernel was built, the source tree could be dirty.

"make ARCH=um mrproper" will not clean the x86_64 build artifacts. Running "make ARCH=x86_64 mrproper" is necessary to clean them.

Add this information to the documentation.

Signed-off-by Shuah Khan <[email protected]>

---
 Documentation/dev-tools/kunit/start.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

Documentation/dev-tools/kunit/start.rst +12 -0

index a98235326bab..568e29aebd6e 100644
@@ -39,6 +39,18 @@ can run kunit_tool:
 	``make ARCH=um mrproper``, just be aware that this will delete the
 	current configuration and all generated files.
 
+	You may see the following error if a prior build leaves behind
+	header files which 'make ARCH=um mrproper' fails to clean:
+
+	"undefined symbol sev_es_trampoline_start referenced ..."
+
+	This is special case scenario when a prior x86_64 build populates
+	the source tree with arch/x86/realmode/rm/pasyms.h. This header
+	will not be cleaned by 'make ARCH=um mrproper'
+
+	If you encouter this problem, run 'make ARCH=x86_64 mrproper' to
+	remove generated header files.
+
 If everything worked correctly, you should see the following:
 
 .. code-block::

Signature · 1 line

2.47.2

Randy Dunlap

reviewer

2025-04-29 22:29 UTC #2 lore raw

Re: [PATCH 1/2] doc: kunit: add information about cleaning source trees

Quoted 21 lines · Shuah Khan

If kunit run happens in a tree in which a x86_64 kernel was built, the source tree could be dirty.
"make ARCH=um mrproper" will not clean the x86_64 build artifacts. Running "make ARCH=x86_64 mrproper" is necessary to clean them.
Add this information to the documentation.
Signed-off-by Shuah Khan <[email protected]>
---
 Documentation/dev-tools/kunit/start.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)
Documentation/dev-tools/kunit/start.rst +0 -0
index a98235326bab..568e29aebd6e 100644
@@ -39,6 +39,18 @@ can run kunit_tool:
 	``make ARCH=um mrproper``, just be aware that this will delete the
 	current configuration and all generated files.
 

Documentation/dev-tools/kunit/start.rst can run kunit_tool: · line 51

Quoted 10 lines

Documentation/dev-tools/kunit/start.rst +10 -0

+	You may see the following error if a prior build leaves behind
+	header files which 'make ARCH=um mrproper' fails to clean:
+
+	"undefined symbol sev_es_trampoline_start referenced ..."
+
+	This is special case scenario when a prior x86_64 build populates
+	the source tree with arch/x86/realmode/rm/pasyms.h. This header
+	will not be cleaned by 'make ARCH=um mrproper'
+
+	If you encouter this problem, run 'make ARCH=x86_64 mrproper' to

encounter

Quoted 5 lines

Documentation/dev-tools/kunit/start.rst +2 -0

+	remove generated header files.
+
 If everything worked correctly, you should see the following:
 
 .. code-block::

Signature · 1 line

~Randy

Shuah Khan

author maintainer

2025-04-29 23:33 UTC #3 lore raw

Re: [PATCH 1/2] doc: kunit: add information about cleaning source trees

Quoted 24 lines · Randy Dunlap

Quoted 21 lines · Shuah Khan
If kunit run happens in a tree in which a x86_64 kernel was built, the source tree could be dirty.
"make ARCH=um mrproper" will not clean the x86_64 build artifacts. Running "make ARCH=x86_64 mrproper" is necessary to clean them.
Add this information to the documentation.
Signed-off-by Shuah Khan <[email protected]>
---
  Documentation/dev-tools/kunit/start.rst | 12 ++++++++++++
  1 file changed, 12 insertions(+)
Documentation/dev-tools/kunit/start.rst +0 -0
index a98235326bab..568e29aebd6e 100644
@@ -39,6 +39,18 @@ can run kunit_tool:
  	``make ARCH=um mrproper``, just be aware that this will delete the
  	current configuration and all generated files.
 

Quoted 12 lines

Documentation/dev-tools/kunit/start.rst can run kunit_tool: · line 51

Quoted 10 lines

Documentation/dev-tools/kunit/start.rst +10 -0

+	You may see the following error if a prior build leaves behind
+	header files which 'make ARCH=um mrproper' fails to clean:
+
+	"undefined symbol sev_es_trampoline_start referenced ..."
+
+	This is special case scenario when a prior x86_64 build populates
+	the source tree with arch/x86/realmode/rm/pasyms.h. This header
+	will not be cleaned by 'make ARCH=um mrproper'
+
+	If you encouter this problem, run 'make ARCH=x86_64 mrproper' to

encounter

Thank you. Will fix it.

thanks,
-- Shuah

Shuah Khan

author maintainer

2025-04-29 22:27 UTC #4 lore raw

PATCH 2/2 kunit: add tips to clean source tree to build help message

In reply to Shuah Khan

Add tips to clean source tree to build help message. When user run kunit.py after building another kernel for ARCH=foo, it is necessary to run 'make ARCH=foo mrproper' to remove all build artifacts generated during the build. In such cases, kunit build could fail.

Signed-off-by Shuah Khan <[email protected]>

---
 tools/testing/kunit/kunit.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

tools/testing/kunit/kunit.py +1 -1

index 7f9ae55fd6d5..db86a396ed33 100755
@@ -583,7 +583,7 @@ def main(argv: Sequence[str]) -> None:
 						'the options in .kunitconfig')
 	add_common_opts(config_parser)
 
-	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests')
+	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests. Successful build depends on a clean source tree. Run mrproper to clean generated artifcats for prior ARCH=foo kernel build. Run 'make ARCH=foo mrproper')
 	add_common_opts(build_parser)
 	add_build_opts(build_parser)

Signature · 1 line

2.47.2

Jonathan Corbet

maintainer

2025-04-29 22:50 UTC #5 lore raw

Re: [PATCH 2/2] kunit: add tips to clean source tree to build help message

Quoted 15 lines · Shuah Khan

Add tips to clean source tree to build help message. When user run kunit.py after building another kernel for ARCH=foo, it is necessary to run 'make ARCH=foo mrproper' to remove all build artifacts generated during the build. In such cases, kunit build could fail.
Signed-off-by Shuah Khan <[email protected]>
---
 tools/testing/kunit/kunit.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
tools/testing/kunit/kunit.py +0 -0
index 7f9ae55fd6d5..db86a396ed33 100755

tools/testing/kunit/kunit.py def main(argv: Sequence[str]) -> None: · line 587

Quoted 6 lines

tools/testing/kunit/kunit.py +1 -1

@@ -583,7 +583,7 @@ def main(argv: Sequence[str]) -> None:
 						'the options in .kunitconfig')
 	add_common_opts(config_parser)
 
-	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests')
+	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests. Successful build depends on a clean source tree. Run mrproper to clean generated artifcats for prior ARCH=foo kernel build. Run 'make ARCH=foo mrproper')
 	add_common_opts(build_parser)

Nit: could perhaps that line be broken in a bit more readable way?

build_parser = subparser.add_parser('build',
help='Builds a kernel with KUnit tests. '
'Successful build depends on a clean source tree. ' 'Run mrproper to clean generated artifacts for prior ' 'ARCH=foo kernel build. '
'Run "make ARCH=foo mrproper"')

(fixed "artifacts" while I was in the neighborhood :)

jon

Shuah Khan

author maintainer

2025-04-29 23:34 UTC #6 lore raw

Re: [PATCH 2/2] kunit: add tips to clean source tree to build help message

Quoted 27 lines · Jonathan Corbet

Quoted 15 lines · Shuah Khan
Add tips to clean source tree to build help message. When user run kunit.py after building another kernel for ARCH=foo, it is necessary to run 'make ARCH=foo mrproper' to remove all build artifacts generated during the build. In such cases, kunit build could fail.
Signed-off-by Shuah Khan <[email protected]>
---
  tools/testing/kunit/kunit.py | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
tools/testing/kunit/kunit.py +0 -0
index 7f9ae55fd6d5..db86a396ed33 100755
tools/testing/kunit/kunit.py def main(argv: Sequence[str]) -> None: · line 587
Quoted 6 lines
tools/testing/kunit/kunit.py +1 -1
@@ -583,7 +583,7 @@ def main(argv: Sequence[str]) -> None:
  						'the options in .kunitconfig')
  	add_common_opts(config_parser)
 
-	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests')
+	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests. Successful build depends on a clean source tree. Run mrproper to clean generated artifcats for prior ARCH=foo kernel build. Run 'make ARCH=foo mrproper')
  	add_common_opts(build_parser)
Nit: could perhaps that line be broken in a bit more readable way?

Quoted 6 lines

build_parser = subparser.add_parser('build',
help='Builds a kernel with KUnit tests. '
'Successful build depends on a clean source tree. ' 'Run mrproper to clean generated artifacts for prior ' 'ARCH=foo kernel build. '
'Run "make ARCH=foo mrproper"')

It improves readability. Will fix it.

Quoted 2 lines

(fixed "artifacts" while I was in the neighborhood :)

Thanks for catching it.

thanks,
-- Shuah

David Gow

2025-04-30 03:54 UTC #7 lore raw

Re: [PATCH 2/2] kunit: add tips to clean source tree to build help message

In reply to Shuah Khan

Quoted 8 lines · Shuah Khan

Add tips to clean source tree to build help message. When user run kunit.py after building another kernel for ARCH=foo, it is necessary to run 'make ARCH=foo mrproper' to remove all build artifacts generated during the build. In such cases, kunit build could fail.
Signed-off-by Shuah Khan <[email protected]>
---

Thanks for doing this.

This looks good to me, save for the issue below.

I do wonder whether there's a more general fix we can do in the makefiles, but I'm not sure how that'd have to work. Maybe by storing the architecture used somewhere and amending the error based on that, or hacking around the specific x86_64/UML incompatibilities. But let's go ahead with this fix regardless.

Cheers,
-- David

tools/testing/kunit/kunit.py def main(argv: Sequence[str]) -> None: · line 586

Quoted 13 lines

 tools/testing/kunit/kunit.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

tools/testing/kunit/kunit.py +1 -1

index 7f9ae55fd6d5..db86a396ed33 100755
@@ -583,7 +583,7 @@ def main(argv: Sequence[str]) -> None:
                                                'the options in .kunitconfig')
        add_common_opts(config_parser)
 
-       build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests')
+       build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests. Successful build depends on a clean source tree. Run mrproper to clean generated artifcats for prior ARCH=foo kernel build. Run 'make ARCH=foo mrproper')

Because this string is enclosed by single quotes, the 'make ARCH=foo mrproper' is not part of the string (and there's a missing terminating quote as well).

Maybe change help= to use double quotes, and add the missing one? Or use double quotes or backticks for the make example?

Quoted 6 lines

tools/testing/kunit/kunit.py +0 -1

        add_common_opts(build_parser)
        add_build_opts(build_parser)
 
--

2.47.2

Shuah Khan

author maintainer

2025-04-30 21:25 UTC #8 lore raw

Re: [PATCH 2/2] kunit: add tips to clean source tree to build help message

Quoted 12 lines · David Gow

Quoted 8 lines · Shuah Khan
Add tips to clean source tree to build help message. When user run kunit.py after building another kernel for ARCH=foo, it is necessary to run 'make ARCH=foo mrproper' to remove all build artifacts generated during the build. In such cases, kunit build could fail.
Signed-off-by Shuah Khan <[email protected]>
---
Thanks for doing this.

Quoted 7 lines

This looks good to me, save for the issue below.
I do wonder whether there's a more general fix we can do in the makefiles, but I'm not sure how that'd have to work. Maybe by storing the architecture used somewhere and amending the error based on that, or hacking around the specific x86_64/UML incompatibilities. But let's go ahead with this fix regardless.

I agree the right fix is to see if kunit.py can suggest the right arch to clean. I will take a look at that.

As you said, it is good to have this documented in this series.

Quoted 22 lines

Cheers,
-- David

tools/testing/kunit/kunit.py def main(argv: Sequence[str]) -> None: · line 586

Quoted 13 lines

  tools/testing/kunit/kunit.py | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)

tools/testing/kunit/kunit.py +1 -1

index 7f9ae55fd6d5..db86a396ed33 100755
@@ -583,7 +583,7 @@ def main(argv: Sequence[str]) -> None:
                                                 'the options in .kunitconfig')
         add_common_opts(config_parser)
 
-       build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests')
+       build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests. Successful build depends on a clean source tree. Run mrproper to clean generated artifcats for prior ARCH=foo kernel build. Run 'make ARCH=foo mrproper')

Because this string is enclosed by single quotes, the 'make ARCH=foo mrproper' is not part of the string (and there's a missing terminating quote as well).

Quoted 6 lines

Maybe change help= to use double quotes, and add the missing one? Or use double quotes or backticks for the make example?
Quoted 2 lines
tools/testing/kunit/kunit.py +0 -0
         add_common_opts(build_parser)
         add_build_opts(build_parser)

Thanks for the pointers. I will go look at those to make this help message coded better,

thanks,
-- Shuah

Shuah Khan

author maintainer

2025-05-01 00:40 UTC #9 lore raw

Re: [PATCH 2/2] kunit: add tips to clean source tree to build help message

Quoted 15 lines · Shuah Khan

Quoted 14 lines · David Gow
Quoted 8 lines · Shuah Khan
Add tips to clean source tree to build help message. When user run kunit.py after building another kernel for ARCH=foo, it is necessary to run 'make ARCH=foo mrproper' to remove all build artifacts generated during the build. In such cases, kunit build could fail.
Signed-off-by Shuah Khan <[email protected]>
---
Thanks for doing this.
This looks good to me, save for the issue below.

Quoted 8 lines

Quoted 5 lines
I do wonder whether there's a more general fix we can do in the makefiles, but I'm not sure how that'd have to work. Maybe by storing the architecture used somewhere and amending the error based on that, or hacking around the specific x86_64/UML incompatibilities. But let's go ahead with this fix regardless.
I agree the right fix is to see if kunit.py can suggest the right arch to clean. I will take a look at that.

It is an easy change to the main Makefile. Will send the patch tomorrow. We won't need the documentation and help message changes with the main Makefile change.

thanks,
-- Shuah

Mauro Carvalho Chehab

2025-04-30 05:18 UTC #10 lore raw

Re: [PATCH 2/2] kunit: add tips to clean source tree to build help message

In reply to Shuah Khan

Em Tue, 29 Apr 2025 16:27:12 -0600
Shuah Khan <[email protected]> escreveu:

Quoted 15 lines

Add tips to clean source tree to build help message. When user run kunit.py after building another kernel for ARCH=foo, it is necessary to run 'make ARCH=foo mrproper' to remove all build artifacts generated during the build. In such cases, kunit build could fail.
Signed-off-by Shuah Khan <[email protected]>
---
 tools/testing/kunit/kunit.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
tools/testing/kunit/kunit.py +0 -0
index 7f9ae55fd6d5..db86a396ed33 100755

tools/testing/kunit/kunit.py def main(argv: Sequence[str]) -> None: · line 589

Quoted 8 lines

tools/testing/kunit/kunit.py +1 -1

@@ -583,7 +583,7 @@ def main(argv: Sequence[str]) -> None:
 						'the options in .kunitconfig')
 	add_common_opts(config_parser)
 
-	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests')
+	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests. Successful build depends on a clean source tree. Run mrproper to clean generated artifcats for prior ARCH=foo kernel build. Run 'make ARCH=foo mrproper')
 	add_common_opts(build_parser)
 	add_build_opts(build_parser)

Would be better instead to detect if the last build was not done by kunit.py and call "make mrproper" inside kunit.py?

Thanks,
Mauro

Shuah Khan

author maintainer

2025-04-30 21:28 UTC #11 lore raw

Re: [PATCH 2/2] kunit: add tips to clean source tree to build help message

Quoted 21 lines · Mauro Carvalho Chehab

Em Tue, 29 Apr 2025 16:27:12 -0600
Shuah Khan <[email protected]> escreveu:
Quoted 18 lines
Add tips to clean source tree to build help message. When user run kunit.py after building another kernel for ARCH=foo, it is necessary to run 'make ARCH=foo mrproper' to remove all build artifacts generated during the build. In such cases, kunit build could fail.
Signed-off-by Shuah Khan <[email protected]>
---
  tools/testing/kunit/kunit.py | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
tools/testing/kunit/kunit.py +0 -0
index 7f9ae55fd6d5..db86a396ed33 100755
@@ -583,7 +583,7 @@ def main(argv: Sequence[str]) -> None:
  						'the options in .kunitconfig')
  	add_common_opts(config_parser)
 

Quoted 7 lines

tools/testing/kunit/kunit.py def main(argv: Sequence[str]) -> None: · line 589
Quoted 5 lines
tools/testing/kunit/kunit.py +1 -1
-	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests')
+	build_parser = subparser.add_parser('build', help='Builds a kernel with KUnit tests. Successful build depends on a clean source tree. Run mrproper to clean generated artifcats for prior ARCH=foo kernel build. Run 'make ARCH=foo mrproper')
  	add_common_opts(build_parser)
  	add_build_opts(build_parser)
 
Would be better instead to detect if the last build was not done by kunit.py and call "make mrproper" inside kunit.py?

Detecting last build and printing out the right "make ARCH= mrproper" command is good. I don't think we want run the call make mrproper from kunit.py - this shouldn't be a automatic step. It would be annoying to loose build artifacts if it isn't what user would want.

thanks,
-- Shuah

Quoted 3 lines

Thanks,
Mauro