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 6
  23
  24 /** Maximum length of a link-layer header */
  25 #define MAX_LL_HEADER_LEN 16
  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 /**
 132  * Network device statistics
 133  *
 134  */
 135 struct net_device_stats {
 136         /** Count of successfully completed transmissions */
 137         unsigned int tx_count;
 138         /** Count of successfully received packets */
 139         unsigned int rx_count;
 140 };
 141
 142 /**
 143  * A network device
 144  *
 145  * This structure represents a piece of networking hardware.  It has
 146  * properties such as a link-layer address and methods for
 147  * transmitting and receiving raw packets.
 148  *
 149  * Note that this structure must represent a generic network device,
 150  * not just an Ethernet device.
 151  */
 152 struct net_device {
 153         /** Reference counter */
 154         struct refcnt refcnt;
 155         /** List of network devices */
 156         struct list_head list;
 157         /** Name of this network device */
 158         char name[8];
 159         /** Underlying hardware device */
 160         struct device *dev;
 161
 162         /** Open network device
 163          *
 164          * @v netdev    Network device
 165          * @ret rc      Return status code
 166          *
 167          * This method should allocate RX I/O buffers and enable
 168          * the hardware to start transmitting and receiving packets.
 169          */
 170         int ( * open ) ( struct net_device *netdev );
 171         /** Close network device
 172          *
 173          * @v netdev    Network device
 174          *
 175          * This method should stop the flow of packets, and free up
 176          * any packets that are currently in the device's TX queue.
 177          */
 178         void ( * close ) ( struct net_device *netdev );
 179         /** Transmit packet
 180          *
 181          * @v netdev    Network device
 182          * @v iobuf     I/O buffer
 183          * @ret rc      Return status code
 184          *
 185          * This method should cause the hardware to initiate
 186          * transmission of the I/O buffer.
 187          *
 188          * If this method returns success, the I/O buffer remains
 189          * owned by the net device's TX queue, and the net device must
 190          * eventually call netdev_tx_complete() to free the buffer.
 191          * If this method returns failure, the I/O buffer is
 192          * immediately released.
 193          *
 194          * This method is guaranteed to be called only when the device
 195          * is open.
 196          */
 197         int ( * transmit ) ( struct net_device *netdev, struct io_buffer *iobuf );
 198         /** Poll for received packet
 199          *
 200          * @v netdev    Network device
 201          * @v rx_quota  Maximum number of packets to receive
 202          *
 203          * This method should cause the hardware to check for received
 204          * packets.  Any received packets should be delivered via
 205          * netdev_rx(), up to a maximum of @c rx_quota packets.
 206          *
 207          * This method is guaranteed to be called only when the device
 208          * is open.
 209          */
 210         void ( * poll ) ( struct net_device *netdev, unsigned int rx_quota );
 211
 212         /** Link-layer protocol */
 213         struct ll_protocol *ll_protocol;
 214         /** Link-layer address
 215          *
 216          * For Ethernet, this is the MAC address.
 217          */
 218         uint8_t ll_addr[MAX_LL_ADDR_LEN];
 219
 220         /** Current device state
 221          *
 222          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
 223          */
 224         unsigned int state;
 225         /** TX packet queue */
 226         struct list_head tx_queue;
 227         /** RX packet queue */
 228         struct list_head rx_queue;
 229         /** Device statistics */
 230         struct net_device_stats stats;
 231
 232         /** Driver private data */
 233         void *priv;
 234 };
 235
 236 /** Network device is open */
 237 #define NETDEV_OPEN 0x0001
 238
 239 /** Declare a link-layer protocol */
 240 #define __ll_protocol  __table ( struct ll_protocol, ll_protocols, 01 )
 241
 242 /** Declare a network-layer protocol */
 243 #define __net_protocol __table ( struct net_protocol, net_protocols, 01 )
 244
 245 extern struct list_head net_devices;
 246
 247 /**
 248  * Get printable network device hardware address
 249  *
 250  * @v netdev            Network device
 251  * @ret name            Hardware address
 252  */
 253 static inline const char * netdev_hwaddr ( struct net_device *netdev ) {
 254         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
 255 }
 256
 257 /** Iterate over all network devices */
 258 #define for_each_netdev( netdev ) \
 259         list_for_each_entry ( (netdev), &net_devices, list )
 260
 261 /** There exist some network devices
 262  *
 263  * @ret existence       Existence of network devices
 264  */
 265 static inline int have_netdevs ( void ) {
 266         return ( ! list_empty ( &net_devices ) );
 267 }
 268
 269 /**
 270  * Get reference to network device
 271  *
 272  * @v netdev            Network device
 273  * @ret netdev          Network device
 274  */
 275 static inline __attribute__ (( always_inline )) struct net_device *
 276 netdev_get ( struct net_device *netdev ) {
 277         ref_get ( &netdev->refcnt );
 278         return netdev;
 279 }
 280
 281 /**
 282  * Drop reference to network device
 283  *
 284  * @v netdev            Network device
 285  */
 286 static inline __attribute__ (( always_inline )) void
 287 netdev_put ( struct net_device *netdev ) {
 288         ref_put ( &netdev->refcnt );
 289 }
 290
 291 extern int netdev_tx ( struct net_device *netdev, struct io_buffer *iobuf );
 292 extern void netdev_tx_complete ( struct net_device *netdev,
 293                                  struct io_buffer *iobuf );
 294 extern void netdev_tx_complete_next ( struct net_device *netdev );
 295 extern void netdev_rx ( struct net_device *netdev, struct io_buffer *iobuf );
 296 extern int netdev_poll ( struct net_device *netdev, unsigned int rx_quota );
 297 extern struct io_buffer * netdev_rx_dequeue ( struct net_device *netdev );
 298 extern struct net_device * alloc_netdev ( size_t priv_size );
 299 extern int register_netdev ( struct net_device *netdev );
 300 extern int netdev_open ( struct net_device *netdev );
 301 extern void netdev_close ( struct net_device *netdev );
 302 extern void unregister_netdev ( struct net_device *netdev );
 303 extern struct net_device * find_netdev ( const char *name );
 304 extern struct net_device * find_netdev_by_location ( unsigned int bus_type,
 305                                                      unsigned int location );
 306 extern int net_tx ( struct io_buffer *iobuf, struct net_device *netdev,
 307                     struct net_protocol *net_protocol, const void *ll_dest );
 308 extern int net_rx ( struct io_buffer *iobuf, struct net_device *netdev,
 309                     uint16_t net_proto, const void *ll_source );
 310
 311 #endif /* _GPXE_NETDEVICE_H */