xref: /src/sys/dev/usb/usbdivar.h

/*	$NetBSD: usbdivar.h,v 1.109.2.5 2014/12/03 12:52:07 skrll Exp $	*/

/*
 * Copyright (c) 1998, 2012 The NetBSD Foundation, Inc.
 * All rights reserved.
 *
 * This code is derived from software contributed to The NetBSD Foundation
 * by Lennart Augustsson (lennart (at) augustsson.net) at
 * Carlstedt Research & Technology and Matthew R. Green (mrg (at) eterna.com.au).
 *
 * 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.
 *
 * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
 * ``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 FOUNDATION OR CONTRIBUTORS
 * 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.
 */

/*
 * Discussion about locking in the USB code:
 *
 * The host controller presents one lock at IPL_SOFTUSB (aka IPL_SOFTNET).
 *
 * List of hardware interface methods, and whether the lock is held
 * when each is called by this module:
 *
 *	BUS METHOD		LOCK  NOTES
 *	----------------------- -------	-------------------------
 *	open_pipe		-	might want to take lock?
 *	soft_intr		x
 *	do_poll			-	might want to take lock?
 *	allocx			-
 *	freex			-
 *	get_lock 		-	Called at attach time
 *	new_device
 *
 *	PIPE METHOD		LOCK  NOTES
 *	----------------------- -------	-------------------------
 *	transfer		-
 *	start			-	might want to take lock?
 *	abort			x
 *	close			x
 *	cleartoggle		-
 *	done			x
 *
 * The above semantics are likely to change.  Little performance
 * evaluation has been done on this code and the locking strategy.
 *
 * USB functions known to expect the lock taken include (this list is
 * probably not exhaustive):
 *    usb_transfer_complete()
 *    usb_insert_transfer()
 *    usb_start_next()
 *
 */

#include <sys/callout.h>
#include <sys/mutex.h>
#include <sys/bus.h>

/* From usb_mem.h */
struct usb_dma_block;
typedef struct {
	struct usb_dma_block *udma_block;
	u_int udma_offs;
} usb_dma_t;

struct usbd_xfer;
struct usbd_pipe;
struct usbd_port;

struct usbd_endpoint {
	usb_endpoint_descriptor_t *ue_edesc;
	int			ue_refcnt;
	int			ue_toggle;
};

struct usbd_bus_methods {
	usbd_status	      (*ubm_open)(struct usbd_pipe *pipe);
	void		      (*ubm_softint)(void *);
	void		      (*ubm_dopoll)(struct usbd_bus *);
	struct usbd_xfer *    (*ubm_allocx)(struct usbd_bus *);
	void		      (*ubm_freex)(struct usbd_bus *, struct usbd_xfer *);
	void		      (*ubm_getlock)(struct usbd_bus *, kmutex_t **);
	usbd_status	      (*ubm_newdev)(device_t, usbd_bus_handle, int,
					    int, int, struct usbd_port *);
};

struct usbd_pipe_methods {
	usbd_status	      (*upm_transfer)(usbd_xfer_handle);
	usbd_status	      (*upm_start)(usbd_xfer_handle);
	void		      (*upm_abort)(usbd_xfer_handle);
	void		      (*upm_close)(usbd_pipe_handle);
	void		      (*upm_cleartoggle)(usbd_pipe_handle);
	void		      (*upm_done)(usbd_xfer_handle);
};

#if 0 /* notyet */
struct usbd_tt {
	struct usbd_hub	       *hub;
};
#endif

struct usbd_port {
	usb_port_status_t	up_status;
	uint16_t		up_power;	/* mA of current on port */
	uint8_t			up_portno;
	uint8_t			up_restartcnt;
#define USBD_RESTART_MAX 5
	uint8_t			up_reattach;
	struct usbd_device     *up_dev;		/* Connected device */
	struct usbd_device     *up_parent;	/* The ports hub */
#if 0
	struct usbd_tt	       *up_tt;	/* Transaction translator (if any) */
#endif
};

struct usbd_hub {
	usbd_status	      (*uh_explore)(usbd_device_handle hub);
	void		       *uh_hubsoftc;
	usb_hub_descriptor_t	uh_hubdesc;
	struct usbd_port        uh_ports[1];
};

