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