"Fossies" - the Fresh Open Source Software Archive

Member "syslinux-6.03/doc/chain.txt" (6 Oct 2014, 12370 Bytes) of package /linux/misc/syslinux-6.03.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "chain.txt": 6.02_vs_6.03.

    1 			    chain.c32 documentation
    2 
    3 Although syslinux is capable of (very simple) native chainloading (through .bss
    4 and .bs options - see doc/syslinux.txt), it also features a very roboust and
    5 rich com32 module designed for such purpose.
    6 
    7 Chain module can perform few basic tasks:
    8 
    9 - load and jump to a sector
   10 - load and jump to a file (also loading a sector for other purposes)
   11 - prepare handover data to use by a file / boot sector
   12 - fix different options in a file / sector / partition entries
   13 - perform a "service-only" run
   14 
   15 It can chainload data from both GPT and DOS partitions, as well as boot the
   16 first sector from a raw disk.
   17 
   18 In more details, the rough overview of code is as follows:
   19 
   20 1.  Parse arguments.
   21 2.  Find drive and/or partition to boot from.
   22 3.  Perform partition-level patching - for example hiding, unhiding, fixing chs values, etc.
   23 4.  Load a file to boot from.
   24 5.  Load a sector to boot from, if it doesn't conflict with #5.
   25 6.  Prepare handover area, if it doesn't conflict with #5 & #6.
   26 7.  Prepare registers.
   27 8.  Patch loaded file if necessary.
   28 9.  Patch loaded sector if necessary.
   29 10. Chainload.
   30 
   31 In most basic form, syslinux loads specified boot sector (or mbr, if not
   32 specified) at 0:0x7c00, prepares handover area as a standard mbr would do, and
   33 jumps to 0:0x7c00.
   34 
   35 A "service-only" run is possible when either:
   36 
   37 - 'break' is in effect
   38 
   39 or
   40 
   41 - 'nofile' and 'nomaps' (or 'nosect') are in effect
   42 
   43 This is useful for invocations such as:
   44 
   45 chain.c32 hdN M setbpb save break
   46 chain.c32 hdN fixchs break
   47 chain.c32 hdN unhideall break
   48 
   49 Please see respective options for more details.
   50 
   51 
   52 Module invocation:
   53 
   54 chain [drive/partition] [options]
   55 
   56 In case of repeated arguments, rightmost ones take precedence.
   57 
   58 
   59 			DRIVE / PARTITION SPECIFICATION
   60 
   61 Drive can be specified as 'hd#', 'fd#', 'boot', 'mbr', or 'guid'.
   62 
   63 - 'mbr' will select a drive by its signature.
   64 - 'guid' will select a drive by its guid (GPT only).
   65 - 'boot' is the drive syslinux was booted from. This is the default value, if
   66   nothing else is specified.
   67 - 'hd#' and 'fd#' are standard ways to specify drive number as seen by bios,
   68   starting from 0.
   69 
   70 Option 'guid' is shared with partition selection (see below). If you happen
   71 to have non-unique guids, they are searched in disk0, partitions of disk0,
   72 disk1 ...  order.
   73 
   74 'mbr' and 'guid' take extra parameter - you should use ':' or '=' as a
   75 delimiter.
   76 
   77 Partition can be specified as '#', 'guid', 'label' or 'fs'.
   78 
   79 - 'guid' option will select a partition by a guid (not a type guid !)
   80 - 'label' will select a partition by a label (searching is done in
   81   disk order)
   82 - 'fs' will select a partition from which syslinux was executed
   83 - '#' is the standard method. Partitions 1-4 are primary, 5+ logical, 0 = boot
   84   MBR (default).
   85 
   86 If you use a number to select a partition it should be specified after a drive
   87 using space or comma as delimiters (after 'hd#', 'fd#', 'mbr', 'guid' or 'boot').
   88 
   89 
   90 				    OPTIONS
   91 	file=<file>
   92        *nofile
   93 
   94 It's often convenient to load a file directly and transfer control to it,
   95 instead of the sector from the disk. Note, that the <file> must reside on
   96 syslinux partition.
   97 
   98 If you choose this option without specifying any addresses explicitly (see
   99 options 'sect=' and 'seg='), the file will cause sector to not be loaded at all
  100 (as their memory placement would overlap).
  101 
  102 	seg=<segment>:<offset>:<ip>
  103 	*seg=0:0x7c00:0x7c00
  104 
  105 This triplet lets you alter the addresses a file will use. It's loaded at
  106 <segment:offset>, the entry point is at <segment:ip>. When you chainload some
  107 other bootloader or kernel, it's almost always mandatory.
  108 
  109 The defaults, if option is not specified, are 0:0x7c00:0x7c00
  110 If any of the fields are omitted (e.g. 0x2000::), they default to 0.
  111 
  112 	sect=<segment>:<offset>:<ip>
  113 	*sect=0:0x7c00:0x7c00
  114 	nosect
  115 	nosect sets: nomaps
  116 
  117 This triplet lets you alter the addresses a sector will use. It's loaded at
  118 <segment:offset>, the entry point is at <segment:ip>. This option is mostly
  119 used in tandem with 'file=' and 'seg=' options, as some loaders/kernels will
  120 expect relocated sector at some particular address (e.g. DRKM).
  121 
  122 'nosect' will cause sector to not be loaded at all. In plenty cases, when a file
  123 is being chainloaded, sector is not necessary.
  124 
  125 The defaults if option is not specified, are 0:0x7c00:0x7c00.
  126 If some of the fields are omitted (e.g. 0x2000::), they default to 0.
  127 
  128 	*maps
  129 	nomaps
  130 
  131 In some cases, it's useful to fix BPB values in NTFS/FATxx bootsectors and
  132 evntually write them back, but otherwise boot sector itself is not necessary to
  133 continue booting. 'nomaps' allows that - a sector will be loaded, but won't be
  134 mmapped into real memory. Any overlap tests (vs. handover or file areas) are
  135 not performed, being meaningless in such case.
  136 
  137 	setbpb
  138 	*nosetbpb
  139 
  140 Microsoft side of the world is paritculary sensitive to certain BPB values.
  141 Depending on the system and chainloading method (sector or file), some or all
  142 of those fields must match reality - and after e.g. drive clonning or
  143 when using usb stick in different computers - that is often not the case.
  144 
  145 The "reality" means:
  146 
  147 "hidden sectors" - valid offset of the partition from the beginning of the disk
  148 "geometry" - valid disk geometry as reported by BIOS
  149 "drive" - valid drive number
  150 
  151 This option will automatically determine the type of BPB and fix what is possible
  152 to fix, relatively to detected BPB. If it's impossible to detect BPB, function
  153 will do nothing.
  154 
  155 	filebpb
  156 	*nofilebpb
  157 
  158 Chainloaded file can simply be an image of a sector. In such case, it could be
  159 useful to also fix its BPB values.
  160 
  161 	save
  162 	*nosave
  163 	save sets: strict=2
  164 
  165 Fixing BPB values only in memory might not be enough. This option allows
  166 writing of the corrected sector. You will probably want to use this option
  167 together with 'setbpb'.
  168 
  169 - this option never applies to a loaded file
  170 - chain module will not save anything to disk by default (besides options such
  171   as hide or fixchs - so options related directly to partition entries)
  172 - writing is only performed, if the values actually changed
  173 
  174 	*hand
  175 	nohand
  176 
  177 By default, a handover area is always prepared if possible - meaning it doesn't
  178 overlap with other areas. It's often not necessary though - usually, a
  179 chainloaded file or kernel don't care about it anymore, so a user can disable
  180 it explicitly with this option.
  181 
  182 	hptr
  183 	*nohptr
  184 
  185 In case when both file and sector are loaded, ds:si and ds:bp will point to
  186 sector address before the chainloading. This option lets user force those
  187 registers to point to handover area. This is useful when both the file and the
  188 sector are actually a sector's image and the sector is mmapped.
  189 
  190 	swap
  191 	*noswap
  192 
  193 This option will install a tiny stub code used to swap drive numbers, if the
  194 drive we use during chainloading is not fd0 or hd0.
  195 
  196 	hide[all]
  197 	unhide[all]
  198 	*nohide
  199 	[un]hide[all] sets: strict=2
  200 
  201 In certain situations it's useful to hide partitions - for example to make sure
  202 DOS gets C:. 'hide' will hide hidable primary partitions, except the one we're
  203 booting from. Similary, 'hideall' will hide all hidable partitions, except the
  204 one we're booting from. Hiding is performed only on the selected drive. Options
  205 starting with 'un' will simply unhide every partition (primary ones or all).
  206 Writing is only performed, if the os type values actually changed.
  207 
  208 	fixchs
  209 	*nofixchs
  210 	fixchs sets: strict=2
  211 
  212 If you want to make a drive you're booting from totally compatible with current
  213 BIOS, you can use this to fix all partitions' CHS numbers. Good to silence e.g.
  214 FreeDOS complainig about 'logical CHS differs from physical' of sfdisk about
  215 'found (...) expected (...).  Functionally seems to be mostly cosmetic, as
  216 Microsoft world - in cases it cares about geometry - generally sticks to values
  217 written in bootsectors. And the rest of the world generally doesn't care about
  218 them at all. Writing is only performed, if the values actually got changed.
  219 
  220 	keepexe
  221 	*nokeepexe
  222 
  223 If you're booting over a network using pxelinux - this lets you keep UNDI
  224 stacks in memory (pxelinux only).
  225 
  226 	warn
  227 	*nowarn
  228 
  229 This option will wait for a keypress right before continuing the chainloading.
  230 Useful to see warnings emited by the chain module.
  231 
  232 	prefmbr
  233 	*noprefmbr
  234 
  235 In the case of presence of non-standard hybrid MBR/GPT layout, this flag makes
  236 chain module prefer MBR layout over GPT.
  237 
  238 	strict[=<0|1|2>]
  239 	*strict=1
  240 	relax
  241 
  242 Those options control the level of sanity checks used during the traversal of
  243 partition table(s). This is useful in buggy corner cases, when the disk size is
  244 reported differently across different computers or virtual machines (if it
  245 happens at all, the size usually differs by 1 sector). Normally the partition
  246 iterator would report an error and abort in such case. Another case scenario is
  247 disk corruption in some later EMBR partition.
  248 
  249 - strict=0 inhibits any checks
  250 - strict=1 enables checks, but ignores those that involve disk size
  251 - strict=2 enables all checks
  252 - relax and nostrict are equivalent to strict=0
  253 - norelax and strict are equivalent to strict=2
  254 
  255 
  256 	break
  257 	*nobreak
  258 	break sets: nofile nomaps nohand
  259 
  260 It is possible to trigger a "service-only" run - The chain module will do
  261 everything requested as usual, but it will not perform the actual chainloading.
  262 'break' option disables handover, file loading and sector mapping, as these
  263 are pointless in such scenario (although file might be reenabled in some future
  264 version, if writing to actual files becomes possible). Mainly useful for
  265 options 'fixchs', '[un]hide[all]' and setbpb.
  266 
  267 	isolinux=<file>
  268 	sets: file=<file> nohand nosect isolinux
  269 
  270 Chainload another version/build of the ISOLINUX bootloader and patch the loader
  271 with appropriate parameters in memory. This avoids the need for the
  272 -eltorito-alt-boot parameter of mkisofs, when you want more than one ISOLINUX
  273 per CD/DVD.
  274 
  275 	ntldr=<file>
  276 	sets: file=<file> seg=0x2000 setbpb nohand
  277 
  278 Prepares to load ntldr directly. You might want to add 'save' option to store
  279 corrected BPB values.
  280 
  281 	cmldr=<file>
  282 	sets: file=<file> seg=0x2000 setbpb nohand cmldr
  283 
  284 Prepares to load recovery console directly. In-memory copy of bootsector is
  285 patched with "cmdcons\0". Remarks the same as in 'ntldr='.
  286 
  287 	reactos=<file>
  288 	sets: file=<file> seg=0:0x8000:0x8100 setbpb nohand
  289 
  290 Prepares to load ReactOS's freeldr directly. You might want to add 'save'
  291 option to store corrected BPB values.
  292 
  293 	freedos=<file>
  294 	sets: file=<file> seg=0x60 sect=0x1FE0 setbpb nohand
  295 
  296 Prepares to load freedos kernel directly. You will likely want to add 'save'
  297 option, as those kernels seem to require proper geometry written back to disk.
  298 Sector address is chosen based on where freedos' bootsectors relocate themselves,
  299 although it seems the kernel doesn't rely on it.
  300 
  301 You might also want to employ 'hide' option, if you have problems with properly
  302 assigned C: drive.
  303 
  304 	pcdos=<file>
  305 	msdos=<file>
  306 	sets: file=<file> seg=0x70 sect=0x8000 setbpb nohand
  307 
  308 Similary to 'freedos=', This prepares to load MSDOS 2.00 - 6.xx or derivatives.
  309 Sector address is chosen arbitrarily. Otherwise comments as above.
  310 
  311 	msdos7=<file>
  312 	sets: file=<file> seg=0x70::0x200 sect=0x8000 setbpb nohand
  313 
  314 Only for MSDOS 7+ versions (98se ~ 7.xx, Me ~ 8.xx). Comments as above.
  315 TODO/TEST
  316 
  317 	drmk=<file>
  318 	sets: file=<file> seg=0x70 sect=0x2000:0:0 setbpb nohand
  319 
  320 This is used for loading of *only* Dell's DOS derivatives. It does require boot
  321 sector at 0x2000 and overall valid BPB values. As in other DOS-ish cases,
  322 likely candidates for use are 'save' and 'hide'.
  323 
  324 	grub=<file> [grubcfg=<config>]
  325 	sets: file=<file> seg=0x800::0x200 nohand nosect grub
  326 
  327 Chainloads grub legacy's stage2, performing additional corrections on the file
  328 in memory. Additionally, alternate config file can be specified through
  329 'grubcfg=' option
  330 
  331 	grldr=<file>
  332 	sets: file=<file> nohand nosect grldr
  333 
  334 Chainloads GRUB4DOS grldr, performing additional corrections on the file
  335 in memory.
  336 
  337 	bss=<file>
  338 	sets: file=<file> nomaps setbpb bss
  339 
  340 This emulates syslinux's native BSS option. This loads both the file and the
  341 sector, adjusts BPB values in the loaded sector, then copies all possible BPB
  342 fields to the loaded file. Everything is made with reference to the selected
  343 disk/partition.
  344 
  345 	bs=<file>
  346 	sets: file=<file> nosect filebpb
  347 
  348 This emulates syslinux's native BS option. This loads the file and if possible
  349 - adjusts its BPB values. Everything is made with reference to the selected
  350 disk/partition.
  351