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.. literalinclude:: ../../../examples/service_cores/main.c 57 :language: c 58 :start-after: Register a service as an application. 8< 59 :end-before: >8 End of registering a service as an application. 60 :dedent: 2 61 62 63Controlling A Service Core 64~~~~~~~~~~~~~~~~~~~~~~~~~~ 65 66This section demonstrates how to add a service core. The ``rte_service.h`` 67header file provides the functions for dynamically adding and removing cores. 68The APIs to add and remove cores use lcore IDs similar to existing DPDK 69functions. 70 71These are the functions to start a service core, and have it run a service: 72 73.. literalinclude:: ../../../examples/service_cores/main.c 74 :language: c 75 :start-after: Register a service as an application. 8< 76 :end-before: >8 End of registering a service as an application. 77 :dedent: 2 78 79Removing A Service Core 80~~~~~~~~~~~~~~~~~~~~~~~ 81 82To remove a service core, the steps are similar to adding but in reverse order. 83Note that it is not allowed to remove a service core if the service is running, 84and the service-core is the only core running that service (see documentation 85for ``rte_service_lcore_stop`` function for details). 86 87 88Conclusion 89~~~~~~~~~~ 90 91The service cores infrastructure provides DPDK with two main features. The first 92is to abstract away hardware differences: the service core can CPU cycles to 93a software fallback implementation, allowing the application to be abstracted 94from the difference in HW / SW availability. The second feature is a flexible 95method of registering functions to be run, allowing the running of the 96functions to be scaled across multiple CPUs. 97