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_WRAPPER_H
29#define MMAL_WRAPPER_H
30
31/** \defgroup MmalComponentWrapper utility
32 * \ingroup MmalUtilities
33 * The component wrapper utility functions can be used in place of common sequences
34 * of calls to the MMAL API in order to control a standalone component. It hides some
35 * of the complexity in using standalone components behind a fully synchronous
36 * interface.
37 * @{
38 */
39
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44/** Forward type definition for a wrapper */
45typedef struct MMAL_WRAPPER_T MMAL_WRAPPER_T;
46
47/** Definition of the callback used by a wrapper to signal back to the client
48 * that a buffer header is available either in the pool or in the output queue.
49 *
50 * @param wrapper Pointer to the wrapper
51 */
52typedef void (*MMAL_WRAPPER_CALLBACK_T)(MMAL_WRAPPER_T *wrapper);
53
54/** Structure describing a wrapper around a component */
55struct MMAL_WRAPPER_T {
56
57 void *user_data; /**< Field reserved for use by the client. */
58 MMAL_WRAPPER_CALLBACK_T callback; /**< Callback set by the client. */
59 MMAL_COMPONENT_T *component;
60 MMAL_STATUS_T status;
61
62 MMAL_PORT_T *control; /**< Control port (Read Only). */
63
64 uint32_t input_num; /**< Number of input ports (Read Only). */
65 MMAL_PORT_T **input; /**< Array of input ports (Read Only). */
66 MMAL_POOL_T **input_pool; /**< Array of input pools (Read Only). */
67
68 uint32_t output_num; /**< Number of output ports (Read Only). */
69 MMAL_PORT_T **output; /**< Array of output ports (Read Only). */
70 MMAL_POOL_T **output_pool; /**< Array of output pools (Read Only). */
71 MMAL_QUEUE_T **output_queue; /**< Array of output queues (Read Only). */
72
73 /* Used for debug / statistics */
74 int64_t time_setup; /**< Time in microseconds taken to setup the connection. */
75 int64_t time_enable; /**< Time in microseconds taken to enable the connection. */
76 int64_t time_disable; /**< Time in microseconds taken to disable the connection. */
77
78};
79
80/** Create a wrapper around a component.
81 * The wrapper shall include a pool of buffer headers for each port. The pools will be suitable
82 * for the current format of its associated port.
83 *
84 * @param wrapper The address of a wrapper pointer that will be set to point to the created
85 * wrapper.
86 * @param name The name of the component to create.
87 * @return MMAL_SUCCESS on success.
88 */
89MMAL_STATUS_T mmal_wrapper_create(MMAL_WRAPPER_T **wrapper, const char *name);
90
91/** \name MMAL wrapper flags
92 * \anchor wrapperflags
93 */
94/* @{ */
95/** The operation should be blocking */
96#define MMAL_WRAPPER_FLAG_WAIT 1
97/** The pool for the port should allocate memory for the payloads */
98#define MMAL_WRAPPER_FLAG_PAYLOAD_ALLOCATE 2
99/** The port will use shared memory payloads */
100#define MMAL_WRAPPER_FLAG_PAYLOAD_USE_SHARED_MEMORY 4
101/* @} */
102
103/** Enable a port on a component wrapper.
104 *
105 * @param port port to enable
106 * @param flags used to specify payload allocation flags for the pool
107 * @return MMAL_SUCCESS on success.
108 */
109MMAL_STATUS_T mmal_wrapper_port_enable(MMAL_PORT_T *port, uint32_t flags);
110
111/** Disable a port on a component wrapper.
112 *
113 * @param port port to disable
114 * @return MMAL_SUCCESS on success.
115 */
116MMAL_STATUS_T mmal_wrapper_port_disable(MMAL_PORT_T *port);
117
118/** Wait for an empty buffer to be available on a port.
119 *
120 * @param port port to get an empty buffer from
121 * @param buffer points to the retreived buffer on return
122 * @param flags specify MMAL_WRAPPER_FLAG_WAIT for a blocking operation
123 * @return MMAL_SUCCESS on success.
124 */
125MMAL_STATUS_T mmal_wrapper_buffer_get_empty(MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T **buffer, uint32_t flags);
126
127/** Wait for a full buffer to be available on a port.
128 *
129 * @param port port to get a full buffer from
130 * @param buffer points to the retreived buffer on return
131 * @param flags specify MMAL_WRAPPER_FLAG_WAIT for a blocking operation
132 * @return MMAL_SUCCESS on success.
133 */
134MMAL_STATUS_T mmal_wrapper_buffer_get_full(MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T **buffer, uint32_t flags);
135
136/** Cancel any ongoing blocking operation on a component wrapper.
137 *
138 * @param wrapper The wrapper on which to cancel operations.
139 * @return MMAL_SUCCESS on success.
140 */
141MMAL_STATUS_T mmal_wrapper_cancel(MMAL_WRAPPER_T *wrapper);
142
143/** Destroy a wrapper.
144 * Destroys a component wrapper and any resources it owns.
145 *
146 * @param wrapper The wrapper to be destroyed.
147 * @return MMAL_SUCCESS on success.
148 */
149MMAL_STATUS_T mmal_wrapper_destroy(MMAL_WRAPPER_T *wrapper);
150
151#ifdef __cplusplus
152}
153#endif
154
155/** @} */
156
157#endif /* MMAL_WRAPPER_H */
158