Libguestfs - Mar 2019 - Re: [PATCH nbdkit v4 01/15] server: Implement extents/can_extents calls for plugins and filters.

On 3/26/19 4:17 PM, Richard W.M. Jones wrote:
> This pair of calls allows plugins to describe which extents in the
> virtual disk are allocated, holes or zeroes.
> ---
> +=head2 C<.extents>
> +
> + int extents (void *handle, uint32_t count, uint64_t offset,
> +              uint32_t flags, struct nbdkit_extents *extents);
> +
> +During the data serving phase, this callback is used to detect
> +allocated, sparse and zeroed regions of the disk.
> +
> +This function will not be called if C<.can_extents> returned false.
> +nbdkit's default behaviour in this case is to treat the whole virtual
> +disk as if it was allocated.
> +
> +The callback should detect and return the list of extents overlapping
> +the range C<[offset...offset+count-1]>.  The C<extents>
parameter
> +points to an opaque object which the callback should fill in by
> +calling C<nbdkit_add_extent>.  See L</Extents list> below.
[1]
> +
> +If there is an error, C<.extents> should call C<nbdkit_error>
with an
> +error message, and C<nbdkit_set_error> to record an appropriate
error
> +(unless C<errno> is sufficient), then return C<-1>.
> +
> +=head3 Extents list
> +
> +The plugin C<extents> callback is passed an opaque pointer
C<struct
> +nbdkit_extents *extents>.  This structure represents a list of
> +L<filesystem
extents|https://en.wikipedia.org/wiki/Extent_(file_systems)>
> +describing which areas of the disk are allocated, which are sparse
> +(“holes”), and, if supported, which are zeroes.
> +
> +The C<extents> callback should scan the disk starting at
C<offset> and
> +call C<nbdkit_add_extent> for each extent found.
> +
> +Extents overlapping the range C<[offset...offset+count-1]> should be
> +returned if possible.  However nbdkit ignores extents E<lt> offset
so
> +the plugin may, if it is easier to implement, return all extent
> +information for the whole disk.  The plugin may return extents beyond
> +the end of the range.  It may also return extent information for less
> +than the whole range, but it must return at least one extent
> +overlapping C<offset>.
> +
> +The extents B<must> be added in ascending order, and B<must>
be
> +contiguous.
> +
> +The C<flags> parameter may contain the flag
C<NBDKIT_FLAG_REQ_ONE>
> +which means that the client is only requesting information about the
> +extent overlapping C<offset>.  The plugin may ignore this flag, or
as
> +an optimization it may return just a single extent for C<offset>.
I wonder if this paragraph belongs up at [1].

Looks good to me.

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

On Wed, Mar 27, 2019 at 01:56:57AM -0500, Eric Blake
wrote:
> On 3/26/19 4:17 PM, Richard W.M. Jones wrote:
> > This pair of calls allows plugins to describe which extents in the
> > virtual disk are allocated, holes or zeroes.
> > ---
> 
> > +=head2 C<.extents>
> > +
> > + int extents (void *handle, uint32_t count, uint64_t offset,
> > +              uint32_t flags, struct nbdkit_extents *extents);
> > +
> > +During the data serving phase, this callback is used to detect
> > +allocated, sparse and zeroed regions of the disk.
> > +
> > +This function will not be called if C<.can_extents> returned
false.
> > +nbdkit's default behaviour in this case is to treat the whole
virtual
> > +disk as if it was allocated.
> > +
> > +The callback should detect and return the list of extents overlapping
> > +the range C<[offset...offset+count-1]>.  The C<extents>
parameter
> > +points to an opaque object which the callback should fill in by
> > +calling C<nbdkit_add_extent>.  See L</Extents list>
below.
> 
> [1]
> 
> > +
> > +If there is an error, C<.extents> should call
C<nbdkit_error> with an
> > +error message, and C<nbdkit_set_error> to record an appropriate
error
> > +(unless C<errno> is sufficient), then return C<-1>.
> > +
> > +=head3 Extents list
> > +
> > +The plugin C<extents> callback is passed an opaque pointer
C<struct
> > +nbdkit_extents *extents>.  This structure represents a list of
> > +L<filesystem
extents|https://en.wikipedia.org/wiki/Extent_(file_systems)>
> > +describing which areas of the disk are allocated, which are sparse
> > +(“holes”), and, if supported, which are zeroes.
> > +
> > +The C<extents> callback should scan the disk starting at
C<offset> and
> > +call C<nbdkit_add_extent> for each extent found.
> > +
> > +Extents overlapping the range C<[offset...offset+count-1]>
should be
> > +returned if possible.  However nbdkit ignores extents E<lt>
offset so
> > +the plugin may, if it is easier to implement, return all extent
> > +information for the whole disk.  The plugin may return extents beyond
> > +the end of the range.  It may also return extent information for less
> > +than the whole range, but it must return at least one extent
> > +overlapping C<offset>.
> > +
> > +The extents B<must> be added in ascending order, and
B<must> be
> > +contiguous.
> > +
> > +The C<flags> parameter may contain the flag
C<NBDKIT_FLAG_REQ_ONE>
> > +which means that the client is only requesting information about the
> > +extent overlapping C<offset>.  The plugin may ignore this flag,
or as
> > +an optimization it may return just a single extent for
C<offset>.
> 
> I wonder if this paragraph belongs up at [1].
> 
> Looks good to me.
I actually moved it down there in this version because otherwise you
end up talking about flags before explaining what extents are.

I'll clarify it by saying "The C<flags> parameter to
C<nbdkit_add_extent> ..."

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v

On Wed, Mar 27, 2019 at 09:49:10AM +0000, Richard W.M. Jones
wrote:
> I'll clarify it by saying "The C<flags> parameter to
C<nbdkit_add_extent> ...
I mean, "The C<flags> parameter of the C<.extents> callback
..."

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-df lists disk usage of guests without needing to install any
software inside the virtual machine.  Supports Linux and Windows.
http://people.redhat.com/~rjones/virt-df/