Re: [PATCH v4 2/7] qapi: Make parameter 'file' optional for BlockdevCreateOptionsLUKS

[Markus Armbruster <armbru@redhat.com>]

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

> On Tue, Feb 20, 2024 at 4:56 PM Markus Armbruster <armbru@redhat.com> wrote:
>
>> Yong Huang <yong.huang@smartx.com> writes:
>>
>> > On Tue, Feb 20, 2024 at 2:31 PM Markus Armbruster <armbru@redhat.com>
>> wrote:
>> >
>> >> yong.huang@smartx.com writes:
>> >>
>> >> > From: Hyman Huang <yong.huang@smartx.com>
>> >> >
>> >> > 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>
>> >>
>> >> [...]
>> >>
>> >> > diff --git a/qapi/block-core.json b/qapi/block-core.json
>> >> > index ae604c6019..69a88d613d 100644
>> >> > --- a/qapi/block-core.json
>> >> > +++ b/qapi/block-core.json
>> >> > @@ -4957,7 +4957,8 @@
>> >> >  #
>> >> >  # Driver specific image creation options for LUKS.
>> >> >  #
>> >> > -# @file: Node to create the image format on
>> >> > +# @file: Node to create the image format on, mandatory except when
>> >> > +#        'preallocation' is not requested
>> >>
>> >> You mean when @preallocation is "off"?
>> >>
>> >> Cases:
>> >>
>> >> 1. @file is mandatory
>> >>
>> >
>> > When @preallocation is specified to PREALLOC_MODE_ON, file
>> > is mandatory because preallocation aims to act on payload data that
>> > @file holds.
>> >
>> >
>> >> 2. @file is optional and present
>> >>
>> >
>> > When @preallocation is not specified or equals to PREALLOC_MODE_OFF,
>> > @file if optional.
>> > If @file present，there are two cases:
>> > 1. @header is absent,  the creation process degenerate to the origin action.
>> > 2. @header is present,  the creation process would trunk the payload data
>> > image that @file holds and do the LUKS formatting on the image that
>> > @header refers;
>> >
>> >
>> >>
>> >> 3. @file is optional and absent
>> >>
>> >
>> > When @preallocation is not specified or equals to PREALLOC_MODE_OFF,
>> > @file if optional.
>> > If @file is absent, do the LUKS formatting only.
>> > Note that Either the parameter 'header' or 'file' must be specified.
>> >
>> > Here's my interpretation; do let me know if any of the points are off or
>> > need to be refactored.
>> >
>> >
>> >>
>> >> Ignorant question: behavior in each case?
>>
>> Thanks!  Would it make sense to work the above into the documentation?
>>
>
> You mean adding the above interpretation to the following patch?
>
> https://patchew.org/QEMU/c2049499aa05758b4cf18dcec942694ed454a980.1708358310.git.yong.huang@smartx.com/

To the doc comments.

The doc comments are the source code for the "QEMU QMP Reference
Manual".  That manual should fully explain what the QMP commands do.

Information on how to best use the commands, or an introduction to
concepts behind the commands can also be useful, but is often a bad fit
for a *reference* manual.  We can put it elsewhere then.

Makes sense?