From 0404a7ab49ca60c225d497c4dd9699a9be433a2d Mon Sep 17 00:00:00 2001 From: hpa Date: Sat, 31 Jan 1998 13:27:53 +0000 Subject: [PATCH] Updated documentation --- Change.log => NEWS | 0 syslinux.doc | 507 ++++++++++++++++++++++++++--------------------------- 2 files changed, 252 insertions(+), 255 deletions(-) rename Change.log => NEWS (100%) diff --git a/Change.log b/NEWS similarity index 100% rename from Change.log rename to NEWS diff --git a/syslinux.doc b/syslinux.doc index 30f942b..0fe14df 100644 --- a/syslinux.doc +++ b/syslinux.doc @@ -1,255 +1,252 @@ - SYSLINUX - Version 1.30 - - A bootloader for Linux using MS-DOS floppies - - Copyright (C) 1994-96 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 is a boot loader for the Linux operating system which operates -off MS-DOS floppies. It is intended to simplify first-time installation -of Linux. It is *not* intended to be used as a general purpose boot -loader; once the operating system is installed I recommend LILO as the -boot loader, except for people whose root filesystem is a UMSDOS -filesystem (where a DOS defragmenter could wreck havoc with LILO's -carefully set up block tables) -- for them I recommend Loadlin (which -loads Linux from the DOS command line). - -SYSLINUX could, however, in conjunction with the UMSDOS filesystem, -completely eliminate the need for distribution of raw diskette images -for boot floppies. A SYSLINUX floppy can be manipulated using standard -MS-DOS (or any other OS that can access an MS-DOS filesystem) tools once -it has been created. - - ++++ 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 drive: - -This will alter the boot sector on the disk and copy a file named -LDLINUX.SYS into its root directory. - -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. - - ++++ 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 floppy. 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): - -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, except that the option "auto" is - automatically added, indicating an automatic boot. - - If no configuration file is present, or no DEFAULT entry is - present in the config file, the default is kernel name "linux", - with no options. - -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. - -LABEL label - KERNEL kernel - APPEND options... - - Indicates that if "label" is entered as the kernel to boot, - SYSLINUX should instead boot "kernel", and the specified APPEND - options should be used instead of the ones specified in the - global section of the file (before the first LABEL command.) - The default for "kernel" is the same as "label", and if no - APPEND is given the default is to use the global entry (if any). - Up to 16 LABEL entries are permitted. - - Note that LILO uses the syntax: - image = mykernel - label = mylabel - append = "myoptions" - - corresponding to the SYSLINUX: - label mylabel - kernel mykernel - append myoptions - - APPEND - - - Append nothing. APPEND with a single hyphen as argument in a - LABEL section can be used to override a global APPEND. - -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. - -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. - - NOTE: The maximum possible timeout value is 35996; corresponding to - just below one hour. - -DISPLAY filename - - Displays the indicated file on the screen at boot time (before - the boot: prompt, if displayed). This option takes the place of - the LINUXMSG.TXT and BOOTMSG.TXT files in SYSLINUX 1.0. Please - see the section below on DISPLAY files. - - NOTE: If the file is missing, this option is simply ignored. - -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. This - option takes the place of testing for the LINUXMSG.TXT file in - SYSLINUX 1.0. - -F1 filename -F2 filename - ...etc... -F9 filename -F0 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.) Note that F10 MUST be entered in the config file as - "F0", not "F10", and that there is currently no way to bind - file names to F11 and F12. Please see the section below on - DISPLAY files. - -Blank lines, and comment lines beginning with a hash mark (#) 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. - -The following combinations of options can be used to mimic the behaviour -of SYSLINUX 1.0 with LINUXMSG.TXT or BOOTMSG.TXT present, respectively: - -# Mimic SYSLINUX 1.0 with LINUXMSG.TXT file present: -display linuxmsg.txt -prompt 1 - -# Mimic SYSLINUX 1.0 with BOOTMSG.TXT file present: -display bootmsg.txt - - ++++ LARGE KERNELS AND INITIAL RAMDISK SUPPORT ++++ - -This version of SYSLINUX supports large kernels (bzImage format), -eliminating the 500K size limit of the zImage kernel format. bzImage -format kernels are detected automatically and handled transparently to -the user. - -This version of SYSLINUX also supports a boottime-loaded ramdisk -(initrd). An initrd is loaded from a DOS file if the option -"initrd=filename" (where filename is the filename of the initrd image; -the file must be located in the root directory on the boot floppy) is -present on the processed command line (after APPEND's have been added, -etc.). If several initrd options are present, the last one has -precedence; this permits user-entered options to override a config -file APPEND. Specifying "initrd=" without a filename inhibits initrd -loading. The file specified by the initrd= option will typically be a -gzipped filesystem image. - -NOTE: One of the main advantages with SYSLINUX is that it makes it -very easy to support users with new or unexpected configurations, -especially in a distribution setting. If initrd is used to -extensively modularize the distribution kernel, it is strongly -recommended that a simple way of adding drivers to the boot floppy be -provided. The suggested manner is to let the initrd system mount the -boot floppy and look for additional drivers in a predetermined -location. - -To bzImage and recent zImage kernels, SYSLINUX 1.30 will identify -using the ID byte 0x31. The ID range 0x32-0x3f is reserved for future -versions of SYSLINUX. - - ++++ DISPLAY FILE FORMAT ++++ - -DISPLAY and function-key help files are text files in either DOS or UNIX -format (with or without ). In addition, the following special codes -are interpreted: - - = = ASCII 12 - Clear the screen, home the cursor. Note that the screen is - filled with the current display color. - - = = ASCII 15 - Set the display colors to the specified background and - foreground colors, where and 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. - - = = ASCII 26 - End of file (DOS convention). - - ++++ NOVICE PROTECTION ++++ - -SYSLINUX will attempt to detect if the user is trying to boot on a 286 -or lower class machine, or a machine with less than 608K of low ("DOS") -RAM (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. - -The compile time and date of a specific SYSLINUX version can be obtained -by the DOS command "type ldlinux.sys". This is also used as the -signature for the LDLINUX.SYS file, which must match the boot sector. - -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 attribute on LDLINUX.SYS. - - ++++ 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. - -Please contact me at email . - -Sincerely, - - H. Peter Anvin November 2, 1996 + SYSLINUX + Version 1.31 + January 31, 1998 + + A bootloader for Linux using MS-DOS floppies + + Copyright (C) 1994-1998 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 is a boot loader for the Linux operating system which operates +off MS-DOS floppies. It is intended to simplify first-time installation +of Linux. It is *not* intended to be used as a general purpose boot +loader; once the operating system is installed I recommend LILO as the +boot loader, except for people whose root filesystem is a UMSDOS +filesystem (where a DOS defragmenter could wreck havoc with LILO's +carefully set up block tables) -- for them I recommend Loadlin (which +loads Linux from the DOS command line). + +SYSLINUX could, however, in conjunction with the UMSDOS filesystem, +completely eliminate the need for distribution of raw diskette images +for boot floppies. A SYSLINUX floppy can be manipulated using standard +MS-DOS (or any other OS that can access an MS-DOS filesystem) tools once +it has been created. + + ++++ 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 drive: + +This will alter the boot sector on the disk and copy a file named +LDLINUX.SYS into its root directory. + +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. + + ++++ 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 floppy. 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): + +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, except that the option "auto" is + automatically added, indicating an automatic boot. + + If no configuration file is present, or no DEFAULT entry is + present in the config file, the default is kernel name "linux", + with no options. + +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. + +LABEL label + KERNEL kernel + APPEND options... + + Indicates that if "label" is entered as the kernel to boot, + SYSLINUX should instead boot "kernel", and the specified APPEND + options should be used instead of the ones specified in the + global section of the file (before the first LABEL command.) + The default for "kernel" is the same as "label", and if no + APPEND is given the default is to use the global entry (if any). + Up to 16 LABEL entries are permitted. + + Note that LILO uses the syntax: + image = mykernel + label = mylabel + append = "myoptions" + + corresponding to the SYSLINUX: + label mylabel + kernel mykernel + append myoptions + + APPEND - + + Append nothing. APPEND with a single hyphen as argument in a + LABEL section can be used to override a global APPEND. + +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. + +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. + + NOTE: The maximum possible timeout value is 35996; corresponding to + just below one hour. + +DISPLAY filename + + Displays the indicated file on the screen at boot time (before + the boot: prompt, if displayed). This option takes the place of + the LINUXMSG.TXT and BOOTMSG.TXT files in SYSLINUX 1.0. Please + see the section below on DISPLAY files. + + NOTE: If the file is missing, this option is simply ignored. + +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. This + option takes the place of testing for the LINUXMSG.TXT file in + SYSLINUX 1.0. + +F1 filename +F2 filename + ...etc... +F9 filename +F0 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.) Note that F10 MUST be entered in the config file as + "F0", not "F10", and that there is currently no way to bind + file names to F11 and F12. Please see the section below on + DISPLAY files. + +Blank lines, and comment lines beginning with a hash mark (#) 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. + +The following combinations of options can be used to mimic the behaviour +of SYSLINUX 1.0 with LINUXMSG.TXT or BOOTMSG.TXT present, respectively: + +# Mimic SYSLINUX 1.0 with LINUXMSG.TXT file present: +display linuxmsg.txt +prompt 1 + +# Mimic SYSLINUX 1.0 with BOOTMSG.TXT file present: +display bootmsg.txt + + ++++ LARGE KERNELS AND INITIAL RAMDISK SUPPORT ++++ + +This version of SYSLINUX supports large kernels (bzImage format), +eliminating the 500K size limit of the zImage kernel format. bzImage +format kernels are detected automatically and handled transparently to +the user. + +This version of SYSLINUX also supports a boottime-loaded ramdisk +(initrd). An initrd is loaded from a DOS file if the option +"initrd=filename" (where filename is the filename of the initrd image; +the file must be located in the root directory on the boot floppy) is +present on the processed command line (after APPEND's have been added, +etc.). If several initrd options are present, the last one has +precedence; this permits user-entered options to override a config +file APPEND. Specifying "initrd=" without a filename inhibits initrd +loading. The file specified by the initrd= option will typically be a +gzipped filesystem image. + +NOTE: One of the main advantages with SYSLINUX is that it makes it +very easy to support users with new or unexpected configurations, +especially in a distribution setting. If initrd is used to +extensively modularize the distribution kernel, it is strongly +recommended that a simple way of adding drivers to the boot floppy be +provided. The suggested manner is to let the initrd system mount the +boot floppy and look for additional drivers in a predetermined +location. + +To bzImage and recent zImage kernels, SYSLINUX 1.30-1.31 will identify +using the ID byte 0x31. The ID range 0x32-0x3f is reserved for future +versions of SYSLINUX. + + ++++ DISPLAY FILE FORMAT ++++ + +DISPLAY and function-key help files are text files in either DOS or UNIX +format (with or without ). In addition, the following special codes +are interpreted: + + = = ASCII 12 + Clear the screen, home the cursor. Note that the screen is + filled with the current display color. + + = = ASCII 15 + Set the display colors to the specified background and + foreground colors, where and 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. + + = = ASCII 26 + End of file (DOS convention). + + ++++ NOVICE PROTECTION ++++ + +SYSLINUX will attempt to detect if the user is trying to boot on a 286 +or lower class machine, or a machine with less than 608K of low ("DOS") +RAM (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. + +The compile time and date of a specific SYSLINUX version can be obtained +by the DOS command "type ldlinux.sys". This is also used as the +signature for the LDLINUX.SYS file, which must match the boot sector. + +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 attribute on LDLINUX.SYS. + + ++++ 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. + +Please contact me at email . -- 2.7.4