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         unhide[all]
 185         *nohide
 186
 187 In certain situations it's useful to hide partitions - for example to make sure
 188 DOS gets C:. 'hide' will hide hidable primary partitions, except the one we're
 189 booting from. Similary, 'hideall' will hide all hidable partitions, except the
 190 one we're booting from. Hiding is performed only on the booting drive. Options
 191 starting with 'un' will simply unhide every partition (primary ones or all).
 192 Writing is only performed, if the os type values actually changed.
 193
 194         mbrchs
 195         *nombrchs
 196
 197 If you want to make a drive you're booting from totally compatible with current
 198 BIOS, you can use this to fix all partitions' CHS numbers. Good to silence e.g.
 199 FreeDOS complainig about 'logical CHS differs from physcial' of sfdisk about
 200 'found (...) expected (...).  Functionally seems to be mostly cosmetic, as
 201 Microsoft world - in cases it cares about geometry - generally sticks to values
 202 written in bootsectors. And the rest of the world generally doesn't care about
 203 them at all. Writing is only performed, if the values actually got changed.
 204
 205         keepexe
 206         *nokeepexe
 207
 208 If you're booting over a network using pxelinux - this lets you keep UNDI
 209 stacks in memory (pxelinux only).
 210
 211         warn
 212         *nowarn
 213
 214 This option will wait for a keypress right before continuing the chainloading.
 215 Useful to see warnings emited by the chain module.
 216
 217         isolinux=<file>
 218         sets: file=<file> nohand nosect isolinux
 219
 220 Chainload another version/build of the ISOLINUX bootloader and patch the loader
 221 with appropriate parameters in memory. This avoids the need for the
 222 -eltorito-alt-boot parameter of mkisofs, when you want more than one ISOLINUX
 223 per CD/DVD.
 224
 225         ntldr=<file>
 226         sets: file=<file> seg=0x2000 setbpb nohand
 227
 228 Prepares to load ntldr directly. You might want to add 'save' option to store
 229 corrected BPB values.
 230
 231         cmldr=<file>
 232         sets: file=<file> seg=0x2000 setbpb nohand cmldr
 233
 234 Prepares to load recovery console directly. In-memory copy of bootsector is
 235 patched with "cmdcons\0". Remarks the same as in 'ntldr='.
 236
 237         freedos=<file>
 238         sets: file=<file> seg=0x60 sect=0x1FE0 setbpb nohand
 239
 240 Prepares to load freedos kernel directly. You will likely want to add 'save'
 241 option, as those kernels seem to require proper geometry written back to disk.
 242 Sector address is chosen based on where freedos' bootsectors relocate themselves,
 243 although it seems the kernel doesn't rely on it.
 244
 245 You might also want to employ 'hide' option, if you have problems with properly
 246 assigned C: drive.
 247
 248         pcdos=<file>
 249         msdos=<file>
 250         sets: file=<file> seg=0x70 sect=0x8000 setbpb nohand
 251
 252 Similary to 'freedos=', This prepares to load MSDOS 2.00 - 6.xx or derivatives.
 253 Sector address is chosen arbitrarily. Otherwise comments as above.
 254
 255         msdos7=<file>
 256         sets: file=<file> seg=0x70::0x200 sect=0x8000 setbpb nohand
 257
 258 Only for MSDOS 7+ versions (98se ~ 7.xx, Me ~ 8.xx). Comments as above.
 259 TODO/TEST
 260
 261         drmk=<file>
 262         sets: file=<file> seg=0x70 sect=0x2000:0:0 setbpb nohand
 263
 264 This is used for loading of *only* Dell's DOS derivatives. It does require boot
 265 sector at 0x2000 and overall valid BPB values. As in other DOS-ish cases,
 266 likely candidates for use are 'save' and 'hide'.
 267
 268         grub=<file> [grubcfg=<config>]
 269         sets: file=<file> seg=0x800::0x200 nohand nosect grub
 270
 271 Chainloads grub legacy's stage2, performing additional corrections on the file
 272 in memory. Additionally, alternate config file can be specified through
 273 'grubcfg=' option
 274
 275         grldr=<file>
 276         sets: file=<file> nohand nosect grldr
 277
 278 Chainloads GRUB4DOS grldr, performing additional corrections on the file
 279 in memory.
 280
 281         bss=<file>
 282         sets: bss=<file> nomaps setbpb bss
 283
 284 This emulates syslinux's native BSS option. This loads both the file and the
 285 sector, adjusts BPB values in the loaded sector, then copies all possible BPB
 286 fields to the loaded file. Everything is made with reference to the selected
 287 disk/partition.
 288
 289         bs=<file>
 290         sets: bs=<file> nosect filebpb
 291
 292 This emulates syslinux's native BS option. This loads the file and if possible
 293 - adjusts its BPB values. Everything is made with reference to the selected
 294 disk/partition.
 295