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