diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/chain.txt | 327 | ||||
| -rw-r--r-- | doc/comboot.txt | 76 | ||||
| -rw-r--r-- | doc/gpt.txt | 2 | ||||
| -rw-r--r-- | doc/isolinux.txt | 31 | ||||
| -rw-r--r-- | doc/logo/LICENSE | 5 | ||||
| -rw-r--r-- | doc/logo/syslinux-100.png | bin | 0 -> 131308 bytes | |||
| -rw-r--r-- | doc/menu.txt | 2 | ||||
| -rw-r--r-- | doc/pxechn.txt | 138 | ||||
| -rw-r--r-- | doc/syslinux.txt | 2 |
9 files changed, 475 insertions, 108 deletions
diff --git a/doc/chain.txt b/doc/chain.txt new file mode 100644 index 00000000..6dd0632d --- /dev/null +++ b/doc/chain.txt @@ -0,0 +1,327 @@ + chain.c32 documentation + +Although syslinux is capable of (very simple) native chainloading (through .bss +and .bs options - see doc/syslinux.txt), it also features a very roboust and +rich com32 module designed for such purpose. + +Chain module can perform few basic tasks: + +- load and jump to a sector +- load and jump to a file (also loading a sector for other purposes) +- prepare handover data to use by a file / boot sector +- fix different options in a file / sector / partition entries +- perform a "service-only" run + +It can chainload data from both GPT and DOS partitions, as well as boot the +first sector from a raw disk. + +In more details, the rough overview of code is as follows: + +1. Parse arguments. +2. Find drive and/or partition to boot from. +3. Perform partition-level patching - for example hiding, unhiding, fixing chs values, etc. +4. Load a file to boot from. +5. Load a sector to boot from, if it doesn't conflict with #5. +6. Prepare handover area, if it doesn't conflict with #5 & #6. +7. Prepare registers. +8. Patch loaded file if necessary. +9. Patch loaded sector if necessary. +10. Chainload. + +In most basic form, syslinux loads specified boot sector (or mbr, if not +specified) at 0:0x7c00, prepares handover area as a standard mbr would do, and +jumps to 0:0x7c00. + +A "service-only" run is possible when either: + +- 'break' is in effect + +or + +- 'nofile' and 'nomaps' (or 'nosect') are in effect + +This is useful for invocations such as: + +chain.c32 hdN M setbpb save break +chain.c32 hdN fixchs break +chain.c32 hdN unhideall break + +Please see respective options for more details. + + +Module invocation: + +chain [drive/partition] [options] + + DRIVE / PARTITION SPECIFICATION + +Drive can be specified as 'hd#', 'fd#', 'boot', 'mbr', or 'guid'. + +- 'mbr' will select a drive by a signature. +- 'guid' will select a drive by a guid +- 'boot' is the drive syslinux was booted from. This is the default value, if + nothing else is specified. +- 'hd#' and 'fd#' are standard ways to specify drive number as seen by bios, + starting from 0. + +Option 'guid' is shared with partition selection (see below). If you happened +to have non-unique guids, they are searched in disk0, partitions of disk0, +disk1 ... order. + +The priority of those options are the same as in the above list. + +If you specify the same value more than once, the last value will be used. + +'mbr' and 'guid' take extra parameter - you should use ':' or '=' as a +delimiter. + + +Partition can be specified as '#', 'guid', 'label' or 'fs'. + +- 'guid' option will select a partition by a guid (not a type guid !) +- 'label' will select a partition by a label (searching is done in + disk order) +- 'fs' will select a partition from which syslinux was executed +- '#' is the standard method. Partitions 1-4 are primary, 5+ logical, 0 = boot + MBR (default). + +The priority of those options are the same as in the above list. + +If you use a number to select a partition it should be specified after a drive +using space or comma as delimiters (after 'hd#', 'fd#', 'mbr', 'guid' or 'boot'). + + OPTIONS + file=<file> + *nofile + +It's often convenient to load a file directly and transfer control to it, +instead of the sector from the disk. Note, that the <file> must reside on +syslinux partition. + +If you choose this option without specifying any addresses explicitly (see +options 'sect=' and 'seg='), the file will cause sector to not be loaded at all +(as their memory placement would overlap). + + seg=<segment>:<offset>:<ip> + *seg=0:0x7c00:0x7c00 + +This triplet lets you alter the addresses a file will use. It's loaded at +<segment:offset>, the entry point is at <segment:ip>. When you chainload some +other bootloader or kernel, it's almost always mandatory. + +The defaults, if option is not specified, are 0:0x7c00:0x7c00 +If any of the fields are ommited (e.g. 0x2000::), they default to 0. + + sect=<segment>:<offset>:<ip> + nosect + *sect=0:0x7c00:0x7c00 + nosect sets: nomaps + +This triplet lets you alter the addresses a sector will use. It's loaded at +<segment:offset>, the entry point is at <segment:ip>. This option is mostly +used in tandem with 'file=' and 'seg=' options, as some loaders/kernels will +expect relocated sector at some particular address (e.g. DRKM). + +'nosect' will cause sector to not be loaded at all. In plenty cases, when a file +is being chainloaded, sector is not necessary. + +The defaults if option is not specified, are 0:0x7c00:0x7c00. +If some of the fields are ommited (e.g. 0x2000::), they default to 0. + + *maps + nomaps + +In some cases, it's useful to fix BPB values in NTFS/FATxx bootsectors and +evntually write them back, but otherwise boot sector itself is not necessary to +continue booting. 'nomaps' allows that - a sector will be loaded, but won't be +mmapped into real memory. Any overlap tests (vs. handover or file areas) are +not performed, being meaningless in such case. + + setbpb + *nosetbpb + +Microsoft side of the world is paritculary sensitive to certain BPB values. +Depending on the system and chainloading method (sector or file), some or all +of those fields must match reality - and after e.g. drive clonning or +when using usb stick in different computers - that is often not the case. + +The "reality" means: + +"hidden sectors" - valid offset of the partition from the beginning of the disk +"geometry" - valid disk geometry as reported by BIOS +"drive" - valid drive number + +This option will automatically determine the type of BPB and fix what is possible +to fix, relatively to detected BPB. If it's impossible to detect BPB, function +will do nothing. + + filebpb + *nofilebpb + +Chainloaded file can simply be an image of a sector. In such case, it could be +useful to also fix its BPB values. + + save + *nosave + +Fixing BPB values only in memory might not be enough. This option allows +writing of the corrected sector. You will probably want to use this option +together with 'setbpb'. + +- this option never applies to a loaded file +- chain module will not save anything to disk by default (besides options such + as hide or fixchs - so options related directly to partition entries) +- writing is only performed, if the values actually changed + + *hand + nohand + +By default, a handover area is always prepared if possible - meaning it doesn't +overlap with other areas. It's often not necessary though - usually, a +chainloaded file or kernel don't care about it anymore, so a user can disable +it explicitly with this option. + + hptr + *nohptr + +In case when both file and sector are loaded, ds:si and ds:bp will point to +sector address before the chainloading. This option lets user force those +registers to point to handover area. This is useful when both the file and the +sector are actually a sector's image and the sector is mmapped. + + swap + *noswap + +This option will install a tiny stub code used to swap drive numbers, if the +drive we use during chainloading is not fd0 or hd0. + + hide[all] + unhide[all] + *nohide + +In certain situations it's useful to hide partitions - for example to make sure +DOS gets C:. 'hide' will hide hidable primary partitions, except the one we're +booting from. Similary, 'hideall' will hide all hidable partitions, except the +one we're booting from. Hiding is performed only on the selected drive. Options +starting with 'un' will simply unhide every partition (primary ones or all). +Writing is only performed, if the os type values actually changed. + + fixchs + *nofixchs + +If you want to make a drive you're booting from totally compatible with current +BIOS, you can use this to fix all partitions' CHS numbers. Good to silence e.g. +FreeDOS complainig about 'logical CHS differs from physical' of sfdisk about +'found (...) expected (...). Functionally seems to be mostly cosmetic, as +Microsoft world - in cases it cares about geometry - generally sticks to values +written in bootsectors. And the rest of the world generally doesn't care about +them at all. Writing is only performed, if the values actually got changed. + + keepexe + *nokeepexe + +If you're booting over a network using pxelinux - this lets you keep UNDI +stacks in memory (pxelinux only). + + warn + *nowarn + +This option will wait for a keypress right before continuing the chainloading. +Useful to see warnings emited by the chain module. + + *nobreak + break + break sets: nofile nomaps nohand + +It is possible to trigger a "service-only" run - The chain module will do +everything requested as usual, but it will not perform the actual chainloading. +'break' option disables handover, file loading and sector mapping, as these +are pointless in such scenario (although file might be reenabled in some future +version, if writing to actual files becomes possible). Mainly useful for +options 'fixchs', '[un]hide[all]' and setbpb. + + isolinux=<file> + sets: file=<file> nohand nosect isolinux + +Chainload another version/build of the ISOLINUX bootloader and patch the loader +with appropriate parameters in memory. This avoids the need for the +-eltorito-alt-boot parameter of mkisofs, when you want more than one ISOLINUX +per CD/DVD. + + ntldr=<file> + sets: file=<file> seg=0x2000 setbpb nohand + +Prepares to load ntldr directly. You might want to add 'save' option to store +corrected BPB values. + + cmldr=<file> + sets: file=<file> seg=0x2000 setbpb nohand cmldr + +Prepares to load recovery console directly. In-memory copy of bootsector is +patched with "cmdcons\0". Remarks the same as in 'ntldr='. + + reactos=<file> + sets: file=<file> seg=0:0x8000:0x8100 setbpb nohand + +Prepares to load ReactOS's freeldr directly. You might want to add 'save' +option to store corrected BPB values. + + freedos=<file> + sets: file=<file> seg=0x60 sect=0x1FE0 setbpb nohand + +Prepares to load freedos kernel directly. You will likely want to add 'save' +option, as those kernels seem to require proper geometry written back to disk. +Sector address is chosen based on where freedos' bootsectors relocate themselves, +although it seems the kernel doesn't rely on it. + +You might also want to employ 'hide' option, if you have problems with properly +assigned C: drive. + + pcdos=<file> + msdos=<file> + sets: file=<file> seg=0x70 sect=0x8000 setbpb nohand + +Similary to 'freedos=', This prepares to load MSDOS 2.00 - 6.xx or derivatives. +Sector address is chosen arbitrarily. Otherwise comments as above. + + msdos7=<file> + sets: file=<file> seg=0x70::0x200 sect=0x8000 setbpb nohand + +Only for MSDOS 7+ versions (98se ~ 7.xx, Me ~ 8.xx). Comments as above. +TODO/TEST + + drmk=<file> + sets: file=<file> seg=0x70 sect=0x2000:0:0 setbpb nohand + +This is used for loading of *only* Dell's DOS derivatives. It does require boot +sector at 0x2000 and overall valid BPB values. As in other DOS-ish cases, +likely candidates for use are 'save' and 'hide'. + + grub=<file> [grubcfg=<config>] + sets: file=<file> seg=0x800::0x200 nohand nosect grub + +Chainloads grub legacy's stage2, performing additional corrections on the file +in memory. Additionally, alternate config file can be specified through +'grubcfg=' option + + grldr=<file> + sets: file=<file> nohand nosect grldr + +Chainloads GRUB4DOS grldr, performing additional corrections on the file +in memory. + + bss=<file> + sets: file=<file> nomaps setbpb bss + +This emulates syslinux's native BSS option. This loads both the file and the +sector, adjusts BPB values in the loaded sector, then copies all possible BPB +fields to the loaded file. Everything is made with reference to the selected +disk/partition. + + bs=<file> + sets: file=<file> nosect filebpb + +This emulates syslinux's native BS option. This loads the file and if possible +- adjusts its BPB values. Everything is made with reference to the selected +disk/partition. + diff --git a/doc/comboot.txt b/doc/comboot.txt index 04d5deb8..6e9d7ab5 100644 --- a/doc/comboot.txt +++ b/doc/comboot.txt @@ -560,29 +560,7 @@ AX=000Ch [2.00] Perform final cleanup 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=000Dh [2.08] Obsoleted in 3.80 AX=000Eh [2.11] Get configuration file name @@ -627,57 +605,7 @@ AX=0010h [3.00] Resolve hostname [PXELINUX] AX=0011h [3.05] Obsoleted in 3.80 -AX=0012h [3.50] Cleanup, shuffle and boot - Input: AX 0012h - DX derivative-specific flags (see function 000Ch) - ES:DI shuffle descriptor list (must be in low memory) - CX number of shuffle descriptors - EBX(!) initial value of EDX after bootstrap - ESI initial value of ESI after bootstrap - DS initial value of DS after bootstrap - EBP CS:IP of routine to jump to - Output: Does not return - (if CX is too large the routine returns with CF=1) - - This routine performs final cleanup, then performs a sequence - of copies, and jumps to a specified real mode entry point. - This is a more general version of function 000Dh, which can - also be used to load other types of programs. - - The copies must not touch memory below address 7C00h. - - ES:DI points to a list of CX descriptors each of the form: - - Offset Size Meaning - 0 dword destination address - 4 dword source address - 8 dword length in bytes - - The copies are overlap-safe, like memmove(). - - Starting in version 3.50, if the source address is -1 - (FFFFFFFFh) then the block specified by the destination - address and the length is set to all zero. - - Starting in version 3.50, if the destination address is -1 - (FFFFFFFFh) then the data block is loaded as a new set of - descriptors, and processing is continued (and unprocessed - descriptors are lost, this is thus typically only used as the - last descriptor in a block.) The block must still fit in the - internal descriptor buffer (see function 0011h), but can, of - course, itself chain another block. - - - Normal boot sectors expect DL to contain the drive number, - and, for hard drives (DL >= 80h) DS:SI to contain a pointer to - the 16-byte partition table entry. The memory between - 600h-7FFh is available to put the partition table entry in. - - For PXELINUX, if the PXE stack is not unloaded, all registers - (except DS, ESI and EDX) and the stack will be set up as they - were set up by the PXE ROM. - - This interface was probably broken before version 3.50. +AX=0012h [3.50] Obsoleted in 3.80 AX=0013h [3.08] Idle loop call diff --git a/doc/gpt.txt b/doc/gpt.txt index 09099320..2ef387a9 100644 --- a/doc/gpt.txt +++ b/doc/gpt.txt @@ -51,7 +51,7 @@ form: 4 1 0xED (partition type: synthetic) 5 3 CHS of partition end 8 4 Partition start LBA - 12 4 Partition end LBA + 12 4 Partition length in sectors 16 4 Length of the GPT entry 20 varies GPT partition entry diff --git a/doc/isolinux.txt b/doc/isolinux.txt index eca2a974..807c6311 100644 --- a/doc/isolinux.txt +++ b/doc/isolinux.txt @@ -100,34 +100,3 @@ The ISO 9660 filesystem is encapsulated in a partition (which starts at offset zero, which may confuse some systems.) This makes it possible for the operating system, once booted, to use the remainder of the device for persistent storage by creating a second partition. - - - ++++ BOOTING DOS (OR OTHER SIMILAR OPERATING SYSTEMS) ++++ - -WARNING: This feature depends on BIOS functionality which is -apparently broken in a very large number of BIOSes. Therefore, this -may not work on any particular system. No workaround is possible; if -you find that it doesn't work please complain to your vendor and -indicate that "BIOS INT 13h AX=4C00h fails." - -To boot DOS, or other real-mode operating systems (protected-mode -operating systems may or may not work correctly), using ISOLINUX, you -need to prepare a disk image (usually a floppy image, but a hard disk -image can be used on *most* systems) with the relevant operating -system. This file should be included on the CD-ROM in the /isolinux -directory, and have a .img extension. The ".img" extension does not -have to be specified on the command line, but has to be explicitly -specified if used in a "kernel" statement in isolinux.cfg. - -For a floppy image, the size of the image should be exactly one of the -following: - - 1,228,800 bytes - For a 1200K floppy image - 1,474,560 bytes - For a 1440K floppy image - 2,949,120 bytes - For a 2880K floppy image - -Any other size is assumed to be a hard disk image. In order to work -on as many systems as possible, a hard disk image should have exactly -one partition, marked active, that covers the entire size of the disk -image file. Even so, hard disk images are not supported on all -BIOSes. diff --git a/doc/logo/LICENSE b/doc/logo/LICENSE new file mode 100644 index 00000000..e753087f --- /dev/null +++ b/doc/logo/LICENSE @@ -0,0 +1,5 @@ +The Syslinux logo is licensed under the Creative Commons +Attribution-ShareAlike 3.0 Unported License. To view a copy of this +license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send +a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain +View, California, 94041, USA. diff --git a/doc/logo/syslinux-100.png b/doc/logo/syslinux-100.png Binary files differnew file mode 100644 index 00000000..647635a2 --- /dev/null +++ b/doc/logo/syslinux-100.png diff --git a/doc/menu.txt b/doc/menu.txt index 620527e6..8a999cd4 100644 --- a/doc/menu.txt +++ b/doc/menu.txt @@ -18,7 +18,7 @@ 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 +com32/menu/vesamenu.c32 (graphical) or com32/menu/menu.c32 (text mode only). It uses the same configuration file as the regular Syslinux command line, and displays all the LABEL statements. diff --git a/doc/pxechn.txt b/doc/pxechn.txt new file mode 100644 index 00000000..7853d9ab --- /dev/null +++ b/doc/pxechn.txt @@ -0,0 +1,138 @@ += pxechn.c32(1) = +:doctype: manpage +:author: Gene Cumm +:email: gene.cumm@gmail.com +:revdate: 2012-09-16 + + +== NAME == +pxechn.c32 - Chainboot to new Network Boot Program (NBP) + + +== SYNOPSIS == +[verse] +*pxechn.c32* [-h | --help | -?] +*pxechn.c32* -r 'FILE' +*pxechn.c32* 'FILE' ['OPTIONS'] + + +== DESCRIPTION == +Chainboot to a new Network Boot Program (NBP) 'FILE' with options to +adjust PXE packet #3 (PXENV_PACKET_TYPE_CACHED_REPLY) to alter end +behavior. 'FILE' may be a filename, an IP::FN ( +192.168.1.1::path/to/file.0 ), or URL. 'FILE' is parsed to adjust the +DHCP 'sname' field/option 66 and 'file' field/option 67. +// but these may be override-able in the future. + + +== OPTIONS == +*-c* 'CONFIG':: + 'config' file for PXELINUX (DHCP Option 209). + +// *-f* 'MOD':: +// 'Force' behavior specified by modifier 'MOD' +// +// *-g* 'HOST':: +// Set 'gateway'/relay DHCP field to 'HOST'. Parsed by pxe_dns(). +// +*-h*, *--help*, *-?*:: + Print 'help'/usage information; invalid options will also cause + this. + +// *-n*:: +// Use 'native' methods, ignoring underlying gPXE/iPXE. +// +// *-N*:: +// Use 'non-native' methods to utilize gPXE/iPXE (if available). +// +*-o* 'OPT.TYPE=VALUE':: + Set 'option'. 'OPT' is in 'DECIMAL INPUT' format (below). 'TYPE' + specifies the output type and input syntax (listed here in quotes + and at present, 1 character). ''b'yte', ''w'ord'(2B), ''l'ong'(4B), + ''q'uad'(8B), character ''s'tring' and colon-separated 'he'x'' + string (case insensitive; bytes must have 2 digits and each byte + must be separated). byte, word, long and quad input values must + meet criteria for 'DECIMAL INPUT' + +*-p* 'PATH':: + 'path' option for PXELINUX (DHCP Option 210). + +*-r*:: + 'restart'. Call the PXE stack with PXENV_RESTART_TFTP. _Must_ be + the only option and before 'FILE'. + +*-S*:: + Set 'sip' based on sname field/option 66 (by direct IP if a + period-delimited address or otherwise DNS). + +*-t* 'SECONDS':: + 'timeout' option for PXELINUX (DHCP Option 211). + +// *-u*:: +// Copy 'UUID' (Option 97) if found in packet #1 + +*-w*:: + 'wait'. After loading, wait for user input before booting. + +*-W*:: + Enable 'WDS' (Windows Deployment Services) - specific options. + 'FILE' (or its overrides for DHCP fields siaddr and file) must point + at the WDS server. + *NOTE:* As of 2012-05-31, there is a known issue with gPXE/iPXE, at + least with undionly.kkpxe. +// PXELINUX asks gPXE/iPXE to unload, reverting to an underlying stack + + +== DECIMAL INPUT == +All parameters that are defaulted to decimal format are processed by +*strtoul*(3) with a base of 0 which allows alternate formats and finds a +suitable non-space separating character. + + +== EXAMPLES == +`pxechn.c32 http://myhost.dom.loc/path/nbp.0 -c myconfig`:: + Load nbp.0 and set PXELINUX config (option 209). + +`pxechn.c32 gpxelinux.0 -p http://10.1.1.4/tftp/ -w -c myconfig -o 15.s=domain.loc -o 6.x=0A:01:01:02:ac:17:4D:Ec -`:: + Load gpxelinux.0 from the current directory, set prefix, wait to + execute, set first config, set the domain name and 2 domain name + servers (case mixed to show insensitivity; 10.1.1.2 and + 172.23.77.236). + +`pxechn.c32 gpxelinux.0 -p http://10.1.1.4/tftp/ -w -o 0xA0.x=12:34:56:78 -x 197.x=00:d0:de:00`:: + Load gpxelinux.0 (relative to the current directory and not + altering sname/option 66), set the PXELINUX path prefix, wait after + loading, set option 160 to 0x12 0x34 0x56 0x78, and option 197 to + 0x00 0xD0 0xDE 0x00. + +`pxechn.c32 10.1.1.8:boot\x86\wdsnbp.com -W`:: + Load wdsnbp.com from 10.1.1.8 and copy DHCP Option 66 to DHCP + field sname if there's room. + +`pxechn.c32 10.1.1.4:boot\x86\wdsnbp.com -W -o 66.x=0a:01:01:08 -S`:: + Load wdsnbp.com from 10.1.1.4, point packets to 10.1.1.8 for use + with WDS, copy DHCP Option 66 to DHCP field sname if there's room + and decode this to an IPv4 address. + + +== NOTES == +Please note that some NBPs may ignore packet #3 by either not examining +it at all or by issuing its own DHCP DISCOVER/REQUEST, negating all DHCP +field/option modifications by pxechn.c32, including Microsoft Windows +Server 2008R2 WDS's wdsnbp.com. See also option '-W'. + +URL specifications in 'FILE' that include user/password before the host +will currently cause the siaddr field to not be set properly. + +The non-space constraint is due to how Syslinux variants parse the +command line as of 2012-09-16. + + +== AUTHOR == +{author} <{email}> + + +== COPYRIGHT == +Copyright \(C) 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). diff --git a/doc/syslinux.txt b/doc/syslinux.txt index 07d5df9a..033a1ec0 100644 --- a/doc/syslinux.txt +++ b/doc/syslinux.txt @@ -100,7 +100,7 @@ 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 +mtools program suite to be available, and one in the "linux" directory which requires root privilege. |
