/*
* libqos driver framework
*
* Copyright (c) 2018 Emanuele Giuseppe Esposito <e.emanuelegiuseppe@gmail.com>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License version 2.1 as published by the Free Software Foundation.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, see <http://www.gnu.org/licenses/>
*/
#ifndef QGRAPH_H
#define QGRAPH_H
#include <gmodule.h>
#include "qemu/module.h"
#include "malloc.h"
/* maximum path length */
#define QOS_PATH_MAX_ELEMENT_SIZE 50
typedef struct QOSGraphObject QOSGraphObject;
typedef struct QOSGraphNode QOSGraphNode;
typedef struct QOSGraphEdge QOSGraphEdge;
typedef struct QOSGraphEdgeOptions QOSGraphEdgeOptions;
typedef struct QOSGraphTestOptions QOSGraphTestOptions;
/* Constructor for drivers, machines and test */
typedef void *(*QOSCreateDriverFunc) (void *parent, QGuestAllocator *alloc,
void *addr);
typedef void *(*QOSCreateMachineFunc) (QTestState *qts);
typedef void (*QOSTestFunc) (void *parent, void *arg, QGuestAllocator *alloc);
/* QOSGraphObject functions */
typedef void *(*QOSGetDriver) (void *object, const char *interface);
typedef QOSGraphObject *(*QOSGetDevice) (void *object, const char *name);
typedef void (*QOSDestructorFunc) (QOSGraphObject *object);
typedef void (*QOSStartFunct) (QOSGraphObject *object);
/* Test options functions */
typedef void *(*QOSBeforeTest) (GString *cmd_line, void *arg);
/**
* struct QOSGraphEdgeOptions:
* Edge options to be passed to the contains/consumes \*_args function.
* @arg: optional arg that will be used by dest edge
* @size_arg: @arg size that will be used by dest edge
* @extra_device_opts: optional additional command line for dest
* edge, used to add additional attributes
* *after* the node command line, the
* framework automatically prepends ","
* to this argument.
* @before_cmd_line: optional additional command line for dest
* edge, used to add additional attributes
* *before* the node command line, usually
* other non-node represented commands,
* like "-fdsev synt"
* @after_cmd_line: optional extra command line to be added
* after the device command. This option
* is used to add other devices
* command line that depend on current node.
* Automatically prepends " " to this argument
* @edge_name: optional edge to differentiate multiple
* devices with same node name
*/
struct QOSGraphEdgeOptions {
void *arg;
uint32_t size_arg;
const char *extra_device_opts;
const char *before_cmd_line;
const char *after_cmd_line;
const char *edge_name;
};
/**
* struct QOSGraphTestOptions:
* Test options to be passed to the test functions.
* @edge: edge arguments that will be used by test.
* Note that test *does not* use edge_name,
* and uses instead arg and size_arg as
* data arg for its test function.
* @arg: if @before is non-NULL, pass @arg there.
* Otherwise pass it to the test function.
* @before: executed before the test. Used to add
* additional parameters to the command line
* and modify the argument to the test function.
* @subprocess: run the test in a subprocess.
*/
struct QOSGraphTestOptions {
QOSGraphEdgeOptions edge;
void *arg;
QOSBeforeTest before;
bool subprocess;
};
/**
* struct QOSGraphObject:
* Each driver, test or machine of this framework will have a
* QOSGraphObject as first field.
*
* This set of functions offered by QOSGraphObject are executed
* in different stages of the framework:
* @get_driver: see @get_device
* @get_device: Once a machine-to-test path has been
* found, the framework traverses it again and allocates all the
* nodes, using the provided constructor. To satisfy their
* relations, i.e. for produces or contains, where a struct
* constructor needs an external parameter represented by the
* previous node, the framework will call
* @get_device (for contains) or @get_driver (for produces),
* depending on the edge type, passing them the name of the next
* node to be taken and getting from them the corresponding
* pointer to the actual structure of the next node to
* be used in the path.
* @start_hw: This function is executed after all the path objects
* have been allocated, but before the test is run. It starts the
* hw, setting the initial configurations (\*_device_enable) and
* making it ready for the test.
* @destructor: Opposite to the node constructor, destroys the object.
* This function is called after the test has been executed, and
* performs a complete cleanup of each node allocated field.
* In case no constructor is provided, no destructor will be
* called.
* @free: free the memory associated to the QOSGraphObject and its contained
* children
*/
struct QOSGraphObject {
QOSGetDriver get_driver;
QOSGetDevice get_device;
QOSStartFunct start_hw;
QOSDestructorFunc destructor;
GDestroyNotify free;
};
/**
* qos_graph_init(): initialize the framework, creates two hash
* tables: one for the nodes and another for the edges.
*/
void qos_graph_init(void);
/**
* qos_graph_destroy(): deallocates all the hash tables,
* freeing all nodes and edges.
*/
void qos_graph_destroy(void);
/**
* 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
* 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 %QOSGraphTestOptions).
*
* For tests, opts->edge.arg and size_arg represent the arg to pass
* to @test_func
*/
void qos_add_test(const char *name, const char *interface,
QOSTestFunc test_func,
QOSGraphTestOptions *opts);
/**
* 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
*/
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
* @opts: Optional additional command line
*/
void qos_node_create_machine_args(const char *name,
QOSCreateMachineFunc function,
const char *opts);
/**
* 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
*/
void qos_node_create_driver(const char *name, QOSCreateDriverFunc function);
/**
* 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.
*/
void qos_node_create_driver_named(const char *name, const char *qemu_name,
QOSCreateDriverFunc function);
/**
* 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.
*
* If @opts is NULL, a single edge will be added with no options.
* If @opts is non-NULL, the arguments after @contained represent a
* NULL-terminated list of %QOSGraphEdgeOptions structs, and an
* edge will be added for each of them.
*
* 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/raspi2b`` contains 2 ``generic-sdhci``
* devices, the right commands will be:
*
* .. code::
*
* qos_node_create_machine("arm/raspi2b");
* 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/raspi2b", "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".
*
* For contains, op1.arg and op1.size_arg represent the arg to pass
* to @contained constructor to properly initialize it.
*/
void qos_node_contains(const char *container, const char *contained,
QOSGraphEdgeOptions *opts, ...);
/**
* 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.
*/
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
* (see %QOSGraphEdgeOptions)
*/
void qos_node_consumes(const char *consumer, const char *interface,
QOSGraphEdgeOptions *opts);
/**
* qos_invalidate_command_line(): invalidates current command line, so that
* qgraph framework cannot try to cache the current command line and
* forces QEMU to restart.
*/
void qos_invalidate_command_line(void);
/**
* qos_get_current_command_line(): return the command line required by the
* machine and driver objects. This is the same string that was passed to
* the test's "before" callback, if any.
*/
const char *qos_get_current_command_line(void);
/**
* qos_allocate_objects():
* @qts: The #QTestState that will be referred to by the machine object.
* @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.
*
* Returns a test object just like the one that was passed to
* the test function, but relative to @qts.
*/
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: Machine node to be instantiated
* @qts: A #QTestState that will be referred to by the machine object.
*
* Returns a machine object.
*/
QOSGraphObject *qos_machine_new(QOSGraphNode *node, QTestState *qts);
/**
* qos_machine_new(): instantiate a new driver node
* @node: A driver node to be instantiated
* @parent: A #QOSGraphObject to be consumed by the new driver node
* @alloc: An allocator to be used by the new driver node.
* @arg: The argument for the consumed-by edge to @node.
*
* Calls the constructor for the driver object.
*/
QOSGraphObject *qos_driver_new(QOSGraphNode *node, QOSGraphObject *parent,
QGuestAllocator *alloc, void *arg);
/**
* 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
* nodes for tests. As the actual graph is assmbled at runtime by the qos
* subsystem, it is sometimes not obvious how the overall graph looks like.
* E.g. when writing new tests it may happen that those new tests are simply
* ignored by the qtest framework.
*
* This function allows to identify problems in the created qgraph. Keep in
* mind: only tests with a path down from the actual test case node (leaf) up
* to the graph's root node are actually executed by the qtest framework. And
* the qtest framework uses QMP to automatically check which QEMU drivers are
* actually currently available, and accordingly qos marks certain pathes as
* 'unavailable' in such cases (e.g. when QEMU was compiled without support for
* a certain feature).
*/
void qos_dump_graph(void);
#endif
