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