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_PORT_H
29#define MMAL_PORT_H
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/** \defgroup MmalPort Ports
36 * Definition of a MMAL port and its associated API */
37/* @{ */
38
39#include "mmal_types.h"
40#include "mmal_format.h"
41#include "mmal_buffer.h"
42#include "mmal_parameters.h"
43
44/** List of port types */
45typedef enum
46{
47 MMAL_PORT_TYPE_UNKNOWN = 0, /**< Unknown port type */
48 MMAL_PORT_TYPE_CONTROL, /**< Control port */
49 MMAL_PORT_TYPE_INPUT, /**< Input port */
50 MMAL_PORT_TYPE_OUTPUT, /**< Output port */
51 MMAL_PORT_TYPE_CLOCK, /**< Clock port */
52 MMAL_PORT_TYPE_INVALID = 0xffffffff /**< Dummy value to force 32bit enum */
53
54} MMAL_PORT_TYPE_T;
55
56/** \name Port capabilities
57 * \anchor portcapabilities
58 * The following flags describe the capabilities advertised by a port */
59/* @{ */
60/** The port is pass-through and doesn't need buffer headers allocated */
61#define MMAL_PORT_CAPABILITY_PASSTHROUGH 0x01
62/** The port wants to allocate the buffer payloads. This signals a preference that
63 * payload allocation should be done on this port for efficiency reasons. */
64#define MMAL_PORT_CAPABILITY_ALLOCATION 0x02
65/** The port supports format change events. This applies to input ports and is used
66 * to let the client know whether the port supports being reconfigured via a format
67 * change event (i.e. without having to disable the port). */
68#define MMAL_PORT_CAPABILITY_SUPPORTS_EVENT_FORMAT_CHANGE 0x04
69/* @} */
70
71/** Definition of a port.
72 * A port is the entity that is exposed by components to receive or transmit
73 * buffer headers (\ref MMAL_BUFFER_HEADER_T). A port is defined by its
74 * \ref MMAL_ES_FORMAT_T.
75 *
76 * It may be possible to override the buffer requirements of a port by using
77 * the MMAL_PARAMETER_BUFFER_REQUIREMENTS parameter.
78 */
79typedef struct MMAL_PORT_T
80{
81 struct MMAL_PORT_PRIVATE_T *priv; /**< Private member used by the framework */
82 const char *name; /**< Port name. Used for debugging purposes (Read Only) */
83
84 MMAL_PORT_TYPE_T type; /**< Type of the port (Read Only) */
85 uint16_t index; /**< Index of the port in its type list (Read Only) */
86 uint16_t index_all; /**< Index of the port in the list of all ports (Read Only) */
87
88 uint32_t is_enabled; /**< Indicates whether the port is enabled or not (Read Only) */
89 MMAL_ES_FORMAT_T *format; /**< Format of the elementary stream */
90
91 uint32_t buffer_num_min; /**< Minimum number of buffers the port requires (Read Only).
92 This is set by the component. */
93 uint32_t buffer_size_min; /**< Minimum size of buffers the port requires (Read Only).
94 This is set by the component. */
95 uint32_t buffer_alignment_min; /**< Minimum alignment requirement for the buffers (Read Only).
96 A value of zero means no special alignment requirements.
97 This is set by the component. */
98 uint32_t buffer_num_recommended; /**< Number of buffers the port recommends for optimal performance (Read Only).
99 A value of zero means no special recommendation.
100 This is set by the component. */
101 uint32_t buffer_size_recommended; /**< Size of buffers the port recommends for optimal performance (Read Only).
102 A value of zero means no special recommendation.
103 This is set by the component. */
104 uint32_t buffer_num; /**< Actual number of buffers the port will use.
105 This is set by the client. */
106 uint32_t buffer_size; /**< Actual maximum size of the buffers that will be sent
107 to the port. This is set by the client. */
108
109 struct MMAL_COMPONENT_T *component; /**< Component this port belongs to (Read Only) */
110 struct MMAL_PORT_USERDATA_T *userdata; /**< Field reserved for use by the client */
111
112 uint32_t capabilities; /**< Flags describing the capabilities of a port (Read Only).
113 * Bitwise combination of \ref portcapabilities "Port capabilities"
114 * values.
115 */
116
117} MMAL_PORT_T;
118
119/** Commit format changes on a port.
120 *
121 * @param port The port for which format changes are to be committed.
122 * @return MMAL_SUCCESS on success
123 */
124MMAL_STATUS_T mmal_port_format_commit(MMAL_PORT_T *port);
125
126/** Definition of the callback used by a port to send a \ref MMAL_BUFFER_HEADER_T
127 * back to the user.
128 *
129 * @param port The port sending the buffer header.
130 * @param buffer The buffer header being sent.
131 */
132typedef void (*MMAL_PORT_BH_CB_T)(MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer);
133
134/** Enable processing on a port
135 *
136 * If this port is connected to another, the given callback must be NULL, while for a
137 * disconnected port, the callback must be non-NULL.
138 *
139 * If this is a connected output port and is successfully enabled:
140 * <ul>
141 * <li>The port shall be populated with a pool of buffers, allocated as required, according
142 * to the buffer_num and buffer_size values.
143 * <li>The input port to which it is connected shall be set to the same buffer
144 * configuration and then be enabled. Should that fail, the original port shall be
145 * disabled.
146 * </ul>
147 *
148 * @param port port to enable
149 * @param cb callback use by the port to send a \ref MMAL_BUFFER_HEADER_T back
150 * @return MMAL_SUCCESS on success
151 */
152MMAL_STATUS_T mmal_port_enable(MMAL_PORT_T *port, MMAL_PORT_BH_CB_T cb);
153
154/** Disable processing on a port
155 *
156 * Disabling a port will stop all processing on this port and return all (non-processed)
157 * buffer headers to the client.
158 *
159 * If this is a connected output port, the input port to which it is connected shall
160 * also be disabled. Any buffer pool shall be released.
161 *
162 * @param port port to disable
163 * @return MMAL_SUCCESS on success
164 */
165MMAL_STATUS_T mmal_port_disable(MMAL_PORT_T *port);
166
167/** Ask a port to release all the buffer headers it currently has.
168 *
169 * Flushing a port will ask the port to send all the buffer headers it currently has
170 * to the client. Flushing is an asynchronous request and the flush call will
171 * return before all the buffer headers are returned to the client.
172 * It is up to the client to keep a count on the buffer headers to know when the
173 * flush operation has completed.
174 * It is also important to note that flushing will also reset the state of the port
175 * and any processing which was buffered by the port will be lost.
176 *
177 * \attention Flushing a connected port behaviour TBD.
178 *
179 * @param port The port to flush.
180 * @return MMAL_SUCCESS on success
181 */
182MMAL_STATUS_T mmal_port_flush(MMAL_PORT_T *port);
183
184/** Set a parameter on a port.
185 *
186 * @param port The port to which the request is sent.
187 * @param param The pointer to the header of the parameter to set.
188 * @return MMAL_SUCCESS on success
189 */
190MMAL_STATUS_T mmal_port_parameter_set(MMAL_PORT_T *port,
191 const MMAL_PARAMETER_HEADER_T *param);
192
193/** Get a parameter from a port.
194 * The size field must be set on input to the maximum size of the parameter
195 * (including the header) and will be set on output to the actual size of the
196 * parameter retrieved.
197 *
198 * \note If MMAL_ENOSPC is returned, the parameter is larger than the size
199 * given. The given parameter will have been filled up to its size and then
200 * the size field set to the full parameter's size. This can be used to
201 * resize the parameter buffer so that a second call should succeed.
202 *
203 * @param port The port to which the request is sent.
204 * @param param The pointer to the header of the parameter to get.
205 * @return MMAL_SUCCESS on success
206 */
207MMAL_STATUS_T mmal_port_parameter_get(MMAL_PORT_T *port,
208 MMAL_PARAMETER_HEADER_T *param);
209
210/** Send a buffer header to a port.
211 *
212 * @param port The port to which the buffer header is to be sent.
213 * @param buffer The buffer header to send.
214 * @return MMAL_SUCCESS on success
215 */
216MMAL_STATUS_T mmal_port_send_buffer(MMAL_PORT_T *port,
217 MMAL_BUFFER_HEADER_T *buffer);
218
219/** Connect an output port to an input port.
220 *
221 * When connected and enabled, buffers will automatically progress from the
222 * output port to the input port when they become available, and released back
223 * to the output port when no longer required by the input port.
224 *
225 * Ports can be given either way around, but one must be an output port and
226 * the other must be an input port. Neither can be connected or enabled
227 * already. The format of the output port will be applied to the input port
228 * on connection.
229 *
230 * @param port One of the ports to connect.
231 * @param other_port The other port to connect.
232 * @return MMAL_SUCCESS on success.
233 */
234MMAL_STATUS_T mmal_port_connect(MMAL_PORT_T *port, MMAL_PORT_T *other_port);
235
236/** Disconnect a connected port.
237 *
238 * If the port is not connected, an error will be returned. Otherwise, if the
239 * ports are enabled, they will be disabled and any buffer pool created will be
240 * freed.
241 *
242 * @param port The ports to disconnect.
243 * @return MMAL_SUCCESS on success.
244 */
245MMAL_STATUS_T mmal_port_disconnect(MMAL_PORT_T *port);
246
247/** Allocate a payload buffer.
248 * This allows a client to allocate memory for a payload buffer based on the preferences
249 * of a port. This for instance will allow the port to allocate memory which can be shared
250 * between the host processor and videocore.
251 *
252 * See \ref mmal_pool_create_with_allocator().
253 *
254 * @param port Port responsible for allocating the memory.
255 * @param payload_size Size of the payload buffer which will be allocated.
256 *
257 * @return Pointer to the allocated memory.
258 */
259uint8_t *mmal_port_payload_alloc(MMAL_PORT_T *port, uint32_t payload_size);
260
261/** Free a payload buffer.
262 * This allows a client to free memory allocated by a previous call to \ref mmal_port_payload_alloc.
263 *
264 * See \ref mmal_pool_create_with_allocator().
265 *
266 * @param port Port responsible for allocating the memory.
267 * @param payload Pointer to the memory to free.
268 */
269void mmal_port_payload_free(MMAL_PORT_T *port, uint8_t *payload);
270
271/** Get an empty event buffer header from a port
272 *
273 * @param port The port from which to get the event buffer header.
274 * @param buffer The address of a buffer header pointer, which will be set on return.
275 * @param event The specific event FourCC required. See the \ref MmalEvents "pre-defined events".
276 * @return MMAL_SUCCESS on success
277 */
278MMAL_STATUS_T mmal_port_event_get(MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T **buffer, uint32_t event);
279
280/* @} */
281
282#ifdef __cplusplus
283}
284#endif
285
286#endif /* MMAL_PORT_H */
287