/*****/

struct usbd_bus {
	/* Filled by HC driver */
	void			*ub_hcpriv;
	const struct usbd_bus_methods *ub_methods;
	uint32_t		ub_pipesize;	/* size of a pipe struct */
	/* Filled by usb driver */
	kmutex_t		*ub_lock;
	struct usbd_device      *ub_roothub;
	usbd_device_handle	ub_devices[USB_MAX_DEVICES];
	kcondvar_t              ub_needsexplore_cv;
	char			ub_needsexplore;/* a hub a signalled a change */
	char			ub_usepolling;
	device_t		ub_usbctl;
	struct usb_device_stats	ub_stats;
	int			ub_revision;	/* USB revision */
#define USBREV_UNKNOWN	0
#define USBREV_PRE_1_0	1
#define USBREV_1_0	2
#define USBREV_1_1	3
#define USBREV_2_0	4
#define USBREV_3_0	5
#define USBREV_STR { "unknown", "pre 1.0", "1.0", "1.1", "2.0", "3.0" }

	void		       *ub_soft; /* soft interrupt cookie */

	bool			ub_usedma;		/* Does this HC support DMA */
	int			ub_dmaflags;
	bus_dma_tag_t		ub_dmatag;	/* DMA tag */
};

struct usbd_device {
	struct usbd_bus	       *ud_bus;		/* our controller */
	struct usbd_pipe       *ud_pipe0;	/* pipe 0 */
	uint8_t			ud_addr;	/* device addess */
	uint8_t			ud_config;	/* current configuration # */
	uint8_t			ud_depth;	/* distance from root hub */
	uint8_t			ud_speed;	/* low/full/high speed */
	uint8_t			ud_selfpowered;	/* flag for self powered */
	uint16_t		ud_power;	/* mA the device uses */
	int16_t			ud_langid;	/* language for strings */
#define USBD_NOLANG (-1)
	usb_event_cookie_t	ud_cookie;	/* unique connection id */
	struct usbd_port       *ud_powersrc;	/* upstream hub port, or 0 */
	struct usbd_device     *ud_myhub;	/* upstream hub */
	struct usbd_port       *ud_myhsport;	/* closest high speed port */
	struct usbd_endpoint	ud_ep0;		/* for pipe 0 */
	usb_endpoint_descriptor_t ud_ep0desc;	/* for pipe 0 */
	struct usbd_interface  *ud_ifaces;	/* array of all interfaces */
	usb_device_descriptor_t ud_ddesc;	/* device descriptor */
	usb_config_descriptor_t *ud_cdesc;	/* full config descr */
	const struct usbd_quirks     *ud_quirks;/* device quirks, always set */
	struct usbd_hub	       *ud_hub;		/* only if this is a hub */
	int			ud_subdevlen;	/* array length of following */
	device_t	       *ud_subdevs;	/* sub-devices */
	int			ud_nifaces_claimed; /* number of ifaces in use */
	void		       *ud_hcpriv;
};

struct usbd_interface {
	struct usbd_device     *ui_dev;
	usb_interface_descriptor_t *ui_idesc;
	int			ui_index;
	int			ui_altindex;
	struct usbd_endpoint   *ui_endpoints;
	void		       *ui_priv;
	LIST_HEAD(, usbd_pipe)	ui_pipes;
};

struct usbd_pipe {
	struct usbd_interface  *up_iface;
	struct usbd_device     *up_dev;
	struct usbd_endpoint   *up_endpoint;
	int			up_refcnt;
	char			up_running;
	char			up_aborting;
	SIMPLEQ_HEAD(, usbd_xfer) up_queue;
	LIST_ENTRY(usbd_pipe)	up_next;
	struct usb_task		up_async_task;

	usbd_xfer_handle	up_intrxfer; /* used for repeating requests */
	char			up_repeat;
	int			up_interval;
	uint8_t			up_flags;

	/* Filled by HC driver. */
	const struct usbd_pipe_methods *up_methods;
};

