Subversion Repositories openrisc

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     sntp.sgml                                                   -->
<!--                                                                 -->
<!--     Simple Network Time Protocol Client                         -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
<!-- =============================================================== -->
<!-- Copyright (C) 2003 Free Software Foundation, Inc.               -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTEND####                                     -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<PART ID="net-sntp-client">
<TITLE>Simple Network Time Protocol Client</TITLE>
<PARTINTRO>
<PARA>
The SNTP package provides implementation of a client for RFC 2030, the
Simple Network Time Protocol (SNTP). The client listens for broadcasts
or IPv6 multicasts from an NTP server and uses the information received to
set the system clock.  It can also be configured to send SNTP time
requests to specific NTP servers using SNTP's unicast mode.
</PARA>
</PARTINTRO>
<CHAPTER id="net-sntp">
<TITLE>The SNTP Client</TITLE>
<SECT1 id="sntp-starting">
<TITLE>Starting the SNTP client</TITLE>
<para>
The sntp client is implemented as a thread which listens for NTP
broadcasts and IPv6 multicasts, and optionally sends SNTP unicast
requests to specific NTP servers. This thread may be automatically
started by the system if it receives a list of (S)NTP servers from the
DHCP server and unicast mode is enabled. Otherwise it must be started
by the user application. The header file
<filename>cyg/sntp/sntp.h</filename> declares the function to be
called.  The thread is then started by calling the function:
</para>
<programlisting>
void cyg_sntp_start(void);
</programlisting>
<para>
It is safe to call this function multiple times. Once started, the
thread will run forever.
</para>
</sect1>

<sect1 id="net-sntp-operation">
<title>What it does</title>
<para>
The SNTP client listens for NTP IPv4 broadcasts from any NTP servers,
or IPv6 multicasts using the address fe0x:0X::101, where X can be
2 (Link Local), 5 (Site-Local) or 0xe (Global). Such
packets contain a timestamp indicating the current time. The packet
also contains information about where the server is in the hierarchy
of time servers. A server at the root of the time server tree normally
has an atomic clock. Such a server is said to be at stratum 0. A time
server which is synchronised to a stratum 0 server is said to be at
stratum 1 etc. The client will accept any NTP packets from
servers using version 3 or 4 of the protocol. When receiving packets
from multiple servers, it will use the packets from the server with
the lowest stratum. However, if there are no packets from this server
for 10 minutes and another server is sending packets, the client will
change servers.
</para>
<para>
If SNTP unicast mode is enabled via the CYGPKG_NET_SNTP_UNICAST
option, the SNTP client can additionally be configured with a list
of specific NTP servers to query.  The general algorithm is as follows: if
the system clock has not yet been set via an NTP time update, then
the client will send out NTP requests every 30 seconds to all
configured NTP servers.  Once an NTP time update has been received,
the client will send out additional NTP requests every 30 minutes
in order to update the system clock.  These requests are resent
every 30 seconds until a response is received.
</para>
<para>
The system clock in eCos is accurate to 1 second. The SNTP client will
change the system clock when the time difference with the received
timestamp is greater than 2 seconds. The change is made as a step. 
</para>
</sect1>

<sect1 id="net-sntp-unicast">
<title>Configuring the unicast list of NTP servers</title>
<para>
If SNTP unicast mode is enabled via the CYGPKG_NET_SNTP_UNICAST
option, the SNTP client can be configured with a list of
NTP servers to contact for time updates.
</para>
<para>
By default, this list is configured with NTP server information
received from DHCP.  The number of NTP servers that are extracted
from DHCP can be configured with the CYGOPT_NET_SNTP_UNICAST_MAXDHCP
option.  This option can also be used to disable DHCP usage entirely.
</para>
<para>
The list of NTP servers can be manually configured with the following
API function.  Note that manual configuration will override any
servers that were automatically configured by DHCP. But later
reconfigurations by DHCP will override manual configurations. Hence it
is not recommended to manually configure servers when
CYGOPT_NET_SNTP_UNICAST is enabled.
</para>
<programlisting>
#include &lt;cyg/sntp/sntp.h&gt;

void cyg_sntp_set_servers(struct sockaddr *server_list, cyg_uint32 num_servers);
</programlisting>
<para>
This function takes an array of sockaddr structures specifying the
IP address and UDP port of each NTP server to query.  Currently,
both IPv4 and IPv6 sockaddr structures are supported.  The
num_servers argument specifies how many sockaddr's are contained
in the array.  The server_list array must be maintained by the caller.
Once the array is registered with this function, it must not be
modified by the caller until it is replaced or unregistered
by another call to this function.
</para>
<para>
Calling this function with a server_list of NULL and a num_servers
value of 0 unregisters any previously configured server_list array.
</para>
<para>
Finally, note that if this function is called with a non-empty server
list, it will implicitly start the SNTP client if it has not already
been started (i.e. it will call cyg_sntp_start()).
</para>
</sect1>

<sect1 id="net-sntp-warning">
<title>Warning: timestamp wrap around</title>
<para>
The timestamp in the NTP packet is a 32bit integer which represents
the number of seconds after 00:00 01/01/1900. This 32bit number will
wrap around at 06:28:16 Feb 7 2036. At this point in time, the eCos
time will jump back to around 00:00:00 Jan 1 1900 when the next
NTP packet is received. 
</para>
<para>
YOU HAVE BEEN WARNED!
</para>
</SECT1>
<sect1 id="net-sntp-testing">
<title>The SNTP test program</title>
<para>
The SNTP package contains a simple test program. Testing an SNTP
client is not easy, so the test program should be considered as more a
proof of concept. It shows that an NTP packet has been received,
and is accurate to within a few days. 
</para>
<para>
The test program starts the network interfaces using the standard
call. It then starts the SNTP thread. A loop is then entered printing
the current system time every second for two minutes. When the client
receives an NTP packet the time will jump from 1970 to hopefully the
present day. Once the two minutes have expired, two simple tests are
made. If the time is still less than 5 minutes since 00:00:00
01/01/1970 the test fails. This indicates no NTP messages have
been received. Check that the server is actually sending packet, using
the correct port (123), correct IPv6 multicast address, and at a
sufficiently frequent rate that the
target has a chance to receive a message within the 2 minute
interval. If all this is correct, assume the target is broken. 
</para>
<para>
The second test is that the current system time is compared with the
build time as reported by the CPP macro __DATE__. If the build date is
in the future relative to the system time, the test fails. If the
build date is more than 90 days in the past relative to the system
time the test also fails. If such failures are seen, use walk-clock
time to verify the time printed during the test. If this seems correct
check the build date for the test. This is printed at startup. If all
else fails check that the computer used to build the test has the
correct time. 
</para>
<para>
If SNTP unicast mode is enabled, the above tests are run twice.  The
first time, the SNTP client is configured with NTP server addresses
from DHCP.  The second time, unicast mode is disabled and only
multicasts are listened for.  Note that the unicast test is partially
bogus in the sense that any multicast packet received will also make
the unicast test pass.  To reduce the chance of this happening the
test will wait for a sorter time for replies. This is not ideal, but
it is the best that can be done with an automated test.
</para>
</SECT1>
</CHAPTER>
</PART>