Documentation/usb/callbacks

Chinese translated version of Documentation/00-INDEX

If you have any comment or update to the content, please contact the
original document maintainer directly.  However, if you have a problem
communicating in English you can also ask the Chinese maintainer for
help.  Contact the Chinese maintainer if this translation is outdated
or if there is a problem with the translation.

Chinese maintainer: LiuLu <541748097@qq.com>
---------------------------------------------------------------------
Documentation/00-INDEX 的中文翻译

如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
译存在问题，请联系中文版维护者。

中文版维护者： 刘璐  <541748097@qq.com>
中文版翻译者： 刘璐  <541748097@qq.com>
中文版校译者： 刘璐  <541748097@qq.com>

What callbacks will usbcore do?
usbcore会做什么样的回调?
===============================


Usbcore will call into a driver through callbacks defined in the driver
structure and through the completion handler of URBs a driver submits.
Only the former are in the scope of this document. These two kinds of
callbacks are completely independent of each other. Information on the
completion callback can be found in Documentation/usb/URB.txt.
Usbcore将通过在驱动程序中定义的回调结构调用驱动程序，并通过完成处理URB的
驱动程序提交。只有前者是在本文的讨论范围。这两种回调是完全相互独立的。在
完成回调中的以上信息可以在Documentation/usb/usb.txt找到的。


The callbacks defined in the driver structure are:
驱动程序的结构中定义的回调函数：


1. Hotplugging callbacks:
   热插拔回调


 * @probe: Called to see if the driver is willing to manage a particular
 * interface on a device.
    探测器：来检查驱动是否在管理特定的接口的设备上。
 * @disconnect: Called when the interface is no longer accessible, usually
 * because its device has been (or is being) disconnected or the
 * driver module is being unloaded.
    未连接：当接口不再可以访问，通常是因为它的设备已经（或正在）断开或正在卸载的驱动模块。
2. Odd backdoor through usbfs:
   奇后门USBF


 * @ioctl: Used for drivers that want to talk to userspace through
 * the "usbfs" filesystem.  This lets devices provide ways to
 * expose information to user space regardless of where they
 * do (or don't) show up otherwise in the filesystem.
        用于通过“USBFS”的文件系统的驱动程序来谈论用户空间。这让设备提供到用户空间的方式
来公开信息，不管他们在哪里做（或没有），否则显示文件系统中的其他信息。


3. Power management (PM) callbacks:
   电源管理（PM）回调


 * @suspend: Called when the device is going to be suspended.
             当设备将被暂停时调用
 * @resume: Called when the device is being resumed.
             当设备恢复时被调用
 * @reset_resume: Called when the suspended device has been reset instead
 * of being resumed.
             当悬浮装置已经复位，而不是被恢复时被调用。


4. Device level operations:
   设备等级操作


 * @pre_reset: Called when the device is about to be reset.
               当设备准备复位时被调用。
 * @post_reset: Called after the device has been reset
               当设备复位后被调用。
The ioctl interface (2) should be used only if you have a very good
reason. Sysfs is preferred these days. The PM callbacks are covered
separately in Documentation/usb/power-management.txt.
只有当你有一些好的理由时，ioctl接口（2）会被使用。现在 Sysfs 是首选的。
在Documentation/usb/power-management.txt中 PM回调被分开覆盖。


Calling conventions
调用约定
===================


All callbacks are mutually exclusive. There's no need for locking
against other USB callbacks. All callbacks are called from a task
context. You may sleep. However, it is important that all sleeps have a
small fixed upper limit in time. In particular you must not call out to
user space and await results.
所有的回调函数是相互排斥的。就没有必要锁定对其他USB回调。所有的回调函数中
调用任务上下文。您可以睡觉。然而，重要的是所有的睡眠有一个小的固定上限时间。
特别是，你必须不叫出来用户空间，并等待结果。


Hotplugging callbacks
热插拔回调
=====================


These callbacks are intended to associate and disassociate a driver with
an interface. A driver's bond to an interface is exclusive.
这些回调关联和撇清驱动程序一个接口。一个驱动债券的接口是独占的。


The probe() callback
探测器回调
--------------------


int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);


