mirror_qemu/docs/devel
Vladimir Sementsov-Ogievskiy aaaa20b69b scripts: add block-coroutine-wrapper.py
We have a very frequent pattern of creating a coroutine from a function
with several arguments:

  - create a structure to pack parameters
  - create _entry function to call original function taking parameters
    from struct
  - do different magic to handle completion: set ret to NOT_DONE or
    EINPROGRESS or use separate bool field
  - fill the struct and create coroutine from _entry function with this
    struct as a parameter
  - do coroutine enter and BDRV_POLL_WHILE loop

Let's reduce code duplication by generating coroutine wrappers.

This patch adds scripts/block-coroutine-wrapper.py together with some
friends, which will generate functions with declared prototypes marked
by the 'generated_co_wrapper' specifier.

The usage of new code generation is as follows:

    1. define the coroutine function somewhere

        int coroutine_fn bdrv_co_NAME(...) {...}

    2. declare in some header file

        int generated_co_wrapper bdrv_NAME(...);

       with same list of parameters (generated_co_wrapper is
       defined in "include/block/block.h").

    3. Make sure the block_gen_c declaration in block/meson.build
       mentions the file with your marker function.

Still, no function is now marked, this work is for the following
commit.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200924185414.28642-5-vsementsov@virtuozzo.com>
[Added encoding='utf-8' to open() calls as requested by Vladimir. Fixed
typo and grammar issues pointed out by Eric Blake. Removed clang-format
dependency that caused build test issues.
--Stefan]
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2020-10-05 10:59:06 +01:00
..
atomics.rst qemu/atomic.h: rename atomic_ to qatomic_ 2020-09-23 16:07:44 +01:00
bitops.rst docs: Create bitops.rst as example of kernel-docs 2019-12-17 19:36:57 +01:00
blkdebug.txt docs/: fix some comment spelling errors 2020-09-17 20:37:13 +02:00
blkverify.txt meson: link emulators without Makefile.target 2020-08-21 06:30:40 -04:00
block-coroutine-wrapper.rst scripts: add block-coroutine-wrapper.py 2020-10-05 10:59:06 +01:00
build-system.rst meson: clean up build_by_default 2020-09-30 19:09:19 +02:00
clocks.rst docs/clocks: add device's clock documentation 2020-04-30 15:35:40 +01:00
conf.py docs: Provide separate conf.py for each manual we want 2019-03-07 14:26:46 +00:00
decodetree.rst docs/devel: Document decodetree no-overlap groups 2020-08-04 16:33:47 +01:00
fuzzing.txt docs/fuzz: add instructions for generating a coverage report 2020-07-21 07:29:18 +02:00
index.rst scripts: add block-coroutine-wrapper.py 2020-10-05 10:59:06 +01:00
kconfig.rst docs: Be consistent about capitalization of 'Arm' 2020-03-12 11:20:20 +00:00
loads-stores.rst accel/tcg: Add endian-specific cpu_{ld, st}* operations 2020-05-11 11:22:06 +01:00
lockcnt.txt qemu/atomic.h: rename atomic_ to qatomic_ 2020-09-23 16:07:44 +01:00
memory.rst docs: add memory API reference 2019-12-17 19:36:58 +01:00
migration.rst docs/: fix some comment spelling errors 2020-09-17 20:37:13 +02:00
multi-thread-tcg.rst docs/devel: fix grammar in multi-thread-tcg 2020-07-15 11:52:39 +01:00
multiple-iothreads.txt block: Remove bdrv_set_aio_context() 2019-06-04 16:55:58 +02:00
qapi-code-gen.txt docs/devel/qapi-code-gen.txt: Update to new rST backend conventions 2020-09-29 17:55:39 +02:00
qom.rst docs: Move object.h overview doc comment to qom.rst 2020-09-30 19:11:36 +02:00
rcu.txt qemu/atomic.h: rename atomic_ to qatomic_ 2020-09-23 16:07:44 +01:00
replay.txt replay: document development rules 2019-08-20 17:26:21 +02:00
reset.rst docs/devel/reset.rst: add doc about Resettable interface 2020-01-30 16:02:05 +00:00
s390-dasd-ipl.rst docs: rstfy s390 dasd ipl documentation 2020-02-26 18:57:07 +01:00
secure-coding-practices.rst docs: add Secure Coding Practices to developer docs 2019-05-10 10:53:52 +01:00
stable-process.rst docs/devel: fix stable process doc formatting 2020-01-27 12:13:09 +01:00
tcg-icount.rst docs/devel: add some notes on tcg-icount for developers 2020-07-11 15:53:00 +01:00
tcg-plugins.rst plugins: move the more involved plugins to contrib 2020-09-10 10:47:03 +01:00
tcg.rst docs: Be consistent about capitalization of 'Arm' 2020-03-12 11:20:20 +00:00
testing.rst docs/: fix some comment spelling errors 2020-09-17 20:37:13 +02:00
tracing.txt docs/: fix some comment spelling errors 2020-09-17 20:37:13 +02:00
virtio-migration.txt docs: create config/, devel/ and spin/ subdirectories 2017-06-07 18:22:03 +02:00
writing-qmp-commands.txt monitor: Move {hmp, qmp}.c to monitor/{hmp, qmp}-cmds.c 2019-06-17 20:36:56 +02:00