11.. _qgraph :
22
3- ========================================
43Qtest Driver Framework
5- ========================================
4+ ======================
65
76In order to test a specific driver, plain libqos tests need to
87take care of booting QEMU with the right machine and devices.
@@ -31,13 +30,15 @@ so the sdhci-test should only care of linking its qgraph node with
3130that interface. In this way, if the command line of a sdhci driver
3231is changed, only the respective qgraph driver node has to be adjusted.
3332
33+ QGraph concepts
34+ ---------------
35+
3436The graph is composed by nodes that represent machines, drivers, tests
3537and edges that define the relationships between them (``CONSUMES ``, ``PRODUCES ``, and
3638``CONTAINS ``).
3739
38-
3940Nodes
40- ^^^^^^
41+ ~~~~~
4142
4243A node can be of four types:
4344
@@ -64,7 +65,7 @@ Notes for the nodes:
6465 drivers name, otherwise they won't be discovered
6566
6667Edges
67- ^^^^^^
68+ ~~~~~
6869
6970An edge relation between two nodes (drivers or machines) ``X `` and ``Y `` can be:
7071
@@ -73,7 +74,7 @@ An edge relation between two nodes (drivers or machines) ``X`` and ``Y`` can be:
7374- ``X CONTAINS Y ``: ``Y `` is part of ``X `` component
7475
7576Execution steps
76- ^^^^^^^^^^^^^^^
77+ ~~~~~~~~~~~~~~~
7778
7879The basic framework steps are the following:
7980
@@ -92,8 +93,64 @@ The basic framework steps are the following:
9293Depending on the QEMU binary used, only some drivers/machines will be
9394available and only test that are reached by them will be executed.
9495
96+ Command line
97+ ~~~~~~~~~~~~
98+
99+ Command line is built by using node names and optional arguments
100+ passed by the user when building the edges.
101+
102+ There are three types of command line arguments:
103+
104+ - ``in node `` : created from the node name. For example, machines will
105+ have ``-M <machine> `` to its command line, while devices
106+ ``-device <device> ``. It is automatically done by the framework.
107+ - ``after node `` : added as additional argument to the node name.
108+ This argument is added optionally when creating edges,
109+ by setting the parameter ``after_cmd_line `` and
110+ ``extra_edge_opts `` in ``QOSGraphEdgeOptions ``.
111+ The framework automatically adds
112+ a comma before ``extra_edge_opts ``,
113+ because it is going to add attributes
114+ after the destination node pointed by
115+ the edge containing these options, and automatically
116+ adds a space before ``after_cmd_line ``, because it
117+ adds an additional device, not an attribute.
118+ - ``before node `` : added as additional argument to the node name.
119+ This argument is added optionally when creating edges,
120+ by setting the parameter ``before_cmd_line `` in
121+ ``QOSGraphEdgeOptions ``. This attribute
122+ is going to add attributes before the destination node
123+ pointed by the edge containing these options. It is
124+ helpful to commands that are not node-representable,
125+ such as ``-fdsev `` or ``-netdev ``.
126+
127+ While adding command line in edges is always used, not all nodes names are
128+ used in every path walk: this is because the contained or produced ones
129+ are already added by QEMU, so only nodes that "consumes" will be used to
130+ build the command line. Also, nodes that will have ``{ "abstract" : true } ``
131+ as QMP attribute will loose their command line, since they are not proper
132+ devices to be added in QEMU.
133+
134+ Example::
135+
136+ QOSGraphEdgeOptions opts = {
137+ .before_cmd_line = "-drive id=drv0,if=none,file=null-co://,"
138+ "file.read-zeroes=on,format=raw",
139+ .after_cmd_line = "-device scsi-hd,bus=vs0.0,drive=drv0",
140+
141+ opts.extra_device_opts = "id=vs0";
142+ };
143+
144+ qos_node_create_driver("virtio-scsi-device",
145+ virtio_scsi_device_create);
146+ qos_node_consumes("virtio-scsi-device", "virtio-bus", &opts);
147+
148+ Will produce the following command line:
149+ ``-drive id=drv0,if=none,file=null-co://, -device virtio-scsi-device,id=vs0 -device scsi-hd,bus=vs0.0,drive=drv0 ``
150+
95151Troubleshooting unavailable tests
96- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
152+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153+
97154If there is no path from an available machine to a test then that test will be
98155unavailable and won't execute. This can happen if a test or driver did not set
99156up its qgraph node correctly. It can also happen if the necessary machine type
@@ -151,7 +208,7 @@ Typically this is because the QEMU binary lacks support for the necessary
151208machine type or device.
152209
153210Creating a new driver and its interface
154- """""""""""""""""""""""""""""""""""""""""
211+ ---------------------------------------
155212
156213Here we continue the ``sdhci `` use case, with the following scenario:
157214
@@ -489,7 +546,7 @@ or inverting the consumes edge in consumed_by::
489546 arm/raspi2b --contains--> generic-sdhci
490547
491548Adding a new test
492- """""""""""""""""
549+ -----------------
493550
494551Given the above setup, adding a new test is very simple.
495552``sdhci-test ``, taken from ``tests/qtest/sdhci-test.c ``::
@@ -565,62 +622,7 @@ and for the binary ``QTEST_QEMU_BINARY=./qemu-system-arm``:
565622
566623Additional examples are also in ``test-qgraph.c ``
567624
568- Command line:
569- """"""""""""""
570-
571- Command line is built by using node names and optional arguments
572- passed by the user when building the edges.
573-
574- There are three types of command line arguments:
575-
576- - ``in node `` : created from the node name. For example, machines will
577- have ``-M <machine> `` to its command line, while devices
578- ``-device <device> ``. It is automatically done by the framework.
579- - ``after node `` : added as additional argument to the node name.
580- This argument is added optionally when creating edges,
581- by setting the parameter ``after_cmd_line `` and
582- ``extra_edge_opts `` in ``QOSGraphEdgeOptions ``.
583- The framework automatically adds
584- a comma before ``extra_edge_opts ``,
585- because it is going to add attributes
586- after the destination node pointed by
587- the edge containing these options, and automatically
588- adds a space before ``after_cmd_line ``, because it
589- adds an additional device, not an attribute.
590- - ``before node `` : added as additional argument to the node name.
591- This argument is added optionally when creating edges,
592- by setting the parameter ``before_cmd_line `` in
593- ``QOSGraphEdgeOptions ``. This attribute
594- is going to add attributes before the destination node
595- pointed by the edge containing these options. It is
596- helpful to commands that are not node-representable,
597- such as ``-fdsev `` or ``-netdev ``.
598-
599- While adding command line in edges is always used, not all nodes names are
600- used in every path walk: this is because the contained or produced ones
601- are already added by QEMU, so only nodes that "consumes" will be used to
602- build the command line. Also, nodes that will have ``{ "abstract" : true } ``
603- as QMP attribute will loose their command line, since they are not proper
604- devices to be added in QEMU.
605-
606- Example::
607-
608- QOSGraphEdgeOptions opts = {
609- .before_cmd_line = "-drive id=drv0,if=none,file=null-co://,"
610- "file.read-zeroes=on,format=raw",
611- .after_cmd_line = "-device scsi-hd,bus=vs0.0,drive=drv0",
612-
613- opts.extra_device_opts = "id=vs0";
614- };
615-
616- qos_node_create_driver("virtio-scsi-device",
617- virtio_scsi_device_create);
618- qos_node_consumes("virtio-scsi-device", "virtio-bus", &opts);
619-
620- Will produce the following command line:
621- ``-drive id=drv0,if=none,file=null-co://, -device virtio-scsi-device,id=vs0 -device scsi-hd,bus=vs0.0,drive=drv0 ``
622-
623625Qgraph API reference
624- ^^^^^^^^^^^^^^^^^^^^
626+ --------------------
625627
626628.. kernel-doc :: tests/qtest/libqos/qgraph.h
0 commit comments