One Hat Cyber Team

Edit File: block-coroutine-wrapper.html

<!DOCTYPE html>

 <html class="no-js" lang="en" > 
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>block-coroutine-wrapper &mdash; QEMU qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4 documentation</title>

</head>

<a href="../index.html" class="icon icon-home"> QEMU

</div>

<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <p class="caption"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../about/index.html">About QEMU</a></li>
<li class="toctree-l1"><a class="reference internal" href="../system/index.html">System Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">User Mode Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../interop/index.html">System Emulation Management and Interoperability</a></li>
<li class="toctree-l1"><a class="reference internal" href="../specs/index.html">System Emulation Guest Hardware Specifications</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Developer Information</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="code-of-conduct.html">Code of Conduct</a></li>
<li class="toctree-l2"><a class="reference internal" href="conflict-resolution.html">Conflict Resolution Policy</a></li>
<li class="toctree-l2"><a class="reference internal" href="build-system.html">The QEMU build system architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="style.html">QEMU Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="kconfig.html">QEMU and Kconfig</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html">Testing in QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="fuzzing.html">Fuzzing</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow-integrity.html">Control-Flow Integrity (CFI)</a></li>
<li class="toctree-l2"><a class="reference internal" href="loads-stores.html">Load and Store APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="memory.html">The memory API</a></li>
<li class="toctree-l2"><a class="reference internal" href="migration.html">Migration</a></li>
<li class="toctree-l2"><a class="reference internal" href="atomics.html">Atomic operations in QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="stable-process.html">QEMU and the stable process</a></li>
<li class="toctree-l2"><a class="reference internal" href="ci.html">CI</a></li>
<li class="toctree-l2"><a class="reference internal" href="qtest.html">QTest Device Emulation Testing Framework</a></li>
<li class="toctree-l2"><a class="reference internal" href="decodetree.html">Decodetree Specification</a></li>
<li class="toctree-l2"><a class="reference internal" href="secure-coding-practices.html">Secure Coding Practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="tcg.html">Translator Internals</a></li>
<li class="toctree-l2"><a class="reference internal" href="tcg-icount.html">TCG Instruction Counting</a></li>
<li class="toctree-l2"><a class="reference internal" href="tracing.html">Tracing</a></li>
<li class="toctree-l2"><a class="reference internal" href="multi-thread-tcg.html">Multi-threaded TCG</a></li>
<li class="toctree-l2"><a class="reference internal" href="tcg-plugins.html">QEMU TCG Plugins</a></li>
<li class="toctree-l2"><a class="reference internal" href="bitops.html">Bitwise operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="ui.html">QEMU UI subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="reset.html">Reset in QEMU: the Resettable interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="s390-dasd-ipl.html">Booting from real channel-attached devices on s390x</a></li>
<li class="toctree-l2"><a class="reference internal" href="clocks.html">Modelling a clock tree in QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="qom.html">The QEMU Object Model (QOM)</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html">QEMU modules</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">block-coroutine-wrapper</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#usage">Usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#links">Links</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="multi-process.html">Multi-process QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="ebpf_rss.html">eBPF RSS virtio-net support</a></li>
<li class="toctree-l2"><a class="reference internal" href="vfio-migration.html">VFIO device Migration</a></li>
<li class="toctree-l2"><a class="reference internal" href="qapi-code-gen.html">How to use the QAPI code generator</a></li>
<li class="toctree-l2"><a class="reference internal" href="writing-monitor-commands.html">How to write monitor commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="trivial-patches.html">Trivial Patches</a></li>
<li class="toctree-l2"><a class="reference internal" href="submitting-a-patch.html">Submitting a Patch</a></li>
<li class="toctree-l2"><a class="reference internal" href="submitting-a-pull-request.html">Submitting a Pull Request</a></li>
</ul>
</li>
</ul>

</div>
      </div>
    </nav>

