From cd99cf2fc02c8a9120c5bea6042fedbfda66bf7c Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Thu, 16 Jan 2025 17:21:50 +0100 Subject: [PATCH] prerequisites and settings tables Signed-off-by: Jens Reinecke --- README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 98 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ff8373a..e130892 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,104 @@ This is a Visual Studio Code extension that supports debugging using gdb and any This extension provides a number of features that integrate into the Visual Studio Code debug environment. This includes launch types, support for the standard debug views as well as a custom viewer for memory browsing. -## Launch Settings - -The Visual Studio Debug Extension for GDB supports two debugger types: -* `gdb`: Launch or attach to an application locally running on your host machine using GDB. -* `gdbtarget`: Launch or attach to a running remote GDB server using GDB. - - +## Prequisites + +External tools are expected to be present on your system depending on the intended use case. +* **Local GDB Debug**: A GDB installation is required on your system. +* **Remote GDB Debug**: A GDB installation is required on your system. In addition to that you must have either access to a running GDB server instance (`attach` use case), or a suitable GDB server variant must be installed to `launch` and attach to your debug target. + +## Launch Configurations + +The Visual Studio Debug Extension for GDB contributes two debugger types: +* `gdb`: Support for **Local GDB Debug**. Launch or attach to an already running application locally on your host machine using GDB. +* `gdbtarget`: Support for **Remote GDB Debug**. Launch or attach to an already running remote GDB server using GDB. + +Both come as `launch` and `attach` request types, each with a sophisticated set of configuration settings. + +### `gdb` Type + +Launch and attach configuration settings that can be used with the `gdb` debugger type for local GDB debug. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `gdb` | x | x | `string` | Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable.
Default: `gdb` | +| `cwd` | x | x | `string` | Current working directory for launching GDB.
Default: Directory of the debugged `program`. | +| `environment` | x | x | `object` | Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable.
Example:
\"environment\": {
  \"VARNAME\": \"value\",
  \"PATH\": \"/new/item:${env:PATH}\",
  \"REMOVEME\": null
}
| +| `program` | x | x | `string` | Path to the program to be debugged. For `launch` requests, this program is also launched.
Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path. | +| `arguments` | x | | `string` | Arguments for the program. | +| `processId` | | x | `string` | Process ID to attach to. | +| `gdbAsync` | x | x | `boolean` | Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`.
Default: `true` | +| `gdbNonStop` | x | x | `boolean` | Use `non-stop` mode for controlling multiple threads.
Default: `false` | +| `verbose` | x | x | `boolean` | Produce verbose log output. | +| `logFile` | x | x | `string` | Absolute path to the file to log interaction with GDB.| +| `openGdbConsole` | x | x | `boolean` | *(UNIX-only)* Open a GDB console in your IDE while debugging. | +| `initCommands` | x | x | `string[]` | List of GDB commands sent before attaching to inferior. | + + +### `gdbtarget` Type + +Launch and attach configuration settings that can be used with the `gdbtarget` debugger type for remote GDB debug connections. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `gdb` | x | x | `string` | Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable.
Default: `gdb` | +| `cwd` | x | x | `string` | Current working directory for launching GDB.
Default: Directory of the debugged `program`. | +| `environment` | x | x | `object` | Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable.
Example:
\"environment\": {
  \"VARNAME\": \"value\",
  \"PATH\": \"/new/item:${env:PATH}\",
  \"REMOVEME\": null
}
| +| `program` | x | x | `string` | Path to the program to be debugged. For `launch` requests, this program is also launched.
Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path.
**Note**: While `program` is marked as required, the debug adapter launches anyway for remote GDB connections. For example to inspect an embedded target system's memory and other hardware resources without debugging a program. | +| `gdbAsync` | x | x | `boolean` | Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`.
Default: `true` | +| `gdbNonStop` | x | x | `boolean` | Use `non-stop` mode for controlling multiple threads.
Default: `false` | +| `verbose` | x | x | `boolean` | Produce verbose log output. | +| `logFile` | x | x | `string` | Absolute path to the file to log interaction with GDB.| +| `openGdbConsole` | x | x | `boolean` | *(UNIX-only)* Open a GDB console in your IDE while debugging. | +| `initCommands` | x | x | `string[]` | List of GDB commands sent before attaching to inferior. | +| `preRunCommands` | x | x | `string[]` | List of GDB commands sent after loading image on target before resuming target. | +| `imageAndSymbols` | x | x | `object` | Additional settings for loading images to the target and symbols into the debugger. See section "`imageAndSymbols` object" for details. +| `target` | x | x | `object` | Additional settings to configure the remote GDB target. See section "`target` object" for details. | + +#### `imageAndSymbols` object + +Additional settings for loading images to the target and symbols into the debugger. This object can be used in `launch` and `attach` configurations for the `gdbtarget` debugger type for remote GDB connections. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `symbolFileName` | x | x | `string` | If specified, a symbol file to load at the given (optional) offset. Also see `symbolOffset`. | +| `symbolOffset` | x | x | `string` | If `symbolFileName` is specified, the offset added to symbol addresses when loaded. | +| `imageFileName` | x | x | `string` | If specified, an image file to load at the given (optional) offset. Also see `imageOffset`. | +| `imageOffset` | x | x | `string` | If `imageFileName` is specified, the offset used to load the image. | + +#### `target` object + +Additional settings for loading images to the target and symbols into the debugger. This object can be used in `launch` and `attach` configurations for the `gdbtarget` debugger type for remote GDB connections. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `type` | x | x | `string` | The kind of target debugging to do. This is passed to `-target-select`.
Default: `remote` | +| `parameters` | x | x | `string[]`| Target parameters for the type of target. Normally something like `localhost:12345`.
Default: `${host}:${port}`. | +| `host` | x | x | `string` | Target host to connect to. Ignored if `parameters` is set.
Default: `localhost` | +| `port` | x | x | `string` | Target port to connect to. Ignored if `parameters` is set.
Default: Value captured by `serverPortRegExp`, otherwise defaults to `2331` | +| `cwd` | x | | `string` | Specifies the working directory of the server.
Default: Working directory of GDB | +| `environment` | x | | `object` | Environment variables to use when launching server, defined as key-value pairs. Defaults to the environment used to launch GDB. Use `null` value to remove variable.
Example:
\"environment\": {
  \"VARNAME\": \"value\",
  \"PATH\": \"/new/item:${env:PATH}\",
  \"REMOVEME\": null
}
| +| `server` | x | | `string` | The executable for the target server to launch (e.g. gdbserver or JLinkGDBServerCLExe). This can be an absolute path or the name of an executable on your PATH environment variable.
Default: `gdbserver` | +| `serverParameters` | x | | `string[]` | Command line arguments passed to server.
Default: `--once :0 ${args.program}` | +| `serverPortRegExp` | x | | `string` | Regular expression to extract `port` from by examinging stdout/stderr of the GDB server. Once the server is launched, `port` will be set to this if unspecified. Defaults to matching a string like `Listening on port 41551` which is what `gdbserver` provides. Ignored if `port` or `parameters` is set. | +| `serverStartupDelay` | x | | `number` | Delay, in milliseconds, after startup but before continuing launch. If `serverPortRegExp` is provided, it is the delay after that regexp is seen. | +| `automaticallyKillServer` | x | | `boolean` | Automatically terminate the launched server when client issues a disconnect.
Default: `true` | +| `uart` | x | x | `object` | Settings related to displaying UART output in the debug console. | + +##### `uart` object + +Settings related to displaying UART output in the debug console. This object can be used in the `target` object of `launch` and `attach` configurations for the `gdbtarget` debugger type for remote GDB connections. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `serialPort` | x | x | `string` | Path to the serial port connected to the UART on the board. | +| `socketPort` | x | x | `string` | Target TCP port on the host machine to attach socket to print UART output.
Default: `3456` | +| `baudRate` | x | x | `number` | Baud Rate (in bits/s) of the serial port to be opened.
Default: `115200`.| +| `characterSize` | x | x | `number` | The number of bits in each character of data sent across the serial line.
Supported values: `5`, `6`, `7`, `8`
Default: `8` | +| `parity` | x | x | `string` | The type of parity check enabled with the transmitted data.
Supported values: `none`, `odd`, `even`, `mark`, `space`
Default: `none` - no parity bit sent | +| `stopBits` | x | x | `number` | The number of stop bits sent to allow the receiver to detect the end of characters and resynchronize with the character stream.
Supported values: `1`, `1.5`, `2`
Default: `1` | +| `handshakingMethod` | x | x | `string` | The handshaking method used for flow control across the serial line.
Supported values: `none`, `XON/XOFF`, `RTS/CTS`
Default: `none` - no handshaking | +| `eolCharacter` | x | x | `string` | The EOL character used to parse the UART output line-by-line.
Supported values: `LF`, `CRLF`
Default: `LF` | ## Memory Browser