---
title: OpenOCD Configurations
description: Shipped configuration files for common debug probes
---

mcjtag ships two OpenOCD configuration files for the Treedix DAP-Link V1 probe (a CMSIS-DAP compatible debugger). These cover the two most common debug transports: SWD and JTAG.

---

## openocd-daplink-swd.cfg

SWD (Serial Wire Debug) configuration for CMSIS-DAP probes.

```tcl
# OpenOCD config for Treedix DAP-Link V1 (CMSIS-DAP) over SWD
# Usage: openocd -f openocd-daplink-swd.cfg
#   or:  OPENOCD_CONFIG=openocd-daplink-swd.cfg uvx mcjtag

source [find interface/cmsis-dap.cfg]
transport select swd
adapter speed 1000

# Default target: STM32F1xx (Blue Pill, etc.)
# Change this line for different targets:
#   source [find target/stm32f4x.cfg]   # STM32F4
#   source [find target/stm32l4x.cfg]   # STM32L4
#   source [find target/gd32vf103.cfg]  # GD32VF103
source [find target/stm32f1x.cfg]
```

**Transport:** SWD -- uses 2 wires (SWDIO + SWCLK). This is the most common transport for ARM Cortex-M targets and the recommended default.

**Adapter speed:** 1000 kHz. This is a safe default that works reliably with most probes and targets. Can be increased to 2000--4000 kHz for faster transfers once communication is confirmed stable.

**Default target:** STM32F1xx series (including the popular Blue Pill board). Change the `source [find target/...]` line for other chips.

**Usage:**

```bash
# Direct OpenOCD
openocd -f openocd-daplink-swd.cfg

# Via mcjtag auto-spawn
OPENOCD_CONFIG=openocd-daplink-swd.cfg uvx mcjtag
```

---

## openocd-daplink-jtag.cfg

JTAG (Joint Test Action Group) configuration for CMSIS-DAP probes.

```tcl
# OpenOCD config for Treedix DAP-Link V1 (CMSIS-DAP) over JTAG
# Usage: openocd -f openocd-daplink-jtag.cfg

source [find interface/cmsis-dap.cfg]
transport select jtag
adapter speed 1000

# Default target: STM32F1xx
source [find target/stm32f1x.cfg]
```

**Transport:** JTAG -- uses 4 wires (TDI, TDO, TMS, TCK) plus optional TRST. JTAG supports scan chain enumeration, which allows discovering multiple devices on the same chain.

**When to use JTAG over SWD:**

- When you need to scan the full JTAG chain (multiple TAPs)
- When the target only exposes a JTAG header (no SWD pins)
- When debugging boundary scan or board-level connectivity

**Adapter speed:** Same 1000 kHz safe default.

---

## SWD vs JTAG

| Feature | SWD | JTAG |
|---------|-----|------|
| Wires | 2 (SWDIO, SWCLK) | 4+ (TDI, TDO, TMS, TCK) |
| Pin count | Fewer pins, smaller headers | More pins, 20-pin connector typical |
| Scan chain | No chain scanning | Full chain enumeration via `jtag_scan()` |
| Speed | Same throughput for single targets | Same throughput for single targets |
| Multi-device | Single target per port | Multiple TAPs on one chain |
| ARM support | Cortex-M, Cortex-A | Cortex-M, Cortex-A, RISC-V, FPGA, etc. |

For most ARM Cortex-M work, SWD is preferred due to fewer wires and simpler wiring.

---

## Changing the Target

Both shipped configs default to `stm32f1x.cfg`. To target a different chip, copy the config and change the `source [find target/...]` line:

```tcl
# STM32F4 (Discovery, Nucleo F4 boards)
source [find target/stm32f4x.cfg]

# STM32L4 (low-power)
source [find target/stm32l4x.cfg]

# nRF52 (Nordic Bluetooth SoC)
source [find target/nrf52.cfg]

# RP2040 (Raspberry Pi Pico)
source [find target/rp2040.cfg]

# ESP32 (Espressif, needs special config)
source [find target/esp32.cfg]

# GD32VF103 (RISC-V)
source [find target/gd32vf103.cfg]
```

---

## Finding Other Configs

OpenOCD ships configuration files for hundreds of targets and interfaces in its `share/openocd/scripts/` directory. The directory is structured as:

```
share/openocd/scripts/
  interface/          # Debug probe configs
    cmsis-dap.cfg
    stlink.cfg
    jlink.cfg
    ftdi/             # FTDI-based probes (many variants)
      ...
  target/             # Target MCU configs
    stm32f1x.cfg
    stm32f4x.cfg
    nrf52.cfg
    rp2040.cfg
    ...
  board/              # Board-specific configs (probe + target combined)
    st_nucleo_f4.cfg
    nordic_nrf52_dk.cfg
    ...
```

To find configs on your system:

```bash
# Find the OpenOCD scripts directory
find / -name "stm32f1x.cfg" -path "*/openocd/*" 2>/dev/null

# List all available target configs
ls $(openocd --search | head -1)/target/

# List all available interface configs
ls $(openocd --search | head -1)/interface/
```

### Common Interface Configs

| Probe | Config |
|-------|--------|
| CMSIS-DAP (DAP-Link, etc.) | `interface/cmsis-dap.cfg` |
| ST-Link V2/V3 | `interface/stlink.cfg` |
| Segger J-Link | `interface/jlink.cfg` |
| FTDI-based (Bus Blaster, etc.) | `interface/ftdi/<variant>.cfg` |
| Raspberry Pi GPIO | `interface/raspberrypi-native.cfg` |

### Writing Custom Configs

A minimal OpenOCD config has three parts:

```tcl
# 1. Interface: which debug probe to use
source [find interface/cmsis-dap.cfg]

# 2. Transport: SWD or JTAG
transport select swd

# 3. Target: which chip to debug
source [find target/stm32f1x.cfg]

# Optional: set adapter speed (kHz)
adapter speed 1000

# Optional: initial commands
init
reset halt
```

The `adapter speed` can be set before or after the target config. Some targets have their own speed constraints documented in their config files.
