[PATCH] docs/system: clarify pflash0 and pflash1 are virt-only options

[PATCH] docs/system: clarify pflash0 and pflash1 are virt-only options

[Linisha]

The pflash0 and pflash1 machine options shown in the Aarch64 virt example are only available for virt machine types on Arm, RISC-V, and LoongArch architectures. Add a note to clarify this for users who may try these options on x86 machines and be confused when they are not available.

Resolves: https://gitlab.com/qemu-project/qemu/-/issues/3254
Signed-off-by: Linisha <linisha232@gmail.com>
---
 docs/system/introduction.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/system/introduction.rst b/docs/system/introduction.rst
index bec7291e47..0c400aefb6 100644
--- a/docs/system/introduction.rst
+++ b/docs/system/introduction.rst
@@ -158,6 +158,12 @@ virtualisation so we can use KVM inside the emulated guest. As the
 ``virt`` machine comes with some built in pflash devices we give them
 names so we can override the defaults later.
 
+.. note::
+   The ``pflash0`` and ``pflash1`` machine options are specific to the
+   ``virt`` machine type on Arm, RISC-V, and LoongArch architectures.
+   They are not available on x86 machines, which use ``-bios`` or
+   ``-pflash`` for firmware instead.
+
 .. code::
 
  $ qemu-system-aarch64 \
-- 
2.47.0.windows.1

Re: [PATCH] docs/system: clarify pflash0 and pflash1 are virt-only options

[Daniel P. Berrangé]

On Wed, Jun 24, 2026 at 02:28:39AM +0530, Linisha wrote:
> The pflash0 and pflash1 machine options shown in the Aarch64 virt example are only available for virt machine types on Arm, RISC-V, and LoongArch architectures. Add a note to clarify this for users who may try these options on x86 machines and be confused when they are not available.
> 
> Resolves: https://gitlab.com/qemu-project/qemu/-/issues/3254
> Signed-off-by: Linisha <linisha232@gmail.com>
> ---
>  docs/system/introduction.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/docs/system/introduction.rst b/docs/system/introduction.rst
> index bec7291e47..0c400aefb6 100644
> --- a/docs/system/introduction.rst
> +++ b/docs/system/introduction.rst
> @@ -158,6 +158,12 @@ virtualisation so we can use KVM inside the emulated guest. As the
>  ``virt`` machine comes with some built in pflash devices we give them
>  names so we can override the defaults later.
>  
> +.. note::
> +   The ``pflash0`` and ``pflash1`` machine options are specific to the
> +   ``virt`` machine type on Arm, RISC-V, and LoongArch architectures.
> +   They are not available on x86 machines, which use ``-bios`` or
> +   ``-pflash`` for firmware instead.

No this is wrong.

The pflash0 and pflash1 properties apply to x86 pc & q35 machines too.

-pflash is a legacy syntax which remaps to pflash0 and pflash1 internally,
but also applies to other machines which don't use the new pflash0/pflash1
properties.

With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

Re: [PATCH] docs/system: clarify pflash0 and pflash1 are virt-only options

[Peter Maydell]

