GoBug as a symbolic debugger
What are symbols?
What is a symbolic debugger?
Viewing the symbols whilst debugging
How GoBug knows the symbols
Embedded versus separate files
Symbols both in exe files and Dlls
The same-name problem - exe file and Dll having the same name
   dbg files
   map files
   pdb files

Search procedures for the symbol files
   dbg files
   map files
   pdb files

What if symbols are not found?
Adding embedded symbol information with various linkers
Making a dbg file
Making a map file
Making a pdb file

What are symbols?
Symbols are non-local data and code labels in your source code. A data label relates to an address in the data section and is given when the data is declared. For example,
SmallBuffer DD 20h DUP 0
creates a buffer of 32 dwords initialised to zero, with a label "SmallBuffer". This buffer can then be referred to as "SmallBuffer" throughout your source code. A code label relates to an address in the code section and may be given as follows:-
Procedure66:
or
Procedure 66 PROC
This will establish the label "Procedure66" in the code section. The procedure can then be called using the code
CALL Procedure66
A data or code label does not have to be at the start of the area of code or data. You can divide data areas so that the label refers only to part of it, and a code label can be on any line in the code section.

What is a symbolic debugger?
A symbolic debugger knows the addresses of the symbols and is able to display them in the disassembly. Here GoBug shows in the disassembly (in the code pane) the code label at the beginning of the procedure, and a second label a couple of lines below. Data references in the disassembly are shown by data label. GoBug can display Unicode symbols. The "Go" tools allow you to use Unicode code and data labels in your application, and GoBug will display these properly. See (for example) displaying Unicode symbols in the codepane. A symbolic debugger may also use the code labels to allow the user to establish breakpoints, and may display the contents of memory by reference to data labels. See code, data and symbol inspectors.

Viewing the symbols whilst debugging
GoBug allows you to view the symbols themselves and also code and data represented by the symbols

How GoBug knows the symbols.
The assembler puts labels, other than local labels, in the object file. The linker, if asked, will sort the labels in the object files and put them in the executable file (or in a separate file) in a way in which GoBug can read. If there is more than one source of symbol information GoBug will use the source it prefers. The order of preference is:-

Embedded versus separate files
The symbolic debug information can either be embedded in the executable or in a separate file. There are advantages and disadvantages in these two methods.

In light of the above I would recommend to assembler programmers using either embedded debug information or a dbg file.

Symbols both in exe files and Dlls
GoBug will look for symbols both in the main executable file, but also in any Dlls which are loaded by the debuggee. Such Dlls might include a Dll which is part of the debuggee itself or a system Dll. A typical Windows application on start up will load several system Dlls. Unless the debug versions of these Dlls are loaded on your system, you will not be able to view the symbols from these system Dlls.

The same-name problem - exe and Dll having the same name.
A Dll used by your application may have the same name as the executable for example
LotteryForecaster.exe
LotteryForecaster.dll

This isn't a problem for the debugger when debug information is embedded in the executable file itself, since then there is no room for confusion as to the source of symbol information. But when using separate symbol files, such as dbg, pdb or map files, you must provide some way for the debugger to know which symbol file refers to which executable.
An obvious solution is to change the name of the Dll during development so that each executable file and its corresponding symbol file has a unique name.
However there are other solutions depending on whether you are using dbg, pdb or map files.

