rte_service.h(3)

📦
version 25.11.3 · 9 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

rte_service.h — bestie, it's the DPDK Service functions header, straight out of the Library Functions Manual (that's your section 3, iykyk). Slash in, and let's get you caught up.

🌸 SYNOPSIS 🌸

#include <stdio.h>
#include <stdint.h>
#include <rte_config.h>
#include <rte_lcore.h>

✨ Macros ✨

#define RTE_SERVICE_CAP_MT_SAFE   (1 << 0)
#define RTE_SERVICE_ATTR_CYCLES   0
#define RTE_SERVICE_ATTR_CALL_COUNT   1
#define RTE_SERVICE_ATTR_IDLE_CALL_COUNT   2
#define RTE_SERVICE_ATTR_ERROR_CALL_COUNT   3
#define RTE_SERVICE_LCORE_ATTR_LOOPS   0
#define RTE_SERVICE_LCORE_ATTR_CYCLES   1

✨ Functions ✨

uint32_t rte_service_get_count (void)
int32_t rte_service_get_by_name (const char *name, uint32_t *service_id)
const char * rte_service_get_name (uint32_t id)
int32_t rte_service_probe_capability (uint32_t id, uint32_t capability)
int32_t rte_service_map_lcore_set (uint32_t service_id, uint32_t lcore,
    uint32_t enable)
int32_t rte_service_map_lcore_get (uint32_t service_id, uint32_t lcore)
int32_t rte_service_runstate_set (uint32_t id, uint32_t runstate)
int32_t rte_service_runstate_get (uint32_t id)
int32_t rte_service_may_be_active (uint32_t id)
int32_t rte_service_set_runstate_mapped_check (uint32_t id, int32_t
    enable)
int32_t rte_service_run_iter_on_app_lcore (uint32_t id, uint32_t
    serialize_multithread_unsafe)
int32_t rte_service_lcore_start (uint32_t lcore_id)
int32_t rte_service_lcore_stop (uint32_t lcore_id)
int32_t rte_service_lcore_may_be_active (uint32_t lcore_id)
int32_t rte_service_lcore_add (uint32_t lcore)
int32_t rte_service_lcore_del (uint32_t lcore)
int32_t rte_service_lcore_count (void)
int32_t rte_service_lcore_reset_all (void)
int32_t rte_service_set_stats_enable (uint32_t id, int32_t enable)
int32_t rte_service_lcore_list (uint32_t array[], uint32_t n)
int32_t rte_service_lcore_count_services (uint32_t lcore)
int32_t rte_service_dump (FILE *f, uint32_t id)
int32_t rte_service_attr_get (uint32_t id, uint32_t attr_id, uint64_t
    *attr_value)
int32_t rte_service_attr_reset_all (uint32_t id)
int32_t rte_service_lcore_attr_get (uint32_t lcore, uint32_t attr_id,
    uint64_t *attr_value)
int32_t rte_service_lcore_attr_reset_all (uint32_t lcore)

🦋 Detailed Description 🦋

Service functions

okay so the tea ☕: the service functionality in this header is what lets a DPDK component basically raise its hand 🙋‍♀️ and say "hey, I need a function call to happen in order for me to do my processing." Like, that's the whole vibe.

An example usage of this functionality would be a component that registers a service to perform a particular packet processing duty — for example the eventdev software PMD. At startup the application requests all services that have been registered, and the cores in the service-coremask run the required services. The EAL removes these number of cores from the available runtime cores, and dedicates them to performing service-core workloads. The application has access to the remaining lcores as normal.

Definition in file rte_service.h.

🎀 Macro Definition Documentation 🎀

🌟 #define RTE_SERVICE_CAP_MT_SAFE (1 << 0)

When this is set, the service is capable of having multiple threads run it at the same time. multi-threaded queen behavior, literally. 👑

Definition at line 46 of file rte_service.h.

🌟 #define RTE_SERVICE_ATTR_CYCLES 0

Returns the number of cycles that this service has consumed. Only cycles spent in non-idle calls (i.e., calls not returning -EAGAIN) count. so the lazy little -EAGAIN naps? not invited to the party. ✋

Definition at line 381 of file rte_service.h.

🌟 #define RTE_SERVICE_ATTR_CALL_COUNT 1

Returns the total number of invocations of this service function (regardless of return value). every single time it got called, no matter how it went. 💅

Definition at line 387 of file rte_service.h.

🌟 #define RTE_SERVICE_ATTR_IDLE_CALL_COUNT 2

Returns the number of invocations of this service function where the service reported having not performed any useful work (i.e., returned -EAGAIN). the "no thoughts, head empty" counter 🙈.

Definition at line 394 of file rte_service.h.

🌟 #define RTE_SERVICE_ATTR_ERROR_CALL_COUNT 3

Returns the number of invocations of this service function where the service reported an error (i.e., the return value was neither 0 nor -EAGAIN). not me checking this one first 😭.

Definition at line 401 of file rte_service.h.

🌟 #define RTE_SERVICE_LCORE_ATTR_LOOPS 0

Returns the number of times the service runner has looped. go lil runner go 🏃‍♀️

Definition at line 424 of file rte_service.h.

🌟 #define RTE_SERVICE_LCORE_ATTR_CYCLES 1

Returns the total number of cycles that the lcore has spent on running services. Only non-idle calls (i.e., calls not returning -EAGAIN) count toward this total. same energy as above — idle calls simply do not get counted ✨.

Definition at line 431 of file rte_service.h.

💜 Function Documentation 💜

🌈 uint32_t rte_service_get_count (void )

Return the number of services registered.

Returns

  • The number of services registered. that's it, that's the number bestie 🫶

🌈 int32_t rte_service_get_by_name (const char * name, uint32_t * service_id)

Return the id of a service by name.

This function provides the id of the service using the service name as lookup key. The service id is to be passed to other functions in the rte_service_* API. like a little name-to-id translation service, serving looks 💅

Example usage:

uint32_t service_id;
int32_t ret = rte_service_get_by_name("service_X", &service_id);
if (ret) {
        // handle error
}

Parameters

  • name — the name of the service to retrieve
  • service_id — a pointer to a uint32_t, to be filled in with the id.

Return values

  • 0 — Success. The service id is provided in service_id.
  • -EINVAL — Null service_id pointer provided
  • -ENODEV — No such service registered

🌈 const char * rte_service_get_name (uint32_t id)

Return the name of the service.

Returns

  • A pointer to the name of the service. The returned pointer remains in ownership of the service, and the application must not free it. so do NOT free() it, I'm so serious 😭

🌈 int32_t rte_service_probe_capability (uint32_t id, uint32_t capability)

Check if a service has a specific capability.

This function returns if service has implements capability. See RTE_SERVICE_CAP_* defines for a list of valid capabilities. vibe check on the capability, basically ✨

Return values

  • 1 — Capability supported by this service instance
  • 0 — Capability not supported by this service instance

🌈 int32_t rte_service_map_lcore_set (uint32_t service_id, uint32_t lcore, uint32_t enable)

Map or unmap a lcore to a service.

Each core can be added or removed from running a specific service. This function enables or disables lcore to run service_id. it's giving "you're in, you're out" 🚪

If multiple cores are enabled on a service, a lock is used to ensure that only one core runs the service at a time. The exception to this is when a service indicates that it is multi-thread safe by setting the capability called RTE_SERVICE_CAP_MT_SAFE. With the multi-thread safe capability set, the service function can be run on multiple threads at the same time.

If the service is known to be mapped to a single lcore, setting the capability of the service to RTE_SERVICE_CAP_MT_SAFE can achieve better performance by avoiding the use of lock. less locking = more slay 🔥

Parameters

  • service_id — the service to apply the lcore to
  • lcore — the lcore that will be mapped to service
  • enable — Zero to unmap or disable the core, non-zero to enable

Return values

  • 0 — lcore map updated successfully
  • -EINVAL — An invalid service or lcore was provided.

🌈 int32_t rte_service_map_lcore_get (uint32_t service_id, uint32_t lcore)

Retrieve the mapping of an lcore to a service. like, are they even together? 👀

Parameters

  • service_id — the service to apply the lcore to
  • lcore — the lcore that will be mapped to service

Return values

  • 1 — lcore is mapped to service
  • 0 — lcore is not mapped to service
  • -EINVAL — An invalid service or lcore was provided.

🌈 int32_t rte_service_runstate_set (uint32_t id, uint32_t runstate)

Set the runstate of the service.

Each service is either running or stopped. Setting a non-zero runstate enables the service to run, while setting runstate zero disables it. binary choice, main character energy 💅

Parameters

  • id — the id of the service
  • runstate — the run state to apply to the service

Return values

  • 0 — The service was successfully started
  • -EINVAL — Invalid service id

🌈 int32_t rte_service_runstate_get (uint32_t id)

Get the runstate for the service with id. See rte_service_runstate_set() for details of runstates. A service can call this function to ensure that the application has indicated that it will receive CPU cycles. Either a service-core is mapped (default case), or the application has explicitly disabled the check that a service-cores is mapped to the service and takes responsibility to run the service manually using the available function rte_service_run_iter_on_app_lcore() to do so. it's the "am I actually gonna get CPU time or are you playing with me" check 😭

Return values

  • 1 — Service is running
  • 0 — Service is stopped
  • -EINVAL — Invalid service id

