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 <berra...@redhat.com>
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 :|
