doc/guides/sample_app_ug/service_cores.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 Service Cores Sample Application
  32 ================================
  33
  34 The service cores sample application demonstrates the service cores capabilities
  35 of DPDK. The service cores infrastructure is part of the DPDK EAL, and allows
  36 any DPDK component to register a service. A service is a work item or task, that
  37 requires CPU time to perform its duty.
  38
  39 This sample application registers 5 dummy services. These 5 services are used
  40 to show how the service_cores API can be used to orchestrate these services to
  41 run on different service lcores. This orchestration is done by calling the
  42 service cores APIs, however the sample application introduces a "profile"
  43 concept to contain the service mapping details. Note that the profile concept
  44 is application specific, and not a part of the service cores API.
  45
  46
  47 Compiling the Application
  48 -------------------------
  49
  50 #.  Go to the example directory:
  51
  52     .. code-block:: console
  53
  54         export RTE_SDK=/path/to/rte_sdk
  55         cd ${RTE_SDK}/examples/service_cores
  56
  57 #.  Set the target (a default target is used if not specified). For example:
  58
  59     .. code-block:: console
  60
  61         export RTE_TARGET=x86_64-native-linuxapp-gcc
  62
  63     See the *DPDK Getting Started* Guide for possible RTE_TARGET values.
  64
  65 #.  Build the application:
  66
  67     .. code-block:: console
  68
  69         make
  70
  71 Running the Application
  72 -----------------------
  73
  74 To run the example, just execute the binary. Since the application dynamically
  75 adds service cores in the application code itself, there is no requirement to
  76 pass a service core-mask as an EAL argument at startup time.
  77
  78 .. code-block:: console
  79
  80     $ ./build/service_cores
  81
  82
  83 Explanation
  84 -----------
  85
  86 The following sections provide some explanation of code focusing on
  87 registering applications from an applications point of view, and modifying the
  88 service core counts and mappings at runtime.
  89
  90
  91 Registering a Service
  92 ~~~~~~~~~~~~~~~~~~~~~
  93
  94 The following code section shows how to register a service as an application.
  95 Note that the service component header must be included by the application in
  96 order to register services: ``rte_service_component.h``, in addition
  97 to the ordinary service cores header ``rte_service.h`` which provides
  98 the runtime functions to add, remove and remap service cores.
  99
 100 .. code-block:: c
 101
 102         struct rte_service_spec service = {
 103                 .name = "service_name",
 104         };
 105         int ret = rte_service_component_register(services, &id);
 106         if (ret)
 107                 return -1;
 108
 109         /* set the service itself to be ready to run. In the case of
 110         * ethdev, eventdev etc PMDs, this will be set when the
 111         * appropriate configure or setup function is called.
 112         */
 113         rte_service_component_runstate_set(id, 1);
 114
 115         /* Collect statistics for the service */
 116         rte_service_set_stats_enable(id, 1);
 117
 118         /* The application sets the service to running state. Note that this
 119          * function enables the service to run - while the 'component' version
 120          * of this function (as above) marks the service itself as ready */
 121         ret = rte_service_runstate_set(id, 1);
 122
 123
 124 Controlling A Service Core
 125 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 126
 127 This section demonstrates how to add a service core. The ``rte_service.h``
 128 header file provides the functions for dynamically adding and removing cores.
 129 The APIs to add and remove cores use lcore IDs similar to existing DPDK
 130 functions.
 131
 132 These are the functions to start a service core, and have it run a service:
 133
 134 .. code-block:: c
 135
 136         /* the lcore ID to use as a service core */
 137         uint32_t service_core_id = 7;
 138         ret = rte_service_lcore_add(service_core_id);
 139         if(ret)
 140                 return -1;
 141
 142         /* service cores are in "stopped" state when added, so start it */
 143         ret = rte_service_lcore_start(service_core_id);
 144         if(ret)
 145                 return -1;
 146
 147         /* map a service to the service core, causing it to run the service */
 148         uint32_t service_id; /* ID of a registered service */
 149         uint32_t enable = 1; /* 1 maps the service, 0 unmaps */
 150         ret = rte_service_map_lcore_set(service_id, service_core_id, enable);
 151         if(ret)
 152                 return -1;
 153
 154
 155 Removing A Service Core
 156 ~~~~~~~~~~~~~~~~~~~~~~~
 157
 158 To remove a service core, the steps are similar to adding but in reverse order.
 159 Note that it is not allowed to remove a service core if the service is running,
 160 and the service-core is the only core running that service (see documentation
 161 for ``rte_service_lcore_stop`` function for details).
 162
 163
 164 Conclusion
 165 ~~~~~~~~~~
 166
 167 The service cores infrastructure provides DPDK with two main features. The first
 168 is to abstract away hardware differences: the service core can CPU cycles to
 169 a software fallback implementation, allowing the application to be abstracted
 170 from the difference in HW / SW availability. The second feature is a flexible
 171 method of registering functions to be run, allowing the running of the
 172 functions to be scaled across multiple CPUs.