qemuboot.conf variables

qemuboot.conf variables

[Mark Hatle]

When I was looking through the large docs, I didn't see anything inside of it to 
explain the various variables used in the qemuboot.conf file.

Looking through the code, I found the stuff mostly in the class that creates the 
file, but there were also fragments of explanation in prior commit messages and 
other places.  Below is my attempt to collect all of the qemuboot.conf variables 
in one place, along with an explanation.  I think this would be useful to add to 
the regular docs, but I'm not exactly sure where or what format.

There are some other things related to runqemu usage that would be nice to 
document as well (command line usage, environment variable, command substitution 
behavior and generated command line rules), but the items below are the ones 
that I had to search for when I was trying to explain the qemuboot.conf to 
someone else.


QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)

QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used 
when QB_AUDIO_DRV is set.

QB_CLEANUP_CMD: enable running custom shell cleanup commands after QEMU.

QB_CMDLINE_IP_SLIRP: explicitely specify the ip= kernel command line arguments 
for slirp mode

QB_CMDLINE_IP_TAP: explicitely specify the ip= kernel command line arguments for 
tap mode

QB_CPU: QEMU cpu (e.g. "-cpu qemu32")

QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")

QB_DEFAULT_BIOS: specify a BIOS the same way that the KERNEL variable is 
specified (same as BIOS command line variable)

QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")

QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")

QB_DRIVE_TYPE: /dev/sd, /dev/hd, /dev/vdb, /dev/vd - config drives that start 
with one of these prefixes, requires virtio

QB_DTB: QEMU dtb name

QB_FSINFO: specify "wic:no-kernel-in-fs" or "wic:kernel-in-fs"

QB_GRAPHICS: QEMU video card type (e.g. "-vga std")

QB_KERNEL_CMDLINE: can be set to “none” to avoid overriding kernel command line 
specified in dtb

QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append option (e.g. 
"console=ttyS0 console=tty")

QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)

QB_MACHINE: QEMU machine (e.g. "-machine virt")

QB_MEM: Memory (e.g. "-m 512")

QB_NET: can be set to "none" to disable networking

QB_NETWORK_DEVICE: network device settings used by both slirp and tap

QB_NFSROOTFS_EXTRA_OPT: allow extra options to be appended to the NFS rootfs 
options in kernel boot args, e.g. "wsize=4096,rsize=4096"

QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")

QB_NO_PNI: By default, if 'DISTRO_FEATURES' does NOT contains 'pni-names' add 
'net.ifnames=0' to QB_CMDLINE_IP_TAP default.  See QB_CMDLINE_IP_TAP.

QB_RNG: Pass-through for host random number generator, it can speedup boot in 
system mode, where system is experiencing entropy starvation (requires virtio)

QB_ROOTFS: can be set to "none" to disable rootfs setup

QB_ROOTFS_EXTRA_OPT: Content of the optional parameter will be appended to the 
rootfs-device in the qemu configuration, in case QB_ROOTFS_OPT is not specified. 
By default this is empty.

