T32CZ20_rtc.h

Go to the documentation of this file.

 
 
 
#ifndef T32CZ20_RTC_H_
#define T32CZ20_RTC_H_
 
#include "tr_hal_platform.h"
 
 
 
 
#define TR_HAL_RTC_YEAR_MINIMUM 2000
#define TR_HAL_RTC_YEAR_MAXIMUM 2099
 
#define TR_HAL_RTC_MONTH_MINIMUM  1
#define TR_HAL_RTC_MONTH_MAXIMUM 12
 
#define TR_HAL_RTC_DAY_MINIMUM  1
#define TR_HAL_RTC_DAY_MAXIMUM 31
 
#define TR_HAL_RTC_SHORT_MONTH_DAY_MAXIMUM   30
#define TR_HAL_RTC_FEB_DAY_MAXIMUM           28
#define TR_HAL_RTC_FEB_LEAP_YEAR_DAY_MAXIMUM 29
 
#define TR_HAL_RTC_HOUR_MINIMUM  0
#define TR_HAL_RTC_HOUR_MAXIMUM 23
 
#define TR_HAL_RTC_MINUTE_MINIMUM  0
#define TR_HAL_RTC_MINUTE_MAXIMUM 59
 
#define TR_HAL_RTC_SECOND_MINIMUM  0
#define TR_HAL_RTC_SECOND_MAXIMUM 59
 
#define TR_HAL_RTC_MILLISECOND_MINIMUM   0
#define TR_HAL_RTC_MILLISECOND_MAXIMUM 999
 
 
#define TR_HAL_MONTH_JANUARY    1
#define TR_HAL_MONTH_FEBRUARY   2
#define TR_HAL_MONTH_MARCH      3
#define TR_HAL_MONTH_APRIL      4
#define TR_HAL_MONTH_MAY        5
#define TR_HAL_MONTH_JUNE       6
#define TR_HAL_MONTH_JULY       7
#define TR_HAL_MONTH_AUGUST     8
#define TR_HAL_MONTH_SEPTEMBER  9
#define TR_HAL_MONTH_OCTOBER   10
#define TR_HAL_MONTH_NOVEMBER  11
#define TR_HAL_MONTH_DECEMBER  12
 
 
 
// date
typedef struct
{
    // 4 digit year and must be >= 2000
    uint16_t years;
    
    // 1-12
    uint8_t  months;
    
    // 1-31, depends on month
    uint8_t  days;
    
} tr_hal_rtc_date;
 
// time
typedef struct
{
    // range 0-23
    uint8_t hours;
    
    // range 0-59
    uint8_t minutes;
    
    // range 0-59
    uint8_t seconds;
    
    // range 0-999
    uint16_t milliseconds;
 
} tr_hal_rtc_time;
 
// date and time
typedef struct
{
    tr_hal_rtc_date date;
    tr_hal_rtc_time time;
 
} tr_hal_rtc_date_time;
 
 
#define TR_HAL_INVALID_DATE_TIME_VALUE 255
 
 
typedef enum
{
    TR_HAL_RTC_TIME_UNIT_MILLISECONDS = 1,
    TR_HAL_RTC_TIME_UNIT_SECONDS      = 2,
    TR_HAL_RTC_TIME_UNIT_MINUTES      = 3,
    TR_HAL_RTC_TIME_UNIT_HOURS        = 4,
    TR_HAL_RTC_TIME_UNIT_DAYS         = 5,
    TR_HAL_RTC_TIME_UNIT_MONTHS       = 6,
    TR_HAL_RTC_TIME_UNIT_YEARS        = 7,
    TR_HAL_RTC_TIME_UNIT_INVALID      = 255,
    
} tr_hal_rtc_time_unit_t;
 
 
typedef enum
{
    TR_HAL_EVENT_TRIGGER_OFF               = 0,
    TR_HAL_EVENT_TRIGGER_ON_UNIT_CHANGE    = 1,
    TR_HAL_EVENT_TRIGGER_ON_SPECIFIC_VALUE = 2,
    TR_HAL_EVENT_TRIGGER_INVALID           = 255,
    
} tr_hal_rtc_event_trigger_t;
 
 
#ifdef RTC_SECURE_EN
    #define CHIP_MEMORY_MAP_RTC_BASE     (0x50004000UL)
#else
    #define CHIP_MEMORY_MAP_RTC_BASE     (0x40004000UL)
