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