[for-2.6] fw_cfg: Adopt /opt/RFQDN convention

Commit Message

Markus Armbruster April 18, 2016, 4:42 p.m. UTC

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 reseved
for such uses.  There is no provision, however, to guide safe sharing
among different such users.

Fix that, losely 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 <[e-mail]>
Cc: Gabriel L. Somlo <[e-mail]>
Cc: Laszlo Ersek <[e-mail]>
Cc: Michael S. Tsirkin <[e-mail]>
Signed-off-by: Markus Armbruster <[e-mail]>
---
Michael's patch:
Message-ID: <[e-mail]>
http://lists.nongnu.org/archive/html/qemu-devel/2016-04/msg01381.html

Michael, I'm happy to add your S-o-b if you feel this patch is
derivative of yours despite my extensive changes.  I didn't do it
proactively because I didn't want to misrepresent your opinions on
this matter.

 docs/specs/fw_cfg.txt | 36 +++++++++++++++++-------------------
 qemu-options.hx       | 24 +++++++++++++++++++-----
 2 files changed, 36 insertions(+), 24 deletions(-)

Comments

Michael S. Tsirkin April 18, 2016, 4:49 p.m. UTC | #1

On Mon, Apr 18, 2016 at 06:42:09PM +0200, Markus Armbruster wrote:
> 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 reseved
> for such uses.  There is no provision, however, to guide safe sharing
> among different such users.
> 
> Fix that, losely 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 <[e-mail]>
> Cc: Gabriel L. Somlo <[e-mail]>
> Cc: Laszlo Ersek <[e-mail]>
> Cc: Michael S. Tsirkin <[e-mail]>
> Signed-off-by: Markus Armbruster <[e-mail]>

Reviewed-by: Michael S. Tsirkin <[e-mail]>
Signed-off-by: Michael S. Tsirkin <[e-mail]>

I don't think there's any rush to get this into 2.6, though.
If no one beats me to it, I'll apply this after 2.6 is out.

> ---
> Michael's patch:
> Message-ID: <[e-mail]>
> http://lists.nongnu.org/archive/html/qemu-devel/2016-04/msg01381.html
> 
> Michael, I'm happy to add your S-o-b if you feel this patch is
> derivative of yours despite my extensive changes.  I didn't do it
> proactively because I didn't want to misrepresent your opinions on
> this matter.
> 
>  docs/specs/fw_cfg.txt | 36 +++++++++++++++++-------------------
>  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 5414140..90e74bb 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.
>  
> -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/"
> -when using the "-fw_cfg" command line option, to avoid conflicting with
> -item names used internally by QEMU. For instance:
> +Item names beginning with "opt/" are reserved for users.  QEMU will
> +never create entries with such names unless explicitly ordered by the
> +user.
>  
> -    -fw_cfg name=opt/my_item_name,file=./my_blob.bin
> +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, prefix "opt/org.seabios/"
> +would be appropriate.
>  
> -Similarly, QEMU developers *SHOULD 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 OVMF firmware.
> +
> +Prefix "opt/org.qemu/" is reserved for QEMU itself.
> +
> +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 587de8f..6106520 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, \
> -- 
> 2.5.5

Eric Blake April 18, 2016, 6:58 p.m. UTC | #2

On 04/18/2016 10:42 AM, Markus Armbruster wrote:
> 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 reseved

s/reseved/reserved/

> for such uses.  There is no provision, however, to guide safe sharing
> among different such users.
> 
> Fix that, losely following QMP precedence: names should start with

s/losely/loosely/

> 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 <[e-mail]>
> Cc: Gabriel L. Somlo <[e-mail]>
> Cc: Laszlo Ersek <[e-mail]>
> Cc: Michael S. Tsirkin <[e-mail]>
> Signed-off-by: Markus Armbruster <[e-mail]>
> ---

Markus Armbruster April 19, 2016, 7:48 a.m. UTC | #3

"Michael S. Tsirkin" <[e-mail]> writes:

> On Mon, Apr 18, 2016 at 06:42:09PM +0200, Markus Armbruster wrote:
>> 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 reseved
>> for such uses.  There is no provision, however, to guide safe sharing
>> among different such users.
>> 
>> Fix that, losely 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 <[e-mail]>
>> Cc: Gabriel L. Somlo <[e-mail]>
>> Cc: Laszlo Ersek <[e-mail]>
>> Cc: Michael S. Tsirkin <[e-mail]>
>> Signed-off-by: Markus Armbruster <[e-mail]>
>
> Reviewed-by: Michael S. Tsirkin <[e-mail]>
> Signed-off-by: Michael S. Tsirkin <[e-mail]>
>
> I don't think there's any rush to get this into 2.6, though.
> If no one beats me to it, I'll apply this after 2.6 is out.

The patch touches only documentation and help text, i.e. it's as safe as
it gets.  I'd like to have it in 2.6.

Since both of the two patched files have no maintainer, I intend to post
a pull request myself, assuming nobody objects.

Markus Armbruster April 19, 2016, 8:30 a.m. UTC | #4

Eric Blake <[e-mail]> writes:

> On 04/18/2016 10:42 AM, Markus Armbruster wrote:
>> 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 reseved
>
> s/reseved/reserved/
>
>> for such uses.  There is no provision, however, to guide safe sharing
>> among different such users.
>> 
>> Fix that, losely following QMP precedence: names should start with
>
> s/losely/loosely/

Fixed both.  Thanks!

>> 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 <[e-mail]>
>> Cc: Gabriel L. Somlo <[e-mail]>
>> Cc: Laszlo Ersek <[e-mail]>
>> Cc: Michael S. Tsirkin <[e-mail]>
>> Signed-off-by: Markus Armbruster <[e-mail]>
>> ---

Gabriel L. Somlo April 19, 2016, 1:04 p.m. UTC | #5

On Tue, Apr 19, 2016 at 09:48:40AM +0200, Markus Armbruster wrote:
> "Michael S. Tsirkin" <[e-mail]> writes:
> 
> > On Mon, Apr 18, 2016 at 06:42:09PM +0200, Markus Armbruster wrote:
> >> 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 reseved
> >> for such uses.  There is no provision, however, to guide safe sharing
> >> among different such users.
> >> 
> >> Fix that, losely 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 <[e-mail]>
> >> Cc: Gabriel L. Somlo <[e-mail]>
> >> Cc: Laszlo Ersek <[e-mail]>
> >> Cc: Michael S. Tsirkin <[e-mail]>
> >> Signed-off-by: Markus Armbruster <[e-mail]>
> >
> > Reviewed-by: Michael S. Tsirkin <[e-mail]>
> > Signed-off-by: Michael S. Tsirkin <[e-mail]>
> >
> > I don't think there's any rush to get this into 2.6, though.
> > If no one beats me to it, I'll apply this after 2.6 is out.
> 
> The patch touches only documentation and help text, i.e. it's as safe as
> it gets.  I'd like to have it in 2.6.
> 
> Since both of the two patched files have no maintainer, I intend to post
> a pull request myself, assuming nobody objects.

Acked-by: Gabriel Somlo <[e-mail]>

Thanks much!
--Gabriel

Laszlo Ersek April 19, 2016, 1:08 p.m. UTC | #6

On 04/18/16 18:42, Markus Armbruster wrote:

> +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, prefix "opt/org.seabios/"

s,prefix "opt/org.seabios/",the prefix "opt/org.seabios/",?

(I.e., I believe I would prepend a definite article to the word
"prefix". The current text feels right as well, but with an extra "the"
it feels right-er to me.)

Either way:
Reviewed-by: Laszlo Ersek <[e-mail]>

Thanks
Laszlo

Patch

diff --git a/docs/specs/fw_cfg.txt b/docs/specs/fw_cfg.txt
index 5414140..90e74bb 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.
 
-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/"
-when using the "-fw_cfg" command line option, to avoid conflicting with
-item names used internally by QEMU. For instance:
+Item names beginning with "opt/" are reserved for users.  QEMU will
+never create entries with such names unless explicitly ordered by the
+user.
 
-    -fw_cfg name=opt/my_item_name,file=./my_blob.bin
+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, prefix "opt/org.seabios/"
+would be appropriate.
 
-Similarly, QEMU developers *SHOULD 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 OVMF firmware.
+
+Prefix "opt/org.qemu/" is reserved for QEMU itself.
+
+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 587de8f..6106520 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, \