On Wed, 24 Jun 2026 at 08:15, Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> On Wed, Jun 24, 2026 at 02:28:39AM +0530, Linisha wrote:
> > The pflash0 and pflash1 machine options shown in the Aarch64 virt example are only available for virt machine types on Arm, RISC-V, and LoongArch architectures. Add a note to clarify this for users who may try these options on x86 machines and be confused when they are not available.
> >
> > Resolves: https://gitlab.com/qemu-project/qemu/-/issues/3254
> > Signed-off-by: Linisha <linisha232@gmail.com>
> > ---
> >  docs/system/introduction.rst | 6 ++++++
> >  1 file changed, 6 insertions(+)
> >
> > diff --git a/docs/system/introduction.rst b/docs/system/introduction.rst
> > index bec7291e47..0c400aefb6 100644
> > --- a/docs/system/introduction.rst
> > +++ b/docs/system/introduction.rst
> > @@ -158,6 +158,12 @@ virtualisation so we can use KVM inside the emulated guest. As the
> >  ``virt`` machine comes with some built in pflash devices we give them
> >  names so we can override the defaults later.
> >
> > +.. note::
> > +   The ``pflash0`` and ``pflash1`` machine options are specific to the
> > +   ``virt`` machine type on Arm, RISC-V, and LoongArch architectures.
> > +   They are not available on x86 machines, which use ``-bios`` or
> > +   ``-pflash`` for firmware instead.
>
> No this is wrong.
>
> The pflash0 and pflash1 properties apply to x86 pc & q35 machines too.
>
> -pflash is a legacy syntax which remaps to pflash0 and pflash1 internally,
> but also applies to other machines which don't use the new pflash0/pflash1
> properties.

I think it is probably worth having something in the intro text that
makes the point that for QEMU all architectures and machines are
potentially different, and that options and command lines that work
on for example an x86 PC machine will not necessarily work on
an Arm machine, and so on. But we should do that as a kind of
general warning somewhere near the start.

The bug report notes that "./build/x86/qemu-system-x86_64 -M pc,help"
does not list the pflash0 and pflash1 options. I think this is
because we set these up as alias properties on the actual flash
device object in pc_pflash_create(), so they don't exist as class
properties that "help" can introspect on.

-- PMM

Re: [PATCH] docs/system: clarify pflash0 and pflash1 are virt-only options

[linisha]

Hi Daniel, Peter,

Thank you both for taking the time to review and explain. I understand
now that pflash0 and pflash1 do work on x86 pc/q35 — the underlying
issue is that help cannot introspect alias properties created at
machine construction.

The deeper code fix to address that is beyond my current scope as a
new contributor. Please disregard this patch — I'd like to withdraw
it. I'll work on a v2 that focuses only on the documentation
improvement Peter suggested — adding a general note about
cross-architecture and cross-machine-type differences near the start
of the introduction text, rather than pflash-specific wording.

I'll send v2 once I've drafted appropriate wording.

Thanks again for the patient guidance.

Best regards,
Linisha


On Wed, Jun 24, 2026 at 2:18 PM Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Wed, 24 Jun 2026 at 08:15, Daniel P. Berrangé <berrange@redhat.com> wrote:
> >
> > On Wed, Jun 24, 2026 at 02:28:39AM +0530, Linisha wrote:
> > > The pflash0 and pflash1 machine options shown in the Aarch64 virt example are only available for virt machine types on Arm, RISC-V, and LoongArch architectures. Add a note to clarify this for users who may try these options on x86 machines and be confused when they are not available.
> > >
> > > Resolves: https://gitlab.com/qemu-project/qemu/-/issues/3254
> > > Signed-off-by: Linisha <linisha232@gmail.com>
> > > ---
> > >  docs/system/introduction.rst | 6 ++++++
> > >  1 file changed, 6 insertions(+)
> > >
> > > diff --git a/docs/system/introduction.rst b/docs/system/introduction.rst
> > > index bec7291e47..0c400aefb6 100644
> > > --- a/docs/system/introduction.rst
> > > +++ b/docs/system/introduction.rst
> > > @@ -158,6 +158,12 @@ virtualisation so we can use KVM inside the emulated guest. As the
> > >  ``virt`` machine comes with some built in pflash devices we give them
> > >  names so we can override the defaults later.
> > >
> > > +.. note::
> > > +   The ``pflash0`` and ``pflash1`` machine options are specific to the
> > > +   ``virt`` machine type on Arm, RISC-V, and LoongArch architectures.
> > > +   They are not available on x86 machines, which use ``-bios`` or
> > > +   ``-pflash`` for firmware instead.
> >
> > No this is wrong.
> >
> > The pflash0 and pflash1 properties apply to x86 pc & q35 machines too.
> >
> > -pflash is a legacy syntax which remaps to pflash0 and pflash1 internally,
> > but also applies to other machines which don't use the new pflash0/pflash1
> > properties.
>
> I think it is probably worth having something in the intro text that
> makes the point that for QEMU all architectures and machines are
> potentially different, and that options and command lines that work
> on for example an x86 PC machine will not necessarily work on
> an Arm machine, and so on. But we should do that as a kind of
> general warning somewhere near the start.
>
> The bug report notes that "./build/x86/qemu-system-x86_64 -M pc,help"
> does not list the pflash0 and pflash1 options. I think this is
> because we set these up as alias properties on the actual flash
> device object in pc_pflash_create(), so they don't exist as class
> properties that "help" can introspect on.
>
> -- PMM

