xref: /freebsd/sys/dev/usb/usb_controller.h (revision 718cf2ccb9956613756ab15d7a0e28f2c8e91cab)
102ac6454SAndrew Thompson /* $FreeBSD$ */
202ac6454SAndrew Thompson /*-
3*718cf2ccSPedro F. Giffuni  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4*718cf2ccSPedro F. Giffuni  *
502ac6454SAndrew Thompson  * Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
602ac6454SAndrew Thompson  *
702ac6454SAndrew Thompson  * Redistribution and use in source and binary forms, with or without
802ac6454SAndrew Thompson  * modification, are permitted provided that the following conditions
902ac6454SAndrew Thompson  * are met:
1002ac6454SAndrew Thompson  * 1. Redistributions of source code must retain the above copyright
1102ac6454SAndrew Thompson  *    notice, this list of conditions and the following disclaimer.
1202ac6454SAndrew Thompson  * 2. Redistributions in binary form must reproduce the above copyright
1302ac6454SAndrew Thompson  *    notice, this list of conditions and the following disclaimer in the
1402ac6454SAndrew Thompson  *    documentation and/or other materials provided with the distribution.
1502ac6454SAndrew Thompson  *
1602ac6454SAndrew Thompson  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
1702ac6454SAndrew Thompson  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1802ac6454SAndrew Thompson  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1902ac6454SAndrew Thompson  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
2002ac6454SAndrew Thompson  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
2102ac6454SAndrew Thompson  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
2202ac6454SAndrew Thompson  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
2302ac6454SAndrew Thompson  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
2402ac6454SAndrew Thompson  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
2502ac6454SAndrew Thompson  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
2602ac6454SAndrew Thompson  * SUCH DAMAGE.
2702ac6454SAndrew Thompson  */
2802ac6454SAndrew Thompson 
2975973647SAndrew Thompson #ifndef _USB_CONTROLLER_H_
3075973647SAndrew Thompson #define	_USB_CONTROLLER_H_
3102ac6454SAndrew Thompson 
3202ac6454SAndrew Thompson /* defines */
3302ac6454SAndrew Thompson 
3402ac6454SAndrew Thompson #define	USB_BUS_DMA_TAG_MAX 8
3502ac6454SAndrew Thompson 
3602ac6454SAndrew Thompson /* structure prototypes  */
3702ac6454SAndrew Thompson 
38760bc48eSAndrew Thompson struct usb_bus;
39760bc48eSAndrew Thompson struct usb_page;
40ae60fdfbSAndrew Thompson struct usb_endpoint;
41760bc48eSAndrew Thompson struct usb_page_cache;
42760bc48eSAndrew Thompson struct usb_setup_params;
43760bc48eSAndrew Thompson struct usb_hw_ep_profile;
44760bc48eSAndrew Thompson struct usb_fs_isoc_schedule;
45760bc48eSAndrew Thompson struct usb_endpoint_descriptor;
4602ac6454SAndrew Thompson 
4702ac6454SAndrew Thompson /* typedefs */
4802ac6454SAndrew Thompson 
49f9cb546cSAndrew Thompson typedef void (usb_bus_mem_sub_cb_t)(struct usb_bus *bus, struct usb_page_cache *pc, struct usb_page *pg, usb_size_t size, usb_size_t align);
50e0a69b51SAndrew Thompson typedef void (usb_bus_mem_cb_t)(struct usb_bus *bus, usb_bus_mem_sub_cb_t *scb);
5102ac6454SAndrew Thompson 
5202ac6454SAndrew Thompson /*
5302ac6454SAndrew Thompson  * The following structure is used to define all the USB BUS
5402ac6454SAndrew Thompson  * callbacks.
5502ac6454SAndrew Thompson  */
56760bc48eSAndrew Thompson struct usb_bus_methods {
5702ac6454SAndrew Thompson 
5802ac6454SAndrew Thompson 	/* USB Device and Host mode - Mandatory */
5902ac6454SAndrew Thompson 
60e0a69b51SAndrew Thompson 	usb_handle_req_t *roothub_exec;
61459d369eSAndrew Thompson 
62ae60fdfbSAndrew Thompson 	void    (*endpoint_init) (struct usb_device *,
63ae60fdfbSAndrew Thompson 		    struct usb_endpoint_descriptor *, struct usb_endpoint *);
64760bc48eSAndrew Thompson 	void    (*xfer_setup) (struct usb_setup_params *);
65760bc48eSAndrew Thompson 	void    (*xfer_unsetup) (struct usb_xfer *);
66527aa7b2SAndrew Thompson 	void    (*get_dma_delay) (struct usb_device *, uint32_t *);
67760bc48eSAndrew Thompson 	void    (*device_suspend) (struct usb_device *);
68760bc48eSAndrew Thompson 	void    (*device_resume) (struct usb_device *);
69760bc48eSAndrew Thompson 	void    (*set_hw_power) (struct usb_bus *);
702e141748SHans Petter Selasky 	void    (*set_hw_power_sleep) (struct usb_bus *, uint32_t);
7102ac6454SAndrew Thompson 	/*
7202ac6454SAndrew Thompson 	 * The following flag is set if one or more control transfers are
7302ac6454SAndrew Thompson 	 * active:
7402ac6454SAndrew Thompson 	 */
7502ac6454SAndrew Thompson #define	USB_HW_POWER_CONTROL	0x01
7602ac6454SAndrew Thompson 	/*
7702ac6454SAndrew Thompson 	 * The following flag is set if one or more bulk transfers are
7802ac6454SAndrew Thompson 	 * active:
7902ac6454SAndrew Thompson 	 */
8002ac6454SAndrew Thompson #define	USB_HW_POWER_BULK	0x02
8102ac6454SAndrew Thompson 	/*
8202ac6454SAndrew Thompson 	 * The following flag is set if one or more interrupt transfers are
8302ac6454SAndrew Thompson 	 * active:
8402ac6454SAndrew Thompson 	 */
8502ac6454SAndrew Thompson #define	USB_HW_POWER_INTERRUPT	0x04
8602ac6454SAndrew Thompson 	/*
8702ac6454SAndrew Thompson 	 * The following flag is set if one or more isochronous transfers
8802ac6454SAndrew Thompson 	 * are active:
8902ac6454SAndrew Thompson 	 */
9002ac6454SAndrew Thompson #define	USB_HW_POWER_ISOC	0x08
9102ac6454SAndrew Thompson 	/*
9202ac6454SAndrew Thompson 	 * The following flag is set if one or more non-root-HUB devices
9302ac6454SAndrew Thompson 	 * are present on the given USB bus:
9402ac6454SAndrew Thompson 	 */
9502ac6454SAndrew Thompson #define	USB_HW_POWER_NON_ROOT_HUB 0x10
962e141748SHans Petter Selasky 	/*
972e141748SHans Petter Selasky 	 * The following flag is set if we are suspending
982e141748SHans Petter Selasky 	 */
992e141748SHans Petter Selasky #define	USB_HW_POWER_SUSPEND 0x20
1002e141748SHans Petter Selasky 	/*
1012e141748SHans Petter Selasky 	 * The following flag is set if we are resuming
1022e141748SHans Petter Selasky 	 */
1032e141748SHans Petter Selasky #define	USB_HW_POWER_RESUME 0x40
1042e141748SHans Petter Selasky 	/*
1052e141748SHans Petter Selasky 	 * The following flag is set if we are shutting down
1062e141748SHans Petter Selasky 	 */
1072e141748SHans Petter Selasky #define	USB_HW_POWER_SHUTDOWN 0x60
10802ac6454SAndrew Thompson 
10902ac6454SAndrew Thompson 	/* USB Device mode only - Mandatory */
11002ac6454SAndrew Thompson 
111760bc48eSAndrew Thompson 	void    (*get_hw_ep_profile) (struct usb_device *udev, const struct usb_hw_ep_profile **ppf, uint8_t ep_addr);
112a5cf1aaaSHans Petter Selasky 	void    (*xfer_stall) (struct usb_xfer *xfer);
113a5cf1aaaSHans Petter Selasky 	void    (*set_stall) (struct usb_device *udev, struct usb_endpoint *ep, uint8_t *did_stall);
114963169b4SHans Petter Selasky 
115963169b4SHans Petter Selasky 	/* USB Device mode mandatory. USB Host mode optional. */
116963169b4SHans Petter Selasky 
117ae60fdfbSAndrew Thompson 	void    (*clear_stall) (struct usb_device *udev, struct usb_endpoint *ep);
11802ac6454SAndrew Thompson 
119dddb25f9SAlfred Perlstein 	/* Optional transfer polling support */
120dddb25f9SAlfred Perlstein 
121dddb25f9SAlfred Perlstein 	void	(*xfer_poll) (struct usb_bus *);
122d2d71ce7SAndrew Thompson 
123d2d71ce7SAndrew Thompson 	/* Optional fixed power mode support */
124d2d71ce7SAndrew Thompson 
125d2d71ce7SAndrew Thompson 	void	(*get_power_mode) (struct usb_device *udev, int8_t *pmode);
126963169b4SHans Petter Selasky 
127963169b4SHans Petter Selasky 	/* Optional endpoint uninit */
128963169b4SHans Petter Selasky 
129963169b4SHans Petter Selasky 	void    (*endpoint_uninit) (struct usb_device *, struct usb_endpoint *);
130963169b4SHans Petter Selasky 
131963169b4SHans Petter Selasky 	/* Optional device init */
132963169b4SHans Petter Selasky 
133963169b4SHans Petter Selasky 	usb_error_t	(*device_init) (struct usb_device *);
134963169b4SHans Petter Selasky 
135963169b4SHans Petter Selasky 	/* Optional device uninit */
136963169b4SHans Petter Selasky 
137963169b4SHans Petter Selasky 	void	(*device_uninit) (struct usb_device *);
138963169b4SHans Petter Selasky 
139963169b4SHans Petter Selasky 	/* Optional for device and host mode */
140963169b4SHans Petter Selasky 
141963169b4SHans Petter Selasky 	void	(*start_dma_delay) (struct usb_xfer *);
142963169b4SHans Petter Selasky 
143963169b4SHans Petter Selasky 	void	(*device_state_change) (struct usb_device *);
144963169b4SHans Petter Selasky 
145963169b4SHans Petter Selasky 	/* Optional for host mode */
146963169b4SHans Petter Selasky 
147963169b4SHans Petter Selasky 	usb_error_t	(*set_address) (struct usb_device *, struct mtx *, uint16_t);
148a5cf1aaaSHans Petter Selasky 
149a5cf1aaaSHans Petter Selasky 	/* Optional for device and host mode */
150a5cf1aaaSHans Petter Selasky 
151a5cf1aaaSHans Petter Selasky 	usb_error_t	(*set_endpoint_mode) (struct usb_device *, struct usb_endpoint *, uint8_t);
15202ac6454SAndrew Thompson };
15302ac6454SAndrew Thompson 
15402ac6454SAndrew Thompson /*
15502ac6454SAndrew Thompson  * The following structure is used to define all the USB pipe
15602ac6454SAndrew Thompson  * callbacks.
15702ac6454SAndrew Thompson  */
158760bc48eSAndrew Thompson struct usb_pipe_methods {
15902ac6454SAndrew Thompson 
16002ac6454SAndrew Thompson 	/* Mandatory USB Device and Host mode callbacks: */
16102ac6454SAndrew Thompson 
162ed6d949aSAndrew Thompson 	void	(*open)(struct usb_xfer *);
163ed6d949aSAndrew Thompson 	void	(*close)(struct usb_xfer *);
16402ac6454SAndrew Thompson 
165ed6d949aSAndrew Thompson 	void	(*enter)(struct usb_xfer *);
166ed6d949aSAndrew Thompson 	void	(*start)(struct usb_xfer *);
16702ac6454SAndrew Thompson 
16802ac6454SAndrew Thompson 	/* Optional */
16902ac6454SAndrew Thompson 
17002ac6454SAndrew Thompson 	void   *info;
17102ac6454SAndrew Thompson };
17202ac6454SAndrew Thompson 
17302ac6454SAndrew Thompson /*
17402ac6454SAndrew Thompson  * The following structure keeps information about what a hardware USB
17502ac6454SAndrew Thompson  * endpoint supports.
17602ac6454SAndrew Thompson  */
177760bc48eSAndrew Thompson struct usb_hw_ep_profile {
17802ac6454SAndrew Thompson 	uint16_t max_in_frame_size;	/* IN-token direction */
17902ac6454SAndrew Thompson 	uint16_t max_out_frame_size;	/* OUT-token direction */
18002ac6454SAndrew Thompson 	uint8_t	is_simplex:1;
18102ac6454SAndrew Thompson 	uint8_t	support_multi_buffer:1;
18202ac6454SAndrew Thompson 	uint8_t	support_bulk:1;
18302ac6454SAndrew Thompson 	uint8_t	support_control:1;
18402ac6454SAndrew Thompson 	uint8_t	support_interrupt:1;
18502ac6454SAndrew Thompson 	uint8_t	support_isochronous:1;
18602ac6454SAndrew Thompson 	uint8_t	support_in:1;		/* IN-token is supported */
18702ac6454SAndrew Thompson 	uint8_t	support_out:1;		/* OUT-token is supported */
18802ac6454SAndrew Thompson };
18902ac6454SAndrew Thompson 
19002ac6454SAndrew Thompson /* prototypes */
19102ac6454SAndrew Thompson 
192a593f6b8SAndrew Thompson void	usb_bus_mem_flush_all(struct usb_bus *bus, usb_bus_mem_cb_t *cb);
193a593f6b8SAndrew Thompson uint8_t	usb_bus_mem_alloc_all(struct usb_bus *bus, bus_dma_tag_t dmat, usb_bus_mem_cb_t *cb);
194a593f6b8SAndrew Thompson void	usb_bus_mem_free_all(struct usb_bus *bus, usb_bus_mem_cb_t *cb);
195a593f6b8SAndrew Thompson uint16_t usb_isoc_time_expand(struct usb_bus *bus, uint16_t isoc_time_curr);
196563ab081SHans Petter Selasky void	usb_bus_reset_async_locked(struct usb_bus *bus);
1970a4cc48fSHans Petter Selasky #if USB_HAVE_TT_SUPPORT
1980a4cc48fSHans Petter Selasky uint8_t	usbd_fs_isoc_schedule_alloc_slot(struct usb_xfer *isoc_xfer, uint16_t isoc_time);
1990a4cc48fSHans Petter Selasky #endif
20002ac6454SAndrew Thompson 
20175973647SAndrew Thompson #endif					/* _USB_CONTROLLER_H_ */
202