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_CONNECTION_H
29#define MMAL_CONNECTION_H
30
31/** \defgroup MmalConnectionUtility Port connection utility
32 * \ingroup MmalUtilities
33 * The port connection utility functions can be used in place of common sequences
34 * of calls to the MMAL API in order to process buffers being passed between two
35 * ports.
36 *
37 * \section ProcessingConnectionBufferHeaders Processing connection buffer headers
38 * Either in response to the client callback function being called, or simply on a
39 * timer, the client will need to process the buffer headers of the connection
40 * (unless tunneling is used).
41 *
42 * Buffer headers that are in the pool queue will need to be sent to the output port,
43 * while buffer headers in the connection queue are sent to the input port. The
44 * buffer headers in the connection queue may contain pixel data (the cmd field is
45 * zero) or an event (the cmd field is non-zero). In general, pixel data buffer
46 * headers need to be passed on, while event buffer headers are released. In the
47 * case of the format changed event, mmal_connection_event_format_changed() can be
48 * called before the event is released.
49 *
50 * Other, specialized use cases may also be implemented, such as getting and
51 * immediately releasing buffer headers from the connection queue in order to
52 * prevent their propagation. This could be used to drop out video, for example.
53 *
54 * \section TunnellingConnections Tunnelling connections
55 * If the \ref MMAL_CONNECTION_FLAG_TUNNELLING flag is set when the connection is
56 * created, MMAL tunneling will be used. This automates the passing of the buffer
57 * headers between the output port and input port, and back again. It will also do
58 * this as efficiently as possible, avoiding trips between the ARM and the VideoCore
59 * if both components are implemented on the VideoCore. The consequence of this is
60 * that there is no client callback made as buffer headers get transferred.
61 *
62 * The client can still monitor the control port of a component (usually a sink
63 * component, such as video_render) for the end of stream, in order to know when to
64 * dismantle the connection.
65 *
66 * \section ConnectionClientCallback Client callback
67 * When not using tunnelling, the client callback function is called each time a
68 * buffer arrives from a port (either input or output).
69 *
70 * \note The callback is made on a different thread from the one used by the
71 * client to set up the connection, so care must be taken with thread safety.
72 * One option is to raise a signal to the main client thread that queue processing
73 * needs to be done, another is for the callback to perform the queue processing
74 * itself.
75 *
76 * The client can also store an opaque pointer in the connection object, which is
77 * never used by the MMAL code and is only meaningful to the client.
78 *
79 * @{
80 */
81
82#ifdef __cplusplus
83extern "C" {
84#endif
85
86/** \name Connection flags
87 * \anchor connectionflags
88 * The following flags describe the properties of the connection. */
89/* @{ */
90/** The connection is tunnelled. Buffer headers do not transit via the client but
91 * directly from the output port to the input port. */
92#define MMAL_CONNECTION_FLAG_TUNNELLING 0x1
93/** Force the pool of buffer headers used by the connection to be allocated on the input port. */
94#define MMAL_CONNECTION_FLAG_ALLOCATION_ON_INPUT 0x2
95/** Force the pool of buffer headers used by the connection to be allocated on the output port. */
96#define MMAL_CONNECTION_FLAG_ALLOCATION_ON_OUTPUT 0x4
97/** Specify that the connection should not modify the buffer requirements. */
98#define MMAL_CONNECTION_FLAG_KEEP_BUFFER_REQUIREMENTS 0x8
99/** The connection is flagged as direct. This doesn't change the behaviour of
100 * the connection itself but is used by the the graph utility to specify that
101 * the buffer should be sent to the input port from with the port callback. */
102#define MMAL_CONNECTION_FLAG_DIRECT 0x10
103/** Specify that the connection should not modify the port formats. */
104#define MMAL_CONNECTION_FLAG_KEEP_PORT_FORMATS 0x20
105/* @} */
106
107/** Forward type definition for a connection */
108typedef struct MMAL_CONNECTION_T MMAL_CONNECTION_T;
109
110/** Definition of the callback used by a connection to signal back to the client
111 * that a buffer header is available either in the pool or in the output queue.
112 *
113 * @param connection Pointer to the connection
114 */
115typedef void (*MMAL_CONNECTION_CALLBACK_T)(MMAL_CONNECTION_T *connection);
116
117/** Structure describing a connection between 2 ports (1 output and 1 input port) */
118struct MMAL_CONNECTION_T {
119
120 void *user_data; /**< Field reserved for use by the client. */
121 MMAL_CONNECTION_CALLBACK_T callback; /**< Callback set by the client. */
122
123 uint32_t is_enabled; /**< Specifies whether the connection is enabled or not (Read Only). */
124
125 uint32_t flags; /**< Flags passed during the create call (Read Only). A bitwise
126 * combination of \ref connectionflags "Connection flags" values.
127 */
128 MMAL_PORT_T *in; /**< Input port used for the connection (Read Only). */
129 MMAL_PORT_T *out; /**< Output port used for the connection (Read Only). */
130
131 MMAL_POOL_T *pool; /**< Pool of buffer headers used by the output port (Read Only). */
132 MMAL_QUEUE_T *queue; /**< Queue for the buffer headers produced by the output port (Read Only). */
133
134 const char *name; /**< Connection name (Read Only). Used for debugging purposes. */
135
136 /* Used for debug / statistics */
137 int64_t time_setup; /**< Time in microseconds taken to setup the connection. */
138 int64_t time_enable; /**< Time in microseconds taken to enable the connection. */
139 int64_t time_disable; /**< Time in microseconds taken to disable the connection. */
140};
141
142/** Create a connection between two ports.
143 * The connection shall include a pool of buffer headers suitable for the current format of
144 * the output port. The format of the input port shall have been set to the same as that of
145 * the input port.
146 * Note that connections are reference counted and creating a connection automatically
147 * acquires a reference to it (released when \ref mmal_connection_destroy is called).
148 *
149 * @param connection The address of a connection pointer that will be set to point to the created
150 * connection.
151 * @param out The output port to use for the connection.
152 * @param in The input port to use for the connection.
153 * @param flags The flags specifying which type of connection should be created.
154 * A bitwise combination of \ref connectionflags "Connection flags" values.
155 * @return MMAL_SUCCESS on success.
156 */
157MMAL_STATUS_T mmal_connection_create(MMAL_CONNECTION_T **connection,
158 MMAL_PORT_T *out, MMAL_PORT_T *in, uint32_t flags);
159
160/** Acquire a reference on a connection.
161 * Acquiring a reference on a connection will prevent a connection from being destroyed until
162 * the acquired reference is released (by a call to \ref mmal_connection_destroy).
163 * References are internally counted so all acquired references need a matching call to
164 * release them.
165 *
166 * @param connection connection to acquire
167 */
168void mmal_connection_acquire(MMAL_CONNECTION_T *connection);
169
170/** Release a reference on a connection
171 * Release an acquired reference on a connection. Triggers the destruction of the connection when
172 * the last reference is being released.
173 * \note This is in fact an alias of \ref mmal_connection_destroy which is added to make client
174 * code clearer.
175 *
176 * @param connection connection to release
177 * @return MMAL_SUCCESS on success
178 */
179MMAL_STATUS_T mmal_connection_release(MMAL_CONNECTION_T *connection);
180
181/** Destroy a connection.
182 * Release an acquired reference on a connection. Only actually destroys the connection when
183 * the last reference is being released.
184 * The actual destruction of the connection will start by disabling it, if necessary.
185 * Any pool, queue, and so on owned by the connection shall then be destroyed.
186 *
187 * @param connection The connection to be destroyed.
188 * @return MMAL_SUCCESS on success.
189 */
190MMAL_STATUS_T mmal_connection_destroy(MMAL_CONNECTION_T *connection);
191
192/** Enable a connection.
193 * The format of the two ports must have been committed before calling this function,
194 * although note that on creation, the connection automatically copies and commits the
195 * output port's format to the input port.
196 *
197 * The MMAL_CONNECTION_T::callback field must have been set if the \ref MMAL_CONNECTION_FLAG_TUNNELLING
198 * flag was not specified on creation. The client may also set the MMAL_CONNECTION_T::user_data
199 * in order to get a pointer passed, via the connection, to the callback.
200 *
201 * @param connection The connection to be enabled.
202 * @return MMAL_SUCCESS on success.
203 */
204MMAL_STATUS_T mmal_connection_enable(MMAL_CONNECTION_T *connection);
205
206/** Disable a connection.
207 *
208 * @param connection The connection to be disabled.
209 * @return MMAL_SUCCESS on success.
210 */
211MMAL_STATUS_T mmal_connection_disable(MMAL_CONNECTION_T *connection);
212
213/** Apply a format changed event to the connection.
214 * This function can be used when the client is processing buffer headers and receives
215 * a format changed event (\ref MMAL_EVENT_FORMAT_CHANGED). The connection is
216 * reconfigured, changing the format of the ports, the number of buffer headers and
217 * the size of the payload buffers as necessary.
218 *
219 * @param connection The connection to which the event shall be applied.
220 * @param buffer The buffer containing a format changed event.
221 * @return MMAL_SUCCESS on success.
222 */
223MMAL_STATUS_T mmal_connection_event_format_changed(MMAL_CONNECTION_T *connection,
224 MMAL_BUFFER_HEADER_T *buffer);
225
226#ifdef __cplusplus
227}
228#endif
229
230/** @} */
231
232#endif /* MMAL_CONNECTION_H */
233