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