1 #ifndef _GPXE_NETDEVICE_H
2 #define _GPXE_NETDEVICE_H
6 * Network device management
10 FILE_LICENCE ( GPL2_OR_LATER );
13 #include <gpxe/list.h>
14 #include <gpxe/tables.h>
15 #include <gpxe/refcnt.h>
16 #include <gpxe/settings.h>
24 /** Maximum length of a link-layer address */
25 #define MAX_LL_ADDR_LEN 20
27 /** Maximum length of a link-layer header */
28 #define MAX_LL_HEADER_LEN 6
30 /** Maximum length of a network-layer address */
31 #define MAX_NET_ADDR_LEN 4
34 * A network-layer protocol
41 * Process received packet
44 * @v netdev Network device
45 * @v ll_source Link-layer source address
47 * This method takes ownership of the I/O buffer.
49 int ( * rx ) ( struct io_buffer *iobuf, struct net_device *netdev,
50 const void *ll_source );
52 * Transcribe network-layer address
54 * @v net_addr Network-layer address
55 * @ret string Human-readable transcription of address
57 * This method should convert the network-layer address into a
58 * human-readable format (e.g. dotted quad notation for IPv4).
60 * The buffer used to hold the transcription is statically
63 const char * ( *ntoa ) ( const void * net_addr );
64 /** Network-layer protocol
66 * This is an ETH_P_XXX constant, in network-byte order
69 /** Network-layer address length */
74 * A link-layer protocol
81 * Add link-layer header
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
89 int ( * push ) ( struct io_buffer *iobuf, const void *ll_dest,
90 const void *ll_source, uint16_t net_proto );
92 * Remove link-layer header
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
100 int ( * pull ) ( struct io_buffer *iobuf, const void **ll_dest,
101 const void **ll_source, uint16_t *net_proto );
103 * Transcribe link-layer address
105 * @v ll_addr Link-layer address
106 * @ret string Human-readable transcription of address
108 * This method should convert the link-layer address into a
109 * human-readable format.
111 * The buffer used to hold the transcription is statically
114 const char * ( * ntoa ) ( const void * ll_addr );
116 * Hash multicast address
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
123 int ( * mc_hash ) ( unsigned int af, const void *net_addr,
125 /** Link-layer protocol
127 * This is an ARPHRD_XXX constant, in network byte order.
130 /** Link-layer address length */
132 /** Link-layer header length */
133 uint8_t ll_header_len;
134 /** Link-layer broadcast address */
135 const uint8_t *ll_broadcast;
138 /** Network device operations */
139 struct net_device_operations {
140 /** Open network device
142 * @v netdev Network device
143 * @ret rc Return status code
145 * This method should allocate RX I/O buffers and enable
146 * the hardware to start transmitting and receiving packets.
148 int ( * open ) ( struct net_device *netdev );
149 /** Close network device
151 * @v netdev Network device
153 * This method should stop the flow of packets, and free up
154 * any packets that are currently in the device's TX queue.
156 void ( * close ) ( struct net_device *netdev );
159 * @v netdev Network device
160 * @v iobuf I/O buffer
161 * @ret rc Return status code
163 * This method should cause the hardware to initiate
164 * transmission of the I/O buffer.
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".
173 * This method is guaranteed to be called only when the device
176 int ( * transmit ) ( struct net_device *netdev,
177 struct io_buffer *iobuf );
178 /** Poll for completed and received packets
180 * @v netdev Network device
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().
186 * This method is guaranteed to be called only when the device
189 void ( * poll ) ( struct net_device *netdev );
190 /** Enable or disable interrupts
192 * @v netdev Network device
193 * @v enable Interrupts should be enabled
195 void ( * irq ) ( struct net_device *netdev, int enable );
198 /** Network device error */
199 struct net_device_error {
200 /** Error status code */
206 /** Maximum number of unique errors that we will keep track of */
207 #define NETDEV_MAX_UNIQUE_ERRORS 4
209 /** Network device statistics */
210 struct net_device_stats {
211 /** Count of successful completions */
213 /** Count of error completions */
215 /** Error breakdowns */
216 struct net_device_error errors[NETDEV_MAX_UNIQUE_ERRORS];
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.
226 * Note that this structure must represent a generic network device,
227 * not just an Ethernet 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 */
238 /** Underlying hardware device */
241 /** Network device operations */
242 struct net_device_operations *op;
244 /** Link-layer protocol */
245 struct ll_protocol *ll_protocol;
246 /** Link-layer address
248 * For Ethernet, this is the MAC address.
250 uint8_t ll_addr[MAX_LL_ADDR_LEN];
252 /** Current device state
254 * This is the bitwise-OR of zero or more NETDEV_XXX constants.
257 /** Maximum packet length
259 * This length includes any link-layer headers.
262 /** TX packet queue */
263 struct list_head tx_queue;
264 /** RX packet queue */
265 struct list_head rx_queue;
267 struct net_device_stats tx_stats;
269 struct net_device_stats rx_stats;
271 /** Configuration settings applicable to this device */
272 struct generic_settings settings;
274 /** Driver private data */
278 /** Network device is open */
279 #define NETDEV_OPEN 0x0001
281 /** Network device has link */
282 #define NETDEV_LINK_UP 0x0002
284 /** Link-layer protocol table */
285 #define LL_PROTOCOLS __table ( struct ll_protocol, "ll_protocols" )
287 /** Declare a link-layer protocol */
288 #define __ll_protocol __table_entry ( LL_PROTOCOLS, 01 )
290 /** Network-layer protocol table */
291 #define NET_PROTOCOLS __table ( struct net_protocol, "net_protocols" )
293 /** Declare a network-layer protocol */
294 #define __net_protocol __table_entry ( NET_PROTOCOLS, 01 )
296 extern struct list_head net_devices;
297 extern struct net_device_operations null_netdev_operations;
298 extern struct settings_operations netdev_settings_operations;
301 * Initialise a network device
303 * @v netdev Network device
304 * @v op Network device operations
306 static inline void netdev_init ( struct net_device *netdev,
307 struct net_device_operations *op ) {
312 * Stop using a network device
314 * @v netdev Network device
316 * Drivers should call this method immediately before the final call
319 static inline void netdev_nullify ( struct net_device *netdev ) {
320 netdev->op = &null_netdev_operations;
324 * Get printable network device hardware address
326 * @v netdev Network device
327 * @ret name Hardware address
329 static inline const char * netdev_hwaddr ( struct net_device *netdev ) {
330 return netdev->ll_protocol->ntoa ( netdev->ll_addr );
333 /** Iterate over all network devices */
334 #define for_each_netdev( netdev ) \
335 list_for_each_entry ( (netdev), &net_devices, list )
337 /** There exist some network devices
339 * @ret existence Existence of network devices
341 static inline int have_netdevs ( void ) {
342 return ( ! list_empty ( &net_devices ) );
346 * Get reference to network device
348 * @v netdev Network device
349 * @ret netdev Network device
351 static inline __attribute__ (( always_inline )) struct net_device *
352 netdev_get ( struct net_device *netdev ) {
353 ref_get ( &netdev->refcnt );
358 * Drop reference to network device
360 * @v netdev Network device
362 static inline __attribute__ (( always_inline )) void
363 netdev_put ( struct net_device *netdev ) {
364 ref_put ( &netdev->refcnt );
368 * Get driver private area for this network device
370 * @v netdev Network device
371 * @ret priv Driver private area for this network device
373 static inline __attribute__ (( always_inline )) void *
374 netdev_priv ( struct net_device *netdev ) {
379 * Get per-netdevice configuration settings block
381 * @v netdev Network device
382 * @ret settings Settings block
384 static inline __attribute__ (( always_inline )) struct settings *
385 netdev_settings ( struct net_device *netdev ) {
386 return &netdev->settings.settings;
390 * Initialise a per-netdevice configuration settings block
392 * @v generics Generic settings block
393 * @v refcnt Containing object reference counter, or NULL
394 * @v name Settings block name
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;
404 * Mark network device as having link up
406 * @v netdev Network device
408 static inline __attribute__ (( always_inline )) void
409 netdev_link_up ( struct net_device *netdev ) {
410 netdev->state |= NETDEV_LINK_UP;
414 * Mark network device as having link down
416 * @v netdev Network device
418 static inline __attribute__ (( always_inline )) void
419 netdev_link_down ( struct net_device *netdev ) {
420 netdev->state &= ~NETDEV_LINK_UP;
424 * Check link state of network device
426 * @v netdev Network device
427 * @ret link_up Link is up
429 static inline __attribute__ (( always_inline )) int
430 netdev_link_ok ( struct net_device *netdev ) {
431 return ( netdev->state & NETDEV_LINK_UP );
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 );
459 * Complete network transmission
461 * @v netdev Network device
462 * @v iobuf I/O buffer
464 * The packet must currently be in the network device's TX queue.
466 static inline void netdev_tx_complete ( struct net_device *netdev,
467 struct io_buffer *iobuf ) {
468 netdev_tx_complete_err ( netdev, iobuf, 0 );
472 * Complete network transmission
474 * @v netdev Network device
476 * Completes the oldest outstanding packet in the TX queue.
478 static inline void netdev_tx_complete_next ( struct net_device *netdev ) {
479 netdev_tx_complete_next_err ( netdev, 0 );
482 #endif /* _GPXE_NETDEVICE_H */