[Libguestfs] [PATCH nbdkit 3/6] docs: Document new .block_size plugin/filter callback

--- docs/nbdkit-filter.pod | 9 +++++++++ docs/nbdkit-plugin.pod | 28 ++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/docs/nbdkit-filter.pod b/docs/nbdkit-filter.pod index 36151e69..d63ee559 100644 --- a/docs/nbdkit-filter.pod +++ b/docs/nbdkit-filter.pod @@ -711,6 +711,15 @@ This intercepts the plugin C<.export_description> method and can be used to read or modify the export description that the NBD client will see. +=head2 C<.block_size> + + int block_size (nbdkit_next *next, void *handle, uint32_t *minimum, + uint32_t *preferred, uint32_t *maximum); + +This intercepts the plugin C<.block_size> method and can be used to +read or modify the block size constraints that the NBD client will +see. + =head2 C<.can_write> =head2 C<.can_flush> diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod index 329bcd31..15573f0a 100644 --- a/docs/nbdkit-plugin.pod +++ b/docs/nbdkit-plugin.pod @@ -872,6 +872,34 @@ 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 by constraints by not +making requests which are smaller than the minimum size or larger than +the maximum size, and usually making requests of the preferred size. +Furthermore requests should be aligned to at least the minimum block +size, and usually the preferred block size. + +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. + +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"). + =head2 C<.can_write> int can_write (void *handle); -- 2.35.1