🌈 int32_t rte_service_may_be_active (uint32_t id)

This function returns whether the service may be currently executing on at least one lcore, or definitely is not. This function can be used to determine if, after setting the service runstate to stopped, the service is still executing a service lcore.

Care must be taken if calling this function when the service runstate is running, since the result of this function may be incorrect by the time the function returns due to service cores running in parallel. bestie the answer can be stale before you even read it, that's the racing-for-you 😭

Return values

  • 1 — Service may be running on one or more lcores
  • 0 — Service is not running on any lcore
  • -EINVAL — Invalid service id

🌈 int32_t rte_service_set_runstate_mapped_check (uint32_t id, int32_t enable)

Enable or disable the check for a service-core being mapped to the service. An application can disable the check when takes the responsibility to run a service itself using rte_service_run_iter_on_app_lcore(). taking matters into your own hands ✨

Parameters

  • id — the id of the service to set the check on
  • enable — When zero, the check is disabled. Non-zero enables the check.

Return values

  • 0 — Success
  • -EINVAL — Invalid service ID

🌈 int32_t rte_service_run_iter_on_app_lcore (uint32_t id, uint32_t serialize_multithread_unsafe)

This function runs a service callback from a non-service lcore. rogue lcore behavior, love that for you 💅

This function is designed to enable gradual porting to service cores, and to enable unit tests to verify a service behaves as expected. baby steps, we love a glow-up into service cores 🌱

When called, this function ensures that the service identified by id is safe to run on this lcore. Multi-thread safe services are invoked even if other cores are simultaneously running them as they are multi-thread safe.

Multi-thread unsafe services are handled depending on the variable serialize_multithread_unsafe:

  • When set, the function will check if a service is already being invoked on another lcore, refusing to run it and returning -EBUSY. nope, not touching it, someone else has the aux cord 🔌
  • When zero, the application takes responsibility to ensure that the service indicated by id is not going to be invoked by another lcore. This setting avoids atomic operations, so is likely to be more performant. you're on your own for safety here, but it's faster bestie.

more coming in part 2, don't go anywhere 🫶✨

okay so continuing from where we left off, we were deep in the function tea ☕ and now we're looking at the parameters and return values for that one function we were just talking about. no need to re-intro, let's get into it 💅

Parameters

  • id — The ID of the service to run
  • serialize_multithread_unsafe — This parameter indicates to the service cores library if it is required to use atomics to serialize access to mult-thread unsafe services. As there is an overhead in using atomics, applications can choose to enable or disable this feature
Note: any thread calling this function MUST be a DPDK EAL thread, as the rte_lcore_id() function is used to access internal data structures. no cap, this is important bestie 🫶

Return values

  • 0 — Service was run on the calling thread successfully ✨
  • -EBUSY — Another lcore is executing the service, and it is not a multi-thread safe service, so the service was not run on this lcore 😤
  • -ENOEXEC — Service is not in a run-able state 💀
  • -EINVAL — Invalid service id 🙈

int32_t rte_service_lcore_start (uint32_t lcore_id)

Start a service core. 👑

Starting a core makes the core begin polling. Any services assigned to it will be run as fast as possible. The application must ensure that the lcore is in a launchable state: e.g. call rte_eal_lcore_wait() on the lcore_id before calling this function.

Return values

  • 0 — Success 🌟
  • -EINVAL — Failed to start core. The lcore_id passed in is not currently assigned to be a service core. ❌

int32_t rte_service_lcore_stop (uint32_t lcore_id)

Stop a service core. 🛑

Stopping a core makes the core become idle, but remains assigned as a service core. Note that the service lcore thread may not have returned from the service it is running when this API returns.

The rte_service_lcore_may_be_active() API can be used to check if the service lcore is * still active.

Return values

  • 0 — Success 🌈
  • -EINVAL — Invalid lcore_id provided 😬
  • -EALREADY — Already stopped core 🛑
  • -EBUSY — Failed to stop core, as it would cause a service to not be run, as this is the only core currently running the service. The application must stop the service first, and then stop the lcore. 🚨

int32_t rte_service_lcore_may_be_active (uint32_t lcore_id)

Reports if a service lcore is currently running. 👀

This function returns if the core has finished service cores code, and has returned to EAL control. If rte_service_lcore_stop() has been called but the lcore has not returned to EAL yet, it might be required to wait and call this function again. The amount of time to wait before the core returns depends on the duration of the services being run. ⏳

Return values

  • 0 — Service thread is not active, and lcore has been returned to EAL. 😴
  • 1 — Service thread is in the service core polling loop. 🔄
  • -EINVAL — Invalid lcore_id provided. ❌

int32_t rte_service_lcore_add (uint32_t lcore)

Adds lcore to the list of service cores. ➕

