fd77d893ad64aaa4ed464159361792241ed6c92f
[people/meteger/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         /** Link-layer protocol
152          *
153          * This is an ARPHRD_XXX constant, in network byte order.
154          */
155         uint16_t ll_proto;
156         /** Hardware address length */
157         uint8_t hw_addr_len;
158         /** Link-layer address length */
159         uint8_t ll_addr_len;
160         /** Link-layer header length */
161         uint8_t ll_header_len;
162 };
163
164 /** Network device operations */
165 struct net_device_operations {
166         /** Open network device
167          *
168          * @v netdev    Network device
169          * @ret rc      Return status code
170          *
171          * This method should allocate RX I/O buffers and enable
172          * the hardware to start transmitting and receiving packets.
173          */
174         int ( * open ) ( struct net_device *netdev );
175         /** Close network device
176          *
177          * @v netdev    Network device
178          *
179          * This method should stop the flow of packets, and free up
180          * any packets that are currently in the device's TX queue.
181          */
182         void ( * close ) ( struct net_device *netdev );
183         /** Transmit packet
184          *
185          * @v netdev    Network device
186          * @v iobuf     I/O buffer
187          * @ret rc      Return status code
188          *
189          * This method should cause the hardware to initiate
190          * transmission of the I/O buffer.
191          *
192          * If this method returns success, the I/O buffer remains
193          * owned by the net device's TX queue, and the net device must
194          * eventually call netdev_tx_complete() to free the buffer.
195          * If this method returns failure, the I/O buffer is
196          * immediately released; the failure is interpreted as
197          * "failure to enqueue buffer".
198          *
199          * This method is guaranteed to be called only when the device
200          * is open.
201          */
202         int ( * transmit ) ( struct net_device *netdev,
203                              struct io_buffer *iobuf );
204         /** Poll for completed and received packets
205          *
206          * @v netdev    Network device
207          *
208          * This method should cause the hardware to check for
209          * completed transmissions and received packets.  Any received
210          * packets should be delivered via netdev_rx().
211          *
212          * This method is guaranteed to be called only when the device
213          * is open.
214          */
215         void ( * poll ) ( struct net_device *netdev );
216         /** Enable or disable interrupts
217          *
218          * @v netdev    Network device
219          * @v enable    Interrupts should be enabled
220          */
221         void ( * irq ) ( struct net_device *netdev, int enable );
222 };
223
224 /** Network device error */
225 struct net_device_error {
226         /** Error status code */
227         int rc;
228         /** Error count */
229         unsigned int count;
230 };
231
232 /** Maximum number of unique errors that we will keep track of */
233 #define NETDEV_MAX_UNIQUE_ERRORS 4
234
235 /** Network device statistics */
236 struct net_device_stats {
237         /** Count of successful completions */
238         unsigned int good;
239         /** Count of error completions */
240         unsigned int bad;
241         /** Error breakdowns */
242         struct net_device_error errors[NETDEV_MAX_UNIQUE_ERRORS];
243 };
244
245 /**
246  * A network device
247  *
248  * This structure represents a piece of networking hardware.  It has
249  * properties such as a link-layer address and methods for
250  * transmitting and receiving raw packets.
251  *
252  * Note that this structure must represent a generic network device,
253  * not just an Ethernet device.
254  */
255 struct net_device {
256         /** Reference counter */
257         struct refcnt refcnt;
258         /** List of network devices */
259         struct list_head list;
260         /** List of open network devices */
261         struct list_head open_list;
262         /** Name of this network device */
263         char name[8];
264         /** Underlying hardware device */
265         struct device *dev;
266
267         /** Network device operations */
268         struct net_device_operations *op;
269
270         /** Link-layer protocol */
271         struct ll_protocol *ll_protocol;
272         /** Hardware address
273          *
274          * This is an address which is an intrinsic property of the
275          * hardware, e.g. an address held in EEPROM.
276          *
277          * Note that the hardware address may not be the same length
278          * as the link-layer address.
279          */
280         uint8_t hw_addr[MAX_HW_ADDR_LEN];
281         /** Link-layer address
282          *
283          * This is the current link-layer address assigned to the
284          * device.  It can be changed at runtime.
285          */
286         uint8_t ll_addr[MAX_LL_ADDR_LEN];
287         /** Link-layer broadcast address */
288         const uint8_t *ll_broadcast;
289
290         /** Current device state
291          *
292          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
293          */
294         unsigned int state;
295         /** Link status code
296          *
297          * Zero indicates that the link is up; any other value
298          * indicates the error preventing link-up.
299          */
300         int link_rc;
301         /** Maximum packet length
302          *
303          * This length includes any link-layer headers.
304          */
305         size_t max_pkt_len;
306         /** TX packet queue */
307         struct list_head tx_queue;
308         /** RX packet queue */
309         struct list_head rx_queue;
310         /** TX statistics */
311         struct net_device_stats tx_stats;
312         /** RX statistics */
313         struct net_device_stats rx_stats;
314
315         /** Configuration settings applicable to this device */
316         struct generic_settings settings;
317
318         /** Driver private data */
319         void *priv;
320 };
321
322 /** Network device is open */
323 #define NETDEV_OPEN 0x0001
324
325 /** Link-layer protocol table */
326 #define LL_PROTOCOLS __table ( struct ll_protocol, "ll_protocols" )
327
328 /** Declare a link-layer protocol */
329 #define __ll_protocol  __table_entry ( LL_PROTOCOLS, 01 )
330
331 /** Network-layer protocol table */
332 #define NET_PROTOCOLS __table ( struct net_protocol, "net_protocols" )
333
334 /** Declare a network-layer protocol */
335 #define __net_protocol __table_entry ( NET_PROTOCOLS, 01 )
336
337 extern struct list_head net_devices;
338 extern struct net_device_operations null_netdev_operations;
339 extern struct settings_operations netdev_settings_operations;
340
341 /**
342  * Initialise a network device
343  *
344  * @v netdev            Network device
345  * @v op                Network device operations
346  */
347 static inline void netdev_init ( struct net_device *netdev,
348                                  struct net_device_operations *op ) {
349         netdev->op = op;
350 }
351
352 /**
353  * Stop using a network device
354  *
355  * @v netdev            Network device
356  *
357  * Drivers should call this method immediately before the final call
358  * to netdev_put().
359  */
360 static inline void netdev_nullify ( struct net_device *netdev ) {
361         netdev->op = &null_netdev_operations;
362 }
363
364 /**
365  * Get printable network device link-layer address
366  *
367  * @v netdev            Network device
368  * @ret name            Link-layer address
369  */
370 static inline const char * netdev_addr ( struct net_device *netdev ) {
371         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
372 }
373
374 /** Iterate over all network devices */
375 #define for_each_netdev( netdev ) \
376         list_for_each_entry ( (netdev), &net_devices, list )
377
378 /** There exist some network devices
379  *
380  * @ret existence       Existence of network devices
381  */
382 static inline int have_netdevs ( void ) {
383         return ( ! list_empty ( &net_devices ) );
384 }
385
386 /**
387  * Get reference to network device
388  *
389  * @v netdev            Network device
390  * @ret netdev          Network device
391  */
392 static inline __attribute__ (( always_inline )) struct net_device *
393 netdev_get ( struct net_device *netdev ) {
394         ref_get ( &netdev->refcnt );
395         return netdev;
396 }
397
398 /**
399  * Drop reference to network device
400  *
401  * @v netdev            Network device
402  */
403 static inline __attribute__ (( always_inline )) void
404 netdev_put ( struct net_device *netdev ) {
405         ref_put ( &netdev->refcnt );
406 }
407
408 /**
409  * Get driver private area for this network device
410  *
411  * @v netdev            Network device
412  * @ret priv            Driver private area for this network device
413  */
414 static inline __attribute__ (( always_inline )) void *
415 netdev_priv ( struct net_device *netdev ) {
416         return netdev->priv;
417 }
418
419 /**
420  * Get per-netdevice configuration settings block
421  *
422  * @v netdev            Network device
423  * @ret settings        Settings block
424  */
425 static inline __attribute__ (( always_inline )) struct settings *
426 netdev_settings ( struct net_device *netdev ) {
427         return &netdev->settings.settings;
428 }
429
430 /**
431  * Initialise a per-netdevice configuration settings block
432  *
433  * @v generics          Generic settings block
434  * @v refcnt            Containing object reference counter, or NULL
435  * @v name              Settings block name
436  */
437 static inline __attribute__ (( always_inline )) void
438 netdev_settings_init ( struct net_device *netdev ) {
439         generic_settings_init ( &netdev->settings,
440                                 &netdev->refcnt, netdev->name );
441         netdev->settings.settings.op = &netdev_settings_operations;
442 }
443
444 /**
445  * Mark network device as having link up
446  *
447  * @v netdev            Network device
448  */
449 static inline __attribute__ (( always_inline )) void
450 netdev_link_up ( struct net_device *netdev ) {
451         netdev->link_rc = 0;
452 }
453
454 /**
455  * Mark network device as having link down due to a specific error
456  *
457  * @v netdev            Network device
458  * @v rc                Link status code
459  */
460 static inline __attribute__ (( always_inline )) void
461 netdev_link_err ( struct net_device *netdev, int rc ) {
462         netdev->link_rc = rc;
463 }
464
465 /**
466  * Check link state of network device
467  *
468  * @v netdev            Network device
469  * @ret link_up         Link is up
470  */
471 static inline __attribute__ (( always_inline )) int
472 netdev_link_ok ( struct net_device *netdev ) {
473         return ( netdev->link_rc == 0 );
474 }
475
476 extern void netdev_link_down ( struct net_device *netdev );
477 extern int netdev_tx ( struct net_device *netdev, struct io_buffer *iobuf );
478 extern void netdev_tx_complete_err ( struct net_device *netdev,
479                                  struct io_buffer *iobuf, int rc );
480 extern void netdev_tx_complete_next_err ( struct net_device *netdev, int rc );
481 extern void netdev_rx ( struct net_device *netdev, struct io_buffer *iobuf );
482 extern void netdev_rx_err ( struct net_device *netdev,
483                             struct io_buffer *iobuf, int rc );
484 extern void netdev_poll ( struct net_device *netdev );
485 extern struct io_buffer * netdev_rx_dequeue ( struct net_device *netdev );
486 extern struct net_device * alloc_netdev ( size_t priv_size );
487 extern int register_netdev ( struct net_device *netdev );
488 extern int netdev_open ( struct net_device *netdev );
489 extern void netdev_close ( struct net_device *netdev );
490 extern void unregister_netdev ( struct net_device *netdev );
491 extern void netdev_irq ( struct net_device *netdev, int enable );
492 extern struct net_device * find_netdev ( const char *name );
493 extern struct net_device * find_netdev_by_location ( unsigned int bus_type,
494                                                      unsigned int location );
495 extern struct net_device * last_opened_netdev ( void );
496 extern int net_tx ( struct io_buffer *iobuf, struct net_device *netdev,
497                     struct net_protocol *net_protocol, const void *ll_dest );
498 extern int net_rx ( struct io_buffer *iobuf, struct net_device *netdev,
499                     uint16_t net_proto, const void *ll_source );
500
501 /**
502  * Complete network transmission
503  *
504  * @v netdev            Network device
505  * @v iobuf             I/O buffer
506  *
507  * The packet must currently be in the network device's TX queue.
508  */
509 static inline void netdev_tx_complete ( struct net_device *netdev,
510                                         struct io_buffer *iobuf ) {
511         netdev_tx_complete_err ( netdev, iobuf, 0 );
512 }
513
514 /**
515  * Complete network transmission
516  *
517  * @v netdev            Network device
518  *
519  * Completes the oldest outstanding packet in the TX queue.
520  */
521 static inline void netdev_tx_complete_next ( struct net_device *netdev ) {
522         netdev_tx_complete_next_err ( netdev, 0 );
523 }
524
525 #endif /* _GPXE_NETDEVICE_H */