@@ -2592,6 +2592,7 @@ S: Maintained
F: softmmu/qtest.c
F: accel/qtest/
F: tests/qtest/
+F: docs/devel/qgraph.rst
X: tests/qtest/bios-tables-test*
Device Fuzzing
@@ -12,6 +12,7 @@ Contents:
.. toctree::
:maxdepth: 2
+ :includehidden:
build-system
kconfig
new file mode 100644
@@ -0,0 +1,261 @@
+.. _qgraph:
+
+========================================
+Qtest Driver Framework
+========================================
+
+This Qgraph API provides all basic functions to create a graph
+and instantiate nodes representing machines, drivers and tests
+representing their relations with ``CONSUMES``, ``PRODUCES``, and
+``CONTAINS`` edges.
+
+The idea is to have a framework where each test asks for a specific
+driver, and the framework takes care of allocating the proper devices
+required and passing the correct command line arguments to QEMU.
+
+Nodes
+^^^^^^
+
+A node can be of four types:
+
+- **QNODE_MACHINE**: for example ``arm/raspi2``
+- **QNODE_DRIVER**: for example ``generic-sdhci``
+- **QNODE_INTERFACE**: for example ``sdhci`` (interface for all ``-sdhci``
+ drivers).
+ An interface is not explicitly created, it will be automatically
+ instantiated when a node consumes or produces it.
+- **QNODE_TEST**: for example ``sdhci-test``, consumes an interface and
+ tests the functions provided.
+
+Notes for the nodes:
+
+- QNODE_MACHINE: each machine struct must have a ``QGuestAllocator`` and
+ implement ``get_driver()`` to return the allocator mapped to the interface
+ "memory". The function can also return ``NULL`` if the allocator
+ is not set.
+- 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
+
+Edges
+^^^^^^
+
+An edge relation between two nodes (drivers or machines) `X` and `Y` can be:
+
+- ``X CONSUMES Y``: `Y` can be plugged into `X`
+- ``X PRODUCES Y``: `X` provides the interface `Y`
+- ``X CONTAINS Y``: `Y` is part of `X` component
+
+Execution steps
+^^^^^^^^^^^^^^^
+
+The basic framework steps are the following:
+
+- All nodes and edges are created in their respective
+ machine/driver/test files
+- 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)
+- The framework walks the graph starting from the available machines and
+ performs a Depth First Search for tests
+- 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
+- The test is executed
+- Unused objects are cleaned and the path discovery is continued
+
+Depending on the QEMU binary used, only some drivers/machines will be
+available and only test that are reached by them will be executed.
+
+Creating a new driver and its interface
+"""""""""""""""""""""""""""""""""""""""""
+
+.. code::
+
+ #include "qgraph.h"
+
+ struct My_driver {
+ QOSGraphObject obj;
+ Node_produced prod;
+ Node_contained cont;
+ }
+
+ static void my_destructor(QOSGraphObject *obj)
+ {
+ g_free(obj);
+ }
+
+ static void *my_get_driver(void *object, const char *interface) {
+ My_driver *dev = object;
+ if (!g_strcmp0(interface, "my_interface")) {
+ return &dev->prod;
+ }
+ abort();
+ }
+
+ static void *my_get_device(void *object, const char *device) {
+ My_driver *dev = object;
+ if (!g_strcmp0(device, "my_driver_contained")) {
+ return &dev->cont;
+ }
+ abort();
+ }
+
+ static void *my_driver_constructor(void *node_consumed,
+ QOSGraphObject *alloc)
+ {
+ My_driver dev = g_new(My_driver, 1);
+
+ // get the node pointed by the produce edge
+ dev->obj.get_driver = my_get_driver;
+
+ // get the node pointed by the contains
+ dev->obj.get_device = my_get_device;
+
+ // free the object
+ dev->obj.destructor = my_destructor;
+
+ do_something_with_node_consumed(node_consumed);
+
+ // set all fields of contained device
+ init_contained_device(&dev->cont);
+ return &dev->obj;
+ }
+
+ static void register_my_driver(void)
+ {
+ qos_node_create_driver("my_driver", my_driver_constructor);
+
+ // contained drivers don't need a constructor,
+ // they will be init by the parent.
+ qos_node_create_driver("my_driver_contained", NULL);
+
+ // For the sake of this example, assume machine x86_64/pc
+ // contains "other_node".
+ // This relation, along with the machine and "other_node"
+ // creation, should be defined in the x86_64_pc-machine.c file.
+ // "my_driver" will then consume "other_node"
+ qos_node_contains("my_driver", "my_driver_contained");
+ qos_node_produces("my_driver", "my_interface");
+ qos_node_consumes("my_driver", "other_node");
+ }
+
+In the above example, all possible types of relations are created:
+node "my_driver" consumes, contains and produces other nodes.
+More specifically::
+
+ x86_64/pc -->contains--> other_node <--consumes-- my_driver
+ |
+ my_driver_contained <--contains--+
+ |
+ my_interface <--produces--+
+
+or inverting the consumes edge in consumed_by::
+
+ x86_64/pc -->contains--> other_node --consumed_by--> my_driver
+ |
+ my_driver_contained <--contains--+
+ |
+ my_interface <--produces--+
+
+Creating new test
+"""""""""""""""""
+
+.. code::
+
+ #include "qgraph.h"
+
+ static void my_test_function(void *obj, void *data)
+ {
+ Node_produced *interface_to_test = obj;
+ // test interface_to_test
+ }
+
+ static void register_my_test(void)
+ {
+ qos_add_test("my_interface", "my_test", my_test_function);
+ }
+
+ libqos_init(register_my_test);
+
+Here a new test is created, consuming "my_interface" node
+and creating a valid path from a machine to a test.
+Final graph will be like this::
+
+ x86_64/pc --contains--> other_node <--consumes-- my_driver
+ |
+ my_driver_contained <--contains--+
+ |
+ my_test --consumes--> my_interface <--produces--+
+
+or inverting the consumes edge in consumed_by::
+
+ x86_64/pc --contains--> other_node --consumed_by--> my_driver
+ |
+ my_driver_contained <--contains--+
+ |
+ my_test <--consumed_by-- my_interface <--produces--+
+
+Assuming there the binary is
+``QTEST_QEMU_BINARY=./qemu-system-x86_64``
+a valid test path will be:
+``/x86_64/pc/other_node/my_driver/my_interface/my_test``.
+
+Additional examples are also in ``test-qgraph.c``
+
+Command line:
+""""""""""""""
+
+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:
+
+- ``in node`` : created from the node name. For example, machines will
+ have ``-M <machine>`` to its command line, while devices
+ ``-device <device>``. It is automatically done by the framework.
+- ``after node`` : added as additional argument to the node name.
+ This argument is added optionally when creating edges,
+ by setting the parameter @after_cmd_line and
+ @extra_edge_opts in #QOSGraphEdgeOptions.
+ The framework automatically adds
+ a comma before @extra_edge_opts,
+ because it is going to add attributes
+ after the destination node pointed by
+ the edge containing these options, and automatically
+ adds a space before @after_cmd_line, because it
+ adds an additional device, not an attribute.
+- ``before node`` : added as additional argument to the node name.
+ This argument is added optionally when creating edges,
+ by setting the parameter @before_cmd_line in
+ #QOSGraphEdgeOptions. 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 ``-fdsev`` or ``-netdev``.
+
+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 ``{ "abstract" : true }``
+as QMP attribute will loose their command line, since they are not proper
+devices to be added in QEMU.
+
+Example::
+
+ QOSGraphEdgeOptions opts = {
+ .arg = NULL,
+ .size_arg = 0,
+ .after_cmd_line = "-device other",
+ .before_cmd_line = "-netdev something",
+ .extra_edge_opts = "addr=04.0",
+ };
+ QOSGraphNodeS *node = qos_node_create_driver("my_node", constructor);
+ qos_node_consumes_args("my_node", "interface", &opts);
+
+Will produce the following command line:
+``-netdev something -device my_node,addr=04.0 -device other``
+
+Qgraph API reference
+^^^^^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: tests/qtest/libqos/qgraph.h
@@ -2,6 +2,11 @@
QTest Device Emulation Testing Framework
========================================
+.. toctree::
+ :hidden:
+
+ qgraph
+
QTest is a device emulation testing framework. It can be very useful to test
device models; it could also control certain aspects of QEMU (such as virtual
clock stepping), with a special purpose "qtest" protocol. Refer to
@@ -24,6 +29,9 @@ On top of libqtest, a higher level library, ``libqos``, was created to
encapsulate common tasks of device drivers, such as memory management and
communicating with system buses or devices. Many virtual device tests use
libqos instead of directly calling into libqtest.
+Libqos also offers the Qgraph API to increase each test coverage and
+automate QEMU command line arguments and devices setup.
+Refer to :ref:`qgraph` for Qgraph explanation and API.
Steps to add a new QTest case are:
@@ -29,7 +29,6 @@
typedef struct QOSGraphObject QOSGraphObject;
typedef struct QOSGraphNode QOSGraphNode;
typedef struct QOSGraphEdge QOSGraphEdge;
-typedef struct QOSGraphNodeOptions QOSGraphNodeOptions;
typedef struct QOSGraphEdgeOptions QOSGraphEdgeOptions;
typedef struct QOSGraphTestOptions QOSGraphTestOptions;
@@ -48,242 +47,6 @@ typedef void (*QOSStartFunct) (QOSGraphObject *object);
/* Test options functions */
typedef void *(*QOSBeforeTest) (GString *cmd_line, void *arg);
-/**
- * SECTION: qgraph.h
- * @title: Qtest Driver Framework
- * @short_description: interfaces to organize drivers and tests
- * as nodes in a graph
- *
- * This Qgraph API provides all basic functions to create a graph
- * and instantiate nodes representing machines, drivers and tests
- * representing their relations with CONSUMES, PRODUCES, and CONTAINS
- * edges.
- *
- * The idea is to have a framework where each test asks for a specific
- * driver, and the framework takes care of allocating the proper devices
- * required and passing the correct command line arguments to QEMU.
- *
- * A node can be of four types:
- * - QNODE_MACHINE: for example "arm/raspi2"
- * - QNODE_DRIVER: for example "generic-sdhci"
- * - QNODE_INTERFACE: for example "sdhci" (interface for all "-sdhci" drivers)
- * an interface is not explicitly created, it will be auto-
- * matically instantiated when a node consumes or produces
- * it.
- * - QNODE_TEST: for example "sdhci-test", consumes an interface and tests
- * the functions provided
- *
- * Notes for the nodes:
- * - QNODE_MACHINE: each machine struct must have a QGuestAllocator and
- * implement get_driver to return the allocator passing
- * "memory". The function can also return NULL if the
- * allocator is not set.
- * - 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
- *
- * An edge relation between two nodes (drivers or machines) X and Y can be:
- * - X CONSUMES Y: Y can be plugged into X
- * - X PRODUCES Y: X provides the interface Y
- * - X CONTAINS Y: Y is part of X component
- *
- * Basic framework steps are the following:
- * - All nodes and edges are created in their respective
- * machine/driver/test files
- * - 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)
- * - The framework walks the graph starting from the available machines and
- * performs a Depth First Search for tests
- * - 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
- * - The test is executed
- * - Unused objects are cleaned and the path discovery is continued
- *
- * Depending on the QEMU binary used, only some drivers/machines will be
- * available and only test that are reached by them will be executed.
- *
- * <example>
- * <title>Creating new driver an its interface</title>
- * <programlisting>
- #include "qgraph.h"
-
- struct My_driver {
- QOSGraphObject obj;
- Node_produced prod;
- Node_contained cont;
- }
-
- static void my_destructor(QOSGraphObject *obj)
- {
- g_free(obj);
- }
-
- static void my_get_driver(void *object, const char *interface) {
- My_driver *dev = object;
- if (!g_strcmp0(interface, "my_interface")) {
- return &dev->prod;
- }
- abort();
- }
-
- static void my_get_device(void *object, const char *device) {
- My_driver *dev = object;
- if (!g_strcmp0(device, "my_driver_contained")) {
- return &dev->cont;
- }
- abort();
- }
-
- static void *my_driver_constructor(void *node_consumed,
- QOSGraphObject *alloc)
- {
- My_driver dev = g_new(My_driver, 1);
- // get the node pointed by the produce edge
- dev->obj.get_driver = my_get_driver;
- // get the node pointed by the contains
- dev->obj.get_device = my_get_device;
- // free the object
- dev->obj.destructor = my_destructor;
- do_something_with_node_consumed(node_consumed);
- // set all fields of contained device
- init_contained_device(&dev->cont);
- return &dev->obj;
- }
-
- static void register_my_driver(void)
- {
- qos_node_create_driver("my_driver", my_driver_constructor);
- // contained drivers don't need a constructor,
- // they will be init by the parent.
- qos_node_create_driver("my_driver_contained", NULL);
-
- // For the sake of this example, assume machine x86_64/pc contains
- // "other_node".
- // This relation, along with the machine and "other_node" creation,
- // should be defined in the x86_64_pc-machine.c file.
- // "my_driver" will then consume "other_node"
- qos_node_contains("my_driver", "my_driver_contained");
- qos_node_produces("my_driver", "my_interface");
- qos_node_consumes("my_driver", "other_node");
- }
- * </programlisting>
- * </example>
- *
- * In the above example, all possible types of relations are created:
- * node "my_driver" consumes, contains and produces other nodes.
- * more specifically:
- * x86_64/pc -->contains--> other_node <--consumes-- my_driver
- * |
- * my_driver_contained <--contains--+
- * |
- * my_interface <--produces--+
- *
- * or inverting the consumes edge in consumed_by:
- *
- * x86_64/pc -->contains--> other_node --consumed_by--> my_driver
- * |
- * my_driver_contained <--contains--+
- * |
- * my_interface <--produces--+
- *
- * <example>
- * <title>Creating new test</title>
- * <programlisting>
- * #include "qgraph.h"
- *
- * static void my_test_function(void *obj, void *data)
- * {
- * Node_produced *interface_to_test = obj;
- * // test interface_to_test
- * }
- *
- * static void register_my_test(void)
- * {
- * qos_add_test("my_interface", "my_test", my_test_function);
- * }
- *
- * libqos_init(register_my_test);
- *
- * </programlisting>
- * </example>
- *
- * Here a new test is created, consuming "my_interface" node
- * and creating a valid path from a machine to a test.
- * Final graph will be like this:
- * x86_64/pc -->contains--> other_node <--consumes-- my_driver
- * |
- * my_driver_contained <--contains--+
- * |
- * my_test --consumes--> my_interface <--produces--+
- *
- * or inverting the consumes edge in consumed_by:
- *
- * x86_64/pc -->contains--> other_node --consumed_by--> my_driver
- * |
- * my_driver_contained <--contains--+
- * |
- * my_test <--consumed_by-- my_interface <--produces--+
- *
- * Assuming there the binary is
- * QTEST_QEMU_BINARY=./qemu-system-x86_64
- * a valid test path will be:
- * "/x86_64/pc/other_node/my_driver/my_interface/my_test".
- *
- * Additional examples are also in test-qgraph.c
- *
- * Command line:
- * 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:
- * - in node : created from the node name. For example, machines will
- * have "-M <machine>" to its command line, while devices
- * "-device <device>". It is automatically done by the
- * framework.
- * - after node : added as additional argument to the node name.
- * This argument is added optionally when creating edges,
- * by setting the parameter @after_cmd_line and
- * @extra_edge_opts in #QOSGraphEdgeOptions.
- * The framework automatically adds
- * a comma before @extra_edge_opts,
- * because it is going to add attributes
- * after the destination node pointed by
- * the edge containing these options, and automatically
- * adds a space before @after_cmd_line, because it
- * adds an additional device, not an attribute.
- * - before node : added as additional argument to the node name.
- * This argument is added optionally when creating edges,
- * by setting the parameter @before_cmd_line in
- * #QOSGraphEdgeOptions. 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 "-fdsev" or "-netdev".
- *
- * 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 { "abstract" : true }
- * as QMP attribute will loose their command line, since they are not proper
- * devices to be added in QEMU.
- *
- * Example:
- *
- QOSGraphEdgeOptions opts = {
- .arg = NULL,
- .size_arg = 0,
- .after_cmd_line = "-device other",
- .before_cmd_line = "-netdev something",
- .extra_edge_opts = "addr=04.0",
- };
- QOSGraphNode * node = qos_node_create_driver("my_node", constructor);
- qos_node_consumes_args("my_node", "interface", &opts);
- *
- * Will produce the following command line:
- * "-netdev something -device my_node,addr=04.0 -device other"
- */
-
/**
* Edge options to be passed to the contains/consumes *_args function.
*/
@@ -399,24 +162,30 @@ void qos_graph_init(void);
void qos_graph_destroy(void);
/**
- * qos_node_destroy(): removes and frees a node from the,
+ * qos_node_destroy(): removes and frees a node from the
* nodes hash table.
+ * @key: Name of the node
*/
void qos_node_destroy(void *key);
/**
- * qos_edge_destroy(): removes and frees an edge from the,
+ * qos_edge_destroy(): removes and frees an edge from the
* edges hash table.
+ * @key: Name of the node
*/
void qos_edge_destroy(void *key);
/**
* qos_add_test(): adds a test node @name to the nodes hash table.
+ * @name: Name of the test
+ * @interface: Name of the interface node it consumes
+ * @test_func: Actual test to perform
+ * @opts: Facultative options (see %QOSGraphTestOptions)
*
* 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 %QOSGraphNodeOptions).
+ * add an optional @opts (see %QOSGraphTestOptions).
*
* For tests, opts->edge.arg and size_arg represent the arg to pass
* to @test_func
@@ -428,6 +197,8 @@ void qos_add_test(const char *name, const char *interface,
/**
* qos_node_create_machine(): creates the machine @name and
* adds it to the node hash table.
+ * @name: Name of the machine
+ * @function: Machine constructor
*
* This node will be of type QNODE_MACHINE and have @function
* as constructor
@@ -438,6 +209,9 @@ void qos_node_create_machine(const char *name, QOSCreateMachineFunc function);
* qos_node_create_machine_args(): same as qos_node_create_machine,
* but with the possibility to add an optional ", @opts" after -M machine
* command line.
+ * @name: Name of the machine
+ * @function: Machine constructor
+ * @pts: Optional additional command line
*/
void qos_node_create_machine_args(const char *name,
QOSCreateMachineFunc function,
@@ -446,6 +220,8 @@ void qos_node_create_machine_args(const char *name,
/**
* qos_node_create_driver(): creates the driver @name and
* adds it to the node hash table.
+ * @name: Name of the driver
+ * @function: Driver constructor
*
* This node will be of type QNODE_DRIVER and have @function
* as constructor
@@ -453,17 +229,17 @@ void qos_node_create_machine_args(const char *name,
void qos_node_create_driver(const char *name, QOSCreateDriverFunc function);
/**
- * Behaves as qos_node_create_driver() with the extension of allowing to
- * specify a different node name vs. associated QEMU device name.
+ * qos_node_create_driver_named(): behaves as qos_node_create_driver() with the
+ * extension of allowing to specify a different node name vs. associated QEMU
+ * device name.
+ * @name: Custom, unique name of the node to be created
+ * @qemu_name: Actual (official) QEMU driver name the node shall be
+ * associated with
+ * @function: Driver constructor
*
* 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.
- *
- * @param name: custom, unique name of the node to be created
- * @param qemu_name: actual (official) QEMU driver name the node shall be
- * associated with
- * @param function: driver constructor
*/
void qos_node_create_driver_named(const char *name, const char *qemu_name,
QOSCreateDriverFunc function);
@@ -472,6 +248,9 @@ void qos_node_create_driver_named(const char *name, const char *qemu_name,
* qos_node_contains(): creates one or more edges of type QEDGE_CONTAINS
* and adds them to the edge list mapped to @container in the
* edge hash table.
+ * @container: Source node that "contains"
+ * @contained: Destination node that "is contained"
+ * @opts: Facultative options (see %QOSGraphEdgeOptions)
*
* The edges will have @container as source and @contained as destination.
*
@@ -483,14 +262,17 @@ void qos_node_create_driver_named(const char *name, const char *qemu_name,
* This function can be useful when there are multiple devices
* with the same node name contained in a machine/other node
*
- * For example, if "arm/raspi2" contains 2 "generic-sdhci"
+ * For example, if ``arm/raspi2`` contains 2 ``generic-sdhci``
* devices, the right commands will be:
- * qos_node_create_machine("arm/raspi2");
- * qos_node_create_driver("generic-sdhci", constructor);
- * //assume rest of the fields are set NULL
- * QOSGraphEdgeOptions op1 = { .edge_name = "emmc" };
- * QOSGraphEdgeOptions op2 = { .edge_name = "sdcard" };
- * qos_node_contains("arm/raspi2", "generic-sdhci", &op1, &op2, NULL);
+ *
+ * .. code::
+ *
+ * qos_node_create_machine("arm/raspi2");
+ * qos_node_create_driver("generic-sdhci", constructor);
+ * // assume rest of the fields are set NULL
+ * QOSGraphEdgeOptions op1 = { .edge_name = "emmc" };
+ * QOSGraphEdgeOptions op2 = { .edge_name = "sdcard" };
+ * qos_node_contains("arm/raspi2", "generic-sdhci", &op1, &op2, NULL);
*
* Of course this also requires that the @container's get_device function
* should implement a case for "emmc" and "sdcard".
@@ -505,6 +287,8 @@ void qos_node_contains(const char *container, const char *contained,
* qos_node_produces(): creates an edge of type QEDGE_PRODUCES and
* adds it to the edge list mapped to @producer in the
* edge hash table.
+ * @producer: Source node that "produces"
+ * @interface: Interface node that "is produced"
*
* This edge will have @producer as source and @interface as destination.
*/
@@ -514,6 +298,9 @@ void qos_node_produces(const char *producer, const char *interface);
* qos_node_consumes(): creates an edge of type QEDGE_CONSUMED_BY and
* adds it to the edge list mapped to @interface in the
* edge hash table.
+ * @consumer: Node that "consumes"
+ * @interface: Interface node that "is consumed by"
+ * @opts: Facultative options (see %QOSGraphEdgeOptions)
*
* This edge will have @interface as source and @consumer as destination.
* It also has the possibility to add an optional @opts
@@ -539,7 +326,7 @@ const char *qos_get_current_command_line(void);
/**
* qos_allocate_objects():
* @qts: The #QTestState that will be referred to by the machine object.
- * @alloc: Where to store the allocator for the machine object, or %NULL.
+ * @p_alloc: Where to store the allocator for the machine object, or %NULL.
*
* Allocate driver objects for the current test
* path, but relative to the QTestState @qts.
@@ -551,24 +338,27 @@ void *qos_allocate_objects(QTestState *qts, QGuestAllocator **p_alloc);
/**
* qos_object_destroy(): calls the destructor for @obj
+ * @obj: A #QOSGraphObject to destroy
*/
void qos_object_destroy(QOSGraphObject *obj);
/**
* qos_object_queue_destroy(): queue the destructor for @obj so that it is
* called at the end of the test
+ * @obj: A #QOSGraphObject to destroy
*/
void qos_object_queue_destroy(QOSGraphObject *obj);
/**
* qos_object_start_hw(): calls the start_hw function for @obj
+ * @obj: A #QOSGraphObject containing the start_hw function
*/
void qos_object_start_hw(QOSGraphObject *obj);
/**
* qos_machine_new(): instantiate a new machine node
- * @node: A machine node to be instantiated
- * @qts: The #QTestState that will be referred to by the machine object.
+ * @node: Machine node to be instantiated
+ * @qts: A #QTestState that will be referred to by the machine object.
*
* Returns a machine object.
*/
@@ -587,8 +377,8 @@ QOSGraphObject *qos_driver_new(QOSGraphNode *node, QOSGraphObject *parent,
QGuestAllocator *alloc, void *arg);
/**
- * Just for debugging purpose: prints all currently existing nodes and
- * edges to stdout.
+ * qos_dump_graph(): prints all currently existing nodes and
+ * edges to stdout. Just for debugging purposes.
*
* All qtests add themselves to the overall qos graph by calling qgraph
* functions that add device nodes and edges between the individual graph
Change documentation style and fix minor typos in tests/qtest/libqos/qgraph.h to automatically generate sphinx documentation in docs/devel/qgraph.rst The mechanism explanation that once was in qgraph.h is now moved to qgraph.rst There is no functional change intended. v2: - qgraph link visible in docs/devel/index but not in docs/index, since it is a subsection of qtest. Signed-off-by: Emanuele Giuseppe Esposito <eesposit@redhat.com> --- MAINTAINERS | 1 + docs/devel/index.rst | 1 + docs/devel/qgraph.rst | 261 ++++++++++++++++++++++++++++++ docs/devel/qtest.rst | 8 + tests/qtest/libqos/qgraph.h | 308 ++++++------------------------------ 5 files changed, 320 insertions(+), 259 deletions(-) create mode 100644 docs/devel/qgraph.rst