One Hat Cyber Team

Your IP : 216.73.216.115

Server IP : 194.44.31.54

Server : Linux zen.imath.kiev.ua 4.18.0-553.77.1.el8_10.x86_64 #1 SMP Fri Oct 3 14:30:23 UTC 2025 x86_64

Server Software : Apache/2.4.37 (Rocky Linux) OpenSSL/1.1.1k

PHP Version : 5.6.40

Buat File | Buat Folder

Dir : ~/usr/share/doc/qemu-kvm/devel/

Edit File: qgraph.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>Qtest Driver Framework &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">
 
 
 
 
 
 
 Contents:
<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 current"><a class="reference internal" href="qtest.html">QTest Device Emulation Testing Framework</a><ul class="current">
<li class="toctree-l3 current"><a class="current reference internal" href="#">Qtest Driver Framework</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#qgraph-concepts">QGraph concepts</a></li>
<li class="toctree-l4"><a class="reference internal" href="#creating-a-new-driver-and-its-interface">Creating a new driver and its interface</a></li>
<li class="toctree-l4"><a class="reference internal" href="#adding-a-new-test">Adding a new test</a></li>
<li class="toctree-l4"><a class="reference internal" href="#qgraph-api-reference">Qgraph API reference</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="qtest.html#qtest-protocol">QTest Protocol</a></li>
<li class="toctree-l3"><a class="reference internal" href="qtest.html#libqtest-api-reference">libqtest API reference</a></li>
</ul>
</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"><a class="reference internal" href="block-coroutine-wrapper.html">block-coroutine-wrapper</a></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><a href="qtest.html">QTest Device Emulation Testing Framework</a> &raquo;</li>
 
 <li>Qtest Driver Framework</li>
 
 
 <li class="wy-breadcrumbs-aside">
 
 
 
 <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/devel/qgraph.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="qtest-driver-framework">
<h1>Qtest Driver Framework<a class="headerlink" href="#qtest-driver-framework" title="Permalink to this headline">¶</a></h1>
In order to test a specific driver, plain libqos tests need to
take care of booting QEMU with the right machine and devices.
This makes each test “hardcoded” for a specific configuration, reducing
the possible coverage that it can reach.
For example, the sdhci device is supported on both x86_64 and ARM boards,
therefore a generic sdhci test should test all machines and drivers that
support that device.
Using only libqos APIs, the test has to manually take care of
covering all the setups, and build the correct command line.
This also introduces backward compatibility issues: if a device/driver command
line name is changed, all tests that use that will not work
properly anymore and need to be adjusted.
The aim of qgraph is to create a graph of drivers, machines and tests such that
a test aimed to a certain driver does not have to care of
booting the right QEMU machine, pick the right device, build the command line
and so on. Instead, it only defines what type of device it is testing
(interface in qgraph terms) and the framework takes care of
covering all supported types of devices and machine architectures.
Following the above example, an interface would be <code class="docutils literal notranslate">sdhci</code>,
so the sdhci-test should only care of linking its qgraph node with
that interface. In this way, if the command line of a sdhci driver
is changed, only the respective qgraph driver node has to be adjusted.
<div class="section" id="qgraph-concepts">
<h2>QGraph concepts<a class="headerlink" href="#qgraph-concepts" title="Permalink to this headline">¶</a></h2>
The graph is composed by nodes that represent machines, drivers, tests
and edges that define the relationships between them (<code class="docutils literal notranslate">CONSUMES</code>, <code class="docutils literal notranslate">PRODUCES</code>, and
<code class="docutils literal notranslate">CONTAINS</code>).
<div class="section" id="nodes">
<h3>Nodes<a class="headerlink" href="#nodes" title="Permalink to this headline">¶</a></h3>
A node can be of four types:
<ul class="simple">
<li>QNODE_MACHINE: for example <code class="docutils literal notranslate">arm/raspi2b</code></li>
<li>QNODE_DRIVER: for example <code class="docutils literal notranslate">generic-sdhci</code></li>
<li>QNODE_INTERFACE: for example <code class="docutils literal notranslate">sdhci</code> (interface for all <code class="docutils literal notranslate">-sdhci</code>
drivers).
An interface is not explicitly created, it will be automatically
instantiated when a node consumes or produces it.
An interface is simply a struct that abstracts the various drivers
for the same type of device, and offers an API to the nodes that
use it (“consume” relation in qgraph terms) that is implemented/backed up by the drivers that implement it (“produce” relation in qgraph terms).</li>
<li>QNODE_TEST: for example <code class="docutils literal notranslate">sdhci-test</code>. A test consumes an interface
and tests the functions provided by it.</li>
</ul>
Notes for the nodes:
<ul class="simple">
<li>QNODE_MACHINE: each machine struct must have a <code class="docutils literal notranslate">QGuestAllocator</code> and
implement <code class="docutils literal notranslate">get_driver()</code> to return the allocator mapped to the interface
“memory”. The function can also return <code class="docutils literal notranslate">NULL</code> if the allocator
is not set.</li>
<li>QNODE_DRIVER: driver names must be unique, and machines and nodes
planned to be “consumed” by other nodes must match QEMU
drivers name, otherwise they won’t be discovered</li>
</ul>
</div>
<div class="section" id="edges">
<h3>Edges<a class="headerlink" href="#edges" title="Permalink to this headline">¶</a></h3>
An edge relation between two nodes (drivers or machines) <code class="docutils literal notranslate">X</code> and <code class="docutils literal notranslate">Y</code> can be:
<ul class="simple">
<li><code class="docutils literal notranslate">X CONSUMES Y</code>: <code class="docutils literal notranslate">Y</code> can be plugged into <code class="docutils literal notranslate">X</code></li>
<li><code class="docutils literal notranslate">X PRODUCES Y</code>: <code class="docutils literal notranslate">X</code> provides the interface <code class="docutils literal notranslate">Y</code></li>
<li><code class="docutils literal notranslate">X CONTAINS Y</code>: <code class="docutils literal notranslate">Y</code> is part of <code class="docutils literal notranslate">X</code> component</li>
</ul>
</div>
<div class="section" id="execution-steps">
<h3>Execution steps<a class="headerlink" href="#execution-steps" title="Permalink to this headline">¶</a></h3>
The basic framework steps are the following:
<ul class="simple">
<li>All nodes and edges are created in their respective
machine/driver/test files</li>
<li>The framework starts QEMU and asks for a list of available devices
and machines (note that only machines and “consumed” nodes are mapped
1:1 with QEMU devices)</li>
<li>The framework walks the graph starting from the available machines and
performs a Depth First Search for tests</li>
<li>Once a test is found, the path is walked again and all drivers are
allocated accordingly and the final interface is passed to the test</li>
<li>The test is executed</li>
<li>Unused objects are cleaned and the path discovery is continued</li>
</ul>
Depending on the QEMU binary used, only some drivers/machines will be
available and only test that are reached by them will be executed.
</div>
<div class="section" id="command-line">
<h3>Command line<a class="headerlink" href="#command-line" title="Permalink to this headline">¶</a></h3>
Command line is built by using node names and optional arguments
passed by the user when building the edges.
There are three types of command line arguments:
<ul class="simple">
<li><code class="docutils literal notranslate">in node</code> : created from the node name. For example, machines will
have <code class="docutils literal notranslate">-M &lt;machine&gt;</code> to its command line, while devices
<code class="docutils literal notranslate">-device &lt;device&gt;</code>. It is automatically done by the framework.</li>
<li><code class="docutils literal notranslate">after node</code> : added as additional argument to the node name.
This argument is added optionally when creating edges,
by setting the parameter <code class="docutils literal notranslate">after_cmd_line</code> and
<code class="docutils literal notranslate">extra_edge_opts</code> in <code class="docutils literal notranslate">QOSGraphEdgeOptions</code>.
The framework automatically adds
a comma before <code class="docutils literal notranslate">extra_edge_opts</code>,
because it is going to add attributes
after the destination node pointed by
the edge containing these options, and automatically
adds a space before <code class="docutils literal notranslate">after_cmd_line</code>, because it
adds an additional device, not an attribute.</li>
<li><code class="docutils literal notranslate">before node</code> : added as additional argument to the node name.
This argument is added optionally when creating edges,
by setting the parameter <code class="docutils literal notranslate">before_cmd_line</code> in
<code class="docutils literal notranslate">QOSGraphEdgeOptions</code>. This attribute
is going to add attributes before the destination node
pointed by the edge containing these options. It is
helpful to commands that are not node-representable,
such as <code class="docutils literal notranslate">-fdsev</code> or <code class="docutils literal notranslate">-netdev</code>.</li>
</ul>
While adding command line in edges is always used, not all nodes names are
used in every path walk: this is because the contained or produced ones
are already added by QEMU, so only nodes that “consumes” will be used to
build the command line. Also, nodes that will have <code class="docutils literal notranslate">{ &quot;abstract&quot; : true }</code>
as QMP attribute will loose their command line, since they are not proper
devices to be added in QEMU.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>QOSGraphEdgeOptions opts = {
 .before_cmd_line = &quot;-drive id=drv0,if=none,file=null-co://,&quot;
 &quot;file.read-zeroes=on,format=raw&quot;,
 .after_cmd_line = &quot;-device scsi-hd,bus=vs0.0,drive=drv0&quot;,

opts.extra_device_opts = &quot;id=vs0&quot;;
};

