Linux 内核文档翻译

原文地址：Linux 内核文档翻译 - kobject.txt 作者：qh997

Everything you never wanted to know about kobjects, ksets, and ktypes

你永远不会想知道的关于 kobject，kset 和 ktype 的一切

 

Greg Kroah-Hartman

 

Based on an original article by Jon Corbet for lwn.net written October 1,

2003 and located at http://lwn.net/Articles/51437/

 

Last updated December 19, 2007

 

 

Part of the difficulty in understanding the driver model - and the kobject

abstraction upon which it is built - is that there is no obvious starting

place. Dealing with kobjects requires understanding a few different types,

all of which make reference to each other. In an attempt to make things

easier, we'll take a multi-pass approach, starting with vague terms and

adding detail as we go. To that end, here are some quick definitions of

some terms we will be working with.

理解那些建立在 kobject 抽象之上的驱动模型的困难之一就是没有一个明确的入口。

使用 kobject 需要了解几种不同的类型，而这些类型又会相互引用。为了让这一切变

得简单些，我们将采取多通道方法，以模糊的术语开始，然后逐渐添加细节。为此，

现在给出一些今后会使用到的一些术语的简单定义。

 

 - A kobject is an object of type struct kobject.  Kobjects have a name

   and a reference count.  A kobject also has a parent pointer (allowing

   objects to be arranged into hierarchies), a specific type, and,

   usually, a representation in the sysfs virtual filesystem.

－ kobject 是一个 struct kobject 类型的对象。kobject 包含一个名字和一个

   引用计数。同时一个 kobject 还包含一个父指针（允许对象被安排成层次结构）、

   一个特定的类型，通常情况下还有一个在 sysfs 虚拟文件系统里的表现。

 

   Kobjects are generally not interesting on their own; instead, they are

   usually embedded within some other structure which contains the stuff

   the code is really interested in.

   通常我们并不关注 kobject 本身，而应该关注那些嵌入了 kobject 的那些结构体。

 

   No structure should EVER have more than one kobject embedded within it.

   If it does, the reference counting for the object is sure to be messed

   up and incorrect, and your code will be buggy.  So do not do this.

   任何结构体都不允许包含一个以上的 kobject。如果这么做，那么引用计数将肯

   定会出

   错，你的代码也将bug 百出。所以千万别这么做。

 

 - A ktype is the type of object that embeds a kobject.  Every structure

   that embeds a kobject needs a corresponding ktype.  The ktype controls

   what happens to the kobject when it is created and destroyed.

－ ktype 是嵌入了 kobject 的对象的类型。每个嵌入了 kobject 的对象都需要一个

   相应的 ktype。ktype 用来控制当 kobject 创建和销毁时所发生的操作。

 

 - A kset is a group of kobjects.  These kobjects can be of the same ktype

   or belong to different ktypes.  The kset is the basic container type for

   collections of kobjects. Ksets contain their own kobjects, but you can

   safely ignore that implementation detail as the kset core code handles

   this kobject automatically.

－ kset 是 kobject 的一组集合。这些 kobject 可以是同样的 ktype，也可以分别

   属于不同的 ktype。kset 是 kobject 集合的基本容器类型。kset 也包含它们自

   己的 kobject，但是你可以放心的忽略这些 kobjects，因为 kset 的核心代码会

   自动处理这些 kobject。

 

   When you see a sysfs directory full of other directories, generally each

   of those directories corresponds to a kobject in the same kset.

   当你看到一个 sysfs 目录里全都是其它目录时，通常每一个目录都对应着一个在

   同一个kset 里的 kobject。

 

We'll look at how to create and manipulate all of these types. A bottom-up

approach will be taken, so we'll go back to kobjects.

我们来看看如何创建和操作所有的这些类型。因为采用自下而上的方法，所以我们

首先回到 kobject。

 

 

Embedding kobjects

内嵌 kobject

 

It is rare for kernel code to create a standalone kobject, with one major

exception explained below.  Instead, kobjects are used to control access to

a larger, domain-specific object.  To this end, kobjects will be found

embedded in other structures.  If you are used to thinking of things in

object-oriented terms, kobjects can be seen as a top-level, abstract class

from which other classes are derived.  A kobject implements a set of

