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/logo/LICENSE | 5 | ||||
| -rw-r--r-- | doc/menu.txt | 2 | ||||
| -rw-r--r-- | doc/pxechn.txt | 138 | ||||
| -rw-r--r-- | doc/syslinux.txt | 2 |
7 files changed, 475 insertions, 77 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/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/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. |