v1.64.0

License-code.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

changelog.md

@@ -6,6 +6,11 @@ sectionid: changelog
 
 #### All notable changes to the specification will be documented in this file.
 
+* 1.64.x
+  * Clarify that the `offset` in the `InstructionBreakpoint` is given in bytes
+  * Add a `presentationHint` to the `DisassembledInstruction`
+  * Add a `reason` to the `Breakpoint` to indicate why verification may have failed
+
 * 1.63.x
   * Add `memoryReference` support to the `SetVariableResponse`/`SetExpressionResponse`
   * Fix a typo in the description of `BreakpointLocationsArguments`

debugAdapterProtocol.json

@@ -3765,7 +3765,7 @@
 				},
 				"offset": {
 					"type": "integer",
-					"description": "The offset from the instruction reference.\nThis can be negative."
+					"description": "The offset from the instruction reference in bytes.\nThis can be negative."
 				},
 				"condition": {
 					"type": "string",
@@ -3822,6 +3822,11 @@
 				"offset": {
 					"type": "integer",
 					"description": "The offset from the instruction reference.\nThis can be negative."
+				},
+				"reason": {
+					"type": "string",
+					"description": "A machine-readable explanation of why a breakpoint may not be verified. If a breakpoint is verified or a specific reason is not known, the adapter should omit this property. Possible values include:\n\n- `pending`: Indicates a breakpoint might be verified in the future, but the adapter cannot verify it in the current state.\n - `failed`: Indicates a breakpoint was not able to be verified, and the adapter does not believe it can be verified without intervention.",
+					"enum": [ "pending", "failed" ]
 				}
 			},
 			"required": [ "verified" ]
@@ -4159,6 +4164,11 @@
 				"endColumn": {
 					"type": "integer",
 					"description": "The end column of the range that corresponds to this instruction, if any."
+				},
+				"presentationHint": {
+					"type": "string",
+					"description": "A hint for how to present the instruction in the UI.\n\nA value of `invalid` may be used to indicate this instruction is 'filler' and cannot be reached by the program. For example, unreadable memory addresses may be presented is 'invalid.'",
+					"enum": [ "normal", "invalid" ]
 				}
 			},
 			"required": [ "address", "instruction" ]

index.html

@@ -86,7 +86,7 @@ <h1 class="text-center"><i class="fa fa-cogs" aria-hidden="true"></i></h1>
             <h1 class="text-center"><i class="fas fa-book" aria-hidden="true"></i></h1>
             <a href='{{ "/specification" | prepend: site.baseurl }}'><h3 class="text-center">Specification</h3></a>
             <p>
-                The latest version of the protocol specification is version 1.63.0.
+                The latest version of the protocol specification is version 1.64.0.
             </p>
             <p>
                 <a href='{{ "/changelog" | prepend: site.baseurl }}'>Change History</a>

spec-generator/generator.ts

