Difference between revisions of "Doc/chain"

From Syslinux Wiki
Jump to: navigation, search
m (Update to 6.03-pre20.)
m (Re-wording. Wiki formatting.)
Line 14: Line 14:
 
* perform a ''service-only'' run.
 
* perform a ''service-only'' run.
  
It can chainload data from both GPT and DOS partitions, as well as boot the  
+
It can chainload data from both GPT and MBR (aka. DOS) partitions, as well as boot the  
 
first sector from a raw disk.
 
first sector from a raw disk.
  
Line 36: Line 36:
 
A ''service-only'' run is possible when either:
 
A ''service-only'' run is possible when either:
  
* <tt>break</tt> is in effect; or,
+
* the <tt>break</tt> option is in effect; or,
* <tt>nofile</tt> and <tt>nomaps</tt> (or <tt>nosect</tt>) are in effect.
+
* the <tt>nofile</tt> and <tt>nomaps</tt> (or <tt>nosect</tt>) options are in effect.
  
 
This is useful for invocations such as:
 
This is useful for invocations such as:
 
<pre>
 
<pre>
chain.c32 hdN M setbpb save break
+
  chain.c32 hdN M setbpb save break
chain.c32 hdN fixchs break
+
  chain.c32 hdN fixchs break
chain.c32 hdN unhideall break
+
  chain.c32 hdN unhideall break
 
</pre>
 
</pre>
 
Please see the respective options for more details.
 
Please see the respective options for more details.
  
 +
<br />
 +
== Syntax ==
  
== Module invocation: ==
+
<pre>  chain [drive/partition] [options]</pre>
  
<pre>chain [drive/partition] [options]</pre>
+
In case of repeated arguments, the rightmost ones take precedence.
  
In case of repeated arguments, rightmost ones take precedence.
+
<br />
 +
== Drive ==
  
 
+
Drives can be specified as either <code>'hd#', 'fd#', 'boot', 'mbr', or  
== DRIVE / PARTITION SPECIFICATION ==
+
 
+
Drive can be specified as either <code>'hd#', 'fd#', 'boot', 'mbr', or  
+
 
'guid'</code>:
 
'guid'</code>:
  
* 'mbr' selects a drive by its signature;
+
* '<tt>mbr</tt>' selects a drive by its signature;
* 'guid' selects a drive by its guid (GPT only);
+
* '<tt>guid</tt>' selects a drive by its guid (GPT only);
* 'boot' is the drive SYSLINUX was booted from. This is the default value, if nothing else is specified.
+
* '<tt>boot</tt>' is the drive SYSLINUX was booted from. This is the default value, if nothing else is specified.
* 'hd#' and 'fd#' are standard ways to specify drive number as seen by BIOS, starting from 0.
+
* '<tt>hd#</tt>' and '<tt>fd#</tt>' are standard ways to specify drive number as seen by BIOS, starting from 0.
  
