gadget.h 简单翻译(2)

**

 * struct usb_gadget - represents a usb slave device代表了一个USB从设备

 * @ops: Function pointers used to access hardware-specific operations.底层硬件的各种函数指针集

 * @ep0: Endpoint zero, used when reading or writing responses to

 *    driver setup() requests端点0，主要用在枚举阶段

 * @ep_list: List of other endpoints supported by the device.该设备支持的端点列表

 * @speed: Speed of current connection to USB host.当前连接到USB主机的速度

 * @is_dualspeed: True if the controller supports both high and full speed

 *    operation.  If it does, the gadget driver must also support both.如果控制器同时支持高速和全速选项，则为true.如果它支持，gadget驱动必须也同时支持。

 * @is_otg: True if the USB device port uses a Mini-AB jack, so that the

 *    gadget driver must provide a USB OTG descriptor.为true,如果USB设备端口使用了mini-AB接头，那么gadget驱动必须提供一个USB OTG描述符。（因为没有涉及到OTG，所以下面几个字段就不翻译了）

 * @is_a_peripheral: False unless is_otg, the "A" end of a USB cable

 *    is in the Mini-AB jack, and HNP has been used to switch roles

 *    so that the "A" device currently acts as A-Peripheral, not A-Host.

* @a_hnp_support: OTG device feature flag, indicating that the A-Host

 *    supports HNP at this port.

 * @a_alt_hnp_support: OTG device feature flag, indicating that the A-Host

 *    only supports HNP on a different root port.

 * @b_hnp_enable: OTG device feature flag, indicating that the A-Host

 *    enabled HNP support.

 * @name: Identifies the controller hardware type.  Used in diagnostics

 *    and sometimes configuration.标志控制器的硬件类型，用在诊断和有些配置中

 * @dev: Driver model state for this abstract device.驱动模型状态对应的抽象设备

 *

 * Gadgets have a mostly-portable "gadget driver" implementing device

 * functions, handling all usb configurations and interfaces.  Gadget

 * drivers talk to hardware-specific code indirectly, through ops vectors.

 * That insulates the gadget driver from hardware details, and packages

 * the hardware endpoints through generic i/o queues.  The "usb_gadget"

 * and "usb_ep" interfaces provide that insulation from the hardware.

 *Gadgets有一个大多数便携性的"gadget driver"来执行设备的功能，处理所有USB配置和接口。Gadget驱动不直接与具体硬件打交道，它通过ops向量操作。ops向量使得gadget驱动程序与具体的硬件隔离开，并通过普通IO队列打包硬件端点。"usb_gadget"与"usb_ep"接口使得linux系统中编写程序时能够把功能的实现和底层通信分离。

 * Except for the driver data, all fields in this structure are

 * read-only to the gadget driver.  That driver data is part of the

 * "driver model" infrastructure in 2.6 (and later) kernels, and for

 * earlier systems is grouped in a similar structure that's not known

 * to the rest of the kernel.除了驱动数据外，所有在这个结构体的字段对于gadget驱动来说都是只读的。该驱动数据是2.6内核驱动模型的一部分。

 *

 * Values of the three OTG device feature flags are updated before the

 * setup() call corresponding to USB_REQ_SET_CONFIGURATION, and before

 * driver suspend() calls.  They are valid only when is_otg, and when the

 * device is acting as a B-Peripheral (so is_a_peripheral is false).

 */

struct usb_gadget {

       /* readonly to gadget driver */

       const struct usb_gadget_ops   *ops;

       struct usb_ep                 *ep0;

       struct list_head              ep_list;    /* of usb_ep */

       enum usb_device_speed        speed;

       unsigned                is_dualspeed:1;

       unsigned                is_otg:1;

       unsigned                is_a_peripheral:1;

       unsigned                b_hnp_enable:1;

       unsigned                a_hnp_support:1;

       unsigned                a_alt_hnp_support:1;

       const char                     *name;

       struct device                 dev;

};

// 把数据指向usb_gadget结构变量的dev的私有数据

static inline void set_gadget_data(struct usb_gadget *gadget, void *data)

       { dev_set_drvdata(&gadget->dev, data); }

// 获得指向usb_gadget结构变量的dev的私有数据的指针

static inline void *get_gadget_data(struct usb_gadget *gadget)

       { return dev_get_drvdata(&gadget->dev); }

 

/* iterates the non-control endpoints; 'tmp' is a struct usb_ep pointer */

#define gadget_for_each_ep(tmp,gadget) \

       list_for_each_entry(tmp, &(gadget)->ep_list, ep_list)

