2 * Copyright (c) 2009, 2010, 2011 Nicira Networks.
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:
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef NETDEV_PROVIDER_H
18 #define NETDEV_PROVIDER_H 1
20 /* Generic interface to network devices. */
32 /* A network device (e.g. an Ethernet device).
34 * This structure should be treated as opaque by network device
37 char *name
; /* Name of network device. */
38 const struct netdev_class
*netdev_class
; /* Functions to control
40 int ref_cnt
; /* Times this devices was opened. */
41 struct shash_node
*node
; /* Pointer to element in global map. */
44 void netdev_dev_init(struct netdev_dev
*, const char *name
,
45 const struct netdev_class
*);
46 void netdev_dev_uninit(struct netdev_dev
*, bool destroy
);
47 const char *netdev_dev_get_type(const struct netdev_dev
*);
48 const struct netdev_class
*netdev_dev_get_class(const struct netdev_dev
*);
49 const char *netdev_dev_get_name(const struct netdev_dev
*);
50 struct netdev_dev
*netdev_dev_from_name(const char *name
);
51 void netdev_dev_get_devices(const struct netdev_class
*,
52 struct shash
*device_list
);
54 static inline void netdev_dev_assert_class(const struct netdev_dev
*netdev_dev
,
55 const struct netdev_class
*class_
)
57 assert(netdev_dev
->netdev_class
== class_
);
60 /* A instance of an open network device.
62 * This structure should be treated as opaque by network device
65 struct netdev_dev
*netdev_dev
; /* Parent netdev_dev. */
66 struct list node
; /* Element in global list. */
68 enum netdev_flags save_flags
; /* Initial device flags. */
69 enum netdev_flags changed_flags
; /* Flags that we changed. */
72 void netdev_init(struct netdev
*, struct netdev_dev
*);
73 void netdev_uninit(struct netdev
*, bool close
);
74 struct netdev_dev
*netdev_get_dev(const struct netdev
*);
76 static inline void netdev_assert_class(const struct netdev
*netdev
,
77 const struct netdev_class
*netdev_class
)
79 netdev_dev_assert_class(netdev_get_dev(netdev
), netdev_class
);
82 /* Network device class structure, to be defined by each implementation of a
85 * These functions return 0 if successful or a positive errno value on failure,
86 * except where otherwise noted. */
88 /* Type of netdevs in this class, e.g. "system", "tap", "gre", etc.
90 * One of the providers should supply a "system" type, since this is
91 * the type assumed if no type is specified when opening a netdev.
92 * The "system" type corresponds to an existing network device on
96 /* Called when the netdev provider is registered, typically at program
97 * startup. Returning an error from this function will prevent any network
98 * device in this class from being opened.
100 * This function may be set to null if a network device class needs no
101 * initialization at registration time. */
104 /* Performs periodic work needed by netdevs of this class. May be null if
105 * no periodic work is necessary. */
108 /* Arranges for poll_block() to wake up if the "run" member function needs
109 * to be called. Implementations are additionally required to wake
110 * whenever something changes in any of its netdevs which would cause their
111 * ->change_seq() function to change its result. May be null if nothing is
115 /* Attempts to create a network device named 'name' in 'netdev_class'. On
116 * success sets 'netdev_devp' to the newly created device. */
117 int (*create
)(const struct netdev_class
*netdev_class
, const char *name
,
118 struct netdev_dev
**netdev_devp
);
120 /* Destroys 'netdev_dev'.
122 * Netdev devices maintain a reference count that is incremented on
123 * netdev_open() and decremented on netdev_close(). If 'netdev_dev'
124 * has a non-zero reference count, then this function will not be
126 void (*destroy
)(struct netdev_dev
*netdev_dev
);
128 /* Fetches the device 'netdev_dev''s configuration, storing it in 'args'.
129 * The caller owns 'args' and pre-initializes it to an empty shash.
131 * If this netdev class does not have any configuration options, this may
132 * be a null pointer. */
133 int (*get_config
)(struct netdev_dev
*netdev_dev
, struct shash
*args
);
135 /* Changes the device 'netdev_dev''s configuration to 'args'.
137 * If this netdev class does not support configuration, this may be a null
139 int (*set_config
)(struct netdev_dev
*netdev_dev
, const struct shash
*args
);
141 /* Attempts to open a network device. On success, sets 'netdevp'
142 * to the new network device. */
143 int (*open
)(struct netdev_dev
*netdev_dev
, struct netdev
**netdevp
);
145 /* Closes 'netdev'. */
146 void (*close
)(struct netdev
*netdev
);
148 /* ## ----------------- ## */
149 /* ## Receiving Packets ## */
150 /* ## ----------------- ## */
152 /* The network provider interface is mostly used for inspecting and configuring
153 * device "metadata", not for sending and receiving packets directly. It may
154 * be impractical to implement these functions on some operating systems and
155 * hardware. These functions may all be NULL in such cases.
157 * (However, the "dpif-netdev" implementation, which is the easiest way to
158 * integrate Open vSwitch with a new operating system or hardware, does require
159 * the ability to receive packets.) */
161 /* Attempts to set up 'netdev' for receiving packets with ->recv().
162 * Returns 0 if successful, otherwise a positive errno value. Return
163 * EOPNOTSUPP to indicate that the network device does not implement packet
164 * reception through this interface. This function may be set to null if
165 * it would always return EOPNOTSUPP anyhow. (This will prevent the
166 * network device from being usefully used by the netdev-based "userspace
168 int (*listen
)(struct netdev
*netdev
);
170 /* Attempts to receive a packet from 'netdev' into the 'size' bytes in
171 * 'buffer'. If successful, returns the number of bytes in the received
172 * packet, otherwise a negative errno value. Returns -EAGAIN immediately
173 * if no packet is ready to be received.
175 * Returns -EMSGSIZE, and discards the packet, if the received packet is
176 * longer than 'size' bytes.
178 * This function can only be expected to return a packet if ->listen() has
179 * been called successfully.
181 * May be null if not needed, such as for a network device that does not
182 * implement packet reception through the 'recv' member function. */
183 int (*recv
)(struct netdev
*netdev
, void *buffer
, size_t size
);
185 /* Registers with the poll loop to wake up from the next call to
186 * poll_block() when a packet is ready to be received with netdev_recv() on
189 * May be null if not needed, such as for a network device that does not
190 * implement packet reception through the 'recv' member function. */
191 void (*recv_wait
)(struct netdev
*netdev
);
193 /* Discards all packets waiting to be received from 'netdev'.
195 * May be null if not needed, such as for a network device that does not
196 * implement packet reception through the 'recv' member function. */
197 int (*drain
)(struct netdev
*netdev
);
199 /* Sends the 'size'-byte packet in 'buffer' on 'netdev'. Returns 0 if
200 * successful, otherwise a positive errno value. Returns EAGAIN without
201 * blocking if the packet cannot be queued immediately. Returns EMSGSIZE
202 * if a partial packet was transmitted or if the packet is too big or too
203 * small to transmit on the device.
205 * The caller retains ownership of 'buffer' in all cases.
207 * The network device is expected to maintain a packet transmission queue,
208 * so that the caller does not ordinarily have to do additional queuing of
211 * May return EOPNOTSUPP if a network device does not implement packet
212 * transmission through this interface. This function may be set to null
213 * if it would always return EOPNOTSUPP anyhow. (This will prevent the
214 * network device from being usefully used by the netdev-based "userspace
215 * datapath". It will also prevent the OVS implementation of bonding from
216 * working properly over 'netdev'.) */
217 int (*send
)(struct netdev
*netdev
, const void *buffer
, size_t size
);
219 /* Registers with the poll loop to wake up from the next call to
220 * poll_block() when the packet transmission queue for 'netdev' has
221 * sufficient room to transmit a packet with netdev_send().
223 * The network device is expected to maintain a packet transmission queue,
224 * so that the caller does not ordinarily have to do additional queuing of
225 * packets. Thus, this function is unlikely to ever be useful.
227 * May be null if not needed, such as for a network device that does not
228 * implement packet transmission through the 'send' member function. */
229 void (*send_wait
)(struct netdev
*netdev
);
231 /* Sets 'netdev''s Ethernet address to 'mac' */
232 int (*set_etheraddr
)(struct netdev
*netdev
, const uint8_t mac
[6]);
234 /* Retrieves 'netdev''s Ethernet address into 'mac'. */
235 int (*get_etheraddr
)(const struct netdev
*netdev
, uint8_t mac
[6]);
237 /* Retrieves 'netdev''s MTU into '*mtup'.
239 * The MTU is the maximum size of transmitted (and received) packets, in
240 * bytes, not including the hardware header; thus, this is typically 1500
241 * bytes for Ethernet devices.
243 * If 'netdev' does not have an MTU (e.g. as some tunnels do not), then
244 * this function should return EOPNOTSUPP. This function may be set to
245 * null if it would always return EOPNOTSUPP. */
246 int (*get_mtu
)(const struct netdev
*netdev
, int *mtup
);
248 /* Sets 'netdev''s MTU to 'mtu'.
250 * If 'netdev' does not have an MTU (e.g. as some tunnels do not), then
251 * this function should return EOPNOTSUPP. This function may be set to
252 * null if it would always return EOPNOTSUPP. */
253 int (*set_mtu
)(const struct netdev
*netdev
, int mtu
);
255 /* Returns the ifindex of 'netdev', if successful, as a positive number.
256 * On failure, returns a negative errno value.
258 * The desired semantics of the ifindex value are a combination of those
259 * specified by POSIX for if_nametoindex() and by SNMP for ifIndex. An
260 * ifindex value should be unique within a host and remain stable at least
261 * until reboot. SNMP says an ifindex "ranges between 1 and the value of
262 * ifNumber" but many systems do not follow this rule anyhow.
264 * This function may be set to null if it would always return -EOPNOTSUPP.
266 int (*get_ifindex
)(const struct netdev
*netdev
);
268 /* Sets 'carrier' to true if carrier is active (link light is on) on
271 * May be null if device does not provide carrier status (will be always
272 * up as long as device is up).
274 int (*get_carrier
)(const struct netdev
*netdev
, bool *carrier
);
276 /* Returns the number of times 'netdev''s carrier has changed since being
279 * If null, callers will assume the number of carrier resets is zero. */
280 long long int (*get_carrier_resets
)(const struct netdev
*netdev
);
282 /* Forces ->get_carrier() to poll 'netdev''s MII registers for link status
283 * instead of checking 'netdev''s carrier. 'netdev''s MII registers will
284 * be polled once ever 'interval' milliseconds. If 'netdev' does not
285 * support MII, another method may be used as a fallback. If 'interval' is
286 * less than or equal to zero, reverts ->get_carrier() to its normal
289 * Most network devices won't support this feature and will set this
290 * function pointer to NULL, which is equivalent to returning EOPNOTSUPP.
292 int (*set_miimon_interval
)(struct netdev
*netdev
, long long int interval
);
294 /* Retrieves current device stats for 'netdev' into 'stats'.
296 * A network device that supports some statistics but not others, it should
297 * set the values of the unsupported statistics to all-1-bits
299 int (*get_stats
)(const struct netdev
*netdev
, struct netdev_stats
*);
301 /* Sets the device stats for 'netdev' to 'stats'.
303 * Most network devices won't support this feature and will set this
304 * function pointer to NULL, which is equivalent to returning EOPNOTSUPP.
306 * Some network devices might only allow setting their stats to 0. */
307 int (*set_stats
)(struct netdev
*netdev
, const struct netdev_stats
*);
309 /* Stores the features supported by 'netdev' into each of '*current',
310 * '*advertised', '*supported', and '*peer'. Each value is a bitmap of
313 * This function may be set to null if it would always return EOPNOTSUPP.
315 int (*get_features
)(const struct netdev
*netdev
,
316 enum netdev_features
*current
,
317 enum netdev_features
*advertised
,
318 enum netdev_features
*supported
,
319 enum netdev_features
*peer
);
321 /* Set the features advertised by 'netdev' to 'advertise', which is a
322 * set of NETDEV_F_* bits.
324 * This function may be set to null for a network device that does not
325 * support configuring advertisements. */
326 int (*set_advertisements
)(struct netdev
*netdev
,
327 enum netdev_features advertise
);
329 /* Attempts to set input rate limiting (policing) policy, such that up to
330 * 'kbits_rate' kbps of traffic is accepted, with a maximum accumulative
331 * burst size of 'kbits' kb.
333 * This function may be set to null if policing is not supported. */
334 int (*set_policing
)(struct netdev
*netdev
, unsigned int kbits_rate
,
335 unsigned int kbits_burst
);
337 /* Adds to 'types' all of the forms of QoS supported by 'netdev', or leaves
338 * it empty if 'netdev' does not support QoS. Any names added to 'types'
339 * should be documented as valid for the "type" column in the "QoS" table
340 * in vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
342 * Every network device must support disabling QoS with a type of "", but
343 * this function must not add "" to 'types'.
345 * The caller is responsible for initializing 'types' (e.g. with
346 * sset_init()) before calling this function. The caller retains ownership
349 * May be NULL if 'netdev' does not support QoS at all. */
350 int (*get_qos_types
)(const struct netdev
*netdev
, struct sset
*types
);
352 /* Queries 'netdev' for its capabilities regarding the specified 'type' of
353 * QoS. On success, initializes 'caps' with the QoS capabilities.
355 * Should return EOPNOTSUPP if 'netdev' does not support 'type'. May be
356 * NULL if 'netdev' does not support QoS at all. */
357 int (*get_qos_capabilities
)(const struct netdev
*netdev
,
359 struct netdev_qos_capabilities
*caps
);
361 /* Queries 'netdev' about its currently configured form of QoS. If
362 * successful, stores the name of the current form of QoS into '*typep'
363 * and any details of configuration as string key-value pairs in
366 * A '*typep' of "" indicates that QoS is currently disabled on 'netdev'.
368 * The caller initializes 'details' before calling this function. The
369 * caller takes ownership of the string key-values pairs added to
372 * The netdev retains ownership of '*typep'.
374 * '*typep' will be one of the types returned by netdev_get_qos_types() for
375 * 'netdev'. The contents of 'details' should be documented as valid for
376 * '*typep' in the "other_config" column in the "QoS" table in
377 * vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
379 * May be NULL if 'netdev' does not support QoS at all. */
380 int (*get_qos
)(const struct netdev
*netdev
,
381 const char **typep
, struct shash
*details
);
383 /* Attempts to reconfigure QoS on 'netdev', changing the form of QoS to
384 * 'type' with details of configuration from 'details'.
386 * On error, the previous QoS configuration is retained.
388 * When this function changes the type of QoS (not just 'details'), this
389 * also resets all queue configuration for 'netdev' to their defaults
390 * (which depend on the specific type of QoS). Otherwise, the queue
391 * configuration for 'netdev' is unchanged.
393 * 'type' should be "" (to disable QoS) or one of the types returned by
394 * netdev_get_qos_types() for 'netdev'. The contents of 'details' should
395 * be documented as valid for the given 'type' in the "other_config" column
396 * in the "QoS" table in vswitchd/vswitch.xml (which is built as
397 * ovs-vswitchd.conf.db(8)).
399 * May be NULL if 'netdev' does not support QoS at all. */
400 int (*set_qos
)(struct netdev
*netdev
,
401 const char *type
, const struct shash
*details
);
403 /* Queries 'netdev' for information about the queue numbered 'queue_id'.
404 * If successful, adds that information as string key-value pairs to
405 * 'details'. Returns 0 if successful, otherwise a positive errno value.
407 * Should return EINVAL if 'queue_id' is greater than or equal to the
408 * number of supported queues (as reported in the 'n_queues' member of
409 * struct netdev_qos_capabilities by 'get_qos_capabilities').
411 * The caller initializes 'details' before calling this function. The
412 * caller takes ownership of the string key-values pairs added to
415 * The returned contents of 'details' should be documented as valid for the
416 * given 'type' in the "other_config" column in the "Queue" table in
417 * vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
419 int (*get_queue
)(const struct netdev
*netdev
,
420 unsigned int queue_id
, struct shash
*details
);
422 /* Configures the queue numbered 'queue_id' on 'netdev' with the key-value
423 * string pairs in 'details'. The contents of 'details' should be
424 * documented as valid for the given 'type' in the "other_config" column in
425 * the "Queue" table in vswitchd/vswitch.xml (which is built as
426 * ovs-vswitchd.conf.db(8)). Returns 0 if successful, otherwise a positive
427 * errno value. On failure, the given queue's configuration should be
430 * Should return EINVAL if 'queue_id' is greater than or equal to the
431 * number of supported queues (as reported in the 'n_queues' member of
432 * struct netdev_qos_capabilities by 'get_qos_capabilities'), or if
433 * 'details' is invalid for the type of queue.
435 * This function does not modify 'details', and the caller retains
438 * May be NULL if 'netdev' does not support QoS at all. */
439 int (*set_queue
)(struct netdev
*netdev
,
440 unsigned int queue_id
, const struct shash
*details
);
442 /* Attempts to delete the queue numbered 'queue_id' from 'netdev'.
444 * Should return EINVAL if 'queue_id' is greater than or equal to the
445 * number of supported queues (as reported in the 'n_queues' member of
446 * struct netdev_qos_capabilities by 'get_qos_capabilities'). Should
447 * return EOPNOTSUPP if 'queue_id' is valid but may not be deleted (e.g. if
448 * 'netdev' has a fixed set of queues with the current QoS mode).
450 * May be NULL if 'netdev' does not support QoS at all, or if all of its
451 * QoS modes have fixed sets of queues. */
452 int (*delete_queue
)(struct netdev
*netdev
, unsigned int queue_id
);
454 /* Obtains statistics about 'queue_id' on 'netdev'. Fills 'stats' with the
455 * queue's statistics. May set individual members of 'stats' to all-1-bits
456 * if the statistic is unavailable.
458 * May be NULL if 'netdev' does not support QoS at all. */
459 int (*get_queue_stats
)(const struct netdev
*netdev
, unsigned int queue_id
,
460 struct netdev_queue_stats
*stats
);
462 /* Iterates over all of 'netdev''s queues, calling 'cb' with the queue's
463 * ID, its configuration, and the 'aux' specified by the caller. The order
464 * of iteration is unspecified, but (when successful) each queue is visited
467 * 'cb' will not modify or free the 'details' argument passed in. */
468 int (*dump_queues
)(const struct netdev
*netdev
,
469 void (*cb
)(unsigned int queue_id
,
470 const struct shash
*details
,
474 /* Iterates over all of 'netdev''s queues, calling 'cb' with the queue's
475 * ID, its statistics, and the 'aux' specified by the caller. The order of
476 * iteration is unspecified, but (when successful) each queue must be
477 * visited exactly once.
479 * 'cb' will not modify or free the statistics passed in. */
480 int (*dump_queue_stats
)(const struct netdev
*netdev
,
481 void (*cb
)(unsigned int queue_id
,
482 struct netdev_queue_stats
*,
486 /* If 'netdev' has an assigned IPv4 address, sets '*address' to that
487 * address and '*netmask' to the associated netmask.
489 * The following error values have well-defined meanings:
491 * - EADDRNOTAVAIL: 'netdev' has no assigned IPv4 address.
493 * - EOPNOTSUPP: No IPv4 network stack attached to 'netdev'.
495 * This function may be set to null if it would always return EOPNOTSUPP
497 int (*get_in4
)(const struct netdev
*netdev
, struct in_addr
*address
,
498 struct in_addr
*netmask
);
500 /* Assigns 'addr' as 'netdev''s IPv4 address and 'mask' as its netmask. If
501 * 'addr' is INADDR_ANY, 'netdev''s IPv4 address is cleared.
503 * This function may be set to null if it would always return EOPNOTSUPP
505 int (*set_in4
)(struct netdev
*netdev
, struct in_addr addr
,
506 struct in_addr mask
);
508 /* If 'netdev' has an assigned IPv6 address, sets '*in6' to that address.
510 * The following error values have well-defined meanings:
512 * - EADDRNOTAVAIL: 'netdev' has no assigned IPv6 address.
514 * - EOPNOTSUPP: No IPv6 network stack attached to 'netdev'.
516 * This function may be set to null if it would always return EOPNOTSUPP
518 int (*get_in6
)(const struct netdev
*netdev
, struct in6_addr
*in6
);
520 /* Adds 'router' as a default IP gateway for the TCP/IP stack that
521 * corresponds to 'netdev'.
523 * This function may be set to null if it would always return EOPNOTSUPP
525 int (*add_router
)(struct netdev
*netdev
, struct in_addr router
);
527 /* Looks up the next hop for 'host'. If succesful, stores the next hop
528 * gateway's address (0 if 'host' is on a directly connected network) in
529 * '*next_hop' and a copy of the name of the device to reach 'host' in
530 * '*netdev_name', and returns 0. The caller is responsible for freeing
531 * '*netdev_name' (by calling free()).
533 * This function may be set to null if it would always return EOPNOTSUPP
535 int (*get_next_hop
)(const struct in_addr
*host
, struct in_addr
*next_hop
,
538 /* Retrieves the status of the device.
540 * Populates 'sh' with key-value pairs representing the status of the
541 * device. A device's status is a set of key-value string pairs
542 * representing netdev type specific information. For more information see
543 * ovs-vswitchd.conf.db(5).
545 * The data of 'sh' are heap allocated strings which the caller is
546 * responsible for deallocating.
548 * This function may be set to null if it would always return EOPNOTSUPP
550 int (*get_status
)(const struct netdev
*netdev
, struct shash
*sh
);
552 /* Looks up the ARP table entry for 'ip' on 'netdev' and stores the
553 * corresponding MAC address in 'mac'. A return value of ENXIO, in
554 * particular, indicates that there is no ARP table entry for 'ip' on
557 * This function may be set to null if it would always return EOPNOTSUPP
559 int (*arp_lookup
)(const struct netdev
*netdev
, ovs_be32 ip
,
562 /* Retrieves the current set of flags on 'netdev' into '*old_flags'.
563 * Then, turns off the flags that are set to 1 in 'off' and turns on the
564 * flags that are set to 1 in 'on'. (No bit will be set to 1 in both 'off'
565 * and 'on'; that is, off & on == 0.)
567 * This function may be invoked from a signal handler. Therefore, it
568 * should not do anything that is not signal-safe (such as logging). */
569 int (*update_flags
)(struct netdev
*netdev
, enum netdev_flags off
,
570 enum netdev_flags on
, enum netdev_flags
*old_flags
);
572 /* Returns a sequence number which indicates changes in one of 'netdev''s
573 * properties. The returned sequence number must be nonzero so that
574 * callers have a value which they may use as a reset when tracking
577 * Minimally, the returned sequence number is required to change whenever
578 * 'netdev''s flags, features, ethernet address, or carrier changes. The
579 * returned sequence number is allowed to change even when 'netdev' doesn't
580 * change, although implementations should try to avoid this. */
581 unsigned int (*change_seq
)(const struct netdev
*netdev
);
584 int netdev_register_provider(const struct netdev_class
*);
585 int netdev_unregister_provider(const char *type
);
586 const struct netdev_class
*netdev_lookup_provider(const char *type
);
588 extern const struct netdev_class netdev_linux_class
;
589 extern const struct netdev_class netdev_internal_class
;
590 extern const struct netdev_class netdev_tap_class
;
596 #endif /* netdev.h */