libretro/Lakka
1
0
Fork 0
mirror of https://github.com/libretro/Lakka.git synced 2024-12-02 13:18:24 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

config/release: move syslinux related files to syslinux package

Browse Source 
Signed-off-by: Stephan Raue <stephan@openelec.tv>
This commit is contained in:
Stephan Raue 2012-05-05 10:25:33 +02:00
parent d1f69783af
commit dd4755752f
31 changed files with 0 additions and 7514 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1536
config/release/3rdparty/syslinux/NEWS vendored
View File

File diff suppressed because it is too large Load Diff

34
config/release/3rdparty/syslinux/README vendored
View File

@ -1,34 +0,0 @@
See the files in the doc directory for documentation about SYSLINUX:
syslinux.txt - Usage instructions; manual.
distrib.txt - For creators of Linux distributions.
pxelinux.txt - Documentation specific to PXELINUX.
isolinux.txt - Documentation specific to ISOLINUX.
extlinux.txt - Documentation specific to EXTLINUX.
menu.txt - About the menu systems.
usbkey.txt - About using SYSLINUX on USB keys.
comboot.txt - About the extension API.
memdisk.txt - Documentation about MEMDISK.
Also see the files:
NEWS - List of changes from previous releases.
TODO - About features planned for future releases.
COPYING - For the license terms of this software.
SYSLINUX now builds in a Linux environment, using nasm. You need nasm
version 2.03 or later (2.07 or later recommended) to build SYSLINUX
from source. See http://www.nasm.us/ for information about nasm.
There is now a mailing list for SYSLINUX. See the end of syslinux.txt
for details.
SYSLINUX is:
Copyright 1994-2011 H. Peter Anvin et al - All Rights Reserved
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, Inc., 53 Temple Place Ste 330,
Boston MA 02111-1307, USA; either version 2 of the License, or
(at your option) any later version; incorporated herein by reference.

831
config/release/3rdparty/syslinux/doc/CodingStyle.txt vendored
View File

@ -1,831 +0,0 @@
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
View File

@ -1,568 +0,0 @@
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>
--

1012
config/release/3rdparty/syslinux/doc/comboot.txt vendored
View File

File diff suppressed because it is too large Load Diff

29
config/release/3rdparty/syslinux/doc/distrib.txt vendored
View File

@ -1,29 +0,0 @@
For creators of Linux distributions:
Syslinux is a notoriously hard program to debug, since it runs outside
of any operating system, and has a tendency to expose BIOS and
hardware bugs on various systems. Therefore, I would appreciate if
you would resist the temptation of recompiling the Syslinux bootloader
itself (ldlinux.asm) if at all possible. If you do that, I will have
to refer any bug reports I receive back to the respective distributor.
However, I have no such concerns about recompiling the installer
programs, and in fact, with both libc 5 and libc 6 in common use in
the Linux world today I understand if you wish to relink the
Linux-based installer against your system version of libc. Therefore
a special makefile targets "make installer" has been included with the
Syslinux distribution, starting with version 1.42.
To rebuild the installer programs *only*, starting from a freshly
untarred distribution copy of Syslinux, do:
make clean
make installer
If you want to remove all intermediate files, including the ones
obtained from assembling ldlinux.asm and which are included in the
distribution, do "make spotless".
I appreciate your assistance in this matter.
H. Peter Anvin

134
config/release/3rdparty/syslinux/doc/extlinux.txt vendored
View File

@ -1,134 +0,0 @@
EXTLINUX is a new Syslinux derivative, which boots from a Linux
ext2/ext3 filesystem.
It works the same way as SYSLINUX (see doc/syslinux.txt), with a few
slight modifications.
1. The installer is run on a *mounted* filesystem. Run the extlinux
installer on the directory in which you want extlinux installed:
extlinux --install /boot
Specify --install (-i) to install for the first time, or
--update (-U) to upgrade a previous installation.
NOTE: this doesn't have to be the root directory of a filesystem.
If /boot is a filesystem, you can do:
mkdir -p /boot/extlinux
extlinux --install /boot/extlinux
... to create a subdirectory and install extlinux in it.
/boot/extlinux is the recommended location for extlinux.
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
slash), they are relative to the root of the filesystem on which
extlinux is installed (/boot in the example above), if relative,
they are relative to the extlinux directory.
extlinux supports subdirectories, but the total path length is
limited to 511 characters.
4. EXTLINUX now supports symbolic links. However, extremely long
symbolic links might hit the pathname limit. Also, please note
that absolute symbolic links are interpreted from the root *of the
filesystem*, which might be different from how the running system
would interpret it (e.g. in the case of a separate /boot
partition.) Therefore, use relative symbolic links if at all
possible.
5. EXTLINUX now has "boot-once" support. The boot-once information is
stored in an on-disk datastructure, part of extlinux.sys, called
the "Auxillary Data Vector". The Auxilliary Data Vector is also
available to COMBOOT/COM32 modules that want to store small amounts
of information.
To set the boot-once information, do:
extlinux --once 'command' /boot/extlinux
where 'command' is any command you could enter at the Syslinux
command line. It will be executed on the next boot and then
erased.
To clear the boot-once information, do:
extlinux --clear-once /boot/extlinux
If EXTLINUX is used on a RAID-1, this is recommended, since under
certain circumstances a RAID-1 rebuild can "resurrect" the
boot-once information otherwise.
To clear the entire Auxillary Data Vector, do:
extlinux --reset-adv /boot/extlinux
This will erase all data stored in the ADV, including boot-once.
The --once, --clear-once, and --reset-adv commands can be combined
with --install or --update, if desired. The ADV is preserved
across updates, unless --reset-adv is specified.
Note that EXTLINUX installs in the filesystem partition like a
well-behaved bootloader :) Thus, it needs a master boot record in the
partition table; the mbr.bin shipped with Syslinux should work well.
To install it just do:
cat mbr.bin > /dev/XXX
... where /dev/XXX is the appropriate master device, e.g. /dev/hda,
and make sure the correct partition in set active.
If you have multiple disks in a software RAID configuration, the
preferred way to boot is:
- Create a separate RAID-1 partition for /boot. Note that the Linux
RAID-1 driver can span as many disks as you wish.
- Install the MBR on *each disk*, and mark the RAID-1 partition
active.
- Run "extlinux --raid --install /boot" to install extlinux. This
will install it on all the drives in the RAID-1 set, which means
you can boot any combination of drives in any order.
It is not required to re-run the extlinux installer after installing
new kernels. If you are using ext3 journalling, however, it might be
desirable to do so, since running the extlinux installer will flush
the log. Otherwise a dirty shutdown could cause some of the new
kernel image to still be in the log. This is a general problem for
boot loaders on journalling filesystems; it is not specific to
extlinux. The "sync" command does not flush the log on the ext3
filesystem.
The Syslinux Project boot loaders support chain loading other
operating systems via a separate module, chain.c32 (located in
com32/modules/chain.c32). To use it, specify a LABEL in the
configuration file with KERNEL chain.c32 and APPEND [hd|fd]<number>
[<partition>]
For example:
# Windows CE/ME/NT, a very dense operating system.
# Second partition (2) on the first hard disk (hd0);
# Linux would *typically* call this /dev/hda2 or /dev/sda2.
LABEL cement
KERNEL chain.c32
APPEND hd0 2
See also doc/menu.txt.

69
config/release/3rdparty/syslinux/doc/gpt.txt vendored
View File

@ -1,69 +0,0 @@
GPT boot protocol
There are two ways to boot a GPT-formatted disk on a BIOS system.
Hybrid booting, and the new GPT-only booting protocol originally
proposed by the author, and later adopted by the T13 committee in
slightly modified form.
*** Hybrid booting ***
Hybrid booting uses a standard MBR, and has bootable ("active")
partitions present, as partitions, in the GPT PMBR sector. This means
the PMBR, instead of containing only one "protective" partition (type
EE), may contain up to three partitions: a protective partition (EE)
*before* the active partition, the active partition, and a protective
partition (EE) *after* the active partition. The active partition is
limited to the first 2^32 sectors (2 TB) of the disk.
All partitions, including the active partition, should have GPT
partition entries. Thus, changing which partition is active does NOT
change the GPT partition table.
This is the only known way to boot Microsoft operating systems from a
GPT disk with BIOS firmware.
*** New protocol ***
This defines the T13-approved protocol for GPT partitions with BIOS
firmware. It maintains backwards compatibility to the extent
possible. It is implemented by the file mbr/gptmbr.bin.
The (P)MBR format is the normal PMBR specified in the UEFI
documentation, with the first 440 bytes used for the boot code. The
partition to be booted is marked by setting bit 2 in the GPT Partition
Entry Attributes field (offset 48); this bit is reserved by the UEFI
Forum for "Legacy BIOS Bootable".
-> The handover protocol
The PMBR boot code loads the first sector of the bootable partition,
and passes in DL=<disk number>, ES:DI=<pointer to $PnP>, sets EAX to
0x54504721 ("!GPT") and points DS:SI to a structure of the following
form:
Offset Size Contents
---------------------------------------------------------
0 1 0x80 (this is a bootable partition)
1 3 CHS of partition (using INT 13h geometry)
4 1 0xED (partition type: synthetic)
5 3 CHS of partition end
8 4 Partition start LBA
12 4 Partition end LBA
16 4 Length of the GPT entry
20 varies GPT partition entry
The CHS information is optional; gptmbr.bin currently does *NOT*
calculate them, and just leaves them as zero.
Bytes 0-15 matches the standard MBR handover (DS:SI points to the
partition entry), except that the information is provided
synthetically. The MBR-compatible fields are directly usable if they
are < 2 TB, otherwise these fields should contain 0xFFFFFFFF and the
OS will need to understand the GPT partition entry which follows the
MBR one. The "!GPT" magic number in EAX and the 0xED partition type
also informs the OS that the GPT partition information is present.
Syslinux 4.00 and later fully implements this protocol.

102
config/release/3rdparty/syslinux/doc/isolinux.txt vendored
View File

@ -1,102 +0,0 @@
ISOLINUX
A bootloader for Linux using ISO 9660/El Torito CD-ROMs
Copyright 1994-2008 H. Peter Anvin - All Rights Reserved
This program is provided under the terms of the GNU General Public
License, version 2 or, at your option, any later version. There is no
warranty, neither expressed nor implied, to the function of this
program. Please see the included file COPYING for details.
----------------------------------------------------------------------
ISOLINUX is a boot loader for Linux/i386 that operates off ISO 9660/El
Torito CD-ROMs in "no emulation" mode. This avoids the need to create
an "emulation disk image" with limited space (for "floppy emulation")
or compatibility problems (for "hard disk emulation".)
This documentation isn't here yet, but here is enough that you should
be able to test it out:
Make sure you have a recent enough version of mkisofs. I recommend
mkisofs 1.13 (distributed with cdrecord 1.9), but 1.12 might work as
well (not tested.)
To create an image, create a directory called "isolinux" (or, if you
prefer, "boot/isolinux") underneath the root directory of your ISO
image master file tree. Copy isolinux.bin, a config file called
"isolinux.cfg" (see syslinux.txt for details on the configuration
file), and all necessary files (kernels, initrd, display files, etc.)
into this directory, then use the following command to create your ISO
image (add additional options as appropriate, such as -J or -R):
mkisofs -o <isoimage> \
-b isolinux/isolinux.bin -c isolinux/boot.cat \
-no-emul-boot -boot-load-size 4 -boot-info-table \
<root-of-iso-tree>
(If you named the directory boot/isolinux that should of course be
-b boot/isolinux/isolinux.bin -c boot/isolinux/boot.cat.)
ISOLINUX resolves pathnames the following way:
- A pathname consists of names separated by slashes, Unix-style.
- A leading / means it searches from the root directory; otherwise the
search is from the isolinux directory (think of this as the "current
directory".)
- . and .. in pathname searches are not supported.
- The maximum length of any pathname is 255 characters.
Note that ISOLINUX only uses the "plain" ISO 9660 filenames, i.e. it
does not support Rock Ridge or Joliet filenames. It can still be used
on a disk which uses Rock Ridge and/or Joliet extensions, of course.
Under Linux, you can verify the plain filenames by mounting with the
"-o norock,nojoliet" option to the mount command. Note, however, that
ISOLINUX does support "long" (level 2) ISO 9660 plain filenames, so if
compatibility with short-names-only operating systems like MS-DOS is
not an issue, you can use the "-l" or "-iso-level 2" option to mkisofs
to generate long (up to 31 characters) plain filenames.
ISOLINUX does not support discontiguous files, interleaved mode, or
logical block and sector sizes other than 2048. This should normally
not be a problem.
ISOLINUX is by default built in two versions, one version with extra
debugging messages enabled. If you are having problems with ISOLINUX,
I would greatly appreciate if you could try out the debugging version
(isolinux-debug.bin) and let me know what it reports. The debugging
version does not include hybrid mode support (see below.)
++++ NOTE ON THE CONFIG FILE DIRECTORY ++++
ISOLINUX will search for the config file directory in the order
/boot/isolinux, /isolinux, /. The first directory that exists is
used, even if it contains no files. Therefore, please make sure that
these directories don't exist if you don't want ISOLINUX to use them.
++++ HYBRID CD-ROM/HARD DISK MODE ++++
Starting in version 3.72, ISOLINUX supports a "hybrid mode" which can
be booted from either CD-ROM or from a device which BIOS considers a
hard disk or ZIP disk, e.g. a USB key or similar.
To enable this mode, the .iso image should be postprocessed with the
"isohybrid" script from the utils directory:
isohybrid filename.iso
This script creates the necessary additional information to be able to
boot in hybrid mode. It also pads out the image to an even multiple
of 1 MB.
This image can then be copied using any raw disk writing tool (on Unix
systems, typically "dd" or "cat") to a USB disk, or written to a
CD-ROM using standard CD burning tools.
The ISO 9660 filesystem is encapsulated in a partition (which starts
at offset zero, which may confuse some systems.) This makes it
possible for the operating system, once booted, to use the remainder
of the device for persistent storage by creating a second partition.

85
config/release/3rdparty/syslinux/doc/keytab-lilo.txt vendored
View File

@ -1,85 +0,0 @@
This is the documentation for the keytab-lilo.pl program. It was
taken verbatim from the LILO-20 README file; only this header was
added.
LILO program code, documentation and auxiliary programs are
Copyright 1992-1997 Werner Almesberger.
All rights reserved.
Redistribution and use in source and binary forms of parts of or the
whole original or derived work are permitted provided that the
original work is properly attributed to the author. The name of the
author may not be used to endorse or promote products derived from
this software without specific prior written permission. This work
is provided "as is" and without any express or implied warranties.
To use a LILO keyboard table with Syslinux, specify the KBDMAP command
in syslinux.cfg, for example:
kbdmap de.ktl
============================================================================
Keyboard translation
--------------------
The PC keyboard emits so-called scan codes, which are basically key
numbers. The BIOS then translates those scan codes to the character codes
of the characters printed on the key-caps. By default, the BIOS normally
assumes that the keyboard has a US layout. Once an operating system is
loaded, this operating system can use a different mapping.
At boot time, LILO only has access to the basic services provided by the
BIOS and therefore receives the character codes for an US keyboard. It
provides a simple mechanism to re-map the character codes to what is
appropriate for the actual layout.*
* The current mechanism isn't perfect, because it sits on top of the
scan code to character code translation performed by the BIOS. This
means that key combinations that don't produce any useful character on
the US keyboard will be ignored by LILO. The advantage of this approach
is its simplicity.
Compiling keyboard translation tables
- - - - - - - - - - - - - - - - - - -
LILO obtains layout information from the keyboard translation tables Linux
uses for the text console. They are usually stored in
/usr/lib/kbd/keytables. LILO comes with a program keytab-lilo.pl that reads
those tables and generates a table suitable for use by the map installer.
keytab-lilo.pl invokes the program loadkeys to print the tables in a format
that is easy to parse.*
* On some systems, only root can execute loadkeys. It is then necessary
to run keytab-lilo.pl as root too.
keytab-lilo.pl is used as follows:
keytab-lilo.pl [ -p <old_code>=<new_code> ] ...
[<path>]<default_layout>[.<extension>] ]
[<path>]<kbd_layout>[.<extension>] ]
-p <old_code>=<new_code>
Specifies corrections ("patches") to the mapping obtained from the
translation table files. E.g. if pressing the upper case "A" should
yield an at sign, -p 65=64 would be used. The -p option can be
repeated any number of times. The codes can also be given as
hexadecimal or as octal numbers if they are prefixed with 0x or 0,
respectively.
<path> The directory in which the file resides. The default path is
/usr/lib/kbd/keytables.
<extension> Usually the trailing .map, which is automatically added if
the file name doesn't contain dots.
<default_layout> Is the layout which specifies the translation by the
BIOS. If none is specified, us is assumed.
<kbd_layout> Is the actual layout of the keyboard.
keytab-lilo.pl writes the resulting translation table as a binary string to
standard output. Such tables can be stored anywhere with any name, but the
suggested naming convention is /boot/<kbd>.ktl ("Keyboard Table for Lilo"),
where <kbd> is the name of the keyboard layout.
Example:
keytab-lilo.pl de >/boot/de.ktl

