Re: [Qemu-devel] [PATCH v3 2/3] virtio-balloon: VIRTIO_BALLOON_F_FREE_PAGE_HINT

[Wei Wang]

On 03/03/2018 02:37 AM, Michael S. Tsirkin wrote:
> On Fri, Mar 02, 2018 at 04:47:29PM +0800, Wei Wang wrote:
> > diff --git a/include/sysemu/balloon.h b/include/sysemu/balloon.h
> > index af49e19..16a2aae 100644
> > --- a/include/sysemu/balloon.h
> > +++ b/include/sysemu/balloon.h
> ...
>
> > +typedef void (QEMUBalloonFreePageStart)(void *opaque);
> > +typedef void (QEMUBalloonFreePageStop)(void *opaque);
> So I think the rule is that no bitmap sync must happen
> between these two, otherwise a hint might arrive and
> override the sync output.
>
> Should be documented I think.

Yes, agree. How about adding the following new balloon API explanation 
to this patch's commit:

    - balloon_free_page_start: Callers call this API to obtain guest free
      page hints, and clear the related bits from the migration dirty 
bitmap.
      The whole process is implemented in a new thread independent of the
      migration thread. Free page hints imply the part of guest memory is
      likely to be free without a guarantee. That is, the reported free 
pages
      may not be free any more when QEMU receives them, so callers are
      responsible for detecting those pages that are not free pages 
after the
      bits are cleared from the dirty bitmap. To ensure the above, this API
      should be used when the migration dirty logging mechanism (e.g.
      guest memory write-protection) has started.

    - balloon_free_page_stop: Callers call this API to stop the guest from
      reporting free page hints. Bits from the dirty bitmap are safe to
      be cleared on condition that the dirty logging mechanism is recording
      pages that the guest has written to. To avoid the case that clearing
      bits of free page hints overrides the dirty bits offered by the dirty
      logging mechanism, this API is suggested to be called before QEMU
      synchronizes the dirty logging bitmap.

    - balloon_free_page_support: This API is called to check whether the
      balloon device supports the guest free page reporting feature. The
      balloon_free_page_start and balloon_free_page_stop APIs should be 
used
      only when this API returns true.


Best,
Wei