usb_controller.h revision 184610 
1/* $FreeBSD: head/sys/dev/usb2/controller/usb2_controller.h 184610 2008-11-04 02:31:03Z alfred $ */
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#ifndef _USB2_CONTROLLER_H_
28#define	_USB2_CONTROLLER_H_
29
30/* defines */
31
32#define	USB_BUS_DMA_TAG_MAX 8
33
34/* structure prototypes */
35
36struct usb2_bus;
37struct usb2_page;
38struct usb2_pipe;
39struct usb2_page_cache;
40struct usb2_setup_params;
41struct usb2_hw_ep_profile;
42struct usb2_fs_isoc_schedule;
43struct usb2_config_descriptor;
44struct usb2_endpoint_descriptor;
45
46/* typedefs */
47
48typedef void (usb2_bus_mem_sub_cb_t)(struct usb2_bus *bus, struct usb2_page_cache *pc, struct usb2_page *pg, uint32_t size, uint32_t align);
49typedef void (usb2_bus_mem_cb_t)(struct usb2_bus *bus, usb2_bus_mem_sub_cb_t *scb);
50
51/*
52 * The following structure is used to define all the USB BUS
53 * callbacks.
54 */
55struct usb2_bus_methods {
56
57	/* USB Device and Host mode - Mandatory */
58
59	void    (*pipe_init) (struct usb2_device *udev, struct usb2_endpoint_descriptor *edesc, struct usb2_pipe *pipe);
60	void    (*do_poll) (struct usb2_bus *);
61	void    (*xfer_setup) (struct usb2_setup_params *parm);
62	void    (*xfer_unsetup) (struct usb2_xfer *xfer);
63	void    (*get_dma_delay) (struct usb2_bus *, uint32_t *pdelay);
64
65	/* USB Device mode only - Mandatory */
66
67	void    (*get_hw_ep_profile) (struct usb2_device *udev, const struct usb2_hw_ep_profile **ppf, uint8_t ep_addr);
68	void    (*set_stall) (struct usb2_device *udev, struct usb2_xfer *xfer, struct usb2_pipe *pipe);
69	void    (*clear_stall) (struct usb2_device *udev, struct usb2_pipe *pipe);
70	void    (*rem_wakeup_set) (struct usb2_device *udev, uint8_t is_on);
71
72	/* USB Device mode only - Optional */
73
74	void    (*vbus_interrupt) (struct usb2_bus *, uint8_t is_on);
75};
76
77/*
78 * The following structure is used to define all the USB pipe
79 * callbacks.
80 */
81struct usb2_pipe_methods {
82
83	/* Mandatory USB Device and Host mode callbacks: */
84
85	void    (*open) (struct usb2_xfer *xfer);
86	void    (*close) (struct usb2_xfer *xfer);
87
88	void    (*enter) (struct usb2_xfer *xfer);
89	void    (*start) (struct usb2_xfer *xfer);
90
91	/* Optional */
92
93	uint8_t (*isdone) (struct usb2_xfer *xfer);
94	void   *info;
95
96	/* Flags */
97
98	uint8_t	enter_is_cancelable:1;
99	uint8_t	start_is_cancelable:1;
100};
101
102/*
103 * The following structure keeps information about what a hardware USB
104 * endpoint supports.
105 */
106struct usb2_hw_ep_profile {
107	uint16_t max_in_frame_size;	/* IN-token direction */
108	uint16_t max_out_frame_size;	/* OUT-token direction */
109	uint8_t	is_simplex:1;
110	uint8_t	support_multi_buffer:1;
111	uint8_t	support_bulk:1;
112	uint8_t	support_control:1;
113	uint8_t	support_interrupt:1;
114	uint8_t	support_isochronous:1;
115	uint8_t	support_in:1;		/* IN-token is supported */
116	uint8_t	support_out:1;		/* OUT-token is supported */
117};
118
119/*
120 * The following structure is used when trying to allocate hardware
121 * endpoints for an USB configuration in USB device side mode.
122 */
123struct usb2_hw_ep_scratch_sub {
124	const struct usb2_hw_ep_profile *pf;
125	uint16_t max_frame_size;
126	uint8_t	hw_endpoint_out;
127	uint8_t	hw_endpoint_in;
128	uint8_t	needs_ep_type;
129	uint8_t	needs_in:1;
130	uint8_t	needs_out:1;
131};
132
133/*
134 * The following structure is used when trying to allocate hardware
135 * endpoints for an USB configuration in USB device side mode.
136 */
137struct usb2_hw_ep_scratch {
138	struct usb2_hw_ep_scratch_sub ep[USB_EP_MAX];
139	struct usb2_hw_ep_scratch_sub *ep_max;
140	struct usb2_config_descriptor *cd;
141	struct usb2_device *udev;
142	struct usb2_bus_methods *methods;
143	uint8_t	bmOutAlloc[(USB_EP_MAX + 15) / 16];
144	uint8_t	bmInAlloc[(USB_EP_MAX + 15) / 16];
145};
146
147/*
148 * The following structure is used when generating USB descriptors
149 * from USB templates.
150 */
151struct usb2_temp_setup {
152	void   *buf;
153	uint32_t size;
154	uint8_t	usb2_speed;
155	uint8_t	self_powered;
156	uint8_t	bNumEndpoints;
157	uint8_t	bInterfaceNumber;
158	uint8_t	bAlternateSetting;
159	uint8_t	bConfigurationValue;
160	usb2_error_t err;
161};
162
163/* prototypes */
164
165void	usb2_bus_mem_flush_all(struct usb2_bus *bus, usb2_bus_mem_cb_t *cb);
166uint8_t	usb2_bus_mem_alloc_all(struct usb2_bus *bus, bus_dma_tag_t dmat, usb2_bus_mem_cb_t *cb);
167void	usb2_bus_mem_free_all(struct usb2_bus *bus, usb2_bus_mem_cb_t *cb);
168uint16_t usb2_isoc_time_expand(struct usb2_bus *bus, uint16_t isoc_time_curr);
169uint16_t usb2_fs_isoc_schedule_isoc_time_expand(struct usb2_device *udev, struct usb2_fs_isoc_schedule **pp_start, struct usb2_fs_isoc_schedule **pp_end, uint16_t isoc_time);
170uint8_t	usb2_fs_isoc_schedule_alloc(struct usb2_fs_isoc_schedule *fss, uint8_t *pstart, uint16_t len);
171
172#endif					/* _USB2_CONTROLLER_H_ */
173