doc: add doc/cmd/sntp.rst and remove doc/README.SNTP

Add a proper documentation file for the sntp command in RST format and
drop doc/README.SNTP. The documentation now includes the NET_LWIP
specificities.

Signed-off-by: Jerome Forissier <jerome.forissier@linaro.org>

diff --git a/doc/README.SNTP b/doc/README.SNTP
deleted file mode 100644 (file)
index da9ec45..0000000
--- a/doc/README.SNTP
+++ /dev/null
@@ -1,17 +0,0 @@
-To use SNTP support, add define CONFIG_CMD_SNTP to the
-configuration file of the board.
-
-The "sntp" command gets network time from NTP time server and
-syncronize RTC of the board. This command needs the command line
-parameter of server's IP address or environment variable
-"ntpserverip". The network time is sent as UTC. So if you want to
-set local time to RTC, set the offset in second from UTC to the
-environment variable "time offset".
-
-If the DHCP server provides time server's IP or time offset, you
-don't need to set the above environment variables yourself.
-
-Current limitations of SNTP support:
-1. The roundtrip time is ignored.
-2. Only the 1st NTP server IP, in the option ntp-servers of DHCP, will
-   be used.

diff --git a/doc/usage/cmd/sntp.rst b/doc/usage/cmd/sntp.rst
new file mode 100644 (file)
index 0000000..d97f830
--- /dev/null
+++ b/doc/usage/cmd/sntp.rst
@@ -0,0 +1,72 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+.. index::
+   single: sntp (command)
+
+sntp command
+============
+
+Synopsis
+--------
+
+::
+
+    sntp [serverip]
+    sntp [servername]  # NET_LWIP=y && CMD_DNS=y only
+
+
+Description
+-----------
+
+The sntp command gets the current time from an NTP time server and
+syncronizes the Real Time Clock (RTC) of the board. This command needs
+the server's IP address to be given on the command line or via the
+`ntpserverip` environment variable.
+
+The address of the NTP server does not need to be given if the DHCP server
+provides one. The legacy network stack (`CONFIG_NET=y`) can only use the
+first NTP server provided in the `ntp-servers` DHCP option.
+
+When the network stack is lwIP (`CONFIG_NET_LWIP=y`) and the dns command
+is enabled (`CONFIG_CMD_DNS=y`), then the sntp command accepts a server
+name as an argument.
+
+The network time is sent as UTC. So, if you want to set the RTC to any local
+time different from UTC, you need to set the `timeoffset` environment variable.
+
+Round-trip delay compensation is not implemented/not enabled. In practice
+this should not matter much given that the RTC API does not have sub-second
+resolution, and round-trip times are typically 10 to 100 ms at most.
+
+Examples
+--------
+
+::
+
+    => setenv ntpserverip 109.190.177.205
+    => date
+    Date: 2025-06-16 (Monday)    Time: 15:19:35
+    => date reset
+    Reset RTC...
+    Date: 2000-01-01 (Saturday)    Time:  0:00:00
+    => date
+    Date: 2000-01-01 (Saturday)    Time:  0:00:03
+    => sntp
+    Date: 2025-06-16 Time: 15:19:43
+    => date
+    Date: 2025-06-16 (Monday)    Time: 15:19:47
+    => setenv timeoffset 7200
+    => sntp
+    Date: 2025-06-16 Time: 17:19:55
+    => date
+    Date: 2025-06-16 (Monday)    Time: 17:19:57
+
+With `CONFIG_NET_LWIP=y` and `CONFIG_CMD_DNS=y`:
+
+::
+
+    => date reset
+    Reset RTC...
+    Date: 2000-01-01 (Saturday)    Time:  0:00:00
+    => sntp 0.us.pool.ntp.org
+    Date: 2025-06-16 Time: 15:10:59

diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index c5b45fd929026a833c3b13efb08a29a6d3c22189..e9e0bd04e05ad4a32518621d3803e857f0c0a4c1 100644 (file)
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -119,6 +119,7 @@ Shell commands
    cmd/sleep
    cmd/sm
    cmd/smbios
+   cmd/sntp
    cmd/sound
    cmd/source
    cmd/tcpm