Documentation_driver-model_device.txt

Chinese translated version of Documentation/driver-model/device


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: 李仁亨 <154778998@qq.com>
---------------------------------------------------------------------
Documentation/driver-model/device 的中文翻译


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


中文版维护者： 李仁亨  <154778998@qq.com>
中文版翻译者： 李仁亨  <154778998@qq.com>
中文版校译者： 李仁亨  <154778998@qq.com>




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


The Basic Device Structure
基本的设备结构体
~~~~~~~~~~~~~~~~~~~~~~~~~~


See the kerneldoc for the struct device.
见结构设备的内核文档。


Programming Interface
编程接口
~~~~~~~~~~~~~~~~~~~~~
The bus driver that discovers the device uses this to register the
device with the core:
发现设备的总线驱动使用下面这个接口将设备注册到内核：


int device_register(struct device * dev);


The bus should initialize the following fields:
总线应该初始化该设备的以下这些字段：


    - parent
    - name
    - bus_id
    - bus


A device is removed from the core when its reference count goes to
0. The reference count can be adjusted using:


当一个设备的引用计数变为0时，该设备需从内核中移除。设备的引用计数
可以使用下面的借口改变：


struct device * get_device(struct device * dev);
void put_device(struct device * dev);


get_device() will return a pointer to the struct device passed to it
if the reference is not already 0 (if it's in the process of being
removed already).
如果引用计数不为0（已经在移除的过程中），get_device()会返回一个指向传
递给它的 struct device 的指针。


A driver can access the lock in the device structure using: 
一个驱动可以使用以下接口访问设备体的 lock：


void lock_device(struct device * dev);
void unlock_device(struct device * dev);




Attributes
属性
~~~~~~~~~~
struct device_attribute {
struct attribute attr;
ssize_t (*show)(struct device *dev, struct device_attribute *attr,
char *buf);
ssize_t (*store)(struct device *dev, struct device_attribute *attr,
const char *buf, size_t count);
};


Attributes of devices can be exported by a device driver through sysfs.
设备驱动可以通过 sysfs 设备的属性导出。


Please see Documentation/filesystems/sysfs.txt for more information
on how sysfs works.
更多关于 sysfs 如何工作的内容，请参考Documentation/filesystems/sysfs.txt。


As explained in Documentation/kobject.txt, device attributes must be be
created before the KOBJ_ADD uevent is generated. The only way to realize
that is by defining an attribute group.
如 Documentation/kobject.txt 中介绍，设备的属性必须在 KOBJ_ADD uevent 生成
之前创建。实现这个的唯一方法就是定义一个属性组。


Attributes are declared using a macro called DEVICE_ATTR:
属性通过使用宏函数 DEVICE_ATTR 声明：


#define DEVICE_ATTR(name,mode,show,store)


Example:
示例：


static DEVICE_ATTR(type, 0444, show_type, NULL);
static DEVICE_ATTR(power, 0644, show_power, store_power);


This declares two structures of type struct device_attribute with respective
names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be
organized as follows into a group:
上例声明了两个分别名为 'dev_attr_type' 和 'dev_attr_power' 的 
struct device_attribute 类型的结构体。这两个属性可以像下面这样组织到一起：


static struct attribute *dev_attrs[] = {
&dev_attr_type.attr,
&dev_attr_power.attr,
NULL,
};


static struct attribute_group dev_attr_group = {
.attrs = dev_attrs,
};


static const struct attribute_group *dev_attr_groups[] = {
&dev_attr_group,
NULL,
};


This array of groups can then be associated with a device by setting the
group pointer in struct device before device_register() is invoked:
这个 groups 的数组在 device_register() 调用之前可以通过设置 group指针
联系到一个设备上：




      dev->groups = dev_attr_groups;
      device_register(dev);


The device_register() function will use the 'groups' pointer to create the
device attributes and the device_unregister() function will use this pointer
to remove the device attributes.
device_register() 函数将使用 'groups' 指针创建设备属性，device_unregister() 
将使用这个指针来移除这个设备属性。


Word of warning:  While the kernel allows device_create_file() and
device_remove_file() to be called on a device at any time, userspace has
strict expectations on when attributes get created.  When a new device is
registered in the kernel, a uevent is generated to notify userspace (like
udev) that a new device is available.  If attributes are added after the
device is registered, then userspace won't get notified and userspace will
not know about the new attributes.
提醒：尽管内核允许在任何时候在一个设备上调用 device_create_file()
和 device_remove_file()，但用户空间严格期望得知设备属性在何时被创建。
当一个新的设备注册进内核时，就会生成一个 uevent 事件并通知用户空间(如 udev)
有一个新设备可用。但如果设备的属性是在设备注册之后才添加的话，那么用户空间将
不会得到通知，也就不知道这个新的属性。


This is important for device driver that need to publish additional
attributes for a device at driver probe time.  If the device driver simply
calls device_create_file() on the device structure passed to it, then
userspace will never be notified of the new attributes.
对于在驱动探测时需要发布附加属性的设备驱动程序来说这是十分重要的。如果设备
驱动程序只是简单地在传递给它的设备结构体上调用 device_create_file() 的话，
用户空间就永远不会得到新属性的通知。