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 23#. Go to the example directory: 24 25 .. code-block:: console 26 27 export RTE_SDK=/path/to/rte_sdk 28 cd ${RTE_SDK}/examples/service_cores 29 30#. Set the target (a default target is used if not specified). For example: 31 32 .. code-block:: console 33 34 export RTE_TARGET=x86_64-native-linuxapp-gcc 35 36 See the *DPDK Getting Started* Guide for possible RTE_TARGET values. 37 38#. Build the application: 39 40 .. code-block:: console 41 42 make 43 44Running the Application 45----------------------- 46 47To run the example, just execute the binary. Since the application dynamically 48adds service cores in the application code itself, there is no requirement to 49pass a service core-mask as an EAL argument at startup time. 50 51.. code-block:: console 52 53 $ ./build/service_cores 54 55 56Explanation 57----------- 58 59The following sections provide some explanation of code focusing on 60registering applications from an applications point of view, and modifying the 61service core counts and mappings at runtime. 62 63 64Registering a Service 65~~~~~~~~~~~~~~~~~~~~~ 66 67The following code section shows how to register a service as an application. 68Note that the service component header must be included by the application in 69order to register services: ``rte_service_component.h``, in addition 70to the ordinary service cores header ``rte_service.h`` which provides 71the runtime functions to add, remove and remap service cores. 72 73.. code-block:: c 74 75 struct rte_service_spec service = { 76 .name = "service_name", 77 }; 78 int ret = rte_service_component_register(services, &id); 79 if (ret) 80 return -1; 81 82 /* set the service itself to be ready to run. In the case of 83 * ethdev, eventdev etc PMDs, this will be set when the 84 * appropriate configure or setup function is called. 85 */ 86 rte_service_component_runstate_set(id, 1); 87 88 /* Collect statistics for the service */ 89 rte_service_set_stats_enable(id, 1); 90 91 /* The application sets the service to running state. Note that this 92 * function enables the service to run - while the 'component' version 93 * of this function (as above) marks the service itself as ready */ 94 ret = rte_service_runstate_set(id, 1); 95 96 97Controlling A Service Core 98~~~~~~~~~~~~~~~~~~~~~~~~~~ 99 100This section demonstrates how to add a service core. The ``rte_service.h`` 101header file provides the functions for dynamically adding and removing cores. 102The APIs to add and remove cores use lcore IDs similar to existing DPDK 103functions. 104 105These are the functions to start a service core, and have it run a service: 106 107.. code-block:: c 108 109 /* the lcore ID to use as a service core */ 110 uint32_t service_core_id = 7; 111 ret = rte_service_lcore_add(service_core_id); 112 if(ret) 113 return -1; 114 115 /* service cores are in "stopped" state when added, so start it */ 116 ret = rte_service_lcore_start(service_core_id); 117 if(ret) 118 return -1; 119 120 /* map a service to the service core, causing it to run the service */ 121 uint32_t service_id; /* ID of a registered service */ 122 uint32_t enable = 1; /* 1 maps the service, 0 unmaps */ 123 ret = rte_service_map_lcore_set(service_id, service_core_id, enable); 124 if(ret) 125 return -1; 126 127 128Removing A Service Core 129~~~~~~~~~~~~~~~~~~~~~~~ 130 131To remove a service core, the steps are similar to adding but in reverse order. 132Note that it is not allowed to remove a service core if the service is running, 133and the service-core is the only core running that service (see documentation 134for ``rte_service_lcore_stop`` function for details). 135 136 137Conclusion 138~~~~~~~~~~ 139 140The service cores infrastructure provides DPDK with two main features. The first 141is to abstract away hardware differences: the service core can CPU cycles to 142a software fallback implementation, allowing the application to be abstracted 143from the difference in HW / SW availability. The second feature is a flexible 144method of registering functions to be run, allowing the running of the 145functions to be scaled across multiple CPUs. 146