-I don't have specific submission guidelines for SYSLINUX, but the ones
+I don't have specific submission guidelines for Syslinux, but the ones
that appropriate to the Linux kernel are certainly good enough for
-SYSLINUX.
+Syslinux.
In particular, however, I appreciate if patches sent follow the
standard Linux submission format, as I can automatically import them
COMBOOT and COM32 files
-SYSLINUX supports simple standalone programs, using a file format
+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.
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
+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:
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.
+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
+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.
+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
+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.
int (*__cfarcall)(uint32_t, void *, size_t)
);
-The intcall helper function can be used to issue BIOS or SYSLINUX API
+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>):
instance of the same structure. The third argument can also be zero
(NULL).
-Since BIOS or SYSLINUX API calls can generally only manipulate data
+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.
++++ SYSLINUX API CALLS +++
-SYSLINUX provides the following API calls. SYSLINUX 1.xx only
+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.)
+of Syslinux which supported this feature (correctly.)
NOTE: Most of the API functionality is still experimental. Expect to
find bugs.
EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h
This function can thus be used to distinguish running on
- SYSLINUX from running on DOS.
+ Syslinux from running on DOS.
++++ SYSLINUX-SPECIFIC API CALLS ++++
-SYSLINUX-specific API calls are executed using INT 22h, with a
+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.
+Syslinux API calls are available.
Any register not specifically listed as modified is preserved;
-however, future versions of SYSLINUX may add additional output
+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
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
+ 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
+ This API call returns the Syslinux version and API
information.
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
+ string as if the user had entered it at the Syslinux command
line. This API call 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.
+ Syslinux command line. This API call does not return.
AX=0005h [2.00] Force text mode
CX file block size
Open a file for reading. The exact syntax of the filenames
- allowed depends on the particular SYSLINUX derivative.
+ allowed depends on the particular Syslinux derivative.
- The SYSLINUX file system is block-oriented. The size of a
+ 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.
+ Note: Syslinux considers a zero-length file to be nonexistent.
In 3.70 or later, EAX can contain -1 indicating that the file
length is unknown.
reached.
The address of the buffer (ES:BX) should be at least 512-byte
- aligned. SYSLINUX guarantees at least this alignment for the
+ 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
AX=4B01h to obtain the spec packet directly from the
BIOS if necessary.
- This call gives information specific to a particular SYSLINUX
+ 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.
EXTLINUX: 0000h Normal cleanup
All other values are undefined, and may have different
- meanings in future versions of SYSLINUX.
+ meanings in future versions of Syslinux.
AX=000Dh [2.08] Cleanup and replace bootstrap code
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
+ 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.
Output: ES:BX pointer to flags in memory
CX number of flag bytes
- This function reports whether or not this SYSLINUX version and
+ 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
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
+ 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.
+ which are undefined in the current version of Syslinux.
The following bits in BX are currently defined:
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
+ If this bit is set, Syslinux will reset the mode
before printing any characters on the screen.
This is common for VESA modes.
For creators of Linux distributions:
-SYSLINUX is a notoriously hard program to debug, since it runs outside
+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
+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.
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.
+Syslinux distribution, starting with version 1.42.
To rebuild the installer programs *only*, starting from a freshly
-untarred distribution copy of SYSLINUX, do:
+untarred distribution copy of Syslinux, do:
make clean
make installer
-EXTLINUX is a new syslinux derivative, which boots from a Linux
+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.
+It works the same way as SYSLINUX (see doc/syslinux.txt), with a few
+slight modifications.
1. The installer is run on a *mounted* filesystem. Run the extlinux
installer on the directory in which you want extlinux installed:
extlinux --once 'command' /boot/extlinux
- where 'command' is any command you could enter at the SYSLINUX
+ where 'command' is any command you could enter at the Syslinux
command line. It will be executed on the next boot and then
erased.
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.
+partition table; the mbr.bin shipped with Syslinux should work well.
To install it just do:
cat mbr.bin > /dev/XXX
filesystem.
-The SYSLINUX series boot loaders support chain loading other operating
-systems via a separate module, chain.c32 (located in
+The Syslinux Project boot loaders support chain loading other
+operating systems via a separate module, chain.c32 (located in
com32/modules/chain.c32). To use it, specify a LABEL in the
-configuration file with KERNEL chain.c32 and
-APPEND [hd|fd]<number> [<partition>]
+configuration file with KERNEL chain.c32 and APPEND [hd|fd]<number>
+[<partition>]
For example:
KERNEL chain.c32
APPEND hd0 2
-See also README.menu.
+See also doc/menu.txt.
+
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
+To use a LILO keyboard table with Syslinux, specify the KBDMAP command
in syslinux.cfg, for example:
kbdmap de.ktl
mboot.c32
---------
-mboot.c32 is a 32-bit comboot module that allows SYSLINUX and its
+mboot.c32 is a 32-bit comboot module that allows Syslinux and its
variants to load and boot kernels that use the Multiboot standard
(e.g. the Xen virtual machine monitor, and the Fiasco and GNU Mach
microkernels).
-To load a multiboot kernel and modules in SYSLINUX, put mboot.c32 (from
+To load a multiboot kernel and modules in Syslinux, put mboot.c32 (from
com32/modules) in the boot directory, and load it as the "kernel" in the
configuration file. The command-line to pass to mboot.c32 is the kernel
command-line, followed by all the module command lines, separated with
KERNEL mboot.c32
APPEND xen.gz dom0_mem=15000 nosmp noacpi --- linux.gz console=tty0 root=/dev/hda1 --- initrd.img
-mboot.c32 requires version 2.12 or later of SYSLINUX.
+mboot.c32 requires version 2.12 or later of Syslinux.
Tim Deegan, May 2005
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:
+To use it, type on the Syslinux command line:
memdisk initrd=diskimg.img
-There are two menu systems included with SYSLINUX, the advanced menu
+There are two menu systems included with Syslinux, the advanced menu
system, and 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.
+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
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
+the keywords MENU or TEXT; like the rest of the Syslinux config file
language, it is case insensitive:
MENU TITLE title
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
+ 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
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
+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.
----------------------------------------------------------------------
-PXELINUX is a SYSLINUX derivative, for booting Linux off a network
+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
On the TFTP server, create the directory "/tftpboot", and copy the
following files to it:
- pxelinux.0 - from the SYSLINUX distribution
+ pxelinux.0 - from the Syslinux distribution
any kernel or initrd images you want to boot
:: 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
+special treatment of :: is a problem, please contact the Syslinux
mailing list.
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
+If you have additional problems, please contact the Syslinux mailing
list (see syslinux.txt for the address.)
SDI files
-PXELINUX, ISOLINUX and SYSLINUX support SDI files ( *.sdi ).
+Syslinux supports SDI files ( *.sdi ).
Features:
* Support for gzipped SDI images
- SYSLINUX
+ The Syslinux Project
A suite of bootloaders for Linux
----------------------------------------------------------------------
- SYSLINUX now has a home page at http://syslinux.zytor.com/
+ Syslinux now has a home page at http://syslinux.zytor.com/
----------------------------------------------------------------------
-The SYSLINUX suite contains the following boot loaders
+The Syslinux suite contains the following boot loaders
("derivatives"), for their respective boot media:
SYSLINUX - MS-DOS/Windows FAT filesystem
EXTLINUX - Linux ext2/ext3 filesystem
For historical reasons, some of the sections in this document applies
-to the FAT loader only; see pxelinux.txt, isolinux.txt and
-extlinux.txt for what differs in these versions.
+to the FAT loader (SYSLINUX) only; see pxelinux.txt, isolinux.txt and
+extlinux.txt for what differs in these versions. The all-caps term
+"SYSLINUX" generally refers to the FAT loader, whereas "Syslinux"
+refers to the project as a whole.
Help with cleaning up the docs would be greatly appreciated.
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.
+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
+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
+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.
will be supported in the future.
DEFAULT kernel options...
- Sets the default command line. If SYSLINUX boots automatically,
+ 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
+ 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
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
+ 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 = mylabel
append = "myoptions"
- ... whereas SYSLINUX uses the syntax:
+ ... whereas Syslinux uses the syntax:
label mylabel
kernel mykernel
append myoptions
foo bar baz
- ... SYSLINUX will execute the following as if entered by the
+ ... Syslinux will execute the following as if entered by the
user:
xyzzy plugh foo bar baz
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
+ 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.
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.
+version of Syslinux, but may break in a future one.
++++ DISPLAY FILE FORMAT ++++
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.
+ the text printed by Syslinux itself.
<EM> <EM> = <Ctrl-Y> = ASCII 25
If we are currently in graphics mode, return to text mode.
<Enter> boot specified command line
<BackSpace> erase one character
<Ctrl-U> erase the whole line
-<Ctrl-V> display the current SYSLINUX version
+<Ctrl-V> display the current Syslinux version
<Ctrl-W> erase one word
<Ctrl-X> force text mode
<F1>..<F10> help screens (if configured)
++++ COMBOOT IMAGES AND OTHER OPERATING SYSTEMS ++++
-This version of SYSLINUX supports chain loading of other operating
+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.
+have reliable magic numbers, Syslinux will look at the file extension.
The following extensions are recognized (case insensitive):
none or other Linux kernel image
.com COMBOOT image (runnable from DOS)
.img Disk image [ISOLINUX only]
-For filenames given on the command line, SYSLINUX will search for the
+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.
---- 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
+(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.
++++ COMBOOT EXECUTABLES ++++
-SYSLINUX supports simple standalone programs, using a file format
+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.
++++ NOVICE PROTECTION ++++
-SYSLINUX will attempt to detect booting on a machine with too little
+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.
++++ 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:
+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
++++ 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,
+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
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
+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: