diff --git a/_data/specification-toc.yml b/_data/specification-toc.yml index 30f7196..39f3d53 100644 --- a/_data/specification-toc.yml +++ b/_data/specification-toc.yml @@ -65,6 +65,8 @@ anchor: Requests_ConfigurationDone - title: Continue anchor: Requests_Continue + - title: DataAddressBreakpointInfo + anchor: Requests_DataAddressBreakpointInfo - title: DataBreakpointInfo anchor: Requests_DataBreakpointInfo - title: Disassemble diff --git a/changelog.md b/changelog.md index 5372626..d8c0609 100644 --- a/changelog.md +++ b/changelog.md @@ -7,6 +7,7 @@ sectionid: changelog #### All notable changes to the specification will be documented in this file. * 1.65.x + * Add a new `DataAddressBreakpointInfo` request to allow setting data breakpoints based on memory address * Clarify handling of multiple filters in the `SetExceptionBreakpoints` request * 1.64.x diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index 6bb7669..ea880ce 100644 --- a/debugAdapterProtocol.json +++ b/debugAdapterProtocol.json @@ -3059,6 +3059,72 @@ }] }, + "DataAddressBreakpointInfoRequest": { + "allOf": [ { "$ref": "#/definitions/Request" }, { + "type": "object", + "description": "Obtains information on a possible data breakpoint that could be set on a memory address or memory address range.\n\nClients should only call this request if the corresponding capability `supportsDataAddressInfo` is true.", + "properties": { + "command": { + "type": "string", + "enum": [ "DataAddressBreakpointInfo" ] + }, + "arguments": { + "$ref": "#/definitions/DataAddressBreakpointInfoArguments" + } + }, + "required": [ "command", "arguments" ] + }] + }, + "DataAddressBreakpointInfoArguments": { + "type": "object", + "description": "Arguments for `dataAddressBreakpointInfo` request.", + "properties": { + "address": { + "type": "string", + "description": "The address of the data for which to obtain breakpoint information.\nTreated as a hex value if prefixed with `0x`, or as a decimal value otherwise." + }, + "bytes": { + "type": "string", + "description": "If passed, requests breakpoint information for an exclusive byte range rather than a single address. The range extends the given number of `bytes` from the start `address`.\nTreated as a hex value if prefixed with `0x`, or as a decimal value otherwise." + } + }, + "required": [ "threadId" ] + }, + "DataAddressBreakpointInfoResponse": { + "allOf": [ { "$ref": "#/definitions/Response" }, { + "type": "object", + "description": "Response to `dataAddressBreakpointInfo` request.", + "properties": { + "body": { + "type": "object", + "properties": { + "dataId": { + "type": [ "string", "null" ], + "description": "An identifier for the data on which a data breakpoint can be registered with the `setDataBreakpoints` request or null if no data breakpoint is available. If a `variablesReference` or `frameId` is passed, the `dataId` is valid in the current suspended state, otherwise it's valid indefinitely. See 'Lifetime of Object References' in the Overview section for details. Breakpoints set using the `dataId` in the `setDataBreakpoints` request may outlive the lifetime of the associated `dataId`." + }, + "description": { + "type": "string", + "description": "UI string that describes on what data the breakpoint is set on or why a data breakpoint is not available." + }, + "accessTypes": { + "type": "array", + "items": { + "$ref": "#/definitions/DataBreakpointAccessType" + }, + "description": "Attribute lists the available access types for a potential data breakpoint. A UI client could surface this information." + }, + "canPersist": { + "type": "boolean", + "description": "Attribute indicates that a potential data breakpoint could be persisted across sessions." + } + }, + "required": [ "dataId", "description" ] + } + }, + "required": [ "body" ] + }] + }, + "Capabilities": { "type": "object", "title": "Types", @@ -3216,6 +3282,10 @@ "type": "boolean", "description": "The debug adapter supports the `clipboard` context value in the `evaluate` request." }, + "supportsDataAddressInfo": { + "type": "boolean", + "description": "The debug adapter supports the `dataAddressBreakpointInfo` request." + }, "supportsSteppingGranularity": { "type": "boolean", "description": "The debug adapter supports stepping granularities (argument `granularity`) for the stepping requests." diff --git a/specification.md b/specification.md index acfa846..8d9f524 100644 --- a/specification.md +++ b/specification.md @@ -1476,9 +1476,7 @@ interface SetFunctionBreakpointsResponse extends Response { ### :leftwards_arrow_with_hook: SetExceptionBreakpoints Request -The request configures the debugger's response to thrown exceptions. - -If an exception is configured to break, a `stopped` event is fired (with reason `exception`). +The request configures the debugger's response to thrown exceptions. Each of the `filters`, `filterOptions`, and `exceptionOptions` in the request are independent configurations to a debug adapter indicating a kind of exception to catch. An exception thrown in a program should result in a `stopped` event from the debug adapter (with reason `exception`) if any of the configured filters match. Clients should only call this request if the corresponding capability `exceptionBreakpointFilters` returns one or more filters. @@ -3246,6 +3244,84 @@ interface DisassembleResponse extends Response { } ``` +### :leftwards_arrow_with_hook: DataAddressBreakpointInfo Request + +Obtains information on a possible data breakpoint that could be set on a memory address or memory address range. + + + +Clients should only call this request if the corresponding capability `supportsDataAddressInfo` is true. + +```typescript +interface DataAddressBreakpointInfoRequest extends Request { + command: 'DataAddressBreakpointInfo'; + + arguments: DataAddressBreakpointInfoArguments; +} +``` + +Arguments for `dataAddressBreakpointInfo` request. + + +```typescript +interface DataAddressBreakpointInfoArguments { + /** + * The address of the data for which to obtain breakpoint information. + * Treated as a hex value if prefixed with `0x`, or as a decimal value + * otherwise. + */ + address?: string; + + /** + * If passed, requests breakpoint information for an exclusive byte range + * rather than a single address. The range extends the given number of `bytes` + * from the start `address`. + * Treated as a hex value if prefixed with `0x`, or as a decimal value + * otherwise. + */ + bytes?: string; +} +``` + +Response to `dataAddressBreakpointInfo` request. + + +```typescript +interface DataAddressBreakpointInfoResponse extends Response { + body: { + /** + * An identifier for the data on which a data breakpoint can be registered + * with the `setDataBreakpoints` request or null if no data breakpoint is + * available. If a `variablesReference` or `frameId` is passed, the `dataId` + * is valid in the current suspended state, otherwise it's valid + * indefinitely. See 'Lifetime of Object References' in the Overview section + * for details. Breakpoints set using the `dataId` in the + * `setDataBreakpoints` request may outlive the lifetime of the associated + * `dataId`. + */ + dataId: string | null; + + /** + * UI string that describes on what data the breakpoint is set on or why a + * data breakpoint is not available. + */ + description: string; + + /** + * Attribute lists the available access types for a potential data + * breakpoint. A UI client could surface this information. + */ + accessTypes?: DataBreakpointAccessType[]; + + /** + * Attribute indicates that a potential data breakpoint could be persisted + * across sessions. + */ + canPersist?: boolean; + }; +} +``` + ## Types ### Capabilities @@ -3444,6 +3520,11 @@ interface Capabilities { */ supportsClipboardContext?: boolean; + /** + * The debug adapter supports the `dataAddressBreakpointInfo` request. + */ + supportsDataAddressInfo?: boolean; + /** * The debug adapter supports stepping granularities (argument `granularity`) * for the stepping requests.