\cfg{chapter}{Section}

\cfg{text-filename}{loader.txt}
\cfg{text-chapter-numeric}{true}
\cfg{text-indent-preamble}{false}
\cfg{text-quotes}{"}{"}
\cfg{text-indent}{4}
\cfg{text-width}{72}

\cfg{html-chapter-numeric}{true}
\cfg{html-suppress-address}{true}
\cfg{html-single-filename}{loader.htm}
\cfg{html-leaf-level}{0}
\cfg{html-template-fragment}{%k}{%b}
\cfg{html-head-end}{<meta name="viewport" content="width=device-width, initial-scale=1.0">}
\cfg{html-leaf-contains-contents}{true}
\cfg{html-heading-hashtag-links}{true}

\cfg{pdf-filename}{loader.pdf}

\cfg{ps-filename}{loader.ps}

\cfg{info-filename}{loader.info}

\cfg{chm-filename}{loader.chm}

\cfg{winhelp-filename}{loader.hlp}

\cfg{man-filename}{loader.7}
\cfg{man-identity}{loader}{7}{2025}{}{E. C. Masloch}

\title Loader manual

\copyright 2020--2025 by E. C. Masloch.
Usage of the works is permitted provided that this
instrument is retained with the works, so that any entity
that uses the works is notified of this instrument.
DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY.

This document has been compiled on \date{%Y-%m-%d}.


\C{overview} Overview

The lDOS pre-boot loader is a kernel replacement application for 86-DOS
systems. It is based on the bootable debugger, lDebug. Many of its commands
are based on those of lDebug.

Unlike lDebug, the loader can only run as a kernel, that is one can boot it
but not run it as a DOS device driver or DOS application. The loader shares
the debugger's support for loading Script for lDebug (.sld) and Extension
for lDebug (.eld) files in principle, though not all ELDs are supported.

\C{commands} Commands

\H{supported-commands} Supported commands

The following commands are supported by the loader.
Most of them are shared with the debugger,
refer to \W{https://pushbx.org/ecm/doc/ldebug.htm}{the lDebug manual}
for their descriptions.

\b \cw{BU}, \cw{BOOT}

\b \cw{D}, \cw{DB}, \cw{DW}, \cw{DD}

\b \cw{DI}

\b \cw{DT}

\b \cw{E}

\b \cw{EXT}

\b \cw{F}

\b \cw{G} and \cw{GODEBUG} (behaviour differs from debugger)

\b \cw{H}

\b \cw{I}, \cw{IW}, \cw{ID}

\b \cw{M}, \cw{MOVE} (\cw{MOVE} is unique to the loader)

\b \cw{O}, \cw{OW}, \cw{OD}

\b \cw{Q} (differs from debugger)

\b \cw{R}, \cw{RF}, \cw{RC}

\b \cw{SLEEP}

\b \cw{Y}


\H{unsupported-commands} Unsupported commands

The following debugger commands are not supported:

\b \cw{A}

\b \cw{B} for permanent breakpoints

\b \cw{C}

\b \cw{DL}

\b \cw{DM}

\b \cw{DX}

\b \cw{D$}, \cw{D#}, \cw{DW#}, \cw{DZ}

\b \cw{G}

\b \cw{K}

\b \cw{L}

\b \cw{N}

\b \cw{P}

\b \cw{Q}

\b \cw{RE}

\b \cw{RM}

\b \cw{RN}

\b \cw{S}

\b \cw{T}

\b \cw{U}

\b \cw{V}

\b \cw{W}

\b \cw{X}

\b \cw{Z}


\H{specific-commands} Specific commands

The following commands are unique to or different in the loader:

\b \cw{BOOT} disallows chainloading of kernels or sectors that would obviously
overwrite the loader at its current position.

\b \cw{EXT} cannot load all Extensions for lDebug as the loader doesn't provide
all functions and variables needed for some ELDs. However, the EXT command
can be used to load N extensions from the loader in the bottom position,
which can install themselves to stay as resident extensions above the Low
Memory Area.

\b \cw{G} doesn't install all the interrupt hooks used by the debugger, so it
effectively transfers control to the loaded program.
AMIS and serial interrupt hooks are undone when running a \cw{G} command
from a bottom or top position,
as it is assumed that the loader is discarded in this case.

\b \cw{GODEBUG} does special postprocessing after loading a supported debugger
using the lDOS load protocol, then runs that debugger. This command must be
run from the hidden position, and will eventually relocate the loader to
the bottom position.

\b \cw{MOVE} allows to change the loader position
from \cw{HIDDEN} to \cw{BOTTOM} or vice versa, and
from \cw{BOTTOM} to \cw{TOP} and vice versa.
(Directly moving from \cw{HIDDEN}
to \cw{TOP} or the reverse is not supported.)

\b \cw{Q} uninstalls the serial I/O connection
and AMIS hook if they are enabled, then just runs an int 19h.
This will be caught by the loader itself if resident in the
hidden position, or another handler otherwise.


\C{positions} Positions of the loader

The positions of the loader are as follows:

\b \cw{HIDDEN}. The loader initially installs itself as a hidden program, above
the Low Memory Area, by adjusting the memory size reported by the ROM-BIOS
int 12h. (An EBDA is relocated down if present.) In this position, int 18h
and int 19h are hooked to return control flow to the loader's main command
loop (cmd3). Loader must be in this position to use the \cw{GODEBUG} command.

\b \cw{BOTTOM}. The loader places itself at segment 60h (linear 00600h). If
moving from the hidden position, the memory size is adjusted back and the
EBDA is relocated up. Most BOOT protocols cannot run while the loader is at
bottom position, albeit lDOS load protocol can be used with a specifier
like SEGMENT=2000 to avoid corrupting the loader. Extensions (in ELD files)
that want to install as resident N extensions can be run from the loader at
bottom position.

\b \cw{TOP}. The loader places itself at a high segment below the end of the
Low Memory Area. Unlike the hidden position, the memory size is not lowered
to reserve memory to the loader. That means it runs in memory belonging to
the kernel if one is loaded. Commands to load using BOOT protocols can
generally be used in this state, and will preserve the loader where it is
at the top of memory. It is expected to then run what was loaded using the
\cw{G} command, which discards the loader.
