Branch data Line data Source code
1 : : /*
2 : : * Copyright (c) 2009, 2010, 2011, 2012, 2013, 2014, 2016 Nicira, Inc.
3 : : *
4 : : * Licensed under the Apache License, Version 2.0 (the "License");
5 : : * you may not use this file except in compliance with the License.
6 : : * You may obtain a copy of the License at:
7 : : *
8 : : * http://www.apache.org/licenses/LICENSE-2.0
9 : : *
10 : : * Unless required by applicable law or agreed to in writing, software
11 : : * distributed under the License is distributed on an "AS IS" BASIS,
12 : : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 : : * See the License for the specific language governing permissions and
14 : : * limitations under the License.
15 : : */
16 : :
17 : : #ifndef NETDEV_PROVIDER_H
18 : : #define NETDEV_PROVIDER_H 1
19 : :
20 : : /* Generic interface to network devices. */
21 : :
22 : : #include "connectivity.h"
23 : : #include "netdev.h"
24 : : #include "openvswitch/list.h"
25 : : #include "ovs-numa.h"
26 : : #include "packets.h"
27 : : #include "seq.h"
28 : : #include "openvswitch/shash.h"
29 : : #include "smap.h"
30 : :
31 : : #ifdef __cplusplus
32 : : extern "C" {
33 : : #endif
34 : :
35 : : struct netdev_tnl_build_header_params;
36 : : #define NETDEV_NUMA_UNSPEC OVS_NUMA_UNSPEC
37 : :
38 : : /* A network device (e.g. an Ethernet device).
39 : : *
40 : : * Network device implementations may read these members but should not modify
41 : : * them. */
42 : : struct netdev {
43 : : /* The following do not change during the lifetime of a struct netdev. */
44 : : char *name; /* Name of network device. */
45 : : const struct netdev_class *netdev_class; /* Functions to control
46 : : this device. */
47 : :
48 : : /* A sequence number which indicates changes in one of 'netdev''s
49 : : * properties. It must be nonzero so that users have a value which
50 : : * they may use as a reset when tracking 'netdev'.
51 : : *
52 : : * Minimally, the sequence number is required to change whenever
53 : : * 'netdev''s flags, features, ethernet address, or carrier changes. */
54 : : uint64_t change_seq;
55 : :
56 : : /* A netdev provider might be unable to change some of the device's
57 : : * parameter (n_rxq, mtu) when the device is in use. In this case
58 : : * the provider can notify the upper layer by calling
59 : : * netdev_request_reconfigure(). The upper layer will react by stopping
60 : : * the operations on the device and calling netdev_reconfigure() to allow
61 : : * the configuration changes. 'last_reconfigure_seq' remembers the value
62 : : * of 'reconfigure_seq' when the last reconfiguration happened. */
63 : : struct seq *reconfigure_seq;
64 : : uint64_t last_reconfigure_seq;
65 : :
66 : : /* If this is 'true', the user explicitly specified an MTU for this
67 : : * netdev. Otherwise, Open vSwitch is allowed to override it. */
68 : : bool mtu_user_config;
69 : :
70 : : /* The core netdev code initializes these at netdev construction and only
71 : : * provide read-only access to its client. Netdev implementations may
72 : : * modify them. */
73 : : int n_txq;
74 : : int n_rxq;
75 : : int ref_cnt; /* Times this devices was opened. */
76 : : struct shash_node *node; /* Pointer to element in global map. */
77 : : struct ovs_list saved_flags_list; /* Contains "struct netdev_saved_flags". */
78 : : };
79 : :
80 : : static inline void
81 : 43098 : netdev_change_seq_changed(const struct netdev *netdev_)
82 : : {
83 : 43098 : struct netdev *netdev = CONST_CAST(struct netdev *, netdev_);
84 : 43098 : seq_change(connectivity_seq_get());
85 : 43098 : netdev->change_seq++;
86 [ - + ]: 43098 : if (!netdev->change_seq) {
87 : 0 : netdev->change_seq++;
88 : : }
89 : 43098 : }
90 : :
91 : : static inline void
92 : 10 : netdev_request_reconfigure(struct netdev *netdev)
93 : : {
94 : 10 : seq_change(netdev->reconfigure_seq);
95 : 10 : }
96 : :
97 : : const char *netdev_get_type(const struct netdev *);
98 : : const struct netdev_class *netdev_get_class(const struct netdev *);
99 : : const char *netdev_get_name(const struct netdev *);
100 : : struct netdev *netdev_from_name(const char *name);
101 : : void netdev_get_devices(const struct netdev_class *,
102 : : struct shash *device_list);
103 : : struct netdev **netdev_get_vports(size_t *size);
104 : :
105 : : /* A data structure for capturing packets received by a network device.
106 : : *
107 : : * Network device implementations may read these members but should not modify
108 : : * them.
109 : : *
110 : : * None of these members change during the lifetime of a struct netdev_rxq. */
111 : : struct netdev_rxq {
112 : : struct netdev *netdev; /* Owns a reference to the netdev. */
113 : : int queue_id;
114 : : };
115 : :
116 : : struct netdev *netdev_rxq_get_netdev(const struct netdev_rxq *);
117 : :
118 : : /* Network device class structure, to be defined by each implementation of a
119 : : * network device.
120 : : *
121 : : * These functions return 0 if successful or a positive errno value on failure,
122 : : * except where otherwise noted.
123 : : *
124 : : *
125 : : * Data Structures
126 : : * ===============
127 : : *
128 : : * These functions work primarily with two different kinds of data structures:
129 : : *
130 : : * - "struct netdev", which represents a network device.
131 : : *
132 : : * - "struct netdev_rxq", which represents a handle for capturing packets
133 : : * received on a network device
134 : : *
135 : : * Each of these data structures contains all of the implementation-independent
136 : : * generic state for the respective concept, called the "base" state. None of
137 : : * them contains any extra space for implementations to use. Instead, each
138 : : * implementation is expected to declare its own data structure that contains
139 : : * an instance of the generic data structure plus additional
140 : : * implementation-specific members, called the "derived" state. The
141 : : * implementation can use casts or (preferably) the CONTAINER_OF macro to
142 : : * obtain access to derived state given only a pointer to the embedded generic
143 : : * data structure.
144 : : *
145 : : *
146 : : * Life Cycle
147 : : * ==========
148 : : *
149 : : * Four stylized functions accompany each of these data structures:
150 : : *
151 : : * "alloc" "construct" "destruct" "dealloc"
152 : : * ------------ ---------------- --------------- --------------
153 : : * netdev ->alloc ->construct ->destruct ->dealloc
154 : : * netdev_rxq ->rxq_alloc ->rxq_construct ->rxq_destruct ->rxq_dealloc
155 : : *
156 : : * Any instance of a given data structure goes through the following life
157 : : * cycle:
158 : : *
159 : : * 1. The client calls the "alloc" function to obtain raw memory. If "alloc"
160 : : * fails, skip all the other steps.
161 : : *
162 : : * 2. The client initializes all of the data structure's base state. If this
163 : : * fails, skip to step 7.
164 : : *
165 : : * 3. The client calls the "construct" function. The implementation
166 : : * initializes derived state. It may refer to the already-initialized
167 : : * base state. If "construct" fails, skip to step 6.
168 : : *
169 : : * 4. The data structure is now initialized and in use.
170 : : *
171 : : * 5. When the data structure is no longer needed, the client calls the
172 : : * "destruct" function. The implementation uninitializes derived state.
173 : : * The base state has not been uninitialized yet, so the implementation
174 : : * may still refer to it.
175 : : *
176 : : * 6. The client uninitializes all of the data structure's base state.
177 : : *
178 : : * 7. The client calls the "dealloc" to free the raw memory. The
179 : : * implementation must not refer to base or derived state in the data
180 : : * structure, because it has already been uninitialized.
181 : : *
182 : : * If netdev support multi-queue IO then netdev->construct should set initialize
183 : : * netdev->n_rxq to number of queues.
184 : : *
185 : : * Each "alloc" function allocates and returns a new instance of the respective
186 : : * data structure. The "alloc" function is not given any information about the
187 : : * use of the new data structure, so it cannot perform much initialization.
188 : : * Its purpose is just to ensure that the new data structure has enough room
189 : : * for base and derived state. It may return a null pointer if memory is not
190 : : * available, in which case none of the other functions is called.
191 : : *
192 : : * Each "construct" function initializes derived state in its respective data
193 : : * structure. When "construct" is called, all of the base state has already
194 : : * been initialized, so the "construct" function may refer to it. The
195 : : * "construct" function is allowed to fail, in which case the client calls the
196 : : * "dealloc" function (but not the "destruct" function).
197 : : *
198 : : * Each "destruct" function uninitializes and frees derived state in its
199 : : * respective data structure. When "destruct" is called, the base state has
200 : : * not yet been uninitialized, so the "destruct" function may refer to it. The
201 : : * "destruct" function is not allowed to fail.
202 : : *
203 : : * Each "dealloc" function frees raw memory that was allocated by the
204 : : * "alloc" function. The memory's base and derived members might not have ever
205 : : * been initialized (but if "construct" returned successfully, then it has been
206 : : * "destruct"ed already). The "dealloc" function is not allowed to fail.
207 : : *
208 : : *
209 : : * Device Change Notification
210 : : * ==========================
211 : : *
212 : : * Minimally, implementations are required to report changes to netdev flags,
213 : : * features, ethernet address or carrier through connectivity_seq. Changes to
214 : : * other properties are allowed to cause notification through this interface,
215 : : * although implementations should try to avoid this. connectivity_seq_get()
216 : : * can be used to acquire a reference to the struct seq. The interface is
217 : : * described in detail in seq.h. */
218 : : struct netdev_class {
219 : : /* Type of netdevs in this class, e.g. "system", "tap", "gre", etc.
220 : : *
221 : : * One of the providers should supply a "system" type, since this is
222 : : * the type assumed if no type is specified when opening a netdev.
223 : : * The "system" type corresponds to an existing network device on
224 : : * the system. */
225 : : const char *type;
226 : :
227 : : /* If 'true' then this netdev should be polled by PMD threads. */
228 : : bool is_pmd;
229 : :
230 : : /* ## ------------------- ## */
231 : : /* ## Top-Level Functions ## */
232 : : /* ## ------------------- ## */
233 : :
234 : : /* Called when the netdev provider is registered, typically at program
235 : : * startup. Returning an error from this function will prevent any network
236 : : * device in this class from being opened.
237 : : *
238 : : * This function may be set to null if a network device class needs no
239 : : * initialization at registration time. */
240 : : int (*init)(void);
241 : :
242 : : /* Performs periodic work needed by netdevs of this class. May be null if
243 : : * no periodic work is necessary.
244 : : *
245 : : * 'netdev_class' points to the class. It is useful in case the same
246 : : * function is used to implement different classes. */
247 : : void (*run)(const struct netdev_class *netdev_class);
248 : :
249 : : /* Arranges for poll_block() to wake up if the "run" member function needs
250 : : * to be called. Implementations are additionally required to wake
251 : : * whenever something changes in any of its netdevs which would cause their
252 : : * ->change_seq() function to change its result. May be null if nothing is
253 : : * needed here.
254 : : *
255 : : * 'netdev_class' points to the class. It is useful in case the same
256 : : * function is used to implement different classes. */
257 : : void (*wait)(const struct netdev_class *netdev_class);
258 : :
259 : : /* ## ---------------- ## */
260 : : /* ## netdev Functions ## */
261 : : /* ## ---------------- ## */
262 : :
263 : : /* Life-cycle functions for a netdev. See the large comment above on
264 : : * struct netdev_class. */
265 : : struct netdev *(*alloc)(void);
266 : : int (*construct)(struct netdev *);
267 : : void (*destruct)(struct netdev *);
268 : : void (*dealloc)(struct netdev *);
269 : :
270 : : /* Fetches the device 'netdev''s configuration, storing it in 'args'.
271 : : * The caller owns 'args' and pre-initializes it to an empty smap.
272 : : *
273 : : * If this netdev class does not have any configuration options, this may
274 : : * be a null pointer. */
275 : : int (*get_config)(const struct netdev *netdev, struct smap *args);
276 : :
277 : : /* Changes the device 'netdev''s configuration to 'args'.
278 : : *
279 : : * If this netdev class does not support configuration, this may be a null
280 : : * pointer. */
281 : : int (*set_config)(struct netdev *netdev, const struct smap *args);
282 : :
283 : : /* Returns the tunnel configuration of 'netdev'. If 'netdev' is
284 : : * not a tunnel, returns null.
285 : : *
286 : : * If this function would always return null, it may be null instead. */
287 : : const struct netdev_tunnel_config *
288 : : (*get_tunnel_config)(const struct netdev *netdev);
289 : :
290 : : /* Build Tunnel header. Ethernet and ip header parameters are passed to
291 : : * tunnel implementation to build entire outer header for given flow. */
292 : : int (*build_header)(const struct netdev *, struct ovs_action_push_tnl *data,
293 : : const struct netdev_tnl_build_header_params *params);
294 : :
295 : : /* build_header() can not build entire header for all packets for given
296 : : * flow. Push header is called for packet to build header specific to
297 : : * a packet on actual transmit. It uses partial header build by
298 : : * build_header() which is passed as data. */
299 : : void (*push_header)(struct dp_packet *packet,
300 : : const struct ovs_action_push_tnl *data);
301 : :
302 : : /* Pop tunnel header from packet, build tunnel metadata and resize packet
303 : : * for further processing.
304 : : * Returns NULL in case of error or tunnel implementation queued packet for further
305 : : * processing. */
306 : : struct dp_packet * (*pop_header)(struct dp_packet *packet);
307 : :
308 : : /* Returns the id of the numa node the 'netdev' is on. If there is no
309 : : * such info, returns NETDEV_NUMA_UNSPEC. */
310 : : int (*get_numa_id)(const struct netdev *netdev);
311 : :
312 : : /* Configures the number of tx queues of 'netdev'. Returns 0 if successful,
313 : : * otherwise a positive errno value.
314 : : *
315 : : * 'n_txq' specifies the exact number of transmission queues to create.
316 : : *
317 : : * The caller will call netdev_reconfigure() (if necessary) before using
318 : : * netdev_send() on any of the newly configured queues, giving the provider
319 : : * a chance to adjust its settings.
320 : : *
321 : : * On error, the tx queue configuration is unchanged. */
322 : : int (*set_tx_multiq)(struct netdev *netdev, unsigned int n_txq);
323 : :
324 : : /* Sends buffers on 'netdev'.
325 : : * Returns 0 if successful (for every buffer), otherwise a positive errno
326 : : * value. Returns EAGAIN without blocking if one or more packets cannot be
327 : : * queued immediately. Returns EMSGSIZE if a partial packet was transmitted
328 : : * or if a packet is too big or too small to transmit on the device.
329 : : *
330 : : * If the function returns a non-zero value, some of the packets might have
331 : : * been sent anyway.
332 : : *
333 : : * If 'may_steal' is false, the caller retains ownership of all the
334 : : * packets. If 'may_steal' is true, the caller transfers ownership of all
335 : : * the packets to the network device, regardless of success.
336 : : *
337 : : * If 'concurrent_txq' is true, the caller may perform concurrent calls
338 : : * to netdev_send() with the same 'qid'. The netdev provider is responsible
339 : : * for making sure that these concurrent calls do not create a race
340 : : * condition by using locking or other synchronization if required.
341 : : *
342 : : * The network device is expected to maintain one or more packet
343 : : * transmission queues, so that the caller does not ordinarily have to
344 : : * do additional queuing of packets. 'qid' specifies the queue to use
345 : : * and can be ignored if the implementation does not support multiple
346 : : * queues.
347 : : *
348 : : * May return EOPNOTSUPP if a network device does not implement packet
349 : : * transmission through this interface. This function may be set to null
350 : : * if it would always return EOPNOTSUPP anyhow. (This will prevent the
351 : : * network device from being usefully used by the netdev-based "userspace
352 : : * datapath". It will also prevent the OVS implementation of bonding from
353 : : * working properly over 'netdev'.) */
354 : : int (*send)(struct netdev *netdev, int qid, struct dp_packet_batch *batch,
355 : : bool may_steal, bool concurrent_txq);
356 : :
357 : : /* Registers with the poll loop to wake up from the next call to
358 : : * poll_block() when the packet transmission queue for 'netdev' has
359 : : * sufficient room to transmit a packet with netdev_send().
360 : : *
361 : : * The network device is expected to maintain one or more packet
362 : : * transmission queues, so that the caller does not ordinarily have to
363 : : * do additional queuing of packets. 'qid' specifies the queue to use
364 : : * and can be ignored if the implementation does not support multiple
365 : : * queues.
366 : : *
367 : : * May be null if not needed, such as for a network device that does not
368 : : * implement packet transmission through the 'send' member function. */
369 : : void (*send_wait)(struct netdev *netdev, int qid);
370 : :
371 : : /* Sets 'netdev''s Ethernet address to 'mac' */
372 : : int (*set_etheraddr)(struct netdev *netdev, const struct eth_addr mac);
373 : :
374 : : /* Retrieves 'netdev''s Ethernet address into 'mac'.
375 : : *
376 : : * This address will be advertised as 'netdev''s MAC address through the
377 : : * OpenFlow protocol, among other uses. */
378 : : int (*get_etheraddr)(const struct netdev *netdev, struct eth_addr *mac);
379 : :
380 : : /* Retrieves 'netdev''s MTU into '*mtup'.
381 : : *
382 : : * The MTU is the maximum size of transmitted (and received) packets, in
383 : : * bytes, not including the hardware header; thus, this is typically 1500
384 : : * bytes for Ethernet devices.
385 : : *
386 : : * If 'netdev' does not have an MTU (e.g. as some tunnels do not), then
387 : : * this function should return EOPNOTSUPP. This function may be set to
388 : : * null if it would always return EOPNOTSUPP. */
389 : : int (*get_mtu)(const struct netdev *netdev, int *mtup);
390 : :
391 : : /* Sets 'netdev''s MTU to 'mtu'.
392 : : *
393 : : * If 'netdev' does not have an MTU (e.g. as some tunnels do not), then
394 : : * this function should return EOPNOTSUPP. This function may be set to
395 : : * null if it would always return EOPNOTSUPP. */
396 : : int (*set_mtu)(struct netdev *netdev, int mtu);
397 : :
398 : : /* Returns the ifindex of 'netdev', if successful, as a positive number.
399 : : * On failure, returns a negative errno value.
400 : : *
401 : : * The desired semantics of the ifindex value are a combination of those
402 : : * specified by POSIX for if_nametoindex() and by SNMP for ifIndex. An
403 : : * ifindex value should be unique within a host and remain stable at least
404 : : * until reboot. SNMP says an ifindex "ranges between 1 and the value of
405 : : * ifNumber" but many systems do not follow this rule anyhow.
406 : : *
407 : : * This function may be set to null if it would always return -EOPNOTSUPP.
408 : : */
409 : : int (*get_ifindex)(const struct netdev *netdev);
410 : :
411 : : /* Sets 'carrier' to true if carrier is active (link light is on) on
412 : : * 'netdev'.
413 : : *
414 : : * May be null if device does not provide carrier status (will be always
415 : : * up as long as device is up).
416 : : */
417 : : int (*get_carrier)(const struct netdev *netdev, bool *carrier);
418 : :
419 : : /* Returns the number of times 'netdev''s carrier has changed since being
420 : : * initialized.
421 : : *
422 : : * If null, callers will assume the number of carrier resets is zero. */
423 : : long long int (*get_carrier_resets)(const struct netdev *netdev);
424 : :
425 : : /* Forces ->get_carrier() to poll 'netdev''s MII registers for link status
426 : : * instead of checking 'netdev''s carrier. 'netdev''s MII registers will
427 : : * be polled once every 'interval' milliseconds. If 'netdev' does not
428 : : * support MII, another method may be used as a fallback. If 'interval' is
429 : : * less than or equal to zero, reverts ->get_carrier() to its normal
430 : : * behavior.
431 : : *
432 : : * Most network devices won't support this feature and will set this
433 : : * function pointer to NULL, which is equivalent to returning EOPNOTSUPP.
434 : : */
435 : : int (*set_miimon_interval)(struct netdev *netdev, long long int interval);
436 : :
437 : : /* Retrieves current device stats for 'netdev' into 'stats'.
438 : : *
439 : : * A network device that supports some statistics but not others, it should
440 : : * set the values of the unsupported statistics to all-1-bits
441 : : * (UINT64_MAX). */
442 : : int (*get_stats)(const struct netdev *netdev, struct netdev_stats *);
443 : :
444 : : /* Stores the features supported by 'netdev' into each of '*current',
445 : : * '*advertised', '*supported', and '*peer'. Each value is a bitmap of
446 : : * NETDEV_F_* bits.
447 : : *
448 : : * This function may be set to null if it would always return EOPNOTSUPP.
449 : : */
450 : : int (*get_features)(const struct netdev *netdev,
451 : : enum netdev_features *current,
452 : : enum netdev_features *advertised,
453 : : enum netdev_features *supported,
454 : : enum netdev_features *peer);
455 : :
456 : : /* Set the features advertised by 'netdev' to 'advertise', which is a
457 : : * set of NETDEV_F_* bits.
458 : : *
459 : : * This function may be set to null for a network device that does not
460 : : * support configuring advertisements. */
461 : : int (*set_advertisements)(struct netdev *netdev,
462 : : enum netdev_features advertise);
463 : :
464 : : /* Attempts to set input rate limiting (policing) policy, such that up to
465 : : * 'kbits_rate' kbps of traffic is accepted, with a maximum accumulative
466 : : * burst size of 'kbits' kb.
467 : : *
468 : : * This function may be set to null if policing is not supported. */
469 : : int (*set_policing)(struct netdev *netdev, unsigned int kbits_rate,
470 : : unsigned int kbits_burst);
471 : :
472 : : /* Adds to 'types' all of the forms of QoS supported by 'netdev', or leaves
473 : : * it empty if 'netdev' does not support QoS. Any names added to 'types'
474 : : * should be documented as valid for the "type" column in the "QoS" table
475 : : * in vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
476 : : *
477 : : * Every network device must support disabling QoS with a type of "", but
478 : : * this function must not add "" to 'types'.
479 : : *
480 : : * The caller is responsible for initializing 'types' (e.g. with
481 : : * sset_init()) before calling this function. The caller retains ownership
482 : : * of 'types'.
483 : : *
484 : : * May be NULL if 'netdev' does not support QoS at all. */
485 : : int (*get_qos_types)(const struct netdev *netdev, struct sset *types);
486 : :
487 : : /* Queries 'netdev' for its capabilities regarding the specified 'type' of
488 : : * QoS. On success, initializes 'caps' with the QoS capabilities.
489 : : *
490 : : * Should return EOPNOTSUPP if 'netdev' does not support 'type'. May be
491 : : * NULL if 'netdev' does not support QoS at all. */
492 : : int (*get_qos_capabilities)(const struct netdev *netdev,
493 : : const char *type,
494 : : struct netdev_qos_capabilities *caps);
495 : :
496 : : /* Queries 'netdev' about its currently configured form of QoS. If
497 : : * successful, stores the name of the current form of QoS into '*typep'
498 : : * and any details of configuration as string key-value pairs in
499 : : * 'details'.
500 : : *
501 : : * A '*typep' of "" indicates that QoS is currently disabled on 'netdev'.
502 : : *
503 : : * The caller initializes 'details' before calling this function. The
504 : : * caller takes ownership of the string key-values pairs added to
505 : : * 'details'.
506 : : *
507 : : * The netdev retains ownership of '*typep'.
508 : : *
509 : : * '*typep' will be one of the types returned by netdev_get_qos_types() for
510 : : * 'netdev'. The contents of 'details' should be documented as valid for
511 : : * '*typep' in the "other_config" column in the "QoS" table in
512 : : * vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
513 : : *
514 : : * May be NULL if 'netdev' does not support QoS at all. */
515 : : int (*get_qos)(const struct netdev *netdev,
516 : : const char **typep, struct smap *details);
517 : :
518 : : /* Attempts to reconfigure QoS on 'netdev', changing the form of QoS to
519 : : * 'type' with details of configuration from 'details'.
520 : : *
521 : : * On error, the previous QoS configuration is retained.
522 : : *
523 : : * When this function changes the type of QoS (not just 'details'), this
524 : : * also resets all queue configuration for 'netdev' to their defaults
525 : : * (which depend on the specific type of QoS). Otherwise, the queue
526 : : * configuration for 'netdev' is unchanged.
527 : : *
528 : : * 'type' should be "" (to disable QoS) or one of the types returned by
529 : : * netdev_get_qos_types() for 'netdev'. The contents of 'details' should
530 : : * be documented as valid for the given 'type' in the "other_config" column
531 : : * in the "QoS" table in vswitchd/vswitch.xml (which is built as
532 : : * ovs-vswitchd.conf.db(8)).
533 : : *
534 : : * May be NULL if 'netdev' does not support QoS at all. */
535 : : int (*set_qos)(struct netdev *netdev,
536 : : const char *type, const struct smap *details);
537 : :
538 : : /* Queries 'netdev' for information about the queue numbered 'queue_id'.
539 : : * If successful, adds that information as string key-value pairs to
540 : : * 'details'. Returns 0 if successful, otherwise a positive errno value.
541 : : *
542 : : * Should return EINVAL if 'queue_id' is greater than or equal to the
543 : : * number of supported queues (as reported in the 'n_queues' member of
544 : : * struct netdev_qos_capabilities by 'get_qos_capabilities').
545 : : *
546 : : * The caller initializes 'details' before calling this function. The
547 : : * caller takes ownership of the string key-values pairs added to
548 : : * 'details'.
549 : : *
550 : : * The returned contents of 'details' should be documented as valid for the
551 : : * given 'type' in the "other_config" column in the "Queue" table in
552 : : * vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
553 : : */
554 : : int (*get_queue)(const struct netdev *netdev,
555 : : unsigned int queue_id, struct smap *details);
556 : :
557 : : /* Configures the queue numbered 'queue_id' on 'netdev' with the key-value
558 : : * string pairs in 'details'. The contents of 'details' should be
559 : : * documented as valid for the given 'type' in the "other_config" column in
560 : : * the "Queue" table in vswitchd/vswitch.xml (which is built as
561 : : * ovs-vswitchd.conf.db(8)). Returns 0 if successful, otherwise a positive
562 : : * errno value. On failure, the given queue's configuration should be
563 : : * unmodified.
564 : : *
565 : : * Should return EINVAL if 'queue_id' is greater than or equal to the
566 : : * number of supported queues (as reported in the 'n_queues' member of
567 : : * struct netdev_qos_capabilities by 'get_qos_capabilities'), or if
568 : : * 'details' is invalid for the type of queue.
569 : : *
570 : : * This function does not modify 'details', and the caller retains
571 : : * ownership of it.
572 : : *
573 : : * May be NULL if 'netdev' does not support QoS at all. */
574 : : int (*set_queue)(struct netdev *netdev,
575 : : unsigned int queue_id, const struct smap *details);
576 : :
577 : : /* Attempts to delete the queue numbered 'queue_id' from 'netdev'.
578 : : *
579 : : * Should return EINVAL if 'queue_id' is greater than or equal to the
580 : : * number of supported queues (as reported in the 'n_queues' member of
581 : : * struct netdev_qos_capabilities by 'get_qos_capabilities'). Should
582 : : * return EOPNOTSUPP if 'queue_id' is valid but may not be deleted (e.g. if
583 : : * 'netdev' has a fixed set of queues with the current QoS mode).
584 : : *
585 : : * May be NULL if 'netdev' does not support QoS at all, or if all of its
586 : : * QoS modes have fixed sets of queues. */
587 : : int (*delete_queue)(struct netdev *netdev, unsigned int queue_id);
588 : :
589 : : /* Obtains statistics about 'queue_id' on 'netdev'. Fills 'stats' with the
590 : : * queue's statistics. May set individual members of 'stats' to all-1-bits
591 : : * if the statistic is unavailable.
592 : : *
593 : : * May be NULL if 'netdev' does not support QoS at all. */
594 : : int (*get_queue_stats)(const struct netdev *netdev, unsigned int queue_id,
595 : : struct netdev_queue_stats *stats);
596 : :
597 : : /* Attempts to begin dumping the queues in 'netdev'. On success, returns 0
598 : : * and initializes '*statep' with any data needed for iteration. On
599 : : * failure, returns a positive errno value.
600 : : *
601 : : * May be NULL if 'netdev' does not support QoS at all. */
602 : : int (*queue_dump_start)(const struct netdev *netdev, void **statep);
603 : :
604 : : /* Attempts to retrieve another queue from 'netdev' for 'state', which was
605 : : * initialized by a successful call to the 'queue_dump_start' function for
606 : : * 'netdev'. On success, stores a queue ID into '*queue_id' and fills
607 : : * 'details' with the configuration of the queue with that ID. Returns EOF
608 : : * if the last queue has been dumped, or a positive errno value on error.
609 : : * This function will not be called again once it returns nonzero once for
610 : : * a given iteration (but the 'queue_dump_done' function will be called
611 : : * afterward).
612 : : *
613 : : * The caller initializes and clears 'details' before calling this
614 : : * function. The caller takes ownership of the string key-values pairs
615 : : * added to 'details'.
616 : : *
617 : : * The returned contents of 'details' should be documented as valid for the
618 : : * given 'type' in the "other_config" column in the "Queue" table in
619 : : * vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
620 : : *
621 : : * May be NULL if 'netdev' does not support QoS at all. */
622 : : int (*queue_dump_next)(const struct netdev *netdev, void *state,
623 : : unsigned int *queue_id, struct smap *details);
624 : :
625 : : /* Releases resources from 'netdev' for 'state', which was initialized by a
626 : : * successful call to the 'queue_dump_start' function for 'netdev'.
627 : : *
628 : : * May be NULL if 'netdev' does not support QoS at all. */
629 : : int (*queue_dump_done)(const struct netdev *netdev, void *state);
630 : :
631 : : /* Iterates over all of 'netdev''s queues, calling 'cb' with the queue's
632 : : * ID, its statistics, and the 'aux' specified by the caller. The order of
633 : : * iteration is unspecified, but (when successful) each queue must be
634 : : * visited exactly once.
635 : : *
636 : : * 'cb' will not modify or free the statistics passed in. */
637 : : int (*dump_queue_stats)(const struct netdev *netdev,
638 : : void (*cb)(unsigned int queue_id,
639 : : struct netdev_queue_stats *,
640 : : void *aux),
641 : : void *aux);
642 : :
643 : : /* Assigns 'addr' as 'netdev''s IPv4 address and 'mask' as its netmask. If
644 : : * 'addr' is INADDR_ANY, 'netdev''s IPv4 address is cleared.
645 : : *
646 : : * This function may be set to null if it would always return EOPNOTSUPP
647 : : * anyhow. */
648 : : int (*set_in4)(struct netdev *netdev, struct in_addr addr,
649 : : struct in_addr mask);
650 : :
651 : : /* Returns all assigned IP address to 'netdev' and returns 0.
652 : : * API allocates array of address and masks and set it to
653 : : * '*addr' and '*mask'.
654 : : * Otherwise, returns a positive errno value and sets '*addr', '*mask
655 : : * and '*n_addr' to NULL.
656 : : *
657 : : * The following error values have well-defined meanings:
658 : : *
659 : : * - EADDRNOTAVAIL: 'netdev' has no assigned IPv6 address.
660 : : *
661 : : * - EOPNOTSUPP: No IPv6 network stack attached to 'netdev'.
662 : : *
663 : : * 'addr' may be null, in which case the address itself is not reported. */
664 : : int (*get_addr_list)(const struct netdev *netdev, struct in6_addr **in,
665 : : struct in6_addr **mask, int *n_in6);
666 : :
667 : : /* Adds 'router' as a default IP gateway for the TCP/IP stack that
668 : : * corresponds to 'netdev'.
669 : : *
670 : : * This function may be set to null if it would always return EOPNOTSUPP
671 : : * anyhow. */
672 : : int (*add_router)(struct netdev *netdev, struct in_addr router);
673 : :
674 : : /* Looks up the next hop for 'host' in the host's routing table. If
675 : : * successful, stores the next hop gateway's address (0 if 'host' is on a
676 : : * directly connected network) in '*next_hop' and a copy of the name of the
677 : : * device to reach 'host' in '*netdev_name', and returns 0. The caller is
678 : : * responsible for freeing '*netdev_name' (by calling free()).
679 : : *
680 : : * This function may be set to null if it would always return EOPNOTSUPP
681 : : * anyhow. */
682 : : int (*get_next_hop)(const struct in_addr *host, struct in_addr *next_hop,
683 : : char **netdev_name);
684 : :
685 : : /* Retrieves driver information of the device.
686 : : *
687 : : * Populates 'smap' with key-value pairs representing the status of the
688 : : * device. 'smap' is a set of key-value string pairs representing netdev
689 : : * type specific information. For more information see
690 : : * ovs-vswitchd.conf.db(5).
691 : : *
692 : : * The caller is responsible for destroying 'smap' and its data.
693 : : *
694 : : * This function may be set to null if it would always return EOPNOTSUPP
695 : : * anyhow. */
696 : : int (*get_status)(const struct netdev *netdev, struct smap *smap);
697 : :
698 : : /* Looks up the ARP table entry for 'ip' on 'netdev' and stores the
699 : : * corresponding MAC address in 'mac'. A return value of ENXIO, in
700 : : * particular, indicates that there is no ARP table entry for 'ip' on
701 : : * 'netdev'.
702 : : *
703 : : * This function may be set to null if it would always return EOPNOTSUPP
704 : : * anyhow. */
705 : : int (*arp_lookup)(const struct netdev *netdev, ovs_be32 ip,
706 : : struct eth_addr *mac);
707 : :
708 : : /* Retrieves the current set of flags on 'netdev' into '*old_flags'. Then,
709 : : * turns off the flags that are set to 1 in 'off' and turns on the flags
710 : : * that are set to 1 in 'on'. (No bit will be set to 1 in both 'off' and
711 : : * 'on'; that is, off & on == 0.)
712 : : *
713 : : * This function may be invoked from a signal handler. Therefore, it
714 : : * should not do anything that is not signal-safe (such as logging). */
715 : : int (*update_flags)(struct netdev *netdev, enum netdev_flags off,
716 : : enum netdev_flags on, enum netdev_flags *old_flags);
717 : :
718 : : /* If the provider called netdev_request_reconfigure(), the upper layer
719 : : * will eventually call this. The provider can update the device
720 : : * configuration knowing that the upper layer will not call rxq_recv() or
721 : : * send() until this function returns.
722 : : *
723 : : * On error, the configuration is indeterminant and the device cannot be
724 : : * used to send and receive packets until a successful configuration is
725 : : * applied. */
726 : : int (*reconfigure)(struct netdev *netdev);
727 : : /* ## -------------------- ## */
728 : : /* ## netdev_rxq Functions ## */
729 : : /* ## -------------------- ## */
730 : :
731 : : /* If a particular netdev class does not support receiving packets, all these
732 : : * function pointers must be NULL. */
733 : :
734 : : /* Life-cycle functions for a netdev_rxq. See the large comment above on
735 : : * struct netdev_class. */
736 : : struct netdev_rxq *(*rxq_alloc)(void);
737 : : int (*rxq_construct)(struct netdev_rxq *);
738 : : void (*rxq_destruct)(struct netdev_rxq *);
739 : : void (*rxq_dealloc)(struct netdev_rxq *);
740 : :
741 : : /* Attempts to receive a batch of packets from 'rx'. In 'batch', the
742 : : * caller supplies 'packets' as the pointer to the beginning of an array
743 : : * of NETDEV_MAX_BURST pointers to dp_packet. If successful, the
744 : : * implementation stores pointers to up to NETDEV_MAX_BURST dp_packets into
745 : : * the array, transferring ownership of the packets to the caller, stores
746 : : * the number of received packets into 'count', and returns 0.
747 : : *
748 : : * The implementation does not necessarily initialize any non-data members
749 : : * of 'packets' in 'batch'. That is, the caller must initialize layer
750 : : * pointers and metadata itself, if desired, e.g. with pkt_metadata_init()
751 : : * and miniflow_extract().
752 : : *
753 : : * Implementations should allocate buffers with DP_NETDEV_HEADROOM bytes of
754 : : * headroom.
755 : : *
756 : : * Returns EAGAIN immediately if no packet is ready to be received or
757 : : * another positive errno value if an error was encountered. */
758 : : int (*rxq_recv)(struct netdev_rxq *rx, struct dp_packet_batch *batch);
759 : :
760 : : /* Registers with the poll loop to wake up from the next call to
761 : : * poll_block() when a packet is ready to be received with
762 : : * netdev_rxq_recv() on 'rx'. */
763 : : void (*rxq_wait)(struct netdev_rxq *rx);
764 : :
765 : : /* Discards all packets waiting to be received from 'rx'. */
766 : : int (*rxq_drain)(struct netdev_rxq *rx);
767 : : };
768 : :
769 : : int netdev_register_provider(const struct netdev_class *);
770 : : int netdev_unregister_provider(const char *type);
771 : :
772 : : #if defined(__FreeBSD__) || defined(__NetBSD__)
773 : : extern const struct netdev_class netdev_bsd_class;
774 : : #elif defined(_WIN32)
775 : : extern const struct netdev_class netdev_windows_class;
776 : : #else
777 : : extern const struct netdev_class netdev_linux_class;
778 : : #endif
779 : : extern const struct netdev_class netdev_internal_class;
780 : : extern const struct netdev_class netdev_tap_class;
781 : :
782 : : #ifdef __cplusplus
783 : : }
784 : : #endif
785 : :
786 : : #endif /* netdev.h */
|
