doc/chain.txt

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