Soft Debugger Wire Format

Introduction

The Mono Soft Debugger (SDB) is a debugger implemented by the Mono runtime. The Mono runtime exposes an interface that debugger clients can use to debug a Mono application. Mono provides a convenience library in the form of the Mono.Debugger.Soft.dll that can be used to communicate with a running Mono process.

The Mono.Debugger.Soft.dll library uses a protocol over sockets to debug applications. The wire protocol is inspired by the JDWP (Java Debug Wire Protocol). Familiarity with that specification is a good read.

This document describes the wire protocol used between debugging clients and the Mono runtime.

Where possible, the corresponding protocol detail is linked to a function name and file location in Mono source code. These informations are based on Mono master version at revision f42ba4a168e7cb9b9486b8a96c53752e4467be8a.

Protocol details

Transport

Mono SDB protocol, just like its Java counterpart, was designed with no specific transport in mind. However, presently the public Mono SDB only has a TCP/IP transport available (under the transport name of dt_socket). Other transports can be plugged by modifying this interface.

Bootstraping a connection

To boostrap a connection, the client send handshake to the server (see debugger-agent.c:1034) in the form of the 13 ASCII characters string "DWP-Handshake" and wait for the server reply which consist of the exact same ASCII character sequence.

Packets

Just like JDWP, Mono SDB protocol is packet-based with two types of packet: command and reply. All fields in a packet is sent in big-endian format which is transparently handled in Mono source code with corresponding helper encode/decode functions.

Command packet are used by either side (client or server) to request information, act on the execution of the debugged program or to inform of some event. Replies is only sent in response to a command with information on the success/failure of the operation and any extra data depending on the command that triggered it.

Both type of packet contains a header. The header is always 11 bytes long. Their descriptions are given afterwards:

In Mono SDB source code, the command header is decoded in the server thread debugger_thread function at debugger-agent.c:7583.

Packet field details

Common fields

length : The total length in byte of the packet including header i.e. this value will be 11 if the packet only consists of header with no other data

id : Uniquely identify sent packet command/reply pair so that they can be asynchronously matched. This is in practise a simple monotonic integer counter. Note that client and server may use the same id value when sending their packets as the uniqueness property is only with respect to a specific source.

flags : At the moment this value is only used with a reply packet in which case its value is set to 0x80. A command packet should have this value set to 0.

Command specific fields

command set : This value allows grouping commands into similar blocks for quicker processing. The different command sets with their values are given below:

command : Tell what command this packet corresponds to. This value is relative to the previously defined command set so the values are reused across different command sets. Definition of each command is given in a later chapter.

Reply specific fields

error code : Define which error occured or if the command was successful. Error code definition is given below:

Data type marshalling

Most of the encoding function for these types are defined as buffer_add_* functions starting from debugger-agent.c:1429. Their counterpart are of the form decode_* starting from debugger-agent.c:1349.

A lot command returns or accepts fixed-length list of value. In these case, such a list is always prefixed with an int value giving its length followed by length element of the same type (which needs to be inferred from the context). When such a list is used the term "list" will be used. For clarification, an empty list is thus a single int value equals to 0.

Various enumeration value definition

For the record, the following C enumerations define the values used for flags, kind, ... parameters in some commands.

typedef enum {
    EVENT_KIND_VM_START = 0,
    EVENT_KIND_VM_DEATH = 1,
    EVENT_KIND_THREAD_START = 2,
    EVENT_KIND_THREAD_DEATH = 3,
    EVENT_KIND_APPDOMAIN_CREATE = 4,
    EVENT_KIND_APPDOMAIN_UNLOAD = 5,
    EVENT_KIND_METHOD_ENTRY = 6,
    EVENT_KIND_METHOD_EXIT = 7,
    EVENT_KIND_ASSEMBLY_LOAD = 8,
    EVENT_KIND_ASSEMBLY_UNLOAD = 9,
    EVENT_KIND_BREAKPOINT = 10,
    EVENT_KIND_STEP = 11,
    EVENT_KIND_TYPE_LOAD = 12,
    EVENT_KIND_EXCEPTION = 13,
    EVENT_KIND_KEEPALIVE = 14,
    EVENT_KIND_USER_BREAK = 15,
    EVENT_KIND_USER_LOG = 16
} EventKind;
 
typedef enum {
    SUSPEND_POLICY_NONE = 0,
    SUSPEND_POLICY_EVENT_THREAD = 1,
    SUSPEND_POLICY_ALL = 2
} SuspendPolicy;
 
typedef enum {
    MOD_KIND_COUNT = 1,
    MOD_KIND_THREAD_ONLY = 3,
    MOD_KIND_LOCATION_ONLY = 7,
    MOD_KIND_EXCEPTION_ONLY = 8,
    MOD_KIND_STEP = 10,
    MOD_KIND_ASSEMBLY_ONLY = 11,
    MOD_KIND_SOURCE_FILE_ONLY = 12,
    MOD_KIND_TYPE_NAME_ONLY = 13,
    MOD_KIND_NONE = 14
} ModifierKind;
 
typedef enum {
    STEP_DEPTH_INTO = 0,
    STEP_DEPTH_OVER = 1,
    STEP_DEPTH_OUT = 2
} StepDepth;
 