Accept or decline an interface. If you accept the device return 0,
otherwise -ENODEV or -ENXIO. Other error codes should be used only if a
genuine error occurred during initialisation which prevented a driver
from accepting a device that would else have been accepted.
You are strongly encouraged to use usbcore's facility,
usb_set_intfdata(), to associate a data structure with an interface, so
that you know which internal state and identity you associate with a
particular interface. The device will not be suspended and you may do IO
to the interface you are called for and endpoint 0 of the device. Device
initialisation that doesn't take too long is a good idea here.
接受或拒绝一个接口。如果您接受设备返回0，否则返回-ENODEV或-ENXIO。其他错
误代码仅仅是如果正版阻止驱动程序的初始化过程中出现错误而接受一种装置，将其
他错误代码接受。强烈建议您使用usbcore设施，usb_set_intfdat（），与接口相关联
的数据结构，所以你知道你的内部状态和身份与关联特定的接口。该设备不会被暂
停，你可以做IO被称为接口和端点0的设备。设备初始化时，不要太长，这是一个好主意。


The disconnect() callback
未连接回调
-------------------------


void (*disconnect) (struct usb_interface *intf);


This callback is a signal to break any connection with an interface.
You are not allowed any IO to a device after returning from this
callback. You also may not do any other operation that may interfere
with another driver bound the interface, eg. a power management
operation.
这个回调是一个信号，打破任何一个接口连接。你不允许任何IO从这个回调返
回之后到达设备。你也可能不会做任何其他操作，可能会干扰另一个绑定的接
口的驱动程序，例如。电源管理操作。


If you are called due to a physical disconnection, all your URBs will be
killed by usbcore. Note that in this case disconnect will be called some
time after the physical disconnection. Thus your driver must be prepared
to deal with failing IO even prior to the callback.
如果由于一个物理断开，那你所有的URB的将被usbcore扼杀。请注意，这种情况下，
在物理连接断开之后，未连接将会被调度一段时间。因此，你的驱动必须准备处理
失败的IO甚至是在回调之前。


Device level callbacks
设备等级回调
======================


pre_reset
---------


int (*pre_reset)(struct usb_interface *intf);


A driver or user space is triggering a reset on the device which
contains the interface passed as an argument. Cease IO, wait for all
outstanding URBs to complete, and save any device state you need to
restore.  No more URBs may be submitted until the post_reset method
is called.
一个驱动或用户空间在包含接口作为参数传递触发设备上复位。停止IO，等待所有
优秀的URB的来完成的，你需要还原并且保存的任何设备状态。没有更多的可提交
URB的直到post_reset方法被调用。


If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
are in atomic context.
如果您需要在这里分配内存，如果你在原子上下文中，使用GFP_NOIO或GFP_ATOMIC。


post_reset
----------


int (*post_reset)(struct usb_interface *intf);


The reset has completed.  Restore any saved device state and begin
using the device again.
重新设置完成。恢复任何保存的设备状态，并开始再次使用该设备。


If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
are in atomic context.
如果您需要在这里分配内存，如果你在原子上下文中，使用GFP_NOIO或GFP_ATOMIC。


Call sequences
调度序列
==============


No callbacks other than probe will be invoked for an interface
that isn't bound to your driver.
没有探头以外的回调函数将被调用一个绑定到你的驱动程序的接口。


Probe will never be called for an interface bound to a driver.
Hence following a successful probe, disconnect will be called
before there is another probe for the same interface.
探头将永远不会被调用来让接口绑定到驱动程序。因此，探测成功后，
将被称为断开之前还有另一个探头相同的接口。


Once your driver is bound to an interface, disconnect can be
called at any time except in between pre_reset and post_reset.
pre_reset is always followed by post_reset, even if the reset
failed or the device has been unplugged.
一旦你的驱动程序绑定到某个接口，除了在pre_reset和post_reset之间
可以在任何时候跟pre_reset post_reset之后进行未连接调度。即使复位
失败或设备已被拔掉。


suspend is always followed by one of: resume, reset_resume, or
disconnect.
暂停总是在这其中一个之后：resume，reset_resume或
disconnect。