Re: [PATCH] docs/system: clarify pflash0 and pflash1 are virt-only options

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Wed, 24 Jun 2026 at 08:15, Daniel P. Berrangé <berrange@redhat.com> wrote:
>>
>> On Wed, Jun 24, 2026 at 02:28:39AM +0530, Linisha wrote:
>> > The pflash0 and pflash1 machine options shown in the Aarch64 virt
>> > example are only available for virt machine types on Arm, RISC-V,
>> > and LoongArch architectures. Add a note to clarify this for users
>> > who may try these options on x86 machines and be confused when
>> > they are not available.
>> >
>> > Resolves: https://gitlab.com/qemu-project/qemu/-/issues/3254
>> > Signed-off-by: Linisha <linisha232@gmail.com>
>> > ---
>> >  docs/system/introduction.rst | 6 ++++++
>> >  1 file changed, 6 insertions(+)
>> >
>> > diff --git a/docs/system/introduction.rst b/docs/system/introduction.rst
>> > index bec7291e47..0c400aefb6 100644
>> > --- a/docs/system/introduction.rst
>> > +++ b/docs/system/introduction.rst
>> > @@ -158,6 +158,12 @@ virtualisation so we can use KVM inside the emulated guest. As the
>> >  ``virt`` machine comes with some built in pflash devices we give them
>> >  names so we can override the defaults later.
>> >
>> > +.. note::
>> > +   The ``pflash0`` and ``pflash1`` machine options are specific to the
>> > +   ``virt`` machine type on Arm, RISC-V, and LoongArch architectures.
>> > +   They are not available on x86 machines, which use ``-bios`` or
>> > +   ``-pflash`` for firmware instead.
>>
>> No this is wrong.
>>
>> The pflash0 and pflash1 properties apply to x86 pc & q35 machines too.
>>
>> -pflash is a legacy syntax which remaps to pflash0 and pflash1 internally,
>> but also applies to other machines which don't use the new pflash0/pflash1
>> properties.
>
> I think it is probably worth having something in the intro text that
> makes the point that for QEMU all architectures and machines are
> potentially different, and that options and command lines that work
> on for example an x86 PC machine will not necessarily work on
> an Arm machine, and so on. But we should do that as a kind of
> general warning somewhere near the start.

That was the intention with the wording:

  QEMU provides a rich and complex API which can be overwhelming to
  understand. While some architectures can boot something with just a
  disk image, those examples elide a lot of details with defaults that
  may not be optimal for modern systems.

  For a non-x86 system where we emulate a broad range of machine types,
  the command lines are generally more explicit in defining the machine
  and boot behaviour.

but it could probably be improved. Aside from working mostly on Arm I
chose the example because the default PC command lines are very prone to
using the old legacy shortcuts.

>
> The bug report notes that "./build/x86/qemu-system-x86_64 -M pc,help"
> does not list the pflash0 and pflash1 options. I think this is because
> we set these up as alias properties on the actual flash device object
> in pc_pflash_create(), so they don't exist as class properties that
> "help" can introspect on.
>
> -- PMM

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro