From 2ce20ba8397c4f2fbbd6a3b57559b63ef09380a4 Mon Sep 17 00:00:00 2001 From: Michal Privoznik Date: Mon, 7 Sep 2020 15:42:46 +0200 Subject: [PATCH] docs: Discourage users from using fwcfg Even though this was brought up in upstream discussion [1] it missed my patches: users should prefer 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 . 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 Signed-off-by: Michal Privoznik Reviewed-by: Laszlo Ersek --- docs/formatdomain.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 451c85ff73..18e237c157 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -508,19 +508,25 @@ layout of sub-elements, with supported values of: ``fwcfg`` 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 - ``/sys/firmware/qemu_fw_cfg``. Note, that these values apply regardless the - mode under . :since:`Since 6.5.0` + 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 (if the guest kernel has FW_CFG_SYSFS + config option enabled), under ``/sys/firmware/qemu_fw_cfg``. Note, that + these values apply regardless the ```` mode under ````. + :since:`Since 6.5.0` + + **Please note that because of limited number of data slots use of fwcfg is + strongly discouraged and should be used instead**. :: - + example value - - + + - 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 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