Update README.md

diff --git a/README.md b/README.md
index f2b374c1e1304545d18908551b5b389f7381c0d0..11e50f4f33338b7e821566548301f463a9db494e 100644 (file)
--- a/README.md
+++ b/README.md
@@ -2,28 +2,28 @@
 Not Quite a PTP Daemon, `nqptp` monitors PTP traffic.
 
 # What is nqptp for?
-Briefly, `nqptp` monitors the times of any PTP clocks -- up to 32 -- it sees on port 319/320. It maintains a record for each clock, identified by its Clock ID and IP. This information is provided via a Posix shared memory interface at `/nqptp` . Here are details of the interface:
+Briefly, `nqptp` monitors the times of any [PTP](https://en.wikipedia.org/wiki/Precision_Time_Protocol) clocks -- up to 32 -- it sees on port 319/320. It maintains a record for each clock, identified by its Clock ID and IP. This information is provided via a Posix shared memory interface at `/nqptp`. Here are details of the interface:
 ```c
 struct clock_source {
-  char ip[64]; // 64 is nicely aligned and bigger than INET6_ADDRSTRLEN (46)
+  char ip[64];                           // the IP the clock information is coming from
   uint64_t clock_id;
   uint64_t reserved;
-  uint64_t source_time;                 // the time at the source at
-  uint64_t local_time;                  // the local time when the source time is valid
+  uint64_t source_time;                 // the time at the source
+  uint64_t local_time;                  // the local time for which when the source time is valid
   uint64_t local_to_source_time_offset; // add this to the local time to get source time
   int flags;                            // not used yet
-  int valid;                            // this entry is valid
+  int valid;                            // true if this entry is valid
 };
 
 struct shm_structure {
   pthread_mutex_t shm_mutex;    // for safely accessing the structure
-  uint16_t size_of_clock_array; // check this is equal to MAX_SHARED_CLOCKS
-  uint16_t version;             // check this is equal to NQPTP_SHM_STRUCTURES_VERSION
+  uint16_t size_of_clock_array; // should contain the value MAX_SHARED_CLOCKS
+  uint16_t version;
   uint32_t flags;
   struct clock_source clocks[MAX_SHARED_CLOCKS];
 };
 ```
-Upon installation, a unix group called `nqptp` is created. Members of that group will have write access to this shared memory and so can use the `shm_mutex` for safe access to the information. Be aware that while your program has the lock, it can halt `nqptp`, so keep any activity while you have the lock very short and very simple, e.g. making a copy of it to local memory. 
+A unix group called `nqptp` is created by the `make install` step. Members of this group have write access to the shared memory interface and can therefore use the `shm_mutex` for safe access to the information. Be aware that while your program has the lock, it can halt `nqptp`, so keep any activity while you have the lock very short and very simple, e.g. copying it to local memory. 
 
 # Installation
 ```
@@ -35,6 +35,8 @@ $ make
 The `make install` creates the `nqptp` group and installs a `systemd` startup script. You should enable it and start it in the normal way. Note that `nqptp` must run in `root` mode to be able to access ports 319 and 320.
 
 # Notes
+The `source_time` and `local_to_source_time_offset` values are averaged over up to 480 samples. Since samples should be make at the rate of eight per second, this means that the values are averaged over the previous minute.
+
 Since `nqptp` uses ports 319 and 320, it can not coexist with any other user of those ports, such as full PTP service daemons.
 
 # Known Issues