doc/guides/sample_app_ug/service_cores.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation.
   3
   4 Service Cores Sample Application
   5 ================================
   6
   7 The service cores sample application demonstrates the service cores capabilities
   8 of DPDK. The service cores infrastructure is part of the DPDK EAL, and allows
   9 any DPDK component to register a service. A service is a work item or task, that
  10 requires CPU time to perform its duty.
  11
  12 This sample application registers 5 dummy services. These 5 services are used
  13 to show how the service_cores API can be used to orchestrate these services to
  14 run on different service lcores. This orchestration is done by calling the
  15 service cores APIs, however the sample application introduces a "profile"
  16 concept to contain the service mapping details. Note that the profile concept
  17 is application specific, and not a part of the service cores API.
  18
  19
  20 Compiling the Application
  21 -------------------------
  22
  23 To compile the sample application see :doc:`compiling`.
  24
  25 The application is located in the ``service_cores`` sub-directory.
  26
  27 Running the Application
  28 -----------------------
  29
  30 To run the example, just execute the binary. Since the application dynamically
  31 adds service cores in the application code itself, there is no requirement to
  32 pass 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
  39 Explanation
  40 -----------
  41
  42 The following sections provide some explanation of code focusing on
  43 registering applications from an applications point of view, and modifying the
  44 service core counts and mappings at runtime.
  45
  46
  47 Registering a Service
  48 ~~~~~~~~~~~~~~~~~~~~~
  49
  50 The following code section shows how to register a service as an application.
  51 Note that the service component header must be included by the application in
  52 order to register services: ``rte_service_component.h``, in addition
  53 to the ordinary service cores header ``rte_service.h`` which provides
  54 the 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
  63 Controlling A Service Core
  64 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  65
  66 This section demonstrates how to add a service core. The ``rte_service.h``
  67 header file provides the functions for dynamically adding and removing cores.
  68 The APIs to add and remove cores use lcore IDs similar to existing DPDK
  69 functions.
  70
  71 These 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
  79 Removing A Service Core
  80 ~~~~~~~~~~~~~~~~~~~~~~~
  81
  82 To remove a service core, the steps are similar to adding but in reverse order.
  83 Note that it is not allowed to remove a service core if the service is running,
  84 and the service-core is the only core running that service (see documentation
  85 for ``rte_service_lcore_stop`` function for details).
  86
  87
  88 Conclusion
  89 ~~~~~~~~~~
  90
  91 The service cores infrastructure provides DPDK with two main features. The first
  92 is to abstract away hardware differences: the service core can CPU cycles to
  93 a software fallback implementation, allowing the application to be abstracted
  94 from the difference in HW / SW availability. The second feature is a flexible
  95 method of registering functions to be run, allowing the running of the
  96 functions to be scaled across multiple CPUs.