Skip to content

Commit dc34d58

Browse files
JonatanAntoniTeoMahnic
JonatanAntoni
and
TeoMahnic
authored
Enhance documentation about debug template processing (#66)
Co-authored-by: Teo Mahnic <teo.mahnic@arm.com>
1 parent 26e3170 commit dc34d58

1 file changed

Lines changed: 266 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 266 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,38 +3,295 @@
33
[![License](https://img.shields.io/github/license/Open-CMSIS-Pack/debug-adapter-registry?label=License)](https://github.com/Open-CMSIS-Pack/debug-adapter-registry/blob/main/LICENSE)
44
[![Test and release ](https://img.shields.io/github/actions/workflow/status/Open-CMSIS-Pack/debug-adapter-registry/ci.yml?logo=arm&logoColor=0091bd&label=Test%20and%20release)](https://github.com/Open-CMSIS-Pack/debug-adapter-registry/tree/main/.github/workflows/ci.yml)
55

6-
This repository contains the [debug adapter registry](https://open-cmsis-pack.github.io/cmsis-toolbox/build-operation/#debug-adapter-integration) and the CMSIS Solution extension specific adapter template files.
6+
This repository contains the [debug adapter registry](https://open-cmsis-pack.github.io/cmsis-toolbox/build-operation/#debug-adapter-integration)
7+
and the CMSIS Solution extension specific adapter template files.
78

89
```txt
910
📦
1011
┣ 📂 registry shared debug adapter registry
1112
┃ ┗ 📄 debug-adapters.yml yaml document listing all available debug adapters
1213
┗ 📂 templates command line tool source code
13-
┣ 📄 *.adapter.json json template for vscode launch and task definitions per debug adapter
14+
┣ 📄 *.adapter.json json template for vscode launch and task definitions per debug adapter
1415
┗ 📄 ...
1516
```
1617

17-
The adapter registry is used by CMSIS-Toolbox starting version 2.9.0 to generate `<solution>+<target-type>.cbuild-run.yml` files for the active target-set selected by
18+
The adapter registry is used by CMSIS-Toolbox starting version 2.9.0 to generate `<solution>+<target-type>.cbuild-run.yml`
19+
files for the active target-set selected by
1820

19-
```
21+
```sh
2022
cbuild setup <solution> --active <target-type>[@<set>]
2123
```
2224

2325
Available target-sets are listed by running
2426

25-
```
27+
```sh
2628
cbuild list target-sets <solution>
2729
```
2830

29-
The `<solution>+<target-type>.cbuild-run.yml` file is then processed by the CMSIS Solution extension to generate launch.json and task.json files from the debug adapter template files.
31+
The `<solution>+<target-type>.cbuild-run.yml` file is then processed by the CMSIS Solution extension to generate
32+
`launch.json` and `task.json` files from the debug adapter template files.
3033

3134
---
3235

36+
## Debug Adapter Specification
37+
38+
The `registry/debug-adapters.yml` lists out all known debug adapters with additional details according to the following schema:
39+
40+
```yml
41+
debug-adapters:
42+
- name: <unique name>
43+
alias-name: [<alias name>, ... ]
44+
template: <adapter json template>
45+
gdbserver:
46+
defaults:
47+
<property>: <value>
48+
user-interface:
49+
- section: <section label>
50+
description: <section description>
51+
yaml-node: <optional section yaml node>
52+
options:
53+
- name: <property label>
54+
description: <property description>
55+
yml-node: <yaml node name>
56+
type: <input field type>
57+
range: [<min value for number fields>, <max value for number fields>]
58+
scale: <scale factor for number fields>
59+
default: <default value>
60+
values: [<values for enum fields>]
61+
values: # alternative long format
62+
- name: <display label for enum value, defaults to value>
63+
value: <yaml text for enum value, defaults to name>
64+
description: <optional description for enum value>
65+
```
66+
67+
```txt
68+
YAML Node Value Type Description
69+
--------------------- ------------------ -----------------------------------------------------------------------
70+
debug-adapters object Top level node for debug-adapters.yml
71+
┣ name string Unique name to identify a debug adapter
72+
┣ alias-name array of strings Optional alias names to identify the debug adapter
73+
┣ template string Reference to the .adapter.json template file
74+
┣ gdbserver object Optional, once specified additional gdb server handling is triggered
75+
┣ defaults object Optional default values for debug adapter specific settings
76+
┗ user-interface array of objects Definition for UI representation for relevant debug adapter settings
77+
┣ section string Label for a UI settings section
78+
┣ description string Optional section description   
79+
┣ yaml-node string Optional yaml node name to group section options
80+
┗ options object Options to group into the section
81+
┣ name string UI label for the option
82+
┣ description string UI description for the option (e.g., for tooltips)
83+
┣ yaml-node string YAML node node name to store the option value to
84+
┣ type enum UI input control type: string, number, file, enum
85+
┣ range [number, number] Value range (for number type options)
86+
┣ scale number Value display scale (for number type options)
87+
┣ default any Default value used as UI preset
88+
┗ values array of strings Accepted values (for enum type options), short form.
89+
┃ array of objects Accepted values (for enum type options), long form.
90+
┣ name string Display label for the enum value, if omitted value is used.
91+
┣ value string Storage value for the enum value, if omitted name is used.
92+
┗ description string Optional description text.
93+
```
94+
95+
## Template Development
96+
97+
### Template input files
98+
99+
The `.adapter.json` files provide snippets to be injected into the workspace `launch.json` and `tasks.json` files:
100+
101+
```json
102+
{
103+
"data": {
104+
"cwd": "${workspaceFolder}/<%= solution_folder %>"
105+
},
106+
"launch": {
107+
"singlecore-launch": {},
108+
"singlecore-attach": {},
109+
"multicore-start-launch": {},
110+
"multicore-start-attach": {},
111+
"multicore-other": {}
112+
},
113+
"tasks": [
114+
{
115+
"label": "CMSIS Erase"
116+
},
117+
{
118+
"label": "CMSIS Load"
119+
},
120+
{
121+
"label": "CMSIS Run"
122+
},
123+
{
124+
"label": "CMSIS Load+Run"
125+
},
126+
{
127+
"label": "CMSIS TargetInfo"
128+
}
129+
]
130+
}
131+
```
132+
133+
```txt
134+
JSON Node Value Type Description
135+
--------------------- ------------------ -----------------------------------------------------------------------
136+
data object User data processed on a global scope
137+
launch object Template launch configurations
138+
┣ singlecore-launch object Launch template for launching a single core debug session
139+
┣ singlecore-attach object Launch template for attaching to a single core debug session
140+
┣ multicore-start-launch object Launch template for launching a multi core debug session
141+
┣ multicore-start-attach object Launch template for attaching to the primary core of a multi core debug session
142+
┗ multicore-other object Launch template for attaching to other cores of a multi core debug session
143+
tasks array of objects Template tasks
144+
┗ label string Unique name to identify the task, specific names are used for CMSIS debug related tasks
145+
```
146+
147+
### Template processing
148+
149+
All string elements are processed one-by-one with the [ETA JS template engine](https://eta.js.org/). The `data` section
150+
is processed in the first pass and the result is passed into subsequent template processing. Hence, one can collect
151+
reused parts under `data` section to avoid duplication.
152+
153+
Arrays-of-strings loaded from the template are joined into a multi-line string, processed at once and split based on linebreaks after processing.
154+
This can be used to generate arrays using a multiline template if required:
155+
156+
```json
157+
{
158+
"template": ["<% for elem in array %> {", "<%= elem.name %>\\n", "<% } %>"]
159+
}
160+
```
161+
162+
Notice the explicit newline character inserted after the template tag. The implicit newline resulting from
163+
concatenation is swallowed by the template processing if a template output data tag runs until the end of a line.
164+
165+
Template output data tags are typically used to create strings, similar to JavaScript format strings (backtick notation).
166+
When outputting objects or arrays, these are stringified using JavaScript Object Notation (JSON). If JSON is detected
167+
in a resulting launch or task configuration object, its converted back. E.g., one can achieve the following:
168+
169+
```json
170+
{
171+
"data": {
172+
"shell": {
173+
"win32": {
174+
"executable": "cmd.exe",
175+
"args": ["/d", "/c"]
176+
},
177+
"linux": {
178+
"executable": "/bin/bash",
179+
"args": ["-c"]
180+
},
181+
"darwin": {
182+
"executable": "/bin/bash",
183+
"args": ["-c"]
184+
}
185+
}
186+
},
187+
"tasks": [
188+
{
189+
"options": {
190+
"shell": "<%= data.shell[process.platform] %>"
191+
}
192+
}
193+
]
194+
}
195+
```
196+
197+
To be transformed into
198+
199+
```json
200+
{
201+
"tasks": [
202+
{
203+
"options": {
204+
"shell": {
205+
"executable": "cmd.exe",
206+
"args": ["/d", "/c"]
207+
}
208+
}
209+
}
210+
]
211+
}
212+
```
213+
214+
Plain numbers and boolean representation strings are converted to plain data type by default.
215+
If instead the value is required as a quoted string, this needs to be enforced explicitly.
216+
217+
```json
218+
{
219+
"data": {
220+
"number": "3000",
221+
"flag": "true"
222+
},
223+
"tasks": [
224+
{
225+
"options": {
226+
"plain-num": "<%= data.number %>",
227+
"quoted-num": "\"<%= data.number %>\"",
228+
"plain-bool": "<%= data.flag %>",
229+
"quoted-bool": "\"<%= data.flag %>\""
230+
}
231+
}
232+
]
233+
}
234+
```
235+
236+
To be transformed into
237+
238+
```json
239+
{
240+
"tasks": [
241+
{
242+
"options": {
243+
"plain-num": 3000,
244+
"quoted-num": "3000",
245+
"plain-bool": true,
246+
"quoted-bool": "true"
247+
}
248+
}
249+
]
250+
}
251+
```
252+
253+
### Dynamic data structure
254+
255+
The following data structure is available to the templates:
256+
257+
```yml
258+
data: { <custom data as specified> }
259+
platform: <JavaScript process.platform>
260+
solution_path: <path to .csolution.yml relative to workspace>
261+
solution_folder: <base directory of .csolution.yml relative to workspace>
262+
device_name: <name of target device>
263+
target_type: <name of active csolution target-type>
264+
start_pname: <processor name of primary processor if multi core device>
265+
image_files: # image files used to program the device (image, image+symbol)
266+
- file: <image file name relative to solution_folder>
267+
pname: <processor name>
268+
symbol_files: # symbol files with debug information (symbol, image+symbol)
269+
- file: <symbol file name relative to solution_folder>
270+
pname: <processor name>
271+
ports: # GDB debug port mapping for all processors
272+
<pname>: <gdb-port>
273+
config: # entire debugger node from .cbuild-run.yml
274+
processors: # List of processors on a multi-core system
275+
- <pname>
276+
```
277+
278+
In template expressions all functions in JavaScript global scope can be used. In addition, the following helper functions are available:
279+
280+
| Function | Description |
281+
| -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
282+
| `Array<T>.groupedBy((e: T) => string): Map<string, T[]>` | Group elements of an array into a Map according to the given key-generator function. |
283+
| `Map<K, V>.every((v: V, k: K) => boolean): boolean` | Determines if all elements satisfy the given condition. |
284+
| `Map<K, V>.mapValues<T>((v: V, k: K) => T): Map<K, T>` | Transforms all elements with given function. |
285+
| `Map<K, V>.toObject(): Record<string, T>` | Converts the Map into a JavaScript object |
286+
33287
## Validation
34288

35-
The [CI worklow](.github/workflows/ci.yml) validates the debugger adapter registry and templates by running linter and schema checker.
36-
Such validation steps can be reproduced in the local environment according to the following instructions.
37-
> Pre-requisite: it assumes [`npm`](https://nodejs.org/en/download) is installed in the system.
289+
The [CI worklow](.github/workflows/ci.yml) validates the debugger adapter registry and templates by running linter and
290+
schema checker. Such validation steps can be reproduced in the local environment according to the following
291+
instructions.
292+
293+
> **prerequisite:**
294+
> [`npm`](https://nodejs.org/en/download) to be installed in the system.
38295

39296
### Linter
40297

0 commit comments

Comments
 (0)