aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorMarkus Armbruster <armbru@redhat.com>2016-04-18 18:29:50 +0200
committerMarkus Armbruster <armbru@redhat.com>2016-04-19 16:09:50 +0200
commit63d3145aadbecaa7e8be1e74b5d6b5cbbeb4e153 (patch)
tree936d8220a33f29886da1760205636a81a1e95ddc /docs
parentef5d5641f5f35f64a7f150bb3593dae0c08f236d (diff)
fw_cfg: Adopt /opt/RFQDN convention
FW CFG's primary user is QEMU, which uses it to expose configuration information (in the widest sense) to Firmware. Thus the name FW CFG. FW CFG can also be used by others for their own purposes. QEMU is merely acting as transport then. Names starting with opt/ are reserved for such uses. There is no provision, however, to guide safe sharing among different such users. Fix that, loosely following QMP precedence: names should start with opt/RFQDN/, where RFQDN is a reverse fully qualified domain name you control. Based on a more ambitious patch from Michael Tsirkin. Cc: Gerd Hoffmann <kraxel@redhat.com> Cc: Gabriel L. Somlo <somlo@cmu.edu> Cc: Laszlo Ersek <lersek@redhat.com> Cc: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> Acked-by: Gabriel Somlo <somlo@cmu.edu> Reviewed-by: Laszlo Ersek <lersek@redhat.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/specs/fw_cfg.txt36
1 files changed, 17 insertions, 19 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:
+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.
+
+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
+user.
-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.