capabilities which are not particularly useful by themselves, but which are

nice to have in other objects.  The C language does not allow for the

direct expression of inheritance, so other techniques - such as structure

embedding - must be used.

就内核代码而言，基本上不会创建一个单独的 kobject，但也有例外，这以后再说。

其实，kobject 通常被用来控制一个更大的特定域对象。因此你将发现 kobject 都被

嵌入到了其他的结构体当中。如果从面向对象的观点出发，那么 kobject 可以被看做

是被其他类继承的、顶层的、抽象的类。一个 kobject 实现了一组对于它们自己不是

很有用，但对那些包含了这个 kobject 的对象很有用的功能。另外 C 语言不支持直接

使用继承，所以必须依靠其他的技术来实现，比如结构体嵌套。

 

(As an aside, for those familiar with the kernel linked list implementation,

this is analogous as to how "list_head" structs are rarely useful on

their own, but are invariably found embedded in the larger objects of

interest.)

（顺便说一句，对于那些熟悉内核链表实现的同志来说，这和“list_head”结构体很

类似。它们都是本身没什么用，其真正的价值是在嵌套进一个更大的结构体中才得以

体现。）

 

So, for example, the UIO code in drivers/uio/uio.c has a structure that

defines the memory region associated with a uio device:

举一个例子，drivers/uio/uio.c 里的 UIO 代码包含一个定义了内存区域的 uio 设备。

 

struct uio_map {
    struct kobject kobj;
    struct uio_mem *mem;
};

 

If you have a struct uio_map structure, finding its embedded kobject is

just a matter of using the kobj member.  Code that works with kobjects will

often have the opposite problem, however: given a struct kobject pointer,

what is the pointer to the containing structure?  You must avoid tricks

(such as assuming that the kobject is at the beginning of the structure)

and, instead, use the container_of() macro, found in :

如果你有一个 struct uio_map 结构体，使用它的成员 kobj 就能找到嵌套的 kobject。

但是操作 kobject 的代码往往会引出一个相反的问题：如果给定一个 struct kobject

指针，那么包含这个指针的结构体又是什么呢？别投机取巧（比如假设这个 kobject

是该结构体的第一个字段），你应该使用 container_of() 宏函数：

container_of(pointer, type, member)

where:

其中：

 

  * "pointer" is the pointer to the embedded kobject,

  * "type" is the type of the containing structure, and

  * "member" is the name of the structure field to which "pointer" points.

 ＊ "pointer" 被嵌入的 kobject。

 ＊ "type" 包含 kobject 的结构体类型。

 ＊ "member" 该结构体中指向 kobject 指针的字段名。

 

The return value from container_of() is a pointer to the corresponding

container type. So, for example, a pointer "kp" to a struct kobject

embedded *within* a struct uio_map could be converted to a pointer to the

*containing* uio_map structure with:

container_of() 的返回值就是一个相应结构体的指针。例如，一个指向嵌套在 uio_map

里的 struct kobject 的指针“kp”，可以这样获得包含它的结构体的指针： 

struct uio_map *u_map = container_of(kp, struct uio_map, kobj);

 

For convenience, programmers often define a simple macro for "back-casting"

kobject pointers to the containing type.  Exactly this happens in the

earlier drivers/uio/uio.c, as you can see here:

为方便起见，程序员通常会定义一个简单的宏，用于“反指”包含这个 kobject 的容器

类型指针。正因为这样，在以前的文件 drivers/uio/uio.c 中你可以看到：

 

struct uio_map {
    struct kobject kobj;
    struct uio_mem *mem;
};

#define to_map(map) container_of(map, struct uio_map, kobj)

 

where the macro argument "map" is a pointer to the struct kobject in

question.  That macro is subsequently invoked with:

宏参数“map”是一个指向 struct kobject 的指针。这个宏函数将随后被调用：

struct uio_map *map = to_map(kobj);

 

Initialization of kobjects

kobject 的初始化

 

Code which creates a kobject must, of course, initialize that object. Some

of the internal fields are setup with a (mandatory) call to kobject_init():

创建一个 kobject 的代码首先必须初始化这个对象。调用 kobject_init() 来设置一些

内部字段（强制性的）。

void kobject_init(struct kobject *kobj, struct kobj_type *ktype);

 

