[ntp:bk-ntp-dev-send] BitKeeper diffs

Harlan Stenn stenn at deacon.udel.edu
Wed Dec 21 20:10:48 UTC 2011


#### ChangeSet ####
2011-12-21 15:05:08-05:00, stenn at deacon.udel.edu
  Documentation updates

==== ChangeLog ====
2011-12-21 15:04:41-05:00, stenn at deacon.udel.edu +1 -0
  Include missing html/icons/sitemap.png, reported by Michael Tatarinov

--- 1.1078/ChangeLog	2011-12-21 15:01:47 -05:00
+++ 1.1079/ChangeLog	2011-12-21 15:04:41 -05:00
@@ -1,3 +1,4 @@
+* Include missing html/icons/sitemap.png, reported by Michael Tatarinov.
 * Documentation updates from Dave Mills.
 (4.2.7p241) 2011/12/18 Released by Harlan Stenn <stenn at ntp.org>
 * [Bug 2015] Overriding sys_tick should recalculate sys_precision.

==== ChangeLog ====
2011-12-21 15:01:47-05:00, stenn at deacon.udel.edu +1 -0
  Documentation updates from Dave Mills

--- 1.1077/ChangeLog	2011-12-18 17:08:51 -05:00
+++ 1.1078/ChangeLog	2011-12-21 15:01:47 -05:00
@@ -1,3 +1,4 @@
+* Documentation updates from Dave Mills.
 (4.2.7p241) 2011/12/18 Released by Harlan Stenn <stenn at ntp.org>
 * [Bug 2015] Overriding sys_tick should recalculate sys_precision.
 * [Bug 2037] Fuzzed non-interpolated clock may decrease.

==== html/icons/sitemap.png ====
2011-12-21 15:01:27-05:00, stenn at deacon.udel.edu +64 -0
  BitKeeper file /deacon/backroom/ntp-dev/html/icons/sitemap.png

Binary files /dev/null and /tmp/bk_mkDiffTarget_15574g differ

==== html/icons/sitemap.png ====
2011-12-21 15:01:27-05:00, stenn at deacon.udel.edu +0 -0

==== html/prefer.html ====
2011-12-21 15:01:40-05:00, stenn at deacon.udel.edu +3 -3
  Documentation updates from Dave Mills

--- 1.29/html/prefer.html	2011-12-11 05:55:27 -05:00
+++ 1.30/html/prefer.html	2011-12-21 15:01:40 -05:00
@@ -9,7 +9,7 @@
 <img src="pic/alice11.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html"> from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a>
 <p>Listen carefully to what I say; it is very complicated.</p>
 <p>Last update:
-  <!-- #BeginDate format:En2m -->05-Dec-2011  7:21<!-- #EndDate -->
+  <!-- #BeginDate format:En2m -->16-Dec-2011  20:58<!-- #EndDate -->
   UTC</p>
 <br clear="left">
 <h4>Related Links</h4>
@@ -29,13 +29,13 @@
 <p>This page summarizes the criteria for choosing from among the survivors of the clock cluster algorithm  a set of  contributors to the clock discipline algorithm. The criteria are very meticulous, since they have to handle many different scenarios that may be optimized for special circumstances, including some scenarios designed to support planetary and deep space missions.</p>
 <p>Recall the suite of NTP data acquisition and grooming algorithms. These algorithms proceed in five phases. Phase one discovers the available <em>sources</em> and mobilizes an association for each source found. These sources can result from explicit configuration, broadcast discovery or the pool and manycast autonomous configuration schemes. See the <a href="discover.html">Automatic Server Discovery Schemes</a> page for further information.</p>
 <p> Phase two selects the <em> candidates</em> from among the sources  by  excluding those sources showing one or more of the  errors summarized on the  <a href="select.html">Clock Select Algorithmm</a> page and to determine the <em>truechimers</em> from among the  candidates, leaving behind the <em>falsetickers</em>. A server or peer configured with the <tt>true</tt> option is declared a truechimer independent of this algorithm. Phase four uses the algorithm described on the <a href="cluster.html">Clock Cluster Algorithm</a> page to trim the statistical outliers from the  truechimers, leaving the <em>survivor list</em><em></em> as result. </p>
-<p> Phase five uses a set of algorithms and mitigation rules to   combined the survivor statistics antdiscipline the systen clock. The mitigation rules select from among the survivors a <em>system peer</em> from which a set of system statistics can be inherited and passed along to  dependent clients, if any.  The algorithms and rules are the main topic of this page. The clock offset developed from these algorithms can discipline the system clock either using the <a href="discipline.html">clock discipline algorithm</a> or enable the kernel to discipline the system clock directly, as described on the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. </p>
+<p> Phase five uses a set of algorithms and mitigation rules to   combined the survivor statistics antdiscipline the systen clock. The mitigation rules select from among the survivors a <em>system peer</em> from which a set of system statistics can be inherited and passed along to  dependent clients, if any.  The algorithms and rules are the main topic of this page. The clock offset developed from these algorithms can discipline the system clock, either using the <a href="discipline.html">clock discipline algorithm</a> or using  the kernel to discipline the system clock directly, as described on the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. </p>
 <h4 id="combine">Combine Algorithm</h4>
 <p> The clock combine algorithm uses the survivor list to produce a weighted average of both offset and jitter. Absent other considerations discussed later, the <em>combined offset</em> is used to discipline the system clock, while the <em>combined jitter</em> is augmented with other components to produce the system jitter statistic inherited by dependent clients, if any.</p>
 <p> The clock combine algorithm uses a weight factor for each survivor equal to the reciprocal of the root distance. This is normalized so that the sum of the reciprocals is equal to unity. This design  favors the survivors at the smallest root distance and thus the smallest  maximum  error.</p>
 <h4 id="clockhop">Anti-Clockhop Algorithm</h4>
 <p>The anti-clockhop algorithm is intended for cases where multiple  servers are available on a fast LAN with modern computers. Typical offset differences between servers in such cases are less than 0.5 ms. However,  changes between servers can result in unnecessary system jitter. The object of the anti-clockhop algorithm is to avoid changing  the current server unless it becomes stale or the offset differences between it and the others on the survivor list becomes substantial.</p>
-<p>To help compact this discussion, we will call the last selected server as the <em>old peer</em>, and the server at the head of the survivor list the <em>candidate peer</em>. The anti-clockhop algorithm is called immediately after the combine algorithm. First, the  survivor list produced by the clock cluster algorithm is  sorted  by increasing root distance. The algorithm then initializes the anti-clockhop threshold with the value of  <tt>mindist</tt>, by default 1 ms. </p>
+<p>To help compact this discussion, we will call the last selected server  the <em>old peer</em>, and thecurrently selected server the  <em>candidate peer</em>. The anti-clockhop algorithm is called immediately after the combine algorithm. The metric used to select the candidate peer  is formed as the root distance plus product of the stratum times the <tt>mindist</tt> variable. It is used to select the minimum  survivor on the list produced by the clock cluster algorithm. The algorithm then initializes the anti-clockhop threshold with the value of  <tt>mindist</tt>, by default 1 ms. </p>
 <p>If there was no old peer or the old and candidate peers are the same,   the candidate peer becomes the system peer. If not, the algorithm measures the difference between the offset of the old peer and the candidate peer. If the difference exceeds the anti-clockhop threshold, the candidate peer becomes the system peer and the anti-clockhop threshold is restored to its original value. If not, the old peer continues as the system peer. However, at each subsequent update, the algorithm reduces the anti-clockhop threshold by half. Should operation continue in this way, the candidate peer will eventually become the system peer.</p>
 <h4 id="peer">Peer Classification</h4>
 <p>The behavior of the various algorithms and mitigation rules involved depends on how the various synchronization sources are classified. This depends on whether the source is local or remote and if local, the type of source. The following classes are defined:</p>

==== html/select.html ====
2011-12-21 15:01:41-05:00, stenn at deacon.udel.edu +2 -2
  Documentation updates from Dave Mills

--- 1.5/html/select.html	2011-12-11 05:55:30 -05:00
+++ 1.6/html/select.html	2011-12-21 15:01:41 -05:00
@@ -10,14 +10,14 @@
 <em></em>
 <h3>Clock Select Algorithm</h3>
 <p>Last update:
-  <!-- #BeginDate format:En2m -->04-Dec-2011  14:27<!-- #EndDate -->
+  <!-- #BeginDate format:En2m -->16-Dec-2011  13:54<!-- #EndDate -->
   UTC</p>
 <hr>
 <p>The clock select algorithm determines from a set of sources , which are correct (<em>truechimers</em>) and which are not (<em>falsetickers</em>) according to a set of formal correctness assertions. The principles are based on the observation that the maximum error in determining the offset of a candidate cannot exceed one-half the roundtrip delay to the primary reference clock at the time of measurement. This must be increased by the maximum error that can accumulate since then.  The selection metric, called the <em>root  distance,</em>, is one-half the roundtrip root delay plus the root dispersion plus minor error contributions not considered here.</p>
 <p>First, a number of sanity checks is performed to sift the selectable candidate from among the source population. The sanity checks are sumarized as follows:.</p>
 <ol>
   <li>A <em>stratum error</em> occurs if (1) the source had never been synchronized or (2) the stratum of the source is below the <tt>floor</tt> option or not below the <tt>ceiling</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. The default values for these options are 0 and 15, respectively. Note that  15 is a valid stratum, but a server operating at that stratum  cannot synchronize  clients.</li>
-  <li>A <em>distance error</em> occurs for a remote source if the root distance (also known ad synchronization distance) of the source is not below the distance threshold <tt>maxdist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. The default value for this option is 1.5 s for networks including only the Earth, but this should be increased to 2.5 s for networks including the Moon.</li>
+  <li>A <em>distance error</em> occurs for a  source if the root distance (also known ad synchronization distance) of the source is not below the distance threshold <tt>maxdist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. The default value for this option is 1.5 s for networks including only the Earth, but this should be increased to 2.5 s for networks including the Moon.</li>
   <li>A <em>loop</em> <em>error</em> occurs if the source is synchronized to the client. This can occur if two peers are configured with each other in symmetric modes.</li>
   <li>An <em>unreachable</em> <em>error</em> occurs if the source is unreachable or if the <tt>server</tt> or <tt>peer</tt> command for the source includes the <tt>noselect</tt> option.</li>
 </ol>

==== html/warp.html ====
2011-12-21 15:01:41-05:00, stenn at deacon.udel.edu +6 -8
  Documentation updates from Dave Mills

--- 1.20/html/warp.html	2011-12-11 05:55:33 -05:00
+++ 1.21/html/warp.html	2011-12-21 15:01:41 -05:00
@@ -9,7 +9,7 @@
 <body>
 <h3>How NTP Works</h3>
 <p>Last update:
-  <!-- #BeginDate format:En2m -->05-Dec-2011  16:26<!-- #EndDate -->
+  <!-- #BeginDate format:En2m -->15-Dec-2011  16:30<!-- #EndDate -->
   UTC</p>
 <h4>Related Links</h4>
 <script type="text/javascript" language="javascript" src="scripts/special.txt"></script>
@@ -43,21 +43,19 @@
 <p>The  algorithm described on the <a href="filter.html">Clock Filter Algorithm</a> page  selects the    offset  and  delay samples most likely to produce accurate results. Those servers that have passed  the  sanity tests     are declared <em>selectable</em>. From the selectable population the statistics are used by the algorithm described on the <a href="select.html">Clock Select Algorithm</a> page to determine a number of <em>truechimers</em> according to correctness principles. From the truechimer population the algorithm described on the <a href="cluster.html">Clock Cluster Algorithm</a> page determines a number of <em>survivors</em> on the basis of statistical clustering principles. The algorithms described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page combine the survivor offsets, designate one of them as the <em>system peer</em> and produces the final offset used by the algorithm described on the <a href="discipline.html">Cloc
 k Discipline Algorithm</a> page to adjust the system clock time and frequency. The clock offset and frequency, are recorded by the <tt>loopstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. For additional details about these algorithms, see the Architecture Briefing on the <a href="http://www.eecis.udel.edu/~mills/ntp.html">Network Time Synchronization Research Project</a> page.</p>
 <h4 id="scale">NTP Timescale and Data Formats</h4>
 <p>NTP clients and servers synchronize to the  Coordinated Universal Time (UTC) timescale used by national laboratories and disseminated by radio, satellite and telephone modem. This is a global timescale independent of geographic position. There are no provisions for local time zone or daylight savings time; however, these functions can be performed by the operating system on a per-user basis.</p>
-<p> The UT1 timescale, upon which UTC is based, is determined by the rotation of the Earth about its axis, which is gradually slowing down. In order to rationalize  UTC with respect to UT1, a  leap second is inserted  at intervals of about 18 months, as determined by the  International Earth Rotation Service (IERS). The historic insertions are documented in the <tt>leap-seconds.list</tt> file, which can be downloaded from the NIST FTP server. This file is updated at intervals not exceeding six months. Leap second warnings are disseminated by the national laboratories in the broadcast timecode format. These warnings are propagated from the NTP primary servers via other server to the clients  by the NTP on-wire protocol. The leap second is implemented by the operating system kernel, as described in  the white  paper <a href="http://www.eecis.udel.edu/~mills/leap.html">The NTP Timescale and Leap Seconds</a>.</p>
+<p> The UT1 timescale, upon which UTC is based, is determined by the rotation of the Earth about its axis, which is gradually slowing down relative to International Attomic Time (TAI). In order to rationalize  UTC with respect to TAI, a  leap second is inserted  at intervals of about 18 months, as determined by the  International Earth Rotation Service (IERS). The historic insertions are documented in the <tt>leap-seconds.list</tt> file, which can be downloaded from the NIST FTP server. This file is updated at intervals not exceeding six months. Leap second warnings are disseminated by the national laboratories in the broadcast timecode format. These warnings are propagated from the NTP primary servers via other server to the clients  by the NTP on-wire protocol. The leap second is implemented by the operating system kernel, as described in  the white  paper <a href="http://www.eecis.udel.edu/~mills/leap.html">The NTP Timescale and Leap Seconds</a>.</p>
 <p>There are two NTP time formats, a 64-bit <em>timestamp</em> format and a 128-bit <em>date</em> format. The date format is used internally, while the timestamp format is used in packet headers exchanged between clients and servers. The timestamp format spans 136 years, called an <em>era</em>. The current era began on 1 January 1900, while  the next one begins in 2036. Details on these formats and conversions between them are  in the white paper <a href="http://www.eecis.udel.edu/~mills/y2k.html">The NTP Era and Era Numbering</a>. However, the NTP protocol will synchronize correctly, regardless of era, as long as  the system clock is set initially within  68 years of the correct time. Further discussion on this issue is in the white paper <a href="http://www.eecis.udel.edu/~mills/time.html">NTP Timestamp Calculations</a>. Ordinarily, these formats are not seen by application programs, which convert these NTP formats to native Unix or Windows formats.</p>
 <h4 id="budget">Statistics Budget</h4>
 <p>Each NTP synchronization source is characterized by the   offset and delay   samples measured by the on-wire protocol using the equations above. The  dispersion  sample is initialized with the sum of the server precision and the client precision as each update is received. The dispersion increases  at a rate of 15 <font face="symbol">m</font>s/s after that. For this purpose, the precision is equal to the latency to read the system clock. The offset, delay and dispersion are called the <em>sample statistics</em>.</p>
-<p> In a window of eight (offset, delay, dispersion) samples, the algorithm described on the  <a href="filter.html">Clock Filter Algorithm</a> page selects the  sample with  minimum  delay, which generally represents the most accurate offset statistic. The selected sample becomes the <em>peer offset</em> and <em>peer delay </em>statistics. The <em>peer dispersion</em> is  a weighted average of the dispersion samples in the window.  These quantities are recalculated as each  update is received from the server. Between updates, both the sample dispersion and  peer dispersion continue to grow at the same  rate, 15 <font face="symbol">m</font>s/s. Finally, the <em>peer jitter</em> is determined as the root mean square (RMS)  of  the offset samples in the window relative to the selected offset sample. The peer    statistics are recorded by the <tt>peerstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. Peer variables are displayed by the <tt>rv</t
 t> command of the <a href="ntpq.html#peer"><tt>ntpq</tt></a> program.</p>
-<p> The clock filter algorithm continues to process packets in this way until the source is no longer reachable. Reachability is determined by an eight-bit shift register, which is shifted left by one bit as each poll packet is sent, with 0 replacing the vacated rightmost bit. Each time an update is received, the rightmost bit is set to 1. The source is considered reachable if any bit is set to 1 in the register; otherwise, it is considered unreachable.</p>
-<p>A server is considered <em>nonselectable</em>  if it is unreachable,  or the <em>peer synchronization distance</em> abbreviated to <em>peer distance</em> (see below) is above the <em>select threshold,</em> or if a timing loop is present. If none of these conditions exist, the server is considered <em>selectable</em>. The select threshold is by default 1.5 s, but can be changed by the <tt>maxdist</tt> option of the <a href="miscopt.html#tos"> <tt>tos</tt></a> command. A timing loop is presentif the server is  synchronized to the client, which can occur, for example, if they  are configured  in symmetric modes with each other. When a source becomes unreachable, a  dummy sample with  &quot;infinite&quot; dispersion  is inserted in the shift register at each poll, thus displacing old samples. This causes the peeer dispersion, and thus the peer distance, to  increase and eventually to exceed the select threshold.</p>
+<p> In a window of eight (offset, delay, dispersion) samples, the algorithm described on the  <a href="filter.html">Clock Filter Algorithm</a> page selects the  sample with  minimum  delay, which generally represents the most accurate offset statistic. The selected sample becomes the <em>peer offset</em> and <em>peer delay </em>statistics. The <em>peer dispersion</em> is  a weighted average of the dispersion samples in the window.  These quantities are recalculated as each  update is received from the source. Between updates, both the sample dispersion and  peer dispersion continue to grow at the same  rate, 15 <font face="symbol">m</font>s/s. Finally, the <em>peer jitter</em> is determined as the root mean square (RMS)  of  the offset samples in the window relative to the selected offset sample. The peer    statistics are recorded by the <tt>peerstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. Peer variables are displayed by the <tt>rv</t
 t> command of the <a href="ntpq.html#peer"><tt>ntpq</tt></a> program.</p>
+<p> The clock filter algorithm continues to process packets in this way until the source is no longer reachable. Reachability is determined by an eight-bit shift register, which is shifted left by one bit as each poll packet is sent, with 0 replacing the vacated rightmost bit. Each time a valid update is received, the rightmost bit is set to 1. The source is considered reachable if any bit is set to 1 in the register; otherwise, it is considered unreachable. When a source becomes unreachable, a  dummy sample with  &quot;infinite&quot; dispersion  is inserted in the shift register at each poll, thus displacing old samples. This causes the peeer dispersion to  increase eventually to infinity.</p>
 <p>The composition of  the survivor population and the system peer selection is re determined as each update from each source is received. The system peer and system variables are determined as described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page.  The system variables are copied from the  system peer variables of the same name and the system stratum set one greater than the system peer stratum. The system    statistics are recorded by the <tt>loopstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. System variables are displayed by the <tt>rv</tt> command of the <a href="ntpq.html#system"><tt>ntpq</tt></a> program.</p>
-<p> The system synchronization distance, usually called the root distance, is defined as half the system peer delay plus the system peer dispersion. Between updates it increases at the same rate as the system  peer dispersion,  even if all sources have become unselectable.  If the server root distance  exceeds the client select threshold, as apparent to dependent clients, the server is considered nonselectable. It is important to understand that a server in this condition remains a reliable source of synchronization within its error bounds, as described in the next section.</p>
 <h4 id="quality">Quality of Service</h4>
-<p>The  algorithms described on  the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page deliver several important statistics, including <em>system offset</em> and <em>system jitter</em>. These statistics are determined by the mitigation algorithms from the survivor statistics produced by the clock cluster algorithm. System offset is best interpreted as the maximum-likelihood estimate of the system clock offset, while system jitter is best interpreted as the expected error of this estimate.</p>
+<p>The  algorithms described on  the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page deliver several important statistics, including <em>system offset</em> and <em>system jitter</em>. These statistics are determined  from the survivor statistics produced by the clock cluster algorithm. System offset is best interpreted as the maximum-likelihood estimate of the system clock offset, while system jitter is best interpreted as the expected error of this estimate.</p>
 <p>Of interest in the following discussion is how the client determines these statistics  from a survivor population including reference clocks and remote servers. This is determined from two statistics, <em>expected error</em> and <em>maximum error.</em> Expected error, also called system jitter, is determined from various jitter components; it represents the nominal error in determining the  clock offset. </p>
 <p>Maximum error is determined from delay and dispersion contributions and represents the worst-case error due to all causes. In order to simplify discussion, certain minor contributions to the maximum error statistic are ignored. Elsewhere in the documentation the maximum error is called system synchronization distance or root distance. If the precision time kernel support is available, both the estimated error and maximum error are reported to user programs via the <tt>ntp_gettime()</tt> kernel system call. See the <a href="kern.html">Kernel Model for Precision Timekeeping</a> page for further information.</p>
 <p>The maximum error statistic is  computed as one-half the <em>root delay</em> to the primary source of time; i.e., the primary reference clock, plus the <em>root dispersion</em>.   The root variables are included in the NTP packet header received from each server. When calculating  maximum error, the  root delay is the sum of the root delay in the packet and the peer  delay, while the root dispersion is the sum of the root dispersion in the packet and the peer dispersion.</p>
-<p>A source is considered selectable only if its maximum error is less than the <em>select threshold</em>, by default 1.5 s, but can be changed according to client preference using the <tt>maxdist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. A common  consequence is when an upstream server loses all sources and its maximum error apparent to dependent clients begins to increase. The clients are not aware of  this condition and  continue to accept synchronization as long as the maximum error is less than the select threshold.</p>
+<p>A source is considered selectable only if its maximum error is less than the <em>select threshold</em>, by default 1.5 s, but can be changed according to client preference using the <tt>maxdist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. A common  consequence is when an upstream server loses all sources and its maximum error apparent to dependent clients  continues to increase. The clients are not aware of  this condition and  continue to accept synchronization as long as the maximum error is less than the select threshold.</p>
 <p>Although it might seem counterintuitive, a cardinal rule in the selection process is, once a sample has been selected by the clock filter algorithm,  older samples are no longer selectable. This applies also to the clock select algorithm. Once the peer variables for a source have been selected, older variables of the same or other sources are no longer selectable. The reason for these rules is to limit the time delay in the  clock discipline algorithm. This is necessary to  preserve the optimum impulse response and thus the risetime and overshoot.</p>
 <p>This means that not every sample can be used to update the peer variables, and up to seven samples can be ignored between selected samples. This fact has been carefully considered in the discipline algorithm design with due consideration for feedback loop delay and minimum sampling rate. In engineering terms, even if only one sample in eight survives, the resulting sample rate is twice the Nyquist rate at any time constant and poll interval.</p>
 <h4 id="house">Clock Initialization and Management</h4>


More information about the bk-ntp-dev-send mailing list