1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2015 Intel Corporation 3 */ 4 5 #ifndef _RTE_ETH_BOND_H_ 6 #define _RTE_ETH_BOND_H_ 7 8 /** 9 * @file rte_eth_bond.h 10 * 11 * RTE Link Bonding Ethernet Device 12 * Link Bonding for 1GbE and 10GbE ports to allow the aggregation of multiple 13 * (slave) NICs into a single logical interface. The bonded device processes 14 * these interfaces based on the mode of operation specified and supported. 15 * This implementation supports 4 modes of operation round robin, active backup 16 * balance and broadcast. Providing redundant links, fault tolerance and/or 17 * load balancing of network ports 18 */ 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #include <rte_ether.h> 25 26 /* Supported modes of operation of link bonding library */ 27 28 #define BONDING_MODE_ROUND_ROBIN (0) 29 /**< Round Robin (Mode 0). 30 * In this mode all transmitted packets will be balanced equally across all 31 * active slaves of the bonded in a round robin fashion. */ 32 #define BONDING_MODE_ACTIVE_BACKUP (1) 33 /**< Active Backup (Mode 1). 34 * In this mode all packets transmitted will be transmitted on the primary 35 * slave until such point as the primary slave is no longer available and then 36 * transmitted packets will be sent on the next available slaves. The primary 37 * slave can be defined by the user but defaults to the first active slave 38 * available if not specified. */ 39 #define BONDING_MODE_BALANCE (2) 40 /**< Balance (Mode 2). 41 * In this mode all packets transmitted will be balanced across the available 42 * slaves using one of three available transmit policies - l2, l2+3 or l3+4. 43 * See BALANCE_XMIT_POLICY macros definitions for further details on transmit 44 * policies. */ 45 #define BONDING_MODE_BROADCAST (3) 46 /**< Broadcast (Mode 3). 47 * In this mode all transmitted packets will be transmitted on all available 48 * active slaves of the bonded. */ 49 #define BONDING_MODE_8023AD (4) 50 /**< 802.3AD (Mode 4). 51 * 52 * This mode provides auto negotiation/configuration 53 * of peers and well as link status changes monitoring using out of band 54 * LACP (link aggregation control protocol) messages. For further details of 55 * LACP specification see the IEEE 802.3ad/802.1AX standards. It is also 56 * described here 57 * https://www.kernel.org/doc/Documentation/networking/bonding.txt. 58 * 59 * Important Usage Notes: 60 * - for LACP mode to work the rx/tx burst functions must be invoked 61 * at least once every 100ms, otherwise the out-of-band LACP messages will not 62 * be handled with the expected latency and this may cause the link status to be 63 * incorrectly marked as down or failure to correctly negotiate with peers. 64 * - For optimal performance during initial handshaking the array of mbufs provided 65 * to rx_burst should be at least 2 times the slave count size. 66 * 67 */ 68 #define BONDING_MODE_TLB (5) 69 /**< Adaptive TLB (Mode 5) 70 * This mode provides an adaptive transmit load balancing. It dynamically 71 * changes the transmitting slave, according to the computed load. Statistics 72 * are collected in 100ms intervals and scheduled every 10ms */ 73 #define BONDING_MODE_ALB (6) 74 /**< Adaptive Load Balancing (Mode 6) 75 * This mode includes adaptive TLB and receive load balancing (RLB). In RLB the 76 * bonding driver intercepts ARP replies send by local system and overwrites its 77 * source MAC address, so that different peers send data to the server on 78 * different slave interfaces. When local system sends ARP request, it saves IP 79 * information from it. When ARP reply from that peer is received, its MAC is 80 * stored, one of slave MACs assigned and ARP reply send to that peer. 81 */ 82 83 /* Balance Mode Transmit Policies */ 84 #define BALANCE_XMIT_POLICY_LAYER2 (0) 85 /**< Layer 2 (Ethernet MAC) */ 86 #define BALANCE_XMIT_POLICY_LAYER23 (1) 87 /**< Layer 2+3 (Ethernet MAC + IP Addresses) transmit load balancing */ 88 #define BALANCE_XMIT_POLICY_LAYER34 (2) 89 /**< Layer 3+4 (IP Addresses + UDP Ports) transmit load balancing */ 90 91 /** 92 * Create a bonded rte_eth_dev device 93 * 94 * @param name Name of new link bonding device. 95 * @param mode Mode to initialize bonding device in. 96 * @param socket_id Socket Id on which to allocate eth_dev resources. 97 * 98 * @return 99 * Port Id of created rte_eth_dev on success, negative value otherwise 100 */ 101 int 102 rte_eth_bond_create(const char *name, uint8_t mode, uint8_t socket_id); 103 104 /** 105 * Free a bonded rte_eth_dev device 106 * 107 * @param name Name of the link bonding device. 108 * 109 * @return 110 * 0 on success, negative value otherwise 111 */ 112 int 113 rte_eth_bond_free(const char *name); 114 115 /** 116 * Add a rte_eth_dev device as a slave to the bonded device 117 * 118 * @param bonded_port_id Port ID of bonded device. 119 * @param slave_port_id Port ID of slave device. 120 * 121 * @return 122 * 0 on success, negative value otherwise 123 */ 124 int 125 rte_eth_bond_slave_add(uint16_t bonded_port_id, uint16_t slave_port_id); 126 127 /** 128 * Remove a slave rte_eth_dev device from the bonded device 129 * 130 * @param bonded_port_id Port ID of bonded device. 131 * @param slave_port_id Port ID of slave device. 132 * 133 * @return 134 * 0 on success, negative value otherwise 135 */ 136 int 137 rte_eth_bond_slave_remove(uint16_t bonded_port_id, uint16_t slave_port_id); 138 139 /** 140 * Set link bonding mode of bonded device 141 * 142 * @param bonded_port_id Port ID of bonded device. 143 * @param mode Bonding mode to set 144 * 145 * @return 146 * 0 on success, negative value otherwise 147 */ 148 int 149 rte_eth_bond_mode_set(uint16_t bonded_port_id, uint8_t mode); 150 151 /** 152 * Get link bonding mode of bonded device 153 * 154 * @param bonded_port_id Port ID of bonded device. 155 * 156 * @return 157 * link bonding mode on success, negative value otherwise 158 */ 159 int 160 rte_eth_bond_mode_get(uint16_t bonded_port_id); 161 162 /** 163 * Set slave rte_eth_dev as primary slave of bonded device 164 * 165 * @param bonded_port_id Port ID of bonded device. 166 * @param slave_port_id Port ID of slave device. 167 * 168 * @return 169 * 0 on success, negative value otherwise 170 */ 171 int 172 rte_eth_bond_primary_set(uint16_t bonded_port_id, uint16_t slave_port_id); 173 174 /** 175 * Get primary slave of bonded device 176 * 177 * @param bonded_port_id Port ID of bonded device. 178 * 179 * @return 180 * Port Id of primary slave on success, -1 on failure 181 */ 182 int 183 rte_eth_bond_primary_get(uint16_t bonded_port_id); 184 185 /** 186 * Populate an array with list of the slaves port id's of the bonded device 187 * 188 * @param bonded_port_id Port ID of bonded eth_dev to interrogate 189 * @param slaves Array to be populated with the current active slaves 190 * @param len Length of slaves array 191 * 192 * @return 193 * Number of slaves associated with bonded device on success, 194 * negative value otherwise 195 */ 196 int 197 rte_eth_bond_slaves_get(uint16_t bonded_port_id, uint16_t slaves[], 198 uint16_t len); 199 200 /** 201 * Populate an array with list of the active slaves port id's of the bonded 202 * device. 203 * 204 * @param bonded_port_id Port ID of bonded eth_dev to interrogate 205 * @param slaves Array to be populated with the current active slaves 206 * @param len Length of slaves array 207 * 208 * @return 209 * Number of active slaves associated with bonded device on success, 210 * negative value otherwise 211 */ 212 int 213 rte_eth_bond_active_slaves_get(uint16_t bonded_port_id, uint16_t slaves[], 214 uint16_t len); 215 216 /** 217 * Set explicit MAC address to use on bonded device and it's slaves. 218 * 219 * @param bonded_port_id Port ID of bonded device. 220 * @param mac_addr MAC Address to use on bonded device overriding 221 * slaves MAC addresses 222 * 223 * @return 224 * 0 on success, negative value otherwise 225 */ 226 int 227 rte_eth_bond_mac_address_set(uint16_t bonded_port_id, 228 struct rte_ether_addr *mac_addr); 229 230 /** 231 * Reset bonded device to use MAC from primary slave on bonded device and it's 232 * slaves. 233 * 234 * @param bonded_port_id Port ID of bonded device. 235 * 236 * @return 237 * 0 on success, negative value otherwise 238 */ 239 int 240 rte_eth_bond_mac_address_reset(uint16_t bonded_port_id); 241 242 /** 243 * Set the transmit policy for bonded device to use when it is operating in 244 * balance mode, this parameter is otherwise ignored in other modes of 245 * operation. 246 * 247 * @param bonded_port_id Port ID of bonded device. 248 * @param policy Balance mode transmission policy. 249 * 250 * @return 251 * 0 on success, negative value otherwise. 252 */ 253 int 254 rte_eth_bond_xmit_policy_set(uint16_t bonded_port_id, uint8_t policy); 255 256 /** 257 * Get the transmit policy set on bonded device for balance mode operation 258 * 259 * @param bonded_port_id Port ID of bonded device. 260 * 261 * @return 262 * Balance transmit policy on success, negative value otherwise. 263 */ 264 int 265 rte_eth_bond_xmit_policy_get(uint16_t bonded_port_id); 266 267 /** 268 * Set the link monitoring frequency (in ms) for monitoring the link status of 269 * slave devices 270 * 271 * @param bonded_port_id Port ID of bonded device. 272 * @param internal_ms Monitoring interval in milliseconds 273 * 274 * @return 275 * 0 on success, negative value otherwise. 276 */ 277 278 int 279 rte_eth_bond_link_monitoring_set(uint16_t bonded_port_id, uint32_t internal_ms); 280 281 /** 282 * Get the current link monitoring frequency (in ms) for monitoring of the link 283 * status of slave devices 284 * 285 * @param bonded_port_id Port ID of bonded device. 286 * 287 * @return 288 * Monitoring interval on success, negative value otherwise. 289 */ 290 int 291 rte_eth_bond_link_monitoring_get(uint16_t bonded_port_id); 292 293 294 /** 295 * Set the period in milliseconds for delaying the disabling of a bonded link 296 * when the link down status has been detected 297 * 298 * @param bonded_port_id Port ID of bonded device. 299 * @param delay_ms Delay period in milliseconds. 300 * 301 * @return 302 * 0 on success, negative value otherwise. 303 */ 304 int 305 rte_eth_bond_link_down_prop_delay_set(uint16_t bonded_port_id, 306 uint32_t delay_ms); 307 308 /** 309 * Get the period in milliseconds set for delaying the disabling of a bonded 310 * link when the link down status has been detected 311 * 312 * @param bonded_port_id Port ID of bonded device. 313 * 314 * @return 315 * Delay period on success, negative value otherwise. 316 */ 317 int 318 rte_eth_bond_link_down_prop_delay_get(uint16_t bonded_port_id); 319 320 /** 321 * Set the period in milliseconds for delaying the enabling of a bonded link 322 * when the link up status has been detected 323 * 324 * @param bonded_port_id Port ID of bonded device. 325 * @param delay_ms Delay period in milliseconds. 326 * 327 * @return 328 * 0 on success, negative value otherwise. 329 */ 330 int 331 rte_eth_bond_link_up_prop_delay_set(uint16_t bonded_port_id, 332 uint32_t delay_ms); 333 334 /** 335 * Get the period in milliseconds set for delaying the enabling of a bonded 336 * link when the link up status has been detected 337 * 338 * @param bonded_port_id Port ID of bonded device. 339 * 340 * @return 341 * Delay period on success, negative value otherwise. 342 */ 343 int 344 rte_eth_bond_link_up_prop_delay_get(uint16_t bonded_port_id); 345 346 347 #ifdef __cplusplus 348 } 349 #endif 350 351 #endif 352