The ktype is required for a kobject to be created properly, as every kobject

must have an associated kobj_type.  After calling kobject_init(), to

register the kobject with sysfs, the function kobject_add() must be called:

因为每一个 kobject 都有一个关联的 kobj_type，所以正确创建一个 kobject 时

ktype 是必须的。调用 kobject_init() 之后，必须是用 kobject_add() 在 sysfs 上

注册 kobject。

 

int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);

 

This sets up the parent of the kobject and the name for the kobject

properly.  If the kobject is to be associated with a specific kset,

kobj->kset must be assigned before calling kobject_add().  If a kset is

associated with a kobject, then the parent for the kobject can be set to

NULL in the call to kobject_add() and then the kobject's parent will be the

kset itself.

这将为 kobject 设置 parent 和 name。如果这个 kobject 将关联于一个指定的

kset，那么 kobj->kset 必须在 kobject_add() 之前被分配好。如果一个 ket 关联

于一个 kobject，那么在调用 kobject_add() 时 parent 可以是 NULL，这时 kobject

的 parent 将会是这个 kset 本身。

 

As the name of the kobject is set when it is added to the kernel, the name

of the kobject should never be manipulated directly.  If you must change

the name of the kobject, call kobject_rename():

当一个 kobject 的 name 已经被设置并添加经 kernel 之后，就不允许直接操作这个

kobject 的 name 了。如果你必须修改这个 name，请使用 kobject_rename():

int kobject_rename(struct kobject *kobj, const char *new_name);

 

kobject_rename does not perform any locking or have a solid notion of

what names are valid so the caller must provide their own sanity checking

and serialization.

kobject_rename 不会执行任何锁定操作，也不会验证 name 的有效性，所以调用者

必须提供自己的完整性检查和序列化。

 

There is a function called kobject_set_name() but that is legacy cruft and

is being removed.  If your code needs to call this function, it is

incorrect and needs to be fixed.

这里有一个函数 kobject_set_name()，但这个函数是遗留问题，而且在将来会被删

除。如果你的代码需要调用这个函数，那么这将是不正确的并且必须被修正。

 

To properly access the name of the kobject, use the function

要正确访问 kobject 的 name，使用这个函数

kobject_name():

const char *kobject_name(const struct kobject * kobj);

 

There is a helper function to both initialize and add the kobject to the

kernel at the same time, called surprisingly enough kobject_init_and_add():

这里有一个辅助函数将同时初始化 kobject 并将其添加至 kernel，kobject_init_and_add():

 

int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
                         struct kobject *parent, const char *fmt, ...);

 

The arguments are the same as the individual kobject_init() and

kobject_add() functions described above.

其中的参数与 kobject_init() 和 kobject_add() 里描述的一致。

 

 

Uevents

 

After a kobject has been registered with the kobject core, you need to

announce to the world that it has been created.  This can be done with a

call to kobject_uevent():

在一个 kobject 注册之后，你需要通过 kobject_uevent() 向全局宣布它被创建了。

 

int kobject_uevent(struct kobject *kobj, enum kobject_action action);

 

Use the KOBJ_ADD action for when the kobject is first added to the kernel.

This should be done only after any attributes or children of the kobject

have been initialized properly, as userspace will instantly start to look

for them when this call happens.

当 kobject 首次被添加进 kernel 时，使用 KOBJ_ADD action。这个调用必须在所有

的 attributes 或 children 都被正确初始化之后，因为当这个调用发生时，用户空间将

会立即开始寻找它们。

 

When the kobject is removed from the kernel (details on how to do that is

below), the uevent for KOBJ_REMOVE will be automatically created by the

kobject core, so the caller does not have to worry about doing that by

hand.

当 kobject 从 kernel 中移除时，KOBJ_REMOVE 的 uevent 将会被 kobject core

自动创建，所以调用者不必担心手动完成这些。

 

 

Reference counts

引用计数

 

One of the key functions of a kobject is to serve as a reference counter

for the object in which it is embedded. As long as references to the object

exist, the object (and the code which supports it) must continue to exist.

The low-level functions for manipulating a kobject's reference counts are:

一个 kobject 的主要功能之一就是在它被嵌入的对象中作为一个引用计数器。只要存

