1#ifndef _GPXE_NETDEVICE_H
2#define _GPXE_NETDEVICE_H
3
4/** @file
5 *
6 * Network device management
7 *
8 */
9
10FILE_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
18struct io_buffer;
19struct net_device;
20struct net_protocol;
21struct ll_protocol;
22struct 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 */
52struct 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 */
92struct 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 */
172struct 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 */
232struct 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 */
243struct 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 */
262struct 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
344extern struct list_head net_devices;
345extern struct net_device_operations null_netdev_operations;
346extern 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 */
354static 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 */
367static 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 */
377static 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 */
389static 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 */
399static inline __attribute__ (( always_inline )) struct net_device *
400netdev_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 */
410static inline __attribute__ (( always_inline )) void
411netdev_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 */
421static inline __attribute__ (( always_inline )) void *
422netdev_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 */
432static inline __attribute__ (( always_inline )) struct settings *
433netdev_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 */
444static inline __attribute__ (( always_inline )) void
445netdev_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 */
456static inline __attribute__ (( always_inline )) void
457netdev_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 */
467static inline __attribute__ (( always_inline )) void
468netdev_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 */
478static inline __attribute__ (( always_inline )) int
479netdev_link_ok ( struct net_device *netdev ) {
480	return ( netdev->link_rc == 0 );
481}
482
483extern void netdev_link_down ( struct net_device *netdev );
484extern int netdev_tx ( struct net_device *netdev, struct io_buffer *iobuf );
485extern void netdev_tx_complete_err ( struct net_device *netdev,
486				 struct io_buffer *iobuf, int rc );
487extern void netdev_tx_complete_next_err ( struct net_device *netdev, int rc );
488extern void netdev_rx ( struct net_device *netdev, struct io_buffer *iobuf );
489extern void netdev_rx_err ( struct net_device *netdev,
490			    struct io_buffer *iobuf, int rc );
491extern void netdev_poll ( struct net_device *netdev );
492extern struct io_buffer * netdev_rx_dequeue ( struct net_device *netdev );
493extern struct net_device * alloc_netdev ( size_t priv_size );
494extern int register_netdev ( struct net_device *netdev );
495extern int netdev_open ( struct net_device *netdev );
496extern void netdev_close ( struct net_device *netdev );
497extern void unregister_netdev ( struct net_device *netdev );
498extern void netdev_irq ( struct net_device *netdev, int enable );
499extern struct net_device * find_netdev ( const char *name );
500extern struct net_device * find_netdev_by_location ( unsigned int bus_type,
501						     unsigned int location );
502extern struct net_device * last_opened_netdev ( void );
503extern int net_tx ( struct io_buffer *iobuf, struct net_device *netdev,
504		    struct net_protocol *net_protocol, const void *ll_dest );
505extern 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 */
516static 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 */
528static 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