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