qos_node_create_driver(&quot;virtio-scsi-device&quot;,
 virtio_scsi_device_create);
qos_node_consumes(&quot;virtio-scsi-device&quot;, &quot;virtio-bus&quot;, &amp;opts);
</pre></div>
</div>
Will produce the following command line:
<code class="docutils literal notranslate">-drive id=drv0,if=none,file=null-co://, -device virtio-scsi-device,id=vs0 -device scsi-hd,bus=vs0.0,drive=drv0</code>
</div>
<div class="section" id="troubleshooting-unavailable-tests">
<h3>Troubleshooting unavailable tests<a class="headerlink" href="#troubleshooting-unavailable-tests" title="Permalink to this headline">¶</a></h3>
If there is no path from an available machine to a test then that test will be
unavailable and won’t execute. This can happen if a test or driver did not set
up its qgraph node correctly. It can also happen if the necessary machine type
or device is missing from the QEMU binary because it was compiled out or
otherwise.
It is possible to troubleshoot unavailable tests by running:
<div class="highlight-default notranslate"><div class="highlight"><pre>$ QTEST_QEMU_BINARY=build/qemu-system-x86_64 build/tests/qtest/qos-test --verbose
# ALL QGRAPH EDGES: {
# src=&#39;virtio-net&#39;
# |-&gt; dest=&#39;virtio-net-tests/vhost-user/multiqueue&#39; type=2 (node=0x559142109e30)
# |-&gt; dest=&#39;virtio-net-tests/vhost-user/migrate&#39; type=2 (node=0x559142109d00)
# src=&#39;virtio-net-pci&#39;
# |-&gt; dest=&#39;virtio-net&#39; type=1 (node=0x55914210d740)
# src=&#39;pci-bus&#39;
# |-&gt; dest=&#39;virtio-net-pci&#39; type=2 (node=0x55914210d880)
# src=&#39;pci-bus-pc&#39;
# |-&gt; dest=&#39;pci-bus&#39; type=1 (node=0x559142103f40)
# src=&#39;i440FX-pcihost&#39;
# |-&gt; dest=&#39;pci-bus-pc&#39; type=0 (node=0x55914210ac70)
# src=&#39;x86_64/pc&#39;
# |-&gt; dest=&#39;i440FX-pcihost&#39; type=0 (node=0x5591421117f0)
# src=&#39;&#39;
# |-&gt; dest=&#39;x86_64/pc&#39; type=0 (node=0x559142111600)
# |-&gt; dest=&#39;arm/raspi2b&#39; type=0 (node=0x559142110740)
...
# }
# ALL QGRAPH NODES: {
# name=&#39;virtio-net-tests/announce-self&#39; type=3 cmd_line=&#39;(null)&#39; [available]
# name=&#39;arm/raspi2b&#39; type=0 cmd_line=&#39;-M raspi2b &#39; [UNAVAILABLE]
...
# }
</pre></div>
</div>
The <code class="docutils literal notranslate">virtio-net-tests/announce-self</code> test is listed as “available” in the
“ALL QGRAPH NODES” output. This means the test will execute. We can follow the
qgraph path in the “ALL QGRAPH EDGES” output as follows: ‘’ -&gt; ‘x86_64/pc’ -&gt;
‘i440FX-pcihost’ -&gt; ‘pci-bus-pc’ -&gt; ‘pci-bus’ -&gt; ‘virtio-net-pci’ -&gt;
‘virtio-net’. The root of the qgraph is ‘’ and the depth first search begins
there.
The <code class="docutils literal notranslate">arm/raspi2b</code> machine node is listed as “UNAVAILABLE”. Although it is
reachable from the root via ‘’ -&gt; ‘arm/raspi2b’ the node is unavailable because
the QEMU binary did not list it when queried by the framework. This is expected
because we used the <code class="docutils literal notranslate">qemu-system-x86_64</code> binary which does not support ARM
machine types.
If a test is unexpectedly listed as “UNAVAILABLE”, first check that the “ALL
QGRAPH EDGES” output reports edge connectivity from the root (‘’) to the test.
If there is no connectivity then the qgraph nodes were not set up correctly and
the driver or test code is incorrect. If there is connectivity, check the
availability of each node in the path in the “ALL QGRAPH NODES” output. The
first unavailable node in the path is the reason why the test is unavailable.
Typically this is because the QEMU binary lacks support for the necessary
machine type or device.
</div>
</div>
<div class="section" id="creating-a-new-driver-and-its-interface">
<h2>Creating a new driver and its interface<a class="headerlink" href="#creating-a-new-driver-and-its-interface" title="Permalink to this headline">¶</a></h2>
Here we continue the <code class="docutils literal notranslate">sdhci</code> use case, with the following scenario:
<ul class="simple">
<li><code class="docutils literal notranslate">sdhci-test</code> aims to test the <code class="docutils literal notranslate">read[q,w], writeq</code> functions
offered by the <code class="docutils literal notranslate">sdhci</code> drivers.</li>
<li>The current <code class="docutils literal notranslate">sdhci</code> device is supported by both <code class="docutils literal notranslate">x86_64/pc</code> and <code class="docutils literal notranslate">ARM</code>
(in this example we focus on the <code class="docutils literal notranslate">arm-raspi2b</code>) machines.</li>
<li>QEMU offers 2 types of drivers: <code class="docutils literal notranslate">QSDHCI_MemoryMapped</code> for <code class="docutils literal notranslate">ARM</code> and
<code class="docutils literal notranslate">QSDHCI_PCI</code> for <code class="docutils literal notranslate">x86_64/pc</code>. Both implement the
<code class="docutils literal notranslate">read[q,w], writeq</code> functions.</li>
</ul>
In order to implement such scenario in qgraph, the test developer needs to:
<ul>
<li>Create the <code class="docutils literal notranslate">x86_64/pc</code> machine node. This machine uses the
<code class="docutils literal notranslate">pci-bus</code> architecture so it <code class="docutils literal notranslate">contains</code> a PCI driver,
<code class="docutils literal notranslate">pci-bus-pc</code>. The actual path is
<code class="docutils literal notranslate">x86_64/pc --contains--&gt; 1440FX-pcihost --contains--&gt;
pci-bus-pc --produces--&gt; pci-bus</code>.
For the sake of this example,
we do not focus on the PCI interface implementation.
</li>
<li>Create the <code class="docutils literal notranslate">sdhci-pci</code> driver node, representing <code class="docutils literal notranslate">QSDHCI_PCI</code>.
The driver uses the PCI bus (and its API),
so it must <code class="docutils literal notranslate">consume</code> the <code class="docutils literal notranslate">pci-bus</code> generic interface (which abstracts
all the pci drivers available)
<code class="docutils literal notranslate">sdhci-pci --consumes--&gt; pci-bus</code>
</li>
<li>Create an <code class="docutils literal notranslate">arm/raspi2b</code> machine node. This machine <code class="docutils literal notranslate">contains</code>
a <code class="docutils literal notranslate">generic-sdhci</code> memory mapped <code class="docutils literal notranslate">sdhci</code> driver node, representing
<code class="docutils literal notranslate">QSDHCI_MemoryMapped</code>.
<code class="docutils literal notranslate">arm/raspi2b --contains--&gt; generic-sdhci</code>
</li>
<li>Create the <code class="docutils literal notranslate">sdhci</code> interface node. This interface offers the
functions that are shared by all <code class="docutils literal notranslate">sdhci</code> devices.
The interface is produced by <code class="docutils literal notranslate">sdhci-pci</code> and <code class="docutils literal notranslate">generic-sdhci</code>,
the available architecture-specific drivers.
<code class="docutils literal notranslate">sdhci-pci --produces--&gt; sdhci</code>
<code class="docutils literal notranslate">generic-sdhci --produces--&gt; sdhci</code>
</li>
<li>Create the <code class="docutils literal notranslate">sdhci-test</code> test node. The test <code class="docutils literal notranslate">consumes</code> the
<code class="docutils literal notranslate">sdhci</code> interface, using its API. It doesn’t need to look at
the supported machines or drivers.
<code class="docutils literal notranslate">sdhci-test --consumes--&gt; sdhci</code>
</li>
</ul>
<code class="docutils literal notranslate">arm-raspi2b</code> machine, simplified from
<code class="docutils literal notranslate">tests/qtest/libqos/arm-raspi2-machine.c</code>:
<div class="highlight-default notranslate"><div class="highlight"><pre>#include &quot;qgraph.h&quot;

