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' 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 mbrchs 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
 121 This triplet lets you alter the addresses a sector will use. File is loaded at
 122 <segment:offset>, the jump is made to <segment:ip>. This option is mostly used
 123 in tandem with 'file=' and 'seg=' options, as some loaders/kernels will expect
 124 relocated sector at some particular address (e.g. DRKM).
 125
 126 'nosect' will cause sector to not be loaded at all. In plenty cases, when a file
 127 is being chainloaded, sector is not necessary.
 128
 129 The defaults if option is not specified, are 0:0x7c00:0x7c00.
 130 If some of the fields are ommited (e.g. 0x2000::), segment defaults to 0,
 131 offset and ip to 0x7c00.
 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 got changed
 176
 177         *hand
 178         nohand
 179
 180 By default, a handover area is always prepared if possible and potentially
 181 useful - meaning it doesn't overlap with other areas, and syslinux chainloads a
 182 partition. It's often not necessary though - usually, a chainloaded file or
 183 kernel don't care about it anymore, so a user can disable it explicitly with
 184 this option.
 185
 186         hptr
 187         *nohptr
 188
 189 In case when both file and sector are loaded, ds:si and ds:bp will point to
 190 sector address before the chainloading. This option lets user force those
 191 registers to point to handover area. This is useful when both the file and the
 192 sector are actually a sector's image and the sector is mmapped.
 193
 194         swap
 195         *noswap
 196
 197 This option will install a tiny stub code used to swap drive numbers, if the
 198 drive we use during chainloading is not fd0 or hd0.
 199
 200         hide[all]
 201         unhide[all]
 202         *nohide
 203
 204 In certain situations it's useful to hide partitions - for example to make sure
 205 DOS gets C:. 'hide' will hide hidable primary partitions, except the one we're
 206 booting from. Similary, 'hideall' will hide all hidable partitions, except the
 207 one we're booting from. Hiding is performed only on the selected drive. Options
 208 starting with 'un' will simply unhide every partition (primary ones or all).
 209 Writing is only performed, if the os type values actually changed.
 210
 211         mbrchs
 212         *nombrchs
 213
 214 If you want to make a drive you're booting from totally compatible with current
 215 BIOS, you can use this to fix all partitions' CHS numbers. Good to silence e.g.
 216 FreeDOS complainig about 'logical CHS differs from physical' of sfdisk about
 217 'found (...) expected (...).  Functionally seems to be mostly cosmetic, as
 218 Microsoft world - in cases it cares about geometry - generally sticks to values
 219 written in bootsectors. And the rest of the world generally doesn't care about
 220 them at all. Writing is only performed, if the values actually got changed.
 221
 222         keepexe
 223         *nokeepexe
 224
 225 If you're booting over a network using pxelinux - this lets you keep UNDI
 226 stacks in memory (pxelinux only).
 227
 228         warn
 229         *nowarn
 230
 231 This option will wait for a keypress right before continuing the chainloading.
 232 Useful to see warnings emited by the chain module.
 233
 234         *chain
 235         nochain
 236         nochain sets: nofile nomaps nohand
 237
 238 It is possible to trigger a "service-only" run - The chain module will do
 239 everything requested as usual, but it will not perform the actual chainloading.
 240 'nochain' option disables handover, file loading and sector mapping, as these
 241 are pointless in such scenario (although file might be reenabled in some future
 242 version, if writing to actual files becomes possible). Mainly useful for
 243 options 'mbrchs', '[un]hide[all]' and setbpb.
 244
 245         isolinux=<file>
 246         sets: file=<file> nohand nosect isolinux
 247
 248 Chainload another version/build of the ISOLINUX bootloader and patch the loader
 249 with appropriate parameters in memory. This avoids the need for the
 250 -eltorito-alt-boot parameter of mkisofs, when you want more than one ISOLINUX
 251 per CD/DVD.
 252
 253         ntldr=<file>
 254         sets: file=<file> seg=0x2000 setbpb nohand
 255
 256 Prepares to load ntldr directly. You might want to add 'save' option to store
 257 corrected BPB values.
 258
 259         cmldr=<file>
 260         sets: file=<file> seg=0x2000 setbpb nohand cmldr
 261
 262 Prepares to load recovery console directly. In-memory copy of bootsector is
 263 patched with "cmdcons\0". Remarks the same as in 'ntldr='.
 264
 265         freedos=<file>
 266         sets: file=<file> seg=0x60 sect=0x1FE0 setbpb nohand
 267
 268 Prepares to load freedos kernel directly. You will likely want to add 'save'
 269 option, as those kernels seem to require proper geometry written back to disk.
 270 Sector address is chosen based on where freedos' bootsectors relocate themselves,
 271 although it seems the kernel doesn't rely on it.
 272
 273 You might also want to employ 'hide' option, if you have problems with properly
 274 assigned C: drive.
 275
 276         pcdos=<file>
 277         msdos=<file>
 278         sets: file=<file> seg=0x70 sect=0x8000 setbpb nohand
 279
 280 Similary to 'freedos=', This prepares to load MSDOS 2.00 - 6.xx or derivatives.
 281 Sector address is chosen arbitrarily. Otherwise comments as above.
 282
 283         msdos7=<file>
 284         sets: file=<file> seg=0x70::0x200 sect=0x8000 setbpb nohand
 285
 286 Only for MSDOS 7+ versions (98se ~ 7.xx, Me ~ 8.xx). Comments as above.
 287 TODO/TEST
 288
 289         drmk=<file>
 290         sets: file=<file> seg=0x70 sect=0x2000:0:0 setbpb nohand
 291
 292 This is used for loading of *only* Dell's DOS derivatives. It does require boot
 293 sector at 0x2000 and overall valid BPB values. As in other DOS-ish cases,
 294 likely candidates for use are 'save' and 'hide'.
 295
 296         grub=<file> [grubcfg=<config>]
 297         sets: file=<file> seg=0x800::0x200 nohand nosect grub
 298
 299 Chainloads grub legacy's stage2, performing additional corrections on the file
 300 in memory. Additionally, alternate config file can be specified through
 301 'grubcfg=' option
 302
 303         grldr=<file>
 304         sets: file=<file> nohand nosect grldr
 305
 306 Chainloads GRUB4DOS grldr, performing additional corrections on the file
 307 in memory.
 308
 309         bss=<file>
 310         sets: file=<file> nomaps setbpb bss
 311
 312 This emulates syslinux's native BSS option. This loads both the file and the
 313 sector, adjusts BPB values in the loaded sector, then copies all possible BPB
 314 fields to the loaded file. Everything is made with reference to the selected
 315 disk/partition.
 316
 317         bs=<file>
 318         sets: file=<file> nosect filebpb
 319
 320 This emulates syslinux's native BS option. This loads the file and if possible
 321 - adjusts its BPB values. Everything is made with reference to the selected
 322 disk/partition.
 323