Skip to content

Commit 510001e

Browse files
ReinhardKeilReinhardKeil
committed
Debugger Config detailed for each adapter type.
1 parent 231674c commit 510001e

File tree

2 files changed

+182
-37
lines changed

2 files changed

+182
-37
lines changed

‎docs/YML-CBuild-Format.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -799,9 +799,7 @@ cbuild-run:
799799
:
800800
801801
debugger:
802-
- name: pyOCD: CMSIS-DAP
803-
:
804-
- name: JLink
802+
- name: pyOCD@CMSIS-DAP
805803
:
806804
807805
debug-vars:

‎docs/YML-Input-Format.md‎

Lines changed: 181 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -2416,66 +2416,82 @@ This sensor shield layer provides a set of interfaces that are configurable.
24162416

24172417
## Debugger Configuration
24182418

2419-
Packs contain information for configuring debugger connection to a device or board. The `debugger:` node that is specified under the [`target-set:`](#target-set) in the *csolution project* allows
2420-
to overwrite configuration information or to define new debugger setups.
2419+
The `debugger:` node specified under the [`target-set:`](#target-set) in the *csolution project* configures the debugger.
2420+
2421+
!!! Notes
2422+
- Packs may provide a default configuration for a debugger connection to a device or board.
2423+
- Serveral settings are optional and the default settings are specific to the selected debug adapter.
2424+
- The complete debugger settings including default values are listed in `debugger:` node of the [`*.cbuild-run.yml` file](YML-CBuild-Format.md#run-and-debug-management).
24212425

24222426
### `debugger:`
24232427

24242428
`debugger:` | | Content
24252429
:---------------------------------------------------------|-------------|:------------------------------------
24262430
    `name:` |**Required** | Identifies the debug adapter.
2427-
    `protocol:` | Optional | Select debug portocol (jtag or swd).
2428-
    `clock:` | Optional | Select debug clock speed (in Hz for pyOCD, in kHz for JLink).
2429-
    `dbgconf:` | Optional | Configuration file for device settings such as trace pins and option bytes.
2430-
    `start-pname:` | Optional | Debugger connects at start to this processor.
2431-
    `*:` | Optional | Other debugger specific options can be used (see below), the section is not schema checked.
2431+
    `*:` | Optional | Other debugger specific options can be used as documented below.
24322432

2433-
!!! Note
2434-
If values are not specified, the default values from `debug-adapter.yml` are used.
2433+
The command `csolution list debuggers` outputs the `name:` of the supported debug adatpers; using the option `--verbose` extends the list with alias names that are also accepted as `name:` There are five different debug adapter categories:
2434+
2435+
Debug Adapter `name:` | Description
2436+
:-------------------------------|:-----------------------------------------------
2437+
[`<adapter>@pyOCD`](#pyocd) | Debug Adapters that interface via pyOCD.
2438+
[`<adapter>@Arm-Debugger`](#arm-debugger) | Debug Adapters that interface via the Arm-Debugger.
2439+
[`Arm-FVP`](#arm-fvp) | [FVP](https://arm-software.github.io/AVH/main/simulation/html/index.html) simulation models that represent processor sub-systems.
2440+
[`Keil uVision`](#keil-uvision) | [uVision Debugger](http://developer.arm.com/documentation/101407/0543/Debugging) that is integrated in the Keil uVision IDE.
2441+
[`JLink Server`](#jlink-server) | [Segger J-Link](https://www.segger.com/products/debug-probes/j-link/) debug probes that connect using the JLink Server.
2442+
2443+
The [Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) VS Code extension creates from the information provided by `debugger:` node, the entries in the files `.vscode/tasks.json` and `.vscode/launch.json` for starting the debug adapter. [`pyOCD`](#pyocd) supports a command-line mode that uses the [`*.cbuild-run.yml`](YML-CBuild-Format.md#run-and-debug-management) file which is created by the CMSIS-Toolbox.
2444+
2445+
The following sections describes the options available for the different debug adapter types.
2446+
2447+
### pyOCD
2448+
2449+
This section lists options that are specific for pyOCD that connects to [CMSIS-DAP](https://arm-software.github.io/CMSIS-DAP/latest/index.html) and ST-Link debug adapters. CMSIS-DAP is a standardize protocol that is used by many different debug adapters. All CMSIS-DAP enabled debug adapters can be accessed with `name: CMSIS-DAP@pyOCD`. A specific debug adapter name such as `name: ULINKplus@pyOCD` provides tailored default settings and a custom configuration dialog in the [Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) VS Code extension.
2450+
2451+
#### `debugger:` for pyOCD
2452+
2453+
debugger: | | Description
2454+
:---------------------------------|:------------|:-----------------------------------------------
2455+
&nbsp;&nbsp;&nbsp; `name:` |**Required** | Identifies the debug adapter with `<adapter>@pyOCD`.
2456+
&nbsp;&nbsp;&nbsp; `clock:` | Optional | Debug clock speed in Hz.
2457+
&nbsp;&nbsp;&nbsp; `protocol:` | Optional | Debug portocol (jtag or swd).
2458+
&nbsp;&nbsp;&nbsp; `dbgconf:` | Optional | Configuration file for device settings such as trace pins and option bytes.
2459+
&nbsp;&nbsp;&nbsp; `start-pname:` | Optional | Debugger connects at start to this processor.
2460+
&nbsp;&nbsp;&nbsp; [`telnet:`](#telnet-for-pyocd) | Optional | Telnet service configuration.
2461+
&nbsp;&nbsp;&nbsp; [`trace:`](#trace-for-pyocd) | Optional | Trace configuration.
24352462

24362463
**Examples:**
24372464

24382465
```yml
24392466
debugger:
2440-
name: CMSIS-DAP
2467+
name: CMSIS-DAP@pyOCD
24412468
protocol: swd
24422469
clock: 20000000 # 20 MHz
24432470
```
24442471

24452472
```yml
24462473
debugger:
2447-
name: ULink
2474+
name: ULINKplus
24482475
protocol: jtag
24492476
clock: 10000000 # 10 MHz
24502477
dbgconf: MyHardware.dbgconf
24512478
```
24522479

2453-
```yml
2454-
debugger:
2455-
name: JLink
2456-
clock: 4000 # 4000 kHz
2457-
protocol: swd
2458-
```
2459-
2460-
<!---
2461-
ToDo: this section needs to be in-synch with pyOCD
2462-
2463-
### Options for pyOCD
2464-
2465-
This section lists options that are specific for pyOCD that is used to connect to CMSIS-DAP and ST-Link debug adapters.
2480+
#### `telnet:` for pyOCD
24662481

2467-
#### `telnet:`
2482+
!!! Note
2483+
The `telnet:` feature will be implemented until Dec 2025. This section is only a preview.
24682484

24692485
pyOCD allows to configure for each processor that runs a independent application an Telnet service that connects to character I/O funtions. Character I/O is supported via Semihosting or Segger RTT channel 0.
24702486
The `telnet:` node configures:
24712487

24722488
- Telnet port for connecting remote tools, for example the [VS Code extension Serial Monitor](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-serial-monitor).
24732489
- Redirect the output to a log file or the console.
24742490

2475-
`telnet:` | | Content
2491+
`telnet:` | | Description
24762492
:---------------------------------------------------------|-------------|:------------------------------------
24772493
`- pname:` | Optional | Identifies the processor (not requried for single core system).
2478-
&nbsp;&nbsp;&nbsp; `port:` | Optional | Set port number of Telnet Server (default: 4444).
2494+
&nbsp;&nbsp;&nbsp; `port:` | Optional | Set TCP/IP port number of Telnet Server (default: 4444).
24792495
&nbsp;&nbsp;&nbsp; `log:` | Optional | Log output to a pre-defined (`file`) or console output (`stdio`). Default is `off`.
24802496

24812497
**Examples:**
@@ -2484,7 +2500,7 @@ Enable Telnet service or a single core system.
24842500

24852501
```yml
24862502
debugger:
2487-
name: CMSIS-DAP
2503+
name: CMSIS-DAP@pyOCD
24882504
protocol: swd
24892505
telnet: # enable Telnet service with default settings
24902506
```
@@ -2493,7 +2509,7 @@ Enable Telnet service or a single core system.
24932509

24942510
```yml
24952511
debugger:
2496-
name: CMSIS-DAP
2512+
name: CMSIS-DAP@pyOCD
24972513
protocol: swd
24982514
telnet:
24992515
port: 4444
@@ -2502,7 +2518,7 @@ debugger:
25022518

25032519
```yml
25042520
debugger:
2505-
name: CMSIS-DAP
2521+
name: CMSIS-DAP@pyOCD
25062522
protocol: swd
25072523
telnet:
25082524
- pname: Core0 # enable Telnet service with default settings
@@ -2513,12 +2529,143 @@ debugger:
25132529
log: file # log Telnet output
25142530
```
25152531

2516-
### Options for Segger JLink
2532+
#### `trace:` for pyOCD
2533+
2534+
!!! Note
2535+
The `trace:` feature will be implemented until Dec 2025. This section is only a preview.
2536+
2537+
CMSIS-DAP supports the SWO trace output of Cortex-M devices. The device-specific trace features are configured using the `*.dbgconf` file.
2538+
2539+
`trace:` | | Description
2540+
:---------------------------------------------------------|-------------|:------------------------------------
2541+
&nbsp;&nbsp;&nbsp; `clock:` |**Required** | Trace clock frequency in Hz.
2542+
&nbsp;&nbsp;&nbsp; `mode:` | Optional | Set Trace Port transport mode. Currently only `SWO-UART` is accepted.
2543+
&nbsp;&nbsp;&nbsp; `port:` | Optional | Set TCP/IP port number of Trace Server (default: 5555).
2544+
&nbsp;&nbsp;&nbsp; `log:` | Optional | Log trace output to a pre-defined file (default: no file created).
2545+
2546+
### Arm Debugger
2547+
2548+
This section lists options that are specific for the Arm Debugger.
2549+
2550+
debugger: | | Description
2551+
:---------------------------------|:------------|:-----------------------------------------------
2552+
&nbsp;&nbsp;&nbsp; `name:` |**Required** | Identifies the debug adapter with `<adapter>@Arm-Debugger`.
2553+
2554+
**Example:**
2555+
2556+
```yml
2557+
debugger:
2558+
name: CMSIS-DAP@Arm-Debugger
2559+
```
2560+
2561+
### Arm-FVP
2562+
2563+
This section lists options that are specific to the [FVP](https://arm-software.github.io/AVH/main/simulation/html/index.html) simulation models. An FVP is a configureable simulation model that are designed for software validation. It represents one or more Arm processors.
2564+
2565+
#### `debugger:` for Arm-FVP
2566+
2567+
debugger: | | Description
2568+
:---------------------------------|:------------|:-----------------------------------------------
2569+
&nbsp;&nbsp;&nbsp; `name:` |**Required** | Identifies the debug adapter with `Arm-FVP`.
2570+
&nbsp;&nbsp;&nbsp; `model:` | Optional | Model selection for a pre-defined list (see table below). Default: `FVP_MPS2_Cortex-M3`.
2571+
&nbsp;&nbsp;&nbsp; `model-file:` | Optional | Path and filename of the FVP executable; this setting overrules `model:`.
2572+
&nbsp;&nbsp;&nbsp; `config-file:` | Optional | Path and filename of the [FVP configuration file](https://arm-software.github.io/AVH/main/simulation/html/using.html).
2573+
`args:` | Optional | Miscellaneous [command line arguments](https://arm-software.github.io/AVH/main/simulation/html/using.html).
2574+
2575+
!!! Note
2576+
- `model-file:` is an explicit filename of an simulation model. This setting overwrites a `model:` selection.
2577+
2578+
`model:` can select only of the following pre-defined reference platforms. You should use the `model:` selection in combination with a `pack:` and `device:` as listed under
2579+
["CMSIS-based projects for AVH FVPs"](https://arm-software.github.io/AVH/main/simulation/html/avh_fvp_cmsis.html).
2580+
2581+
`model:` | Simulation Model Represents
2582+
:--------------------------------|:---------------------------------
2583+
`FVP_Corstone 300` | [Arm Corstone 300](https://developer.arm.com/documentation/100966/1128/Arm--Corstone-SSE-300-FVP) Reference Platform with Cortex-M55
2584+
`FVP_Corstone_SSE-300_Ethos-U55` | [Arm Corstone 300](https://developer.arm.com/documentation/100966/1128/Arm--Corstone-SSE-300-FVP) Reference Platform with Cortex-M55 and Ethos-U55
2585+
`FVP_Corstone_SSE-300_Ethos-U65` | [Arm Corstone 300](https://developer.arm.com/documentation/100966/1128/Arm--Corstone-SSE-300-FVP) Reference Platform with Cortex-M55 and Ethos-U65
2586+
`FVP_Corstone 310` | [Arm Corstone 310](https://developer.arm.com/documentation/102778) Reference Platform with Cortex-M85 and Ethos-U55.
2587+
`FVP_Corstone_SSE-310_Ethos-U65` | [Arm Corstone 310](https://developer.arm.com/documentation/102778) Reference Platform with Cortex-M85 and Ethos-U65.
2588+
`FVP_Corstone 315` | [Arm Corstone 315](https://developer.arm.com/documentation/109395) Reference Platform with Cortex-M85, Ethos-U65, and Mali-C55.
2589+
`FVP_Corstone 320` | [Arm Corstone 320](https://developer.arm.com/documentation/109760) Reference Platform with Cortex-M85, Ethos-U85, and Mali-C55.
2590+
`FVP_MPS2_Cortex-M0` | [Arm Microcontroller Prototyping System with Cortex-M0](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M0)
2591+
`FVP_MPS2_Cortex-M0plus` | [Arm Microcontroller Prototyping System with Cortex-M0+](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M0plus)
2592+
`FVP_MPS2_Cortex-M3` | [Arm Microcontroller Prototyping System with Cortex-M3](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M3)
2593+
`FVP_MPS2_Cortex-M4` | [Arm Microcontroller Prototyping System with Cortex-M4](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M4)
2594+
`FVP_MPS2_Cortex-M7` | [Arm Microcontroller Prototyping System with Cortex-M7](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M7)
2595+
`FVP_MPS2_Cortex-M23` | [Arm Microcontroller Prototyping System with Cortex-M23](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M23)
2596+
`FVP_MPS2_Cortex-M33` | [Arm Microcontroller Prototyping System with Cortex-M33](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M33)
2597+
`FVP_MPS2_Cortex-M35P` | [Arm Microcontroller Prototyping System with Cortex-M35P](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M35P)
2598+
`FVP_MPS2_Cortex-M52` | [Arm Microcontroller Prototyping System with Cortex-M52](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M52)
2599+
`FVP_MPS2_Cortex-M55` | [Arm Microcontroller Prototyping System with Cortex-M55](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M55)
2600+
`FVP_MPS2_Cortex-M85` | [Arm Microcontroller Prototyping System with Cortex-M85](https://developer.arm.com/documentation/100966/latest/MPS2-Platform-FVPs/FVP-MPS2-Cortex-M85)
2601+
2602+
**Example:**
2603+
2604+
```yml
2605+
debugger:
2606+
name: CMSIS-DAP@Arm-Debugger
2607+
model: FVP_Corstone_SSE-320
2608+
config-file: ./FVP_Config.txt
2609+
args: --simlimit 600 # stop simulation after 600 seconds
2610+
```
2611+
2612+
### Keil uVision
2613+
2614+
This section lists options that are specific for the uVision Debugger.
2615+
2616+
#### `debugger:` for Keil uVision
2617+
2618+
debugger: | | Description
2619+
:---------------------------------|:------------|:-----------------------------------------------
2620+
&nbsp;&nbsp;&nbsp; `name:` |**Required** | Identifies the debug adapter with `Keil uVision`.
2621+
&nbsp;&nbsp;&nbsp; `uv4:` | Optional | Path to the uVision executable; default: `C:/Keil_v5/UV4/UV4.exe`.
2622+
2623+
```yml
2624+
debugger:
2625+
name: Keil uVision
2626+
```
2627+
2628+
### JLink Server
25172629

2518-
This section lists options that are specific for Segger JLink.
2630+
This section lists options that are specific for the [Segger J-Link](https://www.segger.com/products/debug-probes/j-link/) debug probes.
2631+
2632+
#### `debugger:` for JLink Server
2633+
2634+
debugger: | | Description
2635+
:---------------------------------|:------------|:-----------------------------------------------
2636+
&nbsp;&nbsp;&nbsp; `name:` |**Required** | Identifies the debug adapter with `<adapter>@pyOCD`.
2637+
&nbsp;&nbsp;&nbsp; `clock:` | Optional | Debug clock speed in Hz.
2638+
&nbsp;&nbsp;&nbsp; `protocol:` | Optional | Debug portocol (jtag or swd).
2639+
&nbsp;&nbsp;&nbsp; [`telnet:`](#telnet-for-pyocd) | Optional | Telnet service configuration.
2640+
&nbsp;&nbsp;&nbsp; [`trace:`](#trace-for-pyocd) | Optional | Trace configuration.
2641+
2642+
**Examples:**
2643+
2644+
```yml
2645+
debugger:
2646+
name: JLink Server
2647+
clock: 4000 # 4000 kHz
2648+
protocol: swd
2649+
```
2650+
2651+
#### `telnet:` for JLink Server
2652+
2653+
JLink supports a Telnet service that connects to character I/O funtions. Character I/O is supported via Semihosting or Segger RTT channel 0.
2654+
2655+
`telnet:` | | Description
2656+
:---------------------------------------------------------|-------------|:------------------------------------
2657+
&nbsp;&nbsp;&nbsp; `port:` | Optional | Set TCP/IP port number of Telnet Server (default: 4444).
2658+
2659+
#### `trace:` for JLink Server
2660+
2661+
JLink supports a SWO Trace.
2662+
2663+
`trace:` | | Description
2664+
:---------------------------------------------------------|-------------|:------------------------------------
2665+
&nbsp;&nbsp;&nbsp; `clock:` |**Required** | Trace clock frequency in Hz.
2666+
&nbsp;&nbsp;&nbsp; `mode:` | Optional | Set Trace Port transport mode. Currently only `SWO-UART` is accepted.
2667+
&nbsp;&nbsp;&nbsp; `port:` | Optional | Set TCP/IP port number of Telnet Server (default: 4444).
25192668

2520-
todo
2521-
--->
25222669

25232670
## Add Memory
25242671

0 commit comments

Comments
 (0)