doc/guides/prog_guide/link_bonding_poll_mode_drv_lib.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2014 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 Link Bonding Poll Mode Driver Library
  32 =====================================
  33
  34 In addition to Poll Mode Drivers (PMDs) for physical and virtual hardware,
  35 Intel® DPDK also includes a pure-software library that
  36 allows physical PMD's to be bonded together to create a single logical PMD.
  37
  38 |link_bonding|
  39
  40 The Link Bonding PMD library(librte_pmd_bond) supports bonding of groups of physical ports of the same speed (1GbE, 10GbE and 40GbE) and
  41 duplex to provide similar the capabilities to that found in Linux bonding driver to allow the aggregation of multiple (slave) NICs
  42 into a single logical interface between a server and a switch.
  43 The new bonded PMD will then process these interfaces based on the mode of operation specified to provide support for features
  44 such as redundant links, fault tolerance and/or load balancing.
  45
  46 The librte_pmd_bond library exports a C API which provides an API for the creation of bonded devices
  47 as well as the configuration and management of the bonded device and its slave devices.
  48
  49 .. note::
  50
  51     The Link Bonding PMD Library is enabled by default in the build configuration files,
  52     the library can be disabled by setting CONFIG_RTE_LIBRTE_PMD_BOND=n and recompiling the Intel® DPDK.
  53
  54 Link Bonding Modes Overview
  55 ---------------------------
  56
  57 Currently the Link Bonding PMD library supports 4 modes of operation:
  58
  59 *   **Round-Robin (Mode 0):**
  60     This mode provides load balancing and fault tolerance by transmission of packets
  61     in sequential order from the first available slave device through the last.
  62     Packets are bulk dequeued from devices then serviced in round-robin manner.
  63
  64 *   **Active Backup (Mode 1):**
  65     In this mode only one slave in the bond is active at any time, a different slave becomes active if,
  66     and only if, the primary active slave fails,
  67     thereby providing fault tolerance to slave failure.
  68     The single logical bonded interface's MAC address is externally visible on only one NIC (port)
  69     to avoid confusing the network switch.
  70
  71 *   **Balance XOR (Mode 2):**
  72     This mode provides load balancing based on transmit packets based on the selected XOR transmission policy and fault tolerance.
  73     The default policy (layer2) uses a simple XOR calculation on the packet source / destination MAC address to select the slave to transmit on.
  74     Alternate transmission policies supported are layer 2+3, this uses the IP source and destination addresses in the calculation of the slave port and
  75     the final supported policy is layer 3+4, this uses IP source and destination addresses as well as the UDP source and destination port.
  76
  77 *   **Broadcast (Mode 3):**
  78     This mode provides fault tolerance by transmission of packets on all slave ports.
  79
  80 Implementation Details
  81 ----------------------
  82
  83 The librte_pmd_bond onded device are compatible with the Ethernet device API exported by the Ethernet PMDs described in the *Intel® DPDK API Reference*.
  84
  85 The Link Bonding Library supports the creation of bonded devices at application startup time during EAL initialization using the
  86 --vdev option as well as programmatically via the C API rte_eth_bond_create function.
  87
  88 Bonded devices support the dynamical addition and removal of slave devices using
  89 the rte_eth_bond_slave_add / rte_eth_bond_slave_remove APIs.
  90
  91 After a slave device is added to a bonded device slave is stopped using
  92 rte_eth_dev_stop and the slave reconfigured using rte_eth_dev_configure the RX and TX queues are also reconfigured
  93 using rte_eth_tx_queue_setup / rte_eth_rx_queue_setup with the parameters use to configure the bonding device.
  94
  95 Requirements / Limitations
  96 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  97
  98 The current implementation only supports physical devices of the same type, speed and duplex to be added as slaves.
  99 The bonded device inherits these values from the first active slave added to the bonded device
 100 and then all further slaves added to the bonded device must match these parameters.
 101
 102 A bonding device must have a minimum of one slave before the bonding device itself can be started.
 103
 104 Like all other PMD, all functions exported by a PMD are lock-free functions that are assumed
 105 not to be invoked in parallel on different logical cores to work on the same target object.
 106
 107 It should also be noted that the PMD receive function should not be invoked directly on a slave devices after they have
 108 been to a bonded device since packets read directly from the slave device will no longer be available to the bonded device to read.
 109
 110 Configuration
 111 ~~~~~~~~~~~~~
 112
 113 Link bonding devices are created using the rte_eth_bond_create API
 114 which requires a unique device name, the bonding mode,
 115 and the socket Id to allocate the bonding device's resources on.
 116 The other configurable parameters for a bonded device are its slave devices, its primary slave,
 117 a user defined MAC address and transmission policy to use if the device is balance XOR mode.
 118
 119 Slave Devices
 120 ^^^^^^^^^^^^^
 121
 122 Bonding devices support up to a maximum of RTE_MAX_ETHPORTS slave devices of the same speed and duplex.
 123 Ethernet devices can be added as a slave to a maximum of one bonded device.
 124 Slave devices are reconfigured with the configuration of the bonded device on being added to a bonded device.
 125
 126 The bonded also guarantees to return the MAC address of the slave device to its original value of removal of a slave from it.
 127
 128 Primary Slave
 129 ^^^^^^^^^^^^^
 130
 131 The primary slave is used to define the default port to use when a bonded device is in active backup mode.
 132 A different port will only be used if, and only if, the current primary port goes down.
 133 If the user does not specify a primary port it will default to being the first port added to the bonded device.
 134
 135 MAC Address
 136 ^^^^^^^^^^^
 137
 138 The bonded device can be configured with a user specified MAC address,
 139 this address will be inherited by the some/all slave devices depending on the operating mode.
 140 If the device is in active backup mode then only the primary device will have the user specified MAC,
 141 all other slaves will retain their original MAC address.
 142 In mode 0, 2, and 3 all slaves devices are configure with the bonded devices MAC address.
 143
 144 If a user defined MAC address is not defined then the bonded device will default to using the primary slaves MAC address.
 145
 146 Balance XOR Transmit Policies
 147 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 148
 149 There are 3 supported transmission policies for bonded device running in Balance XOR mode. Layer 2, Layer 2+3, Layer 3+4.
 150
 151 *   **Layer 2:**   Ethernet MAC address based balancing is the default transmission policy for Balance XOR bonding mode.
 152     It uses a simple XOR calculation on the source MAC address and destination MAC address of the packet and
 153     then calculate the modulus of this value to calculate the slave device to transmit the packet on.
 154
 155 *   **Layer 2 + 3:** Ethernet MAC address & IP Address based balancing uses a combination of source/destination MAC addresses and
 156     the source/destination IP addresses of the data packet to decide which slave port the packet will be transmitted on.
 157
 158 *   **Layer 3 + 4:**  IP Address & UDP Port based  balancing uses a combination of source/destination IP Address and
 159     the source/destination UDP ports of the packet of the data packet to decide which slave port the packet will be transmitted on.
 160
 161 All these policies support 802.1Q VLAN Ethernet packets, as well as IPv4, IPv6 and UDP protocols for load balancing.
 162
 163 Using Link Bonding Devices
 164 --------------------------
 165
 166 The librte_pmd_bond library support two modes of device creation, the libraries export full C API or
 167 using the EAL command line to statically configure link bonding devices at application startup.
 168 Using the EAL option it is possible to use link bonding functionality transparently without specific knowledge of the libraries API,
 169 this can be used, for example, to add bonding functionality, such as active backup,
 170 to an existing application which has no knowledge of the link bonding C API.
 171
 172 Using the Poll Mode Driver from an Application
 173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 174
 175 Using the librte_pmd_bond libraries API it is possible to dynamicall create and manage link bonding device from within any application.
 176 Link bonding device are created using the rte_eth_bond_create API which requires a unqiue device name,
 177 the link bonding mode to initial the device in and finally the socket Id which to allocate the devices resources onto.
 178 After successful creation of a bonding device it must be configured using the generic Ethernet device configure API rte_eth_dev_configure
 179 and then the RX and TX queues which will be used must be setup using rte_eth_tx_queue_setup / rte_eth_rx_queue_setup.
 180
 181 Slave devices can be dynamically added and removed from a link bonding device using the rte_eth_bond_slave_add / rte_eth_bond_slave_remove
 182 APIs but at least one slave device must be added to the link bonding device before it can be started using rte_eth_dev_start.
 183
 184 The link status of a bonded device is dictated by that of its slaves, if all slave device link status are down or
 185 if all slaves are removed from the link bonding device then the link status of the bonding device will go down.
 186
 187 It is also possible to configure / query the configuration of the control parameters of a bonded device using the provided APIs
 188 rte_eth_bond_mode_set/get, rte_eth_bond_primary_set/get, rte_eth_bond_mac_set/reset and rte_eth_bond_xmit_policy_set/get.
 189
 190 Using Link Bonding Devices from the EAL Command Line
 191 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 192
 193 Link bonding devices can be created at application startup time using the --vdev EAL command line option.
 194 The device name must start with the eth_bond prefix followed by numbers or letters. The name must be unique for each device.
 195 Each device can have multiple options arranged in a comma separated list.
 196 Multiple devices definitions can be arranged by calling the --vdev option multiple times.
 197 Device names and bonding options must be separated by commas as shown below:
 198
 199 .. code-block:: console
 200
 201     $RTE_TARGET/app/testpmd -c f -n 4 --vdev 'eth_bond0,bond_opt0=..,bond opt1=..'--vdev 'eth_bond1,bond _opt0=..,bond_opt1=..'
 202
 203 Link Bonding EAL Options
 204 ^^^^^^^^^^^^^^^^^^^^^^^^
 205
 206 There are multiple ways of definitions that can be assessed and combined as long as the following two rules are respected:
 207
 208 *   A unique device name, in the format of eth_bondX is provided,
 209     where X can be any combination of numbers and/or letters,
 210     and the name is no greater than 32 characters long.
 211
 212 *   A least one slave device is provided with for each bonded device definition.
 213
 214 *   The operation mode of the bonded device being created is provided.
 215
 216 The different options are:
 217
 218 *   mode: Integer value defining the bonding mode of the device.
 219     Currently supports modes 0,1,2,3 (round-robin, active backup, balance, and broadcast).
 220
 221         mode=2
 222
 223 *   slave: Defines the PMD device which will be added as slave to the bonded device.
 224     This option can be selected multiple time, for each device to be added as a slave.
 225     Physical devices should be specified using their PCI address, in the format domain:bus:devid.function
 226
 227         slave=0000:0a:00.0,slave=0000:0a:00.1
 228
 229 *   primary: Optional parameter which defines the primary slave port,
 230     is used in active backup mode to select the primary slave for data TX/RX if it is available.
 231     The primary port also is used to select the MAC address to use when it is not defined by the user.
 232     This defaults to the first slave added to the device if it is specified.
 233     The primary device must be a slave of the bonded device.
 234
 235         primary=0000:0a:00.0
 236
 237 *   socket_id: Optional parameter used to select which socket on a NUMA device the bonded devices resources will be allocated on.
 238
 239         socket_id=0
 240
 241 *   mac: Optional parameter to select a MAC address for link bonding device, this overrides the value of the primary slave device.
 242
 243         mac=00:1e:67:1d:fd:1d
 244
 245 *   xmit_policy: Optional parameter which defines the transmission policy when the bonded device is in  balance mode.
 246     If not user specified this defaults to l2 (layer 2) forwarding,
 247     the other transmission policies available are l23 (layer 2+3) and l34 (layer 3+4)
 248
 249         xmit_policy=l2
 250
 251 Examples of Usage
 252 ^^^^^^^^^^^^^^^^^
 253
 254 Create a bonded device in round robin mode with two slaves specified by their PCI address:
 255
 256 .. code-block:: console
 257
 258     $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_bond0,mode=0, slave=0000:00a:00.01,slave=0000:004:00.00' -- --port-topology=chained
 259
 260 Create a bonded device in round robin mode with two slaves specified by their PCI address and an overriding MAC address:
 261
 262 .. code-block:: console
 263
 264     $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_bond0,mode=0, slave=0000:00a:00.01,slave=0000:004:00.00,mac=00:1e:67:1d:fd:1d' -- --port-topology=chained
 265
 266 Create a bonded device in active backup mode with two slaves specified, and a primary slave specified by their PCI addresses:
 267
 268 .. code-block:: console
 269
 270     $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_bond0,mode=1, slave=0000:00a:00.01,slave=0000:004:00.00,primary=0000:00a:00.01' -- --port-topology=chained
 271
 272 Create a bonded device in balance mode with two slaves specified by their PCI addresses, and a transmission policy of layer 3 + 4 forwarding:
 273
 274 .. code-block:: console
 275
 276     $RTE_TARGET/app/testpmd -c '0xf' -n 4 --vdev 'eth_bond0,mode=2, slave=0000:00a:00.01,slave=0000:004:00.00,xmit_policy=l34' -- --port-topology=chained
 277
 278 .. |link_bonding| image:: img/link_bonding.png