Added network interface management commands
[people/dverkamp/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 pk_buff;
16 struct net_device;
17 struct net_protocol;
18 struct ll_protocol;
19
20 /** Maximum length of a link-layer address */
21 #define MAX_LL_ADDR_LEN 6
22
23 /** Maximum length of a link-layer header */
24 #define MAX_LL_HEADER_LEN 16
25
26 /** Maximum length of a network-layer address */
27 #define MAX_NET_ADDR_LEN 4
28
29 /**
30  * A network-layer protocol
31  *
32  */
33 struct net_protocol {
34         /** Protocol name */
35         const char *name;
36         /**
37          * Process received packet
38          *
39          * @v pkb       Packet buffer
40          * @v netdev    Network device
41          * @v ll_source Link-layer source address
42          *
43          * This method takes ownership of the packet buffer.
44          */
45         int ( * rx ) ( struct pk_buff *pkb, struct net_device *netdev,
46                        const void *ll_source );
47         /**
48          * Transcribe network-layer address
49          *
50          * @v net_addr  Network-layer address
51          * @ret string  Human-readable transcription of address
52          *
53          * This method should convert the network-layer address into a
54          * human-readable format (e.g. dotted quad notation for IPv4).
55          *
56          * The buffer used to hold the transcription is statically
57          * allocated.
58          */
59         const char * ( *ntoa ) ( const void * net_addr );
60         /** Network-layer protocol
61          *
62          * This is an ETH_P_XXX constant, in network-byte order
63          */
64         uint16_t net_proto;
65         /** Network-layer address length */
66         uint8_t net_addr_len;
67 };
68
69 /**
70  * A link-layer protocol
71  *
72  */
73 struct ll_protocol {
74         /** Protocol name */
75         const char *name;
76         /**
77          * Transmit network-layer packet via network device
78          *
79          * @v pkb               Packet buffer
80          * @v netdev            Network device
81          * @v net_protocol      Network-layer protocol
82          * @v ll_dest           Link-layer destination address
83          * @ret rc              Return status code
84          *
85          * This method should prepend in the link-layer header
86          * (e.g. the Ethernet DIX header) and transmit the packet.
87          * This method takes ownership of the packet buffer.
88          */
89         int ( * tx ) ( struct pk_buff *pkb, struct net_device *netdev,
90                        struct net_protocol *net_protocol,
91                        const void *ll_dest );
92         /**
93          * Handle received packet
94          *
95          * @v pkb       Packet buffer
96          * @v netdev    Network device
97          *
98          * This method should strip off the link-layer header
99          * (e.g. the Ethernet DIX header) and pass the packet to
100          * net_rx().  This method takes ownership of the packet
101          * buffer.
102          */
103         int ( * rx ) ( struct pk_buff *pkb, struct net_device *netdev );
104         /**
105          * Transcribe link-layer address
106          *
107          * @v ll_addr   Link-layer address
108          * @ret string  Human-readable transcription of address
109          *
110          * This method should convert the link-layer address into a
111          * human-readable format.
112          *
113          * The buffer used to hold the transcription is statically
114          * allocated.
115          */
116         const char * ( * ntoa ) ( const void * ll_addr );
117         /** Link-layer protocol
118          *
119          * This is an ARPHRD_XXX constant, in network byte order.
120          */
121         uint16_t ll_proto;
122         /** Link-layer address length */
123         uint8_t ll_addr_len;
124         /** Link-layer broadcast address */
125         const uint8_t *ll_broadcast;
126 };
127
128 /**
129  * A network device
130  *
131  * This structure represents a piece of networking hardware.  It has
132  * properties such as a link-layer address and methods for
133  * transmitting and receiving raw packets.
134  *
135  * Note that this structure must represent a generic network device,
136  * not just an Ethernet device.
137  */
138 struct net_device {
139         /** List of network devices */
140         struct list_head list;
141         /** Name of this network device */
142         char name[8];
143         /** List of persistent reference holders */
144         struct list_head references;
145
146         /** Open network device
147          *
148          * @v netdev    Network device
149          * @ret rc      Return status code
150          *
151          * This method should allocate RX packet buffers and enable
152          * the hardware to start transmitting and receiving packets.
153          */
154         int ( * open ) ( struct net_device *netdev );
155         /** Close network device
156          *
157          * @v netdev    Network device
158          *
159          * This method should stop the flow of packets, and free up
160          * any packets that are currently in the device's TX queue.
161          */
162         void ( * close ) ( struct net_device *netdev );
163         /** Transmit packet
164          *
165          * @v netdev    Network device
166          * @v pkb       Packet buffer
167          * @ret rc      Return status code
168          *
169          * This method should cause the hardware to initiate
170          * transmission of the packet buffer.
171          *
172          * If this method returns success, the packet buffer remains
173          * owned by the net device's TX queue, and the net device must
174          * eventually call netdev_tx_complete() to free the buffer.
175          * If this method returns failure, the packet buffer is
176          * immediately released.
177          *
178          * This method is guaranteed to be called only when the device
179          * is open.
180          */
181         int ( * transmit ) ( struct net_device *netdev, struct pk_buff *pkb );
182         /** Poll for received packet
183          *
184          * @v netdev    Network device
185          * @v rx_quota  Maximum number of packets to receive
186          *
187          * This method should cause the hardware to check for received
188          * packets.  Any received packets should be delivered via
189          * netdev_rx(), up to a maximum of @c rx_quota packets.
190          *
191          * This method is guaranteed to be called only when the device
192          * is open.
193          */
194         void ( * poll ) ( struct net_device *netdev, unsigned int rx_quota );
195
196         /** Link-layer protocol */
197         struct ll_protocol *ll_protocol;
198         /** Link-layer address
199          *
200          * For Ethernet, this is the MAC address.
201          */
202         uint8_t ll_addr[MAX_LL_ADDR_LEN];
203
204         /** Current device state
205          *
206          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
207          */
208         unsigned int state;
209         /** TX packet queue */
210         struct list_head tx_queue;
211         /** RX packet queue */
212         struct list_head rx_queue;
213
214         /** Driver private data */
215         void *priv;
216 };
217
218 /** Network device is open */
219 #define NETDEV_OPEN 0x0001
220
221 /** Declare a link-layer protocol */
222 #define __ll_protocol  __table ( ll_protocols, 01 )
223
224 /** Declare a network-layer protocol */
225 #define __net_protocol __table ( net_protocols, 01 )
226
227 extern struct list_head net_devices;
228
229 /**
230  * Get printable network device hardware address
231  *
232  * @v netdev            Network device
233  * @ret name            Hardware address
234  */
235 static inline const char * netdev_hwaddr ( struct net_device *netdev ) {
236         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
237 }
238
239 /** Iterate over all network devices */
240 #define for_each_netdev( netdev ) \
241         list_for_each_entry ( (netdev), &net_devices, list )
242
243 /** There exist some network devices
244  *
245  * @ret existence       Existence of network devices
246  */
247 static inline int have_netdevs ( void ) {
248         return ( ! list_empty ( &net_devices ) );
249 }
250
251 extern int netdev_tx ( struct net_device *netdev, struct pk_buff *pkb );
252 void netdev_tx_complete ( struct net_device *netdev, struct pk_buff *pkb );
253 void netdev_tx_complete_next ( struct net_device *netdev );
254 extern void netdev_rx ( struct net_device *netdev, struct pk_buff *pkb );
255 extern int netdev_poll ( struct net_device *netdev, unsigned int rx_quota );
256 extern struct pk_buff * netdev_rx_dequeue ( struct net_device *netdev );
257 extern struct net_device * alloc_netdev ( size_t priv_size );
258 extern int register_netdev ( struct net_device *netdev );
259 extern int netdev_open ( struct net_device *netdev );
260 extern void netdev_close ( struct net_device *netdev );
261 extern void unregister_netdev ( struct net_device *netdev );
262 extern void free_netdev ( struct net_device *netdev );
263 struct net_device * find_netdev ( const char *name );
264 extern int net_tx ( struct pk_buff *pkb, struct net_device *netdev,
265                     struct net_protocol *net_protocol, const void *ll_dest );
266 extern int net_rx ( struct pk_buff *pkb, struct net_device *netdev,
267                     uint16_t net_proto, const void *ll_source );
268
269 #endif /* _GPXE_NETDEVICE_H */