struct QRaspi2Machine {
    QOSGraphObject obj;
    QGuestAllocator alloc;
    QSDHCI_MemoryMapped sdhci;
};

static void *raspi2_get_driver(void *object, const char *interface)
{
    QRaspi2Machine *machine = object;
    if (!g_strcmp0(interface, &quot;memory&quot;)) {
        return &amp;machine-&gt;alloc;
    }

fprintf(stderr, &quot;%s not present in arm/raspi2b\n&quot;, interface);
    g_assert_not_reached();
}

static QOSGraphObject *raspi2_get_device(void *obj,
                                            const char *device)
{
    QRaspi2Machine *machine = obj;
    if (!g_strcmp0(device, &quot;generic-sdhci&quot;)) {
        return &amp;machine-&gt;sdhci.obj;
    }

fprintf(stderr, &quot;%s not present in arm/raspi2b\n&quot;, device);
    g_assert_not_reached();
}

static void *qos_create_machine_arm_raspi2(QTestState *qts)
{
    QRaspi2Machine *machine = g_new0(QRaspi2Machine, 1);

alloc_init(&amp;machine-&gt;alloc, ...);

/* Get node(s) contained inside (CONTAINS) */
    machine-&gt;obj.get_device = raspi2_get_device;

/* Get node(s) produced (PRODUCES) */
    machine-&gt;obj.get_driver = raspi2_get_driver;

/* free the object */
    machine-&gt;obj.destructor = raspi2_destructor;
    qos_init_sdhci_mm(&amp;machine-&gt;sdhci, ...);
    return &amp;machine-&gt;obj;
}

static void raspi2_register_nodes(void)
{
    /* arm/raspi2b --contains--&gt; generic-sdhci */
    qos_node_create_machine(&quot;arm/raspi2b&quot;,
                             qos_create_machine_arm_raspi2);
    qos_node_contains(&quot;arm/raspi2b&quot;, &quot;generic-sdhci&quot;, NULL);
}

libqos_init(raspi2_register_nodes);
</pre></div>
</div>
<code class="docutils literal notranslate">x86_64/pc</code> machine, simplified from
<code class="docutils literal notranslate">tests/qtest/libqos/x86_64_pc-machine.c</code>:
<div class="highlight-default notranslate"><div class="highlight"><pre>#include &quot;qgraph.h&quot;

struct i440FX_pcihost {
    QOSGraphObject obj;
    QPCIBusPC pci;
};

struct QX86PCMachine {
    QOSGraphObject obj;
    QGuestAllocator alloc;
    i440FX_pcihost bridge;
};

/* i440FX_pcihost */

static QOSGraphObject *i440FX_host_get_device(void *obj,
                                            const char *device)
{
    i440FX_pcihost *host = obj;
    if (!g_strcmp0(device, &quot;pci-bus-pc&quot;)) {
        return &amp;host-&gt;pci.obj;
    }
    fprintf(stderr, &quot;%s not present in i440FX-pcihost\n&quot;, device);
    g_assert_not_reached();
}

/* x86_64/pc machine */

static void *pc_get_driver(void *object, const char *interface)
{
    QX86PCMachine *machine = object;
    if (!g_strcmp0(interface, &quot;memory&quot;)) {
        return &amp;machine-&gt;alloc;
    }

fprintf(stderr, &quot;%s not present in x86_64/pc\n&quot;, interface);
    g_assert_not_reached();
}

static QOSGraphObject *pc_get_device(void *obj, const char *device)
{
    QX86PCMachine *machine = obj;
    if (!g_strcmp0(device, &quot;i440FX-pcihost&quot;)) {
        return &amp;machine-&gt;bridge.obj;
    }

fprintf(stderr, &quot;%s not present in x86_64/pc\n&quot;, device);
    g_assert_not_reached();
}

static void *qos_create_machine_pc(QTestState *qts)
{
    QX86PCMachine *machine = g_new0(QX86PCMachine, 1);

/* Get node(s) contained inside (CONTAINS) */
    machine-&gt;obj.get_device = pc_get_device;

/* Get node(s) produced (PRODUCES) */
    machine-&gt;obj.get_driver = pc_get_driver;

/* free the object */
    machine-&gt;obj.destructor = pc_destructor;
    pc_alloc_init(&amp;machine-&gt;alloc, qts, ALLOC_NO_FLAGS);

/* Get node(s) contained inside (CONTAINS) */
    machine-&gt;bridge.obj.get_device = i440FX_host_get_device;

return &amp;machine-&gt;obj;
}

static void pc_machine_register_nodes(void)
{
    /* x86_64/pc --contains--&gt; 1440FX-pcihost --contains--&gt;
     * pci-bus-pc [--produces--&gt; pci-bus (in pci.h)] */
    qos_node_create_machine(&quot;x86_64/pc&quot;, qos_create_machine_pc);
    qos_node_contains(&quot;x86_64/pc&quot;, &quot;i440FX-pcihost&quot;, NULL);

/* contained drivers don&#39;t need a constructor,
     * they will be init by the parent */
    qos_node_create_driver(&quot;i440FX-pcihost&quot;, NULL);
    qos_node_contains(&quot;i440FX-pcihost&quot;, &quot;pci-bus-pc&quot;, NULL);
}

libqos_init(pc_machine_register_nodes);
</pre></div>
</div>
<code class="docutils literal notranslate">sdhci</code> taken from <code class="docutils literal notranslate">tests/qtest/libqos/sdhci.c</code>:
<div class="highlight-default notranslate"><div class="highlight"><pre>/* Interface node, offers the sdhci API */
struct QSDHCI {
 uint16_t (*readw)(QSDHCI *s, uint32_t reg);
 uint64_t (*readq)(QSDHCI *s, uint32_t reg);
 void (*writeq)(QSDHCI *s, uint32_t reg, uint64_t val);
 /* other fields */
};

/* Memory Mapped implementation of QSDHCI */
struct QSDHCI_MemoryMapped {
    QOSGraphObject obj;
    QSDHCI sdhci;
    /* other driver-specific fields */
};

/* PCI implementation of QSDHCI */
struct QSDHCI_PCI {
    QOSGraphObject obj;
    QSDHCI sdhci;
    /* other driver-specific fields */
};

/* Memory mapped implementation of QSDHCI */

static void *sdhci_mm_get_driver(void *obj, const char *interface)
{
    QSDHCI_MemoryMapped *smm = obj;
    if (!g_strcmp0(interface, &quot;sdhci&quot;)) {
        return &amp;smm-&gt;sdhci;
    }
    fprintf(stderr, &quot;%s not present in generic-sdhci\n&quot;, interface);
    g_assert_not_reached();
}

void qos_init_sdhci_mm(QSDHCI_MemoryMapped *sdhci, QTestState *qts,
                    uint32_t addr, QSDHCIProperties *common)
{
    /* Get node contained inside (CONTAINS) */
    sdhci-&gt;obj.get_driver = sdhci_mm_get_driver;

/* SDHCI interface API */
    sdhci-&gt;sdhci.readw = sdhci_mm_readw;
    sdhci-&gt;sdhci.readq = sdhci_mm_readq;
    sdhci-&gt;sdhci.writeq = sdhci_mm_writeq;
    sdhci-&gt;qts = qts;
}

/* PCI implementation of QSDHCI */

static void *sdhci_pci_get_driver(void *object,
                                  const char *interface)
{
    QSDHCI_PCI *spci = object;
    if (!g_strcmp0(interface, &quot;sdhci&quot;)) {
        return &amp;spci-&gt;sdhci;
    }

fprintf(stderr, &quot;%s not present in sdhci-pci\n&quot;, interface);
    g_assert_not_reached();
}

static void *sdhci_pci_create(void *pci_bus,
                              QGuestAllocator *alloc,
                              void *addr)
{
    QSDHCI_PCI *spci = g_new0(QSDHCI_PCI, 1);
    QPCIBus *bus = pci_bus;
    uint64_t barsize;

qpci_device_init(&amp;spci-&gt;dev, bus, addr);

/* SDHCI interface API */
    spci-&gt;sdhci.readw = sdhci_pci_readw;
    spci-&gt;sdhci.readq = sdhci_pci_readq;
    spci-&gt;sdhci.writeq = sdhci_pci_writeq;

/* Get node(s) produced (PRODUCES) */
    spci-&gt;obj.get_driver = sdhci_pci_get_driver;

spci-&gt;obj.start_hw = sdhci_pci_start_hw;
    spci-&gt;obj.destructor = sdhci_destructor;
    return &amp;spci-&gt;obj;
}

