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 32
  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          * Transmit network-layer packet via network device
  80          *
  81          * @v iobuf             I/O buffer
  82          * @v netdev            Network device
  83          * @v net_protocol      Network-layer protocol
  84          * @v ll_dest           Link-layer destination address
  85          * @ret rc              Return status code
  86          *
  87          * This method should prepend in the link-layer header
  88          * (e.g. the Ethernet DIX header) and transmit the packet.
  89          * This method takes ownership of the I/O buffer.
  90          */
  91         int ( * tx ) ( struct io_buffer *iobuf, struct net_device *netdev,
  92                        struct net_protocol *net_protocol,
  93                        const void *ll_dest );
  94         /**
  95          * Handle received packet
  96          *
  97          * @v iobuf     I/O buffer
  98          * @v netdev    Network device
  99          *
 100          * This method should strip off the link-layer header
 101          * (e.g. the Ethernet DIX header) and pass the packet to
 102          * net_rx().  This method takes ownership of the packet
 103          * buffer.
 104          */
 105         int ( * rx ) ( struct io_buffer *iobuf, struct net_device *netdev );
 106         /**
 107          * Transcribe link-layer address
 108          *
 109          * @v ll_addr   Link-layer address
 110          * @ret string  Human-readable transcription of address
 111          *
 112          * This method should convert the link-layer address into a
 113          * human-readable format.
 114          *
 115          * The buffer used to hold the transcription is statically
 116          * allocated.
 117          */
 118         const char * ( * ntoa ) ( const void * ll_addr );
 119         /** Link-layer protocol
 120          *
 121          * This is an ARPHRD_XXX constant, in network byte order.
 122          */
 123         uint16_t ll_proto;
 124         /** Link-layer address length */
 125         uint8_t ll_addr_len;
 126         /** Link-layer header length */
 127         uint8_t ll_header_len;
 128         /** Link-layer broadcast address */
 129         const uint8_t *ll_broadcast;
 130 };
 131
 132 /** Network device operations */
 133 struct net_device_operations {
 134         /** Open network device
 135          *
 136          * @v netdev    Network device
 137          * @ret rc      Return status code
 138          *
 139          * This method should allocate RX I/O buffers and enable
 140          * the hardware to start transmitting and receiving packets.
 141          */
 142         int ( * open ) ( struct net_device *netdev );
 143         /** Close network device
 144          *
 145          * @v netdev    Network device
 146          *
 147          * This method should stop the flow of packets, and free up
 148          * any packets that are currently in the device's TX queue.
 149          */
 150         void ( * close ) ( struct net_device *netdev );
 151         /** Transmit packet
 152          *
 153          * @v netdev    Network device
 154          * @v iobuf     I/O buffer
 155          * @ret rc      Return status code
 156          *
 157          * This method should cause the hardware to initiate
 158          * transmission of the I/O buffer.
 159          *
 160          * If this method returns success, the I/O buffer remains
 161          * owned by the net device's TX queue, and the net device must
 162          * eventually call netdev_tx_complete() to free the buffer.
 163          * If this method returns failure, the I/O buffer is
 164          * immediately released; the failure is interpreted as
 165          * "failure to enqueue buffer".
 166          *
 167          * This method is guaranteed to be called only when the device
 168          * is open.
 169          */
 170         int ( * transmit ) ( struct net_device *netdev,
 171                              struct io_buffer *iobuf );
 172         /** Poll for completed and received packets
 173          *
 174          * @v netdev    Network device
 175          *
 176          * This method should cause the hardware to check for
 177          * completed transmissions and received packets.  Any received
 178          * packets should be delivered via netdev_rx().
 179          *
 180          * This method is guaranteed to be called only when the device
 181          * is open.
 182          */
 183         void ( * poll ) ( struct net_device *netdev );
 184         /** Enable or disable interrupts
 185          *
 186          * @v netdev    Network device
 187          * @v enable    Interrupts should be enabled
 188          */
 189         void ( * irq ) ( struct net_device *netdev, int enable );
 190 };
 191
 192 /** Network device statistics */
 193 struct net_device_stats {
 194         /** Count of successfully completed transmissions */
 195         unsigned int tx_ok;
 196         /** Count of transmission errors */
 197         unsigned int tx_err;
 198         /** Count of successfully received packets */
 199         unsigned int rx_ok;
 200         /** Count of reception errors */
 201         unsigned int rx_err;
 202 };
 203
 204 /**
 205  * A network device
 206  *
 207  * This structure represents a piece of networking hardware.  It has
 208  * properties such as a link-layer address and methods for
 209  * transmitting and receiving raw packets.
 210  *
 211  * Note that this structure must represent a generic network device,
 212  * not just an Ethernet device.
 213  */
 214 struct net_device {
 215         /** Reference counter */
 216         struct refcnt refcnt;
 217         /** List of network devices */
 218         struct list_head list;
 219         /** Name of this network device */
 220         char name[8];
 221         /** Underlying hardware device */
 222         struct device *dev;
 223
 224         /** Network device operations */
 225         struct net_device_operations *op;
 226
 227         /** Link-layer protocol */
 228         struct ll_protocol *ll_protocol;
 229         /** Link-layer address
 230          *
 231          * For Ethernet, this is the MAC address.
 232          */
 233         uint8_t ll_addr[MAX_LL_ADDR_LEN];
 234
 235         /** Current device state
 236          *
 237          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
 238          */
 239         unsigned int state;
 240         /** TX packet queue */
 241         struct list_head tx_queue;
 242         /** RX packet queue */
 243         struct list_head rx_queue;
 244         /** Device statistics */
 245         struct net_device_stats stats;
 246
 247         /** Configuration settings applicable to this device */
 248         struct settings settings;
 249
 250         /** Driver private data */
 251         void *priv;
 252 };
 253
 254 /** Network device is open */
 255 #define NETDEV_OPEN 0x0001
 256
 257 /** Declare a link-layer protocol */
 258 #define __ll_protocol  __table ( struct ll_protocol, ll_protocols, 01 )
 259
 260 /** Declare a network-layer protocol */
 261 #define __net_protocol __table ( struct net_protocol, net_protocols, 01 )
 262
 263 extern struct list_head net_devices;
 264 extern struct net_device_operations null_netdev_operations;
 265
 266 /**
 267  * Initialise a network device
 268  *
 269  * @v netdev            Network device
 270  * @v op                Network device operations
 271  */
 272 static inline void netdev_init ( struct net_device *netdev,
 273                                  struct net_device_operations *op ) {
 274         netdev->op = op;
 275 }
 276
 277 /**
 278  * Stop using a network device
 279  *
 280  * @v netdev            Network device
 281  *
 282  * Drivers should call this method immediately before the final call
 283  * to netdev_put().
 284  */
 285 static inline void netdev_nullify ( struct net_device *netdev ) {
 286         netdev->op = &null_netdev_operations;
 287 }
 288
 289 /**
 290  * Get printable network device hardware address
 291  *
 292  * @v netdev            Network device
 293  * @ret name            Hardware address
 294  */
 295 static inline const char * netdev_hwaddr ( struct net_device *netdev ) {
 296         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
 297 }
 298
 299 /** Iterate over all network devices */
 300 #define for_each_netdev( netdev ) \
 301         list_for_each_entry ( (netdev), &net_devices, list )
 302
 303 /** There exist some network devices
 304  *
 305  * @ret existence       Existence of network devices
 306  */
 307 static inline int have_netdevs ( void ) {
 308         return ( ! list_empty ( &net_devices ) );
 309 }
 310
 311 /**
 312  * Get reference to network device
 313  *
 314  * @v netdev            Network device
 315  * @ret netdev          Network device
 316  */
 317 static inline __attribute__ (( always_inline )) struct net_device *
 318 netdev_get ( struct net_device *netdev ) {
 319         ref_get ( &netdev->refcnt );
 320         return netdev;
 321 }
 322
 323 /**
 324  * Drop reference to network device
 325  *
 326  * @v netdev            Network device
 327  */
 328 static inline __attribute__ (( always_inline )) void
 329 netdev_put ( struct net_device *netdev ) {
 330         ref_put ( &netdev->refcnt );
 331 }
 332
 333 /**
 334  * Get driver private area for this network device
 335  *
 336  * @v netdev            Network device
 337  * @ret priv            Driver private area for this network device
 338  */
 339 static inline __attribute__ (( always_inline )) void *
 340 netdev_priv ( struct net_device *netdev ) {
 341         return netdev->priv;
 342 }
 343
 344 extern int netdev_tx ( struct net_device *netdev, struct io_buffer *iobuf );
 345 extern void netdev_tx_complete_err ( struct net_device *netdev,
 346                                  struct io_buffer *iobuf, int rc );
 347 extern void netdev_tx_complete_next_err ( struct net_device *netdev, int rc );
 348 extern void netdev_rx ( struct net_device *netdev, struct io_buffer *iobuf );
 349 extern void netdev_rx_err ( struct net_device *netdev,
 350                             struct io_buffer *iobuf, int rc );
 351 extern void netdev_poll ( struct net_device *netdev );
 352 extern struct io_buffer * netdev_rx_dequeue ( struct net_device *netdev );
 353 extern struct net_device * alloc_netdev ( size_t priv_size );
 354 extern int register_netdev ( struct net_device *netdev );
 355 extern int netdev_open ( struct net_device *netdev );
 356 extern void netdev_close ( struct net_device *netdev );
 357 extern void unregister_netdev ( struct net_device *netdev );
 358 extern void netdev_irq ( struct net_device *netdev, int enable );
 359 extern struct net_device * find_netdev ( const char *name );
 360 extern struct net_device * find_netdev_by_location ( unsigned int bus_type,
 361                                                      unsigned int location );
 362 extern int net_tx ( struct io_buffer *iobuf, struct net_device *netdev,
 363                     struct net_protocol *net_protocol, const void *ll_dest );
 364 extern int net_rx ( struct io_buffer *iobuf, struct net_device *netdev,
 365                     uint16_t net_proto, const void *ll_source );
 366
 367 extern struct settings_operations netdev_settings_operations;
 368
 369 /**
 370  * Complete network transmission
 371  *
 372  * @v netdev            Network device
 373  * @v iobuf             I/O buffer
 374  *
 375  * The packet must currently be in the network device's TX queue.
 376  */
 377 static inline void netdev_tx_complete ( struct net_device *netdev,
 378                                         struct io_buffer *iobuf ) {
 379         netdev_tx_complete_err ( netdev, iobuf, 0 );
 380 }
 381
 382 /**
 383  * Complete network transmission
 384  *
 385  * @v netdev            Network device
 386  *
 387  * Completes the oldest outstanding packet in the TX queue.
 388  */
 389 static inline void netdev_tx_complete_next ( struct net_device *netdev ) {
 390         netdev_tx_complete_next_err ( netdev, 0 );
 391 }
 392
 393 #endif /* _GPXE_NETDEVICE_H */