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.
44  * @stream_id: The stream id, when USB3.0 bulk streams are being used
56  *	its buffer may be re-used.  The function will always be called with
71  *	Code "-ESHUTDOWN" indicates completion caused by device disconnect,
78  *	reside in a device-side FIFO when the request is reported as
82  * hardware's driver can add extra per-request data to the memory it returns,
93  * transfers. interrupt-only endpoints can be much less functional.
96  * it's thinner and promotes more pre-allocation.
126 /*-------------------------------------------------------------------------*/
128 /* endpoint-specific parts of the api to the usb controller hardware.
157  * struct usb_ep_caps - endpoint capabilities description
195  * struct usb_ep - device side representation of USB endpoint
196  * @name:identifier for the endpoint, such as "ep-a" or "ep9in-bulk"
197  * @ops: Function pointers used to access hardware-specific operations.
209  *	by this EP (0 - 16, actual number is 2^n)
221  * gadget->ep_list.  the control endpoint (gadget->ep0) is not in that list,
244 /*-------------------------------------------------------------------------*/
290 /*-------------------------------------------------------------------------*/
297 	__u8 besl_baseline;	/* Recommended baseline BESL (0-15) */
298 	__u8 besl_deep;		/* Recommended deep BESL (0-15) */
337  * struct usb_gadget - represents a usb device
340  * @ops: Function pointers used to access hardware-specific operations.
360  * @sg_supported: true if we can handle scatter-gather
361  * @is_otg: True if the USB device port uses a Mini-AB jack, so that the
364  *	is in the Mini-AB jack, and HNP has been used to switch roles
365  *	so that the "A" device currently acts as A-Peripheral, not A-Host.
366  * @a_hnp_support: OTG device feature flag, indicating that the A-Host
368  * @a_alt_hnp_support: OTG device feature flag, indicating that the A-Host
370  * @b_hnp_enable: OTG device feature flag, indicating that the A-Host
374  * @host_request_flag: OTG device feature flag, indicating if A-Peripheral
375  *	or B-Peripheral wants to take host role.
383  * @is_selfpowered: if the gadget is self-powered.
384  * @deactivated: True if gadget is deactivated - in deactivated state it cannot
392  * @id_number: a unique ID number for ensuring that gadget names are distinct
394  * Gadgets have a mostly-portable "gadget driver" implementing device
396  * drivers talk to hardware-specific code indirectly, through ops vectors.
402  * read-only to the gadget driver.  That driver data is part of the
410  * device is acting as a B-Peripheral (so is_a_peripheral is false).
461 	{ dev_set_drvdata(&gadget->dev, data); }  in set_gadget_data()
463 	{ return dev_get_drvdata(&gadget->dev); }  in get_gadget_data()
470 	get_device(&gadget->dev);  in usb_get_gadget()
475 	put_device(&gadget->dev);  in usb_put_gadget()
482 /* Legacy device-model interface */
489 /* iterates the non-control endpoints; 'tmp' is a struct usb_ep pointer */
491 	list_for_each_entry(tmp, &(gadget)->ep_list, ep_list)
494  * usb_ep_align - returns @len aligned to ep's maxpacketsize.
502 	int max_packet_size = (size_t)usb_endpoint_maxp(ep->desc);  in usb_ep_align()
508  * usb_ep_align_maybe - returns @len aligned to ep's maxpacketsize if gadget
520 	return g->quirk_ep_out_aligned_size ? usb_ep_align(ep, len) : len;  in usb_ep_align_maybe()
524  * gadget_is_altset_supported - return true iff the hardware supports
530 	return !g->quirk_altset_not_supp;  in gadget_is_altset_supported()
534  * gadget_is_stall_supported - return true iff the hardware supports stalling
539 	return !g->quirk_stall_not_supp;  in gadget_is_stall_supported()
543  * gadget_is_zlp_supported - return true iff the hardware supports zlp
548 	return !g->quirk_zlp_not_supp;  in gadget_is_zlp_supported()
552  * gadget_avoids_skb_reserve - return true iff the hardware would like to avoid
558 	return g->quirk_avoids_skb_reserve;  in gadget_avoids_skb_reserve()
562  * gadget_is_dualspeed - return true iff the hardware handles high speed
567 	return g->max_speed >= USB_SPEED_HIGH;  in gadget_is_dualspeed()
571  * gadget_is_superspeed() - return true if the hardware handles superspeed
576 	return g->max_speed >= USB_SPEED_SUPER;  in gadget_is_superspeed()
580  * gadget_is_superspeed_plus() - return true if the hardware handles
586 	return g->max_speed >= USB_SPEED_SUPER_PLUS;  in gadget_is_superspeed_plus()
590  * gadget_is_otg - return true iff the hardware is OTG-ready
591  * @g: controller that might have a Mini-AB connector
593  * This is a runtime test, since kernels with a USB-OTG stack sometimes
594  * run on boards which only have a Mini-B (or Mini-A) connector.
599 	return g->is_otg;  in gadget_is_otg()
605 /*-------------------------------------------------------------------------*/
650 /*-------------------------------------------------------------------------*/
653  * struct usb_gadget_driver - driver for usb gadget devices
685  * If gadget->is_otg is true, the gadget driver must provide an OTG
691  * Drivers use hardware-specific knowledge to configure the usb hardware.
729  * local controls (buttons, dials, etc) may need to be re-enabled since
757 /*-------------------------------------------------------------------------*/
766  * usb_gadget_register_driver_owner - register a gadget driver
788  * usb_gadget_unregister_driver - unregister a gadget driver
802 /*-------------------------------------------------------------------------*/
807  * struct usb_string - wraps a C string and its USB id
808  * @id:the (nonzero) ID for this string
809  * @s:the string, in UTF-8 encoding
812  * together with its ID.
815 	u8			id;  member
820  * struct usb_gadget_strings - a set of USB strings in a given language
821  * @language:identifies the strings' language (0x0409 for en-us)
825  * strings for a given language.
828 	u16			language;	/* 0x0409 for en-us */  member
837 /* put descriptor for string with that id into buf (buflen >= 256) */
838 int usb_gadget_get_string(const struct usb_gadget_strings *table, int id, u8 *buf);
840 /* check if the given language identifier is valid */
853 /*-------------------------------------------------------------------------*/
865 /* copy a NULL-terminated vector of descriptors */
870  * usb_free_descriptors - free descriptors returned by usb_copy_descriptors()
890 /*-------------------------------------------------------------------------*/
906 		struct usb_request *req, int is_in) { return -ENOSYS; }  in usb_gadget_map_request_by_dev()
908 		struct usb_request *req, int is_in) { return -ENOSYS; }  in usb_gadget_map_request()
916 /*-------------------------------------------------------------------------*/
923 /*-------------------------------------------------------------------------*/
929 /*-------------------------------------------------------------------------*/
936 /*-------------------------------------------------------------------------*/
943 /*-------------------------------------------------------------------------*/
951 /*-------------------------------------------------------------------------*/
956 /*-------------------------------------------------------------------------*/