[PATCH] docs: Discourage users from using fwcfg

[Daniel P. Berrangé]

On Tue, Sep 08, 2020 at 11:02:10AM +0200, Laszlo Ersek wrote:
> On 09/07/20 15:48, Michal Privoznik wrote:
> > Even though this was brought up in upstream discussion [1] it
> > missed my patches: users should prefer <oemStrings/> over fwcfg.
> > The reason is that fwcfg is considered somewhat internal to QEMU
> > and it has limited number of slots and neither of these applies
> > to <oemStrings/>.
> >
> > While I'm at it, I'm fixing the example too (because it contains
> > incorrect element name) and clarifying sysfs/ exposure.
> >
> > 1: https://www.redhat.com/archives/libvir-list/2020-May/msg00957.html
> >
> > Reported-by: Laszlo Ersek <lersek at redhat.com>
> > Signed-off-by: Michal Privoznik <mprivozn at redhat.com>
> > ---
> >  docs/formatdomain.rst | 14 +++++++++-----
> >  1 file changed, 9 insertions(+), 5 deletions(-)
> >
> > diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> > index 1979dfb8d3..821ffe8d60 100644
> > --- a/docs/formatdomain.rst
> > +++ b/docs/formatdomain.rst
> > @@ -509,18 +509,22 @@ layout of sub-elements, with supported values of:
> >     Some hypervisors provide unified way to tweak how firmware configures itself,
> >     or may contain tables to be installed for the guest OS, for instance boot
> >     order, ACPI, SMBIOS, etc. It even allows users to define their own config
> > -   blobs. In case of QEMU, these then appear under domain's sysfs, under
> > +   blobs. In case of QEMU, these then appear under domain's sysfs (if the guest
> > +   kernel has FW_CFG_SYSFS config option enabled), under
> >     ``/sys/firmware/qemu_fw_cfg``. Note, that these values apply regardless the
> >     <smbios/> mode under <os/>. :since:`Since 6.5.0`
> >
> > +   **Please note that because of limited number of data slots use of fwcfg is
> > +   strongly discouraged and <oemStrings/> should be used instead**.
> 
> please replace:
> 
>   strongly discouraged
> 
> with:
> 
>   strongly discouraged for configuring any guest-side component other
>   than the firmware
> 
> (
> 
> Consider for example the following feature:
> 
>   https://bugzilla.tianocore.org/show_bug.cgi?id=2681
> 
> Namely, the following QEMU switches:
> 
>   -fw_cfg name=opt/org.tianocore/IPv4PXESupport,string=[yn]
>   -fw_cfg name=opt/org.tianocore/IPv6PXESupport,string=[yn]
> 
> alter the behavior of OVMF and ArmVirtQemu. These flags are meant to be
> stable. They do not need dedicated QEMU or libvirtd enablement. They
> influence firmware behavior. So <sysinfo type='fwcfg'> is perfectly fine
> (even ideal!) for tweaking them, through the domain XML. What's not fine
> is configuring any random guest payload via <sysinfo type='fwcfg'>.
> 
> The point is that people who parse new fw_cfg files in edk2 such as
> "opt/org.tianocore/IPv6PXESupport" are conscious of the slot count in
> QEMU. They *can* bump the "x-file-slots" property in QEMU, for new
> machine types, they just need to be aware of the property.

I'd suggest that QEMU always sets x-file-slots to be 10 entries larger
than the number of officially known slots. That leads some scope for
app usage without risk of hitting the limits.


> > -          <entry name='opt/com.coreos/config' file='/tmp/provision.ign'/>
> > -        </smbios>
> > +          <entry name='opt/com.example/config' file='/tmp/provision.ign'/>
> 
> We have a functional -- working, stable -- example for name+file as
> well:
> 
> - name: etc/edk2/https/cacerts
> - file: /etc/pki/ca-trust/extracted/edk2/cacerts.bin

I don't think we should document that in libvirt, since it is something
libvirt will set silently behind the scenes. The ignition example is a
acceptable real world example of expected usage in libvirt.


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|