nqptp-shm-structures.h

   1 /*
   2  * This file is part of the nqptp distribution (https://github.com/mikebrady/nqptp).
   3  * Copyright (c) 2021--2023 Mike Brady.
   4  *
   5  * This program is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation, version 2.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  12  * General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Commercial licensing is also available.
  18  */
  19
  20 #ifndef NQPTP_SHM_STRUCTURES_H
  21 #define NQPTP_SHM_STRUCTURES_H
  22
  23 #define NQPTP_INTERFACE_NAME "/nqptp"
  24
  25 #define NQPTP_SHM_STRUCTURES_VERSION 10
  26 #define NQPTP_CONTROL_PORT 9000
  27
  28 // The control port expects a UDP packet with the first character being a command letter
  29 // and the rest being any arguments, the whole not to exceed 4096 characters.
  30 // The "T" command,  must followed by nothing or by
  31 // a space and a space-delimited list of IPv4 or IPv6 numbers.
  32 // The IPs, if provided, will become the new list of timing peers, replacing any
  33 // previous list. The first IP number is the clock that NQPTP will listen to.
  34 // The remaining IP address are the addresses of all the timing peers. The timing peers
  35 // are not used in this version of NQPTP.
  36 // If no timing list is provided, the existing timing list is deleted.
  37 // The "B" command is a message that the client -- which generates the clock --
  38 // is about to start playing.
  39 // NQPTP uses it to determine that the clock is active and will not sleep.
  40 // The "E" command signifies that the client has stopped playing and that
  41 // the clock may shortly sleep.
  42 // The "P" command signifies that SPS has paused play (buffered audio only).
  43 // The clock seems to stay running in this state.
  44
  45 // When the clock is active, it is assumed that any decreases in the offset
  46 // between the local and remote clocks are due to delays in the network.
  47 // NQPTP smooths the offset by clamping any decreases to a small value.
  48 // In this way, it can follow clock drift but ignore network delays.
  49
  50 // When the clock is inactive, it can stop running. This causes the offset to decrease.
  51 // NQPTP clock smoothing would treat this as a network delay, causing true sync to be lost.
  52 // To avoid this, when the clock goes from inactive to active,
  53 // NQPTP resets clock smoothing to the new offset.
  54
  55 #include <inttypes.h>
  56 #include <pthread.h>
  57
  58 typedef struct {
  59   uint64_t master_clock_id;             // the current master clock
  60   uint64_t local_time;                  // the time when the offset was calculated
  61   uint64_t local_to_master_time_offset; // add this to the local time to get master clock time
  62   uint64_t master_clock_start_time;     // this is when the master clock became master
  63 } shm_structure_set;
  64
  65 // The actual interface comprises a shared memory region of type struct shm_structure.
  66 // This comprises two records of type shm_structure_set.
  67 // The secondary record is written strictly after all writes to the main record are
  68 // complete. This is ensured using the __sync_synchronize() construct.
  69 // The reader should ensure that both copies match for a read to be valid.
  70 // For safety, the secondary record should be read strictly after the first.
  71
  72 struct shm_structure {
  73   uint16_t version; // check this is equal to NQPTP_SHM_STRUCTURES_VERSION
  74   shm_structure_set main;
  75   shm_structure_set secondary;
  76 };
  77
  78 #endif