uint32_trte_service_get_count(void)
Return the number of services registered.
Returns
The number of services registered.
int32_trte_service_get_by_name(constchar*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.
Example usage:
uint32_t service_id;
int32_t ret = rte_service_get_by_name("service_X", &service_id);
if (ret) {
// handle error
}
Parametersname The name of the service to retrieve
service_id A pointer to a uint32_t, to be filled in with the id.
Returnvalues0 Success. The service id is provided in service_id.
-EINVAL Null service_id pointer provided
-ENODEV No such service registered
constchar*rte_service_get_name(uint32_tid)
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_trte_service_probe_capability(uint32_tid,uint32_tcapability)
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.
Returnvalues1 Capability supported by this service instance
0 Capability not supported by this service instance
int32_trte_service_map_lcore_set(uint32_tservice_id,uint32_tlcore,uint32_tenable)
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, 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.
Parametersservice_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
Returnvalues0 lcore map updated successfully
-EINVAL An invalid service or lcore was provided.
int32_trte_service_map_lcore_get(uint32_tservice_id,uint32_tlcore)
Retrieve the mapping of an lcore to a service.
Parametersservice_id the service to apply the lcore to
lcore The lcore that will be mapped to service
Returnvalues1 lcore is mapped to service
0 lcore is not mapped to service
-EINVAL An invalid service or lcore was provided.
int32_trte_service_runstate_set(uint32_tid,uint32_trunstate)
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.
Parametersid The id of the service
runstate The run state to apply to the service
Returnvalues0 The service was successfully started
-EINVAL Invalid service id
int32_trte_service_runstate_get(uint32_tid)
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.
Returnvalues1 Service is running
0 Service is stopped
-EINVAL Invalid service id
int32_trte_service_may_be_active(uint32_tid)
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.
Returnvalues1 Service may be running on one or more lcores
0 Service is not running on any lcore
-EINVAL Invalid service id
int32_trte_service_set_runstate_mapped_check(uint32_tid,int32_tenable)
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().
Parametersid The id of the service to set the check on
enable When zero, the check is disabled. Non-zero enables the check.
Returnvalues0 Success
-EINVAL Invalid service ID
int32_trte_service_run_iter_on_app_lcore(uint32_tid,uint32_tserialize_multithread_unsafe)
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.
Parametersid 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 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.
Returnvalues0 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_trte_service_lcore_start(uint32_tlcore_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.
Returnvalues0 Success
-EINVAL Failed to start core. The lcore_id passed in is not currently assigned to be a service core.
int32_trte_service_lcore_stop(uint32_tlcore_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.
Returnvalues0 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_trte_service_lcore_may_be_active(uint32_tlcore_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.
Returnvalues0 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_trte_service_lcore_add(uint32_tlcore)
Adds lcore to the list of service cores.
This functions can be used at runtime in order to modify the service core mask.
Returnvalues0 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_trte_service_lcore_del(uint32_tlcore)
Removes lcore from the list of service cores.
This can fail if the core is not stopped, see rte_service_core_stop().
Returnvalues0 Success
-EBUSY Lcore is not stopped, stop service core before removing.
-EINVAL failed to add lcore to service core mask.
int32_trte_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_trte_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.
Returnvalues0 Success
int32_trte_service_set_stats_enable(uint32_tid,int32_tenable)
Enable or disable statistics collection for service.
This function enables per core, per-service cycle count collection.
Parametersid The service to enable statistics gathering on.
enable Zero to disable statistics, non-zero to enable.
Returnvalues0 Success
-EINVAL Invalid service pointer passed
int32_trte_service_lcore_list(uint32_tarray[],uint32_tn)
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().
Parametersarray An array of at least rte_service_lcore_count() items. If statically allocating the buffer, use
RTE_MAX_LCORE.
n The size of array.
Returnvalues>=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_trte_service_lcore_count_services(uint32_tlcore)
Get the number of services running on the supplied lcore.
Parameterslcore Id of the service core.
Returnvalues>=0 Number of services registered to this core.
-EINVAL Invalid lcore provided
-ENOTSUP The provided lcore is not a service core.
int32_trte_service_dump(FILE*f,uint32_tid)
Dumps any information available about the service. When id is UINT32_MAX, this function dumps info for
all services.
Returnvalues0 Statistics have been successfully dumped
-EINVAL Invalid service id provided
int32_trte_service_attr_get(uint32_tid,uint32_tattr_id,uint64_t*attr_value)
Get an attribute from a service.
Returnvalues0 Success, the attribute value has been written to attr_value. -EINVAL Invalid id, attr_id or
attr_value was NULL.
int32_trte_service_attr_reset_all(uint32_tid)
Reset all attribute values of a service.
Parametersid The service to reset all statistics of
Returnvalues0 Successfully reset attributes -EINVAL Invalid service id provided
int32_trte_service_lcore_attr_get(uint32_tlcore,uint32_tattr_id,uint64_t*attr_value)
Get an attribute from a service core.
Parameterslcore 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.
Returnvalues0 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_trte_service_lcore_attr_reset_all(uint32_tlcore)
Reset all attribute values of a service core.
Parameterslcore The service core to reset all the statistics of
Returnvalues0 Successfully reset attributes -EINVAL Invalid service id provided -ENOTSUP lcore is not a service
core.
Install Now
PNG Icons