gadget之usb_function

usb_function

/**
 * struct usb_function - describes one function of a configuration
 * @name: For diagnostics, identifies the function.
 * @strings: tables of strings, keyed by identifiers assigned during bind()
 *    and by language IDs provided in control requests
 * @fs_descriptors: Table of full (or low) speed descriptors, using interface and
 *    string identifiers assigned during @bind().  If this pointer is null,
 *    the function will not be available at full speed (or at low speed).
 * @hs_descriptors: Table of high speed descriptors, using interface and
 *    string identifiers assigned during @bind().  If this pointer is null,
 *    the function will not be available at high speed.
 * @ss_descriptors: Table of super speed descriptors, using interface and
 *    string identifiers assigned during @bind(). If this
 *    pointer is null after initiation, the function will not
 *    be available at super speed.
 * @ssp_descriptors: Table of super speed plus descriptors, using
 *    interface and string identifiers assigned during @bind(). If
 *    this pointer is null after initiation, the function will not
 *    be available at super speed plus.
 * @config: assigned when @usb_add_function() is called; this is the
 *    configuration with which this function is associated.
 * @os_desc_table: 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.
 * @os_desc_n: Number of entries in os_desc_table
 * @bind: Before the gadget can register, all of its functions bind() to the
 *    available resources including string and interface identifiers used
 *    in interface or class descriptors; endpoints; I/O buffers; and so on.
 * @unbind: Reverses @bind; called as a side effect of unregistering the
 *    driver which added this function.
 * @free_func: free the struct usb_function.
 * @mod: (internal) points to the module that created this structure.
 * @set_alt: (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.
 * @get_alt: Returns the active altsetting.  If this is not provided,
 *    then only altsetting zero is supported.
 * @disable: (REQUIRED) Indicates the function should be disabled.  Reasons
 *    include host resetting or reconfiguring the gadget, and disconnection.
 * @setup: Used for interface-specific control requests.
 * @req_match: Tests if a given class request can be handled by this function.
 * @suspend: Notifies functions when the host stops sending USB traffic.
 * @resume: Notifies functions when the host restarts USB traffic.
 * @get_status: Returns function status as a reply to
 *    GetStatus() request when the recipient is Interface.
 * @func_suspend: callback to be called when
 *    SetFeature(FUNCTION_SUSPEND) is reseived
 *
 * 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 @usb_add_function() with a one configuration; that function
 * causes @bind() 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 @usb_ep_autoconfig().
 *
 * To support dual speed operation, a function driver provides descriptors
 * for both high and full speed operation.  Except in rare cases that don't
 * involve bulk endpoints, each speed needs different endpoint descriptors.
 *
 * Function drivers choose their own strategies for managing instance data.
 * The simplest strategy just declares it "static', 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).
 *
 * A more complex strategy might encapsulate a @usb_function 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.
 */
//描述一个配置的一个功能
struct usb_function {
    const char            *name;//功能名称，匹配时需要用到
    struct usb_gadget_strings    **strings;//string数组，通过bind中分配的id访问
    struct usb_descriptor_header    **fs_descriptors;//全速和低速的描述符表，用于bind中分配的接口描述符和string描述符
    struct usb_descriptor_header    **hs_descriptors;//高速描述符表
    struct usb_descriptor_header    **ss_descriptors;
    struct usb_descriptor_header    **ssp_descriptors;
    struct usb_configuration    *config;//调用usb_add_function()函数赋值，是这个功能关联的配置描述符
    struct usb_os_desc_table    *os_desc_table;
    unsigned            os_desc_n;
    /* REVISIT:  bind() functions can be marked __init, which
     * makes trouble for section mismatch analysis.  See if
     * we can't restructure things to avoid mismatching.
     * Related:  unbind() may kfree() but bind() won't...
     */
    /* configuration management:  bind/unbind */
    int            (*bind)(struct usb_configuration *,
                    struct usb_function *);/*unbind的逆操作*/
    void            (*unbind)(struct usb_configuration *,
                    struct usb_function *);
    void            (*free_func)(struct usb_function *f);
    struct module        *mod;
    /* runtime state management */
    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 *,
                    bool config0);
    void            (*suspend)(struct usb_function *);
    void            (*resume)(struct usb_function *);
    /* USB 3.0 additions */
    int            (*get_status)(struct usb_function *);
    int            (*func_suspend)(struct usb_function *,
                        u8 suspend_opt);
    /* private: */
    /* internals */
    struct list_head        list;
    DECLARE_BITMAP(endpoints, 32);
    const struct usb_function_instance *fi;
    unsigned int        bind_deactivated:1;
};

usb_function_driver

struct usb_function_driver {
    const char *name;//usb_function_driver的name，如："acm"
    struct module *mod;
    struct list_head list;
    struct usb_function_instance *(*alloc_inst)(void);//alloc usb_function_instance
    struct usb_function *(*alloc_func)(struct usb_function_instance *inst);//alloc usb_function
};

创建usb_function_driver
源码：include/linux/usb/composite.h

#define DECLARE_USB_FUNCTION(_name, _inst_alloc, _func_alloc)        \
    static struct usb_function_driver _name ## usb_func = {        \
        .name = __stringify(_name),                \
        .mod  = THIS_MODULE,                    \
        .alloc_inst = _inst_alloc,                \
        .alloc_func = _func_alloc,                \
    };                                \
    MODULE_ALIAS("usbfunc:"__stringify(_name));

注册usb_function_driver
源码：include/linux/usb/composite.h

#define DECLARE_USB_FUNCTION_INIT(_name, _inst_alloc, _func_alloc)    \
    DECLARE_USB_FUNCTION(_name, _inst_alloc, _func_alloc)        \
    static int __init _name ## mod_init(void)            \
    {                                \
        return usb_function_register(&_name ## usb_func);    \
    }                                \
    static void __exit _name ## mod_exit(void)            \
    {                                \
        usb_function_unregister(&_name ## usb_func);        \
    }                                \
    module_init(_name ## mod_init);                    \
    module_exit(_name ## mod_exit)

源码：drivers/usb/gadget/functions.c

int usb_function_register(struct usb_function_driver *newf)
{
    struct usb_function_driver *fd;
    int ret;
    ret = -EEXIST;
    mutex_lock(&func_lock);
    //遍历func_list链表，根据func_name判断该func是否注册
    list_for_each_entry(fd, &func_list, list) {
        if (!strcmp(fd->name, newf->name))
            goto out;
    }
    ret = 0;
    //将new_func添加到func_list中
    list_add_tail(&newf->list, &func_list);
out:
    mutex_unlock(&func_lock);
    return ret;
}
EXPORT_SYMBOL_GPL(usb_function_register);
void usb_function_unregister(struct usb_function_driver *fd)
{
    mutex_lock(&func_lock);
    list_del(&fd->list);
    mutex_unlock(&func_lock);
}
EXPORT_SYMBOL_GPL(usb_function_unregister);

示例：以acm function为例说明，如下：

源码：drivers/usb/gadget/function/f_acm.c

DECLARE_USB_FUNCTION_INIT(acm, acm_alloc_instance, acm_alloc_func);

usb_function_instance

源码：include/linux/usb/composite.h

struct usb_function_instance {
    struct config_group group;
    struct list_head cfs_list;
    struct usb_function_driver *fd;
    int (*set_inst_name)(struct usb_function_instance *inst,
                  const char *name);
    void (*free_func_inst)(struct usb_function_instance *inst);
};