5d5e05bd50c0f3053f37805af3c91339c238a915
[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
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 20
23
24 /** Maximum length of a link-layer header */
25 #define MAX_LL_HEADER_LEN 32
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 /** Network device operations */
132 struct net_device_operations {
133         /** Open network device
134          *
135          * @v netdev    Network device
136          * @ret rc      Return status code
137          *
138          * This method should allocate RX I/O buffers and enable
139          * the hardware to start transmitting and receiving packets.
140          */
141         int ( * open ) ( struct net_device *netdev );
142         /** Close network device
143          *
144          * @v netdev    Network device
145          *
146          * This method should stop the flow of packets, and free up
147          * any packets that are currently in the device's TX queue.
148          */
149         void ( * close ) ( struct net_device *netdev );
150         /** Transmit packet
151          *
152          * @v netdev    Network device
153          * @v iobuf     I/O buffer
154          * @ret rc      Return status code
155          *
156          * This method should cause the hardware to initiate
157          * transmission of the I/O buffer.
158          *
159          * If this method returns success, the I/O buffer remains
160          * owned by the net device's TX queue, and the net device must
161          * eventually call netdev_tx_complete() to free the buffer.
162          * If this method returns failure, the I/O buffer is
163          * immediately released; the failure is interpreted as
164          * "failure to enqueue buffer".
165          *
166          * This method is guaranteed to be called only when the device
167          * is open.
168          */
169         int ( * transmit ) ( struct net_device *netdev,
170                              struct io_buffer *iobuf );
171         /** Poll for completed and received packets
172          *
173          * @v netdev    Network device
174          *
175          * This method should cause the hardware to check for
176          * completed transmissions and received packets.  Any received
177          * packets should be delivered via netdev_rx().
178          *
179          * This method is guaranteed to be called only when the device
180          * is open.
181          */
182         void ( * poll ) ( struct net_device *netdev );
183         /** Enable or disable interrupts
184          *
185          * @v netdev    Network device
186          * @v enable    Interrupts should be enabled
187          */
188         void ( * irq ) ( struct net_device *netdev, int enable );
189 };
190
191 /** Network device statistics */
192 struct net_device_stats {
193         /** Count of successfully completed transmissions */
194         unsigned int tx_ok;
195         /** Count of transmission errors */
196         unsigned int tx_err;
197         /** Count of successfully received packets */
198         unsigned int rx_ok;
199         /** Count of reception errors */
200         unsigned int rx_err;
201 };
202
203 /**
204  * A network device
205  *
206  * This structure represents a piece of networking hardware.  It has
207  * properties such as a link-layer address and methods for
208  * transmitting and receiving raw packets.
209  *
210  * Note that this structure must represent a generic network device,
211  * not just an Ethernet device.
212  */
213 struct net_device {
214         /** Reference counter */
215         struct refcnt refcnt;
216         /** List of network devices */
217         struct list_head list;
218         /** Name of this network device */
219         char name[8];
220         /** Underlying hardware device */
221         struct device *dev;
222
223         /** Network device operations */
224         struct net_device_operations *op;
225
226         /** Link-layer protocol */
227         struct ll_protocol *ll_protocol;
228         /** Link-layer address
229          *
230          * For Ethernet, this is the MAC address.
231          */
232         uint8_t ll_addr[MAX_LL_ADDR_LEN];
233
234         /** Current device state
235          *
236          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
237          */
238         unsigned int state;
239         /** TX packet queue */
240         struct list_head tx_queue;
241         /** RX packet queue */
242         struct list_head rx_queue;
243         /** Device statistics */
244         struct net_device_stats stats;
245
246         /** Driver private data */
247         void *priv;
248 };
249
250 /** Network device is open */
251 #define NETDEV_OPEN 0x0001
252
253 /** Declare a link-layer protocol */
254 #define __ll_protocol  __table ( struct ll_protocol, ll_protocols, 01 )
255
256 /** Declare a network-layer protocol */
257 #define __net_protocol __table ( struct net_protocol, net_protocols, 01 )
258
259 extern struct list_head net_devices;
260 extern struct net_device_operations null_netdev_operations;
261
262 /**
263  * Initialise a network device
264  *
265  * @v netdev            Network device
266  * @v op                Network device operations
267  */
268 static inline void netdev_init ( struct net_device *netdev,
269                                  struct net_device_operations *op ) {
270         netdev->op = op;
271 }
272
273 /**
274  * Stop using a network device
275  *
276  * @v netdev            Network device
277  *
278  * Drivers should call this method immediately before the final call
279  * to netdev_put().
280  */
281 static inline void netdev_nullify ( struct net_device *netdev ) {
282         netdev->op = &null_netdev_operations;
283 }
284
285 /**
286  * Get printable network device hardware address
287  *
288  * @v netdev            Network device
289  * @ret name            Hardware address
290  */
291 static inline const char * netdev_hwaddr ( struct net_device *netdev ) {
292         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
293 }
294
295 /** Iterate over all network devices */
296 #define for_each_netdev( netdev ) \
297         list_for_each_entry ( (netdev), &net_devices, list )
298
299 /** There exist some network devices
300  *
301  * @ret existence       Existence of network devices
302  */
303 static inline int have_netdevs ( void ) {
304         return ( ! list_empty ( &net_devices ) );
305 }
306
307 /**
308  * Get reference to network device
309  *
310  * @v netdev            Network device
311  * @ret netdev          Network device
312  */
313 static inline __attribute__ (( always_inline )) struct net_device *
314 netdev_get ( struct net_device *netdev ) {
315         ref_get ( &netdev->refcnt );
316         return netdev;
317 }
318
319 /**
320  * Drop reference to network device
321  *
322  * @v netdev            Network device
323  */
324 static inline __attribute__ (( always_inline )) void
325 netdev_put ( struct net_device *netdev ) {
326         ref_put ( &netdev->refcnt );
327 }
328
329 /**
330  * Get driver private area for this network device
331  *
332  * @v netdev            Network device
333  * @ret priv            Driver private area for this network device
334  */
335 static inline __attribute__ (( always_inline )) void *
336 netdev_priv ( struct net_device *netdev ) {
337         return netdev->priv;
338 }
339
340 extern int netdev_tx ( struct net_device *netdev, struct io_buffer *iobuf );
341 extern void netdev_tx_complete_err ( struct net_device *netdev,
342                                  struct io_buffer *iobuf, int rc );
343 extern void netdev_tx_complete_next_err ( struct net_device *netdev, int rc );
344 extern void netdev_rx ( struct net_device *netdev, struct io_buffer *iobuf );
345 extern void netdev_rx_err ( struct net_device *netdev,
346                             struct io_buffer *iobuf, int rc );
347 extern void netdev_poll ( struct net_device *netdev );
348 extern struct io_buffer * netdev_rx_dequeue ( struct net_device *netdev );
349 extern struct net_device * alloc_netdev ( size_t priv_size );
350 extern int register_netdev ( struct net_device *netdev );
351 extern int netdev_open ( struct net_device *netdev );
352 extern void netdev_close ( struct net_device *netdev );
353 extern void unregister_netdev ( struct net_device *netdev );
354 extern void netdev_irq ( struct net_device *netdev, int enable );
355 extern struct net_device * find_netdev ( const char *name );
356 extern struct net_device * find_netdev_by_location ( unsigned int bus_type,
357                                                      unsigned int location );
358 extern int net_tx ( struct io_buffer *iobuf, struct net_device *netdev,
359                     struct net_protocol *net_protocol, const void *ll_dest );
360 extern int net_rx ( struct io_buffer *iobuf, struct net_device *netdev,
361                     uint16_t net_proto, const void *ll_source );
362
363 /**
364  * Complete network transmission
365  *
366  * @v netdev            Network device
367  * @v iobuf             I/O buffer
368  *
369  * The packet must currently be in the network device's TX queue.
370  */
371 static inline void netdev_tx_complete ( struct net_device *netdev,
372                                         struct io_buffer *iobuf ) {
373         netdev_tx_complete_err ( netdev, iobuf, 0 );
374 }
375
376 /**
377  * Complete network transmission
378  *
379  * @v netdev            Network device
380  *
381  * Completes the oldest outstanding packet in the TX queue.
382  */
383 static inline void netdev_tx_complete_next ( struct net_device *netdev ) {
384         netdev_tx_complete_next_err ( netdev, 0 );
385 }
386
387 #endif /* _GPXE_NETDEVICE_H */