RE: [PATCH v2 1/3] ethdev: add frequency adjustment API

["Ye, MingjinX" <mingjinx.ye@intel.com>]

Hi Chengwen,

This API is used to synchronise the frequency of the slave node with the master node.

use-case: https://patchwork.dpdk.org/project/dpdk/patch/20240910091328.922082-4-mingjinx.ye@intel.com/

Also, I will refine the description file to avoid confusion.

Regards,
Mingjin

> -----Original Message-----
> From: fengchengwen <fengchengwen@huawei.com>
> Sent: Monday, September 23, 2024 11:12 AM
> To: Ye, MingjinX <mingjinx.ye@intel.com>; dev@dpdk.org
> Cc: Su, Simei <simei.su@intel.com>; Thomas Monjalon
> <thomas@monjalon.net>; Ferruh Yigit <ferruh.yigit@amd.com>; Andrew
> Rybchenko <andrew.rybchenko@oktetlabs.ru>
> Subject: Re: [PATCH v2 1/3] ethdev: add frequency adjustment API
> 
> Hi Mingjin,
> 
>   Why we need this API? What's the use-case?
> 
> Thanks
> 
> On 2024/9/10 17:13, Mingjin Ye wrote:
> > This patch adds freq adjustment API for PTP high accuracy.
> >
> > Signed-off-by: Simei Su <simei.su@intel.com>
> > Signed-off-by: Mingjin Ye <mingjinx.ye@intel.com>
> > ---
> >  doc/guides/nics/features.rst           |  4 +++-
> >  doc/guides/rel_notes/release_24_11.rst | 30 +++-----------------------
> >  lib/ethdev/ethdev_driver.h             |  5 +++++
> >  lib/ethdev/ethdev_trace.h              |  9 ++++++++
> >  lib/ethdev/ethdev_trace_points.c       |  3 +++
> >  lib/ethdev/rte_ethdev.c                | 18 ++++++++++++++++
> >  lib/ethdev/rte_ethdev.h                | 20 +++++++++++++++++
> >  lib/ethdev/version.map                 |  3 +++
> >  8 files changed, 64 insertions(+), 28 deletions(-)
> >
> > diff --git a/doc/guides/nics/features.rst
> > b/doc/guides/nics/features.rst index cd0115ffb3..0508f118fe 100644
> > --- a/doc/guides/nics/features.rst
> > +++ b/doc/guides/nics/features.rst
> > @@ -677,10 +677,12 @@ Supports IEEE1588/802.1AS timestamping.
> >
> >  * **[implements] eth_dev_ops**: ``timesync_enable``,
> ``timesync_disable``
> >    ``timesync_read_rx_timestamp``, ``timesync_read_tx_timestamp``,
> > -  ``timesync_adjust_time``, ``timesync_read_time``,
> ``timesync_write_time``.
> > +  ``timesync_adjust_time``, ``timesync_adjust_freq``,
> > + ``timesync_read_time``, ``timesync_write_time``.
> >  * **[related]    API**: ``rte_eth_timesync_enable()``,
> ``rte_eth_timesync_disable()``,
> >    ``rte_eth_timesync_read_rx_timestamp()``,
> >    ``rte_eth_timesync_read_tx_timestamp``,
> > ``rte_eth_timesync_adjust_time()``,
> > +  ``rte_eth_timesync_adjust_freq()``,
> >    ``rte_eth_timesync_read_time()``, ``rte_eth_timesync_write_time()``.
> >
> >
> > diff --git a/doc/guides/rel_notes/release_24_11.rst
> > b/doc/guides/rel_notes/release_24_11.rst
> > index 0ff70d9057..10ac35e5c0 100644
> > --- a/doc/guides/rel_notes/release_24_11.rst
> > +++ b/doc/guides/rel_notes/release_24_11.rst
> > @@ -25,35 +25,11 @@ New Features
> >  ------------
> >
> >  .. This section should contain new features added in this release.
> > -   Sample format:
> >
> > -   * **Add a title in the past tense with a full stop.**
> > +* **Added Ethernet device clock incremental rate adjustment.**
> >
> > -     Add a short 1-2 sentence description in the past tense.
> > -     The description should be enough to allow someone scanning
> > -     the release notes to understand the new feature.
> > -
> > -     If the feature adds a lot of sub-features you can use a bullet list
> > -     like this:
> > -
> > -     * Added feature foo to do something.
> > -     * Enhanced feature bar to do something else.
> > -
> > -     Refer to the previous release notes for examples.
> > -
> > -     Suggested order in release notes items:
> > -     * Core libs (EAL, mempool, ring, mbuf, buses)
> > -     * Device abstraction libs and PMDs (ordered alphabetically by vendor
> name)
> > -       - ethdev (lib, PMDs)
> > -       - cryptodev (lib, PMDs)
> > -       - eventdev (lib, PMDs)
> > -       - etc
> > -     * Other libs
> > -     * Apps, Examples, Tools (if significant)
> > -
> > -     This section is a comment. Do not overwrite or remove it.
> > -     Also, make sure to start the actual text at the margin.
> > -
> =======================================================
> 
> The above should not delete in this patch, it will remove when release
> 
> > +  Added new function ``rte_eth_timesync_adjust_freq`` to  adjust the
> > + clock increment rate for Ethernet devices.
> >
> >
> >  Removed Items
> > diff --git a/lib/ethdev/ethdev_driver.h b/lib/ethdev/ethdev_driver.h
> > index 883e59a927..68cadc14a5 100644
> > --- a/lib/ethdev/ethdev_driver.h
> > +++ b/lib/ethdev/ethdev_driver.h
> > @@ -664,6 +664,9 @@ typedef int
> > (*eth_timesync_read_tx_timestamp_t)(struct rte_eth_dev *dev,
> >  /** @internal Function used to adjust the device clock. */  typedef
> > int (*eth_timesync_adjust_time)(struct rte_eth_dev *dev, int64_t);
> >
> > +/** @internal Function used to adjust the clock frequency. */ typedef
> > +int (*eth_timesync_adjust_freq)(struct rte_eth_dev *dev, int64_t);
> > +
> >  /** @internal Function used to get time from the device clock. */
> > typedef int (*eth_timesync_read_time)(struct rte_eth_dev *dev,
> >  				      struct timespec *timestamp); @@ -1378,6
> +1381,8 @@ struct
> > eth_dev_ops {
> >  	eth_timesync_read_tx_timestamp_t timesync_read_tx_timestamp;
> >  	/** Adjust the device clock */
> >  	eth_timesync_adjust_time   timesync_adjust_time;
> > +	/** Adjust the clock frequency */
> > +	eth_timesync_adjust_freq   timesync_adjust_freq;
> >  	/** Get the device clock time */
> >  	eth_timesync_read_time     timesync_read_time;
> >  	/** Set the device clock time */
> > diff --git a/lib/ethdev/ethdev_trace.h b/lib/ethdev/ethdev_trace.h
> > index 3bec87bfdb..e273d5853e 100644
> > --- a/lib/ethdev/ethdev_trace.h
> > +++ b/lib/ethdev/ethdev_trace.h
> > @@ -2183,6 +2183,15 @@ RTE_TRACE_POINT_FP(
> >  	rte_trace_point_emit_int(ret);
> >  )
> >
> > +/* Called in loop in examples/ptpclient */ RTE_TRACE_POINT_FP(
> > +	rte_eth_trace_timesync_adjust_freq,
> > +	RTE_TRACE_POINT_ARGS(uint16_t port_id, int64_t ppm, int ret),
> > +	rte_trace_point_emit_u16(port_id);
> > +	rte_trace_point_emit_i64(ppm);
> > +	rte_trace_point_emit_int(ret);
> > +)
> > +
> >  /* Called in loop in app/test-flow-perf */  RTE_TRACE_POINT_FP(
> >  	rte_flow_trace_create,
> > diff --git a/lib/ethdev/ethdev_trace_points.c
> > b/lib/ethdev/ethdev_trace_points.c
> > index 99e04f5893..a99fec0c1e 100644
> > --- a/lib/ethdev/ethdev_trace_points.c
> > +++ b/lib/ethdev/ethdev_trace_points.c
> > @@ -409,6 +409,9 @@
> >
> RTE_TRACE_POINT_REGISTER(rte_eth_trace_timesync_read_tx_timestamp,
> >  RTE_TRACE_POINT_REGISTER(rte_eth_trace_timesync_adjust_time,
> >  	lib.ethdev.timesync_adjust_time)
> >
> > +RTE_TRACE_POINT_REGISTER(rte_eth_trace_timesync_adjust_freq,
> > +	lib.ethdev.timesync_adjust_freq)
> > +
> >  RTE_TRACE_POINT_REGISTER(rte_eth_trace_timesync_read_time,
> >  	lib.ethdev.timesync_read_time)
> >
> > diff --git a/lib/ethdev/rte_ethdev.c b/lib/ethdev/rte_ethdev.c index
> > f1c658f49e..660eab2f1e 100644
> > --- a/lib/ethdev/rte_ethdev.c
> > +++ b/lib/ethdev/rte_ethdev.c
> > @@ -6310,6 +6310,24 @@ rte_eth_timesync_adjust_time(uint16_t port_id,
> int64_t delta)
> >  	return ret;
> >  }
> >
> > +int
> > +rte_eth_timesync_adjust_freq(uint16_t port_id, int64_t ppm) {
> > +	struct rte_eth_dev *dev;
> > +	int ret;
> > +
> > +	RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV);
> > +	dev = &rte_eth_devices[port_id];
> > +
> > +	if (*dev->dev_ops->timesync_adjust_freq == NULL)
> > +		return -ENOTSUP;
> > +	ret = eth_err(port_id, (*dev->dev_ops->timesync_adjust_freq)(dev,
> > +ppm));
> > +
> > +	rte_eth_trace_timesync_adjust_freq(port_id, ppm, ret);
> > +
> > +	return ret;
> > +}
> > +
> >  int
> >  rte_eth_timesync_read_time(uint16_t port_id, struct timespec
> > *timestamp)  { diff --git a/lib/ethdev/rte_ethdev.h
> > b/lib/ethdev/rte_ethdev.h index 548fada1c7..c3587089b9 100644
> > --- a/lib/ethdev/rte_ethdev.h
> > +++ b/lib/ethdev/rte_ethdev.h
> > @@ -5297,6 +5297,26 @@ int
> rte_eth_timesync_read_tx_timestamp(uint16_t port_id,
> >   */
> >  int rte_eth_timesync_adjust_time(uint16_t port_id, int64_t delta);
> >
> > +/**
> > + * Adjust the clock increment rate on an Ethernet device.
> > + *
> > + * This is usually used in conjunction with other Ethdev timesync
> > +functions to
> > + * synchronize the device time using the IEEE1588/802.1AS protocol.
> > + *
> > + * @param port_id
> > + *  The port identifier of the Ethernet device.
> > + * @param ppm
> > + *  Parts per million with 16-bit fractional field
> > + *
> > + * @return
> > + *   - 0: Success.
> > + *   - -ENODEV: The port ID is invalid.
> > + *   - -EIO: if device is removed.
> > + *   - -ENOTSUP: The function is not supported by the Ethernet driver.
> > + */
> > +__rte_experimental
> > +int rte_eth_timesync_adjust_freq(uint16_t port_id, int64_t ppm);
> > +
> >  /**
> >   * Read the time from the timesync clock on an Ethernet device.
> >   *
> > diff --git a/lib/ethdev/version.map b/lib/ethdev/version.map index
> > 1669055ca5..199480ef07 100644
> > --- a/lib/ethdev/version.map
> > +++ b/lib/ethdev/version.map
> > @@ -325,6 +325,9 @@ EXPERIMENTAL {
> >  	rte_flow_template_table_resizable;
> >  	rte_flow_template_table_resize;
> >  	rte_flow_template_table_resize_complete;
> > +
> > +	# added in 24.11
> > +	rte_eth_timesync_adjust_freq;
> >  };
> >
> >  INTERNAL {