qgraph.rst (22577B)
1 .. _qgraph: 2 3 Qtest Driver Framework 4 ====================== 5 6 In order to test a specific driver, plain libqos tests need to 7 take care of booting QEMU with the right machine and devices. 8 This makes each test "hardcoded" for a specific configuration, reducing 9 the possible coverage that it can reach. 10 11 For example, the sdhci device is supported on both x86_64 and ARM boards, 12 therefore a generic sdhci test should test all machines and drivers that 13 support that device. 14 Using only libqos APIs, the test has to manually take care of 15 covering all the setups, and build the correct command line. 16 17 This also introduces backward compatibility issues: if a device/driver command 18 line name is changed, all tests that use that will not work 19 properly anymore and need to be adjusted. 20 21 The aim of qgraph is to create a graph of drivers, machines and tests such that 22 a test aimed to a certain driver does not have to care of 23 booting the right QEMU machine, pick the right device, build the command line 24 and so on. Instead, it only defines what type of device it is testing 25 (interface in qgraph terms) and the framework takes care of 26 covering all supported types of devices and machine architectures. 27 28 Following the above example, an interface would be ``sdhci``, 29 so the sdhci-test should only care of linking its qgraph node with 30 that interface. In this way, if the command line of a sdhci driver 31 is changed, only the respective qgraph driver node has to be adjusted. 32 33 QGraph concepts 34 --------------- 35 36 The graph is composed by nodes that represent machines, drivers, tests 37 and edges that define the relationships between them (``CONSUMES``, ``PRODUCES``, and 38 ``CONTAINS``). 39 40 Nodes 41 ~~~~~ 42 43 A node can be of four types: 44 45 - **QNODE_MACHINE**: for example ``arm/raspi2b`` 46 - **QNODE_DRIVER**: for example ``generic-sdhci`` 47 - **QNODE_INTERFACE**: for example ``sdhci`` (interface for all ``-sdhci`` 48 drivers). 49 An interface is not explicitly created, it will be automatically 50 instantiated when a node consumes or produces it. 51 An interface is simply a struct that abstracts the various drivers 52 for the same type of device, and offers an API to the nodes that 53 use it ("consume" relation in qgraph terms) that is implemented/backed up by the drivers that implement it ("produce" relation in qgraph terms). 54 - **QNODE_TEST**: for example ``sdhci-test``. A test consumes an interface 55 and tests the functions provided by it. 56 57 Notes for the nodes: 58 59 - QNODE_MACHINE: each machine struct must have a ``QGuestAllocator`` and 60 implement ``get_driver()`` to return the allocator mapped to the interface 61 "memory". The function can also return ``NULL`` if the allocator 62 is not set. 63 - QNODE_DRIVER: driver names must be unique, and machines and nodes 64 planned to be "consumed" by other nodes must match QEMU 65 drivers name, otherwise they won't be discovered 66 67 Edges 68 ~~~~~ 69 70 An edge relation between two nodes (drivers or machines) ``X`` and ``Y`` can be: 71 72 - ``X CONSUMES Y``: ``Y`` can be plugged into ``X`` 73 - ``X PRODUCES Y``: ``X`` provides the interface ``Y`` 74 - ``X CONTAINS Y``: ``Y`` is part of ``X`` component 75 76 Execution steps 77 ~~~~~~~~~~~~~~~ 78 79 The basic framework steps are the following: 80 81 - All nodes and edges are created in their respective 82 machine/driver/test files 83 - The framework starts QEMU and asks for a list of available devices 84 and machines (note that only machines and "consumed" nodes are mapped 85 1:1 with QEMU devices) 86 - The framework walks the graph starting from the available machines and 87 performs a Depth First Search for tests 88 - Once a test is found, the path is walked again and all drivers are 89 allocated accordingly and the final interface is passed to the test 90 - The test is executed 91 - Unused objects are cleaned and the path discovery is continued 92 93 Depending on the QEMU binary used, only some drivers/machines will be 94 available and only test that are reached by them will be executed. 95 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 151 Troubleshooting unavailable tests 152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 153 154 If there is no path from an available machine to a test then that test will be 155 unavailable and won't execute. This can happen if a test or driver did not set 156 up its qgraph node correctly. It can also happen if the necessary machine type 157 or device is missing from the QEMU binary because it was compiled out or 158 otherwise. 159 160 It is possible to troubleshoot unavailable tests by running:: 161 162 $ QTEST_QEMU_BINARY=build/qemu-system-x86_64 build/tests/qtest/qos-test --verbose 163 # ALL QGRAPH EDGES: { 164 # src='virtio-net' 165 # |-> dest='virtio-net-tests/vhost-user/multiqueue' type=2 (node=0x559142109e30) 166 # |-> dest='virtio-net-tests/vhost-user/migrate' type=2 (node=0x559142109d00) 167 # src='virtio-net-pci' 168 # |-> dest='virtio-net' type=1 (node=0x55914210d740) 169 # src='pci-bus' 170 # |-> dest='virtio-net-pci' type=2 (node=0x55914210d880) 171 # src='pci-bus-pc' 172 # |-> dest='pci-bus' type=1 (node=0x559142103f40) 173 # src='i440FX-pcihost' 174 # |-> dest='pci-bus-pc' type=0 (node=0x55914210ac70) 175 # src='x86_64/pc' 176 # |-> dest='i440FX-pcihost' type=0 (node=0x5591421117f0) 177 # src='' 178 # |-> dest='x86_64/pc' type=0 (node=0x559142111600) 179 # |-> dest='arm/raspi2b' type=0 (node=0x559142110740) 180 ... 181 # } 182 # ALL QGRAPH NODES: { 183 # name='virtio-net-tests/announce-self' type=3 cmd_line='(null)' [available] 184 # name='arm/raspi2b' type=0 cmd_line='-M raspi2b ' [UNAVAILABLE] 185 ... 186 # } 187 188 The ``virtio-net-tests/announce-self`` test is listed as "available" in the 189 "ALL QGRAPH NODES" output. This means the test will execute. We can follow the 190 qgraph path in the "ALL QGRAPH EDGES" output as follows: '' -> 'x86_64/pc' -> 191 'i440FX-pcihost' -> 'pci-bus-pc' -> 'pci-bus' -> 'virtio-net-pci' -> 192 'virtio-net'. The root of the qgraph is '' and the depth first search begins 193 there. 194 195 The ``arm/raspi2b`` machine node is listed as "UNAVAILABLE". Although it is 196 reachable from the root via '' -> 'arm/raspi2b' the node is unavailable because 197 the QEMU binary did not list it when queried by the framework. This is expected 198 because we used the ``qemu-system-x86_64`` binary which does not support ARM 199 machine types. 200 201 If a test is unexpectedly listed as "UNAVAILABLE", first check that the "ALL 202 QGRAPH EDGES" output reports edge connectivity from the root ('') to the test. 203 If there is no connectivity then the qgraph nodes were not set up correctly and 204 the driver or test code is incorrect. If there is connectivity, check the 205 availability of each node in the path in the "ALL QGRAPH NODES" output. The 206 first unavailable node in the path is the reason why the test is unavailable. 207 Typically this is because the QEMU binary lacks support for the necessary 208 machine type or device. 209 210 Creating a new driver and its interface 211 --------------------------------------- 212 213 Here we continue the ``sdhci`` use case, with the following scenario: 214 215 - ``sdhci-test`` aims to test the ``read[q,w], writeq`` functions 216 offered by the ``sdhci`` drivers. 217 - The current ``sdhci`` device is supported by both ``x86_64/pc`` and ``ARM`` 218 (in this example we focus on the ``arm-raspi2b``) machines. 219 - QEMU offers 2 types of drivers: ``QSDHCI_MemoryMapped`` for ``ARM`` and 220 ``QSDHCI_PCI`` for ``x86_64/pc``. Both implement the 221 ``read[q,w], writeq`` functions. 222 223 In order to implement such scenario in qgraph, the test developer needs to: 224 225 - Create the ``x86_64/pc`` machine node. This machine uses the 226 ``pci-bus`` architecture so it ``contains`` a PCI driver, 227 ``pci-bus-pc``. The actual path is 228 229 ``x86_64/pc --contains--> 1440FX-pcihost --contains--> 230 pci-bus-pc --produces--> pci-bus``. 231 232 For the sake of this example, 233 we do not focus on the PCI interface implementation. 234 - Create the ``sdhci-pci`` driver node, representing ``QSDHCI_PCI``. 235 The driver uses the PCI bus (and its API), 236 so it must ``consume`` the ``pci-bus`` generic interface (which abstracts 237 all the pci drivers available) 238 239 ``sdhci-pci --consumes--> pci-bus`` 240 - Create an ``arm/raspi2b`` machine node. This machine ``contains`` 241 a ``generic-sdhci`` memory mapped ``sdhci`` driver node, representing 242 ``QSDHCI_MemoryMapped``. 243 244 ``arm/raspi2b --contains--> generic-sdhci`` 245 - Create the ``sdhci`` interface node. This interface offers the 246 functions that are shared by all ``sdhci`` devices. 247 The interface is produced by ``sdhci-pci`` and ``generic-sdhci``, 248 the available architecture-specific drivers. 249 250 ``sdhci-pci --produces--> sdhci`` 251 252 ``generic-sdhci --produces--> sdhci`` 253 - Create the ``sdhci-test`` test node. The test ``consumes`` the 254 ``sdhci`` interface, using its API. It doesn't need to look at 255 the supported machines or drivers. 256 257 ``sdhci-test --consumes--> sdhci`` 258 259 ``arm-raspi2b`` machine, simplified from 260 ``tests/qtest/libqos/arm-raspi2-machine.c``:: 261 262 #include "qgraph.h" 263 264 struct QRaspi2Machine { 265 QOSGraphObject obj; 266 QGuestAllocator alloc; 267 QSDHCI_MemoryMapped sdhci; 268 }; 269 270 static void *raspi2_get_driver(void *object, const char *interface) 271 { 272 QRaspi2Machine *machine = object; 273 if (!g_strcmp0(interface, "memory")) { 274 return &machine->alloc; 275 } 276 277 fprintf(stderr, "%s not present in arm/raspi2b\n", interface); 278 g_assert_not_reached(); 279 } 280 281 static QOSGraphObject *raspi2_get_device(void *obj, 282 const char *device) 283 { 284 QRaspi2Machine *machine = obj; 285 if (!g_strcmp0(device, "generic-sdhci")) { 286 return &machine->sdhci.obj; 287 } 288 289 fprintf(stderr, "%s not present in arm/raspi2b\n", device); 290 g_assert_not_reached(); 291 } 292 293 static void *qos_create_machine_arm_raspi2(QTestState *qts) 294 { 295 QRaspi2Machine *machine = g_new0(QRaspi2Machine, 1); 296 297 alloc_init(&machine->alloc, ...); 298 299 /* Get node(s) contained inside (CONTAINS) */ 300 machine->obj.get_device = raspi2_get_device; 301 302 /* Get node(s) produced (PRODUCES) */ 303 machine->obj.get_driver = raspi2_get_driver; 304 305 /* free the object */ 306 machine->obj.destructor = raspi2_destructor; 307 qos_init_sdhci_mm(&machine->sdhci, ...); 308 return &machine->obj; 309 } 310 311 static void raspi2_register_nodes(void) 312 { 313 /* arm/raspi2b --contains--> generic-sdhci */ 314 qos_node_create_machine("arm/raspi2b", 315 qos_create_machine_arm_raspi2); 316 qos_node_contains("arm/raspi2b", "generic-sdhci", NULL); 317 } 318 319 libqos_init(raspi2_register_nodes); 320 321 ``x86_64/pc`` machine, simplified from 322 ``tests/qtest/libqos/x86_64_pc-machine.c``:: 323 324 #include "qgraph.h" 325 326 struct i440FX_pcihost { 327 QOSGraphObject obj; 328 QPCIBusPC pci; 329 }; 330 331 struct QX86PCMachine { 332 QOSGraphObject obj; 333 QGuestAllocator alloc; 334 i440FX_pcihost bridge; 335 }; 336 337 /* i440FX_pcihost */ 338 339 static QOSGraphObject *i440FX_host_get_device(void *obj, 340 const char *device) 341 { 342 i440FX_pcihost *host = obj; 343 if (!g_strcmp0(device, "pci-bus-pc")) { 344 return &host->pci.obj; 345 } 346 fprintf(stderr, "%s not present in i440FX-pcihost\n", device); 347 g_assert_not_reached(); 348 } 349 350 /* x86_64/pc machine */ 351 352 static void *pc_get_driver(void *object, const char *interface) 353 { 354 QX86PCMachine *machine = object; 355 if (!g_strcmp0(interface, "memory")) { 356 return &machine->alloc; 357 } 358 359 fprintf(stderr, "%s not present in x86_64/pc\n", interface); 360 g_assert_not_reached(); 361 } 362 363 static QOSGraphObject *pc_get_device(void *obj, const char *device) 364 { 365 QX86PCMachine *machine = obj; 366 if (!g_strcmp0(device, "i440FX-pcihost")) { 367 return &machine->bridge.obj; 368 } 369 370 fprintf(stderr, "%s not present in x86_64/pc\n", device); 371 g_assert_not_reached(); 372 } 373 374 static void *qos_create_machine_pc(QTestState *qts) 375 { 376 QX86PCMachine *machine = g_new0(QX86PCMachine, 1); 377 378 /* Get node(s) contained inside (CONTAINS) */ 379 machine->obj.get_device = pc_get_device; 380 381 /* Get node(s) produced (PRODUCES) */ 382 machine->obj.get_driver = pc_get_driver; 383 384 /* free the object */ 385 machine->obj.destructor = pc_destructor; 386 pc_alloc_init(&machine->alloc, qts, ALLOC_NO_FLAGS); 387 388 /* Get node(s) contained inside (CONTAINS) */ 389 machine->bridge.obj.get_device = i440FX_host_get_device; 390 391 return &machine->obj; 392 } 393 394 static void pc_machine_register_nodes(void) 395 { 396 /* x86_64/pc --contains--> 1440FX-pcihost --contains--> 397 * pci-bus-pc [--produces--> pci-bus (in pci.h)] */ 398 qos_node_create_machine("x86_64/pc", qos_create_machine_pc); 399 qos_node_contains("x86_64/pc", "i440FX-pcihost", NULL); 400 401 /* contained drivers don't need a constructor, 402 * they will be init by the parent */ 403 qos_node_create_driver("i440FX-pcihost", NULL); 404 qos_node_contains("i440FX-pcihost", "pci-bus-pc", NULL); 405 } 406 407 libqos_init(pc_machine_register_nodes); 408 409 ``sdhci`` taken from ``tests/qtest/libqos/sdhci.c``:: 410 411 /* Interface node, offers the sdhci API */ 412 struct QSDHCI { 413 uint16_t (*readw)(QSDHCI *s, uint32_t reg); 414 uint64_t (*readq)(QSDHCI *s, uint32_t reg); 415 void (*writeq)(QSDHCI *s, uint32_t reg, uint64_t val); 416 /* other fields */ 417 }; 418 419 /* Memory Mapped implementation of QSDHCI */ 420 struct QSDHCI_MemoryMapped { 421 QOSGraphObject obj; 422 QSDHCI sdhci; 423 /* other driver-specific fields */ 424 }; 425 426 /* PCI implementation of QSDHCI */ 427 struct QSDHCI_PCI { 428 QOSGraphObject obj; 429 QSDHCI sdhci; 430 /* other driver-specific fields */ 431 }; 432 433 /* Memory mapped implementation of QSDHCI */ 434 435 static void *sdhci_mm_get_driver(void *obj, const char *interface) 436 { 437 QSDHCI_MemoryMapped *smm = obj; 438 if (!g_strcmp0(interface, "sdhci")) { 439 return &smm->sdhci; 440 } 441 fprintf(stderr, "%s not present in generic-sdhci\n", interface); 442 g_assert_not_reached(); 443 } 444 445 void qos_init_sdhci_mm(QSDHCI_MemoryMapped *sdhci, QTestState *qts, 446 uint32_t addr, QSDHCIProperties *common) 447 { 448 /* Get node contained inside (CONTAINS) */ 449 sdhci->obj.get_driver = sdhci_mm_get_driver; 450 451 /* SDHCI interface API */ 452 sdhci->sdhci.readw = sdhci_mm_readw; 453 sdhci->sdhci.readq = sdhci_mm_readq; 454 sdhci->sdhci.writeq = sdhci_mm_writeq; 455 sdhci->qts = qts; 456 } 457 458 /* PCI implementation of QSDHCI */ 459 460 static void *sdhci_pci_get_driver(void *object, 461 const char *interface) 462 { 463 QSDHCI_PCI *spci = object; 464 if (!g_strcmp0(interface, "sdhci")) { 465 return &spci->sdhci; 466 } 467 468 fprintf(stderr, "%s not present in sdhci-pci\n", interface); 469 g_assert_not_reached(); 470 } 471 472 static void *sdhci_pci_create(void *pci_bus, 473 QGuestAllocator *alloc, 474 void *addr) 475 { 476 QSDHCI_PCI *spci = g_new0(QSDHCI_PCI, 1); 477 QPCIBus *bus = pci_bus; 478 uint64_t barsize; 479 480 qpci_device_init(&spci->dev, bus, addr); 481 482 /* SDHCI interface API */ 483 spci->sdhci.readw = sdhci_pci_readw; 484 spci->sdhci.readq = sdhci_pci_readq; 485 spci->sdhci.writeq = sdhci_pci_writeq; 486 487 /* Get node(s) produced (PRODUCES) */ 488 spci->obj.get_driver = sdhci_pci_get_driver; 489 490 spci->obj.start_hw = sdhci_pci_start_hw; 491 spci->obj.destructor = sdhci_destructor; 492 return &spci->obj; 493 } 494 495 static void qsdhci_register_nodes(void) 496 { 497 QOSGraphEdgeOptions opts = { 498 .extra_device_opts = "addr=04.0", 499 }; 500 501 /* generic-sdhci */ 502 /* generic-sdhci --produces--> sdhci */ 503 qos_node_create_driver("generic-sdhci", NULL); 504 qos_node_produces("generic-sdhci", "sdhci"); 505 506 /* sdhci-pci */ 507 /* sdhci-pci --produces--> sdhci 508 * sdhci-pci --consumes--> pci-bus */ 509 qos_node_create_driver("sdhci-pci", sdhci_pci_create); 510 qos_node_produces("sdhci-pci", "sdhci"); 511 qos_node_consumes("sdhci-pci", "pci-bus", &opts); 512 } 513 514 libqos_init(qsdhci_register_nodes); 515 516 In the above example, all possible types of relations are created:: 517 518 x86_64/pc --contains--> 1440FX-pcihost --contains--> pci-bus-pc 519 | 520 sdhci-pci --consumes--> pci-bus <--produces--+ 521 | 522 +--produces--+ 523 | 524 v 525 sdhci 526 ^ 527 | 528 +--produces-- + 529 | 530 arm/raspi2b --contains--> generic-sdhci 531 532 or inverting the consumes edge in consumed_by:: 533 534 x86_64/pc --contains--> 1440FX-pcihost --contains--> pci-bus-pc 535 | 536 sdhci-pci <--consumed by-- pci-bus <--produces--+ 537 | 538 +--produces--+ 539 | 540 v 541 sdhci 542 ^ 543 | 544 +--produces-- + 545 | 546 arm/raspi2b --contains--> generic-sdhci 547 548 Adding a new test 549 ----------------- 550 551 Given the above setup, adding a new test is very simple. 552 ``sdhci-test``, taken from ``tests/qtest/sdhci-test.c``:: 553 554 static void check_capab_sdma(QSDHCI *s, bool supported) 555 { 556 uint64_t capab, capab_sdma; 557 558 capab = s->readq(s, SDHC_CAPAB); 559 capab_sdma = FIELD_EX64(capab, SDHC_CAPAB, SDMA); 560 g_assert_cmpuint(capab_sdma, ==, supported); 561 } 562 563 static void test_registers(void *obj, void *data, 564 QGuestAllocator *alloc) 565 { 566 QSDHCI *s = obj; 567 568 /* example test */ 569 check_capab_sdma(s, s->props.capab.sdma); 570 } 571 572 static void register_sdhci_test(void) 573 { 574 /* sdhci-test --consumes--> sdhci */ 575 qos_add_test("registers", "sdhci", test_registers, NULL); 576 } 577 578 libqos_init(register_sdhci_test); 579 580 Here a new test is created, consuming ``sdhci`` interface node 581 and creating a valid path from both machines to a test. 582 Final graph will be like this:: 583 584 x86_64/pc --contains--> 1440FX-pcihost --contains--> pci-bus-pc 585 | 586 sdhci-pci --consumes--> pci-bus <--produces--+ 587 | 588 +--produces--+ 589 | 590 v 591 sdhci <--consumes-- sdhci-test 592 ^ 593 | 594 +--produces-- + 595 | 596 arm/raspi2b --contains--> generic-sdhci 597 598 or inverting the consumes edge in consumed_by:: 599 600 x86_64/pc --contains--> 1440FX-pcihost --contains--> pci-bus-pc 601 | 602 sdhci-pci <--consumed by-- pci-bus <--produces--+ 603 | 604 +--produces--+ 605 | 606 v 607 sdhci --consumed by--> sdhci-test 608 ^ 609 | 610 +--produces-- + 611 | 612 arm/raspi2b --contains--> generic-sdhci 613 614 Assuming there the binary is 615 ``QTEST_QEMU_BINARY=./qemu-system-x86_64`` 616 a valid test path will be: 617 ``/x86_64/pc/1440FX-pcihost/pci-bus-pc/pci-bus/sdhci-pc/sdhci/sdhci-test`` 618 619 and for the binary ``QTEST_QEMU_BINARY=./qemu-system-arm``: 620 621 ``/arm/raspi2b/generic-sdhci/sdhci/sdhci-test`` 622 623 Additional examples are also in ``test-qgraph.c`` 624 625 Qgraph API reference 626 -------------------- 627 628 .. kernel-doc:: tests/qtest/libqos/qgraph.h