15630257fSFerruh Yigit.. SPDX-License-Identifier: BSD-3-Clause 25630257fSFerruh Yigit Copyright(c) 2017 Intel Corporation. 3cbdd3420SHarry van Haaren 4cbdd3420SHarry van HaarenService Cores Sample Application 5cbdd3420SHarry van Haaren================================ 6cbdd3420SHarry van Haaren 7cbdd3420SHarry van HaarenThe service cores sample application demonstrates the service cores capabilities 8cbdd3420SHarry van Haarenof DPDK. The service cores infrastructure is part of the DPDK EAL, and allows 9cbdd3420SHarry van Haarenany DPDK component to register a service. A service is a work item or task, that 10cbdd3420SHarry van Haarenrequires CPU time to perform its duty. 11cbdd3420SHarry van Haaren 12cbdd3420SHarry van HaarenThis sample application registers 5 dummy services. These 5 services are used 13cbdd3420SHarry van Haarento show how the service_cores API can be used to orchestrate these services to 14cbdd3420SHarry van Haarenrun on different service lcores. This orchestration is done by calling the 15cbdd3420SHarry van Haarenservice cores APIs, however the sample application introduces a "profile" 16cbdd3420SHarry van Haarenconcept to contain the service mapping details. Note that the profile concept 17cbdd3420SHarry van Haarenis application specific, and not a part of the service cores API. 18cbdd3420SHarry van Haaren 19cbdd3420SHarry van Haaren 20cbdd3420SHarry van HaarenCompiling the Application 21cbdd3420SHarry van Haaren------------------------- 22cbdd3420SHarry van Haaren 23e2a94f9aSCiara PowerTo compile the sample application see :doc:`compiling`. 24cbdd3420SHarry van Haaren 25e2a94f9aSCiara PowerThe application is located in the ``service_cores`` sub-directory. 26cbdd3420SHarry van Haaren 27cbdd3420SHarry van HaarenRunning the Application 28cbdd3420SHarry van Haaren----------------------- 29cbdd3420SHarry van Haaren 30cbdd3420SHarry van HaarenTo run the example, just execute the binary. Since the application dynamically 31cbdd3420SHarry van Haarenadds service cores in the application code itself, there is no requirement to 32cbdd3420SHarry van Haarenpass a service core-mask as an EAL argument at startup time. 33cbdd3420SHarry van Haaren 34cbdd3420SHarry van Haaren.. code-block:: console 35cbdd3420SHarry van Haaren 36e2a94f9aSCiara Power $ ./<build_dir>/examples/dpdk-service_cores 37cbdd3420SHarry van Haaren 38cbdd3420SHarry van Haaren 39cbdd3420SHarry van HaarenExplanation 40cbdd3420SHarry van Haaren----------- 41cbdd3420SHarry van Haaren 42cbdd3420SHarry van HaarenThe following sections provide some explanation of code focusing on 43cbdd3420SHarry van Haarenregistering applications from an applications point of view, and modifying the 44cbdd3420SHarry van Haarenservice core counts and mappings at runtime. 45cbdd3420SHarry van Haaren 46cbdd3420SHarry van Haaren 47cbdd3420SHarry van HaarenRegistering a Service 48cbdd3420SHarry van Haaren~~~~~~~~~~~~~~~~~~~~~ 49cbdd3420SHarry van Haaren 50cbdd3420SHarry van HaarenThe following code section shows how to register a service as an application. 51cbdd3420SHarry van HaarenNote that the service component header must be included by the application in 52cbdd3420SHarry van Haarenorder to register services: ``rte_service_component.h``, in addition 53cbdd3420SHarry van Haarento the ordinary service cores header ``rte_service.h`` which provides 54cbdd3420SHarry van Haarenthe runtime functions to add, remove and remap service cores. 55cbdd3420SHarry van Haaren 56*9a212dc0SConor Fogarty.. literalinclude:: ../../../examples/service_cores/main.c 57*9a212dc0SConor Fogarty :language: c 58*9a212dc0SConor Fogarty :start-after: Register a service as an application. 8< 59*9a212dc0SConor Fogarty :end-before: >8 End of registering a service as an application. 60*9a212dc0SConor Fogarty :dedent: 2 61cbdd3420SHarry van Haaren 62cbdd3420SHarry van Haaren 63cbdd3420SHarry van HaarenControlling A Service Core 64cbdd3420SHarry van Haaren~~~~~~~~~~~~~~~~~~~~~~~~~~ 65cbdd3420SHarry van Haaren 66cbdd3420SHarry van HaarenThis section demonstrates how to add a service core. The ``rte_service.h`` 67cbdd3420SHarry van Haarenheader file provides the functions for dynamically adding and removing cores. 68cbdd3420SHarry van HaarenThe APIs to add and remove cores use lcore IDs similar to existing DPDK 69cbdd3420SHarry van Haarenfunctions. 70cbdd3420SHarry van Haaren 71cbdd3420SHarry van HaarenThese are the functions to start a service core, and have it run a service: 72cbdd3420SHarry van Haaren 73*9a212dc0SConor Fogarty.. literalinclude:: ../../../examples/service_cores/main.c 74*9a212dc0SConor Fogarty :language: c 75*9a212dc0SConor Fogarty :start-after: Register a service as an application. 8< 76*9a212dc0SConor Fogarty :end-before: >8 End of registering a service as an application. 77*9a212dc0SConor Fogarty :dedent: 2 78cbdd3420SHarry van Haaren 79cbdd3420SHarry van HaarenRemoving A Service Core 80cbdd3420SHarry van Haaren~~~~~~~~~~~~~~~~~~~~~~~ 81cbdd3420SHarry van Haaren 82cbdd3420SHarry van HaarenTo remove a service core, the steps are similar to adding but in reverse order. 83cbdd3420SHarry van HaarenNote that it is not allowed to remove a service core if the service is running, 84cbdd3420SHarry van Haarenand the service-core is the only core running that service (see documentation 85cbdd3420SHarry van Haarenfor ``rte_service_lcore_stop`` function for details). 86cbdd3420SHarry van Haaren 87cbdd3420SHarry van Haaren 88cbdd3420SHarry van HaarenConclusion 89cbdd3420SHarry van Haaren~~~~~~~~~~ 90cbdd3420SHarry van Haaren 91cbdd3420SHarry van HaarenThe service cores infrastructure provides DPDK with two main features. The first 92cbdd3420SHarry van Haarenis to abstract away hardware differences: the service core can CPU cycles to 93cbdd3420SHarry van Haarena software fallback implementation, allowing the application to be abstracted 94cbdd3420SHarry van Haarenfrom the difference in HW / SW availability. The second feature is a flexible 95cbdd3420SHarry van Haarenmethod of registering functions to be run, allowing the running of the 96cbdd3420SHarry van Haarenfunctions to be scaled across multiple CPUs. 97