FreeDOS's DEBUG.EXE - Is there a way to set a *.ASM file dependent breakpoint?

[bugthis]

I am using FreeDOS's DEBUG.EXE for debugging and JWASMR.EXE to assemble assembly source code files *.asm.

I know, that DEBUG.EXE is there to be as compatible to MS-DOS's DEBUG.EXE as possible, but is there a way to set a breakpoint depending on a *.asm source code file that is passed to debug when debug is run?

Let's say i have an ASM source code in file hello.asm and i want set a breakpoint in line number 10 and the compiled file is hello.exe is there a feature to pass on besides the binary executable also the source code
and the line number to set a breakpoint in DEBUG?

What i like to have is something like this, starting debug like this:
DEBUG.EXE programfile sourcefile breakpoint_number
debug.exe hello.exe hello.asm 10

Is this possible?
Or is there another way to make DEBUG.EXE use a ASM source code file to set breakpoints?
I ask because setting breakpoints the normal way in DEBUG.EXE is quite cumbersome.

[_japheth]

What i like to have is something like this, starting debug like this:
DEBUG.EXE programfile sourcefile breakpoint_number
debug.exe hello.exe hello.asm 10

Is this possible?

Not with DEBUG - "symbolic debugging" isn't supported.

The most basic tool that allows symbolic debugging is MS symdeb, the predecessor of CodeView, like DEBUG a line oriented debugger, very ancient.

The tool chain for symbolic debugging with symdeb looks like this:

1. jwasm -Zd hello.asm
2. link /li /map hello.obj;
3. mapsym hello.map
4. symdeb hello.sym hello.exe

It still works, I just tested it with this source (hello.asm):

Code Select Expand


.286
.model tiny
.stack 1024
.dosseg

public text1

.data

text1 db "hello",13,10,'$'

.code
start:
mov ax, @data
mov ds, ax
assume ds:dgroup
mov dx, offset text1
mov ah, 9
int 21h
mov ax,4c00h
int 21h

END start


Note that the source must contain at least ONE symbol.declared as public!
The most important lacking feature of symdeb is that it doesn't support 80386+ cpus

Or is there another way to make DEBUG.EXE use a ASM source code file to set breakpoints?
I ask because setting breakpoints the normal way in DEBUG.EXE is quite cumbersome.

No.

[bugthis]

Not with DEBUG - "symbolic debugging" isn't supported.

The most basic tool that allows symbolic debugging is MS symdeb, the predecessor of CodeView, like DEBUG a line oriented debugger, very ancient.

Thank you for your answer. That is sad to hear. Unfortunately I don't have SYMDEB or CodeView.

Will FreeDOS's DEBUG.EXE support symbolic debugging in future? Is this a planned feature?

Now i also know, what SID86.EXE from Digital Research (DR-DOS) does better than Microsoft's  DEBUG.EXE, it does support symbolic debugging.

From the users guide:

SID-86  is a powerful symbolic debugger designed for use with the CP/M-86 and
MP/M-86 operating systems. It expands on the features of the standard CP/M-86
debugger,  DDT-86,  allowing users to test and debug  programs interactively.
SID-86  includes  symbolic  assembly and  disassembly,  expressions involving
hexadecimal,  decimal, ASCII, and symbolic values, permanent breakpoints with
pass  counts,  and trace without call. You should be familiar with  the Intel
8086  processor,  ASM-86  and  the CP/M-86 or  MP/M-86  operating  system, as
described in the "CP/M-86 Operating System System Guide" or "MP/M-86 Operating
System System Guide".

http://www.cpm.z80.de/manuals/SID86_User_Guide.txt

The tool chain for symbolic debugging with symdeb looks like this:

1. jwasm -Zd hello.asm
2. link /li /map hello.obj;
3. mapsym hello.map
4. symdeb hello.sym hello.exe

Unfortunately, I don't have LINK.EXE either. It is not part of MS-DOS 6.x which i have. The last MS-DOS version with which it was delivered was probably MS-DOS 4.x and I don't have that or an older version.

However, FreeDOS comes with the Watcom C compiler and it has WLINK.EXE as the linker. This is the linker I've used so far to include object files.
Now I just need to figure out what the comparable parameters are to use symbolic debugging. Those from LINK.EXE understandably don't work with WLINK.EXE

And then I would still have to test SID86.EXE, which I have with DR-DOS 3.41, whether it is compatible with the JWASM parameter -Zd and its output. If so, then I would have a symbolic debugger I could use.

