Hyman Huang <yong.hu...@smartx.com> writes: > Add comment in detail for commit 433957bb7f (qapi: > Make parameter 'file' optional for > BlockdevCreateOptionsLUKS). > > Signed-off-by: Hyman Huang <yong.hu...@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?
