reactor-c
C Runtime for Lingua Franca
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Functions
clock-sync.h File Reference
#include "low_level_platform.h"

Go to the source code of this file.

Data Structures

struct  socket_stat_t
 

Macros

#define LF_CLOCK_SYNC_OFF   1
 
#define LF_CLOCK_SYNC_INIT   2
 
#define LF_CLOCK_SYNC_ON   3
 
#define LF_CLOCK_SYNC   LF_CLOCK_SYNC_INIT
 
#define _LF_CLOCK_SYNC_EXCHANGES_PER_INTERVAL   10
 
#define _LF_CLOCK_SYNC_ATTENUATION   10
 
#define _LF_CLOCK_SYNC_COLLECT_STATS   true
 
#define CLOCK_SYNC_GUARD_BAND   USEC(100)
 

Typedefs

typedef struct socket_stat_t socket_stat_t
 

Functions

void update_socket_stat (struct socket_stat_t *socket_stat, long long network_delay, long long clock_synchronization_error)
 
struct lf_stat_ll calculate_socket_stat (struct socket_stat_t *socket_stat)
 
void reset_socket_stat (struct socket_stat_t *socket_stat)
 
uint16_t setup_clock_synchronization_with_rti (void)
 
void synchronize_initial_physical_clock_with_rti (int *rti_socket_TCP)
 
int handle_T1_clock_sync_message (unsigned char *buffer, int socket, instant_t t2)
 
void handle_T4_clock_sync_message (unsigned char *buffer, int socket, instant_t r4)
 
void * listen_to_rti_UDP_thread (void *args)
 
int create_clock_sync_thread (lf_thread_t *thread_id)
 
void clock_sync_add_offset (instant_t *t)
 Add the current clock synchronization offset to a specified timestamp.
 
void clock_sync_subtract_offset (instant_t *t)
 Subtract the clock synchronization offset from a timestamp.
 
void clock_sync_set_constant_bias (interval_t offset)
 

Detailed Description

Author
Edward A. Lee (eal@b.nosp@m.erke.nosp@m.ley.e.nosp@m.du)
Soroush Bateni (sorou.nosp@m.sh@u.nosp@m.tdall.nosp@m.as.e.nosp@m.du)

LICENSE

Copyright (c) 2020-21, The University of California at Berkeley.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

DESCRIPTION

Utility functions for clock synchronization.

Macro Definition Documentation

◆ _LF_CLOCK_SYNC_ATTENUATION

#define _LF_CLOCK_SYNC_ATTENUATION   10

Runtime clock offset updates will be divided by this number.

◆ _LF_CLOCK_SYNC_COLLECT_STATS

#define _LF_CLOCK_SYNC_COLLECT_STATS   true

By default, collect statistics on clock synchronization.

◆ _LF_CLOCK_SYNC_EXCHANGES_PER_INTERVAL

#define _LF_CLOCK_SYNC_EXCHANGES_PER_INTERVAL   10

Number of required clock sync T4 messages per synchronization interval. The offset to the clock will not be adjusted until this number of T4 clock synchronization messages have been received.

◆ CLOCK_SYNC_GUARD_BAND

#define CLOCK_SYNC_GUARD_BAND   USEC(100)

Define a guard band to filter clock synchronization messages based on discrepancies in the network delay.

See also
Coded probes in Geng, Yilong, et al. "Exploiting a natural network effect for scalable, fine-grained clock synchronization."

◆ LF_CLOCK_SYNC

#define LF_CLOCK_SYNC   LF_CLOCK_SYNC_INIT

◆ LF_CLOCK_SYNC_INIT

#define LF_CLOCK_SYNC_INIT   2

◆ LF_CLOCK_SYNC_OFF

#define LF_CLOCK_SYNC_OFF   1

◆ LF_CLOCK_SYNC_ON

#define LF_CLOCK_SYNC_ON   3

Typedef Documentation

◆ socket_stat_t

typedef struct socket_stat_t socket_stat_t

Statistics for a given socket. The RTI initiates a clock synchronization action by sending its current physical time T1 to a federate. The federate records the local time T2 that it receives T1. It sends a reply at local time T3, which the RTI receives at its time T4. The RTI sends back T4. The round trip delay on the socket is therefore estimated as: (T4 - T1) - (T3 - T2).

Function Documentation

◆ calculate_socket_stat()

struct lf_stat_ll calculate_socket_stat ( struct socket_stat_t * socket_stat)

