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