View source for Doc/chain

[[Category:Release Documentation]]
== Introduction ==

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

The <tt>chain.c32</tt> 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 be used 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 {{V|4.00+}} 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:

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

In its most basic form, chain.c32 loads either an MBR 
or a specified boot sector at '<code>0:0x7c00</code>', 
prepares handover area as a standard MBR would do, 
and jumps to '<code>0:0x7c00</code>'.

A ''service-only'' run is possible when either:

* the '<tt>break</tt>' option is in effect; or,
* options '<tt>nofile</tt>' and '<tt>nomaps</tt>' (or '<tt>nosect</tt>') are in effect.

This is useful for invocations such as:
<pre>
  chain.c32 hdN M setbpb save break
  chain.c32 hdN fixchs break
  chain.c32 hdN unhideall break
</pre>

Please see the respective options for more details.

<br />
== Syntax ==

<pre>
  chain [drive/partition] [options]
</pre>

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

Note that some options cannot be combined with some other options.

{| class="wikitable"
!OPTION
!TYPE
!BIOS
!MBR/GPT
!PT
!VBR
<!-- <nowiki>!FILE</nowiki> -->
<!-- <nowiki>!OTHER</nowiki> -->
|-
|boot
|flag
|Syslinux's boot drive
|-
|mbr
|argument
|
|Match ID
|-
|guid
|argument
|
|Match ID
|Match ID
|-
|label
|argument
|
|
|Match ID
|-
|hd#,#
|argument
|Device #
|
|Device #
|-
|fs
|flag
|
|
|
|Syslinux's boot volume
|-
|fd#
|argument
|Device #
|}

<br />
== Drive ==

Drives can be specified as either:

; <tt>mbr</tt>
: select a disk by its signature;
; <tt>guid</tt>
: select a disk by its guid (GPT only);
; <tt>boot</tt>
: the drive SYSLINUX was booted from. <!--
--> This is the default value, if nothing else is specified.
; <tt>hd''#''</tt>
: drive number as seen by BIOS, starting from 0.
; <tt>fd''#''</tt>
: floppy drive number as seen by BIOS, starting from 0.

