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
29#ifndef MMAL_CLOCK_H
30#define MMAL_CLOCK_H
31
32#include "interface/vcos/vcos.h"
33#include "mmal_types.h"
34#include "mmal_common.h"
35
36/** \defgroup MmalClock Clock Framework
37 * The MMAL clock framework provides scheduling facilities to the rest of
38 * MMAL.
39 *
40 * The framework consists mainly of clock ports and a clock module. Client
41 * applications and components interact directly with clock ports, while
42 * the clock module is only used internally by clock ports.
43 *
44 * Clock ports ensure that the local media-time for each component is
45 * synchronised across all components. This is done by passing buffers between
46 * clock ports which contain clock-specific data.
47 *
48 * One clock port will normally act as the reference clock for the rest of the
49 * system. This is usually chosen to be the clock port of the audio render
50 * component, but is configurable by the client and could potentially be any
51 * other clock port (or even the client application itself).
52 *
53 * Components that are responsible for timed delivery of frames, do so by
54 * registering callback requests for a particular time-stamp with the clock
55 * port. These requests are scheduled using the clock module which maintains
56 * an internal media-time.
57 *
58 * The clock framework also provides the ability to perform playback at different
59 * speeds. This is achieved with a clock scale factor which determines the speed
60 * at which the media-time advances relative to real-time, with:
61 * scale = 1.0 -> normal playback speed
62 * scale = 0 -> playback paused
63 * scale > 1.0 -> fast-forward
64 * scale < 1.0 -> slow motion
65 */
66
67/** Clock event magic */
68#define MMAL_CLOCK_EVENT_MAGIC MMAL_FOURCC('C','K','L','M')
69
70/** Clock reference update */
71#define MMAL_CLOCK_EVENT_REFERENCE MMAL_FOURCC('C','R','E','F')
72
73/** Clock state update */
74#define MMAL_CLOCK_EVENT_ACTIVE MMAL_FOURCC('C','A','C','T')
75
76/** Clock scale update */
77#define MMAL_CLOCK_EVENT_SCALE MMAL_FOURCC('C','S','C','A')
78
79/** Clock media-time update */
80#define MMAL_CLOCK_EVENT_TIME MMAL_FOURCC('C','T','I','M')
81
82/** Clock update threshold */
83#define MMAL_CLOCK_EVENT_UPDATE_THRESHOLD MMAL_FOURCC('C','U','T','H')
84
85/** Clock discontinuity threshold */
86#define MMAL_CLOCK_EVENT_DISCONT_THRESHOLD MMAL_FOURCC('C','D','T','H')
87
88/** Clock request threshold */
89#define MMAL_CLOCK_EVENT_REQUEST_THRESHOLD MMAL_FOURCC('C','R','T','H')
90
91/** Buffer statistics */
92#define MMAL_CLOCK_EVENT_INPUT_BUFFER_INFO MMAL_FOURCC('C','I','B','I')
93#define MMAL_CLOCK_EVENT_OUTPUT_BUFFER_INFO MMAL_FOURCC('C','O','B','I')
94
95/** Clock latency setting */
96#define MMAL_CLOCK_EVENT_LATENCY MMAL_FOURCC('C','L','A','T')
97
98/** Clock event not valid */
99#define MMAL_CLOCK_EVENT_INVALID 0
100
101
102/** Thresholds used when updating a clock's media-time */
103typedef struct MMAL_CLOCK_UPDATE_THRESHOLD_T
104{
105 /** Time differences below this threshold are ignored (microseconds) */
106 int64_t threshold_lower;
107
108 /** Time differences above this threshold reset media-time (microseconds) */
109 int64_t threshold_upper;
110} MMAL_CLOCK_UPDATE_THRESHOLD_T;
111
112/** Threshold for detecting a discontinuity in media-time */
113typedef struct MMAL_CLOCK_DISCONT_THRESHOLD_T
114{
115 /** Threshold after which backward jumps in media-time are treated as a
116 * discontinuity (microseconds) */
117 int64_t threshold;
118
119 /** Duration in microseconds for which a discontinuity applies (wall-time) */
120 int64_t duration;
121} MMAL_CLOCK_DISCONT_THRESHOLD_T;
122
123/** Threshold applied to client callback requests */
124typedef struct MMAL_CLOCK_REQUEST_THRESHOLD_T
125{
126 /** Frames with a media-time difference (compared to current media-time)
127 * above this threshold are dropped (microseconds) */
128 int64_t threshold;
129
130 /** Enable/disable the request threshold */
131 MMAL_BOOL_T threshold_enable;
132} MMAL_CLOCK_REQUEST_THRESHOLD_T;
133
134/** Structure for passing buffer information to a clock port */
135typedef struct MMAL_CLOCK_BUFFER_INFO_T
136{
137 int64_t time_stamp;
138 uint32_t arrival_time;
139} MMAL_CLOCK_BUFFER_INFO_T;
140
141/** Clock latency settings used by the clock component */
142typedef struct MMAL_CLOCK_LATENCY_T
143{
144 int64_t target; /**< target latency (microseconds) */
145 int64_t attack_period; /**< duration of one attack period (microseconds) */
146 int64_t attack_rate; /**< amount by which media-time will be adjusted
147 every attack_period (microseconds) */
148} MMAL_CLOCK_LATENCY_T;
149
150/** Clock event used to pass data between clock ports and a client. */
151typedef struct MMAL_CLOCK_EVENT_T
152{
153 /** 4cc event id */
154 uint32_t id;
155
156 /** 4cc event magic */
157 uint32_t magic;
158
159 /** buffer associated with this event (can be NULL) */
160 struct MMAL_BUFFER_HEADER_T *buffer;
161
162 /** pad to 64-bit boundary */
163 uint32_t padding0;
164
165 /** additional event data (type-specific) */
166 union
167 {
168 /** used either for clock reference or clock state */
169 MMAL_BOOL_T enable;
170
171 /** new clock scale */
172 MMAL_RATIONAL_T scale;
173
174 /** new media-time */
175 int64_t media_time;
176
177 /** media-time update threshold */
178 MMAL_CLOCK_UPDATE_THRESHOLD_T update_threshold;
179
180 /** media-time discontinuity threshold */
181 MMAL_CLOCK_DISCONT_THRESHOLD_T discont_threshold;
182
183 /** client callback request threshold */
184 MMAL_CLOCK_REQUEST_THRESHOLD_T request_threshold;
185
186 /** input/output buffer information */
187 MMAL_CLOCK_BUFFER_INFO_T buffer;
188
189 /** clock latency setting */
190 MMAL_CLOCK_LATENCY_T latency;
191 } data;
192
193 /** pad to 64-bit boundary */
194 uint64_t padding1;
195} MMAL_CLOCK_EVENT_T;
196
197/* Make sure MMAL_CLOCK_EVENT_T will preserve 64-bit alignment */
198vcos_static_assert(!(sizeof(MMAL_CLOCK_EVENT_T) & 0x7));
199
200#define MMAL_CLOCK_EVENT_INIT(id) { id, MMAL_CLOCK_EVENT_MAGIC, NULL, 0, {0}, 0 }
201
202#endif /* MMAL_CLOCK_H */
203