@@ -277,7 +277,7 @@ function comment(c: P.Commentable): string {
 function breakLines(s: string, breakPat: string, lineStart: string): string {
 	s = s.replace(/\n/g, `${breakPat}@@@${breakPat}`);	// preserve newlines as a special word
 	let ind = `${indent()}${lineStart}`;
-	let result = [];
+	const result: string[] = [];
 	const words= s.split(breakPat);
 	let line = '';
 	for (let w of words) {
@@ -303,7 +303,7 @@ function breakLines(s: string, breakPat: string, lineStart: string): string {
 	if (line.length > 0) {
 		result.push(line);
 	}
-	return result.join(`\n${ind}`);
+	return result.map(l => l.trimEnd()).join(`\n${ind}`);
 }
 
 function openBlock(str: string, openChar?: string, indent?: boolean): string {

specification.md

@@ -114,7 +114,7 @@ interface Response extends ProtocolMessage {
    * This raw error might be interpreted by the client and is not shown in the
    * UI.
    * Some predefined values exist.
-   * Values: 
+   * Values:
    * 'cancelled': the request was cancelled.
    * 'notStopped': the request may be retried once the adapter is in a 'stopped'
    * state.
@@ -393,7 +393,7 @@ interface OutputEvent extends Event {
     /**
      * The output category. If not specified or if the category is not
      * understood by the client, `console` is assumed.
-     * Values: 
+     * Values:
      * 'console': Show the output in the client's default message UI, e.g. a
      * 'debug console'. This category should only be used for informational
      * output from the debugger (as opposed to the debuggee).
@@ -418,7 +418,7 @@ interface OutputEvent extends Event {
 
     /**
      * Support for keeping an output log organized by grouping related messages.
-     * Values: 
+     * Values:
      * 'start': Start a new group in expanded mode. Subsequent output events are
      * members of the group and should be shown indented.
      * The `output` attribute becomes the name of the group and is not indented.
@@ -568,7 +568,7 @@ interface ProcessEvent extends Event {
 
     /**
      * Describes how the debug engine started debugging this process.
-     * Values: 
+     * Values:
      * 'launch': Process was launched under the debugger.
      * 'attach': Debugger attached to an existing process.
      * 'attachForSuspendedLaunch': A project launcher component has launched a
@@ -2639,7 +2639,7 @@ interface EvaluateArguments {
 
   /**
    * The context in which the evaluate request is used.
-   * Values: 
+   * Values:
    * 'watch': evaluate is called from a watch view context.
    * 'repl': evaluate is called from a REPL context.
    * 'hover': evaluate is called to generate the debug hover contents.
@@ -3855,7 +3855,7 @@ interface Scope {
   /**
    * A hint for how to present this scope in the UI. If this attribute is
    * missing, the scope is shown with a generic UI.
-   * Values: 
+   * Values:
    * 'arguments': Scope contains method arguments.
    * 'locals': Scope contains local variables.
    * 'registers': Scope contains registers. Only a single `registers` scope
@@ -4019,7 +4019,7 @@ interface VariablePresentationHint {
   /**
    * The kind of variable. Before introducing additional values, try to use the
    * listed values.
-   * Values: 
+   * Values:
    * 'property': Indicates that the object is a property.
    * 'method': Indicates that the object is a method.
    * 'class': Indicates that the object is a class.
@@ -4044,7 +4044,7 @@ interface VariablePresentationHint {
   /**
    * Set of attributes represented as an array of strings. Before introducing
    * additional values, try to use the listed values.
-   * Values: 
+   * Values:
    * 'static': Indicates that the object is static.
    * 'constant': Indicates that the object is a constant.
    * 'readOnly': Indicates that the object is read only.
@@ -4248,7 +4248,7 @@ interface InstructionBreakpoint {
   instructionReference: string;
 
   /**
-   * The offset from the instruction reference.
+   * The offset from the instruction reference in bytes.
    * This can be negative.
    */
   offset?: number;
@@ -4336,6 +4336,19 @@ interface Breakpoint {
    * This can be negative.
    */
   offset?: number;
+
+  /**
+   * A machine-readable explanation of why a breakpoint may not be verified. If
+   * a breakpoint is verified or a specific reason is not known, the adapter
+   * should omit this property. Possible values include:
+   * 
+   * - `pending`: Indicates a breakpoint might be verified in the future, but
+   * the adapter cannot verify it in the current state.
+   * - `failed`: Indicates a breakpoint was not able to be verified, and the
+   * adapter does not believe it can be verified without intervention.
+   * Values: 'pending', 'failed'
+   */
+  reason?: 'pending' | 'failed';
 }
 ```
 
@@ -4786,6 +4799,16 @@ interface DisassembledInstruction {
    * The end column of the range that corresponds to this instruction, if any.
    */
   endColumn?: number;
+
+  /**
+   * A hint for how to present the instruction in the UI.
+   * 
+   * A value of `invalid` may be used to indicate this instruction is 'filler'
+   * and cannot be reached by the program. For example, unreadable memory
+   * addresses may be presented is 'invalid.'
+   * Values: 'normal', 'invalid'
+   */
+  presentationHint?: 'normal' | 'invalid';
 }
 ```