Or does the Watcom C Compiler Suite provide a better debugger alternative with symbolic debugging support?

It still works, I just tested it with this source (hello.asm):
..

Note that the source must contain at least ONE symbol.declared as public!
The most important lacking feature of symdeb is that it doesn't support 80386+ cpus

Thank you, i will test that as soon as i have a working tool chain.

[_japheth]

Will FreeDOS's DEBUG.EXE support symbolic debugging in future? Is this a planned feature?

No.

Now i also know, what SID86.EXE from Digital Research (DR-DOS) does better than Microsoft's  DEBUG.EXE, it does support symbolic debugging.

Yes - if you'll manage to make it work...

However, FreeDOS comes with the Watcom C compiler and it has WLINK.EXE as the linker. This is the linker I've used so far to include object files.
Now I just need to figure out what the comparable parameters are to use symbolic debugging. Those from LINK.EXE understandably don't work with WLINK.EXE

The Watcom debugger has symbolic debugging capabilities and works quite well. It's a bit biased towards C, however. Your assembly program must have e public "main" proc, and memory model TINY won't work. Also, it's a "full-screen" application like CodeVIew - personally, I prefer the debuggers with a simple line interface.

The tool chain is:
jwasm -Zi hello.asm
wlink debug c format dos file hello.obj op cvp

and then just run: wd hello.exe

If it doesn't work, try jwlink instead of wlink. IIRC, I fixed a bug in the open watcom Codeview format handler for jwlink.

[bugthis]

Now i also know, what SID86.EXE from Digital Research (DR-DOS) does better than Microsoft's  DEBUG.EXE, it does support symbolic debugging.

Yes - if you'll manage to make it work...

I will try.
But first i need to learn the command syntax. It is quite different to DEBUG.EXE

The Watcom debugger has symbolic debugging capabilities and works quite well. It's a bit biased towards C, however. Your assembly program must have e public "main" proc, and memory model TINY won't work. Also, it's a "full-screen" application like CodeVIew - personally, I prefer the debuggers with a simple line interface.

The tool chain is:
jwasm -Zi hello.asm
wlink debug c format dos file hello.obj op cvp

and then just run: wd hello.exe

If it doesn't work, try jwlink instead of wlink. IIRC, I fixed a bug in the open watcom Codeview format handler for jwlink.

Thank you. I will try that.

[bugthis]

The Watcom debugger has symbolic debugging capabilities and works quite well. It's a bit biased towards C, however. Your assembly program must have e public "main" proc, and memory model TINY won't work. Also, it's a "full-screen" application like CodeVIew - personally, I prefer the debuggers with a simple line interface.

The tool chain is:
jwasm -Zi hello.asm
wlink debug c format dos file hello.obj op cvp

and then just run: wd hello.exe

Thanks. I tried that today, but DOS4G/W throws an exception (error 2001) when i try to load my Real Mode program.

I used SMALL, C for .MODEL

Code Select Expand


PUBLIC MAIN
.MODEL SMALL, C
.STACK 256
.DOSSEG

.CODE

MAIN:
....
END MAIN


If it doesn't work, try jwlink instead of wlink. IIRC, I fixed a bug in the open watcom Codeview format handler for jwlink.

jwlink isn't shipped with FreeDOS.
Thus i downloaded the DOS binary from:
https://www.japheth.de/Download/JWlink/JWlink_v19b13_dos.zip

And did what you said.
But wd crashes with the same message.

[_japheth]

Thanks. I tried that today, but DOS4G/W throws an exception (error 2001) when i try to load my Real Mode program.

No idea what's that's supposed to mean. But it may shed light on the reason why I prefer simple tools without "tons of features" ...

Thus i downloaded the DOS binary from:
https://www.japheth.de/Download/JWlink/JWlink_v19b13_dos.zip

That's an outdated link, containing very old and obsolete binaries. But it doesn't matter, using an up-to-date jwlink most likely won't fix the WD "exception".

[bugthis]

Now i also know, what SID86.EXE from Digital Research (DR-DOS) does better than Microsoft's  DEBUG.EXE, it does support symbolic debugging.

Yes - if you'll manage to make it work...

I took a closer look at SID in the last few days.
What I found out so far is that SID expects *.SYM files as symbol files.
They are loaded by passing two arguments to SID at the command line
Where the first is the program file and the second is a *.sym file.

Code Select Expand

SID program symfile

Besides that, i found out, that SID86 was also shipped with a suite called DRI Programmer's Utilities.
This suite also included an assembler called rasm86.exe, a linker link86.exe, a tool lib86.exe to create libraries and xref86.exe to create some documentation for printing.

