drivers/net/bonding/rte_eth_bond.h

   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 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