在对该对象的引用，对象（和支持它的代码）就必须继续存在。操作一个 kobject 的

引用计数的底层函数是：

struct kobject *kobject_get(struct kobject *kobj);
void kobject_put(struct kobject *kobj);

 

A successful call to kobject_get() will increment the kobject's reference

counter and return the pointer to the kobject.

对 kobject_get() 的成功调用将递增 kobject 的引用计数并且返回指向该 kobject 的指针。

 

When a reference is released, the call to kobject_put() will decrement the

reference count and, possibly, free the object. Note that kobject_init()

sets the reference count to one, so the code which sets up the kobject will

need to do a kobject_put() eventually to release that reference.

当一个引用被释放时，调用 kobject_put() 将递减引用计数，并且可能的话，释放对象。

请注意，kobject_init() 将引用计数设置为 1，所以在建立 kobject 的代码里需要执行

kobject_put() 用于最终释放引用。

 

Because kobjects are dynamic, they must not be declared statically or on

the stack, but instead, always allocated dynamically.  Future versions of

the kernel will contain a run-time check for kobjects that are created

statically and will warn the developer of this improper usage.

因为 kobject 是动态的，所以它们不能被声明为静态的或者在栈区分配空间，它们

应该始终被动态分配。为来的 kernel 版本将会包含一个对 kobject 是否静态创建的

运行时检查，并且会警告开发人员这种不正确的使用。

 

If all that you want to use a kobject for is to provide a reference counter

for your structure, please use the struct kref instead; a kobject would be

overkill.  For more information on how to use struct kref, please see the

file Documentation/kref.txt in the Linux kernel source tree.

如果你使用 kobject 的理由仅仅是使用引用计数的话，那么请使用 struct kref 替代

kobject。更多关于 struct kref 的信息请参考 Linux 内核文档 Documentation/kref.txt

 

 

Creating "simple" kobjects

创建“简单”的 kobject

 

Sometimes all that a developer wants is a way to create a simple directory

in the sysfs hierarchy, and not have to mess with the whole complication of

ksets, show and store functions, and other details.  This is the one

exception where a single kobject should be created.  To create such an

entry, use the function:

有时开发人员希望有一种创建一个在 sysfs 层次中简单目录的方式，而并不想搞乱本来

就错综复杂的 ksets，show 和 store 函数，或一些其他的细节。这是一个创建单独的

kobjects 的一个例外。要创建这样的条目，使用这个函数：

 

struct kobject *kobject_create_and_add(char *name, struct kobject *parent);

 

This function will create a kobject and place it in sysfs in the location

underneath the specified parent kobject.  To create simple attributes

associated with this kobject, use:

此函数将创建一个 kobject，并将其放置在指定的父 kobject 的 sysfs 中下层

的位置。要创建简单的与这个 kobject 关联的属性，使用函数：

 

int sysfs_create_file(struct kobject *kobj, struct attribute *attr);

or

int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);

 

Both types of attributes used here, with a kobject that has been created

with the kobject_create_and_add(), can be of type kobj_attribute, so no

special custom attribute is needed to be created.

这两种使用 kobject_create_and_add() 创建的 kobject 的属性类型都可以是

kobj_attribute，所以没有创建自定义属性的需要。

 

See the example module, samples/kobject/kobject-example.c for an

implementation of a simple kobject and attributes.

查看示例模块 samples/kobject/kobject-example.c，一个简单的 kobject

和属性的实现。

 

 

 

ktypes and release methods

ktypes 和 release 方法

 

One important thing still missing from the discussion is what happens to a

kobject when its reference count reaches zero. The code which created the

kobject generally does not know when that will happen; if it did, there

would be little point in using a kobject in the first place. Even

predictable object lifecycles become more complicated when sysfs is brought

in as other portions of the kernel can get a reference on any kobject that

is registered in the system.

到目前为止我们遗漏了一个重要的事情，那就是当一个 kobject 的引用计数达到 0 时将

会发生什么。通常，创建 kobject 的代码并不知道这种情况何时发生。如果它们知道何

时发生，那么把 kobject 放在结构体的首位可能会有那么一点点帮助。即使是一个可预

测的对象生命周期也将变得复杂，特别是在当 sysfs 作为 kernel 的一部分被引入时，它

