From 857bfbd30639862ec4c1e49e84893c978de06c6f Mon Sep 17 00:00:00 2001 From: Gene Cumm Date: Thu, 6 Dec 2012 23:43:01 -0500 Subject: [PATCH] txt/: Add new AsciiDoc formatted documentation Signed-off-by: Gene Cumm --- txt/.gitignore | 7 + txt/Makefile | 108 ++++++++++ txt/com-bug.txt | 11 + txt/com-name.txt | 12 ++ txt/com-rpt.txt | 22 ++ txt/hello.txt | 16 ++ txt/syslinux-cli.txt | 65 ++++++ txt/syslinux.cfg.txt | 564 +++++++++++++++++++++++++++++++++++++++++++++++++++ txt/syslinux.txt | 217 ++++++++++++++++++++ 9 files changed, 1022 insertions(+) create mode 100644 txt/.gitignore create mode 100644 txt/Makefile create mode 100644 txt/com-bug.txt create mode 100644 txt/com-name.txt create mode 100644 txt/com-rpt.txt create mode 100644 txt/hello.txt create mode 100644 txt/syslinux-cli.txt create mode 100644 txt/syslinux.cfg.txt create mode 100644 txt/syslinux.txt diff --git a/txt/.gitignore b/txt/.gitignore new file mode 100644 index 0000000..55c6041 --- /dev/null +++ b/txt/.gitignore @@ -0,0 +1,7 @@ +*.1 +*.5 +*.html +*.pdf +*.text +*.xml +docbook-xsl.css diff --git a/txt/Makefile b/txt/Makefile new file mode 100644 index 0000000..11f1225 --- /dev/null +++ b/txt/Makefile @@ -0,0 +1,108 @@ +## ----------------------------------------------------------------------- +## +## Copyright 2012 Gene Cumm +## +## Some logic from win32/Makefile: +## Copyright 1998-2008 H. Peter Anvin - All Rights Reserved +## Copyright 2010 Intel Corporation; author: H. Peter Anvin +## +## This program is free software; you can redistribute it and/or modify +## it under the terms of the GNU General Public License as published by +## the Free Software Foundation, Inc., 53 Temple Place Ste 330, +## Boston MA 02111-1307, USA; either version 2 of the License, or +## (at your option) any later version; incorporated herein by reference. +## +## ----------------------------------------------------------------------- + +## +## AsciiDoc documentation for syslinux +## + +topdir = .. +MAKEDIR = $(topdir)/mk +# include $(MAKEDIR)/embedded.mk + +A2X_OPTS = -k +# A2X_OPTS += -v +A2X_MAN_OPTS = -D man -f manpage + +DOCS = syslinux.txt syslinux-cli.txt syslinux.cfg.txt +MAN_DOCS = man/syslinux.1 man/syslinux-cli.1 man/syslinux.cfg.5 +HTML_DOCS := $(patsubst %.txt,html/%.html,$(DOCS)) +XHTML_DOCS := $(patsubst %.txt,%.html,$(DOCS)) +# MAN_DOCS := $(patsubst %.txt,man/%.1,$(DOCS1)) $(patsubst %.txt,man/%.5,$(DOCS5)) +TEXT_DOCS := $(patsubst %.txt,%.text,$(DOCS)) +PDF_DOCS := $(patsubst %.txt,%.pdf,$(DOCS)) +TARGETS = + +# ASCIIDOC_OK := $(shell which asciidoc 2>&1 ; echo $$?) +ASCIIDOC_OK := $(shell which asciidoc > /dev/null ; echo $$?) +A2X_XML_OK := $(shell a2x $(A2X_OPTS) -f docbook hello.txt 2>&1 ; echo $$?) +ifeq ($(A2X_XML_OK),0) +A2X_MAN_OK := $(shell a2x $(A2X_MAN_OPTS) hello.txt 2>&1 ; echo $$?) +A2X_XHTML_OK := $(shell a2x $(A2X_OPTS) -f xhtml hello.xml 2>&1 ; echo $$?) +A2X_TEXT_OK := $(shell a2x $(A2X_OPTS) -f text hello.xml 2>&1 ; echo $$?) +endif + +ifeq ($(ASCIIDOC_OK),0) +TARGETS += $(HTML_DOCS) +endif +ifeq ($(A2X_MAN_OK),0) +TARGETS += $(MAN_DOCS) +endif +ifeq ($(A2X_XHTML_OK),0) +TARGETS += $(XHTML_DOCS) +endif +ifeq ($(A2X_TEXT_OK),0) +TARGETS += $(TEXT_DOCS) +endif + +# $(HTML_DOCS) $(MAN_DOCS) $(XHTML_DOCS) $(TEXT_DOCS) +all: $(TARGETS) + +syslinux.cfg.txt: com-bug.txt com-rpt.txt + +# During 'make all', *.xml is kept but deleted at the end; do we _really_ +# need the XML longer? +.PRECIOUS: %.xml + +# %.html: %.txt +# asciidoc -D html $< + +html/%.html: %.txt + asciidoc -o $@ $< + +# As of AsciiDoc-8.5.2, altering the output filename for a2x does not appear possible +# xhtml/%.html: %.txt +# a2x $(A2X_OPTS) -D xhtml -f xhtml $< +# text/%.text: %.xml %.txt +# a2x $(A2X_OPTS) -D text -f text $< + +%.xml: %.txt + a2x $(A2X_OPTS) -f docbook $< + +# when %.xml is missing, an update to %.txt must force regeneration +%.html: %.xml %.txt + a2x $(A2X_OPTS) -f xhtml $< + +man/%.1: %.txt + a2x $(A2X_MAN_OPTS) $< + +man/%.5: %.txt + a2x $(A2X_MAN_OPTS) $< + +%.text: %.xml %.txt + a2x $(A2X_OPTS) -f text $< + +%.pdf: %.xml %.txt + a2x $(A2X_OPTS) -f pdf $< + +tidy dist: + rm -f *~ *.xml *.text.html text/*.text.html text/*.xml xhtml/*.xml + +clean: tidy + +spotless: clean + rm -f *.1 *.5 *.css *.html *.text html/*.html man/*.1 man/*.5 text/*.text xhtml/*.html xhtml/*.css + +-include .*.d diff --git a/txt/com-bug.txt b/txt/com-bug.txt new file mode 100644 index 0000000..f16139a --- /dev/null +++ b/txt/com-bug.txt @@ -0,0 +1,11 @@ + +// == KNOWN BUGS == + +Several known bugs/common problems are listed at +http://www.syslinux.org/wiki/index.php/Common_Problems and known +hardware compatibility issues are listed at +http://www.syslinux.org/wiki/index.php/Hardware_Compatibility with +filename translation difficulty and early PXE stacks being some of the +most common. Reporting of other encountered issues is welcome and +appreciated. + diff --git a/txt/com-name.txt b/txt/com-name.txt new file mode 100644 index 0000000..b24811f --- /dev/null +++ b/txt/com-name.txt @@ -0,0 +1,12 @@ + +// == NAMING CONVENTION == + +As of 3.73, a standard for naming conventions was adopted to more +clearly distinguish different aspects. The moniker "The *Syslinux* +Project", in standard proper noun capitalization, shall be used to refer +to the project as a whole. The all-caps form shall be used to refer to a +particular loader variant such as "*SYSLINUX*" for the standard disk +(floppy/hard disk; formerly just FAT) loader. The all-lower case form +should be used to refer to a particular installer such as +"syslinux-mtools" for the mtools-based installer for *SYSLINUX*. + diff --git a/txt/com-rpt.txt b/txt/com-rpt.txt new file mode 100644 index 0000000..fe368ee --- /dev/null +++ b/txt/com-rpt.txt @@ -0,0 +1,22 @@ + +// == 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/txt/hello.txt b/txt/hello.txt new file mode 100644 index 0000000..3757627 --- /dev/null +++ b/txt/hello.txt @@ -0,0 +1,16 @@ += hello(1) = +:doctype: manpage +:author: World Greeter +:author-email: hello@domain.local +:revdate: 1970-01-01 +:data-uri: + + +== NAME == +hello - hello world + +== SYNOPSIS == +hello + +== Description == +Say hello and greet the world diff --git a/txt/syslinux-cli.txt b/txt/syslinux-cli.txt new file mode 100644 index 0000000..c0affc4 --- /dev/null +++ b/txt/syslinux-cli.txt @@ -0,0 +1,65 @@ += syslinux-cli(1) = +:doctype: manpage +:revdate: 2012-11-10 +:author: H. Peter Anvin +:author-email: hpa@zytor.com +:editor1: Gene Cumm +:editor1-email: gene.cumm@gmail.com +:editor1-revlast: 2012-11-10 +:data-uri: + +== NAME == +syslinux-cli - *Syslinux* boot prompt/command line interface + + +== DESCRIPTION == +*Syslinux*'s boot prompt provides a very simplistic command line +interface for loading modules and booting kernels. + + +== BOOT PROMPT == +=== COMMAND LINE KEYSTROKES === +The command line prompt supports the following keystrokes: + + boot specified command line + erase one character + erase the whole line + display the current Syslinux version + erase one word + force text mode + list matching labels + .. help screens (if configured) + equivalent to F1..F10 + interrupt boot in progress + interrupt boot in progress + display network information (PXELINUX only) + + +=== WORKING DIRECTORY === +At start, the initial working directory for *SYSLINUX*/*ISOLINUX* will +be the directory containing the initial configuration file. If no +configuration file is found, *SYSLINUX* should default to the +install-time working directory, however this is a known issue with some +versions including 4.06. + +At start, the initial working directory for *PXELINUX* will be the +parent directory of pxelinux.0 unless overridden with DHCP option 210. +If no configuration file is found, *PXELINUX* will start a timer to +reboot the system in an attempt to restart the boot process and resolve +a possible transient issue. + + +=== ALTERNATE FILENAMES === +For kernel-like file names given on the command line, *Syslinux* will +attempt to append file name extensions to the specified file naem when +the file is not found in the following order: .0[*PXELINUX* only], +.bin[*ISOLINUX* only], .bs[*SYSLINUX* only], .bss[*SYSLINUX* only], +.c32, .cbt, .com and .img[*ISOLINUX* 1.65-4.04 only]. + +// Is this true of file names specified in a config? As of when? + + +== AUTHOR == +This AsciiDoc derived document is a modified version of the original +*SYSLINUX* documentation by {author} <{author-email}>. The conversion +to an AsciiDoc was made by {editor1} <{editor1-email}> diff --git a/txt/syslinux.cfg.txt b/txt/syslinux.cfg.txt new file mode 100644 index 0000000..18b1681 --- /dev/null +++ b/txt/syslinux.cfg.txt @@ -0,0 +1,564 @@ += syslinux.cfg(5) = +:doctype: manpage +:revdate: 2012-10-28 +:author: H. Peter Anvin +:author-email: hpa@zytor.com +:editor1: Gene Cumm +:editor1-email: gene.cumm@gmail.com +:editor1-revlast: 2012-10-28 +:nbsp8:          +:nbsp32: {nbsp8}{nbsp8}{nbsp8}{nbsp8} +:data-uri: + +== NAME == +syslinux.cfg - *Syslinux* configuration file + + +== DESCRIPTION == +Configuration for the boot behavior and user experience of *Syslinux* +boot loaders, the format of display files and the boot prompt behavior. + +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. + + +== LOCATION/NAME == +*SYSLINUX* (before 4.00) used the configuration filename of +syslinux.cfg. *EXTLINUX* (merged into *SYSLINUX* as of 4.00) used the +filename extlinux.conf. Both default to searching for the config file +in the installed directory (containing ldlinux.sys/extlinux.sys). As of +4.00, *SYSLINUX* will search for extlinux.conf then syslinux.cfg in each +directory before falling back to the next directory. + +As of 3.35, *SYSLINUX* also searches /boot/syslinux, /syslinux and /. + +*ISOLINUX* (before 4.02) used the configuration filename of +isolinux.cfg, searching /boot/isolinux (starting 2.00), then /isolinux +and /. As of 4.02, *ISOLINUX* will search for isolinux.cfg then +syslinux.cfg in /boot/isolinux before searching for the same files in +/isolinux, /boot/syslinux, /syslinux, and /. + + +== GLOBAL DIRECTIVES - MAIN == +*#* comment:: +A line comment. As of version 3.10, the space between the *#* and the +comment is no longer required. + +*MENU* any string:: +(3.00+) A directive for the simple menu system, treated as a comment +outside the menu. See menu.txt. + +*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. Multiple uses will result in an override. ++ +If no configuration file is present, or no *DEFAULT* or *UI* entry is +present in the config file, an error message is displayed and the +'boot:' prompt is shown (3.85+). + +*UI* 'module' 'options...':: +Selects a specific user interface 'module' (typically menu.c32 or +vesamenu.c32). The command-line interface treats this as a directive +that overrides the *DEFAULT* directive to load this module instead at +startup and for an empty command line and *PROMPT* directive to not +prompt. Multiple uses will result in an override. + +*LABEL* 'mylabel':: +Begin a new *LABEL* clause. If 'mylabel' is entered as the kernel to +boot, *Syslinux* should instead boot "image" (specified by a directive +from *KERNEL-LIKE DIRECTIVES*) with any specified *DUAL-PURPOSE +DIRECTIVES* being used instead of the global instance. ++ +'mylabel' must be unique. Currently the first instance is used but may +result in an error or undesired behavior. 'mylabel' ends at the first +character that is not a non-white-space printable character and should +be restricted to non-white-space typeable characters. Prior to version +3.32, this would transformed to a DOS compatible format of 8.3 with a +restricted character set. A *LABEL* clause must contain exactly 1 of +the *KERNEL-LIKE DIRECTIVES* and may contain 1 each of the *LABEL-ONLY +DIRECTIVES* or *DUAL-PURPOSE DIRECTIVES*. ++ +Within a *LABEL*, using multiple *KERNEL-LIKE DIRECTIVES* or reuse of +*LABEL-ONLY DIRECTIVES* or *DUAL-PURPOSE DIRECTIVES* will result in an +override. Otherwise, multiple instances of the same directive will +result in the last being effective. + + +== DUAL-PURPOSE DIRECTIVES == +Use of any of the *DUAL-PURPOSE DIRECTIVES* as *GLOBAL DIRECTIVES* is +discouraged if there will be any non-Linux images loaded as *ALL* images +will get these, including those manually entered at the 'boot:' prompt. + +*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. ++ +Use of the parameter 'initrd=' supports multiple filenames separated by +commas (ie 'initrd=initrd_file1,initrd_file2') within a single instance. +This is mostly useful for initramfs, which can be composed of multiple +separate cpio or cpio.gz archives. ++ +Note: all initrd files except the last one are zero-padded to a 4K page +boundary. This should not affect initramfs. ++ +Note: Only the last effective 'initrd=' parameter is used for loading +initrd files. + +*APPEND* -:: +Append nothing. *APPEND* with a single hyphen as argument in a *LABEL* +section can be used to override a global *APPEND*. + +//[FIXME: Shorten subdefinitions] +*IPAPPEND* 'flag_val':: +(*PXELINUX* only) The *IPAPPEND* option is available only on *PXELINUX*. + The flag_val is an OR (sum) of the following integer options: + +ifndef::doctype-manpage[[horizontal]] +*1*::: An option of the following format should be generated, based on +the input from the DHCP/BOOTP or PXE boot server and added to the kernel +command line(see note below): ++ +---- +ip=::: +---- ++ +NOTE: The use of option 1 is no substitute for running a DHCP client in +the booted system and should instead only be used to seed the client for +a request. Without regular renewals, the lease acquired by the PXE BIOS +will expire, making the IP address available for reuse by the DHCP +server. ++ +*2*::: An option of the following format should be generated, in +dash-separated hexadecimal with leading hardware type (same as for the +configuration file; see pxelinux.txt.) and added to the kernel command +line, allowing an initrd program to determine from which interface the +system booted: ++ +---- +BOOTIF= +---- ++ +*4*::: An option of the following format should be generated, in lower +case hexadecimal in the format normally used for UUIDs (same as for the +configuration file; see pxelinux.txt.) and added to the kernel command +line: ++ +---- +SYSUUID= +---- + + +== KERNEL-LIKE DIRECTIVES == +// Alpha sort after KERNEL and LINUX +*KERNEL* 'image':: +Load a kernel-like file 'image' with automatic filetype detection based +on file extension, listed under the non-auto-detecting directives, +defaulting to *LINUX*. + +//[FIXME: Should "'image' as " be removed entirely or added to all? +*LINUX* is used as an example] +*LINUX* 'image':: +Load 'image' as a Linux-like kernel. MEMDISK is an example of a +non-Linux kernel loaded in a Linux-like fashion. + +*BOOT* 'image':: +(*ISOLINUX* only: .bin; *SYSLINUX* only: .bs) Load a boot sector. .bin +is a "CD boot sector" and .bs is a regular disk boot sector. + +*BSS* 'image':: +(*SYSLINUX* only: .bss) Load a BSS image, a .bs image with the DOS +superblock patched in. + +*COMBOOT* 'image':: +(.com, .cbt) Load a *Syslinux* COMBOOT image. .com images may also be +runnable from DOS while .cbt images are not. See also *comboot.txt* + +*COM32* 'image':: +(.c32) Load a *Syslinux* COM32 (32-bit *COMBOOT*) image. See also +*comboot.txt* + +*CONFIG* 'image':: +Load a new configuration file. The configuration file is read, the +working directory is changed (if specified via an *APPEND*), then the +configuration file is parsed. + +*FDIMAGE* 'image':: +(Removed as of 4.05, added 1.65; *ISOLINUX* only: .img) Load a disk +image. + +*LOCALBOOT* 'type':: +(*PXELINUX* 1.53+; *ISOLINUX* ??3.10+; *SYSLINUX* 3.70+)Attempt a +different local boot method. The special value -1 causes the boot +loader to report failure to the BIOS, which, on recent BIOSes, should +mean that the next boot device in the boot sequence should be activated. + Values other than those documented may produce undesired results. ++ +On *PXELINUX*, "type" 0 means perform a normal boot. "type" 4 will +perform a local boot with the Universal Network Driver Interface (UNDI) +driver still resident in memory. Finally, "type" 5 will perform a local +boot with the entire PXE stack, including the UNDI driver, still +resident in memory. All other values are undefined. If you don't know +what the UNDI or PXE stacks are, don't worry -- you don't want them, +just specify 0. ++ +On *ISOLINUX*/*SYSLINUX*, the "type" specifies the local drive number to +boot from; 0x00 is the primary floppy drive and 0x80 is the primary hard +drive. + +*PXE* 'image':: +(*PXELINUX* only: .0) Load a PXE NBP (Network Boot Program) image. The +PXE protocol does not provide any means for specifiying or using a +command line or initrd. + + +== LABEL-ONLY DIRECTIVES == +*INITRD* 'initrd_file':: +(3.71+) An initrd can be specified in a separate statement (INITRD) +instead of as part of the *APPEND* statement; this functionally appends +"initrd=initrd_file" to the kernel command line. Like 'initrd=', this +also supports multiple comma separated file names (see *APPEND*). + + +== GLOBAL DIRECTIVES - SECONDARY == +These are global directives that are of lesser importance, often +affecting the user experience and not the boot process. + +*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. + +*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 +(the default) will disable the timeout completely. + +*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 to boot. + +*ONERROR* 'kernel options...':: +If a kernel image is not found (either due to it not existing, or +because *IMPLICIT* is set), run the specified command. The faulty +command line is appended to the specified options, so if the *ONERROR* +directive reads as: ++ +---- +ONERROR xyzzy plugh +---- ++ +and the command line as entered by the user is: ++ +---- +foo bar baz +---- ++ +*Syslinux* will execute the following as if entered by the user: ++ +---- +xyzzy plugh foo bar baz +---- + +*SERIAL* 'port [[baudrate] flowcontrol]':: +Enables a serial port to act as the console. "port" is a number (0 = +/dev/ttyS0 = COM1, etc.) or an I/O port address (e.g. 0x3F8); if +"baudrate" is omitted, the baud rate defaults to 9600 bps. The serial +parameters are hardcoded to be 8 bits, no parity, 1 stop bit. ++ +"flowcontrol" is a combination of the following bits: ++ +.... +0x001 - Assert DTR +0x002 - Assert RTS +0x008 - Enable interrupts +0x010 - Wait for CTS assertion +0x020 - Wait for DSR assertion +0x040 - Wait for RI assertion +0x080 - Wait for DCD assertion +0x100 - Ignore input unless CTS asserted +0x200 - Ignore input unless DSR asserted +0x400 - Ignore input unless RI asserted +0x800 - Ignore input unless DCD asserted +.... ++ +All other bits are reserved. ++ +Typical values are: ++ +.... + 0 - No flow control (default) +0x303 - Null modem cable detect +0x013 - RTS/CTS flow control +0x813 - RTS/CTS flow control, modem input +0x023 - DTR/DSR flow control +0x083 - DTR/DCD flow control +.... ++ +For the *SERIAL* directive to be guaranteed to work properly, it should +be the first directive in the configuration file. ++ +NOTE: "port" values from 0 to 3 means the first four serial ports +detected by the BIOS. They may or may not correspond to the legacy port +values 0x3F8, 0x2F8, 0x3E8, 0x2E8. ++ +Enabling interrupts (setting the 0x008 bit) may give better +responsiveness without setting the *NOHALT* option, but could +potentially cause problems with buggy BIOSes. + +*NOHALT* 'flag_val':: +If 'flag_val' is 1, don't halt the processor while idle. Halting the +processor while idle significantly reduces the power consumption, but +can cause poor responsiveness to the serial console, especially when +using scripts to drive the serial console, as opposed to human +interaction. + +*CONSOLE* 'flag_val':: +If 'flag_val' is 0, disable output to the normal video console. If +'flag_val' is 1, enable output to the video console (this is the +default.) ++ +Some BIOSes try to forward this to the serial console and sometimes make +a total mess thereof, so this option lets you disable the video console +on these systems. + +*FONT* 'filename':: +Load a font in .psf format before displaying any output (except the +copyright line, which is output as ldlinux.sys itself is loaded.) +*Syslinux* only loads the font onto the video card; if the .psf file +contains a Unicode table it is ignored. This only works on EGA and VGA +cards; hopefully it should do nothing on others. + +*KBDMAP* 'keymap':: +Install a simple keyboard map. The keyboard remapper used is *very* +simplistic (it simply remaps the keycodes received from the BIOS, which +means that only the key combinations relevant in the default layout -- +usually U.S. English -- can be mapped) but should at least help people +with AZERTY keyboard layout and the locations of = and , (two special +characters used heavily on the Linux kernel command line.) ++ +The included program keytab-lilo.pl from the LILO distribution can be +used to create such keymaps. The file keytab-lilo.txt contains the +documentation for this program. + +*DISPLAY* 'filename':: +Displays the indicated file on the screen at boot time (before the boot: +prompt, if displayed). Please see the section below on *DISPLAY* files. ++ +NOTE: If the file is missing, this option is simply ignored. + +*SAY* 'message':: +Prints the message on the screen. + +*PROMPT* 'flag_val':: +If 'flag_val' is 0, display the boot: prompt only if the Shift or Alt +key is pressed, or Caps Lock or Scroll lock is set (this is the +default). If 'flag_val' is 1, always display the boot: prompt. + +*NOESCAPE* 'flag_val':: +If 'flag_val' is set to 1, ignore the Shift/Alt/Caps Lock/Scroll Lock +escapes. Use this (together with PROMPT 0) to force the default boot +alternative. + +*NOCOMPLETE* 'flag_val':: +If flag_val is set to 1, the Tab key does not display labels at the +boot: prompt. + +// ...etc... +*F1* 'filename':: +*F2* 'filename':: +*F3* 'filename':: +*F4* 'filename':: +*F5* 'filename':: +*F6* 'filename':: +*F7* 'filename':: +*F8* 'filename':: +*F9* 'filename':: +*F10* 'filename':: +*F11* 'filename':: +*F12* 'filename':: +Displays the indicated file on the screen when a function key is pressed +at the boot: prompt. This can be used to implement pre-boot online help +(presumably for the kernel command line options.) Please see the +section below on DISPLAY files. ++ +When using the serial console, press to get to the help +screens, e.g. <2> to get to the F2 screen. For F10-F12, hit +, B, C. For compatibility with earlier +versions, F10 can also be entered as 0. + + +== 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: + +//[FIXME]: #1 doesn't break; #2 as-is; #3 broken but not on right; #4 +identical to #3 +// horizontal extends the line's label, reducing the definition +// tab or space to shift explanation ? align beginning or end? + +// ifndef::doctype-manpage[[horizontal]] +**:: {nbsp32} = = ASCII 12 + +Clear the screen, home the cursor. Note that the screen is filled with +the current display color. + +**:: += = ASCII 12; Clear the screen, home the cursor. Note that the +screen is filled with the current display color. + +**:: = = ASCII 12 ++ +Clear the screen, home the cursor. Note that the screen is filled with +the current display color. + +**:: + = = 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 the 2 hex digits representing 1 byte, +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. + +**'filename':: = = 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 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. + +**:: = = ASCII 25 + +If we are currently in graphics mode, return to text mode. + +**..**:: .. = 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 + ------------------------------------------------------ + = = ASCII 16 No No No + = = ASCII 17 Yes No No + = = ASCII 18 No Yes No + = = ASCII 19 Yes Yes No + = = ASCII 20 No No Yes + = = ASCII 21 Yes No Yes + = = ASCII 22 No Yes Yes + = = ASCII 23 Yes Yes Yes ++ +For example, the following will actually print out which mode the +console is in: ++ + Text modeGraphics modeSerial port + +**:: = = ASCII 26 ++ +End of file (DOS convention). + +**:: = = ASCII 7 + +Beep the speaker. + + +== 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. + + +== 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* installer automatically sets the readonly/hidden/system +attributes on LDLINUX.SYS. + + +== KNOWN BUGS == +include::com-bug.txt[] + + +== BUG REPORTS == +include::com-rpt.txt[] + + +== AUTHOR == +This AsciiDoc derived document is a modified version of the original +*SYSLINUX* documentation by {author} <{author-email}>. The conversion +to an AsciiDoc was made by {editor1} <{editor1-email}> diff --git a/txt/syslinux.txt b/txt/syslinux.txt new file mode 100644 index 0000000..23cad49 --- /dev/null +++ b/txt/syslinux.txt @@ -0,0 +1,217 @@ += syslinux(1) = +:doctype: manpage +:revdate: 2012-10-28 +:author: H. Peter Anvin +:author-email: hpa@zytor.com +:editor1: Gene Cumm +:editor1-email: gene.cumm@gmail.com +:editor1-revlast: 2012-10-28 + + +== NAME == +syslinux - Install SYSLINUX to a file system + + +== SYNOPSIS == +[verse] +*syslinux* ['OPTIONS'] 'DEVICE' +*extlinux* ['OPTIONS'] 'PATH' +*syslinux* [-h | --help] +*extlinux* [-h | --help] + + +== DESCRIPTION == +Install *SYSLINUX* to the 'DEVICE'/'PATH', altering the boot sector and +installing the 'ldlinux.sys' boot loader file. For the Linux installer +extlinux, 'PATH' is the desired path for the control files on a mounted, +supported file system and sets the install-time working directory. For +all others, 'DEVICE' must specify a FAT12/FAT16/FAT32 file system. For +the Linux installers syslinux and syslinux-mtools, 'DEVICE' should be an +unmounted file system. For the DOS/Win32/Win64 installers, 'DEVICE' +should be a drive like 'a:' (case insensitive). + +For versions ~4.00 and later, either -i/--install or -U/--update must be +specified unless modifying the ADV of an existing install (options +tagged with 'ADV') or requesting the help/usage or version info, . + +If, during boot, the Shift or Alt keys are held down, or the Caps or +Scroll locks are set, *Syslinux* will display a *lilo*(8) -style "boot:" +prompt. The user can then type a kernel file name followed by any kernel +parameters. The *Syslinux* bootloader does not need to know about the +kernel or config files in advance. + +*Syslinux* supports the loading of initial ramdisks (initrd) and the +bzImage kernel format. + +Please note, the ldlinux.sys boot loader file is flagged as immutable +(where applicable) and is modified after copying in to help ensure +boot-time integrity. File systems with a sufficiently large boot loader +reserved area, like btrfs, will have ldlinux.sys installed there rather +than as a normal file. + + +== OPTIONS == +// "See"/"See also" notes should reference long options. +=== Standalone options === +*-i*, *--install*:: +(~4.00+) Install SYSLINUX, regardless of an existing install. + +*-U*, *--update*:: +(~4.00+) Update an existing SYSLINUX/EXTLINUX install. If no Syslinux +boot loader is present, return an error. + +*-h*, *--help*:: +Display help/usage information. + +*-v*, *--version*:: +Display version information and exit immediately. + +=== Regular Options === +// Sorted generally by short argument +*-a*, *--active*:: +(DOS/Win32/Win64 ONLY) Mark the install target file system's partition +active. + +*-d*, *--directory* 'subdirectory':: +(Not necessary for extlinux as it is implied by 'PATH') Install the +*SYSLINUX* control files in a subdirectory with the specified name +(relative to the root directory on the device). + +*--device* 'DEVICE':: +(extlinux ONLY; 4.06+) Force use of a specific block device (experts +only). + +*-f*, *--force*:: +Force install even if it appears unsafe. Before 4.00, -f was used for +--offset in the Linux installers. + +*-H*, *--heads* 'head-count':: +Override the detected number of heads for the geometry. See also +*--sector*. + +*-m*, *--mbr*: +(DOS/Win32/Win64 ONLY) Install the regular Syslinux MBR code to the MBR. + +*-M*, *--menu-save*:: +(4.00+; ADV) Set the label to select as default on the next boot. + +*-o*, *--once* 'command':: +(ADV) Declare a boot command to be tried on the first boot only. The +use of *-o* for the Linux installers syslinux or syslinux-mtools has +been deprecated as of ~4.00 and is no longer valid as of ~4.02. + +*-O*, *--clear-once*:: +Clear the boot-once command. See also *--once*. + +*-r*, *--raid*:: +(ADV) RAID mode. If boot fails, tell the BIOS to boot the next device +in the boot sequence (usually the next hard disk) instead of stopping +with an error message. This is useful for RAID-1 booting. + +*--reset-adv*:: +(ADV) Reset auxilliary data vector. + +*-S*, *--sectors* 'sector-count':: +Override the detected number of sectors for the geometry. See also +*--head*. + +*-s*, *--stupid*:: +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. + +*-t*, *--offset* 'offset':: +(Linux syslinux/syslinux-mtools ONLY) Indicates that the filesystem is +at an offset from the base of the device or file. + +*-z*, *--zipdrive* +Assume zipdrive geometry ('--heads 64 --sectors 32'). See also *--head* +and *--sector*. + + +== EXAMPLES == +=== Booting DOS === +For booting DOS and other similar operating systems, there is an easy +and generally reliable solution to substitute in SYSLINUX as the primary +boot loader. + +- Make a DOS-bootable disk; The following are possible commands: + + format a: /s + sys a: + +- Copy the DOS boot sector off using Linux or copybs.com: + + dd if=/dev/fd0 of=dos.bss bs=512 count=1 + copybs a: a:dos.bss + +- Install SYSLINUX using one of: + + syslinux a: + syslinux /dev/fd0 (before 4.00) + syslinux -i /dev/fd0 (4.00+) + +- For Linux, mount the disk and copy the dos.bss to the disk: + + mount -t msdos /dev/fd0 /mnt + cp dos.bss /mnt + +- Copy a Linux kernel image and initrd payload files: +*Linux:*:: + cp vmlinux /mnt + cp initrd.gz /mnt +*DOS/Windows:*:: + copy vmlinux a: + copy initrd.gz a: + +- For Linux, umount the disk (if applicable): + + umount /mnt + +=== MBR === +In order to boot from a hard disk (or hard disk-like device) in BIOS +mode, an appropriate MBR boot block must also be installed in the MBR +(first sector or 512 bytes of the disk), occupying at most 440 bytes. + +*DOS/Windows:*:: +If using FDISK, FDISK or a similar application must also be used to mark +the partition as active. ++ + fdisk /mbr + OR + syslinux -ma c: + +*Linux:*:: ++ + dd bs=440 count=1 conv=notrunc if=mbr/mbr.bin of=/dev/sda ++ +For altmbr.bin, an easy way to overwrite the MBR boot block and specify +the partion number is: ++ + printf '\1' | cat altmbr.bin - | dd bs=440 count=1 iflag=fullblock conv=notrunc of=/dev/sda ++ +Note: using 'cat' for writing the MBR can under some circumstances cause +data loss or overwritting. For this reason, using 'dd' is recommended +for all situations. + +//[FIXME]: any clean way to handle the above long command for manpage? + + +== SEE ALSO == +*syslinux.cfg*(5), *syslinux-cli*(1), *lilo*(8), *keytab-lilo.pl*(8), +*fdisk*(8), *mkfs*(8), *superformat*(1). + + +== AUTHOR == +This AsciiDoc derived document is a modified version of the original +*SYSLINUX* documentation by {author} <{author-email}>. The conversion to +a manpage was made by Arthur Korn . The conversion to +an AsciiDoc was made by {editor1} <{editor1-email}> + + +== COPYRIGHT == +Copyright \(C) 1994-2012 {author}. Free use of this software is granted +under the terms of the GNU General Public License (GPL), version 2 +(GPLv2) (or, at your option, any later version). -- 2.7.4