Calculate statistics of the socket. The releavent information is returned as a lf_stat_ll struct.

Parameters
socket_statThe socket_stat_t struct that keeps track of stats for a given connection
Returns
An lf_stat_ll struct with relevant information.

◆ clock_sync_add_offset()

void clock_sync_add_offset ( instant_t * t)

Add the current clock synchronization offset to a specified timestamp.

Parameters
tPointer to the timestamp to which to add the offset.

◆ clock_sync_set_constant_bias()

void clock_sync_set_constant_bias ( interval_t offset)

Set a fixed offset to the physical clock. After calling this, the value returned by lf_time_physical(void) and get_elpased_physical_time(void) will have this specified offset added to what it would have returned before the call.

◆ clock_sync_subtract_offset()

void clock_sync_subtract_offset ( instant_t * t)

Subtract the clock synchronization offset from a timestamp.

Parameters
tThe timestamp from which to subtract the current clock sync offset.

◆ create_clock_sync_thread()

int create_clock_sync_thread ( lf_thread_t * thread_id)

Create the thread responsible for handling clock synchronization with the RTI if (runtime) clock synchronization is on. Otherwise, do nothing an return 0.

Returns
On success, returns 0; On error, it returns an error number.

◆ handle_T1_clock_sync_message()

int handle_T1_clock_sync_message ( unsigned char * buffer,
int socket,
instant_t t2 )

Handle a clock synchroninzation message T1 coming from the RTI. T1 is the first message in a PTP exchange. This replies to the RTI with a T3 message. It also measures the time it takes between when the method is called and the reply has been sent.

Parameters
bufferThe buffer containing the message, including the message type.
socketThe socket (either _lf_rti_socket_TCP or _lf_rti_socket_UDP).
t2The physical time at which the T1 message was received.
Returns
0 if T3 reply is successfully sent, -1 otherwise.

◆ handle_T4_clock_sync_message()

void handle_T4_clock_sync_message ( unsigned char * buffer,
int socket,
instant_t r4 )

Handle a clock synchronization message T4 coming from the RTI. If the socket is _lf_rti_socket_TCP, then assume we are in the initial clock synchronization phase and set the clock offset based on the estimated clock synchronization error. Otherwise, if the socket is _lf_rti_socket_UDP, then this looks also for a subsequent "coded probe" message on the socket. If the delay between the T4 and the coded probe message is not as expected, then reject this clock synchronization round. If it is not rejected, then make an adjustment to the clock offset based on the estimated error. This function does not acquire the socket_mutex lock. The caller should acquire it unless it is sure there is only one thread running.

Parameters
bufferThe buffer containing the message, including the message type.
socketThe socket (either _lf_rti_socket_TCP or _lf_rti_socket_UDP).
r4The physical time at which this T4 message was received.

◆ listen_to_rti_UDP_thread()

void * listen_to_rti_UDP_thread ( void * args)

Thread that listens for UDP inputs from the RTI.

◆ reset_socket_stat()

void reset_socket_stat ( struct socket_stat_t * socket_stat)

Reset statistics on the socket.

Parameters
socket_statThe socket_stat_t struct that keeps track of stats for a given connection

◆ setup_clock_synchronization_with_rti()

uint16_t setup_clock_synchronization_with_rti ( void )

Setup necessary functionalities to synchronize clock with the RTI.

Returns
port number to be sent to the RTI

◆ synchronize_initial_physical_clock_with_rti()

void synchronize_initial_physical_clock_with_rti ( int * rti_socket_TCP)

Synchronize the initial physical clock with the RTI. A call to this function is inserted into the startup sequence by the code generator if initial clock synchronization is required.

This is a blocking function that expects to read a MSG_TYPE_CLOCK_SYNC_T1 from the RTI TCP socket. It will then follow the PTP protocol to synchronize the local physical clock with the RTI. Failing to complete this protocol is treated as a catastrophic error that causes the federate to exit.

Parameters
rti_socket_TCPPointer to the RTI's socket

◆ update_socket_stat()

void update_socket_stat ( struct socket_stat_t * socket_stat,
long long network_delay,
long long clock_synchronization_error )

Update statistics on the socket based on the newly calculated network delay and clock synchronization error

Parameters
socket_statThe socket_stat_t struct that keeps track of stats for a given connection
network_round_trip_delayThe newly calculated round trip delay to the remote federate/RTI
clock_synchronization_errorThe newly calculated clock synchronization error relative to the remote federate/RTI