Re: [PATCH] qapi: Craft the BlockdevCreateOptionsLUKS comment

[Markus Armbruster <armbru@redhat.com>]

Hyman Huang <yong.huang@smartx.com> writes:

> Add comment in detail for commit 433957bb7f (qapi:
> Make parameter 'file' optional for
> BlockdevCreateOptionsLUKS).
>
> Signed-off-by: Hyman Huang <yong.huang@smartx.com>
> ---
>  qapi/block-core.json | 20 +++++++++++++++++++-
>  1 file changed, 19 insertions(+), 1 deletion(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index ab5a93a966..42b0840d43 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -4973,7 +4973,25 @@
>  ##
>  # @BlockdevCreateOptionsLUKS:
>  #
> -# Driver specific image creation options for LUKS.
> +# Driver specific image creation options for LUKS. Note that
> +# @file is required if @preallocation is specified and equals
> +# PREALLOC_MODE_ON. The following three scenarios determine how
> +# creation logic behaves when @preallocation is either equal to
> +# PREALLOC_MODE_OFF or is not given:
> +#
> +#  1) When @file is given only, format the block device referenced
> +#     by @file as the LUKS specification and trunk it to the @size.

Do you mean "truncate it to @size"?

> +#     In this case, the @size should reflect amount of space made
> +#     available to the guest, so the trunk size must take account
> +#     of that which will be used by the crypto header.
> +#
> +#  2) When @header is given only, just format the block device
> +#     referenced by @header as the LUKS specification.
> +#
> +#  3) When both @file and @header are given, block device
> +#     referenced by @file should be trunked to @size, and block
> +#     device referenced by @header should be formatted as the LUKS
> +#     specification.
>  #
>  # @file: Node to create the image format on, mandatory except when
>  #        'preallocation' is not requested

Let's see whether I understand.

blockdev-create with "driver": "luks" can work in three different ways:

1. Create an image with a LUKS header

2. Create just a detached LUKS header

3. Create an image and a detached LUKS header

Correct?

@file and @header are BlockdevRef, which means they refer to existing
images with arbitrary driver.  Could be "file", "qcow2", or anything.

Correct?

To get 1., specify @file, but not @header.

To get 2., specify @header, but not @file.

To get 3., specify both.

Specifying neither is an error.

Correct?

In any case, @size is the logical size of the image (how much data it
can hold).

With 1., the actual image size is a bit larger due to the LUKS header.
The @file image is resized to that size: if it's shorter, it's grown, if
it's longer, it's truncated.

With 2., @size is merely recorded in the detached LUKS header.

With 3., @size is recorded in the detached LUKS header, and the @file
image is resized as with 1.

Correct?