<ul class="wy-breadcrumbs">
    
      <li><a href="../index.html">Docs</a> &raquo;</li>
        
          <li><a href="index.html">Developer Information</a> &raquo;</li>
        
      <li>block-coroutine-wrapper</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            
              <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/devel/block-coroutine-wrapper.rst" class="fa fa-gitlab"> Edit on GitLab</a>
            
          
        
      </li>
    
  </ul>

<hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="block-coroutine-wrapper">
<h1>block-coroutine-wrapper<a class="headerlink" href="#block-coroutine-wrapper" title="Permalink to this headline">¶</a></h1>
<p>A lot of functions in QEMU block layer (see <code class="docutils literal notranslate"><span class="pre">block/*</span></code>) 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
needed function from it and wait for the coroutine to finish in a
BDRV_POLL_WHILE() loop. To run a coroutine we need a function with one
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.</p>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>Assume we have defined the <code class="docutils literal notranslate"><span class="pre">coroutine_fn</span></code> function
<code class="docutils literal notranslate"><span class="pre">bdrv_co_foo(&lt;some</span> <span class="pre">args&gt;)</span></code> and need a non-coroutine interface for it,
called <code class="docutils literal notranslate"><span class="pre">bdrv_foo(&lt;same</span> <span class="pre">args&gt;)</span></code>. In this case the script can help. To
trigger the generation:</p>
<ol class="arabic simple">
<li>You need <code class="docutils literal notranslate"><span class="pre">bdrv_foo</span></code> declaration somewhere (for example, in
<code class="docutils literal notranslate"><span class="pre">block/coroutines.h</span></code>) with the <code class="docutils literal notranslate"><span class="pre">generated_co_wrapper</span></code> mark,
like this:</li>
</ol>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">generated_co_wrapper</span> <span class="nf">bdrv_foo</span><span class="p">(</span><span class="o">&lt;</span><span class="n">some</span> <span class="n">args</span><span class="o">&gt;</span><span class="p">);</span>
</pre></div>
</div>
<ol class="arabic simple" start="2">
<li>You need to feed this declaration to block-coroutine-wrapper script.
For this, add the .h (or .c) file with the declaration to the
<code class="docutils literal notranslate"><span class="pre">input:</span> <span class="pre">files(...)</span></code> list of <code class="docutils literal notranslate"><span class="pre">block_gen_c</span></code> target declaration in
<code class="docutils literal notranslate"><span class="pre">block/meson.build</span></code></li>
</ol>
<p>You are done. During the build, coroutine wrappers will be generated in
<code class="docutils literal notranslate"><span class="pre">&lt;BUILD_DIR&gt;/block/block-gen.c</span></code>.</p>
</div>
<div class="section" id="links">
<h2>Links<a class="headerlink" href="#links" title="Permalink to this headline">¶</a></h2>
<ol class="arabic simple">
<li>The script location is <code class="docutils literal notranslate"><span class="pre">scripts/block-coroutine-wrapper.py</span></code>.</li>
<li>Generic place for private <code class="docutils literal notranslate"><span class="pre">generated_co_wrapper</span></code> declarations is
<code class="docutils literal notranslate"><span class="pre">block/coroutines.h</span></code>, for public declarations:
<code class="docutils literal notranslate"><span class="pre">include/block/block.h</span></code></li>
<li>The core API of generated coroutine wrappers is placed in
(not generated) <code class="docutils literal notranslate"><span class="pre">block/block-gen.h</span></code></li>
</ol>
</div>
</div>

</div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="multi-process.html" class="btn btn-neutral float-right" title="Multi-process QEMU" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="modules.html" class="btn btn-neutral" title="QEMU modules" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>

<hr/>

<div role="contentinfo">
    <p>
        &copy; Copyright 2021, The QEMU Project Developers.

</p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

<p></p>

<p>This documentation is for QEMU version 6.2.0.</p>

<p><a href="../about/license.html">QEMU and this manual are released under the
GNU General Public License, version 2.</a></p>

</footer>

</div>
      </div>

</section>

</div>

</body>
</html>