The manual gave some informations about the object file format that is used by the assembler and that SID86 understands.
On page 3 of the manual it is stated, that the assembler does use the Intel Object Module Format.
https://bitsavers.org/pdf/digitalResearch/concurrent/1065-2043-001_Programmers_Utilities_Guide_For_Concurrent_DOS_86_Expanded_Memory_XM_Nov1986.pdf

I don't know, if JWASM can generate it or if this is the same, as -omf which is created by default.
https://www.japheth.de/JWasm/Manual.html#CHAPOUTPUTFORMATS

The problem is now, that i don't know how to create a *.sym file with JWASM?

Also i found another big problem or bug. SID86 can read and debug every *.EXE file out there, with the exception of those, i created with JWASM and the -mz parameter.
I really don't know why that is.
When trying to load such a file, SID prints the error "insufficient memory" but the file i used as an example is only 62 bytes in size. Thus it is definitely not a memory issue, it's more some kind of incompatibilities.

*.COM files that where created with the -bin parameter with JWASM can be loaded with SID on the other hand and debugged with SID. I don't know why it fails at JWASM's EXE files and passes at other EXE files that were not created with JWASM.

The biggest difference between SID and DEBUG was, that you have to use the command "tw" inside SID to step over interrupts and other routines, this is similar to DEBUG's "P" command. If you don't do that, it's like a simple "T" command in DEBUG, which will result in stepping into an interrupt and going bogus.

The registers can be shown with the command "X" instead of "R".
To show the disassembly code you must press "L" for list, instead of "U" for unassembly.

A disadvantage of SID is that the assembler mnemonics that appear after a "T" step in a program do not represent the mnemonics that SID will run next, but rather the one that was already ran.
The mnemonic of the next command to be executed is not displayed, only the address is displayed and if you want to know the mnemonic of the next command, you must use the list "L" command to display it.
This is quite cumbersome and solved better in DEBUG, where the next command is shown with each "T" step.

The rest is quite similar, with the exception that SID is in some way much more powerful than DEBUG and the flag register output is much easier to read.

[_japheth]

The manual gave some informations about the object file format that is used by the assembler and that SID86 understands.
On page 3 of the manual it is stated, that the assembler does use the Intel Object Module Format.
I don't know, if JWASM can generate it or if this is the same, as -omf which is created by default.

Yes, this format is pretty well documented.

The problem is now, that i don't know how to create a *.sym file with JWASM?

.SYM files can be created only alter/during the link step. Although jwasm acts as a "micro" linker when using -mz or -bin options, it doesn't output .SYM files - and I doubt that there's a standard/documented format for such files.

Also i found another big problem or bug. SID86 can read and debug every *.EXE file out there, with the exception of those, i created with JWASM and the -mz parameter.

Should be no problem - just don't use the -mz option and let the DR tools do the link step.

[bugthis]

The problem is now, that i don't know how to create a *.sym file with JWASM?

.SYM files can be created only alter/during the link step. Although jwasm acts as a "micro" linker when using -mz or -bin options, it doesn't output .SYM files - and I doubt that there's a standard/documented format for such files.

I did a little research.
So far i found out, that Digital Research's LINK86 does only produce .SYM files, if the symbol table is already embedded in the object file.
Otherwise the .SYM file will be empty and unusable for SID.

When using Digital Research's RASM-86 assembler, this can be done with the Option $SO.
This option integrates the symbol table generated by RASM-86 in the object file:

Code Select Expand


rasm86 program.asm $LO
REM and to link it with DR's link86:
link86 program.obj


This can be also read in the manual "Programmers Utilities Guide For Concurrent DOS 86" on page 7-2

Code Select Expand


Symbol Table (SYM) File
Contains a list of symbols from the object files and
their offsets. This file is suitable for use with
SID-86.

Page 126:
https://bitsavers.org/pdf/digitalResearch/concurrent/1065-2043-001_Programmers_Utilities_Guide_For_Concurrent_DOS_86_Expanded_Memory_XM_Nov1986.pdf

On page 14-3 (page 213 in the PDF) of the same manual, there is an example, how a symbol file does look. In the manual, it is the mentioned output of the following command:

Code Select Expand


type typ.sym


I also have two questions:

1. If JWASM doesn't generate the symbol table, how is JWASM supposed to be able to include it in the object file, as Digital Research's LINK86 expects?

2. Can the Watcom Linker generate such a symbol file with this syntax?

