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_UTIL_H
29#define MMAL_UTIL_H
30
31#include "interface/mmal/mmal.h"
32
33/** \defgroup MmalUtilities Utility functions
34 * The utility functions provide helpers for common functionality that is not part
35 * of the core MMAL API.
36 * @{
37 */
38
39/** Offset in bytes of FIELD in TYPE. */
40#define MMAL_OFFSET(TYPE, FIELD) ((size_t)((uint8_t *)&((TYPE*)0)->FIELD - (uint8_t *)0))
41
42#ifdef __cplusplus
43extern "C" {
44#endif
45
46/** Convert a status to a statically-allocated string.
47 *
48 * @param status The MMAL status code.
49 * @return A C string describing the status code.
50 */
51const char *mmal_status_to_string(MMAL_STATUS_T status);
52
53/** Convert stride to pixel width for a given pixel encoding.
54 *
55 * @param encoding The pixel encoding (such as one of the \ref MmalEncodings "pre-defined encodings")
56 * @param stride The stride in bytes.
57 * @return The width in pixels.
58 */
59uint32_t mmal_encoding_stride_to_width(uint32_t encoding, uint32_t stride);
60
61/** Convert pixel width to stride for a given pixel encoding
62 *
63 * @param encoding The pixel encoding (such as one of the \ref MmalEncodings "pre-defined encodings")
64 * @param width The width in pixels.
65 * @return The stride in bytes.
66 */
67uint32_t mmal_encoding_width_to_stride(uint32_t encoding, uint32_t width);
68
69/** Return the 16 line high sliced version of a given pixel encoding
70 *
71 * @param encoding The pixel encoding (such as one of the \ref MmalEncodings "pre-defined encodings")
72 * @return The sliced equivalent, or MMAL_ENCODING_UNKNOWN if not supported.
73 */
74uint32_t mmal_encoding_get_slice_variant(uint32_t encoding);
75
76/** Convert a port type to a string.
77 *
78 * @param type The MMAL port type.
79 * @return A NULL-terminated string describing the port type.
80 */
81const char* mmal_port_type_to_string(MMAL_PORT_TYPE_T type);
82
83/** Get a parameter from a port allocating the required amount of memory
84 * for the parameter (i.e. for variable length parameters like URI or arrays).
85 * The size field will be set on output to the actual size of the
86 * parameter allocated and retrieved.
87 *
88 * The pointer returned must be released by a call to \ref mmal_port_parameter_free().
89 *
90 * @param port port to send request to
91 * @param id parameter id
92 * @param size initial size hint for allocation (can be 0)
93 * @param status status of the parameter get operation (can be 0)
94 * @return pointer to the header of the parameter or NULL on failure.
95 */
96MMAL_PARAMETER_HEADER_T *mmal_port_parameter_alloc_get(MMAL_PORT_T *port,
97 uint32_t id, uint32_t size, MMAL_STATUS_T *status);
98
99/** Free a parameter structure previously allocated via
100 * \ref mmal_port_parameter_alloc_get().
101 *
102 * @param param pointer to header of the parameter
103 */
104void mmal_port_parameter_free(MMAL_PARAMETER_HEADER_T *param);
105
106/** Copy buffer header metadata from source to destination.
107 *
108 * @param dest The destination buffer header.
109 * @param src The source buffer header.
110 */
111void mmal_buffer_header_copy_header(MMAL_BUFFER_HEADER_T *dest, const MMAL_BUFFER_HEADER_T *src);
112
113/** Create a pool of MMAL_BUFFER_HEADER_T associated with a specific port.
114 * This allows a client to allocate memory for the payload buffers based on the preferences
115 * of a port. This for instance will allow the port to allocate memory which can be shared
116 * between the host processor and videocore.
117 * After allocation, all allocated buffer headers will have been added to the queue.
118 *
119 * It is valid to create a pool with no buffer headers, or with zero size payload buffers.
120 * The mmal_pool_resize() function can be used to increase or decrease the number of buffer
121 * headers, or the size of the payload buffers, after creation of the pool.
122 *
123 * @param port Port responsible for creating the pool.
124 * @param headers Number of buffers which will be allocated with the pool.
125 * @param payload_size Size of the payload buffer which will be allocated in
126 * each of the buffer headers.
127 * @return Pointer to the newly created pool or NULL on failure.
128 */
129MMAL_POOL_T *mmal_port_pool_create(MMAL_PORT_T *port,
130 unsigned int headers, uint32_t payload_size);
131
132/** Destroy a pool of MMAL_BUFFER_HEADER_T associated with a specific port.
133 * This will also deallocate all of the memory which was allocated when creating or
134 * resizing the pool.
135 *
136 * @param port Pointer to the port responsible for creating the pool.
137 * @param pool Pointer to the pool to be destroyed.
138 */
139void mmal_port_pool_destroy(MMAL_PORT_T *port, MMAL_POOL_T *pool);
140
141/** Log the content of a \ref MMAL_PORT_T structure.
142 *
143 * @param port Pointer to the port to dump.
144 */
145void mmal_log_dump_port(MMAL_PORT_T *port);
146
147/** Log the content of a \ref MMAL_ES_FORMAT_T structure.
148 *
149 * @param format Pointer to the format to dump.
150 */
151void mmal_log_dump_format(MMAL_ES_FORMAT_T *format);
152
153/** Return the nth port.
154 *
155 * @param comp component to query
156 * @param index port index
157 * @param type port type
158 *
159 * @return port or NULL if not found
160 */
161MMAL_PORT_T *mmal_util_get_port(MMAL_COMPONENT_T *comp, MMAL_PORT_TYPE_T type, unsigned index);
162
163/** Convert a 4cc into a string.
164 *
165 * @param buf Destination for result
166 * @param len Size of result buffer
167 * @param fourcc 4cc to be converted
168 * @return converted string (buf)
169 *
170 */
171char *mmal_4cc_to_string(char *buf, size_t len, uint32_t fourcc);
172
173
174/** On FW prior to June 2016, camera and video_splitter
175 * had BGR24 and RGB24 support reversed.
176 * This is now fixed, and this function will return whether the
177 * FW has the fix or not.
178 *
179 * @param port MMAL port to check (on camera or video_splitter)
180 * @return 0 if old firmware, 1 if new.
181 *
182 */
183int mmal_util_rgb_order_fixed(MMAL_PORT_T *port);
184
185#ifdef __cplusplus
186}
187#endif
188
189/** @} */
190
191#endif
192