[netdevice] Record whether or not interrupts are currently enabled
[people/pcmattman/gpxe.git] / src / include / gpxe / netdevice.h
1 #ifndef _GPXE_NETDEVICE_H
2 #define _GPXE_NETDEVICE_H
3
4 /** @file
5  *
6  * Network device management
7  *
8  */
9
10 FILE_LICENCE ( GPL2_OR_LATER );
11
12 #include <stdint.h>
13 #include <gpxe/list.h>
14 #include <gpxe/tables.h>
15 #include <gpxe/refcnt.h>
16 #include <gpxe/settings.h>
17
18 struct io_buffer;
19 struct net_device;
20 struct net_protocol;
21 struct ll_protocol;
22 struct device;
23
24 /** Maximum length of a hardware address
25  *
26  * The longest currently-supported link-layer address is for IPoIB.
27  */
28 #define MAX_HW_ADDR_LEN 8
29
30 /** Maximum length of a link-layer address
31  *
32  * The longest currently-supported link-layer address is for IPoIB.
33  */
34 #define MAX_LL_ADDR_LEN 20
35
36 /** Maximum length of a link-layer header
37  *
38  * The longest currently-supported link-layer header is for 802.11: a
39  * 24-byte frame header plus an 8-byte 802.3 LLC/SNAP header.  (The
40  * IPoIB link-layer pseudo-header doesn't actually include link-layer
41  * addresses; see ipoib.c for details).
42  */
43 #define MAX_LL_HEADER_LEN 32
44
45 /** Maximum length of a network-layer address */
46 #define MAX_NET_ADDR_LEN 4
47
48 /**
49  * A network-layer protocol
50  *
51  */
52 struct net_protocol {
53         /** Protocol name */
54         const char *name;
55         /**
56          * Process received packet
57          *
58          * @v iobuf     I/O buffer
59          * @v netdev    Network device
60          * @v ll_source Link-layer source address
61          *
62          * This method takes ownership of the I/O buffer.
63          */
64         int ( * rx ) ( struct io_buffer *iobuf, struct net_device *netdev,
65                        const void *ll_source );
66         /**
67          * Transcribe network-layer address
68          *
69          * @v net_addr  Network-layer address
70          * @ret string  Human-readable transcription of address
71          *
72          * This method should convert the network-layer address into a
73          * human-readable format (e.g. dotted quad notation for IPv4).
74          *
75          * The buffer used to hold the transcription is statically
76          * allocated.
77          */
78         const char * ( *ntoa ) ( const void * net_addr );
79         /** Network-layer protocol
80          *
81          * This is an ETH_P_XXX constant, in network-byte order
82          */
83         uint16_t net_proto;
84         /** Network-layer address length */
85         uint8_t net_addr_len;
86 };
87
88 /**
89  * A link-layer protocol
90  *
91  */
92 struct ll_protocol {
93         /** Protocol name */
94         const char *name;
95         /**
96          * Add link-layer header
97          *
98          * @v netdev            Network device
99          * @v iobuf             I/O buffer
100          * @v ll_dest           Link-layer destination address
101          * @v ll_source         Source link-layer address
102          * @v net_proto         Network-layer protocol, in network-byte order
103          * @ret rc              Return status code
104          */
105         int ( * push ) ( struct net_device *netdev, struct io_buffer *iobuf,
106                          const void *ll_dest, const void *ll_source,
107                          uint16_t net_proto );
108         /**
109          * Remove link-layer header
110          *
111          * @v netdev            Network device
112          * @v iobuf             I/O buffer
113          * @ret ll_dest         Link-layer destination address
114          * @ret ll_source       Source link-layer address
115          * @ret net_proto       Network-layer protocol, in network-byte order
116          * @ret rc              Return status code
117          */
118         int ( * pull ) ( struct net_device *netdev, struct io_buffer *iobuf,
119                          const void **ll_dest, const void **ll_source,
120                          uint16_t *net_proto );
121         /**
122          * Initialise link-layer address
123          *
124          * @v hw_addr           Hardware address
125          * @v ll_addr           Link-layer address to fill in
126          */
127         void ( * init_addr ) ( const void *hw_addr, void *ll_addr );
128         /**
129          * Transcribe link-layer address
130          *
131          * @v ll_addr           Link-layer address
132          * @ret string          Human-readable transcription of address
133          *
134          * This method should convert the link-layer address into a
135          * human-readable format.
136          *
137          * The buffer used to hold the transcription is statically
138          * allocated.
139          */
140         const char * ( * ntoa ) ( const void *ll_addr );
141         /**
142          * Hash multicast address
143          *
144          * @v af                Address family
145          * @v net_addr          Network-layer address
146          * @v ll_addr           Link-layer address to fill in
147          * @ret rc              Return status code
148          */
149         int ( * mc_hash ) ( unsigned int af, const void *net_addr,
150                             void *ll_addr );
151         /**
152          * Generate Ethernet-compatible compressed link-layer address
153          *
154          * @v ll_addr           Link-layer address
155          * @v eth_addr          Ethernet-compatible address to fill in
156          */
157         int ( * eth_addr ) ( const void *ll_addr, void *eth_addr );
158         /** Link-layer protocol
159          *
160          * This is an ARPHRD_XXX constant, in network byte order.
161          */
162         uint16_t ll_proto;
163         /** Hardware address length */
164         uint8_t hw_addr_len;
165         /** Link-layer address length */
166         uint8_t ll_addr_len;
167         /** Link-layer header length */
168         uint8_t ll_header_len;
169 };
170
171 /** Network device operations */
172 struct net_device_operations {
173         /** Open network device
174          *
175          * @v netdev    Network device
176          * @ret rc      Return status code
177          *
178          * This method should allocate RX I/O buffers and enable
179          * the hardware to start transmitting and receiving packets.
180          */
181         int ( * open ) ( struct net_device *netdev );
182         /** Close network device
183          *
184          * @v netdev    Network device
185          *
186          * This method should stop the flow of packets, and free up
187          * any packets that are currently in the device's TX queue.
188          */
189         void ( * close ) ( struct net_device *netdev );
190         /** Transmit packet
191          *
192          * @v netdev    Network device
193          * @v iobuf     I/O buffer
194          * @ret rc      Return status code
195          *
196          * This method should cause the hardware to initiate
197          * transmission of the I/O buffer.
198          *
199          * If this method returns success, the I/O buffer remains
200          * owned by the net device's TX queue, and the net device must
201          * eventually call netdev_tx_complete() to free the buffer.
202          * If this method returns failure, the I/O buffer is
203          * immediately released; the failure is interpreted as
204          * "failure to enqueue buffer".
205          *
206          * This method is guaranteed to be called only when the device
207          * is open.
208          */
209         int ( * transmit ) ( struct net_device *netdev,
210                              struct io_buffer *iobuf );
211         /** Poll for completed and received packets
212          *
213          * @v netdev    Network device
214          *
215          * This method should cause the hardware to check for
216          * completed transmissions and received packets.  Any received
217          * packets should be delivered via netdev_rx().
218          *
219          * This method is guaranteed to be called only when the device
220          * is open.
221          */
222         void ( * poll ) ( struct net_device *netdev );
223         /** Enable or disable interrupts
224          *
225          * @v netdev    Network device
226          * @v enable    Interrupts should be enabled
227          */
228         void ( * irq ) ( struct net_device *netdev, int enable );
229 };
230
231 /** Network device error */
232 struct net_device_error {
233         /** Error status code */
234         int rc;
235         /** Error count */
236         unsigned int count;
237 };
238
239 /** Maximum number of unique errors that we will keep track of */
240 #define NETDEV_MAX_UNIQUE_ERRORS 4
241
242 /** Network device statistics */
243 struct net_device_stats {
244         /** Count of successful completions */
245         unsigned int good;
246         /** Count of error completions */
247         unsigned int bad;
248         /** Error breakdowns */
249         struct net_device_error errors[NETDEV_MAX_UNIQUE_ERRORS];
250 };
251
252 /**
253  * A network device
254  *
255  * This structure represents a piece of networking hardware.  It has
256  * properties such as a link-layer address and methods for
257  * transmitting and receiving raw packets.
258  *
259  * Note that this structure must represent a generic network device,
260  * not just an Ethernet device.
261  */
262 struct net_device {
263         /** Reference counter */
264         struct refcnt refcnt;
265         /** List of network devices */
266         struct list_head list;
267         /** List of open network devices */
268         struct list_head open_list;
269         /** Name of this network device */
270         char name[8];
271         /** Underlying hardware device */
272         struct device *dev;
273
274         /** Network device operations */
275         struct net_device_operations *op;
276
277         /** Link-layer protocol */
278         struct ll_protocol *ll_protocol;
279         /** Hardware address
280          *
281          * This is an address which is an intrinsic property of the
282          * hardware, e.g. an address held in EEPROM.
283          *
284          * Note that the hardware address may not be the same length
285          * as the link-layer address.
286          */
287         uint8_t hw_addr[MAX_HW_ADDR_LEN];
288         /** Link-layer address
289          *
290          * This is the current link-layer address assigned to the
291          * device.  It can be changed at runtime.
292          */
293         uint8_t ll_addr[MAX_LL_ADDR_LEN];
294         /** Link-layer broadcast address */
295         const uint8_t *ll_broadcast;
296
297         /** Current device state
298          *
299          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
300          */
301         unsigned int state;
302         /** Link status code
303          *
304          * Zero indicates that the link is up; any other value
305          * indicates the error preventing link-up.
306          */
307         int link_rc;
308         /** Maximum packet length
309          *
310          * This length includes any link-layer headers.
311          */
312         size_t max_pkt_len;
313         /** TX packet queue */
314         struct list_head tx_queue;
315         /** RX packet queue */
316         struct list_head rx_queue;
317         /** TX statistics */
318         struct net_device_stats tx_stats;
319         /** RX statistics */
320         struct net_device_stats rx_stats;
321
322         /** Configuration settings applicable to this device */
323         struct generic_settings settings;
324
325         /** Driver private data */
326         void *priv;
327 };
328
329 /** Network device is open */
330 #define NETDEV_OPEN 0x0001
331
332 /** Network device interrupts are enabled */
333 #define NETDEV_IRQ_ENABLED 0x0002
334
335 /** Link-layer protocol table */
336 #define LL_PROTOCOLS __table ( struct ll_protocol, "ll_protocols" )
337
338 /** Declare a link-layer protocol */
339 #define __ll_protocol  __table_entry ( LL_PROTOCOLS, 01 )
340
341 /** Network-layer protocol table */
342 #define NET_PROTOCOLS __table ( struct net_protocol, "net_protocols" )
343
344 /** Declare a network-layer protocol */
345 #define __net_protocol __table_entry ( NET_PROTOCOLS, 01 )
346
347 extern struct list_head net_devices;
348 extern struct net_device_operations null_netdev_operations;
349 extern struct settings_operations netdev_settings_operations;
350
351 /**
352  * Initialise a network device
353  *
354  * @v netdev            Network device
355  * @v op                Network device operations
356  */
357 static inline void netdev_init ( struct net_device *netdev,
358                                  struct net_device_operations *op ) {
359         netdev->op = op;
360 }
361
362 /**
363  * Stop using a network device
364  *
365  * @v netdev            Network device
366  *
367  * Drivers should call this method immediately before the final call
368  * to netdev_put().
369  */
370 static inline void netdev_nullify ( struct net_device *netdev ) {
371         netdev->op = &null_netdev_operations;
372 }
373
374 /**
375  * Get printable network device link-layer address
376  *
377  * @v netdev            Network device
378  * @ret name            Link-layer address
379  */
380 static inline const char * netdev_addr ( struct net_device *netdev ) {
381         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
382 }
383
384 /** Iterate over all network devices */
385 #define for_each_netdev( netdev ) \
386         list_for_each_entry ( (netdev), &net_devices, list )
387
388 /** There exist some network devices
389  *
390  * @ret existence       Existence of network devices
391  */
392 static inline int have_netdevs ( void ) {
393         return ( ! list_empty ( &net_devices ) );
394 }
395
396 /**
397  * Get reference to network device
398  *
399  * @v netdev            Network device
400  * @ret netdev          Network device
401  */
402 static inline __attribute__ (( always_inline )) struct net_device *
403 netdev_get ( struct net_device *netdev ) {
404         ref_get ( &netdev->refcnt );
405         return netdev;
406 }
407
408 /**
409  * Drop reference to network device
410  *
411  * @v netdev            Network device
412  */
413 static inline __attribute__ (( always_inline )) void
414 netdev_put ( struct net_device *netdev ) {
415         ref_put ( &netdev->refcnt );
416 }
417
418 /**
419  * Get driver private area for this network device
420  *
421  * @v netdev            Network device
422  * @ret priv            Driver private area for this network device
423  */
424 static inline __attribute__ (( always_inline )) void *
425 netdev_priv ( struct net_device *netdev ) {
426         return netdev->priv;
427 }
428
429 /**
430  * Get per-netdevice configuration settings block
431  *
432  * @v netdev            Network device
433  * @ret settings        Settings block
434  */
435 static inline __attribute__ (( always_inline )) struct settings *
436 netdev_settings ( struct net_device *netdev ) {
437         return &netdev->settings.settings;
438 }
439
440 /**
441  * Initialise a per-netdevice configuration settings block
442  *
443  * @v generics          Generic settings block
444  * @v refcnt            Containing object reference counter, or NULL
445  * @v name              Settings block name
446  */
447 static inline __attribute__ (( always_inline )) void
448 netdev_settings_init ( struct net_device *netdev ) {
449         generic_settings_init ( &netdev->settings,
450                                 &netdev->refcnt, netdev->name );
451         netdev->settings.settings.op = &netdev_settings_operations;
452 }
453
454 /**
455  * Mark network device as having link up
456  *
457  * @v netdev            Network device
458  */
459 static inline __attribute__ (( always_inline )) void
460 netdev_link_up ( struct net_device *netdev ) {
461         netdev->link_rc = 0;
462 }
463
464 /**
465  * Mark network device as having link down due to a specific error
466  *
467  * @v netdev            Network device
468  * @v rc                Link status code
469  */
470 static inline __attribute__ (( always_inline )) void
471 netdev_link_err ( struct net_device *netdev, int rc ) {
472         netdev->link_rc = rc;
473 }
474
475 /**
476  * Check link state of network device
477  *
478  * @v netdev            Network device
479  * @ret link_up         Link is up
480  */
481 static inline __attribute__ (( always_inline )) int
482 netdev_link_ok ( struct net_device *netdev ) {
483         return ( netdev->link_rc == 0 );
484 }
485
486 /**
487  * Check whether or not network device is open
488  *
489  * @v netdev            Network device
490  * @v is_open           Network device is open
491  */
492 static inline __attribute__ (( always_inline )) int
493 netdev_is_open ( struct net_device *netdev ) {
494         return ( netdev->state & NETDEV_OPEN );
495 }
496
497 /**
498  * Check whether or not network device interrupts are currently enabled
499  *
500  * @v netdev            Network device
501  * @v irq_enabled       Network device interrupts are enabled
502  */
503 static inline __attribute__ (( always_inline )) int
504 netdev_irq_enabled ( struct net_device *netdev ) {
505         return ( netdev->state & NETDEV_IRQ_ENABLED );
506 }
507
508 extern void netdev_link_down ( struct net_device *netdev );
509 extern int netdev_tx ( struct net_device *netdev, struct io_buffer *iobuf );
510 extern void netdev_tx_complete_err ( struct net_device *netdev,
511                                  struct io_buffer *iobuf, int rc );
512 extern void netdev_tx_complete_next_err ( struct net_device *netdev, int rc );
513 extern void netdev_rx ( struct net_device *netdev, struct io_buffer *iobuf );
514 extern void netdev_rx_err ( struct net_device *netdev,
515                             struct io_buffer *iobuf, int rc );
516 extern void netdev_poll ( struct net_device *netdev );
517 extern struct io_buffer * netdev_rx_dequeue ( struct net_device *netdev );
518 extern struct net_device * alloc_netdev ( size_t priv_size );
519 extern int register_netdev ( struct net_device *netdev );
520 extern int netdev_open ( struct net_device *netdev );
521 extern void netdev_close ( struct net_device *netdev );
522 extern void unregister_netdev ( struct net_device *netdev );
523 extern void netdev_irq ( struct net_device *netdev, int enable );
524 extern struct net_device * find_netdev ( const char *name );
525 extern struct net_device * find_netdev_by_location ( unsigned int bus_type,
526                                                      unsigned int location );
527 extern struct net_device * last_opened_netdev ( void );
528 extern int net_tx ( struct io_buffer *iobuf, struct net_device *netdev,
529                     struct net_protocol *net_protocol, const void *ll_dest );
530 extern int net_rx ( struct io_buffer *iobuf, struct net_device *netdev,
531                     uint16_t net_proto, const void *ll_source );
532
533 /**
534  * Complete network transmission
535  *
536  * @v netdev            Network device
537  * @v iobuf             I/O buffer
538  *
539  * The packet must currently be in the network device's TX queue.
540  */
541 static inline void netdev_tx_complete ( struct net_device *netdev,
542                                         struct io_buffer *iobuf ) {
543         netdev_tx_complete_err ( netdev, iobuf, 0 );
544 }
545
546 /**
547  * Complete network transmission
548  *
549  * @v netdev            Network device
550  *
551  * Completes the oldest outstanding packet in the TX queue.
552  */
553 static inline void netdev_tx_complete_next ( struct net_device *netdev ) {
554         netdev_tx_complete_next_err ( netdev, 0 );
555 }
556
557 #endif /* _GPXE_NETDEVICE_H */