diff options
Diffstat (limited to 'contrib/syslinux-4.02/doc')
| -rw-r--r-- | contrib/syslinux-4.02/doc/CodingStyle.txt | 831 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/SubmittingPatches.txt | 568 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/comboot.txt | 1012 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/distrib.txt | 29 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/extlinux.txt | 132 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/gpt.txt | 69 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/isolinux.txt | 133 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/keytab-lilo.txt | 85 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/mboot.txt | 26 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/memdisk.txt | 292 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/menu.txt | 566 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/pxelinux.txt | 418 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/rfc5071.txt | 787 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/sdi.txt | 149 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/syslinux.txt | 788 | ||||
| -rw-r--r-- | contrib/syslinux-4.02/doc/usbkey.txt | 47 |
16 files changed, 5932 insertions, 0 deletions
diff --git a/contrib/syslinux-4.02/doc/CodingStyle.txt b/contrib/syslinux-4.02/doc/CodingStyle.txt new file mode 100644 index 0000000..e79e65a --- /dev/null +++ b/contrib/syslinux-4.02/doc/CodingStyle.txt @@ -0,0 +1,831 @@ +Syslinux uses Linux kernel coding style, except that we are "heretic" +in the sense of using 4 spaces instead of 8 for indentation. + +This coding style will be applied after the 3.81 release. + + + ------------------------------------------------- + + Linux kernel coding style + +This is a short document describing the preferred coding style for the +linux kernel. Coding style is very personal, and I won't _force_ my +views on anybody, but this is what goes for anything that I have to be +able to maintain, and I'd prefer it for most other things too. Please +at least consider the points made here. + +First off, I'd suggest printing out a copy of the GNU coding standards, +and NOT read it. Burn them, it's a great symbolic gesture. + +Anyway, here goes: + + + Chapter 1: Indentation + +Tabs are 8 characters, and thus indentations are also 8 characters. +There are heretic movements that try to make indentations 4 (or even 2!) +characters deep, and that is akin to trying to define the value of PI to +be 3. + +Rationale: The whole idea behind indentation is to clearly define where +a block of control starts and ends. Especially when you've been looking +at your screen for 20 straight hours, you'll find it a lot easier to see +how the indentation works if you have large indentations. + +Now, some people will claim that having 8-character indentations makes +the code move too far to the right, and makes it hard to read on a +80-character terminal screen. The answer to that is that if you need +more than 3 levels of indentation, you're screwed anyway, and should fix +your program. + +In short, 8-char indents make things easier to read, and have the added +benefit of warning you when you're nesting your functions too deep. +Heed that warning. + +The preferred way to ease multiple indentation levels in a switch statement is +to align the "switch" and its subordinate "case" labels in the same column +instead of "double-indenting" the "case" labels. E.g.: + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + + +Don't put multiple statements on a single line unless you have +something to hide: + + if (condition) do_this; + do_something_everytime; + +Don't put multiple assignments on a single line either. Kernel coding style +is super simple. Avoid tricky expressions. + +Outside of comments, documentation and except in Kconfig, spaces are never +used for indentation, and the above example is deliberately broken. + +Get a decent editor and don't leave whitespace at the end of lines. + + + Chapter 2: Breaking long lines and strings + +Coding style is all about readability and maintainability using commonly +available tools. + +The limit on the length of lines is 80 columns and this is a strongly +preferred limit. + +Statements longer than 80 columns will be broken into sensible chunks. +Descendants are always substantially shorter than the parent and are placed +substantially to the right. The same applies to function headers with a long +argument list. Long strings are as well broken into shorter strings. The +only exception to this is where exceeding 80 columns significantly increases +readability and does not hide information. + +void fun(int a, int b, int c) +{ + if (condition) + printk(KERN_WARNING "Warning this is a long printk with " + "3 parameters a: %u b: %u " + "c: %u \n", a, b, c); + else + next_statement; +} + + Chapter 3: Placing Braces and Spaces + +The other issue that always comes up in C styling is the placement of +braces. Unlike the indent size, there are few technical reasons to +choose one placement strategy over the other, but the preferred way, as +shown to us by the prophets Kernighan and Ritchie, is to put the opening +brace last on the line, and put the closing brace first, thusly: + + if (x is true) { + we do y + } + +This applies to all non-function statement blocks (if, switch, for, +while, do). E.g.: + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +However, there is one special case, namely functions: they have the +opening brace at the beginning of the next line, thus: + + int function(int x) + { + body of function + } + +Heretic people all over the world have claimed that this inconsistency +is ... well ... inconsistent, but all right-thinking people know that +(a) K&R are _right_ and (b) K&R are right. Besides, functions are +special anyway (you can't nest them in C). + +Note that the closing brace is empty on a line of its own, _except_ in +the cases where it is followed by a continuation of the same statement, +ie a "while" in a do-statement or an "else" in an if-statement, like +this: + + do { + body of do-loop + } while (condition); + +and + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Rationale: K&R. + +Also, note that this brace-placement also minimizes the number of empty +(or almost empty) lines, without any loss of readability. Thus, as the +supply of new-lines on your screen is not a renewable resource (think +25-line terminal screens here), you have more empty lines to put +comments on. + +Do not unnecessarily use braces where a single statement will do. + +if (condition) + action(); + +This does not apply if one branch of a conditional statement is a single +statement. Use braces in both branches. + +if (condition) { + do_this(); + do_that(); +} else { + otherwise(); +} + + 3.1: Spaces + +Linux kernel style for use of spaces depends (mostly) on +function-versus-keyword usage. Use a space after (most) keywords. The +notable exceptions are sizeof, typeof, alignof, and __attribute__, which look +somewhat like functions (and are usually used with parentheses in Linux, +although they are not required in the language, as in: "sizeof info" after +"struct fileinfo info;" is declared). + +So use a space after these keywords: + if, switch, case, for, do, while +but not with sizeof, typeof, alignof, or __attribute__. E.g., + s = sizeof(struct file); + +Do not add spaces around (inside) parenthesized expressions. This example is +*bad*: + + s = sizeof( struct file ); + +When declaring pointer data or a function that returns a pointer type, the +preferred use of '*' is adjacent to the data name or function name and not +adjacent to the type name. Examples: + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +Use one space around (on each side of) most binary and ternary operators, +such as any of these: + + = + - < > * / % | & ^ <= >= == != ? : + +but no space after unary operators: + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +no space before the postfix increment & decrement unary operators: + ++ -- + +no space after the prefix increment & decrement unary operators: + ++ -- + +and no space around the '.' and "->" structure member operators. + +Do not leave trailing whitespace at the ends of lines. Some editors with +"smart" indentation will insert whitespace at the beginning of new lines as +appropriate, so you can start typing the next line of code right away. +However, some such editors do not remove the whitespace if you end up not +putting a line of code there, such as if you leave a blank line. As a result, +you end up with lines containing trailing whitespace. + +Git will warn you about patches that introduce trailing whitespace, and can +optionally strip the trailing whitespace for you; however, if applying a series +of patches, this may make later patches in the series fail by changing their +context lines. + + + Chapter 4: Naming + +C is a Spartan language, and so should your naming be. Unlike Modula-2 +and Pascal programmers, C programmers do not use cute names like +ThisVariableIsATemporaryCounter. A C programmer would call that +variable "tmp", which is much easier to write, and not the least more +difficult to understand. + +HOWEVER, while mixed-case names are frowned upon, descriptive names for +global variables are a must. To call a global function "foo" is a +shooting offense. + +GLOBAL variables (to be used only if you _really_ need them) need to +have descriptive names, as do global functions. If you have a function +that counts the number of active users, you should call that +"count_active_users()" or similar, you should _not_ call it "cntusr()". + +Encoding the type of a function into the name (so-called Hungarian +notation) is brain damaged - the compiler knows the types anyway and can +check those, and it only confuses the programmer. No wonder MicroSoft +makes buggy programs. + +LOCAL variable names should be short, and to the point. If you have +some random integer loop counter, it should probably be called "i". +Calling it "loop_counter" is non-productive, if there is no chance of it +being mis-understood. Similarly, "tmp" can be just about any type of +variable that is used to hold a temporary value. + +If you are afraid to mix up your local variable names, you have another +problem, which is called the function-growth-hormone-imbalance syndrome. +See chapter 6 (Functions). + + + Chapter 5: Typedefs + +Please don't use things like "vps_t". + +It's a _mistake_ to use typedef for structures and pointers. When you see a + + vps_t a; + +in the source, what does it mean? + +In contrast, if it says + + struct virtual_container *a; + +you can actually tell what "a" is. + +Lots of people think that typedefs "help readability". Not so. They are +useful only for: + + (a) totally opaque objects (where the typedef is actively used to _hide_ + what the object is). + + Example: "pte_t" etc. opaque objects that you can only access using + the proper accessor functions. + + NOTE! Opaqueness and "accessor functions" are not good in themselves. + The reason we have them for things like pte_t etc. is that there + really is absolutely _zero_ portably accessible information there. + + (b) Clear integer types, where the abstraction _helps_ avoid confusion + whether it is "int" or "long". + + u8/u16/u32 are perfectly fine typedefs, although they fit into + category (d) better than here. + + NOTE! Again - there needs to be a _reason_ for this. If something is + "unsigned long", then there's no reason to do + + typedef unsigned long myflags_t; + + but if there is a clear reason for why it under certain circumstances + might be an "unsigned int" and under other configurations might be + "unsigned long", then by all means go ahead and use a typedef. + + (c) when you use sparse to literally create a _new_ type for + type-checking. + + (d) New types which are identical to standard C99 types, in certain + exceptional circumstances. + + Although it would only take a short amount of time for the eyes and + brain to become accustomed to the standard types like 'uint32_t', + some people object to their use anyway. + + Therefore, the Linux-specific 'u8/u16/u32/u64' types and their + signed equivalents which are identical to standard types are + permitted -- although they are not mandatory in new code of your + own. + + When editing existing code which already uses one or the other set + of types, you should conform to the existing choices in that code. + + (e) Types safe for use in userspace. + + In certain structures which are visible to userspace, we cannot + require C99 types and cannot use the 'u32' form above. Thus, we + use __u32 and similar types in all structures which are shared + with userspace. + +Maybe there are other cases too, but the rule should basically be to NEVER +EVER use a typedef unless you can clearly match one of those rules. + +In general, a pointer, or a struct that has elements that can reasonably +be directly accessed should _never_ be a typedef. + + + Chapter 6: Functions + +Functions should be short and sweet, and do just one thing. They should +fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, +as we all know), and do one thing and do that well. + +The maximum length of a function is inversely proportional to the +complexity and indentation level of that function. So, if you have a +conceptually simple function that is just one long (but simple) +case-statement, where you have to do lots of small things for a lot of +different cases, it's OK to have a longer function. + +However, if you have a complex function, and you suspect that a +less-than-gifted first-year high-school student might not even +understand what the function is all about, you should adhere to the +maximum limits all the more closely. Use helper functions with +descriptive names (you can ask the compiler to in-line them if you think +it's performance-critical, and it will probably do a better job of it +than you would have done). + +Another measure of the function is the number of local variables. They +shouldn't exceed 5-10, or you're doing something wrong. Re-think the +function, and split it into smaller pieces. A human brain can +generally easily keep track of about 7 different things, anything more +and it gets confused. You know you're brilliant, but maybe you'd like +to understand what you did 2 weeks from now. + +In source files, separate functions with one blank line. If the function is +exported, the EXPORT* macro for it should follow immediately after the closing +function brace line. E.g.: + +int system_is_up(void) +{ + return system_state == SYSTEM_RUNNING; +} +EXPORT_SYMBOL(system_is_up); + +In function prototypes, include parameter names with their data types. +Although this is not required by the C language, it is preferred in Linux +because it is a simple way to add valuable information for the reader. + + + Chapter 7: Centralized exiting of functions + +Albeit deprecated by some people, the equivalent of the goto statement is +used frequently by compilers in form of the unconditional jump instruction. + +The goto statement comes in handy when a function exits from multiple +locations and some common work such as cleanup has to be done. + +The rationale is: + +- unconditional statements are easier to understand and follow +- nesting is reduced +- errors by not updating individual exit points when making + modifications are prevented +- saves the compiler work to optimize redundant code away ;) + +int fun(int a) +{ + int result = 0; + char *buffer = kmalloc(SIZE); + + if (buffer == NULL) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out; + } + ... +out: + kfree(buffer); + return result; +} + + Chapter 8: Commenting + +Comments are good, but there is also a danger of over-commenting. NEVER +try to explain HOW your code works in a comment: it's much better to +write the code so that the _working_ is obvious, and it's a waste of +time to explain badly written code. + +Generally, you want your comments to tell WHAT your code does, not HOW. +Also, try to avoid putting comments inside a function body: if the +function is so complex that you need to separately comment parts of it, +you should probably go back to chapter 6 for a while. You can make +small comments to note or warn about something particularly clever (or +ugly), but try to avoid excess. Instead, put the comments at the head +of the function, telling people what it does, and possibly WHY it does +it. + +When commenting the kernel API functions, please use the kernel-doc format. +See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc +for details. + +Linux style for comments is the C89 "/* ... */" style. +Don't use C99-style "// ..." comments. + +The preferred style for long (multi-line) comments is: + + /* + * This is the preferred style for multi-line + * comments in the Linux kernel source code. + * Please use it consistently. + * + * Description: A column of asterisks on the left side, + * with beginning and ending almost-blank lines. + */ + +It's also important to comment data, whether they are basic types or derived +types. To this end, use just one data declaration per line (no commas for +multiple data declarations). This leaves you room for a small comment on each +item, explaining its use. + + + Chapter 9: You've made a mess of it + +That's OK, we all do. You've probably been told by your long-time Unix +user helper that "GNU emacs" automatically formats the C sources for +you, and you've noticed that yes, it does do that, but the defaults it +uses are less than desirable (in fact, they are worse than random +typing - an infinite number of monkeys typing into GNU emacs would never +make a good program). + +So, you can either get rid of GNU emacs, or change it to use saner +values. To do the latter, you can stick the following in your .emacs file: + +(defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + +(add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + +(add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees") + filename)) + (setq indent-tabs-mode t) + (c-set-style "linux-tabs-only"))))) + +This will make emacs go better with the kernel coding style for C +files below ~/src/linux-trees. + +But even if you fail in getting emacs to do sane formatting, not +everything is lost: use "indent". + +Now, again, GNU indent has the same brain-dead settings that GNU emacs +has, which is why you need to give it a few command line options. +However, that's not too bad, because even the makers of GNU indent +recognize the authority of K&R (the GNU people aren't evil, they are +just severely misguided in this matter), so you just give indent the +options "-kr -i8" (stands for "K&R, 8 character indents"), or use +"scripts/Lindent", which indents in the latest style. + +"indent" has a lot of options, and especially when it comes to comment +re-formatting you may want to take a look at the man page. But +remember: "indent" is not a fix for bad programming. + + + Chapter 10: Kconfig configuration files + +For all of the Kconfig* configuration files throughout the source tree, +the indentation is somewhat different. Lines under a "config" definition +are indented with one tab, while help text is indented an additional two +spaces. Example: + +config AUDIT + bool "Auditing support" + depends on NET + help + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +Features that might still be considered unstable should be defined as +dependent on "EXPERIMENTAL": + +config SLUB + depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT + bool "SLUB (Unqueued Allocator)" + ... + +while seriously dangerous features (such as write support for certain +filesystems) should advertise this prominently in their prompt string: + +config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +For full documentation on the configuration files, see the file +Documentation/kbuild/kconfig-language.txt. + + + Chapter 11: Data structures + +Data structures that have visibility outside the single-threaded +environment they are created and destroyed in should always have +reference counts. In the kernel, garbage collection doesn't exist (and +outside the kernel garbage collection is slow and inefficient), which +means that you absolutely _have_ to reference count all your uses. + +Reference counting means that you can avoid locking, and allows multiple +users to have access to the data structure in parallel - and not having +to worry about the structure suddenly going away from under them just +because they slept or did something else for a while. + +Note that locking is _not_ a replacement for reference counting. +Locking is used to keep data structures coherent, while reference +counting is a memory management technique. Usually both are needed, and +they are not to be confused with each other. + +Many data structures can indeed have two levels of reference counting, +when there are users of different "classes". The subclass count counts +the number of subclass users, and decrements the global count just once +when the subclass count goes to zero. + +Examples of this kind of "multi-level-reference-counting" can be found in +memory management ("struct mm_struct": mm_users and mm_count), and in +filesystem code ("struct super_block": s_count and s_active). + +Remember: if another thread can find your data structure, and you don't +have a reference count on it, you almost certainly have a bug. + + + Chapter 12: Macros, Enums and RTL + +Names of macros defining constants and labels in enums are capitalized. + +#define CONSTANT 0x12345 + +Enums are preferred when defining several related constants. + +CAPITALIZED macro names are appreciated but macros resembling functions +may be named in lower case. + +Generally, inline functions are preferable to macros resembling functions. + +Macros with multiple statements should be enclosed in a do - while block: + +#define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +Things to avoid when using macros: + +1) macros that affect control flow: + +#define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while(0) + +is a _very_ bad idea. It looks like a function call but exits the "calling" +function; don't break the internal parsers of those who will read the code. + +2) macros that depend on having a local variable with a magic name: + +#define FOO(val) bar(index, val) + +might look like a good thing, but it's confusing as hell when one reads the +code and it's prone to breakage from seemingly innocent changes. + +3) macros with arguments that are used as l-values: FOO(x) = y; will +bite you if somebody e.g. turns FOO into an inline function. + +4) forgetting about precedence: macros defining constants using expressions +must enclose the expression in parentheses. Beware of similar issues with +macros using parameters. + +#define CONSTANT 0x4000 +#define CONSTEXP (CONSTANT | 3) + +The cpp manual deals with macros exhaustively. The gcc internals manual also +covers RTL which is used frequently with assembly language in the kernel. + + + Chapter 13: Printing kernel messages + +Kernel developers like to be seen as literate. Do mind the spelling +of kernel messages to make a good impression. Do not use crippled +words like "dont"; use "do not" or "don't" instead. Make the messages +concise, clear, and unambiguous. + +Kernel messages do not have to be terminated with a period. + +Printing numbers in parentheses (%d) adds no value and should be avoided. + +There are a number of driver model diagnostic macros in <linux/device.h> +which you should use to make sure messages are matched to the right device +and driver, and are tagged with the right level: dev_err(), dev_warn(), +dev_info(), and so forth. For messages that aren't associated with a +particular device, <linux/kernel.h> defines pr_debug() and pr_info(). + +Coming up with good debugging messages can be quite a challenge; and once +you have them, they can be a huge help for remote troubleshooting. Such +messages should be compiled out when the DEBUG symbol is not defined (that +is, by default they are not included). When you use dev_dbg() or pr_debug(), +that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG. +A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the +ones already enabled by DEBUG. + + + Chapter 14: Allocating memory + +The kernel provides the following general purpose memory allocators: +kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API +documentation for further information about them. + +The preferred form for passing a size of a struct is the following: + + p = kmalloc(sizeof(*p), ...); + +The alternative form where struct name is spelled out hurts readability and +introduces an opportunity for a bug when the pointer variable type is changed +but the corresponding sizeof that is passed to a memory allocator is not. + +Casting the return value which is a void pointer is redundant. The conversion +from void pointer to any other pointer type is guaranteed by the C programming +language. + + + Chapter 15: The inline disease + +There appears to be a common misperception that gcc has a magic "make me +faster" speedup option called "inline". While the use of inlines can be +appropriate (for example as a means of replacing macros, see Chapter 12), it +very often is not. Abundant use of the inline keyword leads to a much bigger +kernel, which in turn slows the system as a whole down, due to a bigger +icache footprint for the CPU and simply because there is less memory +available for the pagecache. Just think about it; a pagecache miss causes a +disk seek, which easily takes 5 miliseconds. There are a LOT of cpu cycles +that can go into these 5 miliseconds. + +A reasonable rule of thumb is to not put inline at functions that have more +than 3 lines of code in them. An exception to this rule are the cases where +a parameter is known to be a compiletime constant, and as a result of this +constantness you *know* the compiler will be able to optimize most of your +function away at compile time. For a good example of this later case, see +the kmalloc() inline function. + +Often people argue that adding inline to functions that are static and used +only once is always a win since there is no space tradeoff. While this is +technically correct, gcc is capable of inlining these automatically without +help, and the maintenance issue of removing the inline when a second user +appears outweighs the potential value of the hint that tells gcc to do +something it would have done anyway. + + + Chapter 16: Function return values and names + +Functions can return values of many different kinds, and one of the +most common is a value indicating whether the function succeeded or +failed. Such a value can be represented as an error-code integer +(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure, +non-zero = success). + +Mixing up these two sorts of representations is a fertile source of +difficult-to-find bugs. If the C language included a strong distinction +between integers and booleans then the compiler would find these mistakes +for us... but it doesn't. To help prevent such bugs, always follow this +convention: + + If the name of a function is an action or an imperative command, + the function should return an error-code integer. If the name + is a predicate, the function should return a "succeeded" boolean. + +For example, "add work" is a command, and the add_work() function returns 0 +for success or -EBUSY for failure. In the same way, "PCI device present" is +a predicate, and the pci_dev_present() function returns 1 if it succeeds in +finding a matching device or 0 if it doesn't. + +All EXPORTed functions must respect this convention, and so should all +public functions. Private (static) functions need not, but it is +recommended that they do. + +Functions whose return value is the actual result of a computation, rather +than an indication of whether the computation succeeded, are not subject to +this rule. Generally they indicate failure by returning some out-of-range +result. Typical examples would be functions that return pointers; they use +NULL or the ERR_PTR mechanism to report failure. + + + Chapter 17: Don't re-invent the kernel macros + +The header file include/linux/kernel.h contains a number of macros that +you should use, rather than explicitly coding some variant of them yourself. +For example, if you need to calculate the length of an array, take advantage +of the macro + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +Similarly, if you need to calculate the size of some structure member, use + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +There are also min() and max() macros that do strict type checking if you +need them. Feel free to peruse that header file to see what else is already +defined that you shouldn't reproduce in your code. + + + Chapter 18: Editor modelines and other cruft + +Some editors can interpret configuration information embedded in source files, +indicated with special markers. For example, emacs interprets lines marked +like this: + +-*- mode: c -*- + +Or like this: + +/* +Local Variables: +compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" +End: +*/ + +Vim interprets markers that look like this: + +/* vim:set sw=8 noet */ + +Do not include any of these in source files. People have their own personal +editor configurations, and your source files should not override them. This +includes markers for indentation and mode configuration. People may use their +own custom mode, or may have some other magic method for making indentation +work correctly. + + + + Appendix I: References + +The C Programming Language, Second Edition +by Brian W. Kernighan and Dennis M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). +URL: http://cm.bell-labs.com/cm/cs/cbook/ + +The Practice of Programming +by Brian W. Kernighan and Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. +URL: http://cm.bell-labs.com/cm/cs/tpop/ + +GNU manuals - where in compliance with K&R and this text - for cpp, gcc, +gcc internals and indent, all available from http://www.gnu.org/manual/ + +WG14 is the international standardization working group for the programming +language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel CodingStyle, by greg@kroah.com at OLS 2002: +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ + +-- +Last updated on 2007-July-13. + diff --git a/contrib/syslinux-4.02/doc/SubmittingPatches.txt b/contrib/syslinux-4.02/doc/SubmittingPatches.txt new file mode 100644 index 0000000..dd764a7 --- /dev/null +++ b/contrib/syslinux-4.02/doc/SubmittingPatches.txt @@ -0,0 +1,568 @@ +I don't have specific submission guidelines for Syslinux, but the ones +that appropriate to the Linux kernel are certainly good enough for +Syslinux. + +In particular, however, I appreciate if patches sent follow the +standard Linux submission format, as I can automatically import them +into git, retaining description and author information. Thus, this +file from the Linux kernel might be useful. + + + ----------------------------------------------------------------------- + + + + How to Get Your Change Into the Linux Kernel + or + Care And Operation Of Your Linus Torvalds + + + +For a person or company who wishes to submit a change to the Linux +kernel, the process can sometimes be daunting if you're not familiar +with "the system." This text is a collection of suggestions which +can greatly increase the chances of your change being accepted. + +Read Documentation/SubmitChecklist for a list of items to check +before submitting code. If you are submitting a driver, also read +Documentation/SubmittingDrivers. + + + +-------------------------------------------- +SECTION 1 - CREATING AND SENDING YOUR CHANGE +-------------------------------------------- + + + +1) "diff -up" +------------ + +Use "diff -up" or "diff -uprN" to create patches. + +All changes to the Linux kernel occur in the form of patches, as +generated by diff(1). When creating your patch, make sure to create it +in "unified diff" format, as supplied by the '-u' argument to diff(1). +Also, please use the '-p' argument which shows which C function each +change is in - that makes the resultant diff a lot easier to read. +Patches should be based in the root kernel source directory, +not in any lower subdirectory. + +To create a patch for a single file, it is often sufficient to do: + + SRCTREE= linux-2.6 + MYFILE= drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +To create a patch for multiple files, you should unpack a "vanilla", +or unmodified kernel source tree, and generate a diff against your +own source tree. For example: + + MYSRC= /devel/linux-2.6 + + tar xvfz linux-2.6.12.tar.gz + mv linux-2.6.12 linux-2.6.12-vanilla + diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ + linux-2.6.12-vanilla $MYSRC > /tmp/patch + +"dontdiff" is a list of files which are generated by the kernel during +the build process, and should be ignored in any diff(1)-generated +patch. The "dontdiff" file is included in the kernel tree in +2.6.12 and later. For earlier kernel versions, you can get it +from <http://www.xenotime.net/linux/doc/dontdiff>. + +Make sure your patch does not include any extra files which do not +belong in a patch submission. Make sure to review your patch -after- +generated it with diff(1), to ensure accuracy. + +If your changes produce a lot of deltas, you may want to look into +splitting them into individual patches which modify things in +logical stages. This will facilitate easier reviewing by other +kernel developers, very important if you want your patch accepted. +There are a number of scripts which can aid in this: + +Quilt: +http://savannah.nongnu.org/projects/quilt + +Andrew Morton's patch scripts: +http://www.zip.com.au/~akpm/linux/patches/ +Instead of these scripts, quilt is the recommended patch management +tool (see above). + + + +2) Describe your changes. + +Describe the technical detail of the change(s) your patch includes. + +Be as specific as possible. The WORST descriptions possible include +things like "update driver X", "bug fix for driver X", or "this patch +includes updates for subsystem X. Please apply." + +If your description starts to get long, that's a sign that you probably +need to split up your patch. See #3, next. + + + +3) Separate your changes. + +Separate _logical changes_ into a single patch file. + +For example, if your changes include both bug fixes and performance +enhancements for a single driver, separate those changes into two +or more patches. If your changes include an API update, and a new +driver which uses that new API, separate those into two patches. + +On the other hand, if you make a single change to numerous files, +group those changes into a single patch. Thus a single logical change +is contained within a single patch. + +If one patch depends on another patch in order for a change to be +complete, that is OK. Simply note "this patch depends on patch X" +in your patch description. + +If you cannot condense your patch set into a smaller set of patches, +then only post say 15 or so at a time and wait for review and integration. + + + +4) Style check your changes. + +Check your patch for basic style violations, details of which can be +found in Documentation/CodingStyle. Failure to do so simply wastes +the reviewers time and will get your patch rejected, probably +without even being read. + +At a minimum you should check your patches with the patch style +checker prior to submission (scripts/checkpatch.pl). You should +be able to justify all violations that remain in your patch. + + + +5) Select e-mail destination. + +Look through the MAINTAINERS file and the source code, and determine +if your change applies to a specific subsystem of the kernel, with +an assigned maintainer. If so, e-mail that person. + +If no maintainer is listed, or the maintainer does not respond, send +your patch to the primary Linux kernel developer's mailing list, +linux-kernel@vger.kernel.org. Most kernel developers monitor this +e-mail list, and can comment on your changes. + + +Do not send more than 15 patches at once to the vger mailing lists!!! + + +Linus Torvalds is the final arbiter of all changes accepted into the +Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. +He gets a lot of e-mail, so typically you should do your best to -avoid- +sending him e-mail. + +Patches which are bug fixes, are "obvious" changes, or similarly +require little discussion should be sent or CC'd to Linus. Patches +which require discussion or do not have a clear advantage should +usually be sent first to linux-kernel. Only after the patch is +discussed should the patch then be submitted to Linus. + + + +6) Select your CC (e-mail carbon copy) list. + +Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. + +Other kernel developers besides Linus need to be aware of your change, +so that they may comment on it and offer code review and suggestions. +linux-kernel is the primary Linux kernel developer mailing list. +Other mailing lists are available for specific subsystems, such as +USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the +MAINTAINERS file for a mailing list that relates specifically to +your change. + +Majordomo lists of VGER.KERNEL.ORG at: + <http://vger.kernel.org/vger-lists.html> + +If changes affect userland-kernel interfaces, please send +the MAN-PAGES maintainer (as listed in the MAINTAINERS file) +a man-pages patch, or at least a notification of the change, +so that some information makes its way into the manual pages. + +Even if the maintainer did not respond in step #4, make sure to ALWAYS +copy the maintainer when you change their code. + +For small patches you may want to CC the Trivial Patch Monkey +trivial@kernel.org managed by Adrian Bunk; which collects "trivial" +patches. Trivial patches must qualify for one of the following rules: + Spelling fixes in documentation + Spelling fixes which could break grep(1) + Warning fixes (cluttering with useless warnings is bad) + Compilation fixes (only if they are actually correct) + Runtime fixes (only if they actually fix things) + Removing use of deprecated functions/macros (eg. check_region) + Contact detail and documentation fixes + Non-portable code replaced by portable code (even in arch-specific, + since people copy, as long as it's trivial) + Any fix by the author/maintainer of the file (ie. patch monkey + in re-transmission mode) +URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/> + + + +7) No MIME, no links, no compression, no attachments. Just plain text. + +Linus and other kernel developers need to be able to read and comment +on the changes you are submitting. It is important for a kernel +developer to be able to "quote" your changes, using standard e-mail +tools, so that they may comment on specific portions of your code. + +For this reason, all patches should be submitting e-mail "inline". +WARNING: Be wary of your editor's word-wrap corrupting your patch, +if you choose to cut-n-paste your patch. + +Do not attach the patch as a MIME attachment, compressed or not. +Many popular e-mail applications will not always transmit a MIME +attachment as plain text, making it impossible to comment on your +code. A MIME attachment also takes Linus a bit more time to process, +decreasing the likelihood of your MIME-attached change being accepted. + +Exception: If your mailer is mangling patches then someone may ask +you to re-send them using MIME. + +See Documentation/email-clients.txt for hints about configuring +your e-mail client so that it sends your patches untouched. + +8) E-mail size. + +When sending patches to Linus, always follow step #7. + +Large changes are not appropriate for mailing lists, and some +maintainers. If your patch, uncompressed, exceeds 40 kB in size, +it is preferred that you store your patch on an Internet-accessible +server, and provide instead a URL (link) pointing to your patch. + + + +9) Name your kernel version. + +It is important to note, either in the subject line or in the patch +description, the kernel version to which this patch applies. + +If the patch does not apply cleanly to the latest kernel version, +Linus will not apply it. + + + +10) Don't get discouraged. Re-submit. + +After you have submitted your change, be patient and wait. If Linus +likes your change and applies it, it will appear in the next version +of the kernel that he releases. + +However, if your change doesn't appear in the next version of the +kernel, there could be any number of reasons. It's YOUR job to +narrow down those reasons, correct what was wrong, and submit your +updated change. + +It is quite common for Linus to "drop" your patch without comment. +That's the nature of the system. If he drops your patch, it could be +due to +* Your patch did not apply cleanly to the latest kernel version. +* Your patch was not sufficiently discussed on linux-kernel. +* A style issue (see section 2). +* An e-mail formatting issue (re-read this section). +* A technical problem with your change. +* He gets tons of e-mail, and yours got lost in the shuffle. +* You are being annoying. + +When in doubt, solicit comments on linux-kernel mailing list. + + + +11) Include PATCH in the subject + +Due to high e-mail traffic to Linus, and to linux-kernel, it is common +convention to prefix your subject line with [PATCH]. This lets Linus +and other kernel developers more easily distinguish patches from other +e-mail discussions. + + + +12) Sign your work + +To improve tracking of who did what, especially with patches that can +percolate to their final resting place in the kernel through several +layers of maintainers, we've introduced a "sign-off" procedure on +patches that are being emailed around. + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as a open-source patch. The rules are pretty simple: if you +can certify the below: + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + +then you just add a line saying + + Signed-off-by: Random J Developer <random@developer.example.org> + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +Some people also put extra tags at the end. They'll just be ignored for +now, but you can do this to mark internal company procedures or just +point out some special detail about the sign-off. + + +13) When to use Acked-by: + +The Signed-off-by: tag indicates that the signer was involved in the +development of the patch, or that he/she was in the patch's delivery path. + +If a person was not directly involved in the preparation or handling of a +patch but wishes to signify and record their approval of it then they can +arrange to have an Acked-by: line added to the patch's changelog. + +Acked-by: is often used by the maintainer of the affected code when that +maintainer neither contributed to nor forwarded the patch. + +Acked-by: is not as formal as Signed-off-by:. It is a record that the acker +has at least reviewed the patch and has indicated acceptance. Hence patch +mergers will sometimes manually convert an acker's "yep, looks good to me" +into an Acked-by:. + +Acked-by: does not necessarily indicate acknowledgement of the entire patch. +For example, if a patch affects multiple subsystems and has an Acked-by: from +one subsystem maintainer then this usually indicates acknowledgement of just +the part which affects that maintainer's code. Judgement should be used here. + When in doubt people should refer to the original discussion in the mailing +list archives. + + +14) The canonical patch format + +The canonical patch subject line is: + + Subject: [PATCH 001/123] subsystem: summary phrase + +The canonical patch message body contains the following: + + - A "from" line specifying the patch author. + + - An empty line. + + - The body of the explanation, which will be copied to the + permanent changelog to describe this patch. + + - The "Signed-off-by:" lines, described above, which will + also go in the changelog. + + - A marker line containing simply "---". + + - Any additional comments not suitable for the changelog. + + - The actual patch (diff output). + +The Subject line format makes it very easy to sort the emails +alphabetically by subject line - pretty much any email reader will +support that - since because the sequence number is zero-padded, +the numerical and alphabetic sort is the same. + +The "subsystem" in the email's Subject should identify which +area or subsystem of the kernel is being patched. + +The "summary phrase" in the email's Subject should concisely +describe the patch which that email contains. The "summary +phrase" should not be a filename. Do not use the same "summary +phrase" for every patch in a whole patch series (where a "patch +series" is an ordered sequence of multiple, related patches). + +Bear in mind that the "summary phrase" of your email becomes +a globally-unique identifier for that patch. It propagates +all the way into the git changelog. The "summary phrase" may +later be used in developer discussions which refer to the patch. +People will want to google for the "summary phrase" to read +discussion regarding that patch. + +A couple of example Subjects: + + Subject: [patch 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCHv2 001/207] x86: fix eflags tracking + +The "from" line must be the very first line in the message body, +and has the form: + + From: Original Author <author@example.com> + +The "from" line specifies who will be credited as the author of the +patch in the permanent changelog. If the "from" line is missing, +then the "From:" line from the email header will be used to determine +the patch author in the changelog. + +The explanation body will be committed to the permanent source +changelog, so should make sense to a competent reader who has long +since forgotten the immediate details of the discussion that might +have led to this patch. + +The "---" marker line serves the essential purpose of marking for patch +handling tools where the changelog message ends. + +One good use for the additional comments after the "---" marker is for +a diffstat, to show what files have changed, and the number of inserted +and deleted lines per file. A diffstat is especially useful on bigger +patches. Other comments relevant only to the moment or the maintainer, +not suitable for the permanent changelog, should also go here. +Use diffstat options "-p 1 -w 70" so that filenames are listed from the +top of the kernel source tree and don't use too much horizontal space +(easily fit in 80 columns, maybe with some indentation). + +See more details on the proper patch format in the following +references. + + + + +----------------------------------- +SECTION 2 - HINTS, TIPS, AND TRICKS +----------------------------------- + +This section lists many of the common "rules" associated with code +submitted to the kernel. There are always exceptions... but you must +have a really good reason for doing so. You could probably call this +section Linus Computer Science 101. + + + +1) Read Documentation/CodingStyle + +Nuff said. If your code deviates too much from this, it is likely +to be rejected without further review, and without comment. + +One significant exception is when moving code from one file to +another -- in this case you should not modify the moved code at all in +the same patch which moves it. This clearly delineates the act of +moving the code and your changes. This greatly aids review of the +actual differences and allows tools to better track the history of +the code itself. + +Check your patches with the patch style checker prior to submission +(scripts/checkpatch.pl). The style checker should be viewed as +a guide not as the final word. If your code looks better with +a violation then its probably best left alone. + +The checker reports at three levels: + - ERROR: things that are very likely to be wrong + - WARNING: things requiring careful review + - CHECK: things requiring thought + +You should be able to justify all violations that remain in your +patch. + + + +2) #ifdefs are ugly + +Code cluttered with ifdefs is difficult to read and maintain. Don't do +it. Instead, put your ifdefs in a header, and conditionally define +'static inline' functions, or macros, which are used in the code. +Let the compiler optimize away the "no-op" case. + +Simple example, of poor code: + + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + #ifdef CONFIG_NET_FUNKINESS + init_funky_net(dev); + #endif + +Cleaned-up example: + +(in header) + #ifndef CONFIG_NET_FUNKINESS + static inline void init_funky_net (struct net_device *d) {} + #endif + +(in the code itself) + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + init_funky_net(dev); + + + +3) 'static inline' is better than a macro + +Static inline functions are greatly preferred over macros. +They provide type safety, have no length limitations, no formatting +limitations, and under gcc they are as cheap as macros. + +Macros should only be used for cases where a static inline is clearly +suboptimal [there a few, isolated cases of this in fast paths], +or where it is impossible to use a static inline function [such as +string-izing]. + +'static inline' is preferred over 'static __inline__', 'extern inline', +and 'extern __inline__'. + + + +4) Don't over-design. + +Don't try to anticipate nebulous future cases which may or may not +be useful: "Make it as simple as you can, and no simpler." + + + +---------------------- +SECTION 3 - REFERENCES +---------------------- + +Andrew Morton, "The perfect patch" (tpp). + <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> + +Jeff Garzik, "Linux kernel patch submission format". + <http://linux.yyz.us/patch-format.html> + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + <http://www.kroah.com/log/2005/03/31/> + <http://www.kroah.com/log/2005/07/08/> + <http://www.kroah.com/log/2005/10/19/> + <http://www.kroah.com/log/2006/01/11/> + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2> + +Kernel Documentation/CodingStyle: + <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle> + +Linus Torvalds's mail on the canonical patch format: + <http://lkml.org/lkml/2005/4/7/183> +-- diff --git a/contrib/syslinux-4.02/doc/comboot.txt b/contrib/syslinux-4.02/doc/comboot.txt new file mode 100644 index 0000000..4b4b880 --- /dev/null +++ b/contrib/syslinux-4.02/doc/comboot.txt @@ -0,0 +1,1012 @@ + + COMBOOT and COM32 files + + +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. + + + ++++ COMBOOT file format ++++ + +A COMBOOT file is a raw binary file containing 16-bit code. It should +be linked to run at offset 0x100, and contain no absolute segment +references. It is run in 16-bit real mode. + +A COMBOOT image can be written to be compatible with MS-DOS. Such a +file will usually have extension ".com". A COMBOOT file which is not +compatible with MS-DOS will usually have extension ".cbt". + +Before running the program, Syslinux sets up the following fields in +the Program Segment Prefix (PSP), a structure at offset 0 in the +program segment: + + Offset Size Meaning + 0 word Contains an INT 20h instruction + 2 word Contains the paragraph (16-byte "segment" address) at + the end of memory available to the program. + 128 byte Length of the command line arguments, including the leading + space but not including the final CR character. + 129 127b Command line arguments, starting with a space and ending + with a CR character (ASCII 13). + +The program is allowed to use memory between the PSP paragraph (which +all the CS, DS, ES and SS registers point to at program start) and the +paragraph value given at offset 2. + +On startup, SP is set up to point to the end of the 64K segment, at +0xfffe. Under DOS it is possible for SP to contain a smaller +value if memory is very tight; this is never the case under Syslinux. + +The program should make no assumptions about what segment address it +will be loaded at; instead it should look at the segment registers on +program startup. Both DOS and Syslinux will guarantee CS == DS == ES +== SS on program start; the program should not assume anything about +the values of FS or GS. + +To exit, a program can either execute a near RET (which will jump to +offset 0 which contains an INT 20h instruction, terminating the +program), or execute INT 20h or INT 21h AH=00h or INT 21h AH=4Ch. +If compatiblity with Syslinux 1.xx is desired, use INT 20h. + + + ++++ COM32R file format ++++ + +A COM32R file is a raw binary file containing 32-bit code. It should +be self-relocating, as it will be loaded by the Syslinux core at any +4K aligned address. It will be run in flat-memory 32-bit protected +mode. Under Syslinux, it will be run in CPL 0, however, since it may +be possible to create a COM32 execution engine that would run under +something like Linux DOSEMU, it is recommended that the code does not +assume CPL 0 unless absolutely necessary. + +A COM32R program must start with the byte sequence B8 FE 4C CD 21 (mov +eax,21cd4cfeh) as a magic number. + +The COM32R format replaces the earlier COM32 format, which was linked +to a fixed address (0x101000). + +A COM32R file should have extension ".c32". + +On startup, CS will be set up as a flat 32-bit code segment, and DS == +ES == SS will be set up as the equivalent flat 32-bit data segment. +FS and GS are reserved for future use and are currently initialized to +zero. A COM32R image should not assume any particular values of +segment selectors. + +ESP is set up at the end of available memory and also serves as +notification to the program how much memory is available. + +The following arguments are passed to the program on the stack: + + Address Size Meaning + [ESP] dword Return (termination) address + [ESP+4] dword Number of additional arguments (currently 8) + [ESP+8] dword Pointer to the command line arguments (null-terminated string) + [ESP+12] dword Pointer to INT call helper function + [ESP+16] dword Pointer to low memory bounce buffer + [ESP+20] dword Size of low memory bounce buffer + [ESP+24] dword Pointer to FAR call helper function (new in 2.05) + [ESP+28] dword Pointer to CDECL helper function (new in 3.54) + [ESP+32] dword Amount of memory controlled by the Syslinux core (new in 3.74) + [ESP+36] dword Pointer to the filename of the com32 module (new in 3.86) + [ESP+40] dword Pointer to protected-mode functions (new in 4.00) + +The libcom32 startup code loads this into a structure named __com32, +defined in <com32.h>: + +extern struct com32_sys_args { + uint32_t cs_sysargs; + char *cs_cmdline; + void __cdecl(*cs_intcall)(uint8_t, const com32sys_t *, com32sys_t *); + void *cs_bounce; + uint32_t cs_bounce_size; + void __cdecl(*cs_farcall)(uint32_t, const com32sys_t *, com32sys_t *); + int __cdecl(*cs_cfarcall)(uint32_t, const void *, uint32_t); + uint32_t cs_memsize; + const char *cs_name; + const struct com32_pmapi *cs_pm; +} __com32; + +The intcall helper function can be used to issue BIOS or Syslinux API +calls, and takes the interrupt number as first argument. The second +argument is a pointer to the input register definition, an instance of +the following structure (available in <com32.h>): + +typedef union { + uint32_t l; + uint16_t w[2]; + uint8_t b[4]; +} reg32_t; + +typedef struct { + uint16_t gs; /* Offset 0 */ + uint16_t fs; /* Offset 2 */ + uint16_t es; /* Offset 4 */ + uint16_t ds; /* Offset 6 */ + + reg32_t edi; /* Offset 8 */ + reg32_t esi; /* Offset 12 */ + reg32_t ebp; /* Offset 16 */ + reg32_t _unused_esp; /* Offset 20 */ + reg32_t ebx; /* Offset 24 */ + reg32_t edx; /* Offset 28 */ + reg32_t ecx; /* Offset 32 */ + reg32_t eax; /* Offset 36 */ + + reg32_t eflags; /* Offset 40 */ +} com32sys_t; + +The third argument is a pointer to the output register definition, an +instance of the same structure. The third argument can also be zero +(NULL). + +Since BIOS or Syslinux API calls can generally only manipulate data +below address 0x100000, a "bounce buffer" in low memory, at least 64K +in size, is available, to copy data in and out. + +The farcall helper function behaves similarly, but takes as its first +argument the CS:IP (in the form (CS << 16) + IP) of procedure to be +invoked via a FAR CALL. + +The cfarcall helper function takes (CS << 16)+IP, a pointer to a stack +frame, a size of that stack frame, and returns the return value of EAX +(which may need to be appropriate truncated by the user.) + +Starting in version 4.00, some of these API calls are available as +protected-mode function calls, using the regparm(3) calling convention +(the first three argumetns in EAX, EDX, ECX; the rest on the stack.) +Those functions are defined in struct com32_pmapi, defined in +<syslinux/pmapi.h>. + + + ++++ SYSLINUX API CALLS +++ + +Syslinux provides the following API calls. Syslinux 1.xx only +supported INT 20h - terminate program. [] indicates the first version +of Syslinux which supported this feature (correctly.) + +NOTE: Most of the API functionality is still experimental. Expect to +find bugs. + + + ++++ DOS-COMPATIBLE API CALLS ++++ + +INT 20h [1.48] Terminate program +INT 21h AH=00h [2.00] Terminate program +INT 21h AH=4Ch [2.00] Terminate program + + All of these terminate the program. + + +INT 21h AH=01h [2.01] Get Key with Echo + + Reads a key from the console input, with echo to the console + output. The read character is returned in AL. Extended + characters received from the keyboard are returned as NUL (00h) + + the extended character code. + + +INT 21h AH=02h [2.01] Write Character + + Writes a character in DL to the console (video and serial) + output. + + +INT 21h AH=04h [2.01] Write Character to Serial Port + + Writes a character in DL to the serial console output + (if enabled.) If no serial port is configured, this routine + does nothing. + + +INT 21h AH=08h [2.09] Get Key without Echo + + Reads a key fron the console input, without echoing it to the + console output. The read character is returned in AL. + + +INT 21h AH=09h [2.01] Write DOS String to Console + + Writes a DOS $-terminated string in DS:DX to the console. + + +INT 21h AH=0Bh [2.00] Check Keyboard + + Returns AL=FFh if there is a keystroke waiting (which can then + be read with INT 21h, AH=01h or AH=08h), otherwise AL=00h. + + +INT 21h AH=30h [2.00] Check DOS Version + + This function returns AX=BX=CX=DX=0, corresponding to a + hypothetical "DOS 0.0", but the high parts of EAX-EBX-ECX-EDX + spell "SYSLINUX": + + EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h + + This function can thus be used to distinguish running on + Syslinux from running on DOS. + + + ++++ SYSLINUX-SPECIFIC API CALLS ++++ + +Syslinux-specific API calls are executed using INT 22h, with a +function number in AX. INT 22h is used by DOS for internal purposes; +do not execute INT 22h under DOS. + +DOS-compatible function INT 21h, AH=30h can be used to detect if the +Syslinux API calls are available. + +Any register not specifically listed as modified is preserved; +however, future versions of Syslinux may add additional output +registers to existing calls. + +All calls return CF=0 on success, CF=1 on failure. The noted outputs +apply if CF=0 only unless otherwise noted. All calls clobber the +arithmetric flags (CF, PF, AF, ZF, SF and OF) but leave all other +flags unchanged unless otherwise noted. + + +AX=0001h [2.00] Get Version + + Input: AX 0001h + Output: AX number of INT 22h API functions available + CH Syslinux major version number + CL Syslinux minor version number + DL Syslinux derivative ID (e.g. 32h = PXELINUX) + ES:SI Syslinux version string + ES:DI Syslinux copyright string + + This API call returns the Syslinux version and API + information. + + Note: before version 3.86, the version string had a leading CR LF + and the copyright string had a leading space. The strings might + still contain trailing CR and/or LF. + + +AX=0002h [2.01] Write String + + Input: AX 0002h + ES:BX null-terminated string + Output: None + + Writes a null-terminated string on the console. + + +AX=0003h [2.01] Run command + + Input: AX 0003h + ES:BX null-terminated command string + Output: Does not return + + This API call terminates the program and executes the command + string as if the user had entered it at the Syslinux command + line. This API call does not return. + + +AX=0004h [2.01] Run default command + + Input: AX 0004h + Output: Does not return + + This API call terminates the program and executes the default + command string as if the user had pressed Enter alone on the + Syslinux command line. This API call does not return. + + +AX=0005h [2.00] Force text mode + + Input: AX 0005h + Output: None + + If the screen was in graphics mode (due to displaying a splash + screen using the <Ctrl-X> command in a message file, or + similar), return to text mode. + + +AX=0006h [2.08] Open file + + Input: AX 0006h + ES:SI null-terminated filename + Output: SI file handle + EAX length of file in bytes, or -1 + CX file block size + + Open a file for reading. The exact syntax of the filenames + allowed depends on the particular Syslinux derivative. + + The Syslinux file system is block-oriented. The size of a + block will always be a power of two and no greater than 16K. + + Note: Syslinux considers a zero-length file to be nonexistent. + + In 3.70 or later, EAX can contain -1 indicating that the file + length is unknown. + + 32-BIT VERSION: + + int cs_pm->open_file(const char *filename, struct com32_filedata *data) + + filename - null-terminated filename + data - pointer to a file data buffer + + Returns the file handle, or -1 on failure. + The file data buffer contains block size and file size. + + +AX=0007h [2.08] Read file + + Input: AX 0007h + SI file handle + ES:BX buffer + CX number of blocks to read + Output: SI file handle, or 0 if EOF was reached + ECX number of bytes read [3.70] + + Read blocks from a file. Note that the file handle that is + returned in SI may not be the same value that was passed in. + + If end of file was reached (SI=0), the file was automatically + closed. + + In 3.70 or later, ECX returns the number of bytes read. This + will always be a multiple of the block size unless EOF is + reached. + + The address of the buffer (ES:BX) should be at least 512-byte + aligned. Syslinux guarantees at least this alignment for the + COMBOOT load segment or the COM32 bounce buffer. + + Keep in mind that a "file" may be a TFTP connection, and that + leaving a file open for an extended period of time may result + in a timeout. + + WARNING: Calling this function with an invalid file handle + will probably crash the system. + + 32-BIT VERSION: + + size_t cs_pm->read_file(uint16_t *handle, void *buf, size_t blocks) + + handle - file handle (input and output, set to zero on end of file) + buf - buffer to write to + blocks - number of blocks to read + + Returns number of bytes read, or 0 on failure. + + +AX=0008h [2.08] Close file + + Input: AX 0008h + SI file handle + Output: None + + Close a file before reaching the end of file. + + WARNING: Calling this function with an invalid file handle + will probably crash the system. + + 32-BIT VERSION: + + void cs_pm->close_file(uint16_t handle) + + handle - file handle to close + + +AX=0009h [2.00] Call PXE Stack [PXELINUX ONLY] + + Input: AX 0009h + BX PXE function number + ES:DI PXE parameter structure buffer + Output: AX PXE return status code + + Invoke an arbitrary PXE stack function. On SYSLINUX/ISOLINUX, + this function returns with an error (CF=1) and no action is + taken. On PXELINUX, this function always returns with CF=0 + indicating that the PXE stack was successfully invoked; check + the status code in AX and in the first word of the data buffer + to determine if the PXE call succeeded or not. + + The PXE stack will have the UDP stack OPEN; if you change that + you cannot call any of the file-related API functions, and + must restore UDP OPEN before returning to PXELINUX. + + PXELINUX reserves UDP port numbers from 49152 to 65535 for its + own use; port numbers below that range is available. + + +AX=000Ah [2.00] Get Derivative-Specific Information + + [SYSLINUX, EXTLINUX] + Input: AX 000Ah + CL 9 (to get a valid return in CL for all versions) + Output: AL 31h (SYSLINUX), 34h (EXTLINUX) + DL drive number + CL sector size as a power of 2 (9 = 512 bytes) [3.35] + CH mode [3.73] + 1 = CBIOS mode + 2 = EBIOS mode + ES:BX pointer to partition table entry (if DL >= 80h) + FS:SI pointer to initial ES:DI value [3.53] + GS:DI pointer to partition offset (QWORD) [4.00] + + Note: This function was broken in EXTLINUX 3.00-3.02. + + On boot, ES:DI is supposed to point to the BIOS $PnP + structure, although in practice most operating systems + will search for it in memory. However, preserving + this while chainloading is probably a good idea. + + Note that FS:SI is a pointer to a memory location + containing the original ES:DI value, not the value + itself. + + + [PXELINUX] + Input: AX 000Ah + Output: AL 32h (PXELINUX) + DX PXE API version detected (DH=major, DL=minor) + ECX Local IP number (network byte order) [3.85] + ES:BX pointer to PXENV+ or !PXE structure + FS:SI pointer to original stack with invocation record + GS:DI pointer to network information [4.00] + + Note: DX notes the API version detected by PXELINUX, + which may be more conservative than the actual version + available. For exact information examine the API + version entry in the PXENV+ structure, or the API + version entries in the ROMID structures pointed from + the !PXE structure. + + PXELINUX will use, and provide, the !PXE structure + over the PXENV+ structure. Examine the structure + signature to determine which particular structure was + provided. + + The FS:SI pointer points to the top of the original stack + provided by the PXE stack, with the following values + pushed at the time PXELINUX is started: + + [fs:si+0] GS <- top of stack + [fs:si+2] FS + [fs:si+4] ES + [fs:si+6] DS + [fs:si+8] EDI + [fs:si+12] ESI + [fs:si+16] EBP + [fs:si+20] - + [fs:si+24] EBX + [fs:si+28] EDX + [fs:si+32] ECX + [fs:si+36] EAX + [fs:si+40] EFLAGS + [fs:si+44] PXE return IP <- t.o.s. when PXELINUX invoked + [fs:si+46] PXE return CS + + GS:DI points to a structure of the following form: + + [gs:di+0] 4 - IPv4 + [gs:di+4] My IP + [gs:di+8] Boot server IP + [gs:di+12] Gateway IP + [gs:di+16] Netmask + + [ISOLINUX] + Input: AX 000Ah + Output: AL 33h (ISOLINUX) + DL drive number + CL 11 (sector size as a power of 2) [3.35] + CH mode [3.73] + 0 = El Torito + 1 = Hybrid (hard disk), CBIOS mode + 2 = Hybrid (hard disk), EBIOS mode + ES:BX pointer to El Torito spec packet + FS:SI pointer to initial ES:DI value [3.53] + GS:DI pointer to partition offset (QWORD) [4.00] + + Note: Some very broken El Torito implementations do + not provide the spec packet information. If so, ES:BX + may point to all zeroes or to garbage. Call INT 13h, + AX=4B01h to obtain the spec packet directly from the + BIOS if necessary. + + +AX=000Bh [2.00] Get Serial Console Configuration + + Input: AX 000Bh + Output: DX serial port I/O base (e.g. 3F8h = COM1...) + CX baud rate divisor (1 = 115200 bps, 2 = 57600 bps...) + BX flow control configuration bits (see syslinux.txt) + -> bit 15 is set if the video console is disabled + + If no serial port is configured, DX will be set to 0 and the + other registers are undefined. + + +AX=000Ch [2.00] Perform final cleanup + Input: AX 000Ch + DX derivative-specific flags (0000h = clean up all) + Output: None + + This routine performs any "final cleanup" the boot loader + would normally perform before loading a kernel, such as + unloading the PXE stack in the case of PXELINUX. AFTER + INVOKING THIS CALL, NO OTHER API CALLS MAY BE INVOKED, NOR MAY + THE PROGRAM TERMINATE AND RETURN TO THE BOOT LOADER. This + call basically tells the boot loader "get out of the way, I'll + handle it from here." + + For COM32 images, the boot loader will continue to provide + interrupt and BIOS call thunking services as long its memory + areas (0x0800-0xffff, 0x100000-0x100fff) are not overwritten. + MAKE SURE TO DISABLE INTERRUPTS, AND INSTALL NEW GDT AND IDTS + BEFORE OVERWRITING THESE MEMORY AREAS. + + The permissible values for DX is an OR of these values: + + SYSLINUX: 0000h Normal cleanup + + PXELINUX: 0000h Normal cleanup + 0003h Keep UNDI and PXE stacks loaded + + ISOLINUX: 0000h Normal cleanup + + EXTLINUX: 0000h Normal cleanup + + All other values are undefined, and may have different + meanings in future versions of Syslinux. + + +AX=000Dh [2.08] Cleanup and replace bootstrap code + Input: AX 000Dh + DX derivative-specific flags (see previous function) + EDI bootstrap code (linear address, can be in high memory) + ECX bootstrap code length in bytes (must fit in low mem) + EBX(!) initial value of EDX after bootstrap + ESI initial value of ESI after bootstrap + DS initial value of DS after bootstrap + Output: Does not return + + This routine performs final cleanup, then takes a piece of + code, copies it over the primary bootstrap at address 7C00h, + and jumps to it. This can be used to chainload boot sectors, + MBRs, bootstraps, etc. + + Normal boot sectors expect DL to contain the drive number, + and, for hard drives (DL >= 80h) DS:SI to contain a pointer to + the 16-byte partition table entry. The memory between + 600h-7FFh is available to put the partition table entry in. + + For PXELINUX, if the PXE stack is not unloaded, all registers + (except DS, ESI and EDX) and the stack will be set up as they + were set up by the PXE ROM. + + +AX=000Eh [2.11] Get configuration file name + Input: AX 0000Eh + Output: ES:BX null-terminated file name string + + Returns the name of the configuration file. Note that it is + possible that the configuration file doesn't actually exist. + + +AX=000Fh [3.00] Get IPAPPEND strings [PXELINUX] + Input: AX 000Fh + Output: CX number of strings (currently 2) + ES:BX pointer to an array of NEAR pointers in + the same segment, one for each of the above + strings + + Returns the same strings that the "ipappend" option would have + added to the command line, one for each bit of the "ipappend" + flag value, so entry 0 is the "ip=" string and entry 1 is the + "BOOTIF=" string. + + +AX=0010h [3.00] Resolve hostname [PXELINUX] + Input: AX 0010h + ES:BX pointer to null-terminated hostname + Output: EAX IP address of hostname (zero if not found) + + Queries the DNS server(s) for a specific hostname. If the + hostname does not contain a dot (.), the local domain name + is automatically appended. + + This function only return CF=1 if the function is not + supported. If the function is supported, but the hostname did + not resolve, it returns with CF=0, EAX=0. + + The IP address is returned in network byte order, i.e. if the + IP address is 1.2.3.4, EAX will contain 0x04030201. Note that + all uses of IP addresses in PXE are also in network byte order. + + +AX=0011h [3.05] Obsoleted in 3.80 + + +AX=0012h [3.50] Cleanup, shuffle and boot + Input: AX 0012h + DX derivative-specific flags (see function 000Ch) + ES:DI shuffle descriptor list (must be in low memory) + CX number of shuffle descriptors + EBX(!) initial value of EDX after bootstrap + ESI initial value of ESI after bootstrap + DS initial value of DS after bootstrap + EBP CS:IP of routine to jump to + Output: Does not return + (if CX is too large the routine returns with CF=1) + + This routine performs final cleanup, then performs a sequence + of copies, and jumps to a specified real mode entry point. + This is a more general version of function 000Dh, which can + also be used to load other types of programs. + + The copies must not touch memory below address 7C00h. + + ES:DI points to a list of CX descriptors each of the form: + + Offset Size Meaning + 0 dword destination address + 4 dword source address + 8 dword length in bytes + + The copies are overlap-safe, like memmove(). + + Starting in version 3.50, if the source address is -1 + (FFFFFFFFh) then the block specified by the destination + address and the length is set to all zero. + + Starting in version 3.50, if the destination address is -1 + (FFFFFFFFh) then the data block is loaded as a new set of + descriptors, and processing is continued (and unprocessed + descriptors are lost, this is thus typically only used as the + last descriptor in a block.) The block must still fit in the + internal descriptor buffer (see function 0011h), but can, of + course, itself chain another block. + + + Normal boot sectors expect DL to contain the drive number, + and, for hard drives (DL >= 80h) DS:SI to contain a pointer to + the 16-byte partition table entry. The memory between + 600h-7FFh is available to put the partition table entry in. + + For PXELINUX, if the PXE stack is not unloaded, all registers + (except DS, ESI and EDX) and the stack will be set up as they + were set up by the PXE ROM. + + This interface was probably broken before version 3.50. + + +AX=0013h [3.08] Idle loop call + Input: AX 0013h + Output: None + + Call this routine while sitting in an idle loop. It performs + any periodic activities required by the filesystem code. At + the moment, this is a no-op on all derivatives except + PXELINUX, where it executes PXE calls to answer ARP queries. + + Starting with version 3.10, this API call harmlessly returns + failure (CF=1) if invoked on a platform which does not need + idle calls. Additionally, it's safe to call this API call on + previous Syslinux versions (2.00 or later); it will just + harmlessly fail. Thus, if this call returns failure (CF=1), + it means that there is no technical reason to call this + function again, although doing so is of course safe. + + +AX=0014h [3.10] Local boot [PXELINUX, ISOLINUX] + Input: AX 0014h + DX Local boot parameter + Output: Does not return + + This function invokes the equivalent of the "localboot" + configuration file option. The parameter in DX is the same + parameter as would be entered after "localboot" in the + configuration file; this parameter is derivative-specific -- + see syslinux.txt for the definition. + + +AX=0015h [3.10] Get feature flags + Input: AX 0015h + Output: ES:BX pointer to flags in memory + CX number of flag bytes + + This function reports whether or not this Syslinux version and + derivative supports specific features. Keep in mind that + future versions might have more bits; remember to treat any + bits beyond the end of the array (as defined by the value in + CX) as zero. + + Currently the following feature flag is defined: + + Byte Bit Definition + ---------------------------------------------------- + 0 0 Local boot (AX=0014h) supported + 1 Idle loop call (AX=0013h) is a no-op + + All other flags are reserved. + + +AX=0016h [3.10] Run kernel image + Input: AX 0016h + DS:SI Filename of kernel image (zero-terminated string) + ES:BX Command line (zero-terminated string) + ECX IPAPPEND flags [PXELINUX] + EDX Type of file (since 3.50) + Output: Does not return if successful; returns with CF=1 if + the kernel image is not found. + + This function is similiar to AX=0003h Run command, except that + the filename and command line are treated as if specified in a + KERNEL and APPEND statement of a LABEL statement, which means: + + - The filename has to be exact; no variants are tried; + - No global APPEND statement is applied; + - ALLOWOPTIONS and IMPLICIT statements in the configuration + file do not apply. It is therefore important that the + COMBOOT module doesn't allow the end user to violate the + intent of the administrator. + + Additionally, this function returns with a failure if the file + doesn't exist, instead of returning to the command line. (It + may still return to the command line if the image is somehow + corrupt, however.) + + The file types are defined as follows: + + Equivalent + EDX Config Extensions Type of file + 0 KERNEL Determined by filename extension + 1 LINUX none Linux kernel image + 2 BOOT .bs .bin Bootstrap program + 3 BSS .bss Boot sector with patch [SYSLINUX] + 4 PXE .0 PXE Network Bootstrap Prog [PXELINUX] + 5 FDIMAGE .img Floppy disk image [ISOLINUX] + 6 COMBOOT .com .cbt 16-bit COMBOOT program + 7 COM32 .c32 COM32 program + 8 CONFIG Configuration file + + +AX=0017h [3.30] Report video mode change + Input: AX 0017h + BX Video mode flags + Bit 0: graphics mode + Bit 1: non-default mode + Bit 2: VESA mode + Bit 3: text functions not supported + CX For graphics modes, pixel columns + DX For graphics modes, pixel rows + Output: None + + This function is used to report video mode changes to + Syslinux. It does NOT actually change the video mode, but + rather, allows Syslinux to take appropriate action in response + to a video mode change. Modes that cannot be exited either + with the conventional BIOS mode set command (INT 10h, AH=00h) + or the VESA VBE mode set command (INT 10h, AX=4F02h) should + not be used. + + This function returns with a failure if BX contains any bits + which are undefined in the current version of Syslinux. + + The following bits in BX are currently defined: + + Bit 0: graphics mode + + Indicates that the mode is a graphics mode, as opposed + to a text mode. + + Bit 1: non-standard mode + + A non-standard mode is any mode except text mode and + graphics mode 0012h (VGA 640x480, 16 color.) + + Bit 2: VESA mode + + This mode is a VESA mode, and has to be exited with + the VESA VBE API (INT 10h, AX=4F02h) as opposed to the + conventional BIOS API (INT 10h, AH=00h). + + Bit 3: Text functions not supported + + This indicates that the BIOS text output functions + (INT 10h, AH=02h, 03h, 06h, 09h, 0Eh, 11h) don't work. + If this bit is set, Syslinux will reset the mode + before printing any characters on the screen. + + This is common for VESA modes. + + +AX=0018h [3.30] Query custom font + Input: AX 0018h + Output: AL Height of custom font in scan lines, or zero + ES:BX Pointer to custom font in memory + + This call queries if a custom display font has been loaded via + the "font" configuration file command. If no custom font has + been loaded, AL contains zero. + + +AX=0019h [3.50] Read disk [SYSLINUX, ISOLINUX, EXTLINUX] + Input: AX 0019h + EDX Sector number (LSW) + ESI Sector number (MSW) [4.00] + EDI Reserved - MUST BE ZERO + CX Sector count + ES:BX Buffer address + Output: None + + Read disk blocks from the active filesystem (partition); for + disks, sector number zero is the boot sector. For ISOLINUX, + this call reads the CD-ROM. + + For compatiblity with all systems, the buffer should + *neither* cross 64K boundaries, *nor* wrap around the segment. + + This routine reports "boot failed" (and does not return) on + disk error. + + Note: for ISOLINUX in hybrid mode, this call uses simulated + 2048-byte CD-ROM sector numbers. + + +AX=001Ah [3.50] Obsoleted in 3.80 + + +AX=001Bh [3.50] Obsoleted in 3.80 + + +AX=001Ch [3.60] Get pointer to auxilliary data vector + Input: AX 001Ch + Output: ES:BX Auxilliary data vector + CX Size of the ADV (currently 500 bytes) + + The auxillary data vector is a tagged data structure used + to carry a small amount of information (up to 500 bytes) from + one boot to another. + + +AX=001Dh [3.60] Write auxilliary data vector + Input: AX 001Dh + Output: None + + Write the auxilliary data vector back to disk. Returns + failure for non-disk-based derivatives unless the "auxdata" + configuration command is used to specify a disk location + (not yet implemented.) + + In a future version, PXELINUX may end up attempting to save + the ADV on the server via TFTP write. + + +AX=001Eh [3.74] Keyboard remapping table + Input: AX 001Eh + DX 0000h - all other values reserved + Output: AX format version (1) + CX length in bytes (256) + ES:BX pointer to keyboard table + + This call queries the keyboard remapping table. For the current + version, the format code is always 1 and the length is always + 256. This version can be updated simply by overwriting the version + in memory; this may not be true in the future. + + +AX=001Fh [3.74] Get current working directory + Input: AX 0001Fh + Output: ES:BX null-terminated directory name string + + Returns the current working directory. + + +AX=0020h [3.74] Obsoleted in 4.00 +AX=0021h [3.74] Obsoleted in 4.00 +AX=0022h [3.74] Obsoleted in 4.00 + + These three functions provided opendir/readdir/closedir + functionality in the late 3.xx series. They have been + replaced by the protected-mode interface. + + +AX=0023h [3.80] Get shuffler parameters + Input: AX 0023h + Output: CX size of shuffler "safe area" in bytes + Other registers reserved for future use + + This call gives the size of the required shuffler "safe area", + in bytes; for call 0024h. In the future, it may provide + additional parameters. + + +AX=0024h [3.80] Cleanup, shuffle and boot, raw version + Input: AX 0024h + DX derivative-specific flags (see function 000Ch) + EDI shuffle descriptor list safe area + ESI shuffle descriptor list source + ECX byte count of shuffle descriptor list + Output: Does not return + + This routine performs final cleanup, then performs a sequence + of copies, and jumps to a specified real mode entry point. + This is a more general version of function 000Dh, which can + also be used to load other types of programs. + + Unlike previous obsolete versions of this function, there are + no restrictions that copies must not touch memory below + address 7C00h. Either the shuffle descriptor list or the safe + area (or both) may be located in high memory. + + ESI points to a list of descriptors each of the form: + + Offset Size Meaning + 0 dword destination address + 4 dword source address (-1 = zero) + 8 dword length in bytes (0 = end of list) + + The copies are overlap-safe, like memmove(). + + Before actually executing the move list, the list is moved to + the address specified in EDI. The caller is responsibe to + ensure that the moved descriptor list plus a "safe area" + immediately afterwards (the size of which is specified by + function 0023h) is not disturbed by the copy sequence. It is, + however, safe to overwrite descriptors already consumed. + + If the source address is -1 (FFFFFFFFh) then the block + specified by the destination address and the length is set to + all zero. + + The list is terminated by an entry with length 0. For that + entry, the destination is used as an entry point, and the + source represents the type of entry point: + + 0 16-bit protected mode (dst is CS.base) + 1 Flat 32-bit protected mode (dst is EIP) + + This routine does not set up any GPR register state + whatsoever, including stack. It is the responsibility of the + caller to make sure the entry point provided sets up any + registers needed. + + For mode 0 (16-bit real mode), EAX will contain CR0 with bit 0 + masked out, suitable for loading into CR0 to immediately enter + real mode. Note: if real-mode entry is planned, + (CS.base & 0xfff0000f) should == 0 for compatibility with KVM, + and possibly other virtualization solutions. + + In both mode 0 and mode 1, the data segments will be loaded + with read/write data segments, matching the respective code + segment. For mode 0, B=0 and the limits will be 64K, for mode + 1, B=1 and the limits will be 4 GB. + + + ++++ 32-BIT ONLY API CALLS ++++ + +void *pm_cs->lmalloc(size_t bytes) + + Allocate a buffer in low memory (below 1 MB). + + +void pm_cs->lfree(void *ptr) + + Free a buffer allocated with pm_cs->lmalloc(). + + +DIR *pm_cs->opendir(const char *pathname) + + Open a directory. + + +struct dirent *pm_cs->readdir(DIR *dir) + + Read an entry from a directory. The entry is returned in a + static buffer. + + +int pm_cs->closedir(DIR *dir) + + Close a directory. diff --git a/contrib/syslinux-4.02/doc/distrib.txt b/contrib/syslinux-4.02/doc/distrib.txt new file mode 100644 index 0000000..fa10a04 --- /dev/null +++ b/contrib/syslinux-4.02/doc/distrib.txt @@ -0,0 +1,29 @@ +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 diff --git a/contrib/syslinux-4.02/doc/extlinux.txt b/contrib/syslinux-4.02/doc/extlinux.txt new file mode 100644 index 0000000..6974a51 --- /dev/null +++ b/contrib/syslinux-4.02/doc/extlinux.txt @@ -0,0 +1,132 @@ +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. + + +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. + diff --git a/contrib/syslinux-4.02/doc/gpt.txt b/contrib/syslinux-4.02/doc/gpt.txt new file mode 100644 index 0000000..0909932 --- /dev/null +++ b/contrib/syslinux-4.02/doc/gpt.txt @@ -0,0 +1,69 @@ + 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. diff --git a/contrib/syslinux-4.02/doc/isolinux.txt b/contrib/syslinux-4.02/doc/isolinux.txt new file mode 100644 index 0000000..eca2a97 --- /dev/null +++ b/contrib/syslinux-4.02/doc/isolinux.txt @@ -0,0 +1,133 @@ + 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. + + + ++++ BOOTING DOS (OR OTHER SIMILAR OPERATING SYSTEMS) ++++ + +WARNING: This feature depends on BIOS functionality which is +apparently broken in a very large number of BIOSes. Therefore, this +may not work on any particular system. No workaround is possible; if +you find that it doesn't work please complain to your vendor and +indicate that "BIOS INT 13h AX=4C00h fails." + +To boot DOS, or other real-mode operating systems (protected-mode +operating systems may or may not work correctly), using ISOLINUX, you +need to prepare a disk image (usually a floppy image, but a hard disk +image can be used on *most* systems) with the relevant operating +system. This file should be included on the CD-ROM in the /isolinux +directory, and have a .img extension. The ".img" extension does not +have to be specified on the command line, but has to be explicitly +specified if used in a "kernel" statement in isolinux.cfg. + +For a floppy image, the size of the image should be exactly one of the +following: + + 1,228,800 bytes - For a 1200K floppy image + 1,474,560 bytes - For a 1440K floppy image + 2,949,120 bytes - For a 2880K floppy image + +Any other size is assumed to be a hard disk image. In order to work +on as many systems as possible, a hard disk image should have exactly +one partition, marked active, that covers the entire size of the disk +image file. Even so, hard disk images are not supported on all +BIOSes. diff --git a/contrib/syslinux-4.02/doc/keytab-lilo.txt b/contrib/syslinux-4.02/doc/keytab-lilo.txt new file mode 100644 index 0000000..cdbea0f --- /dev/null +++ b/contrib/syslinux-4.02/doc/keytab-lilo.txt @@ -0,0 +1,85 @@ +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 diff --git a/contrib/syslinux-4.02/doc/mboot.txt b/contrib/syslinux-4.02/doc/mboot.txt new file mode 100644 index 0000000..ef00ca5 --- /dev/null +++ b/contrib/syslinux-4.02/doc/mboot.txt @@ -0,0 +1,26 @@ + +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 diff --git a/contrib/syslinux-4.02/doc/memdisk.txt b/contrib/syslinux-4.02/doc/memdisk.txt new file mode 100644 index 0000000..fecf2dc --- /dev/null +++ b/contrib/syslinux-4.02/doc/memdisk.txt @@ -0,0 +1,292 @@ +[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) + + +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. diff --git a/contrib/syslinux-4.02/doc/menu.txt b/contrib/syslinux-4.02/doc/menu.txt new file mode 100644 index 0000000..e2dd1e1 --- /dev/null +++ b/contrib/syslinux-4.02/doc/menu.txt @@ -0,0 +1,566 @@ +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 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. diff --git a/contrib/syslinux-4.02/doc/pxelinux.txt b/contrib/syslinux-4.02/doc/pxelinux.txt new file mode 100644 index 0000000..47aea90 --- /dev/null +++ b/contrib/syslinux-4.02/doc/pxelinux.txt @@ -0,0 +1,418 @@ + 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. + + + ++++ 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.) diff --git a/contrib/syslinux-4.02/doc/rfc5071.txt b/contrib/syslinux-4.02/doc/rfc5071.txt new file mode 100644 index 0000000..68f6f5a --- /dev/null +++ b/contrib/syslinux-4.02/doc/rfc5071.txt @@ -0,0 +1,787 @@ + + + + + + +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] + diff --git a/contrib/syslinux-4.02/doc/sdi.txt b/contrib/syslinux-4.02/doc/sdi.txt new file mode 100644 index 0000000..cf9b73f --- /dev/null +++ b/contrib/syslinux-4.02/doc/sdi.txt @@ -0,0 +1,149 @@ + 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. diff --git a/contrib/syslinux-4.02/doc/syslinux.txt b/contrib/syslinux-4.02/doc/syslinux.txt new file mode 100644 index 0000000..51d1332 --- /dev/null +++ b/contrib/syslinux-4.02/doc/syslinux.txt @@ -0,0 +1,788 @@ + The Syslinux Project + + A suite of bootloaders for Linux + + Copyright 1994-2010 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 the configurable defaults in SYSLINUX can be changed by putting a +file called "syslinux.cfg" in the root directory of the boot disk. + +This is a text file in either UNIX or DOS format, containing one or +more of the following items (case is insensitive for keywords; upper +case is used here to indicate that a word should be typed verbatim): + +Starting with version 3.35, the configuration file can also be in +either the /boot/syslinux or /syslinux directories (searched in that +order.) If that is the case, then all filenames are assumed to be +relative to that same directory, unless preceded with a slash or +backslash. + +All options here applies to PXELINUX, ISOLINUX and EXTLINUX as well as +SYSLINUX unless otherwise noted. See the respective .txt files. + +# comment + A comment line. The whitespace after the hash mark is mandatory. + +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. + + APPEND - + Append nothing. APPEND with a single hyphen as argument in a + LABEL section can be used to override a global APPEND. + + LOCALBOOT type [ISOLINUX, PXELINUX] + On PXELINUX, specifying "LOCALBOOT 0" instead of a "KERNEL" + option means invoking this particular label will cause a local + disk boot instead of booting a kernel. + + The argument 0 means perform a normal boot. The argument 4 + will perform a local boot with the Universal Network Driver + Interface (UNDI) driver still resident in memory. Finally, + the argument 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. The special value -1 causes ISOLINUX to + report failure to the BIOS, which, on recent BIOSes, should + mean that the next boot device in the boot sequence should be + activated. + + 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. diff --git a/contrib/syslinux-4.02/doc/usbkey.txt b/contrib/syslinux-4.02/doc/usbkey.txt new file mode 100644 index 0000000..33613d6 --- /dev/null +++ b/contrib/syslinux-4.02/doc/usbkey.txt @@ -0,0 +1,47 @@ +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. |