QB_ROOTFS_OPT: Used as rootfs (e.g. "-drive 
id=disk0,file=@ROOTFS@,if=none,format=raw -device 
virtio-blk-device,drive=disk0"). runqemu will replace "@ROOTFS@" with the one 
which is used, such as core-image-minimal-qemuarm64.ext4.

QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")

QB_SETUP_CMD: enable running custom shell setup before QEMU.

QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device 
virtio-net-device,netdev=net0")

QB_SMP: amount of CPU cores inside qemu guest, each mapped to a thread on the 
host, e.g. "-smp 8"

QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")

QB_TAP_OPT: Network option for 'tap' mode (e.g. "-netdev 
tap,id=net0,ifname=@TAP@,script=no,downscript=no -device 
virtio-net-device,netdev=net0"). runqemu will replace "@TAP@" with the one that 
is used, such as tap0, tap1 ...

QB_TCPSERIAL_OPT: tcp serial port option (e.g. " -device virtio-serial-device 
-chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device 
virtconsole,chardev=virtcon" runqemu will replace "@PORT@" with the port number 
which is used.

Re: [docs] qemuboot.conf variables

[Quentin Schulz]

Hi Mark,

On 2/14/25 4:50 PM, Mark Hatle via lists.yoctoproject.org wrote:
> When I was looking through the large docs, I didn't see anything inside 
> of it to explain the various variables used in the qemuboot.conf file.
> 
> Looking through the code, I found the stuff mostly in the class that 
> creates the file, but there were also fragments of explanation in prior 
> commit messages and other places.  Below is my attempt to collect all of 
> the qemuboot.conf variables in one place, along with an explanation.  I 
> think this would be useful to add to the regular docs, but I'm not 
> exactly sure where or what format.
> 

We do have a QEMU-specific document so that could be a start though we 
don't have a glossary in there so we wouldn't be able to :term:`QB_DTB` 
for example elsewhere in the docs.

Another option is to have them all in the variables glossary with other 
variables. They may be a bit too machine-specific to be there, but maybe 
that's fine. In short, I don't know either what would be best. We could 
start with documentation/dev-manual/qemu.rst in any case.

> There are some other things related to runqemu usage that would be nice 
> to document as well (command line usage, environment variable, command 

We do have a section on the command line options for runqemu, are you 
thinking about something different?

> substitution behavior and generated command line rules), but the items 
> below are the ones that I had to search for when I was trying to explain 
> the qemuboot.conf to someone else.
> 

Thanks for sharing the info with us, looking forward to having patches 
on the mailing list :)

Cheers,
Quentin

Re: [docs] qemuboot.conf variables

[Mark Hatle]

On 2/17/25 6:04 AM, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Mark,
> 
> On 2/14/25 4:50 PM, Mark Hatle via lists.yoctoproject.org wrote:
>> When I was looking through the large docs, I didn't see anything inside
>> of it to explain the various variables used in the qemuboot.conf file.
>>
>> Looking through the code, I found the stuff mostly in the class that
>> creates the file, but there were also fragments of explanation in prior
>> commit messages and other places.  Below is my attempt to collect all of
>> the qemuboot.conf variables in one place, along with an explanation.  I
>> think this would be useful to add to the regular docs, but I'm not
>> exactly sure where or what format.
>>
> 
> We do have a QEMU-specific document so that could be a start though we
> don't have a glossary in there so we wouldn't be able to :term:`QB_DTB`
> for example elsewhere in the docs.
> 
> Another option is to have them all in the variables glossary with other
> variables. They may be a bit too machine-specific to be there, but maybe
> that's fine. In short, I don't know either what would be best. We could
> start with documentation/dev-manual/qemu.rst in any case.

I think a qemu specific document or section would be my suggested.  There is a 
lot of stuff about runqemu that is documented in the code or in random places 
and it would be nice to move it all to one place.

>> There are some other things related to runqemu usage that would be nice
>> to document as well (command line usage, environment variable, command
> 
> We do have a section on the command line options for runqemu, are you
> thinking about something different?

This is only a small part.  There are environment variables and how they are 
used, substitutions such as @PORT@ and others that are applied to certain parts 
of the configuration, etc.  Each of these really should be documented.

>> substitution behavior and generated command line rules), but the items
>> below are the ones that I had to search for when I was trying to explain
>> the qemuboot.conf to someone else.
>>
> 
> Thanks for sharing the info with us, looking forward to having patches
> on the mailing list :)
> 
> Cheers,
> Quentin
> 
> 
> 
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#6382): https://lists.yoctoproject.org/g/docs/message/6382
> Mute This Topic: https://lists.yoctoproject.org/mt/111184281/3616948
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [mark.hatle@kernel.crashing.org]
> -=-=-=-=-=-=-=-=-=-=-=-
>