From 406e068718ab22b73b6ea3342d7e276ce0ff6afd Mon Sep 17 00:00:00 2001 From: Connor Peet Date: Wed, 14 Feb 2024 06:10:51 -0800 Subject: [PATCH] Add a DataAddressBreakpointInfo request (#461) --- _data/specification-toc.yml | 2 + changelog.md | 1 + debugAdapterProtocol.json | 70 +++++++++++++++++++++++++++++++ specification.md | 83 +++++++++++++++++++++++++++++++++++++ 4 files changed, 156 insertions(+) diff --git a/_data/specification-toc.yml b/_data/specification-toc.yml index de05a0a..858d9ed 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 ebf3bf6..154edc1 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 * Add a `BreakpointMode` for setting different types of breakpoints diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index 1c6a56e..7b06133 100644 --- a/debugAdapterProtocol.json +++ b/debugAdapterProtocol.json @@ -3063,6 +3063,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", @@ -3220,6 +3286,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 d26a300..0ebf074 100644 --- a/specification.md +++ b/specification.md @@ -3250,6 +3250,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 @@ -3448,6 +3526,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.