---
title: "Reference and troubleshooting"
---

# Reference and troubleshooting

Embedded module settings, keys, supported file formats and vendor paths with their verification state, the verification kits, and fixes for common problems.

## Keys

| Key | Action |
|---|---|
| Cmd+Shift+B (Ctrl+Shift+B) | Build the selected configuration |
| Cmd+Alt+U (Ctrl+Alt+U) | Flash |
| F5 | Flash and Debug |

With `neuralInverse.embedded.keymap` set to `keil`, `iar` or `eclipse`, the vendor IDE's keys run the same commands (for example F7 builds in the IAR keymap). See [Vendor keymaps and debug layouts](https://neuralinverse.com/docs/modules/embedded/keymap/).

## Settings

All settings are under `neuralInverse.embedded.`. Settings that name a program or arguments to run are restricted: a workspace that is not trusted cannot set them.

### Project and build

| Setting | Default | Meaning |
|---|---|---|
| `cmake.sourceDirectory` | empty (detect) | Folder with `CMakePresets.json` |
| `elfFile` | empty (newest `.elf`) | Image to measure, flash and debug, relative to the preset's build folder |
| `linkerScript` | empty (the `-T` script) | Linker script whose `MEMORY` regions the size report uses |
| `paths.<tool>` | empty | Path to a tool or its folder; see [tool ids](https://neuralinverse.com/docs/modules/embedded/setup/#how-tools-are-found) |
| `toolVersions` | `{}` | Pinned tool versions, by tool id |
| `clangd.arguments` | `[]` | Extra clangd arguments, after the Editor's |
| `keymap` | `none` | `none`, `keil`, `iar`, `eclipse` |
| `debugLayout` | `ide` | `ide`, `keil`, `iar`, `eclipse` |

### Device, packs and pins

| Setting | Default | Meaning |
|---|---|---|
| `device` | empty | `Vendor::Device` from an installed pack |
| `packs.root` | empty | CMSIS pack root |
| `packs.indexUrl` | `https://www.keil.com/pack/index.pidx` | Pack index, or a company mirror |
| `svdFile` | empty | SVD file for registers |
| `svdOverlays` | `[]` | SVD or IAR `.ddf` files added to the device |
| `ortiFile` | empty | ORTI file of an OSEK or AUTOSAR OS |
| `pins.file` | `pins.json` | Pin configuration |
| `pins.header` | `pins.h` | Header **Generate Pin Header** writes |
| `pins.dataPath` | empty | Local ST pin data or STM32CubeMX `db` folder |
| `pins.repository` | ST's public STM32_open_pin_data repository | Git repository **Download STM32 Pin Data** clones; set it to a company mirror |

### Probes

| Setting | Default | Meaning |
|---|---|---|
| `probeServer` | `auto` | `auto`, `jlink`, `stlink`, `trace32`, `openocd`, `linkserver`, `pemicro` |
| `jlink.device`, `jlink.interface`, `jlink.speed`, `jlink.serial` | empty, `SWD`, 4000, empty | J-Link |
| `stlink.serial`, `stlink.frequency`, `stlink.connectUnderReset` | empty, 0, `false` | ST-LINK |
| `trace32.cpu`, `trace32.connection`, `trace32.node`, `trace32.debugPort`, `trace32.script`, `trace32.flashScript`, `trace32.gdbServerSetup`, `trace32.port` | empty, `USB`, empty, empty, empty, empty, `script`, 30000 | TRACE32 |
| `openocd.board`, `openocd.interface`, `openocd.target`, `openocd.adapterSerial`, `openocd.adapterSpeed`, `openocd.arguments` | `board/stm32f4discovery.cfg`, empty, empty, empty, 0, `[]` | OpenOCD |
| `linkserver.device`, `linkserver.core`, `linkserver.probe`, `linkserver.overrides` | | NXP LinkServer |
| `pemicro.device`, `pemicro.interface`, `pemicro.port`, `pemicro.speed` | | PEmicro |
| `stm32Programmer.externalLoader` | empty | External loader listed first |
| `stm32Bootloader.baudRate` | 115200 | STM32 system bootloader over UART |
| `jflash.productionRecord` | | CSV production record of J-Flash runs |

### Debug

| Setting | Default | Meaning |
|---|---|---|
| `debug.gdbPort` | 3333 | OpenOCD's GDB port |
| `debug.rtos` | `auto` | OpenOCD RTOS awareness |
| `debug.semihosting` | `false` | Semihosting output in the Debug Console |
| `debug.rtt`, `debug.rttChannel` | `false`, 0 | SEGGER RTT output |
| `debug.swo`, `debug.swoCpuClock`, `debug.swoFrequency`, `debug.swoPort` | `false`, 0, 2000000, 0 | ITM over SWO |
| `debug.liveWatchInterval` | 500 | Live Watch interval in ms |
| `debug.livePlotInterval` | 50 | Live Plot interval in ms |
| `debug.profileSampleRate` | 10000 | PC samples a second for the Firmware Profile |
| `debug.profileExceptions` | `true` | Count exception entries in the profile |
| `debug.cycleStopwatch` | `false` | Start the cycle stopwatch at the first halt |
| `fault.recordSymbol` | `g_fault_record` | The firmware's fault record symbol |

### Serial monitor

`serial.baudRate` (115200), `serial.dataBits` (8), `serial.parity` (`none`), `serial.stopBits` (1), `serial.flowControl` (`none`), `serial.lineEnding` (`crlf`), `serial.localEcho` (`false`), `serial.timestamps` (`true`), `serial.logToFile` (`true`), `serial.logDirectory` (empty).

### Analysis and standards

`analysis.misra` (`true`), `analysis.misraRuleTexts`, `analysis.checks`, `analysis.suppressionsFile`, `analysis.exclude`, `analysis.onSave` (`false`), `standards.requiredHeader`, `standards.noDynamicAllocationDirectories`, `standards.exclude`. See [Static analysis and MISRA C](https://neuralinverse.com/docs/modules/embedded/static-analysis/).

## Vendor paths and their state

| Vendor path | State |
|---|---|
| IAR `.ewp` in-place build (`iarbuild`) | Code written; not yet run against IAR |
| IAR language support through clangd | The `__packed` translation run directly with Apple clang and clangd 15.0.0 on macOS (below the Editor's minimum of clangd 17); not yet run against `iccarm` |
| IAR C-SPY tests and C-RUN (`cspybat`) | Not yet run against cspybat |
| Keil `.uvprojx` in-place build (`UV4`) | Code written; not yet run against Keil |
| STM32CubeIDE `.cproject` in-place build and edit | Not yet run against STM32CubeIDE |
| Keil and IAR debug settings, `.ini` and `.mac` set-up scripts | Not yet run against uVision or IAR Embedded Workbench; scripts run in QEMU sessions on Linux |
| SEGGER Ozone project import | Not tested against Ozone |
| Arm Compiler 6 through CMake | Detected in unit tests; not translated for clangd as IAR is |
| SEGGER J-Link: flash, debug, RTT, live reads, J-Flash | Not yet run against J-Link or J-Flash |
| ST-LINK GDB server, STM32CubeProgrammer: flash, debug, option bytes, external flash, bootloader | Not yet run against them |
| Lauterbach TRACE32: debug, flash, complex breakpoints, BMC | Not yet run against TRACE32 |
| NXP LinkServer, PEmicro | Not run with them or a real probe |
| OpenOCD | Unit-tested; no verified run |
| QEMU | Run in Emulator verified against QEMU 9.1.1 |

## File formats

| Format | What the module does with it | State |
|---|---|---|
| `.ewp`, `.eww` (IAR) | Build in place, import into CMake, edit in place | Edits byte-identical on public demo projects (Linux); builds not run against IAR |
| `.uvprojx` (Keil) | Build in place, import into CMake, edit in place | Edits byte-identical on public demo projects (Linux); builds not run against Keil |
| `.uvoptx`, `.uvopt`, IAR `settings/`, `.ewd` | Import breakpoints and debugger settings | Parsers on real public files |
| `.ini` (uVision), `.mac` (C-SPY) | Run as GDB set-up scripts | Run in QEMU sessions on Linux |
| `.cproject` (STM32CubeIDE) | Build in place, import, edit | Edits byte-identical on ST examples (Linux) |
| `.ewt` (IAR) | C-RUN options read and changed | IAR's C-RUN evaluation projects (Linux) |
| `settings/*.xcl` (IAR) | `cspybat` command lines | Embedded Workbench 7.4 to 8.3 files |
| `.custom_argvars` (IAR) | Passed to iarbuild with `-varfile` | Unit tests |
| `.stldr` (STM32CubeProgrammer external loader) | External flash, memory range read | Files laid out by arm-none-eabi-gcc 13.2.1 |
| `.FLM` (CMSIS pack flash algorithm) | Flash sector layout for sector erase | The real `STM32F4xx_1024.FLM` |
| `.ioc` (STM32CubeMX) | Pinout editor, pin import | Unit tests |
| `CMakePresets.json`, `CMakeUserPresets.json` | Presets in the status bar | Unit tests |
| `.svd` (CMSIS-SVD) | Registers editor, hover, Peripherals scope | Fixtures; ST's STM32F407 SVD shown in the running app |
| `.ddf` (IAR) | Registers added to the device | Not verified against IAR |
| `.pdsc` and the pack index | Device picker | Unit tests |
| `.elf`, `.axf`, `.out`, `.hex`, `.bin` | Flash, size, compare with release | Flash not run on a board |
| GNU ld linker script (`.ld`) | Memory regions of the size report | Fixtures |
| GNU ld `.map` | Not read | |
| `.su` (GCC stack usage) | Problems, Firmware Memory editor | Fixtures |
| `compile_commands.json` | clangd, Cppcheck | |
| CTest JSON, JUnit XML | Testing view | Fixtures |
| `.jdebug`, `.jdebug.user` (Ozone) | Debug configuration import | Three public projects; not against Ozone |
| `.jflash` | Production runs | 8 public projects; not against J-Flash |
| `.orti`, `.ort` | RTOS view | Trampoline in QEMU (Linux) |
| `.cmm` (TRACE32 PRACTICE) | Colouring, outline, navigation | Public scripts (Linux) |
| `RTX_Config.h`, `FreeRTOSConfig.h`, `.dbgconf` with wizard annotations | Configuration Wizard | Arm and ST annotated files (Linux) |

## Verification kits

A kit runs exactly the commands the Editor runs, on a reference project, on your own installation, and collects the results into one archive. It needs no administrator rights, no Python or other runtime and no network: Windows PowerShell 5.1 on Windows, bash on Linux.

| Kit | Proves | Hardware |
|---|---|---|
| stm32cubeprogrammer | Test Connection, Read Option Bytes, Flash, Erase Flash Sectors; optionally external flash and the STM32 bootloader (option bytes are never written) | ST-LINK, STM32F407VG board |
| jlink | Test Connection, Flash, a debug session with a log point and a memory write, RTT output and input, Erase Flash Sectors; optionally a J-Flash production project | J-Link, STM32F407VG board |
| stlink-gdbserver | Flash and a debug session through ST's GDB server | ST-LINK, STM32F407VG board |
| iar-clangd | Language support for code built with iccarm | None |
| iar-keil-build | In-place IAR and Keil builds, round-trip edits, C-SPY tests, C-RUN | See the kit |
| trace32 | Debugging, flashing, complex breakpoints and BMC through TRACE32 | See the kit |
| vendor-licences | Licence status and real licence failure output of Arm Compiler 6, Keil MDK and IAR | None |
| stm32cubeide-build | STM32CubeIDE headless builds, before and after the Editor edited the `.cproject` | None |
| nxp-probes | Flash and debug through LinkServer and PEmicro | An NXP board; a PEmicro probe |
| heap-stack-symbols | Heap and stack symbols on IAR ILINK, armlink and MCUXpresso images | None |
| orti | ORTI expressions through your GDB server | The board running the OS image |

To run one:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\run-kit.ps1
```

```bash
./run-kit.sh
```

The script ends with the path of `ni-verify-<kit>-<date>-<time>.zip` (Windows) or `.tar.gz` (Linux), holding the operating system and tool versions, every command line as run, each tool's full output, and `results.tsv` with PASS, FAIL or SKIPPED per check. It contains probe serial numbers, device identification and paths from your machine, and nothing of your own source code. The TRACE32 kit's scripts are `run-trace32-kit.ps1` and `run-trace32-kit.sh`. Send the archive to your Neural Inverse contact whether the checks passed or failed. The PowerShell scripts have not yet been run on Windows by Neural Inverse; the first report from each kit is also the first run of its script. No report has been received yet.

## Troubleshooting

| Problem | What to do |
|---|---|
| Nothing embedded appears | Trust the workspace. Check that it holds a firmware project the module recognises; a CMake project must set up an Arm bare-metal compiler. |
| The status bar shows **Toolchain** | A tool the project needs is missing or older than the minimum. Run **Show Toolchain** for install hints, or set `neuralInverse.embedded.paths.<tool>`. |
| A pinned tool is reported missing | The version in `neuralInverse.embedded.toolVersions` is not installed. The module never falls back to another version. |
| A tool installed in a custom folder is not found | The Windows registry is not read. Set its path setting. |
| clangd does not start | Install clangd 17 or later yourself; the module does not ship it. |
| IAR keywords show errors in clangd | Build once (or configure) so the compile commands are translated. `__packed` with a line break before `struct` is not handled. |
| A build stops at the licence | Read the notification: it names the feature, the server or settings folder, and the variable that named it. Run the vendor-licences kit and send it if the message looks wrong. |
| Live Watch values do not update while running | Only OpenOCD and the J-Link GDB Server read while the core runs; the ST-LINK GDB server and TRACE32 read only while halted. |
| SWO output is garbled | `debug.swoCpuClock` must be the real core clock, and `debug.swoFrequency` must divide it exactly. |
| RTT output does not appear | The firmware must link SEGGER's RTT sources and initialise them; the session finds `_SEGGER_RTT` and starts streaming after that. |
| Option bytes say "not supported for this device" | Only STM32CubeProgrammer, and OpenOCD for STM32F2, F4 and F7, are supported. |
| The emulator asks to accept a generic board | QEMU does not emulate your device (for example the STM32F407). Accept only if the peripherals your test uses do not matter, or name a machine in `launch.json`. |
| A download fails behind the proxy | The message names the host. Set `http.proxy`, or use the offline settings for packs and pin data. |

To report a problem, say what you did, what you expected, what happened, the tool versions, and attach a screenshot or the log, or a kit archive.