                             lDOS kernel manual
                             ==================

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 2025-12-21.

1: Building the lDOS kernel
---------------------------

    To build only the kernel and sharer, the following tools are needed:

     -  bash shell

     -  GNU make, or compatible

     -  perl to process comload.lst listing file

     -  gcc to compile sumspace tool

     -  gcc-ia16 to compile patchini/patldos.com

     -  sumspace tool (source text shipped in repo)

     -  Netwide Assembler, a recent version needed (at least v2.15)

     -  dosemu2 to run DOS tools

     -  WarpLink linker (DOS tool, public domain)

     -  x2b2 tool (DOS tool, public domain)

     -  comtoexe tool (DOS tool, MIT license)

     -  lzexe tool (DOS tool, MIT license)

    The DOS tools have to be found in the DOS path.

    The following components are expected in sister directories to the repo:

     -  lmacros

     -  ldosboot

     -  scanptab

     -  kernwrap

     -  patchini (must be built separately using the mak.sh, with gcc-ia16,
        or provided in binary form)

     -  instsect (must be built separately using this repo's makinst.sh)

     -  inicomp (if to use compression support), also needs one of the
        compression tools:

         -  brieflz (blzpack)

         -  lz4

         -  snappy (snzip)

         -  exomizer

         -  x-compressor

         -  heatshrink

         -  lzip

         -  lzop

         -  lzsa -- default choice, one of the fastest depackers

         -  apultra

         -  bzpack

         -  lzexedat

2: Starting the lDOS kernel
---------------------------

    The lDOS current release build includes four different kernel files in
    the bin/ subdirectory: ldos.com, ldos.sys, ldospak.com, and ldospak.sys.
    Any single one of these four files contains the complete kernel.

    The .com files are called iniload variants, as they are wrapped in
    the lDOS iniload.asm (initial loader) stage. They are valid DOS MZ
    application executables and can be loaded as a number of different
    kernel formats.

    The .sys files are called drload variants, from the stage named
    drload.asm (originally created for the lDOS flavour of the Enhanced
    DR-DOS kernel). They are only valid to be loaded as FreeDOS kernel
    (typically named kernel.sys) or as EDR-DOS kernel (typically named
    drbio.sys). The advantage is that they are smaller than the iniload
    variants.

    The ldos files are uncompressed. The advantage is faster load time and
    being able to patch the kernel image.

    The ldospak files are compressed. The advantage is, again, the smaller
    file size.

2.1 Booting lDOS

    The lDOS kernel can boot off diskette drives (fda, fdb, fdc, fdd) or
    FAT16 or FAT12 partitions on MBR-partitioned hard disk drives. Both
    primary and logical partitions are supported.

    Loading off logical partitions may require loaders that support this
    at all and a correct (unit absolute) value for hidden sectors, either
    hardcoded into the boot sector loader or automatically detected at boot
    time. ldosmbr's altmbr, ldosboot boot.asm, and lDebug all do support
    this.

    The default drive at boot time may be any drive that matches the boot
    partition, that is it may be different than A: or C:. If the exact
    partition cannot be identified from the load unit plus hidden sectors,
    then the first drive that is logged in on the same unit is selected as
    the default drive. If no such drive exists, then either drive A: or the
    first hard disk drive (C:, D:, or E:) is selected, depending on whether
    the load unit is < 128 or >= 128. The configuration files are searched
    for in the root directory of the default drive unless the kernel command
    line specifies pathnames that include a drive specification.

2.2 Installing boot sector loader using INSTSECT

    The recommended choice is to install a boot sector loader using the
    instsect application. This application is found both in instsect.com and
    in the COMLOADER multi-executable tool which is embedded in ldos.com,
    using the command program name instsect.

    The default filename for instsect's loaders is ldos.com. Note that
    the loaders use the lDOS load protocol. Trying to load ldos.sys or
    ldospak.sys using these loaders will fail with a check 'V'alue error
    (letter "V" displayed at boot time).

    The instsect online help can be accessed using the /? switch. Redirect
    to a file or to a tool like "more" to read all of it.

3: Supported file systems
-------------------------

    lDOS currently supports the following file systems:

     -  Diskette drives (up to 4)

     -  MBR-partitioned hard disks

     -  CHS or LBA access on int 13h units

     -  Primary partitions

     -  Logical partitions (in extended partitions of type 5, 0Fh, or 85h)

     -  FAT12 or FAT16 file systems

     -  Partition types 0Eh (FAT16 LBA) and 0Fh (Extended LBA) only
        supported if HDD is accessed using LBA extensions

     -  Cluster sizes that are a power of two between 1 and 64 sectors

     -  Cluster size of 128 sectors (MSW NT extension)

     -  Cluster size of 256 sectors (Enhanced DR-DOS extension)

     -  Int 13h unit must use a sector size of 512 Bytes.

     -  Kernel is LFN aware, that is it doesn't mistake LFNs for volume
        label entries. It doesn't support LFNs.

     -  FAT32 and FAT+ are not supported. (lDOS iniload can boot off a FAT32
        drive but it won't be logged in and supported by the kernel after
        boot time.)

4: lDOS configuration
---------------------

    There are four inputs to the lDOS configuration:

     -  lDOS iniload query patch site, modified using patchqry

     -  lCFG block, modified using patchpro, patchdeb, and patchsca

     -  lDOS kernel command line, can be passed using bootable lDebug to
        chainload lDOS

     -  Configuration file

4.1 Query patch

    The query patch site determines whether the initial loader uses CHS
    or LBA access, and whether it queries the CHS geometry using int 13h
    function 08h. This is accessed using the patchqry tool.

    The query patch site is not passed along to the lDOS kernel yet.

4.2 lCFG block

    The lCFG block currently contains three configuration choices:

    First, the inicomp depack progress display choice. This allows to choose
    none, dots, percentage, bar, or bar with percentage. This is accessed
    using the patchpro tool. Supported values are displayed by running
    patchpro without parameters.

    Second, the debugger detection choice. This indicates conditions for
    detecting a resident debugger in order to avoid overwriting its int 1
    and int 3 handlers. This is accessed using the patchdeb tool. Supported
    values are displayed by running patchdeb without parameters.

    Third, the partition scan mode choice. This specifies several options
    on which partitions to log in and in what order. This is accessed using
    the patchsca tool. Supported values are displayed by running patchsca
    without parameters.

4.2.1 Supported patchpro values

      $ ./patchpro
      Usage: patchpro ldebug.com [APP|DEVICE|BOOT] [number]
      
      Supported progress types:
        0: None
        1: Dots
        2: Percentage
        3: Bar
        4: Bar with percentage

    There is a special flag, with value 16. This is only supported for APP
    and DEVICE modes. If set, then the selected progress choice is written
    to stdout even when stdout is redirected to a file. If clear, using a
    redirected stdout forces the progress display disabled. (As the lDOS
    kernel inicomp payload only supports boot mode, this flag is never
    supported by the kernel.)

4.2.2 Supported patchdeb values

      $ ./patchdeb
      Usage: patchdeb edrdos.com [number]
      
      Supported flags:
        1: Check
        2: Assume
        4: Check only valid
        8: Check only IISP

4.2.3 Supported patchsca values

      $ ./patchsca
      Usage: patchsca ldos.com [number]
      
      Supported flags:
           1|2: Ext5 setting
           4|8: Ext15 setting
          16|32: Ext85h setting
          64: Ignore subsequent nested
         128: Ignore subsequent logical
         256: Ignore subsequent primary
         512: Traditional order logical
        1024: Active priority
        2048: Subsequent primary after
        8192: Ignore FAT32
       16384: Ignore LBA
       32768: DLA sort disable
      Supported ext settings:
       0 = follow all
       1 = ignore all
       2 = follow first of any ext
       3 = follow first of this type

4.3 Kernel command line

    The kernel command line is a text string of up to 255 bytes that can be
    passed to the kernel from the prior loader. Bootable lDebug allows to
    pass a command line when loading a kernel using the RxDOS.2, RxDOS.3,
    lDOS, FreeDOS, or EDR-DOS load protocols. (The latter two need to enable
    this using a CMDLINE=1 parameter.)

    The commands of the command line are separated by semicolons. A
    semicolon immediately following another semicolon is parsed as an
    escaped semicolon. The following command names are recognised:

    CONFIG

        Highest priority configuration file override. This file is tried
        first. Default is empty.

    ALTCONFIG

        Second configuration file override. This file is tried second.
        Default is "ldos.ini".

    OLDCONFIG

        Third configuration file override. This file is tried last. Default
        is "config.sys".

    PREPEND

        Prepend the following line to the configuration file contents.

    APPEND

        Append the following line to the configuration file contents.

    CHECKDEBUGGER

        Modify check debugger value from lCFG block. Refer to section 4.2.2
        for supported values. Numbers may be prepended by "+" plus sign to
        OR number into the variable, or by "-" minus sign to AND the bitwise
        NOT of the number. Otherwise the number will rewrite the entire
        variable to the number. Numbers default to decimal format, unless
        leading "0x" or trailing "h" is specified. Multiple numbers may be
        specified separated by commas.

    SCANMODE

        Modify scan mode value from lCFG block. Refer to section 4.2.3 for
        supported values. Numbers may be prepended by "+" plus sign to OR
        number into the variable, or by "-" minus sign to AND the bitwise
        NOT of the number. Otherwise the number will rewrite the entire
        variable to the number. Numbers default to decimal format, unless
        leading "0x" or trailing "h" is specified. Multiple numbers may be
        specified separated by commas.

    "." (dot)

        Command ignored, possibly used for future optional extensions.

4.4 Configuration file

    If a configuration file is found, its length is checked. The length
    should not exceed 56 KiB. Then a buffer is allocated and the entire
    file is read. Too long file contents may be truncated. The command line
    PREPEND and APPEND lines are also stored in the buffer.

    Aside all the usual MS-DOS v4 level configuration directives, some
    additional directives are supported:

    DEVICEHIGH

        Like DEVICE but attempt to load into the UMA

    INSTALLHIGH

        Like INSTALL but attempt to load into the UMA

    INSTALLLAST, INSTALLLASTHIGH

        Like INSTALL, INSTALLHIGH but after final DOSDATA and DOSCODE
        relocation

    SHELLHIGH

        Like SHELL but attempt to load into the UMA

    COMPAT

        List comma-separated compatibility options. The following options
        are recognised:

        (NO)ALTAH

            Control allocation of a compatible ALTAH (CON device driver
            look-ahead buffer) that should be found at the segmented address
            70h:61Bh.

        (NO)DOSDATAFIRST

            Control relocation of DOSDATA segment first, before loading any
            device drivers. This means the segment will be allocated in the
            Low Memory Area.

        (NO)DOSDATAEARLY

            Control relocation of DOSDATA segment early, after any device
            driver. The segment is relocated after the first device driver
            load that provides DOS with a sufficiently large (ca 6 KiB)
            Upper Memory Block. If no such UMB is provided at all then the
            DOSDATA segment is eventually relocated into the Low Memory Area
            at the default end relocate time.

        (NO)BOUNCEHMACHS

            Control bouncing CHS disk accesses involving the HMA through the
            Low Memory Area (DOSENTRY) disk sector buffer. This slows down
            the access but may be required if the access won't work in the
            HMA.

        (NO)BOUNCEHMALBA

            Control bouncing LBA disk accesses involving the HMA through the
            Low Memory Area (DOSENTRY) disk sector buffer. This slows down
            the access but may be required if the access won't work in the
            HMA. (Appears to be needed for qemu.)

        AUTOBOUNCEHMACHS

            Enable automatic determination of bouncing CHS disk access
            involving the HMA. This is done by reading all DOS-internal CHS
            accessed nonremovable drives' boot sectors to the HMA shortly
            after it is allocated, but before DOSCODE is installed into
            it. If any of them are written to an A20-wrapped address into
            the disk sector in the DOSENTRY section which is in the Low
            Memory Area, bouncing is enabled for all CHS accesses. A message
            indicating the first drive that needs this is then displayed.
            Specifying either BOUNCEHMACHS or NOBOUNCEHMACHS disables this
            automatic detection.

        AUTOBOUNCEHMALBA

            As above but for LBA accessed nonremovable drives.

        (NO)BOUNCEUMACHS

            Control bouncing CHS disk accesses involving the UMA, or HMA.
            If enabled, all accesses to the UMA (typically starting at
            segment A000h) and also the HMA will be bounced through the LMA
            (DOSENTRY) disk sector buffer. If disabled, UMA accesses are not
            bounced but HMA accesses still may be.

        (NO)BOUNCEANYCHS

            If enabled, bounce any CHS disk access through the DOSENTRY disk
            sector buffer. If disabled, LMA accesses are not bounced but UMA
            and HMA accesses still may be.

        (NO)BOUNCEUMALBA

        (NO)BOUNCEANYLBA

            As above but for LBA accessed drives.

        (NO)HIDEDOSENTRY

            Controls hiding of the first MCB, which is for the DOSENTRY
            segment. This MCB typically is located at segment 60h. Some
            programs such as FreeDOS MEM with its /D switch may not expect
            the entry segment and its device driver headers to appear in an
            MCB. If this is enabled, the first MCB in the DOS list of lists
            is changed to point past the DOSENTRY MCB.

        (NO)HIDEDOSDATAFIRST

            Controls hiding of the DOSDATA MCB. This only takes effect
            if DOSDATAFIRST is enabled. The DOS list of lists first MCB
            field is changed to point past the final DOSDATA MCB after the
            relocation, then. This implies that the DOSENTRY MCB is hidden
            as well. The ALTAH MCB may also be hidden due to this, if the
            ALTAH option is enabled.

5: Additional usage conditions
------------------------------

    The kernel executables can be compressed with a choice of different
    compressors. The files then contain a decompression stub. Some of
    these stubs have their own usage conditions. The following stub usage
    conditions apply, if one of these stubs is used.

5.1 BriefLZ depacker usage conditions

    BriefLZ - small fast Lempel-Ziv

    8086 Assembly lDOS iniload payload BriefLZ depacker

    Based on: BriefLZ C safe depacker

    Copyright (c) 2002-2016 Joergen Ibsen

    This software is provided 'as-is', without any express or implied
    warranty. In no event will the authors be held liable for any damages
    arising from the use of this software.

    Permission is granted to anyone to use this software for any purpose,
    including commercial applications, and to alter it and redistribute it
    freely, subject to the following restrictions:

     1. The origin of this software must not be misrepresented; you must not
        claim that you wrote the original software. If you use this software
        in a product, an acknowledgment in the product documentation would
        be appreciated but is not required.

     2. Altered source versions must be plainly marked as such, and must not
        be misrepresented as being the original software.

     3. This notice may not be removed or altered from any source
        distribution.

5.2 LZ4 depacker usage conditions

    8086 Assembly lDOS iniload payload LZ4 depacker

        by E. C. Masloch, 2018

    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.

5.3 Snappy depacker usage conditions

    8086 Assembly lDOS iniload payload Snappy depacker

        by E. C. Masloch, 2018

    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.

5.4 Exomizer depacker usage conditions

    8086 Assembly lDOS iniload payload exomizer raw depacker

        by E. C. Masloch, 2020

    Copyright (c) 2005-2017 Magnus Lind.

    This software is provided 'as-is', without any express or implied
    warranty. In no event will the authors be held liable for any damages
    arising from the use of this software.

    Permission is granted to anyone to use this software for any purpose,
    including commercial applications, and to alter it and redistribute it
    freely, subject to the following restrictions:

     1. The origin of this software must not be misrepresented * you
        must not claim that you wrote the original software. If you use
        this software in a product, an acknowledgment in the product
        documentation would be appreciated but is not required.

     2. Altered source versions must be plainly marked as such, and must not
        be misrepresented as being the original software.

     3. This notice may not be removed or altered from any distribution.

5.5 X compressor depacker usage conditions

    MIT License

    Copyright (c) 2020 David Barina

    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:

    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

5.6 Heatshrink depacker usage conditions

    8086 Assembly lDOS iniload payload heatshrink depacker

        by E. C. Masloch, 2020

    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.

5.7 Lzd usage conditions

    Lzd - Educational decompressor for the lzip format

        Copyright (C) 2013-2019 Antonio Diaz Diaz.

    This program is free software. Redistribution and use in source and
    binary forms, with or without modification, are permitted provided that
    the following conditions are met:

     1. Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.

     2. Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

5.8 LZO depacker usage conditions

    8086 Assembly lDOS iniload payload LZO depacker

        by E. C. Masloch, 2020

    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.

5.9 LZSA2 depacker usage conditions

    8086 Assembly lDOS iniload payload LZSA2 depacker

        by E. C. Masloch, 2021

        based on:

    decompress_small.S - space-efficient decompressor implementation for
    8088

    Copyright (C) 2019 Emmanuel Marty

    This software is provided 'as-is', without any express or implied
    warranty. In no event will the authors be held liable for any damages
    arising from the use of this software.

    Permission is granted to anyone to use this software for any purpose,
    including commercial applications, and to alter it and redistribute it
    freely, subject to the following restrictions:

     1. The origin of this software must not be misrepresented; you must not
        claim that you wrote the original software. If you use this software
        in a product, an acknowledgment in the product documentation would
        be appreciated but is not required.

     2. Altered source versions must be plainly marked as such, and must not
        be misrepresented as being the original software.

     3. This notice may not be removed or altered from any source
        distribution.

5.10 aPLib depacker usage conditions

    8086 Assembly lDOS iniload payload aPLib depacker

        by E. C. Masloch, 2021

        based on:

    aplib_8088_small.S - size-optimized aPLib decompressor for 8088 - 145
    bytes

    Copyright (C) 2019 Emmanuel Marty

    This software is provided 'as-is', without any express or implied
    warranty. In no event will the authors be held liable for any damages
    arising from the use of this software.

    Permission is granted to anyone to use this software for any purpose,
    including commercial applications, and to alter it and redistribute it
    freely, subject to the following restrictions:

     1. The origin of this software must not be misrepresented; you must not
        claim that you wrote the original software. If you use this software
        in a product, an acknowledgment in the product documentation would
        be appreciated but is not required.

     2. Altered source versions must be plainly marked as such, and must not
        be misrepresented as being the original software.

     3. This notice may not be removed or altered from any source
        distribution.

5.11 bzpack depacker usage conditions

    8086 Assembly lDOS iniload payload bzpack depacker

        by E. C. Masloch, 2021

    BSD 2-Clause License

    Copyright (c) 2021, Milos Bazelides

    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are
    met:

     1. Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.

     2. Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
    TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Source Control Revision ID
--------------------------

    hg a501ac0359c8, from commit on at 2025-12-21 17:49:41 +0100

    If this is in ecm's repository, you can find it at
    https://hg.pushbx.org/ecm/msdos4/rev/a501ac0359c8

