diff options
authorPeter Maydell <peter.maydell@linaro.org>2016-04-19 15:25:19 +0100
committerPeter Maydell <peter.maydell@linaro.org>2016-04-19 15:25:20 +0100
commitd4dffa4a3f51b10cc0b7e6e34431919cac7a318e (patch)
parentef5d5641f5f35f64a7f150bb3593dae0c08f236d (diff)
parent63d3145aadbecaa7e8be1e74b5d6b5cbbeb4e153 (diff)
Merge remote-tracking branch 'remotes/armbru/tags/pull-fw_cfg-2016-04-19' into staging
fw_cfg: Adopt /opt/RFQDN convention # gpg: Signature made Tue 19 Apr 2016 15:14:20 BST using RSA key ID EB918653 # gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" # gpg: aka "Markus Armbruster <armbru@pond.sub.org>" * remotes/armbru/tags/pull-fw_cfg-2016-04-19: fw_cfg: Adopt /opt/RFQDN convention Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2 files changed, 36 insertions, 24 deletions
diff --git a/docs/specs/fw_cfg.txt b/docs/specs/fw_cfg.txt
index 5414140f33..7a5f8c7824 100644
--- a/docs/specs/fw_cfg.txt
+++ b/docs/specs/fw_cfg.txt
@@ -210,29 +210,27 @@ 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:
-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.
+Using item_name with plain ASCII characters only is recommended.
+Item names beginning with "opt/" are reserved for users. QEMU will
+never create entries with such names unless explicitly ordered by the
-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.
+To avoid clashes among different users, it is strongly recommended
+that you use names beginning with opt/RFQDN/, where RFQDN is a reverse
+fully qualified domain name you control. For instance, if SeaBIOS
+wanted to define additional names, the prefix "opt/org.seabios/" would
+be appropriate.
-NOTE: Users *SHOULD* choose item names beginning with the prefix "opt/"
-when using the "-fw_cfg" command line option, to avoid conflicting with
-item names used internally by QEMU. For instance:
+For historical reasons, "opt/ovmf/" is reserved for OVMF firmware.
- -fw_cfg name=opt/my_item_name,file=./my_blob.bin
+Prefix "opt/org.qemu/" is reserved for QEMU itself.
-Similarly, QEMU developers *SHOULD NOT* use item names prefixed with
-"opt/" when inserting items programmatically, e.g. via fw_cfg_add_file().
+Use of names not beginning with "opt/" is potentially dangerous and
+entirely unsupported. QEMU will warn if you try.
diff --git a/qemu-options.hx b/qemu-options.hx
index 587de8f3cd..6106520c56 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2864,18 +2864,32 @@ 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 contents from file\n"
"-fw_cfg [name=]<name>,string=<str>\n"
- " add named fw_cfg entry from string\n",
+ " add named fw_cfg entry with contents from string\n",
@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 contents 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 contents from string @var{str}.
+The terminating NUL character of the contents of @var{str} will not be
+included as part of the fw_cfg item data. To insert contents with
+embedded NUL characters, you have to use the @var{file} parameter.
+The fw_cfg entries are passed by QEMU through to the guest.
+ -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
+@end example
+creates an fw_cfg entry named opt/com.mycompany/blob with contents
+from ./my_blob.bin.
DEF("serial", HAS_ARG, QEMU_OPTION_serial, \