[Libguestfs] [PATCH nbdkit v2 4/7] docs: Document new .block_size plugin/filter callback

[Eric Blake]

On Thu, Feb 17, 2022 at 02:36:45PM +0000, Richard W.M. Jones wrote:
> ---
>  docs/nbdkit-filter.pod |  9 +++++++++
>  docs/nbdkit-plugin.pod | 35 +++++++++++++++++++++++++++++++++++
>  2 files changed, 44 insertions(+)
> 
> +++ b/docs/nbdkit-plugin.pod
> @@ -872,6 +872,41 @@ returning a compile-time constant string, you may find
>  C<nbdkit_strdup_intern> helpful for returning a value that avoids a
>  memory leak.
>  
> +=head2 C<.block_size>
> +
> + int block_size (void *handle, uint32_t *minimum,
> +                 uint32_t *preferred, uint32_t *maximum);
> +
> +This is called during the option negotiation phase of the protocol to
> +get the minimum, preferred and maximum block size (all in bytes) of
> +the block device.  The client should obey these constraints by not
> +making requests which are smaller than the minimum size or larger than
> +the maximum size, and usually making requests of a multiple of the
> +preferred size.  Furthermore requests should be aligned to at least
> +the minimum block size, and usually the preferred block size.
> +
> +"Preferred" block size in the NBD specification can be misinterpreted.
> +It means the I/O size which does not have a penalty for
> +read-modify-write.
> +
> +Even if the plugin implements this callback, this does B<not> mean
> +that all client requests will obey the constraints.  A client could
> +still ignore the constraints.  nbdkit passes all requests through to
> +the plugin, because what the plugin does depends on the plugin's
> +policy.  It might decide to serve the requests correctly anyway, or
> +reject them with an error.
> +
> +The minimum block size must be E<ge> 1.  The maximum block size must
> +be E<le> 0xffff_ffff.  minimum E<le> preferred E<le> maximum.

Given that maximum is uint32_t, 'must be <= 0xffff_ffff' is a tautology.

> +
> +As a special case, the plugin may return minimum == preferred ==
> +maximum == 0, meaning no information.
> +
> +If this callback is not used, then the NBD protocol assumes by default
> +minimum = 1, preferred = 4096.  (Maximum block size depends on various
> +factors, see the NBD protocol specification, section "Block size
> +constraints").

ACK. I'm okay with you squashing 1-4.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org