All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
IRTC: IRTC Driver

## Overview

The KSDK provides a driver for the IRTC module of Kinetis devices.

## Data Structures

struct | irtc_datetime_t
| Structure is used to hold the date and time. More...
struct | irtc_daylight_time_t
| Structure is used to hold the daylight saving time. More...
struct | irtc_tamper_config_t
| Structure is used to define the parameters to configure a RTC tamper event. More...
struct | irtc_config_t
| RTC config structure. More...

## Enumerations

enum | irtc_filter_clock_source_t { kIRTC_32K = 0x0, kIRTC_512 = 0x1, kIRTC_128 = 0x2, kIRTC_64 = 0x3, kIRTC_16 = 0x4, kIRTC_8 = 0x5, kIRTC_4 = 0x6, kIRTC_2 = 0x7 }
| IRTC filter clock source options. More...
enum | irtc_tamper_pins_t { kIRTC_Tamper_0 = 0U, kIRTC_Tamper_1, kIRTC_Tamper_2, kIRTC_Tamper_3 }
| IRTC Tamper pins. More...

enum

irtc_interrupt_enable_t {
kIRTC_TamperInterruptEnable = RTC_IER_TAMPER_IE_MASK,
kIRTC_AlarmInterruptEnable = RTC_IER_ALM_IE_MASK,
kIRTC_DayInterruptEnable = RTC_IER_DAY_IE_MASK,
kIRTC_HourInterruptEnable = RTC_IER_HOUR_IE_MASK,
kIRTC_MinInterruptEnable = RTC_IER_MIN_IE_MASK,
kIRTC_1hzInterruptEnable = RTC_IER_IE_1HZ_MASK,
kIRTC_2hzInterruptEnable = RTC_IER_IE_2HZ_MASK,
kIRTC_4hzInterruptEnable = RTC_IER_IE_4HZ_MASK,
kIRTC_8hzInterruptEnable = RTC_IER_IE_8HZ_MASK,
kIRTC_16hzInterruptEnable = RTC_IER_IE_16HZ_MASK,
kIRTC_32hzInterruptEnable = RTC_IER_IE_32HZ_MASK,
kIRTC_64hzInterruptEnable = RTC_IER_IE_64HZ_MASK,
kIRTC_128hzInterruptEnable = RTC_IER_IE_128HZ_MASK,
kIRTC_256hzInterruptEnable = RTC_IER_IE_256HZ_MASK,
kIRTC_512hzInterruptEnable = RTC_IER_IE_512HZ_MASK
}

| List of IRTC interrupts. More...

enum

irtc_status_flags_t {
kIRTC_TamperFlag = RTC_ISR_TAMPER_IS_MASK,
kIRTC_AlarmFlag = RTC_ISR_ALM_IS_MASK,
kIRTC_DayFlag = RTC_ISR_DAY_IS_MASK,
kIRTC_HourFlag = RTC_ISR_HOUR_IS_MASK,
kIRTC_MinFlag = RTC_ISR_MIN_IS_MASK,
kIRTC_1hzFlag = RTC_ISR_IS_1HZ_MASK,
kIRTC_2hzFlag = RTC_ISR_IS_2HZ_MASK,
kIRTC_4hzFlag = RTC_ISR_IS_4HZ_MASK,
kIRTC_8hzFlag = RTC_ISR_IS_8HZ_MASK,
kIRTC_16hzFlag = RTC_ISR_IS_16HZ_MASK,
kIRTC_32hzFlag = RTC_ISR_IS_32HZ_MASK,
kIRTC_64hzFlag = RTC_ISR_IS_64HZ_MASK,
kIRTC_128hzFlag = RTC_ISR_IS_128HZ_MASK,
kIRTC_256hzFlag = RTC_ISR_IS_256HZ_MASK,
kIRTC_512hzFlag = RTC_ISR_IS_512HZ_MASK,
kIRTC_InvalidFlag = (RTC_STATUS_INVAL_BIT_MASK << 16),
kIRTC_WriteProtFlag = (RTC_STATUS_WRITE_PROT_EN_MASK << 16),
kIRTC_CpuLowVoltFlag = (RTC_STATUS_CPU_LOW_VOLT_MASK << 16),
kIRTC_ResetSrcFlag = (RTC_STATUS_RST_SRC_MASK << 16),
kIRTC_CmpIntFlag = (RTC_STATUS_CMP_INT_MASK << 16),
kIRTC_BusErrFlag = (RTC_STATUS_BUS_ERR_MASK << 16),
kIRTC_CmpDoneFlag = (RTC_STATUS_CMP_DONE_MASK << 16)
}

