This requires that all -fw_cfg command line users use names of the form
opt/RQFN/: such names are compatible with QEMU 2.4 and 2.5 as well as
future QEMU versions.
As ability to insert fw_cfg entries in QEMU root is useful for
firmware development, add a special prefix: unsupported/root/ that
allows that, while making sure users are aware it's unsupported.
Cc: Gerd Hoffmann <kra...@redhat.com>
Cc: Gabriel L. Somlo <so...@cmu.edu>
Cc: Laszlo Ersek <ler...@redhat.com>
Cc: Markus Armbruster <arm...@redhat.com>
Signed-off-by: Michael S. Tsirkin <m...@redhat.com>
---
This summarizes the discussions we had on list.
vl.c | 40 ++++++++++++++++++++++++++++++++++++----
docs/specs/fw_cfg.txt | 34 +++++++++++++++++-----------------
qemu-options.hx | 38 +++++++++++++++++++++++++++++++++-----
3 files changed, 86 insertions(+), 26 deletions(-)
diff --git a/vl.c b/vl.c
index 2200e62..af9c9d6 100644
--- a/vl.c
+++ b/vl.c
@@ -2296,8 +2296,10 @@ static int parse_fw_cfg(void *opaque, QemuOpts *opts,
Error **errp)
{
gchar *buf;
size_t size;
- const char *name, *file, *str;
+ const char *name, *file, *str, *slash, *dot;
FWCfgState *fw_cfg = (FWCfgState *) opaque;
+ const char qemu_prefix[] = "opt/org.qemu";
+ const char unsupported_root_prefix[] = "unsupported/root/";
if (fw_cfg == NULL) {
error_report("fw_cfg device not available");
@@ -2320,9 +2322,39 @@ static int parse_fw_cfg(void *opaque, QemuOpts *opts,
Error **errp)
error_report("name too long (max. %d char)", FW_CFG_MAX_FILE_PATH - 1);
return -1;
}
- if (strncmp(name, "opt/", 4) != 0) {
- error_report("warning: externally provided fw_cfg item names "
- "should be prefixed with \"opt/\"");
+ /*
+ * Look for and strip unsupported_root_prefix, which is useful for firmware
+ * development, but warn users.
+ */
+ if (!strncmp(name, unsupported_root_prefix,
strlen(unsupported_root_prefix))) {
+ error_report("warning: removing prefix \"%s\". "
+ "Guest or QEMU may crash. "
+ "Names must be prefixed with \"opt/RQFN/\"",
+ unsupported_root_prefix);
+ name += strlen(unsupported_root_prefix);
+ if (!(nonempty_str(name))) {
+ error_report("invalid argument(s)");
+ return -1;
+ }
+ } else {
+ /*
+ * Don't attempt to validate a valid RQFN in name, as that's not easy:
+ * we do validate that it includes '.' .
+ */
+ if (strncmp(name, "opt/", 4) ||
+ !((dot = strchr(name + 4, '.'))) ||
+ !((slash = strchr(name + 4, '/'))) ||
+ dot > slash) {
+ error_report("error: externally provided fw_cfg item names "
+ "must be prefixed with \"opt/RQFN/\"");
+ return -1;
+ }
+ if (!strncmp(name, qemu_prefix, strlen(qemu_prefix))) {
+ error_report("error: externally provided fw_cfg item names "
+ "must not use the reserved prefix \"%s\"",
+ qemu_prefix);
+ return -1;
+ }
}
if (nonempty_str(str)) {
size = strlen(str); /* NUL terminator NOT included in fw_cfg blob */
diff --git a/docs/specs/fw_cfg.txt b/docs/specs/fw_cfg.txt
index 5414140..83b5e80 100644
--- a/docs/specs/fw_cfg.txt
+++ b/docs/specs/fw_cfg.txt
@@ -210,29 +210,29 @@ the following syntax:
-fw_cfg [name=]<item_name>,file=<path>
-where <item_name> is the fw_cfg item name, and <path> is the location
-on the host file system of a file containing the data to be inserted.
-
-Small enough items may be provided directly as strings on the command
-line, using the syntax:
+Or
-fw_cfg [name=]<item_name>,string=<string>
-The terminating NUL character of the content <string> will NOT be
-included as part of the fw_cfg item data, which is consistent with
-the absence of a NUL terminator for items inserted via the file option.
+See QEMU man page for more documentation.
-Both <item_name> and, if applicable, the content <string> are passed
-through by QEMU without any interpretation, expansion, or further
-processing. Any such processing (potentially performed e.g., by the shell)
-is outside of QEMU's responsibility; as such, using plain ASCII characters
-is recommended.
+Using item_name with plain ASCII characters only is recommended.
-NOTE: Users *SHOULD* choose item names beginning with the prefix "opt/"
+Users MUST choose item names beginning with the prefix "opt/RQFN/"
when using the "-fw_cfg" command line option, to avoid conflicting with
-item names used internally by QEMU. For instance:
+item names used internally by QEMU, or by firmware. For instance:
- -fw_cfg name=opt/my_item_name,file=./my_blob.bin
+ -fw_cfg name=opt/com.my_company/guestagent/guestblob,file=./my_blob.bin
-Similarly, QEMU developers *SHOULD NOT* use item names prefixed with
+Similarly, QEMU developers MUST NOT use item names prefixed with
"opt/" when inserting items programmatically, e.g. via fw_cfg_add_file().
+
+For historical reasons "opt/ovmf/" is reserved for use with the OVMF firmware.
+
+To simplify guest firmware development, the prefix
+unsupported/root/ is automatically stripped from paths, which
+allows creating fw_cfg files in the root QEMU directory. This interface is
+strictly for use by developers, its use can cause guest or QEMU crashes, is
+unsupported and can be removed at any point.
+
+Any use of the prefix "opt/org.qemu/" is reserved for future use.
diff --git a/qemu-options.hx b/qemu-options.hx
index a770086..1af28ac 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2860,18 +2860,46 @@ ETEXI
DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
"-fw_cfg [name=]<name>,file=<file>\n"
- " add named fw_cfg entry from file\n"
+ " add named fw_cfg entry with content from file\n"
"-fw_cfg [name=]<name>,string=<str>\n"
- " add named fw_cfg entry from string\n",
+ " add named fw_cfg entry with content from string\n",
QEMU_ARCH_ALL)
STEXI
+
@item -fw_cfg [name=]@var{name},file=@var{file}
@findex -fw_cfg
-Add named fw_cfg entry from file. @var{name} determines the name of
-the entry in the fw_cfg file directory exposed to the guest.
+Add named fw_cfg entry with content from file @var{file}.
@item -fw_cfg [name=]@var{name},string=@var{str}
-Add named fw_cfg entry from string.
+Add named fw_cfg entry with content from string @var{str}, up to the first NUL
character.
+
+The terminating NUL character of the content @var{str} will NOT be
+included as part of the fw_cfg item data. To insert content including
+the NUL character, store it in file and insert the item via
+the @var{file} option.
+
+Both the name and the content are passed by QEMU through to the guest, where:
+@table @option
+@item @var{name} determines the name of the entry in the fw_cfg file directory
exposed to the guest.
+
+@var{name} must be in the format opt/RQFN/<item_name>.
+
+Any processing of @var{name} values (potentially performed e.g., by the shell)
+is outside of QEMU's responsibility; as such, using plain ASCII characters is
+recommended.
+@end table
+
+Example:
+@example
+ -fw_cfg opt/com.mycompany/guestagent/guestblob,file=./my_blob.bin
+@end example
+
+To simplify guest firmware development, the prefix
+unsupported/root/ is automatically stripped from paths, which
+allows creating fw_cfg files in the root QEMU directory. This interface is
+strictly for use by developers, its use can cause Guest or QEMU crashes, is
+unsupported and can be removed at any point.
+
ETEXI
DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
--
MST
