qapi/ui: correct typos

Correct typos automatically found with the `typos` tool
<https://crates.io/crates/typos>

Signed-off-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
Reviewed-by: Mark

qapi/ui: correct typos

Correct typos automatically found with the `typos` tool
<https://crates.io/crates/typos>

Signed-off-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Michael Tokarev <mjt@tls.msk.ru>
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>

show more ...

qapi/char: Deprecate backend type "memory"

It's an alias for "ringbuf" we kept for backward compatibility; see
commit 3a1da42eb35 (qapi: Rename ChardevBackend member "memory" to
"ringbuf"). Depreca

qapi/char: Deprecate backend type "memory"

It's an alias for "ringbuf" we kept for backward compatibility; see
commit 3a1da42eb35 (qapi: Rename ChardevBackend member "memory" to
"ringbuf"). Deprecation is long overdue.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240203080228.2766159-5-armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

show more ...

qapi/char: Make backend types properly conditional

Character backends are actually QOM types. When a backend's
compile-time conditional QOM type is not compiled in, creation fails
with "'FOO' is no

qapi/char: Make backend types properly conditional

Character backends are actually QOM types. When a backend's
compile-time conditional QOM type is not compiled in, creation fails
with "'FOO' is not a valid char driver name". Okay, except
introspecting chardev-add with query-qmp-schema doesn't work then: the
backend type is there even though the QOM type isn't.

A management application can work around this issue by using
qom-list-types instead.

Fix the issue anyway: add the conditionals to the QAPI schema.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240203080228.2766159-4-armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

show more ...

qapi/migration: Add missing tls-authz documentation

As reported in Markus's recent enforcement series on qapi doc [1], we
accidentally miss one entry for tls-authz. Add it.

[1] https://lore.kernel

qapi/migration: Add missing tls-authz documentation

As reported in Markus's recent enforcement series on qapi doc [1], we
accidentally miss one entry for tls-authz. Add it.

[1] https://lore.kernel.org/r/20240205074709.3613229-1-armbru@redhat.com

Cc: Daniel P. Berrangé <berrange@redhat.com>
Cc: Fabiano Rosas <farosas@suse.de>
Reported-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
Message-ID: <20240207032836.268183-1-peterx@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Update of qapi/pragma.json squashed in, commit message adjusted]

show more ...

qapi: Add missing union tag documentation

Low-hanging fruit, and except for StatsFilter, the only members of
these unions lacking documentation.

Signed-off-by: Markus Armbruster <armbru@redhat.com>

qapi: Add missing union tag documentation

Low-hanging fruit, and except for StatsFilter, the only members of
these unions lacking documentation.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-16-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Move @String out of common.json to discourage reuse

Use of String is problematic, because it results in awkward interface
documentation. The previous commit cleaned up one instance.

Move Str

qapi: Move @String out of common.json to discourage reuse

Use of String is problematic, because it results in awkward interface
documentation. The previous commit cleaned up one instance.

Move String out of common.json next to its remaining users in net.json
to discourage reuse elsewhere.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-15-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Improve documentation of file descriptor socket addresses

SocketAddress branch @fd is documented in enum SocketAddressType,
unlike the other branches. That's because the branch's type is Stri

qapi: Improve documentation of file descriptor socket addresses

SocketAddress branch @fd is documented in enum SocketAddressType,
unlike the other branches. That's because the branch's type is String
from common.json.

Use a local copy of String, so we can put the documentation in the
usual place.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-14-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Plug trivial documentation holes around former simple unions

The conversion of simple to flat unions left the @data members
undocumented. Add documentation where it's trivial. Copy verbatim

qapi: Plug trivial documentation holes around former simple unions

The conversion of simple to flat unions left the @data members
undocumented. Add documentation where it's trivial. Copy verbatim
from the wrapped type's description where possible.

Leftovers: String (to be taken care of in the next commit), and
TransActionAction (left for another day).

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-13-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi/dump: Clean up documentation of DumpGuestMemoryCapability

