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/hotplug.h>
  14
  15 struct pk_buff;
  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 pkb       Packet buffer
  41          * @v netdev    Network device
  42          * @v ll_source Link-layer source address
  43          *
  44          * This method takes ownership of the packet buffer.
  45          */
  46         int ( * rx ) ( struct pk_buff *pkb, 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 pkb               Packet 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 packet buffer.
  89          */
  90         int ( * tx ) ( struct pk_buff *pkb, struct net_device *netdev,
  91                        struct net_protocol *net_protocol,
  92                        const void *ll_dest );
  93         /**
  94          * Handle received packet
  95          *
  96          * @v pkb       Packet 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 pk_buff *pkb, 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 broadcast address */
 126         const uint8_t *ll_broadcast;
 127 };
 128
 129 /**
 130  * A network device
 131  *
 132  * This structure represents a piece of networking hardware.  It has
 133  * properties such as a link-layer address and methods for
 134  * transmitting and receiving raw packets.
 135  *
 136  * Note that this structure must represent a generic network device,
 137  * not just an Ethernet device.
 138  */
 139 struct net_device {
 140         /** List of network devices */
 141         struct list_head list;
 142         /** Name of this network device */
 143         char name[8];
 144         /** Underlying hardware device */
 145         struct device *dev;
 146         /** List of persistent reference holders */
 147         struct list_head references;
 148
 149         /** Open network device
 150          *
 151          * @v netdev    Network device
 152          * @ret rc      Return status code
 153          *
 154          * This method should allocate RX packet buffers and enable
 155          * the hardware to start transmitting and receiving packets.
 156          */
 157         int ( * open ) ( struct net_device *netdev );
 158         /** Close network device
 159          *
 160          * @v netdev    Network device
 161          *
 162          * This method should stop the flow of packets, and free up
 163          * any packets that are currently in the device's TX queue.
 164          */
 165         void ( * close ) ( struct net_device *netdev );
 166         /** Transmit packet
 167          *
 168          * @v netdev    Network device
 169          * @v pkb       Packet buffer
 170          * @ret rc      Return status code
 171          *
 172          * This method should cause the hardware to initiate
 173          * transmission of the packet buffer.
 174          *
 175          * If this method returns success, the packet buffer remains
 176          * owned by the net device's TX queue, and the net device must
 177          * eventually call netdev_tx_complete() to free the buffer.
 178          * If this method returns failure, the packet buffer is
 179          * immediately released.
 180          *
 181          * This method is guaranteed to be called only when the device
 182          * is open.
 183          */
 184         int ( * transmit ) ( struct net_device *netdev, struct pk_buff *pkb );
 185         /** Poll for received packet
 186          *
 187          * @v netdev    Network device
 188          * @v rx_quota  Maximum number of packets to receive
 189          *
 190          * This method should cause the hardware to check for received
 191          * packets.  Any received packets should be delivered via
 192          * netdev_rx(), up to a maximum of @c rx_quota packets.
 193          *
 194          * This method is guaranteed to be called only when the device
 195          * is open.
 196          */
 197         void ( * poll ) ( struct net_device *netdev, unsigned int rx_quota );
 198
 199         /** Link-layer protocol */
 200         struct ll_protocol *ll_protocol;
 201         /** Link-layer address
 202          *
 203          * For Ethernet, this is the MAC address.
 204          */
 205         uint8_t ll_addr[MAX_LL_ADDR_LEN];
 206
 207         /** Current device state
 208          *
 209          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
 210          */
 211         unsigned int state;
 212         /** TX packet queue */
 213         struct list_head tx_queue;
 214         /** RX packet queue */
 215         struct list_head rx_queue;
 216
 217         /** Driver private data */
 218         void *priv;
 219 };
 220
 221 /** Network device is open */
 222 #define NETDEV_OPEN 0x0001
 223
 224 /** Declare a link-layer protocol */
 225 #define __ll_protocol  __table ( struct ll_protocol, ll_protocols, 01 )
 226
 227 /** Declare a network-layer protocol */
 228 #define __net_protocol __table ( struct net_protocol, net_protocols, 01 )
 229
 230 extern struct list_head net_devices;
 231
 232 /**
 233  * Get printable network device hardware address
 234  *
 235  * @v netdev            Network device
 236  * @ret name            Hardware address
 237  */
 238 static inline const char * netdev_hwaddr ( struct net_device *netdev ) {
 239         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
 240 }
 241
 242 /** Iterate over all network devices */
 243 #define for_each_netdev( netdev ) \
 244         list_for_each_entry ( (netdev), &net_devices, list )
 245
 246 /** There exist some network devices
 247  *
 248  * @ret existence       Existence of network devices
 249  */
 250 static inline int have_netdevs ( void ) {
 251         return ( ! list_empty ( &net_devices ) );
 252 }
 253
 254 extern int netdev_tx ( struct net_device *netdev, struct pk_buff *pkb );
 255 void netdev_tx_complete ( struct net_device *netdev, struct pk_buff *pkb );
 256 void netdev_tx_complete_next ( struct net_device *netdev );
 257 extern void netdev_rx ( struct net_device *netdev, struct pk_buff *pkb );
 258 extern int netdev_poll ( struct net_device *netdev, unsigned int rx_quota );
 259 extern struct pk_buff * netdev_rx_dequeue ( struct net_device *netdev );
 260 extern struct net_device * alloc_netdev ( size_t priv_size );
 261 extern int register_netdev ( struct net_device *netdev );
 262 extern int netdev_open ( struct net_device *netdev );
 263 extern void netdev_close ( struct net_device *netdev );
 264 extern void unregister_netdev ( struct net_device *netdev );
 265 extern void free_netdev ( struct net_device *netdev );
 266 struct net_device * find_netdev ( const char *name );
 267 struct net_device * find_pci_netdev ( unsigned int busdevfn );
 268
 269 extern int net_tx ( struct pk_buff *pkb, struct net_device *netdev,
 270                     struct net_protocol *net_protocol, const void *ll_dest );
 271 extern int net_rx ( struct pk_buff *pkb, struct net_device *netdev,
 272                     uint16_t net_proto, const void *ll_source );
 273
 274 #endif /* _GPXE_NETDEVICE_H */