1 /* Copyright (c) 2008-2011 Freescale Semiconductor, Inc.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 * * Redistributions of source code must retain the above copyright
7 * notice, this list of conditions and the following disclaimer.
8 * * Redistributions in binary form must reproduce the above copyright
9 * notice, this list of conditions and the following disclaimer in the
10 * documentation and/or other materials provided with the distribution.
11 * * Neither the name of Freescale Semiconductor nor the
12 * names of its contributors may be used to endorse or promote products
13 * derived from this software without specific prior written permission.
16 * ALTERNATIVELY, this software may be distributed under the terms of the
17 * GNU General Public License ("GPL") as published by the Free Software
18 * Foundation, either version 2 of that License or (at your option) any
21 * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
22 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24 * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
25 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 /**************************************************************************//**
36 @Description External definitions and API for FM RTC IEEE1588 Timer Module.
39 *//***************************************************************************/
41 #ifndef __FM_RTC_EXT_H__
42 #define __FM_RTC_EXT_H__
45 #include "error_ext.h"
49 /**************************************************************************//**
51 @Group FM_grp Frame Manager API
53 @Description FM API functions, definitions and enums
56 *//***************************************************************************/
58 /**************************************************************************//**
59 @Group fm_rtc_grp FM RTC
61 @Description FM RTC functions, definitions and enums.
64 *//***************************************************************************/
66 /**************************************************************************//**
67 @Group fm_rtc_init_grp FM RTC Initialization Unit
69 @Description FM RTC initialization API.
72 *//***************************************************************************/
74 /**************************************************************************//**
75 @Description FM RTC Alarm Polarity Options.
76 *//***************************************************************************/
77 typedef enum e_FmRtcAlarmPolarity
79 e_FM_RTC_ALARM_POLARITY_ACTIVE_HIGH, /**< Active-high output polarity */
80 e_FM_RTC_ALARM_POLARITY_ACTIVE_LOW /**< Active-low output polarity */
81 } e_FmRtcAlarmPolarity;
83 /**************************************************************************//**
84 @Description FM RTC Trigger Polarity Options.
85 *//***************************************************************************/
86 typedef enum e_FmRtcTriggerPolarity
88 e_FM_RTC_TRIGGER_ON_RISING_EDGE, /**< Trigger on rising edge */
89 e_FM_RTC_TRIGGER_ON_FALLING_EDGE /**< Trigger on falling edge */
90 } e_FmRtcTriggerPolarity;
92 /**************************************************************************//**
93 @Description IEEE1588 Timer Module FM RTC Optional Clock Sources.
94 *//***************************************************************************/
95 typedef enum e_FmSrcClock
97 e_FM_RTC_SOURCE_CLOCK_EXTERNAL, /**< external high precision timer reference clock */
98 e_FM_RTC_SOURCE_CLOCK_SYSTEM, /**< MAC system clock */
99 e_FM_RTC_SOURCE_CLOCK_OSCILATOR /**< RTC clock oscilator */
102 /**************************************************************************//**
103 @Description FM RTC configuration parameters structure.
105 This structure should be passed to FM_RTC_Config().
106 *//***************************************************************************/
107 typedef struct t_FmRtcParams
109 t_Handle h_Fm; /**< FM Handle*/
110 uintptr_t baseAddress; /**< Base address of FM RTC registers */
111 t_Handle h_App; /**< A handle to an application layer object; This handle will
112 be passed by the driver upon calling the above callbacks */
116 /**************************************************************************//**
117 @Function FM_RTC_Config
119 @Description Configures the FM RTC module according to user's parameters.
121 The driver assigns default values to some FM RTC parameters.
122 These parameters can be overwritten using the advanced
123 configuration routines.
125 @Param[in] p_FmRtcParam - FM RTC configuration parameters.
127 @Return Handle to the new FM RTC object; NULL pointer on failure.
130 *//***************************************************************************/
131 t_Handle FM_RTC_Config(t_FmRtcParams *p_FmRtcParam);
133 /**************************************************************************//**
134 @Function FM_RTC_Init
136 @Description Initializes the FM RTC driver and hardware.
138 @Param[in] h_FmRtc - Handle to FM RTC object.
140 @Return E_OK on success; Error code otherwise.
142 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
143 *//***************************************************************************/
144 t_Error FM_RTC_Init(t_Handle h_FmRtc);
146 /**************************************************************************//**
147 @Function FM_RTC_Free
149 @Description Frees the FM RTC object and all allocated resources.
151 @Param[in] h_FmRtc - Handle to FM RTC object.
153 @Return E_OK on success; Error code otherwise.
155 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
156 *//***************************************************************************/
157 t_Error FM_RTC_Free(t_Handle h_FmRtc);
160 /**************************************************************************//**
161 @Group fm_rtc_adv_config_grp FM RTC Advanced Configuration Unit
163 @Description FM RTC advanced configuration functions.
166 *//***************************************************************************/
168 /**************************************************************************//**
169 @Function FM_RTC_ConfigPeriod
171 @Description Configures the period of the timestamp if different than
174 @Param[in] h_FmRtc - Handle to FM RTC object.
175 @Param[in] period - Period in nano-seconds.
177 @Return E_OK on success; Error code otherwise.
179 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
180 *//***************************************************************************/
181 t_Error FM_RTC_ConfigPeriod(t_Handle h_FmRtc, uint32_t period);
183 /**************************************************************************//**
184 @Function FM_RTC_ConfigSourceClock
186 @Description Configures the source clock of the RTC.
188 @Param[in] h_FmRtc - Handle to FM RTC object.
189 @Param[in] srcClk - Source clock selection.
190 @Param[in] freqInMhz - the source-clock frequency (in MHz).
192 @Return E_OK on success; Error code otherwise.
194 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
195 *//***************************************************************************/
196 t_Error FM_RTC_ConfigSourceClock(t_Handle h_FmRtc,
200 /**************************************************************************//**
201 @Function FM_RTC_ConfigPulseRealignment
203 @Description Configures the RTC to automatic FIPER pulse realignment in
204 response to timer adjustments [FALSE]
206 In this mode, the RTC clock is identical to the source clock.
207 This feature can be useful when the system contains an external
208 RTC with inherent frequency compensation.
210 @Param[in] h_FmRtc - Handle to FM RTC object.
211 @Param[in] enable - TRUE to enable automatic realignment.
213 @Return E_OK on success; Error code otherwise.
215 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
216 *//***************************************************************************/
217 t_Error FM_RTC_ConfigPulseRealignment(t_Handle h_FmRtc, bool enable);
219 /**************************************************************************//**
220 @Function FM_RTC_ConfigFrequencyBypass
222 @Description Configures the RTC to bypass the frequency compensation
225 In this mode, the RTC clock is identical to the source clock.
226 This feature can be useful when the system contains an external
227 RTC with inherent frequency compensation.
229 @Param[in] h_FmRtc - Handle to FM RTC object.
230 @Param[in] enabled - TRUE to bypass frequency compensation;
233 @Return E_OK on success; Error code otherwise.
235 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
236 *//***************************************************************************/
237 t_Error FM_RTC_ConfigFrequencyBypass(t_Handle h_FmRtc, bool enabled);
239 /**************************************************************************//**
240 @Function FM_RTC_ConfigInvertedInputClockPhase
242 @Description Configures the RTC to invert the source clock phase on input.
245 @Param[in] h_FmRtc - Handle to FM RTC object.
246 @Param[in] inverted - TRUE to invert the source clock phase on input.
249 @Return E_OK on success; Error code otherwise.
251 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
252 *//***************************************************************************/
253 t_Error FM_RTC_ConfigInvertedInputClockPhase(t_Handle h_FmRtc, bool inverted);
255 /**************************************************************************//**
256 @Function FM_RTC_ConfigInvertedOutputClockPhase
258 @Description Configures the RTC to invert the output clock phase.
261 @Param[in] h_FmRtc - Handle to FM RTC object.
262 @Param[in] inverted - TRUE to invert the output clock phase.
265 @Return E_OK on success; Error code otherwise.
267 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
268 *//***************************************************************************/
269 t_Error FM_RTC_ConfigInvertedOutputClockPhase(t_Handle h_FmRtc, bool inverted);
271 /**************************************************************************//**
272 @Function FM_RTC_ConfigOutputClockDivisor
274 @Description Configures the divisor for generating the output clock from
275 the RTC clock. [0x00000002]
277 @Param[in] h_FmRtc - Handle to FM RTC object.
278 @Param[in] divisor - Divisor for generation of the output clock.
280 @Return E_OK on success; Error code otherwise.
282 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
283 *//***************************************************************************/
284 t_Error FM_RTC_ConfigOutputClockDivisor(t_Handle h_FmRtc, uint16_t divisor);
286 /**************************************************************************//**
287 @Function FM_RTC_ConfigAlarmPolarity
289 @Description Configures the polarity (active-high/active-low) of a specific
290 alarm signal. [e_FM_RTC_ALARM_POLARITY_ACTIVE_HIGH]
292 @Param[in] h_FmRtc - Handle to FM RTC object.
293 @Param[in] alarmId - Alarm ID.
294 @Param[in] alarmPolarity - Alarm polarity.
296 @Return E_OK on success; Error code otherwise.
298 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
299 *//***************************************************************************/
300 t_Error FM_RTC_ConfigAlarmPolarity(t_Handle h_FmRtc,
302 e_FmRtcAlarmPolarity alarmPolarity);
304 /**************************************************************************//**
305 @Function FM_RTC_ConfigExternalTriggerPolarity
307 @Description Configures the polarity (rising/falling edge) of a specific
308 external trigger signal. [e_FM_RTC_TRIGGER_ON_FALLING_EDGE]
310 @Param[in] h_FmRtc - Handle to FM RTC object.
311 @Param[in] triggerId - Trigger ID.
312 @Param[in] triggerPolarity - Trigger polarity.
314 @Return E_OK on success; Error code otherwise.
316 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
317 *//***************************************************************************/
318 t_Error FM_RTC_ConfigExternalTriggerPolarity(t_Handle h_FmRtc,
320 e_FmRtcTriggerPolarity triggerPolarity);
322 /** @} */ /* end of fm_rtc_adv_config_grp */
323 /** @} */ /* end of fm_rtc_init_grp */
326 /**************************************************************************//**
327 @Group fm_rtc_control_grp FM RTC Control Unit
329 @Description FM RTC runtime control API.
332 *//***************************************************************************/
334 /**************************************************************************//**
335 @Function t_FmRtcExceptionsCallback
337 @Description Exceptions user callback routine, used for RTC different mechanisms.
339 @Param[in] h_App - User's application descriptor.
340 @Param[in] id - source id.
341 *//***************************************************************************/
342 typedef void (t_FmRtcExceptionsCallback) ( t_Handle h_App, uint8_t id);
344 /**************************************************************************//**
345 @Description FM RTC alarm parameters.
346 *//***************************************************************************/
347 typedef struct t_FmRtcAlarmParams {
348 uint8_t alarmId; /**< 0 or 1 */
349 uint64_t alarmTime; /**< In nanoseconds, the time when the alarm
350 should go off - must be a multiple of
352 t_FmRtcExceptionsCallback *f_AlarmCallback; /**< This routine will be called when RTC
354 bool clearOnExpiration; /**< TRUE to turn off the alarm once expired. */
355 } t_FmRtcAlarmParams;
357 /**************************************************************************//**
358 @Description FM RTC Periodic Pulse parameters.
359 *//***************************************************************************/
360 typedef struct t_FmRtcPeriodicPulseParams {
361 uint8_t periodicPulseId; /**< 0 or 1 */
362 uint64_t periodicPulsePeriod; /**< In Nanoseconds. Must be
363 a multiple of the RTC period */
364 t_FmRtcExceptionsCallback *f_PeriodicPulseCallback; /**< This routine will be called every
365 periodicPulsePeriod. */
366 } t_FmRtcPeriodicPulseParams;
368 /**************************************************************************//**
369 @Description FM RTC Periodic Pulse parameters.
370 *//***************************************************************************/
371 typedef struct t_FmRtcExternalTriggerParams {
372 uint8_t externalTriggerId; /**< 0 or 1 */
373 bool usePulseAsInput; /**< Use the pulse interrupt instead of
374 an external signal */
375 t_FmRtcExceptionsCallback *f_ExternalTriggerCallback; /**< This routine will be called every
376 periodicPulsePeriod. */
377 } t_FmRtcExternalTriggerParams;
380 /**************************************************************************//**
381 @Function FM_RTC_Enable
383 @Description Enable the RTC (time count is started).
385 The user can select to resume the time count from previous
386 point, or to restart the time count.
388 @Param[in] h_FmRtc - Handle to FM RTC object.
389 @Param[in] resetClock - Restart the time count from zero.
391 @Return E_OK on success; Error code otherwise.
393 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
394 *//***************************************************************************/
395 t_Error FM_RTC_Enable(t_Handle h_FmRtc, bool resetClock);
397 /**************************************************************************//**
398 @Function FM_RTC_Disable
400 @Description Disables the RTC (time count is stopped).
402 @Param[in] h_FmRtc - Handle to FM RTC object.
404 @Return E_OK on success; Error code otherwise.
406 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
407 *//***************************************************************************/
408 t_Error FM_RTC_Disable(t_Handle h_FmRtc);
410 /**************************************************************************//**
411 @Function FM_RTC_SetClockOffset
413 @Description Sets the clock offset (usually relative to another clock).
415 The user can pass a negative offset value.
417 @Param[in] h_FmRtc - Handle to FM RTC object.
418 @Param[in] offset - New clock offset (in nanoseconds).
420 @Return E_OK on success; Error code otherwise.
422 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
423 *//***************************************************************************/
424 t_Error FM_RTC_SetClockOffset(t_Handle h_FmRtc, int64_t offset);
426 /**************************************************************************//**
427 @Function FM_RTC_SetAlarm
429 @Description Schedules an alarm event to a given RTC time.
431 @Param[in] h_FmRtc - Handle to FM RTC object.
432 @Param[in] p_FmRtcAlarmParams - Alarm parameters.
434 @Return E_OK on success; Error code otherwise.
436 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
437 Must be called only prior to FM_RTC_Enable().
438 *//***************************************************************************/
439 t_Error FM_RTC_SetAlarm(t_Handle h_FmRtc, t_FmRtcAlarmParams *p_FmRtcAlarmParams);
441 /**************************************************************************//**
442 @Function FM_RTC_SetPeriodicPulse
444 @Description Sets a periodic pulse.
446 @Param[in] h_FmRtc - Handle to FM RTC object.
447 @Param[in] p_FmRtcPeriodicPulseParams - Periodic pulse parameters.
449 @Return E_OK on success; Error code otherwise.
451 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
452 Must be called only prior to FM_RTC_Enable().
453 *//***************************************************************************/
454 t_Error FM_RTC_SetPeriodicPulse(t_Handle h_FmRtc, t_FmRtcPeriodicPulseParams *p_FmRtcPeriodicPulseParams);
456 /**************************************************************************//**
457 @Function FM_RTC_ClearPeriodicPulse
459 @Description Clears a periodic pulse.
461 @Param[in] h_FmRtc - Handle to FM RTC object.
462 @Param[in] periodicPulseId - Periodic pulse id.
464 @Return E_OK on success; Error code otherwise.
466 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
467 *//***************************************************************************/
468 t_Error FM_RTC_ClearPeriodicPulse(t_Handle h_FmRtc, uint8_t periodicPulseId);
470 /**************************************************************************//**
471 @Function FM_RTC_SetExternalTrigger
473 @Description Sets an external trigger indication and define a callback
474 routine to be called on such event.
476 @Param[in] h_FmRtc - Handle to FM RTC object.
477 @Param[in] p_FmRtcExternalTriggerParams - External Trigger parameters.
479 @Return E_OK on success; Error code otherwise.
481 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
482 *//***************************************************************************/
483 t_Error FM_RTC_SetExternalTrigger(t_Handle h_FmRtc, t_FmRtcExternalTriggerParams *p_FmRtcExternalTriggerParams);
485 /**************************************************************************//**
486 @Function FM_RTC_ClearExternalTrigger
488 @Description Clears external trigger indication.
490 @Param[in] h_FmRtc - Handle to FM RTC object.
491 @Param[in] id - External Trigger id.
493 @Return E_OK on success; Error code otherwise.
495 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
496 *//***************************************************************************/
497 t_Error FM_RTC_ClearExternalTrigger(t_Handle h_FmRtc, uint8_t id);
499 /**************************************************************************//**
500 @Function FM_RTC_GetExternalTriggerTimeStamp
502 @Description Reads the External Trigger TimeStamp.
504 @Param[in] h_FmRtc - Handle to FM RTC object.
505 @Param[in] triggerId - External Trigger id.
506 @Param[out] p_TimeStamp - External Trigger timestamp (in nanoseconds).
508 @Return E_OK on success; Error code otherwise.
510 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
511 *//***************************************************************************/
512 t_Error FM_RTC_GetExternalTriggerTimeStamp(t_Handle h_FmRtc,
514 uint64_t *p_TimeStamp);
516 /**************************************************************************//**
517 @Function FM_RTC_GetCurrentTime
519 @Description Returns the current RTC time.
521 @Param[in] h_FmRtc - Handle to FM RTC object.
522 @Param[out] p_Ts - returned time stamp (in nanoseconds).
524 @Return E_OK on success; Error code otherwise.
526 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
527 *//***************************************************************************/
528 t_Error FM_RTC_GetCurrentTime(t_Handle h_FmRtc, uint64_t *p_Ts);
530 /**************************************************************************//**
531 @Function FM_RTC_SetCurrentTime
533 @Description Sets the current RTC time.
535 @Param[in] h_FmRtc - Handle to FM RTC object.
536 @Param[in] ts - The new time stamp (in nanoseconds).
538 @Return E_OK on success; Error code otherwise.
540 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
541 *//***************************************************************************/
542 t_Error FM_RTC_SetCurrentTime(t_Handle h_FmRtc, uint64_t ts);
544 /**************************************************************************//**
545 @Function FM_RTC_GetFreqCompensation
549 @Param[in] h_FmRtc - Handle to FM RTC object.
550 @Param[out] p_Compensation - A pointer to the returned value of compensation.
552 @Return E_OK on success; Error code otherwise.
554 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
555 *//***************************************************************************/
556 t_Error FM_RTC_GetFreqCompensation(t_Handle h_FmRtc, uint32_t *p_Compensation);
558 /**************************************************************************//**
559 @Function FM_RTC_SetFreqCompensation
563 @Param[in] h_FmRtc - Handle to FM RTC object.
564 @Param[in] freqCompensation - the new desired compensation value to be set.
566 @Return E_OK on success; Error code otherwise.
568 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
569 *//***************************************************************************/
570 t_Error FM_RTC_SetFreqCompensation(t_Handle h_FmRtc, uint32_t freqCompensation);
572 #if (defined(DEBUG_ERRORS) && (DEBUG_ERRORS > 0))
573 /**************************************************************************//**
574 @Function FM_RTC_DumpRegs
576 @Description Dumps all FM registers
578 @Param[in] h_FmRtc A handle to an FM RTC Module.
580 @Return E_OK on success;
582 @Cautions Allowed only FM_Init().
583 *//***************************************************************************/
584 t_Error FM_RTC_DumpRegs(t_Handle h_FmRtc);
585 #endif /* (defined(DEBUG_ERRORS) && ... */
587 /** @} */ /* end of fm_rtc_control_grp */
588 /** @} */ /* end of fm_rtc_grp */
589 /** @} */ /* end of FM_grp group */
592 #endif /* __FM_RTC_EXT_H__ */