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