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