Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1486354 > unrolled thread
| Started by | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| First post | 2016-09-19 13:10 +0200 |
| Last post | 2016-09-21 11:30 +0200 |
| Articles | 12 on this page of 32 — 3 participants |
Back to article view | Back to linux.kernel
[PATCH v4 00/29] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 09/29] Documentation/Changes: add minimal requirements for documentation build Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 01/29] doc-rst: add CSS styles for :kbd: and :menuselection: Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 08/29] Documentation/Changes: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 03/29] doc: development-process: rename files to rst Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 04/29] docs-rst: create a book for the development process Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 05/29] Documentation/HOWTO: convert to ReST notation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 06/29] Documentation/applying-patches.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 28/29] Documentation/email-clients.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 25/29] Documentation/HOWTO: adjust external link references Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 11/29] Documentation/CodingStyle: use the proper tag for verbatim font Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 14/29] Documentation/ManagementStyle: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
Re: [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup Greg KH <greg@kroah.com> - 2016-09-20 09:10 +0200
[PATCH v4 12/29] Documentation/CodingStyle: replace underline markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 27/29] Documentation/SubmitChecklist: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 02/29] doc: development-process: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 16/29] Documentation/stable_api_nonsense.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 20/29] Documentation/SubmittingPatches: enrich the Sphinx output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 07/29] Documentation/applying-patches.txt: Update the information there Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 10/29] Documentation/CodingStyle: Convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 24/29] Documentation/HOWTO: improve some markups to make it visually better Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 13/29] Documentation/CodingStyle: use the .. note:: markup where needed Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 23/29] Documentation/HOWTO: update information about generating documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
Re: [PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents Greg KH <greg@kroah.com> - 2016-09-20 09:10 +0200
[PATCH v4 26/29] Documentation/SubmitChecklist: update kernel-doc task Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 15/29] Documentation/SecurityBugs: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 19/29] Documentation/SubmittingPatches: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 18/29] Documentation/SubmittingDrivers: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
Re: [PATCH v4 00/29] Create a book for Kernel development Jonathan Corbet <corbet@lwn.net> - 2016-09-21 02:50 +0200
Re: [PATCH v4 00/29] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-21 11:30 +0200
Page 2 of 2 — ← Prev page 1 [2]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 10/29] Documentation/CodingStyle: Convert to ReST markup |
| Message-ID | <sj4Ma-4KI-43@gated-at.bofh.it> |
| In reply to | #1486354 |
- Fix all chapter identation;
- add c blocks where needed;
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/CodingStyle | 257 ++++++++++++++++++++++++++++++++--------------
1 file changed, 180 insertions(+), 77 deletions(-)
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 0f1dbd87eb48..f103de7e2028 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -1,5 +1,5 @@
-
- Linux kernel coding style
+Linux kernel coding style
+=========================
This is a short document describing the preferred coding style for the
linux kernel. Coding style is very personal, and I won't _force_ my
@@ -13,7 +13,8 @@ and NOT read it. Burn them, it's a great symbolic gesture.
Anyway, here goes:
- Chapter 1: Indentation
+1) Indentation
+--------------
Tabs are 8 characters, and thus indentations are also 8 characters.
There are heretic movements that try to make indentations 4 (or even 2!)
@@ -39,6 +40,8 @@ The preferred way to ease multiple indentation levels in a switch statement is
to align the "switch" and its subordinate "case" labels in the same column
instead of "double-indenting" the "case" labels. E.g.:
+.. code-block:: c
+
switch (suffix) {
case 'G':
case 'g':
@@ -59,6 +62,8 @@ instead of "double-indenting" the "case" labels. E.g.:
Don't put multiple statements on a single line unless you have
something to hide:
+.. code-block:: c
+
if (condition) do_this;
do_something_everytime;
@@ -71,7 +76,8 @@ used for indentation, and the above example is deliberately broken.
Get a decent editor and don't leave whitespace at the end of lines.
- Chapter 2: Breaking long lines and strings
+2) Breaking long lines and strings
+----------------------------------
Coding style is all about readability and maintainability using commonly
available tools.
@@ -87,7 +93,8 @@ with a long argument list. However, never break user-visible strings such as
printk messages, because that breaks the ability to grep for them.
- Chapter 3: Placing Braces and Spaces
+3) Placing Braces and Spaces
+----------------------------
The other issue that always comes up in C styling is the placement of
braces. Unlike the indent size, there are few technical reasons to
@@ -95,6 +102,8 @@ choose one placement strategy over the other, but the preferred way, as
shown to us by the prophets Kernighan and Ritchie, is to put the opening
brace last on the line, and put the closing brace first, thusly:
+.. code-block:: c
+
if (x is true) {
we do y
}
@@ -102,6 +111,8 @@ brace last on the line, and put the closing brace first, thusly:
This applies to all non-function statement blocks (if, switch, for,
while, do). E.g.:
+.. code-block:: c
+
switch (action) {
case KOBJ_ADD:
return "add";
@@ -116,6 +127,8 @@ while, do). E.g.:
However, there is one special case, namely functions: they have the
opening brace at the beginning of the next line, thus:
+.. code-block:: c
+
int function(int x)
{
body of function
@@ -131,12 +144,16 @@ the cases where it is followed by a continuation of the same statement,
ie a "while" in a do-statement or an "else" in an if-statement, like
this:
+.. code-block:: c
+
do {
body of do-loop
} while (condition);
and
+.. code-block:: c
+
if (x == y) {
..
} else if (x > y) {
@@ -155,11 +172,15 @@ comments on.
Do not unnecessarily use braces where a single statement will do.
+.. code-block:: c
+
if (condition)
action();
and
+.. code-block:: none
+
if (condition)
do_this();
else
@@ -168,6 +189,8 @@ and
This does not apply if only one branch of a conditional statement is a single
statement; in the latter case use braces in both branches:
+.. code-block:: c
+
if (condition) {
do_this();
do_that();
@@ -175,50 +198,60 @@ statement; in the latter case use braces in both branches:
otherwise();
}
- 3.1: Spaces
+3.1) Spaces
+***********
Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The
notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
somewhat like functions (and are usually used with parentheses in Linux,
-although they are not required in the language, as in: "sizeof info" after
-"struct fileinfo info;" is declared).
+although they are not required in the language, as in: ``sizeof info`` after
+``struct fileinfo info;`` is declared).
-So use a space after these keywords:
+So use a space after these keywords::
if, switch, case, for, do, while
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
+.. code-block:: c
+
+
s = sizeof(struct file);
Do not add spaces around (inside) parenthesized expressions. This example is
-*bad*:
+**bad**:
+
+.. code-block:: c
+
s = sizeof( struct file );
When declaring pointer data or a function that returns a pointer type, the
-preferred use of '*' is adjacent to the data name or function name and not
+preferred use of '\*' is adjacent to the data name or function name and not
adjacent to the type name. Examples:
+.. code-block:: c
+
+
char *linux_banner;
unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s);
Use one space around (on each side of) most binary and ternary operators,
-such as any of these:
+such as any of these::
= + - < > * / % | & ^ <= >= == != ? :
-but no space after unary operators:
+but no space after unary operators::
& * + - ~ ! sizeof typeof alignof __attribute__ defined
-no space before the postfix increment & decrement unary operators:
+no space before the postfix increment & decrement unary operators::
++ --
-no space after the prefix increment & decrement unary operators:
+no space after the prefix increment & decrement unary operators::
++ --
@@ -237,7 +270,8 @@ of patches, this may make later patches in the series fail by changing their
context lines.
- Chapter 4: Naming
+4) Naming
+---------
C is a Spartan language, and so should your naming be. Unlike Modula-2
and Pascal programmers, C programmers do not use cute names like
@@ -270,16 +304,22 @@ problem, which is called the function-growth-hormone-imbalance syndrome.
See chapter 6 (Functions).
- Chapter 5: Typedefs
+5) Typedefs
+-----------
Please don't use things like "vps_t".
It's a _mistake_ to use typedef for structures and pointers. When you see a
+.. code-block:: c
+
+
vps_t a;
in the source, what does it mean?
In contrast, if it says
+.. code-block:: c
+
struct virtual_container *a;
you can actually tell what "a" is.
@@ -344,7 +384,8 @@ In general, a pointer, or a struct that has elements that can reasonably
be directly accessed should _never_ be a typedef.
- Chapter 6: Functions
+6) Functions
+------------
Functions should be short and sweet, and do just one thing. They should
fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
@@ -372,8 +413,10 @@ and it gets confused. You know you're brilliant, but maybe you'd like
to understand what you did 2 weeks from now.
In source files, separate functions with one blank line. If the function is
-exported, the EXPORT* macro for it should follow immediately after the closing
-function brace line. E.g.:
+exported, the **EXPORT** macro for it should follow immediately after the
+closing function brace line. E.g.:
+
+.. code-block:: c
int system_is_up(void)
{
@@ -386,7 +429,8 @@ Although this is not required by the C language, it is preferred in Linux
because it is a simple way to add valuable information for the reader.
- Chapter 7: Centralized exiting of functions
+7) Centralized exiting of functions
+-----------------------------------
Albeit deprecated by some people, the equivalent of the goto statement is
used frequently by compilers in form of the unconditional jump instruction.
@@ -409,9 +453,11 @@ The rationale for using gotos is:
- unconditional statements are easier to understand and follow
- nesting is reduced
- errors by not updating individual exit points when making
- modifications are prevented
+ modifications are prevented
- saves the compiler work to optimize redundant code away ;)
+.. code-block:: c
+
int fun(int a)
{
int result = 0;
@@ -436,6 +482,8 @@ The rationale for using gotos is:
A common type of bug to be aware of is "one err bugs" which look like this:
+.. code-block:: c
+
err:
kfree(foo->bar);
kfree(foo);
@@ -445,6 +493,8 @@ The bug in this code is that on some exit paths "foo" is NULL. Normally the
fix for this is to split it up into two error labels "err_free_bar:" and
"err_free_foo:":
+.. code-block:: c
+
err_free_bar:
kfree(foo->bar);
err_free_foo:
@@ -454,7 +504,8 @@ fix for this is to split it up into two error labels "err_free_bar:" and
Ideally you should simulate errors to test all exit paths.
- Chapter 8: Commenting
+8) Commenting
+-------------
Comments are good, but there is also a danger of over-commenting. NEVER
try to explain HOW your code works in a comment: it's much better to
@@ -476,6 +527,8 @@ for details.
The preferred style for long (multi-line) comments is:
+.. code-block:: c
+
/*
* This is the preferred style for multi-line
* comments in the Linux kernel source code.
@@ -488,6 +541,8 @@ The preferred style for long (multi-line) comments is:
For files in net/ and drivers/net/ the preferred style for long (multi-line)
comments is a little different.
+.. code-block:: c
+
/* The preferred comment style for files in net/ and drivers/net
* looks like this.
*
@@ -501,7 +556,8 @@ multiple data declarations). This leaves you room for a small comment on each
item, explaining its use.
- Chapter 9: You've made a mess of it
+9) You've made a mess of it
+---------------------------
That's OK, we all do. You've probably been told by your long-time Unix
user helper that "GNU emacs" automatically formats the C sources for
@@ -513,38 +569,40 @@ make a good program).
So, you can either get rid of GNU emacs, or change it to use saner
values. To do the latter, you can stick the following in your .emacs file:
-(defun c-lineup-arglist-tabs-only (ignored)
- "Line up argument lists by tabs, not spaces"
- (let* ((anchor (c-langelem-pos c-syntactic-element))
- (column (c-langelem-2nd-pos c-syntactic-element))
- (offset (- (1+ column) anchor))
- (steps (floor offset c-basic-offset)))
- (* (max steps 1)
- c-basic-offset)))
+.. code-block:: none
-(add-hook 'c-mode-common-hook
- (lambda ()
- ;; Add kernel style
- (c-add-style
- "linux-tabs-only"
- '("linux" (c-offsets-alist
- (arglist-cont-nonempty
- c-lineup-gcc-asm-reg
- c-lineup-arglist-tabs-only))))))
+ (defun c-lineup-arglist-tabs-only (ignored)
+ "Line up argument lists by tabs, not spaces"
+ (let* ((anchor (c-langelem-pos c-syntactic-element))
+ (column (c-langelem-2nd-pos c-syntactic-element))
+ (offset (- (1+ column) anchor))
+ (steps (floor offset c-basic-offset)))
+ (* (max steps 1)
+ c-basic-offset)))
-(add-hook 'c-mode-hook
- (lambda ()
- (let ((filename (buffer-file-name)))
- ;; Enable kernel mode for the appropriate files
- (when (and filename
- (string-match (expand-file-name "~/src/linux-trees")
- filename))
- (setq indent-tabs-mode t)
- (setq show-trailing-whitespace t)
- (c-set-style "linux-tabs-only")))))
+ (add-hook 'c-mode-common-hook
+ (lambda ()
+ ;; Add kernel style
+ (c-add-style
+ "linux-tabs-only"
+ '("linux" (c-offsets-alist
+ (arglist-cont-nonempty
+ c-lineup-gcc-asm-reg
+ c-lineup-arglist-tabs-only))))))
+
+ (add-hook 'c-mode-hook
+ (lambda ()
+ (let ((filename (buffer-file-name)))
+ ;; Enable kernel mode for the appropriate files
+ (when (and filename
+ (string-match (expand-file-name "~/src/linux-trees")
+ filename))
+ (setq indent-tabs-mode t)
+ (setq show-trailing-whitespace t)
+ (c-set-style "linux-tabs-only")))))
This will make emacs go better with the kernel coding style for C
-files below ~/src/linux-trees.
+files below ``~/src/linux-trees``.
But even if you fail in getting emacs to do sane formatting, not
everything is lost: use "indent".
@@ -562,14 +620,15 @@ re-formatting you may want to take a look at the man page. But
remember: "indent" is not a fix for bad programming.
- Chapter 10: Kconfig configuration files
+10) Kconfig configuration files
+-------------------------------
For all of the Kconfig* configuration files throughout the source tree,
the indentation is somewhat different. Lines under a "config" definition
are indented with one tab, while help text is indented an additional two
-spaces. Example:
+spaces. Example::
-config AUDIT
+ config AUDIT
bool "Auditing support"
depends on NET
help
@@ -579,9 +638,9 @@ config AUDIT
auditing without CONFIG_AUDITSYSCALL.
Seriously dangerous features (such as write support for certain
-filesystems) should advertise this prominently in their prompt string:
+filesystems) should advertise this prominently in their prompt string::
-config ADFS_FS_RW
+ config ADFS_FS_RW
bool "ADFS write support (DANGEROUS)"
depends on ADFS_FS
...
@@ -590,7 +649,8 @@ For full documentation on the configuration files, see the file
Documentation/kbuild/kconfig-language.txt.
- Chapter 11: Data structures
+11) Data structures
+-------------------
Data structures that have visibility outside the single-threaded
environment they are created and destroyed in should always have
@@ -621,10 +681,13 @@ Remember: if another thread can find your data structure, and you don't
have a reference count on it, you almost certainly have a bug.
- Chapter 12: Macros, Enums and RTL
+12) Macros, Enums and RTL
+-------------------------
Names of macros defining constants and labels in enums are capitalized.
+.. code-block:: c
+
#define CONSTANT 0x12345
Enums are preferred when defining several related constants.
@@ -636,7 +699,9 @@ Generally, inline functions are preferable to macros resembling functions.
Macros with multiple statements should be enclosed in a do - while block:
- #define macrofun(a, b, c) \
+.. code-block:: c
+
+ #define macrofun(a, b, c) \
do { \
if (a == 5) \
do_this(b, c); \
@@ -646,6 +711,8 @@ Things to avoid when using macros:
1) macros that affect control flow:
+.. code-block:: c
+
#define FOO(x) \
do { \
if (blah(x) < 0) \
@@ -657,6 +724,8 @@ function; don't break the internal parsers of those who will read the code.
2) macros that depend on having a local variable with a magic name:
+.. code-block:: c
+
#define FOO(val) bar(index, val)
might look like a good thing, but it's confusing as hell when one reads the
@@ -669,18 +738,22 @@ bite you if somebody e.g. turns FOO into an inline function.
must enclose the expression in parentheses. Beware of similar issues with
macros using parameters.
+.. code-block:: c
+
#define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3)
5) namespace collisions when defining local variables in macros resembling
functions:
-#define FOO(x) \
-({ \
- typeof(x) ret; \
- ret = calc_ret(x); \
- (ret); \
-})
+.. code-block:: c
+
+ #define FOO(x) \
+ ({ \
+ typeof(x) ret; \
+ ret = calc_ret(x); \
+ (ret); \
+ })
ret is a common name for a local variable - __foo_ret is less likely
to collide with an existing variable.
@@ -689,7 +762,8 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also
covers RTL which is used frequently with assembly language in the kernel.
- Chapter 13: Printing kernel messages
+13) Printing kernel messages
+----------------------------
Kernel developers like to be seen as literate. Do mind the spelling
of kernel messages to make a good impression. Do not use crippled
@@ -723,7 +797,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
used.
- Chapter 14: Allocating memory
+14) Allocating memory
+---------------------
The kernel provides the following general purpose memory allocators:
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
@@ -732,6 +807,8 @@ about them.
The preferred form for passing a size of a struct is the following:
+.. code-block:: c
+
p = kmalloc(sizeof(*p), ...);
The alternative form where struct name is spelled out hurts readability and
@@ -744,17 +821,22 @@ language.
The preferred form for allocating an array is the following:
+.. code-block:: c
+
p = kmalloc_array(n, sizeof(...), ...);
The preferred form for allocating a zeroed array is the following:
+.. code-block:: c
+
p = kcalloc(n, sizeof(...), ...);
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.
- Chapter 15: The inline disease
+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
@@ -781,7 +863,8 @@ 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
+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
@@ -793,7 +876,7 @@ 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:
+convention::
If the name of a function is an action or an imperative command,
the function should return an error-code integer. If the name
@@ -815,17 +898,22 @@ result. Typical examples would be functions that return pointers; they use
NULL or the ERR_PTR mechanism to report failure.
- Chapter 17: Don't re-invent the kernel macros
+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
+.. code-block:: c
+
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
Similarly, if you need to calculate the size of some structure member, use
+.. code-block:: c
+
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
There are also min() and max() macros that do strict type checking if you
@@ -833,16 +921,21 @@ 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
+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:
+.. code-block:: c
+
-*- mode: c -*-
Or like this:
+.. code-block:: c
+
/*
Local Variables:
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
@@ -851,6 +944,8 @@ Or like this:
Vim interprets markers that look like this:
+.. code-block:: c
+
/* vim:set sw=8 noet */
Do not include any of these in source files. People have their own personal
@@ -860,7 +955,8 @@ own custom mode, or may have some other magic method for making indentation
work correctly.
- Chapter 19: Inline assembly
+19) Inline assembly
+-------------------
In architecture-specific code, you may need to use inline assembly to interface
with CPU or platform functionality. Don't hesitate to do so when necessary.
@@ -884,12 +980,15 @@ instructions, put each instruction on a separate line in a separate quoted
string, and end each string except the last with \n\t to properly indent the
next instruction in the assembly output:
+.. code-block:: c
+
asm ("magic %reg1, #42\n\t"
"more_magic %reg2, %reg3"
: /* outputs */ : /* inputs */ : /* clobbers */);
- Chapter 20: Conditional Compilation
+20) Conditional Compilation
+---------------------------
Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
files; doing so makes code harder to read and logic harder to follow. Instead,
@@ -913,6 +1012,8 @@ unused, delete it.)
Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
symbol into a C boolean expression, and use it in a normal C conditional:
+.. code-block:: c
+
if (IS_ENABLED(CONFIG_SOMETHING)) {
...
}
@@ -928,12 +1029,15 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines),
place a comment after the #endif on the same line, noting the conditional
expression used. For instance:
+.. code-block:: c
+
#ifdef CONFIG_SOMETHING
...
#endif /* CONFIG_SOMETHING */
- Appendix I: References
+Appendix I) References
+----------------------
The C Programming Language, Second Edition
by Brian W. Kernighan and Dennis M. Ritchie.
@@ -953,4 +1057,3 @@ 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/
-
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 24/29] Documentation/HOWTO: improve some markups to make it visually better |
| Message-ID | <sj4Ma-4KI-53@gated-at.bofh.it> |
| In reply to | #1486354 |
Do a series of minor improvements at the ReST output format:
- Instead of using the quote blocks (::) for quotes, use
italics. That looks nicer on epub (and html) output, as
no scroll bar will be added. Also, it will adjust line
breaks on the text automatically.
- Add a missing reference to SubmittingPatches.rst and use
**foo** instead of _foo_.
- use bold for "The Perfect Patch" by removing a newline.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/HOWTO | 36 ++++++++++++++++--------------------
1 file changed, 16 insertions(+), 20 deletions(-)
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
index f297d5512885..784724aa4f34 100644
--- a/Documentation/HOWTO
+++ b/Documentation/HOWTO
@@ -292,11 +292,9 @@ process is as follows:
It is worth mentioning what Andrew Morton wrote on the linux-kernel
mailing list about kernel releases:
-::
-
- "Nobody knows when a kernel will be released, because it's
+ *"Nobody knows when a kernel will be released, because it's
released according to perceived bug status, not according to a
- preconceived timeline."
+ preconceived timeline."*
4.x.y -stable kernel tree
-------------------------
@@ -449,13 +447,14 @@ add your statements between the individual quoted sections instead of
writing at the top of the mail.
If you add patches to your mail, make sure they are plain readable text
-as stated in Documentation/SubmittingPatches. Kernel developers don't
-want to deal with attachments or compressed patches; they may want
-to comment on individual lines of your patch, which works only that way.
-Make sure you use a mail program that does not mangle spaces and tab
-characters. A good first test is to send the mail to yourself and try
-to apply your own patch by yourself. If that doesn't work, get your
-mail program fixed or change it until it works.
+as stated in Documentation/SubmittingPatches.
+Kernel developers don't want to deal with
+attachments or compressed patches; they may want to comment on
+individual lines of your patch, which works only that way. Make sure you
+use a mail program that does not mangle spaces and tab characters. A
+good first test is to send the mail to yourself and try to apply your
+own patch by yourself. If that doesn't work, get your mail program fixed
+or change it until it works.
Above all, please remember to show respect to other subscribers.
@@ -496,8 +495,8 @@ Remember, being wrong is acceptable as long as you are willing to work
toward a solution that is right.
It is normal that the answers to your first patch might simply be a list
-of a dozen things you should correct. This does _not_ imply that your
-patch will not be accepted, and it is _not_ meant against you
+of a dozen things you should correct. This does **not** imply that your
+patch will not be accepted, and it is **not** meant against you
personally. Simply correct all issues raised against your patch and
resend it.
@@ -582,19 +581,17 @@ The reasons for breaking things up are the following:
Here is an analogy from kernel developer Al Viro:
-::
-
- "Think of a teacher grading homework from a math student. The
+ *"Think of a teacher grading homework from a math student. The
teacher does not want to see the student's trials and errors
before they came up with the solution. They want to see the
cleanest, most elegant answer. A good student knows this, and
would never submit her intermediate work before the final
- solution.
+ solution.*
- The same is true of kernel development. The maintainers and
+ *The same is true of kernel development. The maintainers and
reviewers do not want to see the thought process behind the
solution to the problem one is solving. They want to see a
- simple and elegant solution."
+ simple and elegant solution."*
It may be challenging to keep the balance between presenting an elegant
solution and working together with the community and discussing your
@@ -632,7 +629,6 @@ For more details on what this should all look like, please see the
ChangeLog section of the document:
"The Perfect Patch"
-
http://www.ozlabs.org/~akpm/stuff/tpp.txt
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 13/29] Documentation/CodingStyle: use the .. note:: markup where needed |
| Message-ID | <sj4Ma-4KI-31@gated-at.bofh.it> |
| In reply to | #1486354 |
There are two places there where there are notes that should
be highlighted. So, use the ReST note markup for such texts.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/CodingStyle | 14 +++++++++-----
1 file changed, 9 insertions(+), 5 deletions(-)
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 0024c36b8046..7e30da38bb3a 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -333,9 +333,11 @@ useful only for:
Example: ``pte_t`` etc. opaque objects that you can only access using
the proper accessor functions.
- NOTE! Opaqueness and ``accessor functions`` are not good in themselves.
- The reason we have them for things like pte_t etc. is that there
- really is absolutely **zero** portably accessible information there.
+ .. note::
+
+ Opaqueness and ``accessor functions`` are not good in themselves.
+ The reason we have them for things like pte_t etc. is that there
+ really is absolutely **zero** portably accessible information there.
(b) Clear integer types, where the abstraction **helps** avoid confusion
whether it is ``int`` or ``long``.
@@ -343,8 +345,10 @@ useful only for:
u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here.
- NOTE! Again - there needs to be a **reason** for this. If something is
- ``unsigned long``, then there's no reason to do
+ .. note::
+
+ Again - there needs to be a **reason** for this. If something is
+ ``unsigned long``, then there's no reason to do
typedef unsigned long myflags_t;
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 23/29] Documentation/HOWTO: update information about generating documentation |
| Message-ID | <sj4Ma-4KI-49@gated-at.bofh.it> |
| In reply to | #1486354 |
The description there are pre-Sphinx. Update it to cover the
new way.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/HOWTO | 28 ++++++++++++++++++++++------
1 file changed, 22 insertions(+), 6 deletions(-)
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
index 31c8df5d20c7..f297d5512885 100644
--- a/Documentation/HOWTO
+++ b/Documentation/HOWTO
@@ -164,21 +164,37 @@ required reading:
apply it to the different development branches of the kernel.
The kernel also has a large number of documents that can be
-automatically generated from the source code itself. This includes a
+automatically generated from the source code itself or from
+ReStructuredText markups (ReST), like this one. This includes a
full description of the in-kernel API, and rules on how to handle
-locking properly. The documents will be created in the
-Documentation/DocBook/ directory and can be generated as PDF,
-Postscript, HTML, and man pages by running:
+locking properly.
+
+All such documents can be generated as PDF or HTML by running:
::
make pdfdocs
- make psdocs
make htmldocs
- make mandocs
respectively from the main kernel source directory.
+The documents that uses ReST markup will be generated at Documentation/output.
+They can also be generated on LaTeX and ePub formats with:
+
+::
+
+ make latexdocs
+ make epubdocs
+
+Currently, there are some documents written on DocBook that are in
+the process of conversion to ReST. Such documents will be created in the
+Documentation/DocBook/ directory and can be generated also as
+Postscript or man pages by running:
+
+::
+
+ make psdocs
+ make mandocs
Becoming A Kernel Developer
---------------------------
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents |
| Message-ID | <sj4Ma-4KI-33@gated-at.bofh.it> |
| In reply to | #1486354 |
Add cross references for the documents mentioned at HOWTO and
are under the Documentation/ directory, using the ReST notation.
It should be noticed that HOWTO also mentions the /README file.
We opted to not touch it, for now, as making it build on
Sphinx would require it to be moved to a Documentation/foo
directory.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/Changes | 2 ++
Documentation/CodingStyle | 2 ++
Documentation/HOWTO | 18 +++++++++---------
Documentation/ManagementStyle | 2 ++
Documentation/SecurityBugs | 2 ++
Documentation/SubmittingDrivers | 2 ++
Documentation/SubmittingPatches | 1 +
Documentation/applying-patches.txt | 1 +
Documentation/kernel-docs.txt | 2 ++
Documentation/stable_api_nonsense.txt | 2 ++
Documentation/stable_kernel_rules.txt | 2 ++
11 files changed, 27 insertions(+), 9 deletions(-)
diff --git a/Documentation/Changes b/Documentation/Changes
index 93c8e1c15844..754cd50c1bc6 100644
--- a/Documentation/Changes
+++ b/Documentation/Changes
@@ -1,3 +1,5 @@
+.. _changes:
+
Minimal requerements to compile the Kernel
++++++++++++++++++++++++++++++++++++++++++
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 7e30da38bb3a..852253c932fe 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -1,3 +1,5 @@
+.. _codingstyle:
+
Linux kernel coding style
=========================
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
index 5a85e3a8112b..31c8df5d20c7 100644
--- a/Documentation/HOWTO
+++ b/Documentation/HOWTO
@@ -90,19 +90,19 @@ required reading:
what is necessary to do to configure and build the kernel. People
who are new to the kernel should start here.
- Documentation/Changes
+ :ref:`Documentation/Changes <changes>`
This file gives a list of the minimum levels of various software
packages that are necessary to build and run the kernel
successfully.
- Documentation/CodingStyle
+ :ref:`Documentation/CodingStyle <codingstyle>`
This describes the Linux kernel coding style, and some of the
rationale behind it. All new code is expected to follow the
guidelines in this document. Most maintainers will only accept
patches if these rules are followed, and many people will only
review code if it is in the proper style.
- Documentation/SubmittingPatches and Documentation/SubmittingDrivers
+ :ref:`Documentation/SubmittingPatches <submittingpatches>` and :ref:`Documentation/SubmittingDrivers <submittingdrivers>`
These files describe in explicit detail how to successfully create
and send a patch, including (but not limited to):
@@ -124,7 +124,7 @@ required reading:
http://linux.yyz.us/patch-format.html
- Documentation/stable_api_nonsense.txt
+ :ref:`Documentation/stable_api_nonsense.txt <stable_api_nonsense>`
This file describes the rationale behind the conscious decision to
not have a stable API within the kernel, including things like:
@@ -137,29 +137,29 @@ required reading:
philosophy and is very important for people moving to Linux from
development on other Operating Systems.
- Documentation/SecurityBugs
+ :ref:`Documentation/SecurityBugs <securitybugs>`
If you feel you have found a security problem in the Linux kernel,
please follow the steps in this document to help notify the kernel
developers, and help solve the issue.
- Documentation/ManagementStyle
+ :ref:`Documentation/ManagementStyle <managementstyle>`
This document describes how Linux kernel maintainers operate and the
shared ethos behind their methodologies. This is important reading
for anyone new to kernel development (or anyone simply curious about
it), as it resolves a lot of common misconceptions and confusion
about the unique behavior of kernel maintainers.
- Documentation/stable_kernel_rules.txt
+ :ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
This file describes the rules on how the stable kernel releases
happen, and what to do if you want to get a change into one of these
releases.
- Documentation/kernel-docs.txt
+ :ref:`Documentation/kernel-docs.txt <kernel_docs>`
A list of external documentation that pertains to kernel
development. Please consult this list if you do not find what you
are looking for within the in-kernel documentation.
- Documentation/applying-patches.txt
+ :ref:`Documentation/applying-patches.txt <applying_patches>`
A good introduction describing exactly what a patch is and how to
apply it to the different development branches of the kernel.
diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle
index 1471df6015a2..dea2e66c9a10 100644
--- a/Documentation/ManagementStyle
+++ b/Documentation/ManagementStyle
@@ -1,3 +1,5 @@
+.. _managementstyle:
+
Linux kernel management style
=============================
diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs
index 10a1f79376a2..342d769834f6 100644
--- a/Documentation/SecurityBugs
+++ b/Documentation/SecurityBugs
@@ -1,3 +1,5 @@
+.. _securitybugs:
+
Security bugs
=============
diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers
index a2f30a9e28d1..2ac931645e53 100644
--- a/Documentation/SubmittingDrivers
+++ b/Documentation/SubmittingDrivers
@@ -1,3 +1,5 @@
+.. _submittingdrivers:
+
Submitting Drivers For The Linux Kernel
=======================================
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 352771b736cd..9c3dfa7babf3 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -1,3 +1,4 @@
+.. _submittingpatches:
How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
=========================================================================================
diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt
index 0e873dbf5566..bc113bff86b7 100644
--- a/Documentation/applying-patches.txt
+++ b/Documentation/applying-patches.txt
@@ -1,3 +1,4 @@
+.. _applying_patches:
Applying Patches To The Linux Kernel
++++++++++++++++++++++++++++++++++++
diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index 7ca806184426..955f5b775e69 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -1,3 +1,5 @@
+.. _kernel_docs:
+
Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel
=============================================================================================
diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt
index 9187b4ef4bac..24f5aeecee91 100644
--- a/Documentation/stable_api_nonsense.txt
+++ b/Documentation/stable_api_nonsense.txt
@@ -1,3 +1,5 @@
+.. _stable_api_nonsense:
+
The Linux Kernel Driver Interface
==================================
diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
index 387d8a44eda2..1eba72708c7f 100644
--- a/Documentation/stable_kernel_rules.txt
+++ b/Documentation/stable_kernel_rules.txt
@@ -1,3 +1,5 @@
+.. _stable_kernel_rules:
+
Everything you ever wanted to know about Linux -stable releases
===============================================================
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Greg KH <greg@kroah.com> |
|---|---|
| Date | 2016-09-20 09:10 +0200 |
| Subject | Re: [PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents |
| Message-ID | <sjnlM-8eo-17@gated-at.bofh.it> |
| In reply to | #1486385 |
On Mon, Sep 19, 2016 at 08:07:56AM -0300, Mauro Carvalho Chehab wrote: > Add cross references for the documents mentioned at HOWTO and > are under the Documentation/ directory, using the ReST notation. > > It should be noticed that HOWTO also mentions the /README file. > We opted to not touch it, for now, as making it build on > Sphinx would require it to be moved to a Documentation/foo > directory. > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> > --- Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 26/29] Documentation/SubmitChecklist: update kernel-doc task |
| Message-ID | <sj4Ma-4KI-35@gated-at.bofh.it> |
| In reply to | #1486354 |
Task 11 (kernel-doc) still mentions usage of make manpages, but
this won't work if the API is documented via Sphinx. So, update
it to use either htmldocs or pdfdocs, with are the documentation
targets that work for all.
While here, add ReST reference to the kernel documentation book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/SubmitChecklist | 7 ++++---
Documentation/kernel-documentation.rst | 2 ++
2 files changed, 6 insertions(+), 3 deletions(-)
diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
index 2b7e32dfe00d..bb114c8a781c 100644
--- a/Documentation/SubmitChecklist
+++ b/Documentation/SubmitChecklist
@@ -47,9 +47,10 @@ kernel patches.
but any one function that uses more than 512 bytes on the stack is a
candidate for change.
-11: Include kernel-doc to document global kernel APIs. (Not required for
- static functions, but OK there also.) Use 'make htmldocs' or 'make
- mandocs' to check the kernel-doc and fix any issues.
+11: Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
+ (Not required for static functions, but OK there also.) Use
+ ``make htmldocs`` or ``make pdfdocs`` to check the
+ :ref:`kernel-doc <kernel_doc>` and fix any issues.
12: Has been tested with CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT,
CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES,
diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index a0dcae15639b..10cc7ddb6235 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -294,6 +294,8 @@ The kernel-doc extension is included in the kernel source tree, at
``scripts/kernel-doc`` script to extract the documentation comments from the
source.
+.. _kernel_doc:
+
Writing kernel-doc comments
===========================
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 15/29] Documentation/SecurityBugs: convert it to ReST markup |
| Message-ID | <sj4Ma-4KI-37@gated-at.bofh.it> |
| In reply to | #1486354 |
Add a name for the document and convert the sections to ReST markups. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/SecurityBugs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs index a660d494c8ed..10a1f79376a2 100644 --- a/Documentation/SecurityBugs +++ b/Documentation/SecurityBugs @@ -1,9 +1,13 @@ +Security bugs +============= + Linux kernel developers take security very seriously. As such, we'd like to know when a security bug is found so that it can be fixed and disclosed as quickly as possible. Please report security bugs to the Linux kernel security team. 1) Contact +---------- The Linux kernel security team can be contacted by email at <security@kernel.org>. This is a private list of security officers @@ -18,6 +22,7 @@ Any exploit code is very helpful and will not be released without consent from the reporter unless it has already been made public. 2) Disclosure +------------- The goal of the Linux kernel security team is to work with the bug submitter to bug resolution as well as disclosure. We prefer @@ -33,6 +38,7 @@ to a few weeks. As a basic default policy, we expect report date to disclosure date to be on the order of 7 days. 3) Non-disclosure agreements +---------------------------- The Linux kernel security team is not a formal body and therefore unable to enter any non-disclosure agreements. -- 2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 19/29] Documentation/SubmittingPatches: convert it to ReST markup |
| Message-ID | <sj4Mb-4KI-65@gated-at.bofh.it> |
| In reply to | #1486354 |
- Change the sections to use ReST markup;
- Add cross-references where needed;
- convert aspas to verbatim text;
- use code block tags;
- make Sphinx happy.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/SubmittingPatches | 207 ++++++++++++++++++++--------------------
1 file changed, 105 insertions(+), 102 deletions(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 8c79f1d53731..04a4284d8ee4 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -1,9 +1,6 @@
- How to Get Your Change Into the Linux Kernel
- or
- Care And Operation Of Your Linus Torvalds
-
-
+How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
+=========================================================================================
For a person or company who wishes to submit a change to the Linux
kernel, the process can sometimes be daunting if you're not familiar
@@ -24,9 +21,8 @@ of the mechanical work done for you, though you'll still need to prepare
and document a sensible set of patches. In general, use of git will make
your life as a kernel developer easier.
---------------------------------------------
-SECTION 1 - CREATING AND SENDING YOUR CHANGE
---------------------------------------------
+Creating and Sending your Change
+********************************
0) Obtain a current source tree
@@ -34,35 +30,35 @@ SECTION 1 - CREATING AND SENDING YOUR CHANGE
If you do not have a repository with the current kernel source handy, use
git to obtain one. You'll want to start with the mainline repository,
-which can be grabbed with:
+which can be grabbed with::
- git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Note, however, that you may not want to develop against the mainline tree
directly. Most subsystem maintainers run their own trees and want to see
-patches prepared against those trees. See the "T:" entry for the subsystem
+patches prepared against those trees. See the **T:** entry for the subsystem
in the MAINTAINERS file to find that tree, or simply ask the maintainer if
the tree is not listed there.
It is still possible to download kernel releases via tarballs (as described
in the next section), but that is the hard way to do kernel development.
-1) "diff -up"
-------------
+1) ``diff -up``
+---------------
-If you must generate your patches by hand, use "diff -up" or "diff -uprN"
+If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN``
to create patches. Git generates patches in this form by default; if
you're using git, you can skip this section entirely.
All changes to the Linux kernel occur in the form of patches, as
generated by diff(1). When creating your patch, make sure to create it
-in "unified diff" format, as supplied by the '-u' argument to diff(1).
-Also, please use the '-p' argument which shows which C function each
+in "unified diff" format, as supplied by the ``-u`` argument to diff(1).
+Also, please use the ``-p`` argument which shows which C function each
change is in - that makes the resultant diff a lot easier to read.
Patches should be based in the root kernel source directory,
not in any lower subdirectory.
-To create a patch for a single file, it is often sufficient to do:
+To create a patch for a single file, it is often sufficient to do::
SRCTREE= linux
MYFILE= drivers/net/mydriver.c
@@ -75,7 +71,7 @@ To create a patch for a single file, it is often sufficient to do:
To create a patch for multiple files, you should unpack a "vanilla",
or unmodified kernel source tree, and generate a diff against your
-own source tree. For example:
+own source tree. For example::
MYSRC= /devel/linux
@@ -84,7 +80,7 @@ own source tree. For example:
diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
linux-3.19-vanilla $MYSRC > /tmp/patch
-"dontdiff" is a list of files which are generated by the kernel during
+``dontdiff`` is a list of files which are generated by the kernel during
the build process, and should be ignored in any diff(1)-generated
patch.
@@ -93,18 +89,18 @@ belong in a patch submission. Make sure to review your patch -after-
generating it with diff(1), to ensure accuracy.
If your changes produce a lot of deltas, you need to split them into
-individual patches which modify things in logical stages; see section
-#3. This will facilitate review by other kernel developers,
+individual patches which modify things in logical stages; see
+:ref:`split_changes`. This will facilitate review by other kernel developers,
very important if you want your patch accepted.
-If you're using git, "git rebase -i" can help you with this process. If
+If you're using git, ``git rebase -i`` can help you with this process. If
you're not using git, quilt <http://savannah.nongnu.org/projects/quilt>
is another popular alternative.
+.. _describe_changes:
-
-2) Describe your changes.
--------------------------
+2) Describe your changes
+------------------------
Describe your problem. Whether your patch is a one-line bug fix or
5000 lines of a new feature, there must be an underlying problem that
@@ -137,11 +133,11 @@ as you intend it to.
The maintainer will thank you if you write your patch description in a
form which can be easily pulled into Linux's source code management
-system, git, as a "commit log". See #15, below.
+system, git, as a "commit log". See :ref:`explicit_in_reply_to`.
Solve only one problem per patch. If your description starts to get
long, that's a sign that you probably need to split up your patch.
-See #3, next.
+See :ref:`split_changes`.
When you submit or resubmit a patch or patch series, include the
complete patch description and justification for it. Don't just
@@ -171,7 +167,7 @@ patch as submitted.
If you want to refer to a specific commit, don't just refer to the
SHA-1 ID of the commit. Please also include the oneline summary of
the commit, to make it easier for reviewers to know what it is about.
-Example:
+Example::
Commit e21d2170f36602ae2708 ("video: remove unnecessary
platform_set_drvdata()") removed the unnecessary
@@ -186,22 +182,24 @@ change five years from now.
If your patch fixes a bug in a specific commit, e.g. you found an issue using
git-bisect, please use the 'Fixes:' tag with the first 12 characters of the
-SHA-1 ID, and the one line summary. For example:
+SHA-1 ID, and the one line summary. For example::
Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
The following git-config settings can be used to add a pretty format for
-outputting the above style in the git log or git show commands
+outputting the above style in the git log or git show commands::
[core]
abbrev = 12
[pretty]
fixes = Fixes: %h (\"%s\")
-3) Separate your changes.
--------------------------
+.. _split_changes:
-Separate each _logical change_ into a separate patch.
+3) Separate your changes
+------------------------
+
+Separate each **logical change** into a separate patch.
For example, if your changes include both bug fixes and performance
enhancements for a single driver, separate those changes into two
@@ -217,12 +215,12 @@ change that can be verified by reviewers. Each patch should be justifiable
on its own merits.
If one patch depends on another patch in order for a change to be
-complete, that is OK. Simply note "this patch depends on patch X"
+complete, that is OK. Simply note **"this patch depends on patch X"**
in your patch description.
When dividing your change into a series of patches, take special care to
ensure that the kernel builds and runs properly after each patch in the
-series. Developers using "git bisect" to track down a problem can end up
+series. Developers using ``git bisect`` to track down a problem can end up
splitting your patch series at any point; they will not thank you if you
introduce bugs in the middle.
@@ -231,8 +229,8 @@ then only post say 15 or so at a time and wait for review and integration.
-4) Style-check your changes.
-----------------------------
+4) Style-check your changes
+---------------------------
Check your patch for basic style violations, details of which can be
found in Documentation/CodingStyle. Failure to do so simply wastes
@@ -260,8 +258,8 @@ You should be able to justify all violations that remain in your
patch.
-5) Select the recipients for your patch.
-----------------------------------------
+5) Select the recipients for your patch
+---------------------------------------
You should always copy the appropriate subsystem maintainer(s) on any patch
to code that they maintain; look through the MAINTAINERS file and the
@@ -295,7 +293,7 @@ to allow distributors to get the patch out to users; in such cases,
obviously, the patch should not be sent to any public lists.
Patches that fix a severe bug in a released kernel should be directed
-toward the stable maintainers by putting a line like this:
+toward the stable maintainers by putting a line like this::
Cc: stable@vger.kernel.org
@@ -312,12 +310,14 @@ If changes affect userland-kernel interfaces, please send the MAN-PAGES
maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
least a notification of the change, so that some information makes its way
into the manual pages. User-space API changes should also be copied to
-linux-api@vger.kernel.org.
+linux-api@vger.kernel.org.
For small patches you may want to CC the Trivial Patch Monkey
trivial@kernel.org which collects "trivial" patches. Have a look
into the MAINTAINERS file for its current manager.
+
Trivial patches must qualify for one of the following rules:
+
Spelling fixes in documentation
Spelling fixes for errors which could break grep(1)
Warning fixes (cluttering with useless warnings is bad)
@@ -332,8 +332,8 @@ Trivial patches must qualify for one of the following rules:
-6) No MIME, no links, no compression, no attachments. Just plain text.
------------------------------------------------------------------------
+6) No MIME, no links, no compression, no attachments. Just plain text
+----------------------------------------------------------------------
Linus and other kernel developers need to be able to read and comment
on the changes you are submitting. It is important for a kernel
@@ -356,8 +356,8 @@ you to re-send them using MIME.
See Documentation/email-clients.txt for hints about configuring
your e-mail client so that it sends your patches untouched.
-7) E-mail size.
----------------
+7) E-mail size
+--------------
Large changes are not appropriate for mailing lists, and some
maintainers. If your patch, uncompressed, exceeds 300 kB in size,
@@ -366,8 +366,8 @@ server, and provide instead a URL (link) pointing to your patch. But note
that if your patch exceeds 300 kB, it almost certainly needs to be broken up
anyway.
-8) Respond to review comments.
-------------------------------
+8) Respond to review comments
+-----------------------------
Your patch will almost certainly get comments from reviewers on ways in
which the patch can be improved. You must respond to those comments;
@@ -382,8 +382,8 @@ reviewers sometimes get grumpy. Even in that case, though, respond
politely and address the problems they have pointed out.
-9) Don't get discouraged - or impatient.
-----------------------------------------
+9) Don't get discouraged - or impatient
+---------------------------------------
After you have submitted your change, be patient and wait. Reviewers are
busy people and may not get to your patch right away.
@@ -419,9 +419,10 @@ patch, which certifies that you wrote it or otherwise have the right to
pass it on as an open-source patch. The rules are pretty simple: if you
can certify the below:
- Developer's Certificate of Origin 1.1
+Developer's Certificate of Origin 1.1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- By making a contribution to this project, I certify that:
+By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
@@ -445,7 +446,7 @@ can certify the below:
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
-then you just add a line saying
+then you just add a line saying::
Signed-off-by: Random J Developer <random@developer.example.org>
@@ -466,7 +467,7 @@ you add a line between the last Signed-off-by header and yours, indicating
the nature of your changes. While there is nothing mandatory about this, it
seems like prepending the description with your mail and/or name, all
enclosed in square brackets, is noticeable enough to make it obvious that
-you are responsible for last-minute changes. Example :
+you are responsible for last-minute changes. Example::
Signed-off-by: Random J Developer <random@developer.example.org>
[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
@@ -481,15 +482,15 @@ which appears in the changelog.
Special note to back-porters: It seems to be a common and useful practice
to insert an indication of the origin of a patch at the top of the commit
message (just after the subject line) to facilitate tracking. For instance,
-here's what we see in a 3.x-stable release:
+here's what we see in a 3.x-stable release::
-Date: Tue Oct 7 07:26:38 2014 -0400
+ Date: Tue Oct 7 07:26:38 2014 -0400
libata: Un-break ATA blacklist
commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
-And here's what might appear in an older kernel once a patch is backported:
+And here's what might appear in an older kernel once a patch is backported::
Date: Tue May 13 22:12:27 2008 +0200
@@ -529,7 +530,7 @@ When in doubt people should refer to the original discussion in the mailing
list archives.
If a person has had the opportunity to comment on a patch, but has not
-provided such comments, you may optionally add a "Cc:" tag to the patch.
+provided such comments, you may optionally add a ``Cc:`` tag to the patch.
This is the only tag which might be added without an explicit action by the
person it names - but it should indicate that this person was copied on the
patch. This tag documents that potentially interested parties
@@ -552,11 +553,12 @@ future patches, and ensures credit for the testers.
Reviewed-by:, instead, indicates that the patch has been reviewed and found
acceptable according to the Reviewer's Statement:
- Reviewer's statement of oversight
+Reviewer's statement of oversight
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- By offering my Reviewed-by: tag, I state that:
+By offering my Reviewed-by: tag, I state that:
- (a) I have carried out a technical review of this patch to
+ (a) I have carried out a technical review of this patch to
evaluate its appropriateness and readiness for inclusion into
the mainline kernel.
@@ -594,7 +596,8 @@ A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
is used to make it easy to determine where a bug originated, which can help
review a bug fix. This tag also assists the stable kernel team in determining
which stable kernel versions should receive your fix. This is the preferred
-method for indicating a bug fixed by the patch. See #2 above for more details.
+method for indicating a bug fixed by the patch. See :ref:`describe_changes`
+for more details.
14) The canonical patch format
@@ -602,16 +605,16 @@ method for indicating a bug fixed by the patch. See #2 above for more details.
This section describes how the patch itself should be formatted. Note
that, if you have your patches stored in a git repository, proper patch
-formatting can be had with "git format-patch". The tools cannot create
+formatting can be had with ``git format-patch``. The tools cannot create
the necessary text, though, so read the instructions below anyway.
-The canonical patch subject line is:
+The canonical patch subject line is::
Subject: [PATCH 001/123] subsystem: summary phrase
The canonical patch message body contains the following:
- - A "from" line specifying the patch author (only needed if the person
+ - A ``from`` line specifying the patch author (only needed if the person
sending the patch is not the author).
- An empty line.
@@ -619,10 +622,10 @@ The canonical patch message body contains the following:
- The body of the explanation, line wrapped at 75 columns, which will
be copied to the permanent changelog to describe this patch.
- - The "Signed-off-by:" lines, described above, which will
+ - The ``Signed-off-by:`` lines, described above, which will
also go in the changelog.
- - A marker line containing simply "---".
+ - A marker line containing simply ``---``.
- Any additional comments not suitable for the changelog.
@@ -633,32 +636,32 @@ alphabetically by subject line - pretty much any email reader will
support that - since because the sequence number is zero-padded,
the numerical and alphabetic sort is the same.
-The "subsystem" in the email's Subject should identify which
+The ``subsystem`` in the email's Subject should identify which
area or subsystem of the kernel is being patched.
-The "summary phrase" in the email's Subject should concisely
-describe the patch which that email contains. The "summary
-phrase" should not be a filename. Do not use the same "summary
-phrase" for every patch in a whole patch series (where a "patch
-series" is an ordered sequence of multiple, related patches).
+The ``summary phrase`` in the email's Subject should concisely
+describe the patch which that email contains. The ``summary
+phrase`` should not be a filename. Do not use the same ``summary
+phrase`` for every patch in a whole patch series (where a ``patch
+series`` is an ordered sequence of multiple, related patches).
-Bear in mind that the "summary phrase" of your email becomes a
+Bear in mind that the ``summary phrase`` of your email becomes a
globally-unique identifier for that patch. It propagates all the way
-into the git changelog. The "summary phrase" may later be used in
+into the git changelog. The ``summary phrase`` may later be used in
developer discussions which refer to the patch. People will want to
-google for the "summary phrase" to read discussion regarding that
+google for the ``summary phrase`` to read discussion regarding that
patch. It will also be the only thing that people may quickly see
when, two or three months later, they are going through perhaps
-thousands of patches using tools such as "gitk" or "git log
+thousands of patches using tools such as ``gitk`` or "git log
--oneline".
-For these reasons, the "summary" must be no more than 70-75
+For these reasons, the ``summary`` must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary. It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.
-The "summary phrase" may be prefixed by tags enclosed in square
+The ``summary phrase`` may be prefixed by tags enclosed in square
brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are
not considered part of the summary phrase, but describe how the patch
should be treated. Common tags might include a version descriptor if
@@ -670,19 +673,19 @@ that developers understand the order in which the patches should be
applied and that they have reviewed or applied all of the patches in
the patch series.
-A couple of example Subjects:
+A couple of example Subjects::
Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
Subject: [PATCH v2 01/27] x86: fix eflags tracking
-The "from" line must be the very first line in the message body,
+The ``from`` line must be the very first line in the message body,
and has the form:
From: Original Author <author@example.com>
-The "from" line specifies who will be credited as the author of the
-patch in the permanent changelog. If the "from" line is missing,
-then the "From:" line from the email header will be used to determine
+The ``from`` line specifies who will be credited as the author of the
+patch in the permanent changelog. If the ``from`` line is missing,
+then the ``From:`` line from the email header will be used to determine
the patch author in the changelog.
The explanation body will be committed to the permanent source
@@ -694,23 +697,23 @@ especially useful for people who might be searching the commit logs
looking for the applicable patch. If a patch fixes a compile failure,
it may not be necessary to include _all_ of the compile failures; just
enough that it is likely that someone searching for the patch can find
-it. As in the "summary phrase", it is important to be both succinct as
+it. As in the ``summary phrase``, it is important to be both succinct as
well as descriptive.
-The "---" marker line serves the essential purpose of marking for patch
+The ``---`` marker line serves the essential purpose of marking for patch
handling tools where the changelog message ends.
-One good use for the additional comments after the "---" marker is for
+One good use for the additional comments after the ``---`` marker is for
a diffstat, to show what files have changed, and the number of
inserted and deleted lines per file. A diffstat is especially useful
on bigger patches. Other comments relevant only to the moment or the
maintainer, not suitable for the permanent changelog, should also go
-here. A good example of such comments might be "patch changelogs"
+here. A good example of such comments might be ``patch changelogs``
which describe what has changed between the v1 and v2 version of the
patch.
-If you are going to include a diffstat after the "---" marker, please
-use diffstat options "-p 1 -w 70" so that filenames are listed from
+If you are going to include a diffstat after the ``---`` marker, please
+use diffstat options ``-p 1 -w 70`` so that filenames are listed from
the top of the kernel source tree and don't use too much horizontal
space (easily fit in 80 columns, maybe with some indentation). (git
generates appropriate diffstats by default.)
@@ -718,11 +721,13 @@ generates appropriate diffstats by default.)
See more details on the proper patch format in the following
references.
+.. _explicit_in_reply_to:
+
15) Explicit In-Reply-To headers
--------------------------------
It can be helpful to manually add In-Reply-To: headers to a patch
-(e.g., when using "git send-email") to associate the patch with
+(e.g., when using ``git send-email``) to associate the patch with
previous relevant discussion, e.g. to link a bug fix to the email with
the bug report. However, for a multi-patch series, it is generally
best to avoid using In-Reply-To: to link to older versions of the
@@ -732,12 +737,12 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
the cover email text) to link to an earlier version of the patch series.
-16) Sending "git pull" requests
--------------------------------
+16) Sending ``git pull`` requests
+---------------------------------
If you have a series of patches, it may be most convenient to have the
maintainer pull them directly into the subsystem repository with a
-"git pull" operation. Note, however, that pulling patches from a developer
+``git pull`` operation. Note, however, that pulling patches from a developer
requires a higher degree of trust than taking patches from a mailing list.
As a result, many subsystem maintainers are reluctant to take pull
requests, especially from new, unknown developers. If in doubt you can use
@@ -746,7 +751,7 @@ series, giving the maintainer the option of using either.
A pull request should have [GIT] or [PULL] in the subject line. The
request itself should include the repository name and the branch of
-interest on a single line; it should look something like:
+interest on a single line; it should look something like::
Please pull from
@@ -755,10 +760,10 @@ interest on a single line; it should look something like:
to get these changes:
A pull request should also include an overall message saying what will be
-included in the request, a "git shortlog" listing of the patches
+included in the request, a ``git shortlog`` listing of the patches
themselves, and a diffstat showing the overall effect of the patch series.
The easiest way to get all this information together is, of course, to let
-git do it for you with the "git request-pull" command.
+git do it for you with the ``git request-pull`` command.
Some maintainers (including Linus) want to see pull requests from signed
commits; that increases their confidence that the request actually came
@@ -771,7 +776,7 @@ new developers, but there is no way around it. Attending conferences can
be a good way to find developers who can sign your key.
Once you have prepared a patch series in git that you wish to have somebody
-pull, create a signed tag with "git tag -s". This will create a new tag
+pull, create a signed tag with ``git tag -s``. This will create a new tag
identifying the last commit in the series and containing a signature
created with your private key. You will also have the opportunity to add a
changelog-style message to the tag; this is an ideal place to describe the
@@ -782,14 +787,13 @@ are working from, don't forget to push the signed tag explicitly to the
public tree.
When generating your pull request, use the signed tag as the target. A
-command like this will do the trick:
+command like this will do the trick::
git request-pull master git://my.public.tree/linux.git my-signed-tag
-----------------------
-SECTION 2 - REFERENCES
-----------------------
+REFERENCES
+**********
Andrew Morton, "The perfect patch" (tpp).
<http://www.ozlabs.org/~akpm/stuff/tpp.txt>
@@ -818,4 +822,3 @@ Andi Kleen, "On submitting kernel patches"
Some strategies to get difficult or controversial changes in.
http://halobates.de/on-submitting-patches.pdf
---
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 18/29] Documentation/SubmittingDrivers: convert it to ReST markup |
| Message-ID | <sj4Mb-4KI-67@gated-at.bofh.it> |
| In reply to | #1486354 |
- Change the document title markup to make it on a higher level; - Add blank lines as needed, to improve the output; - use italics for the country-code at kernel.org ftp URL. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/SubmittingDrivers | 45 ++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 31d372609ac0..a2f30a9e28d1 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -1,5 +1,5 @@ Submitting Drivers For The Linux Kernel ---------------------------------------- +======================================= This document is intended to explain how to submit device drivers to the various kernel trees. Note that if you are interested in video card drivers @@ -46,34 +46,39 @@ Linux 2.6: What Criteria Determine Acceptance ---------------------------------- -Licensing: The code must be released to us under the +Licensing: + The code must be released to us under the GNU General Public License. We don't insist on any kind of exclusive GPL licensing, and if you wish the driver to be useful to other communities such as BSD you may well wish to release under multiple licenses. See accepted licenses at include/linux/module.h -Copyright: The copyright owner must agree to use of GPL. +Copyright: + The copyright owner must agree to use of GPL. It's best if the submitter and copyright owner are the same person/entity. If not, the name of the person/entity authorizing use of GPL should be listed in case it's necessary to verify the will of the copyright owner. -Interfaces: If your driver uses existing interfaces and behaves like +Interfaces: + If your driver uses existing interfaces and behaves like other drivers in the same class it will be much more likely to be accepted than if it invents gratuitous new ones. If you need to implement a common API over Linux and NT drivers do it in userspace. -Code: Please use the Linux style of code formatting as documented +Code: + Please use the Linux style of code formatting as documented in Documentation/CodingStyle. If you have sections of code that need to be in other formats, for example because they are shared with a windows driver kit and you want to maintain them just once separate them out nicely and note this fact. -Portability: Pointers are not always 32bits, not all computers are little +Portability: + Pointers are not always 32bits, not all computers are little endian, people do not all have floating point and you shouldn't use inline x86 assembler in your driver without careful thought. Pure x86 drivers generally are not popular. @@ -81,12 +86,14 @@ Portability: Pointers are not always 32bits, not all computers are little but it is easy to make sure the code can easily be made portable. -Clarity: It helps if anyone can see how to fix the driver. It helps +Clarity: + It helps if anyone can see how to fix the driver. It helps you because you get patches not bug reports. If you submit a driver that intentionally obfuscates how the hardware works it will go in the bitbucket. -PM support: Since Linux is used on many portable and desktop systems, your +PM support: + Since Linux is used on many portable and desktop systems, your driver is likely to be used on such a system and therefore it should support basic power management by implementing, if necessary, the .suspend and .resume methods used during the @@ -101,7 +108,8 @@ PM support: Since Linux is used on many portable and desktop systems, your complete overview of the power management issues related to drivers see Documentation/power/devices.txt . -Control: In general if there is active maintenance of a driver by +Control: + In general if there is active maintenance of a driver by the author then patches will be redirected to them unless they are totally obvious and without need of checking. If you want to be the contact and update point for the @@ -111,13 +119,15 @@ Control: In general if there is active maintenance of a driver by What Criteria Do Not Determine Acceptance ----------------------------------------- -Vendor: Being the hardware vendor and maintaining the driver is +Vendor: + Being the hardware vendor and maintaining the driver is often a good thing. If there is a stable working driver from other people already in the tree don't expect 'we are the vendor' to get your driver chosen. Ideally work with the existing driver author to build a single perfect driver. -Author: It doesn't matter if a large Linux company wrote the driver, +Author: + It doesn't matter if a large Linux company wrote the driver, or you did. Nobody has any special access to the kernel tree. Anyone who tells you otherwise isn't telling the whole story. @@ -127,8 +137,10 @@ Resources --------- Linux kernel master tree: - ftp.??.kernel.org:/pub/linux/kernel/... - ?? == your country code, such as "us", "uk", "fr", etc. + ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/... + + where *country_code* == your country code, such as + **us**, **uk**, **fr**, etc. http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git @@ -141,14 +153,19 @@ Linux Device Drivers, Third Edition (covers 2.6.10): LWN.net: Weekly summary of kernel development activity - http://lwn.net/ + 2.6 API changes: + http://lwn.net/Articles/2.6-kernel-api/ + Porting drivers from prior kernels to 2.6: + http://lwn.net/Articles/driver-porting/ KernelNewbies: Documentation and assistance for new kernel programmers - http://kernelnewbies.org/ + + http://kernelnewbies.org/ Linux USB project: http://www.linux-usb.org/ -- 2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2016-09-21 02:50 +0200 |
| Message-ID | <sjDTA-1SY-9@gated-at.bofh.it> |
| In reply to | #1486354 |
On Mon, 19 Sep 2016 08:07:34 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> That's the 4th version of this series. It also contains a second patch series
> with more ReST conversions and documentation improvements.
> This patchset merges the content of a second patch series:
>
> [PATCH 00/17] Improve documentation for the development-process
>
OK, I'm applying these through 28; I'm going to hold off on #29. Thanks
for separating that part out so nicely.
> I opted to keep the patch changing the kernel-docs.txt changes
> (patch 21/29). The patch is already written and another patch
> (patch 22/29) depends on it, because there are references to
> this file at Documentation/HOWTO.
>
> It shouldn't be hard to get rid of it, but I'm not sure if worths
> the effort. As I commented, people might find useful to update
> it to point to more modern documents. If people won't do it,
> it can still be removed from the Kernel a the next Kernel version.
I'll take them for now, since there seems to be interest in doing something
with this document. I kept the applying-patches one as well. But I do
think that we need to start being a bit more willing to get rid of musty
old docs. We don't carry unused code because "it might be useful to
somebody"; I think we should take the same approach to docs. Out-of-date
or irrelevant docs are a maintenance burden, and they impose a heavy burden
on the people the docs are most meant to help...
A few notes:
#1 didn't apply, I had to do it by hand. I suspect my late application of
Marcus's work got in the way there.
#2 had this:
> Content-Type: text/plain; charset=true
...which threw git am for a loop; I had to fix it manually. What gives
there?
#4 didn't apply and had to be done by hand.
#10 (CodingStyle) has a lot of ".. code-block:: c" constructs. Why are
those needed? We're still using C by default for literal blocks, right?
#15 (SecurityBugs) leaves the section numbers in place; did you intend
that?
#21 (kernel-docs.txt) had the charset=true weirdness
#28 actually, I balked at applying this one, since it assumes that
the great renaming is taking place, and that hasn't happened yet.
So actually I only went through #27, but that took a long time - seemingly
longer than it takes you to create them! :)
A few of the patches still have the bare "::" lines in them; I think I'll
just add a patch to fix those up real quick.
Thanks,
jon
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-21 11:30 +0200 |
| Message-ID | <sjM0O-7bE-23@gated-at.bofh.it> |
| In reply to | #1487742 |
Em Tue, 20 Sep 2016 18:44:54 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > On Mon, 19 Sep 2016 08:07:34 -0300 > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > > > That's the 4th version of this series. It also contains a second patch series > > with more ReST conversions and documentation improvements. > > This patchset merges the content of a second patch series: > > > > [PATCH 00/17] Improve documentation for the development-process > > > > OK, I'm applying these through 28; I'm going to hold off on #29. Thanks > for separating that part out so nicely. > > > I opted to keep the patch changing the kernel-docs.txt changes > > (patch 21/29). The patch is already written and another patch > > (patch 22/29) depends on it, because there are references to > > this file at Documentation/HOWTO. > > > > It shouldn't be hard to get rid of it, but I'm not sure if worths > > the effort. As I commented, people might find useful to update > > it to point to more modern documents. If people won't do it, > > it can still be removed from the Kernel a the next Kernel version. > > I'll take them for now, since there seems to be interest in doing something > with this document. I kept the applying-patches one as well. But I do > think that we need to start being a bit more willing to get rid of musty > old docs. We don't carry unused code because "it might be useful to > somebody"; I think we should take the same approach to docs. Out-of-date > or irrelevant docs are a maintenance burden, and they impose a heavy burden > on the people the docs are most meant to help... > > A few notes: > > #1 didn't apply, I had to do it by hand. I suspect my late application of > Marcus's work got in the way there. > > #2 had this: > > > Content-Type: text/plain; charset=true > > ...which threw git am for a loop; I had to fix it manually. What gives > there? That's really weird! I did only the usual stuff here... patches created with git format-patch and C/C added via get_maintainers.pl. The resulting patch is sent via: git send-email patches/tmp I double-checked: the patches created are without any Content-Type:. It is git send-email (git-2.7.4-2.fc24.x86_64) that added those: Content-Type: text/plain; charset=true Content-Transfer-Encoding: 8bit I'll try to investigate what's wrong there or otherwise check if the upstream version from git's repository works better. > > #4 didn't apply and had to be done by hand. > > #10 (CodingStyle) has a lot of ".. code-block:: c" constructs. Why are > those needed? We're still using C by default for literal blocks, right? I opted to keep the code-block there, because, at least on one of the blocks, we had to use: .. code-block:: none Because pygments were doing weird highlights on it. So, for coherency, I ended by keeping it all along. > > #15 (SecurityBugs) leaves the section numbers in place; did you intend > that? Yes. Since we remove the :numbered:, and this document had already the sections numbered manually, I opted to preserve. Yet, I don't see anything special there that would justify numbering. So, I guess we can just remove it. > #21 (kernel-docs.txt) had the charset=true weirdness > > #28 actually, I balked at applying this one, since it assumes that > the great renaming is taking place, and that hasn't happened yet. Oh! Ok, I'll fix this one, removing the rename stuff from the conversion and resend. > So actually I only went through #27, but that took a long time - seemingly > longer than it takes you to create them! :) Sorry for that. I'll try to make it easier for you next time. > A few of the patches still have the bare "::" lines in them; I think I'll > just add a patch to fix those up real quick. OK. Thanks, Mauro
[toc] | [prev] | [standalone]
Page 2 of 2 — ← Prev page 1 [2]
Back to top | Article view | linux.kernel
csiph-web