Also i found another big problem or bug. SID86 can read and debug every *.EXE file out there, with the exception of those, i created with JWASM and the -mz parameter.

Should be no problem - just don't use the -mz option and let the DR tools do the link step.

Thanks, using Digital Resaerch's LINK86 worked, but i also tried to use WATCOM's WLINK, but with this, sid fails again with the same error "insufficient memory" as when using the JWASM -mz option.

3. Why is that so? Why does it matter, that the EXE file is created with different linkers when SID is just a normal debugger like debug? Shouldn't the linked EXE file be identical everywhere?

[fearless]

Could look at using SoftICE if running FreeDOS on a physical machine. If its emulated or in a container then SoftICE probably wont work, although I don't know for sure. Or DOSBOX which has an debugger available for it - from what I could glean from glancing at some stuff.

[_japheth]

1. If JWASM doesn't generate the symbol table, how is JWASM supposed to be able to include it in the object file, as Digital Research's LINK86 expects?

internally, jwasm creates a symbol table, of course, but it is written as a part of (codeview) debug info in the .OBJ file. I'm pretty sure that LINK86 has no clue how to handle that.

2. Can the Watcom Linker generate such a symbol file with this syntax?

AFAIK, wlink may be able to create debug info in 3 formats: codeview, dwarf and "watcom". I'm afraid none of those will be understood by SID86.

... using Digital Resaerch's LINK86 worked, but i also tried to use WATCOM's WLINK, but with this, sid fails again with the same error "insufficient memory" as when using the JWASM -mz option.
3. Why is that so? Why does it matter, that the EXE file is created with different linkers when SID is just a normal debugger like debug? Shouldn't the linked EXE file be identical everywhere?

The linker has full control onto what it emits. It may add info to the EXE header or even add code/data to the binary. While briefly testing LINK86 I found that it at least does the latter - and that's something assembly programmers don't like at all.

[bugthis]

1. If JWASM doesn't generate the symbol table, how is JWASM supposed to be able to include it in the object file, as Digital Research's LINK86 expects?

internally, jwasm creates a symbol table, of course, but it is written as a part of (codeview) debug info in the .OBJ file. I'm pretty sure that LINK86 has no clue how to handle that.

2. Can the Watcom Linker generate such a symbol file with this syntax?

AFAIK, wlink may be able to create debug info in 3 formats: codeview, dwarf and "watcom". I'm afraid none of those will be understood by SID86.

... using Digital Resaerch's LINK86 worked, but i also tried to use WATCOM's WLINK, but with this, sid fails again with the same error "insufficient memory" as when using the JWASM -mz option.
3. Why is that so? Why does it matter, that the EXE file is created with different linkers when SID is just a normal debugger like debug? Shouldn't the linked EXE file be identical everywhere?

The linker has full control onto what it emits. It may add info to the EXE header or even add code/data to the binary. While briefly testing LINK86 I found that it at least does the latter - and that's something assembly programmers don't like at all.

Thank you. Now i did a full test with several combinations of assembler and linkers.
Here's the result:

This project addressed the following questions:
1. Adaptation of the assembler source code file to the different assemblers.
2. Linking of the created object files with various linkers.
3. Test whether SID can debug the executable files.
3. Check if SID can debug this and if there is support for its symbol files.

Used software:

Code Select Expand

1. Digital Research (DR)
     RASM86.EXE  ; RASM86 Assembler
     LINK86.EXE  ; Digital Research Linker

2. INTEL
     ASM86.EXE   ; Intel Assembler
     LINK86.EXE  ; Intel Linker

3. JWASM
     JWASMR.EXE  ; Assembler
     WLINK.EXE   ; Watcom Linker

The table below shows the steps from right to left per row. Every row is one test with a specific combination of assembler and linker:
1. Create the object file using the mentioned assembler.
2. Linking the EXE file using the mentioned linker
3. If an EXE file could be created, the column EXE? is a YES,
   otherwise a NO.
4. Attempt to debug the EXE with SID
5. If a symbol file exists, test to use it. If it works, it is a YES.

Code Select Expand


Assembler | Linker | EXE?     | SID debugging? | SID symbol file?
----------|--------|----------|----------------|------------------
INTEL     | INTEL  | YES      | YES            | NO
INTEL     | DR     | YES      | NO 1)          | test not possible 5)
INTEL     | WATCOM | YES      | NO 1)          | test not possible 5)
DR        | DR     | YES      | YES            | YES
DR        | INTEL  | NO 2)    | not tested     | test not possible 5)
DR        | WATCOM | NO 3)    | not tested     | test not possible 5)
JWASMR    | WATCOM | YES      | NO 1)          | test not possible 5)
JWASMR    | DR     | YES      | YES            | Not really 4)
JWASMR    | INTEL  | YES      | YES            | NO