/**

 * gadget_is_dualspeed - return true iff the hardware handles high speed

 * @g: controller that might support both high and full speeds反馈是否同时支持全速和高速

 */

static inline int gadget_is_dualspeed(struct usb_gadget *g)

{

#ifdef CONFIG_USB_GADGET_DUALSPEED

       /* runtime test would check "g->is_dualspeed" ... that might be

        * useful to work around hardware bugs, but is mostly pointless

        */

       return 1;

#else

       return 0;

#endif

}

 

/**

 * gadget_is_otg - return true if the hardware is OTG-ready

 * @g: controller that might have a Mini-AB connector

 *

 * This is a runtime test, since kernels with a USB-OTG stack sometimes

 * run on boards which only have a Mini-B (or Mini-A) connector.反馈是否支持OTG

 */

static inline int gadget_is_otg(struct usb_gadget *g)

{

#ifdef CONFIG_USB_OTG

       return g->is_otg;

#else

       return 0;

#endif

}

 

/**

 * usb_gadget_frame_number - returns the current frame number返回当前帧号

 * @gadget: controller that reports the frame number用来报告帧数的控制器

 *

 * Returns the usb frame number, normally eleven bits from a SOF packet,

 * or negative errno if this device doesn't support this capability.返回USB帧号，正常情况下是得到SOF包的11位数据，或错误

 */

static inline int usb_gadget_frame_number(struct usb_gadget *gadget)

{

       return gadget->ops->get_frame(gadget);

}

 

/**

 * usb_gadget_wakeup - tries to wake up the host connected to this gadget尝试唤醒连在该gadget的主机

 * @gadget: controller used to wake up the host

 *

 * Returns zero on success, else negative error code if the hardware

 * doesn't support such attempts, or its support has not been enabled

 * by the usb host.  Drivers must return device descriptors that report

 * their ability to support this, or hosts won't enable it.成功则返回0，否则如果硬件不支持则返回错误代码。驱动必须返回设备描述符用来报告他们的能力来支持这个功能。

 *

 * This may also try to use SRP to wake the host and start enumeration,

 * even if OTG isn't otherwise in use.  OTG devices may also start

 * remote wakeup even when hosts don't explicitly enable it.

 */

static inline int usb_gadget_wakeup(struct usb_gadget *gadget)

{

       if (!gadget->ops->wakeup)

              return -EOPNOTSUPP;

       return gadget->ops->wakeup(gadget);

}

 

/**

 * usb_gadget_set_selfpowered - sets the device selfpowered feature.设置该设备为自供电状态

 * @gadget:the device being declared as self-powered

 *

 * this affects the device status reported by the hardware driver

 * to reflect that it now has a local power supply.

 *

 * returns zero on success, else negative errno.

 */

static inline int usb_gadget_set_selfpowered(struct usb_gadget *gadget)

{

       if (!gadget->ops->set_selfpowered)

              return -EOPNOTSUPP;

       return gadget->ops->set_selfpowered(gadget, 1);

}

 

/**

 * usb_gadget_clear_selfpowered - clear the device selfpowered feature.清除自供电状态

 * @gadget:the device being declared as bus-powered

 *

 * this affects the device status reported by the hardware driver.

 * some hardware may not support bus-powered operation, in which

 * case this feature's value can never change.

 *

 * returns zero on success, else negative errno.

 */

static inline int usb_gadget_clear_selfpowered(struct usb_gadget *gadget)

{

       if (!gadget->ops->set_selfpowered)

              return -EOPNOTSUPP;

       return gadget->ops->set_selfpowered(gadget, 0);

}

 

/**

 * usb_gadget_vbus_connect - Notify controller that VBUS is powered注意控制器VBUS已经供电

 * @gadget:The device which now has VBUS power.设备端已经由VBUS供电

 *

 * This call is used by a driver for an external transceiver (or GPIO)

 * that detects a VBUS power session starting.  Common responses include

 * resuming the controller, activating the D+ (or D-) pullup to let the

 * host detect that a USB device is attached, and starting to draw power

 * (8mA or possibly more, especially after SET_CONFIGURATION).

 *通过额外的收发器(或者GPIO)的驱动来调用，能检测到VBUS电源部分已经启动。普通的反馈包括恢复控制器，激活 D+ (or D-)的上拉让主机可以检测到一个USB设备已经插入，然后开始限制电源相关。

 * Returns zero on success, else negative errno.

 */

static inline int usb_gadget_vbus_connect(struct usb_gadget *gadget)

{

       if (!gadget->ops->vbus_session)

              return -EOPNOTSUPP;

       return gadget->ops->vbus_session(gadget, 1);

}

 