static void qsdhci_register_nodes(void)
{
    QOSGraphEdgeOptions opts = {
        .extra_device_opts = &quot;addr=04.0&quot;,
    };

/* generic-sdhci */
    /* generic-sdhci --produces--&gt; sdhci */
    qos_node_create_driver(&quot;generic-sdhci&quot;, NULL);
    qos_node_produces(&quot;generic-sdhci&quot;, &quot;sdhci&quot;);

/* sdhci-pci */
    /* sdhci-pci --produces--&gt; sdhci
     * sdhci-pci --consumes--&gt; pci-bus */
    qos_node_create_driver(&quot;sdhci-pci&quot;, sdhci_pci_create);
    qos_node_produces(&quot;sdhci-pci&quot;, &quot;sdhci&quot;);
    qos_node_consumes(&quot;sdhci-pci&quot;, &quot;pci-bus&quot;, &amp;opts);
}

libqos_init(qsdhci_register_nodes);
</pre></div>
</div>
In the above example, all possible types of relations are created:
<div class="highlight-default notranslate"><div class="highlight"><pre>x86_64/pc --contains--&gt; 1440FX-pcihost --contains--&gt; pci-bus-pc
 |
 sdhci-pci --consumes--&gt; pci-bus &lt;--produces--+
 |
 +--produces--+
 |
 v
 sdhci
 ^
 |
 +--produces-- +
 |
 arm/raspi2b --contains--&gt; generic-sdhci
</pre></div>
</div>
or inverting the consumes edge in consumed_by:
<div class="highlight-default notranslate"><div class="highlight"><pre>x86_64/pc --contains--&gt; 1440FX-pcihost --contains--&gt; pci-bus-pc
 |
 sdhci-pci &lt;--consumed by-- pci-bus &lt;--produces--+
 |
 +--produces--+
 |
 v
 sdhci
 ^
 |
 +--produces-- +
 |
 arm/raspi2b --contains--&gt; generic-sdhci
</pre></div>
</div>
</div>
<div class="section" id="adding-a-new-test">
<h2>Adding a new test<a class="headerlink" href="#adding-a-new-test" title="Permalink to this headline">¶</a></h2>
Given the above setup, adding a new test is very simple.
<code class="docutils literal notranslate">sdhci-test</code>, taken from <code class="docutils literal notranslate">tests/qtest/sdhci-test.c</code>:
<div class="highlight-default notranslate"><div class="highlight"><pre>static void check_capab_sdma(QSDHCI *s, bool supported)
{
 uint64_t capab, capab_sdma;

capab = s-&gt;readq(s, SDHC_CAPAB);
 capab_sdma = FIELD_EX64(capab, SDHC_CAPAB, SDMA);
 g_assert_cmpuint(capab_sdma, ==, supported);
}

static void test_registers(void *obj, void *data,
 QGuestAllocator *alloc)
{
 QSDHCI *s = obj;

/* example test */
 check_capab_sdma(s, s-&gt;props.capab.sdma);
}

static void register_sdhci_test(void)
{
 /* sdhci-test --consumes--&gt; sdhci */
 qos_add_test(&quot;registers&quot;, &quot;sdhci&quot;, test_registers, NULL);
}

libqos_init(register_sdhci_test);
</pre></div>
</div>
Here a new test is created, consuming <code class="docutils literal notranslate">sdhci</code> interface node
and creating a valid path from both machines to a test.
Final graph will be like this:
<div class="highlight-default notranslate"><div class="highlight"><pre>x86_64/pc --contains--&gt; 1440FX-pcihost --contains--&gt; pci-bus-pc
 |
 sdhci-pci --consumes--&gt; pci-bus &lt;--produces--+
 |
 +--produces--+
 |
 v
 sdhci &lt;--consumes-- sdhci-test
 ^
 |
 +--produces-- +
 |
 arm/raspi2b --contains--&gt; generic-sdhci
</pre></div>
</div>
or inverting the consumes edge in consumed_by:
<div class="highlight-default notranslate"><div class="highlight"><pre>x86_64/pc --contains--&gt; 1440FX-pcihost --contains--&gt; pci-bus-pc
 |
 sdhci-pci &lt;--consumed by-- pci-bus &lt;--produces--+
 |
 +--produces--+
 |
 v
 sdhci --consumed by--&gt; sdhci-test
 ^
 |
 +--produces-- +
 |
 arm/raspi2b --contains--&gt; generic-sdhci
</pre></div>
</div>
Assuming there the binary is
<code class="docutils literal notranslate">QTEST_QEMU_BINARY=./qemu-system-x86_64</code>
a valid test path will be:
<code class="docutils literal notranslate">/x86_64/pc/1440FX-pcihost/pci-bus-pc/pci-bus/sdhci-pc/sdhci/sdhci-test</code>
and for the binary <code class="docutils literal notranslate">QTEST_QEMU_BINARY=./qemu-system-arm</code>:
<code class="docutils literal notranslate">/arm/raspi2b/generic-sdhci/sdhci/sdhci-test</code>
Additional examples are also in <code class="docutils literal notranslate">test-qgraph.c</code>
</div>
<div class="section" id="qgraph-api-reference">
<h2>Qgraph API reference<a class="headerlink" href="#qgraph-api-reference" title="Permalink to this headline">¶</a></h2>
<dl class="type">
<dt id="c.QOSGraphEdgeOptions">
struct <code class="descname">QOSGraphEdgeOptions</code><a class="headerlink" href="#c.QOSGraphEdgeOptions" title="Permalink to this definition">¶</a></dt>
<dd>Edge options to be passed to the contains/consumes *_args function.
</dd></dl>

Definition
<div class="highlight-default notranslate"><div class="highlight"><pre>struct QOSGraphEdgeOptions {
 void *arg;
 uint32_t size_arg;
 const char *extra_device_opts;
 const char *before_cmd_line;
 const char *after_cmd_line;
 const char *edge_name;
};
</pre></div>
</div>
Members
<dl class="docutils">
<dt><code class="docutils literal notranslate">arg</code></dt>
<dd>optional arg that will be used by dest edge</dd>
<dt><code class="docutils literal notranslate">size_arg</code></dt>
<dd>arg size that will be used by dest edge</dd>
<dt><code class="docutils literal notranslate">extra_device_opts</code></dt>
<dd>optional additional command line for dest
edge, used to add additional attributes
after the node command line, the
framework automatically prepends “,”
to this argument.</dd>
<dt><code class="docutils literal notranslate">before_cmd_line</code></dt>
<dd>optional additional command line for dest
edge, used to add additional attributes
before the node command line, usually
other non-node represented commands,
like “-fdsev synt”</dd>
<dt><code class="docutils literal notranslate">after_cmd_line</code></dt>
<dd>optional extra command line to be added
after the device command. This option
is used to add other devices
command line that depend on current node.
Automatically prepends ” ” to this argument</dd>
<dt><code class="docutils literal notranslate">edge_name</code></dt>
<dd>optional edge to differentiate multiple
devices with same node name</dd>
</dl>
<dl class="type">
<dt id="c.QOSGraphTestOptions">
struct <code class="descname">QOSGraphTestOptions</code><a class="headerlink" href="#c.QOSGraphTestOptions" title="Permalink to this definition">¶</a></dt>
<dd>Test options to be passed to the test functions.
</dd></dl>