| List of IRTC flags. More...
enum | irtc_alarm_match_t { kRTC_MatchSecMinHr = 0, kRTC_MatchSecMinHrDay = 1, kRTC_MatchSecMinHrDayMnth = 2, kRTC_MatchSecMinHrDayMnthYr = 3 }
| IRTC alarm match options. More...
enum | irtc_osc_cap_load_t { kIRTC_Capacitor2p = (1U << 1), kIRTC_Capacitor4p = (1U << 2), kIRTC_Capacitor8p = (1U << 3), kIRTC_Capacitor16p = (1U << 4) }
| List of RTC Oscillator capacitor load settings. More...

## Functions

static void | IRTC_SetOscCapLoad (RTC_Type *base, uint16_t capLoad)
| This function sets the specified capacitor configuration for the RTC oscillator. More...
status_t | IRTC_SetWriteProtection (RTC_Type *base, bool lock)
| Locks or unlocks IRTC registers for write access. More...
static void | IRTC_Reset (RTC_Type *base)
| Performs a software reset on the IRTC module. More...

## Driver version

#define | FSL_IRTC_DRIVER_VERSION (MAKE_VERSION(2, 0, 0))
| Version 2.0.0.

## Initialization and deinitialization

status_t | IRTC_Init (RTC_Type *base, const irtc_config_t *config)
| Ungates the IRTC clock and configures the peripheral for basic operation. More...
static void | IRTC_Deinit (RTC_Type *base)
| Gate the IRTC clock. More...
void | IRTC_GetDefaultConfig (irtc_config_t *config)
| Fill in the IRTC config struct with the default settings. More...

## Current Time & Alarm

status_t | IRTC_SetDatetime (RTC_Type *base, const irtc_datetime_t *datetime)
| Sets the IRTC date and time according to the given time structure. More...
void | IRTC_GetDatetime (RTC_Type *base, irtc_datetime_t *datetime)
| Gets the IRTC time and stores it in the given time structure. More...
status_t | IRTC_SetAlarm (RTC_Type *base, const irtc_datetime_t *alarmTime)
| Sets the IRTC alarm time. More...
void | IRTC_GetAlarm (RTC_Type *base, irtc_datetime_t *datetime)
| Returns the IRTC alarm time. More...

## Interrupt Interface

static void | IRTC_EnableInterrupts (RTC_Type *base, uint32_t mask)
| Enables the selected IRTC interrupts. More...
static void | IRTC_DisableInterrupts (RTC_Type *base, uint32_t mask)
| Disables the selected IRTC interrupts. More...
static uint16_t | IRTC_GetEnabledInterrupts (RTC_Type *base)
| Gets the enabled IRTC interrupts. More...

## Status Interface

static uint32_t | IRTC_GetStatusFlags (RTC_Type *base)
| Gets the IRTC status flags. More...
static void | IRTC_ClearStatusFlags (RTC_Type *base, uint32_t mask)
| Clears the IRTC status flags. More...

## Daylight Savings Interface

void | IRTC_SetDaylightTime (RTC_Type *base, const irtc_daylight_time_t *datetime)
| Sets the IRTC daylight savings start and stop date and time. More...
void | IRTC_GetDaylightTime (RTC_Type *base, irtc_daylight_time_t *datetime)
| Gets the IRTC daylight savings time and stores it in the given time structure. More...

## Time Compensation Interface

void | IRTC_SetCoarseCompensation (RTC_Type *base, uint8_t compensationValue, uint8_t compensationInterval)
| Enables the coarse compensation and sets the value in the IRTC compensation register. More...
void | IRTC_SetFineCompensation (RTC_Type *base, uint8_t integralValue, uint8_t fractionValue, bool accumulateFractional)
| Enables the fine compensation and sets the value in the IRTC compensation register. More...

## Tamper Interface

void | IRTC_SetTamperParams (RTC_Type *base, irtc_tamper_pins_t tamperNumber, const irtc_tamper_config_t *tamperConfig)
| This function allows configuring the four tamper inputs. More...

## Data Structure Documentation

struct irtc_datetime_t

### Data Fields

uint16_t | year
| Range from 1984 to 2239. More...
uint8_t | month
| Range from 1 to 12. More...
uint8_t | day
| Range from 1 to 31 (depending on month). More...
uint8_t | weekDay
| Range from 0(Sunday) to 6(Saturday). More...
uint8_t | hour
| Range from 0 to 23. More...
uint8_t | minute
| Range from 0 to 59. More...
uint8_t | second
| Range from 0 to 59. More...

