System Clock Management

Logicrom provide system clock management using a time library with support for multiple time sources to sync system clock. Each time source has a priority predefined by the library.

Available time sources based on priority:

Network service provider (lowest priority)
NTP Service (available when enabled)
GPS Time (highest priority, available when gps library is used)

A custom time source can also be added using time source API.

API Reference

Header File

Source: include/libtime.h

#include <libtime.h>

Functions

int clock_src_register(const struct clocksrc_t *src)

Register clock sync source, clock is considered invalid by default

Parameters:: src – [in] Clock source structure pointer clocksrc_t
Returns:: 0 on success, negative value on error

int clock_src_setvalid(const char *name, int status)

Set clock source as valid, after clock source is marked valid system will call clocksrc_t::sync_cb after 30s.

Parameters:

name – [in] Clock source name
status – [in] 1 for valid, 0 for invalid

Returns:

0 on success, negative on error

int clock_src_getvalid(const char *name)

Get clock source valid status

Parameters:: name – [in] Clock source name
Returns:: returns 1 if valid, 0 if not valid

const char *clock_getsourcename(void)

Get currently used clock source name for system clock synchronization

Returns:: returns clock source name

int clock_get_syncstatus(void)

Get system clock sync status

Returns:: returns clkstatus_e

int clock_set_ntpserver(const char *server)

Set ntp server address, default is “service.logicrom.com”

Parameters:: server – [in] NTP server domain or IP
Returns:: return 0 on success, negative on error

const char *clock_get_ntpserver(void)

Get currently configured NTP server address

Returns:: returns NTP server address

int clock_set_mode(int mode)

Set clock synchronization mode

Parameters:: mode – [in] Clock mode clkmode_e
Returns:: 0 on success, negative on failure

int clock_get_mode(void)

Get current clock synchronization mode

Returns:: returns clockmode_e

int clock_sync(struct clocktm_t *timeval)

Update system clock, this function can be called from clock source sync callback to update system time.

Parameters:: timeval – [in] Time structure with current time information
Returns:: return 0 on success, negative on failure

Structures

struct clocksrc_t

Clock Source Structure

Public Members

const char *name: Clock Source name

int prio: Clock source priority clockprio_e

int sync_duration: Clock sync duration in seconds

int (*sync_cb)(void): Clock source sync callback function

struct clocktm_t

Time structure for sync

Public Members

int year: Year from 0

int month: Month 1 to 12

int day: Day 1 to 31

int hour: Hour 0 to 23

int minute: Minute 0 to 59

int second: Second 0 to 59

int reserved: reserved must be 0

Macros

CLKSYNC_SECONDS(x)

CLKSYNC_MINUTE(x)

Enumerations

enum clkstatus_e

Clock status

Values:

enumerator CLK_STATUS_NOTSYNCED: System clock not synced

enumerator CLK_STATUS_SYNCED: System clock synced

enum clkprio_e

Clock Source priority, for multiple clock sources, highest priority source is selected for sync

Following are the library provided clock sources and their priorities:

Network Provider Clock : Low Priority

NTP : Medium Priority

GPS : High Priority

Values:

enumerator CLK_SRC_PRIO_VLOW: Priority very low

enumerator CLK_SRC_PRIO_LOW: Priority low

enumerator CLK_SRC_PRIO_MED: Priority medium

enumerator CLK_SRC_PRIO_HIGH: Priority high

enumerator CLK_SRC_PRIO_VHIGH: Priority Very High

enum clkmode_e

Clock synchronization mode select

Values:

enumerator CLOCK_MODE_AUTO: Auto Sync

enumerator CLOCK_MODE_MANUAL: Manual Sync