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