FAQ: Describe the state of MPLS in Open vSwitch.
[sliver-openvswitch.git] / lib / netdev-provider.h
1 /*
2  * Copyright (c) 2009, 2010, 2011, 2012, 2013 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 "netdev.h"
23 #include "list.h"
24 #include "shash.h"
25 #include "smap.h"
26
27 #ifdef  __cplusplus
28 extern "C" {
29 #endif
30
31 /* A network device (e.g. an Ethernet device).
32  *
33  * Network device implementations may read these members but should not modify
34  * them. */
35 struct netdev {
36     /* The following do not change during the lifetime of a struct netdev. */
37     char *name;                         /* Name of network device. */
38     const struct netdev_class *netdev_class; /* Functions to control
39                                                 this device. */
40
41     /* The following are protected by 'netdev_mutex' (internal to netdev.c). */
42     int ref_cnt;                        /* Times this devices was opened. */
43     struct shash_node *node;            /* Pointer to element in global map. */
44     struct list saved_flags_list; /* Contains "struct netdev_saved_flags". */
45 };
46
47 const char *netdev_get_type(const struct netdev *);
48 const struct netdev_class *netdev_get_class(const struct netdev *);
49 const char *netdev_get_name(const struct netdev *);
50 struct netdev *netdev_from_name(const char *name);
51 void netdev_get_devices(const struct netdev_class *,
52                         struct shash *device_list);
53
54 /* A data structure for capturing packets received by a network device.
55  *
56  * Network device implementations may read these members but should not modify
57  * them.
58  *
59  * None of these members change during the lifetime of a struct netdev_rx. */
60 struct netdev_rx {
61     struct netdev *netdev;      /* Owns a reference to the netdev. */
62 };
63
64 struct netdev *netdev_rx_get_netdev(const struct netdev_rx *);
65
66 /* Network device class structure, to be defined by each implementation of a
67  * network device.
68  *
69  * These functions return 0 if successful or a positive errno value on failure,
70  * except where otherwise noted.
71  *
72  *
73  * Data Structures
74  * ===============
75  *
76  * These functions work primarily with two different kinds of data structures:
77  *
78  *   - "struct netdev", which represents a network device.
79  *
80  *   - "struct netdev_rx", which represents a handle for capturing packets
81  *     received on a network device
82  *
83  * Each of these data structures contains all of the implementation-independent
84  * generic state for the respective concept, called the "base" state.  None of
85  * them contains any extra space for implementations to use.  Instead, each
86  * implementation is expected to declare its own data structure that contains
87  * an instance of the generic data structure plus additional
88  * implementation-specific members, called the "derived" state.  The
89  * implementation can use casts or (preferably) the CONTAINER_OF macro to
90  * obtain access to derived state given only a pointer to the embedded generic
91  * data structure.
92  *
93  *
94  * Life Cycle
95  * ==========
96  *
97  * Four stylized functions accompany each of these data structures:
98  *
99  *            "alloc"       "construct"       "destruct"       "dealloc"
100  *            ------------  ----------------  ---------------  --------------
101  * netdev     ->alloc       ->construct       ->destruct       ->dealloc
102  * netdev_rx  ->rx_alloc    ->rx_construct    ->rx_destruct    ->rx_dealloc
103  *
104  * Any instance of a given data structure goes through the following life
105  * cycle:
106  *
107  *   1. The client calls the "alloc" function to obtain raw memory.  If "alloc"
108  *      fails, skip all the other steps.
109  *
110  *   2. The client initializes all of the data structure's base state.  If this
111  *      fails, skip to step 7.
112  *
113  *   3. The client calls the "construct" function.  The implementation
114  *      initializes derived state.  It may refer to the already-initialized
115  *      base state.  If "construct" fails, skip to step 6.
116  *
117  *   4. The data structure is now initialized and in use.
118  *
119  *   5. When the data structure is no longer needed, the client calls the
120  *      "destruct" function.  The implementation uninitializes derived state.
121  *      The base state has not been uninitialized yet, so the implementation
122  *      may still refer to it.
123  *
124  *   6. The client uninitializes all of the data structure's base state.
125  *
126  *   7. The client calls the "dealloc" to free the raw memory.  The
127  *      implementation must not refer to base or derived state in the data
128  *      structure, because it has already been uninitialized.
129  *
130  * Each "alloc" function allocates and returns a new instance of the respective
131  * data structure.  The "alloc" function is not given any information about the
132  * use of the new data structure, so it cannot perform much initialization.
133  * Its purpose is just to ensure that the new data structure has enough room
134  * for base and derived state.  It may return a null pointer if memory is not
135  * available, in which case none of the other functions is called.
136  *
137  * Each "construct" function initializes derived state in its respective data
138  * structure.  When "construct" is called, all of the base state has already
139  * been initialized, so the "construct" function may refer to it.  The
140  * "construct" function is allowed to fail, in which case the client calls the
141  * "dealloc" function (but not the "destruct" function).
142  *
143  * Each "destruct" function uninitializes and frees derived state in its
144  * respective data structure.  When "destruct" is called, the base state has
145  * not yet been uninitialized, so the "destruct" function may refer to it.  The
146  * "destruct" function is not allowed to fail.
147  *
148  * Each "dealloc" function frees raw memory that was allocated by the the
149  * "alloc" function.  The memory's base and derived members might not have ever
150  * been initialized (but if "construct" returned successfully, then it has been
151  * "destruct"ed already).  The "dealloc" function is not allowed to fail.
152  *
153  *
154  * Device Change Notification
155  * ==========================
156  *
157  * Minimally, implementations are required to report changes to netdev flags,
158  * features, ethernet address or carrier through connectivity_seq. Changes to
159  * other properties are allowed to cause notification through this interface,
160  * although implementations should try to avoid this. connectivity_seq_get()
161  * can be used to acquire a reference to the struct seq. The interface is
162  * described in detail in seq.h. */
163 struct netdev_class {
164     /* Type of netdevs in this class, e.g. "system", "tap", "gre", etc.
165      *
166      * One of the providers should supply a "system" type, since this is
167      * the type assumed if no type is specified when opening a netdev.
168      * The "system" type corresponds to an existing network device on
169      * the system. */
170     const char *type;
171
172 /* ## ------------------- ## */
173 /* ## Top-Level Functions ## */
174 /* ## ------------------- ## */
175
176     /* Called when the netdev provider is registered, typically at program
177      * startup.  Returning an error from this function will prevent any network
178      * device in this class from being opened.
179      *
180      * This function may be set to null if a network device class needs no
181      * initialization at registration time. */
182     int (*init)(void);
183
184     /* Performs periodic work needed by netdevs of this class.  May be null if
185      * no periodic work is necessary. */
186     void (*run)(void);
187
188     /* Arranges for poll_block() to wake up if the "run" member function needs
189      * to be called.  Implementations are additionally required to wake
190      * whenever something changes in any of its netdevs which would cause their
191      * ->change_seq() function to change its result.  May be null if nothing is
192      * needed here. */
193     void (*wait)(void);
194
195 /* ## ---------------- ## */
196 /* ## netdev Functions ## */
197 /* ## ---------------- ## */
198
199     /* Life-cycle functions for a netdev.  See the large comment above on
200      * struct netdev_class. */
201     struct netdev *(*alloc)(void);
202     int (*construct)(struct netdev *);
203     void (*destruct)(struct netdev *);
204     void (*dealloc)(struct netdev *);
205
206     /* Fetches the device 'netdev''s configuration, storing it in 'args'.
207      * The caller owns 'args' and pre-initializes it to an empty smap.
208      *
209      * If this netdev class does not have any configuration options, this may
210      * be a null pointer. */
211     int (*get_config)(const struct netdev *netdev, struct smap *args);
212
213     /* Changes the device 'netdev''s configuration to 'args'.
214      *
215      * If this netdev class does not support configuration, this may be a null
216      * pointer. */
217     int (*set_config)(struct netdev *netdev, const struct smap *args);
218
219     /* Returns the tunnel configuration of 'netdev'.  If 'netdev' is
220      * not a tunnel, returns null.
221      *
222      * If this function would always return null, it may be null instead. */
223     const struct netdev_tunnel_config *
224         (*get_tunnel_config)(const struct netdev *netdev);
225
226     /* Sends the 'size'-byte packet in 'buffer' on 'netdev'.  Returns 0 if
227      * successful, otherwise a positive errno value.  Returns EAGAIN without
228      * blocking if the packet cannot be queued immediately.  Returns EMSGSIZE
229      * if a partial packet was transmitted or if the packet is too big or too
230      * small to transmit on the device.
231      *
232      * The caller retains ownership of 'buffer' in all cases.
233      *
234      * The network device is expected to maintain a packet transmission queue,
235      * so that the caller does not ordinarily have to do additional queuing of
236      * packets.
237      *
238      * May return EOPNOTSUPP if a network device does not implement packet
239      * transmission through this interface.  This function may be set to null
240      * if it would always return EOPNOTSUPP anyhow.  (This will prevent the
241      * network device from being usefully used by the netdev-based "userspace
242      * datapath".  It will also prevent the OVS implementation of bonding from
243      * working properly over 'netdev'.) */
244     int (*send)(struct netdev *netdev, const void *buffer, size_t size);
245
246     /* Registers with the poll loop to wake up from the next call to
247      * poll_block() when the packet transmission queue for 'netdev' has
248      * sufficient room to transmit a packet with netdev_send().
249      *
250      * The network device is expected to maintain a packet transmission queue,
251      * so that the caller does not ordinarily have to do additional queuing of
252      * packets.  Thus, this function is unlikely to ever be useful.
253      *
254      * May be null if not needed, such as for a network device that does not
255      * implement packet transmission through the 'send' member function. */
256     void (*send_wait)(struct netdev *netdev);
257
258     /* Sets 'netdev''s Ethernet address to 'mac' */
259     int (*set_etheraddr)(struct netdev *netdev, const uint8_t mac[6]);
260
261     /* Retrieves 'netdev''s Ethernet address into 'mac'.
262      *
263      * This address will be advertised as 'netdev''s MAC address through the
264      * OpenFlow protocol, among other uses. */
265     int (*get_etheraddr)(const struct netdev *netdev, uint8_t mac[6]);
266
267     /* Retrieves 'netdev''s MTU into '*mtup'.
268      *
269      * The MTU is the maximum size of transmitted (and received) packets, in
270      * bytes, not including the hardware header; thus, this is typically 1500
271      * bytes for Ethernet devices.
272      *
273      * If 'netdev' does not have an MTU (e.g. as some tunnels do not), then
274      * this function should return EOPNOTSUPP.  This function may be set to
275      * null if it would always return EOPNOTSUPP. */
276     int (*get_mtu)(const struct netdev *netdev, int *mtup);
277
278     /* Sets 'netdev''s MTU to 'mtu'.
279      *
280      * If 'netdev' does not have an MTU (e.g. as some tunnels do not), then
281      * this function should return EOPNOTSUPP.  This function may be set to
282      * null if it would always return EOPNOTSUPP. */
283     int (*set_mtu)(const struct netdev *netdev, int mtu);
284
285     /* Returns the ifindex of 'netdev', if successful, as a positive number.
286      * On failure, returns a negative errno value.
287      *
288      * The desired semantics of the ifindex value are a combination of those
289      * specified by POSIX for if_nametoindex() and by SNMP for ifIndex.  An
290      * ifindex value should be unique within a host and remain stable at least
291      * until reboot.  SNMP says an ifindex "ranges between 1 and the value of
292      * ifNumber" but many systems do not follow this rule anyhow.
293      *
294      * This function may be set to null if it would always return -EOPNOTSUPP.
295      */
296     int (*get_ifindex)(const struct netdev *netdev);
297
298     /* Sets 'carrier' to true if carrier is active (link light is on) on
299      * 'netdev'.
300      *
301      * May be null if device does not provide carrier status (will be always
302      * up as long as device is up).
303      */
304     int (*get_carrier)(const struct netdev *netdev, bool *carrier);
305
306     /* Returns the number of times 'netdev''s carrier has changed since being
307      * initialized.
308      *
309      * If null, callers will assume the number of carrier resets is zero. */
310     long long int (*get_carrier_resets)(const struct netdev *netdev);
311
312     /* Forces ->get_carrier() to poll 'netdev''s MII registers for link status
313      * instead of checking 'netdev''s carrier.  'netdev''s MII registers will
314      * be polled once ever 'interval' milliseconds.  If 'netdev' does not
315      * support MII, another method may be used as a fallback.  If 'interval' is
316      * less than or equal to zero, reverts ->get_carrier() to its normal
317      * behavior.
318      *
319      * Most network devices won't support this feature and will set this
320      * function pointer to NULL, which is equivalent to returning EOPNOTSUPP.
321      */
322     int (*set_miimon_interval)(struct netdev *netdev, long long int interval);
323
324     /* Retrieves current device stats for 'netdev' into 'stats'.
325      *
326      * A network device that supports some statistics but not others, it should
327      * set the values of the unsupported statistics to all-1-bits
328      * (UINT64_MAX). */
329     int (*get_stats)(const struct netdev *netdev, struct netdev_stats *);
330
331     /* Sets the device stats for 'netdev' to 'stats'.
332      *
333      * Most network devices won't support this feature and will set this
334      * function pointer to NULL, which is equivalent to returning EOPNOTSUPP.
335      *
336      * Some network devices might only allow setting their stats to 0. */
337     int (*set_stats)(struct netdev *netdev, const struct netdev_stats *);
338
339     /* Stores the features supported by 'netdev' into each of '*current',
340      * '*advertised', '*supported', and '*peer'.  Each value is a bitmap of
341      * NETDEV_F_* bits.
342      *
343      * This function may be set to null if it would always return EOPNOTSUPP.
344      */
345     int (*get_features)(const struct netdev *netdev,
346                         enum netdev_features *current,
347                         enum netdev_features *advertised,
348                         enum netdev_features *supported,
349                         enum netdev_features *peer);
350
351     /* Set the features advertised by 'netdev' to 'advertise', which is a
352      * set of NETDEV_F_* bits.
353      *
354      * This function may be set to null for a network device that does not
355      * support configuring advertisements. */
356     int (*set_advertisements)(struct netdev *netdev,
357                               enum netdev_features advertise);
358
359     /* Attempts to set input rate limiting (policing) policy, such that up to
360      * 'kbits_rate' kbps of traffic is accepted, with a maximum accumulative
361      * burst size of 'kbits' kb.
362      *
363      * This function may be set to null if policing is not supported. */
364     int (*set_policing)(struct netdev *netdev, unsigned int kbits_rate,
365                         unsigned int kbits_burst);
366
367     /* Adds to 'types' all of the forms of QoS supported by 'netdev', or leaves
368      * it empty if 'netdev' does not support QoS.  Any names added to 'types'
369      * should be documented as valid for the "type" column in the "QoS" table
370      * in vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
371      *
372      * Every network device must support disabling QoS with a type of "", but
373      * this function must not add "" to 'types'.
374      *
375      * The caller is responsible for initializing 'types' (e.g. with
376      * sset_init()) before calling this function.  The caller retains ownership
377      * of 'types'.
378      *
379      * May be NULL if 'netdev' does not support QoS at all. */
380     int (*get_qos_types)(const struct netdev *netdev, struct sset *types);
381
382     /* Queries 'netdev' for its capabilities regarding the specified 'type' of
383      * QoS.  On success, initializes 'caps' with the QoS capabilities.
384      *
385      * Should return EOPNOTSUPP if 'netdev' does not support 'type'.  May be
386      * NULL if 'netdev' does not support QoS at all. */
387     int (*get_qos_capabilities)(const struct netdev *netdev,
388                                 const char *type,
389                                 struct netdev_qos_capabilities *caps);
390
391     /* Queries 'netdev' about its currently configured form of QoS.  If
392      * successful, stores the name of the current form of QoS into '*typep'
393      * and any details of configuration as string key-value pairs in
394      * 'details'.
395      *
396      * A '*typep' of "" indicates that QoS is currently disabled on 'netdev'.
397      *
398      * The caller initializes 'details' before calling this function.  The
399      * caller takes ownership of the string key-values pairs added to
400      * 'details'.
401      *
402      * The netdev retains ownership of '*typep'.
403      *
404      * '*typep' will be one of the types returned by netdev_get_qos_types() for
405      * 'netdev'.  The contents of 'details' should be documented as valid for
406      * '*typep' in the "other_config" column in the "QoS" table in
407      * vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
408      *
409      * May be NULL if 'netdev' does not support QoS at all. */
410     int (*get_qos)(const struct netdev *netdev,
411                    const char **typep, struct smap *details);
412
413     /* Attempts to reconfigure QoS on 'netdev', changing the form of QoS to
414      * 'type' with details of configuration from 'details'.
415      *
416      * On error, the previous QoS configuration is retained.
417      *
418      * When this function changes the type of QoS (not just 'details'), this
419      * also resets all queue configuration for 'netdev' to their defaults
420      * (which depend on the specific type of QoS).  Otherwise, the queue
421      * configuration for 'netdev' is unchanged.
422      *
423      * 'type' should be "" (to disable QoS) or one of the types returned by
424      * netdev_get_qos_types() for 'netdev'.  The contents of 'details' should
425      * be documented as valid for the given 'type' in the "other_config" column
426      * in the "QoS" table in vswitchd/vswitch.xml (which is built as
427      * ovs-vswitchd.conf.db(8)).
428      *
429      * May be NULL if 'netdev' does not support QoS at all. */
430     int (*set_qos)(struct netdev *netdev,
431                    const char *type, const struct smap *details);
432
433     /* Queries 'netdev' for information about the queue numbered 'queue_id'.
434      * If successful, adds that information as string key-value pairs to
435      * 'details'.  Returns 0 if successful, otherwise a positive errno value.
436      *
437      * Should return EINVAL if 'queue_id' is greater than or equal to the
438      * number of supported queues (as reported in the 'n_queues' member of
439      * struct netdev_qos_capabilities by 'get_qos_capabilities').
440      *
441      * The caller initializes 'details' before calling this function.  The
442      * caller takes ownership of the string key-values pairs added to
443      * 'details'.
444      *
445      * The returned contents of 'details' should be documented as valid for the
446      * given 'type' in the "other_config" column in the "Queue" table in
447      * vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
448      */
449     int (*get_queue)(const struct netdev *netdev,
450                      unsigned int queue_id, struct smap *details);
451
452     /* Configures the queue numbered 'queue_id' on 'netdev' with the key-value
453      * string pairs in 'details'.  The contents of 'details' should be
454      * documented as valid for the given 'type' in the "other_config" column in
455      * the "Queue" table in vswitchd/vswitch.xml (which is built as
456      * ovs-vswitchd.conf.db(8)).  Returns 0 if successful, otherwise a positive
457      * errno value.  On failure, the given queue's configuration should be
458      * unmodified.
459      *
460      * Should return EINVAL if 'queue_id' is greater than or equal to the
461      * number of supported queues (as reported in the 'n_queues' member of
462      * struct netdev_qos_capabilities by 'get_qos_capabilities'), or if
463      * 'details' is invalid for the type of queue.
464      *
465      * This function does not modify 'details', and the caller retains
466      * ownership of it.
467      *
468      * May be NULL if 'netdev' does not support QoS at all. */
469     int (*set_queue)(struct netdev *netdev,
470                      unsigned int queue_id, const struct smap *details);
471
472     /* Attempts to delete the queue numbered 'queue_id' from 'netdev'.
473      *
474      * Should return EINVAL if 'queue_id' is greater than or equal to the
475      * number of supported queues (as reported in the 'n_queues' member of
476      * struct netdev_qos_capabilities by 'get_qos_capabilities').  Should
477      * return EOPNOTSUPP if 'queue_id' is valid but may not be deleted (e.g. if
478      * 'netdev' has a fixed set of queues with the current QoS mode).
479      *
480      * May be NULL if 'netdev' does not support QoS at all, or if all of its
481      * QoS modes have fixed sets of queues. */
482     int (*delete_queue)(struct netdev *netdev, unsigned int queue_id);
483
484     /* Obtains statistics about 'queue_id' on 'netdev'.  Fills 'stats' with the
485      * queue's statistics.  May set individual members of 'stats' to all-1-bits
486      * if the statistic is unavailable.
487      *
488      * May be NULL if 'netdev' does not support QoS at all. */
489     int (*get_queue_stats)(const struct netdev *netdev, unsigned int queue_id,
490                            struct netdev_queue_stats *stats);
491
492     /* Attempts to begin dumping the queues in 'netdev'.  On success, returns 0
493      * and initializes '*statep' with any data needed for iteration.  On
494      * failure, returns a positive errno value.
495      *
496      * May be NULL if 'netdev' does not support QoS at all. */
497     int (*queue_dump_start)(const struct netdev *netdev, void **statep);
498
499     /* Attempts to retrieve another queue from 'netdev' for 'state', which was
500      * initialized by a successful call to the 'queue_dump_start' function for
501      * 'netdev'.  On success, stores a queue ID into '*queue_id' and fills
502      * 'details' with the configuration of the queue with that ID.  Returns EOF
503      * if the last queue has been dumped, or a positive errno value on error.
504      * This function will not be called again once it returns nonzero once for
505      * a given iteration (but the 'queue_dump_done' function will be called
506      * afterward).
507      *
508      * The caller initializes and clears 'details' before calling this
509      * function.  The caller takes ownership of the string key-values pairs
510      * added to 'details'.
511      *
512      * The returned contents of 'details' should be documented as valid for the
513      * given 'type' in the "other_config" column in the "Queue" table in
514      * vswitchd/vswitch.xml (which is built as ovs-vswitchd.conf.db(8)).
515      *
516      * May be NULL if 'netdev' does not support QoS at all. */
517     int (*queue_dump_next)(const struct netdev *netdev, void *state,
518                            unsigned int *queue_id, struct smap *details);
519
520     /* Releases resources from 'netdev' for 'state', which was initialized by a
521      * successful call to the 'queue_dump_start' function for 'netdev'.
522      *
523      * May be NULL if 'netdev' does not support QoS at all. */
524     int (*queue_dump_done)(const struct netdev *netdev, void *state);
525
526     /* Iterates over all of 'netdev''s queues, calling 'cb' with the queue's
527      * ID, its statistics, and the 'aux' specified by the caller.  The order of
528      * iteration is unspecified, but (when successful) each queue must be
529      * visited exactly once.
530      *
531      * 'cb' will not modify or free the statistics passed in. */
532     int (*dump_queue_stats)(const struct netdev *netdev,
533                             void (*cb)(unsigned int queue_id,
534                                        struct netdev_queue_stats *,
535                                        void *aux),
536                             void *aux);
537
538     /* If 'netdev' has an assigned IPv4 address, sets '*address' to that
539      * address and '*netmask' to the associated netmask.
540      *
541      * The following error values have well-defined meanings:
542      *
543      *   - EADDRNOTAVAIL: 'netdev' has no assigned IPv4 address.
544      *
545      *   - EOPNOTSUPP: No IPv4 network stack attached to 'netdev'.
546      *
547      * This function may be set to null if it would always return EOPNOTSUPP
548      * anyhow. */
549     int (*get_in4)(const struct netdev *netdev, struct in_addr *address,
550                    struct in_addr *netmask);
551
552     /* Assigns 'addr' as 'netdev''s IPv4 address and 'mask' as its netmask.  If
553      * 'addr' is INADDR_ANY, 'netdev''s IPv4 address is cleared.
554      *
555      * This function may be set to null if it would always return EOPNOTSUPP
556      * anyhow. */
557     int (*set_in4)(struct netdev *netdev, struct in_addr addr,
558                    struct in_addr mask);
559
560     /* If 'netdev' has an assigned IPv6 address, sets '*in6' to that address.
561      *
562      * The following error values have well-defined meanings:
563      *
564      *   - EADDRNOTAVAIL: 'netdev' has no assigned IPv6 address.
565      *
566      *   - EOPNOTSUPP: No IPv6 network stack attached to 'netdev'.
567      *
568      * This function may be set to null if it would always return EOPNOTSUPP
569      * anyhow. */
570     int (*get_in6)(const struct netdev *netdev, struct in6_addr *in6);
571
572     /* Adds 'router' as a default IP gateway for the TCP/IP stack that
573      * corresponds to 'netdev'.
574      *
575      * This function may be set to null if it would always return EOPNOTSUPP
576      * anyhow. */
577     int (*add_router)(struct netdev *netdev, struct in_addr router);
578
579     /* Looks up the next hop for 'host'.  If successful, stores the next hop
580      * gateway's address (0 if 'host' is on a directly connected network) in
581      * '*next_hop' and a copy of the name of the device to reach 'host' in
582      * '*netdev_name', and returns 0.  The caller is responsible for freeing
583      * '*netdev_name' (by calling free()).
584      *
585      * This function may be set to null if it would always return EOPNOTSUPP
586      * anyhow. */
587     int (*get_next_hop)(const struct in_addr *host, struct in_addr *next_hop,
588                         char **netdev_name);
589
590     /* Retrieves driver information of the device.
591      *
592      * Populates 'smap' with key-value pairs representing the status of the
593      * device.  'smap' is a set of key-value string pairs representing netdev
594      * type specific information.  For more information see
595      * ovs-vswitchd.conf.db(5).
596      *
597      * The caller is responsible for destroying 'smap' and its data.
598      *
599      * This function may be set to null if it would always return EOPNOTSUPP
600      * anyhow. */
601     int (*get_status)(const struct netdev *netdev, struct smap *smap);
602
603     /* Looks up the ARP table entry for 'ip' on 'netdev' and stores the
604      * corresponding MAC address in 'mac'.  A return value of ENXIO, in
605      * particular, indicates that there is no ARP table entry for 'ip' on
606      * 'netdev'.
607      *
608      * This function may be set to null if it would always return EOPNOTSUPP
609      * anyhow. */
610     int (*arp_lookup)(const struct netdev *netdev, ovs_be32 ip,
611                       uint8_t mac[6]);
612
613     /* Retrieves the current set of flags on 'netdev' into '*old_flags'.  Then,
614      * turns off the flags that are set to 1 in 'off' and turns on the flags
615      * that are set to 1 in 'on'.  (No bit will be set to 1 in both 'off' and
616      * 'on'; that is, off & on == 0.)
617      *
618      * This function may be invoked from a signal handler.  Therefore, it
619      * should not do anything that is not signal-safe (such as logging). */
620     int (*update_flags)(struct netdev *netdev, enum netdev_flags off,
621                         enum netdev_flags on, enum netdev_flags *old_flags);
622
623 /* ## ------------------- ## */
624 /* ## netdev_rx Functions ## */
625 /* ## ------------------- ## */
626
627 /* If a particular netdev class does not support receiving packets, all these
628  * function pointers must be NULL. */
629
630     /* Life-cycle functions for a netdev_rx.  See the large comment above on
631      * struct netdev_class. */
632     struct netdev_rx *(*rx_alloc)(void);
633     int (*rx_construct)(struct netdev_rx *);
634     void (*rx_destruct)(struct netdev_rx *);
635     void (*rx_dealloc)(struct netdev_rx *);
636
637     /* Attempts to receive a packet from 'rx' into the tailroom of 'buffer',
638      * which should initially be empty.  If successful, returns 0 and
639      * increments 'buffer->size' by the number of bytes in the received packet,
640      * otherwise a positive errno value.  Returns EAGAIN immediately if no
641      * packet is ready to be received.
642      *
643      * Must return EMSGSIZE, and discard the packet, if the received packet
644      * is longer than 'ofpbuf_tailroom(buffer)'.
645      *
646      * Implementations may make use of VLAN_HEADER_LEN bytes of tailroom to
647      * add a VLAN header which is obtained out-of-band to the packet. If
648      * this occurs then VLAN_HEADER_LEN bytes of tailroom will no longer be
649      * available for the packet, otherwise it may be used for the packet
650      * itself.
651      *
652      * It is advised that the tailroom of 'buffer' should be
653      * VLAN_HEADER_LEN bytes longer than the MTU to allow space for an
654      * out-of-band VLAN header to be added to the packet.
655      *
656      * This function may be set to null if it would always return EOPNOTSUPP
657      * anyhow. */
658     int (*rx_recv)(struct netdev_rx *rx, struct ofpbuf *buffer);
659
660     /* Registers with the poll loop to wake up from the next call to
661      * poll_block() when a packet is ready to be received with netdev_rx_recv()
662      * on 'rx'. */
663     void (*rx_wait)(struct netdev_rx *rx);
664
665     /* Discards all packets waiting to be received from 'rx'. */
666     int (*rx_drain)(struct netdev_rx *rx);
667 };
668
669 int netdev_register_provider(const struct netdev_class *);
670 int netdev_unregister_provider(const char *type);
671
672 extern const struct netdev_class netdev_linux_class;
673 extern const struct netdev_class netdev_internal_class;
674 extern const struct netdev_class netdev_tap_class;
675 #if defined(__FreeBSD__) || defined(__NetBSD__)
676 extern const struct netdev_class netdev_bsd_class;
677 #endif
678
679 #ifdef  __cplusplus
680 }
681 #endif
682
683 #endif /* netdev.h */