Documentation-driver-model-class.txt

Chinese translated version of Documentation/driver-model/class.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.


Maintainer: Eric W. Biederman <ebiederman@xmission.com>
Chinese maintainer: Shao Qi <shaoqitony@gmail.com>
---------------------------------------------------------------------
Documentation/driver-model/class.txt 的中文翻译


如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
译存在问题，请联系中文版维护者。
英文版维护者： Eric W. Biederman <ebiederman@xmission.com>
中文版维护者： 邵奇 Shao Qi <shaoqitony@gmail.com>
中文版翻译者： 邵奇 Shao Qi <shaoqitony@gmail.com>
中文版校译者： 邵奇 Shao Qi <shaoqitony@gmail.com>


以下为正文
---------------------------------------------------------------------






Device Classes
设备类


Introduction
介绍
~~~~~~~~~~~~
A device class describes a type of device, like an audio or network
device. The following device classes have been identified:
设备类描述了设备类型，如音频或网络设备。以下设备类已经被确定：


<Insert List of Device Classes Here>
<在这里插入设备类的清单>


Each device class defines a set of semantics and a programming interface
that devices of that class adhere to. Device drivers are the
implementation of that programming interface for a particular device on
a particular bus. 
每个设备类定义了这类设备都遵从的一组语义和一个编程接口。
设备驱动是特定总线上特定设备的编程接口的实现。
Device classes are agnostic with respect to what bus a device resides
on. 
对于设备在总线上的位置，设备类是不知道的。


Programming Interface
编程接口
~~~~~~~~~~~~~~~~~~~~~
The device class structure looks like: 
设备类的结构像是这样：




typedef int (*devclass_add)(struct device *);
typedef void (*devclass_remove)(struct device *);


See the kerneldoc for the struct class.
结构类的内容请看kerleldoc。


A typical device class definition would look like: 
一个典型的设备类定义像是这样：


struct device_class input_devclass = {
        .name = "input",
        .add_device = input_add_device,
.remove_device = input_remove_device,
};


Each device class structure should be exported in a header file so it
can be used by drivers, extensions and interfaces.
每个设备类结构要被输出在一个头文件里，这样就能被驱动程序，扩展程序和接口所使用。


Device classes are registered and unregistered with the core using: 
注册、未注册设备类的核心用法：
int devclass_register(struct device_class * cls);
void devclass_unregister(struct device_class * cls);




Devices
设备
~~~~~~~
As devices are bound to drivers, they are added to the device class
that the driver belongs to. Before the driver model core, this would
typically happen during the driver's probe() callback, once the device
has been initialized. It now happens after the probe() callback
finishes from the core. 
由于设备必须要有驱动程序，所以他们被添加到该驱动程序所属的设备类中。一旦
设备被初始化，在驱动模式核心之前，这通常将在设备的probe() callback期间发生。
现在它在probe() callback从核心结束之后发生。


The device is enumerated in the class. Each time a device is added to
the class, the class's devnum field is incremented and assigned to the
device. The field is never decremented, so if the device is removed
from the class and re-added, it will receive a different enumerated
value. 
设备在设备类中被赋予枚举值。每次设备被添加到类中，该类的devnum字段值增加，并且被分配给
这个设备。这个字段值从不减少，所以，如果该设备从类中被移除后再添加，它将得到
一个不同的枚举值。


The class is allowed to create a class-specific structure for the
device and store it in the device's class_data pointer. 
设备类允许为设备创建一个特定类结构，并存储在设备的class_data pointer中。


There is no list of devices in the device class. Each driver has a
list of devices that it supports. The device class has a list of
drivers of that particular class. To access all of the devices in the
class, iterate over the device lists of each driver in the class.
在设备类中没有设备列表。每一个驱动有一张它所支持设备的列表。设备类有特殊类
的驱动的列表。
要访问设备类中所有的设备，那就遍历类中每一个驱动所支持的设备名单。


Device Drivers
设备驱动
~~~~~~~~~~~~~~
Device drivers are added to device classes when they are registered
with the core. A driver specifies the class it belongs to by setting
the struct device_driver::devclass field. 
当设备驱动在核心被注册时，它们被添加到设备类中。通过下面的代码，驱动
程序指定它所属的类
the struct device_driver::devclass field. 




sysfs directory structure
sysfs 目录结构
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There is a top-level sysfs directory named 'class'. 
有一个命名为class的顶级sysfs目录


Each class gets a directory in the class directory, along with two
default subdirectories:
这个类在类目录中有目录，连同两个默认的子目录：


        class/
        `-- input
            |-- devices
            `-- drivers




Drivers registered with the class get a symlink in the drivers/ directory 
that points to the driver's directory (under its bus directory):
登记于类中的驱动在驱动/目录中获得指向驱动目录（在它的总线目录下）的符号
链接：


   class/
   `-- input
       |-- devices
       `-- drivers
           `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/




Each device gets a symlink in the devices/ directory that points to the 
device's directory in the physical hierarchy:
每一个设备在驱动/目录中获得指向物理层次中设备目录的符号链接：


   class/
   `-- input
       |-- devices
       |   `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/
       `-- drivers




Exporting Attributes
输出属性
~~~~~~~~~~~~~~~~~~~~
struct devclass_attribute {
        struct attribute        attr;
        ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);
        ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off);
};


Class drivers can export attributes using the DEVCLASS_ATTR macro that works
similarly to the DEVICE_ATTR macro for devices. For example, a definition 
like this:
类驱动能用，同为设备工作的DEVICE_ATTR宏一样的DEVCLASS_ATTR宏输出属性。比如，像这样的定义：


static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);


is equivalent to declaring:
等同于声明：


static devclass_attribute devclass_attr_debug;


The bus driver can add and remove the attribute from the class's
sysfs directory using:
总线驱动能加减类sysfs中的属性，如下所示:


int devclass_create_file(struct device_class *, struct devclass_attribute *);
void devclass_remove_file(struct device_class *, struct devclass_attribute *);


In the example above, the file will be named 'debug' in placed in the
class's directory in sysfs. 
在上面的例子中，文件将被命名为debug，置于sysfs的类目录中。


Interfaces
接口
~~~~~~~~~~
There may exist multiple mechanisms for accessing the same device of a
particular class type. Device interfaces describe these mechanisms. 
要访问一个特殊类模式的同种设备，存在多重机制。设备接口描述这些机制。


When a device is added to a device class, the core attempts to add it
to every interface that is registered with the device class.
当一个设备被添加到设备类中，核心尝试去将它添加到每一个在设备类中登记的接口。