block-coroutine-wrapper.rst (2122B)
1======================= 2block-coroutine-wrapper 3======================= 4 5A lot of functions in QEMU block layer (see ``block/*``) can only be 6called in coroutine context. Such functions are normally marked by the 7coroutine_fn specifier. Still, sometimes we need to call them from 8non-coroutine context; for this we need to start a coroutine, run the 9needed function from it and wait for the coroutine to finish in a 10BDRV_POLL_WHILE() loop. To run a coroutine we need a function with one 11void* argument. So for each coroutine_fn function which needs a 12non-coroutine interface, we should define a structure to pack the 13parameters, define a separate function to unpack the parameters and 14call the original function and finally define a new interface function 15with same list of arguments as original one, which will pack the 16parameters into a struct, create a coroutine, run it and wait in 17BDRV_POLL_WHILE() loop. It's boring to create such wrappers by hand, 18so we have a script to generate them. 19 20Usage 21===== 22 23Assume we have defined the ``coroutine_fn`` function 24``bdrv_co_foo(<some args>)`` and need a non-coroutine interface for it, 25called ``bdrv_foo(<same args>)``. In this case the script can help. To 26trigger the generation: 27 281. You need ``bdrv_foo`` declaration somewhere (for example, in 29 ``block/coroutines.h``) with the ``generated_co_wrapper`` mark, 30 like this: 31 32.. code-block:: c 33 34 int generated_co_wrapper bdrv_foo(<some args>); 35 362. You need to feed this declaration to block-coroutine-wrapper script. 37 For this, add the .h (or .c) file with the declaration to the 38 ``input: files(...)`` list of ``block_gen_c`` target declaration in 39 ``block/meson.build`` 40 41You are done. During the build, coroutine wrappers will be generated in 42``<BUILD_DIR>/block/block-gen.c``. 43 44Links 45===== 46 471. The script location is ``scripts/block-coroutine-wrapper.py``. 48 492. Generic place for private ``generated_co_wrapper`` declarations is 50 ``block/coroutines.h``, for public declarations: 51 ``include/block/block.h`` 52 533. The core API of generated coroutine wrappers is placed in 54 (not generated) ``block/block-gen.h``