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 #.  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
  44 Running the Application
  45 -----------------------
  46
  47 To run the example, just execute the binary. Since the application dynamically
  48 adds service cores in the application code itself, there is no requirement to
  49 pass a service core-mask as an EAL argument at startup time.
  50
  51 .. code-block:: console
  52
  53     $ ./build/service_cores
  54
  55
  56 Explanation
  57 -----------
  58
  59 The following sections provide some explanation of code focusing on
  60 registering applications from an applications point of view, and modifying the
  61 service core counts and mappings at runtime.
  62
  63
  64 Registering a Service
  65 ~~~~~~~~~~~~~~~~~~~~~
  66
  67 The following code section shows how to register a service as an application.
  68 Note that the service component header must be included by the application in
  69 order to register services: ``rte_service_component.h``, in addition
  70 to the ordinary service cores header ``rte_service.h`` which provides
  71 the 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
  97 Controlling A Service Core
  98 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  99
 100 This section demonstrates how to add a service core. The ``rte_service.h``
 101 header file provides the functions for dynamically adding and removing cores.
 102 The APIs to add and remove cores use lcore IDs similar to existing DPDK
 103 functions.
 104
 105 These 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
 128 Removing A Service Core
 129 ~~~~~~~~~~~~~~~~~~~~~~~
 130
 131 To remove a service core, the steps are similar to adding but in reverse order.
 132 Note that it is not allowed to remove a service core if the service is running,
 133 and the service-core is the only core running that service (see documentation
 134 for ``rte_service_lcore_stop`` function for details).
 135
 136
 137 Conclusion
 138 ~~~~~~~~~~
 139
 140 The service cores infrastructure provides DPDK with two main features. The first
 141 is to abstract away hardware differences: the service core can CPU cycles to
 142 a software fallback implementation, allowing the application to be abstracted
 143 from the difference in HW / SW availability. The second feature is a flexible
 144 method of registering functions to be run, allowing the running of the
 145 functions to be scaled across multiple CPUs.