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/** \file
29 * Multi-Media Abstraction Layer API
30 */
31
32#ifndef MMAL_H
33#define MMAL_H
34
35/**
36 *
37 * \mainpage Multi-Media Abstraction Layer (MMAL). Draft Version 0.1.
38 *
39 * \par Contents
40 * - \ref intro_sec
41 * - \ref features
42 * - \ref concepts
43 * - \ref comp
44 * - \ref create
45 * - \ref port
46 * - \ref buf
47 * - \ref queue
48 * - \ref pool
49 * - \ref param
50 * - \ref events
51 * - \ref version
52 * - \ref example
53 *
54 * \section intro_sec Introduction
55 *
56 * MMAL (Multi-Media Abstraction Layer) is a framework which is used to provide a host-side,
57 * simple and relatively low-level interface to multimedia components running on VideoCore.
58 * It also provides a component interface so that new components can be easily created and
59 * integrated into the framework.
60 *
61 * There is no requirement that all the components be running on VideoCore as MMAL doesn't
62 * put any restriction on where components live. The current implementation for instance
63 * provides some components which can be run on both host-side or VideoCore (e.g. the splitter
64 * component).
65 *
66 * \section features Features
67 *
68 * The MMAL API has been designed to support all the following features:
69 * - Sufficiently generic to support different kinds of multimedia component.
70 * - Simple to use from client side (mostly synchronous except where it matters).
71 * - Straightforward API for designing components (e.g. avoids multiple data paths, as found in RIL).
72 * - Allows for fully-optimised implementation of components (e.g. zero-copy buffer passing).
73 * - Portability (API is self-contained).
74 * - Supports multiple instances (e.g. of VideoCore).
75 * - Extensible without breaking source or binary backward compatibility.
76 *
77 * \section concepts API concepts
78 *
79 * The MMAL API is based on the concept of components, ports and buffer headers.
80 * Clients create MMAL components which expose ports for each individual
81 * elementary stream of data they support (e.g. audio/video). Components expose
82 * input ports to receive data from the client, and expose output ports
83 * to return data to the client.
84 *
85 * Data sent to or received from the component needs to be attached to a buffer header.
86 * Buffer headers are necessary because they contain buffer specific ancillary data which is
87 * necessary for the component and client to do their processing (e.g timestamps).
88 *
89 * \section comp Components
90 *
91 * MMAL lets clients create multi-media components (video encoders,
92 * video decoders, camera, and so-on) using a common API. Clients exchange
93 * data with components using buffer headers. A buffer header
94 * has a pointer to the payload data.
95 * Buffer headers are sent to and received from ports that are provided by components.
96 *
97 * A typical decoder component would have a single input port and a
98 * single output port, but the same architecture could also be used
99 * for components with different layouts (e.g. a camera with a
100 * capture and preview port, or a debugging component with just an input port).
101 *
102 * \subsection create Component Creation
103 *
104 * Each component is identified by a unique name. To create a specific component
105 * the client needs to call \ref mmal_component_create with the desired component's
106 * name as an argument.
107 * This call will return a context (\ref MMAL_COMPONENT_T) to the component. This
108 * context will expose the input and output ports (\ref MMAL_PORT_T) supported
109 * by this specific component.
110 *
111 * \note All VideoCore components have a name starting with the "vc." prefix (this prefix
112 * is used to distinguish when a creation request needs to be forwarded to VideoCore).
113 *
114 * \section port Component Ports
115 *
116 * A port (\ref MMAL_PORT_T) is the entity which exposes an elementary stream
117 * (\ref MMAL_ES_FORMAT_T) on a component. It is also the entity to which buffer headers
118 * (\ref MMAL_BUFFER_HEADER_T) are sent or from which they are received.
119 *
120 * Clients do not need to create ports. They are created automatically by
121 * the component when this one is created but the format of a port might need to
122 * be set by the client depending on the type of component the client is using.
123 *
124 * For example, for a video decoding component, one input port and one output port
125 * will be available. The format of the input port must be set by the
126 * client (using \ref mmal_port_format_commit) while the format of the output port
127 * will be automatically set by the component once the component has enough information
128 * to find out what its format should be.
129 *
130 * If the input port format contains enough information for the component to determine
131 * the format of the output port straight away, then the output port will be set to the proper
132 * format when \ref mmal_port_format_commit returns. Otherwise the output format will be set to
133 * \ref MMAL_ENCODING_UNKNOWN until the component is fed enough data to determine the format
134 * of the output port.
135 * When this happens, the client will receive an event on the output port, signalling
136 * that its format has changed.
137 *
138 * \section buf Buffer Headers
139 *
140 * Buffer headers (\ref MMAL_BUFFER_HEADER_T) are used to exchange data with components.
141 * They do not contain the data directly but instead contain a pointer to the data being
142 * transferred.
143 *
144 * Separating the buffer headers from the payload means that the memory for the data can
145 * be allocated outside of MMAL (e.g. if it is supplied by an external library) while still
146 * providing a consistent way to exchange data between clients and components.
147 *
148 * Buffer headers are allocated from pools and are reference counted. The refcount
149 * will drop when \ref mmal_buffer_header_release is called and the buffer header
150 * will be recycled to its pool when it reaches zero.
151 * The client can be notified when the buffer header is recycled so that it can recycle the
152 * associated payload memory as well.
153 *
154 * A pool of buffer headers should be created after committing the format of the port. When
155 * the format is changed, the minimum and recommended size and number of buffers may change.
156 *
157 * \note The current number of buffers and their size (\ref MMAL_PORT_T::buffer_num and \ref
158 * MMAL_PORT_T::buffer_size) are not modified by MMAL, and must be updated by the client as
159 * required after changes to a port's format.
160 *
161 * \subsection queue Queues of Buffer Headers
162 *
163 * Queues (\ref MMAL_QUEUE_T) are a facility that allows thread-safe processing of buffer headers
164 * from the client. Callbacks triggered by a MMAL component when it sends a buffer header to the
165 * client can simply put the buffer in a queue and let the main processing thread of the client
166 * get its data from the queue.
167 *
168 * \subsection pool Pools of Buffer Headers
169 *
170 * Pools (\ref MMAL_POOL_T) let clients allocate a fixed number of buffer headers, and
171 * a queue (\ref MMAL_QUEUE_T). They are used for buffer header allocation.
172 * Optionally a pool can also allocate the payload memory for the client.
173 *
174 * Pools can also be resized after creation, for example, if the port format is changed leading
175 * to a new number or size of buffers being required.
176 *
177 * \section param Port Parameters
178 *
179 * Components support setting and getting component specific parameters using
180 * \ref mmal_port_parameter_set and \ref mmal_port_parameter_get. Parameters
181 * are identified using an integer index; parameter data is binary. See the \ref MMAL_PARAMETER_IDS
182 * "Pre-defined MMAL parameter IDs" page for more information on the pre-defined parameters.
183 *
184 * \section events Port Events
185 *
186 * Components can generate events on their ports. Events are sent to clients
187 * as buffer headers and thus when the client receives a buffer header on one
188 * of the component's port it should check if the buffer header is an event
189 * and in which case process it and then release it (\ref mmal_buffer_header_release).
190 * The reason for transmitting events in-band with the actual data is that it
191 * is often very valuable to know exactly when the event happens relative to the
192 * the actual data (e.g. with a focus event, from which video frame are we in focus).\n
193 * Buffer headers used to transmit events are allocated internally by the framework
194 * so it is important to release the buffer headers with \ref mmal_buffer_header_release
195 * so the buffer headers make it back to their actual owner.
196 *
197 * Event buffer headers are allocated when the component is created, based on the
198 * minimum number and size of control port buffers set by the component. Component
199 * wide events (not port specific) are sent to the control port callback when that
200 * port is enabled. Port events are sent to the port callback, the same as data
201 * buffers, but the 'cmd' field is non-zero.
202 *
203 * \section version Versioning
204 *
205 * The API requires that the MMAL core be the same or more recent version
206 * as the components and clients. Clients and components can be older and
207 * the API will still work both at compile-time and run-time.
208 *
209 * \section example Example Code
210 *
211 * The following code is a simple example on how to do video decoding using MMAL. Note that
212 * the code is intended to be clear and illustrate how to use MMAL at its most fundamental
213 * level, not necessarily the most efficient way to achieve the same result. Use of opaque
214 * images, tunneling and zero-copy inter-processor buffers can all improve the performance
215 * or reduce the load.
216 *
217 * The \ref MmalConnectionUtility "Port Connection Utility" functions can also be used to
218 * replace much of the common "boilerplate" code, especially when a pipeline of several
219 * components needs to be processed.
220 *
221 * \code
222 * #include <mmal.h>
223 * ...
224 * static void input_callback(MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer)
225 * {
226 * // The decoder is done with the data, just recycle the buffer header into its pool
227 * mmal_buffer_header_release(buffer);
228 * }
229 * static void output_callback(MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer)
230 * {
231 * MMAL_QUEUE_T *queue = (MMAL_QUEUE_T *)port->userdata;
232 * mmal_queue_put(queue, buffer); // Queue the decoded video frame
233 * }
234 * ...
235 *
236 * MMAL_COMPONENT_T *decoder = 0;
237 * MMAL_STATUS_T status;
238 *
239 * // Create the video decoder component on VideoCore
240 * status = mmal_component_create("vc.ril.video_decoder", &decoder);
241 * ABORT_IF_ERROR(status);
242 *
243 * // Set format of video decoder input port
244 * MMAL_ES_FORMAT_T *format_in = decoder->input[0]->format;
245 * format_in->type = MMAL_ES_TYPE_VIDEO;
246 * format_in->encoding = MMAL_ENCODING_H264;
247 * format_in->es->video.width = 1280;
248 * format_in->es->video.height = 720;
249 * format_in->es->video.frame_rate.num = 30;
250 * format_in->es->video.frame_rate.den = 1;
251 * format_in->es->video.par.num = 1;
252 * format_in->es->video.par.den = 1;
253 * format_in->flags = MMAL_ES_FORMAT_FLAG_FRAMED;
254 * status = mmal_format_extradata_alloc(format_in, YOUR_H264_CODEC_HEADER_BYTES_SIZE);
255 * ABORT_IF_ERROR(status);
256 * format_in->extradata_size = YOUR_H264_CODEC_HEADER_BYTES_SIZE;
257 * memcpy(format_in->extradata, YOUR_H264_CODEC_HEADER_BYTES, format_in->extradata_size);
258 *
259 * status = mmal_port_format_commit(decoder->input[0]);
260 * ABORT_IF_ERROR(status);
261 *
262 * // Once the call to mmal_port_format_commit() on the input port returns, the decoder will
263 * // have set the format of the output port.
264 * // If the decoder still doesn t have enough information to determine the format of the
265 * // output port, the encoding will be set to unknown. As soon as the decoder receives
266 * // enough stream data to determine the format of the output port it will send an event
267 * // to the client to signal that the format of the port has changed.
268 * // However, for the sake of simplicity this example assumes that the decoder was given
269 * // all the necessary information right at the start (i.e. video format and codec header bytes)
270 * MMAL_FORMAT_T *format_out = decoder->output[0]->format;
271 * if (format_out->encoding == MMAL_ENCODING_UNKNOWN)
272 * ABORT();
273 *
274 * // Now we know the format of both ports and the requirements of the decoder, we can create
275 * // our buffer headers and their associated memory buffers. We use the buffer pool API for this.
276 * decoder->input[0]->buffer_num = decoder->input[0]->buffer_num_min;
277 * decoder->input[0]->buffer_size = decoder->input[0]->buffer_size_min;
278 * MMAL_POOL_T *pool_in = mmal_pool_create(decoder->input[0]->buffer_num,
279 * decoder->input[0]->buffer_size);
280 * decoder->output[0]->buffer_num = decoder->output[0]->buffer_num_min;
281 * decoder->output[0]->buffer_size = decoder->output[0]->buffer_size_min;
282 * MMAL_POOL_T *pool_out = mmal_pool_create(decoder->output[0]->buffer_num,
283 * decoder->output[0]->buffer_size);
284 *
285 * // Create a queue to store our decoded video frames. The callback we will get when
286 * // a frame has been decoded will put the frame into this queue.
287 * MMAL_QUEUE_T *queue_decoded_frames = mmal_queue_create();
288 * decoder->output[0]->userdata = (void)queue_decoded_frames;
289 *
290 * // Enable all the input port and the output port.
291 * // The callback specified here is the function which will be called when the buffer header
292 * // we sent to the component has been processed.
293 * status = mmal_port_enable(decoder->input[0], input_callback);
294 * ABORT_IF_ERROR(status);
295 * status = mmal_port_enable(decoder->output[0], output_callback);
296 * ABORT_IF_ERROR(status);
297 *
298 * // Enable the component. Components will only process data when they are enabled.
299 * status = mmal_component_enable(decoder);
300 * ABORT_IF_ERROR(status);
301 *
302 * // Data processing loop
303 * while (1)
304 * {
305 * MMAL_BUFFER_HEADER_T *buffer;
306 *
307 * // The client needs to implement its own blocking code.
308 * // (e.g. a semaphore which is posted when a buffer header is put in one of the queues)
309 * WAIT_FOR_QUEUES_TO_HAVE_BUFFERS();
310 *
311 * // Send empty buffers to the output port of the decoder to allow the decoder to start
312 * // producing frames as soon as it gets input data
313 * while ((buffer = mmal_queue_get(pool_out->queue)) != NULL)
314 * {
315 * status = mmal_port_send_buffer(decoder->output[0], buffer);
316 * ABORT_IF_ERROR(status);
317 * }
318 *
319 * // Send data to decode to the input port of the video decoder
320 * if ((buffer = mmal_queue_get(pool_in->queue)) != NULL)
321 * {
322 * READ_DATA_INTO_BUFFER(buffer);
323 *
324 * status = mmal_port_send_buffer(decoder->input[0], buffer);
325 * ABORT_IF_ERROR(status);
326 * }
327 *
328 * // Get our decoded frames. We also need to cope with events
329 * // generated from the component here.
330 * while ((buffer = mmal_queue_get(queue_decoded_frames)) != NULL)
331 * {
332 * if (buffer->cmd)
333 * {
334 * // This is an event. Do something with it and release the buffer.
335 * mmal_buffer_header_release(buffer);
336 * continue;
337 * }
338 *
339 * // We have a frame, do something with it (why not display it for instance?).
340 * // Once we're done with it, we release it. It will magically go back
341 * // to its original pool so it can be reused for a new video frame.
342 * mmal_buffer_header_release(buffer);
343 * }
344 * }
345 *
346 * // Cleanup everything
347 * mmal_component_destroy(decoder);
348 * mmal_pool_destroy(pool_in);
349 * mmal_pool_destroy(pool_out);
350 * mmal_queue_destroy(queue_decode_frames);
351 *
352 * \endcode
353 */
354
355#include "mmal_common.h"
356#include "mmal_types.h"
357#include "mmal_port.h"
358#include "mmal_component.h"
359#include "mmal_parameters.h"
360#include "mmal_queue.h"
361#include "mmal_pool.h"
362#include "mmal_events.h"
363
364/**/
365/** \name API Version
366 * The following define the version number of the API */
367/* @{ */
368/** Major version number.
369 * This changes when the API breaks in a way which is not backward compatible. */
370#define MMAL_VERSION_MAJOR 0
371/** Minor version number.
372 * This changes each time the API is extended in a way which is still source and
373 * binary compatible. */
374#define MMAL_VERSION_MINOR 1
375
376#define MMAL_VERSION (MMAL_VERSION_MAJOR << 16 | MMAL_VERSION_MINOR)
377#define MMAL_VERSION_TO_MAJOR(a) (a >> 16)
378#define MMAL_VERSION_TO_MINOR(a) (a & 0xFFFF)
379/* @} */
380
381#endif /* MMAL_H */
382