#### Field Documentation

uint16_t irtc_datetime_t::year

uint8_t irtc_datetime_t::month

uint8_t irtc_datetime_t::day

uint8_t irtc_datetime_t::weekDay

uint8_t irtc_datetime_t::hour

uint8_t irtc_datetime_t::minute

uint8_t irtc_datetime_t::second

struct irtc_daylight_time_t

### Data Fields

uint8_t | startMonth
| Range from 1 to 12.
uint8_t | endMonth
| Range from 1 to 12.
uint8_t | startDay
| Range from 1 to 31 (depending on month)
uint8_t | endDay
| Range from 1 to 31 (depending on month)
uint8_t | startHour
| Range from 0 to 23.
uint8_t | endHour
| Range from 0 to 23.

struct irtc_tamper_config_t

### Data Fields

bool | pinPolarity
| true: tamper has active low polarity; false: active high polarity
irtc_filter_clock_source_t | filterClk
| Clock source for the tamper filter.
uint8_t | filterDuration
| Tamper filter duration. More...

#### Field Documentation

uint8_t irtc_tamper_config_t::filterDuration

struct irtc_config_t

This structure holds the configuration settings for the RTC peripheral. To initialize this structure to reasonable defaults, call the IRTC_GetDefaultConfig() function and pass a pointer to your config structure instance.

The config struct can be made const so it resides in flash

### Data Fields

bool | wakeupSelect
| true: Tamper pin 0 is used to wakeup the chip; false: Tamper pin 0 is used as the tamper pin
bool | timerStdMask
| true: Sampling clocks gated in standby mode; false: Sampling clocks not gated
irtc_alarm_match_t | alrmMatch
| Pick one option from enumeration :: irtc_alarm_match_t.

## Enumeration Type Documentation

enum irtc_filter_clock_source_t

Enumerator
kIRTC_32K | Use 32 kHz clock source for the tamper filter.
kIRTC_512 | Use 512 Hz clock source for the tamper filter.
kIRTC_128 | Use 128 Hz clock source for the tamper filter.
kIRTC_64 | Use 64 Hz clock source for the tamper filter.
kIRTC_16 | Use 16 Hz clock source for the tamper filter.
kIRTC_8 | Use 8 Hz clock source for the tamper filter.
kIRTC_4 | Use 4 Hz clock source for the tamper filter.
kIRTC_2 | Use 2 Hz clock source for the tamper filter.

enum irtc_tamper_pins_t

Enumerator
kIRTC_Tamper_0 | External Tamper 0.
kIRTC_Tamper_1 | External Tamper 1.
kIRTC_Tamper_2 | External Tamper 2.
kIRTC_Tamper_3 | Internal tamper, does not have filter configuration.

enum irtc_interrupt_enable_t

Enumerator
kIRTC_TamperInterruptEnable | Tamper Interrupt Enable.
kIRTC_AlarmInterruptEnable | Alarm Interrupt Enable.
kIRTC_DayInterruptEnable | Days Interrupt Enable.
kIRTC_HourInterruptEnable | Hours Interrupt Enable.
kIRTC_MinInterruptEnable | Minutes Interrupt Enable.
kIRTC_1hzInterruptEnable | 1 Hz interval Interrupt Enable
kIRTC_2hzInterruptEnable | 2 Hz interval Interrupt Enable
kIRTC_4hzInterruptEnable | 4 Hz interval Interrupt Enable
kIRTC_8hzInterruptEnable | 8 Hz interval Interrupt Enable
kIRTC_16hzInterruptEnable | 16 Hz interval Interrupt Enable
kIRTC_32hzInterruptEnable | 32 Hz interval Interrupt Enable
kIRTC_64hzInterruptEnable | 64 Hz interval Interrupt Enable
kIRTC_128hzInterruptEnable | 128 Hz interval Interrupt Enable
kIRTC_256hzInterruptEnable | 256 Hz interval Interrupt Enable
kIRTC_512hzInterruptEnable | 512 Hz interval Interrupt Enable

enum irtc_status_flags_t

