1 /* $NetBSD: usbnet.h,v 1.33 2022/03/03 05:56:51 riastradh Exp $ */ 2 3 /* 4 * Copyright (c) 2019 Matthew R. Green 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 #ifndef _DEV_USB_USBNET_H 30 #define _DEV_USB_USBNET_H 31 32 /* 33 * Common code/data shared by all USB ethernet drivers (using these routines.) 34 * 35 * This framework provides the following features for USB ethernet drivers: 36 * 37 * - USB endpoint pipe handling 38 * - rx and tx chain handling 39 * - generic handlers or support for several struct ifnet callbacks 40 * - MII bus locking 41 * - interrupt handling 42 * - partial autoconf handling 43 * 44 * Consumers of this interface need to: 45 * 46 * - replace most softc members with "struct usbnet" usage, in particular 47 * use usbnet pointer for ifp->if_softc, and device_private (real softc 48 * can be stored in un_sc member) 49 * - use MII bus lock / access methods 50 * - usbnet_attach() to initialise and allocate rx/tx chains 51 * - usbnet_attach_ifp() to attach the interface, and either ether_ifattach() 52 * for ethernet devices, or if_alloc_sadl()/bpf_attach() pair otherwise. 53 * - usbnet_detach() to clean them up 54 * - usbnet_activate() for autoconf 55 * - interface ioctl and start have direct frontends with callbacks for 56 * device specific handling: 57 * - ioctl can use either a device-specific override (useful for special 58 * cases), but provides a normal handler with callback to handle 59 * ENETRESET conditions that should be sufficient for most users 60 * - start uses usbnet transmit prepare callback (uno_tx_prepare) 61 * - interrupt handling: 62 * - for rx, usbnet will enable the receive pipes and 63 * call the rx_loop callback to handle device specific processing of 64 * packets, which can use usbnet_enqueue() to provide data to the 65 * higher layers 66 * - for tx, usbnet will pull entries out of the 67 * transmit queue and use the transmit prepare callback (uno_tx_prepare) 68 * for the given mbuf. the usb callback will use usbnet_txeof() for 69 * the transmit completion function (internal to usbnet) 70 * - there is special interrupt pipe handling 71 * - timer/tick: 72 * - the uno_tick callback will be called once a second if present. 73 */ 74 75 #include <sys/device.h> 76 #include <sys/mbuf.h> 77 #include <sys/rndsource.h> 78 #include <sys/mutex.h> 79 #include <sys/module.h> 80 81 #include <net/bpf.h> 82 #include <net/if.h> 83 #include <net/if_arp.h> 84 #include <net/if_dl.h> 85 #include <net/if_ether.h> 86 #include <net/if_media.h> 87 88 #include <dev/mii/mii.h> 89 #include <dev/mii/miivar.h> 90 91 #include <dev/usb/usb.h> 92 #include <dev/usb/usbdi.h> 93 #include <dev/usb/usbdivar.h> 94 #include <dev/usb/usbdi_util.h> 95 #include <dev/usb/usbdevs.h> 96 97 /* 98 * Per-transfer data. 99 * 100 * Front-end must set un_rx_list_cnt and un_tx_list_cnt before 101 * calling usbnet_attach(), and then call usbnet_rx_tx_init() 102 * which will allocate the chain arrays, and must be NULL to 103 * indicate the first call. 104 */ 105 struct usbnet; 106 struct usbnet_chain { 107 struct usbnet *unc_un; 108 struct usbd_xfer *unc_xfer; 109 uint8_t *unc_buf; 110 }; 111 112 /* 113 * Extend this as necessary. axe(4) claims to want 6 total, but 114 * does not implement them. 115 */ 116 enum usbnet_ep { 117 USBNET_ENDPT_RX, 118 USBNET_ENDPT_TX, 119 USBNET_ENDPT_INTR, 120 USBNET_ENDPT_MAX, 121 }; 122 123 /* Interface stop callback. */ 124 typedef void (*usbnet_stop_cb)(struct ifnet *, int); 125 /* Interface ioctl callback. */ 126 typedef int (*usbnet_ioctl_cb)(struct ifnet *, u_long, void *); 127 /* Reprogram multicast filters callback. */ 128 typedef void (*usbnet_mcast_cb)(struct ifnet *); 129 /* Initialise device callback. */ 130 typedef int (*usbnet_init_cb)(struct ifnet *); 131 132 /* MII read register callback. */ 133 typedef int (*usbnet_mii_read_reg_cb)(struct usbnet *, int reg, 134 int phy, uint16_t *val); 135 /* MII write register callback. */ 136 typedef int (*usbnet_mii_write_reg_cb)(struct usbnet *, int reg, 137 int phy, uint16_t val); 138 /* MII status change callback. */ 139 typedef void (*usbnet_mii_statchg_cb)(struct ifnet *); 140 141 /* Prepare packet to send callback, returns length. */ 142 typedef unsigned (*usbnet_tx_prepare_cb)(struct usbnet *, struct mbuf *, 143 struct usbnet_chain *); 144 /* Receive some packets callback. */ 145 typedef void (*usbnet_rx_loop_cb)(struct usbnet *, struct usbnet_chain *, 146 uint32_t); 147 /* Tick callback. */ 148 typedef void (*usbnet_tick_cb)(struct usbnet *); 149 /* Interrupt pipe callback. */ 150 typedef void (*usbnet_intr_cb)(struct usbnet *, usbd_status); 151 152 /* 153 * LOCKING 154 * ======= 155 * 156 * The following annotations indicate which locks are held when 157 * usbnet_ops functions are invoked: 158 * 159 * I -> IFNET_LOCK (if_ioctl_lock) 160 * C -> CORE_LOCK (usbnet core_lock) 161 * T -> TX_LOCK (usbnet tx_lock) 162 * R -> RX_LOCK (usbnet rx_lock) 163 * n -> no locks held 164 * 165 * Note that when CORE_LOCK is held, IFNET_LOCK may or may not also 166 * be held. 167 * 168 * Note that the IFNET_LOCK **may not be held** for the ioctl commands 169 * SIOCADDMULTI/SIOCDELMULTI. These commands are only passed 170 * explicitly to uno_override_ioctl; for all other devices, they are 171 * handled by uno_mcast (also without IFNET_LOCK). 172 */ 173 struct usbnet_ops { 174 usbnet_stop_cb uno_stop; /* C */ 175 usbnet_ioctl_cb uno_ioctl; /* I */ 176 usbnet_ioctl_cb uno_override_ioctl; /* I (except mcast) */ 177 usbnet_mcast_cb uno_mcast; /* I */ 178 usbnet_init_cb uno_init; /* I */ 179 usbnet_mii_read_reg_cb uno_read_reg; /* C */ 180 usbnet_mii_write_reg_cb uno_write_reg; /* C */ 181 usbnet_mii_statchg_cb uno_statchg; /* C */ 182 usbnet_tx_prepare_cb uno_tx_prepare; /* T */ 183 usbnet_rx_loop_cb uno_rx_loop; /* R */ 184 usbnet_tick_cb uno_tick; /* n */ 185 usbnet_intr_cb uno_intr; /* n */ 186 }; 187 188 /* 189 * USB interrupt pipe support. Use this if usbd_open_pipe_intr() should 190 * be used for the interrupt pipe. 191 */ 192 struct usbnet_intr { 193 /* 194 * Point un_intr to this structure to use usbd_open_pipe_intr() not 195 * usbd_open_pipe() for USBNET_ENDPT_INTR, with this buffer, size, 196 * and interval. 197 */ 198 void *uni_buf; 199 unsigned uni_bufsz; 200 unsigned uni_interval; 201 }; 202 203 /* 204 * Structure to setup MII. Use the USBNET_MII_DECL_DEFAULT() macro for 205 * sane default. Pass a copy to usbnet_attach_ifp(). Not used 206 * after the usbnet_attach_ifp() function returns. 207 */ 208 struct usbnet_mii { 209 int un_mii_flags; 210 int un_mii_capmask; 211 int un_mii_phyloc; 212 int un_mii_offset; 213 }; 214 215 #define USBNET_MII_DECL(name, capmask, loc, off, flags) \ 216 struct usbnet_mii name = { \ 217 .un_mii_capmask = capmask, \ 218 .un_mii_phyloc = loc, \ 219 .un_mii_offset = off, \ 220 .un_mii_flags = flags, \ 221 } 222 #define USBNET_MII_DECL_DEFAULT(name) \ 223 USBNET_MII_DECL(name, 0xffffffff, MII_PHY_ANY, MII_OFFSET_ANY, 0) 224 225 /* 226 * Generic USB ethernet structure. Use this as ifp->if_softc and set as 227 * device_private() in attach unless already using struct usbnet here. 228 * 229 * Devices without MII should call usbnet_attach_ifp() with have_mii set 230 * to true, and should ensure that the un_statchg_cb callback sets the 231 * un_link member. Devices without MII have this forced to true. 232 */ 233 struct usbnet_private; 234 struct usbnet { 235 /* 236 * This section should be filled in before calling 237 * usbnet_attach(). 238 */ 239 void *un_sc; /* real softc */ 240 device_t un_dev; 241 struct usbd_interface *un_iface; 242 struct usbd_device *un_udev; 243 const struct usbnet_ops *un_ops; 244 struct usbnet_intr *un_intr; 245 246 /* Inputs for rx/tx chain control. */ 247 unsigned un_rx_bufsz; 248 unsigned un_tx_bufsz; 249 unsigned un_rx_list_cnt; 250 unsigned un_tx_list_cnt; 251 int un_rx_xfer_flags; 252 int un_tx_xfer_flags; 253 254 /* 255 * This section should be filled in before calling 256 * usbnet_attach_ifp(). 257 */ 258 uByte un_ed[USBNET_ENDPT_MAX]; 259 260 /* MII specific. Not used without MII. */ 261 int un_phyno; 262 /* Ethernet specific. All zeroes indicates non-Ethernet. */ 263 uint8_t un_eaddr[ETHER_ADDR_LEN]; 264 265 /* 266 * This section is for driver to use, not touched by usbnet. 267 */ 268 unsigned un_flags; 269 270 /* 271 * This section is private to usbnet. Don't touch. 272 */ 273 struct usbnet_private *un_pri; 274 }; 275 276 /* Various accessors. */ 277 278 void usbnet_set_link(struct usbnet *, bool); 279 280 struct ifnet *usbnet_ifp(struct usbnet *); 281 struct ethercom *usbnet_ec(struct usbnet *); 282 struct mii_data *usbnet_mii(struct usbnet *); 283 krndsource_t *usbnet_rndsrc(struct usbnet *); 284 void *usbnet_softc(struct usbnet *); 285 286 bool usbnet_havelink(struct usbnet *); 287 bool usbnet_isdying(struct usbnet *); 288 289 /* 290 * Endpoint / rx/tx chain management: 291 * 292 * 1. usbnet_attach() initialises usbnet and allocates rx and tx chains 293 * 294 * 2. On if_init, usbnet: 295 * - calls uno_init to initialize hardware 296 * - open pipes 297 * - initialises the rx/tx chains for use 298 * - calls uno_mcast to program hardware multicast filter 299 * 300 * 3. On if_stop, usbnet: 301 * - stops pipes 302 * - calls uno_stop to stop hardware (unless we're detaching anyway) 303 * - cleans (not frees) rx/tx chains 304 * - closes pipes 305 * 306 * usbnet_detach() frees the rx/tx chains 307 * 308 * Setup un_ed[] with valid end points before calling usbnet_attach(). 309 */ 310 311 /* interrupt handling */ 312 void usbnet_enqueue(struct usbnet * const, uint8_t *, size_t, int, 313 uint32_t, int); 314 void usbnet_input(struct usbnet * const, uint8_t *, size_t); 315 316 /* autoconf */ 317 void usbnet_attach(struct usbnet *); 318 void usbnet_attach_ifp(struct usbnet *, unsigned, unsigned, 319 const struct usbnet_mii *); 320 int usbnet_detach(device_t, int); 321 int usbnet_activate(device_t, devact_t); 322 323 /* module hook up */ 324 325 #ifdef _MODULE 326 #define USBNET_INIT(name) \ 327 error = config_init_component(cfdriver_ioconf_##name, \ 328 cfattach_ioconf_##name, cfdata_ioconf_##name); 329 #define USBNET_FINI(name) \ 330 error = config_fini_component(cfdriver_ioconf_##name, \ 331 cfattach_ioconf_##name, cfdata_ioconf_##name); 332 #else 333 #define USBNET_INIT(name) 334 #define USBNET_FINI(name) 335 #endif 336 337 #define USBNET_MODULE(name) \ 338 \ 339 MODULE(MODULE_CLASS_DRIVER, if_##name, "usbnet"); \ 340 \ 341 static int \ 342 if_##name##_modcmd(modcmd_t cmd, void *aux) \ 343 { \ 344 int error = 0; \ 345 \ 346 switch (cmd) { \ 347 case MODULE_CMD_INIT: \ 348 USBNET_INIT(name) \ 349 return error; \ 350 case MODULE_CMD_FINI: \ 351 USBNET_FINI(name) \ 352 return error; \ 353 default: \ 354 return ENOTTY; \ 355 } \ 356 } 357 358 #endif /* _DEV_USB_USBNET_H */ 359