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