pushbx wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Bootable lDebug vs FreeDOS DebugB ======

FreeDOS Debug got a new build variant earlier: DebugB. It is implemented by these two git revisions so far: [[https://github.com/Baron-von-Riedesel/DOS-debug/commit/88a97d7d1f7f627e561d14b8e63efae57106d5cb|88a97d7]] and the subsequent [[https://github.com/Baron-von-Riedesel/DOS-debug/commit/4ae8e4142dca55447ce241a00b3265f8bc1c6331|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, [[https://github.com/Baron-von-Riedesel/DOS-debug/blob/4ae8e4142dca55447ce241a00b3265f8bc1c6331/DEBUG.TXT#L800|in the DEBUG.TXT file]].


===== Bootable lDebug documentation =====

Here's the [[https://pushbx.org/ecm/doc/ldebug.htm#invoking-boot|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 [[https://pushbx.org/ecm/doc/ldebug.htm#buildingprocess|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 [[https://pushbx.org/ecm/doc/ldebug.htm#buildinginstsect|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 [[https://pushbx.org/ecm/doc/ldebug.htm#helpboot|the ?BOOT online help page]] and to [[https://pushbx.org/ecm/doc/ldebug.htm#cmdhelp-instsect|the instsect online help]] as reproduced in the lDebug manual, as well as to [[https://pushbx.org/ecm/doc/ldosboot.htm|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 that is also usable as a DOS application (which can be Debug, DDebug, [[blog:pushbx:2022:0804_conditionally_debuggable_ldebug|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 [[https://hg.pushbx.org/ecm/ldebug/file/94da9948c96d/source/init.asm#l1483|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.


{{tag>ldebug fddebug boot}}


~~DISCUSSION~~