1 /*
2 * u_ether.h -- interface to USB gadget "ethernet link" utilities
3 *
4 * Copyright (C) 2003-2005,2008 David Brownell
5 * Copyright (C) 2003-2004 Robert Schwebel, Benedikt Spranger
6 * Copyright (C) 2008 Nokia Corporation
7 *
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
12 */
13
14 #ifndef __U_ETHER_H
15 #define __U_ETHER_H
16
17 #include <linux/err.h>
18 #include <linux/if_ether.h>
19 #include <linux/usb/composite.h>
20 #include <linux/usb/cdc.h>
21 #include <linux/netdevice.h>
22
23 #include "gadget_chips.h"
24
25 #define QMULT_DEFAULT 5
26
27 /*
28 * dev_addr: initial value
29 * changed by "ifconfig usb0 hw ether xx:xx:xx:xx:xx:xx"
30 * host_addr: this address is invisible to ifconfig
31 */
32 #define USB_ETHERNET_MODULE_PARAMETERS() \
33 static unsigned qmult = QMULT_DEFAULT; \
34 module_param(qmult, uint, S_IRUGO|S_IWUSR); \
35 MODULE_PARM_DESC(qmult, "queue length multiplier at high/super speed");\
36 \
37 static char *dev_addr; \
38 module_param(dev_addr, charp, S_IRUGO); \
39 MODULE_PARM_DESC(dev_addr, "Device Ethernet Address"); \
40 \
41 static char *host_addr; \
42 module_param(host_addr, charp, S_IRUGO); \
43 MODULE_PARM_DESC(host_addr, "Host Ethernet Address")
44
45 struct eth_dev;
46
47 /*
48 * This represents the USB side of an "ethernet" link, managed by a USB
49 * function which provides control and (maybe) framing. Two functions
50 * in different configurations could share the same ethernet link/netdev,
51 * using different host interaction models.
52 *
53 * There is a current limitation that only one instance of this link may
54 * be present in any given configuration. When that's a problem, network
55 * layer facilities can be used to package multiple logical links on this
56 * single "physical" one.
57 */
58 struct gether {
59 struct usb_function func;
60
61 /* updated by gether_{connect,disconnect} */
62 struct eth_dev *ioport;
63
64 /* endpoints handle full and/or high speeds */
65 struct usb_ep *in_ep;
66 struct usb_ep *out_ep;
67
68 bool is_zlp_ok;
69
70 u16 cdc_filter;
71
72 /* hooks for added framing, as needed for RNDIS and EEM. */
73 u32 header_len;
74 /* NCM requires fixed size bundles */
75 bool is_fixed;
76 u32 fixed_out_len;
77 u32 fixed_in_len;
78 unsigned ul_max_pkts_per_xfer;
79 unsigned dl_max_pkts_per_xfer;
80 bool multi_pkt_xfer;
81 bool supports_multi_frame;
82 struct sk_buff *(*wrap)(struct gether *port,
83 struct sk_buff *skb);
84 int (*unwrap)(struct gether *port,
85 struct sk_buff *skb,
86 struct sk_buff_head *list);
87
88 /* called on network open/close */
89 void (*open)(struct gether *);
90 void (*close)(struct gether *);
91 };
92
93 #define DEFAULT_FILTER (USB_CDC_PACKET_TYPE_BROADCAST \
94 |USB_CDC_PACKET_TYPE_ALL_MULTICAST \
95 |USB_CDC_PACKET_TYPE_PROMISCUOUS \
96 |USB_CDC_PACKET_TYPE_DIRECTED)
97
98 /* variant of gether_setup that allows customizing network device name */
99 struct eth_dev *gether_setup_name(struct usb_gadget *g,
100 const char *dev_addr, const char *host_addr,
101 u8 ethaddr[ETH_ALEN], unsigned qmult, const char *netname);
102
103 /* netdev setup/teardown as directed by the gadget driver */
104 /* gether_setup - initialize one ethernet-over-usb link
105 * @g: gadget to associated with these links
106 * @ethaddr: NULL, or a buffer in which the ethernet address of the
107 * host side of the link is recorded
108 * Context: may sleep
109 *
110 * This sets up the single network link that may be exported by a
111 * gadget driver using this framework. The link layer addresses are
112 * set up using module parameters.
113 *
114 * Returns a eth_dev pointer on success, or an ERR_PTR on failure
115 */
gether_setup(struct usb_gadget * g,const char * dev_addr,const char * host_addr,u8 ethaddr[ETH_ALEN],unsigned qmult)116 static inline struct eth_dev *gether_setup(struct usb_gadget *g,
117 const char *dev_addr, const char *host_addr,
118 u8 ethaddr[ETH_ALEN], unsigned qmult)
119 {
120 return gether_setup_name(g, dev_addr, host_addr, ethaddr, qmult, "usb");
121 }
122
123 /*
124 * variant of gether_setup_default that allows customizing
125 * network device name
126 */
127 struct net_device *gether_setup_name_default(const char *netname);
128
129 /*
130 * gether_register_netdev - register the net device
131 * @net: net device to register
132 *
133 * Registers the net device associated with this ethernet-over-usb link
134 *
135 */
136 int gether_register_netdev(struct net_device *net);
137
138 /* gether_setup_default - initialize one ethernet-over-usb link
139 * Context: may sleep
140 *
141 * This sets up the single network link that may be exported by a
142 * gadget driver using this framework. The link layer addresses
143 * are set to random values.
144 *
145 * Returns negative errno, or zero on success
146 */
gether_setup_default(void)147 static inline struct net_device *gether_setup_default(void)
148 {
149 return gether_setup_name_default("usb");
150 }
151
152 /**
153 * gether_set_gadget - initialize one ethernet-over-usb link with a gadget
154 * @net: device representing this link
155 * @g: the gadget to initialize with
156 *
157 * This associates one ethernet-over-usb link with a gadget.
158 */
159 void gether_set_gadget(struct net_device *net, struct usb_gadget *g);
160
161 /**
162 * gether_set_dev_addr - initialize an ethernet-over-usb link with eth address
163 * @net: device representing this link
164 * @dev_addr: eth address of this device
165 *
166 * This sets the device-side Ethernet address of this ethernet-over-usb link
167 * if dev_addr is correct.
168 * Returns negative errno if the new address is incorrect.
169 */
170 int gether_set_dev_addr(struct net_device *net, const char *dev_addr);
171
172 /**
173 * gether_get_dev_addr - get an ethernet-over-usb link eth address
174 * @net: device representing this link
175 * @dev_addr: place to store device's eth address
176 * @len: length of the @dev_addr buffer
177 *
178 * This gets the device-side Ethernet address of this ethernet-over-usb link.
179 * Returns zero on success, else negative errno.
180 */
181 int gether_get_dev_addr(struct net_device *net, char *dev_addr, int len);
182
183 /**
184 * gether_set_host_addr - initialize an ethernet-over-usb link with host address
185 * @net: device representing this link
186 * @host_addr: eth address of the host
187 *
188 * This sets the host-side Ethernet address of this ethernet-over-usb link
189 * if host_addr is correct.
190 * Returns negative errno if the new address is incorrect.
191 */
192 int gether_set_host_addr(struct net_device *net, const char *host_addr);
193
194 /**
195 * gether_get_host_addr - get an ethernet-over-usb link host address
196 * @net: device representing this link
197 * @host_addr: place to store eth address of the host
198 * @len: length of the @host_addr buffer
199 *
200 * This gets the host-side Ethernet address of this ethernet-over-usb link.
201 * Returns zero on success, else negative errno.
202 */
203 int gether_get_host_addr(struct net_device *net, char *host_addr, int len);
204
205 /**
206 * gether_get_host_addr_cdc - get an ethernet-over-usb link host address
207 * @net: device representing this link
208 * @host_addr: place to store eth address of the host
209 * @len: length of the @host_addr buffer
210 *
211 * This gets the CDC formatted host-side Ethernet address of this
212 * ethernet-over-usb link.
213 * Returns zero on success, else negative errno.
214 */
215 int gether_get_host_addr_cdc(struct net_device *net, char *host_addr, int len);
216
217 /**
218 * gether_get_host_addr_u8 - get an ethernet-over-usb link host address
219 * @net: device representing this link
220 * @host_mac: place to store the eth address of the host
221 *
222 * This gets the binary formatted host-side Ethernet address of this
223 * ethernet-over-usb link.
224 */
225 void gether_get_host_addr_u8(struct net_device *net, u8 host_mac[ETH_ALEN]);
226
227 /**
228 * gether_set_qmult - initialize an ethernet-over-usb link with a multiplier
229 * @net: device representing this link
230 * @qmult: queue multiplier
231 *
232 * This sets the queue length multiplier of this ethernet-over-usb link.
233 * For higher speeds use longer queues.
234 */
235 void gether_set_qmult(struct net_device *net, unsigned qmult);
236
237 /**
238 * gether_get_qmult - get an ethernet-over-usb link multiplier
239 * @net: device representing this link
240 *
241 * This gets the queue length multiplier of this ethernet-over-usb link.
242 */
243 unsigned gether_get_qmult(struct net_device *net);
244
245 /**
246 * gether_get_ifname - get an ethernet-over-usb link interface name
247 * @net: device representing this link
248 * @name: place to store the interface name
249 * @len: length of the @name buffer
250 *
251 * This gets the interface name of this ethernet-over-usb link.
252 * Returns zero on success, else negative errno.
253 */
254 int gether_get_ifname(struct net_device *net, char *name, int len);
255
256 void gether_cleanup(struct eth_dev *dev);
257
258 /* connect/disconnect is handled by individual functions */
259 struct net_device *gether_connect(struct gether *);
260 void gether_disconnect(struct gether *);
261
262 /* Some controllers can't support CDC Ethernet (ECM) ... */
can_support_ecm(struct usb_gadget * gadget)263 static inline bool can_support_ecm(struct usb_gadget *gadget)
264 {
265 if (!gadget_supports_altsettings(gadget))
266 return false;
267
268 /* Everything else is *presumably* fine ... but this is a bit
269 * chancy, so be **CERTAIN** there are no hardware issues with
270 * your controller. Add it above if it can't handle CDC.
271 */
272 return true;
273 }
274
275 #endif /* __U_ETHER_H */
276