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