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 _______________________________________________ Libguestfs mailing list [email protected] https://www.redhat.com/mailman/listinfo/libguestfs
