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