Re: [Qemu-devel] [PATCH for-2.6] fw_cfg: Adopt /opt/RFQDN convention

[Michael S. Tsirkin]

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 <address@hidden>
> Cc: Gabriel L. Somlo <address@hidden>
> Cc: Laszlo Ersek <address@hidden>
> Cc: Michael S. Tsirkin <address@hidden>
> Signed-off-by: Markus Armbruster <address@hidden>

Reviewed-by: Michael S. Tsirkin <address@hidden>
Signed-off-by: Michael S. Tsirkin <address@hidden>

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: <address@hidden>
> 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 address@hidden,address@hidden
>  @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 address@hidden,address@hidden
> -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:
> address@hidden
> +    -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
> address@hidden 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