1 2.. BSD LICENSE 3 Copyright(c) 2015-2016 Intel Corporation. All rights reserved. 4 All rights reserved. 5 6 Redistribution and use in source and binary forms, with or without 7 modification, are permitted provided that the following conditions 8 are met: 9 10 * Redistributions of source code must retain the above copyright 11 notice, this list of conditions and the following disclaimer. 12 * Redistributions in binary form must reproduce the above copyright 13 notice, this list of conditions and the following disclaimer in 14 the documentation and/or other materials provided with the 15 distribution. 16 * Neither the name of Intel Corporation nor the names of its 17 contributors may be used to endorse or promote products derived 18 from this software without specific prior written permission. 19 20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 24 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 26 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 32Keep Alive Sample Application 33============================= 34 35The Keep Alive application is a simple example of a 36heartbeat/watchdog for packet processing cores. It demonstrates how 37to detect 'failed' DPDK cores and notify a fault management entity 38of this failure. Its purpose is to ensure the failure of the core 39does not result in a fault that is not detectable by a management 40entity. 41 42 43Overview 44-------- 45 46The application demonstrates how to protect against 'silent outages' 47on packet processing cores. A Keep Alive Monitor Agent Core (master) 48monitors the state of packet processing cores (worker cores) by 49dispatching pings at a regular time interval (default is 5ms) and 50monitoring the state of the cores. Cores states are: Alive, MIA, Dead 51or Buried. MIA indicates a missed ping, and Dead indicates two missed 52pings within the specified time interval. When a core is Dead, a 53callback function is invoked to restart the packet processing core; 54A real life application might use this callback function to notify a 55higher level fault management entity of the core failure in order to 56take the appropriate corrective action. 57 58Note: Only the worker cores are monitored. A local (on the host) mechanism 59or agent to supervise the Keep Alive Monitor Agent Core DPDK core is required 60to detect its failure. 61 62Note: This application is based on the :doc:`l2_forward_real_virtual`. As 63such, the initialization and run-time paths are very similar to those 64of the L2 forwarding application. 65 66Compiling the Application 67------------------------- 68 69To compile the sample application see :doc:`compiling`. 70 71The application is located in the ``l2fwd_keep_alive`` sub-directory. 72 73Running the Application 74----------------------- 75 76The application has a number of command line options: 77 78.. code-block:: console 79 80 ./build/l2fwd-keepalive [EAL options] \ 81 -- -p PORTMASK [-q NQ] [-K PERIOD] [-T PERIOD] 82 83where, 84 85* ``p PORTMASK``: A hexadecimal bitmask of the ports to configure 86 87* ``q NQ``: A number of queues (=ports) per lcore (default is 1) 88 89* ``K PERIOD``: Heartbeat check period in ms(5ms default; 86400 max) 90 91* ``T PERIOD``: statistics will be refreshed each PERIOD seconds (0 to 92 disable, 10 default, 86400 maximum). 93 94To run the application in linuxapp environment with 4 lcores, 16 ports 958 RX queues per lcore and a ping interval of 10ms, issue the command: 96 97.. code-block:: console 98 99 ./build/l2fwd-keepalive -l 0-3 -n 4 -- -q 8 -p ffff -K 10 100 101Refer to the *DPDK Getting Started Guide* for general information on 102running applications and the Environment Abstraction Layer (EAL) 103options. 104 105 106Explanation 107----------- 108 109The following sections provide some explanation of the The 110Keep-Alive/'Liveliness' conceptual scheme. As mentioned in the 111overview section, the initialization and run-time paths are very 112similar to those of the :doc:`l2_forward_real_virtual`. 113 114The Keep-Alive/'Liveliness' conceptual scheme: 115 116* A Keep- Alive Agent Runs every N Milliseconds. 117 118* DPDK Cores respond to the keep-alive agent. 119 120* If keep-alive agent detects time-outs, it notifies the 121 fault management entity through a callback function. 122 123The following sections provide some explanation of the code aspects 124that are specific to the Keep Alive sample application. 125 126The keepalive functionality is initialized with a struct 127rte_keepalive and the callback function to invoke in the 128case of a timeout. 129 130.. code-block:: c 131 132 rte_global_keepalive_info = rte_keepalive_create(&dead_core, NULL); 133 if (rte_global_keepalive_info == NULL) 134 rte_exit(EXIT_FAILURE, "keepalive_create() failed"); 135 136The function that issues the pings keepalive_dispatch_pings() 137is configured to run every check_period milliseconds. 138 139.. code-block:: c 140 141 if (rte_timer_reset(&hb_timer, 142 (check_period * rte_get_timer_hz()) / 1000, 143 PERIODICAL, 144 rte_lcore_id(), 145 &rte_keepalive_dispatch_pings, 146 rte_global_keepalive_info 147 ) != 0 ) 148 rte_exit(EXIT_FAILURE, "Keepalive setup failure.\n"); 149 150The rest of the initialization and run-time path follows 151the same paths as the L2 forwarding application. The only 152addition to the main processing loop is the mark alive 153functionality and the example random failures. 154 155.. code-block:: c 156 157 rte_keepalive_mark_alive(&rte_global_keepalive_info); 158 cur_tsc = rte_rdtsc(); 159 160 /* Die randomly within 7 secs for demo purposes.. */ 161 if (cur_tsc - tsc_initial > tsc_lifetime) 162 break; 163 164The rte_keepalive_mark_alive function simply sets the core state to alive. 165 166.. code-block:: c 167 168 static inline void 169 rte_keepalive_mark_alive(struct rte_keepalive *keepcfg) 170 { 171 keepcfg->state_flags[rte_lcore_id()] = ALIVE; 172 } 173