Index: bootcd/isolinux/syslinux-6.03/doc/chain.txt
===================================================================
--- bootcd/isolinux/syslinux-6.03/doc/chain.txt	(revision e16e8f2a41938d263af54a9fd6b4020d6c0d69fa)
+++ bootcd/isolinux/syslinux-6.03/doc/chain.txt	(revision e16e8f2a41938d263af54a9fd6b4020d6c0d69fa)
@@ -0,0 +1,351 @@
+			    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]
+
+In case of repeated arguments, rightmost ones take precedence.
+
+
+			DRIVE / PARTITION SPECIFICATION
+
+Drive can be specified as 'hd#', 'fd#', 'boot', 'mbr', or 'guid'.
+
+- 'mbr' will select a drive by its signature.
+- 'guid' will select a drive by its guid (GPT only).
+- '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 happen
+to have non-unique guids, they are searched in disk0, partitions of disk0,
+disk1 ...  order.
+
+'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).
+
+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 omitted (e.g. 0x2000::), they default to 0.
+
+	sect=<segment>:<offset>:<ip>
+	*sect=0:0x7c00:0x7c00
+	nosect
+	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 omitted (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
+	save sets: strict=2
+
+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
+	[un]hide[all] sets: strict=2
+
+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
+	fixchs sets: strict=2
+
+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.
+
+	prefmbr
+	*noprefmbr
+
+In the case of presence of non-standard hybrid MBR/GPT layout, this flag makes
+chain module prefer MBR layout over GPT.
+
+	strict[=<0|1|2>]
+	*strict=1
+	relax
+
+Those options control the level of sanity checks used during the traversal of
+partition table(s). This is useful in buggy corner cases, when the disk size is
+reported differently across different computers or virtual machines (if it
+happens at all, the size usually differs by 1 sector). Normally the partition
+iterator would report an error and abort in such case. Another case scenario is
+disk corruption in some later EMBR partition.
+
+- strict=0 inhibits any checks
+- strict=1 enables checks, but ignores those that involve disk size
+- strict=2 enables all checks
+- relax and nostrict are equivalent to strict=0
+- norelax and strict are equivalent to strict=2
+
+
+	break
+	*nobreak
+	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.
+
