'\" t .\" Title: struct usb_function .\" Author: .\" Generator: DocBook XSL Stylesheets v1.79.1 .\" Date: January 2017 .\" Manual: Kernel Mode Gadget API .\" Source: Kernel Hackers Manual 4.8.15 .\" Language: English .\" .TH "STRUCT USB_FUNCTION" "9" "January 2017" "Kernel Hackers Manual 4\&.8\&." "Kernel Mode Gadget API" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" struct_usb_function \- describes one function of a configuration .SH "SYNOPSIS" .sp .nf struct usb_function { const char * name; struct usb_gadget_strings ** strings; struct usb_descriptor_header ** fs_descriptors; struct usb_descriptor_header ** hs_descriptors; struct usb_descriptor_header ** ss_descriptors; struct usb_descriptor_header ** ssp_descriptors; struct usb_configuration * config; struct usb_os_desc_table * os_desc_table; unsigned os_desc_n; int (* bind) (struct usb_configuration *,struct usb_function *); void (* unbind) (struct usb_configuration *,struct usb_function *); void (* free_func) (struct usb_function *f); struct module * mod; int (* set_alt) (struct usb_function *,unsigned interface, unsigned alt); int (* get_alt) (struct usb_function *,unsigned interface); void (* disable) (struct usb_function *); int (* setup) (struct usb_function *,const struct usb_ctrlrequest *); bool (* req_match) (struct usb_function *,const struct usb_ctrlrequest *); void (* suspend) (struct usb_function *); void (* resume) (struct usb_function *); int (* get_status) (struct usb_function *); int (* func_suspend) (struct usb_function *,u8 suspend_opt); }; .fi .SH "MEMBERS" .PP name .RS 4 For diagnostics, identifies the function\&. .RE .PP strings .RS 4 tables of strings, keyed by identifiers assigned during \fBbind\fR and by language IDs provided in control requests .RE .PP fs_descriptors .RS 4 Table of full (or low) speed descriptors, using interface and string identifiers assigned during \fIbind\fR()\&. If this pointer is null, the function will not be available at full speed (or at low speed)\&. .RE .PP hs_descriptors .RS 4 Table of high speed descriptors, using interface and string identifiers assigned during \fIbind\fR()\&. If this pointer is null, the function will not be available at high speed\&. .RE .PP ss_descriptors .RS 4 Table of super speed descriptors, using interface and string identifiers assigned during \fIbind\fR()\&. If this pointer is null after initiation, the function will not be available at super speed\&. .RE .PP ssp_descriptors .RS 4 Table of super speed plus descriptors, using interface and string identifiers assigned during \fIbind\fR()\&. If this pointer is null after initiation, the function will not be available at super speed plus\&. .RE .PP config .RS 4 assigned when \fIusb_add_function\fR() is called; this is the configuration with which this function is associated\&. .RE .PP os_desc_table .RS 4 Table of (interface id, os descriptors) pairs\&. The function can expose more than one interface\&. If an interface is a member of an IAD, only the first interface of IAD has its entry in the table\&. .RE .PP os_desc_n .RS 4 Number of entries in os_desc_table .RE .PP bind .RS 4 Before the gadget can register, all of its functions \fBbind\fR to the available resources including string and interface identifiers used in interface or class descriptors; endpoints; I/O buffers; and so on\&. .RE .PP unbind .RS 4 Reverses \fIbind\fR; called as a side effect of unregistering the driver which added this function\&. .RE .PP free_func .RS 4 free the struct usb_function\&. .RE .PP mod .RS 4 (internal) points to the module that created this structure\&. .RE .PP set_alt .RS 4 (REQUIRED) Reconfigures altsettings; function drivers may initialize usb_ep\&.driver data at this time (when it is used)\&. Note that setting an interface to its current altsetting resets interface state, and that all interfaces have a disabled state\&. .RE .PP get_alt .RS 4 Returns the active altsetting\&. If this is not provided, then only altsetting zero is supported\&. .RE .PP disable .RS 4 (REQUIRED) Indicates the function should be disabled\&. Reasons include host resetting or reconfiguring the gadget, and disconnection\&. .RE .PP setup .RS 4 Used for interface\-specific control requests\&. .RE .PP req_match .RS 4 Tests if a given class request can be handled by this function\&. .RE .PP suspend .RS 4 Notifies functions when the host stops sending USB traffic\&. .RE .PP resume .RS 4 Notifies functions when the host restarts USB traffic\&. .RE .PP get_status .RS 4 Returns function status as a reply to \fBGetStatus\fR request when the recipient is Interface\&. .RE .PP func_suspend .RS 4 callback to be called when SetFeature(FUNCTION_SUSPEND) is reseived .RE .SH "DESCRIPTION" .PP A single USB function uses one or more interfaces, and should in most cases support operation at both full and high speeds\&. Each function is associated by \fIusb_add_function\fR() with a one configuration; that function causes \fIbind\fR() to be called so resources can be allocated as part of setting up a gadget driver\&. Those resources include endpoints, which should be allocated using \fIusb_ep_autoconfig\fR()\&. .PP To support dual speed operation, a function driver provides descriptors for both high and full speed operation\&. Except in rare cases that don\*(Aqt involve bulk endpoints, each speed needs different endpoint descriptors\&. .PP Function drivers choose their own strategies for managing instance data\&. The simplest strategy just declares it "static\*(Aq, which means the function can only be activated once\&. If the function needs to be exposed in more than one configuration at a given speed, it needs to support multiple usb_function structures (one for each configuration)\&. .PP A more complex strategy might encapsulate a \fIusb_function\fR structure inside a driver\-specific instance structure to allows multiple activations\&. An example of multiple activations might be a CDC ACM function that supports two or more distinct instances within the same configuration, providing several independent logical data links to a USB host\&. .SH "AUTHOR" .PP \fBDavid Brownell\fR <\&dbrownell@users.sourceforge.net\&> .RS 4 Author. .RE .SH "COPYRIGHT" .br