The type's doc comment describes its member, but it's not marked up as
such. Easy enough to fix.

Signed-off-by: Markus Armbruster <ar

qapi/dump: Clean up documentation of DumpGuestMemoryCapability

The type's doc comment describes its member, but it's not marked up as
such. Easy enough to fix.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-12-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi/yank: Clean up documentaion of yank

The command's doc comment describes the argument, but it's not marked
up as such. Easy enough to fix.

Signed-off-by: Markus Armbruster <armbru@redhat.com>

qapi/yank: Clean up documentaion of yank

The command's doc comment describes the argument, but it's not marked
up as such. Easy enough to fix.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-11-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Require member documentation (with loophole)

The QAPI generator forces you to document your stuff. Except for
command arguments, event data, and members of enum and object types:
these the ge

qapi: Require member documentation (with loophole)

The QAPI generator forces you to document your stuff. Except for
command arguments, event data, and members of enum and object types:
these the generator silently "documents" as "Not documented".

We can't require proper documentation there without first fixing all
the offenders. We've always had too many offenders to pull that off.
Right now, we have more than 500. Worse, we seem to fix old ones no
faster than we add new ones: in the past year, we fixed 22 ones, but
added 26 new ones.

To help arrest the backsliding, make missing documentation an error
unless the command, type, or event is in listed in new pragma
documentation-exceptions.

List all the current offenders: 117 commands and types in qapi/, and 9
in qga/.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-7-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Indent tagged doc comment sections properly

docs/devel/qapi-code-gen demands that the "second and subsequent lines
of sections other than "Example"/"Examples" should be indented".
Commit a937b

qapi: Indent tagged doc comment sections properly

docs/devel/qapi-code-gen demands that the "second and subsequent lines
of sections other than "Example"/"Examples" should be indented".
Commit a937b6aa739q (qapi: Reformat doc comments to conform to current
conventions) missed a few instances, and messed up a few others.
Clean that up.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-5-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi/block-core: Fix BlockLatencyHistogramInfo doc markup

The description of @bins ends with a literal block:

# @bins: list of io request counts corresponding to histogram
# intervals,

qapi/block-core: Fix BlockLatencyHistogramInfo doc markup

The description of @bins ends with a literal block:

# @bins: list of io request counts corresponding to histogram
# intervals, one more element than @boundaries has. For the
# example above, @bins may be something like [3, 1, 5, 2], and
# corresponding histogram looks like:
#
# ::
#
# 5| *

Except it actually ends *before* the block: the unindented '::' line
starts a new section. Makes no sense.

We could fix this by indenting the '::' line. Instead, double the
colon at the end of the preceding paragraph, and drop the '::' line.

This shifts the box for the literal block right in generated
documentation, so it lines up with the description.

Fixes: commit a0fcff383b34 (qapi: Use rST markup for literal blocks)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-4-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

crypto: Introduce 'detached-header' field in QCryptoBlockInfoLUKS

When querying the LUKS disk with the qemu-img tool or other APIs,
add information about whether the LUKS header is detached.

Additi

crypto: Introduce 'detached-header' field in QCryptoBlockInfoLUKS

When querying the LUKS disk with the qemu-img tool or other APIs,
add information about whether the LUKS header is detached.

Additionally, update the test case with the appropriate
modification.

Signed-off-by: Hyman Huang <yong.huang@smartx.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

block: Support detached LUKS header creation using qemu-img

Even though a LUKS header might be created with cryptsetup,
qemu-img should be enhanced to accommodate it as well.

Add the 'detached-head

block: Support detached LUKS header creation using qemu-img

Even though a LUKS header might be created with cryptsetup,
qemu-img should be enhanced to accommodate it as well.

Add the 'detached-header' option to specify the creation of
a detached LUKS header. This is how it is used:
$ qemu-img create --object secret,id=sec0,data=abc123 -f luks
> -o cipher-alg=aes-256,cipher-mode=xts -o key-secret=sec0
> -o detached-header=true header.luks

Using qemu-img or cryptsetup tools to query information of
an LUKS header image as follows:

Assume a detached LUKS header image has been created by:
$ dd if=/dev/zero of=test-header.img bs=1M count=32
$ dd if=/dev/zero of=test-payload.img bs=1M count=1000
$ cryptsetup luksFormat --header test-header.img test-payload.img
> --force-password --type luks1

Header image information could be queried using cryptsetup:
$ cryptsetup luksDump test-header.img

or qemu-img:
$ qemu-img info 'json:{"driver":"luks","file":{"filename":
> "test-payload.img"},"header":{"filename":"test-header.img"}}'

When using qemu-img, keep in mind that the entire disk
information specified by the JSON-format string above must be
supplied on the commandline; if not, an overlay check will reveal
a problem with the LUKS volume check logic.

Signed-off-by: Hyman Huang <yong.huang@smartx.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
[changed to pass 'cflags' to block_crypto_co_create_generic]
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

block: Support detached LUKS header creation using blockdev-create

Firstly, enable the ability to choose the block device containing
a detachable LUKS header by adding the 'header' parameter to
Bloc

block: Support detached LUKS header creation using blockdev-create

Firstly, enable the ability to choose the block device containing
a detachable LUKS header by adding the 'header' parameter to
BlockdevCreateOptionsLUKS.

Secondly, when formatting the LUKS volume with a detachable header,
truncate the payload volume to length without a header size.

Using the qmp blockdev command, create the LUKS volume with a
detachable header as follows:

1. add the secret to lock/unlock the cipher stored in the
detached LUKS header
$ virsh qemu-monitor-command vm '{"execute":"object-add",
> "arguments":{"qom-type": "secret", "id": "sec0", "data": "foo"}}'

2. create a header img with 0 size
$ virsh qemu-monitor-command vm '{"execute":"blockdev-create",
> "arguments":{"job-id":"job0", "options":{"driver":"file",
> "filename":"/path/to/detached_luks_header.img", "size":0 }}}'

3. add protocol blockdev node for header
$ virsh qemu-monitor-command vm '{"execute":"blockdev-add",
> "arguments": {"driver":"file", "filename":
> "/path/to/detached_luks_header.img", "node-name":
> "detached-luks-header-storage"}}'

4. create a payload img with 0 size
$ virsh qemu-monitor-command vm '{"execute":"blockdev-create",
> "arguments":{"job-id":"job1", "options":{"driver":"file",
> "filename":"/path/to/detached_luks_payload_raw.img", "size":0}}}'

5. add protocol blockdev node for payload
$ virsh qemu-monitor-command vm '{"execute":"blockdev-add",
> "arguments": {"driver":"file", "filename":
> "/path/to/detached_luks_payload_raw.img", "node-name":
> "luks-payload-raw-storage"}}'

6. do the formatting with 128M size
$ virsh qemu-monitor-command c81_node1 '{"execute":"blockdev-create",
> "arguments":{"job-id":"job2", "options":{"driver":"luks", "header":
> "detached-luks-header-storage", "file":"luks-payload-raw-storage",
> "size":134217728, "preallocation":"full", "key-secret":"sec0" }}}'

Signed-off-by: Hyman Huang <yong.huang@smartx.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Make parameter 'file' optional for BlockdevCreateOptionsLUKS

To support detached LUKS header creation, make the existing 'file'
field in BlockdevCreateOptionsLUKS optional.

Signed-off-by: Hym

qapi: Make parameter 'file' optional for BlockdevCreateOptionsLUKS

To support detached LUKS header creation, make the existing 'file'
field in BlockdevCreateOptionsLUKS optional.

Signed-off-by: Hyman Huang <yong.huang@smartx.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

crypto: Support LUKS volume with detached header

By enhancing the LUKS driver, it is possible to implement
the LUKS volume with a detached header.

Normally a LUKS volume has a layout:
disk: | he

crypto: Support LUKS volume with detached header

By enhancing the LUKS driver, it is possible to implement
the LUKS volume with a detached header.

