Network API now allows for multiple network devices (although the
[people/oremanj/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/tables.h>
12
13 struct pk_buff;
14 struct net_protocol;
15 struct ll_protocol;
16
17 /** Maximum length of a link-layer address */
18 #define MAX_LL_ADDR_LEN 6
19
20 /** Maximum length of a network-layer address */
21 #define MAX_NET_ADDR_LEN 4
22
23 /* Network-layer address may be required to hold a link-layer address
24  * (if NETADDR_FL_RAW is set
25  */
26 #if MAX_NET_ADDR_LEN < MAX_LL_ADDR_LEN
27 #undef MAX_NET_ADDR_LEN
28 #define MAX_NET_ADDR_LEN MAX_LL_ADDR_LEN
29 #endif
30
31 /** A generic network-layer header */
32 struct net_header {
33         /** Network-layer protocol */
34         struct net_protocol *net_protocol;
35         /** Destination address flags
36          *
37          * This is the bitwise OR of zero or more NETADDR_FL_XXX
38          * values.
39          */
40         int dest_flags;
41         /** Network-layer destination address */
42         uint8_t dest_net_addr[MAX_NET_ADDR_LEN];
43         /** Network-layer source address */
44         uint8_t source_net_addr[MAX_NET_ADDR_LEN];
45 };
46
47 /** Address is a broadcast address */
48 #define NETADDR_FL_BROADCAST 0x01
49
50 /** Address is a multicast address */
51 #define NETADDR_FL_MULTICAST 0x02
52
53 /** Address is a raw hardware address */
54 #define NETADDR_FL_RAW 0x04
55
56 /** A generic link-layer header */
57 struct ll_header {
58         /** Link-layer protocol */
59         struct ll_protocol *ll_protocol;
60         /** Destination address flags
61          *
62          * This is the bitwise OR of zero or more NETADDR_FL_XXX
63          * values.
64          */
65         int dest_flags;
66         /** Link-layer destination address */
67         uint8_t dest_ll_addr[MAX_LL_ADDR_LEN];
68         /** Link-layer source address */
69         uint8_t source_ll_addr[MAX_LL_ADDR_LEN];
70         /** Network-layer protocol
71          *
72          *
73          * This is an ETH_P_XXX constant, in network-byte order
74          */
75         uint16_t net_proto;
76 };
77
78 /**
79  * A network-layer protocol
80  *
81  */
82 struct net_protocol {
83         /**
84          * Perform network-layer routing
85          *
86          * @v pkb       Packet buffer
87          * @ret source  Network-layer source address
88          * @ret dest    Network-layer destination address
89          * @ret rc      Return status code
90          *
91          * This method should fill in the source and destination
92          * addresses with enough information to allow the link layer
93          * to route the packet.
94          *
95          * For example, in the case of IPv4, this method should fill
96          * in @c source with the IP addresses of the local adapter and
97          * @c dest with the next hop destination (e.g. the gateway).
98          */
99         int ( * route ) ( const struct pk_buff *pkb,
100                           struct net_header *nethdr );
101         /**
102          * Handle received packets
103          *
104          * @v pkb       Packet buffer
105          * @ret rc      Return status code
106          *
107          * If this method returns success, it has taken ownership of
108          * the packet buffer.
109          */
110         int ( * rx ) ( struct pk_buff *pkb );
111         /** Network-layer protocol
112          *
113          * This is an ETH_P_XXX constant, in network-byte order
114          */
115         uint16_t net_proto;
116         /** Network-layer address length */
117         uint8_t net_addr_len;
118 };
119
120 /**
121  * A link-layer protocol
122  *
123  */
124 struct ll_protocol {
125         /**
126          * Perform link-layer routing
127          *
128          * @v nethdr    Generic network-layer header
129          * @ret llhdr   Generic link-layer header
130          * @ret rc      Return status code
131          *
132          * This method should construct the generic link-layer header
133          * based on the generic network-layer header.
134          *
135          * If a link-layer header cannot be constructed (e.g. because
136          * of a missing ARP cache entry), then this method should
137          * return an error (after transmitting an ARP request, if
138          * applicable).
139          */
140         int ( * route ) ( const struct net_header *nethdr,
141                           struct ll_header *llhdr );
142         /**
143          * Fill media-specific link-layer header
144          *
145          * @v llhdr     Generic link-layer header
146          * @v pkb       Packet buffer
147          *
148          * This method should fill in the link-layer header in the
149          * packet buffer based on information in the generic
150          * link-layer header.
151          */
152         void ( * fill_llh ) ( const struct ll_header *llhdr,
153                               struct pk_buff *pkb );
154         /**
155          * Parse media-specific link-layer header
156          *
157          * @v pkb       Packet buffer
158          * @v llhdr     Generic link-layer header
159          *
160          * This method should fill in the generic link-layer header
161          * based on information in the link-layer header in the packet
162          * buffer.
163          */
164         void ( * parse_llh ) ( const struct pk_buff *pkb,
165                                struct ll_header *llhdr );
166
167         /** Link-layer protocol
168          *
169          * This is an ARPHRD_XXX constant, in network byte order.
170          */
171         uint16_t ll_proto;
172         /** Link-layer address length */
173         uint8_t ll_addr_len;
174         /** Link-layer header length */
175         uint8_t ll_header_len;
176 };
177
178 /**
179  * A network-layer address assigned to a network device
180  *
181  */
182 struct net_address {
183         /** Network-layer protocol */
184         struct net_protocol *net_protocol;
185         /** Network-layer address */
186         uint8_t net_addr[MAX_NET_ADDR_LEN];
187 };
188
189 /**
190  * A network device
191  *
192  * This structure represents a piece of networking hardware.  It has
193  * properties such as a link-layer address and methods for
194  * transmitting and receiving raw packets.
195  *
196  * Note that this structure must represent a generic network device,
197  * not just an Ethernet device.
198  */
199 struct net_device {
200         /** Transmit packet
201          *
202          * @v netdev    Network device
203          * @v pkb       Packet buffer
204          * @ret rc      Return status code
205          *
206          * This method should cause the hardware to initiate
207          * transmission of the packet buffer.
208          *
209          * If the method returns success, ownership of the packet
210          * buffer is transferred to the @c net_device, which must
211          * eventually call free_pkb() to release the buffer.
212          */
213         int ( * transmit ) ( struct net_device *netdev, struct pk_buff *pkb );
214         /** Poll for received packet
215          *
216          * @v netdev    Network device
217          *
218          * This method should cause the hardware to check for received
219          * packets.  Any received packets should be delivered via
220          * netdev_rx().
221          */
222         void ( * poll ) ( struct net_device *netdev );
223
224         /** Link-layer protocol */
225         struct ll_protocol *ll_protocol;
226         /** Link-layer address
227          *
228          * For Ethernet, this is the MAC address.
229          */
230         uint8_t ll_addr[MAX_LL_ADDR_LEN];
231
232         /** Driver private data */
233         void *priv;
234 };
235
236 extern struct net_device static_single_netdev;
237
238 /**
239  * Allocate network device
240  *
241  * @v priv_size         Size of private data area (net_device::priv)
242  * @ret netdev          Network device, or NULL
243  *
244  * Allocates space for a network device and its private data area.
245  *
246  * This macro allows for a very efficient implementation in the case
247  * of a single static network device; it neatly avoids dynamic
248  * allocation and can never return failure, meaning that the failure
249  * path will be optimised away.  However, driver writers should not
250  * rely on this feature; the drivers should be written to allow for
251  * multiple instances of network devices.
252  */
253 #define alloc_netdev( priv_size ) ( {           \
254         static char priv_data[priv_size];       \
255         static_single_netdev.priv = priv_data;  \
256         &static_single_netdev; } )
257
258 /**
259  * Register network device
260  *
261  * @v netdev            Network device
262  * @ret rc              Return status code
263  *
264  * Adds the network device to the list of network devices.
265  */
266 static inline int
267 register_netdev ( struct net_device *netdev __attribute__ (( unused )) ) {
268         return 0;
269 }
270
271 /**
272  * Unregister network device
273  *
274  * @v netdev            Network device
275  *
276  * Removes the network device from the list of network devices.
277  */
278 static inline void 
279 unregister_netdev ( struct net_device *netdev __attribute__ (( unused )) ) {
280         /* Nothing to do */
281 }
282
283 /**
284  * Free network device
285  *
286  * @v netdev            Network device
287  */
288 static inline void
289 free_netdev ( struct net_device *netdev __attribute__ (( unused )) ) {
290         /* Nothing to do */
291 }
292
293 /**
294  * Register a link-layer protocol
295  *
296  * @v protocol          Link-layer protocol
297  */
298 #define LL_PROTOCOL( protocol ) \
299         struct ll_protocol protocol __table ( ll_protocols, 00 )
300
301 /**
302  * Register a network-layer protocol
303  *
304  * @v protocol          Network-layer protocol
305  */
306 #define NET_PROTOCOL( protocol ) \
307         struct net_protocol protocol __table ( net_protocols, 00 )
308
309 /**
310  * Register a network-layer address for the static single network device
311  *
312  * @v net_address       Network-layer address
313  */
314 #define STATIC_SINGLE_NETDEV_ADDRESS( address ) \
315         struct net_address address __table ( sgl_netdev_addresses, 00 )
316
317 extern struct net_protocol *net_find_protocol ( uint16_t net_proto );
318 extern struct net_device * net_find_address ( struct net_protocol *net_proto,
319                                               void *net_addr );
320
321 extern int net_transmit ( struct pk_buff *pkb );
322 extern int net_poll ( void );
323 extern void netdev_rx ( struct net_device *netdev, struct pk_buff *pkb );
324 extern struct pk_buff * net_rx_dequeue ( void );
325
326 #endif /* _GPXE_NETDEVICE_H */