docs: Discourage users from using fwcfg

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@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Laszlo Ersek <lersek@redhat.com>
This commit is contained in:
Michal Privoznik 2020-09-07 15:42:46 +02:00
parent 84f911d3ba
commit 2ce20ba839

View File

@ -508,19 +508,25 @@ layout of sub-elements, with supported values of:
``fwcfg`` ``fwcfg``
Some hypervisors provide unified way to tweak how firmware configures itself, 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 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 order, ACPI, SMBIOS, etc.
blobs. In case of QEMU, these then appear under domain's sysfs, under
``/sys/firmware/qemu_fw_cfg``. Note, that these values apply regardless the It even allows users to define their own config blobs. In case of QEMU,
<smbios/> mode under <os/>. :since:`Since 6.5.0` 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**.
:: ::
<smbios type='fwcfg'> <sysinfo type='fwcfg'>
<entry name='opt/com.example/name'>example value</entry> <entry name='opt/com.example/name'>example value</entry>
<entry name='opt/com.coreos/config' file='/tmp/provision.ign'/> <entry name='opt/com.example/config' file='/tmp/provision.ign'/>
</smbios> </sysinfo>
The ``smbios`` element can have multiple ``entry`` child elements. Each The ``sysinfo`` element can have multiple ``entry`` child elements. Each
element then has mandatory ``name`` attribute, which defines the name of the element then has mandatory ``name`` attribute, which defines the name of the
blob and must begin with ``"opt/"`` and to avoid clashing with other names is blob and must begin with ``"opt/"`` and to avoid clashing with other names is
advised to be in form ``"opt/$RFQDN/$name"`` where ``$RFQDN`` is a reverse advised to be in form ``"opt/$RFQDN/$name"`` where ``$RFQDN`` is a reverse