2 * Copyright 2008-2012 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.
34 /**************************************************************************//**
37 @Description External definitions and API for FM RTC IEEE1588 Timer Module.
40 *//***************************************************************************/
42 #ifndef __FM_RTC_EXT_H__
43 #define __FM_RTC_EXT_H__
46 #include "error_ext.h"
48 #include "fsl_fman_rtc.h"
50 /**************************************************************************//**
52 @Group FM_grp Frame Manager API
54 @Description FM API functions, definitions and enums
57 *//***************************************************************************/
59 /**************************************************************************//**
60 @Group fm_rtc_grp FM RTC
62 @Description FM RTC functions, definitions and enums.
65 *//***************************************************************************/
67 /**************************************************************************//**
68 @Group fm_rtc_init_grp FM RTC Initialization Unit
70 @Description FM RTC initialization API.
73 *//***************************************************************************/
75 /**************************************************************************//**
76 @Description FM RTC Alarm Polarity Options.
77 *//***************************************************************************/
78 typedef enum e_FmRtcAlarmPolarity
80 e_FM_RTC_ALARM_POLARITY_ACTIVE_HIGH = E_FMAN_RTC_ALARM_POLARITY_ACTIVE_HIGH, /**< Active-high output polarity */
81 e_FM_RTC_ALARM_POLARITY_ACTIVE_LOW = E_FMAN_RTC_ALARM_POLARITY_ACTIVE_LOW /**< Active-low output polarity */
82 } e_FmRtcAlarmPolarity;
84 /**************************************************************************//**
85 @Description FM RTC Trigger Polarity Options.
86 *//***************************************************************************/
87 typedef enum e_FmRtcTriggerPolarity
89 e_FM_RTC_TRIGGER_ON_RISING_EDGE = E_FMAN_RTC_TRIGGER_ON_RISING_EDGE, /**< Trigger on rising edge */
90 e_FM_RTC_TRIGGER_ON_FALLING_EDGE = E_FMAN_RTC_TRIGGER_ON_FALLING_EDGE /**< Trigger on falling edge */
91 } e_FmRtcTriggerPolarity;
93 /**************************************************************************//**
94 @Description IEEE1588 Timer Module FM RTC Optional Clock Sources.
95 *//***************************************************************************/
96 typedef enum e_FmSrcClock
98 e_FM_RTC_SOURCE_CLOCK_EXTERNAL = E_FMAN_RTC_SOURCE_CLOCK_EXTERNAL, /**< external high precision timer reference clock */
99 e_FM_RTC_SOURCE_CLOCK_SYSTEM = E_FMAN_RTC_SOURCE_CLOCK_SYSTEM, /**< MAC system clock */
100 e_FM_RTC_SOURCE_CLOCK_OSCILATOR = E_FMAN_RTC_SOURCE_CLOCK_OSCILATOR /**< RTC clock oscilator */
103 /**************************************************************************//**
104 @Description FM RTC configuration parameters structure.
106 This structure should be passed to FM_RTC_Config().
107 *//***************************************************************************/
108 typedef struct t_FmRtcParams
110 t_Handle h_Fm; /**< FM Handle*/
111 uintptr_t baseAddress; /**< Base address of FM RTC registers */
112 t_Handle h_App; /**< A handle to an application layer object; This handle will
113 be passed by the driver upon calling the above callbacks */
117 /**************************************************************************//**
118 @Function FM_RTC_Config
120 @Description Configures the FM RTC module according to user's parameters.
122 The driver assigns default values to some FM RTC parameters.
123 These parameters can be overwritten using the advanced
124 configuration routines.
126 @Param[in] p_FmRtcParam - FM RTC configuration parameters.
128 @Return Handle to the new FM RTC object; NULL pointer on failure.
131 *//***************************************************************************/
132 t_Handle FM_RTC_Config(t_FmRtcParams *p_FmRtcParam);
134 /**************************************************************************//**
135 @Function FM_RTC_Init
137 @Description Initializes the FM RTC driver and hardware.
139 @Param[in] h_FmRtc - Handle to FM RTC object.
141 @Return E_OK on success; Error code otherwise.
143 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
144 *//***************************************************************************/
145 t_Error FM_RTC_Init(t_Handle h_FmRtc);
147 /**************************************************************************//**
148 @Function FM_RTC_Free
150 @Description Frees the FM RTC object and all allocated resources.
152 @Param[in] h_FmRtc - Handle to FM RTC object.
154 @Return E_OK on success; Error code otherwise.
156 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
157 *//***************************************************************************/
158 t_Error FM_RTC_Free(t_Handle h_FmRtc);
161 /**************************************************************************//**
162 @Group fm_rtc_adv_config_grp FM RTC Advanced Configuration Unit
164 @Description FM RTC advanced configuration functions.
167 *//***************************************************************************/
169 /**************************************************************************//**
170 @Function FM_RTC_ConfigPeriod
172 @Description Configures the period of the timestamp if different than
173 default [DEFAULT_clockPeriod].
175 @Param[in] h_FmRtc - Handle to FM RTC object.
176 @Param[in] period - Period in nano-seconds.
178 @Return E_OK on success; Error code otherwise.
180 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
181 *//***************************************************************************/
182 t_Error FM_RTC_ConfigPeriod(t_Handle h_FmRtc, uint32_t period);
184 /**************************************************************************//**
185 @Function FM_RTC_ConfigSourceClock
187 @Description Configures the source clock of the RTC.
189 @Param[in] h_FmRtc - Handle to FM RTC object.
190 @Param[in] srcClk - Source clock selection.
191 @Param[in] freqInMhz - the source-clock frequency (in MHz).
193 @Return E_OK on success; Error code otherwise.
195 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
196 *//***************************************************************************/
197 t_Error FM_RTC_ConfigSourceClock(t_Handle h_FmRtc,
201 /**************************************************************************//**
202 @Function FM_RTC_ConfigPulseRealignment
204 @Description Configures the RTC to automatic FIPER pulse realignment in
205 response to timer adjustments [DEFAULT_pulseRealign]
207 In this mode, the RTC clock is identical to the source clock.
208 This feature can be useful when the system contains an external
209 RTC with inherent frequency compensation.
211 @Param[in] h_FmRtc - Handle to FM RTC object.
212 @Param[in] enable - TRUE to enable automatic realignment.
214 @Return E_OK on success; Error code otherwise.
216 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
217 *//***************************************************************************/
218 t_Error FM_RTC_ConfigPulseRealignment(t_Handle h_FmRtc, bool enable);
220 /**************************************************************************//**
221 @Function FM_RTC_ConfigFrequencyBypass
223 @Description Configures the RTC to bypass the frequency compensation
224 mechanism. [DEFAULT_bypass]
226 In this mode, the RTC clock is identical to the source clock.
227 This feature can be useful when the system contains an external
228 RTC with inherent frequency compensation.
230 @Param[in] h_FmRtc - Handle to FM RTC object.
231 @Param[in] enabled - TRUE to bypass frequency compensation;
234 @Return E_OK on success; Error code otherwise.
236 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
237 *//***************************************************************************/
238 t_Error FM_RTC_ConfigFrequencyBypass(t_Handle h_FmRtc, bool enabled);
240 /**************************************************************************//**
241 @Function FM_RTC_ConfigInvertedInputClockPhase
243 @Description Configures the RTC to invert the source clock phase on input.
244 [DEFAULT_invertInputClkPhase]
246 @Param[in] h_FmRtc - Handle to FM RTC object.
247 @Param[in] inverted - TRUE to invert the source clock phase on input.
250 @Return E_OK on success; Error code otherwise.
252 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
253 *//***************************************************************************/
254 t_Error FM_RTC_ConfigInvertedInputClockPhase(t_Handle h_FmRtc, bool inverted);
256 /**************************************************************************//**
257 @Function FM_RTC_ConfigInvertedOutputClockPhase
259 @Description Configures the RTC to invert the output clock phase.
260 [DEFAULT_invertOutputClkPhase]
262 @Param[in] h_FmRtc - Handle to FM RTC object.
263 @Param[in] inverted - TRUE to invert the output clock phase.
266 @Return E_OK on success; Error code otherwise.
268 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
269 *//***************************************************************************/
270 t_Error FM_RTC_ConfigInvertedOutputClockPhase(t_Handle h_FmRtc, bool inverted);
272 /**************************************************************************//**
273 @Function FM_RTC_ConfigOutputClockDivisor
275 @Description Configures the divisor for generating the output clock from
276 the RTC clock. [DEFAULT_outputClockDivisor]
278 @Param[in] h_FmRtc - Handle to FM RTC object.
279 @Param[in] divisor - Divisor for generation of the output clock.
281 @Return E_OK on success; Error code otherwise.
283 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
284 *//***************************************************************************/
285 t_Error FM_RTC_ConfigOutputClockDivisor(t_Handle h_FmRtc, uint16_t divisor);
287 /**************************************************************************//**
288 @Function FM_RTC_ConfigAlarmPolarity
290 @Description Configures the polarity (active-high/active-low) of a specific
291 alarm signal. [DEFAULT_alarmPolarity]
293 @Param[in] h_FmRtc - Handle to FM RTC object.
294 @Param[in] alarmId - Alarm ID.
295 @Param[in] alarmPolarity - Alarm polarity.
297 @Return E_OK on success; Error code otherwise.
299 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
300 *//***************************************************************************/
301 t_Error FM_RTC_ConfigAlarmPolarity(t_Handle h_FmRtc,
303 e_FmRtcAlarmPolarity alarmPolarity);
305 /**************************************************************************//**
306 @Function FM_RTC_ConfigExternalTriggerPolarity
308 @Description Configures the polarity (rising/falling edge) of a specific
309 external trigger signal. [DEFAULT_triggerPolarity]
311 @Param[in] h_FmRtc - Handle to FM RTC object.
312 @Param[in] triggerId - Trigger ID.
313 @Param[in] triggerPolarity - Trigger polarity.
315 @Return E_OK on success; Error code otherwise.
317 @Cautions h_FmRtc must have been previously created using FM_RTC_Config().
318 *//***************************************************************************/
319 t_Error FM_RTC_ConfigExternalTriggerPolarity(t_Handle h_FmRtc,
321 e_FmRtcTriggerPolarity triggerPolarity);
323 /** @} */ /* end of fm_rtc_adv_config_grp */
324 /** @} */ /* end of fm_rtc_init_grp */
327 /**************************************************************************//**
328 @Group fm_rtc_control_grp FM RTC Control Unit
330 @Description FM RTC runtime control API.
333 *//***************************************************************************/
335 /**************************************************************************//**
336 @Function t_FmRtcExceptionsCallback
338 @Description Exceptions user callback routine, used for RTC different mechanisms.
340 @Param[in] h_App - User's application descriptor.
341 @Param[in] id - source id.
342 *//***************************************************************************/
343 typedef void (t_FmRtcExceptionsCallback) ( t_Handle h_App, uint8_t id);
345 /**************************************************************************//**
346 @Description FM RTC alarm parameters.
347 *//***************************************************************************/
348 typedef struct t_FmRtcAlarmParams {
349 uint8_t alarmId; /**< 0 or 1 */
350 uint64_t alarmTime; /**< In nanoseconds, the time when the alarm
351 should go off - must be a multiple of
353 t_FmRtcExceptionsCallback *f_AlarmCallback; /**< This routine will be called when RTC
355 bool clearOnExpiration; /**< TRUE to turn off the alarm once expired. */
356 } t_FmRtcAlarmParams;
358 /**************************************************************************//**
359 @Description FM RTC Periodic Pulse parameters.
360 *//***************************************************************************/
361 typedef struct t_FmRtcPeriodicPulseParams {
362 uint8_t periodicPulseId; /**< 0 or 1 */
363 uint64_t periodicPulsePeriod; /**< In Nanoseconds. Must be
364 a multiple of the RTC period */
365 t_FmRtcExceptionsCallback *f_PeriodicPulseCallback; /**< This routine will be called every
366 periodicPulsePeriod. */
367 } t_FmRtcPeriodicPulseParams;
369 /**************************************************************************//**
370 @Description FM RTC Periodic Pulse parameters.
371 *//***************************************************************************/
372 typedef struct t_FmRtcExternalTriggerParams {
373 uint8_t externalTriggerId; /**< 0 or 1 */
374 bool usePulseAsInput; /**< Use the pulse interrupt instead of
375 an external signal */
376 t_FmRtcExceptionsCallback *f_ExternalTriggerCallback; /**< This routine will be called every
377 periodicPulsePeriod. */
378 } t_FmRtcExternalTriggerParams;
381 /**************************************************************************//**
382 @Function FM_RTC_Enable
384 @Description Enable the RTC (time count is started).
386 The user can select to resume the time count from previous
387 point, or to restart the time count.
389 @Param[in] h_FmRtc - Handle to FM RTC object.
390 @Param[in] resetClock - Restart the time count from zero.
392 @Return E_OK on success; Error code otherwise.
394 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
395 *//***************************************************************************/
396 t_Error FM_RTC_Enable(t_Handle h_FmRtc, bool resetClock);
398 /**************************************************************************//**
399 @Function FM_RTC_Disable
401 @Description Disables the RTC (time count is stopped).
403 @Param[in] h_FmRtc - Handle to FM RTC object.
405 @Return E_OK on success; Error code otherwise.
407 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
408 *//***************************************************************************/
409 t_Error FM_RTC_Disable(t_Handle h_FmRtc);
411 /**************************************************************************//**
412 @Function FM_RTC_SetClockOffset
414 @Description Sets the clock offset (usually relative to another clock).
416 The user can pass a negative offset value.
418 @Param[in] h_FmRtc - Handle to FM RTC object.
419 @Param[in] offset - New clock offset (in nanoseconds).
421 @Return E_OK on success; Error code otherwise.
423 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
424 *//***************************************************************************/
425 t_Error FM_RTC_SetClockOffset(t_Handle h_FmRtc, int64_t offset);
427 /**************************************************************************//**
428 @Function FM_RTC_SetAlarm
430 @Description Schedules an alarm event to a given RTC time.
432 @Param[in] h_FmRtc - Handle to FM RTC object.
433 @Param[in] p_FmRtcAlarmParams - Alarm parameters.
435 @Return E_OK on success; Error code otherwise.
437 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
438 Must be called only prior to FM_RTC_Enable().
439 *//***************************************************************************/
440 t_Error FM_RTC_SetAlarm(t_Handle h_FmRtc, t_FmRtcAlarmParams *p_FmRtcAlarmParams);
442 /**************************************************************************//**
443 @Function FM_RTC_SetPeriodicPulse
445 @Description Sets a periodic pulse.
447 @Param[in] h_FmRtc - Handle to FM RTC object.
448 @Param[in] p_FmRtcPeriodicPulseParams - Periodic pulse parameters.
450 @Return E_OK on success; Error code otherwise.
452 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
453 Must be called only prior to FM_RTC_Enable().
454 *//***************************************************************************/
455 t_Error FM_RTC_SetPeriodicPulse(t_Handle h_FmRtc, t_FmRtcPeriodicPulseParams *p_FmRtcPeriodicPulseParams);
457 /**************************************************************************//**
458 @Function FM_RTC_ClearPeriodicPulse
460 @Description Clears a periodic pulse.
462 @Param[in] h_FmRtc - Handle to FM RTC object.
463 @Param[in] periodicPulseId - Periodic pulse id.
465 @Return E_OK on success; Error code otherwise.
467 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
468 *//***************************************************************************/
469 t_Error FM_RTC_ClearPeriodicPulse(t_Handle h_FmRtc, uint8_t periodicPulseId);
471 /**************************************************************************//**
472 @Function FM_RTC_SetExternalTrigger
474 @Description Sets an external trigger indication and define a callback
475 routine to be called on such event.
477 @Param[in] h_FmRtc - Handle to FM RTC object.
478 @Param[in] p_FmRtcExternalTriggerParams - External Trigger parameters.
480 @Return E_OK on success; Error code otherwise.
482 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
483 *//***************************************************************************/
484 t_Error FM_RTC_SetExternalTrigger(t_Handle h_FmRtc, t_FmRtcExternalTriggerParams *p_FmRtcExternalTriggerParams);
486 /**************************************************************************//**
487 @Function FM_RTC_ClearExternalTrigger
489 @Description Clears external trigger indication.
491 @Param[in] h_FmRtc - Handle to FM RTC object.
492 @Param[in] id - External Trigger id.
494 @Return E_OK on success; Error code otherwise.
496 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
497 *//***************************************************************************/
498 t_Error FM_RTC_ClearExternalTrigger(t_Handle h_FmRtc, uint8_t id);
500 /**************************************************************************//**
501 @Function FM_RTC_GetExternalTriggerTimeStamp
503 @Description Reads the External Trigger TimeStamp.
505 @Param[in] h_FmRtc - Handle to FM RTC object.
506 @Param[in] triggerId - External Trigger id.
507 @Param[out] p_TimeStamp - External Trigger timestamp (in nanoseconds).
509 @Return E_OK on success; Error code otherwise.
511 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
512 *//***************************************************************************/
513 t_Error FM_RTC_GetExternalTriggerTimeStamp(t_Handle h_FmRtc,
515 uint64_t *p_TimeStamp);
517 /**************************************************************************//**
518 @Function FM_RTC_GetCurrentTime
520 @Description Returns the current RTC time.
522 @Param[in] h_FmRtc - Handle to FM RTC object.
523 @Param[out] p_Ts - returned time stamp (in nanoseconds).
525 @Return E_OK on success; Error code otherwise.
527 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
528 *//***************************************************************************/
529 t_Error FM_RTC_GetCurrentTime(t_Handle h_FmRtc, uint64_t *p_Ts);
531 /**************************************************************************//**
532 @Function FM_RTC_SetCurrentTime
534 @Description Sets the current RTC time.
536 @Param[in] h_FmRtc - Handle to FM RTC object.
537 @Param[in] ts - The new time stamp (in nanoseconds).
539 @Return E_OK on success; Error code otherwise.
541 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
542 *//***************************************************************************/
543 t_Error FM_RTC_SetCurrentTime(t_Handle h_FmRtc, uint64_t ts);
545 /**************************************************************************//**
546 @Function FM_RTC_GetFreqCompensation
548 @Description Retrieves the frequency compensation value
550 @Param[in] h_FmRtc - Handle to FM RTC object.
551 @Param[out] p_Compensation - A pointer to the returned value of compensation.
553 @Return E_OK on success; Error code otherwise.
555 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
556 *//***************************************************************************/
557 t_Error FM_RTC_GetFreqCompensation(t_Handle h_FmRtc, uint32_t *p_Compensation);
559 /**************************************************************************//**
560 @Function FM_RTC_SetFreqCompensation
562 @Description Sets a new frequency compensation value.
564 @Param[in] h_FmRtc - Handle to FM RTC object.
565 @Param[in] freqCompensation - The new frequency compensation value to set.
567 @Return E_OK on success; Error code otherwise.
569 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init().
570 *//***************************************************************************/
571 t_Error FM_RTC_SetFreqCompensation(t_Handle h_FmRtc, uint32_t freqCompensation);
573 #ifdef CONFIG_PTP_1588_CLOCK_DPAA
574 /**************************************************************************//**
575 *@Function FM_RTC_EnableInterrupt
577 *@Description Enable interrupt of FM RTC.
579 *@Param[in] h_FmRtc - Handle to FM RTC object.
580 *@Param[in] events - Interrupt events.
582 *@Return E_OK on success; Error code otherwise.
583 *//***************************************************************************/
584 t_Error FM_RTC_EnableInterrupt(t_Handle h_FmRtc, uint32_t events);
586 /**************************************************************************//**
587 *@Function FM_RTC_DisableInterrupt
589 *@Description Disable interrupt of FM RTC.
591 *@Param[in] h_FmRtc - Handle to FM RTC object.
592 *@Param[in] events - Interrupt events.
594 *@Return E_OK on success; Error code otherwise.
595 *//***************************************************************************/
596 t_Error FM_RTC_DisableInterrupt(t_Handle h_FmRtc, uint32_t events);
599 #if (defined(DEBUG_ERRORS) && (DEBUG_ERRORS > 0))
600 /**************************************************************************//**
601 @Function FM_RTC_DumpRegs
603 @Description Dumps all FM registers
605 @Param[in] h_FmRtc A handle to an FM RTC Module.
607 @Return E_OK on success;
609 @Cautions Allowed only FM_Init().
610 *//***************************************************************************/
611 t_Error FM_RTC_DumpRegs(t_Handle h_FmRtc);
612 #endif /* (defined(DEBUG_ERRORS) && ... */
614 /** @} */ /* end of fm_rtc_control_grp */
615 /** @} */ /* end of fm_rtc_grp */
616 /** @} */ /* end of FM_grp group */
619 #endif /* __FM_RTC_EXT_H__ */