Documentation_driver-model_bus.txt

Documentation_driver-model_bus.txt

Chinese translated version of Documentation/CodingStyle

 

If you have any comment or update to the content, please post to LKML directly.

However, if you have problem communicating in English you can also ask the

Chinese maintainer for help. Contact the Chinese maintainer, if this

translation is outdated or there is problem with translation.

 

Chinese maintainer: lin wei 

---------------------------------------------------------------------

Documentation/CodingStyle的中文翻译

 

如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可

以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。

 

以下为正文

---------------------------------------------------------------------

Bus Types

总线类型

Definition

定义

~~~~~~~~~~

See the kerneldoc for the struct bus_type.

请从kerneldoc查阅bus_type这个结构

int bus_register(struct bus_type * bus);

 

 

Declaration

声明

~~~~~~~~~~~

 

Each bus type in the kernel (PCI, USB, etc) should declare one static

object of this type. They must initialize the name field, and may

optionally initialize the match callback.

在内核中的每个总线类型（ PCI ， USB等）应宣布一个静态的此类对象。

他们必须初始化名字域，和有选择性的初始化相应的回调函数

 

struct bus_type pci_bus_type = {

       .name       = "pci",

       .match       = pci_bus_match,

};

 

The structure should be exported to drivers in a header file:

该结构应该在头文件输出给驱动程序

extern struct bus_type pci_bus_type;

外部结构 bus_type pci_bus_type;

 

Registration

注册

~~~~~~~~~~~~

 

When a bus driver is initialized, it calls bus_register. This

initializes the rest of the fields in the bus object and inserts it

into a global list of bus types. Once the bus object is registered,

the fields in it are usable by the bus driver.

当一个总线驱动被初始化,它调用bus_register。

这个初始化总线对象的其余字段插入到一个全局总线类型表

一旦这个总线类型被注册，这个对象的字段就能被总线驱动使用

 

Callbacks

回调

~~~~~~~~~

 

match(): Attaching Drivers to Devices

匹配：给设备添配驱动

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 

The format of device ID structures and the semantics for comparing

them are inherently bus-specific. Drivers typically declare an array

of device IDs of devices they support that reside in a bus-specific

driver structure.

设备的ID结构和其相对意义

它们本质上是针对不同总线。设备通常声明一个设备ID数组来支持驻留在

特定总线上的驱动结构

 

The purpose of the match callback is provide the bus an opportunity to

determine if a particular driver supports a particular device by

comparing the device IDs the driver supports with the device ID of a

particular device, without sacrificing bus-specific functionality or

type-safety.

匹配回调的目的是在在不牺牲总线特定功能的或类型安全的情况下。

让总线有机会通过比较驱动所支持的设备ID组和设备的独特ID来去顶是否存在

一个特定的驱动来支持该设备

When a driver is registered with the bus, the bus's list of devices is

iterated over, and the match callback is called for each device that

does not have a driver associated with it.

当一个驱动在总线上被注册时，这个总线设备表被遍历。即匹配回调函数被

任一一个没有关联这个驱动的设备调用

 

 

Device and Driver Lists

设备和驱动程序列表

~~~~~~~~~~~~~~~~~~~~~~~

 

The lists of devices and drivers are intended to replace the local

lists that many buses keep. They are lists of struct devices and

struct device_drivers, respectively. Bus drivers are free to use the

lists as they please, but conversion to the bus-specific type may be

necessary.

这个设备和驱动表是为了替换本地多数总线所持有的表。它罗列了设备结构

和设备驱动的机构。个别来说，总线驱动能够随意使用这个表，但是可能

需要先转换成特定的总线类型。

The LDM core provides helper functions for iterating over each list.

LDM内核提供了帮助函数去遍历每一个表

int bus_for_each_dev(struct bus_type * bus, struct device * start, void * data,

                   int (*fn)(struct device *, void *));

 

int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,

                   void * data, int (*fn)(struct device_driver *, void *));

 

These helpers iterate over the respective list, and call the callback

for each device or driver in the list. All list accesses are

synchronized by taking the bus's lock (read currently). The reference

count on each object in the list is incremented before the callback is

called; it is decremented after the next object has been obtained. The

lock is not held when calling the callback.

这些辅助函数遍历各自的表单，并为每一个表单上的设备或者驱动调用回调函数

所有表单的访问需要通过总线同步锁（当前为读）。在调用回调函数之前参考

值根据表中每一个对象递增。在取得下一个对象的时候递减。这个锁在调用回调

函数时不被执行。

sysfs

~~~~~~~~

There is a top-level directory named 'bus'.

这是一个叫做总线的顶层目录。

Each bus gets a directory in the bus directory, along with two default

directories:

每个总线有总线目录中的一个目录，以及两个默认的目录：

       /sys/bus/pci/

       |-- devices

       `-- drivers

 

Drivers registered with the bus get a directory in the bus's drivers

directory:

总线上的已注册驱动 拥有一个目录在总线驱动目录上：

 

       /sys/bus/pci/

       |-- devices

       `-- drivers

           |-- Intel ICH

           |-- Intel ICH Joystick

           |-- agpgart

           `-- e100

 

Each device that is discovered on a bus of that type gets a symlink in

the bus's devices directory to the device's directory in the physical

hierarchy:

每一个设备在总线上被发现是通过一个符号链接来

实现从总线设备目录到物理层上的设备目录

       /sys/bus/pci/

       |-- devices

       |   |-- 00:00.0 -> ../../../root/pci0/00:00.0

       |   |-- 00:01.0 -> ../../../root/pci0/00:01.0

       |   `-- 00:02.0 -> ../../../root/pci0/00:02.0

       `-- drivers

 

 

Exporting Attributes

~~~~~~~~~~~~~~~~~~~~

struct bus_attribute {

       struct attribute       attr;

       ssize_t (*show)(struct bus_type *, char * buf);

       ssize_t (*store)(struct bus_type *, const char * buf, size_t count);

};

 

Bus drivers can export attributes using the BUS_ATTR macro that works

similarly to the DEVICE_ATTR macro for devices. For example, a definition

like this:

总线设备能够使用类似于设备上的DEVICE_ATTR宏一样的BUS_ATTR的宏来导出属性

比如，像这样定义：

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

 

is equivalent to declaring:

 

static bus_attribute bus_attr_debug;

 

This can then be used to add and remove the attribute from the bus's

sysfs directory using:

这可以用来添加和删除属性总线的sysfs目录使用：

 

int bus_create_file(struct bus_type *, struct bus_attribute *);

void bus_remove_file(struct bus_type *, struct bus_attribute *);