This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new d6d06c72ad7 Documentation/stm32f4: document the Ethernet PTP support.
d6d06c72ad7 is described below
commit d6d06c72ad741a0a7589b59094f48011aaa22c16
Author: Daniel P. Carvalho <[email protected]>
AuthorDate: Sun Sep 20 13:51:35 2026 -0300
Documentation/stm32f4: document the Ethernet PTP support.
The STM32F4 page did not say anything about the Ethernet MAC.
- Describe the time counter of the MAC and the options that enable the
timestamping of received packets, the pulse-per-second output and
the use of the counter as a high-resolution RTC.
- Describe the /dev/ptp0 clock that the driver registers: the
operations it offers, the numbering, and that the timestamps of the
received packets are values of the MAC counter and not of
CLOCK_REALTIME, so they have to be compared with /dev/ptp0.
- Show how to start ptpd with them and a configuration that enables
everything above.
- Say that the driver does not timestamp transmitted packets.
Signed-off-by: Daniel P. Carvalho <[email protected]>
Assisted-by: Claude:claude-sonnet-5
---
Documentation/platforms/arm/stm32f4/index.rst | 80 +++++++++++++++++++++++++++
1 file changed, 80 insertions(+)
diff --git a/Documentation/platforms/arm/stm32f4/index.rst
b/Documentation/platforms/arm/stm32f4/index.rst
index 3433d538879..11b28dde626 100644
--- a/Documentation/platforms/arm/stm32f4/index.rst
+++ b/Documentation/platforms/arm/stm32f4/index.rst
@@ -195,6 +195,86 @@ SDIO
- CONFIG_STM32_SDIO_WIDTH_D1_ONLY - Select 1-bit transfer mode. Default:
4-bit transfer mode.
+Ethernet
+--------
+
+The Ethernet MAC of the STM32F4 has a time counter that can stamp every
+frame it sends or receives in hardware, at the moment the frame crosses the
+MAC. A protocol such as the Precision Time Protocol (IEEE 1588, PTP) uses
+these stamps to compare its clock with the clock of another node without the
+delay of the software (interrupts and task scheduling) getting into the
+measurement. The options below enable that part of the driver.
+
+Precision Time Protocol
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The counter has a 32-bit seconds part and a 31-bit sub-second part and is
+clocked from ``SYSCLK``. Its rate can be trimmed by up to +/- 50 %, and its
+phase can be stepped, which is what a PTP daemon needs to steer it towards a
+master clock.
+
+- CONFIG_STM32_ETH_PTP - Enables the PTP timer of the MAC.
+
+- CONFIG_STM32_ETH_ENHANCEDDESC - Uses the double-length DMA descriptors,
+ which have room for the timestamp. Needed for timestamping received
+ packets.
+
+- CONFIG_STM32_ETH_TIMESTAMP_RX - Timestamps every received packet with the
+ counter. Requires CONFIG_STM32_ETH_PTP, CONFIG_STM32_ETH_ENHANCEDDESC and
+ CONFIG_NET_TIMESTAMP. The timestamp is delivered to the application with
+ the packet through the socket options of the network stack, for example
+ ``SO_TIMESTAMPNS``. A packet for which the MAC did not store a timestamp
+ gets a timestamp of zero.
+
+- CONFIG_STM32_ETH_PTP_GPIO - Enables the pulse-per-second output of the MAC
+ on the pin ``GPIO_ETH_PPS_OUT``. The board has to define it in its
+ ``board.h`` with one of the pins of the chip (on the STM32F40xxx and
+ STM32F42xxx parts ``GPIO_ETH_PPS_OUT_1`` is PB5 and ``GPIO_ETH_PPS_OUT_2``
+ is PG8). The pulse is derived from the counter, so it shows how well the
+ counter follows the master clock.
+
+- CONFIG_STM32_ETH_PTP_RTC_HIRES - Uses the counter as the source of
+ ``CONFIG_RTC_HIRES``.
+
+Clock device
+^^^^^^^^^^^^
+
+With CONFIG_PTP_CLOCK the driver registers the counter as a PTP hardware
+clock, ``/dev/ptp0`` for the first Ethernet interface (the number of the
+device is the number of the interface). It follows the generic framework
+described in :doc:`/components/drivers/special/ptp` and offers reading and
+setting the time, the resolution, frequency adjustment (``ADJ_FREQUENCY``, up
+to +/- 50 %) and phase steps (``ADJ_OFFSET`` and ``ADJ_SETOFFSET``). It does
+not offer the cross timestamp of the system and the device clock.
+CONFIG_CLOCK_ADJTIME is needed for ``clock_adjtime()``.
+
+The timestamps of the received packets are values of this same counter, not of
+``CLOCK_REALTIME``. A program that uses them has to compare them with
+``/dev/ptp0``. The ``ptpd`` daemon does that when it is started with hardware
+timestamping and the device as its clock:
+
+.. code-block:: console
+
+ nsh> ptpd -H -p /dev/ptp0 -i eth0 &
+
+A configuration with everything above, for a board with the Ethernet MAC,
+looks like this:
+
+.. code-block:: kconfig
+
+ CONFIG_STM32_ETHMAC=y
+ CONFIG_STM32_ETH_PTP=y
+ CONFIG_STM32_ETH_ENHANCEDDESC=y
+ CONFIG_STM32_ETH_TIMESTAMP_RX=y
+ CONFIG_STM32_ETH_PTP_GPIO=y
+ CONFIG_NET_TIMESTAMP=y
+ CONFIG_PTP_CLOCK=y
+ CONFIG_CLOCK_ADJTIME=y
+ CONFIG_NETUTILS_PTPD=y
+
+This driver stamps received packets only. The packets it sends are not
+stamped by the hardware yet.
+
USB
---
