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