26
config/release/3rdparty/syslinux/doc/mboot.txt vendored
View File

@ -1,26 +0,0 @@
mboot.c32
---------
mboot.c32 is a 32-bit comboot module that allows Syslinux and its
variants to load and boot kernels that use the Multiboot standard
(e.g. the Xen virtual machine monitor, and the Fiasco and GNU Mach
microkernels).
To load a multiboot kernel and modules in Syslinux, put mboot.c32 (from
com32/modules) in the boot directory, and load it as the "kernel" in the
configuration file. The command-line to pass to mboot.c32 is the kernel
command-line, followed by all the module command lines, separated with
'---'. For example, to load a Xen VMM, xenlinux and an initrd:
DEFAULT mboot.c32 xen.gz dom0_mem=15000 nosmp noacpi --- linux.gz console=tty0 root=/dev/hda1 --- initrd.img
or, as a choice in a menu:
LABEL Xen
KERNEL mboot.c32
APPEND xen.gz dom0_mem=15000 nosmp noacpi --- linux.gz console=tty0 root=/dev/hda1 --- initrd.img
mboot.c32 requires version 2.12 or later of Syslinux.
Tim Deegan, May 2005

298
config/release/3rdparty/syslinux/doc/memdisk.txt vendored
View File

@ -1,298 +0,0 @@
[This documentation is rather crufty at the moment.]
MEMDISK is meant to allow booting legacy operating systems via PXE,
and as a workaround for BIOSes where ISOLINUX image support doesn't
work.
MEMDISK simulates a disk by claiming a chunk of high memory for the
disk and a (very small - 2K typical) chunk of low (DOS) memory for the
driver itself, then hooking the INT 13h (disk driver) and INT 15h
(memory query) BIOS interrupts.
MEMDISK allows for an OS to detect the MEMDISK instance. (See the
"Additional technical information" section below.)
To use it, type on the Syslinux command line:
memdisk initrd=diskimg.img
... where diskimg.img is the disk image you want to boot from.
[Obviously, the memdisk binary as well as your disk image file need to
be present in the boot image directory.]
... or add to your syslinux.cfg/pxelinux.cfg/isolinux.cfg something like:
label dos
kernel memdisk
append initrd=dosboot.img
Note the following:
a) The disk image can be uncompressed or compressed with gzip or zip.
b) If the disk image is less than 4,194,304 bytes (4096K, 4 MB) it is
assumed to be a floppy image and MEMDISK will try to guess its
geometry based on the size of the file. MEMDISK recognizes all the
standard floppy sizes as well as common extended formats:
163,840 bytes (160K) c=40 h=1 s=8 5.25" SSSD
184,320 bytes (180K) c=40 h=1 s=9 5.25" SSSD
327,680 bytes (320K) c=40 h=2 s=8 5.25" DSDD
368,640 bytes (360K) c=40 h=2 s=9 5.25" DSDD
655,360 bytes (640K) c=80 h=2 s=8 3.5" DSDD
737,280 bytes (720K) c=80 h=2 s=9 3.5" DSDD
1,222,800 bytes (1200K) c=80 h=2 s=15 5.25" DSHD
1,474,560 bytes (1440K) c=80 h=2 s=18 3.5" DSHD
1,638,400 bytes (1600K) c=80 h=2 s=20 3.5" DSHD (extended)
1,720,320 bytes (1680K) c=80 h=2 s=21 3.5" DSHD (extended)
1,763,328 bytes (1722K) c=82 h=2 s=21 3.5" DSHD (extended)
1,784,832 bytes (1743K) c=83 h=2 s=21 3.5" DSHD (extended)
1,802,240 bytes (1760K) c=80 h=2 s=22 3.5" DSHD (extended)
1,884,160 bytes (1840K) c=80 h=2 s=23 3.5" DSHD (extended)
1,966,080 bytes (1920K) c=80 h=2 s=24 3.5" DSHD (extended)
2,949,120 bytes (2880K) c=80 h=2 s=36 3.5" DSED
3,194,880 bytes (3120K) c=80 h=2 s=39 3.5" DSED (extended)
3,276,800 bytes (3200K) c=80 h=2 s=40 3.5" DSED (extended)
3,604,480 bytes (3520K) c=80 h=2 s=44 3.5" DSED (extended)
3,932,160 bytes (3840K) c=80 h=2 s=48 3.5" DSED (extended)
A small perl script is included in the MEMDISK directory which can
determine the geometry that MEMDISK would select for other sizes;
in general MEMDISK will correctly detect most physical extended
formats used, with 80 cylinders or slightly more.
If the image is 4 MB or larger, it is assumed to be a hard disk
image, and should typically have an MBR and a partition table. It
may optionally have a DOSEMU geometry header; in which case the
header is used to determine the C/H/S geometry of the disk.
Otherwise, the geometry is determined by examining the partition
table, so the entire image should be partitioned for proper
operation (it may be divided between multiple partitions, however.)
You can also specify the geometry manually with the following command
line options:
c=# Specify number of cylinders (max 1024[*])
h=# Specify number of heads (max 256[*])
s=# Specify number of sectors (max 63)
floppy[=#] The image is a floppy image[**]
harddisk[=#] The image is a hard disk image[**]
iso The image is an El Torito ISO9660 image (drive 0xE0)
# represents a decimal number.
[*] MS-DOS only allows max 255 heads, and only allows 255 cylinders
on floppy disks.
[**] Normally MEMDISK emulates the first floppy or hard disk. This
can be overridden by specifying an index, e.g. floppy=1 will
simulate fd1 (B:). This may not work on all operating systems
or BIOSes.
c) The disk is normally writable (although, of course, there is
nothing backing it up, so it only lasts until reset.) If you want,
you can mimic a write-protected disk by specifying the command line
option:
ro Disk is readonly
d) MEMDISK normally uses the BIOS "INT 15h mover" API to access high
memory. This is well-behaved with extended memory managers which load
later. Unfortunately it appears that the "DOS boot disk" from
WinME/XP *deliberately* crash the system when this API is invoked.
The following command-line options tells MEMDISK to enter protected
mode directly, whenever possible:
raw Use raw access to protected mode memory.
bigraw Use raw access to protected mode memory, and leave the
CPU in "big real" mode afterwards.
int Use plain INT 15h access to protected memory. This assumes
that anything which hooks INT 15h knows what it is doing.
safeint Use INT 15h access to protected memory, but invoke
INT 15h the way it was *before* MEMDISK was loaded.
This is the default since version 3.73.
e) MEMDISK by default supports EDD/EBIOS on hard disks, but not on
floppy disks. This can be controlled with the options:
edd Enable EDD/EBIOS
noedd Disable EDD/EBIOS
f) The following option can be used to pause to view the messages:
pause Wait for a keypress right before booting
g) The following option can be used to set the real-mode stack size.
The default is 512 bytes, but if there is a failure it might be
interesting to set it to something larger:
stack=size Set the stack to "size" bytes
h) Some systems without a floppy drive have been known to have
problems with floppy images. To avoid that those problems, first
of all make sure you don't have a floppy drive configured on the
BIOS screen. If there is no option to configure that, or that
doesn't work, you can use the option:
nopass Hide all real drives of the same type (floppy or hard disk)
nopassany Hide all real drives (floppy and hard disk)
i) The following standard Linux option will mark memory as reserved.
Please note that the Syslinux core already loads MEMDISK and its
initrd below this point:
mem=size Mark available memory above this point as Reserved.
Some interesting things to note:
If you're using MEMDISK to boot DOS from a CD-ROM (using ISOLINUX),
you might find the generic El Torito CD-ROM driver by Gary Tong and
Bart Lagerweij useful. It is now included with the Syslinux
distribution, in the dosutil directory. See the file
dosutil/eltorito.txt for more information.
Similarly, if you're booting DOS over the network using PXELINUX, you
can use the "keeppxe" option and use the generic PXE (UNDI) NDIS
network driver, which is part of the PROBOOT.EXE distribution from
Intel:
http://www.intel.com/support/network/adapter/1000/software.htm
Additional technical information:
Starting with version 2.08, MEMDISK now supports an installation check
API. This works as follows:
EAX = 454D08xxh ("ME") (08h = parameter query)
ECX = 444Dxxxxh ("MD")
EDX = 5349xxnnh ("IS") (nn = drive #)
EBX = 3F4Bxxxxh ("K?")
INT 13h
If drive nn is a MEMDISK, the registers will contain:
EAX = 4D21xxxxh ("!M")
ECX = 4D45xxxxh ("EM")
EDX = 4944xxxxh ("DI")
EBX = 4B53xxxxh ("SK")
ES:DI -> MEMDISK info structures
The low parts of EAX/ECX/EDX/EBX have the normal return values for INT
13h, AH=08h, i.e. information of the disk geometry etc.
See Ralf Brown's interrupt list,
http://www.cs.cmu.edu/afs/cs.cmu.edu/user/ralf/pub/WWW/files.html or
http://www.ctyme.com/rbrown.htm, for a detailed description.
The MEMDISK info structure currently contains:
[ES:DI] word Total size of structure (currently 30 bytes)
[ES:DI+2] byte MEMDISK minor version
[ES:DI+3] byte MEMDISK major version
[ES:DI+4] dword Pointer to MEMDISK data in high memory
[ES:DI+8] dword Size of MEMDISK data in sectors
[ES:DI+12] 16:16 Far pointer to command line
[ES:DI+16] 16:16 Old INT 13h pointer
[ES:DI+20] 16:16 Old INT 15h pointer
[ES:DI+24] word Amount of DOS memory before MEMDISK loaded
[ES:DI+26] byte Boot loader ID
[ES:DI+27] byte Sector size as a power of 2
(If zero, assume 512-byte sectors)
[ES:DI+28] word If nonzero, offset (vs ES) to installed DPT
This pointer+16 contains the original INT 1Eh
Sizes of this structure:
3.71+ 30 bytes Added DPT pointer
3.00-3.70 27 bytes Added boot loader ID
pre-3.00 26 bytes
In addition, the following fields are available at [ES:0]:
[ES:0] word Offset of INT 13h routine (segment == ES)
[ES:2] word Offset of INT 15h routine (segment == ES)
The program mdiskchk.c in the sample directory is an example on how
this API can be used.
The following code can be used to "disable" MEMDISK. Note that it
does not free the handler in DOS memory, and that running this from
DOS will probably crash your machine (DOS doesn't like drives suddenly
disappearing from underneath.) This is also not necessarily the best
method for this.
mov eax, 454D0800h
mov ecx, 444D0000h
mov edx, 53490000h
mov dl,drive_number
mov ebx, 3F4B0000h
int 13h
shr eax, 16
cmp ax, 4D21h
jne not_memdisk
shr ecx, 16
cmp cx, 4D45h
jne not_memdisk
shr edx, 16
cmp dx, 4944h
jne not_memdisk
shr ebx, 16
cmp bx, 4B53h
jne not_memdisk
cli
mov bx,[es:0] ; INT 13h handler offset
mov eax,[es:di+16] ; Old INT 13h handler
mov byte [es:bx], 0EAh ; FAR JMP
mov [es:bx+1], eax
mov bx,[es:2] ; INT 15h handler offset
mov eax,[es:di+20] ; Old INT 15h handler
mov byte [es:bx], 0EAh ; FAR JMP
mov [es:bx+1], eax
sti
MEMDISK supports the Win9x "safe hook" structure for OS detection.
(See "Safe Master Boot Record INT 13h Hook Routines," available at
http://www.osronline.com/ddkx/w98ddk/storage_5l6g.htm as of
December 7th, 2009.) An OS driver can take a look at the INTerrupt table
and try to walk along the chain of those hooks that implement the "safe hook"
structure. For each hook discovered, a vendor can be identified and the OS
driver can take appropriate action. The OS driver can mark the "flags" field
of the "safe hook" to indicate that the driver has reviewed it already. This
prevents accidental re-detection, for example.
MEMDISK adds one additional extension field to the "safe hook" structure, a
pointer to a special MEMDISK structure called the "mBFT." The mBFT is the
"MEMDISK Boot Firmware Table" (akin to the iSCSI iBFT and the AoE aBFT). An
OS driver looking at MEMDISK's "safe hook" should know that this field will
be present based on the fact that MEMDISK is the vendor identifier.
The mBFT is little more than an ACPI table to prefix MEMDISK's traditional
MEMDISK info structure (the "MDI"). The ACPI table's details are:
OEM ID. . . .: MEMDSK
OEM Table ID : Syslinux
There is a 1-byte checksum field which covers the length of the mBFT all
the way through to the end of the MEMDISK info structure.
There is also a physical pointer to the "safe hook" structure associated
with the MEMDISK instance. An OS driver might use the following logic:
1. Walk INT 13h "safe hook" chain as far as possible, marking hooks as
having been reviewed. For MEMDISK hooks, the driver then follows the
pointer to the mBFT and gathers the RAM disk details from the included
MDI.
2. The OS driver scans low memory for valid mBFTs. MEMDISK instances that
have been "disconnected" from the INT 13h "safe hook" chain can be thus
discovered. Looking at their associated "safe hook" structure will
reveal if they were indeed reviewed by the previous stage.

585
config/release/3rdparty/syslinux/doc/menu.txt vendored
View File

@ -1,585 +0,0 @@
There are two menu systems included with Syslinux, the advanced menu
system, and the simple menu system.
+++ THE ADVANCED MENU SYSTEM +++
The advanced menu system, written by Murali Krishnan Ganapathy, is
located in the menu/ subdirectly. It allows the user to create
hierarchial submenus, dynamic options, checkboxes, and just about
anything you want. It requires that the menu is compiled from a
simple C file, see menu/simple.c and menu/complex.c for examples.
The advanced menu system doesn't support serial console at this time.
See menu/README for more information.
+++ THE SIMPLE MENU SYSTEM +++
The simple menu system is a single module located at
com32/modules/vesamenu.c32 (graphical) or com32/modules/menu.c32 (text
mode only). It uses the same configuration file as the regular
Syslinux command line, and displays all the LABEL statements.
To use the menu system, simply make sure [vesa]menu.c32 is in the
appropriate location for your boot medium (the same directory as the
configuration file for SYSLINUX, EXTLINUX and ISOLINUX, and the same
directory as pxelinux.0 for PXELINUX), and put the following options
in your configuration file:
UI menu.c32
There are a few menu additions to the configuration file, all starting
with the keywords MENU or TEXT; like the rest of the Syslinux config
file language, it is case insensitive:
MENU TITLE title
Give the menu a title. The title is presented at the top of
the menu.
MENU HIDDEN
Do not display the actual menu unless the user presses a key.
All that is displayed is a timeout message.
MENU HIDDENKEY key[,key...] command...
If they key used to interrupt MENU HIDDEN is <key>, then
execute the specified command instead of displaying the menu.
Currently, the following key names are recognized:
Backspace, Tab, Enter, Esc, Space, F1..F12, Up, Down, Left,
Right, PgUp, PgDn, Home, End, Insert, Delete
... in addition to all single characters plus the syntax ^X
for Ctrl-X. Note that single characters are treated as case
sensitive, so a different command can be bound to "A" than
"a". One can bind the same command to multiple keys by giving
a comma-separated list of keys:
menu hiddenkey A,a key_a_command
MENU CLEAR
Clear the screen when exiting the menu, instead of leaving the
menu displayed. For vesamenu, this means the graphical
background is still displayed without the menu itself for as
long as the screen remains in graphics mode.
MENU SHIFTKEY
Exit the menu system immediately unless either the Shift or Alt
key is pressed, or Caps Lock or Scroll Lock is set.
MENU SEPARATOR
Insert an empty line in the menu.
MENU LABEL label
(Only valid after a LABEL statement.)
Changes the label displayed for a specific entry. This allows
you to have a label that isn't suitable for the command line,
for example:
# Soft Cap Linux
LABEL softcap
MENU LABEL Soft Cap ^Linux 9.6.36
KERNEL softcap-9.6.36.bzi
APPEND whatever
# A very dense operating system
LABEL brick
MENU LABEL ^Windows CE/ME/NT
KERNEL chain.c32
APPEND hd0 2
The ^ symbol in a MENU LABEL statement defines a hotkey.
The hotkey will be highlighted in the menu and will move the
menu cursor immediately to that entry.
Reusing hotkeys is disallowed, subsequent entries will not be
highlighted, and will not work.
Keep in mind that the LABELs, not MENU LABELs, must be unique,
or odd things will happen to the command-line.
MENU INDENT count
(Only valid after a LABEL statement.)
Will add "count" spaces in front of the displayed menu entry.
MENU DISABLE
(Only valid after a LABEL statement.)
Makes the entry unselectable. This allows you to make a
section in your menu with different options below it.
for example:
# Entries for network boots
LABEL -
MENU LABEL Network:
MENU DISABLE
# Soft Cap Linux
LABEL softcap
MENU LABEL Soft Cap ^Linux 9.6.36
MENU INDENT 1
KERNEL softcap-9.6.36.bzi
APPEND whatever
# Dos 6.22
LABEL dos
MENU LABEL ^Dos 6.22
MENU INDENT 1
KERNEL memdisk
APPEND initrd=dos622.imz
# Separator
MENU SEPARATOR
# Entries for local boots
LABEL -
MENU LABEL Local:
MENU DISABLE
# Windows 2000
LABEL w2k
MENU LABEL ^Windows 2000
MENU INDENT 1
KERNEL chain.c32
APPEND hd0 1
# Windows XP
LABEL xp
MENU LABEL Windows ^XP
MENU INDENT 1
KERNEL chain.c32
APPEND hd0 2
MENU HIDE
(Only valid after a LABEL statement.)
Suppresses a particular LABEL entry from the menu.
MENU DEFAULT
(Only valid after a LABEL statement.)
Indicates that this entry should be the default for this
particular submenu. See also the DEFAULT directive below.
TEXT HELP
Help text ...
... which can span multiple lines
ENDTEXT
(Only valid after a LABEL statement.)
Specifies a help text that should be displayed when a particular
selection is highlighted.
MENU PASSWD passwd
(Only valid after a LABEL statement.)
Sets a password on this menu entry. "passwd" can be either a
cleartext password or a password encrypted with one of the
following algorithms:
MD5 (Signature: $1$)
SHA-1 (Signature: $4$)
SHA-2-256 (Signature: $5$)
SHA-2-512 (Signature: $6$)
Use the included Perl scripts "sha1pass" or "md5pass" to
encrypt passwords. MD5 passwords are compatible with most
Unix password file utilities; SHA-1 passwords are probably
unique to Syslinux; SHA-2 passwords are compatible with very
recent Linux distributions. Obviously, if you don't encrypt
your passwords they will not be very secure at all.
If you are using passwords, you want to make sure you also use
the settings "NOESCAPE 1", "PROMPT 0", and either set
"ALLOWOPTIONS 0" or use a master password (see below.)
If passwd is an empty string, this menu entry can only be
unlocked with the master password.
MENU MASTER PASSWD passwd
Sets a master password. This password can be used to boot any
menu entry, and is required for the [Tab] and [Esc] keys to
work.
MENU RESOLUTION height width
Requests a specific screen resolution when in graphics mode.
The default is "640 480" corresponding to a resolution of
640x480 pixels, which all VGA-compatible monitors should be
able to display.
If the selected resolution is unavailable, the text mode menu
is displayed instead.
MENU BACKGROUND background
For vesamenu.c32, sets the background image. The background
can either be a color (see MENU COLOR) or the name of an image
file, which should be the size of the screen (normally 640x480
pixels, but see MENU RESOLUTION) and either in PNG, JPEG or
LSS16 format.
MENU BEGIN [tagname]
MENU END
Begin/end a submenu. The entries between MENU BEGIN and MENU
END form a submenu, which is marked with a > mark on the right
hand of the screen. Submenus inherit the properties of their
parent menus, but can override them, and can thus have their
own backgrounds, master passwords, titles, timeouts, messages
and so forth.
MENU GOTO tagname
(Only valid after a LABEL statement.)
This label will transfer to the named submenu instead of
booting anything. To transfer to the top-level menu, specify
"menu goto .top".
MENU EXIT [tagname]
(Only valid after a label statement inside MENU BEGIN ...
MENU END)
Exit to the next higher menu, or, if tagname is specified, to
the named menu.
MENU QUIT
(Only valid after a LABEL statement.)
This label quits the menu system.
WARNING: if MENU MASTER PASSWD or ALLOWOPTIONS 0 is set, this
will still allow exiting to the CLI; however, a separate MENU
PASSWD can of course be set for this label.
MENU START
(Only valid inside MENU BEGIN ... MENU END)
Indicates that the menu system should start at the menu being
defined instead of at the top-level menu. See also the
DEFAULT directive below.
DEFAULT label
Set the global default. If "label" points into a submenu,
that menu becomes the start menu; in other words, this
directive has the same effect as both MENU DEFAULT and MENU
START.
For backwards compatibility with earlier versions of Syslinux,
this directive is ignored unless the configuration file also
contains a UI directive.
Note: the CLI accepts options after the label, or even a
non-label. The menu system does not support that.
MENU SAVE
MENU NOSAVE
Remember the last entry selected and make that the default for
the next boot. A password-protected menu entry is *not*
saved. This requires the ADV data storage mechanism, which is
currently only implemented for EXTLINUX, although the other
Syslinux derivatives will accept the command (and ignore it.)
NOTE: MENU SAVE stores the LABEL tag of the selected entry;
this mechanism therefore relies on LABEL tags being unique.
On the other hand, it handles changes in the configuration
file gracefully.
NOTE: In software RAID-1 setups MENU SAVE only stores the
default label on the actual boot disk. This may lead to
inconsistent reads from the array, or unexpectedly change the
default label after array resynchronization or disk failure.
The MENU SAVE information can be fully cleared with
"extlinux --reset-adv <bootdir>".
A MENU SAVE or MENU NOSAVE at the top of a (sub)menu affects
all entries underneath that (sub)menu except those that in
turn have MENU SAVE or MENU NOSAVE declared. This can be used
to only save certain entires when selected.
INCLUDE filename [tagname]
MENU INCLUDE filename [tagname]
Include the contents of the configuration file filename at
this point.
In the case of MENU INCLUDE, the included data is only seen by
the menu system; the core syslinux code does not parse this
command, so any labels defined in it are unavailable.
If a tagname is included, the whole file is considered to have
been bracketed with a MENU BEGIN tagname ... MENU END pair,
and will therefore show up as a submenu.
MENU AUTOBOOT message
Replaces the message "Automatic boot in # second{,s}...". The
symbol # is replaced with the number of seconds remaining.
The syntax "{singular,[dual,]plural}" can be used to conjugate
appropriately.
MENU TABMSG message
Replaces the message "Press [Tab] to edit options".
MENU NOTABMSG message
Takes the place of the TABMSG message if option editing is
disabled. Defaults to blank.
MENU PASSPROMPT message
Replaces the message "Password required".
MENU COLOR element ansi foreground background shadow
Sets the color of element "element" to the specified color
sequence:
screen Rest of the screen
border Border area
title Title bar
unsel Unselected menu item
hotkey Unselected hotkey
sel Selection bar
hotsel Selected hotkey
disabled Disabled menu item
scrollbar Scroll bar
tabmsg Press [Tab] message
cmdmark Command line marker
cmdline Command line
pwdborder Password box border
pwdheader Password box header
pwdentry Password box contents
timeout_msg Timeout message
timeout Timeout counter
help Help text
msgXX Message (F-key) file attribute XX
... where XX is two hexadecimal digits (the "plain text" is 07).
"ansi" is a sequence of semicolon-separated ECMA-48 Set
Graphics Rendition (<ESC>[m) sequences:
0 reset all attributes to their defaults
1 set bold
4 set underscore (simulated with color on a color display)
5 set blink
7 set reverse video
22 set normal intensity
24 underline off
25 blink off
27 reverse video off
30 set black foreground
31 set red foreground
32 set green foreground
33 set brown foreground
34 set blue foreground
35 set magenta foreground
36 set cyan foreground
37 set white foreground
38 set underscore on, set default foreground color
39 set underscore off, set default foreground color
40 set black background
41 set red background
42 set green background
43 set brown background
44 set blue background
45 set magenta background
46 set cyan background
47 set white background
49 set default background color
These are used (a) in text mode, and (b) on the serial
console.
"foreground" and "background" are color codes in #AARRGGBB
notation, where AA RR GG BB are hexadecimal digits for alpha
(opacity), red, green and blue, respectively. #00000000
represents fully transparent, and #ffffffff represents opaque
white.
"shadow" controls the handling of the graphical console text
shadow. Permitted values are "none" (no shadowing), "std" or
"standard" (standard shadowing - foreground pixels are
raised), "all" (both background and foreground raised), and
"rev" or "reverse" (background pixels are raised.)
If any field is set to "*" or omitted (at the end of the line)
then that field is left unchanged.
The current defaults are:
menu color screen 37;40 #80ffffff #00000000 std
menu color border 30;44 #40000000 #00000000 std
menu color title 1;36;44 #c00090f0 #00000000 std
menu color unsel 37;44 #90ffffff #00000000 std
menu color hotkey 1;37;44 #ffffffff #00000000 std
menu color sel 7;37;40 #e0000000 #20ff8000 all
menu color hotsel 1;7;37;40 #e0400000 #20ff8000 all
menu color disabled 1;30;44 #60cccccc #00000000 std
menu color scrollbar 30;44 #40000000 #00000000 std
menu color tabmsg 31;40 #90ffff00 #00000000 std
menu color cmdmark 1;36;40 #c000ffff #00000000 std
menu color cmdline 37;40 #c0ffffff #00000000 std
menu color pwdborder 30;47 #80ffffff #20ffffff std
menu color pwdheader 31;47 #80ff8080 #20ffffff std
menu color pwdentry 30;47 #80ffffff #20ffffff std
menu color timeout_msg 37;40 #80ffffff #00000000 std
menu color timeout 1;37;40 #c0ffffff #00000000 std
menu color help 37;40 #c0ffffff #00000000 std
menu color msg07 37;40 #90ffffff #00000000 std
MENU MSGCOLOR fg_filter bg_filter shadow
Sets *all* the msgXX colors to a color scheme derived from the
fg_filter and bg_filter values. Background color zero is
always treated as transparent. The default corresponds to:
menu msgcolor #90ffffff #80ffffff std
This directive should come before any directive that
customizes individual msgXX colors.
MENU WIDTH 80
MENU MARGIN 10
MENU PASSWORDMARGIN 3
MENU ROWS 12
MENU TABMSGROW 18
MENU CMDLINEROW 18
MENU ENDROW -1
MENU PASSWORDROW 11
MENU TIMEOUTROW 20
MENU HELPMSGROW 22
MENU HELPMSGENDROW -1
MENU HIDDENROW -2
MENU HSHIFT 0
MENU VSHIFT 0
These options control the layout of the menu on the screen.
The values above are the defaults.
A negative value is relative to the calculated length of the
screen (25 for text mode, 28 for VESA graphics mode.)
F1 textfile [background]
...
F12 textfile [background]
Displays full-screen help (also available at the command line.)
The same control code sequences as in the command line
interface are supported, although some are ignored.
Additionally, a optional second argument allows a different
background image (see MENU BACKGROUND for supported formats)
to be displayed.
MENU HELP textfile [background]
Creates a menu entry which, when selected, displays
full-screen help in the same way as the F-key help.
The menu system honours the TIMEOUT command; if TIMEOUT is specified
it will execute the ONTIMEOUT command if one exists, otherwise it will
pick the default menu option. WARNING: the timeout action will bypass
password protection even if one is set for the specified or default
entry!
Normally, the user can press [Tab] to edit the menu entry, and [Esc]
to return to the Syslinux command line. However, if the configuration
file specifies ALLOWOPTIONS 0, these keys will be disabled, and if
MENU MASTER PASSWD is set, they require the master password.
The simple menu system supports serial console, using the normal
SERIAL directive. However, it can be quite slow over a slow serial
link; you probably want to set your baudrate to 38400 or higher if
possible. It requires a Linux/VT220/ANSI-compatible terminal on the
other end.
+++ USING AN ALTERNATE CONFIGURATION FILE +++
It is also possible to load a secondary configuration file, to get to
another menu. To do that, invoke menu.c32 with the name of the
secondary configuration file.
LABEL othermenu
MENU LABEL Another Menu
KERNEL menu.c32
APPEND othermenu.conf
If you specify more than one file, they will all be read, in the order
specified. The dummy filename ~ (tilde) is replaced with the filename
of the main configuration file.
# The file graphics.conf contains common color and layout commands for
# all menus.
LABEL othermenu
MENU LABEL Another Menu
KERNEL vesamenu.c32
APPEND graphics.conf othermenu.conf
# Return to the main menu
LABEL mainmenu
MENU LABEL Return to Main Menu
KERNEL vesamenu.c32
APPEND graphics.conf ~
See also the MENU INCLUDE directive above.

432
config/release/3rdparty/syslinux/doc/pxelinux.txt vendored
View File

@ -1,432 +0,0 @@
PXELINUX
A bootloader for Linux using the PXE network booting protocol
Copyright 1994-2008 H. Peter Anvin - All Rights Reserved
This program is provided under the terms of the GNU General Public
License, version 2 or, at your option, any later version. There is no
warranty, neither expressed nor implied, to the function of this
program. Please see the included file COPYING for details.
----------------------------------------------------------------------
PXELINUX is a Syslinux derivative, for booting Linux off a network
server, using a network ROM conforming to the Intel PXE (Pre-Execution
Environment) specification. PXELINUX is *not* a program that is
intended to be flashed or burned into a PROM on the network card; if
you want that, check out Etherboot (http://www.etherboot.org/).
Etherboot 5.4 or later can also be used to create a PXE-compliant boot
PROM for many network cards.
++++ HOW TO CONFIGURE PXELINUX ++++
PXELINUX operates in many ways like SYSLINUX. If you are not familiar
with SYSLINUX, read syslinux.txt first, since this documentation only
explains the differences.
On the TFTP server, create the directory "/tftpboot", and copy the
following files to it:
pxelinux.0 - from the Syslinux distribution
any kernel or initrd images you want to boot
Finally, create the directory "/tftpboot/pxelinux.cfg". The
configuration file (equivalent of syslinux.cfg -- see syslinux.txt for
the options here) will live in this directory. Because more than one
system may be booted from the same server, the configuration file name
depends on the IP address of the booting machine. PXELINUX will
search for its config file on the boot server in the following way:
First, it will search for the config file using the client UUID, if
one is provided by the PXE stack (note, some BIOSes don't have a
valid UUID, and you might end up with something like all 1's.) This is
in the standard UUID format using lower case hexadecimal digits, e.g.
b8945908-d6a6-41a9-611d-74a6ab80b83d.
Next, it will search for the config file using the hardware type
(using its ARP type code) and address, all in lower case hexadecimal
with dash separators; for example, for an Ethernet (ARP type 1)
with address 88:99:AA:BB:CC:DD it would search for the filename
01-88-99-aa-bb-cc-dd.
Next, it will search for the config file using its own IP address
in upper case hexadecimal, e.g. 192.0.2.91 -> C000025B
(you can use the included progam "gethostip" to compute the
hexadecimal IP address for any host.)
If that file is not found, it will remove one hex digit and try
again. Ultimately, it will try looking for a file named "default"
(in lower case).
As an example, if the boot file name is /mybootdir/pxelinux.0, the
UUID is b8945908-d6a6-41a9-611d-74a6ab80b83d, the Ethernet MAC
address is 88:99:AA:BB:CC:DD and the IP address 192.0.2.91, it will
try:
/mybootdir/pxelinux.cfg/b8945908-d6a6-41a9-611d-74a6ab80b83d
/mybootdir/pxelinux.cfg/01-88-99-aa-bb-cc-dd
/mybootdir/pxelinux.cfg/C000025B
/mybootdir/pxelinux.cfg/C000025
/mybootdir/pxelinux.cfg/C00002
/mybootdir/pxelinux.cfg/C0000
/mybootdir/pxelinux.cfg/C000
/mybootdir/pxelinux.cfg/C00
/mybootdir/pxelinux.cfg/C0
/mybootdir/pxelinux.cfg/C
/mybootdir/pxelinux.cfg/default
... in that order.
Note that all filename references are relative to the directory
pxelinux.0 lives in. PXELINUX generally requires that filenames
(including any relative path) are 127 characters or shorter in length.
Starting in release 3.20, PXELINUX will no longer apply a built-in
default if it cannot find any configuration file at all; instead it
will reboot after the timeout interval has expired. This keeps a
machine from getting stuck indefinitely due to a boot server failure.
Starting in release 3.50, PXELINUX displays network information at
the boot prompt pressing <Ctrl-N>.
PXELINUX does not support MTFTP, and I have no plans of doing so, as
MTFTP is inherently broken for files more than 65535 packets (about
92 MB) in size. It is of course possible to use MTFTP for the initial
boot, if you have such a setup. MTFTP server setup is beyond the
scope of this document.
++++ gPXE-ENHANCED VARIANTS ++++
gPXE can be used to enhance PXELINUX's functionality to also include
HTTP transfers, greatly increasing load speed and allowing for standard
HTTP scripts to present PXELINUX's configuration file. pxelinux.0 is
the plain variant. gpxelinux.0 (included as of 3.70) is gPXE's
undionly.kkpxe, pxelinux.0 and a script to run pxelinux.0. gpxelinuxk.0
(included as of 4.04) is gPXE's undionly.kpxe, pxelinux.0 and a script
to run pxelinux.0. gpxelinuxk.0 should only be used with systems that
are incompatible with gpxelinux.0 as it prevents certain functionality
from working (LOCALBOOT with a type not equal to -1) and is incompatible
with certain hardware, PXE stacks and network setups.
++++ SETTING UP THE TFTP SERVER ++++
PXELINUX currently requires that the boot server has a TFTP server
which supports the "tsize" TFTP option (RFC 1784/RFC 2349). The
"tftp-hpa" TFTP server, which support options, is available at:
http://www.kernel.org/pub/software/network/tftp/
ftp://www.kernel.org/pub/software/network/tftp/
... and on any kernel.org mirror (see http://www.kernel.org/mirrors/).
Another TFTP server which supports this is atftp by Jean-Pierre
Lefebvre:
ftp://ftp.mamalinux.com/pub/atftp/
If your boot server is running Windows (and you can't fix that), try
tftpd32 by Philippe Jounin (you need version 2.11 or later; previous
versions had a bug which made it incompatible with PXELINUX):
http://tftpd32.jounin.net/
++++ SETTING UP THE DHCP SERVER ++++
The PXE protocol uses a very complex set of extensions to DHCP or
BOOTP. However, most PXE implementations -- this includes all Intel
ones version 0.99n and later -- seem to be able to boot in a
"conventional" DHCP/TFTP configuration. Assuming you don't have to
support any very old or otherwise severely broken clients, this is
probably the best configuration unless you already have a PXE boot
server on your network.
A sample DHCP setup, using the "conventional TFTP" configuration,
would look something like the following, using ISC dhcp 2.0 dhcpd.conf
syntax:
allow booting;
allow bootp;
# Standard configuration directives...
option domain-name "<domain name>";
option subnet-mask <subnet mask>;
option broadcast-address <broadcast address>;
option domain-name-servers <dns servers>;
option routers <default router>;
# Group the PXE bootable hosts together
group {
# PXE-specific configuration directives...
next-server <TFTP server address>;
filename "/tftpboot/pxelinux.0";
# You need an entry like this for every host
# unless you're using dynamic addresses
host <hostname> {
hardware ethernet <ethernet address>;
fixed-address <hostname>;
}
}
Note that if your particular TFTP daemon runs under chroot (tftp-hpa
will do this if you specify the -s (secure) option; this is highly
recommended), you almost certainly should not include the /tftpboot
prefix in the filename statement.
If this does not work for your configuration, you probably should set
up a "PXE boot server" on port 4011 of your TFTP server; a free PXE
boot server is available at:
http://www.kano.org.uk/projects/pxe/
With such a boot server defined, your DHCP configuration should look
the same except for an "option dhcp-class-identifier" ("option
vendor-class-identifier" if you are using DHCP 3.0):
allow booting;
allow bootp;
# Standard configuration directives...
option domain-name "<domain name>";
option subnet-mask <subnet mask>;
option broadcast-address <broadcast address>;
option domain-name-servers <dns servers>;
option routers <default router>;
# Group the PXE bootable hosts together
group {
# PXE-specific configuration directives...
option dhcp-class-identifier "PXEClient";
next-server <pxe boot server address>;
# You need an entry like this for every host
# unless you're using dynamic addresses
host <hostname> {
hardware ethernet <ethernet address>;
fixed-address <hostname>;
}
}
Here, the boot file name is obtained from the PXE server.
If the "conventional TFTP" configuration doesn't work on your clients,
and setting up a PXE boot server is not an option, you can attempt the
following configuration. It has been known to boot some
configurations correctly; however, there are no guarantees:
allow booting;
allow bootp;
# Standard configuration directives...
option domain-name "<domain name>";
option subnet-mask <subnet mask>;
option broadcast-address <broadcast address>;
option domain-name-servers <dns servers>;
option routers <default router>;
# Group the PXE bootable hosts together
group {
# PXE-specific configuration directives...
option dhcp-class-identifier "PXEClient";
option vendor-encapsulated-options 09:0f:80:00:0c:4e:65:74:77:6f:72:6b:20:62:6f:6f:74:0a:07:00:50:72:6f:6d:70:74:06:01:02:08:03:80:00:00:47:04:80:00:00:00:ff;
next-server <TFTP server>;
filename "/tftpboot/pxelinux.0";
# You need an entry like this for every host
# unless you're using dynamic addresses
host <hostname> {
hardware ethernet <ethernet address>;
fixed-address <hostname>;
}
}
Note that this *will not* boot some clients that *will* boot with the
"conventional TFTP" configuration; Intel Boot Client 3.0 and later are
known to fall into this category.
++++ SPECIAL DHCP OPTIONS ++++
PXELINUX (starting with version 1.62) supports the following
nonstandard DHCP options, which depending on your DHCP server you may
be able to use to customize the specific behaviour of PXELINUX. See
RFC 5071 for some additional information about these options.
Option 208 pxelinux.magic
- Earlier versions of PXELINUX required this to be set to
F1:00:74:7E (241.0.116.126) for PXELINUX to
recognize any special DHCP options whatsoever. As of
PXELINUX 3.55, this option is deprecated and is no longer
required.
Option 209 pxelinux.configfile
- Specifies the PXELINUX configuration file name.
Option 210 pxelinux.pathprefix
- Specifies the PXELINUX common path prefix, instead of
deriving it from the boot file name. This almost certainly
needs to end in whatever character the TFTP server OS uses
as a pathname separator, e.g. slash (/) for Unix.
Option 211 pxelinux.reboottime
- Specifies, in seconds, the time to wait before reboot in the
event of TFTP failure. 0 means wait "forever" (in reality,
it waits approximately 136 years.)
ISC dhcp 3.0 supports a rather nice syntax for specifying custom
options; you can use the following syntax in dhcpd.conf if you are
running this version of dhcpd:
option space pxelinux;
option pxelinux.magic code 208 = string;
option pxelinux.configfile code 209 = text;
option pxelinux.pathprefix code 210 = text;
option pxelinux.reboottime code 211 = unsigned integer 32;
NOTE: In earlier versions of PXELINUX, this would only work as a
"site-option-space". Since PXELINUX 2.07, this will work both as a
"site-option-space" (unencapsulated) and as a "vendor-option-space"
(type 43 encapsulated.) This may avoid messing with the
dhcp-parameter-request-list, as detailed below.
Then, inside your PXELINUX-booting group or class (whereever you have
the PXELINUX-related options, such as the filename option), you can
add, for example:
# Always include the following lines for all PXELINUX clients
site-option-space "pxelinux";
option pxelinux.magic f1:00:74:7e;
if exists dhcp-parameter-request-list {
# Always send the PXELINUX options (specified in hexadecimal)
option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
}
# These lines should be customized to your setup
option pxelinux.configfile "configs/common";
option pxelinux.pathprefix "/tftpboot/pxelinux/files/";
option pxelinux.reboottime 30;
filename "/tftpboot/pxelinux/pxelinux.bin";
Note that the configfile is relative to the pathprefix: this will look
for a config file called /tftpboot/pxelinux/files/configs/common on
the TFTP server.
The "option dhcp-parameter-request-list" statement forces the DHCP
server to send the PXELINUX-specific options, even though they are not
explicitly requested. Since the DHCP request is done before PXELINUX
is loaded, the PXE client won't know to request them.
Using ISC dhcp 3.0 you can create a lot of these strings on the fly.
For example, to use the hexadecimal form of the hardware address as
the configuration file name, you could do something like:
site-option-space "pxelinux";
option pxelinux.magic f1:00:74:7e;
if exists dhcp-parameter-request-list {
# Always send the PXELINUX options (specified in hexadecimal)
option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
}
option pxelinux.configfile =
concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
filename "/tftpboot/pxelinux.bin";
If you used this from a client whose Ethernet address was
58:FA:84:CF:55:0E, this would look for a configuration file named
"/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".
++++ ALTERNATE TFTP SERVERS ++++
PXELINUX supports the following special pathname conventions:
::filename
Suppresses the common filename prefix, i.e. passes the string
"filename" unmodified to the server.
IP address::filename (e.g. 192.0.2.1::filename)
Suppresses the common filename prefix, *and* sends a request
to an alternate TFTP server. Instead of an IP address, a
DNS name can be used. It will be assumed to be fully
qualified if it contains dots; otherwise the local domain as
reported by the DHCP server (option 15) will be added.
:: was chosen because it is unlikely to conflict with operating system
usage. However, if you happen to have an environment for which the
special treatment of :: is a problem, please contact the Syslinux
mailing list.
++++ SOME NOTES ++++
If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever;
rather, if it has not received any input for approximately five
minutes after displaying an error message, it will reset the machine.
This allows an unattended machine to recover in case it had bad enough
luck of trying to boot at the same time the TFTP server goes down.
Lots of PXE stacks, especially old ones, have various problems of
varying degrees of severity. Please see:
http://syslinux.zytor.com/hardware.php
... for a list of currently known hardware problems, with workarounds
if known.
++++ KEEPING THE PXE STACK AROUND ++++
Normally, PXELINUX will unload the PXE and UNDI stacks before invoking
the kernel. In special circumstances (for example, when using MEMDISK
to boot an operating system with an UNDI network driver) it might be
desirable to keep the PXE stack in memory. If the option "keeppxe"
is given on the kernel command line, PXELINUX will keep the PXE and
UNDI stacks in memory. (If you don't know what this means, you
probably don't need it.)
++++ PROBLEMS WITH YOUR PXE STACK ++++
There are a number of extremely broken PXE stacks in the field. The
gPXE project (formerly known as Etherboot) provides an open-source PXE
stack that works with a number of cards, and which can be loaded from
a CD-ROM, USB key, or floppy if desired.
Information on gPXE is available from:
http://www.etherboot.org/
... and ready-to-use ROM or disk images from:
http://www.rom-o-matic.net/
Some cards, like may systems with the SiS 900, has a PXE stack which
works just barely well enough to load a single file, but doesn't
handle the more advanced items required by PXELINUX. If so, it is
possible to use the built-in PXE stack to load gPXE, which can then
load PXELINUX. See:
http://www.etherboot.org/wiki/pxechaining
++++ CURRENTLY KNOWN PROBLEMS ++++
The following problems are known with PXELINUX, so far:
+ The error recovery routine doesn't work quite right. For right now,
it just does a hard reset - seems good enough.
+ We should probably call the UDP receive function in the keyboard
entry loop, so that we answer ARP requests.
+ Boot sectors/disk images are not supported yet.
If you have additional problems, please contact the Syslinux mailing
list (see syslinux.txt for the address.)

787
config/release/3rdparty/syslinux/doc/rfc5071.txt vendored
View File

@ -1,787 +0,0 @@
Network Working Group D. Hankins
Request for Comments: 5071 ISC
Category: Informational December 2007
Dynamic Host Configuration Protocol Options Used by PXELINUX
Status of This Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Abstract
This document describes the use by PXELINUX of some DHCP Option Codes
numbering from 208-211.
Hankins Informational [Page 1]
RFC 5071 PXELINUX Options December 2007
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. MAGIC Option . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Description . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 5
3.4. Response to RFC 3942 . . . . . . . . . . . . . . . . . . . 5
4. Configuration File Option . . . . . . . . . . . . . . . . . . 5
4.1. Description . . . . . . . . . . . . . . . . . . . . . . . 5
4.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 6
4.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 6
4.4. Response to RFC 3942 . . . . . . . . . . . . . . . . . . . 6
4.5. Client and Server Behaviour . . . . . . . . . . . . . . . 6
5. Path Prefix Option . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Description . . . . . . . . . . . . . . . . . . . . . . . 7
5.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 7
5.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 7
5.4. Response to RFC 3942 . . . . . . . . . . . . . . . . . . . 8
5.5. Client and Server Behaviour . . . . . . . . . . . . . . . 8
6. Reboot Time Option . . . . . . . . . . . . . . . . . . . . . . 9
6.1. Description . . . . . . . . . . . . . . . . . . . . . . . 9
6.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 9
6.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 10
6.4. Response to RFC 3942 . . . . . . . . . . . . . . . . . . . 10
6.5. Client and Server Behaviour . . . . . . . . . . . . . . . 10
7. Specification Conformance . . . . . . . . . . . . . . . . . . 11
8. Security Considerations . . . . . . . . . . . . . . . . . . . 11
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
11.1. Normative References . . . . . . . . . . . . . . . . . . . 12
11.2. Informative References . . . . . . . . . . . . . . . . . . 12
Hankins Informational [Page 2]
RFC 5071 PXELINUX Options December 2007
1. Introduction
PXE, the Preboot eXecution Environment, is a first-stage network
bootstrap agent. PXE is loaded out of firmware on the client host,
and performs DHCP [3] queries to obtain an IP address.
Once on the network, it loads a second-stage bootstrap agent as
configured by DHCP header and option contents.
PXELINUX is one such second-stage bootstrap agent. Once PXE has
passed execution to it, PXELINUX seeks its configuration from a cache
of DHCP options supplied to the PXE first-stage agent, and then takes
action based upon those options.
Most frequently, this implies loading via Trivial File Transfer
Protocol (TFTP) [6] one or more images that are decompressed into
memory, then executed to pass execution to the final Host Operating
System.
PXELINUX uses DHCP options 208-211 to govern parts of this bootstrap
process, but these options are not requested by the PXE DHCP client
at the time it acquires its lease. At that time, the PXE bootloader
has no knowledge that PXELINUX is going to be in use, and even so,
would have no way to know what option(s) PXELINUX might digest.
Local installations that serve this PXELINUX image to its clients
must also configure their DHCP servers to provide these options even
though they are not on the DHCP Parameter Request List [4].
These options are:
o "MAGIC" - 208 - An option whose presence and content verifies to
the PXELINUX bootloader that the options numbered 209-211 are for
the purpose as described herein.
o "ConfigFile" - 209 - Configures the path/filename component of the
configuration file's location, which this bootloader should use to
configure itself.
o "PathPrefix" - 210 - Configures a value to be prepended to the
ConfigFile to discern the directory location of the file.
o "RebootTime" - 211 - Configures a timeout after which the
bootstrap program will reboot the system (most likely returning it
to PXE).
Historically, these option codes numbering from 208-211 were
designated 'Site Local', but after publication of RFC3942 [8], they
were made available for allocation as new standard DHCP options.
Hankins Informational [Page 3]
RFC 5071 PXELINUX Options December 2007
This document marks these codes as assigned.
This direct assignment of option code values in the option
definitions below is unusual as it is not mentioned in DHCP Option
Code assignment guidelines [5]. This document's Option Code
assignments are done within RFC 3942's provisions for documenting
prior use of option codes within the new range (128-223 inclusive).
2. Terminology
o "first-stage bootloader" - Although a given bootloading order may
have many stages, such as where a BIOS boots a DOS Boot Disk,
which then loads a PXE executable, it is, in this example, only
the PXE executable that this document describes as the "first-
stage bootloader" -- in essence, this is the first stage of
booting at which DHCP is involved.
o "second-stage bootloader" - This describes a program loaded by the
first-stage bootloader at the behest of the DHCP server.
o "bootloader" and "network bootstrap agent" - These are synonyms,
excepting that "bootloader" is intentionally vague in that its
next form of bootstrapping may not in fact involve network
resources.
The key words "MAY", "MUST", "MUST NOT", "SHOULD", and "SHOULD NOT"
in this document are to be interpreted as described in RFC 2119 [2].
3. MAGIC Option
3.1. Description
If this option is provided to the PXE bootloader, then the value is
checked by PXELINUX to match the octet string f1:00:74:7e. If this
matches, then PXELINUX bootloaders will also consume options 209-211,
as described below. Otherwise, they are ignored.
This measure was intended to ensure that, as the 'Site Local' option
space is not allocated from a central authority, no conflict would
result in a PXELINUX bootloader improperly digesting options intended
for another purpose.
Hankins Informational [Page 4]
RFC 5071 PXELINUX Options December 2007
3.2. Packet Format
The MAGIC Option format is as follows:
Code Length m1 m2 m3 m4
+--------+--------+--------+--------+--------+--------+
| 208 | 4 | 0xF1 | 0x00 | 0x74 | 0x7E |
+--------+--------+--------+--------+--------+--------+
The code for this option is 208. The length is always four.
3.3. Applicability
This option is absolutely inapplicable to any other purpose.
3.4. Response to RFC 3942
The option code 208 will be adopted for this purpose and immediately
deprecated. Future standards action may return this option to an
available status should it be necessary.
A collision of the use of this option is harmless (at least from
PXELINUX' point of view) by design: if it does not match the
aforementioned magic value, the PXELINUX bootloader will take no
special action.
The PXELINUX project will deprecate the use of this option; future
versions of the software will not evaluate its contents.
It is reasonable to utilize this option code for another purpose, but
it is recommended to do this at a later time, given the desire to
avoid potential collisions in legacy user bases.
4. Configuration File Option
4.1. Description
Once the PXELINUX executable has been entered from the PXE
bootloader, it evaluates this option and loads a file of that name
via TFTP. The contents of this file serve to configure PXELINUX in
its next stage of bootloading (specifying boot image names,
locations, boot-time flags, text to present the user in menu
selections, etc).
In the absence of this option, the PXELINUX agent will search the
TFTP server (as determined by PXE prior to this stage) for a config
file of several default names.
Hankins Informational [Page 5]
RFC 5071 PXELINUX Options December 2007
4.2. Packet Format
The Configuration File Option format is as follows:
Code Length Config-file...
+--------+--------+--------+--------+--------+--------+
| 209 | n | c1 | c2 | ... | c(n) |
+--------+--------+--------+--------+--------+--------+
The code for this option is 209. The Config-file (c1..c(n)) is an
NVT-ASCII [1] printable string; it is not terminated by a zero or any
other value.
4.3. Applicability
Any bootloader, PXE or otherwise, that makes use of a separate
configuration file rather than containing all configurations within
DHCP options (which may be impossible due to the limited space
available for DHCP options) may conceivably make use of this option.
4.4. Response to RFC 3942
The code 209 will be adopted for this purpose.
4.5. Client and Server Behaviour
The Config File Option MUST be supplied by the DHCP server if it
appears on the Parameter Request List, but MUST also be supplied if
the server administrator believed it would later be useful to the
client (such as because the server is configured to offer a second-
stage boot image, which they know will make use of it). The option
MUST NOT be supplied if no value has been configured for it, or if a
value of zero length has been configured.
The DHCP client MUST only cache this option in a location the second-
stage bootloader may access.
The second-stage bootloader MUST, in concert with other DHCP options
and fields, use this option's value as a filename to be loaded via
TFTP and read for further second-stage-loader-specific configuration
parameters. The format and content of such a file is specific to the
second-stage bootloader, and as such, is out of scope of this
document.
Hankins Informational [Page 6]
RFC 5071 PXELINUX Options December 2007
5. Path Prefix Option
5.1. Description
In PXELINUX' case, it is often the case that several different
environments would have the same TFTP path prefix, but would have
different filenames (for example: hosts' bootloader images and config
files may be kept in a directory structure derived from their Media
Access Control (MAC) address). Consequently, it was deemed
worthwhile to deliver a TFTP path prefix configuration option, so
that these two things could be configured separately in a DHCP Server
configuration: the prefix and the possibly host-specific file
location.
The actual filename that PXELINUX requests from its TFTP server is
derived by prepending this value to the Config File Option above.
Once this config file is loaded and during processing, any TFTP file
paths specified within it are similarly processed -- prepending the
contents of this option.
5.2. Packet Format
The Path Prefix Option format is as follows:
Code Length Path-Prefix...
+--------+--------+--------+--------+--------+--------+
| 210 | n | p1 | p2 | ... | p(n) |
+--------+--------+--------+--------+--------+--------+
The code for this option is 210. The Path Prefix is an NVT-ASCII
printable string; it is not terminated by zero or any other value.
5.3. Applicability
This option came into existence because server administrators found
it useful to configure the prefix and suffix of the config file path
separately. A group of different PXE booting clients may use the
same path prefix, but different filenames, or vice versa.
The 'shortcut' this represents is worthwhile, but it is questionable
whether that needs to manifest itself on the protocol wire.
Hankins Informational [Page 7]
RFC 5071 PXELINUX Options December 2007
It only becomes interesting from a protocol standpoint if other
options are adopted that prefix this value as well -- performing a
kind of string compression is highly beneficial to the limited
available DHCP option space.
But it's clearly inapplicable to any current use of, e.g., the
FILENAME header contents or the DHCP Boot File Name option (#67).
Use of these fields is encoded on firmware of thousands of devices
that can't or are not likely to be upgraded. Altering any behaviour
here is likely to cause severe compatibility problems.
Although compression of the TFTP-loaded configuration file contents
is not a compelling factor, contrived configurations using these
values may also exist: where each of a large variety of different
clients load the same configuration file, with the same contents, but
due to a differently configured path prefix actually load different
images. Whether this sort of use is truly needed remains unproven.
5.4. Response to RFC 3942
The code 210 will be adopted for this purpose.
5.5. Client and Server Behaviour
The Path Prefix option MUST be supplied by the DHCP server if it
appears on the Parameter Request List, but MUST also be supplied if
the server administrator believed it would later be useful to the
client (such as because the server is configured to offer a second-
stage boot image that they know will make use of it). The option
MUST NOT be supplied if no value has been configured for it, or if a
value of zero length has been configured.
The DHCP client MUST only cache this option in a location where the
second-stage bootloader may access it.
The second-stage bootloader MUST prepend this option's value, if any,
to the contents of the ConfigFile option prior to obtaining the
resulting value via TFTP, or the default 'Config File Search Path',
which the second-stage bootloader iterates in the absence of a Config
File Option. The client MAY prepend the value to other configuration
directives within that file once it has been loaded. The client MUST
NOT prepend this option's value to any other DHCP option contents or
field, unless explicitly stated in a document describing that option
or field.
Hankins Informational [Page 8]
RFC 5071 PXELINUX Options December 2007
6. Reboot Time Option
6.1. Description
Should PXELINUX be executed, and then for some reason, be unable to
reach its TFTP server to continue bootstrapping, the client will, by
default, reboot itself after 300 seconds have passed. This may be
too long, too short, or inappropriate behaviour entirely, depending
on the environment.
By configuring a non-zero value in this option, admins can inform
PXELINUX of which specific timeout is desired. The client will
reboot itself if it fails to achieve its configured network resources
within the specified number of seconds.
This reboot will run through the system's normal boot-time execution
path, most likely leading it back to PXE and therefore PXELINUX. So,
in the general case, this is akin to returning the client to the DHCP
INIT state.
By configuring zero, the feature is disabled, and instead the client
chooses to remove itself from the network and wait indefinitely for
operator intervention.
It should be stressed that this is in no way related to configuring a
lease time. The perceived transition to INIT state is due to client
running state -- reinitializing itself -- not due to lease timer
activity. That is, it is not safe to assume that a PXELINUX client
will abandon its lease when this timer expires.
6.2. Packet Format
The Reboot Time Option format is as follows:
Code Length
+--------+--------+--------+--------+--------+--------+
| 211 | 4 | Reboot Time |
+--------+--------+--------+--------+--------+--------+
The code for this option is 211. The length is always four. The
Reboot Time is a 32-bit (4 byte) integer in network byte order.
Hankins Informational [Page 9]
RFC 5071 PXELINUX Options December 2007
6.3. Applicability
Any network bootstrap program in any sufficiently complex networking
environment could conceivably enter into such a similar condition,
either due to having its IP address stolen out from under it by a
rogue client on the network, by being moved between networks where
its PXE-derived DHCP lease is no longer valid, or any similar means.
It seems desirable for any network bootstrap agent to implement an
ultimate timeout for it to start over.
The client may, for example, get different working configuration
parameters from a different DHCP server upon restarting.
6.4. Response to RFC 3942
The code 211 will be adopted for this purpose.
6.5. Client and Server Behaviour
The Reboot Time Option MUST be supplied by the DHCP server if it
appears on the Parameter Request List, but MUST also be supplied if
the server administrator believed it would later be useful to the
client (such as because the server is configured to offer a second-
stage boot image that they know will make use of it). The option
MUST NOT be supplied if no value has been configured for it, or if it
contains a value of zero length.
The DHCP client MUST only cache this option in a location the second-
stage bootloader may access.
If the value of this option is nonzero, the second-stage bootloader
MUST schedule a timeout: after a number of seconds equal to this
option's value have passed, the second-stage bootloader MUST reboot
the system, ultimately returning the path of execution back to the
first-stage bootloader. It MUST NOT reboot the system once the
thread of execution has been passed to the host operating system (at
which point, this timeout is effectively obviated).
If the value of this option is zero, the second-stage bootloader MUST
NOT schedule such a timeout at all. Any second-stage bootloader that
finds it has encountered excessive timeouts attempting to obtain its
host operating system SHOULD disconnect itself from the network to
wait for operator intervention, but MAY continue to attempt to
acquire the host operating system indefinitely.
Hankins Informational [Page 10]
RFC 5071 PXELINUX Options December 2007
7. Specification Conformance
To conform to this specification, clients and servers MUST implement
the Configuration File, Path Prefix, and Reboot Time options as
directed.
The MAGIC option MAY NOT be implemented, as it has been deprecated.
8. Security Considerations
PXE and PXELINUX allow any entity acting as a DHCP server to execute
arbitrary code upon a system. At present, no PXE implementation is
known to implement authentication mechanisms [7] so that PXE clients
can be sure they are receiving configuration information from the
correct, authoritative DHCP server.
The use of TFTP by PXE and PXELINUX also lacks any form of
cryptographic signature -- so a 'Man in the Middle' attack may lead
to an attacker's code being executed on the client system. Since
this is not an encrypted channel, any of the TFTP loaded data may
also be exposed (such as in loading a "RAMDISK" image, which contains
/etc/passwd or similar information).
The use of the Ethernet MAC Address as the client's unique identity
may allow an attacker who takes on that identity to gain
inappropriate access to a client system's network resources by being
given by the DHCP server whatever 'keys' are required, in fact, to be
the target system (to boot up as though it were the target).
Great care should be taken to secure PXE and PXELINUX installations,
such as by using IP firewalls, to reduce or eliminate these concerns.
A nearby attacker might feed a "Reboot Time" option value of 1 second
to a mass of unsuspecting clients, to effect a Denial Of Service
(DoS) upon the DHCP server, but then again it may just as easily
supply these clients with rogue second-stage bootloaders that simply
transmit a flood of packets.
This document in and by itself provides no security, nor does it
impact existing DCHP security as described in RFC 2131 [3].
9. IANA Considerations
IANA has done the following:
1. Moved DHCPv4 Option code 208 from 'Tentatively Assigned' to
'Assigned', referencing this document. IANA has marked this same
option code, 208, as Deprecated.
Hankins Informational [Page 11]
RFC 5071 PXELINUX Options December 2007
2. Moved DHCPv4 Option code 209 from 'Tentatively Assigned' to
'Assigned', referencing this document.
3. Moved DHCPv4 Option code 210 from 'Tentatively Assigned' to
'Assigned', referencing this document.
4. Moved DHCPv4 Option code 211 from 'Tentatively Assigned' to
'Assigned', referencing this document.
10. Acknowledgements
These options were designed and implemented for the PXELINUX project
by H. Peter Anvin, and he was instrumental in producing this
document. Shane Kerr has also provided feedback that has improved
this document.
11. References
11.1. Normative References
[1] Postel, J. and J. Reynolds, "Telnet Protocol Specification",
STD 8, RFC 854, May 1983.
[2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[3] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131,
March 1997.
[4] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor
Extensions", RFC 2132, March 1997.
[5] Droms, R., "Procedures and IANA Guidelines for Definition of New
DHCP Options and Message Types", BCP 43, RFC 2939,
September 2000.
11.2. Informative References
[6] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350,
July 1992.
[7] Droms, R. and W. Arbaugh, "Authentication for DHCP Messages",
RFC 3118, June 2001.
[8] Volz, B., "Reclassifying Dynamic Host Configuration Protocol
version 4 (DHCPv4) Options", RFC 3942, November 2004.
Hankins Informational [Page 12]
RFC 5071 PXELINUX Options December 2007
Author's Address
David W. Hankins
Internet Systems Consortium, Inc.
950 Charter Street
Redwood City, CA 94063
US
Phone: +1 650 423 1307
EMail: David_Hankins@isc.org
Hankins Informational [Page 13]
RFC 5071 PXELINUX Options December 2007
Full Copyright Statement
Copyright (C) The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Hankins Informational [Page 14]

149
config/release/3rdparty/syslinux/doc/sdi.txt vendored
View File

@ -1,149 +0,0 @@
SDI files
Syslinux supports SDI files ( *.sdi ).
Features:
* Support for gzipped SDI images
* When used with gpxelinux.0, images can be downloaded by HTTP or FTP,
leading to fastest boot times.
"System Deployment Image" is a file format created by Microsoft and mostly used
in its products to provide in a single file a boot loader, an OS loader
(like NTLDR) and a disk or partition image to boot from it without any
other installed program. This is typically used in a PXE environment to boot
embedded Windows versions without boot disk support.
The support of SDI images in Syslinux is based on a white
paper from Saad Syed. You can find the paper here:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnxpesp1/html/ram_sdi.asp
SDI support has been only been tested with SDI v1.0 with Windows XP Embedded
images and may not work with later versions or alternative uses.
++++ Supported SDI images ++++
To make a SDI image supported by pxelinux/isolinux/syslinux, you need to
follow the steps below (detailed instructions are in the white paper
cited above):
You need to install "Windows Embedded Studio" and to run the
"Remote Boot Service Setup".
1) Create a new SDI file (eg: sdimgr /new xpe.sdi).
2) Before importing your target partition, add the following files
in the root folder:
* ntdetect.com
* boot.ini
Its content should be:
[boot loader]
default=ramdisk(0)\WINDOWS
[operating systems]
ramdisk(0)\WINDOWS="Windows XPE From RAM" /fastdetect
(you can customize the name and add options like /debug)
Note: Your partition may be compressed (using compressed NTFS), but these two
files need to be uncompressed.
3) Import the partition in the SDI file (eg: sdimgr xpe.sdi /readpart:D:).
The size of the partition must be less than 500 MB.
4) Import the boot program STARTROM.COM
(eg: sdimgr xpe.sdi /import:BOOT,0,C:\Program Files\Windows Embedded\Remote Boot Service\Downloads\startrom.com)
5) Import the nt loader NTLDR in the SDI file
(eg: sdimgr xpe.sdi /import:LOAD,0,C:\Program Files\Windows Embedded\Remote Boot Service\Downloads\ntldr)
Note: only the version of NTLDR provided by Remote Boot Service Setup
and located in this directory has been tested. According to
"http://skolk.livejournal.com/667.html", "osloader.exe" from retail XP
can also be used to replace this NTLDR version.
6) Pack the SDI file (eg: sdimgr xpe.sdi /pack)
7) Gzip your image
If you want to speed the download time, you can gzip the image as it will
be uncompressed by syslinux during the loading. You can use some programs
like ntfsclone ("http://www.linux-ntfs.org/doku.php?id=ntfsclone") to
remove unused blocks from the NTFS filesystem before deploying your image.
8) You are now ready to boot your image.
Unlike the traditional way of using SDI images (startrom.n12), you don't need
other files than your SDI image in the tftpboot (for pxelinux), the CD
(for isolinux), or the hard disk for syslinux.
* You can use the usual options of pxelinux/isolinux/syslinux (config file,
config path, reboot time...)
For example, a simple configuration with pxelinux:
/tftpboot/xpe.sdi
/tftpboot/pxelinux.0
/tftpboot/pxelinux.cfg/default with the following content:
DEFAULT 0
label 0 [WinXpe]
KERNEL sdi.c32
APPEND xpe.sdi
++++ Error messages ++++
* No $SDI signature in file
A SDI image should begin by a signature "$SDI", the signature has not
been found in your file. Perhaps your file is corrupted or has not been created
correctly. Run sdimgr on it to see if everything is correct.
* No BOOT BLOB in image
You have to import a boot program (eg: startrom.com) when you make
your SDI image (see above). The offset of this program in the SDI file
is in the SDI header (begining of the file). However, the offset
found in your SDI file is null.
You probably forgot to include the boot program. Run the sdimgr program
and look if you see a line like:
BOOT 0x00000000.00001000 0x00000000.00005EC2...
--------
This is the
offset and
should not
be null
* BOOT BLOB is empty
See above. The size of your boot program included in the SDI
is null. You probably imported a corrupted version of startrom.com.
Run sdimgr and check the size in the following line:
BOOT 0x00000000.00001000 0x00000000.00005EC2...
--------
this is the
size and
should not
be null
* BOOT BLOB extends beyond file
You have a BOOT BLOB in your SDI file, but its size is invalid
because its goes beyond the total image size. Check the tools you used
to build the image file.
* BOOT BLOB too large for memory
Your BOOT BLOB seems correct, however there is not enough memory
to load it. Increase your RAM or reduce the SDI size. This is a very
abnormal situation as the BOOT BLOB is usually very small. Your SDI
file might be corrupted.
* Image too large for memory
Your SDI file seems correct, however there is not enough memory
to load it. Increase your RAM or reduce the SDI size.
* SDI header is corrupted
Your SDI file seems correct, but its header contains a checksum
that is invalid. You most likely have a corrupted SDI file.
++++ Warning messages ++++
* Warning: unknown SDI version
You are using a newer version of SDI than the one with which this program
has been tested. It may not work. Please give feedback and provide your
SDI version.

790
config/release/3rdparty/syslinux/doc/syslinux.txt vendored
View File

@ -1,790 +0,0 @@
The Syslinux Project
A suite of bootloaders for Linux
Copyright 1994-2011 H. Peter Anvin and contributors
This program is provided under the terms of the GNU General Public
License, version 2 or, at your option, any later version. There is no
warranty, neither expressed nor implied, to the function of this
program. Please see the included file COPYING for details.
----------------------------------------------------------------------
Syslinux now has a home page at http://syslinux.zytor.com/
----------------------------------------------------------------------
The Syslinux suite contains the following boot loaders
("derivatives"), for their respective boot media:
SYSLINUX - MS-DOS/Windows FAT filesystem
PXELINUX - PXE network booting
ISOLINUX - ISO9660 CD-ROM
EXTLINUX - Linux ext2/ext3 filesystem
For historical reasons, some of the sections in this document applies
to the FAT loader (SYSLINUX) only; see pxelinux.txt, isolinux.txt and
extlinux.txt for what differs in these versions. The all-caps term
"SYSLINUX" generally refers to the FAT loader, whereas "Syslinux"
refers to the project as a whole.
Help with cleaning up the docs would be greatly appreciated.
++++ Options ++++
These are the options common to all versions of Syslinux:
-s Safe, slow, stupid; uses simpler code that boots better
-f Force installing
-r Raid mode. If boot fails, tell the BIOS to boot the next
device in the boot sequence (usually the next hard disk)
instead of stopping with an error message.
This is useful for RAID-1 booting.
These are only in the Windows version:
-m Mbr; install a bootable MBR sector to the beginning of the
drive.
-a Active; marks the partition used active (=bootable)
++++ CREATING A BOOTABLE LINUX FLOPPY +++
In order to create a bootable Linux floppy using SYSLINUX, prepare a
normal MS-DOS formatted floppy. Copy one or more Linux kernel files to
it, then execute the DOS command:
syslinux [-sfrma][-d directory] a: [bootsecfile]
(or whichever drive letter is appropriate; the [] meaning optional.)
Use "syslinux.com" (in the dos subdirectory of the distribution) for
plain DOS (MS-DOS, DR-DOS, PC-DOS, FreeDOS...) or Win9x/ME.
Use "syslinux.exe" (in the win32 subdirectory of the distribution) for
WinNT/2000/XP.
Under Linux, execute the command:
syslinux [-sfr][-d directory][-o offset] /dev/fd0
(or, again, whichever device is the correct one.)
This will alter the boot sector on the disk and copy a file named
LDLINUX.SYS into its root directory (or a subdirectory, if the -d
option is specified.)
The -s option, if given, will install a "safe, slow and stupid"
version of SYSLINUX. This version may work on some very buggy BIOSes
on which SYSLINUX would otherwise fail. If you find a machine on
which the -s option is required to make it boot reliably, please send
as much info about your machine as you can, and include the failure
mode.
The -o option is used with a disk image file and specifies the byte
offset of the filesystem image in the file.
For the DOS and Windows installers, the -m and -a options can be used
on hard drives to write a Master Boot Record (MBR), and to mark the
specific partition active.
If the Shift or Alt keys are held down during boot, or the Caps or Scroll
locks are set, Syslinux will display a LILO-style "boot:" prompt. The
user can then type a kernel file name followed by any kernel parameters.
The Syslinux loader does not need to know about the kernel file in
advance; all that is required is that it is a file located in the root
directory on the disk.
There are two versions of the Linux installer; one in the "mtools"
directory which requires no special privilege (other than write
permission to the device where you are installing) but requires the
mtools program suite to be available, and one in the "unix" directory
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.
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.
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.
INCLUDE filename
Inserts the contents of another file at this point in the
configuration file. Files can currently be nested up to 16
levels deep, but it is not guaranteed that more than 8 levels
will be supported in the future.
DEFAULT kernel options...
Sets the default command line. If Syslinux boots automatically,
it will act just as if the entries after DEFAULT had been typed
in at the "boot:" prompt.
If no configuration file is present, or no DEFAULT entry is
present in the config file, an error message is displayed and
the boot: prompt is shown.
UI module options...
Selects a specific user interface module (typically menu.c32
or vesamenu.c32). The command-line interface treats this as a
directive that overrides the DEFAULT and PROMPT directives.
APPEND options...
Add one or more options to the kernel command line. These are
added both for automatic and manual boots. The options are
added at the very beginning of the kernel command line,
usually permitting explicitly entered kernel options to override
them. This is the equivalent of the LILO "append" option.
IPAPPEND flag_val [PXELINUX only]
The IPAPPEND option is available only on PXELINUX. The
flag_val is an OR of the following options:
1: indicates that an option of the following format
should be generated and added to the kernel command line:
ip=<client-ip>:<boot-server-ip>:<gw-ip>:<netmask>
... based on the input from the DHCP/BOOTP or PXE boot server.
NOTE: The use of this option is no substitute for running a
DHCP client in the booted system. Without regular renewals,
the lease acquired by the PXE BIOS will expire, making the
IP address available for reuse by the DHCP server.
2: indicates that an option of the following format
should be generated and added to the kernel command line:
BOOTIF=<hardware-address-of-boot-interface>
... in dash-separated hexadecimal with leading hardware type
(same as for the configuration file; see pxelinux.txt.)
This allows an initrd program to determine from which
interface the system booted.
4: indicates that an option of the following format
should be generated and added to the kernel command line:
SYSUUID=<system uuid>
... in lower case hexadecimal in the format normally used for
UUIDs (same as for the configuration file; see pxelinux.txt.)
LABEL label
KERNEL image
APPEND options...
IPAPPEND flag_val [PXELINUX only]
Indicates that if "label" is entered as the kernel to boot,
Syslinux should instead boot "image", and the specified APPEND
and IPAPPEND options should be used instead of the ones
specified in the global section of the file (before the first
LABEL command.) The default for "image" is the same as
"label", and if no APPEND is given the default is to use the
global entry (if any).
Starting with version 3.62, the number of LABEL statements is
virtually unlimited.
Note that LILO uses the syntax:
image = mykernel
label = mylabel
append = "myoptions"
... whereas Syslinux uses the syntax:
label mylabel
kernel mykernel
append myoptions
Note: The "kernel" doesn't have to be a Linux kernel; it can
be a boot sector or a COMBOOT file (see below.)
Since version 3.32 label names are no longer mangled into DOS
format (for SYSLINUX.)
The following commands are available after a LABEL statement:
LINUX image - Linux kernel image (default)
BOOT image - Bootstrap program (.bs, .bin)
BSS image - BSS image (.bss)
PXE image - PXE Network Bootstrap Program (.0)
FDIMAGE image - Floppy disk image (.img)
COMBOOT image - COMBOOT program (.com, .cbt)
COM32 image - COM32 program (.c32)
CONFIG image - New configuration file
Using one of these keywords instead of KERNEL forces the
filetype, regardless of the filename.
CONFIG means restart the boot loader using a different
configuration file. The configuration file is read, the
working directory is changed (if specified via an APPEND), then
the configuration file is parsed.
APPEND -
Append nothing. APPEND with a single hyphen as argument in a
LABEL section can be used to override a global APPEND.
LOCALBOOT type
Attempt a different local boot method. The special value -1
causes the boot loader to report failure to the BIOS, which, on
recent BIOSes, should mean that the next boot device in the
boot sequence should be activated. Values other than those
documented may produce undesired results.
On PXELINUX, "type" 0 means perform a normal boot. "type" 4
will perform a local boot with the Universal Network Driver
Interface (UNDI) driver still resident in memory. Finally,
"type" 5 will perform a local boot with the entire PXE
stack, including the UNDI driver, still resident in memory.
All other values are undefined. If you don't know what the
UNDI or PXE stacks are, don't worry -- you don't want them,
just specify 0.
On ISOLINUX, the "type" specifies the local drive number to
boot from; 0x00 is the primary floppy drive and 0x80 is the
primary hard drive.
INITRD initrd_file
Starting with version 3.71, an initrd can be specified in a
separate statement (INITRD) instead of as part of the APPEND
statement; this functionally appends "initrd=initrd_file" to
the kernel command line.
It supports multiple filenames separated by commas.
This is mostly useful for initramfs, which can be composed of
multiple separate cpio or cpio.gz archives.
Note: all files except the last one are zero-padded to a
4K page boundary. This should not affect initramfs.
IMPLICIT flag_val
If flag_val is 0, do not load a kernel image unless it has been
explicitly named in a LABEL statement. The default is 1.
ALLOWOPTIONS flag_val
If flag_val is 0, the user is not allowed to specify any
arguments on the kernel command line. The only options
recognized are those specified in an APPEND statement. The
default is 1.
TIMEOUT timeout
Indicates how long to wait at the boot: prompt until booting
automatically, in units of 1/10 s. The timeout is cancelled as
soon as the user types anything on the keyboard, the assumption
being that the user will complete the command line already
begun. A timeout of zero will disable the timeout completely,
this is also the default.
TOTALTIMEOUT timeout
Indicates how long to wait until booting automatically, in
units of 1/10 s. This timeout is *not* cancelled by user
input, and can thus be used to deal with serial port glitches
or "the user walked away" type situations. A timeout of zero
will disable the timeout completely, this is also the default.
Both TIMEOUT and TOTALTIMEOUT can be used together, for
example:
# Wait 5 seconds unless the user types something, but
# always boot after 15 minutes.
TIMEOUT 50
TOTALTIMEOUT 9000
ONTIMEOUT kernel options...
Sets the command line invoked on a timeout. Normally this is
the same thing as invoked by "DEFAULT". If this is specified,
then "DEFAULT" is used only if the user presses <Enter> to
boot.
ONERROR kernel options...
If a kernel image is not found (either due to it not existing,
or because IMPLICIT is set), run the specified command. The
faulty command line is appended to the specified options, so
if the ONERROR directive reads as:
ONERROR xyzzy plugh
... and the command line as entered by the user is:
foo bar baz
... Syslinux will execute the following as if entered by the
user:
xyzzy plugh foo bar baz
SERIAL port [[baudrate] flowcontrol]
Enables a serial port to act as the console. "port" is a
number (0 = /dev/ttyS0 = COM1, etc.) or an I/O port address
(e.g. 0x3F8); if "baudrate" is omitted, the baud rate defaults
to 9600 bps. The serial parameters are hardcoded to be 8
bits, no parity, 1 stop bit.
"flowcontrol" is a combination of the following bits:
0x001 - Assert DTR
0x002 - Assert RTS
0x008 - Enable interrupts
0x010 - Wait for CTS assertion
0x020 - Wait for DSR assertion
0x040 - Wait for RI assertion
0x080 - Wait for DCD assertion
0x100 - Ignore input unless CTS asserted
0x200 - Ignore input unless DSR asserted
0x400 - Ignore input unless RI asserted
0x800 - Ignore input unless DCD asserted
All other bits are reserved.
Typical values are:
0 - No flow control (default)
0x303 - Null modem cable detect
0x013 - RTS/CTS flow control
0x813 - RTS/CTS flow control, modem input
0x023 - DTR/DSR flow control
0x083 - DTR/DCD flow control
For the SERIAL directive to be guaranteed to work properly, it
should be the first directive in the configuration file.
NOTE: "port" values from 0 to 3 means the first four serial
ports detected by the BIOS. They may or may not correspond to
the legacy port values 0x3F8, 0x2F8, 0x3E8, 0x2E8.
Enabling interrupts (setting the 0x008 bit) may give better
responsiveness without setting the NOHALT option, but could
potentially cause problems with buggy BIOSes.
NOHALT flag_val
If flag_val is 1, don't halt the processor while idle.
Halting the processor while idle significantly reduces the
power consumption, but can cause poor responsiveness to the
serial console, especially when using scripts to drive the
serial console, as opposed to human interaction.
CONSOLE flag_val
If flag_val is 0, disable output to the normal video console.
If flag_val is 1, enable output to the video console (this is
the default.)
Some BIOSes try to forward this to the serial console and
sometimes make a total mess thereof, so this option lets you
disable the video console on these systems.
FONT filename
Load a font in .psf format before displaying any output
(except the copyright line, which is output as ldlinux.sys
itself is loaded.) Syslinux only loads the font onto the
video card; if the .psf file contains a Unicode table it is
ignored. This only works on EGA and VGA cards; hopefully it
should do nothing on others.
KBDMAP keymap
Install a simple keyboard map. The keyboard remapper used is
*very* simplistic (it simply remaps the keycodes received from
the BIOS, which means that only the key combinations relevant
in the default layout -- usually U.S. English -- can be
mapped) but should at least help people with AZERTY keyboard
layout and the locations of = and , (two special characters
used heavily on the Linux kernel command line.)
The included program keytab-lilo.pl from the LILO distribution
can be used to create such keymaps. The file keytab-lilo.txt
contains the documentation for this program.
DISPLAY filename
Displays the indicated file on the screen at boot time (before
the boot: prompt, if displayed). Please see the section below
on DISPLAY files.
NOTE: If the file is missing, this option is simply ignored.
SAY message
Prints the message on the screen.
PROMPT flag_val
If flag_val is 0, display the boot: prompt only if the Shift or Alt
key is pressed, or Caps Lock or Scroll lock is set (this is the
default). If flag_val is 1, always display the boot: prompt.
NOESCAPE flag_val
If flag_val is set to 1, ignore the Shift/Alt/Caps Lock/Scroll
Lock escapes. Use this (together with PROMPT 0) to force the
default boot alternative.
NOCOMPLETE flag_val
If flag_val is set to 1, the Tab key does not display labels
at the boot: prompt.
F1 filename
F2 filename
...etc...
F9 filename
F10 filename
F11 filename
F12 filename
Displays the indicated file on the screen when a function key is
pressed at the boot: prompt. This can be used to implement
pre-boot online help (presumably for the kernel command line
options.) Please see the section below on DISPLAY files.
When using the serial console, press <Ctrl-F><digit> to get to
the help screens, e.g. <Ctrl-F><2> to get to the F2 screen.
For F10-F12, hit <Ctrl-F><A>, <Ctrl-F>B, <Ctrl-F>C. For
compatibility with earlier versions, F10 can also be entered as
<Ctrl-F>0.
Blank lines are ignored.
Note that the configuration file is not completely decoded. Syntax
different from the one described above may still work correctly in this
version of Syslinux, but may break in a future one.
++++ DISPLAY FILE FORMAT ++++
DISPLAY and function-key help files are text files in either DOS or UNIX
format (with or without <CR>). In addition, the following special codes
are interpreted:
<FF> <FF> = <Ctrl-L> = ASCII 12
Clear the screen, home the cursor. Note that the screen is
filled with the current display color.
<SI><bg><fg> <SI> = <Ctrl-O> = ASCII 15
Set the display colors to the specified background and
foreground colors, where <bg> and <fg> are hex digits,
corresponding to the standard PC display attributes:
0 = black 8 = dark grey
1 = dark blue 9 = bright blue
2 = dark green a = bright green
3 = dark cyan b = bright cyan
4 = dark red c = bright red
5 = dark purple d = bright purple
6 = brown e = yellow
7 = light grey f = white
Picking a bright color (8-f) for the background results in the
corresponding dark color (0-7), with the foreground flashing.
Colors are not visible over the serial console.
<CAN>filename<newline> <CAN> = <Ctrl-X> = ASCII 24
If a VGA display is present, enter graphics mode and display
the graphic included in the specified file. The file format
is an ad hoc format called LSS16; the included Perl program
"ppmtolss16" can be used to produce these images. This Perl
program also includes the file format specification.
The image is displayed in 640x480 16-color mode. Once in
graphics mode, the display attributes (set by <SI> code
sequences) work slightly differently: the background color is
ignored, and the foreground colors are the 16 colors specified
in the image file. For that reason, ppmtolss16 allows you to
specify that certain colors should be assigned to specific
color indicies.
Color indicies 0 and 7, in particular, should be chosen with
care: 0 is the background color, and 7 is the color used for
the text printed by Syslinux itself.
<EM> <EM> = <Ctrl-Y> = ASCII 25
If we are currently in graphics mode, return to text mode.
<DLE>..<ETB> <Ctrl-P>..<Ctrl-W> = ASCII 16-23
These codes can be used to select which modes to print a
certain part of the message file in. Each of these control
characters select a specific set of modes (text screen,
graphics screen, serial port) for which the output is actually
displayed:
Character Text Graph Serial
------------------------------------------------------
<DLE> = <Ctrl-P> = ASCII 16 No No No
<DC1> = <Ctrl-Q> = ASCII 17 Yes No No
<DC2> = <Ctrl-R> = ASCII 18 No Yes No
<DC3> = <Ctrl-S> = ASCII 19 Yes Yes No
<DC4> = <Ctrl-T> = ASCII 20 No No Yes
<NAK> = <Ctrl-U> = ASCII 21 Yes No Yes
<SYN> = <Ctrl-V> = ASCII 22 No Yes Yes
<ETB> = <Ctrl-W> = ASCII 23 Yes Yes Yes
For example:
<DC1>Text mode<DC2>Graphics mode<DC4>Serial port<ETB>
... will actually print out which mode the console is in!
<SUB> <SUB> = <Ctrl-Z> = ASCII 26
End of file (DOS convention).
<BEL> <BEL> = <Ctrl-G> = ASCII 7
Beep the speaker.
++++ COMMAND LINE KEYSTROKES ++++
The command line prompt supports the following keystrokes:
<Enter> boot specified command line
<BackSpace> erase one character
<Ctrl-U> erase the whole line
<Ctrl-V> display the current Syslinux version
<Ctrl-W> erase one word
<Ctrl-X> force text mode
<Tab> list matching labels
<F1>..<F12> help screens (if configured)
<Ctrl-F><digit> equivalent to F1..F10
<Ctrl-C> interrupt boot in progress
<Esc> interrupt boot in progress
<Ctrl-N> display network information (PXELINUX only)
++++ COMBOOT IMAGES AND OTHER OPERATING SYSTEMS ++++
This version of Syslinux supports chain loading of other operating
systems (such as MS-DOS and its derivatives, including Windows 95/98),
as well as COMBOOT-style standalone executables (a subset of DOS .COM
files; see separate section below.)
Chain loading requires the boot sector of the foreign operating system
to be stored in a file in the root directory of the filesystem.
Because neither Linux kernels, boot sector images, nor COMBOOT files
have reliable magic numbers, Syslinux will look at the file extension.
The following extensions are recognized (case insensitive):
none or other Linux kernel image
.0 PXE bootstrap program (NBP) [PXELINUX only]
.bin "CD boot sector" [ISOLINUX only]
.bs Boot sector [SYSLINUX only]
.bss Boot sector, DOS superblock will be patched in [SYSLINUX only]
.c32 COM32 image (32-bit COMBOOT)
.cbt COMBOOT image (not runnable from DOS)
.com COMBOOT image (runnable from DOS)
.img Disk image [ISOLINUX only]
For filenames given on the command line, Syslinux will search for the
file by adding extensions in the order listed above if the plain
filename is not found. Filenames in KERNEL statements must be fully
qualified.
If this is specified with one of the keywords LINUX, BOOT, BSS,
FDIMAGE, COMBOOT, COM32, or CONFIG instead of KERNEL, the filetype is
considered to be the one specified regardless of the filename.
++++ BOOTING DOS (OR OTHER SIMILAR OPERATING SYSTEMS) ++++
This section applies to SYSLINUX only, not to PXELINUX or ISOLINUX.
See isolinux.txt for an equivalent procedure for ISOLINUX.
This is the recommended procedure for creating a SYSLINUX disk that
can boot either DOS or Linux. This example assumes the drive is A: in
DOS and /dev/fd0 in Linux; for other drives, substitute the
appropriate drive designator.
---- Linux procedure ----
1. Make a DOS bootable disk. This can be done either by specifying
the /s option when formatting the disk in DOS, or by running the
DOS command SYS (this can be done under DOSEMU if DOSEMU has
direct device access to the relevant drive):
format a: /s
or
sys a:
2. Boot Linux. Copy the DOS boot sector from the disk into a file:
dd if=/dev/fd0 of=dos.bss bs=512 count=1
3. Run SYSLINUX on the disk:
syslinux /dev/fd0
4. Mount the disk and copy the DOS boot sector file to it. The file
*must* have extension .bss:
mount -t msdos /dev/fd0 /mnt
cp dos.bss /mnt
5. Copy the Linux kernel image(s), initrd(s), etc to the disk, and
create/edit syslinux.cfg and help files if desired:
cp vmlinux /mnt
cp initrd.gz /mnt
6. Unmount the disk (if applicable.)
umount /mnt
---- DOS/Windows procedure ----
To make this installation in DOS only, you need the utility copybs.com
(included with Syslinux) as well as the syslinux.com installer. If
you are on an WinNT-based system (WinNT, Win2k, WinXP or later), use
syslinux.exe instead.
1. Make a DOS bootable disk. This can be done either by specifying
the /s option when formatting the disk in DOS, or by running the
DOS command SYS:
format a: /s
or
sys a:
2. Copy the DOS boot sector from the disk into a file. The file
*must* have extension .bss:
copybs a: a:dos.bss
3. Run SYSLINUX on the disk:
syslinux a:
4. Copy the Linux kernel image(s), initrd(s), etc to the disk, and
create/edit syslinux.cfg and help files if desired:
copy vmlinux a:
copy initrd.gz a:
++++ COMBOOT EXECUTABLES ++++
Syslinux supports simple standalone programs, using a file format
similar to DOS ".com" files. A 32-bit version, called COM32, is also
provided. A simple API provides access to a limited set of filesystem
and console functions.
See the file comboot.txt for more information on COMBOOT and COM32
programs.
++++ NOVICE PROTECTION ++++
Syslinux will attempt to detect booting on a machine with too little
memory, which means the Linux boot sequence cannot complete. If so, a
message is displayed and the boot sequence aborted. Holding down the
Ctrl key while booting disables this feature.
Any file that SYSLINUX uses can be marked hidden, system or readonly
if so is convenient; SYSLINUX ignores all file attributes. The
SYSLINUX installed automatically sets the readonly/hidden/system
attributes on LDLINUX.SYS.
++++ NOTES ON BOOTABLE CD-ROMS ++++
SYSLINUX can be used to create bootdisk images for El
Torito-compatible bootable CD-ROMs. However, it appears that many
BIOSes are very buggy when it comes to booting CD-ROMs. Some users
have reported that the following steps are helpful in making a CD-ROM
that is bootable on the largest possible number of machines:
a) Use the -s (safe, slow and stupid) option to SYSLINUX;
b) Put the boot image as close to the beginning of the
ISO 9660 filesystem as possible.
A CD-ROM is so much faster than a floppy that the -s option shouldn't
matter from a speed perspective.
Of course, you probably want to use ISOLINUX instead. See isolinux.txt.
++++ BOOTING FROM A FAT FILESYSTEM PARTITION ON A HARD DISK ++++
SYSLINUX can boot from a FAT filesystem partition on a hard disk
(including FAT32). The installation procedure is identical to the
procedure for installing it on a floppy, and should work under either
DOS or Linux. To boot from a partition, SYSLINUX needs to be launched
from a Master Boot Record or another boot loader, just like DOS itself
would.
Under DOS, you can install a standard simple MBR on the primary hard
disk by running the command:
FDISK /MBR
Then use the FDISK command to mark the appropriate partition active.
A simple MBR, roughly on par with the one installed by DOS (but
unencumbered), is included in the SYSLINUX distribution. To install
it under Linux, simply type:
cat mbr.bin > /dev/XXX
... where /dev/XXX is the device you wish to install it on.
Under DOS or Win32, you can install the SYSLINUX MBR with the -m
option to the SYSLINUX installer, and use the -a option to mark the
current partition active:
syslinux -ma c:
Note that this will also install SYSLINUX on the specified partition.
++++ HARDWARE INFORMATION +++
I have started to maintain a web page of hardware with known
problems. There are, unfortunately, lots of broken hardware out
there; especially early PXE stacks (for PXELINUX) have lots of
problems.
A list of problems, and workarounds (if known), is maintained at:
http://syslinux.zytor.com/hardware.php
++++ BOOT LOADER IDS USED ++++
The Linux boot protocol supports a "boot loader ID", a single byte
where the upper nybble specifies a boot loader family (3 = Syslinux)
and the lower nybble is version or, in the case of Syslinux, media:
0x31 (49) = SYSLINUX
0x32 (50) = PXELINUX
0x33 (51) = ISOLINUX
0x34 (52) = EXTLINUX
In recent versions of Linux, this ID is available as
/proc/sys/kernel/bootloader_type.
++++ BUG REPORTS ++++
I would appreciate hearing of any problems you have with Syslinux. I
would also like to hear from you if you have successfully used Syslinux,
*especially* if you are using it for a distribution.
If you are reporting problems, please include all possible information
about your system and your BIOS; the vast majority of all problems
reported turn out to be BIOS or hardware bugs, and I need as much
information as possible in order to diagnose the problems.
There is a mailing list for discussion among Syslinux users and for
announcements of new and test versions. To join, or to browse the
archive, go to:
http://www.zytor.com/mailman/listinfo/syslinux
Please DO NOT send HTML messages or attachments to the mailing list
(including multipart/alternative or similar.) All such messages will
be bounced.

47
config/release/3rdparty/syslinux/doc/usbkey.txt vendored
View File

@ -1,47 +0,0 @@
The proper mode to boot a USB key drive in is "USB-HDD". That is the
ONLY mode in which the C/H/S geometry encoded on the disk itself
doesn't have to match what the BIOS thinks it is. Since geometry on
USB drives is completely arbitrary, and can vary from BIOS to BIOS,
this is the only mode which will work in general.
Some BIOSes have been reported (in particular, certain versions of the
Award BIOS) that cannot boot USB keys in "USB-HDD" mode. This is a
very serious BIOS bug, but it is unfortunately rather typical of the
kind of quality we're seeing out of major BIOS vendors these days. On
these BIOSes, you're generally stuck booting them in USB-ZIP mode.
THIS MEANS THE FILESYSTEM IMAGE ON THE DISK HAS TO HAVE A CORRECT
ZIPDRIVE-COMPATIBLE GEOMETRY.
A standard zipdrive (both the 100 MB and the 250 MB varieties) have a
"geometry" of 64 heads, 32 sectors, and are partitioned devices with a
single partition 4 (unlike most other media of this type which uses
partition 1.) The 100 MB variety has 96 cylinders, and the 250 MB
variety has 239 cylinders; but any number of cylinders will do as
appropriate for the size device you have. For example, if your device
reports when inserted into a Linux system:
usb-storage: device found at 4
Vendor: 32MB Model: HardDrive Rev: 1.88
Type: Direct-Access ANSI SCSI revision: 02
SCSI device sda: 64000 512-byte hdwr sectors (33 MB)
... you would have 64000/(64*32) = 31.25 cylinders; round down to 31.
The script "mkdiskimage" which is supplied with the syslinux
distribution can be used to initialize USB keys in a Zip-like fashion.
To do that, calculate the correct number of cylinders (31 in the
example above), and, if your USB key is /dev/sda (CHECK THE KERNEL
MESSAGES CAREFULLY - IF YOU ENTER THE WRONG DISK DRIVE IT CANNOT BE
RECOVERED), run:
mkdiskimage -4 /dev/sda 0 64 32
(The 0 means automatically determine the size of the device, and -4
means mimic a zipdisk by using partition 4.)
Then you should be able to run
syslinux /dev/sda4
... and mount /dev/sda4 and put your files on it as needed.

BIN
config/release/3rdparty/syslinux/dos/syslinux.com vendored
View File

Binary file not shown.

BIN
config/release/3rdparty/syslinux/win32/syslinux.exe vendored
View File

Binary file not shown.

0
config/release/3rdparty/md5sum/README → packages/tools/syslinux/files/3rdparty/md5sum/README vendored
View File

0
config/release/3rdparty/md5sum/md5sum.exe → packages/tools/syslinux/files/3rdparty/md5sum/md5sum.exe vendored
View File

0
config/release/INSTALL → packages/tools/syslinux/files/INSTALL
View File

0
config/release/create_installstick → packages/tools/syslinux/files/create_installstick
View File

0
config/release/create_installstick.bat → packages/tools/syslinux/files/create_installstick.bat
View File

0
config/release/create_installstick.exe → packages/tools/syslinux/files/create_installstick.exe
View File

0
config/release/create_virtualimage → packages/tools/syslinux/files/create_virtualimage
View File

0
config/release/sample.conf/extlinux.conf → packages/tools/syslinux/files/sample.conf/extlinux.conf
View File

0
config/release/sample.conf/grub.conf → packages/tools/syslinux/files/sample.conf/grub.conf
View File

0
config/release/sample.conf/syslinux.cfg → packages/tools/syslinux/files/sample.conf/syslinux.cfg
View File

0
config/release/sample.conf/syslinux_installer.cfg → packages/tools/syslinux/files/sample.conf/syslinux_installer.cfg
View File