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_VC_API_H
29#define MMAL_VC_API_H
30
31/** @file
32 *
33 * Public API for MMAL VC client. Most functionality is exposed
34 * via MMAL itself.
35 */
36
37#include "interface/mmal/mmal_types.h"
38#include "interface/mmal/mmal_parameters.h"
39#include "interface/mmal/mmal_port.h"
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/** State of components created by the VC adaptation layer, used for
46 * statistics reporting.
47 */
48typedef enum {
49 MMAL_STATS_COMP_IDLE,
50 MMAL_STATS_COMP_CREATED,
51 MMAL_STATS_COMP_DESTROYING,
52 MMAL_STATS_COMP_DESTROYED,
53 MMAL_STATS_COMP_UNUSED = 0xffffffff /* force 32bit */
54} MMAL_STATS_COMP_STATE_T;
55
56/** Per-component statistics collected by the VC adaptation layer.
57 */
58struct MMAL_VC_COMP_STATS_T {
59 struct MMAL_DRIVER_COMPONENT_T *comp;
60 MMAL_STATS_COMP_STATE_T state;
61 uint32_t pid;
62 uint32_t pool_mem_alloc_size;
63 char name[20];
64};
65
66/** VC adaptation layer statistics.
67 */
68struct MMAL_VC_STATS_T
69{
70 struct
71 {
72 uint32_t rx; /**< Count of data buffers received */
73 uint32_t rx_zero_copy; /**< Count of zero-copy data buffers received */
74 uint32_t rx_empty; /**< Empty data buffers (to be filled) */
75 uint32_t rx_fails; /**< Gave up partway through */
76 uint32_t tx; /**< Count of data buffers sent */
77 uint32_t tx_zero_copy; /**< Count of zero-copy data buffers sent */
78 uint32_t tx_empty; /**< Count of empty data buffers sent */
79 uint32_t tx_fails; /**< Gave up partway through */
80 uint32_t tx_short_msg; /**< Messages sent directly in the control message */
81 uint32_t rx_short_msg; /**< Messages received directly in the control message */
82 } buffers;
83 struct service
84 {
85 uint32_t created; /**< How many services created */
86 uint32_t pending_destroy; /**< How many destroyed */
87 uint32_t destroyed; /**< How many destroyed */
88 uint32_t failures; /**< Failures to create a service */
89 } service;
90 struct commands
91 {
92 uint32_t bad_messages;
93 uint32_t executed;
94 uint32_t failed;
95 uint32_t replies;
96 uint32_t reply_fails;
97 } commands;
98 struct
99 {
100 uint32_t tx; /**< Count of events sent */
101 uint32_t tx_fails; /**< Count of events not fully sent */
102 } events;
103 struct
104 {
105 uint32_t created;
106 uint32_t destroyed;
107 uint32_t destroying;
108 uint32_t failed;
109 uint32_t list_size;
110 struct MMAL_VC_COMP_STATS_T component_list[8];
111 } components;
112 struct
113 {
114 uint32_t enqueued_messages;
115 uint32_t dequeued_messages;
116 uint32_t max_parameter_set_delay;
117 uint32_t max_messages_waiting;
118 } worker;
119
120};
121typedef struct MMAL_VC_STATS_T MMAL_VC_STATS_T;
122
123/* Simple circular text buffer used to store 'interesting' data
124 * from MMAL clients. e.g. settings for each picture taken */
125struct MMAL_VC_HOST_LOG_T
126{
127 /** Simple circular buffer of plain text log messages separated by NUL */
128 char buffer[16 << 10];
129 /** For VCDBG validation and to help detect buffer overflow */
130 uint32_t magic;
131 /** Write offset into buffer */
132 int32_t offset;
133 /** Counter of host messages logged since boot */
134 unsigned count;
135};
136typedef struct MMAL_VC_HOST_LOG_T MMAL_VC_HOST_LOG_T;
137
138/** Status from querying MMAL core statistics.
139 */
140typedef enum
141{
142 MMAL_STATS_FOUND,
143 MMAL_STATS_COMPONENT_NOT_FOUND,
144 MMAL_STATS_PORT_NOT_FOUND,
145 MMAL_STATS_INVALID = 0x7fffffff
146} MMAL_STATS_RESULT_T;
147
148/* If opening dev_vchiq outside mmal/vchiq this is the file path and mode */
149#define MMAL_DEV_VCHIQ_PATH "/dev/vchiq"
150#define MMAL_DEV_VCHIQ_MODE O_RDWR
151
152MMAL_STATUS_T mmal_vc_init(void);
153MMAL_STATUS_T mmal_vc_init_fd(int dev_vchiq_fd);
154void mmal_vc_deinit(void);
155
156MMAL_STATUS_T mmal_vc_use(void);
157MMAL_STATUS_T mmal_vc_release(void);
158
159MMAL_STATUS_T mmal_vc_get_version(uint32_t *major, uint32_t *minor, uint32_t *minimum);
160MMAL_STATUS_T mmal_vc_get_stats(MMAL_VC_STATS_T *stats, int reset);
161
162/** Return the MMAL core statistics for a given component/port.
163 *
164 * @param stats Updated with given port statistics
165 * @param result Whether the port/component was found
166 * @param name Filled in with the name of the port
167 * @param namelen Length of name
168 * @param component Which component (indexed from zero)
169 * @param port_type Which type of port
170 * @param port Which port (index from zero)
171 * @param reset Reset the stats.
172 */
173MMAL_STATUS_T mmal_vc_get_core_stats(MMAL_CORE_STATISTICS_T *stats,
174 MMAL_STATS_RESULT_T *result,
175 char *name,
176 size_t namelen,
177 MMAL_PORT_TYPE_T type,
178 unsigned component,
179 unsigned port,
180 MMAL_CORE_STATS_DIR dir,
181 MMAL_BOOL_T reset);
182/**
183 * Stores an arbitrary text message in a circular buffer inside the MMAL VC server.
184 * The purpose of this message is to log high level events from the host in order
185 * to diagnose problems that require multiple actions to reproduce. e.g. taking
186 * multiple pictures with different settings.
187 *
188 * @param msg The message text.
189 * @return MMAL_SUCCESS if the message was logged or MMAL_ENOSYS if the API
190 * if not supported.
191 */
192MMAL_STATUS_T mmal_vc_host_log(const char *msg);
193
194/* For backwards compatibility in builds */
195#define MMAL_VC_API_HAVE_HOST_LOG
196
197/* VC DEBUG ONLY ************************************************************/
198/** Consumes memory in the relocatable heap.
199 *
200 * The existing reserved memory is freed first then the new chunk is allocated.
201 * If zero is specified for the size then the previously reserved memory
202 * is freed and no allocation occurs.
203 *
204 * At startup no memory is reserved.
205 *
206 * @param size Size of memory to consume in bytes.
207 * @param handle Set to the mem handle for the reserved memory or zero
208 * if no memory was allocated.
209 * @return MMAL_SUCCESS if memory was reserved (or size zero requested),
210 * MMAL_ENOSPC if the allocation failed or MMAL_ENOSYS if the
211 * API is not supported e.g in release mode VC images.
212 * @internal
213 */
214MMAL_STATUS_T mmal_vc_consume_mem(size_t size, uint32_t *handle);
215
216typedef enum
217{
218 MMAL_VC_COMPACT_NONE = 0,
219 MMAL_VC_COMPACT_NORMAL = 1,
220 MMAL_VC_COMPACT_DISCARD = 2,
221 MMAL_VC_COMPACT_AGGRESSIVE = 4,
222 MMAL_VC_COMPACT_SHUFFLE = 0x80,
223 MMAL_VC_COMPACT_ALL = MMAL_VC_COMPACT_NORMAL | MMAL_VC_COMPACT_DISCARD | MMAL_VC_COMPACT_AGGRESSIVE,
224} MMAL_VC_COMPACT_MODE_T;
225
226/** Trigger relocatable heap compaction.
227 * @internal
228 */
229MMAL_STATUS_T mmal_vc_compact(MMAL_VC_COMPACT_MODE_T mode, uint32_t *duration);
230
231/** Trigger LMK action from VC, for diagnostics.
232 * @internal
233 */
234MMAL_STATUS_T mmal_vc_lmk(uint32_t alloc_size);
235
236#ifdef __cplusplus
237}
238#endif
239#endif
240