Option 'guid' is shared with partition selection (see below). If you happen  
+
Option 'guid' is shared with [[#partition|partition]] selection. If you happen  
to have non-unique guids, they are searched in disk0, partitions of disk0,  
+
to have non-unique guids, they are searched first in disk0, then partitions of disk0, then
 
disk1, ...  order.
 
disk1, ...  order.
  
 
'mbr' and 'guid' take an extra parameter; you should use either ':' or '='  
 
'mbr' and 'guid' take an extra parameter; you should use either ':' or '='  
 
as delimiter.
 
as delimiter.
 +
 +
== Partition ==
  
 
''Partition'' can be specified as <code>'#', 'guid', 'label' or 'fs'</code>:
 
''Partition'' can be specified as <code>'#', 'guid', 'label' or 'fs'</code>:
  
* 'guid' selects a partition by a specified guid value (not by type ''guid'' !);
+
* '<tt>guid</tt>' selects a partition by a specified guid value (not by type ''guid'' !);
* 'label' selects a partition by label (searching by disk order);
+
* '<tt>label</tt>' selects a partition by label (searching by disk order);
* 'fs' selects the partition from which SYSLINUX was executed;
+
* '<tt>fs</tt>' selects the partition from which SYSLINUX was executed;
* '#' is the standard method.  
+
* '<tt>#</tt>' is the standard method.  
 
Partitions 1-4 are primary, 5+ are logical, 0 = boot MBR (default).
 
Partitions 1-4 are primary, 5+ are logical, 0 = boot MBR (default).
  
Line 84: Line 86:
 
(after 'hd#', 'fd#', 'mbr', 'guid' or 'boot').
 
(after 'hd#', 'fd#', 'mbr', 'guid' or 'boot').
  
 +
<br />
 +
== Options ==
  
== OPTIONS ==
+
=== file ===
  
<br /><br /><pre>
+
<pre>
        file=<file>
+
  file=<file>
        *nofile
+
  *nofile
 
</pre>
 
</pre>
It's often convenient to load a file directly and transfer control to it,  
+
It is often convenient to load a file directly and transfer control to it,  
instead of the sector from the disk. Note that the  
+
instead of the sector from the disk. <u>Note that the  
''<nowiki><file></nowiki>'' must reside on the SYSLINUX's partition.
+
''<nowiki><file></nowiki>'' must reside on the '''SYSLINUX's partition'''.</u>
  
 
If you choose this option without explicitly specifying any addresses (see  
 
If you choose this option without explicitly specifying any addresses (see  
options 'sect=' and 'seg='), the file will cause the sector to not be loaded  
+
options '[[#sect|sect=]]' and '[[#seg|seg=]]'), the file will cause the sector to not be loaded  
 
at all (as their memory placement would overlap).
 
at all (as their memory placement would overlap).
  
<br /><br /><pre>
+
=== seg ===
        seg=<segment>:<offset>:<ip>
+
 
        *seg=0:0x7c00:0x7c00
+
<pre>
 +
  seg=<segment>:<offset>:<ip>
 +
  *seg=0:0x7c00:0x7c00
 
</pre>
 
</pre>
This triplet lets you alter the addresses a file will use. It's loaded at  
+
This triplet lets you alter the addresses a file will use. It is loaded at  
 
<code><segment:offset></code>; the entry point is at <code><segment:ip></code>.  
 
<code><segment:offset></code>; the entry point is at <code><segment:ip></code>.  
 +
 
When you chainload some other bootloader or kernel, this option is almost  
 
When you chainload some other bootloader or kernel, this option is almost  
 
always mandatory.
 
always mandatory.
Line 110: Line 117:
 
If this option is not specified, the defaults are <code>0:0x7c00:0x7c00</code>.  
 
If this option is not specified, the defaults are <code>0:0x7c00:0x7c00</code>.  
 
If any field is omitted (e.g. 0x2000::), it defaults to 0.
 
If any field is omitted (e.g. 0x2000::), it defaults to 0.
<br /><br /><pre>
+
 
        sect=<segment>:<offset>:<ip>
+
=== sect ===
        *sect=0:0x7c00:0x7c00
+
 
        nosect
+
<pre>
        nosect sets: nomaps
+
  sect=<segment>:<offset>:<ip>
 +
  *sect=0:0x7c00:0x7c00
 +
  nosect               &rarr; sets: nomaps
 
</pre>
 
</pre>
This triplet lets you alter the addresses a sector will use. It's loaded at  
+
This triplet lets you alter the addresses a sector will use. It is loaded at  
 
<code><segment:offset></code>; the entry point is at <code><segment:ip></code>.  
 
<code><segment:offset></code>; the entry point is at <code><segment:ip></code>.  
This option is mostly used in tandem with the 'file=' and 'seg=' options, as  
+
 
 +
This option is mostly used in tandem with the '[[#file|file=]]' and '[[#seg|seg=]]' options, as  
 
some loaders/kernels expect a relocated sector at some particular address  
 
some loaders/kernels expect a relocated sector at some particular address  
(e.g. DRKM).
+
(e.g. [[DRMK]]).
  
'nosect' will cause the sector to not be loaded at all. In many cases, when a  
+
'<code>nosect</code>' will cause the sector to not be loaded at all. In many cases, when a  
 
file is being chainloaded, specifying a sector is not necessary.
 
file is being chainloaded, specifying a sector is not necessary.
  
 
If this option is not specified, the defaults are <code>0:0x7c00:0x7c00</code>.  
 
If this option is not specified, the defaults are <code>0:0x7c00:0x7c00</code>.  
 
If any field is omitted (e.g. 0x2000::), it defaults to 0.
 
If any field is omitted (e.g. 0x2000::), it defaults to 0.
<br /><br /><pre>
+
 
        *maps
+
=== maps ===
        nomaps
+
 
 +
<pre>
 +
  *maps
 +
  nomaps
 
</pre>
 
</pre>
In some cases, it's useful to fix BPB values in NTFS/FATxx boot sectors and  
+
In some cases, it is useful to fix BPB values in NTFS/FATxx boot sectors and  
 
eventually write them back, but otherwise the boot sector itself is not  
 
eventually write them back, but otherwise the boot sector itself is not  
necessary so to continue the booting process. 'nomaps' allows such situation:  
+
necessary so to continue the booting process. '<code>nomaps</code>' allows such situation:  
 
a sector will be loaded, but it won't be mapped into real memory.  
 
a sector will be loaded, but it won't be mapped into real memory.  
 
Any overlap tests (vs. handover or file areas) are not performed,  
 
Any overlap tests (vs. handover or file areas) are not performed,  
 
being meaningless in such case.
 
being meaningless in such case.
<br /><br /><pre>
+
 
        setbpb
+
=== setbpb ===
        *nosetbpb
+
 
 +
<pre>
 +
  setbpb
 +
  *nosetbpb
 
</pre>
 
</pre>
 
Microsoft's side of the world is particularly sensitive to certain BPB values.  
 
Microsoft's side of the world is particularly sensitive to certain BPB values.  
Line 160: Line 176:
 
according to the detected BPB. If the detection of the BPB is not possible,  
 
according to the detected BPB. If the detection of the BPB is not possible,  
 
this function does nothing.
 
this function does nothing.
<br /><br /><pre>
+
 
        filebpb
+
=== filebpb ===
        *nofilebpb
+
 
 +
<pre>
 +
  filebpb
 +
  *nofilebpb
 
</pre>
 
</pre>
 
A chainloaded file can simply be an image of a sector. In such case, it  
 
A chainloaded file can simply be an image of a sector. In such case, it  
 
could be useful to also fix its BPB values.
 
could be useful to also fix its BPB values.
<br /><br /><pre>
+
 
        save
+
=== save ===
        *nosave
+
 
        save sets: strict=2
+
<pre>
 +
  save                 &rarr; sets: strict=2
 +
  *nosave
 
</pre>
 
</pre>
 
Fixing BPB values only in memory might not be enough. This option allows  
 
Fixing BPB values only in memory might not be enough. This option allows  
 
writing the corrected values to the sector. You would probably want to use  
 
writing the corrected values to the sector. You would probably want to use  
this option together with 'setbpb'.
+
this option together with '[[#setbpb|setbpb]]'.
  
* this option never applies to a loaded file.
+
* This option never applies to a loaded file.
* by default, the chain module will not save anything (such as BPB values) to disk (other than options such as 'hide' or 'fixchs', which are directly related to partition entries).
+
* By default, the chain module will not save anything (such as BPB values) to disk (other than options such as '[[#hide|hide]]' or '[[#fixchs|fixchs]]', which are directly related to partition entries).
* the writing is only performed if the values actually changed.
+
* The writing is only performed if the values actually changed.
<br /><br /><pre>
+
 
        *hand
+
=== hand ===
        nohand
+
 
 +
<pre>
 +
  *hand
 +
  nohand
 
</pre>
 
</pre>
By default, a handover area is prepared if possible - meaning it  
+
By default, a handover area is prepared if possible - meaning if it  
 
doesn't overlap with other areas. This is often not necessary though;  
 
doesn't overlap with other areas. This is often not necessary though;  
usually, a chainloaded file or kernel doesn't care about it anymore, so a  
+
usually, a chainloaded file or kernel does not care about it anymore, so a  
 
user can disable it explicitly with this option.
 
user can disable it explicitly with this option.
<br /><br /><pre>
+
 
        hptr
+
=== hptr ===
        *nohptr
+
 
 +
<pre>
 +
  hptr
 +
  *nohptr
 
</pre>
 
</pre>
In case both, file and sector, are loaded, then <code>ds:si</code> and <code>ds:bp</code>  
+
In case both, file and sector, are loaded, then '<code>ds:si</code>' and '<code>ds:bp</code>'
 
will point to the sector address before the chainloading. This option forces  
 
will point to the sector address before the chainloading. This option forces  
 
those registers to point to the handover area. This is useful when both the  
 
those registers to point to the handover area. This is useful when both the  
 
file and the sector are actually a sector's image and the sector is mapped.
 
file and the sector are actually a sector's image and the sector is mapped.
<br /><br /><pre>
+
 
        swap
+
=== swap ===
        *noswap
+
 
 +
<pre>
 +
  swap
 +
  *noswap
 
</pre>
 
</pre>
 
This option installs a tiny stub code used to swap drive numbers, if the  
 
This option installs a tiny stub code used to swap drive numbers, if the  
drive we use during chainloading is not 'fd0' or 'hd0'.
+
drive we use during chainloading is not '<tt>fd0</tt>' or '<tt>hd0</tt>'.
<br /><br /><pre>
+
 
        hide[all]
+
=== hide ===
        unhide[all]
+
 
        *nohide
+
<pre>
        [un]hide[all] sets: strict=2
+
  [un]hide[all]       &rarr; sets: strict=2
 +
  *nohide
 
</pre>
 
</pre>
In certain situations it's useful to hide partitions - for example to make sure  
+
In certain situations it is useful to hide partitions - for example to make sure  
DOS gets C:. 'hide' will hide hidable primary partitions, except the one we're
+
DOS gets C:. '<tt>hide</tt>' will hide hidable ''primary'' partitions, except the one we are
booting from. Similarly, 'hideall' will hide all hidable partitions, except the  
+
booting from. Similarly, '<tt>hideall</tt>' will hide all hidable partitions, except the  
one we're booting from. Hiding is performed only on the selected drive. Options  
+
one we are booting from. Hiding is performed only on the selected drive. Options  
starting with 'un' will simply unhide every partition (primary ones or all).  
+
starting with '<tt>un</tt>' will simply unhide partitions (primary ones or all, accordingly).  
 
The writing is only performed if the OS type values actually changed.
 
The writing is only performed if the OS type values actually changed.
<br /><br /><pre>
+
 
        fixchs
+
=== fixchs ===
        *nofixchs
+
 
        fixchs sets: strict=2
+
<pre>
 +
  fixchs               &rarr; sets: strict=2
 +
  *nofixchs
 
</pre>
 
</pre>
If you want to make a drive you're booting from totally compatible with current  
+
If you want to make a drive you are booting from totally compatible with current  
 
BIOS, you can use this to fix all partitions' CHS numbers. Good to silence e.g.  
 
BIOS, you can use this to fix all partitions' CHS numbers. Good to silence e.g.  
 
FreeDOS complaining about ''logical CHS differs from physical'', or sfdisk about  
 
FreeDOS complaining about ''logical CHS differs from physical'', or sfdisk about  
 
''found (...) expected (...)''. Functionally, it seems to be mostly cosmetic, as  
 
''found (...) expected (...)''. Functionally, it seems to be mostly cosmetic, as  
Microsoft world (in those cases it cares about geometry) generally sticks to values  
+
Microsoft's world (in those cases it cares about geometry) generally sticks to values  
 
written in bootsectors. And the rest of the world generally doesn't care about  
 
written in bootsectors. And the rest of the world generally doesn't care about  
 
them at all. The writing is only performed if the values actually changed.
 
them at all. The writing is only performed if the values actually changed.
<br /><br /><pre>
+
 
        keepexe
+
=== keepexe ===
        *nokeepexe
+
 
 +
<pre>
 +
  keepexe
 +
  *nokeepexe
 
</pre>
 
</pre>
 
If you are booting over a network using PXELINUX, this option lets you keep  
 
If you are booting over a network using PXELINUX, this option lets you keep  
UNDI stacks in memory (PXELINUX only).
+
UNDI stacks in memory <tt>[PXELINUX only]</tt>.
<br /><br /><pre>
+
 
        warn
+
=== warn ===
        *nowarn
+
 
 +
<pre>
 +
  warn
 +
  *nowarn
 
</pre>
 
</pre>
 
This option will wait for a key-press right before continuing the chainloading.  
 
This option will wait for a key-press right before continuing the chainloading.  
 
Useful to see warnings emitted by the chain module.
 
Useful to see warnings emitted by the chain module.
<br /><br /><pre>
+
 
        prefmbr
+
=== prefmbr ===
        *noprefmbr
+
 
 +
<pre>
 +
  prefmbr
 +
  *noprefmbr
 
</pre>
 
</pre>
 
In case non-standard hybrid MBR/GPT layout is present, this flag makes the  
 
In case non-standard hybrid MBR/GPT layout is present, this flag makes the  
 
chain module prefer MBR layout over GPT.
 
chain module prefer MBR layout over GPT.
<br /><br /><pre>
 
        strict[=<0|1|2>]
 
        *strict=1
 
        relax
 
  
        strict=1 enables checks, but ignores those that involve disk size
+
=== strict ===
        strict=2 enables all checks
+
 
        relax and nostrict are equivalent to strict=0  
+
<pre>
        norelax and strict are equivalent to strict=2
+
  strict[=<0|1|2>]
 +
  *strict=1
 +
  relax
 
</pre>
 
</pre>
 +
* '<code>strict=1</code>' enables checks, but ignores those that involve disk size.
 +
* '<code>strict=2</code>' enables all checks.
 +
* '<code>relax</code>' and '<code>nostrict</code>' are equivalent to '<code>strict=0</code>'.
 +
* '<code>norelax</code>' and '<code>strict</code>' are equivalent to '<code>strict=2</code>'.
 +
 
These options control the level of sanity checks used during the traversal of  
 
These options control the level of sanity checks used during the traversal of  
 
partition table(s). This is potentially useful in (buggy) corner cases, for example when the disk size is  
 
partition table(s). This is potentially useful in (buggy) corner cases, for example when the disk size is  
Line 258: Line 303:
 
iterator would report an error and abort in such case. Another case scenario is  
 
iterator would report an error and abort in such case. Another case scenario is  
 
disk corruption in some later EMBR partition.
 
disk corruption in some later EMBR partition.
<br /><br /><pre>
+
 
        break
+
=== break ===
        *nobreak
+
 
        break sets: nofile nomaps nohand
+
<pre>
 +
  break               &rarr; sets: nofile nomaps nohand
 +
  *nobreak
 
</pre>
 
</pre>
 
It is possible to trigger a ''service-only'' run; the chain module will do  
 
It is possible to trigger a ''service-only'' run; the chain module will do  
 
everything requested as usual, but it will not perform the actual chainloading.  
 
everything requested as usual, but it will not perform the actual chainloading.  
The 'break' option disables the handover, file loading and sector mapping, as these  
+
The '<tt>break</tt>' option disables the handover, file loading and sector mapping, as these  
 
are pointless in such scenario (although the file might be re-enabled in some future  
 
are pointless in such scenario (although the file might be re-enabled in some future  
version, if the writing to actual files becomes possible). Mainly useful for  
+
version, if writing to actual files becomes possible). Mainly useful for  
options such as 'fixchs', '<nowiki>[un]hide[all]</nowiki>' and 'setbpb'.
+
options such as '<tt>fixchs</tt>', {{nowrap|'<nowiki><code>[un]hide[all]</code></nowiki>'}} and '<tt>setbpb</tt>'.
<br /><br /><pre>
+
 
        isolinux=<file>
+
=== isolinux ===
        sets: file=<file> nohand nosect isolinux
+
 
 +
<pre>
 +
  isolinux=<file>
 +
  sets: file=<file> nohand nosect isolinux
 
</pre>
 
</pre>
 
Chainload to another version/build of the ISOLINUX bootloader and patch the loader  
 
Chainload to another version/build of the ISOLINUX bootloader and patch the loader  
 
with appropriate parameters in memory. This avoids the need for the  
 
with appropriate parameters in memory. This avoids the need for the  
-eltorito-alt-boot parameter of mkisofs, when you want more than one ISOLINUX  
+
<code>-eltorito-alt-boot</code> parameter of mkisofs, when you want more than one ISOLINUX  
 
per CD/DVD.
 
per CD/DVD.
<br /><br /><pre>
+
 
        ntldr=<file>
+
=== ntldr ===
        sets: file=<file> seg=0x2000 setbpb nohand
+
 
 +
<pre>
 +
  ntldr=<file>
 +
  sets: file=<file> seg=0x2000 setbpb nohand
 
</pre>
 
</pre>
Prepares to load ''ntldr'' directly. You might want to add the 'save' option  
+
Prepares to load ''ntldr'' directly. You might want to add the '[[#save|save]]' option  
 
so to store corrected BPB values.
 
so to store corrected BPB values.
<br /><br /><pre>
+
 
        cmldr=<file>
+
=== cmldr ===
        sets: file=<file> seg=0x2000 setbpb nohand cmldr
+
 
 +
<pre>
 +
  cmldr=<file>
 +
  sets: file=<file> seg=0x2000 setbpb nohand cmldr
 
</pre>
 
</pre>
 
Prepares to load ''recovery console'' directly. The in-memory copy of the bootsector is  
 
Prepares to load ''recovery console'' directly. The in-memory copy of the bootsector is  
patched with <code> cmdcons\0 </code>. Same remarks as in 'ntldr='.
+
patched with {{nowrap|1='<code> cmdcons\0 </code>'}}. Same remarks as in '[[#ntldr|ntldr=]]'.
<br /><br /><pre>
+
 
        reactos=<file>
+
=== reactos ===
        sets: file=<file> seg=0:0x8000:0x8100 setbpb nohand
+
 
 +
<pre>
 +
  reactos=<file>
 +
  sets: file=<file> seg=0:0x8000:0x8100 setbpb nohand
 
</pre>
 
</pre>
Prepares to load ''ReactOS's freeldr'' directly. You might want to add the 'save'  
+
Prepares to load ''ReactOS's freeldr'' directly. You might want to add the '[[#save|save]]'  
 
option so to store corrected BPB values.
 
option so to store corrected BPB values.
<br /><br /><pre>
+
 
        freedos=<file>
+
=== freedos ===
        sets: file=<file> seg=0x60 sect=0x1FE0 setbpb nohand
+
 
 +
<pre>
 +
  freedos=<file>
 +
  sets: file=<file> seg=0x60 sect=0x1FE0 setbpb nohand
 
</pre>
 
</pre>
Prepares to load ''FreeDOS kernel'' directly. You will likely want to add the 'save'  
+
Prepares to load ''FreeDOS kernel'' directly. You will likely want to add the '[[#save|save]]'  
 
option, as those kernels seem to require a proper geometry written back to disk.  
 
option, as those kernels seem to require a proper geometry written back to disk.  
 
The sector address is chosen based on where FreeDOS' bootsectors relocate themselves,  
 
The sector address is chosen based on where FreeDOS' bootsectors relocate themselves,  
 
although it seems the kernel doesn't rely on it.
 
although it seems the kernel doesn't rely on it.
  
You might also want to employ the 'hide' option, if you have problems with  
+
You might also want to employ the '[[#hide|hide]]' option, if you have problems with  
 
properly assigning the C: drive.
 
properly assigning the C: drive.
<br /><br /><pre>
+
 
        pcdos=<file>
+
=== msdos and pcdos ===
        msdos=<file>
+
 
        sets: file=<file> seg=0x70 sect=0x8000 setbpb nohand
+
<pre>
 +
  pcdos=<file>
 +
  msdos=<file>
 +
  sets: file=<file> seg=0x70 sect=0x8000 setbpb nohand
 
</pre>
 
</pre>
Similarly to 'freedos=', this prepares to load MSDOS 2.00 - 6.xx or derivatives.  
+
Similarly to '[[#freedos|freedos=]]', this prepares to load MSDOS 2.00 - 6.xx or derivatives.  
 
The sector address is chosen arbitrarily. Otherwise, comments as above.
 
The sector address is chosen arbitrarily. Otherwise, comments as above.
<br /><br /><pre>
+
 
        msdos7=<file>
+
=== msdos7 ===
        sets: file=<file> seg=0x70::0x200 sect=0x8000 setbpb nohand
+
 
 +
<pre>
 +
  msdos7=<file>
 +
  sets: file=<file> seg=0x70::0x200 sect=0x8000 setbpb nohand
 
</pre>
 
</pre>
 
Only for MSDOS 7+ versions (98se ~ 7.xx, Me ~ 8.xx). Comments as above.
 
Only for MSDOS 7+ versions (98se ~ 7.xx, Me ~ 8.xx). Comments as above.
  
 +
<!--  -->
 +
<!--  -->
 +
<!--    TODO/TEST -->
 +
<!--    TODO/TEST -->
 +
<!--    TODO/TEST -->
 +
<!--  -->
 +
<!--  -->
  
<!-- TODO/TEST -->
+
=== drmk ===
  
 
+
<pre>
<br /><br /><pre>
+
  drmk=<file>
        drmk=<file>
+
  sets: file=<file> seg=0x70 sect=0x2000:0:0 setbpb nohand
        sets: file=<file> seg=0x70 sect=0x2000:0:0 setbpb nohand
+
 
</pre>
 
</pre>
 
This is used for loading of Dell's DOS derivatives <u>only</u>. It does require a boot  
 
This is used for loading of Dell's DOS derivatives <u>only</u>. It does require a boot  
sector at 0x2000 and overall valid BPB values. As in other DOS-ish cases,  
+
sector at <tt>0x2000</tt> and overall valid BPB values. As in other DOS-ish cases,  
likely candidates for use are the 'save' and 'hide' options.
+
likely candidates for use are the '[[#save|save]]' and '[[#hide|hide]]' options.
<br /><br /><pre>
+
 
        grub=<file> [grubcfg=<config>]
+
=== grub ===
        sets: file=<file> seg=0x800::0x200 nohand nosect grub
+
 
 +
<pre>
 +
  grub=<file> [grubcfg=<config>]
 +
  sets: file=<file> seg=0x800::0x200 nohand nosect grub
 
</pre>
 
</pre>
 
Chainloads to grub legacy's stage2, performing additional corrections on the file  
 
Chainloads to grub legacy's stage2, performing additional corrections on the file  
in memory. Additionally, an alternate config file can be specified through the  
+
in memory. Additionally, an alternative config file can be specified through the  
'grubcfg=' option.
+
'<code>grubcfg=</code>' option.
<br /><br /><pre>
+
 
        grldr=<file>
+
=== grldr ===
        sets: file=<file> nohand nosect grldr
+
 
 +
<pre>
 +
  grldr=<file>
 +
  sets: file=<file> nohand nosect grldr
 
</pre>
 
</pre>
 
Chainloads to GRUB4DOS grldr, performing additional corrections on the file  
 
Chainloads to GRUB4DOS grldr, performing additional corrections on the file  
 
in memory.
 
in memory.
<br /><br /><pre>
+
 
        bss=<file>
+
=== bss ===
        sets: file=<file> nomaps setbpb bss
+
 
 +
<pre>
 +
  bss=<file>
 +
  sets: file=<file> nomaps setbpb bss
 
</pre>
 
</pre>
 
This emulates SYSLINUX's native BSS option. This loads both the file and the  
 
This emulates SYSLINUX's native BSS option. This loads both the file and the  
sector, adjusts BPB values in the loaded sector, then copies all possible BPB  
+
sector, adjusts BPB values in the loaded sector, and then copies all possible BPB  
 
fields to the loaded file. Everything is made in reference to the selected  
 
fields to the loaded file. Everything is made in reference to the selected  
 
disk/partition.
 
disk/partition.
<br /><br /><pre>
+
 
        bs=<file>
+
=== bs ===
        sets: file=<file> nosect filebpb
+
 
 +
<pre>
 +
  bs=<file>
 +
  sets: file=<file> nosect filebpb
 
</pre>
 
</pre>
 
This emulates SYSLINUX's native BS option. This loads the file and, if possible,  
 
This emulates SYSLINUX's native BS option. This loads the file and, if possible,  
Line 359: Line 445:
 
disk/partition.
 
disk/partition.
  
 
+
<br />
 
== See Also ==
 
== See Also ==
  
 
* [[Comboot/chain.c32]]
 
* [[Comboot/chain.c32]]

Revision as of 14:02, 5 September 2014

Introduction

Although Syslinux is capable of (very simple) native chainloading (through .bss and .bs options - see doc/syslinux), it also features a very robust and rich com32 module designed for such purpose.

The chain.c32 module can perform some basic tasks:

  • load and jump to a sector
  • load and jump to a file (also loading a sector for other purposes)
  • prepare handover data to use by a file / boot sector
  • fix different options in a file / sector / partition entries
  • perform a service-only run.

It can chainload data from both GPT and MBR (aka. DOS) partitions, as well as boot the first sector from a raw disk.

A rough overview of the code is as follows:

  1. Parse arguments.
  2. Find drive and/or partition to boot from.
  3. Perform partition-level patching - for example (un)hiding, fixing CHS values, etc.
  4. Load a file to boot from.
  5. Load a sector to boot from, if it doesn't conflict with #4.
  6. Prepare handover area, if it doesn't conflict with #4 and #5.
  7. Prepare registers.
  8. Patch loaded file if necessary.
  9. Patch loaded sector if necessary.
  10. Chainload.

In its most basic form, SYSLINUX loads a specified boot sector (or MBR, if not specified) at 0:0x7c00, prepares handover area as a standard MBR would do, and jumps to 0:0x7c00.

A service-only run is possible when either:

  • the break option is in effect; or,
  • the nofile and nomaps (or nosect) options are in effect.

This is useful for invocations such as:

  chain.c32 hdN M setbpb save break
  chain.c32 hdN fixchs break
  chain.c32 hdN unhideall break

Please see the respective options for more details.


Syntax

  chain [drive/partition] [options]

In case of repeated arguments, the rightmost ones take precedence.


Drive

Drives can be specified as either 'hd#', 'fd#', 'boot', 'mbr', or 'guid':

  • 'mbr' selects a drive by its signature;
  • 'guid' selects a drive by its guid (GPT only);
  • 'boot' is the drive SYSLINUX was booted from. This is the default value, if nothing else is specified.
  • 'hd#' and 'fd#' are standard ways to specify drive number as seen by BIOS, starting from 0.

Option 'guid' is shared with partition selection. If you happen to have non-unique guids, they are searched first in disk0, then partitions of disk0, then disk1, ... order.

'mbr' and 'guid' take an extra parameter; you should use either ':' or '=' as delimiter.

Partition

Partition can be specified as '#', 'guid', 'label' or 'fs':

  • 'guid' selects a partition by a specified guid value (not by type guid !);
  • 'label' selects a partition by label (searching by disk order);
  • 'fs' selects the partition from which SYSLINUX was executed;
  • '#' is the standard method.

Partitions 1-4 are primary, 5+ are logical, 0 = boot MBR (default).

If you use a number to select a partition, it should be specified after a drive by using either a space or a comma character as delimiter (after 'hd#', 'fd#', 'mbr', 'guid' or 'boot').


Options

file

  file=<file>
  *nofile

It is often convenient to load a file directly and transfer control to it, instead of the sector from the disk. Note that the <file> must reside on the SYSLINUX's partition.

If you choose this option without explicitly specifying any addresses (see options 'sect=' and 'seg='), the file will cause the sector to not be loaded at all (as their memory placement would overlap).

seg

  seg=<segment>:<offset>:<ip>
  *seg=0:0x7c00:0x7c00

This triplet lets you alter the addresses a file will use. It is loaded at <segment:offset>; the entry point is at <segment:ip>.

When you chainload some other bootloader or kernel, this option is almost always mandatory.

If this option is not specified, the defaults are 0:0x7c00:0x7c00. If any field is omitted (e.g. 0x2000::), it defaults to 0.

sect

  sect=<segment>:<offset>:<ip>
  *sect=0:0x7c00:0x7c00
  nosect               		→ sets: nomaps

This triplet lets you alter the addresses a sector will use. It is loaded at <segment:offset>; the entry point is at <segment:ip>.

This option is mostly used in tandem with the 'file=' and 'seg=' options, as some loaders/kernels expect a relocated sector at some particular address (e.g. DRMK).

'nosect' will cause the sector to not be loaded at all. In many cases, when a file is being chainloaded, specifying a sector is not necessary.

If this option is not specified, the defaults are 0:0x7c00:0x7c00. If any field is omitted (e.g. 0x2000::), it defaults to 0.

maps

  *maps
  nomaps

In some cases, it is useful to fix BPB values in NTFS/FATxx boot sectors and eventually write them back, but otherwise the boot sector itself is not necessary so to continue the booting process. 'nomaps' allows such situation: a sector will be loaded, but it won't be mapped into real memory. Any overlap tests (vs. handover or file areas) are not performed, being meaningless in such case.

setbpb

  setbpb
  *nosetbpb

Microsoft's side of the world is particularly sensitive to certain BPB values. Depending on the system and the chainloading method (i.e. sector or file), some or all of those fields must match "reality"; but after performing certain operations such as drive cloning, or when using a USB stick in different computers, that's often not the case (i.e. some BPB values might not match the real media).

Matching the "reality" means evaluating:

"hidden sectors"
Valid offset of the partition from the beginning of the disk.
"geometry"
Valid disk geometry as reported by BIOS.
"drive"
Valid drive number.

This option will automatically determine the type of BPB and fix what it can, according to the detected BPB. If the detection of the BPB is not possible, this function does nothing.

filebpb

  filebpb
  *nofilebpb

A chainloaded file can simply be an image of a sector. In such case, it could be useful to also fix its BPB values.

save

  save                 		→ sets: strict=2
  *nosave

Fixing BPB values only in memory might not be enough. This option allows writing the corrected values to the sector. You would probably want to use this option together with 'setbpb'.

  • This option never applies to a loaded file.
  • By default, the chain module will not save anything (such as BPB values) to disk (other than options such as 'hide' or 'fixchs', which are directly related to partition entries).
  • The writing is only performed if the values actually changed.

hand

  *hand
  nohand

By default, a handover area is prepared if possible - meaning if it doesn't overlap with other areas. This is often not necessary though; usually, a chainloaded file or kernel does not care about it anymore, so a user can disable it explicitly with this option.

hptr

  hptr
  *nohptr

In case both, file and sector, are loaded, then 'ds:si' and 'ds:bp' will point to the sector address before the chainloading. This option forces those registers to point to the handover area. This is useful when both the file and the sector are actually a sector's image and the sector is mapped.

swap

  swap
  *noswap

This option installs a tiny stub code used to swap drive numbers, if the drive we use during chainloading is not 'fd0' or 'hd0'.

hide

  [un]hide[all]        		→ sets: strict=2
  *nohide

In certain situations it is useful to hide partitions - for example to make sure DOS gets C:. 'hide' will hide hidable primary partitions, except the one we are booting from. Similarly, 'hideall' will hide all hidable partitions, except the one we are booting from. Hiding is performed only on the selected drive. Options starting with 'un' will simply unhide partitions (primary ones or all, accordingly). The writing is only performed if the OS type values actually changed.

fixchs

  fixchs               		→ sets: strict=2
  *nofixchs

If you want to make a drive you are booting from totally compatible with current BIOS, you can use this to fix all partitions' CHS numbers. Good to silence e.g. FreeDOS complaining about logical CHS differs from physical, or sfdisk about found (...) expected (...). Functionally, it seems to be mostly cosmetic, as Microsoft's world (in those cases it cares about geometry) generally sticks to values written in bootsectors. And the rest of the world generally doesn't care about them at all. The writing is only performed if the values actually changed.

keepexe

  keepexe
  *nokeepexe

If you are booting over a network using PXELINUX, this option lets you keep UNDI stacks in memory [PXELINUX only].

warn

  warn
  *nowarn

This option will wait for a key-press right before continuing the chainloading. Useful to see warnings emitted by the chain module.

prefmbr

  prefmbr
  *noprefmbr

In case non-standard hybrid MBR/GPT layout is present, this flag makes the chain module prefer MBR layout over GPT.

strict

  strict[=<0|1|2>] 
  *strict=1
  relax
  • 'strict=1' enables checks, but ignores those that involve disk size.
  • 'strict=2' enables all checks.
  • 'relax' and 'nostrict' are equivalent to 'strict=0'.
  • 'norelax' and 'strict' are equivalent to 'strict=2'.

These options control the level of sanity checks used during the traversal of partition table(s). This is potentially useful in (buggy) corner cases, for example when the disk size is reported differently across different computers or virtual machines (if it happens at all, the size usually differs by 1 sector). Normally, the partition iterator would report an error and abort in such case. Another case scenario is disk corruption in some later EMBR partition.

break

  break                		→ sets: nofile nomaps nohand
  *nobreak

It is possible to trigger a service-only run; the chain module will do everything requested as usual, but it will not perform the actual chainloading. The 'break' option disables the handover, file loading and sector mapping, as these are pointless in such scenario (although the file might be re-enabled in some future version, if writing to actual files becomes possible). Mainly useful for options such as 'fixchs', '<code>[un]hide[all]</code>' and 'setbpb'.

isolinux

  isolinux=<file>
  sets: file=<file> nohand nosect isolinux

Chainload to another version/build of the ISOLINUX bootloader and patch the loader with appropriate parameters in memory. This avoids the need for the -eltorito-alt-boot parameter of mkisofs, when you want more than one ISOLINUX per CD/DVD.

ntldr

  ntldr=<file>
  sets: file=<file> seg=0x2000 setbpb nohand

Prepares to load ntldr directly. You might want to add the 'save' option so to store corrected BPB values.

cmldr

  cmldr=<file>
  sets: file=<file> seg=0x2000 setbpb nohand cmldr

Prepares to load recovery console directly. The in-memory copy of the bootsector is patched with ' cmdcons\0 '. Same remarks as in 'ntldr='.

reactos

  reactos=<file>
  sets: file=<file> seg=0:0x8000:0x8100 setbpb nohand

Prepares to load ReactOS's freeldr directly. You might want to add the 'save' option so to store corrected BPB values.

freedos

  freedos=<file>
  sets: file=<file> seg=0x60 sect=0x1FE0 setbpb nohand

Prepares to load FreeDOS kernel directly. You will likely want to add the 'save' option, as those kernels seem to require a proper geometry written back to disk. The sector address is chosen based on where FreeDOS' bootsectors relocate themselves, although it seems the kernel doesn't rely on it.

You might also want to employ the 'hide' option, if you have problems with properly assigning the C: drive.

msdos and pcdos

  pcdos=<file>
  msdos=<file>
  sets: file=<file> seg=0x70 sect=0x8000 setbpb nohand

Similarly to 'freedos=', this prepares to load MSDOS 2.00 - 6.xx or derivatives. The sector address is chosen arbitrarily. Otherwise, comments as above.

msdos7

  msdos7=<file>
  sets: file=<file> seg=0x70::0x200 sect=0x8000 setbpb nohand

Only for MSDOS 7+ versions (98se ~ 7.xx, Me ~ 8.xx). Comments as above.


drmk

  drmk=<file>
  sets: file=<file> seg=0x70 sect=0x2000:0:0 setbpb nohand

This is used for loading of Dell's DOS derivatives only. It does require a boot sector at 0x2000 and overall valid BPB values. As in other DOS-ish cases, likely candidates for use are the 'save' and 'hide' options.

grub

  grub=<file> [grubcfg=<config>]
  sets: file=<file> seg=0x800::0x200 nohand nosect grub

Chainloads to grub legacy's stage2, performing additional corrections on the file in memory. Additionally, an alternative config file can be specified through the 'grubcfg=' option.

grldr

  grldr=<file>
  sets: file=<file> nohand nosect grldr

Chainloads to GRUB4DOS grldr, performing additional corrections on the file in memory.

bss

  bss=<file>
  sets: file=<file> nomaps setbpb bss

This emulates SYSLINUX's native BSS option. This loads both the file and the sector, adjusts BPB values in the loaded sector, and then copies all possible BPB fields to the loaded file. Everything is made in reference to the selected disk/partition.

bs

  bs=<file>
  sets: file=<file> nosect filebpb

This emulates SYSLINUX's native BS option. This loads the file and, if possible, also adjusts its BPB values. Everything is made in reference to the selected disk/partition.


See Also