[PATCH 0/2] Update kunit doc and tool with tips to build errors

[PATCH 0/2] Update kunit doc and tool with tips to build errors

[Shuah Khan]

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(-)

-- 
2.47.2

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

[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 <skhan@linuxfoundation.org>
---
 Documentation/dev-tools/kunit/start.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
index a98235326bab..568e29aebd6e 100644
--- a/Documentation/dev-tools/kunit/start.rst
+++ b/Documentation/dev-tools/kunit/start.rst
@@ -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::
-- 
2.47.2

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

[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 <skhan@linuxfoundation.org>
---
 tools/testing/kunit/kunit.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/testing/kunit/kunit.py b/tools/testing/kunit/kunit.py
index 7f9ae55fd6d5..db86a396ed33 100755
--- a/tools/testing/kunit/kunit.py
+++ b/tools/testing/kunit/kunit.py
@@ -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)
 
-- 
2.47.2

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

[Randy Dunlap]

On 4/29/25 3:27 PM, Shuah Khan wrote:
> 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 <skhan@linuxfoundation.org>
> ---
>  Documentation/dev-tools/kunit/start.rst | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
> index a98235326bab..568e29aebd6e 100644
> --- a/Documentation/dev-tools/kunit/start.rst
> +++ b/Documentation/dev-tools/kunit/start.rst
> @@ -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

	       encounter

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

-- 
~Randy

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

[Jonathan Corbet]

Shuah Khan <skhan@linuxfoundation.org> writes:

> 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 <skhan@linuxfoundation.org>
> ---
>  tools/testing/kunit/kunit.py | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/tools/testing/kunit/kunit.py b/tools/testing/kunit/kunit.py
> index 7f9ae55fd6d5..db86a396ed33 100755
> --- a/tools/testing/kunit/kunit.py
> +++ b/tools/testing/kunit/kunit.py
> @@ -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

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

[Shuah Khan]

On 4/29/25 16:29, Randy Dunlap wrote:
> 
> 
> On 4/29/25 3:27 PM, Shuah Khan wrote:
>> 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 <skhan@linuxfoundation.org>
>> ---
>>   Documentation/dev-tools/kunit/start.rst | 12 ++++++++++++
>>   1 file changed, 12 insertions(+)
>>
>> diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst
>> index a98235326bab..568e29aebd6e 100644
>> --- a/Documentation/dev-tools/kunit/start.rst
>> +++ b/Documentation/dev-tools/kunit/start.rst
>> @@ -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
> 
> 	       encounter

Thank you. Will fix it.

thanks,
-- Shuah

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

[Shuah Khan]

On 4/29/25 16:49, Jonathan Corbet wrote:
> Shuah Khan <skhan@linuxfoundation.org> writes:
> 
>> 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 <skhan@linuxfoundation.org>
>> ---
>>   tools/testing/kunit/kunit.py | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/tools/testing/kunit/kunit.py b/tools/testing/kunit/kunit.py
>> index 7f9ae55fd6d5..db86a396ed33 100755
>> --- a/tools/testing/kunit/kunit.py
>> +++ b/tools/testing/kunit/kunit.py
>> @@ -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"')

It improves readability. Will fix it.
> 
> (fixed "artifacts" while I was in the neighborhood :)

Thanks for catching it.

thanks,
-- Shuah

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

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 2009 bytes --]

On Wed, 30 Apr 2025 at 06:27, Shuah Khan <skhan@linuxfoundation.org> wrote:
>
> 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 <skhan@linuxfoundation.org>
> ---

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 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/tools/testing/kunit/kunit.py b/tools/testing/kunit/kunit.py
> index 7f9ae55fd6d5..db86a396ed33 100755
> --- a/tools/testing/kunit/kunit.py
> +++ b/tools/testing/kunit/kunit.py
> @@ -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?


>         add_common_opts(build_parser)
>         add_build_opts(build_parser)
>
> --
> 2.47.2
>

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 5281 bytes --]

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

[Mauro Carvalho Chehab]

Em Tue, 29 Apr 2025 16:27:12 -0600
Shuah Khan <skhan@linuxfoundation.org> escreveu:

> 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 <skhan@linuxfoundation.org>
> ---
>  tools/testing/kunit/kunit.py | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/tools/testing/kunit/kunit.py b/tools/testing/kunit/kunit.py
> index 7f9ae55fd6d5..db86a396ed33 100755
> --- a/tools/testing/kunit/kunit.py
> +++ b/tools/testing/kunit/kunit.py
> @@ -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

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

[Shuah Khan]

On 4/29/25 21:54, David Gow wrote:
> On Wed, 30 Apr 2025 at 06:27, Shuah Khan <skhan@linuxfoundation.org> wrote:
>>
>> 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 <skhan@linuxfoundation.org>
>> ---
> 
> 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.

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.

> 
> Cheers,
> -- David
> 
>>   tools/testing/kunit/kunit.py | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/tools/testing/kunit/kunit.py b/tools/testing/kunit/kunit.py
>> index 7f9ae55fd6d5..db86a396ed33 100755
>> --- a/tools/testing/kunit/kunit.py
>> +++ b/tools/testing/kunit/kunit.py
>> @@ -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?
> 
> 
>>          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

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

[Shuah Khan]

On 4/29/25 23:18, Mauro Carvalho Chehab wrote:
> Em Tue, 29 Apr 2025 16:27:12 -0600
> Shuah Khan <skhan@linuxfoundation.org> escreveu:
> 
>> 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 <skhan@linuxfoundation.org>
>> ---
>>   tools/testing/kunit/kunit.py | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/tools/testing/kunit/kunit.py b/tools/testing/kunit/kunit.py
>> index 7f9ae55fd6d5..db86a396ed33 100755
>> --- a/tools/testing/kunit/kunit.py
>> +++ b/tools/testing/kunit/kunit.py
>> @@ -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?

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

> 
> Thanks,
> Mauro

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

[Shuah Khan]

On 4/30/25 15:25, Shuah Khan wrote:
> On 4/29/25 21:54, David Gow wrote:
>> On Wed, 30 Apr 2025 at 06:27, Shuah Khan <skhan@linuxfoundation.org> wrote:
>>>
>>> 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 <skhan@linuxfoundation.org>
>>> ---
>>
>> 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.
> 
> 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