0bc5311ca3fd288dc43a6d4ace669091cdd58558
[people/xl0/gpxe-arm.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 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 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 /**
132  * Network device statistics
133  *
134  */
135 struct net_device_stats {
136         /** Count of successfully completed transmissions */
137         unsigned int tx_count;
138         /** Count of successfully received packets */
139         unsigned int rx_count;
140 };
141
142 /**
143  * A network device
144  *
145  * This structure represents a piece of networking hardware.  It has
146  * properties such as a link-layer address and methods for
147  * transmitting and receiving raw packets.
148  *
149  * Note that this structure must represent a generic network device,
150  * not just an Ethernet device.
151  */
152 struct net_device {
153         /** Reference counter */
154         struct refcnt refcnt;
155         /** List of network devices */
156         struct list_head list;
157         /** Name of this network device */
158         char name[8];
159         /** Underlying hardware device */
160         struct device *dev;
161
162         /** Open network device
163          *
164          * @v netdev    Network device
165          * @ret rc      Return status code
166          *
167          * This method should allocate RX I/O buffers and enable
168          * the hardware to start transmitting and receiving packets.
169          */
170         int ( * open ) ( struct net_device *netdev );
171         /** Close network device
172          *
173          * @v netdev    Network device
174          *
175          * This method should stop the flow of packets, and free up
176          * any packets that are currently in the device's TX queue.
177          */
178         void ( * close ) ( struct net_device *netdev );
179         /** Transmit packet
180          *
181          * @v netdev    Network device
182          * @v iobuf     I/O buffer
183          * @ret rc      Return status code
184          *
185          * This method should cause the hardware to initiate
186          * transmission of the I/O buffer.
187          *
188          * If this method returns success, the I/O buffer remains
189          * owned by the net device's TX queue, and the net device must
190          * eventually call netdev_tx_complete() to free the buffer.
191          * If this method returns failure, the I/O buffer is
192          * immediately released.
193          *
194          * This method is guaranteed to be called only when the device
195          * is open.
196          */
197         int ( * transmit ) ( struct net_device *netdev, struct io_buffer *iobuf );
198         /** Poll for received packet
199          *
200          * @v netdev    Network device
201          * @v rx_quota  Maximum number of packets to receive
202          *
203          * This method should cause the hardware to check for received
204          * packets.  Any received packets should be delivered via
205          * netdev_rx(), up to a maximum of @c rx_quota packets.
206          *
207          * This method is guaranteed to be called only when the device
208          * is open.
209          */
210         void ( * poll ) ( struct net_device *netdev, unsigned int rx_quota );
211
212         /** Link-layer protocol */
213         struct ll_protocol *ll_protocol;
214         /** Link-layer address
215          *
216          * For Ethernet, this is the MAC address.
217          */
218         uint8_t ll_addr[MAX_LL_ADDR_LEN];
219
220         /** Current device state
221          *
222          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
223          */
224         unsigned int state;
225         /** TX packet queue */
226         struct list_head tx_queue;
227         /** RX packet queue */
228         struct list_head rx_queue;
229         /** Device statistics */
230         struct net_device_stats stats;
231
232         /** Driver private data */
233         void *priv;
234 };
235
236 /** Network device is open */
237 #define NETDEV_OPEN 0x0001
238
239 /** Declare a link-layer protocol */
240 #define __ll_protocol  __table ( struct ll_protocol, ll_protocols, 01 )
241
242 /** Declare a network-layer protocol */
243 #define __net_protocol __table ( struct net_protocol, net_protocols, 01 )
244
245 extern struct list_head net_devices;
246
247 /**
248  * Get printable network device hardware address
249  *
250  * @v netdev            Network device
251  * @ret name            Hardware address
252  */
253 static inline const char * netdev_hwaddr ( struct net_device *netdev ) {
254         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
255 }
256
257 /** Iterate over all network devices */
258 #define for_each_netdev( netdev ) \
259         list_for_each_entry ( (netdev), &net_devices, list )
260
261 /** There exist some network devices
262  *
263  * @ret existence       Existence of network devices
264  */
265 static inline int have_netdevs ( void ) {
266         return ( ! list_empty ( &net_devices ) );
267 }
268
269 /**
270  * Get reference to network device
271  *
272  * @v netdev            Network device
273  * @ret netdev          Network device
274  */
275 static inline __attribute__ (( always_inline )) struct net_device *
276 netdev_get ( struct net_device *netdev ) {
277         ref_get ( &netdev->refcnt );
278         return netdev;
279 }
280
281 /**
282  * Drop reference to network device
283  *
284  * @v netdev            Network device
285  */
286 static inline __attribute__ (( always_inline )) void
287 netdev_put ( struct net_device *netdev ) {
288         ref_put ( &netdev->refcnt );
289 }
290
291 extern int netdev_tx ( struct net_device *netdev, struct io_buffer *iobuf );
292 extern void netdev_tx_complete ( struct net_device *netdev,
293                                  struct io_buffer *iobuf );
294 extern void netdev_tx_complete_next ( struct net_device *netdev );
295 extern void netdev_rx ( struct net_device *netdev, struct io_buffer *iobuf );
296 extern int netdev_poll ( struct net_device *netdev, unsigned int rx_quota );
297 extern struct io_buffer * netdev_rx_dequeue ( struct net_device *netdev );
298 extern struct net_device * alloc_netdev ( size_t priv_size );
299 extern int register_netdev ( struct net_device *netdev );
300 extern int netdev_open ( struct net_device *netdev );
301 extern void netdev_close ( struct net_device *netdev );
302 extern void unregister_netdev ( struct net_device *netdev );
303 extern struct net_device * find_netdev ( const char *name );
304 extern struct net_device * find_netdev_by_location ( unsigned int bus_type,
305                                                      unsigned int location );
306 extern int net_tx ( struct io_buffer *iobuf, struct net_device *netdev,
307                     struct net_protocol *net_protocol, const void *ll_dest );
308 extern int net_rx ( struct io_buffer *iobuf, struct net_device *netdev,
309                     uint16_t net_proto, const void *ll_source );
310
311 #endif /* _GPXE_NETDEVICE_H */