Enumerator
kIRTC_TamperFlag | Tamper Status flag.
kIRTC_AlarmFlag | Alarm Status flag.
kIRTC_DayFlag | Days Status flag.
kIRTC_HourFlag | Hour Status flag.
kIRTC_MinFlag | Minutes Status flag.
kIRTC_1hzFlag | 1 Hz interval status flag
kIRTC_2hzFlag | 2 Hz interval status flag
kIRTC_4hzFlag | 4 Hz interval status flag
kIRTC_8hzFlag | 8 Hz interval status flag
kIRTC_16hzFlag | 16 Hz interval status flag
kIRTC_32hzFlag | 32 Hz interval status flag
kIRTC_64hzFlag | 64 Hz interval status flag
kIRTC_128hzFlag | 128 Hz interval status flag
kIRTC_256hzFlag | 256 Hz interval status flag
kIRTC_512hzFlag | 512 Hz interval status flag
kIRTC_InvalidFlag | Indicates if time/date counters are invalid.
kIRTC_WriteProtFlag | Write protect enable status flag.
kIRTC_CpuLowVoltFlag | CPU low voltage warning flag.
kIRTC_ResetSrcFlag | Reset source flag.
kIRTC_CmpIntFlag | Compensation interval status flag.
kIRTC_BusErrFlag | Bus error flag.
kIRTC_CmpDoneFlag | Compensation done flag.

enum irtc_alarm_match_t

Enumerator
kRTC_MatchSecMinHr | Only match second, minute and hour.
kRTC_MatchSecMinHrDay | Only match second, minute, hour and day.
kRTC_MatchSecMinHrDayMnth | Only match second, minute, hour, day and month.
kRTC_MatchSecMinHrDayMnthYr | Only match second, minute, hour, day, month and year.

enum irtc_osc_cap_load_t

Enumerator
kIRTC_Capacitor2p | 2pF capacitor load
kIRTC_Capacitor4p | 4pF capacitor load
kIRTC_Capacitor8p | 8pF capacitor load
kIRTC_Capacitor16p | 16pF capacitor load

## Function Documentation

status_t IRTC_Init | ( | RTC_Type * | base,
|  | const irtc_config_t * | config
| ) |  |

This function initiates a soft-reset of the IRTC module, this has not effect on DST, calendaring, standby time and tamper detect registers.

Note
  This API should be called at the beginning of the application using the IRTC driver.

Parameters

  base | IRTC peripheral base address
  config | Pointer to user's IRTC config structure.

Returns
  kStatus_Fail if we cannot disable register write protection

static void IRTC_Deinit | ( | RTC_Type * | base | ) |

inlinestatic

Parameters

  base | IRTC peripheral base address

void IRTC_GetDefaultConfig | ( | irtc_config_t * | config | ) |

The default values are:

* config->wakeupSelect = true;
* config->timerStdMask = false;
* config->alrmMatch = kRTC_MatchSecMinHr;
*

Parameters

  config | Pointer to user's IRTC config structure.

status_t IRTC_SetDatetime | ( | RTC_Type * | base,
|  | const irtc_datetime_t * | datetime
| ) |  |

The IRTC counter is started after the time is set.

Parameters

  base | IRTC peripheral base address
  datetime | Pointer to structure where the date and time details to set are stored

Returns
  kStatus_Success: success in setting the time and starting the IRTC kStatus_InvalidArgument: failure. An error occurs because the datetime format is incorrect.

void IRTC_GetDatetime | ( | RTC_Type * | base,
|  | irtc_datetime_t * | datetime
| ) |  |

Parameters

  base | IRTC peripheral base address
  datetime | Pointer to structure where the date and time details are stored.

status_t IRTC_SetAlarm | ( | RTC_Type * | base,
|  | const irtc_datetime_t * | alarmTime
| ) |  |

Parameters

  base | RTC peripheral base address
  alarmTime | Pointer to structure where the alarm time is stored.

Note
  weekDay field of alarmTime is not used during alarm match and should be set to 0

Returns
  kStatus_Success: success in setting the alarm kStatus_InvalidArgument: error in setting the alarm. Error occurs because the alarm datetime format is incorrect.

void IRTC_GetAlarm | ( | RTC_Type * | base,
|  | irtc_datetime_t * | datetime
| ) |  |

Parameters

  base | RTC peripheral base address
  datetime | Pointer to structure where the alarm date and time details are stored.

static void IRTC_EnableInterrupts | ( | RTC_Type * | base,
|  | uint32_t | mask
| ) |  |

inlinestatic

Parameters

  base | IRTC peripheral base address
  mask | The interrupts to enable. This is a logical OR of members of the enumeration ::rtc_interrupt_enable_t

