[NETDEV] Add notion of link state
[people/sha0/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          * 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 simple_settings settings;
249
250         /** Driver private data */
251         void *priv;
252 };
253
254 /** Network device is open */
255 #define NETDEV_OPEN 0x0001
256
257 /** Network device has link */
258 #define NETDEV_LINK_UP 0x0002
259
260 /** Declare a link-layer protocol */
261 #define __ll_protocol  __table ( struct ll_protocol, ll_protocols, 01 )
262
263 /** Declare a network-layer protocol */
264 #define __net_protocol __table ( struct net_protocol, net_protocols, 01 )
265
266 extern struct list_head net_devices;
267 extern struct net_device_operations null_netdev_operations;
268
269 /**
270  * Initialise a network device
271  *
272  * @v netdev            Network device
273  * @v op                Network device operations
274  */
275 static inline void netdev_init ( struct net_device *netdev,
276                                  struct net_device_operations *op ) {
277         netdev->op = op;
278 }
279
280 /**
281  * Stop using a network device
282  *
283  * @v netdev            Network device
284  *
285  * Drivers should call this method immediately before the final call
286  * to netdev_put().
287  */
288 static inline void netdev_nullify ( struct net_device *netdev ) {
289         netdev->op = &null_netdev_operations;
290 }
291
292 /**
293  * Get printable network device hardware address
294  *
295  * @v netdev            Network device
296  * @ret name            Hardware address
297  */
298 static inline const char * netdev_hwaddr ( struct net_device *netdev ) {
299         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
300 }
301
302 /** Iterate over all network devices */
303 #define for_each_netdev( netdev ) \
304         list_for_each_entry ( (netdev), &net_devices, list )
305
306 /** There exist some network devices
307  *
308  * @ret existence       Existence of network devices
309  */
310 static inline int have_netdevs ( void ) {
311         return ( ! list_empty ( &net_devices ) );
312 }
313
314 /**
315  * Get reference to network device
316  *
317  * @v netdev            Network device
318  * @ret netdev          Network device
319  */
320 static inline __attribute__ (( always_inline )) struct net_device *
321 netdev_get ( struct net_device *netdev ) {
322         ref_get ( &netdev->refcnt );
323         return netdev;
324 }
325
326 /**
327  * Drop reference to network device
328  *
329  * @v netdev            Network device
330  */
331 static inline __attribute__ (( always_inline )) void
332 netdev_put ( struct net_device *netdev ) {
333         ref_put ( &netdev->refcnt );
334 }
335
336 /**
337  * Get driver private area for this network device
338  *
339  * @v netdev            Network device
340  * @ret priv            Driver private area for this network device
341  */
342 static inline __attribute__ (( always_inline )) void *
343 netdev_priv ( struct net_device *netdev ) {
344         return netdev->priv;
345 }
346
347 /**
348  * Get per-netdevice configuration settings block
349  *
350  * @v netdev            Network device
351  * @ret settings        Settings block
352  */
353 static inline __attribute__ (( always_inline )) struct settings *
354 netdev_settings ( struct net_device *netdev ) {
355         return &netdev->settings.settings;
356 }
357
358 /**
359  * Mark network device as having link up
360  *
361  * @v netdev            Network device
362  */
363 static inline __attribute__ (( always_inline )) void
364 netdev_link_up ( struct net_device *netdev ) {
365         netdev->state |= NETDEV_LINK_UP;
366 }
367
368 /**
369  * Mark network device as having link down
370  *
371  * @v netdev            Network device
372  */
373 static inline __attribute__ (( always_inline )) void
374 netdev_link_down ( struct net_device *netdev ) {
375         netdev->state &= ~NETDEV_LINK_UP;
376 }
377
378 /**
379  * Check link state of network device
380  *
381  * @v netdev            Network device
382  * @ret link_up         Link is up
383  */
384 static inline __attribute__ (( always_inline )) int
385 netdev_link_ok ( struct net_device *netdev ) {
386         return ( netdev->state & NETDEV_LINK_UP );
387 }
388
389 extern int netdev_tx ( struct net_device *netdev, struct io_buffer *iobuf );
390 extern void netdev_tx_complete_err ( struct net_device *netdev,
391                                  struct io_buffer *iobuf, int rc );
392 extern void netdev_tx_complete_next_err ( struct net_device *netdev, int rc );
393 extern void netdev_rx ( struct net_device *netdev, struct io_buffer *iobuf );
394 extern void netdev_rx_err ( struct net_device *netdev,
395                             struct io_buffer *iobuf, int rc );
396 extern void netdev_poll ( struct net_device *netdev );
397 extern struct io_buffer * netdev_rx_dequeue ( struct net_device *netdev );
398 extern struct net_device * alloc_netdev ( size_t priv_size );
399 extern int register_netdev ( struct net_device *netdev );
400 extern int netdev_open ( struct net_device *netdev );
401 extern void netdev_close ( struct net_device *netdev );
402 extern void unregister_netdev ( struct net_device *netdev );
403 extern void netdev_irq ( struct net_device *netdev, int enable );
404 extern struct net_device * find_netdev ( const char *name );
405 extern struct net_device * find_netdev_by_location ( unsigned int bus_type,
406                                                      unsigned int location );
407 extern int net_tx ( struct io_buffer *iobuf, struct net_device *netdev,
408                     struct net_protocol *net_protocol, const void *ll_dest );
409 extern int net_rx ( struct io_buffer *iobuf, struct net_device *netdev,
410                     uint16_t net_proto, const void *ll_source );
411
412 extern struct settings_operations netdev_settings_operations;
413
414 /**
415  * Complete network transmission
416  *
417  * @v netdev            Network device
418  * @v iobuf             I/O buffer
419  *
420  * The packet must currently be in the network device's TX queue.
421  */
422 static inline void netdev_tx_complete ( struct net_device *netdev,
423                                         struct io_buffer *iobuf ) {
424         netdev_tx_complete_err ( netdev, iobuf, 0 );
425 }
426
427 /**
428  * Complete network transmission
429  *
430  * @v netdev            Network device
431  *
432  * Completes the oldest outstanding packet in the TX queue.
433  */
434 static inline void netdev_tx_complete_next ( struct net_device *netdev ) {
435         netdev_tx_complete_next_err ( netdev, 0 );
436 }
437
438 #endif /* _GPXE_NETDEVICE_H */