DPDK: Data Plane Development Kit

18.02.0-rc0
rte_service.h File Reference
#include <stdio.h>
#include <stdint.h>
#include <sys/queue.h>
#include <rte_lcore.h>

Go to the source code of this file.

Macros

#define RTE_SERVICE_CAP_MT_SAFE   (1 << 0)

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_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_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)

Detailed Description

Service functions

The service functionality provided by this header allows a DPDK component to indicate that it requires a function call in order for it to perform its processing.

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 set, the service is capable of having multiple threads run it at the same time.

Definition at line 74 of file rte_service.h.

Function Documentation

uint32_t rte_service_get_count ( void  )
Warning
EXPERIMENTAL: this API may change without prior notice

Return the number of services registered.

The number of services registered can be passed to rte_service_get_by_id, enabling the application to retrieve the specification of each service.

Returns
The number of services registered.
int32_t rte_service_get_by_name ( const char *  name,
uint32_t *  service_id 
)
Warning
EXPERIMENTAL: this API may change without prior notice

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.

Example usage:

uint32_t service_id;
int32_t ret = rte_service_get_by_name("service_X", &service_id);
if (ret) {
// handle error
}
Parameters
nameThe name of the service to retrieve
[out]service_idA pointer to a uint32_t, to be filled in with the id.
Return values
0Success. The service id is provided in service_id.
-EINVALNull service_id pointer provided
-ENODEVNo such service registered
const char* rte_service_get_name ( uint32_t  id)
Warning
EXPERIMENTAL: this API may change without prior notice

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.
int32_t rte_service_probe_capability ( uint32_t  id,
uint32_t  capability 
)
Warning
EXPERIMENTAL: this API may change without prior notice

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.

Return values
1Capability supported by this service instance
0Capability not supported by this service instance
int32_t rte_service_map_lcore_set ( uint32_t  service_id,
uint32_t  lcore,
uint32_t  enable 
)
Warning
EXPERIMENTAL: this API may change without prior notice

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.

If multiple cores are enabled on a service, an atomic is used to ensure that only one cores 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.

Parameters
service_idthe service to apply the lcore to
lcoreThe lcore that will be mapped to service
enableZero to unmap or disable the core, non-zero to enable
Return values
0lcore map updated successfully
-EINVALAn invalid service or lcore was provided.
Examples:
examples/service_cores/main.c.
int32_t rte_service_map_lcore_get ( uint32_t  service_id,
uint32_t  lcore 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Retrieve the mapping of an lcore to a service.

Parameters
service_idthe service to apply the lcore to
lcoreThe lcore that will be mapped to service
Return values
1lcore is mapped to service
0lcore is not mapped to service
-EINVALAn invalid service or lcore was provided.
int32_t rte_service_runstate_set ( uint32_t  id,
uint32_t  runstate 
)
Warning
EXPERIMENTAL: this API may change without prior notice

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.

Parameters
idThe id of the service
runstateThe run state to apply to the service
Return values
0The service was successfully started
-EINVALInvalid service id
Examples:
examples/eventdev_pipeline_sw_pmd/main.c, and examples/service_cores/main.c.
int32_t rte_service_runstate_get ( uint32_t  id)
Warning
EXPERIMENTAL: this API may change without prior notice

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.

Return values
1Service is running
0Service is stopped
-EINVALInvalid service id
int32_t rte_service_set_runstate_mapped_check ( uint32_t  id,
int32_t  enable 
)
Warning
EXPERIMENTAL: this API may change without prior notice

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.

Parameters
idThe id of the service to set the check on
enableWhen zero, the check is disabled. Non-zero enables the check.
Return values
0Success
-EINVALInvalid service ID
Examples:
examples/eventdev_pipeline_sw_pmd/main.c.
int32_t rte_service_run_iter_on_app_lcore ( uint32_t  id,
uint32_t  serialize_multithread_unsafe 
)
Warning
EXPERIMENTAL: this API may change without prior notice

This function runs a service callback from a non-service lcore.

This function is designed to enable gradual porting to service cores, and to enable unit tests to verify a service behaves as expected.

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.
  • 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.
Parameters
idThe ID of the service to run
serialize_multithread_unsafeThis 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 that any thread calling this function MUST be a DPDK EAL thread, as the rte_lcore_id function is used to access internal data structures.

Return values
0Service was run on the calling thread successfully
-EBUSYAnother lcore is executing the service, and it is not a multi-thread safe service, so the service was not run on this lcore
-ENOEXECService is not in a run-able state
-EINVALInvalid service id
Examples:
examples/eventdev_pipeline_sw_pmd/main.c.
int32_t rte_service_lcore_start ( uint32_t  lcore_id)
Warning
EXPERIMENTAL: this API may change without prior notice

Start a service core.

Starting a core makes the core begin polling. Any services assigned to it will be run as fast as possible.

Return values
0Success
-EINVALFailed to start core. The lcore_id passed in is not currently assigned to be a service core.
Examples:
examples/service_cores/main.c.
int32_t rte_service_lcore_stop ( uint32_t  lcore_id)
Warning
EXPERIMENTAL: this API may change without prior notice

Stop a service core.

Stopping a core makes the core become idle, but remains assigned as a service core.

Return values
0Success
-EINVALInvalid lcore_id provided
-EALREADYAlready stopped core
-EBUSYFailed 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.
Examples:
examples/service_cores/main.c.
int32_t rte_service_lcore_add ( uint32_t  lcore)
Warning
EXPERIMENTAL: this API may change without prior notice

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
0Success
-EBUSYlcore is busy, and not available for service core duty
-EALREADYlcore is already added to the service core list
-EINVALInvalid lcore provided
Examples:
examples/service_cores/main.c.
int32_t rte_service_lcore_del ( uint32_t  lcore)
Warning
EXPERIMENTAL: this API may change without prior notice

Removes lcore from the list of service cores.

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

Return values
0Success
-EBUSYLcore is not stopped, stop service core before removing.
-EINVALfailed to add lcore to service core mask.
Examples:
examples/service_cores/main.c.
int32_t rte_service_lcore_count ( void  )
Warning
EXPERIMENTAL: this API may change without prior notice

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  )
Warning
EXPERIMENTAL: this API may change without prior notice

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.

Return values
0Success
int32_t rte_service_set_stats_enable ( uint32_t  id,
int32_t  enable 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Enable or disable statistics collection for service.

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

Parameters
idThe service to enable statistics gathering on.
enableZero to disable statistics, non-zero to enable.
Return values
0Success
-EINVALInvalid service pointer passed
Examples:
examples/service_cores/main.c.
int32_t rte_service_lcore_list ( uint32_t  array[],
uint32_t  n 
)
Warning
EXPERIMENTAL: this API may change without prior notice

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
[out]arrayAn array of at least rte_service_lcore_count items. If statically allocating the buffer, use RTE_MAX_LCORE.
[out]nThe size of array.
Return values
>=0Number of service cores that have been populated in the array
-ENOMEMThe 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)
Warning
EXPERIMENTAL: this API may change without prior notice

Get the numer of services running on the supplied lcore.

Parameters
lcoreId of the service core.
Return values
>=0Number of services registered to this core.
-EINVALInvalid lcore provided
-ENOTSUPThe provided lcore is not a service core.
int32_t rte_service_dump ( FILE *  f,
uint32_t  id 
)
Warning
EXPERIMENTAL: this API may change without prior notice

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

Return values
0Statistics have been successfully dumped
-EINVALInvalid service id provided
Examples:
examples/service_cores/main.c.