/**

 * usb_gadget_vbus_draw - constrain controller's VBUS power usage约束控制器的VBUS电源使用

 * @gadget:The device whose VBUS usage is being described

 * @mA:How much current to draw, in milliAmperes.  This should be twice

 *    the value listed in the configuration descriptor bMaxPower field.限制在多大电流，单位是mA，它应该是配置描述符bMaxPower的2倍。

 *

 * This call is used by gadget drivers during SET_CONFIGURATION calls,

 * reporting how much power the device may consume.  For example, this

 * could affect how quickly batteries are recharged.它由gadget驱动在设置配置时调用，报告设备需要消耗多少电流。

 *

 * Returns zero on success, else negative errno.

 */

static inline int usb_gadget_vbus_draw(struct usb_gadget *gadget, unsigned mA)

{

       if (!gadget->ops->vbus_draw)

              return -EOPNOTSUPP;

       return gadget->ops->vbus_draw(gadget, mA);

}

 

/**

 * usb_gadget_vbus_disconnect - notify controller about VBUS session end

 * @gadget:the device whose VBUS supply is being described

 *

 * This call is used by a driver for an external transceiver (or GPIO)

 * that detects a VBUS power session ending.  Common responses include

 * reversing everything done in usb_gadget_vbus_connect().

 *

 * Returns zero on success, else negative errno.

 */

static inline int usb_gadget_vbus_disconnect(struct usb_gadget *gadget)

{

       if (!gadget->ops->vbus_session)

              return -EOPNOTSUPP;

       return gadget->ops->vbus_session(gadget, 0);

}

 

/**

 * usb_gadget_connect - software-controlled connect to USB host软件控制控制器连接到USB主机

 * @gadget:the peripheral being connected被连接的外设端

 *

 * Enables the D+ (or potentially D-) pullup.  The host will start

 * enumerating this gadget when the pullup is active and a VBUS session

 * is active (the link is powered).  This pullup is always enabled unless

 * usb_gadget_disconnect() has been used to disable it.使能D+(或D-)上拉，当上拉和VBUS激活后，主机开始枚举。它会一直上拉除非调用usb_gadget_disconnect()禁止它。

 *

 * Returns zero on success, else negative errno.

 */

static inline int usb_gadget_connect(struct usb_gadget *gadget)

{

       if (!gadget->ops->pullup)

              return -EOPNOTSUPP;

       return gadget->ops->pullup(gadget, 1);

}

 

/**

 * usb_gadget_disconnect - software-controlled disconnect from USB host软件控制控制器从USB主机断开

 * @gadget:the peripheral being disconnected被断开的外设端

 *

 * Disables the D+ (or potentially D-) pullup, which the host may see

 * as a disconnect (when a VBUS session is active).  Not all systems

 * support software pullup controls.撤销D+(或D-)上拉，主机会认为是一个断开。并不是所有的系统都支持软件控制上拉。

 *

 * This routine may be used during the gadget driver bind() call to prevent

 * the peripheral from ever being visible to the USB host, unless later

 * usb_gadget_connect() is called.  For example, user mode components may

 * need to be activated before the system can talk to hosts.这个例程会在gadget驱动的bind()函数被使用来阻止外设被USB主机看到，除非稍后usb_gadget_connect()被调用。

 *

 * Returns zero on success, else negative errno.

 */

static inline int usb_gadget_disconnect(struct usb_gadget *gadget)

{

       if (!gadget->ops->pullup)

              return -EOPNOTSUPP;

       return gadget->ops->pullup(gadget, 0);

}

 

/*-------------------------------------------------------------------------*/

