Introduction

The debugger is a monumental piece of work and one of the key enabling elements of making Cosmos unique. We have put an immense amount of work into the debugger and will continue to do so even though it takes a lot of time and detracts from resources that could be used to develop Cosmos kernel code. We do this because we believe that every hour put into the debugger will be returned in many times as many hours saved in kernel development. Some users have criticized this approach, but we stand firm in this belief and believe that Cosmos success rests heavily on the debugger and tight Visual Studio integration.

Obstacles

The Visual Studio debugger is only lightly documented (lightly might be a kind adjective). There are few if any samples and much of our progress is the result of sheer determination and experimentation.

Debug Stub

Communication

Communication currently uses the serial port. Other methods such as ethernet are planned in the future.

Data Files

All files are generated in the output directory. Usually this is bin/debug or bin/release.

CMAP file

The CMAP file maps assembler labels to physical memory locations. These labels include data (internal data, static fields, string literals) and code locations (method entry, points for each line of code, internal locations for exception handling).

The format is address, tab, label. A small excerpt is shown below.

00500000 DebugTraceMode
00500004 DebugStatus
00500008 DebugRunning

CXDB file

The CXDB contains a series of records with information about the methods. Each record contains:

LabelName (string) - Label as used in the ASM file to start the method. Each label emitted exists, that is many labels for each method.
Address (uint) - Address in physical memory.
StackDifference (int) - Size of stack. Arguments only?
AssemblyFile (string) - .NET assmebly containing IL source.
TypeToken (int) - .NET token for the containing type.
MethodToken (int) - .NET token for the method.
ILOffset (int) - Offset into the .NET assembly file where the method resides.
MethodName (string) - Name of the method. Not unique, as many labels exist per method.

Cosmos.Debug.Common.SourceInfos is a class for reading the CXDB file (and the PDB too). Currently the CXDB is handled by a dataset and saved as an XML file. However we never need the whole file in RAM, and in the future it should be changed to a database such as embedded Firebird (SQL Express has size limits we could forseeably encounter).

ASM file

The ASM file is actually generated by the Cosmos compiler, however in some cases it can be useful to the debugger. Most notably to display the assembly during interaction with GDB, or the given assembly for .NET code. Currently it is only used by the Cosmos GDB client, however there are plans to integrate assembly view and GDB debugging into Visual Studio.

PDB files

PDB files are debug files generated by the .NET compiler. (More info, although its summed up as "A .NET PDB only contains two pieces of information, the source file names and their lines and the local variable names. All the other information is already in the .NET metadata so there is no need to duplicate the same information in a PDB file. ")

PDB maps methods to source file locations. Given a method name, the source file and exact start and end locations can be determined. It also contains "SequencePoints" which map to individual source code lines in a source file.

LOG.html

If logging is enabled, a log file containting the scan tree used by the Cosmos compiler will be generated.