# lDOS kernel manual

- 1: Building the lDOS kernel
- 2: Starting the lDOS kernel
  - 2.1 Booting lDOS
  - 2.2 Installing boot sector loader using INSTSECT
- 3: Supported file systems
- 4: lDOS configuration
  - 4.1 Query patch
  - 4.2 lCFG block
  - 4.3 Kernel command line
  - 4.4 Configuration file
- 5: Additional usage conditions
  - 5.1 BriefLZ depacker usage conditions
  - 5.2 LZ4 depacker usage conditions
  - 5.3 Snappy depacker usage conditions
  - 5.4 Exomizer depacker usage conditions
  - 5.5 X compressor depacker usage conditions
  - 5.6 Heatshrink depacker usage conditions
  - 5.7 Lzd usage conditions
  - 5.8 LZO depacker usage conditions
  - 5.9 LZSA2 depacker usage conditions
  - 5.10 aPLib depacker usage conditions
  - 5.11 bzpack depacker usage conditions
- Source Control Revision ID

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