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 */ 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 */ 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 */ 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 */ 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 * 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 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 * 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 * 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 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 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 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 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 */ 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 */ 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
