User Tools

Site Tools


blog:pushbx:2022:1107_bootable_ldebug_vs_freedos_debugb

This is an old revision of the document!


Bootable lDebug vs FreeDOS DebugB

FreeDOS Debug got a new build variant earlier: DebugB. It is implemented by these two git revisions so far: 88a97d7 and the subsequent 4ae8e41. Let's compare and contrast it with lDebug's boot mode support!

FreeDOS DebugB documentation

It is listed as follows in the history:

- added a "boot" version of the debugger - it's supposed to be loaded
before DOS by boot sector code.

And in the readme:

- DebugB.BIN: a version that is supposed to be loaded during the
boot process, before DOS is loaded. Has to be installed in "free"
disk space ( for example, in the "reserved" sectors of a FAT partition
or behind the disk's MBR ) and must be initialized before it becomes
active. Definitely not for beginners. See "Installing and Initializing
DebugB" in DEBUG.TXT for details.

There is a longer introduction, referenced here, which includes some of the load protocol used by DebugB, in the DEBUG.TXT file.

Bootable lDebug documentation

Here's the section "Invoking the debugger in boot loaded mode" from the current lDebug manual:

The debugger can be loaded as a variety of kernel formats.

The Multiboot1 and Multiboot2 entrypoints will expect that a kernel
command line is provided. The FreeDOS, RxDOS.3, and lDOS load protocols
allow specifying a kernel command line, but it is optional.

If a kernel command line is detected then its contents are entered
into the command line buffer. Unescaped semicolons are translated
into Carriage Returns. Semicolons and backslashes may be escaped with
backslashes.

If no kernel command line is given, the debugger assumes a default. It
is equivalent to checking for a file and label using the IF command
(section 9.18), then if found to execute that script file. The IF
condition is like "if exists y ldp/LDEBUG.SLD :bootstartup then" and the
subsequent script command is "y ldp/LDEBUG.SLD :bootstartup" (section
9.48). The filename is however "LDDEBUG.SLD" for DDebug builds, and
"LCDEBUG.SLD" for CDebug builds.

Executing the Q command (section 9.26) makes the debugger uninstall
itself then continue running whatever code the debuggee is in. Executing
the BOOT QUIT command (section 14.10) makes the debugger attempt to shut
down the machine. First it will try to call a dosemu-specific callback.
Next it will attempt shutting down with APM. (This works in qemu.)
Finally it will give up if no attempt worked.

And here's some more text on the kernel load protocols supported by lDebug, from the "How to build" section:

The bootable executables can be used as MS-DOS 6 protocol IO.SYS, MS-
DOS 7/8 IO.SYS, PC-DOS 6/7 IBMBIO.COM, FreeDOS KERNEL.SYS, RxDOS.3
RXDOS.COM, or as a Multiboot specification or Multiboot2 specification
kernel. In any kernel load protocol case, the root FS that is being
loaded from should be a valid FAT12, FAT16, or FAT32 file system on
an unpartitioned (super)floppy diskette (unit number up to 127) or
MBR-partitioned hard disk (unit number above 127). In addition, the
bootable executables also are valid 86-DOS application programs that
can be loaded in EXE mode either as application or as device driver.
(Internally, all the .com files are MZ executables with a header, but
they are named with a .COM file name extension for compatibility.)

It is valid to append additional data, such as a .ZIP archive, to any of
the executables. However, if too large this may render loading with the
FreeDOS load protocol impossible. All the other protocols work even in
the presence of arbitrarily large appended data.

Here's some text on the use of instsect from the section "How to build the instsect application" from the lDebug manual:

ldebug/tmp, ldebug/lst, and ldebug/bin will receive the files created
by the makinst script. ldebug/bin/instsect.com will be the instsect
application, which has boot sector loaders for FAT12, FAT16, and
FAT32 embedded. The default protocol is lDOS and the default kernel
name LDEBUG.COM. Read the instsect help page for instructions on how
to use it. Refer to section 13.2 for the instsect help. The help can
also be obtained by running instsect.com /? from DOS. The kernel
name can be modified with the /F= switch to instsect. For instance,
"instsect.com /f=lddebugu.com a:" installs the loader onto drive A: with
the name set up to load the uncompressed lDDebug.

Current lDOS boot32 uses the FSIBOOT4 protocol for an additional stage.
This is interoperable with the upcoming RxDOS version 7.25's use of the
FSIBOOT4 protocol, as well as with loaders that use a different sector
for their additional stage (like Microsoft's), or those that do not use
an additional stage (like FreeDOS's).

And finally here are three more links: To the ?BOOT online help page and to the instsect online help as reproduced in the lDebug manual, as well as to the ldosboot documentation which documents the lDebug native lDOS boot load protocol.

Comparison

Supported modes per build

  • DebugB is provided as a binary file that is a special purpose build. It can only be used in boot loaded mode.
  • lDebug includes booting capabilities in a single build (which can be Debug, DDebug, CDebug, or any of those three with additional DPMI support indicated by a trailing X)

I believe that lDebug wins out here as part of its "go everywhere, do everything" theme. However, disk space and memory requirements are larger for current lDebug than for a special purpose build that can only be used in one mode. (The disk space obviously only wins out if you do not need multiple different special purpose builds where one all purpose build could do.) I'm now considering adding build time conditionals to create special purpose builds like this from the lDebug sources.

Installation and loading

  • DebugB is said to be installed by doing a far call to it. Its entire executable image needs to be loaded. It is suggested to store its image behind the MBR or in the reserved sectors of a file system partition. No loader is provided to implement this.
  • lDebug ships with instsect, which will install a FAT12, FAT16, or FAT32+FSIBOOT boot sector loader that can load any bootable lDebug build from any root directory entry, regardless any fragmentation of the kernel image in the executable file, using LBA if available or CHS else. It also can be used as a compatible replacement for a number of other ROM-BIOS-based boot load protocol kernel files, thanks to its use of the versatile ldosboot initial loader. The protocol is also well-defined in the ldosboot documentation (linked above).

lDebug clearly wins out here. DebugB's odd load protocol doesn't buy it anything that cannot be emulated with lDebug's lDOS load protocol. (I do not currently provide an lDOS boot loader that reads an image from reserved areas behind the MBR or VBR, but it would be no more difficult to implement than what DebugB requires currently.) The provided lDOS loaders are easily installed once built. They are distributed as free software, building with NASM and the lmacros macro collection.

Relocation

  • DebugB will try to relocate itself to the top of the Low Memory Area then adjust the BIOS Data Area memory size indicator. The actual relocation takes place after interrupt handlers have already been installed.
  • lDebug will relocate itself multiple times if necessary. Error conditions are also detected, unlike DebugB. lDebug eventually places itself at the top of the LMA and adjusts the memory size in the BIOS Data Area, much like DebugB. It will relocate and initialise itself before installing any interrupt handlers.

lDebug wins out in that its relocation handling is more involved and more robust.

Detection

  • DebugB installs itself behind the LMA. It cannot be detected easily.
  • lDebug will install one or several image identification paragraphs with the signature "NDEB" or "NSYM" which can be used to detect lDebug.

lDebug wins, although its image identification could be documented better.

Accessing sectors

  • DebugB provides a barebones L command to read sectors off an int 13h unit. It currently assumes that the LBA extensions are available for reading from the unit.
  • lDebug provides the BOOT READ and BOOT WRITE commands, which can be used to read and write sectors either from LBA (if available), CHS (if LBA unavailable), or from CHS forced (even if LBA available). lDebug uses its sector segment buffer to transparently handle DMA boundary errors that may be returned by the interrupt 13h handler. (Eg, when crossing a 64 KiB boundary in memory for diskette DMA.) It also automatically loads sectors one by one, avoiding errors due to crossing track boundaries or exceeding 64 KiB in one command.

lDebug clearly wins.

Quitting

  • DebugB does not provide any quit or uninstall commands.
  • lDebug provides the Q command to try to uninstall the debugger then continue running the current debuggee, as well as the BOOT QUIT command to try to shut down the machine which works with dosemu2 and qemu.

lDebug wins again.

Loading programs

  • DebugB suggests using its limited L command to "load and run another boot sector from inside the debugger". It does not provide any other ways to load programs.
  • lDebug provides its BOOT commands, either (the default) BOOT PROTOCOL=SECTOR or BOOT with a protocol specification to directly simulate the operation of a boot sector loader and load another kernel. The loader handling used for this provides a highly compatible operation but extends the protocols so as to, for example, allow loading from any directory entries and regardless fragmentation. Even if none of this is desired, lDebug's BOOT READ command can be used the same way as DebugB's L command.

lDebug provides many more features.

Listing partitions

  • DebugB advertises that the "DP command may be used to list the available partitions of a disk". It appears to not have been implemented or uploaded yet.
  • lDebug allows listing partitions using the BOOT LIST family of commands. While this cannot yet be compared to what the DP command may provide it does allow listing single partitions or all partitions of a particular unit.

lDebug tentatively wins.

Discussion

C. MaslochC. Masloch, 2022-11-07 22:45:40 +0100 Nov Mon

While writing this article a new revision of FreeDOS Debug with some DebugB changes went up. In particular the L command now falls back to CHS for diskettes (unit ⇐ 7Fh) or if the LBA detection fails, though requiring interrupt 13h service 08h to be provided for CHS calculation (and no CHS overflow checks). And the DP command was added. It seems to load sector 0 (the MBR) of unit 80h and display the four possible primary partitions.

C. MaslochC. Masloch, 2022-11-09 01:16:36 +0100 Nov Wed

New revision at https://github.com/Baron-von-Riedesel/DOS-debug/commit/94cc66ac5607a3c53a033341d08b781da4e436ec

Now the DP command takes a unit number to read, which must be 80h or higher. An MBR loader is provided which loads the debugger image by assuming it is stored within the first 40 sectors starting at LBA sector number 1. A single 13.02 or 13.42 call is used to load the entire image.

You could leave a comment if you were logged in.
blog/pushbx/2022/1107_bootable_ldebug_vs_freedos_debugb.1667857992.txt.gz · Last modified: 2022-11-07 22:53:12 +0100 Nov Mon by ecm