RTT Interface

Driver API for RTT (plib_rtt.h) More...

Data Structures
struct	RTT_OBJECT
	RTT object structure. More...

Typedefs
typedef uint32_t	RTT_CLOCK_SOURCE
	RTT counter clock source selection type.
typedef uint32_t	RTT_INT_MASK
	RTT interrupt source mask type.
typedef void(*	RTT_CALLBACK) (RTT_INT_MASK int_cause)
	RTT callback function type.

Functions
void	RTT_Enable (void)
	Starts the RTT counter so it begins (or resumes) counting.
void	RTT_Disable (void)
	Stops the RTT counter and removes its dynamic power consumption.
void	RTT_RestartTimer (void)
	Restarts the RTT counter from zero and reloads the prescaler.
bool	RTT_SetPrescaler (uint16_t prescaler)
	Sets the prescaler value that divides the RTT source clock. The values 1 and 2 are not allowed by the hardware; pass 0 to get a divide ratio of 65536 (2^16). The increment interrupt must be turned off before calling this function.
bool	RTT_SelectClockSource (RTT_CLOCK_SOURCE source)
	Chooses what drives the 32-bit counter.
bool	RTT_SetAlarm (uint32_t alarm)
	Sets the value the counter is compared against to fire an alarm. The alarm interrupt must be turned off before calling this function.
uint32_t	RTT_GetTimerValue (void)
	Reads the current 32-bit counter value. The counter runs on a different clock than the CPU, so this function reads it twice and returns a stable value.
void	RTT_EnableInterrupt (RTT_INT_MASK interrupt_mask)
	Turns on one or more RTT interrupt sources.
void	RTT_DisableInterrupt (RTT_INT_MASK interrupt_mask)
	Turns off one or more RTT interrupt sources.
void	RTT_SetCallbackHandler (RTT_CALLBACK callback)
	Registers a function to be called from the RTT interrupt handler.
RTT_INT_MASK	RTT_GetStatus (void)
	Reads the pending status flags and clears them in one step. Intended for polling. Do not mix with interrupt mode: this read clears the very flags the interrupt handler would otherwise see.
uint32_t	RTT_GetTickFrequency (void)
	Returns the rate at which the counter increments, in Hz.

Variables
RTT_INT_MASK	RTT_OBJECT::rtt_int_cause
	Interrupt cause mask for the last RTT interrupt.
RTT_CALLBACK	RTT_OBJECT::rtt_callback
	Callback function pointer for RTT interrupts.

Description

Driver API for RTT (plib_rtt.h)

Usage Example

The following example demonstrates typical usage of the RTT peripheral:

/*******************************************************************************
 * @file configure_rtt.c
 * @brief Real-Time Timer (RTT) configuration template
 *
 * @details
 * The RTT peripheral maintains a 32-bit free-running
 * counter clocked from the 32.768 kHz slow clock. The slow clock can be divided
 * down by a 16-bit prescaler, or the counter can be driven directly by the
 * RTC's calibrated 1 Hz output for long-term accuracy.
 *
 * Key concepts:
 * - Prescaler: divides the slow clock so the counter increments at a chosen
 *   rate. Setting the prescaler to 0x8000 yields a 1 Hz tick on a 32.768 kHz
 *   crystal. Values 1 and 2 are not allowed by the hardware.
 * - Two interrupt sources: an alarm interrupt that fires when the counter
 *   matches a programmed value, and an increment interrupt that fires on every
 *   prescaler roll-over (i.e. on every tick of the counter).
 * - The status register tells you which event is pending. Reading it also
 *   clears the flags, so polling and interrupt mode cannot be mixed.
 *
 * Typical use cases:
 * - Periodic wake-ups for low-power applications
 * - Coarse timekeeping (counts seconds for over 136 years before rolling over)
 * - One-shot delayed actions via the alarm
 *
 * In this template:
 * - The counter is clocked from the prescaler at 1 Hz (RTPRES = 0x8000).
 * - An alarm is armed at counter value 5, so the alarm fires 5 seconds after
 *   the timer is enabled.
 * - Both interrupt sources are turned on: the increment interrupt fires on
 *   every tick, and the alarm interrupt fires once when the counter hits 5.
 * - The user callback is registered. The caller is responsible for enabling
 *   the RTT NVIC line.
 ******************************************************************************/
#include "plib_rtt.h"
#include <pic32c.h>
#include <stdint.h>
#include <stdbool.h>
 
volatile bool     rtt_alarm_triggered     = false;
volatile bool     rtt_increment_triggered = false;
volatile uint32_t rtt_increment_count     = 0U;
 
static void RTT_EventCallback(RTT_INT_MASK int_cause)
{
    if ((int_cause & RTT_SR_ALMS_Msk) != 0U)
    {
        rtt_alarm_triggered = true;
    }
    if ((int_cause & RTT_SR_RTTINC_Msk) != 0U)
    {
        rtt_increment_triggered = true;
        rtt_increment_count++;
    }
}
 
