Questions about runqemu --help, misleading usage string?

Questions about runqemu --help, misleading usage string?

[Michael Opdenacker]

Hello,

Following some experiments with the runqemu command, I'm trying to
update its documentation in the development manual, which looks
significantly out of date. However, reading the code, I think that the
usage string is misleading...

Here's the current usage:

   Usage: you can run this script with any valid combination
   of the following environment variables (in any order):
     KERNEL - the kernel image file to use
     BIOS - the bios image file to use
     ROOTFS - the rootfs image file or nfsroot directory to use
     DEVICE_TREE - the device tree blob to use
     MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
     Simplified QEMU command-line options can be passed with:
       nographic - disable video console
       ....

I understand that MACHINE can be recognized because of unique valid
strings corresponding to it (such as "qemuarm64"), KERNEL because its
filename and extension can be recognized, ROOTFS because it is a file
with a known extension or is a directory. I also checked that MACHINE,
KERNEL and ROOTFS can be set as environment variables.

But what about BIOS and DEVICE_TREE? It only seems to be possible to
pass them as environment variables.

If so, then the usage string is very confusing, because it gives the
impression that BIOS and DEVICE_TREE are at the same level as KERNEL,
ROOTFS and MACHINE, but unlike the latter, they cannot be passed as
command line arguments.

Shouldn't we modify "runqemu --help" so that it lists supported
environment variables and details that only KERNEL, ROOTFS and MACHINE
can be set by parsing the command line?

Thank you in advance,

Cheers,

Michael.


-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] Questions about runqemu --help, misleading usage string?

[Richard Purdie]

On Thu, 2021-05-06 at 17:10 +0200, Michael Opdenacker wrote:
> Following some experiments with the runqemu command, I'm trying to
> update its documentation in the development manual, which looks
> significantly out of date. However, reading the code, I think that the
> usage string is misleading...
> 
> Here's the current usage:
> 
>    Usage: you can run this script with any valid combination
>    of the following environment variables (in any order):
>      KERNEL - the kernel image file to use
>      BIOS - the bios image file to use
>      ROOTFS - the rootfs image file or nfsroot directory to use
>      DEVICE_TREE - the device tree blob to use
>      MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
>      Simplified QEMU command-line options can be passed with:
>        nographic - disable video console
>        ....
> 
> I understand that MACHINE can be recognized because of unique valid
> strings corresponding to it (such as "qemuarm64"), KERNEL because its
> filename and extension can be recognized, ROOTFS because it is a file
> with a known extension or is a directory. I also checked that MACHINE,
> KERNEL and ROOTFS can be set as environment variables.
> 
> But what about BIOS and DEVICE_TREE? It only seems to be possible to
> pass them as environment variables.
> 
> If so, then the usage string is very confusing, because it gives the
> impression that BIOS and DEVICE_TREE are at the same level as KERNEL,
> ROOTFS and MACHINE, but unlike the latter, they cannot be passed as
> command line arguments.
> 
> Shouldn't we modify "runqemu --help" so that it lists supported
> environment variables and details that only KERNEL, ROOTFS and MACHINE
> can be set by parsing the command line?

I suspect you're right and we should fix the help output...

Cheers,

Richard

Re: [docs] Questions about runqemu --help, misleading usage string?

[Michael Opdenacker]

HI Richard,

On 5/10/21 10:57 AM, Richard Purdie wrote:
> On Thu, 2021-05-06 at 17:10 +0200, Michael Opdenacker wrote:
>> Following some experiments with the runqemu command, I'm trying to
>> update its documentation in the development manual, which looks
>> significantly out of date. However, reading the code, I think that the
>> usage string is misleading...
>>
>> Here's the current usage:
>>
>>    Usage: you can run this script with any valid combination
>>    of the following environment variables (in any order):
>>      KERNEL - the kernel image file to use
>>      BIOS - the bios image file to use
>>      ROOTFS - the rootfs image file or nfsroot directory to use
>>      DEVICE_TREE - the device tree blob to use
>>      MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
>>      Simplified QEMU command-line options can be passed with:
>>        nographic - disable video console
>>        ....
>>
>> I understand that MACHINE can be recognized because of unique valid
>> strings corresponding to it (such as "qemuarm64"), KERNEL because its
>> filename and extension can be recognized, ROOTFS because it is a file
>> with a known extension or is a directory. I also checked that MACHINE,
>> KERNEL and ROOTFS can be set as environment variables.
>>
>> But what about BIOS and DEVICE_TREE? It only seems to be possible to
>> pass them as environment variables.
>>
>> If so, then the usage string is very confusing, because it gives the
>> impression that BIOS and DEVICE_TREE are at the same level as KERNEL,
>> ROOTFS and MACHINE, but unlike the latter, they cannot be passed as
>> command line arguments.
>>
>> Shouldn't we modify "runqemu --help" so that it lists supported
>> environment variables and details that only KERNEL, ROOTFS and MACHINE
>> can be set by parsing the command line?
> I suspect you're right and we should fix the help output...

Many thanks for the feedback. Then I'll submit a patch to double check
this, and if it's accepted, I'll update the documentation accordingly.

Cheers,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com