On Mon,  8 Sep 2025 16:17:33 +0200
Serhii Iliushyk <sil-plv@napatech.com> wrote:

> diff --git a/doc/guides/nics/ntnic.rst b/doc/guides/nics/ntnic.rst
> index b3d6ad70c1..a173eaa2ac 100644
> --- a/doc/guides/nics/ntnic.rst
> +++ b/doc/guides/nics/ntnic.rst
> @@ -185,3 +185,115 @@ There are list of characteristics that age timeout action has:
>  - after flow is aged-out it's not automatically deleted;
>  - aged-out flow can be updated with ``flow update`` command,
>    and its aged-out status will be reverted;
> +
> +Service API
> +-----------
> +
> +**nthw_service_add**
> +**nthw_service_del**
> +**nthw_service_get_info**
> +
> +The NTNIC PMD provides a service API that allows applications to configure services
> +
> +The services are responsible for handling the vital functionality of the NTNIC PMD:
> +
> +- **FLM Update**: is responsible for creating and destroying flows;
> +- **Statistics**: is responsible for collecting statistics;
> +- **Port event**: is responsible for handling port events: aging, port load, and flow load;
> +- **Adapter monitor** is responsible for link control;
> +
> +**NOTE**: Use next EAL options to configure set service cores
> +   * -s SERVICE COREMASK Hexadecimal bitmask of cores to be used as service cores;
> +   * -S SERVICE CORELIST List of cores to run services on;
> +
> +**NOTE**: **At least 5 lcores must be reserved** for the ntnic services by EAL options. above.
> +
> +For example
> +
> +.. code-block:: console
> +
> +   dpdk-testpmd -S 8,9,10,11,12
> +
> +The PMD registers each service during initialization by function:
> +
> +.. code-block:: c
> +
> +   int nthw_service_add(struct rte_service_spec *srv_spec, const enum rte_ntnic_service_tag tag)
> +
> +and unregistered by the PMD during deinitialization by the function:
> +
> +.. code-block:: c
> +
> +   int nthw_service_del(const enum rte_ntnic_service_tag tag)
> +
> +The service info may be retrieved by function:
> +
> +.. code-block:: c
> +
> +   struct nt_service *nthw_service_get_info(const enum rte_ntnic_service_tag tag)
> +
> +The service info includes the service ID, assigned lcore, and initialization state.
> +
> +Service API for user applications
> +---------------------------------
> +**rte_pmd_ntnic_service_set_lcore**
> +**rte_pmd_ntnic_service_get_id**
> +
> +The exported service API is available for applications to configure the services.
> +
> +By API function:
> +
> +.. code-block:: c
> +
> +   int rte_pmd_ntnic_service_set_lcore(enum rte_ntnic_service_tag tag, uint32_t lcore_id)
> +
> +For example to assign lcores 8,9,10,11,12 to the services, the application can use:
> +
> +.. code-block:: c
> +
> +   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_STAT, 8);
> +   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_ADAPTER_MON, 9);
> +   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_PORT_0_EVENT, 10);
> +   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_PORT_1_EVENT,11);
> +   rte_pmd_ntnic_service_set_lcore(RTE_NTNIC_SERVICE_FLM_UPDATE, 12);
> +
> +The API will automatically lcore to service core list and map the service to the lcore.
> +
> +.. note:: Use `rte_service_lcore_start` to start the lcore after mapping it to the service.
> +
> +Each service has its own tag to identify it.
> +
> +.. code-block:: c
> +
> +   enum rte_ntnic_service_tag {
> +      RTE_NTNIC_SERVICE_FLM_UPDATE = 0,
> +      RTE_NTNIC_SERVICE_STAT = 1,
> +      RTE_NTNIC_SERVICE_PORT_0_EVENT = 2,
> +      RTE_NTNIC_SERVICE_PORT_1_EVENT = 3,
> +      RTE_NTNIC_SERVICE_ADAPTER_MON = 4,
> +      RTE_NTNIC_SERVICE_MAX
> +   };
> +
> +The application may use next API function to retrieve the service id:
> +
> +.. code-block:: c
> +
> +  int rte_pmd_ntnic_service_get_id(enum rte_ntnic_service_tag tag);
> +
> +
> +For example, to enable statistics for flm_update service, the application can use:
> +
> +.. code-block:: c
> +
> +   int flm_update_id = rte_pmd_ntnic_service_get_id(RTE_NTNIC_SERVICE_FLM_UPDATE);
> +   rte_service_set_stats_enable(flm_update_id, 1);
> +
> +All other manipulations with the service can be done with the service ID and rte_service* API.
> +
> +To use the service API, an application must have included the header file:
> +
> +.. code-block:: c
> +
> +   #include <rte_pmd_ntnic.h>
> +
> +And linked with the library: `https://linkprotect.cudasvc.com/url?a=https%3a%2f%2flibrte_net_ntnic.so&c=E,1,Y0L6xj9VNKcZFYqAqRe-8zIt_7rMPD4KOWRMISoqVC_WIz7nsVj8xFm2zsiLl9o97z8bgkUxWD4uEioCtxO_S3AIO5hqm9inj17-Hase1qRv2byMWjlBinC_4A,,&typo=1` or `librte_net_ntnic.a` for static linking.

It is not clear what happens if application does not use the driver API?
What happens "out of the box" with OVS and VPP?

The fact that it requires special driver API's shows that there is a missing
feature in the service lcore library. Should be able to do this stuff through that
API. But that is not your problem, and doesn't need solving in this set.

Hi Stephen!

If this option is passed, then the ntnic services will be started with the function rte_service_start_with_defaults  https://git.dpdk.org/dpdk/tree/lib/eal/linux/eal.c#n1259 inside of the rte_eal_init, since they are already registered after rte_bus_probe.

That list does not include handling service cores, so a small extension for the DPDK plugin is necessary here to support extra EAL option(s).