Re: [PATCH v8 4/7] scripts: add block-coroutine-wrapper.py

[Stefan Hajnoczi]

On Tue, Sep 15, 2020 at 07:44:08PM +0300, Vladimir Sementsov-Ogievskiy wrote:
>  create mode 100755 scripts/block-coroutine-wrapper.py

Please see docs/devel/build-system.rst "Support scripts" for the
preferred way of adding Python scripts to the build system. Mode should
be 644 and the interpreter line should be "#! /usr/bin/env python3"
(with the space). That way meson will run it under the configured
--python= interpreter.

> 
> diff --git a/docs/devel/block-coroutine-wrapper.rst 
> b/docs/devel/block-coroutine-wrapper.rst
> new file mode 100644
> index 0000000000..f7050bbc8f
> --- /dev/null
> +++ b/docs/devel/block-coroutine-wrapper.rst
> @@ -0,0 +1,54 @@
> +=======================
> +block-coroutine-wrapper
> +=======================
> +
> +A lot of functions in QEMJ block layer (see ``block/*``) can by called

s/QEMJ/QEMU/

> +only in coroutine context. Such functions are normally marked by
> +coroutine_fn specifier. Still, sometimes we need to call them from
> +non-coroutine context, for this we need to start a coroutine, run the
> +needed function from it and wait for coroutine finish in
> +BDRV_POLL_WHILE() loop. To run a coroutine we need a function with one
> +void* argument. So for each coroutine_fn function, which needs
> +non-coroutine interface, we should define a structure to pack the
> +parameters, define a separate function to unpack the parameters and
> +call the original function and finally define a new interface function
> +with same list of arguments as original one, which will pack the
> +parameters into a struct, create a coroutine, run it and wait in
> +BDRV_POLL_WHILE() loop. It's boring to create such wrappers by hand, so
> +we have a script to generate them.
> +
> +Usage
> +=====
> +
> +Assume we have defined ``coroutine_fn`` function
> +``bdrv_co_foo(<some args>)`` and need a non-coroutine interface for it,
> +called ``bdrv_foo(<same args>)``. In this case the script can help. To
> +trigger the generation:
> +
> +1. You need ``bdrv_foo`` declaration somewhere (for example in
> +   ``block/coroutines.h`` with ``generated_co_wrapper`` mark,
> +   like this:
> +
> +.. code-block:: c
> +
> +    int generated_co_wrapper bdrv_foor(<some args>);

s/foor/foo/

signature.asc
Description: PGP signature