Normally a LUKS volume has a layout:
disk: | header | key material | disk payload data |

With a detached LUKS header, you need 2 disks so getting:
disk1: | header | key material |
disk2: | disk payload data |

There are a variety of benefits to doing this:
* Secrecy - the disk2 cannot be identified as containing LUKS
volume since there's no header
* Control - if access to the disk1 is restricted, then even
if someone has access to disk2 they can't unlock
it. Might be useful if you have disks on NFS but
want to restrict which host can launch a VM
instance from it, by dynamically providing access
to the header to a designated host
* Flexibility - your application data volume may be a given
size and it is inconvenient to resize it to
add encryption.You can store the LUKS header
separately and use the existing storage
volume for payload
* Recovery - corruption of a bit in the header may make the
entire payload inaccessible. It might be
convenient to take backups of the header. If
your primary disk header becomes corrupt, you
can unlock the data still by pointing to the
backup detached header

Take the raw-format image as an example to introduce the usage
of the LUKS volume with a detached header:

1. prepare detached LUKS header images
$ dd if=/dev/zero of=test-header.img bs=1M count=32
$ dd if=/dev/zero of=test-payload.img bs=1M count=1000
$ cryptsetup luksFormat --header test-header.img test-payload.img
> --force-password --type luks1

2. block-add a protocol blockdev node of payload image
$ virsh qemu-monitor-command vm '{"execute":"blockdev-add",
> "arguments":{"node-name":"libvirt-1-storage", "driver":"file",
> "filename":"test-payload.img"}}'

3. block-add a protocol blockdev node of LUKS header as above.
$ virsh qemu-monitor-command vm '{"execute":"blockdev-add",
> "arguments":{"node-name":"libvirt-2-storage", "driver":"file",
> "filename": "test-header.img" }}'

4. object-add the secret for decrypting the cipher stored in
LUKS header above
$ virsh qemu-monitor-command vm '{"execute":"object-add",
> "arguments":{"qom-type":"secret", "id":
> "libvirt-2-storage-secret0", "data":"abc123"}}'

5. block-add the raw-drived blockdev format node
$ virsh qemu-monitor-command vm '{"execute":"blockdev-add",
> "arguments":{"node-name":"libvirt-1-format", "driver":"raw",
> "file":"libvirt-1-storage"}}'

6. block-add the luks-drived blockdev to link the raw disk
with the LUKS header by specifying the field "header"
$ virsh qemu-monitor-command vm '{"execute":"blockdev-add",
> "arguments":{"node-name":"libvirt-2-format", "driver":"luks",
> "file":"libvirt-1-format", "header":"libvirt-2-storage",
> "key-secret":"libvirt-2-format-secret0"}}'

7. hot-plug the virtio-blk device finally
$ virsh qemu-monitor-command vm '{"execute":"device_add",
> "arguments": {"num-queues":"1", "driver":"virtio-blk-pci",
> "drive": "libvirt-2-format", "id":"virtio-disk2"}}'

Starting a VM with a LUKS volume with detached header is
somewhat similar to hot-plug in that both maintaining the
same json command while the starting VM changes the
"blockdev-add/device_add" parameters to "blockdev/device".

Signed-off-by: Hyman Huang <yong.huang@smartx.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

crypto: Introduce SM4 symmetric cipher algorithm

Introduce the SM4 cipher algorithms (OSCCA GB/T 32907-2016).

SM4 (GBT.32907-2016) is a cryptographic standard issued by the
Organization of State Co

crypto: Introduce SM4 symmetric cipher algorithm

Introduce the SM4 cipher algorithms (OSCCA GB/T 32907-2016).

SM4 (GBT.32907-2016) is a cryptographic standard issued by the
Organization of State Commercial Administration of China (OSCCA)
as an authorized cryptographic algorithms for the use within China.

Detect the SM4 cipher algorithms and enable the feature silently
if it is available.

Signed-off-by: Hyman Huang <yong.huang@smartx.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

monitor: use aio_co_reschedule_self()