1) The EXE can't be loaded by SID. SID prints a "Insufficient memory" error message.
2) Invalid Object File. EXE can't be build.
   "Error 23: Bad Object File" (See also INTEL LINK86 manual page 161, Appendix D)
3) Invalid Object File. EXE can't be build.
   "Error! E3156: program.obj is an invalid object file."
4) A symbol table file *.SYM is created, but the file is garbage. This is also the case for the combination of DR's RASM86 + DR's LINK86 if the symbol table data is NOT embedded in the object file by RASM86. LINK86 doesn't seem to be able to create a working symbol file itself. RASM86 does provide a compiler option to embedded the symbol data into the object file. If the latter is done, there is a working SYM file that can be used by SID.
5) The test of loading a symbol file is not possible because of 1) or the EXE file cannot be created due to 2) and 3).

For 2) and 3) it seems to be, that Digital Research's RASM86 is adding some data to the object file, the linkers from Intel and Watcom can't understand.

[_japheth]

If you're curious enough, you can also try the Open Watcom debugger variant that I uploaded a few years ago. IIRC it's linked differently, using another extender than DOS4/GW ( which apparently has problems running on your system ).

In my tests this variant worked quite well for symbolic debugging both DOS real-mode and protected-mode programs.

https://github.com/Baron-von-Riedesel/HX-OpenWatcom-Debugger

[bugthis]

Now i tried LINK.EXE Version 2.0 from Microsoft with object code from DR and JWASMR assembler. I didn't test LINK.EXE with Objectcode from Intel's assembler.
Here's the updated table:

Code Select Expand

Assembler | Linker | EXE?     | SID debugging? | SID symbol file?
----------|--------|----------|----------------|------------------
INTEL     | INTEL  | YES      | YES            | NO
INTEL     | DR     | YES      | NO 1)          | test not possible 5)
INTEL     | WATCOM | YES      | NO 1)          | test not possible 5)
DR        | DR     | YES      | YES            | YES
DR        | INTEL  | NO 2)    | not tested     | test not possible 5)
DR        | WATCOM | NO 3)    | not tested     | test not possible 5)
DR        | MS     | YES      | YES But 6)     | NO
JWASMR    | WATCOM | YES      | NO 1)          | test not possible 5)
JWASMR    | DR     | YES      | YES            | Not really 4)
JWASMR    | INTEL  | YES      | YES            | NO
JWASMR    | MS     | YES      | YES            | NO


6) The resulting EXE file is garbage. Reason is, that LINK can't find a start address. The ASM code does have a START: label, but maybe there are other directives for RASM-86 which are necessary here?


EDIT:

I found the error that results in the error of the above 6).

RASM-86 requires also the mentioning of the START label at the end of the file after the END directive.
Example:

Code Select Expand


CODE CSEG
START: ..... ; Do some stuff

DOS:  MOV AH, 4CH
      INT 21h
end START


In the first try, i only had:

Code Select Expand


end

at the end, but not the start label.

Code Select Expand


end START


This is also mentioned in the RASM-86 manual "PROGRAMMER'S UTILITIES GUIDE FOR CONCURRENTTM DOS" in chapter "3.4.1 END Directive" at page 3-9.

With this fix, the new table looks like this:

Code Select Expand

Assembler | Linker | EXE?     | SID debugging? | SID symbol file?
----------|--------|----------|----------------|------------------
INTEL     | INTEL  | YES      | YES            | NO
INTEL     | DR     | YES      | NO 1)          | test not possible 5)
INTEL     | WATCOM | YES      | NO 1)          | test not possible 5)
DR        | DR     | YES      | YES            | YES
DR        | INTEL  | NO 2)    | not tested     | test not possible 5)
DR        | WATCOM | NO 3)    | not tested     | test not possible 5)
DR        | MS     | YES      | YES            | NO
JWASMR    | WATCOM | YES      | NO 1)          | test not possible 5)
JWASMR    | DR     | YES      | YES            | Not really 4)
JWASMR    | INTEL  | YES      | YES            | NO
JWASMR    | MS     | YES      | YES            | NO


However, I was not able to solve the problem with the Intel and Watcom linker with this fix when feeding these two with the object code that RASM-86 produced.
So this only works with the linker from Microsoft.