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