1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
28#ifndef MMAL_GRAPH_H
29#define MMAL_GRAPH_H
30
31#include "util/mmal_connection.h"
32
33/** \defgroup MmalGraphUtility Graph Utility
34 * \ingroup MmalUtilities
35 * The graph utility functions allows one to easily create graphs of MMAL components.
36 *
37 * @{
38 */
39
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44/** List of topology types */
45typedef enum
46{
47 MMAL_GRAPH_TOPOLOGY_ALL = 0, /**< All input ports and output ports are linked */
48 MMAL_GRAPH_TOPOLOGY_STRAIGHT, /**< Input ports and output ports of the same index are linked */
49 MMAL_GRAPH_TOPOLOGY_CUSTOM, /**< Custom defined topology */
50 MMAL_GRAPH_TOPOLOGY_MAX
51
52} MMAL_GRAPH_TOPOLOGY_T;
53
54/** Structure describing a graph */
55typedef struct MMAL_GRAPH_T
56{
57 /** Pointer to private data of the client */
58 struct MMAL_GRAPH_USERDATA_T *userdata;
59
60 /** Optional callback that the client can set to get notified when the graph is going to be destroyed */
61 void (*pf_destroy)(struct MMAL_GRAPH_T *);
62
63 /** Optional callback that the client can set to intercept parameter requests on ports exposed by the graph */
64 MMAL_STATUS_T (*pf_parameter_set)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port, const MMAL_PARAMETER_HEADER_T *param);
65 /** Optional callback that the client can set to intercept parameter requests on ports exposed by the graph */
66 MMAL_STATUS_T (*pf_parameter_get)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port, MMAL_PARAMETER_HEADER_T *param);
67 /** Optional callback that the client can set to intercept format commit calls on ports exposed by the graph */
68 MMAL_STATUS_T (*pf_format_commit)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port);
69 /** Optional callback that the client can set to intercept send buffer calls on ports exposed by the graph */
70 MMAL_STATUS_T (*pf_send_buffer)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer);
71 /** Optional callback that the client can set to intercept buffer callbacks on ports exposed by the graph */
72 MMAL_STATUS_T (*pf_return_buffer)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer);
73 /** Optional callback that the client can set to intercept payload alloc calls on ports exposed by the graph */
74 MMAL_STATUS_T (*pf_payload_alloc)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port, uint32_t payload_size, uint8_t **);
75 /** Optional callback that the client can set to intercept payload free calls on ports exposed by the graph */
76 MMAL_STATUS_T (*pf_payload_free)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port, uint8_t *payload);
77 /** Optional callback that the client can set to intercept flush calls on ports exposed by the graph */
78 MMAL_STATUS_T (*pf_flush)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port);
79 /** Optional callback that the client can set to control callbacks from the internal components of the graph */
80 /** Optional callback that the client can set to intercept enable calls on ports exposed by the graph */
81 MMAL_STATUS_T (*pf_enable)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port);
82 /** Optional callback that the client can set to intercept disable calls on ports exposed by the graph */
83 MMAL_STATUS_T (*pf_disable)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port);
84 /** Optional callback that the client can set to control callbacks from the internal components of the graph */
85 MMAL_STATUS_T (*pf_control_callback)(struct MMAL_GRAPH_T *, MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer);
86 /** Optional callback that the client can set to intercept component_enable/disable calls made to the graph */
87 MMAL_STATUS_T (*pf_graph_enable)(struct MMAL_GRAPH_T *, MMAL_BOOL_T enable);
88 /** Optional callback that the client can set to intercept buffers going through internal connections.
89 * This will only be triggered if the connection is not tunnelled */
90 MMAL_STATUS_T (*pf_connection_buffer)(struct MMAL_GRAPH_T *, MMAL_CONNECTION_T *connection, MMAL_BUFFER_HEADER_T *buffer);
91
92} MMAL_GRAPH_T;
93
94/** Create an instance of a graph.
95 * The newly created graph will need to be populated by the client.
96 *
97 * @param graph returned graph
98 * @param userdata_size size to be allocated for the userdata field
99 * @return MMAL_SUCCESS on success
100 */
101MMAL_STATUS_T mmal_graph_create(MMAL_GRAPH_T **graph, unsigned int userdata_size);
102
103/** Add a component to a graph.
104 * Allows the client to add a component to the graph.
105 *
106 * @param graph instance of the graph
107 * @param component component to add to a graph
108 * @return MMAL_SUCCESS on success
109 */
110MMAL_STATUS_T mmal_graph_add_component(MMAL_GRAPH_T *graph, MMAL_COMPONENT_T *component);
111
112/** Describe the topology of the ports of a component.
113 * Allows the client to describe the topology of a component. This information
114 * is used by the graph to choose which action to perform when
115 * enabling / disabling / committing / flushing a port exposed by the graph.
116 * Note that by default the topology of a component is set to MMAL_GRAPH_TOPOLOGY_ALL.
117 *
118 * @param graph instance of the graph
119 * @param component component to describe
120 * @param topology type of topology used by this component
121 * @param input output index (or -1 if sink) linked to each input port
122 * @param input_num number of indexes in the input list
123 * @param output input index (or -1 if source) linked to each output port
124 * @param output_num number of indexes in the output list
125 * @return MMAL_SUCCESS on success
126 */
127MMAL_STATUS_T mmal_graph_component_topology(MMAL_GRAPH_T *graph, MMAL_COMPONENT_T *component,
128 MMAL_GRAPH_TOPOLOGY_T topology, int8_t *input, unsigned int input_num,
129 int8_t *output, unsigned int output_num);
130
131/** Add a port to a graph.
132 * Allows the client to add an input or output port to a graph. The given port
133 * will effectively become an end point for the graph.
134 *
135 * @param graph instance of the graph
136 * @param port port to add to the graph
137 * @return MMAL_SUCCESS on success
138 */
139MMAL_STATUS_T mmal_graph_add_port(MMAL_GRAPH_T *graph, MMAL_PORT_T *port);
140
141/** Add a connection to a graph.
142 * Allows the client to add an internal connection to a graph.
143 *
144 * @param graph instance of the graph
145 * @param connection connection to add to the graph
146 * @return MMAL_SUCCESS on success
147 */
148MMAL_STATUS_T mmal_graph_add_connection(MMAL_GRAPH_T *graph, MMAL_CONNECTION_T *connection);
149
150/** Create a new component and add it to a graph.
151 * Allows the client to create and add a component to the graph.
152 *
153 * @param graph instance of the graph
154 * @param name name of the component to create
155 * @param component if not NULL, will contain a pointer to the created component
156 * @return MMAL_SUCCESS on success
157 */
158MMAL_STATUS_T mmal_graph_new_component(MMAL_GRAPH_T *graph, const char *name,
159 MMAL_COMPONENT_T **component);
160
161/** Create and add a connection to a graph.
162 * Allows the client to create and add an internal connection to a graph.
163 *
164 * @param graph instance of the graph
165 * @param out the output port to use for the connection
166 * @param in the input port to use for the connection
167 * @param flags the flags specifying which type of connection should be created
168 * @param connection if not NULL, will contain a pointer to the created connection
169 * @return MMAL_SUCCESS on success
170 */
171MMAL_STATUS_T mmal_graph_new_connection(MMAL_GRAPH_T *graph, MMAL_PORT_T *out, MMAL_PORT_T *in,
172 uint32_t flags, MMAL_CONNECTION_T **connection);
173
174/** Definition of the callback used by a graph to send events to the client.
175 *
176 * @param graph the graph sending the event
177 * @param port the port which generated the event
178 * @param buffer the buffer header containing the event data
179 * @param cb_data data passed back to the client when the callback is invoked
180 */
181typedef void (*MMAL_GRAPH_EVENT_CB)(MMAL_GRAPH_T *graph, MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer,
182 void *cb_data);
183
184/** Enable the graph and start processing.
185 *
186 * @param graph the graph to enable
187 * @param cb the callback to invoke when an event occurs on any of the internal control ports
188 * @param cb_data data passed back to the client when the callback is invoked
189 *
190 * @return MMAL_SUCCESS on success
191 */
192MMAL_STATUS_T mmal_graph_enable(MMAL_GRAPH_T *graph, MMAL_GRAPH_EVENT_CB cb, void *cb_data);
193
194MMAL_STATUS_T mmal_graph_disable(MMAL_GRAPH_T *graph);
195
196/** Find a port in the graph.
197 *
198 * @param graph graph instance
199 * @param name name of the component of interest
200 * @param type type of port (in/out)
201 * @param index which port index within the component
202 *
203 * @return port, or NULL if not found
204 */
205MMAL_PORT_T *mmal_graph_find_port(MMAL_GRAPH_T *graph,
206 const char *name,
207 MMAL_PORT_TYPE_T type,
208 unsigned index);
209
210/** Create an instance of a component from a graph.
211 * The newly created component will expose input and output ports to the client.
212 * Not that all the exposed ports will be in a disabled state by default.
213 *
214 * @param graph graph to create the component from
215 * @param name name of the component to create
216 * @param component returned component
217 * @return MMAL_SUCCESS on success
218 */
219MMAL_STATUS_T mmal_graph_build(MMAL_GRAPH_T *ctx,
220 const char *name, MMAL_COMPONENT_T **component);
221
222/** Component constructor for a graph.
223 * FIXME: private function
224 *
225 * @param name name of the component to create
226 * @param component component
227 * @return MMAL_SUCCESS on success
228 */
229MMAL_STATUS_T mmal_graph_component_constructor(const char *name, MMAL_COMPONENT_T *component);
230
231/** Destroy a previously created graph
232 * @param graph graph to destroy
233 * @return MMAL_SUCCESS on success
234 */
235MMAL_STATUS_T mmal_graph_destroy(MMAL_GRAPH_T *ctx);
236
237#ifdef __cplusplus
238}
239#endif
240
241/** @} */
242
243#endif /* MMAL_GRAPH_H */
244