"Fossies" - the Fresh Open Source Software Archive
Member "syslinux-6.03/doc/chain.txt" (6 Oct 2014, 12370 Bytes) of package /linux/misc/syslinux-6.03.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
See also the latest Fossies "Diffs"
side-by-side code changes report for "chain.txt": 6.02_vs_6.03
1 chain.c32 documentation
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.
7 Chain module can perform few basic tasks:
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
15 It can chainload data from both GPT and DOS partitions, as well as boot the
16 first sector from a raw disk.
18 In more details, the rough overview of code is as follows:
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.
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.
35 A "service-only" run is possible when either:
37 - 'break' is in effect
41 - 'nofile' and 'nomaps' (or 'nosect') are in effect
43 This is useful for invocations such as:
45 chain.c32 hdN M setbpb save break
46 chain.c32 hdN fixchs break
47 chain.c32 hdN unhideall break
49 Please see respective options for more details.
52 Module invocation:
54 chain [drive/partition] [options]
56 In case of repeated arguments, rightmost ones take precedence.
59 DRIVE / PARTITION SPECIFICATION
61 Drive can be specified as 'hd#', 'fd#', 'boot', 'mbr', or 'guid'.
63 - 'mbr' will select a drive by its signature.
64 - 'guid' will select a drive by its guid (GPT only).
65 - 'boot' is the drive syslinux was booted from. This is the default value, if
66 nothing else is specified.
67 - 'hd#' and 'fd#' are standard ways to specify drive number as seen by bios,
68 starting from 0.
70 Option 'guid' is shared with partition selection (see below). If you happen
71 to have non-unique guids, they are searched in disk0, partitions of disk0,
72 disk1 ... order.
74 'mbr' and 'guid' take extra parameter - you should use ':' or '=' as a
77 Partition can be specified as '#', 'guid', 'label' or 'fs'.
79 - 'guid' option will select a partition by a guid (not a type guid !)
80 - 'label' will select a partition by a label (searching is done in
81 disk order)
82 - 'fs' will select a partition from which syslinux was executed
83 - '#' is the standard method. Partitions 1-4 are primary, 5+ logical, 0 = boot
84 MBR (default).
86 If you use a number to select a partition it should be specified after a drive
87 using space or comma as delimiters (after 'hd#', 'fd#', 'mbr', 'guid' or 'boot').
94 It's often convenient to load a file directly and transfer control to it,
95 instead of the sector from the disk. Note, that the <file> must reside on
96 syslinux partition.
98 If you choose this option without specifying any addresses explicitly (see
99 options 'sect=' and 'seg='), the file will cause sector to not be loaded at all
100 (as their memory placement would overlap).
105 This triplet lets you alter the addresses a file will use. It's loaded at
106 <segment:offset>, the entry point is at <segment:ip>. When you chainload some
107 other bootloader or kernel, it's almost always mandatory.
109 The defaults, if option is not specified, are 0:0x7c00:0x7c00
110 If any of the fields are omitted (e.g. 0x2000::), they default to 0.
115 nosect sets: nomaps
117 This triplet lets you alter the addresses a sector will use. It's loaded at
118 <segment:offset>, the entry point is at <segment:ip>. This option is mostly
119 used in tandem with 'file=' and 'seg=' options, as some loaders/kernels will
120 expect relocated sector at some particular address (e.g. DRKM).
122 'nosect' will cause sector to not be loaded at all. In plenty cases, when a file
123 is being chainloaded, sector is not necessary.
125 The defaults if option is not specified, are 0:0x7c00:0x7c00.
126 If some of the fields are omitted (e.g. 0x2000::), they default to 0.
131 In some cases, it's useful to fix BPB values in NTFS/FATxx bootsectors and
132 evntually write them back, but otherwise boot sector itself is not necessary to
133 continue booting. 'nomaps' allows that - a sector will be loaded, but won't be
134 mmapped into real memory. Any overlap tests (vs. handover or file areas) are
135 not performed, being meaningless in such case.
140 Microsoft side of the world is paritculary sensitive to certain BPB values.
141 Depending on the system and chainloading method (sector or file), some or all
142 of those fields must match reality - and after e.g. drive clonning or
143 when using usb stick in different computers - that is often not the case.
145 The "reality" means:
147 "hidden sectors" - valid offset of the partition from the beginning of the disk
148 "geometry" - valid disk geometry as reported by BIOS
149 "drive" - valid drive number
151 This option will automatically determine the type of BPB and fix what is possible
152 to fix, relatively to detected BPB. If it's impossible to detect BPB, function
153 will do nothing.
158 Chainloaded file can simply be an image of a sector. In such case, it could be
159 useful to also fix its BPB values.
163 save sets: strict=2
165 Fixing BPB values only in memory might not be enough. This option allows
166 writing of the corrected sector. You will probably want to use this option
167 together with 'setbpb'.
169 - this option never applies to a loaded file
170 - chain module will not save anything to disk by default (besides options such
171 as hide or fixchs - so options related directly to partition entries)
172 - writing is only performed, if the values actually changed
177 By default, a handover area is always prepared if possible - meaning it doesn't
178 overlap with other areas. It's often not necessary though - usually, a
179 chainloaded file or kernel don't care about it anymore, so a user can disable
180 it explicitly with this option.
185 In case when both file and sector are loaded, ds:si and ds:bp will point to
186 sector address before the chainloading. This option lets user force those
187 registers to point to handover area. This is useful when both the file and the
188 sector are actually a sector's image and the sector is mmapped.
193 This option will install a tiny stub code used to swap drive numbers, if the
194 drive we use during chainloading is not fd0 or hd0.
199 [un]hide[all] sets: strict=2
201 In certain situations it's useful to hide partitions - for example to make sure
202 DOS gets C:. 'hide' will hide hidable primary partitions, except the one we're
203 booting from. Similary, 'hideall' will hide all hidable partitions, except the
204 one we're booting from. Hiding is performed only on the selected drive. Options
205 starting with 'un' will simply unhide every partition (primary ones or all).
206 Writing is only performed, if the os type values actually changed.
210 fixchs sets: strict=2
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.
223 If you're booting over a network using pxelinux - this lets you keep UNDI
224 stacks in memory (pxelinux only).
229 This option will wait for a keypress right before continuing the chainloading.
230 Useful to see warnings emited by the chain module.
235 In the case of presence of non-standard hybrid MBR/GPT layout, this flag makes
236 chain module prefer MBR layout over GPT.
242 Those options control the level of sanity checks used during the traversal of
243 partition table(s). This is useful in buggy corner cases, when the disk size is
244 reported differently across different computers or virtual machines (if it
245 happens at all, the size usually differs by 1 sector). Normally the partition
246 iterator would report an error and abort in such case. Another case scenario is
247 disk corruption in some later EMBR partition.
249 - strict=0 inhibits any checks
250 - strict=1 enables checks, but ignores those that involve disk size
251 - strict=2 enables all checks
252 - relax and nostrict are equivalent to strict=0
253 - norelax and strict are equivalent to strict=2
258 break sets: nofile nomaps nohand
260 It is possible to trigger a "service-only" run - The chain module will do
261 everything requested as usual, but it will not perform the actual chainloading.
262 'break' option disables handover, file loading and sector mapping, as these
263 are pointless in such scenario (although file might be reenabled in some future
264 version, if writing to actual files becomes possible). Mainly useful for
265 options 'fixchs', '[un]hide[all]' and setbpb.
268 sets: file=<file> nohand nosect isolinux
270 Chainload another version/build of the ISOLINUX bootloader and patch the loader
271 with appropriate parameters in memory. This avoids the need for the
272 -eltorito-alt-boot parameter of mkisofs, when you want more than one ISOLINUX
273 per CD/DVD.
276 sets: file=<file> seg=0x2000 setbpb nohand
278 Prepares to load ntldr directly. You might want to add 'save' option to store
279 corrected BPB values.
282 sets: file=<file> seg=0x2000 setbpb nohand cmldr
284 Prepares to load recovery console directly. In-memory copy of bootsector is
285 patched with "cmdcons\0". Remarks the same as in 'ntldr='.
288 sets: file=<file> seg=0:0x8000:0x8100 setbpb nohand
290 Prepares to load ReactOS's freeldr directly. You might want to add 'save'
291 option to store corrected BPB values.
294 sets: file=<file> seg=0x60 sect=0x1FE0 setbpb nohand
296 Prepares to load freedos kernel directly. You will likely want to add 'save'
297 option, as those kernels seem to require proper geometry written back to disk.
298 Sector address is chosen based on where freedos' bootsectors relocate themselves,
299 although it seems the kernel doesn't rely on it.
301 You might also want to employ 'hide' option, if you have problems with properly
302 assigned C: drive.
306 sets: file=<file> seg=0x70 sect=0x8000 setbpb nohand
308 Similary to 'freedos=', This prepares to load MSDOS 2.00 - 6.xx or derivatives.
309 Sector address is chosen arbitrarily. Otherwise comments as above.
312 sets: file=<file> seg=0x70::0x200 sect=0x8000 setbpb nohand
314 Only for MSDOS 7+ versions (98se ~ 7.xx, Me ~ 8.xx). Comments as above.
318 sets: file=<file> seg=0x70 sect=0x2000:0:0 setbpb nohand
320 This is used for loading of *only* Dell's DOS derivatives. It does require boot
321 sector at 0x2000 and overall valid BPB values. As in other DOS-ish cases,
322 likely candidates for use are 'save' and 'hide'.
324 grub=<file> [grubcfg=<config>]
325 sets: file=<file> seg=0x800::0x200 nohand nosect grub
327 Chainloads grub legacy's stage2, performing additional corrections on the file
328 in memory. Additionally, alternate config file can be specified through
329 'grubcfg=' option
332 sets: file=<file> nohand nosect grldr
334 Chainloads GRUB4DOS grldr, performing additional corrections on the file
335 in memory.
338 sets: file=<file> nomaps setbpb bss
340 This emulates syslinux's native BSS option. This loads both the file and the
341 sector, adjusts BPB values in the loaded sector, then copies all possible BPB
342 fields to the loaded file. Everything is made with reference to the selected
346 sets: file=<file> nosect filebpb
348 This emulates syslinux's native BS option. This loads the file and if possible
349 - adjusts its BPB values. Everything is made with reference to the selected