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_XFER_LOCK(_x)		mtx_lock((_x)->xroot->xfer_mtx)
48#define	USB_XFER_UNLOCK(_x)		mtx_unlock((_x)->xroot->xfer_mtx)
49#define	USB_XFER_LOCK_ASSERT(_x, _t)	mtx_assert((_x)->xroot->xfer_mtx, _t)
50
51/* helper for converting pointers to integers */
52#define	USB_P2U(ptr) \
53  (((const uint8_t *)(ptr)) - ((const uint8_t *)0))
54
55/* helper for computing offsets */
56#define	USB_ADD_BYTES(ptr,size) \
57  ((void *)(USB_P2U(ptr) + (size)))
58
59/* debug macro */
60#define	USB_ASSERT KASSERT
61
62/* structure prototypes */
63
64struct file;
65struct usb_bus;
66struct usb_device;
67struct usb_device_request;
68struct usb_page;
69struct usb_page_cache;
70struct usb_xfer;
71struct usb_xfer_root;
72
73/* typedefs */
74
75/* structures */
76
77/*
78 * The following structure defines a set of internal USB transfer
79 * flags.
80 */
81struct usb_xfer_flags_int {
82
83	enum usb_hc_mode usb_mode;	/* shadow copy of "udev->usb_mode" */
84	uint16_t control_rem;		/* remainder in bytes */
85
86	uint8_t	open:1;			/* set if USB pipe has been opened */
87	uint8_t	transferring:1;		/* set if an USB transfer is in
88					 * progress */
89	uint8_t	did_dma_delay:1;	/* set if we waited for HW DMA */
90	uint8_t	did_close:1;		/* set if we closed the USB transfer */
91	uint8_t	draining:1;		/* set if we are draining an USB
92					 * transfer */
93	uint8_t	started:1;		/* keeps track of started or stopped */
94	uint8_t	bandwidth_reclaimed:1;
95	uint8_t	control_xfr:1;		/* set if control transfer */
96	uint8_t	control_hdr:1;		/* set if control header should be
97					 * sent */
98	uint8_t	control_act:1;		/* set if control transfer is active */
99	uint8_t	control_stall:1;	/* set if control transfer should be stalled */
100
101	uint8_t	short_frames_ok:1;	/* filtered version */
102	uint8_t	short_xfer_ok:1;	/* filtered version */
103#if USB_HAVE_BUSDMA
104	uint8_t	bdma_enable:1;		/* filtered version (only set if
105					 * hardware supports DMA) */
106	uint8_t	bdma_no_post_sync:1;	/* set if the USB callback wrapper
107					 * should not do the BUS-DMA post sync
108					 * operation */
109	uint8_t	bdma_setup:1;		/* set if BUS-DMA has been setup */
110#endif
111	uint8_t	isochronous_xfr:1;	/* set if isochronous transfer */
112	uint8_t	curr_dma_set:1;		/* used by USB HC/DC driver */
113	uint8_t	can_cancel_immed:1;	/* set if USB transfer can be
114					 * cancelled immediately */
115	uint8_t	doing_callback:1;	/* set if executing the callback */
116	uint8_t maxp_was_clamped:1;	/* set if the max packet size
117					 * was outside its allowed range */
118};
119
120/*
121 * The following structure defines an USB transfer.
122 */
123struct usb_xfer {
124	struct usb_callout timeout_handle;
125	TAILQ_ENTRY(usb_xfer) wait_entry;	/* used at various places */
126
127	struct usb_page_cache *buf_fixup;	/* fixup buffer(s) */
128	struct usb_xfer_queue *wait_queue;	/* pointer to queue that we
129						 * are waiting on */
130	struct usb_page *dma_page_ptr;
131	struct usb_endpoint *endpoint;	/* our USB endpoint */
132	struct usb_xfer_root *xroot;	/* used by HC driver */
133	void   *qh_start[2];		/* used by HC driver */
134	void   *td_start[2];		/* used by HC driver */
135	void   *td_transfer_first;	/* used by HC driver */
136	void   *td_transfer_last;	/* used by HC driver */
137	void   *td_transfer_cache;	/* used by HC driver */
138	void   *priv_sc;		/* device driver data pointer 1 */
139	void   *priv_fifo;		/* device driver data pointer 2 */
140	void   *local_buffer;
141	usb_frlength_t *frlengths;
142	struct usb_page_cache *frbuffers;
143	usb_callback_t *callback;
144
145	usb_frlength_t max_hc_frame_size;
146	usb_frlength_t max_data_length;
147	usb_frlength_t sumlen;		/* sum of all lengths in bytes */
148	usb_frlength_t actlen;		/* actual length in bytes */
149	usb_timeout_t timeout;		/* milliseconds */
150
151	usb_frcount_t max_frame_count;	/* initial value of "nframes" after
152					 * setup */
153	usb_frcount_t nframes;		/* number of USB frames to transfer */
154	usb_frcount_t aframes;		/* actual number of USB frames
155					 * transferred */
156
157	uint16_t max_packet_size;
158	uint16_t max_frame_size;
159	uint16_t qh_pos;
160	uint16_t isoc_time_complete;	/* in ms */
161	usb_timeout_t interval;	/* milliseconds */
162
163	uint8_t	address;		/* physical USB address */
164	uint8_t	endpointno;		/* physical USB endpoint */
165	uint8_t	max_packet_count;
166	uint8_t	usb_state;
167	uint8_t fps_shift;		/* down shift of FPS, 0..3 */
168
169	usb_error_t error;
170
171	struct usb_xfer_flags flags;
172	struct usb_xfer_flags_int flags_int;
173};
174
175/* external variables */
176
177extern struct mtx usb_ref_lock;
178
179/* typedefs */
180
181typedef struct malloc_type *usb_malloc_type;
182
183/* prototypes */
184
185#endif					/* _USB_CORE_H_ */
186