path: root/drivers/usb/host/ehci.h

// SPDX-License-Identifier: GPL-2.0+
/*
 * Copyright (c) 2001-2002 by David Brownell
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 2 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#ifndef __LINUX_EHCI_HCD_H
#define __LINUX_EHCI_HCD_H

/* definitions used for the EHCI driver */

/*
 * __hc32 and __hc16 are "Host Controller" types, they may be equivalent to
 * __leXX (normally) or __beXX (given EHCI_BIG_ENDIAN_DESC), depending on
 * the host controller implementation.
 *
 * To facilitate the strongest possible byte-order checking from "sparse"
 * and so on, we use __leXX unless that's not practical.
 */
#ifdef CONFIG_USB_EHCI_BIG_ENDIAN_DESC
typedef __u32 __bitwise __hc32;
typedef __u16 __bitwise __hc16;
#else
#define __hc32	__le32
#define __hc16	__le16
#endif

/* statistics can be kept for tuning/monitoring */
#ifdef CONFIG_DYNAMIC_DEBUG
#define EHCI_STATS
#endif

struct ehci_stats {
	/* irq usage */
	unsigned long		normal;
	unsigned long		error;
	unsigned long		iaa;
	unsigned long		lost_iaa;

	/* termination of urbs from core */
	unsigned long		complete;
	unsigned long		unlink;
};

/*
 * Scheduling and budgeting information for periodic transfers, for both
 * high-speed devices and full/low-speed devices lying behind a TT.
 */
struct ehci_per_sched {
	struct usb_device	*udev;		/* access to the TT */
	struct usb_host_endpoint *ep;
	struct list_head	ps_list;	/* node on ehci_tt's ps_list */
	u16			tt_usecs;	/* time on the FS/LS bus */
	u16			cs_mask;	/* C-mask and S-mask bytes */
	u16			period;		/* actual period in frames */
	u16			phase;		/* actual phase, frame part */
	u8			bw_phase;	/* same, for bandwidth
						   reservation */
	u8			phase_uf;	/* uframe part of the phase */
	u8			usecs, c_usecs;	/* times on the HS bus */
	u8			bw_uperiod;	/* period in microframes, for
						   bandwidth reservation */
	u8			bw_period;	/* same, in frames */
};
#define NO_FRAME	29999			/* frame not assigned yet */

/* ehci_hcd->lock guards shared data against other CPUs:
 *   ehci_hcd:	async, unlink, periodic (and shadow), ...
 *   usb_host_endpoint: hcpriv
 *   ehci_qh:	qh_next, qtd_list
 *   ehci_qtd:	qtd_list
 *
 * Also, hold this lock when talking to HC registers or
 * when updating hw_* fields in shared qh/qtd/... structures.
 */

#define	EHCI_MAX_ROOT_PORTS	15		/* see HCS_N_PORTS */

/*
 * ehci_rh_state values of EHCI_RH_RUNNING or above mean that the
 * controller may be doing DMA.  Lower values mean there's no DMA.
 */
enum ehci_rh_state {
	EHCI_RH_HALTED,
	EHCI_RH_SUSPENDED,
	EHCI_RH_RUNNING,
	EHCI_RH_STOPPING
};

/*
 * Timer events, ordered by increasing delay length.
 * Always update event_delays_ns[] and event_handlers[] (defined in
 * ehci-timer.c) in parallel with this list.
 */
enum ehci_hrtimer_event {
	EHCI_HRTIMER_POLL_ASS,		/* Poll for async schedule off */
	EHCI_HRTIMER_POLL_PSS,		/* Poll for periodic schedule off */
	EHCI_HRTIMER_POLL_DEAD,		/* Wait for dead controller to stop */
	EHCI_HRTIMER_UNLINK_INTR,	/* Wait for interrupt QH unlink */
	EHCI_HRTIMER_FREE_ITDS,		/* Wait for unused iTDs and siTDs */
	EHCI_HRTIMER_ACTIVE_UNLINK,	/* Wait while unlinking an active QH */
	EHCI_HRTIMER_START_UNLINK_INTR, /* Unlink empty interrupt QHs */
	EHCI_HRTIMER_ASYNC_UNLINKS,	/* Unlink empty async QHs */
	EHCI_HRTIMER_IAA_WATCHDOG,	/* Handle lost IAA interrupts */
	EHCI_HRTIMER_DISABLE_PERIODIC,	/* Wait to disable periodic sched */
	EHCI_HRTIMER_DISABLE_ASYNC,	/* Wait to disable async sched */
	EHCI_HRTIMER_IO_WATCHDOG,	/* Check for missing IRQs */
	EHCI_HRTIMER_NUM_EVENTS		/* Must come last */
};
#define EHCI_HRTIMER_NO_EVENT	99