typedef enum {
    STEP_SIZE_MIN = 0,
    STEP_SIZE_LINE = 1
} StepSize;
 
typedef enum {
    TOKEN_TYPE_STRING = 0,
    TOKEN_TYPE_TYPE = 1,
    TOKEN_TYPE_FIELD = 2,
    TOKEN_TYPE_METHOD = 3,
    TOKEN_TYPE_UNKNOWN = 4
} DebuggerTokenType;
 
typedef enum {
    VALUE_TYPE_ID_NULL = 0xf0,
    VALUE_TYPE_ID_TYPE = 0xf1,
    VALUE_TYPE_ID_PARENT_VTYPE = 0xf2
} ValueTypeId;
 
typedef enum {
    FRAME_FLAG_DEBUGGER_INVOKE = 1,

    // Use to allow the debugger to display managed-to-native transitions in stack frames.
    FRAME_FLAG_NATIVE_TRANSITION = 2
} StackFrameFlags;
 
typedef enum {
    INVOKE_FLAG_DISABLE_BREAKPOINTS = 1,
    INVOKE_FLAG_SINGLE_THREADED = 2,

    // Allow for returning the changed value types after an invocation
    INVOKE_FLAG_RETURN_OUT_THIS = 4,

    // Allows the return of modified value types after invocation
    INVOKE_FLAG_RETURN_OUT_ARGS = 8,

    // Performs a virtual method invocation
    INVOKE_FLAG_VIRTUAL = 16
} InvokeFlags;

Command list

Types given in each command comments corresponds to the type described above. When there are additional arguments or multiple values in a command's reply, they are each time described in the order they appear or have to appear in the data part. Not also that there is no kind of separation sequence or added alignement padding between each value.

In all cases, if you ask for a command that doesn't exist, a reply will be sent with an error code of NOT_IMPLEMENTED.

Virtual machine commands

The main function handling these commands is vm_commands and is situated at debugger-agent.c:5671

Events commands

Events allows the debuggee to act on program execution (stepping) and also to set up things like breakpoints, watchpoints, exception catching, etc.

The main function handling these commands is event_commands and is situated at debugger-agent.c:5916

Each modifier has the first byte describing the modification it's carrying out and corresponding to the values found in the ModifierKind enumeration. The following table list the remaining body depending on the modification value.

Thread commands

Each command requires at least one ObjectID (of type id) parameter mapping to a thread instance before any additional parameter the command may require.

The main function handling these commands is thread_commands and is situated at debugger-agent.c:6991

AppDomains commands

The main function handling these commands is domain_commands and is situated at debugger-agent.c:6104

Assembly commands

Each command requires at least one AssemblyID (of type id) parameter before any additional parameter the command may require.

The main function handling these commands is assembly_commands and is situated at debugger-agent.c:6203

Module commands

The main function handling these commands is module_commands and is situated at debugger-agent.c:6295

Method commands

Each command requires at least one MethodID (of type id) parameter before any additional parameter the command may require.

The main functions handling these commands are method_commands and method_commands_internal and are situated at debugger-agent.c:6968 and debugger-agent.c:6968 respectively.

Type commands

Each command requires at least one TypeID (of type id) parameter before any additional parameter the command may require.

The main functions handling these commands are type_commands and type_commands_internal and are situated at debugger-agent.c:6726 and debugger-agent.c:6403 respectively.

Byval flags is an indication of the type attribute for a parameter when it's passed by value. A description of these flags follows:

Custom attribute definition is as follows: MethodID of the attribute ctor, a list of variant objects representing the typed arguments of the attribute prepended by a length attribute (int) and another list representing named arguments of which elements are either tuple of the constant 0x53 followed by a variant value (in case the named argument is a field) or a triplet of the constant 0x54 followed by a PropertyID followed by a variant value (in case the named argument is a property). In both list case, an empty list is simply one int of value 0.

Stackframe commands

Each command requires at least one ObjectID (of type id) parameter mapping to a System.Threading.Thread instance and a FrameID (of type id) before any additional parameter the command may require.

The main function handling these commands is frame_commands and is situated at debugger-agent.c:7082

Array commands

Each command requires at least one ObjectID (of type id) parameter mapping to a System.Array instance before any additional parameter the command may require.

The main function handling these commands is vm_commands and is situated at debugger-agent.c:5671

String commands

Each command requires at least one ObjectID (of type id) parameter mapping to a System.String instance before any additional parameter the command may require.

The main function handling these commands is string_commands and is situated at debugger-agent.c:7293

Object commands

Each command requires at least one ObjectID (of type id) parameter before any additional parameter the command may require.

The main function handling these commands is object_commands and is situated at debugger-agent.c:7318

Composite commands

Differences with JDWP

• Handshake ASCII sequence is DWP-Handshake instead of JDWP-Handshake
• Some new Mono specific command set such as AppDomain, Assembly or Module and removal/renaming of some Java specific set such as InterfaceType, ThreadGroupReference, ClassLoaderReference, etc.
• Mono SDB protocol has its own specific ID types related to the new command sets.
• SDB protocol has less error code although some are Mono-specific like "No Invocation", "Absent Informations" and "No seq point at IL offset" codes.