The aio_co_reschedule_self() API is designed to avoid the race
condition between scheduling the coroutine in another AioContext and
yielding.

The QMP dispatch

monitor: use aio_co_reschedule_self()

The aio_co_reschedule_self() API is designed to avoid the race
condition between scheduling the coroutine in another AioContext and
yielding.

The QMP dispatch code uses the open-coded version that appears
susceptible to the race condition at first glance:

aio_co_schedule(qemu_get_aio_context(), qemu_coroutine_self());
qemu_coroutine_yield();

The code is actually safe because the iohandler and qemu_aio_context
AioContext run under the Big QEMU Lock. Nevertheless, set a good example
and use aio_co_reschedule_self() so it's obvious that there is no race.

Suggested-by: Hanna Reitz <hreitz@redhat.com>
Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
Reviewed-by: Hanna Czenczek <hreitz@redhat.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-ID: <20240206190610.107963-6-stefanha@redhat.com>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>

show more ...

qga: Move type description right after type name

Documentation of type BlockdevOptionsIscsi describes the type's
purpose after its members. Everywhere else, we do it the other way
round. Move it f

qga: Move type description right after type name

Documentation of type BlockdevOptionsIscsi describes the type's
purpose after its members. Everywhere else, we do it the other way
round. Move it for consistency.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-5-armbru@redhat.com>
Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>

show more ...

qapi: Elide "Potential additional modes" from generated docs

Documentation of BlockExportRemoveMode has

Potential additional modes to be added in the future:

hide: Just hide export from ne

qapi: Elide "Potential additional modes" from generated docs

Documentation of BlockExportRemoveMode has

Potential additional modes to be added in the future:

hide: Just hide export from new clients, leave existing connections
as is. Remove export after all clients are disconnected.

soft: Hide export from new clients, answer with ESHUTDOWN for all
further requests from existing clients.

I think this is useful only for developers. Elide it from generated
documentation by turning it into a TODO section.

This effectively reverts my own commit b71fd73cc45 (Revert "qapi:
BlockExportRemoveMode: move comments to TODO"). At the time, I was
about to elide TODO sections from the generated manual, I wasn't sure
about this one, and decided to avoid change. And now I've made up my
mind.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-4-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

show more ...

qapi: Drop redundant documentation of conditional

Documentation generated for dump-skeys contains

This command is only supported on s390 architecture.

and

If
~~

"TARGET_S390X"

T

qapi: Drop redundant documentation of conditional

Documentation generated for dump-skeys contains

This command is only supported on s390 architecture.

and

If
~~

"TARGET_S390X"

The former became redundant in commit 901a34a400a (qapi: add 'If:'
section to generated documentation) added the latter. Drop the
former.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-3-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

show more ...

qapi: Drop redundant documentation of inherited members

Documentation generated for SchemaInfo looks like

The members of "SchemaInfoBuiltin" when "meta-type" is ""builtin""
The members of "

qapi: Drop redundant documentation of inherited members

Documentation generated for SchemaInfo looks like

The members of "SchemaInfoBuiltin" when "meta-type" is ""builtin""
The members of "SchemaInfoEnum" when "meta-type" is ""enum""
The members of "SchemaInfoArray" when "meta-type" is ""array""
The members of "SchemaInfoObject" when "meta-type" is ""object""
The members of "SchemaInfoAlternate" when "meta-type" is ""alternate""
The members of "SchemaInfoCommand" when "meta-type" is ""command""
The members of "SchemaInfoEvent" when "meta-type" is ""event""
Additional members depend on the value of "meta-type".

The last line became redundant when commit 88f63467c57 (qapi2texi:
Generate reference to base type members) added the lines preceding it.
Drop it.

BlockdevOptions has the same issue. Drop

Remaining options are determined by the block driver.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-2-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

show more ...

qapi/migration.json: Fix the member name for MigrationCapability

s/@compression/@compress/

Fixes: 864128df46

Signed-off-by: Han Han <hhan@redhat.com>
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>