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

[Eric Blake <eblake@redhat.com>]

On 9/23/20 7:00 PM, Eric Blake wrote:

> 
> Tested-by: Eric Blake <eblake@redhat.com>
> 
> There's enough grammar fixes, and the fact that John is working on 
> python cleanups, to make me wonder if we need a v9, or if I should just 
> stage it where it is with any other cleanups as followups.  But I'm 
> liking the reduced maintenance burden once it is in, and don't want to 
> drag it out to the point that it needs more rebasing as other things 
> land first.
> 

Here's what I've squashed in and temporarily pushed to my tree if you 
want to double-check my rebase work:
https://repo.or.cz/qemu/ericb.git/shortlog/refs/heads/master

diff --git a/docs/devel/block-coroutine-wrapper.rst 
b/docs/devel/block-coroutine-wrapper.rst
index f7050bbc8fa6..d09fff2cc539 100644
--- a/docs/devel/block-coroutine-wrapper.rst
+++ b/docs/devel/block-coroutine-wrapper.rst
@@ -2,43 +2,43 @@
  block-coroutine-wrapper
  =======================

-A lot of functions in QEMJ block layer (see ``block/*``) can by called
-only in coroutine context. Such functions are normally marked by
+A lot of functions in QEMU block layer (see ``block/*``) can only be
+called in coroutine context. Such functions are normally marked by the
  coroutine_fn specifier. Still, sometimes we need to call them from
-non-coroutine context, for this we need to start a coroutine, run the
+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
+void* argument. So for each coroutine_fn function which needs a
  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.
+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
+Assume we have defined the ``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,
+1. You need ``bdrv_foo`` declaration somewhere (for example, in
+   ``block/coroutines.h``) with the ``generated_co_wrapper`` mark,
     like this:

  .. code-block:: c

-    int generated_co_wrapper bdrv_foor(<some args>);
+    int generated_co_wrapper bdrv_foo(<some args>);

  2. You need to feed this declaration to block-coroutine-wrapper script.
-   For this, add .h (or .c) file with the declaration to
+   For this, add the .h (or .c) file with the declaration to the
     ``input: files(...)`` list of ``block_gen_c`` target declaration in
     ``block/meson.build``

-You are done. On build, coroutine wrappers will be generated in
+You are done. During the build, coroutine wrappers will be generated in
  ``<BUILD_DIR>/block/block-gen.c``.

  Links
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 04773ce076b3..cb0abe1e6988 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -31,3 +31,4 @@ Contents:
     reset
     s390-dasd-ipl
     clocks
+   block-coroutine-wrapper
diff --git a/scripts/block-coroutine-wrapper.py 
b/scripts/block-coroutine-wrapper.py
index d859c07a5f55..8c0a08d9b020 100755
--- a/scripts/block-coroutine-wrapper.py
+++ b/scripts/block-coroutine-wrapper.py
@@ -2,7 +2,7 @@
  """Generate coroutine wrappers for block subsystem.

  The program parses one or several concatenated c files from stdin,
-searches for functions with 'generated_co_wrapper' specifier
+searches for functions with the 'generated_co_wrapper' specifier
  and generates corresponding wrappers on stdout.

  Usage: block-coroutine-wrapper.py generated-file.c FILE.[ch]...
@@ -39,7 +39,7 @@ def prettify(code: str) -> str:
              'BraceWrapping': {'AfterFunction': True},
              'BreakBeforeBraces': 'Custom',
              'SortIncludes': False,
-            'MaxEmptyLinesToKeep': 2
+            'MaxEmptyLinesToKeep': 2,
          })
          p = subprocess.run(['clang-format', f'-style={style}'], 
check=True,
                             encoding='utf-8', input=code,
@@ -168,7 +168,7 @@ int {func.name}({ func.gen_list('{decl}') })


  def gen_wrappers_file(input_code: str) -> str:
-    res = gen_header()
+    res = ''
      for func in func_decl_iter(input_code):
          res += '\n\n\n'
          res += gen_wrapper(func)
@@ -181,6 +181,7 @@ if __name__ == '__main__':
          exit(f'Usage: {sys.argv[0]} OUT_FILE.c IN_FILE.[ch]...')

      with open(sys.argv[1], 'w') as f_out:
+        f_out.write(gen_header())
          for fname in sys.argv[2:]:
              with open(fname) as f_in:
                  f_out.write(gen_wrappers_file(f_in.read()))
diff --git a/include/block/block.h b/include/block/block.h
index d861883b8d9e..0f0ddc51b49e 100644
--- a/include/block/block.h
+++ b/include/block/block.h
@@ -13,7 +13,7 @@
  /*
   * generated_co_wrapper
   *
- * Function specifier, which does nothing but marking functions to be
+ * Function specifier, which does nothing but mark functions to be
   * generated by scripts/block-coroutine-wrapper.py
   *
   * Read more in docs/devel/block-coroutine-wrapper.rst



-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org