drivers: use SPDX tag for Intel copyright files
[dpdk.git] / 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