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