/**

 * struct usb_gadget_driver - driver for usb 'slave' devices USB从设备驱动

 * @function: String describing the gadget's function 描述gadget功能的字符串

 * @speed: Highest speed the driver handles.USB速度

 * @bind: Invoked when the driver is bound to a gadget, usually

 *    after registering the driver. 当驱动被绑定到一个gadget时起作用，通常是在注册该驱动之后。

 *    At that point, ep0 is fully initialized, and ep_list holds

 *    the currently-available endpoints.

 *    Called in a context that permits sleeping.这个时候，ep0已经完全初始化，并且ep_list列出了所有当前可用的端点。调用该函数的时候允许睡眠

 * @setup: Invoked for ep0 control requests that aren't handled by

 *    the hardware level driver. Most calls must be handled by

 *    the gadget driver, including descriptor and configuration

 *    management.  The 16 bit members of the setup data are in

 *    USB byte order. Called in_interrupt; this may not sleep.  Driver

 *    queues a response to ep0, or returns negative to stall.使能ep0中不能由硬件层驱动处理的控制请求。大多数调用必须由gadget驱动处理，包括描述符和配置管理。16位setup数据成员用的是USB字节序。可以在中断中被调用，它可能不会睡眠。驱动把反馈加入到队列挥着返回一个负的错误代码来停止。

 * @disconnect: Invoked after all transfers have been stopped,

 *    when the host is disconnected.  May be called in_interrupt; this

 *    may not sleep.  Some devices can't detect disconnect, so this might

 *    not be called except as part of controller shutdown.当主机断开时，所有的传输停止后调用。可以在中断中调用，它可能不会睡眠。有些设备不能检测到断开，因此有时可能在控制器断开后不会被调用。

 * @unbind: Invoked when the driver is unbound from a gadget,

 *    usually from rmmod (after a disconnect is reported).

 *    Called in a context that permits sleeping.当驱动从gadget脱离后，一般是rmmod（当断开被报告后）。可以被上下文调用允许睡眠

 * @suspend: Invoked on USB suspend.  May be called in_interrupt.

 * @resume: Invoked on USB resume.  May be called in_interrupt.

 * @driver: Driver model state for this driver.该驱动的驱动模型

 *

 * Devices are disabled till a gadget driver successfully bind()s, which

 * means the driver will handle setup() requests needed to enumerate (and

 * meet "chapter 9" requirements) then do some useful work.设备是被禁止的知道一个gadget驱动成功bind(),这意味着驱动将会处理setup()的请求来进行枚举，然后做些有用的工作。

 *

 * If gadget->is_otg is true, the gadget driver must provide an OTG

 * descriptor during enumeration, or else fail the bind() call.  In such

 * cases, no USB traffic may flow until both bind() returns without

 * having called usb_gadget_disconnect(), and the USB host stack has

 * initialized.如果gadget->is_otg is true，gadget驱动必须在枚举过程中提供OTG描述符，否则会在调用bind()时失败。在这种情况下，不会有任何USB数据传输直到bind()返回且没有调用usb_gadget_disconnect(),同时USB主机栈已经初始化。

 *

 * Drivers use hardware-specific knowledge to configure the usb hardware.

 * endpoint addressing is only one of several hardware characteristics that

 * are in descriptors the ep0 implementation returns from setup() calls.驱动使用硬件具体相关来配置USB硬件端口。端口地址映射只能是几个硬件特征中的一个，这些硬件特征是在调用setup()函数后返回的ep0描述符。

 *

 * Except for ep0 implementation, most driver code shouldn't need change to

 * run on top of different usb controllers.  It'll use endpoints set up by

 * that ep0 implementation.除了ep0实例外，大多数驱动代码不需要在不同的USB控制器的运行过程中变化。

 *

 * The usb controller driver handles a few standard usb requests.  Those

 * include set_address, and feature flags for devices, interfaces, and

 * endpoints (the get_status, set_feature, and clear_feature requests).USB控制器驱动处理一些标准的usb请求，包括设置地址，设备特征标记，接口和端点等

 *

 * Accordingly, the driver's setup() callback must always implement all

 * get_descriptor requests, returning at least a device descriptor and

 * a configuration descriptor.  Drivers must make sure the endpoint

 * descriptors match any hardware constraints. Some hardware also constrains

 * other descriptors. (The pxa250 allows only configurations 1, 2, or 3).

 *

 * The driver's setup() callback must also implement set_configuration,

 * and should also implement set_interface, get_configuration, and

 * get_interface.  Setting a configuration (or interface) is where

 * endpoints should be activated or (config 0) shut down.

 *

 * (Note that only the default control endpoint is supported.  Neither

 * hosts nor devices generally support control traffic except to ep0.)

 *

 * Most devices will ignore USB suspend/resume operations, and so will

 * not provide those callbacks.  However, some may need to change modes

 * when the host is not longer directing those activities.  For example,

 * local controls (buttons, dials, etc) may need to be re-enabled since

 * the (remote) host can't do that any longer; or an error state might

 * be cleared, to make the device behave identically whether or not

 * power is maintained.

 */

struct usb_gadget_driver {

       char               *function;

       enum usb_device_speed speed;

       int                 (*bind)(struct usb_gadget *);

       void               (*unbind)(struct usb_gadget *);

       int                 (*setup)(struct usb_gadget *,

                                   const struct usb_ctrlrequest *);

       void               (*disconnect)(struct usb_gadget *);

       void               (*suspend)(struct usb_gadget *);

       void               (*resume)(struct usb_gadget *);

 

       /* FIXME support safe rmmod */

       struct device_driver       driver;

};