68226dc25a5c24a7fbabf0cdd21f6598d42a1cce
[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/tables.h>
12
13 struct pk_buff;
14 struct net_device;
15 struct net_protocol;
16 struct ll_protocol;
17
18 /** Maximum length of a link-layer address */
19 #define MAX_LL_ADDR_LEN 6
20
21 /** Maximum length of a link-layer header */
22 #define MAX_LL_HEADER_LEN 16
23
24 /** Maximum length of a network-layer address */
25 #define MAX_NET_ADDR_LEN 4
26
27 /* Network-layer address may be required to hold a link-layer address
28  * (if NETADDR_FL_RAW is set
29  */
30 #if MAX_NET_ADDR_LEN < MAX_LL_ADDR_LEN
31 #undef MAX_NET_ADDR_LEN
32 #define MAX_NET_ADDR_LEN MAX_LL_ADDR_LEN
33 #endif
34
35 /** A generic network-layer header */
36 struct net_header {
37         /** Network-layer protocol */
38         struct net_protocol *net_protocol;
39         /** Flags
40          *
41          * This is the bitwise OR of zero or more PKT_FL_XXX
42          * values.
43          */
44         int flags;
45         /** Network-layer destination address */
46         uint8_t dest_net_addr[MAX_NET_ADDR_LEN];
47         /** Network-layer source address */
48         uint8_t source_net_addr[MAX_NET_ADDR_LEN];
49 };
50
51 /** Packet is a broadcast packet */
52 #define PKT_FL_BROADCAST 0x01
53
54 /** Packet is a multicast packet */
55 #define PKT_FL_MULTICAST 0x02
56
57 /** Addresses are raw hardware addresses */
58 #define PKT_FL_RAW_ADDR 0x04
59
60 /** A generic link-layer header */
61 struct ll_header {
62         /** Link-layer protocol */
63         struct ll_protocol *ll_protocol;
64         /** Flags
65          *
66          * This is the bitwise OR of zero or more PKT_FL_XXX
67          * values.
68          */
69         int flags;
70         /** Link-layer destination address */
71         uint8_t dest_ll_addr[MAX_LL_ADDR_LEN];
72         /** Link-layer source address */
73         uint8_t source_ll_addr[MAX_LL_ADDR_LEN];
74         /** Network-layer protocol
75          *
76          *
77          * This is an ETH_P_XXX constant, in network-byte order
78          */
79         uint16_t net_proto;
80 };
81
82 /**
83  * A network-layer protocol
84  *
85  */
86 struct net_protocol {
87         /** Protocol name */
88         const char *name;
89         /**
90          * Process received packet
91          *
92          * @v pkb       Packet buffer
93          * @ret rc      Return status code
94          *
95          * This method takes ownership of the packet buffer.
96          */
97         int ( * rx_process ) ( struct pk_buff *pkb );
98         /**
99          * Transcribe network-layer address
100          *
101          * @v net_addr  Network-layer address
102          * @ret string  Human-readable transcription of address
103          *
104          * This method should convert the network-layer address into a
105          * human-readable format (e.g. dotted quad notation for IPv4).
106          *
107          * The buffer used to hold the transcription is statically
108          * allocated.
109          */
110         const char * ( *ntoa ) ( const void * net_addr );
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         /** Protocol name */
126         const char *name;
127         /**
128          * Transmit network-layer packet via network device
129          *
130          *
131          * @v pkb               Packet buffer
132          * @v netdev            Network device
133          * @v net_protocol      Network-layer protocol
134          * @v ll_dest           Link-layer destination address
135          * @ret rc              Return status code
136          *
137          * This method should prepend in the link-layer header
138          * (e.g. the Ethernet DIX header) and transmit the packet.
139          */
140         int ( * transmit ) ( struct pk_buff *pkb, struct net_device *netdev,
141                              struct net_protocol *net_protocol,
142                              const void *ll_dest );
143         /**
144          * Parse media-specific link-layer header
145          *
146          * @v pkb       Packet buffer
147          * @v llhdr     Generic link-layer header
148          *
149          * This method should fill in the generic link-layer header
150          * based on information in the link-layer header in the packet
151          * buffer.
152          */
153         void ( * parse_llh ) ( const struct pk_buff *pkb,
154                                struct ll_header *llhdr );
155
156         /**
157          * Transcribe link-layer address
158          *
159          * @v ll_addr   Link-layer address
160          * @ret string  Human-readable transcription of address
161          *
162          * This method should convert the link-layer address into a
163          * human-readable format.
164          *
165          * The buffer used to hold the transcription is statically
166          * allocated.
167          */
168         const char * ( *ntoa ) ( const void * ll_addr );
169         /** Link-layer protocol
170          *
171          * This is an ARPHRD_XXX constant, in network byte order.
172          */
173         uint16_t ll_proto;
174         /** Link-layer address length */
175         uint8_t ll_addr_len;
176         /** Link-layer broadcast address */
177         const uint8_t *ll_broadcast;
178 };
179
180 /**
181  * A network-layer address assigned to a network device
182  *
183  */
184 struct net_address {
185         /** Network-layer protocol */
186         struct net_protocol *net_protocol;
187         /** Network-layer address */
188         uint8_t net_addr[MAX_NET_ADDR_LEN];
189 };
190
191 /**
192  * A network device
193  *
194  * This structure represents a piece of networking hardware.  It has
195  * properties such as a link-layer address and methods for
196  * transmitting and receiving raw packets.
197  *
198  * Note that this structure must represent a generic network device,
199  * not just an Ethernet device.
200  */
201 struct net_device {
202         /** Transmit packet
203          *
204          * @v netdev    Network device
205          * @v pkb       Packet buffer
206          * @ret rc      Return status code
207          *
208          * This method should cause the hardware to initiate
209          * transmission of the packet buffer.
210          *
211          * Ownership of the packet buffer is transferred to the @c
212          * net_device, which must eventually call free_pkb() to
213          * release the buffer.
214          */
215         int ( * transmit ) ( struct net_device *netdev, struct pk_buff *pkb );
216         /** Poll for received packet
217          *
218          * @v netdev    Network device
219          *
220          * This method should cause the hardware to check for received
221          * packets.  Any received packets should be delivered via
222          * netdev_rx().
223          */
224         void ( * poll ) ( struct net_device *netdev );
225
226         /** Link-layer protocol */
227         struct ll_protocol *ll_protocol;
228         /** Link-layer address
229          *
230          * For Ethernet, this is the MAC address.
231          */
232         uint8_t ll_addr[MAX_LL_ADDR_LEN];
233
234         /** Driver private data */
235         void *priv;
236 };
237
238 extern struct net_device static_single_netdev;
239
240 /**
241  * Allocate network device
242  *
243  * @v priv_size         Size of private data area (net_device::priv)
244  * @ret netdev          Network device, or NULL
245  *
246  * Allocates space for a network device and its private data area.
247  *
248  * This macro allows for a very efficient implementation in the case
249  * of a single static network device; it neatly avoids dynamic
250  * allocation and can never return failure, meaning that the failure
251  * path will be optimised away.  However, driver writers should not
252  * rely on this feature; the drivers should be written to allow for
253  * multiple instances of network devices.
254  */
255 #define alloc_netdev( priv_size ) ( {           \
256         static char priv_data[priv_size];       \
257         static_single_netdev.priv = priv_data;  \
258         &static_single_netdev; } )
259
260 /**
261  * Free network device
262  *
263  * @v netdev            Network device
264  */
265 static inline void
266 free_netdev ( struct net_device *netdev __attribute__ (( unused )) ) {
267         /* Nothing to do */
268 }
269
270 /**
271  * Transmit raw packet via network device
272  *
273  * @v netdev            Network device
274  * @v pkb               Packet buffer
275  * @ret rc              Return status code
276  *
277  * Transmits the packet via the specified network device.  The
278  * link-layer header must already have been filled in.  This function
279  * takes ownership of the packet buffer.
280  */
281 static inline int netdev_transmit ( struct net_device *netdev,
282                                     struct pk_buff *pkb ) {
283         return netdev->transmit ( netdev, pkb );
284 }
285
286 /**
287  * Transmit network-layer packet
288  *
289  * @v pkb               Packet buffer
290  * @v netdev            Network device
291  * @v net_protocol      Network-layer protocol
292  * @v ll_dest           Destination link-layer address
293  * @ret rc              Return status code
294  *
295  * Prepends link-layer headers to the packet buffer and transmits the
296  * packet via the specified network device.  This function takes
297  * ownership of the packet buffer.
298  */
299 static inline int net_transmit ( struct pk_buff *pkb,
300                                  struct net_device *netdev,
301                                  struct net_protocol *net_protocol,
302                                  const void *ll_dest ) {
303         return netdev->ll_protocol->transmit ( pkb, netdev, net_protocol,
304                                                ll_dest );
305 }
306
307 /**
308  * Register a link-layer protocol
309  *
310  * @v protocol          Link-layer protocol
311  */
312 #define LL_PROTOCOL( protocol ) \
313         struct ll_protocol protocol __table ( ll_protocols, 01 )
314
315 /**
316  * Register a network-layer protocol
317  *
318  * @v protocol          Network-layer protocol
319  */
320 #define NET_PROTOCOL( protocol ) \
321         struct net_protocol protocol __table ( net_protocols, 01 )
322
323 /**
324  * Register a network-layer address for the static single network device
325  *
326  * @v net_address       Network-layer address
327  */
328 #define STATIC_SINGLE_NETDEV_ADDRESS( address ) \
329         struct net_address address __table ( sgl_netdev_addresses, 01 )
330
331 extern int register_netdev ( struct net_device *netdev );
332 extern void unregister_netdev ( struct net_device *netdev );
333 extern void netdev_rx ( struct net_device *netdev, struct pk_buff *pkb );
334
335 extern struct net_protocol *find_net_protocol ( uint16_t net_proto );
336 extern struct net_device *
337 find_netdev_by_net_addr ( struct net_protocol *net_protocol, void *net_addr );
338
339 extern int net_poll ( void );
340 extern struct pk_buff * net_rx_dequeue ( void );
341 extern int net_rx_process ( struct pk_buff *pkb );
342
343 #endif /* _GPXE_NETDEVICE_H */