packages/net/sntp/v2_0/doc/sntp.sgml

   1 <!-- {{{ Banner                         -->
   2
   3 <!-- =============================================================== -->
   4 <!--                                                                 -->
   5 <!--     sntp.sgml                                                   -->
   6 <!--                                                                 -->
   7 <!--     Simple Network Time Protocol Client                         -->
   8 <!--                                                                 -->
   9 <!-- =============================================================== -->
  10 <!-- ####COPYRIGHTBEGIN####                                          -->
  11 <!--                                                                 -->
  12 <!-- =============================================================== -->
  13 <!-- Copyright (C) 2003 Andrew Lunn                                  -->
  14 <!-- This material may be distributed only subject to the terms      -->
  15 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  16 <!-- or later (the latest version is presently available at          -->
  17 <!-- http://www.opencontent.org/openpub/)                            -->
  18 <!-- Distribution of the work or derivative of the work in any       -->
  19 <!-- standard (paper) book form is prohibited unless prior           -->
  20 <!-- permission obtained from the copyright holder                   -->
  21 <!-- =============================================================== -->
  22 <!--                                                                 -->
  23 <!-- ####COPYRIGHTEND####                                            -->
  24 <!-- =============================================================== -->
  25 <!-- #####DESCRIPTIONBEGIN####                                       -->
  26 <!--                                                                 -->
  27 <!-- ####DESCRIPTIONEND####                                          -->
  28 <!-- =============================================================== -->
  29
  30 <!-- }}} -->
  31
  32 <PART ID="net-sntp-client">
  33 <TITLE>Simple Network Time Protocol Client</TITLE>
  34 <PARTINTRO>
  35 <PARA>
  36 The SNTP package provides implementation of a client for RFC 2030, the
  37 Simple Network Time Protocol (SNTP). The client listens for broadcasts
  38 or IPv6 multicasts from an NTP server and uses the information received to
  39 set the system clock.  It can also be configured to send SNTP time
  40 requests to specific NTP servers using SNTP's unicast mode.
  41 </PARA>
  42 </PARTINTRO>
  43 <CHAPTER id="net-sntp">
  44 <TITLE>The SNTP Client</TITLE>
  45 <SECT1 id="sntp-starting">
  46 <TITLE>Starting the SNTP client</TITLE>
  47 <para>
  48 The sntp client is implemented as a thread which listens for NTP
  49 broadcasts and IPv6 multicasts, and optionally sends SNTP unicast
  50 requests to specific NTP servers. This thread may be automatically
  51 started by the system if it receives a list of (S)NTP servers from the
  52 DHCP server and unicast mode is enabled. Otherwise it must be started
  53 by the user application. The header file
  54 <filename>cyg/sntp/sntp.h</filename> declares the function to be
  55 called.  The thread is then started by calling the function:
  56 </para>
  57 <programlisting>
  58 void cyg_sntp_start(void);
  59 </programlisting>
  60 <para>
  61 It is safe to call this function multiple times. Once started, the
  62 thread will run forever.
  63 </para>
  64 </sect1>
  65
  66 <sect1 id="net-sntp-operation">
  67 <title>What it does</title>
  68 <para>
  69 The SNTP client listens for NTP IPv4 broadcasts from any NTP servers,
  70 or IPv6 multicasts using the address fe0x:0X::101, where X can be
  71 2 (Link Local), 5 (Site-Local) or 0xe (Global). Such
  72 packets contain a timestamp indicating the current time. The packet
  73 also contains information about where the server is in the hierarchy
  74 of time servers. A server at the root of the time server tree normally
  75 has an atomic clock. Such a server is said to be at stratum 0. A time
  76 server which is synchronised to a stratum 0 server is said to be at
  77 stratum 1 etc. The client will accept any NTP packets from
  78 servers using version 3 or 4 of the protocol. When receiving packets
  79 from multiple servers, it will use the packets from the server with
  80 the lowest stratum. However, if there are no packets from this server
  81 for 10 minutes and another server is sending packets, the client will
  82 change servers.
  83 </para>
  84 <para>
  85 If SNTP unicast mode is enabled via the CYGPKG_NET_SNTP_UNICAST
  86 option, the SNTP client can additionally be configured with a list
  87 of specific NTP servers to query.  The general algorithm is as follows: if
  88 the system clock has not yet been set via an NTP time update, then
  89 the client will send out NTP requests every 30 seconds to all
  90 configured NTP servers.  Once an NTP time update has been received,
  91 the client will send out additional NTP requests every 30 minutes
  92 in order to update the system clock.  These requests are resent
  93 every 30 seconds until a response is received.
  94 </para>
  95 <para>
  96 The system clock in eCos is accurate to 1 second. The SNTP client will
  97 change the system clock when the time difference with the received
  98 timestamp is greater than 2 seconds. The change is made as a step.
  99 </para>
 100 </sect1>
 101
 102 <sect1 id="net-sntp-unicast">
 103 <title>Configuring the unicast list of NTP servers</title>
 104 <para>
 105 If SNTP unicast mode is enabled via the CYGPKG_NET_SNTP_UNICAST
 106 option, the SNTP client can be configured with a list of
 107 NTP servers to contact for time updates.
 108 </para>
 109 <para>
 110 By default, this list is configured with NTP server information
 111 received from DHCP.  The number of NTP servers that are extracted
 112 from DHCP can be configured with the CYGOPT_NET_SNTP_UNICAST_MAXDHCP
 113 option.  This option can also be used to disable DHCP usage entirely.
 114 </para>
 115 <para>
 116 The list of NTP servers can be manually configured with the following
 117 API function.  Note that manual configuration will override any
 118 servers that were automatically configured by DHCP. But later
 119 reconfigurations by DHCP will override manual configurations. Hence it
 120 is not recommended to manually configure servers when
 121 CYGOPT_NET_SNTP_UNICAST is enabled.
 122 </para>
 123 <programlisting>
 124 #include &lt;cyg/sntp/sntp.h&gt;
 125
 126 void cyg_sntp_set_servers(struct sockaddr *server_list, cyg_uint32 num_servers);
 127 </programlisting>
 128 <para>
 129 This function takes an array of sockaddr structures specifying the
 130 IP address and UDP port of each NTP server to query.  Currently,
 131 both IPv4 and IPv6 sockaddr structures are supported.  The
 132 num_servers argument specifies how many sockaddr's are contained
 133 in the array.  The server_list array must be maintained by the caller.
 134 Once the array is registered with this function, it must not be
 135 modified by the caller until it is replaced or unregistered
 136 by another call to this function.
 137 </para>
 138 <para>
 139 Calling this function with a server_list of NULL and a num_servers
 140 value of 0 unregisters any previously configured server_list array.
 141 </para>
 142 <para>
 143 Finally, note that if this function is called with a non-empty server
 144 list, it will implicitly start the SNTP client if it has not already
 145 been started (i.e. it will call cyg_sntp_start()).
 146 </para>
 147 </sect1>
 148
 149 <sect1 id="net-sntp-warning">
 150 <title>Warning: timestamp wrap around</title>
 151 <para>
 152 The timestamp in the NTP packet is a 32bit integer which represents
 153 the number of seconds after 00:00 01/01/1900. This 32bit number will
 154 wrap around at 06:28:16 Feb 7 2036. At this point in time, the eCos
 155 time will jump back to around 00:00:00 Jan 1 1900 when the next
 156 NTP packet is received.
 157 </para>
 158 <para>
 159 YOU HAVE BEEN WARNED!
 160 </para>
 161 </SECT1>
 162 <sect1 id="net-sntp-testing">
 163 <title>The SNTP test program</title>
 164 <para>
 165 The SNTP package contains a simple test program. Testing an SNTP
 166 client is not easy, so the test program should be considered as more a
 167 proof of concept. It shows that an NTP packet has been received,
 168 and is accurate to within a few days.
 169 </para>
 170 <para>
 171 The test program starts the network interfaces using the standard
 172 call. It then starts the SNTP thread. A loop is then entered printing
 173 the current system time every second for two minutes. When the client
 174 receives an NTP packet the time will jump from 1970 to hopefully the
 175 present day. Once the two minutes have expired, two simple tests are
 176 made. If the time is still less than 5 minutes since 00:00:00
 177 01/01/1970 the test fails. This indicates no NTP messages have
 178 been received. Check that the server is actually sending packet, using
 179 the correct port (123), correct IPv6 multicast address, and at a
 180 sufficiently frequent rate that the
 181 target has a chance to receive a message within the 2 minute
 182 interval. If all this is correct, assume the target is broken.
 183 </para>
 184 <para>
 185 The second test is that the current system time is compared with the
 186 build time as reported by the CPP macro __DATE__. If the build date is
 187 in the future relative to the system time, the test fails. If the
 188 build date is more than 90 days in the past relative to the system
 189 time the test also fails. If such failures are seen, use walk-clock
 190 time to verify the time printed during the test. If this seems correct
 191 check the build date for the test. This is printed at startup. If all
 192 else fails check that the computer used to build the test has the
 193 correct time.
 194 </para>
 195 <para>
 196 If SNTP unicast mode is enabled, the above tests are run twice.  The
 197 first time, the SNTP client is configured with NTP server addresses
 198 from DHCP.  The second time, unicast mode is disabled and only
 199 multicasts are listened for.  Note that the unicast test is partially
 200 bogus in the sense that any multicast packet received will also make
 201 the unicast test pass.  To reduce the chance of this happening the
 202 test will wait for a sorter time for replies. This is not ideal, but
 203 it is the best that can be done with an automated test.
 204 </para>
 205 </SECT1>
 206 </CHAPTER>
 207 </PART>