#endif // RTC_SECURE_EN
 
 
typedef struct
{
    // register values for seconds, minutes, hours, days, months, years
    // note that these must be written and read in BCD
    __IO  uint32_t   seconds_value;         // 0x00
    __IO  uint32_t   minutes_value;         // 0x04
    __IO  uint32_t   hours_value;           // 0x08
    __IO  uint32_t   days_value;            // 0x0C
    __IO  uint32_t   months_value;          // 0x10
    __IO  uint32_t   years_value;           // 0x14
 
    // used for testing (can speed up rate) and to clear counters and values 
    __IO  uint32_t   control;               // 0x18
    
    // Clock Divisor for generating a 1Hz enable pulse to the seconds counter
    __IO  uint32_t   clock_divisor;         // 0x1C
 
    // what trigger to use for each time unit: off, on_change, on_value, combo
    // these registers also hold the trigger value if in on_value mode
    __IO  uint32_t   seconds_event_trigger; // 0x20
    __IO  uint32_t   minutes_event_trigger; // 0x24
    __IO  uint32_t   hours_event_trigger;   // 0x28
    __IO  uint32_t   days_event_trigger;    // 0x2C
    __IO  uint32_t   months_event_trigger;  // 0x30
    __IO  uint32_t   years_event_trigger;   // 0x34
 
    // interrupts
    __IO  uint32_t   interrupt_enable;      // 0x38
    __IO  uint32_t   interrupt_status;      // 0x3C
    __IO  uint32_t   interrupt_clear;       // 0x40
    
    // once clock divisior, event trigger values, or time values have been updated,
    // this register allows them to be "loaded" == become active
    __IO  uint32_t   load;                  // 0x44
    
    // NEW in CZ20
    __IO  uint32_t   milliseconds_value;          // 0x48
    __IO  uint32_t   milliseconds_event_trigger;  // 0x4C
    
 
} RTC_REGISTERS_T;
 
 
// *****************************************************************
// this enum helps when dealing with the CONTROL REGISTER (0x18)
#define TR_HAL_RTC_CONTROL_REG_ENABLE_BIT 0x100
 
typedef enum
{
    TR_HAL_RTC_SPEEDUP_NONE    = 0x01,
    TR_HAL_RTC_SPEEDUP_MINUTES = 0x02,
    TR_HAL_RTC_SPEEDUP_HOURS   = 0x04,
    TR_HAL_RTC_SPEEDUP_DAYS    = 0x08,
    TR_HAL_RTC_SPEEDUP_MONTHS  = 0x10,
    TR_HAL_RTC_SPEEDUP_YEARS   = 0x20,
    
} tr_hal_rtc_speedup_unit_t;
 
 
// *****************************************************************
// these defines help when dealing with the CLOCK DIVISIOR REGISTER (0x1C)
// 32.768 KHz = 20.C49C = 0x20C49C = 2147484
//#define TR_HAL_DEFAULT_CLOCK_DIVISOR 0x20C49C
// tuned for my board
#define TR_HAL_DEFAULT_CLOCK_DIVISOR 2110000
 
 
// *****************************************************************
// these defines help when dealing with the EVENT TRIGGER REGISTERs (0x20 - 0x34)
#define TR_HAL_REG_SETTING_EVENT_OFF       0x0000
#define TR_HAL_REG_SETTING_EVENT_ON_CHANGE 0x0100
#define TR_HAL_REG_SETTING_EVENT_ON_VALUE  0x0000
#define TR_HAL_REG_SETTING_COMBO_EVENT     0x0200
 
 
// *****************************************************************
// these defines help when dealing with the INTERRUPT ENABLE REGISTER (0x38),
// the INTERRUPT STATUS REGISTER (0x3C) and the INTERRUPT CLEAR REGISTER (0x40)
#define TR_HAL_RTC_INTERRUPT_NONE             0x00
#define TR_HAL_RTC_INTERRUPT_SECONDS          0x01
#define TR_HAL_RTC_INTERRUPT_MINUTES          0x02
#define TR_HAL_RTC_INTERRUPT_HOURS            0x04
#define TR_HAL_RTC_INTERRUPT_DAYS             0x08
#define TR_HAL_RTC_INTERRUPT_MONTHS           0x10
#define TR_HAL_RTC_INTERRUPT_YEARS            0x20
#define TR_HAL_RTC_INTERRUPT_COMBINED_EVENT   0x40
#define TR_HAL_RTC_INTERRUPT_MILLISECONDS     0x80
#define TR_HAL_RTC_INTERRUPT_ALL              0xFF
 
 
// *****************************************************************
// these defines help when dealing with the LOAD REGISTER (0x44)
#define TR_HAL_RTC_UPDATE_TIME_VALUES   0x01
#define TR_HAL_RTC_UPDATE_EVENT_TRIGGER 0x02
#define TR_HAL_RTC_UPDATE_CLOCK_DIVISOR 0x04
 
 
// *****************************************************************
// this orients the RTC_REGISTERS struct with the correct address
// so referencing a field will now read/write the correct RTC
// register chip address 
#define RTC_REGISTERS  ((RTC_REGISTERS_T *) CHIP_MEMORY_MAP_RTC_BASE)
 
 
RTC_REGISTERS_T* tr_hal_rtc_get_register_address(void);
 
 
typedef void (*tr_hal_rtc_event_callback_t) (uint32_t event_bitmask,
                                             tr_hal_rtc_date_time current_date_time);
 
 