static void IRTC_DisableInterrupts | ( | RTC_Type * | base,
|  | uint32_t | mask
| ) |  |

inlinestatic

Parameters

  base | IRTC peripheral base address
  mask | The interrupts to enable. This is a logical OR of members of the enumeration ::rtc_interrupt_enable_t

static uint16_t IRTC_GetEnabledInterrupts | ( | RTC_Type * | base | ) |

inlinestatic

Parameters

  base | IRTC peripheral base address

Returns
  The enabled interrupts. This is the logical OR of members of the enumeration ::rtc_interrupt_enable_t

static uint32_t IRTC_GetStatusFlags | ( | RTC_Type * | base | ) |

inlinestatic

Parameters

  base | IRTC peripheral base address

Returns
  The status flags. This is the logical OR of members of the enumeration irtc_status_flags_t

static void IRTC_ClearStatusFlags | ( | RTC_Type * | base,
|  | uint32_t | mask
| ) |  |

inlinestatic

Parameters

  base | IRTC peripheral base address
  mask | The status flags to clear. This is a logical OR of members of the enumeration irtc_status_flags_t

static void IRTC_SetOscCapLoad | ( | RTC_Type * | base,
|  | uint16_t | capLoad
| ) |  |

inlinestatic

Parameters

  base | IRTC peripheral base address
  capLoad | Oscillator loads to enable. This is a logical OR of members of the enumeration irtc_osc_cap_load_t

status_t IRTC_SetWriteProtection | ( | RTC_Type * | base,
|  | bool | lock
| ) |  |

Note
  When the registers are unlocked, they remain in unlocked state for 2 seconds, after which they are locked automatically. After power-on-reset, the registers come out unlocked and they are locked automatically 15 seconds after power on.

Parameters

  base | IRTC peripheral base address
  lock | true: Lock IRTC registers; false: Unlock IRTC registers.

Returns
  kStatus_Success: if lock or unlock operation is successful kStatus_Fail: if lock or unlock operation fails even after multiple retry attempts

static void IRTC_Reset | ( | RTC_Type * | base | ) |

inlinestatic

Clears contents of alarm, interrupt (status and enable except tamper interrupt enable bit) registers, STATUS[CMP_DONE] and STATUS[BUS_ERR]. This has no effect on DST, calendaring, standby time and tamper detect registers.

Parameters

  base | IRTC peripheral base address

void IRTC_SetDaylightTime | ( | RTC_Type * | base,
|  | const irtc_daylight_time_t * | datetime
| ) |  |

It also enables the daylight saving bit in the IRTC control register

Parameters

  base | IRTC peripheral base address
  datetime | Pointer to a structure where the date and time details are stored.

void IRTC_GetDaylightTime | ( | RTC_Type * | base,
|  | irtc_daylight_time_t * | datetime
| ) |  |

Parameters

  base | IRTC peripheral base address
  datetime | Pointer to a structure where the date and time details are stored.

void IRTC_SetCoarseCompensation | ( | RTC_Type * | base,
|  | uint8_t | compensationValue,
|  | uint8_t | compensationInterval
| ) |  |

Parameters

  base | IRTC peripheral base address
  compensationValue | Compensation value is a 2's complement value.
  compensationInterval | Compensation interval.

void IRTC_SetFineCompensation | ( | RTC_Type * | base,
|  | uint8_t | integralValue,
|  | uint8_t | fractionValue,
|  | bool | accumulateFractional
| ) |  |

Parameters

  base | The IRTC peripheral base address
  integralValue | Compensation integral value; twos complement value of the integer part
  fractionValue | Compensation fraction value expressed as number of clock cycles of a fixed 4.194304Mhz clock that have to be added.
  accumulateFractional | Flag indicating if we want to add to previous fractional part; true: Add to previously accumulated fractional part, false: Start afresh and overwrite current value

void IRTC_SetTamperParams | ( | RTC_Type * | base,
|  | irtc_tamper_pins_t | tamperNumber,
|  | const irtc_tamper_config_t * | tamperConfig
| ) |  |

The function configures the filter properties for the three external tampers. It also sets up active/passive and direction of the tamper bits, which are not available on all platforms.

Note
  This function programs the tamper filter parameters. The user must gate the 32K clock to the RTC before calling this function. It is assumed that the time and date are set after this and the tamper parameters do not require to be changed again later.

Parameters

  base | The IRTC peripheral base address
  tamperNumber | The IRTC tamper input to configure
  tamperConfig | The IRTC tamper properties