1/* $FreeBSD$ */
2/*-
3 * Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 *    notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 *    notice, this list of conditions and the following disclaimer in the
12 *    documentation and/or other materials provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 * SUCH DAMAGE.
25 */
26
27/*
28 * Including this file is mandatory for all USB related c-files in the kernel.
29 */
30
31#ifndef _USB_CORE_H_
32#define	_USB_CORE_H_
33
34/*
35 * The following macro will tell if an USB transfer is currently
36 * receiving or transferring data.
37 */
38#define	USB_GET_DATA_ISREAD(xfer) ((xfer)->flags_int.usb_mode == \
39	USB_MODE_DEVICE ? (((xfer)->endpointno & UE_DIR_IN) ? 0 : 1) : \
40	(((xfer)->endpointno & UE_DIR_IN) ? 1 : 0))
41
42/* macros */
43
44#define	USB_BUS_LOCK(_b)		mtx_lock(&(_b)->bus_mtx)
45#define	USB_BUS_UNLOCK(_b)		mtx_unlock(&(_b)->bus_mtx)
46#define	USB_BUS_LOCK_ASSERT(_b, _t)	mtx_assert(&(_b)->bus_mtx, _t)
47#define	USB_BUS_SPIN_LOCK(_b)		mtx_lock_spin(&(_b)->bus_spin_lock)
48#define	USB_BUS_SPIN_UNLOCK(_b)		mtx_unlock_spin(&(_b)->bus_spin_lock)
49#define	USB_BUS_SPIN_LOCK_ASSERT(_b, _t)	mtx_assert(&(_b)->bus_spin_lock, _t)
50#define	USB_XFER_LOCK(_x)		mtx_lock((_x)->xroot->xfer_mtx)
51#define	USB_XFER_UNLOCK(_x)		mtx_unlock((_x)->xroot->xfer_mtx)
52#define	USB_XFER_LOCK_ASSERT(_x, _t)	mtx_assert((_x)->xroot->xfer_mtx, _t)
53
54/* helper for converting pointers to integers */
55#define	USB_P2U(ptr) \
56  (((const uint8_t *)(ptr)) - ((const uint8_t *)0))
57
58/* helper for computing offsets */
59#define	USB_ADD_BYTES(ptr,size) \
60  ((void *)(USB_P2U(ptr) + (size)))
61
62/* debug macro */
63#define	USB_ASSERT KASSERT
64
65/* structure prototypes */
66
67struct file;
68struct usb_bus;
69struct usb_device;
70struct usb_device_request;
71struct usb_page;
72struct usb_page_cache;
73struct usb_xfer;
74struct usb_xfer_root;
75struct usb_string_lang;
76
77/* typedefs */
78
79/* structures */
80
81/*
82 * The following structure defines a set of internal USB transfer
83 * flags.
84 */
85struct usb_xfer_flags_int {
86
87	enum usb_hc_mode usb_mode;	/* shadow copy of "udev->usb_mode" */
88	uint16_t control_rem;		/* remainder in bytes */
89
90	uint8_t	open:1;			/* set if USB pipe has been opened */
91	uint8_t	transferring:1;		/* set if an USB transfer is in
92					 * progress */
93	uint8_t	did_dma_delay:1;	/* set if we waited for HW DMA */
94	uint8_t	did_close:1;		/* set if we closed the USB transfer */
95	uint8_t	draining:1;		/* set if we are draining an USB
96					 * transfer */
97	uint8_t	started:1;		/* keeps track of started or stopped */
98	uint8_t	bandwidth_reclaimed:1;
99	uint8_t	control_xfr:1;		/* set if control transfer */
100	uint8_t	control_hdr:1;		/* set if control header should be
101					 * sent */
102	uint8_t	control_act:1;		/* set if control transfer is active */
103	uint8_t	control_stall:1;	/* set if control transfer should be stalled */
104	uint8_t control_did_data:1;	/* set if control DATA has been transferred */
105
106	uint8_t	short_frames_ok:1;	/* filtered version */
107	uint8_t	short_xfer_ok:1;	/* filtered version */
108#if USB_HAVE_BUSDMA
109	uint8_t	bdma_enable:1;		/* filtered version (only set if
110					 * hardware supports DMA) */
111	uint8_t	bdma_no_post_sync:1;	/* set if the USB callback wrapper
112					 * should not do the BUS-DMA post sync
113					 * operation */
114	uint8_t	bdma_setup:1;		/* set if BUS-DMA has been setup */
115#endif
116	uint8_t	isochronous_xfr:1;	/* set if isochronous transfer */
117	uint8_t	curr_dma_set:1;		/* used by USB HC/DC driver */
118	uint8_t	can_cancel_immed:1;	/* set if USB transfer can be
119					 * cancelled immediately */
120	uint8_t	doing_callback:1;	/* set if executing the callback */
121	uint8_t maxp_was_clamped:1;	/* set if the max packet size
122					 * was outside its allowed range */
123};
124
125/*
126 * The following structure defines an USB transfer.
127 */
128struct usb_xfer {
129	struct usb_callout timeout_handle;
130	TAILQ_ENTRY(usb_xfer) wait_entry;	/* used at various places */
131
132	struct usb_page_cache *buf_fixup;	/* fixup buffer(s) */
133	struct usb_xfer_queue *wait_queue;	/* pointer to queue that we
134						 * are waiting on */
135	struct usb_page *dma_page_ptr;
136	struct usb_endpoint *endpoint;	/* our USB endpoint */
137	struct usb_xfer_root *xroot;	/* used by HC driver */
138	void   *qh_start[2];		/* used by HC driver */
139	void   *td_start[2];		/* used by HC driver */
140	void   *td_transfer_first;	/* used by HC driver */
141	void   *td_transfer_last;	/* used by HC driver */
142	void   *td_transfer_cache;	/* used by HC driver */
143	void   *priv_sc;		/* device driver data pointer 1 */
144	void   *priv_fifo;		/* device driver data pointer 2 */
145	void   *local_buffer;
146	usb_frlength_t *frlengths;
147	struct usb_page_cache *frbuffers;
148	usb_callback_t *callback;
149
150	usb_frlength_t max_hc_frame_size;
151	usb_frlength_t max_data_length;
152	usb_frlength_t sumlen;		/* sum of all lengths in bytes */
153	usb_frlength_t actlen;		/* actual length in bytes */
154	usb_timeout_t timeout;		/* milliseconds */
155
156	usb_frcount_t max_frame_count;	/* initial value of "nframes" after
157					 * setup */
158	usb_frcount_t nframes;		/* number of USB frames to transfer */
159	usb_frcount_t aframes;		/* actual number of USB frames
160					 * transferred */
161	usb_stream_t stream_id;		/* USB3.0 specific field */
162
163	uint16_t max_packet_size;
164	uint16_t max_frame_size;
165	uint16_t qh_pos;
166	uint16_t isoc_time_complete;	/* in ms */
167	usb_timeout_t interval;	/* milliseconds */
168
169	uint8_t	address;		/* physical USB address */
170	uint8_t	endpointno;		/* physical USB endpoint */
171	uint8_t	max_packet_count;
172	uint8_t	usb_state;
173	uint8_t fps_shift;		/* down shift of FPS, 0..3 */
174
175	usb_error_t error;
176
177	struct usb_xfer_flags flags;
178	struct usb_xfer_flags_int flags_int;
179};
180
181/* external variables */
182
183extern struct mtx usb_ref_lock;
184extern const struct usb_string_lang usb_string_lang_en;
185
186/* typedefs */
187
188typedef struct malloc_type *usb_malloc_type;
189
190/* prototypes */
191
192#endif					/* _USB_CORE_H_ */
193