立你斯學習記錄

Chapter 15: The inline disease

There appears to be a common misperception that gcc has a magic "make me faster" speedup option called "inline". While the use of inlines can be appropriate (for example as a means of replacing macros, see Chapter 12), it very often is not. Abundant use of the inline keyword leads to a much bigger kernel, which in turn slows the system as a whole down, due to a bigger icache footprint for the CPU and simply because there is less memory available for the pagecache. Just think about it; a pagecache miss causes a

disk seek, which easily takes 5 miliseconds. There are a LOT of cpu cycles that can go into these 5 miliseconds.

A reasonable rule of thumb is to not put inline at functions that have more than 3 lines of code in them. An exception to this rule are the cases where a parameter is known to be a compiletime constant, and as a result of this constantness you *know* the compiler will be able to optimize most of your function away at compile time. For a good example of this later case, see the kmalloc() inline function.

Often people argue that adding inline to functions that are static and used only once is always a win since there is no space tradeoff. While this is technically correct, gcc is capable of inlining these automatically without help, and the maintenance issue of removing the inline when a second user appears outweighs the potential value of the hint that tells gcc to do something it would have done anyway.

         Chapter 16: Function return values and names

Functions can return values of many different kinds, and one of the most common is a value indicating whether the function succeeded or failed.  Such a value can be represented as an error-code integer (-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure, non-zero = success).

函式可以有很多不同型式的回傳值，而且最常見的是回傳表示函式是否成功或失敗的值。這樣的值可以表示完整的錯誤碼 (-Exxx = 失敗，0 = 成功)或一個布林值(0 = 失敗，non-zero = 成功) 。

Mixing up these two sorts of representations is a fertile source of difficult-to-find bugs.  If the C language included a strong distinction between integers and booleans then the compiler would find these mistakes for us... but it doesn't.  To help prevent such bugs, always follow this convention:

混淆這兩種表達方法是很難發現程式中的錯誤。如果C語言可以判別整數和布林值之間的區別，那麼編譯器將為我們找這些錯誤... 但是它不。為了幫助防止這樣的缺陷，總是遵守這些規範︰

        If the name of a function is an action or an imperative command,

        the function should return an error-code integer.  If the name

        is a predicate, the function should return a "succeeded" boolean.

        如果一個函式的名字是一個動作或者緊急的命令，功能應該回傳

        一個整數的錯誤代碼。如果名字是一個描述語 (predicate)，功能

        應該回傳 "成功" 的布林值。

For example, "add work" is a command, and the add_work() function returns 0 for success or -EBUSY for failure.  In the same way, "PCI device present" is a predicate, and the pci_dev_present() function returns 1 if it succeeds in finding a matching device or 0 if it doesn't.

例如，"增加工作 (add work) " 是一個命令，和add_work()函式在成功時回傳0或失敗時回傳 -EBUSY。同樣，"PCI device present" 是一個描述語和pci_dev_present()函式在成功找到符合的裝置時回傳1或在它沒找到時回傳0。

All EXPORTed functions must respect this convention, and so should all public functions.  Private (static) functions need not, but it is recommended that they do.

公用 (public) 函式和出口 (EXPORT) 函式的回傳值必須遵守這個規範。但私人 (static靜態)函式就可不必，但仍建議去遵守。

Functions whose return value is the actual result of a computation, rather than an indication of whether the computation succeeded, are not subject to this rule.  Generally they indicate failure by returning some out-of-range result.  Typical examples would be functions that return pointers; they use NULL or the ERR_PTR mechanism to report failure.

回傳值是經過函式計算過的實際結果，而不是表示函式是否成功，就不受這個規範影響。通常他們透過回傳一些在範圍之外 (out-of-range) 的結果來表示失敗。典型的例子是函式回傳指標時；他們使用NULL或者ERR_PTR來表示失敗。

         Chapter 17:  Don't re-invent the kernel macros

The header file include/linux/kernel.h contains a number of macros that you should use, rather than explicitly coding some variant of them yourself.

For example, if you need to calculate the length of an array, take advantage of the macro

  #define ARRAY_SIZE(x)          (sizeof(x) / sizeof((x)[0]))

Similarly, if you need to calculate the size of some structure member, use

  #define FIELD_SIZEOF(t, f)     (sizeof(((t*)0)->f))

There are also min() and max() macros that do strict type checking if you need them.  Feel free to peruse that header file to see what else is already defined that you shouldn't reproduce in your code.

         Chapter 18:  Editor modelines and other cruft

Some editors can interpret configuration information embedded in source files, indicated with special markers.  For example, emacs interprets lines marked like this:

-*- mode: c -*-

Or like this:

/*

Local Variables:

compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"

End:

*/

Vim interprets markers that look like this:

/* vim:set sw=8 noet */

Do not include any of these in source files.  People have their own personal editor configurations, and your source files should not override them.  This includes markers for indentation and mode configuration.  People may use their own custom mode, or may have some other magic method for making indentation work correctly.

         Appendix I: References

The C Programming Language, Second Edition

by Brian W. Kernighan and Dennis M. Ritchie.

Prentice Hall, Inc., 1988.

ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).

URL: http://cm.bell-labs.com/cm/cs/cbook/

The Practice of Programming

by Brian W. Kernighan and Rob Pike.

Addison-Wesley, Inc., 1999.

ISBN 0-201-61586-X.

URL: http://cm.bell-labs.com/cm/cs/tpop/

GNU manuals - where in compliance with K&R and this text - for cpp, gcc,

gcc internals and indent, all available from http://www.gnu.org/manual/

WG14 is the international standardization working group for the programming

language C, URL: http://www.open-std.org/JTC1/SC22/WG14/

Kernel CodingStyle, by greg@kroah.com at OLS 2002:

http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/

--

Last updated on 2007-July-13.