add memory event; fixes #194

_data/specification-toc.yml

@@ -32,6 +32,8 @@
       anchor: Events_Invalidated
     - title: LoadedSource
       anchor: Events_LoadedSource
+    - title: Memory
+      anchor: Events_Memory
     - title: Module
       anchor: Events_Module
     - title: Output

changelog.md

@@ -6,14 +6,17 @@ sectionid: changelog
 
 #### All notable changes to the specification will be documented in this file.
 
+* 1.49.x:
+  * Add `memory` event and a corresponding **client** capability `supportsMemoryEvent`.
+
 * 1.48.x:
   * Add guidance for the case that a debug adapter implements both `setVariable` and `setExpression` and clients need to decide which request to use.
   * Add `writeMemory` request and a corresponding `supportsWriteMemoryRequest` capability.
 
 * 1.47.x:
   * The `setExceptionBreakpoints` can now optionally return an array of `Breakpoint`s as the other `setXxxxBreakpoints` do. This allows clients to show validation error messages for individual exception breakpoints or filters.
   * The `restart` request got a new optional parameter `arguments` where a client can pass the latest version of a launch or attach configuration.
-  * Adds a new optional argument `suspendDebuggee` to the `disconnect` request. If a debug adapter has opted into this feature with the 'supportSuspendDebuggee' capability, a client can use this to control whether the debuggee should be suspended when the debugger is disconnected.
+  * Adds a new optional argument `suspendDebuggee` to the `disconnect` request. If a debug adapter has opted into this feature with the `supportSuspendDebuggee` capability, a client can use this to control whether the debuggee should be suspended when the debugger is disconnected.
 
 * 1.46.x:
   * Add an optional attribute `hitBreakpointIds` to the `stopped` event which contains the ids of the breakpoints that triggered the event.

debugAdapterProtocol.json

@@ -691,6 +691,38 @@
 			}]
 		},
 
+		"MemoryEvent": {
+			"allOf": [ { "$ref": "#/definitions/Event" }, {
+				"type": "object",
+				"description": "This event indicates that some memory range has been updated. It should only be sent if the debug adapter has received a value true for the `supportsMemoryEvent` capability of the `initialize` request.\nClients typically react to the event by re-issuing a `readMemory` request if they show the memory identified by the `memoryReference` and if the updated memory range overlaps the displayed range. Clients should not make assumptions how individual memory references relate to each other, so they should not assume that they are part of a single continuous address range and might overlap.\nDebug adapters can use this event to indicate that the contents of a memory range has changed due to some other DAP request like `setVariable` or `setExpression`. Debug adapters are not expected to emit this event for each and every memory change of a running program, because that information is typically not available from debuggers and it would flood clients with too many events.",
+				"properties": {
+					"event": {
+						"type": "string",
+						"enum": [ "memory" ]
+					},
+					"body": {
+						"type": "object",
+						"properties": {
+							"memoryReference": {
+								"type": "string",
+								"description": "Memory reference of a memory range that has been updated."
+							},
+							"offset": {
+								"type": "integer",
+								"description": "Starting offset in bytes where memory has been updated. Can be negative."
+							},
+							"count": {
+								"type": "integer",
+								"description": "Number of bytes updated."
+							}
+						},
+						"required": [ "memoryReference", "offset", "count" ]
+					}
+				},
+				"required": [ "event", "body" ]
+			}]
+		},
+
 		"RunInTerminalRequest": {
 			"allOf": [ { "$ref": "#/definitions/Request" }, {
 				"type": "object",
@@ -839,6 +871,10 @@
 				"supportsInvalidatedEvent": {
 					"type": "boolean",
 					"description": "Client supports the invalidated event."
+				},
+				"supportsMemoryEvent": {
+					"type": "boolean",
+					"description": "Client supports the memory event."
 				}
 			},
 			"required": [ "adapterID" ]

specification.md

@@ -746,6 +746,37 @@ interface InvalidatedEvent extends Event {
 }
 ```
 
+### <a name="Events_Memory" class="anchor"></a>:arrow_left: Memory Event
+
+This event indicates that some memory range has been updated. It should only be sent if the debug adapter has received a value true for the `supportsMemoryEvent` capability of the `initialize` request.
+
+Clients typically react to the event by re-issuing a `readMemory` request if they show the memory identified by the `memoryReference` and if the updated memory range overlaps the displayed range. Clients should not make assumptions how individual memory references relate to each other, so they should not assume that they are part of a single continuous address range and might overlap.
+
+Debug adapters can use this event to indicate that the contents of a memory range has changed due to some other DAP request like `setVariable` or `setExpression`. Debug adapters are not expected to emit this event for each and every memory change of a running program, because that information is typically not available from debuggers and it would flood clients with too many events.
+
+```typescript
+interface MemoryEvent extends Event {
+  event: 'memory';
+
+  body: {
+    /**
+     * Memory reference of a memory range that has been updated.
+     */
+    memoryReference: string;
+
+    /**
+     * Starting offset in bytes where memory has been updated. Can be negative.
+     */
+    offset: number;
+
+    /**
+     * Number of bytes updated.
+     */
+    count: number;
+  };
+}
+```
+
 ## <a name="Reverse_Requests" class="anchor"></a>Reverse Requests
 
 ### <a name="Reverse_Requests_RunInTerminal" class="anchor"></a>:arrow_right_hook: RunInTerminal Request
@@ -914,6 +945,11 @@ interface InitializeRequestArguments {
    * Client supports the invalidated event.
    */
   supportsInvalidatedEvent?: boolean;
+
+  /**
+   * Client supports the memory event.
+   */
+  supportsMemoryEvent?: boolean;
 }
 ```