diff options
| -rw-r--r-- | docs/specs/fw_cfg.txt | 36 | ||||
| -rw-r--r-- | qemu-options.hx | 24 |
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: +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. 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", 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 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. + +Example: +@example + -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. + ETEXI DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ |