sntp_opts.h

00001 /**
00002  * @file
00003  * SNTP client options list
00004  */
00005 
00006 /*
00007  * Copyright (c) 2007-2009 Frédéric Bernon, Simon Goldschmidt
00008  * All rights reserved.
00009  *
00010  * Redistribution and use in source and binary forms, with or without modification,
00011  * are permitted provided that the following conditions are met:
00012  *
00013  * 1. Redistributions of source code must retain the above copyright notice,
00014  *    this list of conditions and the following disclaimer.
00015  * 2. Redistributions in binary form must reproduce the above copyright notice,
00016  *    this list of conditions and the following disclaimer in the documentation
00017  *    and/or other materials provided with the distribution.
00018  * 3. The name of the author may not be used to endorse or promote products
00019  *    derived from this software without specific prior written permission.
00020  *
00021  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
00022  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00023  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
00024  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00025  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
00026  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00027  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00028  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
00029  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
00030  * OF SUCH DAMAGE.
00031  *
00032  * This file is part of the lwIP TCP/IP stack.
00033  *
00034  * Author: Frédéric Bernon, Simon Goldschmidt
00035  *
00036  */
00037 #ifndef LWIP_HDR_APPS_SNTP_OPTS_H
00038 #define LWIP_HDR_APPS_SNTP_OPTS_H
00039 
00040 #include "lwip/opt.h"
00041 #include "lwip/prot/iana.h"
00042 
00043 /**
00044  * @defgroup sntp_opts Options
00045  * @ingroup sntp
00046  * @{
00047  */
00048 
00049 /** SNTP macro to change system time in seconds
00050  * Define SNTP_SET_SYSTEM_TIME_US(sec, us) to set the time in microseconds
00051  * instead of this one if you need the additional precision. Alternatively,
00052  * define SNTP_SET_SYSTEM_TIME_NTP(sec, frac) in order to work with native
00053  * NTP timestamps instead.
00054  */
00055 #if !defined SNTP_SET_SYSTEM_TIME || defined __DOXYGEN__
00056 #define SNTP_SET_SYSTEM_TIME(sec)   LWIP_UNUSED_ARG(sec)
00057 #endif
00058 
00059 /** The maximum number of SNTP servers that can be set */
00060 #if !defined SNTP_MAX_SERVERS || defined __DOXYGEN__
00061 #define SNTP_MAX_SERVERS           LWIP_DHCP_MAX_NTP_SERVERS
00062 #endif
00063 
00064 /** Set this to 1 to implement the callback function called by dhcp when
00065  * NTP servers are received. */
00066 #if !defined SNTP_GET_SERVERS_FROM_DHCP || defined __DOXYGEN__
00067 #define SNTP_GET_SERVERS_FROM_DHCP LWIP_DHCP_GET_NTP_SRV
00068 #endif
00069 
00070 /** Set this to 1 to support DNS names (or IP address strings) to set sntp servers
00071  * One server address/name can be defined as default if SNTP_SERVER_DNS == 1:
00072  * \#define SNTP_SERVER_ADDRESS "pool.ntp.org"
00073  */
00074 #if !defined SNTP_SERVER_DNS || defined __DOXYGEN__
00075 #define SNTP_SERVER_DNS            0
00076 #endif
00077 
00078 /**
00079  * SNTP_DEBUG: Enable debugging for SNTP.
00080  */
00081 #if !defined SNTP_DEBUG || defined __DOXYGEN__
00082 #define SNTP_DEBUG                  LWIP_DBG_OFF
00083 #endif
00084 
00085 /** SNTP server port */
00086 #if !defined SNTP_PORT || defined __DOXYGEN__
00087 #define SNTP_PORT                   LWIP_IANA_PORT_SNTP
00088 #endif
00089 
00090 /** Sanity check:
00091  * Define this to
00092  * - 0 to turn off sanity checks (default; smaller code)
00093  * - >= 1 to check address and port of the response packet to ensure the
00094  *        response comes from the server we sent the request to.
00095  * - >= 2 to check returned Originate Timestamp against Transmit Timestamp
00096  *        sent to the server (to ensure response to older request).
00097  * - >= 3 @todo: discard reply if any of the VN, Stratum, or Transmit Timestamp
00098  *        fields is 0 or the Mode field is not 4 (unicast) or 5 (broadcast).
00099  * - >= 4 @todo: to check that the Root Delay and Root Dispersion fields are each
00100  *        greater than or equal to 0 and less than infinity, where infinity is
00101  *        currently a cozy number like one second. This check avoids using a
00102  *        server whose synchronization source has expired for a very long time.
00103  */
00104 #if !defined SNTP_CHECK_RESPONSE || defined __DOXYGEN__
00105 #define SNTP_CHECK_RESPONSE         0
00106 #endif
00107 
00108 /** Enable round-trip delay compensation.
00109  * Compensate for the round-trip delay by calculating the clock offset from
00110  * the originate, receive, transmit and destination timestamps, as per RFC.
00111  *
00112  * The calculation requires compiler support for 64-bit integers. Also, either
00113  * SNTP_SET_SYSTEM_TIME_US or SNTP_SET_SYSTEM_TIME_NTP has to be implemented
00114  * for setting the system clock with sub-second precision. Likewise, either
00115  * SNTP_GET_SYSTEM_TIME or SNTP_GET_SYSTEM_TIME_NTP needs to be implemented
00116  * with sub-second precision.
00117  *
00118  * Although not strictly required, it makes sense to combine this option with
00119  * SNTP_CHECK_RESPONSE >= 2 for sanity-checking of the received timestamps.
00120  * Also, in order for the round-trip calculation to work, the difference
00121  * between the local clock and the NTP server clock must not be larger than
00122  * about 34 years. If that limit is exceeded, the implementation will fall back
00123  * to setting the clock without compensation. In order to ensure that the local
00124  * clock is always within the permitted range for compensation, even at first
00125  * try, it may be necessary to store at least the current year in non-volatile
00126  * memory.
00127  */
00128 #if !defined SNTP_COMP_ROUNDTRIP || defined __DOXYGEN__
00129 #define SNTP_COMP_ROUNDTRIP         0
00130 #endif
00131 
00132 /** According to the RFC, this shall be a random delay
00133  * between 1 and 5 minutes (in milliseconds) to prevent load peaks.
00134  * This can be defined to a random generation function,
00135  * which must return the delay in milliseconds as u32_t.
00136  * Turned off by default.
00137  */
00138 #if !defined SNTP_STARTUP_DELAY || defined __DOXYGEN__
00139 #ifdef LWIP_RAND
00140 #define SNTP_STARTUP_DELAY          1
00141 #else
00142 #define SNTP_STARTUP_DELAY          0
00143 #endif
00144 #endif
00145 
00146 /** If you want the startup delay to be a function, define this
00147  * to a function (including the brackets) and define SNTP_STARTUP_DELAY to 1.
00148  */
00149 #if !defined SNTP_STARTUP_DELAY_FUNC || defined __DOXYGEN__
00150 #define SNTP_STARTUP_DELAY_FUNC     (LWIP_RAND() % 5000)
00151 #endif
00152 
00153 /** SNTP receive timeout - in milliseconds
00154  * Also used as retry timeout - this shouldn't be too low.
00155  * Default is 15 seconds. Must not be beolw 15 seconds by specification (i.e. 15000)
00156  */
00157 #if !defined SNTP_RECV_TIMEOUT || defined __DOXYGEN__
00158 #define SNTP_RECV_TIMEOUT           15000
00159 #endif
00160 
00161 /** SNTP update delay - in milliseconds
00162  * Default is 1 hour. Must not be beolw 60 seconds by specification (i.e. 60000)
00163  */
00164 #if !defined SNTP_UPDATE_DELAY || defined __DOXYGEN__
00165 #define SNTP_UPDATE_DELAY           3600000
00166 #endif
00167 
00168 /** SNTP macro to get system time, used with SNTP_CHECK_RESPONSE >= 2
00169  * to send in request and compare in response. Also used for round-trip
00170  * delay compensation if SNTP_COMP_ROUNDTRIP != 0.
00171  * Alternatively, define SNTP_GET_SYSTEM_TIME_NTP(sec, frac) in order to
00172  * work with native NTP timestamps instead.
00173  */
00174 #if !defined SNTP_GET_SYSTEM_TIME || defined __DOXYGEN__
00175 #define SNTP_GET_SYSTEM_TIME(sec, us)     do { (sec) = 0; (us) = 0; } while(0)
00176 #endif
00177 
00178 /** Default retry timeout (in milliseconds) if the response
00179  * received is invalid.
00180  * This is doubled with each retry until SNTP_RETRY_TIMEOUT_MAX is reached.
00181  */
00182 #if !defined SNTP_RETRY_TIMEOUT || defined __DOXYGEN__
00183 #define SNTP_RETRY_TIMEOUT          SNTP_RECV_TIMEOUT
00184 #endif
00185 
00186 /** Maximum retry timeout (in milliseconds). */
00187 #if !defined SNTP_RETRY_TIMEOUT_MAX || defined __DOXYGEN__
00188 #define SNTP_RETRY_TIMEOUT_MAX      (SNTP_RETRY_TIMEOUT * 10)
00189 #endif
00190 
00191 /** Increase retry timeout with every retry sent
00192  * Default is on to conform to RFC.
00193  */
00194 #if !defined SNTP_RETRY_TIMEOUT_EXP || defined __DOXYGEN__
00195 #define SNTP_RETRY_TIMEOUT_EXP      1
00196 #endif
00197 
00198 /** Keep a reachability shift register per server
00199  * Default is on to conform to RFC.
00200  */
00201 #if !defined SNTP_MONITOR_SERVER_REACHABILITY || defined __DOXYGEN__
00202 #define SNTP_MONITOR_SERVER_REACHABILITY 1
00203 #endif
00204 
00205 /**
00206  * @}
00207  */
00208 
00209 #endif /* LWIP_HDR_APPS_SNTP_OPTS_H */