This functions can be used at runtime in order to modify the service core mask.

Return values

  • 0 — Success ✨
  • -EBUSY — lcore is busy, and not available for service core duty 😵
  • -EALREADY — lcore is already added to the service core list 😅
  • -EINVAL — Invalid lcore provided 🙅

int32_t rte_service_lcore_del (uint32_t lcore)

Removes lcore from the list of service cores. ➖

This can fail if the core is not stopped, see rte_service_core_stop().

Return values

  • 0 — Success 💖
  • -EBUSY — Lcore is not stopped, stop service core before removing. 🛑
  • -EINVAL — failed to add lcore to service core mask. 😭

int32_t rte_service_lcore_count (void )

Retrieve the number of service cores currently available. 🔢

This function returns the integer count of service cores available. The service core count can be used in mapping logic when creating mappings from service cores to services.

See rte_service_lcore_list() for details on retrieving the lcore_id of each service core.

Returns

  • The number of service cores currently configured. 🎯

int32_t rte_service_lcore_reset_all (void )

Resets all service core mappings. This does not remove the service cores from duty, just unmaps all services / cores, and stops() the service cores. The runstate of services is not modified. 🔄

The cores that are stopped with this call, are in WAIT state. ⏸️

Return values

  • 0 — Success 🌟

int32_t rte_service_set_stats_enable (uint32_t id, int32_t enable)

Enable or disable statistics collection for service. 📊

This function enables per core, per-service cycle count collection.

Parameters

  • id — The service to enable statistics gathering on.
  • enable — Zero to disable statistics, non-zero to enable.

Return values

  • 0 — Success ✅
  • -EINVAL — Invalid service pointer passed ❌

int32_t rte_service_lcore_list (uint32_t array[], uint32_t n)

Retrieve the list of currently enabled service cores. 📋

This function fills in an application supplied array, with each element indicating the lcore_id of a service core.

Adding and removing service cores can be performed using rte_service_lcore_add() and rte_service_lcore_del().

Parameters

  • array — An array of at least rte_service_lcore_count() items. If statically allocating the buffer, use RTE_MAX_LCORE.
  • n — The size of array.

Return values

  • >=0 — Number of service cores that have been populated in the array 🌈
  • -ENOMEM — The provided array is not large enough to fill in the service core list. No items have been populated, call this function with a size of at least rte_service_core_count() items. 😵

int32_t rte_service_lcore_count_services (uint32_t lcore)

Get the number of services running on the supplied lcore. 🔍

Parameters

  • lcore — Id of the service core.

Return values

  • >=0 — Number of services registered to this core. 🎉
  • -EINVAL — Invalid lcore provided ❌
  • -ENOTSUP — The provided lcore is not a service core. 🚫

int32_t rte_service_dump (FILE * f, uint32_t id)

Dumps any information available about the service. When id is UINT32_MAX, this function dumps info for all services. 🗑️

Return values

  • 0 — Statistics have been successfully dumped 💅
  • -EINVAL — Invalid service id provided ❌

int32_t rte_service_attr_get (uint32_t id, uint32_t attr_id, uint64_t * attr_value)

Get an attribute from a service. 🔎

Return values

  • 0 — Success, the attribute value has been written to attr_value. ✨
  • -EINVAL — Invalid id, attr_id or attr_value was NULL. 😭

int32_t rte_service_attr_reset_all (uint32_t id)

Reset all attribute values of a service. 🔄

Parameters

  • id — The service to reset all statistics of

Return values

  • 0 — Successfully reset attributes ✅
  • -EINVAL — Invalid service id provided ❌

int32_t rte_service_lcore_attr_get (uint32_t lcore, uint32_t attr_id, uint64_t * attr_value)

Get an attribute from a service core. 🧐

Parameters

  • lcore — Id of the service core.
  • attr_id — Id of the attribute to be retrieved.
  • attr_value — Pointer to storage in which to write retrieved value.

Return values

  • 0 — Success, the attribute value has been written to attr_value. 💖
  • -EINVAL — Invalid lcore, attr_id or attr_value was NULL. 😬
  • -ENOTSUP — lcore is not a service core. 🚫

int32_t rte_service_lcore_attr_reset_all (uint32_t lcore)

Reset all attribute values of a service core. ♻️

Parameters

  • lcore — The service core to reset all the statistics of

Return values

  • 0 — Successfully reset attributes ✅
  • -EINVAL — Invalid service id provided ❌
  • -ENOTSUP — lcore is not a service core. 🚫

Author

Generated automatically by Doxygen for DPDK from the source code. 🤖

and that's a wrap bestie! this page was served fresh from DPDK version 25.11.3, rte_service.h(3), and auto-generated by Doxygen. stay slaying those service cores 💅💖✨

📦 where this page comes from