Option 'guid' is shared with [[#partition|partition]] selection. 
If there are non-unique guids, they are searched first in disk0, 
then partitions of disk0, then disk1, ...  order.

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

== Partition ==

''Partition'' can be specified as either:

; <tt>guid</tt>
: select a partition by a specified guid value (not by ''guid'' type !);
; <tt>label</tt>
: select a partition by a specified label (searching by disk order);
; <tt>fs</tt>
: the partition SYSLINUX was booted from;
; <tt>''#''</tt>
: partition number within disk; the standard method. <!--
--> Partitions 1-4 are primary, 5+ are logical, 0 (zero) is the MBR (default).

If a partition is selected by number, it should be specified after a 
disk drive notation by using either a ''space'' or a ''comma'' character as delimiter 
(after <tt>'hd''#''<nowiki />', 'fd''#''<nowiki />', 'mbr', 'guid' or 'boot'</tt>).

<br />
== Options ==

{| class="wikitable"
!OPTION
!TYPE
!BIOS
!MBR/GPT
!PT
!VBR
!FILE
!OTHER
|-
|[[#swap|swap]]
|flag
|Set as first device
|-
|[[#prefmbr|prefmbr]]
|flag
|
|Prefer MBR over GPT
|-
|[[#hide|hide]]
|multiflag
|
|
|Modify partition ID
|-
|[[#fixchs|fixchs]]
|flag
|
|
|Fix CHS
|-
|[[#gpthcrc_and_gptlcrc|gpthcrc]]
|flag
|
|GPT header checksum
|-
|[[#gpthcrc_and_gptlcrc|gptlcrc]]
|flag
|
|
|GPT list checksum
|-
|[[#strict|strict]]
|multiflag
|
|
|Sanity check level
|-
|[[#file|file]]
|argument
|
|
|
|
|Select file to load
|-
|[[#seg|seg]]
|argument
|
|
|
|
|Address
|-
|[[#sect|sect]]
|argument
|
|
|
|Address
|-
|[[#maps|maps]]
|flag
|
|
|
|Map in address
|-
|[[#hand|hand]]
|flag
|
|
|
|
|Use handover (area)
|-
|[[#hptr|hptr]]
|flag
|
|
|
|Point registers to handover area
|-
|[[#setbpb|setbpb]]
|flag
|
|
|
|Patch BPB
|-
|[[#filebpb|filebpb]]
|flag
|
|
|
|
|Patch BPB
|-
|[[#save|save]]
|flag
|
|
|
|Write BPB
|-
|[[#keeppxe|keeppxe]]
|flag
|
|
|
|
|
|Keep UNDI stack loaded
|-
|[[#break|break]]
|flag
|
|
|
|
|
|Service-only run
|-
|[[#warn|warn]]
|flag
|
|
|
|
|
|Wait for a key-press
|-
|[[#exit|exit]]
|flag
|
|
|
|
|
|Force end of command line
|-
|[[#isolinux|isolinux]]
|shortcut
|
|
|
|
|Load a different ISOLINUX version
|-
|[[#ntldr|ntldr]]
|shortcut
|
|
|
|
|Windows NTLDR
|-
|[[#cmldr|cmldr]]
|shortcut
|
|
|
|
|Windows Recovery Console
|-
|[[#reactos|reactos]]
|shortcut
|
|
|
|
|Reactos freeldr.sys
|-
|[[#freedos|freedos]]
|shortcut
|
|
|
|
|FreeDOS kernel.sys
|-
|[[#msdos_and_pcdos|pcdos]]
|shortcut
|
|
|
|
|PCDOS ibmbio.com
|-
|[[#msdos_and_pcdos|msdos]]
|shortcut
|
|
|
|
|MSDOS 2-6.xx io.sys
|-
|[[#msdos7|msdos7]]
|shortcut
|
|
|
|
|MSDOS7+ io.sys
|-
|[[#drmk|drmk]]
|shortcut
|
|
|
|
|DELLDOS dellbio.bin
|-
|[[#grub|grub]]
|shortcut
|
|
|
|
|GRUB legacy's stage2
|-
|[[#grldr|grldr]]
|shortcut
|
|
|
|
|GRUB4DOS grldr
|-
|[[#bs|bs]]
|shortcut
|
|
|
|
|Emulate SYSLINUX's BS
|-
|[[#bss|bss]]
|shortcut
|
|
|
|
|Emulate SYSLINUX's BSS
|}

=== swap ===
<pre>
  swap
  *noswap
</pre>
{{S|swap}}{{V|3.70+}}Install a tiny stub code that swaps device numbers, if the 
device we use during chainloading is not '<tt>fd0</tt>' nor '<tt>hd0</tt>'.

=== prefmbr ===
<pre>
  prefmbr
  *noprefmbr
</pre>
{{S|prefmbr}}In case non-standard hybrid MBR/GPT layout is present, 
this flag makes the chain module prefer MBR layout over GPT.

=== hide ===
<pre>
  [un]hide[all]        		&rarr; sets: strict=2
  *nohide
</pre>
{{S|hide}}{{V|3.71+}}Modify the partition ID ("type") in the partition table (typically, "0x0''n''"&harr;"0x1''n''"). 
In certain situations it is useful to hide partitions; for example to make sure 
DOS gets "C:". '<tt>hide</tt>' will hide hidable ''primary'' partitions, except the one we are 
booting from. Similarly, '<tt>hideall</tt>' will hide all hidable partitions, except the 
one we are booting from. Hiding is performed only on the selected disk. Options 
starting with '<tt>un</tt>' will simply unhide partitions (primary ones or all, accordingly). 
The writing is only performed if the values actually changed. See also '[[#break|break]]'.

=== fixchs ===
<pre>
  fixchs               		&rarr; sets: strict=2
  *nofixchs
</pre>
{{S|fixchs}}Fix all partitions' CHS numbers so as to make the partition table totally 
compatible with the current BIOS. This option can be useful, for example, to silence 
FreeDOS complaining about "''logical CHS differs from physical''", or sfdisk about 
"''found (...) expected (...)''". Functionally, it seems to be mostly cosmetic, as 
Microsoft's world (when 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. 
See also '[[#break|break]]'.

=== gpthcrc and gptlcrc ===
<pre>
  *gpthcrc             		&rarr; Perform gpt header crc check
  nogpthcrc            		&rarr; Skip crc check
  *gptlcrc             		&rarr; Perform gpt list crc check
  nogptlcrc            		&rarr; Skip crc check
</pre>
{{S|gpthcrc_and_gptlcrc}}Force boot when checksums of GPT header and/or 
partition list are invalid. 
This works independently from the '[[#strict|strict]' option.

=== strict ===
<pre>
  strict[=<0|1|2>] 
  *strict=1
  relax
</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>'. 

{{S|strict}}{{V|6.03+}}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.

=== file ===
<pre>
  file=</><path/to/><myfile>
  *nofile
</pre>
{{S|file}}{{V|3.70+}}It is often convenient to load a file directly and transfer control to it, 
instead of the sector from the disk. Note that 
<u>''<nowiki><myfile></nowiki>'' must reside on the ''Syslinux's filesystem volume''.</u>

Choosing a file without explicitly specifying any addresses 
(see options '[[#sect|sect]]' and '[[#seg|seg]]') 
will cause the sector to not be loaded 
at all (as their memory placement would overlap).

=== seg ===
<pre>
  seg=<segment>:<offset>:<ip>
  *seg=0:0x7c00:0x7c00
</pre>
{{S|seg}}{{V|3.70+}}Alter the addresses a file will use. It is loaded at 
'<code><segment:offset></code>'; the entry point is at '<code><segment:ip></code>'.

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

If this option is not specified, the defaults are '<code>0:0x7c00:0x7c00</code>'. 
If any field is omitted (e.g. {{nowrap|'<tt>0x2000::</tt>'),}} it defaults to 0.

=== sect ===
<pre>
  sect=<segment>:<offset>:<ip>
  *sect=0:0x7c00:0x7c00
  nosect               		&rarr; sets: nomaps
</pre>
{{S|sect}}Alter the addresses a sector will use. It is loaded at 
'<code><segment:offset></code>; the entry point is at '<code><segment:ip></code>'. 

'sect' is mostly used in tandem with options '[[#file|file]]' and 
'[[#seg|seg]]', as some loaders/kernels expect a relocated 
sector at some particular address (e.g. [[#drmk|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 '<code>0:0x7c00:0x7c00</code>'. 
If any field is omitted (e.g. {{nowrap|'<tt>0x2000::</tt>'),}} it defaults to 0.

=== maps ===
<pre>
  *maps
  nomaps
</pre>
{{S|maps}}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 as 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.

=== hand ===
<pre>
  *hand
  nohand
</pre>
{{S|hand}}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 'nohand'.

=== hptr ===
<pre>
  hptr
  *nohptr
</pre>
{{S|hptr}}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 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.

=== setbpb ===
<pre>
  setbpb
  *nosetbpb
</pre>
{{S|setbpb}}Microsoft's side of the world is particularly sensitive to certain BPB values. 
Depending on the system and on the chainloading method (i.e. sector or file), 
some or all of those fields must match "reality"; but after performing 
certain operations such as disk 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 drive 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 ===
<pre>
  filebpb
  *nofilebpb
</pre>
{{S|filebpb}}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 ===
<pre>
  save                 		&rarr; sets: strict=2
  *nosave
</pre>
{{S|save}}Fixing BPB values (with '[[#setbpb|setbpb]]') only in memory might not be enough. 
This option allows writing the corrected values to the sector.

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.

When 'save' is used:
* it can apply to a sector, never to a loaded file; 
* the writing is only performed if the values actually changed.

=== keeppxe ===
<pre>
  keepexe
  *nokeepexe
</pre>
{{S|keeppxe}}{{V|PXELINUX only}}When booting over a network using PXELINUX, 'keeppxe' 
will keep UNDI stacks in memory.

=== break ===
<pre>
  break                		&rarr; sets: nofile nomaps nohand
  *nobreak
</pre>
{{S|break}}{{V|4.05+}}Trigger a ''service-only'' run; 
the chain module will do everything requested as usual, 
but it will not perform the actual chainloading. 
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 version, 
if writing to actual files becomes possible). 
Mainly useful for options such as '[[#fixchs|fixchs]]', 
{{nowrap|'<code>[un][[#hide|hide]][all]</code>'}} and '[[#setbpb|setbpb]]'.

=== warn ===
<pre>
  warn
  *nowarn
</pre>
{{S|warn}}Wait for a key-press, right before continuing the chainloading. 
Useful to see warnings emitted by the chain module.

=== exit ===
{{S|exit}}{{V|6.04+}}Impose the end of the command to be parsed by chain.c32. 
In some cases (e.g. when using gfxboot) the resulting command line 
seems to end with some "garbage" that chain.c32 cannot understand, 
creating unexpected behavior. 
By adding '<tt>exit</tt>' to the end of the command, 
chain.c32 disregards anything after this option and should work as expected. 
Usually, this option is not required.


=== isolinux ===
<pre>
  isolinux=<myfile>
  &rarr; sets: file=<myfile> nohand nosect isolinux
</pre>
{{S|isolinux}}{{V|ISOLINUX only; 3.83+}}Chainload to another version/build of the ISOLINUX bootloader and patch the 
loader with appropriate parameters in memory. This avoids the need for the 
{{nowrap|"<code>-eltorito-alt-boot</code>"}} parameter of mkisofs, 
when you want more than one ISOLINUX per CD/DVD.

=== ntldr ===
<pre>
  ntldr=<myfile>
  &rarr; sets: file=<myfile> seg=0x2000 setbpb nohand
</pre>
{{S|ntldr}}{{V|3.70+}}Prepare to load ''ntldr'' directly. Add the 
'[[#save|save]]' option so as to store corrected BPB values.

=== cmldr ===
<pre>
  cmldr=<myfile>
  &rarr; sets: file=<myfile> seg=0x2000 setbpb nohand cmldr
</pre>
{{S|cmldr}}{{V|3.85+}}Prepare to load ''Windows Recovery Console'' directly. 
The in-memory copy of the bootsector is patched 
with {{nowrap|1='<code> cmdcons\0 </code>'}}. 
Same remarks as in '[[#ntldr|ntldr]]'.

=== reactos ===
<pre>
  reactos=<myfile>
  &rarr; sets: file=<myfile> seg=0x0F80 setbpb nohand
</pre>
{{S|reactos}}{{V|6.04+}}Prepare to load ''ReactOS's freeldr'' directly. 
Add the '[[#save|save]]' 
option so as to store corrected BPB values.

=== freedos ===
<pre>
  freedos=<myfile>
  &rarr; sets: file=<myfile> seg=0x60 sect=0x1FE0 setbpb nohand
</pre>
{{S|freedos}}{{V|3.70+}}Prepare to load ''FreeDOS kernel'' directly. 
The '[[#save|save]]' option is likely needed, 
as these 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.

Consider using the '[[#hide|hide]]' option, 
if the OS has problems with properly assigning the "C:" drive letter.

=== msdos and pcdos ===
<pre>
  pcdos=<myfile>
  msdos=<myfile>
  &rarr; sets: file=<myfile> seg=0x70 sect=0x8000 setbpb nohand
</pre>
{{S|msdos_and_pcdos}}{{V|3.70+}}Similarly to '[[#freedos|Freedos]]', prepare to load MSDOS 2.00 - 6.xx or derivatives. 
The sector address is chosen arbitrarily. Otherwise, same remarks as in '[[#freedos|Freedos]]'.

=== msdos7 ===
<pre>
  msdos7=<myfile>
  &rarr; sets: file=<myfile> seg=0x70::0x200 sect=0x8000 setbpb nohand
</pre>
{{S|msdos7}}Only for MSDOS 7+ versions (98se ~ 7.xx, Me ~ 8.xx). 
Otherwise, same remarks as in '[[#freedos|Freedos]]'.

<!--  -->
<!--  -->
<!--     TODO/TEST -->
<!--     TODO/TEST -->
<!--     TODO/TEST -->
<!--  -->
<!--  -->

=== drmk ===
<pre>
  drmk=<myfile>
  &rarr; sets: file=<myfile> seg=0x70 sect=0x2000:0:0 setbpb nohand
</pre>
{{S|drmk}}{{V|4.03+}}Used for loading of [[DRMK|Dell's]] DOS derivatives <u>only</u>. 
It requires a boot sector at <tt>0x2000</tt> and overall valid BPB values. 
As in other DOS-ish cases, likely candidates for use 
are options '[[#save|save]]' and '[[#hide|hide]]'.

=== grub ===
<pre>
  grub=<myfile> [grubcfg=<myconfig>]
  &rarr; sets: file=<myfile> seg=0x800::0x200 nohand nosect grub
</pre>
{{S|grub}}{{V|4.00+}}Chainload to grub legacy's stage2, 
performing additional corrections on the file in memory. 
{{V|4.02+}}Optionally, an alternative ''<nowiki><myconfig></nowiki>'' 
file can be specified via the '<code>grubcfg</code>' option.

=== grldr ===
<pre>
  grldr=<myfile>
  &rarr; sets: file=<myfile> nohand nosect grldr
</pre>
{{S|grldr}}{{V|3.85+}}Chainload to GRUB4DOS grldr, 
performing additional corrections on the file in memory.

=== bs ===
<pre>
  bs=<myfile>
  &rarr; sets: file=<myfile> nosect filebpb
</pre>
{{S|bs}}Emulate SYSLINUX's native BS option. Load the file and, 
if possible, also adjust its BPB values. 
Everything is made in reference to the selected disk/partition.

=== bss ===
<pre>
  bss=<myfile>
  &rarr; sets: file=<myfile> nomaps setbpb bss
</pre>
{{S|bss}}Emulate SYSLINUX's native BSS option. Load both, the 
file and the sector, adjust BPB values in the loaded sector, 
and then copy all possible BPB fields to the loaded file. 
Everything is made in reference to the selected disk/partition.


<br />
== See Also ==

* [[Comboot/chain.c32]]
* BPB: [https://en.wikipedia.org/wiki/BIOS_parameter_block BIOS Parameter Block]