dbg files with same name
When using dbg files, the tools normally ensure that the dbg files are placed in an "\exe" or "\dll" subdirectory of the file being made (depending on whether it's an exe or a Dll). This fact may then be recorded in the "MISC" debug directory in the executable [note it seems this does not happen automatically when the dbg file is made using the SplitSymbols API, nor using the rebase program, but this does not matter to GoBug]. GoBug will look for the symbol file in the \exe or \dll subdirectory if it exists. You can also place the dbg files in "\symbols\exe" or "symbols\dll" subdirectories, being subdirectories of the directory of which \bin is a subdirectory. See dbg file search procedures for an explanation of this.
Your linker may also permit you to specify a name for the dbg file, so that you can distinguish between the dbg file for the exe and the dbg file for the Dll. The correct name for the dbg file is recorded in the "MISC" debug directory of the executable. GoBug will look for the filename specified.

map files with same name
At link time, you can normally specify the path of the map file. Ensure it is placed in an "\exe" or "\dll" subdirectory of the file being made, depending on whether it's an an exe or a Dll. GoBug will look in the subdirectory to suit whether the executable being loaded is an exe or a Dll. You can also place the map files in "\symbols\exe" or "symbols\dll" subdirectories, being subdirectories of the directory of which \bin is a subdirectory. See map file search procedures for an explanation of this.

pdb files with same name
At link time you can specify the path and name of the pdb file and this is written into the executable itself. GoBug looks for this path and name and searches for the appropriate pdb file holding symbols for the executable concerned. Alternatively you can specify that the pdb file goes to the \exe or \dll (or \symbols\exe or \symbols\dll subdirectories as appropriate see pdb file search procedures for an explanation of this).

Search procedures for symbol files
dbg file search procedures
When looking for a dbg file, if the filename of the dbg file is given in the "MISC" debug directory then that file is looked for. If not, GoBug looks for a dbg file with the same name as the executable. The following search sequence is used:

If the dbg file contains symbols it also contains the name of the file to which the symbols apply. GoBug checks that this matches the correct file before using the dbg file.
If the dbg file contains symbols GoBug also checks the file timedate of the dbg file. This is because when the dbg file is made, the executable is normally written to at the same time so the file timedate should be the same or very near. If the timedate is not near the timedate of the executable the dbg file will not be used and GoBug assumes it is the wrong file.

map file search procedures
When looking for a map file, GoBug always looks for a map file with the same name as the executable. The following search sequence is used:

GoBug also checks the file timedate of the map file. This is because the map file is made at the same time as the executable. If the timedate is not near the timedate of the executable, and it is the main executable being loaded and not a Dll, you will prompted and asked whether you want to use the map file (note that the date and time given to you will be adjusted to allow for the current daylight saving time setting on your computer).

pdb file search procedures
When looking for a pdb file, the filename of the pdb file to look for is either that given in the "CODEVIEW" debug directory, or in a dbg file whose name is given in the "MISC" debug directory of the executable. If neither of these apply GoBug looks for a pdb file with the same name as the executable. The following search sequence is used:

GoBug also checks the timedate (or in later files a machine-specific Globally Unique Identifier) and "age" codes within the pdb file with those contained in the "CODEVIEW" debug directory of the executable. The age code identifies how many times the pdb file has been updated. Both these values should match and if they do not the pdb file is ignored.
GoBug never writes the path/filename of the pdb file or the dbg file in the executable itself, as is done by the VC++ debugger.

What if symbols are not found?
If GoBug fails to find symbols for the debuggee's main exe file it will show a warning message box. GoBug will work perfectly well without symbols. However, the symbols will not appear on disassembly, you will not be able to create breakpoints or inspect data based on symbols, nor will you be able to create a symbol inspector. If GoBug fails to find symbols in a Dll, whether the debuggee's own Dlls or a system Dll, an error message box will not appear. If you want to check in which loaded files symbols were found click on the menu item "inspect, information about the debuggee".

Adding embedded symbol information with various linkers
Using my GoLink, use the switch "/debug coff". The format is COFF.
If you are using Anthony Williams' ALINK linker, use the switch "-debug". The format is CodeView.
With older Microsoft linkers you can use the switch "/DEBUG:FULL" and then "/DEBUGTYPE:COFF" or "/DEBUGTYPE:CV" to add embedded COFF or CodeView debug information to the executable file respectively.
The latest Microsoft linker does not embed CodeView symbol information. Instead the symbol information is put into a separate Program Database (pdb) file which can be read by GoBug. See making a pdb file.
However the switch /DEBUGTYPE:COFF does still embed COFF information in the executable on the latest Microsoft linker, as does /DEBUGTYPE:BOTH. If you wish you can then remove the symbols from the executable by making a dbg file, and GoBug will read the symbols from the dbg file.
If you are using Borland's TLINK, use the switch /v to add debug information to the executable. GoBug can read the FB09 or FB0A format symbols which are then emitted. Later versions of TLINK may use new formats. Please send the executable file to me if you have problems.

Making a dbg file
Using my GoLink, use the switch "/debug dbg". This will make a dbg file in an \exe or \dll directory as appropriate.
Another way to make a dbg file is to make the executable with embedded COFF information and then run Microsoft's rebase.exe with the appropriate switch (try the command line "REBASE -x Drive:\Path -b 0x400000 FileName.Ext" where FileName.Ext is the executable concerned; rebase will create a dbg file in a sub-directory in Drive:\Path called exe or dll depending on the extension of the filename). Alternatively you can use the SplitSymbols API which appears to do the same job.

Making a map file
With the Microsoft linker you can use the switch "/MAP" to create a map file which can be read by GoBug. If you are using Borland's TLINK, use the switch /m to create a mapfile which can be read by GoBug. Anthony Williams' ALINK linker does also make a map file using the "-m" switch, but it is not in a format which GoBug can use. It can, however, be used as a manual method of identifying the addresses of data and code symbols (where GoBug runs without loaded symbols).

Making a pdb file.
The latest Microsoft linkers create a Program Database (pdb) file when linking if the /DEBUG option, or /DEBUG:FULL option is chosen. The pdb file contains information about the creation of the executable, and also contain the symbol information in the latest CodeView format. The executable contains a path and filename for the pdb file on the local machine, together with an identification code, so that the correct pdb file can be located. Neither the format of the pdb file itself nor the latest CodeView format are documented. However GoBug does read these files as they currently known - that is, it reads the "JG" and "DS" (also known as "RSDS") formats.
If the above switches are used, the REBASE utility now creates a dbg file which merely contains a path to, and identifier of, the pdb file.