Definition
<div class="highlight-default notranslate"><div class="highlight"><pre>struct QOSGraphTestOptions {
 QOSGraphEdgeOptions edge;
 void *arg;
 QOSBeforeTest before;
 bool subprocess;
};
</pre></div>
</div>
Members
<dl class="docutils">
<dt><code class="docutils literal notranslate">edge</code></dt>
<dd>edge arguments that will be used by test.
Note that test does not use edge_name,
and uses instead arg and size_arg as
data arg for its test function.</dd>
<dt><code class="docutils literal notranslate">arg</code></dt>
<dd>if before is non-NULL, pass arg there.
Otherwise pass it to the test function.</dd>
<dt><code class="docutils literal notranslate">before</code></dt>
<dd>executed before the test. Used to add
additional parameters to the command line
and modify the argument to the test function.</dd>
<dt><code class="docutils literal notranslate">subprocess</code></dt>
<dd>run the test in a subprocess.</dd>
</dl>
<dl class="type">
<dt id="c.QOSGraphObject">
struct <code class="descname">QOSGraphObject</code><a class="headerlink" href="#c.QOSGraphObject" title="Permalink to this definition">¶</a></dt>
<dd>Each driver, test or machine of this framework will have a QOSGraphObject as first field.
</dd></dl>

Definition
<div class="highlight-default notranslate"><div class="highlight"><pre>struct QOSGraphObject {
 QOSGetDriver get_driver;
 QOSGetDevice get_device;
 QOSStartFunct start_hw;
 QOSDestructorFunc destructor;
 GDestroyNotify free;
};
</pre></div>
</div>
Members
<dl class="docutils">
<dt><code class="docutils literal notranslate">get_driver</code></dt>
<dd>see get_device</dd>
<dt><code class="docutils literal notranslate">get_device</code></dt>
<dd>Once a machine-to-test path has been
found, the framework traverses it again and allocates all the
nodes, using the provided constructor. To satisfy their
relations, i.e. for produces or contains, where a struct
constructor needs an external parameter represented by the
previous node, the framework will call
get_device (for contains) or get_driver (for produces),
depending on the edge type, passing them the name of the next
node to be taken and getting from them the corresponding
pointer to the actual structure of the next node to
be used in the path.</dd>
<dt><code class="docutils literal notranslate">start_hw</code></dt>
<dd>This function is executed after all the path objects
have been allocated, but before the test is run. It starts the
hw, setting the initial configurations (*_device_enable) and
making it ready for the test.</dd>
<dt><code class="docutils literal notranslate">destructor</code></dt>
<dd>Opposite to the node constructor, destroys the object.
This function is called after the test has been executed, and
performs a complete cleanup of each node allocated field.
In case no constructor is provided, no destructor will be
called.</dd>
<dt><code class="docutils literal notranslate">free</code></dt>
<dd>free the memory associated to the QOSGraphObject and its contained
children</dd>
</dl>
Description
This set of functions offered by QOSGraphObject are executed
in different stages of the framework:
<dl class="function">
<dt id="c.qos_graph_init">
void <code class="descname">qos_graph_init</code>(void)<a class="headerlink" href="#c.qos_graph_init" title="Permalink to this definition">¶</a></dt>
<dd>initialize the framework, creates two hash tables: one for the nodes and another for the edges.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">void</code></dt>
<dd>no arguments</dd>
</dl>
<dl class="function">
<dt id="c.qos_graph_destroy">
void <code class="descname">qos_graph_destroy</code>(void)<a class="headerlink" href="#c.qos_graph_destroy" title="Permalink to this definition">¶</a></dt>
<dd>deallocates all the hash tables, freeing all nodes and edges.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">void</code></dt>
<dd>no arguments</dd>
</dl>
<dl class="function">
<dt id="c.qos_node_destroy">
void <code class="descname">qos_node_destroy</code>(void&nbsp;*key)<a class="headerlink" href="#c.qos_node_destroy" title="Permalink to this definition">¶</a></dt>
<dd>removes and frees a node from the nodes hash table.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">void *key</code></dt>
<dd>Name of the node</dd>
</dl>
<dl class="function">
<dt id="c.qos_edge_destroy">
void <code class="descname">qos_edge_destroy</code>(void&nbsp;*key)<a class="headerlink" href="#c.qos_edge_destroy" title="Permalink to this definition">¶</a></dt>
<dd>removes and frees an edge from the edges hash table.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">void *key</code></dt>
<dd>Name of the node</dd>
</dl>
<dl class="function">
<dt id="c.qos_add_test">
void <code class="descname">qos_add_test</code>(const char&nbsp;*name, const char&nbsp;*interface, QOSTestFunc&nbsp;test_func, <a class="reference internal" href="#c.QOSGraphTestOptions" title="QOSGraphTestOptions">QOSGraphTestOptions</a>&nbsp;*opts)<a class="headerlink" href="#c.qos_add_test" title="Permalink to this definition">¶</a></dt>
<dd>adds a test node name to the nodes hash table.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">const char *name</code></dt>
<dd>Name of the test</dd>
<dt><code class="docutils literal notranslate">const char *interface</code></dt>
<dd>Name of the interface node it consumes</dd>
<dt><code class="docutils literal notranslate">QOSTestFunc test_func</code></dt>
<dd>Actual test to perform</dd>
<dt><code class="docutils literal notranslate">QOSGraphTestOptions *opts</code></dt>
<dd>Facultative options (see <code class="docutils literal notranslate">QOSGraphTestOptions</code>)</dd>
</dl>
Description
The test will consume a interface node, and once the
graph walking algorithm has found it, the test_func will be
executed. It also has the possibility to
add an optional opts (see <code class="docutils literal notranslate">QOSGraphTestOptions</code>).
For tests, opts-&gt;edge.arg and size_arg represent the arg to pass
to test_func
<dl class="function">
<dt id="c.qos_node_create_machine">
void <code class="descname">qos_node_create_machine</code>(const char&nbsp;*name, QOSCreateMachineFunc&nbsp;function)<a class="headerlink" href="#c.qos_node_create_machine" title="Permalink to this definition">¶</a></dt>
<dd>creates the machine name and adds it to the node hash table.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">const char *name</code></dt>
<dd>Name of the machine</dd>
<dt><code class="docutils literal notranslate">QOSCreateMachineFunc function</code></dt>
<dd>Machine constructor</dd>
</dl>
Description
This node will be of type QNODE_MACHINE and have function
as constructor
<dl class="function">
<dt id="c.qos_node_create_machine_args">
void <code class="descname">qos_node_create_machine_args</code>(const char&nbsp;*name, QOSCreateMachineFunc&nbsp;function, const char&nbsp;*opts)<a class="headerlink" href="#c.qos_node_create_machine_args" title="Permalink to this definition">¶</a></dt>
<dd>same as qos_node_create_machine, but with the possibility to add an optional “, opts” after -M machine command line.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">const char *name</code></dt>
<dd>Name of the machine</dd>
<dt><code class="docutils literal notranslate">QOSCreateMachineFunc function</code></dt>
<dd>Machine constructor</dd>
<dt><code class="docutils literal notranslate">const char *opts</code></dt>
<dd>Optional additional command line</dd>
</dl>
<dl class="function">
<dt id="c.qos_node_create_driver">
void <code class="descname">qos_node_create_driver</code>(const char&nbsp;*name, QOSCreateDriverFunc&nbsp;function)<a class="headerlink" href="#c.qos_node_create_driver" title="Permalink to this definition">¶</a></dt>
<dd>creates the driver name and adds it to the node hash table.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">const char *name</code></dt>
<dd>Name of the driver</dd>
<dt><code class="docutils literal notranslate">QOSCreateDriverFunc function</code></dt>
<dd>Driver constructor</dd>
</dl>
Description
This node will be of type QNODE_DRIVER and have function
as constructor
<dl class="function">
<dt id="c.qos_node_create_driver_named">
void <code class="descname">qos_node_create_driver_named</code>(const char&nbsp;*name, const char&nbsp;*qemu_name, QOSCreateDriverFunc&nbsp;function)<a class="headerlink" href="#c.qos_node_create_driver_named" title="Permalink to this definition">¶</a></dt>
<dd>behaves as qos_node_create_driver() with the extension of allowing to specify a different node name vs. associated QEMU device name.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">const char *name</code></dt>
<dd>Custom, unique name of the node to be created</dd>
<dt><code class="docutils literal notranslate">const char *qemu_name</code></dt>
<dd>Actual (official) QEMU driver name the node shall be
associated with</dd>
<dt><code class="docutils literal notranslate">QOSCreateDriverFunc function</code></dt>
<dd>Driver constructor</dd>
</dl>
Description
Use this function instead of qos_node_create_driver() if you need to create
several instances of the same QEMU device. You are free to choose a custom
node name, however the chosen node name must always be unique.
<dl class="function">
<dt id="c.qos_node_contains">
void <code class="descname">qos_node_contains</code>(const char&nbsp;*container, const char&nbsp;*contained, <a class="reference internal" href="#c.QOSGraphEdgeOptions" title="QOSGraphEdgeOptions">QOSGraphEdgeOptions</a>&nbsp;*opts, ...)<a class="headerlink" href="#c.qos_node_contains" title="Permalink to this definition">¶</a></dt>
<dd>creates one or more edges of type QEDGE_CONTAINS and adds them to the edge list mapped to container in the edge hash table.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">const char *container</code></dt>
<dd>Source node that “contains”</dd>
<dt><code class="docutils literal notranslate">const char *contained</code></dt>
<dd>Destination node that “is contained”</dd>
<dt><code class="docutils literal notranslate">QOSGraphEdgeOptions *opts</code></dt>
<dd>Facultative options (see <code class="docutils literal notranslate">QOSGraphEdgeOptions</code>)</dd>
<dt><code class="docutils literal notranslate">...</code></dt>
<dd>variable arguments</dd>
</dl>
Description
The edges will have container as source and contained as destination.
If opts is NULL, a single edge will be added with no options.
If opts is non-NULL, the arguments after contained represent a
NULL-terminated list of <code class="docutils literal notranslate">QOSGraphEdgeOptions</code> structs, and an
edge will be added for each of them.
This function can be useful when there are multiple devices
with the same node name contained in a machine/other node
For example, if <code class="docutils literal notranslate">arm/raspi2b</code> contains 2 <code class="docutils literal notranslate">generic-sdhci</code>
devices, the right commands will be:
<div class="code highlight-default notranslate"><div class="highlight"><pre>qos_node_create_machine(&quot;arm/raspi2b&quot;);
qos_node_create_driver(&quot;generic-sdhci&quot;, constructor);
// assume rest of the fields are set NULL
QOSGraphEdgeOptions op1 = { .edge_name = &quot;emmc&quot; };
QOSGraphEdgeOptions op2 = { .edge_name = &quot;sdcard&quot; };
qos_node_contains(&quot;arm/raspi2b&quot;, &quot;generic-sdhci&quot;, &amp;op1, &amp;op2, NULL);
</pre></div>
</div>
Of course this also requires that the container’s get_device function
should implement a case for “emmc” and “sdcard”.
For contains, op1.arg and op1.size_arg represent the arg to pass
to contained constructor to properly initialize it.
<dl class="function">
<dt id="c.qos_node_produces">
void <code class="descname">qos_node_produces</code>(const char&nbsp;*producer, const char&nbsp;*interface)<a class="headerlink" href="#c.qos_node_produces" title="Permalink to this definition">¶</a></dt>
<dd>creates an edge of type QEDGE_PRODUCES and adds it to the edge list mapped to producer in the edge hash table.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">const char *producer</code></dt>
<dd>Source node that “produces”</dd>
<dt><code class="docutils literal notranslate">const char *interface</code></dt>
<dd>Interface node that “is produced”</dd>
</dl>
Description
This edge will have producer as source and interface as destination.
<dl class="function">
<dt id="c.qos_node_consumes">
void <code class="descname">qos_node_consumes</code>(const char&nbsp;*consumer, const char&nbsp;*interface, <a class="reference internal" href="#c.QOSGraphEdgeOptions" title="QOSGraphEdgeOptions">QOSGraphEdgeOptions</a>&nbsp;*opts)<a class="headerlink" href="#c.qos_node_consumes" title="Permalink to this definition">¶</a></dt>
<dd>creates an edge of type QEDGE_CONSUMED_BY and adds it to the edge list mapped to interface in the edge hash table.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">const char *consumer</code></dt>
<dd>Node that “consumes”</dd>
<dt><code class="docutils literal notranslate">const char *interface</code></dt>
<dd>Interface node that “is consumed by”</dd>
<dt><code class="docutils literal notranslate">QOSGraphEdgeOptions *opts</code></dt>
<dd>Facultative options (see <code class="docutils literal notranslate">QOSGraphEdgeOptions</code>)</dd>
</dl>
Description
This edge will have interface as source and consumer as destination.
It also has the possibility to add an optional opts
(see <code class="docutils literal notranslate">QOSGraphEdgeOptions</code>)
<dl class="function">
<dt id="c.qos_invalidate_command_line">
void <code class="descname">qos_invalidate_command_line</code>(void)<a class="headerlink" href="#c.qos_invalidate_command_line" title="Permalink to this definition">¶</a></dt>
<dd>invalidates current command line, so that qgraph framework cannot try to cache the current command line and forces QEMU to restart.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">void</code></dt>
<dd>no arguments</dd>
</dl>
<dl class="function">
<dt id="c.qos_get_current_command_line">
const char * <code class="descname">qos_get_current_command_line</code>(void)<a class="headerlink" href="#c.qos_get_current_command_line" title="Permalink to this definition">¶</a></dt>
<dd>return the command line required by the machine and driver objects. This is the same string that was passed to the test’s “before” callback, if any.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">void</code></dt>
<dd>no arguments</dd>
</dl>
<dl class="function">
<dt id="c.qos_allocate_objects">
void * <code class="descname">qos_allocate_objects</code>(QTestState&nbsp;*qts, QGuestAllocator&nbsp;**p_alloc)<a class="headerlink" href="#c.qos_allocate_objects" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">QTestState *qts</code></dt>
<dd>The <code class="xref c c-type docutils literal notranslate">QTestState</code> that will be referred to by the machine object.</dd>
<dt><code class="docutils literal notranslate">QGuestAllocator **p_alloc</code></dt>
<dd>Where to store the allocator for the machine object, or <code class="docutils literal notranslate">NULL</code>.</dd>
</dl>
Description
Allocate driver objects for the current test
path, but relative to the QTestState qts.
Returns a test object just like the one that was passed to
the test function, but relative to qts.
<dl class="function">
<dt id="c.qos_object_destroy">
void <code class="descname">qos_object_destroy</code>(<a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject">QOSGraphObject</a>&nbsp;*obj)<a class="headerlink" href="#c.qos_object_destroy" title="Permalink to this definition">¶</a></dt>
<dd>calls the destructor for obj
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">QOSGraphObject *obj</code></dt>
<dd>A <a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject"><code class="xref c c-type docutils literal notranslate">QOSGraphObject</code></a> to destroy</dd>
</dl>
<dl class="function">
<dt id="c.qos_object_queue_destroy">
void <code class="descname">qos_object_queue_destroy</code>(<a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject">QOSGraphObject</a>&nbsp;*obj)<a class="headerlink" href="#c.qos_object_queue_destroy" title="Permalink to this definition">¶</a></dt>
<dd>queue the destructor for obj so that it is called at the end of the test
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">QOSGraphObject *obj</code></dt>
<dd>A <a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject"><code class="xref c c-type docutils literal notranslate">QOSGraphObject</code></a> to destroy</dd>
</dl>
<dl class="function">
<dt id="c.qos_object_start_hw">
void <code class="descname">qos_object_start_hw</code>(<a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject">QOSGraphObject</a>&nbsp;*obj)<a class="headerlink" href="#c.qos_object_start_hw" title="Permalink to this definition">¶</a></dt>
<dd>calls the start_hw function for obj
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">QOSGraphObject *obj</code></dt>
<dd>A <a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject"><code class="xref c c-type docutils literal notranslate">QOSGraphObject</code></a> containing the start_hw function</dd>
</dl>
<dl class="function">
<dt id="c.qos_machine_new">
<a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject">QOSGraphObject</a> * <code class="descname">qos_machine_new</code>(QOSGraphNode&nbsp;*node, QTestState&nbsp;*qts)<a class="headerlink" href="#c.qos_machine_new" title="Permalink to this definition">¶</a></dt>
<dd>instantiate a new machine node
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">QOSGraphNode *node</code></dt>
<dd>Machine node to be instantiated</dd>
<dt><code class="docutils literal notranslate">QTestState *qts</code></dt>
<dd>A <code class="xref c c-type docutils literal notranslate">QTestState</code> that will be referred to by the machine object.</dd>
</dl>
Description
Returns a machine object.
<dl class="function">
<dt id="c.qos_driver_new">
<a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject">QOSGraphObject</a> * <code class="descname">qos_driver_new</code>(QOSGraphNode&nbsp;*node, <a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject">QOSGraphObject</a>&nbsp;*parent, QGuestAllocator&nbsp;*alloc, void&nbsp;*arg)<a class="headerlink" href="#c.qos_driver_new" title="Permalink to this definition">¶</a></dt>
<dd>instantiate a new driver node
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">QOSGraphNode *node</code></dt>
<dd>A driver node to be instantiated</dd>
<dt><code class="docutils literal notranslate">QOSGraphObject *parent</code></dt>
<dd>A <a class="reference internal" href="#c.QOSGraphObject" title="QOSGraphObject"><code class="xref c c-type docutils literal notranslate">QOSGraphObject</code></a> to be consumed by the new driver node</dd>
<dt><code class="docutils literal notranslate">QGuestAllocator *alloc</code></dt>
<dd>An allocator to be used by the new driver node.</dd>
<dt><code class="docutils literal notranslate">void *arg</code></dt>
<dd>The argument for the consumed-by edge to node.</dd>
</dl>
Description
Calls the constructor for the driver object.
<dl class="function">
<dt id="c.qos_dump_graph">
void <code class="descname">qos_dump_graph</code>(void)<a class="headerlink" href="#c.qos_dump_graph" title="Permalink to this definition">¶</a></dt>
<dd>prints all currently existing nodes and edges to stdout. Just for debugging purposes.
</dd></dl>

Parameters
<dl class="docutils">
<dt><code class="docutils literal notranslate">void</code></dt>
<dd>no arguments</dd>
</dl>
Description
All qtests add themselves to the overall qos graph by calling qgraph
functions that add device nodes and edges between the individual graph
nodes for tests. As the actual graph is assmbled at runtime by the qos
subsystem, it is sometimes not obvious how the overall graph looks like.
E.g. when writing new tests it may happen that those new tests are simply
ignored by the qtest framework.
This function allows to identify problems in the created qgraph. Keep in
mind: only tests with a path down from the actual test case node (leaf) up
to the graph’s root node are actually executed by the qtest framework. And
the qtest framework uses QMP to automatically check which QEMU drivers are
actually currently available, and accordingly qos marks certain pathes as
‘unavailable’ in such cases (e.g. when QEMU was compiled without support for
a certain feature).
</div>
</div>

</div>
 
 </div>
 <footer>
 
 <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 
 <a href="decodetree.html" class="btn btn-neutral float-right" title="Decodetree Specification" accesskey="n" rel="next">Next </a>
 
 
 <a href="qtest.html" class="btn btn-neutral" title="QTest Device Emulation Testing Framework" accesskey="p" rel="prev"> Previous</a>
 
 </div>

<hr/>

</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>.

This documentation is for QEMU version 6.2.0.

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

</footer>

</div>
 </div>

</section>

</div>

</body>
</html>