diff mbox series

[v3,12/13] doc: add doc/cmd/sntp.rst and remove doc/README.SNTP

Message ID 20250617100720.2544758-13-jerome.forissier@linaro.org
State New
Headers show
Series sntp for NET_LWIP | expand

Commit Message

Jerome Forissier June 17, 2025, 10:04 a.m. UTC 
Add a proper documentation file for the cntp 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>
- Create a new RST file and delete doc/README.SNTP
---

(no changes since v2)

Changes in v2:
- New patch

 doc/README.SNTP        | 17 ----------
 doc/usage/cmd/sntp.rst | 72 ++++++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst    |  1 +
 3 files changed, 73 insertions(+), 17 deletions(-)
 delete mode 100644 doc/README.SNTP
 create mode 100644 doc/usage/cmd/sntp.rst

Comments

Tom Rini June 17, 2025, 10:42 p.m. UTC | #1 
On Tue, Jun 17, 2025 at 12:04:02PM +0200, Jerome Forissier wrote:

> Add a proper documentation file for the cntp command in RST format and

sntp :)

> drop doc/README.SNTP. The documentation now includes the NET_LWIP
> specificities.
> 
> Signed-off-by: Jerome Forissier <jerome.forissier@linaro.org>
> - Create a new RST file and delete doc/README.SNTP

Thanks for doing this. I see a small problem:

[snip]
> diff --git a/doc/usage/cmd/sntp.rst b/doc/usage/cmd/sntp.rst
> new file mode 100644
> index 00000000000..eab7c664728
> --- /dev/null
> +++ b/doc/usage/cmd/sntp.rst
> @@ -0,0 +1,72 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +.. index::
> +   single: wget (command)
> +
> +wget command
> +============

This isn't wget but I assume you started from that file.
Jerome Forissier June 18, 2025, 7:32 a.m. UTC | #2 
On 6/18/25 00:42, Tom Rini wrote:
> On Tue, Jun 17, 2025 at 12:04:02PM +0200, Jerome Forissier wrote:
> 
>> Add a proper documentation file for the cntp command in RST format and
> 
> sntp :)
> 
>> drop doc/README.SNTP. The documentation now includes the NET_LWIP
>> specificities.
>>
>> Signed-off-by: Jerome Forissier <jerome.forissier@linaro.org>
>> - Create a new RST file and delete doc/README.SNTP
> 
> Thanks for doing this. I see a small problem:
> 
> [snip]
>> diff --git a/doc/usage/cmd/sntp.rst b/doc/usage/cmd/sntp.rst
>> new file mode 100644
>> index 00000000000..eab7c664728
>> --- /dev/null
>> +++ b/doc/usage/cmd/sntp.rst
>> @@ -0,0 +1,72 @@
>> +.. SPDX-License-Identifier: GPL-2.0+:
>> +
>> +.. index::
>> +   single: wget (command)
>> +
>> +wget command
>> +============
> 
> This isn't wget but I assume you started from that file.

Yeah I really should improve my proofreading ;-) thanks
diff mbox series

Patch

diff --git a/doc/README.SNTP b/doc/README.SNTP
deleted file mode 100644
index da9ec459ad4..00000000000
--- 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
index 00000000000..eab7c664728
--- /dev/null
+++ b/doc/usage/cmd/sntp.rst
@@ -0,0 +1,72 @@ 
+.. SPDX-License-Identifier: GPL-2.0+:
+
+.. index::
+   single: wget (command)
+
+wget 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 372ef56c967..1f2de69b953 100644
--- 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