Updated docs

docs/platform-specification.md

@@ -1335,13 +1335,74 @@ the [core platform](#platform-terminology) is not used at all in defining the re
 actions. When using Arduino development software other than the Arduino IDE, the handling of properties from the core
 platform's platform.txt is done as usual.
 
-### Sketch debugging configuration
+## Sketch debugging configuration
 
 Starting from Arduino CLI 0.9.0 / Arduino IDE 2.x, sketch debugging support is available for platforms.
 
 The debug action is triggered when the user clicks the Debug button in the Arduino IDE or runs the
 [`arduino-cli debug`](commands/arduino-cli_debug.md) command.
 
+Since opening a debug session requires the orchestration of numerous tools, the CLI/IDE will take care of that duty:
+differently from the upload actions, there is no need for the platform to provide debug recipes, the only requirement is
+to provide some debug configuration directives.
+
+### Debugger configuration directives
+
+All the debug directives are grouped under the `debug.*` directives. Here is the complete list of the supported
+directives:
+
+- `debug.toolchain`: is a unique identifier of the required toolchain, currently we support `gcc` (and compatible) only
+- `debug.toolchain.path`: is the absolute path to the toolchain directory
+- `debug.toolchain.prefix`: is the prefix of the toolchain (for example `arm-none-eabi-`)
+- `debug.server`: is a unique identifier of the required debug server, currently we support only `openocd`
+- `debug.svd_file`: is the absolute path to the SVD descriptor.
+
+OpenOCD server specific confgiurations:
+
+- `debug.server.openocd.path`: is the absolute path to the OpenOCD directory
+- `debug.server.openocd.scripts_dir`: is the absolute path to the OpenOCD scripts directory
+- `debug.server.openocd.scripts.N`: is a list of OpenOCD scripts to run (where N is a number starting from 0)
+
+### Custom config for Cortext-debug plugin for Arduino IDE
+
+The Arduino IDE uses cortex-debug plugin to start a debugging session. The IDE creates a `launch.json` file that is
+needed to start the debugging via the cortex-debug plugin. To give the platform developers more flexibility, it is
+allowed to pass any extra arbitrary setup to `launch.json` generated by the IDE. To allow this the directives under the
+group `debug.cortex-debug.custom.*` are converted into JSON and added to the generated `launch.json` as-is. Moreover, if
+a directive has a key with a numeric suffix, it is converted into a JSON array.
+
+For example the following directives:
+
+```
+debug.cortex-debug.custom.postAttachCommands.0=set remote hardware-watchpoint-limit 2
+debug.cortex-debug.custom.postAttachCommands.1=monitor reset halt
+debug.cortex-debug.custom.postAttachCommands.2=monitor gdb_sync
+debug.cortex-debug.custom.postAttachCommands.3=thb setup
+debug.cortex-debug.custom.postAttachCommands.4=c
+debug.cortex-debug.custom.overrideRestartCommands.0=monitor reset halt
+debug.cortex-debug.custom.overrideRestartCommands.1=monitor gdb_sync
+debug.cortex-debug.custom.overrideRestartCommands.2=thb setup
+debug.cortex-debug.custom.overrideRestartCommands.3=c
+```
+
+will result in the following JSON to be merged in the Arduino IDE generated `launch.json`:
+
+```json
+{
+  "anotherStringParamer": "hellooo",
+  "overrideRestartCommands": ["monitor reset halt", "monitor gdb_sync", "thb setup", "c"],
+  "postAttachCommands": [
+    "set remote hardware-watchpoint-limit 2",
+    "monitor reset halt",
+    "monitor gdb_sync",
+    "thb setup",
+    "c"
+  ]
+}
+```
+
+### Optimization level for debugging
+
 The compiler optimization level that is appropriate for normal usage will often not provide a good experience while
 debugging. For this reason, it may be helpful to use different compiler flags when compiling a sketch for use with the
 debugger. The flags for use when compiling for debugging can be defined via the **compiler.optimization_flags.debug**