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