aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2007-12-18 15:58:13 -0800
committerH. Peter Anvin <hpa@zytor.com>2007-12-18 15:58:13 -0800
commit808b03603854aede50b7ebd09129053ab4025113 (patch)
tree84f535337de360bb3fc644596678aea56d35c086 /doc
parentcbcc195e1ac4d7b4f4c3a37b51fa3c58db14269b (diff)
parent8fd5e917a23b6ba2d1bf9128be3524ca8cf8ab34 (diff)
downloadsyslinux-elf-808b03603854aede50b7ebd09129053ab4025113.tar.gz
syslinux-elf-808b03603854aede50b7ebd09129053ab4025113.tar.xz
syslinux-elf-808b03603854aede50b7ebd09129053ab4025113.zip
Merge commit 'origin/master' into advsyslinux-3.60-pre6
Diffstat (limited to 'doc')
-rw-r--r--doc/comboot.doc894
-rw-r--r--doc/distrib.doc29
-rw-r--r--doc/extlinux.doc130
-rw-r--r--doc/isolinux.doc109
-rw-r--r--doc/keytab-lilo.doc85
-rw-r--r--doc/memdisk.doc202
-rw-r--r--doc/menu.doc423
-rw-r--r--doc/pxelinux.doc416
-rw-r--r--doc/syslinux.doc736
-rw-r--r--doc/usbkey.doc47
10 files changed, 3071 insertions, 0 deletions
diff --git a/doc/comboot.doc b/doc/comboot.doc
new file mode 100644
index 00000000..a69bfc41
--- /dev/null
+++ b/doc/comboot.doc
@@ -0,0 +1,894 @@
+
+ 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.
+
+
+ ++++ COM32 file format ++++
+
+A COM32 file is a raw binary file containing 32-bit code. It should
+be linked to run at address 0x101000, and should not contain any
+segment references. 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.
+
+It is highly recommended that every COM32 program begins with the byte
+sequence B8 FF 4C CD 21 (mov eax,21cd4cffh) as a magic number.
+
+A COM32 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 COM32 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 5)
+ [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)
+
+This corresponds to the following C prototype, available in the file
+com32/include/com32.h:
+
+/* The standard prototype for _start() */
+int _start(unsigned int __nargs,
+ char *__cmdline,
+ void (*__intcall)(uint8_t, com32sys_t *, com32sys_t *),
+ void *__bounce_ptr,
+ unsigned int __bounce_len,
+ void (*__farcall)(uint32_t, com32sys_t *, com32sys_t *),
+ int (*__cfarcall)(uint32_t, void *, size_t)
+ );
+
+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.)
+
+
+ ++++ 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.
+
+
+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
+ 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.
+
+
+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
+
+ 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.
+
+ 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.
+
+
+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.
+
+
+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]
+ ES:BX pointer to partition table entry (if DL >= 80h)
+ FS:SI pointer to initial ES:DI value [3.53]
+
+ 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)
+ ES:BX pointer to PXENV+ or !PXE structure
+ FS:SI pointer to original stack with invocation record
+
+ 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
+
+
+ [ISOLINUX]
+ Input: AX 000Ah
+ Output: AL 33h (ISOLINUX)
+ DL drive number
+ CL 11 (sector size as a power of 2) [3.35]
+ ES:BX pointer to El Torito spec packet
+ FS:SI pointer to initial ES:DI value [3.53]
+
+ 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.
+
+ This call gives information specific to a particular SYSLINUX
+ derivative. The value returned in AL is the same as is
+ returned in DL by INT 22h AX=0001h.
+
+
+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.doc)
+ -> 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: 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] Maximum number of shuffle descriptors
+ Input: AX 0011h
+ Output: CX maximum number of descriptors
+
+ This routine reports the maximum number of shuffle descriptors
+ permitted in a call to function 0012h.
+
+ Typical values are 682 and 1365.
+
+
+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.doc 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
+ ESI Reserved - MUST BE ZERO
+ 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.
+
+
+AX=001Ah [3.50] Cleanup, shuffle and boot to flat protected mode
+ Input: AX 001Ah
+ DX derivative-specific flags (see function 000Ch)
+ ES:DI shuffle descriptor list (must be in low memory)
+ CX number of shuffle descriptors
+ DS:SI pointer to register values (must be in low memory)
+ 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 protected mode entry point.
+ This is otherwise similar to function 0012h; see that function
+ for the meaning of ES:DI and CX.
+
+ DS:SI points to the initial register file, which is a structure
+ of 9 dwords (available in <syslinux/bootpm.h>):
+
+ struct syslinux_pm_regs {
+ uint32_t eax; /* Offset 0 */
+ uint32_t ecx; /* Offset 4 */
+ uint32_t edx; /* Offset 8 */
+ uint32_t ebx; /* Offset 12 */
+ uint32_t esp; /* Offset 16 */
+ uint32_t ebp; /* Offset 20 */
+ uint32_t esi; /* Offset 24 */
+ uint32_t edi; /* Offset 28 */
+
+ uint32_t eip; /* Offset 32 */
+ };
+
+ Protected mode is entered with all data segments set up as a
+ flat 32-bit read/write segment and the code segment a flat 32-bit
+ read/execute segment. Interrupts and paging is off, CPL=0, DF=0;
+ however, GDT, LDT and IDT are undefined, so it is up to the
+ invoked code to set new descriptor tables to its liking.
+
+
+AX=001Bh [3.50] Cleanup, shuffle and boot to real mode
+ Input: AX 001Bh
+ DX derivative-specific flags (see function 000Ch)
+ ES:DI shuffle descriptor list (must be in low memory)
+ CX number of shuffle descriptors
+ DS:SI pointer to register values (must be in low memory)
+ 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 entry point.
+ This is similar to function 0012h but allow more control over
+ the initial register state; see that function for the meaning of
+ ES:DI and CX.
+
+ DS:SI points to the initial register file, which is a structure
+ in the following format (available in <syslinux/bootrm.h>;
+ note that this is a completely different structure from the
+ com32sys_t structure described at the top of this document!):
+
+ struct syslinux_rm_regs {
+ uint16_t es; /* Offset 0 */
+ uint16_t _unused_cs; /* Offset 2 */
+ uint16_t ds; /* Offset 4 */
+ uint16_t ss; /* Offset 6 */
+ uint16_t fs; /* Offset 8 */
+ uint16_t gs; /* Offset 10 */
+
+ reg32_t eax; /* Offset 12 */
+ reg32_t ecx; /* Offset 16 */
+ reg32_t edx; /* Offset 20 */
+ reg32_t ebx; /* Offset 24 */
+ reg32_t esp; /* Offset 28 */
+ reg32_t ebp; /* Offset 32 */
+ reg32_t esi; /* Offset 36 */
+ reg32_t edi; /* Offset 40 */
+
+ uint16_t ip; /* Offset 44 */
+ uint16_t cs; /* Offset 46 */
+ };
+
+ Interrupts are off and DF=0 on entry.
+
+
+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.
diff --git a/doc/distrib.doc b/doc/distrib.doc
new file mode 100644
index 00000000..5e71017d
--- /dev/null
+++ b/doc/distrib.doc
@@ -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/doc/extlinux.doc b/doc/extlinux.doc
new file mode 100644
index 00000000..2508fa1c
--- /dev/null
+++ b/doc/extlinux.doc
@@ -0,0 +1,130 @@
+EXTLINUX is a new syslinux derivative, which boots from a Linux
+ext2/ext3 filesystem.
+
+It works the same way as SYSLINUX, 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 now 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 -i /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 series 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 README.menu.
diff --git a/doc/isolinux.doc b/doc/isolinux.doc
new file mode 100644
index 00000000..fa261362
--- /dev/null
+++ b/doc/isolinux.doc
@@ -0,0 +1,109 @@
+ ISOLINUX
+
+ A bootloader for Linux using ISO 9660/El Torito CD-ROMs
+
+ Copyright (C) 1994-2003 H. Peter Anvin
+
+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.doc 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.
+
+YOU MAY WANT TO CONSIDER USING THE DEBUGGING VERSION BY DEFAULT.
+
+
+ ++++ 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.
+
+
+ ++++ 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/doc/keytab-lilo.doc b/doc/keytab-lilo.doc
new file mode 100644
index 00000000..df9a1d9f
--- /dev/null
+++ b/doc/keytab-lilo.doc
@@ -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/doc/memdisk.doc b/doc/memdisk.doc
new file mode 100644
index 00000000..759a7b27
--- /dev/null
+++ b/doc/memdisk.doc
@@ -0,0 +1,202 @@
+[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.
+
+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 one of the following sizes, it's assumed to be a
+ floppy image:
+
+ 368,640 bytes - 360K floppy
+ 737,280 bytes - 720K floppy
+ 1,222,800 bytes - 1200K floppy
+ 1,474,560 bytes - 1440K floppy
+ 1,720,320 bytes - 1680K floppy (common extended format)
+ 1,763,328 bytes - 1722K floppy (common extended format)
+ 2,949,120 bytes - 2880K floppy
+ 3,932,160 bytes - 3840K floppy (extended format)
+
+ For any other size, the image 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[**]
+
+ # 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.
+
+ safeint Use INT 15h access to protected memory, but invoke
+ INT 15h the way it was *before* MEMDISK was loaded.
+
+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
+
+
+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:
+
+ http://www.nu2.nu/eltorito/
+
+
+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 28 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 512-byte 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
+
+MEMDISK 3.00 and higher has the size of this structure as 27; earlier
+versions had size 26 and did not include the boot loader ID.
+
+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):
+
+ 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
diff --git a/doc/menu.doc b/doc/menu.doc
new file mode 100644
index 00000000..5fba0f2c
--- /dev/null
+++ b/doc/menu.doc
@@ -0,0 +1,423 @@
+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:
+
+DEFAULT menu.c32
+PROMPT 0
+
+
+There are a few menu additions to the command line, 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 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. If no
+ default is specified, use the first one.
+
+
+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, a SHA-1 encrypted password (starting with
+ $4$), or and MD5 encrypted password (starting with $1$).
+
+ 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. 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 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 640x480 pixels and either in PNG or JPEG
+ format.
+
+
+INCLUDE filename
+MENU INCLUDE filename
+
+ 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.
+
+
+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 second argument allows a different background
+ image (see MENU BACKGROUND for supported formats) to be displayed.
+
+
+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.
+
+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/doc/pxelinux.doc b/doc/pxelinux.doc
new file mode 100644
index 00000000..955a6079
--- /dev/null
+++ b/doc/pxelinux.doc
@@ -0,0 +1,416 @@
+ PXELINUX
+
+ A bootloader for Linux using the PXE network booting protocol
+
+ Copyright (C) 1994-2007 H. Peter Anvin
+
+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.doc 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.doc 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.
+
+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:
+
++ Requires a TFTP server which supports the "tsize" option.
++ 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.doc for the address.)
diff --git a/doc/syslinux.doc b/doc/syslinux.doc
new file mode 100644
index 00000000..17370739
--- /dev/null
+++ b/doc/syslinux.doc
@@ -0,0 +1,736 @@
+ SYSLINUX
+
+ A suite of bootloaders for Linux
+
+ Copyright (C) 1994-2007 H. Peter Anvin
+
+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 only; see pxelinux.doc, isolinux.doc and
+extlinux.doc for what differs in these versions.
+
+Help with cleaning up the docs would be greatly appreciated.
+
+
+ ++++ 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 [-sfma][-d directory] a:
+
+(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 [-sf][-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.
+
+On boot time, by default, the kernel will be loaded from the image named
+LINUX on the boot floppy. This default can be changed, see the section
+on the SYSLINUX config file.
+
+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 .doc 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, the default is "linux auto".
+
+ NOTE: Earlier versions of SYSLINUX used to automatically
+ append the string "auto" to whatever the user specified using
+ the DEFAULT command. As of version 1.54, this is no longer
+ true, as it caused problems when using a shell as a substitute
+ for "init." You may want to include this option manually.
+
+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.
+
+ THE USE OF THIS OPTION IS NOT RECOMMENDED. If you have to use
+ it, it is probably an indication that your network configuration
+ is broken. Using just "ip=dhcp" on the kernel command line
+ is a preferrable option, or, better yet, run dhcpcd/dhclient,
+ from an initrd if necessary.
+
+ 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.doc.)
+
+ This allows an initrd program to determine from which
+ interface the system booted.
+
+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 2.20, LABEL statements are compressed
+ internally, therefore the maximum number of LABEL statements
+ depends on their complexity. Typical is around 600. SYSLINUX
+ will print an error message if the internal memory for labels
+ is overrun.
+
+ 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.)
+
+ 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.
+
+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
+ 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.
+
+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.doc
+ 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.
+
+F1 filename
+F2 filename
+ ...etc...
+F9 filename
+F10 filename
+F11 filename
+F11 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
+ compatiblity 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
+<F1>..<F10> help screens (if configured)
+<Ctrl-F><digit> equivalent to F1..F10
+<Ctrl-C> interrupt boot in progress
+<Esc> interrupt boot in progress
+
+
+ ++++ 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.doc 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.doc 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.doc.
+
+
+ ++++ 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/doc/usbkey.doc b/doc/usbkey.doc
new file mode 100644
index 00000000..33613d69
--- /dev/null
+++ b/doc/usbkey.doc
@@ -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.