struct usbd_xfer {
	struct usbd_pipe       *ux_pipe;
	void		       *ux_priv;
	void		       *ux_buffer;
	kcondvar_t		ux_cv;
	uint32_t		ux_length;
	uint32_t		ux_actlen;
	uint16_t		ux_flags;
	uint32_t		ux_timeout;
	usbd_status		ux_status;
	usbd_callback		ux_callback;
	volatile uint8_t	ux_done;
	uint8_t			ux_state;	/* used for DIAGNOSTIC */
#define XFER_FREE 0x46
#define XFER_BUSY 0x55
#define XFER_ONQU 0x9e

	/* For control pipe */
	usb_device_request_t	ux_request;

	/* For isoc */
	uint16_t		*ux_frlengths;
	int			ux_nframes;

	/* For memory allocation */
	struct usbd_device     *ux_dev;
	usb_dma_t		ux_dmabuf;
	void		       *ux_buf;
	uint32_t		ux_bufsize;

	uint8_t			ux_rqflags;
#define URQ_REQUEST	0x01
#define URQ_AUTO_BUFFER	0x10

	SIMPLEQ_ENTRY(usbd_xfer) ux_next;

	void		       *ux_hcpriv;	/* private use by the HC driver */
	uint8_t			ux_hcflags;	/* private use by the HC driver */
#define UXFER_ABORTING	0x01	/* xfer is aborting. */
#define UXFER_ABORTWAIT	0x02	/* abort completion is being awaited. */
	kcondvar_t		ux_hccv;	/* private use by the HC driver */

	struct callout		ux_callout;
};

void usbd_init(void);
void usbd_finish(void);

#if defined(USB_DEBUG) || defined(EHCI_DEBUG) || defined(OHCI_DEBUG)
void usbd_dump_iface(struct usbd_interface *iface);
void usbd_dump_device(struct usbd_device *dev);
void usbd_dump_endpoint(struct usbd_endpoint *endp);
void usbd_dump_queue(usbd_pipe_handle pipe);
void usbd_dump_pipe(usbd_pipe_handle pipe);
#endif

/* Routines from usb_subr.c */
int		usbctlprint(void *, const char *);
void		usb_delay_ms_locked(usbd_bus_handle, u_int, kmutex_t *);
void		usb_delay_ms(usbd_bus_handle, u_int);
void		usbd_delay_ms_locked(usbd_device_handle, u_int, kmutex_t *);
void		usbd_delay_ms(usbd_device_handle, u_int);
usbd_status	usbd_reset_port(usbd_device_handle, int, usb_port_status_t *);
usbd_status	usbd_setup_pipe(usbd_device_handle dev,
				usbd_interface_handle iface,
				struct usbd_endpoint *, int,
				usbd_pipe_handle *pipe);
usbd_status	usbd_setup_pipe_flags(usbd_device_handle dev,
				      usbd_interface_handle iface,
				      struct usbd_endpoint *, int,
				      usbd_pipe_handle *pipe,
				      uint8_t flags);
usbd_status	usbd_new_device(device_t, usbd_bus_handle, int, int, int,
				struct usbd_port *);
usbd_status	usbd_reattach_device(device_t, usbd_device_handle,
				     int, const int *);

void		usbd_remove_device(usbd_device_handle, struct usbd_port *);
int		usbd_printBCD(char *, size_t, int);
usbd_status	usbd_fill_iface_data(usbd_device_handle, int, int);
void		usb_free_device(usbd_device_handle);

usbd_status	usb_insert_transfer(usbd_xfer_handle);
void		usb_transfer_complete(usbd_xfer_handle);
int		usb_disconnect_port(struct usbd_port *, device_t, int);

void		usbd_kill_pipe(usbd_pipe_handle);
usbd_status	usbd_attach_roothub(device_t, usbd_device_handle);
usbd_status	usbd_probe_and_attach(device_t, usbd_device_handle, int, int);
usbd_status	usbd_get_initial_ddesc(usbd_device_handle,
				       usb_device_descriptor_t *);

/* Routines from usb.c */
void		usb_needs_explore(usbd_device_handle);
void		usb_needs_reattach(usbd_device_handle);
void		usb_schedsoftintr(struct usbd_bus *);

/*
 * These macros reflect the current locking scheme.  They might change.
 */

#define usbd_lock_pipe(p)	mutex_enter((p)->up_dev->ud_bus->ub_lock)
#define usbd_unlock_pipe(p)	mutex_exit((p)->up_dev->ud_bus->ub_lock)