1 #ifndef _IPXE_NETDEVICE_H
2 #define _IPXE_NETDEVICE_H
6 * Network device management
10 FILE_LICENCE ( GPL2_OR_LATER );
13 #include <ipxe/list.h>
14 #include <ipxe/tables.h>
15 #include <ipxe/refcnt.h>
16 #include <ipxe/settings.h>
17 #include <ipxe/interface.h>
25 /** Maximum length of a hardware address
27 * The longest currently-supported link-layer address is for IPoIB.
29 #define MAX_HW_ADDR_LEN 8
31 /** Maximum length of a link-layer address
33 * The longest currently-supported link-layer address is for IPoIB.
35 #define MAX_LL_ADDR_LEN 20
37 /** Maximum length of a link-layer header
39 * The longest currently-supported link-layer header is for 802.11: a
40 * 24-byte frame header plus an 8-byte 802.3 LLC/SNAP header, plus a
41 * possible 4-byte VLAN header. (The IPoIB link-layer pseudo-header
42 * doesn't actually include link-layer addresses; see ipoib.c for
45 #define MAX_LL_HEADER_LEN 36
47 /** Maximum length of a network-layer address */
48 #define MAX_NET_ADDR_LEN 16
50 /** Maximum length of a network-layer header
52 * The longest currently-supported network-layer header is for IPv6 at
55 #define MAX_NET_HEADER_LEN 40
57 /** Maximum combined length of a link-layer and network-layer header */
58 #define MAX_LL_NET_HEADER_LEN ( MAX_LL_HEADER_LEN + MAX_NET_HEADER_LEN )
61 * A network-layer protocol
68 * Process received packet
71 * @v netdev Network device
72 * @v ll_dest Link-layer destination address
73 * @v ll_source Link-layer source address
74 * @v flags Packet flags
75 * @ret rc Return status code
77 * This method takes ownership of the I/O buffer.
79 int ( * rx ) ( struct io_buffer *iobuf, struct net_device *netdev,
80 const void *ll_dest, const void *ll_source,
83 * Transcribe network-layer address
85 * @v net_addr Network-layer address
86 * @ret string Human-readable transcription of address
88 * This method should convert the network-layer address into a
89 * human-readable format (e.g. dotted quad notation for IPv4).
91 * The buffer used to hold the transcription is statically
94 const char * ( *ntoa ) ( const void * net_addr );
95 /** Network-layer protocol
97 * This is an ETH_P_XXX constant, in network-byte order
100 /** Network-layer address length */
101 uint8_t net_addr_len;
104 /** Packet is a multicast (including broadcast) packet */
105 #define LL_MULTICAST 0x0001
107 /** Packet is a broadcast packet */
108 #define LL_BROADCAST 0x0002
111 * A link-layer protocol
118 * Add link-layer header
120 * @v netdev Network device
121 * @v iobuf I/O buffer
122 * @v ll_dest Link-layer destination address
123 * @v ll_source Source link-layer address
124 * @v net_proto Network-layer protocol, in network-byte order
125 * @ret rc Return status code
127 int ( * push ) ( struct net_device *netdev, struct io_buffer *iobuf,
128 const void *ll_dest, const void *ll_source,
129 uint16_t net_proto );
131 * Remove link-layer header
133 * @v netdev Network device
134 * @v iobuf I/O buffer
135 * @ret ll_dest Link-layer destination address
136 * @ret ll_source Source link-layer address
137 * @ret net_proto Network-layer protocol, in network-byte order
138 * @ret flags Packet flags
139 * @ret rc Return status code
141 int ( * pull ) ( struct net_device *netdev, struct io_buffer *iobuf,
142 const void **ll_dest, const void **ll_source,
143 uint16_t *net_proto, unsigned int *flags );
145 * Initialise link-layer address
147 * @v hw_addr Hardware address
148 * @v ll_addr Link-layer address to fill in
150 void ( * init_addr ) ( const void *hw_addr, void *ll_addr );
152 * Transcribe link-layer address
154 * @v ll_addr Link-layer address
155 * @ret string Human-readable transcription of address
157 * This method should convert the link-layer address into a
158 * human-readable format.
160 * The buffer used to hold the transcription is statically
163 const char * ( * ntoa ) ( const void *ll_addr );
165 * Hash multicast address
167 * @v af Address family
168 * @v net_addr Network-layer address
169 * @v ll_addr Link-layer address to fill in
170 * @ret rc Return status code
172 int ( * mc_hash ) ( unsigned int af, const void *net_addr,
175 * Generate Ethernet-compatible compressed link-layer address
177 * @v ll_addr Link-layer address
178 * @v eth_addr Ethernet-compatible address to fill in
179 * @ret rc Return status code
181 int ( * eth_addr ) ( const void *ll_addr, void *eth_addr );
183 * Generate EUI-64 address
185 * @v ll_addr Link-layer address
186 * @v eui64 EUI-64 address to fill in
187 * @ret rc Return status code
189 int ( * eui64 ) ( const void *ll_addr, void *eui64 );
190 /** Link-layer protocol
192 * This is an ARPHRD_XXX constant, in network byte order.
195 /** Hardware address length */
197 /** Link-layer address length */
199 /** Link-layer header length */
200 uint8_t ll_header_len;
205 /** Local link-layer address functions only as a name
207 * This flag indicates that the local link-layer address cannot
208 * directly be used as a destination address by a remote node.
210 #define LL_NAME_ONLY 0x0001
212 /** Network device operations */
213 struct net_device_operations {
214 /** Open network device
216 * @v netdev Network device
217 * @ret rc Return status code
219 * This method should allocate RX I/O buffers and enable
220 * the hardware to start transmitting and receiving packets.
222 int ( * open ) ( struct net_device *netdev );
223 /** Close network device
225 * @v netdev Network device
227 * This method should stop the flow of packets, and free up
228 * any packets that are currently in the device's TX queue.
230 void ( * close ) ( struct net_device *netdev );
233 * @v netdev Network device
234 * @v iobuf I/O buffer
235 * @ret rc Return status code
237 * This method should cause the hardware to initiate
238 * transmission of the I/O buffer.
240 * If this method returns success, the I/O buffer remains
241 * owned by the net device's TX queue, and the net device must
242 * eventually call netdev_tx_complete() to free the buffer.
243 * If this method returns failure, the I/O buffer is
244 * immediately released; the failure is interpreted as
245 * "failure to enqueue buffer".
247 * This method is guaranteed to be called only when the device
250 int ( * transmit ) ( struct net_device *netdev,
251 struct io_buffer *iobuf );
252 /** Poll for completed and received packets
254 * @v netdev Network device
256 * This method should cause the hardware to check for
257 * completed transmissions and received packets. Any received
258 * packets should be delivered via netdev_rx().
260 * This method is guaranteed to be called only when the device
263 void ( * poll ) ( struct net_device *netdev );
264 /** Enable or disable interrupts
266 * @v netdev Network device
267 * @v enable Interrupts should be enabled
269 * This method may be NULL to indicate that interrupts are not
272 void ( * irq ) ( struct net_device *netdev, int enable );
275 /** Network device error */
276 struct net_device_error {
277 /** Error status code */
283 /** Maximum number of unique errors that we will keep track of */
284 #define NETDEV_MAX_UNIQUE_ERRORS 4
286 /** Network device statistics */
287 struct net_device_stats {
288 /** Count of successful completions */
290 /** Count of error completions */
292 /** Error breakdowns */
293 struct net_device_error errors[NETDEV_MAX_UNIQUE_ERRORS];
296 /** A network device configuration */
297 struct net_device_configuration {
298 /** Network device */
299 struct net_device *netdev;
300 /** Network device configurator */
301 struct net_device_configurator *configurator;
302 /** Configuration status */
304 /** Job control interface */
305 struct interface job;
308 /** A network device configurator */
309 struct net_device_configurator {
312 /** Check applicability of configurator
314 * @v netdev Network device
315 * @ret applies Configurator applies to this network device
317 int ( * applies ) ( struct net_device *netdev );
318 /** Start configuring network device
320 * @v job Job control interface
321 * @v netdev Network device
322 * @ret rc Return status code
324 int ( * start ) ( struct interface *job, struct net_device *netdev );
327 /** Network device configurator table */
328 #define NET_DEVICE_CONFIGURATORS \
329 __table ( struct net_device_configurator, "net_device_configurators" )
331 /** Declare a network device configurator */
332 #define __net_device_configurator \
333 __table_entry ( NET_DEVICE_CONFIGURATORS, 01 )
335 /** Maximum length of a network device name */
336 #define NETDEV_NAME_LEN 12
341 * This structure represents a piece of networking hardware. It has
342 * properties such as a link-layer address and methods for
343 * transmitting and receiving raw packets.
345 * Note that this structure must represent a generic network device,
346 * not just an Ethernet device.
349 /** Reference counter */
350 struct refcnt refcnt;
351 /** List of network devices */
352 struct list_head list;
353 /** List of open network devices */
354 struct list_head open_list;
355 /** Index of this network device */
357 /** Name of this network device */
358 char name[NETDEV_NAME_LEN];
359 /** Underlying hardware device */
362 /** Network device operations */
363 struct net_device_operations *op;
365 /** Link-layer protocol */
366 struct ll_protocol *ll_protocol;
369 * This is an address which is an intrinsic property of the
370 * hardware, e.g. an address held in EEPROM.
372 * Note that the hardware address may not be the same length
373 * as the link-layer address.
375 uint8_t hw_addr[MAX_HW_ADDR_LEN];
376 /** Link-layer address
378 * This is the current link-layer address assigned to the
379 * device. It can be changed at runtime.
381 uint8_t ll_addr[MAX_LL_ADDR_LEN];
382 /** Link-layer broadcast address */
383 const uint8_t *ll_broadcast;
385 /** Current device state
387 * This is the bitwise-OR of zero or more NETDEV_XXX constants.
392 * Zero indicates that the link is up; any other value
393 * indicates the error preventing link-up.
396 /** Maximum packet length
398 * This length includes any link-layer headers.
401 /** TX packet queue */
402 struct list_head tx_queue;
403 /** Deferred TX packet queue */
404 struct list_head tx_deferred;
405 /** RX packet queue */
406 struct list_head rx_queue;
408 struct net_device_stats tx_stats;
410 struct net_device_stats rx_stats;
412 /** Configuration settings applicable to this device */
413 struct generic_settings settings;
415 /** Driver private data */
418 /** Network device configurations (variable length) */
419 struct net_device_configuration configs[0];
422 /** Network device is open */
423 #define NETDEV_OPEN 0x0001
425 /** Network device interrupts are enabled */
426 #define NETDEV_IRQ_ENABLED 0x0002
428 /** Network device receive queue processing is frozen */
429 #define NETDEV_RX_FROZEN 0x0004
431 /** Link-layer protocol table */
432 #define LL_PROTOCOLS __table ( struct ll_protocol, "ll_protocols" )
434 /** Declare a link-layer protocol */
435 #define __ll_protocol __table_entry ( LL_PROTOCOLS, 01 )
437 /** Network-layer protocol table */
438 #define NET_PROTOCOLS __table ( struct net_protocol, "net_protocols" )
440 /** Declare a network-layer protocol */
441 #define __net_protocol __table_entry ( NET_PROTOCOLS, 01 )
443 /** A network upper-layer driver */
449 * @v netdev Network device
450 * @ret rc Return status code
452 int ( * probe ) ( struct net_device *netdev );
453 /** Notify of device or link state change
455 * @v netdev Network device
457 void ( * notify ) ( struct net_device *netdev );
460 * @v netdev Network device
462 void ( * remove ) ( struct net_device *netdev );
465 /** Network driver table */
466 #define NET_DRIVERS __table ( struct net_driver, "net_drivers" )
468 /** Declare a network driver */
469 #define __net_driver __table_entry ( NET_DRIVERS, 01 )
471 extern struct list_head net_devices;
472 extern struct net_device_operations null_netdev_operations;
473 extern struct settings_operations netdev_settings_operations;
476 * Initialise a network device
478 * @v netdev Network device
479 * @v op Network device operations
481 static inline void netdev_init ( struct net_device *netdev,
482 struct net_device_operations *op ) {
487 * Stop using a network device
489 * @v netdev Network device
491 * Drivers should call this method immediately before the final call
494 static inline void netdev_nullify ( struct net_device *netdev ) {
495 netdev->op = &null_netdev_operations;
499 * Get printable network device link-layer address
501 * @v netdev Network device
502 * @ret name Link-layer address
504 static inline const char * netdev_addr ( struct net_device *netdev ) {
505 return netdev->ll_protocol->ntoa ( netdev->ll_addr );
508 /** Iterate over all network devices */
509 #define for_each_netdev( netdev ) \
510 list_for_each_entry ( (netdev), &net_devices, list )
512 /** There exist some network devices
514 * @ret existence Existence of network devices
516 static inline int have_netdevs ( void ) {
517 return ( ! list_empty ( &net_devices ) );
521 * Get reference to network device
523 * @v netdev Network device
524 * @ret netdev Network device
526 static inline __attribute__ (( always_inline )) struct net_device *
527 netdev_get ( struct net_device *netdev ) {
528 ref_get ( &netdev->refcnt );
533 * Drop reference to network device
535 * @v netdev Network device
537 static inline __attribute__ (( always_inline )) void
538 netdev_put ( struct net_device *netdev ) {
539 ref_put ( &netdev->refcnt );
543 * Get driver private area for this network device
545 * @v netdev Network device
546 * @ret priv Driver private area for this network device
548 static inline __attribute__ (( always_inline )) void *
549 netdev_priv ( struct net_device *netdev ) {
554 * Get per-netdevice configuration settings block
556 * @v netdev Network device
557 * @ret settings Settings block
559 static inline __attribute__ (( always_inline )) struct settings *
560 netdev_settings ( struct net_device *netdev ) {
561 return &netdev->settings.settings;
565 * Initialise a per-netdevice configuration settings block
567 * @v generics Generic settings block
568 * @v refcnt Containing object reference counter, or NULL
569 * @v name Settings block name
571 static inline __attribute__ (( always_inline )) void
572 netdev_settings_init ( struct net_device *netdev ) {
573 generic_settings_init ( &netdev->settings, &netdev->refcnt );
574 netdev->settings.settings.op = &netdev_settings_operations;
578 * Get network device configuration
580 * @v netdev Network device
581 * @v configurator Network device configurator
582 * @ret config Network device configuration
584 static inline struct net_device_configuration *
585 netdev_configuration ( struct net_device *netdev,
586 struct net_device_configurator *configurator ) {
588 return &netdev->configs[ table_index ( NET_DEVICE_CONFIGURATORS,
593 * Check if configurator applies to network device
595 * @v netdev Network device
596 * @v configurator Network device configurator
597 * @ret applies Configurator applies to network device
600 netdev_configurator_applies ( struct net_device *netdev,
601 struct net_device_configurator *configurator ) {
602 return ( ( configurator->applies == NULL ) ||
603 configurator->applies ( netdev ) );
607 * Check link state of network device
609 * @v netdev Network device
610 * @ret link_up Link is up
612 static inline __attribute__ (( always_inline )) int
613 netdev_link_ok ( struct net_device *netdev ) {
614 return ( netdev->link_rc == 0 );
618 * Check whether or not network device is open
620 * @v netdev Network device
621 * @ret is_open Network device is open
623 static inline __attribute__ (( always_inline )) int
624 netdev_is_open ( struct net_device *netdev ) {
625 return ( netdev->state & NETDEV_OPEN );
629 * Check whether or not network device supports interrupts
631 * @v netdev Network device
632 * @ret irq_supported Network device supports interrupts
634 static inline __attribute__ (( always_inline )) int
635 netdev_irq_supported ( struct net_device *netdev ) {
636 return ( netdev->op->irq != NULL );
640 * Check whether or not network device interrupts are currently enabled
642 * @v netdev Network device
643 * @ret irq_enabled Network device interrupts are enabled
645 static inline __attribute__ (( always_inline )) int
646 netdev_irq_enabled ( struct net_device *netdev ) {
647 return ( netdev->state & NETDEV_IRQ_ENABLED );
651 * Check whether or not network device receive queue processing is frozen
653 * @v netdev Network device
654 * @ret rx_frozen Network device receive queue processing is frozen
656 static inline __attribute__ (( always_inline )) int
657 netdev_rx_frozen ( struct net_device *netdev ) {
658 return ( netdev->state & NETDEV_RX_FROZEN );
661 extern void netdev_rx_freeze ( struct net_device *netdev );
662 extern void netdev_rx_unfreeze ( struct net_device *netdev );
663 extern void netdev_link_err ( struct net_device *netdev, int rc );
664 extern void netdev_link_down ( struct net_device *netdev );
665 extern int netdev_tx ( struct net_device *netdev, struct io_buffer *iobuf );
666 extern void netdev_tx_defer ( struct net_device *netdev,
667 struct io_buffer *iobuf );
668 extern void netdev_tx_err ( struct net_device *netdev,
669 struct io_buffer *iobuf, int rc );
670 extern void netdev_tx_complete_err ( struct net_device *netdev,
671 struct io_buffer *iobuf, int rc );
672 extern void netdev_tx_complete_next_err ( struct net_device *netdev, int rc );
673 extern void netdev_rx ( struct net_device *netdev, struct io_buffer *iobuf );
674 extern void netdev_rx_err ( struct net_device *netdev,
675 struct io_buffer *iobuf, int rc );
676 extern void netdev_poll ( struct net_device *netdev );
677 extern struct io_buffer * netdev_rx_dequeue ( struct net_device *netdev );
678 extern struct net_device * alloc_netdev ( size_t priv_size );
679 extern int register_netdev ( struct net_device *netdev );
680 extern int netdev_open ( struct net_device *netdev );
681 extern void netdev_close ( struct net_device *netdev );
682 extern void unregister_netdev ( struct net_device *netdev );
683 extern void netdev_irq ( struct net_device *netdev, int enable );
684 extern struct net_device * find_netdev ( const char *name );
685 extern struct net_device * find_netdev_by_index ( unsigned int index );
686 extern struct net_device * find_netdev_by_location ( unsigned int bus_type,
687 unsigned int location );
688 extern struct net_device *
689 find_netdev_by_ll_addr ( struct ll_protocol *ll_protocol, const void *ll_addr );
690 extern struct net_device * last_opened_netdev ( void );
691 extern int net_tx ( struct io_buffer *iobuf, struct net_device *netdev,
692 struct net_protocol *net_protocol, const void *ll_dest,
693 const void *ll_source );
694 extern int net_rx ( struct io_buffer *iobuf, struct net_device *netdev,
695 uint16_t net_proto, const void *ll_dest,
696 const void *ll_source, unsigned int flags );
697 extern void net_poll ( void );
698 extern struct net_device_configurator *
699 find_netdev_configurator ( const char *name );
700 extern int netdev_configure ( struct net_device *netdev,
701 struct net_device_configurator *configurator );
702 extern int netdev_configure_all ( struct net_device *netdev );
703 extern int netdev_configuration_in_progress ( struct net_device *netdev );
704 extern int netdev_configuration_ok ( struct net_device *netdev );
707 * Complete network transmission
709 * @v netdev Network device
710 * @v iobuf I/O buffer
712 * The packet must currently be in the network device's TX queue.
714 static inline void netdev_tx_complete ( struct net_device *netdev,
715 struct io_buffer *iobuf ) {
716 netdev_tx_complete_err ( netdev, iobuf, 0 );
720 * Complete network transmission
722 * @v netdev Network device
724 * Completes the oldest outstanding packet in the TX queue.
726 static inline void netdev_tx_complete_next ( struct net_device *netdev ) {
727 netdev_tx_complete_next_err ( netdev, 0 );
731 * Mark network device as having link up
733 * @v netdev Network device
735 static inline __attribute__ (( always_inline )) void
736 netdev_link_up ( struct net_device *netdev ) {
737 netdev_link_err ( netdev, 0 );
740 #endif /* _IPXE_NETDEVICE_H */