Make open() and close() an official part of the netdevice API.
[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
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          * Ownership of the packet buffer is transferred to the @c
172          * net_device, which must eventually call free_pkb() to
173          * release the buffer.
174          *
175          * This method is guaranteed to be called only when the device
176          * is open.
177          */
178         int ( * transmit ) ( struct net_device *netdev, struct pk_buff *pkb );
179         /** Poll for received packet
180          *
181          * @v netdev    Network device
182          *
183          * This method should cause the hardware to check for received
184          * packets.  Any received packets should be delivered via
185          * netdev_rx().
186          *
187          * This method is guaranteed to be called only when the device
188          * is open.
189          */
190         void ( * poll ) ( struct net_device *netdev );
191
192         /** Link-layer protocol */
193         struct ll_protocol *ll_protocol;
194         /** Link-layer address
195          *
196          * For Ethernet, this is the MAC address.
197          */
198         uint8_t ll_addr[MAX_LL_ADDR_LEN];
199
200         /** Current device state
201          *
202          * This is the bitwise-OR of zero or more NETDEV_XXX constants.
203          */
204         unsigned int state;
205         /** Received packet queue */
206         struct list_head rx_queue;
207
208         /** Driver private data */
209         void *priv;
210 };
211
212 /** Network device is open */
213 #define NETDEV_OPEN 0x0001
214
215 /** Declare a link-layer protocol */
216 #define __ll_protocol  __table ( ll_protocols, 01 )
217
218 /** Declare a network-layer protocol */
219 #define __net_protocol __table ( net_protocols, 01 )
220
221 /**
222  * Get network device name
223  *
224  * @v netdev            Network device
225  * @ret name            Network device name
226  *
227  * The name will be the device's link-layer address.
228  */
229 static inline const char * netdev_name ( struct net_device *netdev ) {
230         return netdev->ll_protocol->ntoa ( netdev->ll_addr );
231 }
232
233 extern int netdev_tx ( struct net_device *netdev, struct pk_buff *pkb );
234 extern void netdev_rx ( struct net_device *netdev, struct pk_buff *pkb );
235 extern int net_tx ( struct pk_buff *pkb, struct net_device *netdev,
236                     struct net_protocol *net_protocol, const void *ll_dest );
237 extern int net_rx ( struct pk_buff *pkb, struct net_device *netdev,
238                     uint16_t net_proto, const void *ll_source );
239 extern int netdev_poll ( struct net_device *netdev );
240 extern struct pk_buff * netdev_rx_dequeue ( struct net_device *netdev );
241 extern struct net_device * alloc_netdev ( size_t priv_size );
242 extern int register_netdev ( struct net_device *netdev );
243 extern int netdev_open ( struct net_device *netdev );
244 extern void netdev_close ( struct net_device *netdev );
245 extern void unregister_netdev ( struct net_device *netdev );
246 extern void free_netdev ( struct net_device *netdev );
247 extern struct net_device * next_netdev ( void );
248
249 #endif /* _GPXE_NETDEVICE_H */