From 6b2cb91efce215c3c34b1b79b15f30e860761a3e Mon Sep 17 00:00:00 2001 From: Li Yang Date: Wed, 25 Jul 2007 02:03:06 +0800 Subject: Chinese: Add the known_regression URI to the HOWTO Update translation for commit be3884943674f8ee7656b1d8b71c087ec900c836. Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/HOWTO | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index 48fc67bfbe3..c8660da7344 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -218,6 +218,8 @@ kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循 时，一个新的-rc版本就会被发布。计划是每周都发布新的-rc版本。 - 这个过程一直持续下去直到内核被认为达到足够稳定的状态，持续时间大概是 6个星期。 + - 以下地址跟踪了在每个-rc发布中发现的退步列表： + http://kernelnewbies.org/known_regressions 关于内核发布，值得一提的是Andrew Morton在linux-kernel邮件列表中如是说： “没有人知道新内核何时会被发布，因为发布是根据已知bug的情况来决定 -- cgit v1.2.3 From 24277db3894941026662743e400e77c68c4a9e92 Mon Sep 17 00:00:00 2001 From: Li Yang Date: Wed, 25 Jul 2007 02:43:32 +0800 Subject: Chinese: rephrase English introduction in HOWTO Rephrase the introduction as suggested by Jesper Juhl. Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/HOWTO | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index c8660da7344..79d1c3c7071 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -1,10 +1,10 @@ Chinese translated version of Documentation/HOWTO If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have problem +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 there is problem with translation. +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. Maintainer: Greg Kroah-Hartman Chinese maintainer: Li Yang -- cgit v1.2.3 From 5dae82cc186da487cf33d7f5648a9ab3e02eaee4 Mon Sep 17 00:00:00 2001 From: Li Yang Date: Tue, 23 Oct 2007 21:58:51 +0800 Subject: Chinese: Change man-pages maintainer address in HOWOTO The email address of the man-pages maintainer has changed. Cc: Michael Kerrisk Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/HOWTO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index 79d1c3c7071..3d80e8af36e 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -85,7 +85,7 @@ Linux内核源代码都是在GPL（通用公共许可证）的保护下发布的 Linux内核代码中包含有大量的文档。这些文档对于学习如何与内核社区互动有着 不可估量的价值。当一个新的功能被加入内核，最好把解释如何使用这个功能的文 档也放进内核。当内核的改动导致面向用户空间的接口发生变化时，最好将相关信 -息或手册页(manpages)的补丁发到mtk-manpages@gmx.net，以向手册页(manpages) +息或手册页(manpages)的补丁发到mtk.manpages@gmail.com，以向手册页(manpages) 的维护者解释这些变化。 以下是内核代码中需要阅读的文档： -- cgit v1.2.3 From 12428e7626378dec7968cd4f5df9aab2ee58e735 Mon Sep 17 00:00:00 2001 From: TripleX Chung Date: Wed, 24 Oct 2007 00:46:43 +0800 Subject: Chinese: add translation of SubmittingPatches Signed-off-by: TripleX Chung Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/SubmittingPatches | 416 ++++++++++++++++++++++++++++++++++ 1 file changed, 416 insertions(+) create mode 100644 Documentation/zh_CN/SubmittingPatches (limited to 'Documentation') diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/zh_CN/SubmittingPatches new file mode 100644 index 00000000000..985c92e20b7 --- /dev/null +++ b/Documentation/zh_CN/SubmittingPatches @@ -0,0 +1,416 @@ +Chinese translated version of Documentation/SubmittingPatches + +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: TripleX Chung +--------------------------------------------------------------------- +Documentation/SubmittingPatches 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 钟宇 TripleX Chung +中文版翻译者： 钟宇 TripleX Chung +中文版校译者： 李阳 Li Yang + 王聪 Wang Cong + +以下为正文 +--------------------------------------------------------------------- + + 如何让你的改动进入内核 + 或者 + 获得亲爱的 Linus Torvalds 的关注和处理 +---------------------------------- + +对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”， +提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你 +的改动被接受的机会。 +阅读 Documentation/SubmitChecklist 来获得在提交代码前需要检查的项目的列 +表。如果你在提交一个驱动程序，那么同时阅读一下 +Documentation/SubmittingDrivers 。 + + +-------------------------- +第一节 - 创建并发送你的改动 +-------------------------- + +1) "diff -up" +----------- + +使用 "diff -up" 或者 "diff -uprN" 来创建补丁。 + +所有内核的改动，都是以补丁的形式呈现的，补丁由 diff(1) 生成。创建补丁的 +时候，要确认它是以 "unified diff" 格式创建的，这种格式由 diff(1) 的 '-u' +参数生成。而且，请使用 '-p' 参数，那样会显示每个改动所在的C函数，使得 +产生的补丁容易读得多。补丁应该基于内核源代码树的根目录，而不是里边的任 +何子目录。 +为一个单独的文件创建补丁，一般来说这样做就够了： + + SRCTREE= linux-2.6 + MYFILE= drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +为多个文件创建补丁，你可以解开一个没有修改过的内核源代码树，然后和你自 +己的代码树之间做 diff 。例如： + + MYSRC= /devel/linux-2.6 + + tar xvfz linux-2.6.12.tar.gz + mv linux-2.6.12 linux-2.6.12-vanilla + diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ + linux-2.6.12-vanilla $MYSRC > /tmp/patch + +"dontdiff" 是内核在编译的时候产生的文件的列表，列表中的文件在 diff(1) +产生的补丁里会被跳过。"dontdiff" 文件被包含在2.6.12和之后版本的内核源代 +码树中。对于更早的内核版本，你可以从 + 获取它。 +确定你的补丁里没有包含任何不属于这次补丁提交的额外文件。记得在用diff(1) +生成补丁之后，审阅一次补丁，以确保准确。 +如果你的改动很散乱，你应该研究一下如何将补丁分割成独立的部分，将改动分 +割成一系列合乎逻辑的步骤。这样更容易让其他内核开发者审核，如果你想你的 +补丁被接受，这是很重要的。下面这些脚本能够帮助你做这件事情： +Quilt: +http://savannah.nongnu.org/projects/quilt + +Andrew Morton 的补丁脚本: +http://www.zip.com.au/~akpm/linux/patches/ +作为这些脚本的替代，quilt 是值得推荐的补丁管理工具(看上面的链接)。 + +2)描述你的改动。 +描述你的改动包含的技术细节。 + +要多具体就写多具体。最糟糕的描述可能是像下面这些语句：“更新了某驱动程 +序”，“修正了某驱动程序的bug”，或者“这个补丁包含了某子系统的修改，请 +使用。” + +如果你的描述开始变长，这表示你也许需要拆分你的补丁了，请看第3小节， +继续。 + +3)拆分你的改动 + +将改动拆分，逻辑类似的放到同一个补丁文件里。 + +例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动才分到两个或 +者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适 +应这些新的API，那么把这些修改分成两个补丁。 + +另一方面，如果你将一个单独的改动做成多个补丁文件，那么将它们合并成一个 +单独的补丁文件。这样一个逻辑上单独的改动只被包含在一个补丁文件里。 + +如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。简单的在你的补 +丁描述里指出“这个补丁依赖某补丁”就好了。 + +如果你不能将补丁浓缩成更少的文件，那么每次大约发送出15个，然后等待审查 +和整合。 + +4)选择 e-mail 的收件人 + +看一遍 MAINTAINERS 文件和源代码，看看你所的改动所在的内核子系统有没有指 +定的维护者。如果有，给他们发e-mail。 + +如果没有找到维护者，或者维护者没有反馈，将你的补丁发送到内核开发者主邮 +件列表 linux-kernel@vger.kernel.org。大部分的内核开发者都跟踪这个邮件列 +表，可以评价你的改动。 + +每次不要发送超过15个补丁到 vger 邮件列表！！！ + +Linus Torvalds 是决定改动能否进入 Linux 内核的最终裁决者。他的 e-mail +地址是 。他收到的 e-mail 很多，所以一般 +的说，最好别给他发 e-mail。 + +那些修正bug，“显而易见”的修改或者是类似的只需要很少讨论的补丁可以直接 +发送或者CC给Linus。那些需要讨论或者没有很清楚的好处的补丁，一般先发送到 +linux-kernel邮件列表。只有当补丁被讨论得差不多了，才提交给Linus。 + +5)选择CC( e-mail 抄送)列表 + +除非你有理由不这样做，否则CC linux-kernel@vger.kernel.org。 + +除了 Linus 之外，其他内核开发者也需要注意到你的改动，这样他们才能评论你 +的改动并提供代码审查和建议。linux-kernel 是 Linux 内核开发者主邮件列表 +。其它的邮件列表为特定的子系统提供服务，比如 USB，framebuffer 设备，虚 +拟文件系统，SCSI 子系统，等等。查看 MAINTAINERS 文件来获得和你的改动有 +关的邮件列表。 + +Majordomo lists of VGER.KERNEL.ORG at: + + +如果改动影响了用户空间和内核之间的接口，请给 MAN-PAGES 的维护者（列在 +MAITAINERS 文件里的）发送一个手册页（man-pages）补丁，或者至少通知一下改 +变，让一些信息有途径进入手册页。 + +即使在第四步的时候，维护者没有作出回应，也要确认在修改他们的代码的时候 +，一直将维护者拷贝到CC列表中。 + +对于小的补丁，你也许会CC到 Adrian Bunk 管理的搜集琐碎补丁的邮件列表 +(Trivial Patch Monkey)trivial@kernel.org，那里专门收集琐碎的补丁。下面这样 +的补丁会被看作“琐碎的”补丁： + 文档的拼写修正。 + 修正会影响到 grep(1) 的拼写。 + 警告信息修正(频繁的打印无用的警告是不好的。) + 编译错误修正（代码逻辑的确是对的，只是编译有问题。） + 运行时修正（只要真的修正了错误。） + 移除使用了被废弃的函数/宏的代码(例如 check_region。) + 联系方式和文档修正。 + 用可移植的代码替换不可移植的代码（即使在体系结构相关的代码中，既然有 + 人拷贝，只要它是琐碎的） + 任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下） + +URL: + +(译注，关于“琐碎补丁”的一些说明：因为原文的这一部分写得比较简单，所以不得不 +违例写一下译注。"trivial"这个英文单词的本意是“琐碎的，不重要的。”但是在这里 +有稍微有一些变化，例如对一些明显的NULL指针的修正，属于运行时修正，会被归类 +到琐碎补丁里。虽然NULL指针的修正很重要，但是这样的修正往往很小而且很容易得到 +检验，所以也被归入琐碎补丁。琐碎补丁更精确的归类应该是 +“simple, localized & easy to verify”，也就是说简单的，局部的和易于检验的。 +trivial@kernel.org邮件列表的目的是针对这样的补丁，为提交者提供一个中心，来 +降低提交的门槛。) + +6)没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本。 + +Linus 和其他的内核开发者需要阅读和评论你提交的改动。对于内核开发者来说 +，可以“引用”你的改动很重要，使用一般的 e-mail 工具，他们就可以在你的 +代码的任何位置添加评论。 + +因为这个原因，所有的提交的补丁都是 e-mail 中“内嵌”的。 +警告：如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的 +补丁。 + +不要将补丁作为 MIME 编码的附件，不管是否压缩。很多流行的 e-mail 软件不 +是任何时候都将 MIME 编码的附件当作纯文本发送的，这会使得别人无法在你的 +代码中加评论。另外，MIME 编码的附件会让 Linus 多花一点时间来处理，这就 +降低了你的改动被接受的可能性。 + +警告：一些邮件软件，比如 Mozilla 会将你的信息以如下格式发送： +---- 邮件头 ---- +Content-Type: text/plain; charset=us-ascii; format=flowed +---- 邮件头 ---- +问题在于 “format=flowed” 会让接收端的某些邮件软件将邮件中的制表符替换 +成空格以及做一些类似的替换。这样，你发送的时候看起来没问题的补丁就被破 +坏了。 + +要修正这个问题，只需要将你的 mozilla 的 defaults/pref/mailnews.js 文件 +里的 +pref("mailnews.send_plaintext_flowed", false); // RFC 2646======= +修改成 +pref("mailnews.display.disable_format_flowed_support", true); +就可以了。 + +7) e-mail 的大小 + +给 Linus 发送补丁的时候，永远按照第6小节说的做。 + +大的改动对邮件列表不合适，对某些维护者也不合适。如果你的补丁，在不压缩 +的情况下，超过了40kB，那么你最好将补丁放在一个能通过 internet 访问的服 +务器上，然后用指向你的补丁的 URL 替代。 + +8) 指出你的内核版本 + +在标题和在补丁的描述中，指出补丁对应的内核的版本，是很重要的。 + +如果补丁不能干净的在最新版本的内核上打上，Linus 是不会接受它的。 + +9) 不要气馁，继续提交。 + +当你提交了改动以后，耐心地等待。如果 Linus 喜欢你的改动并且同意它，那么 +它将在下一个内核发布版本中出现。 + +然而，如果你的改动没有出现在下一个版本的内核中，可能有若干原因。减少那 +些原因，修正错误，重新提交更新后的改动，是你自己的工作。 + +Linus不给出任何评论就“丢弃”你的补丁是常见的事情。在系统中这样的事情很 +平常。如果他没有接受你的补丁，也许是由于以下原本： +* 你的补丁不能在最新版本的内核上干净的打上。 +* 你的补丁在 linux-kernel 邮件列表中没有得到充分的讨论。 +* 风格问题（参照第2小节） +* 邮件格式问题（重读本节） +* 你的改动有技术问题。 +* 他收到了成吨的 e-mail，而你的在混乱中丢失了。 +* 你让人为难。 + +有疑问的时候，在 linux-kernel 邮件列表上请求评论。 + +10) 在标题上加上 PATCH 的字样 + +Linus 和 linux-kernel 邮件列表的 e-mail 流量都很高，一个通常的约定是标 +题行以 [PATCH] 开头。这样可以让 Linus 和其他内核开发人员可以从 e-mail +的讨论中很轻易的将补丁分辨出来。 + +11）为你的工作签名 + +为了加强对谁做了何事的追踪，尤其是对那些透过好几层的维护者的补丁，我们 +建议在发送出去的补丁上加一个 “sign-off” 的过程。 + +"sign-off" 是在补丁的注释的最后的简单的一行文字，认证你编写了它或者其他 +人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息 +： + 开发者来源证书 1.1 + 对于本项目的贡献，我认证如下信息： + （a）这些贡献是完全或者部分的由我创建，我有权利以文件中指出 + 的开放源代码许可证提交它；或者 + （b）这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放 + 源代码许可证保护，而且，根据许可证，我有权提交修改后的贡献， + 无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证 + （除非我被允许用其它的许可证），正如文件中指出的；或者 + （c）这些贡献由认证（a），（b）或者（c）的人直接提供给我，而 + 且我没有修改它。 + （d）我理解并同意这个项目和贡献是公开的，贡献的记录（包括我 + 一起提交的个人记录，包括 sign-off ）被永久维护并且可以和这个项目 + 或者开放源代码的许可证同步地再发行。 + 那么加入这样一行： + Signed-off-by: Random J Developer + +使用你的真名（抱歉，不能使用假名或者匿名。） + +有人在最后加上标签。现在这些东西会被忽略，但是你可以这样做，来标记公司 +内部的过程，或者只是指出关于 sign-off 的一些特殊细节。 + +12）标准补丁格式 + +标准的补丁，标题行是： + Subject: [PATCH 001/123] 子系统:一句话概述 + +标准补丁的信体存在如下部分： + + - 一个 "from" 行指出补丁作者。 + + - 一个空行 + + - 说明的主体，这些说明文字会被拷贝到描述该补丁的永久改动记录里。 + + - 一个由"---"构成的标记行 + + - 不合适放到改动记录里的额外的注解。 + + - 补丁本身（diff 输出） + +标题行的格式，使得对标题行按字母序排序非常的容易 - 很多 e-mail 客户端都 +可以支持 - 因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。 + +e-mail 标题中的“子系统”标识哪个内核子系统将被打补丁。 + +e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。“一句话概述” +不应该是一个文件名。对于一个补丁系列（“补丁系列”指一系列的多个相关补 +丁），不要对每个补丁都使用同样的“一句话概述”。 + +记住 e-mail 的“一句话概述”会成为该补丁的全局唯一标识。它会蔓延到 git +的改动记录里。然后“一句话概述”会被用在开发者的讨论里，用来指代这个补 +丁。用户将希望通过 google 来搜索"一句话概述"来找到那些讨论这个补丁的文 +章。 + +一些标题的例子： + + Subject: [patch 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCHv2 001/207] x86: fix eflags tracking + +"from" 行是信体里的最上面一行，具有如下格式： + From: Original Author + +"from" 行指明在永久改动日志里，谁会被确认为作者。如果没有 "from" 行，那 +么邮件头里的 "From: " 行会被用来决定改动日志中的作者。 + +说明的主题将会被提交到永久的源代码改动日志里，因此对那些早已经不记得和 +这个补丁相关的讨论细节的有能力的读者来说，是有意义的。 + +"---" 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少 +的。 + +对于 "---" 标记之后的额外注解，一个好的用途就是用来写 diffstat，用来显 +示修改了什么文件和每个文件都增加和删除了多少行。diffstat 对于比较大的补 +丁特别有用。其余那些只是和时刻或者开发者相关的注解，不合适放到永久的改 +动日志里的，也应该放这里。 +使用 diffstat的选项 "-p 1 -w 70" 这样文件名就会从内核源代码树的目录开始 +，不会占用太宽的空间（很容易适合80列的宽度，也许会有一些缩进。） + +在后面的参考资料中能看到适当的补丁格式的更多细节。 + +------------------------------- +第二节 提示，建议和诀窍 +------------------------------- + +本节包含很多和提交到内核的代码有关的通常的"规则"。事情永远有例外...但是 +你必须真的有好的理由这样做。你可以把本节叫做Linus的计算机科学入门课。 + +1) 读 Document/CodingStyle + +Nuff 说过，如果你的代码和这个偏离太多，那么它有可能会被拒绝，没有更多的 +审查，没有更多的评价。 + +2) #ifdef 是丑陋的 +混杂了 ifdef 的代码难以阅读和维护。别这样做。作为替代，将你的 ifdef 放 +在头文件里，有条件地定义 "static inline" 函数，或者宏，在代码里用这些东 +西。让编译器把那些"空操作"优化掉。 + +一个简单的例子，不好的代码： + + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + #ifdef CONFIG_NET_FUNKINESS + init_funky_net(dev); + #endif + +清理后的例子: + +(头文件里) + #ifndef CONFIG_NET_FUNKINESS + static inline void init_funky_net (struct net_device *d) {} + #endif + +(代码文件里) + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + init_funky_net(dev); + +3) 'static inline' 比宏好 + +Static inline 函数相比宏来说，是好得多的选择。Static inline 函数提供了 +类型安全，没有长度限制，没有格式限制，在 gcc 下开销和宏一样小。 + +宏只在 static inline 函数不是最优的时候[在 fast paths 里有很少的独立的 +案例]，或者不可能用 static inline 函数的时候[例如字符串分配]。 +应该用 'static inline' 而不是 'static __inline__', 'extern inline' 和 +'extern __inline__' 。 + +4) 不要过度设计 + +不要试图预计模糊的未来事情，这些事情也许有用也许没有用："让事情尽可能的 +简单，而不是更简单"。 + +---------------- +第三节 参考文献 +---------------- + +Andrew Morton, "The perfect patch" (tpp). + + +Jeff Garzik, "Linux kernel patch submission format". + + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + + + + + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + + +Kernel Documentation/CodingStyle: + + +Linus Torvalds's mail on the canonical patch format: + +-- -- cgit v1.2.3 From 09792200e465db0861dee25bdecfc55278907ed3 Mon Sep 17 00:00:00 2001 From: Li Yang Date: Wed, 24 Oct 2007 00:51:11 +0800 Subject: Chinese: add translation of SubmittingDrivers Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/SubmittingDrivers | 168 ++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 Documentation/zh_CN/SubmittingDrivers (limited to 'Documentation') diff --git a/Documentation/zh_CN/SubmittingDrivers b/Documentation/zh_CN/SubmittingDrivers new file mode 100644 index 00000000000..5f4815c63ec --- /dev/null +++ b/Documentation/zh_CN/SubmittingDrivers @@ -0,0 +1,168 @@ +Chinese translated version of Documentation/SubmittingDrivers + +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: Li Yang +--------------------------------------------------------------------- +Documentation/SubmittingDrivers 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 李阳 Li Yang +中文版翻译者： 李阳 Li Yang +中文版校译者： 陈琦 Maggie Chen + 王聪 Wang Cong + 张巍 Zhang Wei + +以下为正文 +--------------------------------------------------------------------- + +如何向 Linux 内核提交驱动程序 +----------------------------- + +这篇文档将会解释如何向不同的内核源码树提交设备驱动程序。请注意，如果你感 +兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/) +和／或 X.org 项目 (http://x.org)。 + +另请参阅 Documentation/SubmittingPatches 文档。 + + +分配设备号 +---------- + +块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（ +现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。 +即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息， +请参阅 Documentation/devices.txt。 + +如果你使用的不是已经分配的设备号，那么当你提交设备驱动的时候，它将会被强 +制分配一个新的设备号，即便这个设备号和你之前发给客户的截然不同。 + +设备驱动的提交对象 +------------------ + +Linux 2.0: + 此内核源码树不接受新的驱动程序。 + +Linux 2.2: + 此内核源码树不接受新的驱动程序。 + +Linux 2.4: + 如果所属的代码领域在内核的 MAINTAINERS 文件中列有一个总维护者， + 那么请将驱动程序提交给他。如果此维护者没有回应或者你找不到恰当的 + 维护者，那么请联系 Willy Tarreau 。 + +Linux 2.6: + 除了遵循和 2.4 版内核同样的规则外，你还需要在 linux-kernel 邮件 + 列表上跟踪最新的 API 变化。向 Linux 2.6 内核提交驱动的顶级联系人 + 是 Andrew Morton 。 + +决定设备驱动能否被接受的条件 +---------------------------- + +许可： 代码必须使用 GNU 通用公开许可证 (GPL) 提交给 Linux，但是 + 我们并不要求 GPL 是唯一的许可。你或许会希望同时使用多种 + 许可证发布，如果希望驱动程序可以被其他开源社区（比如BSD） + 使用。请参考 include/linux/module.h 文件中所列出的可被 + 接受共存的许可。 + +版权： 版权所有者必须同意使用 GPL 许可。最好提交者和版权所有者 + 是相同个人或实体。否则，必需列出授权使用 GPL 的版权所有 + 人或实体，以备验证之需。 + +接口： 如果你的驱动程序使用现成的接口并且和其他同类的驱动程序行 + 为相似，而不是去发明无谓的新接口，那么它将会更容易被接受。 + 如果你需要一个 Linux 和 NT 的通用驱动接口，那么请在用 + 户空间实现它。 + +代码： 请使用 Documentation/CodingStyle 中所描述的 Linux 代码风 + 格。如果你的某些代码段（例如那些与 Windows 驱动程序包共 + 享的代码段）需要使用其他格式，而你却只希望维护一份代码， + 那么请将它们很好地区分出来，并且注明原因。 + +可移植性： 请注意，指针并不永远是 32 位的，不是所有的计算机都使用小 + 尾模式 (little endian) 存储数据，不是所有的人都拥有浮点 + 单元，不要随便在你的驱动程序里嵌入 x86 汇编指令。只能在 + x86 上运行的驱动程序一般是不受欢迎的。虽然你可能只有 x86 + 硬件，很难测试驱动程序在其他平台上是否可用，但是确保代码 + 可以被轻松地移植却是很简单的。 + +清晰度： 做到所有人都能修补这个驱动程序将会很有好处，因为这样你将 + 会直接收到修复的补丁而不是 bug 报告。如果你提交一个试图 + 隐藏硬件工作机理的驱动程序，那么它将会被扔进废纸篓。 + +电源管理： 因为 Linux 正在被很多移动设备和桌面系统使用，所以你的驱 + 动程序也很有可能被使用在这些设备上。它应该支持最基本的电 + 源管理，即在需要的情况下实现系统级休眠和唤醒要用到的 + .suspend 和 .resume 函数。你应该检查你的驱动程序是否能正 + 确地处理休眠与唤醒，如果实在无法确认，请至少把 .suspend + 函数定义成返回 -ENOSYS（功能未实现）错误。你还应该尝试确 + 保你的驱动在什么都不干的情况下将耗电降到最低。要获得驱动 + 程序测试的指导，请参阅 + Documentation/power/drivers-testing.txt。有关驱动程序电 + 源管理问题相对全面的概述，请参阅 + Documentation/power/devices.txt。 + +管理： 如果一个驱动程序的作者还在进行有效的维护，那么通常除了那 + 些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会 + 被转发给作者。如果你希望成为驱动程序的联系人和更新者，最 + 好在代码注释中写明并且在 MAINTAINERS 文件中加入这个驱动 + 程序的条目。 + +不影响设备驱动能否被接受的条件 +------------------------------ + +供应商： 由硬件供应商来维护驱动程序通常是一件好事。不过，如果源码 + 树里已经有其他人提供了可稳定工作的驱动程序，那么请不要期 + 望“我是供应商”会成为内核改用你的驱动程序的理由。理想的情 + 况是：供应商与现有驱动程序的作者合作，构建一个统一完美的 + 驱动程序。 + +作者： 驱动程序是由大的 Linux 公司研发还是由你个人编写，并不影 + 响其是否能被内核接受。没有人对内核源码树享有特权。只要你 + 充分了解内核社区，你就会发现这一点。 + + +资源列表 +-------- + +Linux 内核主源码树： + ftp.??.kernel.org:/pub/linux/kernel/... + ?? == 你的国家代码，例如 "cn"、"us"、"uk"、"fr" 等等 + +Linux 内核邮件列表： + linux-kernel@vger.kernel.org + [可通过向majordomo@vger.kernel.org发邮件来订阅] + +Linux 设备驱动程序，第三版（探讨 2.6.10 版内核）： + http://lwn.net/Kernel/LDD3/ （免费版） + +LWN.net: + 每周内核开发活动摘要 - http://lwn.net/ + 2.6 版中 API 的变更： + http://lwn.net/Articles/2.6-kernel-api/ + 将旧版内核的驱动程序移植到 2.6 版： + http://lwn.net/Articles/driver-porting/ + +KernelTrap： + Linux 内核的最新动态以及开发者访谈 + http://kerneltrap.org/ + +内核新手(KernelNewbies): + 为新的内核开发者提供文档和帮助 + http://kernelnewbies.org/ + +Linux USB项目： + http://www.linux-usb.org/ + +写内核驱动的“不要”（Arjan van de Ven著）: + http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf + +内核清洁工 (Kernel Janitor): + http://janitor.kernelnewbies.org/ -- cgit v1.2.3 From d1a1d45142ed3969b3cc3964f81e4249f9e49fbf Mon Sep 17 00:00:00 2001 From: Dave Young Date: Wed, 24 Oct 2007 01:14:29 +0800 Subject: Chinese: add translation of oops-tracing.txt Signed-off-by: Dave Young Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/oops-tracing.txt | 212 +++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 Documentation/zh_CN/oops-tracing.txt (limited to 'Documentation') diff --git a/Documentation/zh_CN/oops-tracing.txt b/Documentation/zh_CN/oops-tracing.txt new file mode 100644 index 00000000000..9312608ffb8 --- /dev/null +++ b/Documentation/zh_CN/oops-tracing.txt @@ -0,0 +1,212 @@ +Chinese translated version of Documentation/oops-tracing.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: Dave Young +--------------------------------------------------------------------- +Documentation/oops-tracing.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 杨瑞 Dave Young +中文版翻译者： 杨瑞 Dave Young +中文版校译者： 李阳 Li Yang + 王聪 Wang Cong + +以下为正文 +--------------------------------------------------------------------- + +注意： ksymoops 在2.6中是没有用的。 请以原有格式使用Oops(来自dmesg，等等)。 +忽略任何这样那样关于“解码Oops”或者“通过ksymoops运行”的文档。 如果你贴出运行过 +ksymoops的来自2.6的Oops，人们只会让你重贴一次。 + +快速总结 +------------- + +发现Oops并发送给看似相关的内核领域的维护者。别太担心对不上号。如果你不确定就发给 +和你所做的事情相关的代码的负责人。 如果可重现试着描述怎样重构。 那甚至比oops更有 +价值。 + +如果你对于发送给谁一无所知， 发给linux-kernel@vger.kernel.org。感谢你帮助Linux +尽可能地稳定。 + +Oops在哪里? +---------------------- + +通常Oops文本由klogd从内核缓冲区里读取并传给syslogd，由syslogd写到syslog文件中， +典型地是/var/log/messages(依赖于/etc/syslog.conf)。有时klogd崩溃了,这种情况下你 +能够运行dmesg > file来从内核缓冲区中读取数据并保存下来。 否则你可以 +cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“永不结束的文件”。如 +果机器崩溃坏到你不能输入命令或者磁盘不可用那么你有三种选择:- + +（1） 手抄屏幕上的文本待机器重启后再输入计算机。 麻烦但如果没有针对崩溃的准备， +这是仅有的选择。 另外，你可以用数码相机把屏幕拍下来-不太好，但比没有强。 如果信 +息滚动到了终端的上面，你会发现以高分辩率启动（比如，vga=791）会让你读到更多的文 +本。（注意：这需要vesafb，所以对‘早期’的oops没有帮助） + +（2）用串口终端启动（请参看Documentation/serial-console.txt），运行一个null +modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。 + +（3）使用Kdump（请参看Documentation/kdump/kdump.txt）， +使用在Documentation/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核 +环形缓冲区。 + +完整信息 +---------------- + +注意：以下来自于Linus的邮件适用于2.4内核。 我因为历史原因保留了它，并且因为其中 +一些信息仍然适用。 特别注意的是，请忽略任何ksymoops的引用。 + +From: Linus Torvalds + +怎样跟踪Oops.. [原发到linux-kernel的一封邮件] + +主要的窍门是有五年和这些烦人的oops消息打交道的经验;-) + +实际上，你有办法使它更简单。我有两个不同的方法： + + gdb /usr/src/linux/vmlinux + gdb> disassemble + +那是发现问题的简单办法，至少如果bug报告做的好的情况下（象这个一样-运行ksymoops +得到oops发生的函数及函数内的偏移）。 + +哦，如果报告发生的内核以相同的编译器和相似的配置编译它会有帮助的。 + +另一件要做的事是反汇编bug报告的“Code”部分：ksymoops也会用正确的工具来做这件事， +但如果没有那些工具你可以写一个傻程序： + + char str[] = "\xXX\xXX\xXX..."; + main(){} + +并用gcc -g编译它然后执行“disassemble str”（XX部分是由Oops报告的值-你可以仅剪切 +粘贴并用“\x”替换空格-我就是这么做的，因为我懒得写程序自动做这一切）。 + +另外，你可以用scripts/decodecode这个shell脚本。它的使用方法是： +decodecode < oops.txt + +“Code”之后的十六进制字节可能（在某些架构上）有一些当前指令之前的指令字节以及 +当前和之后的指令字节 + +Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 +64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 +7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 + +最后，如果你想知道代码来自哪里，你可以： + + cd /usr/src/linux + make fs/buffer.s # 或任何产生BUG的文件 + +然后你会比gdb反汇编更清楚的知道发生了什么。 + +现在，问题是把你所拥有的所有数据结合起来：C源码（关于它应该怎样的一般知识）， +汇编代码及其反汇编得到的代码（另外还有从“oops”消息得到的寄存器状态-对了解毁坏的 +指针有用，而且当你有了汇编代码你也能拿其它的寄存器和任何它们对应的C表达式做匹配 +）。 + +实际上，你仅需看看哪里不匹配（这个例子是“Code”反汇编和编译器生成的代码不匹配）。 +然后你须要找出为什么不匹配。通常很简单-你看到代码使用了空指针然后你看代码想知道 +空指针是怎么出现的，还有检查它是否合法.. + +现在，如果明白这是一项耗时的工作而且需要一丁点儿的专心，没错。这就是我为什么大多 +只是忽略那些没有符号表信息的崩溃报告的原因：简单的说太难查找了（我有一些 +程序用于在内核代码段中搜索特定的模式，而且有时我也已经能找出那些崩溃的地方，但是 +仅仅是找出正确的序列也确实需要相当扎实的内核知识） + +_有时_会发生这种情况，我仅看到崩溃中的反汇编代码序列， 然后我马上就明白问题出在 +哪里。这时我才意识到自己干这个工作已经太长时间了;-) + + Linus + + +--------------------------------------------------------------------------- +关于Oops跟踪的注解： + +为了帮助Linus和其它内核开发者，klogd纳入了大量的支持来处理保护错误。为了拥有对 +地址解析的完整支持至少应该使用1.3-pl3的sysklogd包。 + +当保护错误发生时，klogd守护进程自动把内核日志信息中的重要地址翻译成它们相应的符 +号。 + +klogd执行两种类型的地址解析。首先是静态翻译其次是动态翻译。静态翻译和ksymoops +一样使用System.map文件。为了做静态翻译klogd守护进程必须在初始化时能找到system +map文件。关于klogd怎样搜索map文件请参看klogd手册页。 + +动态地址翻译在使用内核可装载模块时很重要。 因为内核模块的内存是从内核动态内存池 +里分配的，所以不管是模块开始位置还是模块中函数和符号的位置都不是固定的。 + +内核支持允许程序决定装载哪些模块和它们在内存中位置的系统调用。使用这些系统调用 +klogd守护进程生成一张符号表用于调试发生在可装载模块中的保护错误。 + +至少klogd会提供产生保护错误的模块名。还可有额外的符号信息供可装载模块开发者选择 +以从模块中输出符号信息。 + +因为内核模块环境可能是动态的，所以必须有一种机制当模块环境发生改变时来通知klogd +守护进程。 有一些可用的命令行选项允许klogd向当前执行中的守护进程发送信号，告知符 +号信息应该被刷新了。 更多信息请参看klogd手册页。 + +sysklogd发布时包含一个补丁修改了modules-2.0.0包，无论何时一个模块装载或者卸载都 +会自动向klogd发送信号。打上这个补丁提供了必要的对调试发生于内核可装载模块的保护 +错误的无缝支持。 + +以下是被klogd处理过的发生在可装载模块中的一个保护错误例子： +--------------------------------------------------------------------------- +Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc +Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 +Aug 29 09:51:01 blizard kernel: *pde = 00000000 +Aug 29 09:51:01 blizard kernel: Oops: 0002 +Aug 29 09:51:01 blizard kernel: CPU: 0 +Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] +Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 +Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c +Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c +Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 +Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) +Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 +Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 +Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 +Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] +Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 +--------------------------------------------------------------------------- + +Dr. G.W. Wettstein Oncology Research Div. Computing Facility +Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com +820 4th St. N. +Fargo, ND 58122 +Phone: 701-234-7556 + + +--------------------------------------------------------------------------- +受污染的内核 + +一些oops报告在程序记数器之后包含字符串'Tainted: '。这表明内核已经被一些东西给污 +染了。 该字符串之后紧跟着一系列的位置敏感的字符，每个代表一个特定的污染值。 + + 1：'G'如果所有装载的模块都有GPL或相容的许可证，'P'如果装载了任何的专有模块。 +没有模块MODULE_LICENSE或者带有insmod认为是与GPL不相容的的MODULE_LICENSE的模块被 +认定是专有的。 + + 2：'F'如果有任何通过“insmod -f”被强制装载的模块，' '如果所有模块都被正常装载。 + + 3：'S'如果oops发生在SMP内核中，运行于没有证明安全运行多处理器的硬件。 当前这种 +情况仅限于几种不支持SMP的速龙处理器。 + + 4：'R'如果模块通过“insmod -f”被强制装载，' '如果所有模块都被正常装载。 + + 5：'M'如果任何处理器报告了机器检查异常，' '如果没有发生机器检查异常。 + + 6：'B'如果页释放函数发现了一个错误的页引用或者一些非预期的页标志。 + + 7：'U'如果用户或者用户应用程序特别请求设置污染标志，否则' '。 + + 8：'D'如果内核刚刚死掉，比如有OOPS或者BUG。 + +使用'Tainted: '字符串的主要原因是要告诉内核调试者，这是否是一个干净的内核亦或发 +生了任何的不正常的事。污染是永久的：即使出错的模块已经被卸载了，污染值仍然存在， +以表明内核不再值得信任。 -- cgit v1.2.3 From 6941ee8896bfc462c3e3ad113c769a57ecbf3b2a Mon Sep 17 00:00:00 2001 From: TripleX Chung Date: Wed, 24 Oct 2007 00:57:24 +0800 Subject: Chinese: add translation of stable_kernel_rules.txt Signed-off-by: TripleX Chung Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/stable_kernel_rules.txt | 66 +++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 Documentation/zh_CN/stable_kernel_rules.txt (limited to 'Documentation') diff --git a/Documentation/zh_CN/stable_kernel_rules.txt b/Documentation/zh_CN/stable_kernel_rules.txt new file mode 100644 index 00000000000..b5b9b0ab02f --- /dev/null +++ b/Documentation/zh_CN/stable_kernel_rules.txt @@ -0,0 +1,66 @@ +Chinese translated version of Documentation/stable_kernel_rules.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: TripleX Chung +--------------------------------------------------------------------- +Documentation/stable_kernel_rules.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + + +中文版维护者： 钟宇 TripleX Chung +中文版翻译者： 钟宇 TripleX Chung +中文版校译者： 李阳 Li Yang + Kangkai Yin + +以下为正文 +--------------------------------------------------------------------- + +关于Linux 2.6稳定版发布，所有你想知道的事情。 + +关于哪些类型的补丁可以被接收进入稳定版代码树，哪些不可以的规则： + + - 必须是显而易见的正确，并且经过测试的。 + - 连同上下文，不能大于100行。 + - 必须只修正一件事情。 + - 必须修正了一个给大家带来麻烦的真正的bug（不是“这也许是一个问题...” + 那样的东西）。 + - 必须修正带来如下后果的问题：编译错误（对被标记为CONFIG_BROKEN的例外）， + 内核崩溃，挂起，数据损坏，真正的安全问题，或者一些类似“哦，这不 + 好”的问题。简短的说，就是一些致命的问题。 + - 没有“理论上的竞争条件”，除非能给出竞争条件如何被利用的解释。 + - 不能存在任何的“琐碎的”修正（拼写修正，去掉多余空格之类的）。 + - 必须被相关子系统的维护者接受。 + - 必须遵循Documentation/SubmittingPatches里的规则。 + +向稳定版代码树提交补丁的过程： + + - 在确认了补丁符合以上的规则后，将补丁发送到stable@kernel.org。 + - 如果补丁被接受到队列里，发送者会收到一个ACK回复，如果没有被接受，收 + 到的是NAK回复。回复需要几天的时间，这取决于开发者的时间安排。 + - 被接受的补丁会被加到稳定版本队列里，等待其他开发者的审查。 + - 安全方面的补丁不要发到这个列表，应该发送到security@kernel.org。 + +审查周期： + + - 当稳定版的维护者决定开始一个审查周期，补丁将被发送到审查委员会，以 + 及被补丁影响的领域的维护者（除非提交者就是该领域的维护者）并且抄送 + 到linux-kernel邮件列表。 + - 审查委员会有48小时的时间，用来决定给该补丁回复ACK还是NAK。 + - 如果委员会中有成员拒绝这个补丁，或者linux-kernel列表上有人反对这个 + 补丁，并提出维护者和审查委员会之前没有意识到的问题，补丁会从队列中 + 丢弃。 + - 在审查周期结束的时候，那些得到ACK回应的补丁将会被加入到最新的稳定版 + 发布中，一个新的稳定版发布就此产生。 + - 安全性补丁将从内核安全小组那里直接接收到稳定版代码树中，而不是通过 + 通常的审查周期。请联系内核安全小组以获得关于这个过程的更多细节。 + +审查委员会： + - 由一些自愿承担这项任务的内核开发者，和几个非志愿的组成。 -- cgit v1.2.3 From c642ecf874028c9f41d18d59a9d663c2a954cc45 Mon Sep 17 00:00:00 2001 From: Bryan Wu Date: Wed, 24 Oct 2007 01:00:23 +0800 Subject: Chinese: add translation of volatile-considered-harmful.txt Signed-off-by: Bryan Wu Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- .../zh_CN/volatile-considered-harmful.txt | 113 +++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 Documentation/zh_CN/volatile-considered-harmful.txt (limited to 'Documentation') diff --git a/Documentation/zh_CN/volatile-considered-harmful.txt b/Documentation/zh_CN/volatile-considered-harmful.txt new file mode 100644 index 00000000000..ba8149d2233 --- /dev/null +++ b/Documentation/zh_CN/volatile-considered-harmful.txt @@ -0,0 +1,113 @@ +Chinese translated version of Documentation/volatile-considered-harmful.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: Jonathan Corbet +Chinese maintainer: Bryan Wu +--------------------------------------------------------------------- +Documentation/volatile-considered-harmful.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Jonathan Corbet +中文版维护者： 伍鹏 Bryan Wu +中文版翻译者： 伍鹏 Bryan Wu +中文版校译者： 张汉辉 Eugene Teo + 杨瑞 Dave Young +以下为正文 +--------------------------------------------------------------------- + +为什么不应该使用“volatile”类型 +------------------------------ + +C程序员通常认为volatile表示某个变量可以在当前执行的线程之外被改变；因此，在内核 +中用到共享数据结构时，常常会有C程序员喜欢使用volatile这类变量。换句话说，他们经 +常会把volatile类型看成某种简易的原子变量，当然它们不是。在内核中使用volatile几 +乎总是错误的；本文档将解释为什么这样。 + +理解volatile的关键是知道它的目的是用来消除优化，实际上很少有人真正需要这样的应 +用。在内核中，程序员必须防止意外的并发访问破坏共享的数据结构，这其实是一个完全 +不同的任务。用来防止意外并发访问的保护措施，可以更加高效的避免大多数优化相关的 +问题。 + +像volatile一样，内核提供了很多原语来保证并发访问时的数据安全（自旋锁, 互斥量,内 +存屏障等等），同样可以防止意外的优化。如果可以正确使用这些内核原语，那么就没有 +必要再使用volatile。如果仍然必须使用volatile，那么几乎可以肯定在代码的某处有一 +个bug。在正确设计的内核代码中，volatile能带来的仅仅是使事情变慢。 + +思考一下这段典型的内核代码： + + spin_lock(&the_lock); + do_something_on(&shared_data); + do_something_else_with(&shared_data); + spin_unlock(&the_lock); + +如果所有的代码都遵循加锁规则，当持有the_lock的时候，不可能意外的改变shared_data的 +值。任何可能访问该数据的其他代码都会在这个锁上等待。自旋锁原语跟内存屏障一样—— 它 +们显式的用来书写成这样 —— 意味着数据访问不会跨越它们而被优化。所以本来编译器认为 +它知道在shared_data里面将有什么，但是因为spin_lock()调用跟内存屏障一样，会强制编 +译器忘记它所知道的一切。那么在访问这些数据时不会有优化的问题。 + +如果shared_data被声名为volatile，锁操作将仍然是必须的。就算我们知道没有其他人正在 +使用它，编译器也将被阻止优化对临界区内shared_data的访问。在锁有效的同时， +shared_data不是volatile的。在处理共享数据的时候，适当的锁操作可以不再需要 +volatile —— 并且是有潜在危害的。 + +volatile的存储类型最初是为那些内存映射的I/O寄存器而定义。在内核里，寄存器访问也应 +该被锁保护，但是人们也不希望编译器“优化”临界区内的寄存器访问。内核里I/O的内存访问 +是通过访问函数完成的；不赞成通过指针对I/O内存的直接访问，并且不是在所有体系架构上 +都能工作。那些访问函数正是为了防止意外优化而写的，因此，再说一次，volatile类型不 +是必需的。 + +另一种引起用户可能使用volatile的情况是当处理器正忙着等待一个变量的值。正确执行一 +个忙等待的方法是： + + while (my_variable != what_i_want) + cpu_relax(); + +cpu_relax()调用会降低CPU的能量消耗或者让位于超线程双处理器；它也作为内存屏障一样出 +现，所以，再一次，volatile不是必需的。当然，忙等待一开始就是一种反常规的做法。 + +在内核中，一些稀少的情况下volatile仍然是有意义的： + + - 在一些体系架构的系统上，允许直接的I/0内存访问，那么前面提到的访问函数可以使用 + volatile。基本上，每一个访问函数调用它自己都是一个小的临界区域并且保证了按照 + 程序员期望的那样发生访问操作。 + + - 某些会改变内存的内联汇编代码虽然没有什么其他明显的附作用，但是有被GCC删除的可 + 能性。在汇编声明中加上volatile关键字可以防止这种删除操作。 + + - Jiffies变量是一种特殊情况，虽然每次引用它的时候都可以有不同的值，但读jiffies + 变量时不需要任何特殊的加锁保护。所以jiffies变量可以使用volatile，但是不赞成 + 其他跟jiffies相同类型变量使用volatile。Jiffies被认为是一种“愚蠢的遗留物" + （Linus的话）因为解决这个问题比保持现状要麻烦的多。 + + - 由于某些I/0设备可能会修改连续一致的内存,所以有时,指向连续一致内存的数据结构 + 的指针需要正确的使用volatile。网络适配器使用的环状缓存区正是这类情形的一个例 + 子，其中适配器用改变指针来表示哪些描述符已经处理过了。 + +对于大多代码，上述几种可以使用volatile的情况都不适用。所以，使用volatile是一种 +bug并且需要对这样的代码额外仔细检查。那些试图使用volatile的开发人员需要退一步想想 +他们真正想实现的是什么。 + +非常欢迎删除volatile变量的补丁 － 只要证明这些补丁完整的考虑了并发问题。 + +注释 +---- + +[1] http://lwn.net/Articles/233481/ +[2] http://lwn.net/Articles/233482/ + +致谢 +---- + +最初由Randy Dunlap推动并作初步研究 +由Jonathan Corbet撰写 +参考Satyam Sharma，Johannes Stezenbach，Jesper Juhl，Heikki Orsila， +H. Peter Anvin，Philipp Hahn和Stefan Richter的意见改善了本档。 -- cgit v1.2.3 From 22033d38bca82a4a511450562086c69f5dc457ee Mon Sep 17 00:00:00 2001 From: Li Yang Date: Wed, 24 Oct 2007 01:04:21 +0800 Subject: Chinese: add translation of sparse.txt Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/sparse.txt | 100 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 Documentation/zh_CN/sparse.txt (limited to 'Documentation') diff --git a/Documentation/zh_CN/sparse.txt b/Documentation/zh_CN/sparse.txt new file mode 100644 index 00000000000..75992a603ae --- /dev/null +++ b/Documentation/zh_CN/sparse.txt @@ -0,0 +1,100 @@ +Chinese translated version of Documentation/sparse.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: Li Yang +--------------------------------------------------------------------- +Documentation/sparse.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 李阳 Li Yang +中文版翻译者： 李阳 Li Yang + + +以下为正文 +--------------------------------------------------------------------- + +Copyright 2004 Linus Torvalds +Copyright 2004 Pavel Machek +Copyright 2006 Bob Copeland + +使用 sparse 工具做类型检查 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +"__bitwise" 是一种类型属性，所以你应该这样使用它： + + typedef int __bitwise pm_request_t; + + enum pm_request { + PM_SUSPEND = (__force pm_request_t) 1, + PM_RESUME = (__force pm_request_t) 2 + }; + +这样会使 PM_SUSPEND 和 PM_RESUME 成为位方式(bitwise)整数（使用"__force" +是因为 sparse 会抱怨改变位方式的类型转换，但是这里我们确实需要强制进行转 +换）。而且因为所有枚举值都使用了相同的类型，这里的"enum pm_request"也将 +会使用那个类型做为底层实现。 + +而且使用 gcc 编译的时候，所有的 __bitwise/__force 都会消失，最后在 gcc +看来它们只不过是普通的整数。 + +坦白来说，你并不需要使用枚举类型。上面那些实际都可以浓缩成一个特殊的"int +__bitwise"类型。 + +所以更简单的办法只要这样做： + + typedef int __bitwise pm_request_t; + + #define PM_SUSPEND ((__force pm_request_t) 1) + #define PM_RESUME ((__force pm_request_t) 2) + +现在你就有了严格的类型检查所需要的所有基础架构。 + +一个小提醒：常数整数"0"是特殊的。你可以直接把常数零当作位方式整数使用而 +不用担心 sparse 会抱怨。这是因为"bitwise"（恰如其名）是用来确保不同位方 +式类型不会被弄混（小尾模式，大尾模式，cpu尾模式，或者其他），对他们来说 +常数"0"确实是特殊的。 + +获取 sparse 工具 +~~~~~~~~~~~~~~~~ + +你可以从 Sparse 的主页获取最新的发布版本： + + http://www.kernel.org/pub/linux/kernel/people/josh/sparse/ + +或者，你也可以使用 git 克隆最新的 sparse 开发版本： + + git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git + +DaveJ 把每小时自动生成的 git 源码树 tar 包放在以下地址： + + http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ + +一旦你下载了源码，只要以普通用户身份运行： + + make + make install + +它将会被自动安装到你的 ~/bin 目录下。 + +使用 sparse 工具 +~~~~~~~~~~~~~~~~ + +用"make C=1"命令来编译内核，会对所有重新编译的 C 文件使用 sparse 工具。 +或者使用"make C=2"命令，无论文件是否被重新编译都会对其使用 sparse 工具。 +如果你已经编译了内核，用后一种方式可以很快地检查整个源码树。 + +make 的可选变量 CHECKFLAGS 可以用来向 sparse 工具传递参数。编译系统会自 +动向 sparse 工具传递 -Wbitwise 参数。你可以定义 __CHECK_ENDIAN__ 来进行 +大小尾检查。 + + make C=2 CHECKFLAGS="-D__CHECK_ENDIAN__" + +这些检查默认都是被关闭的，因为他们通常会产生大量的警告。 -- cgit v1.2.3 From 463e526083fdaa284eaea45b53bb917ed3c72900 Mon Sep 17 00:00:00 2001 From: Zhang Le Date: Tue, 8 Jan 2008 00:59:16 +0800 Subject: Chinese: add translation of Codingstyle Signed-off-by: Zhang Le Signed-off-by: Li Yang Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/CodingStyle | 701 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 701 insertions(+) create mode 100644 Documentation/zh_CN/CodingStyle (limited to 'Documentation') diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle new file mode 100644 index 00000000000..ecd9307a641 --- /dev/null +++ b/Documentation/zh_CN/CodingStyle @@ -0,0 +1,701 @@ +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: Zhang Le +--------------------------------------------------------------------- +Documentation/CodingStyle的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 +以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 + +中文版维护者： 张乐 Zhang Le +中文版翻译者： 张乐 Zhang Le +中文版校译者： 王聪 Wang Cong + wheelz + 管旭东 Xudong Guan + Li Zefan + Wang Chen +以下为正文 +--------------------------------------------------------------------- + + Linux内核代码风格 + +这是一个简短的文档，描述了linux内核的首选代码风格。代码风格是因人而异的，而且我 +不愿意把我的观点强加给任何人，不过这里所讲述的是我必须要维护的代码所遵守的风格， +并且我也希望绝大多数其他代码也能遵守这个风格。请在写代码时至少考虑一下本文所述的 +风格。 + +首先，我建议你打印一份GNU代码规范，然后不要读它。烧了它，这是一个具有重大象征性 +意义的动作。 + +不管怎样，现在我们开始： + + + 第一章：缩进 + +制表符是8个字符，所以缩进也是8个字符。有些异端运动试图将缩进变为4（乃至2）个字符 +深，这几乎相当于尝试将圆周率的值定义为3。 + +理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的屏幕 +连续看了20小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。 + +现在，有些人会抱怨8个字符的缩进会使代码向右边移动的太远，在80个字符的终端屏幕上 +就很难读这样的代码。这个问题的答案是，如果你需要3级以上的缩进，不管用何种方式你 +的代码已经有问题了，应该修正你的程序。 + +简而言之，8个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的 +时候可以给你警告。留心这个警告。 + +在switch语句中消除多级缩进的首选的方式是让“switch”和从属于它的“case”标签对齐于同 +一列，而不要“两次缩进”“case”标签。比如： + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + + +不要把多个语句放在一行里，除非你有什么东西要隐藏： + + if (condition) do_this; + do_something_everytime; + +也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读的表 +达式。 + +除了注释、文档和Kconfig之外，不要使用空格来缩进，前面的例子是例外，是有意为之。 + +选用一个好的编辑器，不要在行尾留空格。 + + + 第二章：把长的行和字符串打散 + +代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。 + +每一行的长度的限制是80列，我们强烈建议您遵守这个惯例。 + +长于80列的语句要打散成有意义的片段。每个片段要明显短于原来的语句，而且放置的位置 +也明显的靠右。同样的规则也适用于有很长参数列表的函数头。长字符串也要打散成较短的 +字符串。唯一的例外是超过80列可以大幅度提高可读性并且不会隐藏信息的情况。 + +void fun(int a, int b, int c) +{ + if (condition) + printk(KERN_WARNING "Warning this is a long printk with " + "3 parameters a: %u b: %u " + "c: %u \n", a, b, c); + else + next_statement; +} + + 第三章：大括号和空格的放置 + +C语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放置策 +略并没有多少技术上的原因，不过首选的方式，就像Kernighan和Ritchie展示给我们的，是 +把起始大括号放在行尾，而把结束大括号放在行首，所以： + + if (x is true) { + we do y + } + +这适用于所有的非函数语句块（if、switch、for、while、do）。比如： + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +不过，有一个例外，那就是函数：函数的起始大括号放置于下一行的开头，所以： + + int function(int x) + { + body of function + } + +全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道（ +a）K&R是_正确的_，并且（b）K&R是正确的。此外，不管怎样函数都是特殊的（在C语言中 +，函数是不能嵌套的）。 + +注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是do语句中的 +“while”或者if语句中的“else”，像这样： + + do { + body of do-loop + } while (condition); + +和 + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +理由：K&R。 + +也请注意这种大括号的放置方式也能使空（或者差不多空的）行的数量最小化，同时不失可 +读性。因此，由于你的屏幕上的新行是不可再生资源（想想25行的终端屏幕），你将会有更 +多的空行来放置注释。 + +当只有一个单独的语句的时候，不用加不必要的大括号。 + +if (condition) + action(); + +这点不适用于本身为某个条件语句的一个分支的单独语句。这时需要在两个分支里都使用大 +括号。 + +if (condition) { + do_this(); + do_that(); +} else { + otherwise(); +} + + 3.1：空格 + +Linux内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后 +要加一个空格。值得注意的例外是sizeof、typeof、alignof和__attribute__，这些关键字 +某些程度上看起来更像函数（它们在Linux里也常常伴随小括号而使用，尽管在C语言里这样 +的小括号不是必需的，就像“struct fileinfo info”声明过后的“sizeof info”）。 + +所以在这些关键字之后放一个空格： + if, switch, case, for, do, while +但是不要在sizeof、typeof、alignof或者__attribute__这些关键字之后放空格。例如， + s = sizeof(struct file); + +不要在小括号里的表达式两侧加空格。这是一个反例： + + s = sizeof( struct file ); + +当声明指针类型或者返回指针类型的函数时，“*”的首选使用方式是使之靠近变量名或者函 +数名，而不是靠近类型名。例子： + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +在大多数二元和三元操作符两侧使用一个空格，例如下面所有这些操作符： + + = + - < > * / % | & ^ <= >= == != ? : + +但是一元操作符后不要加空格： + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +后缀自加和自减一元操作符前不加空格： + ++ -- + +前缀自加和自减一元操作符后不加空格： + ++ -- + +“.”和“->”结构体成员操作符前后不加空格。 + +不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白，然后你 +就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码，有些编辑器就不 +会移除已经加入的空白，就像你故意留下一个只有空白的行。包含行尾空白的行就这样产 +生了。 + +当git发现补丁包含了行尾空白的时候会警告你，并且可以应你的要求去掉行尾空白；不过 +如果你是正在打一系列补丁，这样做会导致后面的补丁失败，因为你改变了补丁的上下文。 + + + 第四章：命名 + +C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal程序员不同，C程序员不使 +用类似ThisVariableIsATemporaryCounter这样华丽的名字。C程序员会称那个变量为“tmp” +，这样写起来会更容易，而且至少不会令其难于理解。 + +不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的名字 +。称一个全局函数为“foo”是一个难以饶恕的错误。 + +全局变量（只有当你真正需要它们的时候再用它）需要有一个具描述性的名字，就像全局函 +数。如果你有一个可以计算活动用户数量的函数，你应该叫它“count_active_users()”或者 +类似的名字，你不应该叫它“cntuser()”。 + +在函数名中包含函数类型（所谓的匈牙利命名法）是脑子出了问题——编译器知道那些类型而 +且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题的程序。 + +本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计数器 +，它应该被称为“i”。叫它“loop_counter”并无益处，如果它没有被误解的可能的话。类似 +的，“tmp”可以用来称呼任意类型的临时变量。 + +如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综合症 +。请看第六章（函数）。 + + + 第五章：Typedef + +不要使用类似“vps_t”之类的东西。 + +对结构体和指针使用typedef是一个错误。当你在代码里看到： + + vps_t a; + +这代表什么意思呢？ + +相反，如果是这样 + + struct virtual_container *a; + +你就知道“a”是什么了。 + +很多人认为typedef“能提高可读性”。实际不是这样的。它们只在下列情况下有用： + + (a) 完全不透明的对象（这种情况下要主动使用typedef来隐藏这个对象实际上是什么）。 + + 例如：“pte_t”等不透明对象，你只能用合适的访问函数来访问它们。 + + 注意！不透明性和“访问函数”本身是不好的。我们使用pte_t等类型的原因在于真的是 + 完全没有任何共用的可访问信息。 + + (b) 清楚的整数类型，如此，这层抽象就可以帮助消除到底是“int”还是“long”的混淆。 + + u8/u16/u32是完全没有问题的typedef，不过它们更符合类别(d)而不是这里。 + + 再次注意！要这样做，必须事出有因。如果某个变量是“unsigned long“，那么没有必要 + + typedef unsigned long myflags_t; + + 不过如果有一个明确的原因，比如它在某种情况下可能会是一个“unsigned int”而在 + 其他情况下可能为“unsigned long”，那么就不要犹豫，请务必使用typedef。 + + (c) 当你使用sparse按字面的创建一个新类型来做类型检查的时候。 + + (d) 和标准C99类型相同的类型，在某些例外的情况下。 + + 虽然让眼睛和脑筋来适应新的标准类型比如“uint32_t”不需要花很多时间，可是有些 + 人仍然拒绝使用它们。 + + 因此，Linux特有的等同于标准类型的“u8/u16/u32/u64”类型和它们的有符号类型是被 + 允许的——尽管在你自己的新代码中，它们不是强制要求要使用的。 + + 当编辑已经使用了某个类型集的已有代码时，你应该遵循那些代码中已经做出的选择。 + + (e) 可以在用户空间安全使用的类型。 + + 在某些用户空间可见的结构体里，我们不能要求C99类型而且不能用上面提到的“u32” + 类型。因此，我们在与用户空间共享的所有结构体中使用__u32和类似的类型。 + +可能还有其他的情况，不过基本的规则是永远不要使用typedef，除非你可以明确的应用上 +述某个规则中的一个。 + +总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们就不 +应该是一个typedef。 + + + 第六章：函数 + +函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完（我们都知 +道ISO/ANSI屏幕大小是80x24），只做一件事情，而且把它做好。 + +一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理论上 +很简单的只有一个很长（但是简单）的case语句的函数，而且你需要在每个case里做很多很 +小的事情，这样的函数尽管很长，但也是可以的。 + +不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能甚至 +搞不清楚这个函数的目的，你应该严格的遵守前面提到的长度限制。使用辅助函数，并为之 +取个具描述性的名字（如果你觉得它们的性能很重要的话，可以让编译器内联它们，这样的 +效果往往会比你写一个复杂函数的效果要好。） + +函数的另外一个衡量标准是本地变量的数量。此数量不应超过5－10个，否则你的函数就有 +问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松的同时跟 +踪7个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你2 +个星期前做过的事情。 + +在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的EXPORT*宏应该紧贴 +在它的结束大括号之下。比如： + +int system_is_up(void) +{ + return system_state == SYSTEM_RUNNING; +} +EXPORT_SYMBOL(system_is_up); + +在函数原型中，包含函数名和它们的数据类型。虽然C语言里没有这样的要求，在Linux里这 +是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。 + + + 第七章：集中的函数退出途径 + +虽然被某些人声称已经过时，但是goto语句的等价物还是经常被编译器所使用，具体形式是 +无条件跳转指令。 + +当一个函数从多个位置退出并且需要做一些通用的清理工作的时候，goto的好处就显现出来 +了。 + +理由是： + +- 无条件语句容易理解和跟踪 +- 嵌套程度减小 +- 可以避免由于修改时忘记更新某个单独的退出点而导致的错误 +- 减轻了编译器的工作，无需删除冗余代码;) + +int fun(int a) +{ + int result = 0; + char *buffer = kmalloc(SIZE); + + if (buffer == NULL) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out; + } + ... +out: + kfree(buffer); + return result; +} + + 第八章：注释 + +注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的：更好 +的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。 + +一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把注释 +放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能需要回到 +第六章看一看。你可以做一些小注释来注明或警告某些很聪明（或者槽糕）的做法，但不要 +加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么，也可以加上它做这 +些事情的原因。 + +当注释内核API函数时，请使用kernel-doc格式。请看 +Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc以获得详细信息。 + +Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ...”注释。 + +长（多行）的首选注释风格是： + + /* + * This is the preferred style for multi-line + * comments in the Linux kernel source code. + * Please use it consistently. + * + * Description: A column of asterisks on the left side, + * with beginning and ending almost-blank lines. + */ + +注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行应只 +声明一个数据（不要使用逗号来一次声明多个数据）。这样你就有空间来为每个数据写一段 +小注释来解释它们的用途了。 + + + 第九章：你已经把事情弄糟了 + +这没什么，我们都是这样。可能你的使用了很长时间Unix的朋友已经告诉你“GNU emacs”能 +自动帮你格式化C源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们 +想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在GNU emacs里打字永远不 +会创造出一个好程序）（译注：请参考Infinite Monkey Theorem） + +所以你要么放弃GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，你可 +以把下面这段粘贴到你的.emacs文件里。 + +(defun linux-c-mode () + "C mode with adjusted defaults for use with the Linux kernel." + (interactive) + (c-mode) + (c-set-style "K&R") + (setq tab-width 8) + (setq indent-tabs-mode t) + (setq c-basic-offset 8)) + +这样就定义了M-x linux-c-mode命令。当你hack一个模块的时候，如果你把字符串 +-*- linux-c -*-放在头两行的某个位置，这个模式将会被自动调用。如果你希望在你修改 +/usr/src/linux里的文件时魔术般自动打开linux-c-mode的话，你也可能需要添加 + +(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode) + auto-mode-alist)) + +到你的.emacs文件里。 + +不过就算你尝试让emacs正确的格式化代码失败了，也并不意味着你失去了一切：还可以用“ +indent”。 + +不过，GNU indent也有和GNU emacs一样有问题的设定，所以你需要给它一些命令选项。不 +过，这还不算太糟糕，因为就算是GNU indent的作者也认同K&R的权威性（GNU的人并不是坏 +人，他们只是在这个问题上被严重的误导了），所以你只要给indent指定选项“-kr -i8” +（代表“K&R，8个字符缩进”），或者使用“scripts/Lindent”，这样就可以以最时髦的方式 +缩进源代码。 + +“indent”有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过 +记住：“indent”不能修正坏的编程习惯。 + + + 第十章：Kconfig配置文件 + +对于遍布源码树的所有Kconfig*配置文件来说，它们缩进方式与C代码相比有所不同。紧挨 +在“config”定义下面的行缩进一个制表符，帮助信息则再多缩进2个空格。比如： + +config AUDIT + bool "Auditing support" + depends on NET + help + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +仍然被认为不够稳定的功能应该被定义为依赖于“EXPERIMENTAL”： + +config SLUB + depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT + bool "SLUB (Unqueued Allocator)" + ... + +而那些危险的功能（比如某些文件系统的写支持）应该在它们的提示字符串里显著的声明这 +一点： + +config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +要查看配置文件的完整文档，请看Documentation/kbuild/kconfig-language.txt。 + + + 第十一章：数据结构 + +如果一个数据结构，在创建和销毁它的单线执行环境之外可见，那么它必须要有一个引用计 +数器。内核里没有垃圾收集（并且内核之外的垃圾收集慢且效率低下），这意味着你绝对需 +要记录你对这种数据结构的使用情况。 + +引用计数意味着你能够避免上锁，并且允许多个用户并行访问这个数据结构——而不需要担心 +这个数据结构仅仅因为暂时不被使用就消失了，那些用户可能不过是沉睡了一阵或者做了一 +些其他事情而已。 + +注意上锁不能取代引用计数。上锁是为了保持数据结构的一致性，而引用计数是一个内存管 +理技巧。通常二者都需要，不要把两个搞混了。 + +很多数据结构实际上有2级引用计数，它们通常有不同“类”的用户。子类计数器统计子类用 +户的数量，每当子类计数器减至零时，全局计数器减一。 + +这种“多级引用计数”的例子可以在内存管理（“struct mm_struct”：mm_users和mm_count） +和文件系统（“struct super_block”：s_count和s_active）中找到。 + +记住：如果另一个执行线索可以找到你的数据结构，但是这个数据结构没有引用计数器，这 +里几乎肯定是一个bug。 + + + 第十二章：宏，枚举和RTL + +用于定义常量的宏的名字及枚举里的标签需要大写。 + +#define CONSTANT 0x12345 + +在定义几个相关的常量时，最好用枚举。 + +宏的名字请用大写字母，不过形如函数的宏的名字可以用小写字母。 + +一般的，如果能写成内联函数就不要写成像函数的宏。 + +含有多个语句的宏应该被包含在一个do-while代码块里： + +#define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +使用宏的时候应避免的事情： + +1) 影响控制流程的宏： + +#define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while(0) + +非常不好。它看起来像一个函数，不过却能导致“调用”它的函数退出；不要打乱读者大脑里 +的语法分析器。 + +2) 依赖于一个固定名字的本地变量的宏： + +#define FOO(val) bar(index, val) + +可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起来 +不相关的改动带来错误。 + +3) 作为左值的带参数的宏： FOO(x) = y；如果有人把FOO变成一个内联函数的话，这种用 +法就会出错了。 + +4) 忘记了优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数的 +宏也要注意此类问题。 + +#define CONSTANT 0x4000 +#define CONSTEXP (CONSTANT | 3) + +cpp手册对宏的讲解很详细。Gcc internals手册也详细讲解了RTL（译注：register +transfer language），内核里的汇编语言经常用到它。 + + + 第十三章：打印内核消息 + +内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。不要 +用不规范的单词比如“dont”，而要用“do not”或者“don't”。保证这些信息简单、明了、无 +歧义。 + +内核信息不必以句号（译注：英文句号，即点）结束。 + +在小括号里打印数字(%d)没有任何价值，应该避免这样做。 + +里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的 +设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err(), dev_warn(), +dev_info()等等。对于那些不和某个特定设备相关连的信息，定义了 +pr_debug()和pr_info()。 + +写出好的调试信息可以是一个很大的挑战；当你写出来之后，这些信息在远程除错的时候 +就会成为极大的帮助。当DEBUG符号没有被定义的时候，这些信息不应该被编译进内核里 +（也就是说，默认地，它们不应该被包含在内）。如果你使用dev_dbg()或者pr_debug()， +就能自动达到这个效果。很多子系统拥有Kconfig选项来启用-DDEBUG。还有一个相关的惯例 +是使用VERBOSE_DEBUG来添加dev_vdbg()消息到那些已经由DEBUG启用的消息之上。 + + + 第十四章：分配内存 + +内核提供了下面的一般用途的内存分配函数：kmalloc()，kzalloc()，kcalloc()和 +vmalloc()。请参考API文档以获取有关它们的详细信息。 + +传递结构体大小的首选形式是这样的： + + p = kmalloc(sizeof(*p), ...); + +另外一种传递方式中，sizeof的操作数是结构体的名字，这样会降低可读性，并且可能会引 +入bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的sizeof的结果不变。 + +强制转换一个void指针返回值是多余的。C语言本身保证了从void指针到其他任何指针类型 +的转换是没有问题的。 + + + 第十五章：内联弊病 + +有一个常见的误解是内联函数是gcc提供的可以让代码运行更快的一个选项。虽然使用内联 +函数有时候是恰当的（比如作为一种替代宏的方式，请看第十二章），不过很多情况下不是 +这样。inline关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核 +会占用更多的指令高速缓存（译注：一级缓存通常是指令缓存和数据缓存分开的）而且会导 +致pagecache的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址，将 +耗时5毫秒。5毫秒的时间内CPU能执行很多很多指令。 + +一个基本的原则是如果一个函数有3行以上，就不要把它变成内联函数。这个原则的一个例 +外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在编译时能 +优化掉你的函数的大部分代码，那仍然可以给它加上inline关键字。kmalloc()内联函数就 +是一个很好的例子。 + +人们经常主张给static的而且只用了一次的函数加上inline，如此不会有任何损失，因为没 +有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加inline gcc +也可以自动使其内联。而且其他用户可能会要求移除inline，由此而来的争论会抵消inline +自身的潜在价值，得不偿失。 + + + 第十六章：函数返回值及命名 + +函数可以返回很多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样 +的一个值可以表示为一个错误代码整数（-Exxx＝失败，0＝成功）或者一个“成功”布尔值（ +0＝失败，非0＝成功）。 + +混合使用这两种表达方式是难于发现的bug的来源。如果C语言本身严格区分整形和布尔型变 +量，那么编译器就能够帮我们发现这些错误……不过C语言不区分。为了避免产生这种bug，请 +遵循下面的惯例： + + 如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代码整 + 数。如果是一个判断，那么函数应该返回一个“成功”布尔值。 + +比如，“add work”是一个命令，所以add_work()函数在成功时返回0，在失败时返回-EBUSY。 +类似的，因为“PCI device present”是一个判断，所以pci_dev_present()函数在成功找到 +一个匹配的设备时应该返回1，如果找不到时应该返回0。 + +所有导出（译注：EXPORT）的函数都必须遵守这个惯例，所有的公共函数也都应该如此。私 +有（static）函数不需要如此，但是我们也推荐这样做。 + +返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的，他们 +通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数，他们使用 +NULL或者ERR_PTR机制来报告错误。 + + + 第十七章：不要重新发明内核宏 + +头文件include/linux/kernel.h包含了一些宏，你应该使用它们，而不要自己写一些它们的 +变种。比如，如果你需要计算一个数组的长度，使用这个宏 + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +类似的，如果你要计算某结构体成员的大小，使用 + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +还有可以做严格的类型检查的min()和max()宏，如果你需要可以使用它们。你可以自己看看 +那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应在你的代码里 +自己重新定义。 + + + 第十八章：编辑器模式行和其他需要罗嗦的事情 + +有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs +能够解释被标记成这样的行： + +-*- mode: c -*- + +或者这样的： + +/* +Local Variables: +compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" +End: +*/ + +Vim能够解释这样的标记： + +/* vim:set sw=8 noet */ + +不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置，你的源文件不应 +该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制的模 +式，或者使用其他可以产生正确的缩进的巧妙方法。 + + + + 附录 I：参考 + +The C Programming Language, 第二版, 作者Brian W. Kernighan和Denni +M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8 (软皮), +0-13-110370-9 (硬皮). URL: http://cm.bell-labs.com/cm/cs/cbook/ + +The Practice of Programming 作者Brian W. Kernighan和Rob Pike. Addison-Wesley, +Inc., 1999. ISBN 0-201-61586-X. URL: http://cm.bell-labs.com/cm/cs/tpop/ + +cpp，gcc，gcc internals和indent的GNU手册——和K&R及本文相符合的部分，全部可以在 +http://www.gnu.org/manual/找到 + +WG14是C语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel CodingStyle，作者greg@kroah.com发表于OLS 2002： +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ + +-- +最后更新于2007年7月13日。 -- cgit v1.2.3 From b1c7192df1b089ed654c76fbf14d7f7dbf4b9616 Mon Sep 17 00:00:00 2001 From: "Robert P. J. Day" Date: Wed, 7 Nov 2007 04:09:46 -0500 Subject: Documentation: Replace obsolete "driverfs" with "sysfs". Signed-off-by: Robert P. J. Day --- Documentation/pnp.txt | 4 ++-- Documentation/s390/cds.txt | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/pnp.txt b/Documentation/pnp.txt index 481faf515d5..a327db67782 100644 --- a/Documentation/pnp.txt +++ b/Documentation/pnp.txt @@ -17,9 +17,9 @@ The User Interface ------------------ The Linux Plug and Play user interface provides a means to activate PnP devices for legacy and user level drivers that do not support Linux Plug and Play. The -user interface is integrated into driverfs. +user interface is integrated into sysfs. -In addition to the standard driverfs file the following are created in each +In addition to the standard sysfs file the following are created in each device's directory: id - displays a list of support EISA IDs options - displays possible resource configurations diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.txt index 3081927cc2d..c4b7b2bd369 100644 --- a/Documentation/s390/cds.txt +++ b/Documentation/s390/cds.txt @@ -133,7 +133,7 @@ During its startup the Linux/390 system checks for peripheral devices. Each of those devices is uniquely defined by a so called subchannel by the ESA/390 channel subsystem. While the subchannel numbers are system generated, each subchannel also takes a user defined attribute, the so called device number. -Both subchannel number and device number cannot exceed 65535. During driverfs +Both subchannel number and device number cannot exceed 65535. During sysfs initialisation, the information about control unit type and device types that imply specific I/O commands (channel command words - CCWs) in order to operate the device are gathered. Device drivers can retrieve this set of hardware -- cgit v1.2.3 From 081248de0a0288a0ce4e1447a07ccf56aa4fae01 Mon Sep 17 00:00:00 2001 From: Greg Kroah-Hartman Date: Thu, 1 Nov 2007 09:29:06 -0600 Subject: kset: move /sys/slab to /sys/kernel/slab /sys/kernel is where these things should go. Also updated the documentation and tool that used this directory. Cc: Kay Sievers Acked-by: Christoph Lameter Signed-off-by: Greg Kroah-Hartman --- Documentation/vm/slabinfo.c | 2 +- Documentation/vm/slub.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/vm/slabinfo.c b/Documentation/vm/slabinfo.c index 7047696c47a..488c1f31b99 100644 --- a/Documentation/vm/slabinfo.c +++ b/Documentation/vm/slabinfo.c @@ -1021,7 +1021,7 @@ void read_slab_dir(void) char *t; int count; - if (chdir("/sys/slab")) + if (chdir("/sys/kernel/slab")) fatal("SYSFS support for SLUB not active\n"); dir = opendir("."); diff --git a/Documentation/vm/slub.txt b/Documentation/vm/slub.txt index d17f324db9f..dcf8bcf846d 100644 --- a/Documentation/vm/slub.txt +++ b/Documentation/vm/slub.txt @@ -63,7 +63,7 @@ In case you forgot to enable debugging on the kernel command line: It is possible to enable debugging manually when the kernel is up. Look at the contents of: -/sys/slab// +/sys/kernel/slab// Look at the writable files. Writing 1 to them will enable the corresponding debug option. All options can be set on a slab that does -- cgit v1.2.3 From 5008743dc7f98dd1ad4f20f4d7ff0b479e78895d Mon Sep 17 00:00:00 2001 From: Greg Kroah-Hartman Date: Tue, 27 Nov 2007 11:28:26 -0800 Subject: kobject: remove old, outdated documentation. As we are replacing the documentation, it's easier to do this in a two stage pass, delete the old file and add the new one. Cc: Kay Sievers Signed-off-by: Greg Kroah-Hartman --- Documentation/kobject.txt | 289 ---------------------------------------------- 1 file changed, 289 deletions(-) delete mode 100644 Documentation/kobject.txt (limited to 'Documentation') diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt deleted file mode 100644 index ca86a885ad8..00000000000 --- a/Documentation/kobject.txt +++ /dev/null @@ -1,289 +0,0 @@ -The kobject Infrastructure - -Patrick Mochel - -Updated: 3 June 2003 - - -Copyright (c) 2003 Patrick Mochel -Copyright (c) 2003 Open Source Development Labs - - -0. Introduction - -The kobject infrastructure performs basic object management that larger -data structures and subsystems can leverage, rather than reimplement -similar functionality. This functionality primarily concerns: - -- Object reference counting. -- Maintaining lists (sets) of objects. -- Object set locking. -- Userspace representation. - -The infrastructure consists of a number of object types to support -this functionality. Their programming interfaces are described below -in detail, and briefly here: - -- kobjects a simple object. -- kset a set of objects of a certain type. -- ktype a set of helpers for objects of a common type. - - -The kobject infrastructure maintains a close relationship with the -sysfs filesystem. Each kobject that is registered with the kobject -core receives a directory in sysfs. Attributes about the kobject can -then be exported. Please see Documentation/filesystems/sysfs.txt for -more information. - -The kobject infrastructure provides a flexible programming interface, -and allows kobjects and ksets to be used without being registered -(i.e. with no sysfs representation). This is also described later. - - -1. kobjects - -1.1 Description - - -struct kobject is a simple data type that provides a foundation for -more complex object types. It provides a set of basic fields that -almost all complex data types share. kobjects are intended to be -embedded in larger data structures and replace fields they duplicate. - -1.2 Definition - -struct kobject { - const char * k_name; - struct kref kref; - struct list_head entry; - struct kobject * parent; - struct kset * kset; - struct kobj_type * ktype; - struct sysfs_dirent * sd; - wait_queue_head_t poll; -}; - -void kobject_init(struct kobject *); -int kobject_add(struct kobject *); -int kobject_register(struct kobject *); - -void kobject_del(struct kobject *); -void kobject_unregister(struct kobject *); - -struct kobject * kobject_get(struct kobject *); -void kobject_put(struct kobject *); - - -1.3 kobject Programming Interface - -kobjects may be dynamically added and removed from the kobject core -using kobject_register() and kobject_unregister(). Registration -includes inserting the kobject in the list of its dominant kset and -creating a directory for it in sysfs. - -Alternatively, one may use a kobject without adding it to its kset's list -or exporting it via sysfs, by simply calling kobject_init(). An -initialized kobject may later be added to the object hierarchy by -calling kobject_add(). An initialized kobject may be used for -reference counting. - -Note: calling kobject_init() then kobject_add() is functionally -equivalent to calling kobject_register(). - -When a kobject is unregistered, it is removed from its kset's list, -removed from the sysfs filesystem, and its reference count is decremented. -List and sysfs removal happen in kobject_del(), and may be called -manually. kobject_put() decrements the reference count, and may also -be called manually. - -A kobject's reference count may be incremented with kobject_get(), -which returns a valid reference to a kobject; and decremented with -kobject_put(). An object's reference count may only be incremented if -it is already positive. - -When a kobject's reference count reaches 0, the method struct -kobj_type::release() (which the kobject's kset points to) is called. -This allows any memory allocated for the object to be freed. - - -NOTE!!! - -It is _imperative_ that you supply a destructor for dynamically -allocated kobjects to free them if you are using kobject reference -counts. The reference count controls the lifetime of the object. -If it goes to 0, then it is assumed that the object will -be freed and cannot be used. - -More importantly, you must free the object there, and not immediately -after an unregister call. If someone else is referencing the object -(e.g. through a sysfs file), they will obtain a reference to the -object, assume it's valid and operate on it. If the object is -unregistered and freed in the meantime, the operation will then -reference freed memory and go boom. - -This can be prevented, in the simplest case, by defining a release -method and freeing the object from there only. Note that this will not -secure reference count/object management models that use a dual -reference count or do other wacky things with the reference count -(like the networking layer). - - -1.4 sysfs - -Each kobject receives a directory in sysfs. This directory is created -under the kobject's parent directory. - -If a kobject does not have a parent when it is registered, its parent -becomes its dominant kset. - -If a kobject does not have a parent nor a dominant kset, its directory -is created at the top-level of the sysfs partition. - - - -2. ksets - -2.1 Description - -A kset is a set of kobjects that are embedded in the same type. - - -struct kset { - struct kobj_type * ktype; - struct list_head list; - struct kobject kobj; - struct kset_uevent_ops * uevent_ops; -}; - - -void kset_init(struct kset * k); -int kset_add(struct kset * k); -int kset_register(struct kset * k); -void kset_unregister(struct kset * k); - -struct kset * kset_get(struct kset * k); -void kset_put(struct kset * k); - -struct kobject * kset_find_obj(struct kset *, char *); - - -The type that the kobjects are embedded in is described by the ktype -pointer. - -A kset contains a kobject itself, meaning that it may be registered in -the kobject hierarchy and exported via sysfs. More importantly, the -kset may be embedded in a larger data type, and may be part of another -kset (of that object type). - -For example, a block device is an object (struct gendisk) that is -contained in a set of block devices. It may also contain a set of -partitions (struct hd_struct) that have been found on the device. The -following code snippet illustrates how to express this properly. - - struct gendisk * disk; - ... - disk->kset.kobj.kset = &block_kset; - disk->kset.ktype = &partition_ktype; - kset_register(&disk->kset); - -- The kset that the disk's embedded object belongs to is the - block_kset, and is pointed to by disk->kset.kobj.kset. - -- The type of objects on the disk's _subordinate_ list are partitions, - and is set in disk->kset.ktype. - -- The kset is then registered, which handles initializing and adding - the embedded kobject to the hierarchy. - - -2.2 kset Programming Interface - -All kset functions, except kset_find_obj(), eventually forward the -calls to their embedded kobjects after performing kset-specific -operations. ksets offer a similar programming model to kobjects: they -may be used after they are initialized, without registering them in -the hierarchy. - -kset_find_obj() may be used to locate a kobject with a particular -name. The kobject, if found, is returned. - -There are also some helper functions which names point to the formerly -existing "struct subsystem", whose functions have been taken over by -ksets. - - -decl_subsys(name,type,uevent_ops) - -Declares a kset named '_subsys' of type with -uevent_ops . For example, - -decl_subsys(devices, &ktype_device, &device_uevent_ops); - -is equivalent to doing: - -struct kset devices_subsys = { - .ktype = &ktype_devices, - .uevent_ops = &device_uevent_ops, -}; -kobject_set_name(&devices_subsys, name); - -The objects that are registered with a subsystem that use the -subsystem's default list must have their kset ptr set properly. These -objects may have embedded kobjects or ksets. The -following helper makes setting the kset easier: - - -kobj_set_kset_s(obj,subsys) - -- Assumes that obj->kobj exists, and is a struct kobject. -- Sets the kset of that kobject to the kset . - -int subsystem_register(struct kset *s); -void subsystem_unregister(struct kset *s); - -These are just wrappers around the respective kset_* functions. - -2.3 sysfs - -ksets are represented in sysfs when their embedded kobjects are -registered. They follow the same rules of parenting, with one -exception. If a kset does not have a parent, nor is its embedded -kobject part of another kset, the kset's parent becomes its dominant -subsystem. - -If the kset does not have a parent, its directory is created at the -sysfs root. This should only happen when the kset registered is -embedded in a subsystem itself. - - -3. struct ktype - -3.1. Description - -struct kobj_type { - void (*release)(struct kobject *); - struct sysfs_ops * sysfs_ops; - struct attribute ** default_attrs; -}; - - -Object types require specific functions for converting between the -generic object and the more complex type. struct kobj_type provides -the object-specific fields, which include: - -- release: Called when the kobject's reference count reaches 0. This - should convert the object to the more complex type and free it. - -- sysfs_ops: Provides conversion functions for sysfs access. Please - see the sysfs documentation for more information. - -- default_attrs: Default attributes to be exported via sysfs when the - object is registered.Note that the last attribute has to be - initialized to NULL ! You can find a complete implementation - in block/genhd.c - - -Instances of struct kobj_type are not registered; only referenced by -the kset. A kobj_type may be referenced by an arbitrary number of -ksets, as there may be disparate sets of identical objects. - -- cgit v1.2.3 From 36d78d6c5b50ba945bbdee9bf1d8daac00154e02 Mon Sep 17 00:00:00 2001 From: Greg Kroah-Hartman Date: Tue, 27 Nov 2007 11:28:26 -0800 Subject: kobject: update the kobject/kset documentation This provides a much-needed kobject and kset documentation update. Thanks to Kay Sievers, Alan Stern, Jonathan Corbet, Randy Dunlap, Jan Engelhardt, and others for reviewing and providing help with this document. Cc: Kay Sievers Signed-off-by: Greg Kroah-Hartman --- Documentation/kobject.txt | 386 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 386 insertions(+) create mode 100644 Documentation/kobject.txt (limited to 'Documentation') diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt new file mode 100644 index 00000000000..bf3256e0402 --- /dev/null +++ b/Documentation/kobject.txt @@ -0,0 +1,386 @@ +Everything you never wanted to know about kobjects, ksets, and ktypes + +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. + + - 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. + + 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. + + 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. + + - 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. + + - 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. + + When you see a sysfs directory full of other directories, generally each + of those directories corresponds to a kobject in the same kset. + +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. + + +Embedding kobjects + +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. + +So, for example, the UIO code has a structure that defines the memory +region associated with a uio device: + +struct uio_mem { + struct kobject kobj; + unsigned long addr; + unsigned long size; + int memtype; + void __iomem *internal_addr; +}; + +If you have a struct uio_mem 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 : + + 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. The return value from container_of() is a pointer to +the given type. So, for example, a pointer "kp" to a struct kobject +embedded within a struct uio_mem could be converted to a pointer to the +containing uio_mem structure with: + + struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj); + +Programmers often define a simple macro for "back-casting" kobject pointers +to the containing type. + + +Initialization of kobjects + +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(): + + 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: + + 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. + +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(): + + int kobject_rename(struct kobject *kobj, const char *new_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. + +To properly access the name of the kobject, use the function +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 supprisingly enough 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. + + +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(): + + 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. + +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. + + +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: + + 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. + +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. + +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. + +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. + + +Creating "simple" kobjects + +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: + + 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: + + 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. + +See the example module, samples/kobject/kobject-example.c for an +implementation of a simple kobject and attributes. + + + +ktypes and release methods + +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. + +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. + +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. + +This notification is done through a kobject's release() method. Usually +such a method has a form like: + + void my_object_release(struct kobject *kobj) + { + struct my_object *mine = container_of(kobj, struct my_object, kobj); + + /* Perform any additional cleanup on this object, then... */ + 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. + +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. + +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: + + struct kobj_type { + void (*release)(struct kobject *); + 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(). + +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. + +The default_attrs pointer is a list of default attributes that will be +automatically created for any kobject that is registered with this ktype. + + +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. + +A kset serves these functions: + + - 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." + + - 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. + + - Ksets can support the "hotplugging" of kobjects and influence how + uevent events are reported to user space. + +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. + +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 ket have that kset (or, strictly, its embedded +kobject) in their parent. + +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: + 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: + 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. + +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: + +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. + +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. + +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. + +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. + +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. + + +Kobject removal + +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. + +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_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. + + +Example code to copy from + +For a more complete example of using ksets and kobjects properly, see the +sample/kobject/kset-example.c code. -- cgit v1.2.3