* [PATCH v2] doc: Describe missing generic -blockdev options
@ 2019-10-18 12:02 Kevin Wolf
2019-10-18 12:06 ` Peter Maydell
0 siblings, 1 reply; 2+ messages in thread
From: Kevin Wolf @ 2019-10-18 12:02 UTC (permalink / raw)
To: qemu-block; +Cc: kwolf, peter.maydell, qemu-devel
We added more generic options after introducing -blockdev and forgot to
update the documentation (man page and --help output) accordingly. Do
that now.
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
qemu-options.hx | 22 +++++++++++++++++++++-
1 file changed, 21 insertions(+), 1 deletion(-)
diff --git a/qemu-options.hx b/qemu-options.hx
index 793d70ff93..2e6ba5ef1f 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -849,7 +849,8 @@ ETEXI
DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
"-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
" [,cache.direct=on|off][,cache.no-flush=on|off]\n"
- " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
+ " [,read-only=on|off][,auto-read-only=on|off]\n"
+ " [,force-share=on|off][,detect-zeroes=on|off|unmap]\n"
" [,driver specific parameters...]\n"
" configure a block backend\n", QEMU_ARCH_ALL)
STEXI
@@ -885,6 +886,25 @@ name is not intended to be predictable and changes between QEMU invocations.
For the top level, an explicit node name must be specified.
@item read-only
Open the node read-only. Guest write attempts will fail.
+
+Note that some block drivers support only read-only access, either generally or
+in certain configurations. In this case, the default value
+@option{read-only=off} does not work and the option must be specified
+explicitly.
+@item auto-read-only
+If @option{auto-read-only=on} is set, QEMU may fall back to read-only usage
+even when @option{read-only=off} is requested, or even switch between modes as
+needed, e.g. depending on whether the image file is writable or whether a
+writing user is attached to the node.
+@item force-share
+Override the image locking system of QEMU by forcing the node to utilize
+weaker shared access for permissions where it would normally request exclusive
+access. When there is the potential for multiple instances to have the same
+file open (whether this invocation of qemu is the first or the second
+instance), both instances must permit shared access for the second instance to
+succeed at opening the file.
+
+Enabling @option{force-share=on} requires @option{read-only=on}.
@item cache.direct
The host page cache can be avoided with @option{cache.direct=on}. This will
attempt to do disk IO directly to the guest's memory. QEMU may still perform an
--
2.20.1
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH v2] doc: Describe missing generic -blockdev options
2019-10-18 12:02 [PATCH v2] doc: Describe missing generic -blockdev options Kevin Wolf
@ 2019-10-18 12:06 ` Peter Maydell
0 siblings, 0 replies; 2+ messages in thread
From: Peter Maydell @ 2019-10-18 12:06 UTC (permalink / raw)
To: Kevin Wolf; +Cc: QEMU Developers, Qemu-block
On Fri, 18 Oct 2019 at 13:02, Kevin Wolf <kwolf@redhat.com> wrote:
>
> We added more generic options after introducing -blockdev and forgot to
> update the documentation (man page and --help output) accordingly. Do
> that now.
>
> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> ---
> qemu-options.hx | 22 +++++++++++++++++++++-
> 1 file changed, 21 insertions(+), 1 deletion(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 793d70ff93..2e6ba5ef1f 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -849,7 +849,8 @@ ETEXI
> DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
> "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
> " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
> - " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
> + " [,read-only=on|off][,auto-read-only=on|off]\n"
> + " [,force-share=on|off][,detect-zeroes=on|off|unmap]\n"
> " [,driver specific parameters...]\n"
> " configure a block backend\n", QEMU_ARCH_ALL)
> STEXI
> @@ -885,6 +886,25 @@ name is not intended to be predictable and changes between QEMU invocations.
> For the top level, an explicit node name must be specified.
> @item read-only
> Open the node read-only. Guest write attempts will fail.
> +
> +Note that some block drivers support only read-only access, either generally or
> +in certain configurations. In this case, the default value
> +@option{read-only=off} does not work and the option must be specified
> +explicitly.
> +@item auto-read-only
> +If @option{auto-read-only=on} is set, QEMU may fall back to read-only usage
> +even when @option{read-only=off} is requested, or even switch between modes as
> +needed, e.g. depending on whether the image file is writable or whether a
> +writing user is attached to the node.
> +@item force-share
> +Override the image locking system of QEMU by forcing the node to utilize
> +weaker shared access for permissions where it would normally request exclusive
> +access. When there is the potential for multiple instances to have the same
> +file open (whether this invocation of qemu is the first or the second
"QEMU" should be all-upper-case.
> +instance), both instances must permit shared access for the second instance to
> +succeed at opening the file.
> +
> +Enabling @option{force-share=on} requires @option{read-only=on}.
> @item cache.direct
> The host page cache can be avoided with @option{cache.direct=on}. This will
> attempt to do disk IO directly to the guest's memory. QEMU may still perform an
> --
> 2.20.1
Otherwise
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
thanks
-- PMM
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2019-10-18 12:08 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-10-18 12:02 [PATCH v2] doc: Describe missing generic -blockdev options Kevin Wolf
2019-10-18 12:06 ` Peter Maydell
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).