Documentation/usb/functionfs.txt

Chinese translated version of Documentation\Documentation/usb/functionfs.txt

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:朱伟婧  <313997199@qq.com>
---------------------------------------------------------------------
Documentation/usb/functionfs.txt的中文翻译

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

中文版维护者： 朱伟婧  <313997199@qq.com>
中文版翻译者： 朱伟婧  <313997199@qq.com>
中文版校译者： 朱伟婧  <313997199@qq.com>

以下为正文

  *How FunctionFS works*
 
  From kernel point of view it is just a composite function with some
  unique behaviour.  It may be added to an USB configuration only after
  the user space driver has registered by writing descriptors and
  strings (the user space program has to provide the same information
  that kernel level composite functions provide when they are added to
  the configuration).
 
  FunctionFS如何工作？
  从核心点是一些独特的行为的复合函数,它可能只有在用户空间驱动程序已经通过
  写描述符字符串注册添加到一个USB配置（当被添加到配置时，用户空间的程序必
  须提供内核级复合功能提供的相同的信息）

  This in particular means that the composite initialisation functions
  may not be in init section (ie. may not use the __init tag).
 
  From user space point of view it is a file system which when
  mounted provides an "ep0" file.  User space driver need to
  write descriptors and strings to that file.  It does not need
  to worry about endpoints, interfaces or strings numbers but
  simply provide descriptors such as if the function was the
  only one (endpoints and strings numbers starting from one and
  interface numbers starting from zero).  The FunctionFS changes
  them as needed also handling situation when numbers differ in
  different configurations.
 
  这个特别意味着复合初始化功能可能无法初始部分（即不可使用__init标签）。

  从用户空间的观点来看这是一个文件系统，安装时提供了一个“ep0”的文件。
  用户空间驱动程序需要写描述符和字符串。它不需要担心端点，接口或字符串数
  只提供描述例如函数是唯一一个（端点和字符串数据从一开始，接口数从零开始）
  当数和不同的配置不一样的时候，该FunctionFS 改变他们需要同时处理情况

  When descriptors and strings are written "ep#" files appear
  (one for each declared endpoint) which handle communication on
  a single endpoint.  Again, FunctionFS takes care of the real
  numbers and changing of the configuration (which means that
  "ep1" file may be really mapped to (say) endpoint 3 (and when
  configuration changes to (say) endpoint 2)).  "ep0" is used
  for receiving events and handling setup requests.

  When all files are closed the function disables itself.
 
  What I also want to mention is that the FunctionFS is designed in such
  a way that it is possible to mount it several times so in the end
  a gadget could use several FunctionFS functions. The idea is that
  each FunctionFS instance is identified by the device name used
  when mounting.
  当被写入“ep#”文件（一个端点）的描述符和字符串出现时，是处理一个单一的端点的通信。
  再者，FunctionFS 需要考虑实际数量和形态变化（即“ep1”文件可能真正映射到终点3（当配置更改为端点2））。
  ”ep0”用于接收事件和处理设置请求。

  当所有的文件都关闭禁用自身功能。

  我还想说的是，FunctionFS是这样一种方式，它可以安装它好几次，
  所以最后一个小工具可以使用几种FunctionFS功能设计。
  这个想法是，每一FunctionFS实例由设备名称在安装时发现的。

  One can imagine a gadget that has an Ethernet, MTP and HID interfaces
  where the last two are implemented via FunctionFS.  On user space
  level it would look like this:
 
  $ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid
  $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp
  $ ( cd /dev/ffs-mtp && mtp-daemon ) &
  $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid
  $ ( cd /dev/ffs-hid && hid-daemon ) &
 
  On kernel level the gadget checks ffs_data->dev_name to identify
  whether it's FunctionFS designed for MTP ("mtp") or HID ("hid").
 
  If no "functions" module parameters is supplied, the driver accepts
  just one function with any name.
 
  可以想象一个小工具，以太网，MTP和HID接口，最后两个是通过FunctionFS。在用户空间的水平，它看起来像这样：
  $ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid
  $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp
  $ ( cd /dev/ffs-mtp && mtp-daemon ) &
  $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid
  $ ( cd /dev/ffs-hid && hid-daemon ) &
  内核级小工具检查ffs_data -> dev_name鉴定是否functionfs设计的MTP（“MTP”）或ID ("hid")。
  如果没有“functions”模块参数提供，驱动接受任何名字只作为一个函数。

  When "functions" module parameter is supplied, only functions
  with listed names are accepted. In particular, if the "functions"
  parameter's value is just a one-element list, then the behaviour
  is similar to when there is no "functions" at all; however,
  only a function with the specified name is accepted.
 
  The gadget is registered only after all the declared function
  filesystems have been mounted and USB descriptors of all functions
  have been written to their ep0's.
 
  Conversely, the gadget is unregistered after the first USB function
  closes its endpoints.
 
  当“functions"”模块参数被应用的时候，仅仅列出名字的函数能被接受。
  特别是，如果“functions"”参数的值是一个元素的列表，然后行为是相似的，没有“functions”；
  然而，只有具有指定名称的函数是可接受的。
  这种工具只有在所有声明的函数文件系统已安装的所有功能的USB描述符已被写入EP0的才被注册。
  相反，这种工具在USB功能关闭其端点情况下不被注册。