You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+98-7
Original file line number
Diff line number
Diff line change
@@ -6,13 +6,104 @@ This is a Visual Studio Code extension that supports debugging using gdb and any
6
6
7
7
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.
8
8
9
-
## Launch Settings
10
-
11
-
The Visual Studio Debug Extension for GDB supports two debugger types:
12
-
*`gdb`: Launch or attach to an application locally running on your host machine using GDB.
13
-
*`gdbtarget`: Launch or attach to a running remote GDB server using GDB.
14
-
15
-
9
+
## Prequisites
10
+
11
+
External tools are expected to be present on your system depending on the intended use case.
12
+
***Local GDB Debug**: A GDB installation is required on your system.
13
+
***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.
14
+
15
+
## Launch Configurations
16
+
17
+
The Visual Studio Debug Extension for GDB contributes two debugger types:
18
+
*`gdb`: Support for **Local GDB Debug**. Launch or attach to an already running application locally on your host machine using GDB.
19
+
*`gdbtarget`: Support for **Remote GDB Debug**. Launch or attach to an already running remote GDB server using GDB.
20
+
21
+
Both come as `launch` and `attach` request types, each with a sophisticated set of configuration settings.
22
+
23
+
### `gdb` Type
24
+
25
+
Launch and attach configuration settings that can be used with the `gdb` debugger type for local GDB debug.
26
+
27
+
| Setting |`launch`|`attach`| Type | Description |
28
+
|:---|:---:|:---:|:---:|:---|
29
+
|`gdb`| x | x |`string`| Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable.<br>Default: `gdb`|
30
+
|`cwd`| x | x |`string`| Current working directory for launching GDB.<br>Default: Directory of the debugged `program`. |
31
+
|`environment`| x | x |`object`| Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable.<br>Example:<pre>\"environment\": {<br> \"VARNAME\": \"value\",<br> \"PATH\": \"/new/item:${env:PATH}\",<br> \"REMOVEME\": null<br>}</pre> |
32
+
|`program`| x | x |`string`| Path to the program to be debugged. For `launch` requests, this program is also launched.<br>Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path. |
33
+
|`arguments`| x ||`string`| Arguments for the program. |
34
+
|`processId`|| x |`string`| Process ID to attach to. |
35
+
|`gdbAsync`| x | x |`boolean`| Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`.<br>Default: `true`|
36
+
|`gdbNonStop`| x | x |`boolean`| Use `non-stop` mode for controlling multiple threads.<br> Default: `false`|
37
+
|`verbose`| x | x |`boolean`| Produce verbose log output. |
38
+
|`logFile`| x | x |`string`| Absolute path to the file to log interaction with GDB.|
39
+
|`openGdbConsole`| x | x |`boolean`|*(UNIX-only)* Open a GDB console in your IDE while debugging. |
40
+
|`initCommands`| x | x |`string[]`| List of GDB commands sent before attaching to inferior. |
41
+
42
+
43
+
### `gdbtarget` Type
44
+
45
+
Launch and attach configuration settings that can be used with the `gdbtarget` debugger type for remote GDB debug connections.
46
+
47
+
| Setting |`launch`|`attach`| Type | Description |
48
+
|:---|:---:|:---:|:---:|:---|
49
+
|`gdb`| x | x |`string`| Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable.<br>Default: `gdb`|
50
+
|`cwd`| x | x |`string`| Current working directory for launching GDB.<br>Default: Directory of the debugged `program`. |
51
+
|`environment`| x | x |`object`| Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable.<br>Example:<pre>\"environment\": {<br> \"VARNAME\": \"value\",<br> \"PATH\": \"/new/item:${env:PATH}\",<br> \"REMOVEME\": null<br>}</pre> |
52
+
|`program`| x | x |`string`| Path to the program to be debugged. For `launch` requests, this program is also launched.<br>Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path.<br>**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. |
53
+
|`gdbAsync`| x | x |`boolean`| Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`.<br>Default: `true`|
54
+
|`gdbNonStop`| x | x |`boolean`| Use `non-stop` mode for controlling multiple threads.<br> Default: `false`|
55
+
|`verbose`| x | x |`boolean`| Produce verbose log output. |
56
+
|`logFile`| x | x |`string`| Absolute path to the file to log interaction with GDB.|
57
+
|`openGdbConsole`| x | x |`boolean`|*(UNIX-only)* Open a GDB console in your IDE while debugging. |
58
+
|`initCommands`| x | x |`string[]`| List of GDB commands sent before attaching to inferior. |
59
+
|`preRunCommands`| x | x |`string[]`| List of GDB commands sent after loading image on target before resuming target. |
60
+
| `imageAndSymbols` | x | x | `object` | Additional settings for loading images to the target and symbols into the debugger. See section "`imageAndSymbols` object" for details.
61
+
|`target`| x | x |`object`| Additional settings to configure the remote GDB target. See section "`target` object" for details. |
62
+
63
+
#### `imageAndSymbols` object
64
+
65
+
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.
66
+
67
+
| Setting |`launch`|`attach`| Type | Description |
68
+
|:---|:---:|:---:|:---:|:---|
69
+
|`symbolFileName`| x | x |`string`| If specified, a symbol file to load at the given (optional) offset. Also see `symbolOffset`. |
70
+
|`symbolOffset`| x | x |`string`| If `symbolFileName` is specified, the offset added to symbol addresses when loaded. |
71
+
|`imageFileName`| x | x |`string`| If specified, an image file to load at the given (optional) offset. Also see `imageOffset`. |
72
+
|`imageOffset`| x | x |`string`| If `imageFileName` is specified, the offset used to load the image. |
73
+
74
+
#### `target` object
75
+
76
+
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.
77
+
78
+
| Setting |`launch`|`attach`| Type | Description |
79
+
|:---|:---:|:---:|:---:|:---|
80
+
|`type`| x | x |`string`| The kind of target debugging to do. This is passed to `-target-select`.<br>Default: `remote`|
81
+
|`parameters`| x | x |`string[]`| Target parameters for the type of target. Normally something like `localhost:12345`.<br>Default: `${host}:${port}`. |
82
+
|`host`| x | x |`string`| Target host to connect to. Ignored if `parameters` is set.<br>Default: `localhost`|
83
+
|`port`| x | x |`string`| Target port to connect to. Ignored if `parameters` is set.<br>Default: Value captured by `serverPortRegExp`, otherwise defaults to `2331`|
84
+
|`cwd`| x ||`string`| Specifies the working directory of the server.<br>Default: Working directory of GDB |
85
+
|`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.<br>Example:<pre>\"environment\": {<br> \"VARNAME\": \"value\",<br> \"PATH\": \"/new/item:${env:PATH}\",<br> \"REMOVEME\": null<br>}</pre> |
86
+
|`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.<br>Default: `gdbserver`|
87
+
|`serverParameters`| x ||`string[]`| Command line arguments passed to server.<br>Default: `--once :0 ${args.program}`|
88
+
|`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. |
89
+
|`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. |
90
+
|`automaticallyKillServer`| x ||`boolean`| Automatically terminate the launched server when client issues a disconnect.<br>Default: `true`|
91
+
|`uart`| x | x |`object`| Settings related to displaying UART output in the debug console. |
92
+
93
+
##### `uart` object
94
+
95
+
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.
96
+
97
+
| Setting |`launch`|`attach`| Type | Description |
98
+
|:---|:---:|:---:|:---:|:---|
99
+
|`serialPort`| x | x |`string`| Path to the serial port connected to the UART on the board. |
100
+
|`socketPort`| x | x |`string`| Target TCP port on the host machine to attach socket to print UART output.<br>Default: `3456`|
101
+
|`baudRate`| x | x |`number`| Baud Rate (in bits/s) of the serial port to be opened.<br>Default: `115200`.|
102
+
|`characterSize`| x | x |`number`| The number of bits in each character of data sent across the serial line.<br>Supported values: `5`, `6`, `7`, `8`<br>Default: `8`|
103
+
|`parity`| x | x |`string`| The type of parity check enabled with the transmitted data.<br>Supported values: `none`, `odd`, `even`, `mark`, `space`<br>Default: `none` - no parity bit sent |
104
+
|`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.<br>Supported values: `1`, `1.5`, `2`<br>Default: `1`|
105
+
|`handshakingMethod`| x | x |`string`| The handshaking method used for flow control across the serial line.<br>Supported values: `none`, `XON/XOFF`, `RTS/CTS`<br>Default: `none` - no handshaking |
106
+
|`eolCharacter`| x | x |`string`| The EOL character used to parse the UART output line-by-line.<br>Supported values: `LF`, `CRLF`<br>Default: `LF`|
0 commit comments