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_BUFFER_H
29#define MMAL_BUFFER_H
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/** \defgroup MmalBufferHeader Buffer headers
36 * Definition of a buffer header and its associated API.
37 * Buffer headers are the basic element used to pass data and information between different
38 * parts of the system. They are passed to components via ports and sent back to the client
39 * using a callback mechanism.
40 */
41/* @{ */
42
43/** Specific data associated with video frames */
44typedef struct {
45 uint32_t planes; /**< Number of planes composing the video frame */
46 uint32_t offset[4]; /**< Offsets to the different planes. These must point within the
47 payload buffer */
48 uint32_t pitch[4]; /**< Pitch (size in bytes of a line of a plane) of the different
49 planes */
50 uint32_t flags; /**< Flags describing video specific properties of a buffer header
51 (see \ref videobufferheaderflags "Video buffer header flags") */
52 /* TBD stereoscopic support */
53} MMAL_BUFFER_HEADER_VIDEO_SPECIFIC_T;
54
55/** Type specific data that's associated with a payload buffer */
56typedef union
57{
58 /** Specific data associated with video frames */
59 MMAL_BUFFER_HEADER_VIDEO_SPECIFIC_T video;
60
61} MMAL_BUFFER_HEADER_TYPE_SPECIFIC_T;
62
63/** Definition of the buffer header structure.
64 * A buffer header does not directly carry the data to be passed to a component but instead
65 * it references the actual data using a pointer (and an associated length).
66 * It also contains an internal area which can be used to store command to be associated
67 * with the external data.
68 */
69typedef struct MMAL_BUFFER_HEADER_T
70{
71 struct MMAL_BUFFER_HEADER_T *next; /**< Used to link several buffer headers together */
72
73 struct MMAL_BUFFER_HEADER_PRIVATE_T *priv; /**< Data private to the framework */
74
75 uint32_t cmd; /**< Defines what the buffer header contains. This is a FourCC
76 with 0 as a special value meaning stream data */
77
78 uint8_t *data; /**< Pointer to the start of the payload buffer (should not be
79 changed by component) */
80 uint32_t alloc_size; /**< Allocated size in bytes of payload buffer */
81 uint32_t length; /**< Number of bytes currently used in the payload buffer (starting
82 from offset) */
83 uint32_t offset; /**< Offset in bytes to the start of valid data in the payload buffer */
84
85 uint32_t flags; /**< Flags describing properties of a buffer header (see
86 \ref bufferheaderflags "Buffer header flags") */
87
88 int64_t pts; /**< Presentation timestamp in microseconds. \ref MMAL_TIME_UNKNOWN
89 is used when the pts is unknown. */
90 int64_t dts; /**< Decode timestamp in microseconds (dts = pts, except in the case
91 of video streams with B frames). \ref MMAL_TIME_UNKNOWN
92 is used when the dts is unknown. */
93
94 /** Type specific data that's associated with a payload buffer */
95 MMAL_BUFFER_HEADER_TYPE_SPECIFIC_T *type;
96
97 void *user_data; /**< Field reserved for use by the client */
98
99} MMAL_BUFFER_HEADER_T;
100
101/** \name Buffer header flags
102 * \anchor bufferheaderflags
103 * The following flags describe properties of a buffer header */
104/* @{ */
105/** Signals that the current payload is the end of the stream of data */
106#define MMAL_BUFFER_HEADER_FLAG_EOS (1<<0)
107/** Signals that the start of the current payload starts a frame */
108#define MMAL_BUFFER_HEADER_FLAG_FRAME_START (1<<1)
109/** Signals that the end of the current payload ends a frame */
110#define MMAL_BUFFER_HEADER_FLAG_FRAME_END (1<<2)
111/** Signals that the current payload contains only complete frames (1 or more) */
112#define MMAL_BUFFER_HEADER_FLAG_FRAME (MMAL_BUFFER_HEADER_FLAG_FRAME_START|MMAL_BUFFER_HEADER_FLAG_FRAME_END)
113/** Signals that the current payload is a keyframe (i.e. self decodable) */
114#define MMAL_BUFFER_HEADER_FLAG_KEYFRAME (1<<3)
115/** Signals a discontinuity in the stream of data (e.g. after a seek).
116 * Can be used for instance by a decoder to reset its state */
117#define MMAL_BUFFER_HEADER_FLAG_DISCONTINUITY (1<<4)
118/** Signals a buffer containing some kind of config data for the component
119 * (e.g. codec config data) */
120#define MMAL_BUFFER_HEADER_FLAG_CONFIG (1<<5)
121/** Signals an encrypted payload */
122#define MMAL_BUFFER_HEADER_FLAG_ENCRYPTED (1<<6)
123/** Signals a buffer containing side information */
124#define MMAL_BUFFER_HEADER_FLAG_CODECSIDEINFO (1<<7)
125/** Signals a buffer which is the snapshot/postview image from a stills capture */
126#define MMAL_BUFFER_HEADER_FLAGS_SNAPSHOT (1<<8)
127/** Signals a buffer which contains data known to be corrupted */
128#define MMAL_BUFFER_HEADER_FLAG_CORRUPTED (1<<9)
129/** Signals that a buffer failed to be transmitted */
130#define MMAL_BUFFER_HEADER_FLAG_TRANSMISSION_FAILED (1<<10)
131/** Signals the output buffer won't be used, just update reference frames */
132#define MMAL_BUFFER_HEADER_FLAG_DECODEONLY (1<<11)
133/** Signals that the end of the current payload ends a NAL */
134#define MMAL_BUFFER_HEADER_FLAG_NAL_END (1<<12)
135/** User flags - can be passed in and will get returned */
136#define MMAL_BUFFER_HEADER_FLAG_USER0 (1<<28)
137#define MMAL_BUFFER_HEADER_FLAG_USER1 (1<<29)
138#define MMAL_BUFFER_HEADER_FLAG_USER2 (1<<30)
139#define MMAL_BUFFER_HEADER_FLAG_USER3 (1<<31)
140/* @} */
141
142/** \name Video buffer header flags
143 * \anchor videobufferheaderflags
144 * The following flags describe properties of a video buffer header.
145 * As there is no collision with the MMAL_BUFFER_HEADER_FLAGS_ defines, these
146 * flags will also be present in the MMAL_BUFFER_HEADER_T flags field.
147 */
148#define MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT 16
149#define MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START (1<<MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT)
150/* @{ */
151/** 16: Signals an interlaced video frame */
152#define MMAL_BUFFER_HEADER_VIDEO_FLAG_INTERLACED (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<0)
153/** 17: Signals that the top field of the current interlaced frame should be displayed first */
154#define MMAL_BUFFER_HEADER_VIDEO_FLAG_TOP_FIELD_FIRST (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<1)
155/** 19: Signals that the buffer should be displayed on external display if attached. */
156#define MMAL_BUFFER_HEADER_VIDEO_FLAG_DISPLAY_EXTERNAL (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<3)
157/** 20: Signals that contents of the buffer requires copy protection. */
158#define MMAL_BUFFER_HEADER_VIDEO_FLAG_PROTECTED (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<4)
159/** 27-24: If non-zero it signals the video frame is encoded in column mode,
160 * with a column width equal to 2^<masked value>.
161 * Zero is raster order. */
162#define MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_SHIFT (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT+8)
163#define MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_MASK (0xF<<MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_SHIFT)
164/* @} */
165
166/** Acquire a buffer header.
167 * Acquiring a buffer header increases a reference counter on it and makes sure that the
168 * buffer header won't be recycled until all the references to it are gone.
169 * This is useful for instance if a component needs to return a buffer header but still needs
170 * access to it for some internal processing (e.g. reference frames in video codecs).
171 *
172 * @param header buffer header to acquire
173 */
174void mmal_buffer_header_acquire(MMAL_BUFFER_HEADER_T *header);
175
176/** Reset a buffer header.
177 * Resets all header variables to default values.
178 *
179 * @param header buffer header to reset
180 */
181void mmal_buffer_header_reset(MMAL_BUFFER_HEADER_T *header);
182
183/** Release a buffer header.
184 * Releasing a buffer header will decrease its reference counter and when no more references
185 * are left, the buffer header will be recycled by calling its 'release' callback function.
186 *
187 * If a pre-release callback is set (\ref MMAL_BH_PRE_RELEASE_CB_T), this will be invoked
188 * before calling the buffer's release callback and potentially postpone buffer recycling.
189 * Once pre-release is complete the buffer header is recycled with
190 * \ref mmal_buffer_header_release_continue.
191 *
192 * @param header buffer header to release
193 */
194void mmal_buffer_header_release(MMAL_BUFFER_HEADER_T *header);
195
196/** Continue the buffer header release process.
197 * This should be called to complete buffer header recycling once all pre-release activity
198 * has been completed.
199 *
200 * @param header buffer header to release
201 */
202void mmal_buffer_header_release_continue(MMAL_BUFFER_HEADER_T *header);
203
204/** Buffer header pre-release callback.
205 * The callback is invoked just before a buffer is released back into a
206 * pool. This is used by clients who need to trigger additional actions
207 * before the buffer can finally be released (e.g. wait for a bulk transfer
208 * to complete).
209 *
210 * The callback should return TRUE if the buffer release need to be post-poned.
211 *
212 * @param header buffer header about to be released
213 * @param userdata user-specific data
214 *
215 * @return TRUE if the buffer should not be released
216 */
217typedef MMAL_BOOL_T (*MMAL_BH_PRE_RELEASE_CB_T)(MMAL_BUFFER_HEADER_T *header, void *userdata);
218
219/** Set a buffer header pre-release callback.
220 * If the callback is NULL, the buffer will be released back into the pool
221 * immediately as usual.
222 *
223 * @param header buffer header to associate callback with
224 * @param cb pre-release callback to invoke
225 * @param userdata user-specific data
226 */
227void mmal_buffer_header_pre_release_cb_set(MMAL_BUFFER_HEADER_T *header, MMAL_BH_PRE_RELEASE_CB_T cb, void *userdata);
228
229/** Replicate a buffer header into another one.
230 * Replicating a buffer header will not only do an exact copy of all the public fields of the
231 * buffer header (including data and alloc_size), but it will also acquire a reference to the
232 * source buffer header which will only be released once the replicate has been released.
233 *
234 * @param dest buffer header into which to replicate
235 * @param src buffer header to use as the source for the replication
236 * @return MMAL_SUCCESS on success
237 */
238MMAL_STATUS_T mmal_buffer_header_replicate(MMAL_BUFFER_HEADER_T *dest, MMAL_BUFFER_HEADER_T *src);
239
240/** Lock the data buffer contained in the buffer header in memory.
241 * This call does nothing on all platforms except VideoCore where it is needed to pin a
242 * buffer in memory before any access to it.
243 *
244 * @param header buffer header to lock
245 */
246MMAL_STATUS_T mmal_buffer_header_mem_lock(MMAL_BUFFER_HEADER_T *header);
247
248/** Unlock the data buffer contained in the buffer header.
249 * This call does nothing on all platforms except VideoCore where it is needed to un-pin a
250 * buffer in memory after any access to it.
251 *
252 * @param header buffer header to unlock
253 */
254void mmal_buffer_header_mem_unlock(MMAL_BUFFER_HEADER_T *header);
255
256/* @} */
257
258#ifdef __cplusplus
259}
260#endif
261
262#endif /* MMAL_BUFFER_H */
263