可以获取到任意在系统中注册的 kobject 的引用。

 

The end result is that a structure protected by a kobject cannot be freed

before its reference count goes to zero. The reference count is not under

the direct control of the code which created the kobject. So that code must

be notified asynchronously whenever the last reference to one of its

kobjects goes away.

结论就是一个被 kobject 保护的结构体不能在这个 kobject 引用计数到 0 之前被释放。

而这个引用计数又不被创建这个 kobject 的代码所直接控制，所以必须在这个 kobject

的最后一个引用消失时异步通知这些代码。

 

Once you registered your kobject via kobject_add(), you must never use

kfree() to free it directly. The only safe way is to use kobject_put(). It

is good practice to always use kobject_put() after kobject_init() to avoid

errors creeping in.

一旦你通过 kobject_add() 注册你的 kobject 之后，永远也不要使用 kfree() 去释

放直接它。唯一安全的途径是使用 kobject_put()。总是在 kobject_init() 之后使

用 kobject_put() 是避免错误蔓延的很好的做法。

 

This notification is done through a kobject's release() method. Usually

such a method has a form like:

这个通知是通过 kobject 的 release() 函数完成的。该函数通常具有这样的形式：

 

void my_object_release(struct kobject *kobj)
{
   struct my_object *mine = container_of(kobj, struct my_object, kobj);

   kfree(mine);
}

 

One important point cannot be overstated: every kobject must have a

release() method, and the kobject must persist (in a consistent state)

until that method is called. If these constraints are not met, the code is

flawed.  Note that the kernel will warn you if you forget to provide a

release() method.  Do not try to get rid of this warning by providing an

"empty" release function; you will be mocked mercilessly by the kobject

maintainer if you attempt this.

很重要的一点怎么强调也不过分：每个 kobject 必须有一个 release() 方法，而且

在这个方法被调用之前 kobject 必须继续存在（保持一致的状态）。如果不符合这

些限制，那么代码是有缺陷的。需要注意的是，如果你忘记提供一个 release() 方法，

kernel 会警告你。不要试图提供一个“空”的 release 函数来摆脱这个警告，如果你

这样做你会受到 kobject 维护者们无情的嘲笑。

 

 

Note, the name of the kobject is available in the release function, but it

must NOT be changed within this callback.  Otherwise there will be a memory

leak in the kobject core, which makes people unhappy.

注意，尽管在 release 函数中 kobject 的 name 是可用的，但是千万不要在这个回调函

数中修改它。否则将会在 kobject core 中发生令人不愉快的内存泄露问题。

 

Interestingly, the release() method is not stored in the kobject itself;

instead, it is associated with the ktype. So let us introduce struct

kobj_type:

有趣的是 release() 方法并没有保存在 kobject 之中，而是关联在它的 ktype

成员中。让我们来介绍 struct kobj_type:

 

struct kobj_type {
    void (*release)(struct kobject *);
    const struct sysfs_ops *sysfs_ops;
    struct attribute **default_attrs;
};

 

This structure is used to describe a particular type of kobject (or, more

correctly, of containing object). Every kobject needs to have an associated

kobj_type structure; a pointer to that structure must be specified when you

call kobject_init() or kobject_init_and_add().

这个结构体是用来描述一个特定类型的 kobject（或者更确切的说，包含它的对象）。

每个 kobject 都需要一个关联的 kobj_type 结构体，当你调用 kobject_init() 或

kobject_init_and_add() 时必须指定一个指向 kobj_type 结构体的指针。

 

The release field in struct kobj_type is, of course, a pointer to the

release() method for this type of kobject. The other two fields (sysfs_ops

and default_attrs) control how objects of this type are represented in

sysfs; they are beyond the scope of this document.

当然 struct kobj_type 中的 release 字段就是一个指向同类型对象 release() 方法的

函数指针。另外两个字段（sysfs_ops 和 default_attrs）是用来控制这些类型的对象在

sysfs 里是如何表现的，这已经超出了本文的讨论范围。

 

The default_attrs pointer is a list of default attributes that will be

automatically created for any kobject that is registered with this ktype.

default_attrs 成员指针是一个在任何属于这个 ktype 的 kobject 注册时自动创

建的默认属性列表。

 

 

ksets

 

