mirror of
https://github.com/LibreELEC/LibreELEC.tv.git
synced 2025-07-24 11:16:51 +00:00
3rdparty: update syslinux to syslinux-4.03
Signed-off-by: Stephan Raue <stephan@openelec.tv>
This commit is contained in:
parent
5af409135b
commit
5f6b021812
14
config/release/3rdparty/syslinux/NEWS
vendored
14
config/release/3rdparty/syslinux/NEWS
vendored
@ -2,6 +2,20 @@ Starting with 1.47, changes marked with SYSLINUX, PXELINUX, ISOLINUX
|
||||
or EXTLINUX apply to that specific program only; other changes apply
|
||||
to all derivatives.
|
||||
|
||||
Changes in 4.03:
|
||||
* Don't hang if no configuration file is found.
|
||||
* Better support for booting from MBRs which don't pass
|
||||
handover information.
|
||||
* EXTLINUX: Try to be smarter about finding the partition
|
||||
offset.
|
||||
* chain.c32: support chainloading Dell Real Mode Kernel (Gene
|
||||
Cumm).
|
||||
* chain.c32: fix booting in CHS mode.
|
||||
* rosh.c32 updated (Gene Cumm).
|
||||
* Fix the -s option to the syslinux/extlinux installer (Arwin
|
||||
Vosselman).
|
||||
* isohybrid: fix padding of large images (PJ Pandit).
|
||||
|
||||
Changes in 4.02:
|
||||
* SYSLINUX: correctly handle the case where the -d option is
|
||||
specified with a non-absolute path, i.e. "syslinux -d
|
||||
|
831
config/release/3rdparty/syslinux/doc/CodingStyle.txt
vendored
Normal file
831
config/release/3rdparty/syslinux/doc/CodingStyle.txt
vendored
Normal file
@ -0,0 +1,831 @@
|
||||
Syslinux uses Linux kernel coding style, except that we are "heretic"
|
||||
in the sense of using 4 spaces instead of 8 for indentation.
|
||||
|
||||
This coding style will be applied after the 3.81 release.
|
||||
|
||||
|
||||
-------------------------------------------------
|
||||
|
||||
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
|
||||
views on anybody, but this is what goes for anything that I have to be
|
||||
able to maintain, and I'd prefer it for most other things too. Please
|
||||
at least consider the points made here.
|
||||
|
||||
First off, I'd suggest printing out a copy of the GNU coding standards,
|
||||
and NOT read it. Burn them, it's a great symbolic gesture.
|
||||
|
||||
Anyway, here goes:
|
||||
|
||||
|
||||
Chapter 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!)
|
||||
characters deep, and that is akin to trying to define the value of PI to
|
||||
be 3.
|
||||
|
||||
Rationale: The whole idea behind indentation is to clearly define where
|
||||
a block of control starts and ends. Especially when you've been looking
|
||||
at your screen for 20 straight hours, you'll find it a lot easier to see
|
||||
how the indentation works if you have large indentations.
|
||||
|
||||
Now, some people will claim that having 8-character indentations makes
|
||||
the code move too far to the right, and makes it hard to read on a
|
||||
80-character terminal screen. The answer to that is that if you need
|
||||
more than 3 levels of indentation, you're screwed anyway, and should fix
|
||||
your program.
|
||||
|
||||
In short, 8-char indents make things easier to read, and have the added
|
||||
benefit of warning you when you're nesting your functions too deep.
|
||||
Heed that warning.
|
||||
|
||||
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.:
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
|
||||
Don't put multiple statements on a single line unless you have
|
||||
something to hide:
|
||||
|
||||
if (condition) do_this;
|
||||
do_something_everytime;
|
||||
|
||||
Don't put multiple assignments on a single line either. Kernel coding style
|
||||
is super simple. Avoid tricky expressions.
|
||||
|
||||
Outside of comments, documentation and except in Kconfig, spaces are never
|
||||
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
|
||||
|
||||
Coding style is all about readability and maintainability using commonly
|
||||
available tools.
|
||||
|
||||
The limit on the length of lines is 80 columns and this is a strongly
|
||||
preferred limit.
|
||||
|
||||
Statements longer than 80 columns will be broken into sensible chunks.
|
||||
Descendants are always substantially shorter than the parent and are placed
|
||||
substantially to the right. The same applies to function headers with a long
|
||||
argument list. Long strings are as well broken into shorter strings. The
|
||||
only exception to this is where exceeding 80 columns significantly increases
|
||||
readability and does not hide information.
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
Chapter 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
|
||||
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:
|
||||
|
||||
if (x is true) {
|
||||
we do y
|
||||
}
|
||||
|
||||
This applies to all non-function statement blocks (if, switch, for,
|
||||
while, do). E.g.:
|
||||
|
||||
switch (action) {
|
||||
case KOBJ_ADD:
|
||||
return "add";
|
||||
case KOBJ_REMOVE:
|
||||
return "remove";
|
||||
case KOBJ_CHANGE:
|
||||
return "change";
|
||||
default:
|
||||
return NULL;
|
||||
}
|
||||
|
||||
However, there is one special case, namely functions: they have the
|
||||
opening brace at the beginning of the next line, thus:
|
||||
|
||||
int function(int x)
|
||||
{
|
||||
body of function
|
||||
}
|
||||
|
||||
Heretic people all over the world have claimed that this inconsistency
|
||||
is ... well ... inconsistent, but all right-thinking people know that
|
||||
(a) K&R are _right_ and (b) K&R are right. Besides, functions are
|
||||
special anyway (you can't nest them in C).
|
||||
|
||||
Note that the closing brace is empty on a line of its own, _except_ in
|
||||
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:
|
||||
|
||||
do {
|
||||
body of do-loop
|
||||
} while (condition);
|
||||
|
||||
and
|
||||
|
||||
if (x == y) {
|
||||
..
|
||||
} else if (x > y) {
|
||||
...
|
||||
} else {
|
||||
....
|
||||
}
|
||||
|
||||
Rationale: K&R.
|
||||
|
||||
Also, note that this brace-placement also minimizes the number of empty
|
||||
(or almost empty) lines, without any loss of readability. Thus, as the
|
||||
supply of new-lines on your screen is not a renewable resource (think
|
||||
25-line terminal screens here), you have more empty lines to put
|
||||
comments on.
|
||||
|
||||
Do not unnecessarily use braces where a single statement will do.
|
||||
|
||||
if (condition)
|
||||
action();
|
||||
|
||||
This does not apply if one branch of a conditional statement is a single
|
||||
statement. Use braces in both branches.
|
||||
|
||||
if (condition) {
|
||||
do_this();
|
||||
do_that();
|
||||
} else {
|
||||
otherwise();
|
||||
}
|
||||
|
||||
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).
|
||||
|
||||
So use a space after these keywords:
|
||||
if, switch, case, for, do, while
|
||||
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
|
||||
s = sizeof(struct file);
|
||||
|
||||
Do not add spaces around (inside) parenthesized expressions. This example is
|
||||
*bad*:
|
||||
|
||||
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
|
||||
adjacent to the type name. Examples:
|
||||
|
||||
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:
|
||||
|
||||
= + - < > * / % | & ^ <= >= == != ? :
|
||||
|
||||
but no space after unary operators:
|
||||
& * + - ~ ! sizeof typeof alignof __attribute__ defined
|
||||
|
||||
no space before the postfix increment & decrement unary operators:
|
||||
++ --
|
||||
|
||||
no space after the prefix increment & decrement unary operators:
|
||||
++ --
|
||||
|
||||
and no space around the '.' and "->" structure member operators.
|
||||
|
||||
Do not leave trailing whitespace at the ends of lines. Some editors with
|
||||
"smart" indentation will insert whitespace at the beginning of new lines as
|
||||
appropriate, so you can start typing the next line of code right away.
|
||||
However, some such editors do not remove the whitespace if you end up not
|
||||
putting a line of code there, such as if you leave a blank line. As a result,
|
||||
you end up with lines containing trailing whitespace.
|
||||
|
||||
Git will warn you about patches that introduce trailing whitespace, and can
|
||||
optionally strip the trailing whitespace for you; however, if applying a series
|
||||
of patches, this may make later patches in the series fail by changing their
|
||||
context lines.
|
||||
|
||||
|
||||
Chapter 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
|
||||
ThisVariableIsATemporaryCounter. A C programmer would call that
|
||||
variable "tmp", which is much easier to write, and not the least more
|
||||
difficult to understand.
|
||||
|
||||
HOWEVER, while mixed-case names are frowned upon, descriptive names for
|
||||
global variables are a must. To call a global function "foo" is a
|
||||
shooting offense.
|
||||
|
||||
GLOBAL variables (to be used only if you _really_ need them) need to
|
||||
have descriptive names, as do global functions. If you have a function
|
||||
that counts the number of active users, you should call that
|
||||
"count_active_users()" or similar, you should _not_ call it "cntusr()".
|
||||
|
||||
Encoding the type of a function into the name (so-called Hungarian
|
||||
notation) is brain damaged - the compiler knows the types anyway and can
|
||||
check those, and it only confuses the programmer. No wonder MicroSoft
|
||||
makes buggy programs.
|
||||
|
||||
LOCAL variable names should be short, and to the point. If you have
|
||||
some random integer loop counter, it should probably be called "i".
|
||||
Calling it "loop_counter" is non-productive, if there is no chance of it
|
||||
being mis-understood. Similarly, "tmp" can be just about any type of
|
||||
variable that is used to hold a temporary value.
|
||||
|
||||
If you are afraid to mix up your local variable names, you have another
|
||||
problem, which is called the function-growth-hormone-imbalance syndrome.
|
||||
See chapter 6 (Functions).
|
||||
|
||||
|
||||
Chapter 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
|
||||
|
||||
vps_t a;
|
||||
|
||||
in the source, what does it mean?
|
||||
|
||||
In contrast, if it says
|
||||
|
||||
struct virtual_container *a;
|
||||
|
||||
you can actually tell what "a" is.
|
||||
|
||||
Lots of people think that typedefs "help readability". Not so. They are
|
||||
useful only for:
|
||||
|
||||
(a) totally opaque objects (where the typedef is actively used to _hide_
|
||||
what the object is).
|
||||
|
||||
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.
|
||||
|
||||
(b) Clear integer types, where the abstraction _helps_ avoid confusion
|
||||
whether it is "int" or "long".
|
||||
|
||||
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
|
||||
|
||||
typedef unsigned long myflags_t;
|
||||
|
||||
but if there is a clear reason for why it under certain circumstances
|
||||
might be an "unsigned int" and under other configurations might be
|
||||
"unsigned long", then by all means go ahead and use a typedef.
|
||||
|
||||
(c) when you use sparse to literally create a _new_ type for
|
||||
type-checking.
|
||||
|
||||
(d) New types which are identical to standard C99 types, in certain
|
||||
exceptional circumstances.
|
||||
|
||||
Although it would only take a short amount of time for the eyes and
|
||||
brain to become accustomed to the standard types like 'uint32_t',
|
||||
some people object to their use anyway.
|
||||
|
||||
Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
|
||||
signed equivalents which are identical to standard types are
|
||||
permitted -- although they are not mandatory in new code of your
|
||||
own.
|
||||
|
||||
When editing existing code which already uses one or the other set
|
||||
of types, you should conform to the existing choices in that code.
|
||||
|
||||
(e) Types safe for use in userspace.
|
||||
|
||||
In certain structures which are visible to userspace, we cannot
|
||||
require C99 types and cannot use the 'u32' form above. Thus, we
|
||||
use __u32 and similar types in all structures which are shared
|
||||
with userspace.
|
||||
|
||||
Maybe there are other cases too, but the rule should basically be to NEVER
|
||||
EVER use a typedef unless you can clearly match one of those rules.
|
||||
|
||||
In general, a pointer, or a struct that has elements that can reasonably
|
||||
be directly accessed should _never_ be a typedef.
|
||||
|
||||
|
||||
Chapter 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,
|
||||
as we all know), and do one thing and do that well.
|
||||
|
||||
The maximum length of a function is inversely proportional to the
|
||||
complexity and indentation level of that function. So, if you have a
|
||||
conceptually simple function that is just one long (but simple)
|
||||
case-statement, where you have to do lots of small things for a lot of
|
||||
different cases, it's OK to have a longer function.
|
||||
|
||||
However, if you have a complex function, and you suspect that a
|
||||
less-than-gifted first-year high-school student might not even
|
||||
understand what the function is all about, you should adhere to the
|
||||
maximum limits all the more closely. Use helper functions with
|
||||
descriptive names (you can ask the compiler to in-line them if you think
|
||||
it's performance-critical, and it will probably do a better job of it
|
||||
than you would have done).
|
||||
|
||||
Another measure of the function is the number of local variables. They
|
||||
shouldn't exceed 5-10, or you're doing something wrong. Re-think the
|
||||
function, and split it into smaller pieces. A human brain can
|
||||
generally easily keep track of about 7 different things, anything more
|
||||
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.:
|
||||
|
||||
int system_is_up(void)
|
||||
{
|
||||
return system_state == SYSTEM_RUNNING;
|
||||
}
|
||||
EXPORT_SYMBOL(system_is_up);
|
||||
|
||||
In function prototypes, include parameter names with their data types.
|
||||
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
|
||||
|
||||
Albeit deprecated by some people, the equivalent of the goto statement is
|
||||
used frequently by compilers in form of the unconditional jump instruction.
|
||||
|
||||
The goto statement comes in handy when a function exits from multiple
|
||||
locations and some common work such as cleanup has to be done.
|
||||
|
||||
The rationale is:
|
||||
|
||||
- unconditional statements are easier to understand and follow
|
||||
- nesting is reduced
|
||||
- errors by not updating individual exit points when making
|
||||
modifications are prevented
|
||||
- saves the compiler work to optimize redundant code away ;)
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
Chapter 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
|
||||
write the code so that the _working_ is obvious, and it's a waste of
|
||||
time to explain badly written code.
|
||||
|
||||
Generally, you want your comments to tell WHAT your code does, not HOW.
|
||||
Also, try to avoid putting comments inside a function body: if the
|
||||
function is so complex that you need to separately comment parts of it,
|
||||
you should probably go back to chapter 6 for a while. You can make
|
||||
small comments to note or warn about something particularly clever (or
|
||||
ugly), but try to avoid excess. Instead, put the comments at the head
|
||||
of the function, telling people what it does, and possibly WHY it does
|
||||
it.
|
||||
|
||||
When commenting the kernel API functions, please use the kernel-doc format.
|
||||
See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
|
||||
for details.
|
||||
|
||||
Linux style for comments is the C89 "/* ... */" style.
|
||||
Don't use C99-style "// ..." comments.
|
||||
|
||||
The preferred style for long (multi-line) comments is:
|
||||
|
||||
/*
|
||||
* 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.
|
||||
*/
|
||||
|
||||
It's also important to comment data, whether they are basic types or derived
|
||||
types. To this end, use just one data declaration per line (no commas for
|
||||
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
|
||||
|
||||
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
|
||||
you, and you've noticed that yes, it does do that, but the defaults it
|
||||
uses are less than desirable (in fact, they are worse than random
|
||||
typing - an infinite number of monkeys typing into GNU emacs would never
|
||||
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)))
|
||||
|
||||
(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)
|
||||
(c-set-style "linux-tabs-only")))))
|
||||
|
||||
This will make emacs go better with the kernel coding style for C
|
||||
files below ~/src/linux-trees.
|
||||
|
||||
But even if you fail in getting emacs to do sane formatting, not
|
||||
everything is lost: use "indent".
|
||||
|
||||
Now, again, GNU indent has the same brain-dead settings that GNU emacs
|
||||
has, which is why you need to give it a few command line options.
|
||||
However, that's not too bad, because even the makers of GNU indent
|
||||
recognize the authority of K&R (the GNU people aren't evil, they are
|
||||
just severely misguided in this matter), so you just give indent the
|
||||
options "-kr -i8" (stands for "K&R, 8 character indents"), or use
|
||||
"scripts/Lindent", which indents in the latest style.
|
||||
|
||||
"indent" has a lot of options, and especially when it comes to comment
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
|
||||
Features that might still be considered unstable should be defined as
|
||||
dependent on "EXPERIMENTAL":
|
||||
|
||||
config SLUB
|
||||
depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT
|
||||
bool "SLUB (Unqueued Allocator)"
|
||||
...
|
||||
|
||||
while seriously dangerous features (such as write support for certain
|
||||
filesystems) should advertise this prominently in their prompt string:
|
||||
|
||||
config ADFS_FS_RW
|
||||
bool "ADFS write support (DANGEROUS)"
|
||||
depends on ADFS_FS
|
||||
...
|
||||
|
||||
For full documentation on the configuration files, see the file
|
||||
Documentation/kbuild/kconfig-language.txt.
|
||||
|
||||
|
||||
Chapter 11: Data structures
|
||||
|
||||
Data structures that have visibility outside the single-threaded
|
||||
environment they are created and destroyed in should always have
|
||||
reference counts. In the kernel, garbage collection doesn't exist (and
|
||||
outside the kernel garbage collection is slow and inefficient), which
|
||||
means that you absolutely _have_ to reference count all your uses.
|
||||
|
||||
Reference counting means that you can avoid locking, and allows multiple
|
||||
users to have access to the data structure in parallel - and not having
|
||||
to worry about the structure suddenly going away from under them just
|
||||
because they slept or did something else for a while.
|
||||
|
||||
Note that locking is _not_ a replacement for reference counting.
|
||||
Locking is used to keep data structures coherent, while reference
|
||||
counting is a memory management technique. Usually both are needed, and
|
||||
they are not to be confused with each other.
|
||||
|
||||
Many data structures can indeed have two levels of reference counting,
|
||||
when there are users of different "classes". The subclass count counts
|
||||
the number of subclass users, and decrements the global count just once
|
||||
when the subclass count goes to zero.
|
||||
|
||||
Examples of this kind of "multi-level-reference-counting" can be found in
|
||||
memory management ("struct mm_struct": mm_users and mm_count), and in
|
||||
filesystem code ("struct super_block": s_count and s_active).
|
||||
|
||||
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
|
||||
|
||||
Names of macros defining constants and labels in enums are capitalized.
|
||||
|
||||
#define CONSTANT 0x12345
|
||||
|
||||
Enums are preferred when defining several related constants.
|
||||
|
||||
CAPITALIZED macro names are appreciated but macros resembling functions
|
||||
may be named in lower case.
|
||||
|
||||
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) \
|
||||
do { \
|
||||
if (a == 5) \
|
||||
do_this(b, c); \
|
||||
} while (0)
|
||||
|
||||
Things to avoid when using macros:
|
||||
|
||||
1) macros that affect control flow:
|
||||
|
||||
#define FOO(x) \
|
||||
do { \
|
||||
if (blah(x) < 0) \
|
||||
return -EBUGGERED; \
|
||||
} while(0)
|
||||
|
||||
is a _very_ bad idea. It looks like a function call but exits the "calling"
|
||||
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:
|
||||
|
||||
#define FOO(val) bar(index, val)
|
||||
|
||||
might look like a good thing, but it's confusing as hell when one reads the
|
||||
code and it's prone to breakage from seemingly innocent changes.
|
||||
|
||||
3) macros with arguments that are used as l-values: FOO(x) = y; will
|
||||
bite you if somebody e.g. turns FOO into an inline function.
|
||||
|
||||
4) forgetting about precedence: macros defining constants using expressions
|
||||
must enclose the expression in parentheses. Beware of similar issues with
|
||||
macros using parameters.
|
||||
|
||||
#define CONSTANT 0x4000
|
||||
#define CONSTEXP (CONSTANT | 3)
|
||||
|
||||
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
|
||||
|
||||
Kernel developers like to be seen as literate. Do mind the spelling
|
||||
of kernel messages to make a good impression. Do not use crippled
|
||||
words like "dont"; use "do not" or "don't" instead. Make the messages
|
||||
concise, clear, and unambiguous.
|
||||
|
||||
Kernel messages do not have to be terminated with a period.
|
||||
|
||||
Printing numbers in parentheses (%d) adds no value and should be avoided.
|
||||
|
||||
There are a number of driver model diagnostic macros in <linux/device.h>
|
||||
which you should use to make sure messages are matched to the right device
|
||||
and driver, and are tagged with the right level: dev_err(), dev_warn(),
|
||||
dev_info(), and so forth. For messages that aren't associated with a
|
||||
particular device, <linux/kernel.h> defines pr_debug() and pr_info().
|
||||
|
||||
Coming up with good debugging messages can be quite a challenge; and once
|
||||
you have them, they can be a huge help for remote troubleshooting. Such
|
||||
messages should be compiled out when the DEBUG symbol is not defined (that
|
||||
is, by default they are not included). When you use dev_dbg() or pr_debug(),
|
||||
that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG.
|
||||
A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the
|
||||
ones already enabled by DEBUG.
|
||||
|
||||
|
||||
Chapter 14: Allocating memory
|
||||
|
||||
The kernel provides the following general purpose memory allocators:
|
||||
kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API
|
||||
documentation for further information about them.
|
||||
|
||||
The preferred form for passing a size of a struct is the following:
|
||||
|
||||
p = kmalloc(sizeof(*p), ...);
|
||||
|
||||
The alternative form where struct name is spelled out hurts readability and
|
||||
introduces an opportunity for a bug when the pointer variable type is changed
|
||||
but the corresponding sizeof that is passed to a memory allocator is not.
|
||||
|
||||
Casting the return value which is a void pointer is redundant. The conversion
|
||||
from void pointer to any other pointer type is guaranteed by the C programming
|
||||
language.
|
||||
|
||||
|
||||
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).
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
568
config/release/3rdparty/syslinux/doc/SubmittingPatches.txt
vendored
Normal file
568
config/release/3rdparty/syslinux/doc/SubmittingPatches.txt
vendored
Normal file
@ -0,0 +1,568 @@
|
||||
I don't have specific submission guidelines for Syslinux, but the ones
|
||||
that appropriate to the Linux kernel are certainly good enough for
|
||||
Syslinux.
|
||||
|
||||
In particular, however, I appreciate if patches sent follow the
|
||||
standard Linux submission format, as I can automatically import them
|
||||
into git, retaining description and author information. Thus, this
|
||||
file from the Linux kernel might be useful.
|
||||
|
||||
|
||||
-----------------------------------------------------------------------
|
||||
|
||||
|
||||
|
||||
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
|
||||
with "the system." This text is a collection of suggestions which
|
||||
can greatly increase the chances of your change being accepted.
|
||||
|
||||
Read Documentation/SubmitChecklist for a list of items to check
|
||||
before submitting code. If you are submitting a driver, also read
|
||||
Documentation/SubmittingDrivers.
|
||||
|
||||
|
||||
|
||||
--------------------------------------------
|
||||
SECTION 1 - CREATING AND SENDING YOUR CHANGE
|
||||
--------------------------------------------
|
||||
|
||||
|
||||
|
||||
1) "diff -up"
|
||||
------------
|
||||
|
||||
Use "diff -up" or "diff -uprN" to create patches.
|
||||
|
||||
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
|
||||
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:
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
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" 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. The "dontdiff" file is included in the kernel tree in
|
||||
2.6.12 and later. For earlier kernel versions, you can get it
|
||||
from <http://www.xenotime.net/linux/doc/dontdiff>.
|
||||
|
||||
Make sure your patch does not include any extra files which do not
|
||||
belong in a patch submission. Make sure to review your patch -after-
|
||||
generated it with diff(1), to ensure accuracy.
|
||||
|
||||
If your changes produce a lot of deltas, you may want to look into
|
||||
splitting them into individual patches which modify things in
|
||||
logical stages. This will facilitate easier reviewing by other
|
||||
kernel developers, very important if you want your patch accepted.
|
||||
There are a number of scripts which can aid in this:
|
||||
|
||||
Quilt:
|
||||
http://savannah.nongnu.org/projects/quilt
|
||||
|
||||
Andrew Morton's patch scripts:
|
||||
http://www.zip.com.au/~akpm/linux/patches/
|
||||
Instead of these scripts, quilt is the recommended patch management
|
||||
tool (see above).
|
||||
|
||||
|
||||
|
||||
2) Describe your changes.
|
||||
|
||||
Describe the technical detail of the change(s) your patch includes.
|
||||
|
||||
Be as specific as possible. The WORST descriptions possible include
|
||||
things like "update driver X", "bug fix for driver X", or "this patch
|
||||
includes updates for subsystem X. Please apply."
|
||||
|
||||
If your description starts to get long, that's a sign that you probably
|
||||
need to split up your patch. See #3, next.
|
||||
|
||||
|
||||
|
||||
3) Separate your changes.
|
||||
|
||||
Separate _logical changes_ into a single patch file.
|
||||
|
||||
For example, if your changes include both bug fixes and performance
|
||||
enhancements for a single driver, separate those changes into two
|
||||
or more patches. If your changes include an API update, and a new
|
||||
driver which uses that new API, separate those into two patches.
|
||||
|
||||
On the other hand, if you make a single change to numerous files,
|
||||
group those changes into a single patch. Thus a single logical change
|
||||
is contained within a single patch.
|
||||
|
||||
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"
|
||||
in your patch description.
|
||||
|
||||
If you cannot condense your patch set into a smaller set of patches,
|
||||
then only post say 15 or so at a time and wait for review and integration.
|
||||
|
||||
|
||||
|
||||
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
|
||||
the reviewers time and will get your patch rejected, probably
|
||||
without even being read.
|
||||
|
||||
At a minimum you should check your patches with the patch style
|
||||
checker prior to submission (scripts/checkpatch.pl). You should
|
||||
be able to justify all violations that remain in your patch.
|
||||
|
||||
|
||||
|
||||
5) Select e-mail destination.
|
||||
|
||||
Look through the MAINTAINERS file and the source code, and determine
|
||||
if your change applies to a specific subsystem of the kernel, with
|
||||
an assigned maintainer. If so, e-mail that person.
|
||||
|
||||
If no maintainer is listed, or the maintainer does not respond, send
|
||||
your patch to the primary Linux kernel developer's mailing list,
|
||||
linux-kernel@vger.kernel.org. Most kernel developers monitor this
|
||||
e-mail list, and can comment on your changes.
|
||||
|
||||
|
||||
Do not send more than 15 patches at once to the vger mailing lists!!!
|
||||
|
||||
|
||||
Linus Torvalds is the final arbiter of all changes accepted into the
|
||||
Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
|
||||
He gets a lot of e-mail, so typically you should do your best to -avoid-
|
||||
sending him e-mail.
|
||||
|
||||
Patches which are bug fixes, are "obvious" changes, or similarly
|
||||
require little discussion should be sent or CC'd to Linus. Patches
|
||||
which require discussion or do not have a clear advantage should
|
||||
usually be sent first to linux-kernel. Only after the patch is
|
||||
discussed should the patch then be submitted to Linus.
|
||||
|
||||
|
||||
|
||||
6) Select your CC (e-mail carbon copy) list.
|
||||
|
||||
Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org.
|
||||
|
||||
Other kernel developers besides Linus need to be aware of your change,
|
||||
so that they may comment on it and offer code review and suggestions.
|
||||
linux-kernel is the primary Linux kernel developer mailing list.
|
||||
Other mailing lists are available for specific subsystems, such as
|
||||
USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the
|
||||
MAINTAINERS file for a mailing list that relates specifically to
|
||||
your change.
|
||||
|
||||
Majordomo lists of VGER.KERNEL.ORG at:
|
||||
<http://vger.kernel.org/vger-lists.html>
|
||||
|
||||
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.
|
||||
|
||||
Even if the maintainer did not respond in step #4, make sure to ALWAYS
|
||||
copy the maintainer when you change their code.
|
||||
|
||||
For small patches you may want to CC the Trivial Patch Monkey
|
||||
trivial@kernel.org managed by Adrian Bunk; which collects "trivial"
|
||||
patches. Trivial patches must qualify for one of the following rules:
|
||||
Spelling fixes in documentation
|
||||
Spelling fixes which could break grep(1)
|
||||
Warning fixes (cluttering with useless warnings is bad)
|
||||
Compilation fixes (only if they are actually correct)
|
||||
Runtime fixes (only if they actually fix things)
|
||||
Removing use of deprecated functions/macros (eg. check_region)
|
||||
Contact detail and documentation fixes
|
||||
Non-portable code replaced by portable code (even in arch-specific,
|
||||
since people copy, as long as it's trivial)
|
||||
Any fix by the author/maintainer of the file (ie. patch monkey
|
||||
in re-transmission mode)
|
||||
URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/>
|
||||
|
||||
|
||||
|
||||
7) 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
|
||||
developer to be able to "quote" your changes, using standard e-mail
|
||||
tools, so that they may comment on specific portions of your code.
|
||||
|
||||
For this reason, all patches should be submitting e-mail "inline".
|
||||
WARNING: Be wary of your editor's word-wrap corrupting your patch,
|
||||
if you choose to cut-n-paste your patch.
|
||||
|
||||
Do not attach the patch as a MIME attachment, compressed or not.
|
||||
Many popular e-mail applications will not always transmit a MIME
|
||||
attachment as plain text, making it impossible to comment on your
|
||||
code. A MIME attachment also takes Linus a bit more time to process,
|
||||
decreasing the likelihood of your MIME-attached change being accepted.
|
||||
|
||||
Exception: If your mailer is mangling patches then someone may ask
|
||||
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.
|
||||
|
||||
8) E-mail size.
|
||||
|
||||
When sending patches to Linus, always follow step #7.
|
||||
|
||||
Large changes are not appropriate for mailing lists, and some
|
||||
maintainers. If your patch, uncompressed, exceeds 40 kB in size,
|
||||
it is preferred that you store your patch on an Internet-accessible
|
||||
server, and provide instead a URL (link) pointing to your patch.
|
||||
|
||||
|
||||
|
||||
9) Name your kernel version.
|
||||
|
||||
It is important to note, either in the subject line or in the patch
|
||||
description, the kernel version to which this patch applies.
|
||||
|
||||
If the patch does not apply cleanly to the latest kernel version,
|
||||
Linus will not apply it.
|
||||
|
||||
|
||||
|
||||
10) Don't get discouraged. Re-submit.
|
||||
|
||||
After you have submitted your change, be patient and wait. If Linus
|
||||
likes your change and applies it, it will appear in the next version
|
||||
of the kernel that he releases.
|
||||
|
||||
However, if your change doesn't appear in the next version of the
|
||||
kernel, there could be any number of reasons. It's YOUR job to
|
||||
narrow down those reasons, correct what was wrong, and submit your
|
||||
updated change.
|
||||
|
||||
It is quite common for Linus to "drop" your patch without comment.
|
||||
That's the nature of the system. If he drops your patch, it could be
|
||||
due to
|
||||
* Your patch did not apply cleanly to the latest kernel version.
|
||||
* Your patch was not sufficiently discussed on linux-kernel.
|
||||
* A style issue (see section 2).
|
||||
* An e-mail formatting issue (re-read this section).
|
||||
* A technical problem with your change.
|
||||
* He gets tons of e-mail, and yours got lost in the shuffle.
|
||||
* You are being annoying.
|
||||
|
||||
When in doubt, solicit comments on linux-kernel mailing list.
|
||||
|
||||
|
||||
|
||||
11) Include PATCH in the subject
|
||||
|
||||
Due to high e-mail traffic to Linus, and to linux-kernel, it is common
|
||||
convention to prefix your subject line with [PATCH]. This lets Linus
|
||||
and other kernel developers more easily distinguish patches from other
|
||||
e-mail discussions.
|
||||
|
||||
|
||||
|
||||
12) Sign your work
|
||||
|
||||
To improve tracking of who did what, especially with patches that can
|
||||
percolate to their final resting place in the kernel through several
|
||||
layers of maintainers, we've introduced a "sign-off" procedure on
|
||||
patches that are being emailed around.
|
||||
|
||||
The sign-off is a simple line at the end of the explanation for the
|
||||
patch, which certifies that you wrote it or otherwise have the right to
|
||||
pass it on as a open-source patch. The rules are pretty simple: if you
|
||||
can certify the below:
|
||||
|
||||
Developer's Certificate of Origin 1.1
|
||||
|
||||
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
|
||||
indicated in the file; or
|
||||
|
||||
(b) The contribution is based upon previous work that, to the best
|
||||
of my knowledge, is covered under an appropriate open source
|
||||
license and I have the right under that license to submit that
|
||||
work with modifications, whether created in whole or in part
|
||||
by me, under the same open source license (unless I am
|
||||
permitted to submit under a different license), as indicated
|
||||
in the file; or
|
||||
|
||||
(c) The contribution was provided directly to me by some other
|
||||
person who certified (a), (b) or (c) and I have not modified
|
||||
it.
|
||||
|
||||
(d) I understand and agree that this project and the contribution
|
||||
are public and that a record of the contribution (including all
|
||||
personal information I submit with it, including my sign-off) is
|
||||
maintained indefinitely and may be redistributed consistent with
|
||||
this project or the open source license(s) involved.
|
||||
|
||||
then you just add a line saying
|
||||
|
||||
Signed-off-by: Random J Developer <random@developer.example.org>
|
||||
|
||||
using your real name (sorry, no pseudonyms or anonymous contributions.)
|
||||
|
||||
Some people also put extra tags at the end. They'll just be ignored for
|
||||
now, but you can do this to mark internal company procedures or just
|
||||
point out some special detail about the sign-off.
|
||||
|
||||
|
||||
13) When to use Acked-by:
|
||||
|
||||
The Signed-off-by: tag indicates that the signer was involved in the
|
||||
development of the patch, or that he/she was in the patch's delivery path.
|
||||
|
||||
If a person was not directly involved in the preparation or handling of a
|
||||
patch but wishes to signify and record their approval of it then they can
|
||||
arrange to have an Acked-by: line added to the patch's changelog.
|
||||
|
||||
Acked-by: is often used by the maintainer of the affected code when that
|
||||
maintainer neither contributed to nor forwarded the patch.
|
||||
|
||||
Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
|
||||
has at least reviewed the patch and has indicated acceptance. Hence patch
|
||||
mergers will sometimes manually convert an acker's "yep, looks good to me"
|
||||
into an Acked-by:.
|
||||
|
||||
Acked-by: does not necessarily indicate acknowledgement of the entire patch.
|
||||
For example, if a patch affects multiple subsystems and has an Acked-by: from
|
||||
one subsystem maintainer then this usually indicates acknowledgement of just
|
||||
the part which affects that maintainer's code. Judgement should be used here.
|
||||
When in doubt people should refer to the original discussion in the mailing
|
||||
list archives.
|
||||
|
||||
|
||||
14) The canonical patch format
|
||||
|
||||
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.
|
||||
|
||||
- An empty line.
|
||||
|
||||
- The body of the explanation, which will be copied to the
|
||||
permanent changelog to describe this patch.
|
||||
|
||||
- The "Signed-off-by:" lines, described above, which will
|
||||
also go in the changelog.
|
||||
|
||||
- A marker line containing simply "---".
|
||||
|
||||
- Any additional comments not suitable for the changelog.
|
||||
|
||||
- The actual patch (diff output).
|
||||
|
||||
The Subject line format makes it very easy to sort the emails
|
||||
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
|
||||
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).
|
||||
|
||||
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 developer discussions which refer to the patch.
|
||||
People will want to google for the "summary phrase" to read
|
||||
discussion regarding that patch.
|
||||
|
||||
A couple of example Subjects:
|
||||
|
||||
Subject: [patch 2/5] ext2: improve scalability of bitmap searching
|
||||
Subject: [PATCHv2 001/207] x86: fix eflags tracking
|
||||
|
||||
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 patch author in the changelog.
|
||||
|
||||
The explanation body will be committed to the permanent source
|
||||
changelog, so should make sense to a competent reader who has long
|
||||
since forgotten the immediate details of the discussion that might
|
||||
have led to this 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
|
||||
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.
|
||||
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).
|
||||
|
||||
See more details on the proper patch format in the following
|
||||
references.
|
||||
|
||||
|
||||
|
||||
|
||||
-----------------------------------
|
||||
SECTION 2 - HINTS, TIPS, AND TRICKS
|
||||
-----------------------------------
|
||||
|
||||
This section lists many of the common "rules" associated with code
|
||||
submitted to the kernel. There are always exceptions... but you must
|
||||
have a really good reason for doing so. You could probably call this
|
||||
section Linus Computer Science 101.
|
||||
|
||||
|
||||
|
||||
1) Read Documentation/CodingStyle
|
||||
|
||||
Nuff said. If your code deviates too much from this, it is likely
|
||||
to be rejected without further review, and without comment.
|
||||
|
||||
One significant exception is when moving code from one file to
|
||||
another -- in this case you should not modify the moved code at all in
|
||||
the same patch which moves it. This clearly delineates the act of
|
||||
moving the code and your changes. This greatly aids review of the
|
||||
actual differences and allows tools to better track the history of
|
||||
the code itself.
|
||||
|
||||
Check your patches with the patch style checker prior to submission
|
||||
(scripts/checkpatch.pl). The style checker should be viewed as
|
||||
a guide not as the final word. If your code looks better with
|
||||
a violation then its probably best left alone.
|
||||
|
||||
The checker reports at three levels:
|
||||
- ERROR: things that are very likely to be wrong
|
||||
- WARNING: things requiring careful review
|
||||
- CHECK: things requiring thought
|
||||
|
||||
You should be able to justify all violations that remain in your
|
||||
patch.
|
||||
|
||||
|
||||
|
||||
2) #ifdefs are ugly
|
||||
|
||||
Code cluttered with ifdefs is difficult to read and maintain. Don't do
|
||||
it. Instead, put your ifdefs in a header, and conditionally define
|
||||
'static inline' functions, or macros, which are used in the code.
|
||||
Let the compiler optimize away the "no-op" case.
|
||||
|
||||
Simple example, of poor code:
|
||||
|
||||
dev = alloc_etherdev (sizeof(struct funky_private));
|
||||
if (!dev)
|
||||
return -ENODEV;
|
||||
#ifdef CONFIG_NET_FUNKINESS
|
||||
init_funky_net(dev);
|
||||
#endif
|
||||
|
||||
Cleaned-up example:
|
||||
|
||||
(in header)
|
||||
#ifndef CONFIG_NET_FUNKINESS
|
||||
static inline void init_funky_net (struct net_device *d) {}
|
||||
#endif
|
||||
|
||||
(in the code itself)
|
||||
dev = alloc_etherdev (sizeof(struct funky_private));
|
||||
if (!dev)
|
||||
return -ENODEV;
|
||||
init_funky_net(dev);
|
||||
|
||||
|
||||
|
||||
3) 'static inline' is better than a macro
|
||||
|
||||
Static inline functions are greatly preferred over macros.
|
||||
They provide type safety, have no length limitations, no formatting
|
||||
limitations, and under gcc they are as cheap as macros.
|
||||
|
||||
Macros should only be used for cases where a static inline is clearly
|
||||
suboptimal [there a few, isolated cases of this in fast paths],
|
||||
or where it is impossible to use a static inline function [such as
|
||||
string-izing].
|
||||
|
||||
'static inline' is preferred over 'static __inline__', 'extern inline',
|
||||
and 'extern __inline__'.
|
||||
|
||||
|
||||
|
||||
4) Don't over-design.
|
||||
|
||||
Don't try to anticipate nebulous future cases which may or may not
|
||||
be useful: "Make it as simple as you can, and no simpler."
|
||||
|
||||
|
||||
|
||||
----------------------
|
||||
SECTION 3 - REFERENCES
|
||||
----------------------
|
||||
|
||||
Andrew Morton, "The perfect patch" (tpp).
|
||||
<http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt>
|
||||
|
||||
Jeff Garzik, "Linux kernel patch submission format".
|
||||
<http://linux.yyz.us/patch-format.html>
|
||||
|
||||
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
|
||||
<http://www.kroah.com/log/2005/03/31/>
|
||||
<http://www.kroah.com/log/2005/07/08/>
|
||||
<http://www.kroah.com/log/2005/10/19/>
|
||||
<http://www.kroah.com/log/2006/01/11/>
|
||||
|
||||
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
|
||||
<http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2>
|
||||
|
||||
Kernel Documentation/CodingStyle:
|
||||
<http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle>
|
||||
|
||||
Linus Torvalds's mail on the canonical patch format:
|
||||
<http://lkml.org/lkml/2005/4/7/183>
|
||||
--
|
@ -24,6 +24,8 @@ slight modifications.
|
||||
|
||||
2. The configuration file is called "extlinux.conf", and is expected
|
||||
to be found in the same directory as extlinux is installed in.
|
||||
Since 4.00 "syslinux.cfg" is also tried if "extlinux.conf" is not
|
||||
found.
|
||||
|
||||
|
||||
3. Pathnames can be absolute or relative; if absolute (with a leading
|
||||
|
@ -106,24 +106,25 @@ which requires root privilege.
|
||||
|
||||
++++ CONFIGURATION FILE ++++
|
||||
|
||||
All options here apply to PXELINUX, ISOLINUX and EXTLINUX as well as
|
||||
SYSLINUX unless otherwise noted. See the respective .txt files.
|
||||
|
||||
All the configurable defaults in SYSLINUX can be changed by putting a
|
||||
file called "syslinux.cfg" in the root directory of the boot disk.
|
||||
|
||||
This is a text file in either UNIX or DOS format, containing one or
|
||||
more of the following items (case is insensitive for keywords; upper
|
||||
case is used here to indicate that a word should be typed verbatim):
|
||||
|
||||
Starting with version 3.35, the configuration file can also be in
|
||||
either the /boot/syslinux or /syslinux directories (searched in that
|
||||
order.) If that is the case, then all filenames are assumed to be
|
||||
relative to that same directory, unless preceded with a slash or
|
||||
backslash.
|
||||
|
||||
All options here applies to PXELINUX, ISOLINUX and EXTLINUX as well as
|
||||
SYSLINUX unless otherwise noted. See the respective .txt files.
|
||||
The configuration file is a text file in either UNIX or DOS format,
|
||||
containing one or more of the following items, each on its own line with
|
||||
optional leading whitespace. Case is insensitive for keywords; upper
|
||||
case is used here to indicate that a word should be typed verbatim.
|
||||
|
||||
# comment
|
||||
A comment line. The whitespace after the hash mark is mandatory.
|
||||
#comment
|
||||
A comment line.
|
||||
|
||||
INCLUDE filename
|
||||
Inserts the contents of another file at this point in the
|
||||
|
BIN
config/release/3rdparty/syslinux/dos/syslinux.com
vendored
BIN
config/release/3rdparty/syslinux/dos/syslinux.com
vendored
Binary file not shown.
BIN
config/release/3rdparty/syslinux/win32/syslinux.exe
vendored
BIN
config/release/3rdparty/syslinux/win32/syslinux.exe
vendored
Binary file not shown.
Loading…
x
Reference in New Issue
Block a user