int32_t configure_rtt(void)
{
    const uint16_t prescaler_1hz    = 0x8000U;   /* 32768 / 32768 = 1 Hz tick */
    const uint32_t alarm_at_5_ticks = 5U;        /* fire 5 s after enable     */
 
    /* Drive the 32-bit counter from the prescaled slow clock and divide by 32768 to produce a 1 Hz tick. */
    (void)RTT_SelectClockSource(0U);
    (void)RTT_SetPrescaler(prescaler_1hz);
 
    /* Arm the alarm. The alarm fires once when the counter reaches this
     * value; the counter keeps running afterwards. */
    (void)RTT_SetAlarm(alarm_at_5_ticks);
 
    /* Hand the callback to the PLIB before enabling interrupts. */
    RTT_SetCallbackHandler(&RTT_EventCallback);
 
    /* Turn on both interrupt sources. The increment interrupt fires on every
     * tick of the counter; the alarm interrupt fires once at counter == 5. */
    RTT_EnableInterrupt(RTT_MR_ALMIEN_Msk | RTT_MR_RTTINCIEN_Msk);
 
    /* Start the counter. */
    RTT_Enable();
 
    return 0;
}

Typedef Documentation

RTT_CALLBACK

typedef void(* RTT_CALLBACK) (RTT_INT_MASK int_cause)

RTT callback function type.

Parameters

int_cause

Interrupt cause mask asserted at the time of the interrupt.

RTT_CLOCK_SOURCE

RTT_CLOCK_SOURCE

RTT counter clock source selection type.

RTT_INT_MASK

RTT_INT_MASK

RTT interrupt source mask type.

Function Documentation

RTT_Disable()

void RTT_Disable

(

void

)

Stops the RTT counter and removes its dynamic power consumption.

Returns

None

RTT_DisableInterrupt()

void RTT_DisableInterrupt

(

RTT_INT_MASK

interrupt_mask

)

Turns off one or more RTT interrupt sources.

Parameters

interrupt_mask

Bitmask of interrupts to turn off (alarm and/or increment).

Returns

None

RTT_Enable()

void RTT_Enable

(

void

)

Starts the RTT counter so it begins (or resumes) counting.

Returns

None

RTT_EnableInterrupt()

void RTT_EnableInterrupt

(

RTT_INT_MASK

interrupt_mask

)

Turns on one or more RTT interrupt sources.

Parameters

interrupt_mask

Bitmask of interrupts to turn on (alarm and/or increment).

Returns

None

RTT_GetStatus()

RTT_INT_MASK RTT_GetStatus

(

void

)

Reads the pending status flags and clears them in one step. Intended for polling. Do not mix with interrupt mode: this read clears the very flags the interrupt handler would otherwise see.

Returns

Bitmask of flags that were pending (alarm and/or increment).

RTT_GetTickFrequency()

uint32_t RTT_GetTickFrequency

(

void

)

Returns the rate at which the counter increments, in Hz.

Returns

Tick frequency in Hz (1 when running on the RTC 1 Hz source).

RTT_GetTimerValue()

uint32_t RTT_GetTimerValue

(

void

)

Reads the current 32-bit counter value. The counter runs on a different clock than the CPU, so this function reads it twice and returns a stable value.

Returns

Current counter value.

RTT_RestartTimer()

void RTT_RestartTimer

(

void

)

Restarts the RTT counter from zero and reloads the prescaler.

Returns

None

RTT_SelectClockSource()

bool RTT_SelectClockSource

(

RTT_CLOCK_SOURCE

source

)

Chooses what drives the 32-bit counter.

Note

The new clock source does not take effect until the clock divider is reloaded. Call RTT_RestartTimer() after this function for the change to apply (this also resets the counter to zero).

Parameters

source

0 = prescaled slow clock; 1 = the RTC's calibrated 1 Hz output.

Returns

true on success; false if source is not 0 or 1.

RTT_SetAlarm()

bool RTT_SetAlarm

(

uint32_t

alarm

)

Sets the value the counter is compared against to fire an alarm. The alarm interrupt must be turned off before calling this function.

Parameters

alarm

Counter value at which the alarm event is generated.

Returns

true on success; false if the alarm interrupt is still enabled.

RTT_SetCallbackHandler()

void RTT_SetCallbackHandler

(

RTT_CALLBACK

callback

)

Registers a function to be called from the RTT interrupt handler.

Parameters

callback

Pointer to the callback. Pass NULL to unregister.

Returns

None

RTT_SetPrescaler()

bool RTT_SetPrescaler

(

uint16_t

prescaler

)

Sets the prescaler value that divides the RTT source clock. The values 1 and 2 are not allowed by the hardware; pass 0 to get a divide ratio of 65536 (2^16). The increment interrupt must be turned off before calling this function.

Note

The new prescaler does not take effect until the clock divider is reloaded. Call RTT_RestartTimer() after this function for the change to apply (this also resets the counter to zero).

Parameters

prescaler

Prescaler value (0, or any value in the range 3..0xFFFF).

Returns

true on success; false if the value is invalid or the increment interrupt is still enabled.

Variable Documentation

rtt_callback

RTT_CALLBACK RTT_OBJECT::rtt_callback

Callback function pointer for RTT interrupts.

rtt_int_cause

RTT_INT_MASK RTT_OBJECT::rtt_int_cause

Interrupt cause mask for the last RTT interrupt.