A kset is merely a collection of kobjects that want to be associated with

each other.  There is no restriction that they be of the same ktype, but be

very careful if they are not.

kset 仅仅是一个需要相互关联的 kobject 集合。在这里没有任何规定它们必须是同

样的 ktype，但如果它们不是一样的 ktype 则一定要小心处理。

 

A kset serves these functions:

一个 kset 提供以下功能：

 

 - It serves as a bag containing a group of objects. A kset can be used by

   the kernel to track "all block devices" or "all PCI device drivers."

－ 它就像一个装有一堆对象袋子。kernel 可以用一个 kset 来跟踪像“所有的

   块设备”或者“所有的 PCI 设备驱动”这样的东西。

 

 - A kset is also a subdirectory in sysfs, where the associated kobjects

   with the kset can show up.  Every kset contains a kobject which can be

   set up to be the parent of other kobjects; the top-level directories of

   the sysfs hierarchy are constructed in this way.

－ 一个 kset 也是一个 sysfs 里的子目录，该目录里能够看见这些相关的 kobject。

   每个 kset 都另外包含一个 kobject，这个 kobject 可以用来设置成其他 kobjects

   的 parent。sysfs 层次结构中的顶层目录就是通过这样的方法构建的。

 

 - Ksets can support the "hotplugging" of kobjects and influence how

   uevent events are reported to user space.

－ kset 还可以支持 kobject 的“热插拔”，并会影响 uevent 事件如何报告给用户空间。

 

In object-oriented terms, "kset" is the top-level container class; ksets

contain their own kobject, but that kobject is managed by the kset code and

should not be manipulated by any other user.

以面向对象的观点来看，“kset” 是一个顶层容器类。kset 包含有它们自己的 kobject，

这个 kobject 是在 kset 代码管理之下的，而且不允许其他任何用户对其操作。

 

A kset keeps its children in a standard kernel linked list.  Kobjects point

back to their containing kset via their kset field. In almost all cases,

the kobjects belonging to a kset have that kset (or, strictly, its embedded

kobject) in their parent.

一个 kset 使用标准的 kernel 链表来保存它的 children。kobjects 通过它们的 kset

字段回指向包含它们的 kset。在几乎所有的情况下，属于某 kset 的 kobject 的

parent 都指向这个 kset（严格的说是嵌套进这个 kset 的 kobject）。

 

As a kset contains a kobject within it, it should always be dynamically

created and never declared statically or on the stack.  To create a new

kset use:

正是因为一个 kset 包含了一个 kobject，就应该始终动态创建这个 kset，千万

不要将其声明为静态的或在栈区分配空间。创建一个 kset 使用：

 

struct kset *kset_create_and_add(const char *name,
                                 struct kset_uevent_ops *u,
                                 struct kobject *parent);

 

When you are finished with the kset, call:

当你使用完一个 kset 时，调用这个函数：

void kset_unregister(struct kset *kset);

to destroy it.

来销毁它。

 

An example of using a kset can be seen in the

samples/kobject/kset-example.c file in the kernel tree.

内核树中的 samples/kobject/kset-example.c 文件是一个

有关于如何使用 kset 的示例。

 

If a kset wishes to control the uevent operations of the kobjects

associated with it, it can use the struct kset_uevent_ops to handle it:

如果一个 kset 希望控制那些与它相关联的 kobject 的 uevent 操作，可以使用

struct kset_uevent_ops 处理。

 

struct kset_uevent_ops {
    int (*filter)(struct kset *kset, struct kobject *kobj);
    const char *(*name)(struct kset *kset, struct kobject *kobj);
    int (*uevent)(struct kset *kset, struct kobject *kobj,
                  struct kobj_uevent_env *env);
};

 

The filter function allows a kset to prevent a uevent from being emitted to

userspace for a specific kobject.  If the function returns 0, the uevent

will not be emitted.

filter 函数允许 kset 阻止一个特定的 kobject 的 uevent 是否发送到用户空间。如果

这个函数返回 0，则 uevent 将不会被发出。

 

The name function will be called to override the default name of the kset

that the uevent sends to userspace.  By default, the name will be the same

as the kset itself, but this function, if present, can override that name.

name 函数用来重写那些将被 uevent 发送到用户空间的 kset 的默认名称。默认情况