#define TR_HAL_RTC_EVENT_TRIGGERED_SECONDS          0x00000001
#define TR_HAL_RTC_EVENT_TRIGGERED_MINUTES          0x00000002
#define TR_HAL_RTC_EVENT_TRIGGERED_HOURS            0x00000004
#define TR_HAL_RTC_EVENT_TRIGGERED_DAYS             0x00000008
#define TR_HAL_RTC_EVENT_TRIGGERED_MONTHS           0x00000010
#define TR_HAL_RTC_EVENT_TRIGGERED_YEARS            0x00000020
#define TR_HAL_RTC_EVENT_TRIGGERED_COMBINED_EVENT   0x00000040
#define TR_HAL_RTC_EVENT_TRIGGERED_MILLISECONDS     0x00000080
 
 
#define TR_HAL_RTC_MILLISECOND_TRIGGER_OFF_VALUE 1001
#define TR_HAL_RTC_SECOND_TRIGGER_OFF_VALUE      62
#define TR_HAL_RTC_MINUTE_TRIGGER_OFF_VALUE      62
#define TR_HAL_RTC_HOUR_TRIGGER_OFF_VALUE        25
#define TR_HAL_RTC_DAY_TRIGGER_OFF_VALUE         32
#define TR_HAL_RTC_MONTH_TRIGGER_OFF_VALUE       0
#define TR_HAL_RTC_YEAR_TRIGGER_OFF_VALUE        0
 
 
typedef struct
{
    // **** date, time, and clock divisor ****
 
    tr_hal_rtc_date_time rtc_date_time;
 
    uint32_t clock_divisor;
 
 
    // **** event callback from HAL to App when an event happens ****
    // if the app doesn't want this, then set it to NULL
    tr_hal_rtc_event_callback_t  event_handler_fx;
 
 
    // **** chip behavior settings ****
 
    // are the chip interrupts enabled?
    bool enable_chip_interrupts;
    
    // set the INT priority
    tr_hal_int_pri_t interrupt_priority;
 
    // when the device is sleeping, we can choose to DISABLE interrupts, 
    // or leave them enabled which would allow the device to wake on
    // an interrupt from this peripheral
    bool wake_on_interrupt;
 
 
    // **** time unit events ****
    
    tr_hal_rtc_event_trigger_t seconds_event_trigger;
    uint8_t                    seconds_trigger_value;
    tr_hal_rtc_event_trigger_t minutes_event_trigger;
    uint8_t                    minutes_trigger_value;
    tr_hal_rtc_event_trigger_t hours_event_trigger;
    uint8_t                    hours_trigger_value;
    tr_hal_rtc_event_trigger_t days_event_trigger;
    uint8_t                    days_trigger_value;
    tr_hal_rtc_event_trigger_t months_event_trigger;
    uint8_t                    months_trigger_value;
    tr_hal_rtc_event_trigger_t years_event_trigger;
    uint16_t                   years_trigger_value;
    tr_hal_rtc_event_trigger_t milliseconds_event_trigger;
    uint16_t                   milliseconds_trigger_value;
 
    // **** combo event ****
 
    bool                      combo_event_enabled;
    tr_hal_rtc_date_time      combo_event_trigger_date_time;
 
} tr_hal_rtc_settings_t;
 
 
#define DEFAULT_RTC_CONFIG                                  \
    {                                                       \
        .rtc_date_time.time.milliseconds =  0,              \
        .rtc_date_time.time.seconds =  0,                   \
        .rtc_date_time.time.minutes =  0,                   \
        .rtc_date_time.time.hours =  0,                     \
        .rtc_date_time.date.days =  1,                      \
        .rtc_date_time.date.months =  1,                    \
        .rtc_date_time.date.years =  2025,                  \
        .clock_divisor =  TR_HAL_DEFAULT_CLOCK_DIVISOR,     \
        .event_handler_fx =  NULL,                          \
        .enable_chip_interrupts =  true,                    \
        .interrupt_priority =  TR_HAL_INTERRUPT_PRIORITY_5, \
        .wake_on_interrupt =  false,                        \
        .seconds_event_trigger = TR_HAL_EVENT_TRIGGER_OFF,  \
        .minutes_event_trigger = TR_HAL_EVENT_TRIGGER_OFF,  \
        .hours_event_trigger   = TR_HAL_EVENT_TRIGGER_OFF,  \
        .days_event_trigger    = TR_HAL_EVENT_TRIGGER_OFF,  \
        .months_event_trigger  = TR_HAL_EVENT_TRIGGER_OFF,  \
        .years_event_trigger   = TR_HAL_EVENT_TRIGGER_OFF,  \
        .milliseconds_event_trigger = TR_HAL_EVENT_TRIGGER_OFF, \
        .combo_event_enabled = false,                       \
    }
 
 
// this API causes the time unit specified to speed up to change once per second
// this is useful for testing
tr_hal_status_t tr_hal_rtc_speedup_for_testing(tr_hal_rtc_speedup_unit_t speedup_unit);
 
// expose these so they can be fully tested
uint32_t convert_bcd_to_int(uint32_t register_value);
uint32_t convert_int_to_bcd(uint32_t int_value);
 
 
 
 
#endif // T32CZ20_RTC_H_