1 /* Copyright (c) 2008-2011 Freescale Semiconductor, Inc. 2 * All rights reserved. 3 * 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. 14 * 15 * 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 19 * later version. 20 * 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. 31 */ 32 33 /**************************************************************************//** 34 @File fm_rtc_ext.h 35 36 @Description External definitions and API for FM RTC IEEE1588 Timer Module. 37 38 @Cautions None. 39 *//***************************************************************************/ 40 41 #ifndef __FM_RTC_EXT_H__ 42 #define __FM_RTC_EXT_H__ 43 44 45 #include "error_ext.h" 46 #include "std_ext.h" 47 48 49 /**************************************************************************//** 50 51 @Group FM_grp Frame Manager API 52 53 @Description FM API functions, definitions and enums 54 55 @{ 56 *//***************************************************************************/ 57 58 /**************************************************************************//** 59 @Group fm_rtc_grp FM RTC 60 61 @Description FM RTC functions, definitions and enums. 62 63 @{ 64 *//***************************************************************************/ 65 66 /**************************************************************************//** 67 @Group fm_rtc_init_grp FM RTC Initialization Unit 68 69 @Description FM RTC initialization API. 70 71 @{ 72 *//***************************************************************************/ 73 74 /**************************************************************************//** 75 @Description FM RTC Alarm Polarity Options. 76 *//***************************************************************************/ 77 typedef enum e_FmRtcAlarmPolarity 78 { 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; 82 83 /**************************************************************************//** 84 @Description FM RTC Trigger Polarity Options. 85 *//***************************************************************************/ 86 typedef enum e_FmRtcTriggerPolarity 87 { 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; 91 92 /**************************************************************************//** 93 @Description IEEE1588 Timer Module FM RTC Optional Clock Sources. 94 *//***************************************************************************/ 95 typedef enum e_FmSrcClock 96 { 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 */ 100 }e_FmSrcClk; 101 102 /**************************************************************************//** 103 @Description FM RTC configuration parameters structure. 104 105 This structure should be passed to FM_RTC_Config(). 106 *//***************************************************************************/ 107 typedef struct t_FmRtcParams 108 { 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 */ 113 } t_FmRtcParams; 114 115 116 /**************************************************************************//** 117 @Function FM_RTC_Config 118 119 @Description Configures the FM RTC module according to user's parameters. 120 121 The driver assigns default values to some FM RTC parameters. 122 These parameters can be overwritten using the advanced 123 configuration routines. 124 125 @Param[in] p_FmRtcParam - FM RTC configuration parameters. 126 127 @Return Handle to the new FM RTC object; NULL pointer on failure. 128 129 @Cautions None 130 *//***************************************************************************/ 131 t_Handle FM_RTC_Config(t_FmRtcParams *p_FmRtcParam); 132 133 /**************************************************************************//** 134 @Function FM_RTC_Init 135 136 @Description Initializes the FM RTC driver and hardware. 137 138 @Param[in] h_FmRtc - Handle to FM RTC object. 139 140 @Return E_OK on success; Error code otherwise. 141 142 @Cautions h_FmRtc must have been previously created using FM_RTC_Config(). 143 *//***************************************************************************/ 144 t_Error FM_RTC_Init(t_Handle h_FmRtc); 145 146 /**************************************************************************//** 147 @Function FM_RTC_Free 148 149 @Description Frees the FM RTC object and all allocated resources. 150 151 @Param[in] h_FmRtc - Handle to FM RTC object. 152 153 @Return E_OK on success; Error code otherwise. 154 155 @Cautions h_FmRtc must have been previously created using FM_RTC_Config(). 156 *//***************************************************************************/ 157 t_Error FM_RTC_Free(t_Handle h_FmRtc); 158 159 160 /**************************************************************************//** 161 @Group fm_rtc_adv_config_grp FM RTC Advanced Configuration Unit 162 163 @Description FM RTC advanced configuration functions. 164 165 @{ 166 *//***************************************************************************/ 167 168 /**************************************************************************//** 169 @Function FM_RTC_ConfigPeriod 170 171 @Description Configures the period of the timestamp if different than 172 default [1000]. 173 174 @Param[in] h_FmRtc - Handle to FM RTC object. 175 @Param[in] period - Period in nano-seconds. 176 177 @Return E_OK on success; Error code otherwise. 178 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); 182 183 /**************************************************************************//** 184 @Function FM_RTC_ConfigSourceClock 185 186 @Description Configures the source clock of the RTC. 187 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). 191 192 @Return E_OK on success; Error code otherwise. 193 194 @Cautions h_FmRtc must have been previously created using FM_RTC_Config(). 195 *//***************************************************************************/ 196 t_Error FM_RTC_ConfigSourceClock(t_Handle h_FmRtc, 197 e_FmSrcClk srcClk, 198 uint32_t freqInMhz); 199 200 /**************************************************************************//** 201 @Function FM_RTC_ConfigPulseRealignment 202 203 @Description Configures the RTC to automatic FIPER pulse realignment in 204 response to timer adjustments [FALSE] 205 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. 209 210 @Param[in] h_FmRtc - Handle to FM RTC object. 211 @Param[in] enable - TRUE to enable automatic realignment. 212 213 @Return E_OK on success; Error code otherwise. 214 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); 218 219 /**************************************************************************//** 220 @Function FM_RTC_ConfigFrequencyBypass 221 222 @Description Configures the RTC to bypass the frequency compensation 223 mechanism. [FALSE] 224 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. 228 229 @Param[in] h_FmRtc - Handle to FM RTC object. 230 @Param[in] enabled - TRUE to bypass frequency compensation; 231 FALSE otherwise. 232 233 @Return E_OK on success; Error code otherwise. 234 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); 238 239 /**************************************************************************//** 240 @Function FM_RTC_ConfigInvertedInputClockPhase 241 242 @Description Configures the RTC to invert the source clock phase on input. 243 [FALSE] 244 245 @Param[in] h_FmRtc - Handle to FM RTC object. 246 @Param[in] inverted - TRUE to invert the source clock phase on input. 247 FALSE otherwise. 248 249 @Return E_OK on success; Error code otherwise. 250 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); 254 255 /**************************************************************************//** 256 @Function FM_RTC_ConfigInvertedOutputClockPhase 257 258 @Description Configures the RTC to invert the output clock phase. 259 [FALSE] 260 261 @Param[in] h_FmRtc - Handle to FM RTC object. 262 @Param[in] inverted - TRUE to invert the output clock phase. 263 FALSE otherwise. 264 265 @Return E_OK on success; Error code otherwise. 266 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); 270 271 /**************************************************************************//** 272 @Function FM_RTC_ConfigOutputClockDivisor 273 274 @Description Configures the divisor for generating the output clock from 275 the RTC clock. [0x00000002] 276 277 @Param[in] h_FmRtc - Handle to FM RTC object. 278 @Param[in] divisor - Divisor for generation of the output clock. 279 280 @Return E_OK on success; Error code otherwise. 281 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); 285 286 /**************************************************************************//** 287 @Function FM_RTC_ConfigAlarmPolarity 288 289 @Description Configures the polarity (active-high/active-low) of a specific 290 alarm signal. [e_FM_RTC_ALARM_POLARITY_ACTIVE_HIGH] 291 292 @Param[in] h_FmRtc - Handle to FM RTC object. 293 @Param[in] alarmId - Alarm ID. 294 @Param[in] alarmPolarity - Alarm polarity. 295 296 @Return E_OK on success; Error code otherwise. 297 298 @Cautions h_FmRtc must have been previously created using FM_RTC_Config(). 299 *//***************************************************************************/ 300 t_Error FM_RTC_ConfigAlarmPolarity(t_Handle h_FmRtc, 301 uint8_t alarmId, 302 e_FmRtcAlarmPolarity alarmPolarity); 303 304 /**************************************************************************//** 305 @Function FM_RTC_ConfigExternalTriggerPolarity 306 307 @Description Configures the polarity (rising/falling edge) of a specific 308 external trigger signal. [e_FM_RTC_TRIGGER_ON_FALLING_EDGE] 309 310 @Param[in] h_FmRtc - Handle to FM RTC object. 311 @Param[in] triggerId - Trigger ID. 312 @Param[in] triggerPolarity - Trigger polarity. 313 314 @Return E_OK on success; Error code otherwise. 315 316 @Cautions h_FmRtc must have been previously created using FM_RTC_Config(). 317 *//***************************************************************************/ 318 t_Error FM_RTC_ConfigExternalTriggerPolarity(t_Handle h_FmRtc, 319 uint8_t triggerId, 320 e_FmRtcTriggerPolarity triggerPolarity); 321 322 /** @} */ /* end of fm_rtc_adv_config_grp */ 323 /** @} */ /* end of fm_rtc_init_grp */ 324 325 326 /**************************************************************************//** 327 @Group fm_rtc_control_grp FM RTC Control Unit 328 329 @Description FM RTC runtime control API. 330 331 @{ 332 *//***************************************************************************/ 333 334 /**************************************************************************//** 335 @Function t_FmRtcExceptionsCallback 336 337 @Description Exceptions user callback routine, used for RTC different mechanisms. 338 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); 343 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 351 the RTC period */ 352 t_FmRtcExceptionsCallback *f_AlarmCallback; /**< This routine will be called when RTC 353 reaches alarmTime */ 354 bool clearOnExpiration; /**< TRUE to turn off the alarm once expired. */ 355 } t_FmRtcAlarmParams; 356 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; 367 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; 378 379 380 /**************************************************************************//** 381 @Function FM_RTC_Enable 382 383 @Description Enable the RTC (time count is started). 384 385 The user can select to resume the time count from previous 386 point, or to restart the time count. 387 388 @Param[in] h_FmRtc - Handle to FM RTC object. 389 @Param[in] resetClock - Restart the time count from zero. 390 391 @Return E_OK on success; Error code otherwise. 392 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); 396 397 /**************************************************************************//** 398 @Function FM_RTC_Disable 399 400 @Description Disables the RTC (time count is stopped). 401 402 @Param[in] h_FmRtc - Handle to FM RTC object. 403 404 @Return E_OK on success; Error code otherwise. 405 406 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init(). 407 *//***************************************************************************/ 408 t_Error FM_RTC_Disable(t_Handle h_FmRtc); 409 410 /**************************************************************************//** 411 @Function FM_RTC_SetClockOffset 412 413 @Description Sets the clock offset (usually relative to another clock). 414 415 The user can pass a negative offset value. 416 417 @Param[in] h_FmRtc - Handle to FM RTC object. 418 @Param[in] offset - New clock offset (in nanoseconds). 419 420 @Return E_OK on success; Error code otherwise. 421 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); 425 426 /**************************************************************************//** 427 @Function FM_RTC_SetAlarm 428 429 @Description Schedules an alarm event to a given RTC time. 430 431 @Param[in] h_FmRtc - Handle to FM RTC object. 432 @Param[in] p_FmRtcAlarmParams - Alarm parameters. 433 434 @Return E_OK on success; Error code otherwise. 435 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); 440 441 /**************************************************************************//** 442 @Function FM_RTC_SetPeriodicPulse 443 444 @Description Sets a periodic pulse. 445 446 @Param[in] h_FmRtc - Handle to FM RTC object. 447 @Param[in] p_FmRtcPeriodicPulseParams - Periodic pulse parameters. 448 449 @Return E_OK on success; Error code otherwise. 450 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); 455 456 /**************************************************************************//** 457 @Function FM_RTC_ClearPeriodicPulse 458 459 @Description Clears a periodic pulse. 460 461 @Param[in] h_FmRtc - Handle to FM RTC object. 462 @Param[in] periodicPulseId - Periodic pulse id. 463 464 @Return E_OK on success; Error code otherwise. 465 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); 469 470 /**************************************************************************//** 471 @Function FM_RTC_SetExternalTrigger 472 473 @Description Sets an external trigger indication and define a callback 474 routine to be called on such event. 475 476 @Param[in] h_FmRtc - Handle to FM RTC object. 477 @Param[in] p_FmRtcExternalTriggerParams - External Trigger parameters. 478 479 @Return E_OK on success; Error code otherwise. 480 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); 484 485 /**************************************************************************//** 486 @Function FM_RTC_ClearExternalTrigger 487 488 @Description Clears external trigger indication. 489 490 @Param[in] h_FmRtc - Handle to FM RTC object. 491 @Param[in] id - External Trigger id. 492 493 @Return E_OK on success; Error code otherwise. 494 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); 498 499 /**************************************************************************//** 500 @Function FM_RTC_GetExternalTriggerTimeStamp 501 502 @Description Reads the External Trigger TimeStamp. 503 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). 507 508 @Return E_OK on success; Error code otherwise. 509 510 @Cautions h_FmRtc must have been previously initialized using FM_RTC_Init(). 511 *//***************************************************************************/ 512 t_Error FM_RTC_GetExternalTriggerTimeStamp(t_Handle h_FmRtc, 513 uint8_t triggerId, 514 uint64_t *p_TimeStamp); 515 516 /**************************************************************************//** 517 @Function FM_RTC_GetCurrentTime 518 519 @Description Returns the current RTC time. 520 521 @Param[in] h_FmRtc - Handle to FM RTC object. 522 @Param[out] p_Ts - returned time stamp (in nanoseconds). 523 524 @Return E_OK on success; Error code otherwise. 525 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); 529 530 /**************************************************************************//** 531 @Function FM_RTC_SetCurrentTime 532 533 @Description Sets the current RTC time. 534 535 @Param[in] h_FmRtc - Handle to FM RTC object. 536 @Param[in] ts - The new time stamp (in nanoseconds). 537 538 @Return E_OK on success; Error code otherwise. 539 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); 543 544 /**************************************************************************//** 545 @Function FM_RTC_GetFreqCompensation 546 547 @Description TODO 548 549 @Param[in] h_FmRtc - Handle to FM RTC object. 550 @Param[out] p_Compensation - A pointer to the returned value of compensation. 551 552 @Return E_OK on success; Error code otherwise. 553 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); 557 558 /**************************************************************************//** 559 @Function FM_RTC_SetFreqCompensation 560 561 @Description TODO 562 563 @Param[in] h_FmRtc - Handle to FM RTC object. 564 @Param[in] freqCompensation - the new desired compensation value to be set. 565 566 @Return E_OK on success; Error code otherwise. 567 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); 571 572 #if (defined(DEBUG_ERRORS) && (DEBUG_ERRORS > 0)) 573 /**************************************************************************//** 574 @Function FM_RTC_DumpRegs 575 576 @Description Dumps all FM registers 577 578 @Param[in] h_FmRtc A handle to an FM RTC Module. 579 580 @Return E_OK on success; 581 582 @Cautions Allowed only FM_Init(). 583 *//***************************************************************************/ 584 t_Error FM_RTC_DumpRegs(t_Handle h_FmRtc); 585 #endif /* (defined(DEBUG_ERRORS) && ... */ 586 587 /** @} */ /* end of fm_rtc_control_grp */ 588 /** @} */ /* end of fm_rtc_grp */ 589 /** @} */ /* end of FM_grp group */ 590 591 592 #endif /* __FM_RTC_EXT_H__ */ 593