linux/usb/gadget.h

1 // SPDX-License-Identifier: GPL-2.0
5  * We call the USB code inside a Linux-based peripheral device a "gadget"
6  * driver, except for the hardware-specific bus glue.  One USB host can
11  * (C) Copyright 2002-2004 by David Brownell
34  * struct usb_request - describes one i/o request
40  * @sg: a scatterlist for SG-capable controllers.
57  *	its buffer may be re-used.  The function will always be called with
67  * @frame_number: Reports the interval number in (micro)frame in which the
72  *	Code "-ESHUTDOWN" indicates completion caused by device disconnect,
79  *	reside in a device-side FIFO when the request is reported as
83  * hardware's driver can add extra per-request data to the memory it returns,
94  * transfers. interrupt-only endpoints can be much less functional.
97  * it's thinner and promotes more pre-allocation.
128 /*-------------------------------------------------------------------------*/
130 /* endpoint-specific parts of the api to the usb controller hardware.
159  * struct usb_ep_caps - endpoint capabilities description
197  * struct usb_ep - device side representation of USB endpoint
198  * @name:identifier for the endpoint, such as "ep-a" or "ep9in-bulk"
199  * @ops: Function pointers used to access hardware-specific operations.
211  *	by this EP (0 - 16, actual number is 2^n)
223  * gadget->ep_list.  the control endpoint (gadget->ep0) is not in that list,
246 /*-------------------------------------------------------------------------*/
292 /*-------------------------------------------------------------------------*/
299 	__u8 besl_baseline;	/* Recommended baseline BESL (0-15) */
300 	__u8 besl_deep;		/* Recommended deep BESL (0-15) */
339  * struct usb_gadget - represents a usb device
342  * @ops: Function pointers used to access hardware-specific operations.
362  * @sg_supported: true if we can handle scatter-gather
363  * @is_otg: True if the USB device port uses a Mini-AB jack, so that the
366  *	is in the Mini-AB jack, and HNP has been used to switch roles
367  *	so that the "A" device currently acts as A-Peripheral, not A-Host.
368  * @a_hnp_support: OTG device feature flag, indicating that the A-Host
370  * @a_alt_hnp_support: OTG device feature flag, indicating that the A-Host
372  * @b_hnp_enable: OTG device feature flag, indicating that the A-Host
376  * @host_request_flag: OTG device feature flag, indicating if A-Peripheral
377  *	or B-Peripheral wants to take host role.
385  * @is_selfpowered: if the gadget is self-powered.
386  * @deactivated: True if gadget is deactivated - in deactivated state it cannot
396  * Gadgets have a mostly-portable "gadget driver" implementing device
398  * drivers talk to hardware-specific code indirectly, through ops vectors.
404  * read-only to the gadget driver.  That driver data is part of the
412  * device is acting as a B-Peripheral (so is_a_peripheral is false).
463 	{ dev_set_drvdata(&gadget->dev, data); }  in set_gadget_data()
465 	{ return dev_get_drvdata(&gadget->dev); }  in get_gadget_data()
472 	get_device(&gadget->dev);  in usb_get_gadget()
477 	put_device(&gadget->dev);  in usb_put_gadget()
484 /* Legacy device-model interface */
491 /* iterates the non-control endpoints; 'tmp' is a struct usb_ep pointer */
493 	list_for_each_entry(tmp, &(gadget)->ep_list, ep_list)
496  * usb_ep_align - returns @len aligned to ep's maxpacketsize.
504 	int max_packet_size = (size_t)usb_endpoint_maxp(ep->desc);  in usb_ep_align()
510  * usb_ep_align_maybe - returns @len aligned to ep's maxpacketsize if gadget
522 	return g->quirk_ep_out_aligned_size ? usb_ep_align(ep, len) : len;  in usb_ep_align_maybe()
526  * gadget_is_altset_supported - return true iff the hardware supports
532 	return !g->quirk_altset_not_supp;  in gadget_is_altset_supported()
536  * gadget_is_stall_supported - return true iff the hardware supports stalling
541 	return !g->quirk_stall_not_supp;  in gadget_is_stall_supported()
545  * gadget_is_zlp_supported - return true iff the hardware supports zlp
550 	return !g->quirk_zlp_not_supp;  in gadget_is_zlp_supported()
554  * gadget_avoids_skb_reserve - return true iff the hardware would like to avoid
560 	return g->quirk_avoids_skb_reserve;  in gadget_avoids_skb_reserve()
564  * gadget_is_dualspeed - return true iff the hardware handles high speed
569 	return g->max_speed >= USB_SPEED_HIGH;  in gadget_is_dualspeed()
573  * gadget_is_superspeed() - return true if the hardware handles superspeed
578 	return g->max_speed >= USB_SPEED_SUPER;  in gadget_is_superspeed()
582  * gadget_is_superspeed_plus() - return true if the hardware handles
588 	return g->max_speed >= USB_SPEED_SUPER_PLUS;  in gadget_is_superspeed_plus()
592  * gadget_is_otg - return true iff the hardware is OTG-ready
593  * @g: controller that might have a Mini-AB connector
595  * This is a runtime test, since kernels with a USB-OTG stack sometimes
596  * run on boards which only have a Mini-B (or Mini-A) connector.
601 	return g->is_otg;  in gadget_is_otg()
607 /*-------------------------------------------------------------------------*/
652 /*-------------------------------------------------------------------------*/
655  * struct usb_gadget_driver - driver for usb gadget devices
687  * If gadget->is_otg is true, the gadget driver must provide an OTG
693  * Drivers use hardware-specific knowledge to configure the usb hardware.
731  * local controls (buttons, dials, etc) may need to be re-enabled since
759 /*-------------------------------------------------------------------------*/
768  * usb_gadget_register_driver_owner - register a gadget driver
790  * usb_gadget_unregister_driver - unregister a gadget driver
804 /*-------------------------------------------------------------------------*/
809  * struct usb_string - wraps a C string and its USB id
811  * @s:the string, in UTF-8 encoding
822  * struct usb_gadget_strings - a set of USB strings in a given language
823  * @language:identifies the strings' language (0x0409 for en-us)
830 	u16			language;	/* 0x0409 for en-us */
855 /*-------------------------------------------------------------------------*/
867 /* copy a NULL-terminated vector of descriptors */
872  * usb_free_descriptors - free descriptors returned by usb_copy_descriptors()
892 /*-------------------------------------------------------------------------*/
908 		struct usb_request *req, int is_in) { return -ENOSYS; }  in usb_gadget_map_request_by_dev()
910 		struct usb_request *req, int is_in) { return -ENOSYS; }  in usb_gadget_map_request()
918 /*-------------------------------------------------------------------------*/
925 /*-------------------------------------------------------------------------*/
931 /*-------------------------------------------------------------------------*/
938 /*-------------------------------------------------------------------------*/
945 /*-------------------------------------------------------------------------*/
953 /*-------------------------------------------------------------------------*/
958 /*-------------------------------------------------------------------------*/