tests/qtest/libqos/qgraph.h

   1 /*
   2  * libqos driver framework
   3  *
   4  * Copyright (c) 2018 Emanuele Giuseppe Esposito <e.emanuelegiuseppe@gmail.com>
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License version 2.1 as published by the Free Software Foundation.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, see <http://www.gnu.org/licenses/>
  17  */
  18
  19 #ifndef QGRAPH_H
  20 #define QGRAPH_H
  21
  22 #include <gmodule.h>
  23 #include "qemu/module.h"
  24 #include "malloc.h"
  25
  26 /* maximum path length */
  27 #define QOS_PATH_MAX_ELEMENT_SIZE 50
  28
  29 typedef struct QOSGraphObject QOSGraphObject;
  30 typedef struct QOSGraphNode QOSGraphNode;
  31 typedef struct QOSGraphEdge QOSGraphEdge;
  32 typedef struct QOSGraphEdgeOptions QOSGraphEdgeOptions;
  33 typedef struct QOSGraphTestOptions QOSGraphTestOptions;
  34
  35 /* Constructor for drivers, machines and test */
  36 typedef void *(*QOSCreateDriverFunc) (void *parent, QGuestAllocator *alloc,
  37                                       void *addr);
  38 typedef void *(*QOSCreateMachineFunc) (QTestState *qts);
  39 typedef void (*QOSTestFunc) (void *parent, void *arg, QGuestAllocator *alloc);
  40
  41 /* QOSGraphObject functions */
  42 typedef void *(*QOSGetDriver) (void *object, const char *interface);
  43 typedef QOSGraphObject *(*QOSGetDevice) (void *object, const char *name);
  44 typedef void (*QOSDestructorFunc) (QOSGraphObject *object);
  45 typedef void (*QOSStartFunct) (QOSGraphObject *object);
  46
  47 /* Test options functions */
  48 typedef void *(*QOSBeforeTest) (GString *cmd_line, void *arg);
  49
  50 /**
  51  * struct QOSGraphEdgeOptions:
  52  * Edge options to be passed to the contains/consumes \*_args function.
  53  * @arg: optional arg that will be used by dest edge
  54  * @size_arg: @arg size that will be used by dest edge
  55  * @extra_device_opts: optional additional command line for dest
  56  *                     edge, used to add additional attributes
  57  *                     *after* the node command line, the
  58  *                     framework automatically prepends ","
  59  *                     to this argument.
  60  * @before_cmd_line: optional additional command line for dest
  61  *                   edge, used to add additional attributes
  62  *                   *before* the node command line, usually
  63  *                   other non-node represented commands,
  64  *                   like "-fdsev synt"
  65  * @after_cmd_line: optional extra command line to be added
  66  *                  after the device command. This option
  67  *                  is used to add other devices
  68  *                  command line that depend on current node.
  69  *                  Automatically prepends " " to this argument
  70  * @edge_name: optional edge to differentiate multiple
  71  *             devices with same node name
  72  */
  73 struct QOSGraphEdgeOptions {
  74     void *arg;
  75     uint32_t size_arg;
  76     const char *extra_device_opts;
  77     const char *before_cmd_line;
  78     const char *after_cmd_line;
  79     const char *edge_name;
  80 };
  81
  82 /**
  83  * struct QOSGraphTestOptions:
  84  * Test options to be passed to the test functions.
  85  * @edge: edge arguments that will be used by test.
  86  *        Note that test *does not* use edge_name,
  87  *        and uses instead arg and size_arg as
  88  *        data arg for its test function.
  89  * @arg:  if @before is non-NULL, pass @arg there.
  90  *        Otherwise pass it to the test function.
  91  * @before: executed before the test. Used to add
  92  *          additional parameters to the command line
  93  *          and modify the argument to the test function.
  94  * @subprocess: run the test in a subprocess.
  95  */
  96 struct QOSGraphTestOptions {
  97     QOSGraphEdgeOptions edge;
  98     void *arg;
  99     QOSBeforeTest before;
 100     bool subprocess;
 101 };
 102
 103 /**
 104  * struct QOSGraphObject:
 105  * Each driver, test or machine of this framework will have a
 106  * QOSGraphObject as first field.
 107  *
 108  * This set of functions offered by QOSGraphObject are executed
 109  * in different stages of the framework:
 110  * @get_driver: see @get_device
 111  * @get_device: Once a machine-to-test path has been
 112  *              found, the framework traverses it again and allocates all the
 113  *              nodes, using the provided constructor. To satisfy their
 114  *              relations, i.e. for produces or contains, where a struct
 115  *              constructor needs an external parameter represented by the
 116  *              previous node, the framework will call
 117  *              @get_device (for contains) or @get_driver (for produces),
 118  *              depending on the edge type, passing them the name of the next
 119  *              node to be taken and getting from them the corresponding
 120  *              pointer to the actual structure of the next node to
 121  *              be used in the path.
 122  * @start_hw: This function is executed after all the path objects
 123  *            have been allocated, but before the test is run. It starts the
 124  *            hw, setting the initial configurations (\*_device_enable) and
 125  *            making it ready for the test.
 126  * @destructor: Opposite to the node constructor, destroys the object.
 127  *              This function is called after the test has been executed, and
 128  *              performs a complete cleanup of each node allocated field.
 129  *              In case no constructor is provided, no destructor will be
 130  *              called.
 131  * @free: free the memory associated to the QOSGraphObject and its contained
 132  *        children
 133  */
 134 struct QOSGraphObject {
 135     QOSGetDriver get_driver;
 136     QOSGetDevice get_device;
 137     QOSStartFunct start_hw;
 138     QOSDestructorFunc destructor;
 139     GDestroyNotify free;
 140 };
 141
 142 /**
 143  * qos_graph_init(): initialize the framework, creates two hash
 144  * tables: one for the nodes and another for the edges.
 145  */
 146 void qos_graph_init(void);
 147
 148 /**
 149  * qos_graph_destroy(): deallocates all the hash tables,
 150  * freeing all nodes and edges.
 151  */
 152 void qos_graph_destroy(void);
 153
 154 /**
 155  * qos_node_destroy(): removes and frees a node from the
 156  * nodes hash table.
 157  * @key: Name of the node
 158  */
 159 void qos_node_destroy(void *key);
 160
 161 /**
 162  * qos_edge_destroy(): removes and frees an edge from the
 163  * edges hash table.
 164  * @key: Name of the node
 165  */
 166 void qos_edge_destroy(void *key);
 167
 168 /**
 169  * qos_add_test(): adds a test node @name to the nodes hash table.
 170  * @name: Name of the test
 171  * @interface: Name of the interface node it consumes
 172  * @test_func: Actual test to perform
 173  * @opts: Facultative options (see %QOSGraphTestOptions)
 174  *
 175  * The test will consume a @interface node, and once the
 176  * graph walking algorithm has found it, the @test_func will be
 177  * executed. It also has the possibility to
 178  * add an optional @opts (see %QOSGraphTestOptions).
 179  *
 180  * For tests, opts->edge.arg and size_arg represent the arg to pass
 181  * to @test_func
 182  */
 183 void qos_add_test(const char *name, const char *interface,
 184                   QOSTestFunc test_func,
 185                   QOSGraphTestOptions *opts);
 186
 187 /**
 188  * qos_node_create_machine(): creates the machine @name and
 189  * adds it to the node hash table.
 190  * @name: Name of the machine
 191  * @function: Machine constructor
 192  *
 193  * This node will be of type QNODE_MACHINE and have @function
 194  * as constructor
 195  */
 196 void qos_node_create_machine(const char *name, QOSCreateMachineFunc function);
 197
 198 /**
 199  * qos_node_create_machine_args(): same as qos_node_create_machine,
 200  * but with the possibility to add an optional ", @opts" after -M machine
 201  * command line.
 202  * @name: Name of the machine
 203  * @function: Machine constructor
 204  * @opts: Optional additional command line
 205  */
 206 void qos_node_create_machine_args(const char *name,
 207                                   QOSCreateMachineFunc function,
 208                                   const char *opts);
 209
 210 /**
 211  * qos_node_create_driver(): creates the driver @name and
 212  * adds it to the node hash table.
 213  * @name: Name of the driver
 214  * @function: Driver constructor
 215  *
 216  * This node will be of type QNODE_DRIVER and have @function
 217  * as constructor
 218  */
 219 void qos_node_create_driver(const char *name, QOSCreateDriverFunc function);
 220
 221 /**
 222  * qos_node_create_driver_named(): behaves as qos_node_create_driver() with the
 223  * extension of allowing to specify a different node name vs. associated QEMU
 224  * device name.
 225  * @name: Custom, unique name of the node to be created
 226  * @qemu_name: Actual (official) QEMU driver name the node shall be
 227  * associated with
 228  * @function: Driver constructor
 229  *
 230  * Use this function instead of qos_node_create_driver() if you need to create
 231  * several instances of the same QEMU device. You are free to choose a custom
 232  * node name, however the chosen node name must always be unique.
 233  */
 234 void qos_node_create_driver_named(const char *name, const char *qemu_name,
 235                                   QOSCreateDriverFunc function);
 236
 237 /**
 238  * qos_node_contains(): creates one or more edges of type QEDGE_CONTAINS
 239  * and adds them to the edge list mapped to @container in the
 240  * edge hash table.
 241  * @container: Source node that "contains"
 242  * @contained: Destination node that "is contained"
 243  * @opts: Facultative options (see %QOSGraphEdgeOptions)
 244  *
 245  * The edges will have @container as source and @contained as destination.
 246  *
 247  * If @opts is NULL, a single edge will be added with no options.
 248  * If @opts is non-NULL, the arguments after @contained represent a
 249  * NULL-terminated list of %QOSGraphEdgeOptions structs, and an
 250  * edge will be added for each of them.
 251  *
 252  * This function can be useful when there are multiple devices
 253  * with the same node name contained in a machine/other node
 254  *
 255  * For example, if ``arm/raspi2`` contains 2 ``generic-sdhci``
 256  * devices, the right commands will be:
 257  *
 258  * .. code::
 259  *
 260  *    qos_node_create_machine("arm/raspi2");
 261  *    qos_node_create_driver("generic-sdhci", constructor);
 262  *    // assume rest of the fields are set NULL
 263  *    QOSGraphEdgeOptions op1 = { .edge_name = "emmc" };
 264  *    QOSGraphEdgeOptions op2 = { .edge_name = "sdcard" };
 265  *    qos_node_contains("arm/raspi2", "generic-sdhci", &op1, &op2, NULL);
 266  *
 267  * Of course this also requires that the @container's get_device function
 268  * should implement a case for "emmc" and "sdcard".
 269  *
 270  * For contains, op1.arg and op1.size_arg represent the arg to pass
 271  * to @contained constructor to properly initialize it.
 272  */
 273 void qos_node_contains(const char *container, const char *contained,
 274                        QOSGraphEdgeOptions *opts, ...);
 275
 276 /**
 277  * qos_node_produces(): creates an edge of type QEDGE_PRODUCES and
 278  * adds it to the edge list mapped to @producer in the
 279  * edge hash table.
 280  * @producer: Source node that "produces"
 281  * @interface: Interface node that "is produced"
 282  *
 283  * This edge will have @producer as source and @interface as destination.
 284  */
 285 void qos_node_produces(const char *producer, const char *interface);
 286
 287 /**
 288  * qos_node_consumes():  creates an edge of type QEDGE_CONSUMED_BY and
 289  * adds it to the edge list mapped to @interface in the
 290  * edge hash table.
 291  * @consumer: Node that "consumes"
 292  * @interface: Interface node that "is consumed by"
 293  * @opts: Facultative options (see %QOSGraphEdgeOptions)
 294  *
 295  * This edge will have @interface as source and @consumer as destination.
 296  * It also has the possibility to add an optional @opts
 297  * (see %QOSGraphEdgeOptions)
 298  */
 299 void qos_node_consumes(const char *consumer, const char *interface,
 300                        QOSGraphEdgeOptions *opts);
 301
 302 /**
 303  * qos_invalidate_command_line(): invalidates current command line, so that
 304  * qgraph framework cannot try to cache the current command line and
 305  * forces QEMU to restart.
 306  */
 307 void qos_invalidate_command_line(void);
 308
 309 /**
 310  * qos_get_current_command_line(): return the command line required by the
 311  * machine and driver objects.  This is the same string that was passed to
 312  * the test's "before" callback, if any.
 313  */
 314 const char *qos_get_current_command_line(void);
 315
 316 /**
 317  * qos_allocate_objects():
 318  * @qts: The #QTestState that will be referred to by the machine object.
 319  * @p_alloc: Where to store the allocator for the machine object, or %NULL.
 320  *
 321  * Allocate driver objects for the current test
 322  * path, but relative to the QTestState @qts.
 323  *
 324  * Returns a test object just like the one that was passed to
 325  * the test function, but relative to @qts.
 326  */
 327 void *qos_allocate_objects(QTestState *qts, QGuestAllocator **p_alloc);
 328
 329 /**
 330  * qos_object_destroy(): calls the destructor for @obj
 331  * @obj: A #QOSGraphObject to destroy
 332  */
 333 void qos_object_destroy(QOSGraphObject *obj);
 334
 335 /**
 336  * qos_object_queue_destroy(): queue the destructor for @obj so that it is
 337  * called at the end of the test
 338  * @obj: A #QOSGraphObject to destroy
 339  */
 340 void qos_object_queue_destroy(QOSGraphObject *obj);
 341
 342 /**
 343  * qos_object_start_hw(): calls the start_hw function for @obj
 344  * @obj: A #QOSGraphObject containing the start_hw function
 345  */
 346 void qos_object_start_hw(QOSGraphObject *obj);
 347
 348 /**
 349  * qos_machine_new(): instantiate a new machine node
 350  * @node: Machine node to be instantiated
 351  * @qts: A #QTestState that will be referred to by the machine object.
 352  *
 353  * Returns a machine object.
 354  */
 355 QOSGraphObject *qos_machine_new(QOSGraphNode *node, QTestState *qts);
 356
 357 /**
 358  * qos_machine_new(): instantiate a new driver node
 359  * @node: A driver node to be instantiated
 360  * @parent: A #QOSGraphObject to be consumed by the new driver node
 361  * @alloc: An allocator to be used by the new driver node.
 362  * @arg: The argument for the consumed-by edge to @node.
 363  *
 364  * Calls the constructor for the driver object.
 365  */
 366 QOSGraphObject *qos_driver_new(QOSGraphNode *node, QOSGraphObject *parent,
 367                                QGuestAllocator *alloc, void *arg);
 368
 369 /**
 370  * qos_dump_graph(): prints all currently existing nodes and
 371  * edges to stdout. Just for debugging purposes.
 372  *
 373  * All qtests add themselves to the overall qos graph by calling qgraph
 374  * functions that add device nodes and edges between the individual graph
 375  * nodes for tests. As the actual graph is assmbled at runtime by the qos
 376  * subsystem, it is sometimes not obvious how the overall graph looks like.
 377  * E.g. when writing new tests it may happen that those new tests are simply
 378  * ignored by the qtest framework.
 379  *
 380  * This function allows to identify problems in the created qgraph. Keep in
 381  * mind: only tests with a path down from the actual test case node (leaf) up
 382  * to the graph's root node are actually executed by the qtest framework. And
 383  * the qtest framework uses QMP to automatically check which QEMU drivers are
 384  * actually currently available, and accordingly qos marks certain pathes as
 385  * 'unavailable' in such cases (e.g. when QEMU was compiled without support for
 386  * a certain feature).
 387  */
 388 void qos_dump_graph(void);
 389
 390 #endif