1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Intel Corporation. 3 4Service Cores Sample Application 5================================ 6 7The service cores sample application demonstrates the service cores capabilities 8of DPDK. The service cores infrastructure is part of the DPDK EAL, and allows 9any DPDK component to register a service. A service is a work item or task, that 10requires CPU time to perform its duty. 11 12This sample application registers 5 dummy services. These 5 services are used 13to show how the service_cores API can be used to orchestrate these services to 14run on different service lcores. This orchestration is done by calling the 15service cores APIs, however the sample application introduces a "profile" 16concept to contain the service mapping details. Note that the profile concept 17is application specific, and not a part of the service cores API. 18 19 20Compiling the Application 21------------------------- 22 23To compile the sample application see :doc:`compiling`. 24 25The application is located in the ``service_cores`` sub-directory. 26 27Running the Application 28----------------------- 29 30To run the example, just execute the binary. Since the application dynamically 31adds service cores in the application code itself, there is no requirement to 32pass a service core-mask as an EAL argument at startup time. 33 34.. code-block:: console 35 36 $ ./<build_dir>/examples/dpdk-service_cores 37 38 39Explanation 40----------- 41 42The following sections provide some explanation of code focusing on 43registering applications from an applications point of view, and modifying the 44service core counts and mappings at runtime. 45 46 47Registering a Service 48~~~~~~~~~~~~~~~~~~~~~ 49 50The following code section shows how to register a service as an application. 51Note that the service component header must be included by the application in 52order to register services: ``rte_service_component.h``, in addition 53to the ordinary service cores header ``rte_service.h`` which provides 54the runtime functions to add, remove and remap service cores. 55 56.. code-block:: c 57 58 struct rte_service_spec service = { 59 .name = "service_name", 60 }; 61 int ret = rte_service_component_register(services, &id); 62 if (ret) 63 return -1; 64 65 /* set the service itself to be ready to run. In the case of 66 * ethdev, eventdev etc PMDs, this will be set when the 67 * appropriate configure or setup function is called. 68 */ 69 rte_service_component_runstate_set(id, 1); 70 71 /* Collect statistics for the service */ 72 rte_service_set_stats_enable(id, 1); 73 74 /* The application sets the service to running state. Note that this 75 * function enables the service to run - while the 'component' version 76 * of this function (as above) marks the service itself as ready */ 77 ret = rte_service_runstate_set(id, 1); 78 79 80Controlling A Service Core 81~~~~~~~~~~~~~~~~~~~~~~~~~~ 82 83This section demonstrates how to add a service core. The ``rte_service.h`` 84header file provides the functions for dynamically adding and removing cores. 85The APIs to add and remove cores use lcore IDs similar to existing DPDK 86functions. 87 88These are the functions to start a service core, and have it run a service: 89 90.. code-block:: c 91 92 /* the lcore ID to use as a service core */ 93 uint32_t service_core_id = 7; 94 ret = rte_service_lcore_add(service_core_id); 95 if(ret) 96 return -1; 97 98 /* service cores are in "stopped" state when added, so start it */ 99 ret = rte_service_lcore_start(service_core_id); 100 if(ret) 101 return -1; 102 103 /* map a service to the service core, causing it to run the service */ 104 uint32_t service_id; /* ID of a registered service */ 105 uint32_t enable = 1; /* 1 maps the service, 0 unmaps */ 106 ret = rte_service_map_lcore_set(service_id, service_core_id, enable); 107 if(ret) 108 return -1; 109 110 111Removing A Service Core 112~~~~~~~~~~~~~~~~~~~~~~~ 113 114To remove a service core, the steps are similar to adding but in reverse order. 115Note that it is not allowed to remove a service core if the service is running, 116and the service-core is the only core running that service (see documentation 117for ``rte_service_lcore_stop`` function for details). 118 119 120Conclusion 121~~~~~~~~~~ 122 123The service cores infrastructure provides DPDK with two main features. The first 124is to abstract away hardware differences: the service core can CPU cycles to 125a software fallback implementation, allowing the application to be abstracted 126from the difference in HW / SW availability. The second feature is a flexible 127method of registering functions to be run, allowing the running of the 128functions to be scaled across multiple CPUs. 129