下，这个名称应该和 kset 本身的名称相同，但这个函数的出现将可以改写这个名称。

 

The uevent function will be called when the uevent is about to be sent to

userspace to allow more environment variables to be added to the uevent.

uevent 函数会向即将被发送到用户空间的 uevent 中添加更多的环境变量。

 

One might ask how, exactly, a kobject is added to a kset, given that no

functions which perform that function have been presented.  The answer is

that this task is handled by kobject_add().  When a kobject is passed to

kobject_add(), its kset member should point to the kset to which the

kobject will belong.  kobject_add() will handle the rest.

有人可能会问，当一个 kobject 加入到一个 kset 时并没有提供完成这些功能的函数。

答案就是这些任务由 kobject_add() 来完成，kobject 的成员 kset 必须指向它将被

加入到的 kset，然后kobject_add() 会帮你干完剩下的活。

 

If the kobject belonging to a kset has no parent kobject set, it will be

added to the kset's directory.  Not all members of a kset do necessarily

live in the kset directory.  If an explicit parent kobject is assigned

before the kobject is added, the kobject is registered with the kset, but

added below the parent kobject.

如果一个属于某个 kset 的 kobject 没有设置它的 parent kobject，那么它将被

添加到 kset 的目录中去。但并不是 kset 的所有成员都一定存在于 kset 目录下。

如果在 kobject 被添加前就指明了它的 parent kobject， 那么该 kobject 将被

注册到这个 kset 下，然后添加到它的 parent kobject 下。

 

 

Kobject removal

kobject 的移除

 

After a kobject has been registered with the kobject core successfully, it

must be cleaned up when the code is finished with it.  To do that, call

kobject_put().  By doing this, the kobject core will automatically clean up

all of the memory allocated by this kobject.  If a KOBJ_ADD uevent has been

sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and

any other sysfs housekeeping will be handled for the caller properly.

当 kobject core 成功的注册了一个 kobject之后，这个 kobject 必须在代码完成对它的

使用时销毁。要做到这一点，请调用 kobject_put()。通过这个调用， kobject core 会

自动清理所有通过这个 kobject 分配的内存空间。如果曾经为了这个 kobject 发送过一个

KOBJ_ADD uevent，那么一个相应的 KOBJ_REMOVE uevent 将会被发送，并且任何

其他的 sysfs 维护者都将为这个调用作出相应的处理。

 

If you need to do a two-stage delete of the kobject (say you are not

allowed to sleep when you need to destroy the object), then call

kobject_del() which will unregister the kobject from sysfs.  This makes the

kobject "invisible", but it is not cleaned up, and the reference count of

the object is still the same.  At a later time call kobject_put() to finish

the cleanup of the memory associated with the kobject.

如果你需要分两步来删除一个 kobject 的话（也就是说在你需要销毁一个对象时不允

许 sleep），那么请使用 kobject_del() 来从 sysfs 注销这个 kobject。这将使得

kobject “不可见”，但是它并没有被清理，并且它的引用计数也没变。在稍后的时候

调用 kobject_put() 去完成对这个 kobject 相关的内存空间的清理。

 

kobject_del() can be used to drop the reference to the parent object, if

circular references are constructed.  It is valid in some cases, that a

parent objects references a child.  Circular references _must_ be broken

with an explicit call to kobject_del(), so that a release functions will be

called, and the objects in the former circle release each other.

如果建立了一个循环引用的话，kobject_del() 可以用来删除指向 parent 对象的

引用。当某个 parnet 对象又引用了它的 child 时，这是非常有效的。循环引用必

须显示的通过调用 kobject_del() 来打破，这样做之后将会调用一个 release 函数，

并且这些先前在循环引用中的对象才会彼此释放。

 

 

Example code to copy from

示例代码

 

For a more complete example of using ksets and kobjects properly, see the

example programs samples/kobject/{kobject-example.c,kset-example.c},

which will be built as loadable modules if you select CONFIG_SAMPLE_KOBJECT.

想要获得更完整的关于正确使用 kset 和 konject 的例子，请参考示例程序

samples/kobject/{kobject-example.c,kset-example.c}。可以通过选择编译条件

CONFIG_SAMPLE_KOBJECT 来把这些示例编译成可装载模块。