1 /* $NetBSD: usbnet.h,v 1.35 2022/08/22 08:37:16 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 -> usbnet un_mcastlock 161 * M -> usbnet un_miilock 162 * T -> usbnet un_txlock 163 * R -> usbnet un_rxlock 164 * n -> no locks held 165 * 166 * Note that the IFNET_LOCK **may not be held** for the ioctl commands 167 * SIOCADDMULTI/SIOCDELMULTI. These commands are only passed 168 * explicitly to uno_override_ioctl; for all other devices, they are 169 * handled by uno_mcast (also without IFNET_LOCK). 170 */ 171 struct usbnet_ops { 172 usbnet_stop_cb uno_stop; /* I */ 173 usbnet_ioctl_cb uno_ioctl; /* I */ 174 usbnet_ioctl_cb uno_override_ioctl; /* I (except mcast) */ 175 usbnet_mcast_cb uno_mcast; /* C */ 176 usbnet_init_cb uno_init; /* I */ 177 usbnet_mii_read_reg_cb uno_read_reg; /* M */ 178 usbnet_mii_write_reg_cb uno_write_reg; /* M */ 179 usbnet_mii_statchg_cb uno_statchg; /* M */ 180 usbnet_tx_prepare_cb uno_tx_prepare; /* T */ 181 usbnet_rx_loop_cb uno_rx_loop; /* R */ 182 usbnet_tick_cb uno_tick; /* n */ 183 usbnet_intr_cb uno_intr; /* n */ 184 }; 185 186 /* 187 * USB interrupt pipe support. Use this if usbd_open_pipe_intr() should 188 * be used for the interrupt pipe. 189 */ 190 struct usbnet_intr { 191 /* 192 * Point un_intr to this structure to use usbd_open_pipe_intr() not 193 * usbd_open_pipe() for USBNET_ENDPT_INTR, with this buffer, size, 194 * and interval. 195 */ 196 void *uni_buf; 197 unsigned uni_bufsz; 198 unsigned uni_interval; 199 }; 200 201 /* 202 * Structure to setup MII. Use the USBNET_MII_DECL_DEFAULT() macro for 203 * sane default. Pass a copy to usbnet_attach_ifp(). Not used 204 * after the usbnet_attach_ifp() function returns. 205 */ 206 struct usbnet_mii { 207 int un_mii_flags; 208 int un_mii_capmask; 209 int un_mii_phyloc; 210 int un_mii_offset; 211 }; 212 213 #define USBNET_MII_DECL(name, capmask, loc, off, flags) \ 214 struct usbnet_mii name = { \ 215 .un_mii_capmask = capmask, \ 216 .un_mii_phyloc = loc, \ 217 .un_mii_offset = off, \ 218 .un_mii_flags = flags, \ 219 } 220 #define USBNET_MII_DECL_DEFAULT(name) \ 221 USBNET_MII_DECL(name, 0xffffffff, MII_PHY_ANY, MII_OFFSET_ANY, 0) 222 223 /* 224 * Generic USB ethernet structure. Use this as ifp->if_softc and set as 225 * device_private() in attach unless already using struct usbnet here. 226 * 227 * Devices without MII should call usbnet_attach_ifp() with have_mii set 228 * to true, and should ensure that the un_statchg_cb callback sets the 229 * un_link member. Devices without MII have this forced to true. 230 */ 231 struct usbnet_private; 232 struct usbnet { 233 /* 234 * This section should be filled in before calling 235 * usbnet_attach(). 236 */ 237 void *un_sc; /* real softc */ 238 device_t un_dev; 239 struct usbd_interface *un_iface; 240 struct usbd_device *un_udev; 241 const struct usbnet_ops *un_ops; 242 struct usbnet_intr *un_intr; 243 244 /* Inputs for rx/tx chain control. */ 245 unsigned un_rx_bufsz; 246 unsigned un_tx_bufsz; 247 unsigned un_rx_list_cnt; 248 unsigned un_tx_list_cnt; 249 int un_rx_xfer_flags; 250 int un_tx_xfer_flags; 251 252 /* 253 * This section should be filled in before calling 254 * usbnet_attach_ifp(). 255 */ 256 uByte un_ed[USBNET_ENDPT_MAX]; 257 258 /* MII specific. Not used without MII. */ 259 int un_phyno; 260 /* Ethernet specific. All zeroes indicates non-Ethernet. */ 261 uint8_t un_eaddr[ETHER_ADDR_LEN]; 262 263 /* 264 * This section is for driver to use, not touched by usbnet. 265 */ 266 unsigned un_flags; 267 268 /* 269 * This section is private to usbnet. Don't touch. 270 */ 271 struct usbnet_private *un_pri; 272 }; 273 274 /* Various accessors. */ 275 276 void usbnet_set_link(struct usbnet *, bool); 277 278 struct ifnet *usbnet_ifp(struct usbnet *); 279 struct ethercom *usbnet_ec(struct usbnet *); 280 struct mii_data *usbnet_mii(struct usbnet *); 281 krndsource_t *usbnet_rndsrc(struct usbnet *); 282 void *usbnet_softc(struct usbnet *); 283 284 bool usbnet_havelink(struct usbnet *); 285 bool usbnet_isdying(struct usbnet *); 286 bool usbnet_ispromisc(struct usbnet *); 287 288 /* 289 * Endpoint / rx/tx chain management: 290 * 291 * 1. usbnet_attach() initialises usbnet and allocates rx and tx chains 292 * 293 * 2. On if_init, usbnet: 294 * - calls uno_init to initialize hardware 295 * - open pipes 296 * - initialises the rx/tx chains for use 297 * - calls uno_mcast to program hardware multicast filter 298 * 299 * 3. On if_stop, usbnet: 300 * - stops pipes 301 * - calls uno_stop to stop hardware (unless we're detaching anyway) 302 * - cleans (not frees) rx/tx chains 303 * - closes pipes 304 * 305 * usbnet_detach() frees the rx/tx chains 306 * 307 * Setup un_ed[] with valid end points before calling usbnet_attach(). 308 */ 309 310 /* interrupt handling */ 311 void usbnet_enqueue(struct usbnet * const, uint8_t *, size_t, int, 312 uint32_t, int); 313 void usbnet_input(struct usbnet * const, uint8_t *, size_t); 314 315 /* autoconf */ 316 void usbnet_attach(struct usbnet *); 317 void usbnet_attach_ifp(struct usbnet *, unsigned, unsigned, 318 const struct usbnet_mii *); 319 int usbnet_detach(device_t, int); 320 int usbnet_activate(device_t, devact_t); 321 322 /* module hook up */ 323 324 #ifdef _MODULE 325 #define USBNET_INIT(name) \ 326 error = config_init_component(cfdriver_ioconf_##name, \ 327 cfattach_ioconf_##name, cfdata_ioconf_##name); 328 #define USBNET_FINI(name) \ 329 error = config_fini_component(cfdriver_ioconf_##name, \ 330 cfattach_ioconf_##name, cfdata_ioconf_##name); 331 #else 332 #define USBNET_INIT(name) 333 #define USBNET_FINI(name) 334 #endif 335 336 #define USBNET_MODULE(name) \ 337 \ 338 MODULE(MODULE_CLASS_DRIVER, if_##name, "usbnet"); \ 339 \ 340 static int \ 341 if_##name##_modcmd(modcmd_t cmd, void *aux) \ 342 { \ 343 int error = 0; \ 344 \ 345 switch (cmd) { \ 346 case MODULE_CMD_INIT: \ 347 USBNET_INIT(name) \ 348 return error; \ 349 case MODULE_CMD_FINI: \ 350 USBNET_FINI(name) \ 351 return error; \ 352 default: \ 353 return ENOTTY; \ 354 } \ 355 } 356 357 #endif /* _DEV_USB_USBNET_H */ 358