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