/* $NetBSD: usbnet.h,v 1.14.2.3 2019/09/13 06:51:58 martin Exp $ */
/*
* Copyright (c) 2019 Matthew R. Green
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. The name of the author may not be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
#ifndef _DEV_USB_USBNET_H
#define _DEV_USB_USBNET_H
/*
* Common code/data shared by all USB ethernet drivers (using these routines.)
*
* This framework provides the following features for USB ethernet drivers:
*
* - USB endpoint pipe handling
* - rx and tx chain handling
* - generic handlers or support for several struct ifnet callbacks
* - MII bus locking
* - interrupt handling
* - partial autoconf handling
*
* Consumers of this interface need to:
*
* - replace most softc members with "struct usbnet" usage, in particular
* use usbnet pointer for ifp->if_softc, and device_private (real softc
* can be stored in un_sc member)
* - use MII bus lock / access methods
* - usbnet_attach() to initialise and allocate rx/tx chains
* - usbnet_attach_ifp() to attach the interface, and either ether_ifattach()
* for ethernet devices, or if_alloc_sadl()/bpf_attach() pair otherwise.
* - usbnet_detach() to clean them up
* - usbnet_activate() for autoconf
* - interface ioctl and start have direct frontends with callbacks for
* device specific handling:
* - ioctl can use either a device-specific override (useful for special
* cases), but provides a normal handler with callback to handle
* ENETRESET conditions that should be sufficient for most users
* - start uses usbnet send callback
* - interface init and stop have helper functions
* - device specific init should use usbnet_init_rx_tx() to open pipes
* to the device and setup the rx/tx chains for use after any device
* specific setup
* - usbnet_stop() must be called with the un_lock held, and will
* call the device-specific usbnet stop callback, which enables the
* standard init calls stop idiom.
* - interrupt handling:
* - for rx, usbnet_init_rx_tx() will enable the receive pipes and
* call the rx_loop callback to handle device specific processing of
* packets, which can use usbnet_enqueue() to provide data to the
* higher layers
* - for tx, usbnet_start (if_start) will pull entries out of the
* transmit queue and use the send callback for the given mbuf.
* the usb callback will use usbnet_txeof() for the transmit
* completion function (internal to usbnet)
* - there is special interrupt pipe handling
* - timer/tick:
* - the uno_tick callback will be called once a second if present.
*/
#include <sys/device.h>
#include <sys/mbuf.h>
#include <sys/rndsource.h>
#include <sys/mutex.h>
#include <sys/module.h>
#include <sys/sysctl.h>
#include <net/bpf.h>
#include <net/if.h>
#include <net/if_arp.h>
#include <net/if_dl.h>
#include <net/if_ether.h>
#include <net/if_media.h>
#include <dev/mii/mii.h>
#include <dev/mii/miivar.h>
#include <dev/usb/usb.h>
#include <dev/usb/usbdi.h>
#include <dev/usb/usbdivar.h>
#include <dev/usb/usbdi_util.h>
#include <dev/usb/usbdevs.h>
/*
* Per-transfer data.
*
* Front-end must set un_rx_list_cnt and un_tx_list_cnt before
* calling usbnet_attach(), and then call usbnet_rx_tx_init()
* which will allocate the chain arrays, and must be NULL to
* indicate the first call.
*/
struct usbnet;
struct usbnet_chain {
struct usbnet *unc_un;
struct usbd_xfer *unc_xfer;
uint8_t *unc_buf;
};
/*
* Extend this as necessary. axe(4) claims to want 6 total, but
* does not implement them.
*/
enum usbnet_ep {
USBNET_ENDPT_RX,
USBNET_ENDPT_TX,
USBNET_ENDPT_INTR,
USBNET_ENDPT_MAX,
};
/* Interface stop callback. */
typedef void (*usbnet_stop_cb)(struct ifnet *, int);
/* Interface ioctl callback. */
typedef int (*usbnet_ioctl_cb)(struct ifnet *, u_long, void *);
/* Initialise device callback. */
typedef int (*usbnet_init_cb)(struct ifnet *);
/* MII read register callback. */
typedef int (*usbnet_mii_read_reg_cb)(struct usbnet *, int reg,
int phy, uint16_t *val);
/* MII write register callback. */
typedef int (*usbnet_mii_write_reg_cb)(struct usbnet *, int reg,
int phy, uint16_t val);
/* MII status change callback. */
typedef void (*usbnet_mii_statchg_cb)(struct ifnet *);
/* Prepare packet to send callback, returns length. */
typedef unsigned (*usbnet_tx_prepare_cb)(struct usbnet *, struct mbuf *,
struct usbnet_chain *);
/* Receive some packets callback. */
typedef void (*usbnet_rx_loop_cb)(struct usbnet *, struct usbnet_chain *,
uint32_t);
/* Tick callback. */
typedef void (*usbnet_tick_cb)(struct usbnet *);
/* Interrupt pipe callback. */
typedef void (*usbnet_intr_cb)(struct usbnet *, usbd_status);
struct usbnet_ops {
usbnet_stop_cb uno_stop;
usbnet_ioctl_cb uno_ioctl;
usbnet_ioctl_cb uno_override_ioctl;
usbnet_init_cb uno_init;
usbnet_mii_read_reg_cb uno_read_reg;
usbnet_mii_write_reg_cb uno_write_reg;
usbnet_mii_statchg_cb uno_statchg;
usbnet_tx_prepare_cb uno_tx_prepare;
usbnet_rx_loop_cb uno_rx_loop;
usbnet_tick_cb uno_tick;
usbnet_intr_cb uno_intr;
};
/*
* USB interrupt pipe support. Use this if usbd_open_pipe_intr() should
* be used for the interrupt pipe.
*/
struct usbnet_intr {
/*
* Point un_intr to this structure to use usbd_open_pipe_intr() not
* usbd_open_pipe() for USBNET_ENDPT_INTR, with this buffer, size,
* and interval.
*/
void *uni_buf;
unsigned uni_bufsz;
unsigned uni_interval;
};
/*
* Structure to setup MII. Use the USBNET_MII_DECL_DEFAULT() macro for
* sane default. Pass a copy to usbnet_attach_ifp(). Not used
* after the usbnet_attach_ifp() function returns.
*/
struct usbnet_mii {
int un_mii_flags;
int un_mii_capmask;
int un_mii_phyloc;
int un_mii_offset;
};
#define UBSNET_MII_DECL(name, capmask, loc, off, flags) \
struct usbnet_mii name = { \
.un_mii_capmask = capmask, \
.un_mii_phyloc = loc, \
.un_mii_offset = off, \
.un_mii_flags = flags, \
}
#define USBNET_MII_DECL_DEFAULT(name) \
UBSNET_MII_DECL(name, 0xffffffff, MII_PHY_ANY, MII_OFFSET_ANY, 0)
/*
* Generic USB ethernet structure. Use this as ifp->if_softc and set as
* device_private() in attach unless already using struct usbnet here.
*
* Devices without MII should call usbnet_attach_ifp() with have_mii set
* to true, and should ensure that the un_statchg_cb callback sets the
* un_link member. Devices without MII have this forced to true.
*/
struct usbnet_private;
struct usbnet {
/*
* This section should be filled in before calling
* usbnet_attach().
*/
void *un_sc; /* real softc */
device_t un_dev;
struct usbd_interface *un_iface;
struct usbd_device *un_udev;
struct usbnet_ops *un_ops;
struct usbnet_intr *un_intr;
/* Inputs for rx/tx chain control. */
unsigned un_rx_bufsz;
unsigned un_tx_bufsz;
unsigned un_rx_list_cnt;
unsigned un_tx_list_cnt;
int un_rx_xfer_flags;
int un_tx_xfer_flags;
/*
* This section should be filled in before calling
* usbnet_attach_ifp().
*/
enum usbnet_ep un_ed[USBNET_ENDPT_MAX];
/* MII specific. Not used without MII. */
int un_phyno;
/* Ethernet specific. All zeroes indicates non-Ethernet. */
uint8_t un_eaddr[ETHER_ADDR_LEN];
/*
* This section is for driver to use, not touched by usbnet.
*/
unsigned un_flags;
/*
* This section is private to usbnet. Don't touch.
*/
struct usbnet_private *un_pri;
/*
* NetBSD 9.x specific portion. Not needed afterwards.
*
* This structure will be passed to sysctl_teardown() in
* usbnet_detach() if it is not NULL.
*/
struct sysctllog *un_sysctl_log;
};
/* Various accessors. */
void usbnet_set_link(struct usbnet *, bool);
void usbnet_set_dying(struct usbnet *, bool);
struct ifnet *usbnet_ifp(struct usbnet *);
struct ethercom *usbnet_ec(struct usbnet *);
struct mii_data *usbnet_mii(struct usbnet *);
krndsource_t *usbnet_rndsrc(struct usbnet *);
void *usbnet_softc(struct usbnet *);
bool usbnet_havelink(struct usbnet *);
bool usbnet_isdying(struct usbnet *);
/*
* Locking. Note that the isowned() are implemented here so that
* empty-KASSERT() causes them to be elided for non-DIAG builds.
*/
void usbnet_lock(struct usbnet *);
void usbnet_unlock(struct usbnet *);
kmutex_t *usbnet_mutex(struct usbnet *);
static __inline__ void
usbnet_isowned(struct usbnet *un)
{
KASSERT(mutex_owned(usbnet_mutex(un)));
}
void usbnet_lock_rx(struct usbnet *);
void usbnet_unlock_rx(struct usbnet *);
kmutex_t *usbnet_mutex_rx(struct usbnet *);
static __inline__ void
usbnet_isowned_rx(struct usbnet *un)
{
KASSERT(mutex_owned(usbnet_mutex_rx(un)));
}
void usbnet_lock_tx(struct usbnet *);
void usbnet_unlock_tx(struct usbnet *);
kmutex_t *usbnet_mutex_tx(struct usbnet *);
static __inline__ void
usbnet_isowned_tx(struct usbnet *un)
{
KASSERT(mutex_owned(usbnet_mutex_tx(un)));
}
/*
* Endpoint / rx/tx chain management:
*
* usbnet_attach() initialises usbnet and allocates rx and tx chains
* usbnet_init_rx_tx() open pipes, initialises the rx/tx chains for use
* usbnet_stop() stops pipes, cleans (not frees) rx/tx chains, locked
* version assumes un_lock is held
* usbnet_detach() frees the rx/tx chains
*
* Setup un_ed[] with valid end points before calling usbnet_attach().
* Call usbnet_init_rx_tx() to initialise pipes, which will be open
* upon success.
*/
int usbnet_init_rx_tx(struct usbnet * const);
/* MII. */
void usbnet_lock_mii(struct usbnet *);
void usbnet_lock_mii_un_locked(struct usbnet *);
void usbnet_unlock_mii(struct usbnet *);
void usbnet_unlock_mii_un_locked(struct usbnet *);
kmutex_t *usbnet_mutex_mii(struct usbnet *);
static __inline__ void
usbnet_isowned_mii(struct usbnet *un)
{
KASSERT(mutex_owned(usbnet_mutex_mii(un)));
}
int usbnet_mii_readreg(device_t, int, int, uint16_t *);
int usbnet_mii_writereg(device_t, int, int, uint16_t);
void usbnet_mii_statchg(struct ifnet *);
/* interrupt handling */
void usbnet_enqueue(struct usbnet * const, uint8_t *, size_t, int,
uint32_t, int);
void usbnet_input(struct usbnet * const, uint8_t *, size_t);
/* autoconf */
void usbnet_attach(struct usbnet *un, const char *);
void usbnet_attach_ifp(struct usbnet *, unsigned, unsigned,
const struct usbnet_mii *);
int usbnet_detach(device_t, int);
int usbnet_activate(device_t, devact_t);
/* stop backend */
void usbnet_stop(struct usbnet *, struct ifnet *, int);
/* module hook up */
#ifdef _MODULE
#define USENET_INIT(name) \
error = config_init_component(cfdriver_ioconf_##name, \
cfattach_ioconf_##name, cfdata_ioconf_##name);
#define USENET_FINI(name) \
error = config_fini_component(cfdriver_ioconf_##name, \
cfattach_ioconf_##name, cfdata_ioconf_##name);
#else
#define USENET_INIT(name)
#define USENET_FINI(name)
#endif
#define USBNET_MODULE(name) \
\
MODULE(MODULE_CLASS_DRIVER, if_##name, "usbnet"); \
\
static int \
if_##name##_modcmd(modcmd_t cmd, void *aux) \
{ \
int error = 0; \
\
switch (cmd) { \
case MODULE_CMD_INIT: \
USENET_INIT(name) \
return error; \
case MODULE_CMD_FINI: \
USENET_FINI(name) \
return error; \
default: \
return ENOTTY; \
} \
}
#endif /* _DEV_USB_USBNET_H */