3 ========================================
5 ========================================
7 In order to test a specific driver, plain libqos tests need to
8 take care of booting QEMU with the right machine and devices.
9 This makes each test "hardcoded" for a specific configuration, reducing
10 the possible coverage that it can reach.
12 For example, the sdhci device is supported on both x86_64 and ARM boards,
13 therefore a generic sdhci test should test all machines and drivers that
15 Using only libqos APIs, the test has to manually take care of
16 covering all the setups, and build the correct command line.
18 This also introduces backward compability issues: if a device/driver command
19 line name is changed, all tests that use that will not work
20 properly anymore and need to be adjusted.
22 The aim of qgraph is to create a graph of drivers, machines and tests such that
23 a test aimed to a certain driver does not have to care of
24 booting the right QEMU machine, pick the right device, build the command line
25 and so on. Instead, it only defines what type of device it is testing
26 (interface in qgraph terms) and the framework takes care of
27 covering all supported types of devices and machine architectures.
29 Following the above example, an interface would be ``sdhci``,
30 so the sdhci-test should only care of linking its qgraph node with
31 that interface. In this way, if the command line of a sdhci driver
32 is changed, only the respective qgraph driver node has to be adjusted.
34 The graph is composed by nodes that represent machines, drivers, tests
35 and edges that define the relationships between them (``CONSUMES``, ``PRODUCES``, and
42 A node can be of four types:
44 - **QNODE_MACHINE**: for example ``arm/raspi2``
45 - **QNODE_DRIVER**: for example ``generic-sdhci``
46 - **QNODE_INTERFACE**: for example ``sdhci`` (interface for all ``-sdhci``
48 An interface is not explicitly created, it will be automatically
49 instantiated when a node consumes or produces it.
50 An interface is simply a struct that abstracts the various drivers
51 for the same type of device, and offers an API to the nodes that
52 use it ("consume" relation in qgraph terms) that is implemented/backed up by the drivers that implement it ("produce" relation in qgraph terms).
53 - **QNODE_TEST**: for example ``sdhci-test``. A test consumes an interface
54 and tests the functions provided by it.
58 - QNODE_MACHINE: each machine struct must have a ``QGuestAllocator`` and
59 implement ``get_driver()`` to return the allocator mapped to the interface
60 "memory". The function can also return ``NULL`` if the allocator
62 - QNODE_DRIVER: driver names must be unique, and machines and nodes
63 planned to be "consumed" by other nodes must match QEMU
64 drivers name, otherwise they won't be discovered
69 An edge relation between two nodes (drivers or machines) `X` and `Y` can be:
71 - ``X CONSUMES Y``: `Y` can be plugged into `X`
72 - ``X PRODUCES Y``: `X` provides the interface `Y`
73 - ``X CONTAINS Y``: `Y` is part of `X` component
78 The basic framework steps are the following:
80 - All nodes and edges are created in their respective
81 machine/driver/test files
82 - The framework starts QEMU and asks for a list of available devices
83 and machines (note that only machines and "consumed" nodes are mapped
84 1:1 with QEMU devices)
85 - The framework walks the graph starting from the available machines and
86 performs a Depth First Search for tests
87 - Once a test is found, the path is walked again and all drivers are
88 allocated accordingly and the final interface is passed to the test
89 - The test is executed
90 - Unused objects are cleaned and the path discovery is continued
92 Depending on the QEMU binary used, only some drivers/machines will be
93 available and only test that are reached by them will be executed.
95 Troubleshooting unavailable tests
96 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
97 If there is no path from an available machine to a test then that test will be
98 unavailable and won't execute. This can happen if a test or driver did not set
99 up its qgraph node correctly. It can also happen if the necessary machine type
100 or device is missing from the QEMU binary because it was compiled out or
103 It is possible to troubleshoot unavailable tests by running::
105 $ QTEST_QEMU_BINARY=build/qemu-system-x86_64 build/tests/qtest/qos-test --verbose
106 # ALL QGRAPH EDGES: {
108 # |-> dest='virtio-net-tests/vhost-user/multiqueue' type=2 (node=0x559142109e30)
109 # |-> dest='virtio-net-tests/vhost-user/migrate' type=2 (node=0x559142109d00)
110 # src='virtio-net-pci'
111 # |-> dest='virtio-net' type=1 (node=0x55914210d740)
113 # |-> dest='virtio-net-pci' type=2 (node=0x55914210d880)
115 # |-> dest='pci-bus' type=1 (node=0x559142103f40)
116 # src='i440FX-pcihost'
117 # |-> dest='pci-bus-pc' type=0 (node=0x55914210ac70)
119 # |-> dest='i440FX-pcihost' type=0 (node=0x5591421117f0)
121 # |-> dest='x86_64/pc' type=0 (node=0x559142111600)
122 # |-> dest='arm/raspi2' type=0 (node=0x559142110740)
125 # ALL QGRAPH NODES: {
126 # name='virtio-net-tests/announce-self' type=3 cmd_line='(null)' [available]
127 # name='arm/raspi2' type=0 cmd_line='-M raspi2 ' [UNAVAILABLE]
131 The ``virtio-net-tests/announce-self`` test is listed as "available" in the
132 "ALL QGRAPH NODES" output. This means the test will execute. We can follow the
133 qgraph path in the "ALL QGRAPH EDGES" output as follows: '' -> 'x86_64/pc' ->
134 'i440FX-pcihost' -> 'pci-bus-pc' -> 'pci-bus' -> 'virtio-net-pci' ->
135 'virtio-net'. The root of the qgraph is '' and the depth first search begins
138 The ``arm/raspi`` machine node is listed as "UNAVAILABLE". Although it is
139 reachable from the root via '' -> 'arm/raspi2' the node is unavailable because
140 the QEMU binary did not list it when queried by the framework. This is expected
141 because we used the ``qemu-system-x86_64`` binary which does not support ARM
144 If a test is unexpectedly listed as "UNAVAILABLE", first check that the "ALL
145 QGRAPH EDGES" output reports edge connectivity from the root ('') to the test.
146 If there is no connectivity then the qgraph nodes were not set up correctly and
147 the driver or test code is incorrect. If there is connectivity, check the
148 availability of each node in the path in the "ALL QGRAPH NODES" output. The
149 first unavailable node in the path is the reason why the test is unavailable.
150 Typically this is because the QEMU binary lacks support for the necessary
151 machine type or device.
153 Creating a new driver and its interface
154 """""""""""""""""""""""""""""""""""""""""
156 Here we continue the ``sdhci`` use case, with the following scenario:
158 - ``sdhci-test`` aims to test the ``read[q,w], writeq`` functions
159 offered by the ``sdhci`` drivers.
160 - The current ``sdhci`` device is supported by both ``x86_64/pc`` and ``ARM``
161 (in this example we focus on the ``arm-raspi2``) machines.
162 - QEMU offers 2 types of drivers: ``QSDHCI_MemoryMapped`` for ``ARM`` and
163 ``QSDHCI_PCI`` for ``x86_64/pc``. Both implement the
164 ``read[q,w], writeq`` functions.
166 In order to implement such scenario in qgraph, the test developer needs to:
168 - Create the ``x86_64/pc`` machine node. This machine uses the
169 ``pci-bus`` architecture so it ``contains`` a PCI driver,
170 ``pci-bus-pc``. The actual path is
172 ``x86_64/pc --contains--> 1440FX-pcihost --contains-->
173 pci-bus-pc --produces--> pci-bus``.
175 For the sake of this example,
176 we do not focus on the PCI interface implementation.
177 - Create the ``sdhci-pci`` driver node, representing ``QSDHCI_PCI``.
178 The driver uses the PCI bus (and its API),
179 so it must ``consume`` the ``pci-bus`` generic interface (which abstracts
180 all the pci drivers available)
182 ``sdhci-pci --consumes--> pci-bus``
183 - Create an ``arm/raspi2`` machine node. This machine ``contains``
184 a ``generic-sdhci`` memory mapped ``sdhci`` driver node, representing
185 ``QSDHCI_MemoryMapped``.
187 ``arm/raspi2 --contains--> generic-sdhci``
188 - Create the ``sdhci`` interface node. This interface offers the
189 functions that are shared by all ``sdhci`` devices.
190 The interface is produced by ``sdhci-pci`` and ``generic-sdhci``,
191 the available architecture-specific drivers.
193 ``sdhci-pci --produces--> sdhci``
195 ``generic-sdhci --produces--> sdhci``
196 - Create the ``sdhci-test`` test node. The test ``consumes`` the
197 ``sdhci`` interface, using its API. It doesn't need to look at
198 the supported machines or drivers.
200 ``sdhci-test --consumes--> sdhci``
202 ``arm-raspi2`` machine, simplified from
203 ``tests/qtest/libqos/arm-raspi2-machine.c``::
207 struct QRaspi2Machine {
209 QGuestAllocator alloc;
210 QSDHCI_MemoryMapped sdhci;
213 static void *raspi2_get_driver(void *object, const char *interface)
215 QRaspi2Machine *machine = object;
216 if (!g_strcmp0(interface, "memory")) {
217 return &machine->alloc;
220 fprintf(stderr, "%s not present in arm/raspi2\n", interface);
221 g_assert_not_reached();
224 static QOSGraphObject *raspi2_get_device(void *obj,
227 QRaspi2Machine *machine = obj;
228 if (!g_strcmp0(device, "generic-sdhci")) {
229 return &machine->sdhci.obj;
232 fprintf(stderr, "%s not present in arm/raspi2\n", device);
233 g_assert_not_reached();
236 static void *qos_create_machine_arm_raspi2(QTestState *qts)
238 QRaspi2Machine *machine = g_new0(QRaspi2Machine, 1);
240 alloc_init(&machine->alloc, ...);
242 /* Get node(s) contained inside (CONTAINS) */
243 machine->obj.get_device = raspi2_get_device;
245 /* Get node(s) produced (PRODUCES) */
246 machine->obj.get_driver = raspi2_get_driver;
248 /* free the object */
249 machine->obj.destructor = raspi2_destructor;
250 qos_init_sdhci_mm(&machine->sdhci, ...);
251 return &machine->obj;
254 static void raspi2_register_nodes(void)
256 /* arm/raspi2 --contains--> generic-sdhci */
257 qos_node_create_machine("arm/raspi2",
258 qos_create_machine_arm_raspi2);
259 qos_node_contains("arm/raspi2", "generic-sdhci", NULL);
262 libqos_init(raspi2_register_nodes);
264 ``x86_64/pc`` machine, simplified from
265 ``tests/qtest/libqos/x86_64_pc-machine.c``::
269 struct i440FX_pcihost {
274 struct QX86PCMachine {
276 QGuestAllocator alloc;
277 i440FX_pcihost bridge;
282 static QOSGraphObject *i440FX_host_get_device(void *obj,
285 i440FX_pcihost *host = obj;
286 if (!g_strcmp0(device, "pci-bus-pc")) {
287 return &host->pci.obj;
289 fprintf(stderr, "%s not present in i440FX-pcihost\n", device);
290 g_assert_not_reached();
293 /* x86_64/pc machine */
295 static void *pc_get_driver(void *object, const char *interface)
297 QX86PCMachine *machine = object;
298 if (!g_strcmp0(interface, "memory")) {
299 return &machine->alloc;
302 fprintf(stderr, "%s not present in x86_64/pc\n", interface);
303 g_assert_not_reached();
306 static QOSGraphObject *pc_get_device(void *obj, const char *device)
308 QX86PCMachine *machine = obj;
309 if (!g_strcmp0(device, "i440FX-pcihost")) {
310 return &machine->bridge.obj;
313 fprintf(stderr, "%s not present in x86_64/pc\n", device);
314 g_assert_not_reached();
317 static void *qos_create_machine_pc(QTestState *qts)
319 QX86PCMachine *machine = g_new0(QX86PCMachine, 1);
321 /* Get node(s) contained inside (CONTAINS) */
322 machine->obj.get_device = pc_get_device;
324 /* Get node(s) produced (PRODUCES) */
325 machine->obj.get_driver = pc_get_driver;
327 /* free the object */
328 machine->obj.destructor = pc_destructor;
329 pc_alloc_init(&machine->alloc, qts, ALLOC_NO_FLAGS);
331 /* Get node(s) contained inside (CONTAINS) */
332 machine->bridge.obj.get_device = i440FX_host_get_device;
334 return &machine->obj;
337 static void pc_machine_register_nodes(void)
339 /* x86_64/pc --contains--> 1440FX-pcihost --contains-->
340 * pci-bus-pc [--produces--> pci-bus (in pci.h)] */
341 qos_node_create_machine("x86_64/pc", qos_create_machine_pc);
342 qos_node_contains("x86_64/pc", "i440FX-pcihost", NULL);
344 /* contained drivers don't need a constructor,
345 * they will be init by the parent */
346 qos_node_create_driver("i440FX-pcihost", NULL);
347 qos_node_contains("i440FX-pcihost", "pci-bus-pc", NULL);
350 libqos_init(pc_machine_register_nodes);
352 ``sdhci`` taken from ``tests/qtest/libqos/sdhci.c``::
354 /* Interface node, offers the sdhci API */
356 uint16_t (*readw)(QSDHCI *s, uint32_t reg);
357 uint64_t (*readq)(QSDHCI *s, uint32_t reg);
358 void (*writeq)(QSDHCI *s, uint32_t reg, uint64_t val);
362 /* Memory Mapped implementation of QSDHCI */
363 struct QSDHCI_MemoryMapped {
366 /* other driver-specific fields */
369 /* PCI implementation of QSDHCI */
373 /* other driver-specific fields */
376 /* Memory mapped implementation of QSDHCI */
378 static void *sdhci_mm_get_driver(void *obj, const char *interface)
380 QSDHCI_MemoryMapped *smm = obj;
381 if (!g_strcmp0(interface, "sdhci")) {
384 fprintf(stderr, "%s not present in generic-sdhci\n", interface);
385 g_assert_not_reached();
388 void qos_init_sdhci_mm(QSDHCI_MemoryMapped *sdhci, QTestState *qts,
389 uint32_t addr, QSDHCIProperties *common)
391 /* Get node contained inside (CONTAINS) */
392 sdhci->obj.get_driver = sdhci_mm_get_driver;
394 /* SDHCI interface API */
395 sdhci->sdhci.readw = sdhci_mm_readw;
396 sdhci->sdhci.readq = sdhci_mm_readq;
397 sdhci->sdhci.writeq = sdhci_mm_writeq;
401 /* PCI implementation of QSDHCI */
403 static void *sdhci_pci_get_driver(void *object,
404 const char *interface)
406 QSDHCI_PCI *spci = object;
407 if (!g_strcmp0(interface, "sdhci")) {
411 fprintf(stderr, "%s not present in sdhci-pci\n", interface);
412 g_assert_not_reached();
415 static void *sdhci_pci_create(void *pci_bus,
416 QGuestAllocator *alloc,
419 QSDHCI_PCI *spci = g_new0(QSDHCI_PCI, 1);
420 QPCIBus *bus = pci_bus;
423 qpci_device_init(&spci->dev, bus, addr);
425 /* SDHCI interface API */
426 spci->sdhci.readw = sdhci_pci_readw;
427 spci->sdhci.readq = sdhci_pci_readq;
428 spci->sdhci.writeq = sdhci_pci_writeq;
430 /* Get node(s) produced (PRODUCES) */
431 spci->obj.get_driver = sdhci_pci_get_driver;
433 spci->obj.start_hw = sdhci_pci_start_hw;
434 spci->obj.destructor = sdhci_destructor;
438 static void qsdhci_register_nodes(void)
440 QOSGraphEdgeOptions opts = {
441 .extra_device_opts = "addr=04.0",
445 /* generic-sdhci --produces--> sdhci */
446 qos_node_create_driver("generic-sdhci", NULL);
447 qos_node_produces("generic-sdhci", "sdhci");
450 /* sdhci-pci --produces--> sdhci
451 * sdhci-pci --consumes--> pci-bus */
452 qos_node_create_driver("sdhci-pci", sdhci_pci_create);
453 qos_node_produces("sdhci-pci", "sdhci");
454 qos_node_consumes("sdhci-pci", "pci-bus", &opts);
457 libqos_init(qsdhci_register_nodes);
459 In the above example, all possible types of relations are created::
461 x86_64/pc --contains--> 1440FX-pcihost --contains--> pci-bus-pc
463 sdhci-pci --consumes--> pci-bus <--produces--+
473 arm/raspi2 --contains--> generic-sdhci
475 or inverting the consumes edge in consumed_by::
477 x86_64/pc --contains--> 1440FX-pcihost --contains--> pci-bus-pc
479 sdhci-pci <--consumed by-- pci-bus <--produces--+
489 arm/raspi2 --contains--> generic-sdhci
494 Given the above setup, adding a new test is very simple.
495 ``sdhci-test``, taken from ``tests/qtest/sdhci-test.c``::
497 static void check_capab_sdma(QSDHCI *s, bool supported)
499 uint64_t capab, capab_sdma;
501 capab = s->readq(s, SDHC_CAPAB);
502 capab_sdma = FIELD_EX64(capab, SDHC_CAPAB, SDMA);
503 g_assert_cmpuint(capab_sdma, ==, supported);
506 static void test_registers(void *obj, void *data,
507 QGuestAllocator *alloc)
512 check_capab_sdma(s, s->props.capab.sdma);
515 static void register_sdhci_test(void)
517 /* sdhci-test --consumes--> sdhci */
518 qos_add_test("registers", "sdhci", test_registers, NULL);
521 libqos_init(register_sdhci_test);
523 Here a new test is created, consuming ``sdhci`` interface node
524 and creating a valid path from both machines to a test.
525 Final graph will be like this::
527 x86_64/pc --contains--> 1440FX-pcihost --contains--> pci-bus-pc
529 sdhci-pci --consumes--> pci-bus <--produces--+
534 sdhci <--consumes-- sdhci-test
539 arm/raspi2 --contains--> generic-sdhci
541 or inverting the consumes edge in consumed_by::
543 x86_64/pc --contains--> 1440FX-pcihost --contains--> pci-bus-pc
545 sdhci-pci <--consumed by-- pci-bus <--produces--+
550 sdhci --consumed by--> sdhci-test
555 arm/raspi2 --contains--> generic-sdhci
557 Assuming there the binary is
558 ``QTEST_QEMU_BINARY=./qemu-system-x86_64``
559 a valid test path will be:
560 ``/x86_64/pc/1440FX-pcihost/pci-bus-pc/pci-bus/sdhci-pc/sdhci/sdhci-test``
562 and for the binary ``QTEST_QEMU_BINARY=./qemu-system-arm``:
564 ``/arm/raspi2/generic-sdhci/sdhci/sdhci-test``
566 Additional examples are also in ``test-qgraph.c``
571 Command line is built by using node names and optional arguments
572 passed by the user when building the edges.
574 There are three types of command line arguments:
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``.
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.
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",
613 opts.extra_device_opts = "id=vs0";
616 qos_node_create_driver("virtio-scsi-device",
617 virtio_scsi_device_create);
618 qos_node_consumes("virtio-scsi-device", "virtio-bus", &opts);
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``
626 .. kernel-doc:: tests/qtest/libqos/qgraph.h