struct ehci_hcd {			/* one per controller */
	/* timing support */
	enum ehci_hrtimer_event	next_hrtimer_event;
	unsigned		enabled_hrtimer_events;
	ktime_t			hr_timeouts[EHCI_HRTIMER_NUM_EVENTS];
	struct hrtimer		hrtimer;

	int			PSS_poll_count;
	int			ASS_poll_count;
	int			died_poll_count;

	/* glue to PCI and HCD framework */
	struct ehci_caps __iomem *caps;
	struct ehci_regs __iomem *regs;
	struct ehci_dbg_port __iomem *debug;

	__u32			hcs_params;	/* cached register copy */
	spinlock_t		lock;
	enum ehci_rh_state	rh_state;

	/* general schedule support */
	bool			scanning:1;
	bool			need_rescan:1;
	bool			intr_unlinking:1;
	bool			iaa_in_progress:1;
	bool			async_unlinking:1;
	bool			shutdown:1;
	struct ehci_qh		*qh_scan_next;

	/* async schedule support */
	struct ehci_qh		*async;
	struct ehci_qh		*dummy;		/* For AMD quirk use */
	struct list_head	async_unlink;
	struct list_head	async_idle;
	unsigned		async_unlink_cycle;
	unsigned		async_count;	/* async activity count */
	__hc32			old_current;	/* Test for QH becoming */
	__hc32			old_token;	/*  inactive during unlink */

	/* periodic schedule support */
#define	DEFAULT_I_TDPS		1024		/* some HCs can do less */
	unsigned		periodic_size;
	__hc32			*periodic;	/* hw periodic table */
	dma_addr_t		periodic_dma;
	struct list_head	intr_qh_list;
	unsigned		i_thresh;	/* uframes HC might cache */

	union ehci_shadow	*pshadow;	/* mirror hw periodic table */
	struct list_head	intr_unlink_wait;
	struct list_head	intr_unlink;
	unsigned		intr_unlink_wait_cycle;
	unsigned		intr_unlink_cycle;
	unsigned		now_frame;	/* frame from HC hardware */
	unsigned		last_iso_frame;	/* last frame scanned for iso */
	unsigned		intr_count;	/* intr activity count */
	unsigned		isoc_count;	/* isoc activity count */
	unsigned		periodic_count;	/* periodic activity count */
	unsigned		uframe_periodic_max; /* max periodic time per uframe */


	/* list of itds & sitds completed while now_frame was still active */
	struct list_head	cached_itd_list;
	struct ehci_itd		*last_itd_to_free;
	struct list_head	cached_sitd_list;
	struct ehci_sitd	*last_sitd_to_free;

	/* per root hub port */
	unsigned long		reset_done[EHCI_MAX_ROOT_PORTS];

	/* bit vectors (one bit per port) */
	unsigned long		bus_suspended;		/* which ports were
			already suspended at the start of a bus suspend */
	unsigned long		companion_ports;	/* which ports are
			dedicated to the companion controller */
	unsigned long		owned_ports;		/* which ports are
			owned by the companion during a bus suspend */
	unsigned long		port_c_suspend;		/* which ports have
			the change-suspend feature turned on */
	unsigned long		suspended_ports;	/* which ports are
			suspended */
	unsigned long		resuming_ports;		/* which ports have
			started to resume */

	/* per-HC memory pools (could be per-bus, but ...) */
	struct dma_pool		*qh_pool;	/* qh per active urb */
	struct dma_pool		*qtd_pool;	/* one or more per qh */
	struct dma_pool		*itd_pool;	/* itd per iso urb */
	struct dma_pool		*sitd_pool;	/* sitd per split iso urb */

	unsigned		random_frame;
	unsigned long		next_statechange;
	ktime_