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