[PATCH] qemu-options: Clarify handling of commas in options parameters

[PATCH] qemu-options: Clarify handling of commas in options parameters

[Yihuan Pan]

Provide explicit guidance on dealing with option parameters as arbitrary
strings containing commas, such as in "file=my,file" and "string=a,b". The
updated documentation emphasizes the need to double commas when they
appear within such parameters.

Resolves: https://gitlab.com/qemu-project/qemu/-/issues/1839
Signed-off-by: Yihuan Pan <xun794@gmail.com>
---
 docs/system/invocation.rst   | 5 +++++
 docs/system/qemu-manpage.rst | 5 +++++
 qemu-options.hx              | 4 ++++
 3 files changed, 14 insertions(+)

Changes since the previous version:
- Added a generic comment about doubling the commas to the
  documentation.

diff --git a/docs/system/invocation.rst b/docs/system/invocation.rst
index 4ba38fc23d..14b7db1c10 100644
--- a/docs/system/invocation.rst
+++ b/docs/system/invocation.rst
@@ -10,6 +10,11 @@ Invocation
 disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
 not need a disk image.
 
+When dealing with options parameters as arbitrary strings containing
+commas, such as in "file=my,file" and "string=a,b", it's necessary to
+double the commas. For instance,"-fw_cfg name=z,string=a,,b" will be
+parsed as "-fw_cfg name=z,string=a,b".
+
 .. hxtool-doc:: qemu-options.hx
 
 Device URL Syntax
diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst
index c47a412758..3ade4ee45b 100644
--- a/docs/system/qemu-manpage.rst
+++ b/docs/system/qemu-manpage.rst
@@ -31,6 +31,11 @@ Options
 disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
 not need a disk image.
 
+When dealing with options parameters as arbitrary strings containing
+commas, such as in "file=my,file" and "string=a,b", it's necessary to
+double the commas. For instance,"-fw_cfg name=z,string=a,,b" will be
+parsed as "-fw_cfg name=z,string=a,b".
+
 .. hxtool-doc:: qemu-options.hx
 
 .. include:: keys.rst.inc
diff --git a/qemu-options.hx b/qemu-options.hx
index 42fd09e4de..a935aaae44 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -4086,9 +4086,13 @@ DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
 SRST
 ``-fw_cfg [name=]name,file=file``
     Add named fw\_cfg entry with contents from file file.
+    If the filename contains comma, you must double it (for instance,
+    "file=my,,file" to use file "my,file").
 
 ``-fw_cfg [name=]name,string=str``
     Add named fw\_cfg entry with contents from string str.
+    If the string contains comma, you must double it (for instance,
+    "string=my,,string" to use file "my,string").
 
     The terminating NUL character of the contents of str will not be
     included as part of the fw\_cfg item data. To insert contents with
-- 
2.43.0

Re: [PATCH] qemu-options: Clarify handling of commas in options parameters

[Thomas Huth]

On 13/12/2023 15.17, Yihuan Pan wrote:
> Provide explicit guidance on dealing with option parameters as arbitrary
> strings containing commas, such as in "file=my,file" and "string=a,b". The
> updated documentation emphasizes the need to double commas when they
> appear within such parameters.
> 
> Resolves: https://gitlab.com/qemu-project/qemu/-/issues/1839
> Signed-off-by: Yihuan Pan <xun794@gmail.com>
> ---
>   docs/system/invocation.rst   | 5 +++++
>   docs/system/qemu-manpage.rst | 5 +++++
>   qemu-options.hx              | 4 ++++
>   3 files changed, 14 insertions(+)
> 
> Changes since the previous version:
> - Added a generic comment about doubling the commas to the
>    documentation.
> 
> diff --git a/docs/system/invocation.rst b/docs/system/invocation.rst
> index 4ba38fc23d..14b7db1c10 100644
> --- a/docs/system/invocation.rst
> +++ b/docs/system/invocation.rst
> @@ -10,6 +10,11 @@ Invocation
>   disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
>   not need a disk image.
>   
> +When dealing with options parameters as arbitrary strings containing
> +commas, such as in "file=my,file" and "string=a,b", it's necessary to
> +double the commas. For instance,"-fw_cfg name=z,string=a,,b" will be
> +parsed as "-fw_cfg name=z,string=a,b".
> +
>   .. hxtool-doc:: qemu-options.hx
>   
>   Device URL Syntax
> diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst
> index c47a412758..3ade4ee45b 100644
> --- a/docs/system/qemu-manpage.rst
> +++ b/docs/system/qemu-manpage.rst
> @@ -31,6 +31,11 @@ Options
>   disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
>   not need a disk image.
>   
> +When dealing with options parameters as arbitrary strings containing
> +commas, such as in "file=my,file" and "string=a,b", it's necessary to
> +double the commas. For instance,"-fw_cfg name=z,string=a,,b" will be
> +parsed as "-fw_cfg name=z,string=a,b".
> +
>   .. hxtool-doc:: qemu-options.hx
>   
>   .. include:: keys.rst.inc
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 42fd09e4de..a935aaae44 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -4086,9 +4086,13 @@ DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
>   SRST
>   ``-fw_cfg [name=]name,file=file``
>       Add named fw\_cfg entry with contents from file file.
> +    If the filename contains comma, you must double it (for instance,
> +    "file=my,,file" to use file "my,file").
>   
>   ``-fw_cfg [name=]name,string=str``
>       Add named fw\_cfg entry with contents from string str.
> +    If the string contains comma, you must double it (for instance,
> +    "string=my,,string" to use file "my,string").
>   
>       The terminating NUL character of the contents of str will not be
>       included as part of the fw\_cfg item data. To insert contents with

Looks fine to me, thanks!

Reviewed-by: Thomas Huth <thuth@redhat.com>

If nobody objects, I can queue it for my next pull request.

  Thomas