Added net device TX queue; this will be needed to support the PXE UNDI API
[people/xl0/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
142         /** List of persistent reference holders */
143         struct list_head references;
144
145         /** Open network device
146          *
147          * @v netdev    Network device
148          * @ret rc      Return status code
149          *
150          * This method should allocate RX packet buffers and enable
151          * the hardware to start transmitting and receiving packets.
152          */
153         int ( * open ) ( struct net_device *netdev );
154         /** Close network device
155          *
156          * @v netdev    Network device
157          *
158          * This method should stop the flow of packets, and free up
159          * any packets that are currently in the device's TX queue.
160          */
161         void ( * close ) ( struct net_device *netdev );
162         /** Transmit packet
163          *
164          * @v netdev    Network device
165          * @v pkb       Packet buffer
166          * @ret rc      Return status code
167          *
168          * This method should cause the hardware to initiate
169          * transmission of the packet buffer.
170          *
171          * If this method returns success, the packet buffer remains
172          * owned by the net device's TX queue, and the net device must
173          * eventually call netdev_tx_complete() to free the buffer.
174          * If this method returns failure, the packet buffer is
175          * immediately released.
176          *
177          * This method is guaranteed to be called only when the device
178          * is open.
179          */
180         int ( * transmit ) ( struct net_device *netdev, struct pk_buff *pkb );
181         /** Poll for received packet
182          *
183          * @v netdev    Network device
184          *
185          * This method should cause the hardware to check for received
186          * packets.  Any received packets should be delivered via
187          * netdev_rx().
188          *
189          * This method is guaranteed to be called only when the device
190          * is open.
191          */
192         void ( * poll ) ( struct net_device *netdev );
193
194         /** Link-layer protocol */
195         struct ll_protocol *ll_protocol;
196         /** Link-layer address
197          *
198          * For Ethernet, this is the MAC address.
199          */
200         uint8_t ll_addr[MAX_LL_ADDR_LEN];
201
202         /** Current device state
203          *
204          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
205          */
206         unsigned int state;
207         /** TX packet queue */
208         struct list_head tx_queue;
209         /** RX packet queue */
210         struct list_head rx_queue;
211
212         /** Driver private data */
213         void *priv;
214 };
215
216 /** Network device is open */
217 #define NETDEV_OPEN 0x0001
218
219 /** Declare a link-layer protocol */
220 #define __ll_protocol  __table ( ll_protocols, 01 )
221
222 /** Declare a network-layer protocol */
223 #define __net_protocol __table ( net_protocols, 01 )
224
225 /**
226  * Get network device name
227  *
228  * @v netdev            Network device
229  * @ret name            Network device name
230  *
231  * The name will be the device's link-layer address.
232  */
233 static inline const char * netdev_name ( struct net_device *netdev ) {
234         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
235 }
236
237 extern int netdev_tx ( struct net_device *netdev, struct pk_buff *pkb );
238 void netdev_tx_complete ( struct net_device *netdev, struct pk_buff *pkb );
239 void netdev_tx_complete_next ( struct net_device *netdev );
240 extern void netdev_rx ( struct net_device *netdev, struct pk_buff *pkb );
241 extern int netdev_poll ( struct net_device *netdev );
242 extern struct pk_buff * netdev_rx_dequeue ( struct net_device *netdev );
243 extern struct net_device * alloc_netdev ( size_t priv_size );
244 extern int register_netdev ( struct net_device *netdev );
245 extern int netdev_open ( struct net_device *netdev );
246 extern void netdev_close ( struct net_device *netdev );
247 extern void unregister_netdev ( struct net_device *netdev );
248 extern void free_netdev ( struct net_device *netdev );
249 extern struct net_device * next_netdev ( void );
250 extern int net_tx ( struct pk_buff *pkb, struct net_device *netdev,
251                     struct net_protocol *net_protocol, const void *ll_dest );
252 extern int net_rx ( struct pk_buff *pkb, struct net_device *netdev,
253                     uint16_t net_proto, const void *ll_source );
254
255 #endif /* _GPXE_NETDEVICE_H */