add support for stepping granularities

Author: weinand

debugProtocol.json

@@ -181,7 +181,7 @@
 		"StoppedEvent": {
 			"allOf": [ { "$ref": "#/definitions/Event" }, {
 				"type": "object",
-				"description": "The event indicates that the execution of the debuggee has stopped due to some condition.\nThis can be caused by a break point previously set, a stepping action has completed, by executing a debugger statement etc.",
+				"description": "The event indicates that the execution of the debuggee has stopped due to some condition.\nThis can be caused by a break point previously set, a stepping request has completed, by executing a debugger statement etc.",
 				"properties": {
 					"event": {
 						"type": "string",
@@ -1425,6 +1425,10 @@
 				"threadId": {
 					"type": "integer",
 					"description": "Execute 'next' for this thread."
+				},
+				"granularity": {
+					"$ref": "#/definitions/SteppingGranularity",
+					"description": "Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed."
 				}
 			},
 			"required": [ "threadId" ]
@@ -1463,6 +1467,10 @@
 				"targetId": {
 					"type": "integer",
 					"description": "Optional id of the target to step into."
+				},
+				"granularity": {
+					"$ref": "#/definitions/SteppingGranularity",
+					"description": "Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed."
 				}
 			},
 			"required": [ "threadId" ]
@@ -1497,6 +1505,10 @@
 				"threadId": {
 					"type": "integer",
 					"description": "Execute 'stepOut' for this thread."
+				},
+				"granularity": {
+					"$ref": "#/definitions/SteppingGranularity",
+					"description": "Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed."
 				}
 			},
 			"required": [ "threadId" ]
@@ -1531,6 +1543,10 @@
 				"threadId": {
 					"type": "integer",
 					"description": "Execute 'stepBack' for this thread."
+				},
+				"granularity": {
+					"$ref": "#/definitions/SteppingGranularity",
+					"description": "Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed."
 				}
 			},
 			"required": [ "threadId" ]
@@ -2840,6 +2856,10 @@
 				"supportsClipboardContext": {
 					"type": "boolean",
 					"description": "The debug adapter supports the 'clipboard' context value in the 'evaluate' request."
+				},
+				"supportsSteppingGranularity": {
+					"type": "boolean",
+					"description": "The debug adapter supports stepping granularities (argument 'granularity') for the stepping requests."
 				}
 			}
 		},
@@ -3397,6 +3417,17 @@
 			"required": [ "verified" ]
 		},
 
+		"SteppingGranularity": {
+			"type": "string",
+			"description": "The granularity of one 'step' in the stepping requests 'next', 'stepIn', 'stepOut', and 'stepBack'.",
+			"enum": [ "statement", "line", "instruction" ],
+			"enumDescriptions": [
+				"The step should allow the program to run until the current statement has finished executing.\nThe meaning of a statement is determined by the adapter and it may be considered equivalent to a line.\nFor example 'for(int i = 0; i < 10; i++) could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.",
+				"The step should allow the program to run until the current source line has executed.",
+				"The step should allow one instruction to execute (e.g. one x86 instruction)."
+			]
+		},
+
 		"StepInTarget": {
 			"type": "object",
 			"description": "A StepInTarget can be used in the 'stepIn' request and determines into which single target the stepIn request should step.",

protocol/src/debugProtocol.ts

@@ -121,7 +121,7 @@ export module DebugProtocol {
 
 	/** Event message for 'stopped' event type.
 		The event indicates that the execution of the debuggee has stopped due to some condition.
-		This can be caused by a break point previously set, a stepping action has completed, by executing a debugger statement etc.
+		This can be caused by a break point previously set, a stepping request has completed, by executing a debugger statement etc.
 	*/
 	export interface StoppedEvent extends Event {
 		// event: 'stopped';
@@ -805,6 +805,8 @@ export module DebugProtocol {
 	export interface NextArguments {
 		/** Execute 'next' for this thread. */
 		threadId: number;
+		/** Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed. */
+		granularity?: SteppingGranularity;
 	}
 
 	/** Response to 'next' request. This is just an acknowledgement, so no body field is required. */
@@ -830,6 +832,8 @@ export module DebugProtocol {
 		threadId: number;
 		/** Optional id of the target to step into. */
 		targetId?: number;
+		/** Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed. */
+		granularity?: SteppingGranularity;
 	}
 
 	/** Response to 'stepIn' request. This is just an acknowledgement, so no body field is required. */
@@ -849,6 +853,8 @@ export module DebugProtocol {
 	export interface StepOutArguments {
 		/** Execute 'stepOut' for this thread. */
 		threadId: number;
+		/** Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed. */
+		granularity?: SteppingGranularity;
 	}
 
 	/** Response to 'stepOut' request. This is just an acknowledgement, so no body field is required. */
@@ -869,6 +875,8 @@ export module DebugProtocol {
 	export interface StepBackArguments {
 		/** Execute 'stepBack' for this thread. */
 		threadId: number;
+		/** Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed. */
+		granularity?: SteppingGranularity;
 	}
 
 	/** Response to 'stepBack' request. This is just an acknowledgement, so no body field is required. */
@@ -1561,6 +1569,8 @@ export module DebugProtocol {
 		supportsBreakpointLocationsRequest?: boolean;
 		/** The debug adapter supports the 'clipboard' context value in the 'evaluate' request. */
 		supportsClipboardContext?: boolean;
+		/** The debug adapter supports stepping granularities (argument 'granularity') for the stepping requests. */
+		supportsSteppingGranularity?: boolean;
 	}
 
 	/** An ExceptionBreakpointsFilter is shown in the UI as an option for configuring how exceptions are dealt with. */
@@ -1921,6 +1931,15 @@ export module DebugProtocol {
 		endColumn?: number;
 	}
 
+	/** The granularity of one 'step' in the stepping requests 'next', 'stepIn', 'stepOut', and 'stepBack'.
+		'statement': The step should allow the program to run until the current statement has finished executing.
+		The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
+		For example 'for(int i = 0; i < 10; i++) could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.
+		'line': The step should allow the program to run until the current source line has executed.
+		'instruction': The step should allow one instruction to execute (e.g. one x86 instruction).
+	*/
+	export type SteppingGranularity = 'statement' | 'line' | 'instruction';
+
 	/** A StepInTarget can be used in the 'stepIn' request and determines into which single target the stepIn request should step. */
 	export interface StepInTarget {
 		/** Unique identifier for a stepIn target. */