Re: [Qemu-devel] Block layer complexity: what to do to keep it under control?

[Daniel P. Berrange]

On Wed, Nov 29, 2017 at 11:55:02AM +0800, Fam Zheng wrote:
> So in principle, what should we do to make the block layer easy to understand,
> develop with and debug? I think we have opportunities in these aspects:
> 
> - Documentation
> 
>   There is no central developer doc about block layer, especially how all 
> pieces
>   fit together. Having one will make it a lot easier for new contributors to
>   understand better. Of course, we're facing the old problem: the code is
>   moving, maintaining an updated document needs effort.
> 
>   Idea: add ./doc/deve/block.txt?

When I was writing the LUKS block driver one of the bug problems I had was
understanding the internal BlockDriver APIs, as there's almost a complete
lack of any API documentation for them. So I would strongly like to see
inline API documentation in the header files to describe the APIs. eg more
of this:

  commit b461151ff31c7925f271c297e8abed20231ac7d3
  Author: Daniel P. Berrange <address@hidden>
  Date:   Thu Aug 31 11:54:56 2017 +0100

    block: document semantics of bdrv_co_preadv|pwritev
    

> More thoughts?

Currently the block driver layer has three different ways you can
implement the I/O path. bdrv_aio_{readv,writev},  bdrv_co_{readv,writev}
and bdrv_co_{preadv,pwritev}. This is pretty confusing to people who are
not core block maintainers, and doubtless increases the code complexity
to deal with three different I/O paths.

This is the usual curse of QEMU refactoring - a new framework is introduced
but only a few existing users are updated to use it.  I'd suggest an
aggressive push to convert all block drivers to use the same internal APIs.
Set a deadline for maintainers to convert them, and if missed, drop the
drivers in question.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|