OpenOCD

https://openocd.org/doc/html/
Admin
OpenOCD is an open-source debugger that provides debugging, in-system programming, and boundary-scan...
Tokens:99,322
Snippets:1,515
Trust Score:9.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### OpenOCD Command Line Configuration Example

Source: https://openocd.org/doc/html/OpenOCD-Project-Setup.html

The command-line equivalent of the example configuration file. This demonstrates how to achieve the same setup using multiple -f and -c options.

```bash
openocd -f interface/ftdi/signalyzer.cfg \
        -c "gdb memory_map enable" \
        -c "gdb flash_program enable" \
        -f target/sam7x256.cfg

```

--------------------------------

### Basic OpenOCD Setup with Interface and Board Configuration

Source: https://openocd.org/doc/html/Running.html

A common setup using two configuration files: one for the debug adapter interface and another for the target board. This is a good starting point for many projects.

```bash
openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
```

```bash
openocd -f interface/ftdi/ADAPTER.cfg -f board/MYBOARD.cfg
```

--------------------------------

### Configure Setup Event for TAP Enable

Source: https://openocd.org/doc/html/TAP-Declaration.html

This example configures the JRC's setup event to ensure a specific TAP is enabled. Note the use of quotes to ensure variable evaluation at configuration time.

```tcl
jtag configure $CHIP.jrc -event setup "jtag tapenable $CHIP.cpu"
```

--------------------------------

### Open Firmware Recovery Script

Source: https://openocd.org/doc/html/Utility-Commands.html

Launch the firmware recovery script with the 'firmware_help' command to get quickstart instructions for mass-market device recovery.

```bash
openocd -f tools/firmware-recovery.tcl -c firmware_help
```

--------------------------------

### Sample GDB Session Startup

Source: https://openocd.org/doc/html/GDB-and-OpenOCD.html

An example of starting a GDB session to debug an ARM program loaded into SRAM, including connecting, resetting, halting, and loading the program.

```gdb
$ arm-none-eabi-gdb example.elf
(gdb) target extended-remote localhost:3333
Remote debugging using localhost:3333
... 
(gdb) monitor reset halt
... 
(gdb) load
Loading section .vectors, size 0x100 lma 0x20000000
Loading section .text, size 0x5a0 lma 0x20000100
Loading section .data, size 0x18 lma 0x200006a0
Start address 0x2000061c, load size 1720
Transfer rate: 22 KB/sec, 573 bytes/write.
(gdb) continue
Continuing
...
```

--------------------------------

### Setup and Start RTT with TCP Server

Source: https://openocd.org/doc/html/General-Commands.html

Configures RTT to search for a control block at a specified address and size, starts RTT, and exposes RTT channel 0 via a TCP server on a given port. This is useful for targets without SWO or when semihosting is not feasible due to real-time constraints.

```bash
resume

rtt setup 0x20000000 2048
rtt start

rtt server start 9090 0

```

--------------------------------

### XScale Vector Table Setup Example

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

This assembly code demonstrates how to set up the XScale vector table using pc-relative indirect branches to ensure code constancy.

```assembly
_vectors:
        ldr     pc,[pc,#0x100-8]
        ldr     pc,[pc,#0x100-8]
        ldr     pc,[pc,#0x100-8]
        ldr     pc,[pc,#0x100-8]
        ldr     pc,[pc,#0x100-8]
        ldr     pc,[pc,#0x100-8]
        ldr     pc,[pc,#0x100-8]
        ldr     pc,[pc,#0x100-8]
        .org 0x100
        .long real_reset_vector
        .long real_ui_handler
        .long real_swi_handler
        .long real_pf_abort
        .long real_data_abort
        .long 0 /* unused */
        .long real_irq_handler
        .long real_fiq_handler

```

--------------------------------

### Start eSi-RISC Manual Trace Collection

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Manually starts trace collection for eSi-RISC.

```tcl
esirisc trace start
```

--------------------------------

### OpenOCD Server Output Example

Source: https://openocd.org/doc/html/Running.html

Example output indicating successful JTAG communication. Seeing the 'tap/device found' message without warnings is a positive sign.

```text
Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
       (mfg: 0x23b, part: 0xba00, ver: 0x3)
```

--------------------------------

### Tcl/Tk Button Example

Source: https://openocd.org/doc/html/CPU-Configuration.html

Illustrates the creation, modification, querying, and reporting of a Tcl/Tk button object, demonstrating the object command model.

```tcl
# Create
button .foobar -background red -command { foo }
# Modify
.foobar configure -foreground blue
# Query
set x [.foobar cget -background]
# Report
puts [format "The button is %s" $x]
```

--------------------------------

### RAM Boot Utility Script

Source: https://openocd.org/doc/html/OpenOCD-Project-Setup.html

Use this script to load and debug bootloader code directly into RAM, bypassing finicky early hardware setup. It resets the target, loads the image, and starts execution from a specified RAM address.

```tcl
proc ramboot { } {
    # Reset, running the target's "reset-init" scripts
    # to initialize clocks and the DDR RAM controller.
    # Leave the CPU halted.
    reset init

    # Load CONFIG_SKIP_LOWLEVEL_INIT version into DDR RAM.
    load_image u-boot.bin 0x20000000

    # Start running.
    resume 0x20000000
}
```

--------------------------------

### OpenOCD Configuration File Example

Source: https://openocd.org/doc/html/OpenOCD-Project-Setup.html

An example OpenOCD configuration file (openocd.cfg) for a Signalyzer FT2232 JTAG adapter and an Atmel AT91SAM7X256 microcontroller. This file sources interface and target configuration files and enables GDB memory map and flash programming.

```tcl
source [find interface/ftdi/signalyzer.cfg]

# GDB can also flash my flash!
gdb memory_map enable
gdb flash_program enable

source [find target/sam7x256.cfg]

```

--------------------------------

### RISC-V Authentication Example

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Example of implementing a challenge-response protocol using RISC-V authentication commands. Reads an authentication data value and writes an incremented value back.

```tcl
set challenge [riscv authdata_read]
riscv authdata_write [expr {$challenge + 1}]
```

--------------------------------

### STR9xpec Flash Driver Example: Read Option Bytes

Source: https://openocd.org/doc/html/Flash-Commands.html

Example sequence for reading option bytes using the STR9xpec driver. This involves disabling the core, performing the read, and then re-enabling the core.

```tcl
# assert srst, we do not want core running
# while accessing str9xpec flash driver
adapter assert srst
# turn off target polling
poll off
# disable str9 core
str9xpec enable_turbo 0
# read option bytes
str9xpec options_read 0
# re-enable str9 core
str9xpec disable_turbo 0
poll on
reset halt
```

--------------------------------

### Board Configuration with init_board Procedure

Source: https://openocd.org/doc/html/Config-File-Guidelines.html

Example of a board configuration file using the init_board procedure to handle board-specific initialization, including reset configurations and adapter speed settings for different reset events.

```tcl
### board_file.cfg ###

source [find target/target.cfg]

proc enable_fast_clock {} {
    # enables fast on-board clock source
    # configures the chip to use it
}

# initialize only board specifics - reset, clock, adapter frequency
proc init_board {} {
    reset_config trst_and_srst trst_pulls_srst

    $_TARGETNAME configure -event reset-start {
        adapter speed 100
    }

    $_TARGETNAME configure -event reset-init {
        enable_fast_clock
        adapter speed 10000
    }
}

```

--------------------------------

### Configuring Multiple Chips in a Board

Source: https://openocd.org/doc/html/Config-File-Guidelines.html

This example demonstrates how to configure a board with multiple chips, each with potentially different settings like endianness. It shows how to set chip-specific variables and source target configuration files.

```tcl
# Chip #1: PXA270 for network side, big endian
set CHIPNAME network
set ENDIAN big
source [find target/pxa270.cfg]
# on return: _TARGETNAME = network.cpu
# other commands can refer to the "network.cpu" target.
$_TARGETNAME configure .... events for this CPU..

# Chip #2: PXA270 for video side, little endian
set CHIPNAME video
set ENDIAN little
source [find target/pxa270.cfg]
# on return: _TARGETNAME = video.cpu
# other commands can refer to the "video.cpu" target.
$_TARGETNAME configure .... events for this CPU..

# Chip #3: Xilinx FPGA for glue logic
set CHIPNAME xilinx
unset ENDIAN
source [find target/spartan3.cfg]

```

--------------------------------

### OpenOCD Target Memory Write Example

Source: https://openocd.org/doc/html/CPU-Configuration.html

Shows how to write data to a target's memory using the 'mww' command.

```tcl
str912.cpu    mww 0x1234 0x42
omap3530.cpu  mww 0x5555 123
```

--------------------------------

### Tcl Associative Array Example

Source: https://openocd.org/doc/html/Tcl-Scripting-API.html

Demonstrates setting and retrieving values from a Tcl associative array. The 'set foo' command without arguments returns all key-value pairs.

```tcl
>  set foo(me)  Duane
>  set foo(you) Oyvind
>  set foo(mouse) Micky
>  set foo(duck) Donald
```

```tcl
>  set foo
```

```tcl
me Duane you Oyvind mouse Micky duck Donald
```

```tcl
foreach { name value } [set foo] {
        puts "Name: $name, Value: $value"
}
```

--------------------------------

### Configure USB-Blaster VID/PID for Kolja Waschk's JTAG

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

Example of specifying the VID/PID for Kolja Waschk's USB JTAG device.

```openocd
adapter usb vid_pid 0x16C0 0x06AD
```

--------------------------------

### Include Interface and Board Configuration Files

Source: https://openocd.org/doc/html/OpenOCD-Project-Setup.html

This snippet shows the basic structure for including an interface configuration file and a board-specific configuration file. These two files often handle all necessary project setup.

```tcl
source [find interface/olimex-jtag-tiny.cfg]
source [find board/csb337.cfg]
```

--------------------------------

### TAP Identification Mismatch Example

Source: https://openocd.org/doc/html/Config-File-Guidelines.html

This output shows an example of a TAP identification mismatch error. It indicates the expected TAP ID and the one actually detected, helping to diagnose configuration issues.

```text
JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
                (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
ERROR:      got: mfg: 0x787, part: 0xf0f0, ver: 0x3

```

--------------------------------

### Start RTT TCP Server

Source: https://openocd.org/doc/html/General-Commands.html

Starts a TCP server on a specified port to expose a given RTT channel. Optionally, a message can be provided to be sent to a client upon connection.

```bash
rtt server start <port> <channel> [message]
```

--------------------------------

### Tcl Capture Command Example

Source: https://openocd.org/doc/html/Tcl-Scripting-API.html

Executes a command and captures its full log output along with the command's return value. Useful for debugging.

```tcl
> capture "reset init"
```

--------------------------------

### Reading Target Supply Voltage with ST-LINK

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

This example shows how to send a custom command to an ST-LINK adapter to read the target's supply voltage. It involves sending a specific byte sequence and interpreting the returned bytes.

```tcl
> st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0xf1 0x05 0x00 0x00 0x0b 0x08 0x00 0x00
```

--------------------------------

### Initialize eSi-RISC Trace Collection

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Initializes trace collection for eSi-RISC. This command must be run after any configuration changes. Existing trace buffer contents are overwritten when collection starts.

```tcl
esirisc trace init
```

--------------------------------

### Connect via UNIX Socket using remote_bitbang

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

Example configuration for connecting to a local process via UNIX sockets using a socket named 'mysocket'.

```openocd
adapter driver remote_bitbang
remote_bitbang port 0
remote_bitbang host mysocket
```

--------------------------------

### OpenOCD Autoprobing Output Example

Source: https://openocd.org/doc/html/TAP-Declaration.html

This output shows the results of OpenOCD's autoprobing, including discovered TAPs with their expected IDs and instruction register lengths. It also indicates when autoprobing might not work.

```text
clock speed 8 kHz
There are no enabled taps. AUTO PROBING MIGHT NOT WORK!!
AUTO auto0.tap - use "jtag newtap auto0 tap -expected-id 0x2b900f0f ..."
AUTO auto1.tap - use "jtag newtap auto1 tap -expected-id 0x07926001 ..."
AUTO auto2.tap - use "jtag newtap auto2 tap -expected-id 0x0b73b02f ..."
AUTO auto0.tap - use "... -irlen 4"
AUTO auto1.tap - use "... -irlen 4"
AUTO auto2.tap - use "... -irlen 6"
no gdb ports allocated as no target has been specified

```

--------------------------------

### Measure and Set Parallel Port Toggling Time

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

Example demonstrating how to measure the TCK toggling time using a logic analyzer and then configure the `parport toggling_time` setting accordingly. This helps in accurately setting the JTAG clock speed.

```bash
parport toggling_time 1000
adapter speed 500
```

```bash
parport toggling_time <measured nanoseconds>
```

--------------------------------

### Display CPU Targets

Source: https://openocd.org/doc/html/CPU-Configuration.html

Use the 'targets' command to display a table of all known CPU targets, including their name, type, endianness, TAP name, and state. This is useful for understanding the current debug setup.

```text
    TargetName         Type       Endian TapName            State
--  ------------------ ---------- ------ ------------------ ------------
 0* at91rm9200.cpu     arm920t    little at91rm9200.cpu     running
 1  MyTarget           cortex_m   little mychip.foo         tap-disabled

```

--------------------------------

### Translate Lauterbach Syntax to OpenOCD using a Procedure

Source: https://openocd.org/doc/html/Config-File-Guidelines.html

Shows how to translate configuration syntax from other tools, like Lauterbach, into OpenOCD syntax using a Tcl procedure. This example defines a `setc15` procedure to handle specific register settings.

```tcl
#   Lauterbach syntax(?)
#
#       Data.Set c15:0x042f %long 0x40000015
#
#   OpenOCD syntax when using procedure below.
#
#       setc15 0x01 0x00050078

proc setc15 {regs value} {
    global TARGETNAME

    echo [format "set p15 0x%04x, 0x%08x" $regs $value]

    arm mcr 15 [expr {($regs >> 12) & 0x7}]
        [expr {($regs >> 0) & 0xf}] [expr {($regs >> 4) & 0xf}]
        [expr {($regs >> 8) & 0x7}] $value
}


```

--------------------------------

### Expose RISC-V Custom Register Command Examples

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Shows how to use the 'expose_custom' command to expose RISC-V custom registers by their abstract command number or range, with optional user-defined names.

```tcl
# Expose one RISC-V custom register with number 0xc010 (0xc000 + 16)
# under the name "custom16":
$_TARGETNAME expose_custom 16

```

```tcl
# Expose a range of RISC-V custom registers with numbers 0xc010 .. 0xc018
# (0xc000+16 .. 0xc000+24) under the names "custom16" through "custom24":
$_TARGETNAME expose_custom 16-24

```

```tcl
# Expose one RISC-V custom register with number 0xc020 (0xc000 + 32) under
# user-defined name "custom_myregister":
$_TARGETNAME expose_custom 32=myregister

```

--------------------------------

### Configure ambiqmicro Flash Driver - Bank 1

Source: https://openocd.org/doc/html/Flash-Commands.html

This command configures the second flash bank (Bank 1) for Ambiq Micro Apollo microcontrollers. It is set up to start immediately after Bank 0 and has the same size.

```tcl
# Flash bank 1 - same size as bank0, starts after bank 0.
flash bank $_FLASHNAME ambiqmicro 0x00040000 0x00040000 0 0 \
           $_TARGETNAME
```

--------------------------------

### Configure Flash Bank with stmqspi Driver (Dual Mode)

Source: https://openocd.org/doc/html/Flash-Commands.html

Configures the QuadSPI/OctoSPI interface for external SPI flash devices on STMicroelectronics devices. This example shows dual flash mode configuration, mapping two devices to the same memory bank.

```tcl
flash bank $_FLASHNAME stmqspi 0x90000000 0 0 0 \
           $_TARGETNAME 0xA0001000
```

```tcl
flash bank $_FLASHNAME stmqspi 0x70000000 0 0 0 \
           $_TARGETNAME 0xA0001400
```

--------------------------------

### tpiu init command

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Initializes all registered TPIU and SWO objects.

```APIDOC
## tpiu init

### Description
Initialize all registered TPIU and SWO. The two commands are equivalent. These commands are used internally during initialization. They can be issued at any time after the initialization, too.

### Command
tpiu init
```

--------------------------------

### Start RTT Data Transfer

Source: https://openocd.org/doc/html/General-Commands.html

Starts the Real Time Transfer (RTT) interface. If the control block location is not already known, OpenOCD will begin searching for it.

```bash
rtt start
```

--------------------------------

### Set Kinetis NVM Partition for EEPROM Backup

Source: https://openocd.org/doc/html/Flash-Commands.html

Sets the NVM partition for FlexNVM devices. This example configures 16 KB for EEPROM backup, with two EEPROM blocks (1024 bytes each) and disables EEPROM content loading to FlexRAM on reset. Setting is only possible once after mass_erase.

```tcl
kinetis nvm_partition eebkp 16 1024 1024 off
```

--------------------------------

### Configure dw-spi Flash Driver using Jaguar2 Shortcut

Source: https://openocd.org/doc/html/Flash-Commands.html

This configuration uses the shortcut argument '-jaguar2' to simplify the setup of the dw-spi flash driver for MSCC Jaguar2 SoC family. It automatically sets the correct values for -freq, -simc, -spi_mst, and -if_owner_offset. A custom communication speed is also specified.

```tcl
flash bank $_FLASHNAME dw-spi 0x40000000 0x02000000 4 4 $_TARGETNAME -jaguar2 -speed 3000000
```

--------------------------------

### Configure External Flash with xcf

Source: https://openocd.org/doc/html/Flash-Commands.html

Initiates the FPGA loading procedure. Useful when the board lacks a dedicated 'configure' button.

```bash
xcf configure 0
```

--------------------------------

### Generic and Specific Target Initialization Procedures

Source: https://openocd.org/doc/html/Config-File-Guidelines.html

Demonstrates how to use the `init_targets` procedure for generic and specific target configurations. The generic file defines a base procedure, while the specific file sources it and overrides `init_targets` for specialized initialization.

```tcl
### generic_file.cfg ###

proc setup_my_chip {chip_name flash_size ram_size} {
    # basic initialization procedure ...
}

proc init_targets {} {
    # initializes generic chip with 4kB of flash and 1kB of RAM
    setup_my_chip MY_GENERIC_CHIP 4096 1024
}

### specific_file.cfg ###

source [find target/generic_file.cfg]

proc init_targets {} {
    # initializes specific chip with 128kB of flash and 64kB of RAM
    setup_my_chip MY_CHIP_WITH_128K_FLASH_64KB_RAM 131072 65536
}


```

--------------------------------

### Tcl FOR Command Implementation (Pseudo-code)

Source: https://openocd.org/doc/html/Tcl-Crash-Course.html

Demonstrates a C-level implementation of the Tcl FOR command, using helper functions to execute strings and evaluate expressions. Error handling is omitted for clarity.

```c
void Execute_AsciiString( void *interp, const char *string );

int Evaluate_AsciiExpression( void *interp, const char *string );

int
MyForCommand( void *interp,
              int argc,
              char **argv )
{
   if( argc != 5 ){
       SetResult( interp, "WRONG number of parameters");
       return ERROR;
   }

   // argv[0] = the ascii string just like C

   // Execute the start statement.
   Execute_AsciiString( interp, argv[1] );

   // Top of loop test
   for(;;){
        i = Evaluate_AsciiExpression(interp, argv[2]);
        if( i == 0 )
            break;

        // Execute the body
        Execute_AsciiString( interp, argv[3] );

        // Execute the LOOP part
        Execute_AsciiString( interp, argv[4] );
    }

    // Return no error
    SetResult( interp, "" );
    return SUCCESS;
}


```

--------------------------------

### MSP432 Flash Driver Configuration

Source: https://openocd.org/doc/html/Flash-Commands.html

Configures the MSP432 flash driver for Texas Instruments microcontrollers. Automatically recognizes flash parameters. Main program flash starts at 0, information flash on MSP432P4 starts at 0x200000.

```tcl
flash bank $_FLASHNAME msp432 0 0 0 0 $_TARGETNAME

```

--------------------------------

### Source Board Configuration File

Source: https://openocd.org/doc/html/Config-File-Guidelines.html

Include a board configuration file in your user config file using this command. Board files package board-specific initialization and configuration details.

```tcl
source [find board/FOOBAR.cfg]
```

--------------------------------

### Initialize Marvell QSPI Flash Driver

Source: https://openocd.org/doc/html/Flash-Commands.html

Initializes the Marvell QSPI flash driver, autodetecting flash size based on JEDEC IDs.

```tcl
flash bank $_FLASHNAME mrvlqspi 0x0 0 0 0 $_TARGETNAME 0x46010000
```

--------------------------------

### Get lpc2000 Part ID

Source: https://openocd.org/doc/html/Flash-Commands.html

Retrieves the four-byte part identifier for a specified lpc2000 flash bank.

```tcl
lpc2000 part_id _bank_
```

--------------------------------

### Initialize PSoC Acquisition Sequence (KitProg)

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

Use this command to indicate that a PSoC acquisition sequence is needed during adapter initialization. This sequence hard-resets the target device.

```bash
kitprog init_acquire_psoc
```

--------------------------------

### Create and Configure a Target

Source: https://openocd.org/doc/html/CPU-Configuration.html

This snippet demonstrates the typical steps for creating and configuring a CPU target in OpenOCD. It first creates a DAP, then a target, and finally configures its work area and event handlers.

```tcl
dap create mychip.dap -chain-position mychip.cpu
target create MyTarget cortex_m -dap mychip.dap
MyTarget configure -work-area-phys 0x08000 -work-area-size 8096
MyTarget configure -event reset-deassert-pre { jtag_rclk 5 }
MyTarget configure -event reset-init { myboard_reinit }
```

--------------------------------

### Get the Name of the Current Debug Adapter

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

This command returns the name of the debug adapter driver that OpenOCD is currently using.

```tcl
adapter name
```

--------------------------------

### Display Flash Bank Summary

Source: https://openocd.org/doc/html/Flash-Commands.html

Prints a one-line summary of each device configured with 'flash bank'. The devices are numbered starting from zero.

```tcl
flash banks
```

--------------------------------

### Include Tcl Configuration Files

Source: https://openocd.org/doc/html/Tcl-Crash-Course.html

Use the 'source' command with 'find' to include Tcl configuration files. 'find' searches an internal path for the specified FILENAME.

```tcl
source [find FILENAME]
```

--------------------------------

### Configure Bus Pirate Serial Port

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

Specifies the serial port's filename for the Bus Pirate driver. Example uses /dev/ttyUSB0.

```bash
buspirate port /dev/ttyUSB0
```

--------------------------------

### Display Help Text

Source: https://openocd.org/doc/html/General-Commands.html

Prints help text for all commands when no parameter is provided. Otherwise, it prints help text containing the specified string. Not all commands have associated help text.

```bash
help _[string]_
```

--------------------------------

### Connect via TCP with Remote Sleep using remote_bitbang

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

Example configuration for connecting remotely via TCP with remote sleep enabled.

```openocd
adapter driver remote_bitbang
remote_bitbang port 3335
remote_bitbang host foobar
remote_bitbang use_remote_sleep on
```

--------------------------------

### Connect via TCP using remote_bitbang

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

Example configuration for connecting remotely via TCP to a host named 'foobar' on port 3335.

```openocd
adapter driver remote_bitbang
remote_bitbang port 3335
remote_bitbang host foobar
```

--------------------------------

### Specify USB Adapter by VID and PID

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

Use this command to select a specific USB adapter based on its Vendor ID (VID) and Product ID (PID). Multiple pairs can be provided to match different adapters.

```openocd
adapter usb vid_pid 0xc251 0xf001 0x0d28 0x0204
```

--------------------------------

### Get Value of a Bit-Field in an ARC Register

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Use `arc get-reg-field` to retrieve the value of a specific bit-field from a register that has been defined as a 'struct' type.

```tcl
arc get-reg-field "DBGR" "DB"
```

--------------------------------

### OpenOCD Help Command

Source: https://openocd.org/doc/html/Running.html

Displays all available command-line options for the OpenOCD server. Use this to understand the various parameters you can control.

```bash
openocd --help
```

--------------------------------

### Get Cortex-A Cache Information

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Displays information about the target caches for Cortex-A processors. This command provides insights into the cache hierarchy and status.

```text
cortex_a cache_info
```

--------------------------------

### Get Current Time in Milliseconds

Source: https://openocd.org/doc/html/General-Commands.html

Returns the current time in milliseconds since the Epoch. This is useful for calculating delays within Tcl scripts.

```bash
ms
```

--------------------------------

### Disassemble Code

Source: https://openocd.org/doc/html/CPU-Configuration.html

Disassembles instructions starting at a given address. Requires Capstone library. Supports specifying instruction set and dumping supported lists.

```tcl
$target_name disassemble _address [count [instruction_set]]_
```

```tcl
$target_name disassemble _list_
```

--------------------------------

### Configure eSi-RISC Trace Buffer

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Sets up an in-memory buffer for trace data collection. The wrap option allows continuous collection by overwriting old data once the buffer is full.

```text
esirisc trace buffer address size [ wrap]
```

--------------------------------

### Get RTT Channels as Tcl List

Source: https://openocd.org/doc/html/General-Commands.html

Returns a list of all RTT channels and their properties formatted as a Tcl list, which is easily manipulable within scripts.

```bash
rtt channellist
```

--------------------------------

### Configure Flash Bank with lpcspifi Driver

Source: https://openocd.org/doc/html/Flash-Commands.html

Initializes the SPIFI peripheral on NXP LPC43xx and LPC18xx families for external SPI flash devices. Requires a working area of at least 1kB.

```tcl
flash bank $_FLASHNAME lpcspifi 0x14000000 0 0 0 $_TARGETNAME
```

--------------------------------

### Configure Internal Flash for CC26xx

Source: https://openocd.org/doc/html/Flash-Commands.html

This command configures the internal flash for Texas Instruments CC13xx and CC26xx microcontrollers. The flash bank starts at address 0.

```tcl
flash bank $_FLASHNAME cc26xx 0 0 0 0 $_TARGETNAME
```

--------------------------------

### Clear DAP AP CSW Pattern Bit

Source: https://openocd.org/doc/html/TAP-Declaration.html

Clears a specific bit in the CSW pattern while leaving other bits intact. This example clears the SPROT bit.

```bash
set CSW_SPROT [expr {1 << 30}]
samv.dap apcsw 0 $CSW_SPROT
```

--------------------------------

### Get AT91SAM3 Chip Information

Source: https://openocd.org/doc/html/Flash-Commands.html

The 'at91sam3 info' command attempts to display detailed information about the AT91SAM3 microcontroller, including chip ID and clock configuration.

```tcl
at91sam3 info

```

--------------------------------

### Source a Target Configuration File

Source: https://openocd.org/doc/html/Config-File-Guidelines.html

Board configuration files can include target configuration files using the 'source' command. This allows for modularity and reuse of chip-specific settings.

```tcl
source [find target/FOOBAR.cfg]
```

--------------------------------

### Get OpenOCD Version

Source: https://openocd.org/doc/html/General-Commands.html

Returns a string identifying the version of the OpenOCD server. If the 'git' option is provided, it returns the git version obtained at compile time.

```bash
version [git]
```

--------------------------------

### DAP Configuration Parameters

Source: https://openocd.org/doc/html/TAP-Declaration.html

Optional parameters for `dap create` command, specifying DAP type (ADIv5/ADIv6), ignoring system power-up acknowledge bits, and debug port/instance IDs for SWD DPv2 multidrop.

```tcl
-adiv5
```

```tcl
-adiv6
```

```tcl
-ignore-syspwrupack
```

```tcl
-dp-id number
```

```tcl
-instance-id number
```

--------------------------------

### Get Register Values

Source: https://openocd.org/doc/html/General-Commands.html

Retrieves register values from the target and returns them as a Tcl dictionary. Use the '-force' option to bypass caching and read directly from the target.

```tcl
get_reg {pc sp}
```

--------------------------------

### Configure NPCX Flash Bank (Default FIU)

Source: https://openocd.org/doc/html/Flash-Commands.html

Configures an NPCX flash bank using the default FIU version. The flash bank starts at address 0x64000000.

```tcl
flash bank $_FLASHNAME npcx 0x64000000 0 0 0 $_TARGETNAME
```

--------------------------------

### Create Intel FPGA Device

Source: https://openocd.org/doc/html/PLD_002fFPGA-Commands.html

Creates a new PLD device for an Intel FPGA of the Cyclone III family. Specify the TAP name and family for the device.

```bash
pld create cycloneiii.pld intel -chain-position cycloneiii.tap -family cycloneiii
```

--------------------------------

### Erase Flash Sectors by Number

Source: https://openocd.org/doc/html/Flash-Commands.html

Erase a range of sectors within a specified flash bank. Sector numbering starts at 0. 'last' can specify the end of the bank.

```openocd
flash erase_sector num first last
```

--------------------------------

### Configure Trace Trigger Stop Condition

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Specifies the condition that halts trace collection. Similar to start conditions, this allows precise control over the trace capture duration.

```text
esirisc trace trigger stop ( condition) [stop_data stop_mask]
```

--------------------------------

### Connect GDB to OpenOCD via Pipe

Source: https://openocd.org/doc/html/GDB-and-OpenOCD.html

Connects GDB to OpenOCD using pipes, allowing GDB to start and stop OpenOCD. Logs OpenOCD output to a file.

```gdb
target extended-remote | \
       openocd -c "gdb port pipe; log_output openocd.log"
```

--------------------------------

### Configure ATSAME5 Bootloader Size

Source: https://openocd.org/doc/html/Flash-Commands.html

Manage the bootloader size configuration stored in the User Page. Specify size in bytes; the nearest larger protection size is used. Setting to 0 disables protection. Settings take effect on MCU reset.

```tcl
atsame5 bootloader
atsame5 bootloader 16384

```

--------------------------------

### Configure ATSAME5 Flash Bank

Source: https://openocd.org/doc/html/Flash-Commands.html

This command sets up a flash bank for ATSAME5 microcontrollers, specifying memory regions and target names.

```tcl
flash bank $_FLASHNAME atsame5 0x00000000 0 1 1 $_TARGETNAME

```

--------------------------------

### Configure Orion NAND Device

Source: https://openocd.org/doc/html/Flash-Commands.html

Sets up the NAND flash device for Orion controllers. Requires the address of the controller.

```shell
nand device orion 0xd8000000
```

--------------------------------

### Configure NPCX Flash Bank with FIU Version

Source: https://openocd.org/doc/html/Flash-Commands.html

Configures an NPCX flash bank. The flash bank starts at address 0x64000000. An optional parameter sets the FIU version.

```tcl
flash bank $_FLASHNAME npcx 0x64000000 0 0 0 $_TARGETNAME npcx_v2.fiu
```

--------------------------------

### Set Software Breakpoint

Source: https://openocd.org/doc/html/General-Commands.html

Sets a software breakpoint on code execution starting at a specified address for a given length. Hardware breakpoints can be set using 'hw' or 'hw_ctx' options.

```cli
bp address [asid] len [hw | hw_ctx]
```

--------------------------------

### Enable TPIU Trace

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Enables the TPIU or SWO using previously configured parameters. The adapter is also configured and enabled to receive trace data. This command takes effect after 'init'.

```tcl
stm32l1.tpiu enable
```

--------------------------------

### NOR Flash Boot Utility Script

Source: https://openocd.org/doc/html/OpenOCD-Project-Setup.html

This script is useful for booting from NOR flash after initial RAM-based testing. It writes a standard U-Boot version to NOR flash, ensuring it performs its own low-level initialization, and then reboots the target.

```tcl
proc newboot { } {
    # Reset, leaving the CPU halted. The "reset-init" event
    # proc gives faster access to the CPU and to NOR flash;
    # "reset halt" would be slower.
    reset init

    # Write standard version of U-Boot into the first two
    # sectors of NOR flash ... the standard version should
    # do the same lowlevel init as "reset-init".
    flash protect 0 0 1 off
    flash erase_sector 0 0 1
    flash write_bank 0 u-boot.bin 0x0
    flash protect 0 0 1 on

    # Reboot from scratch using that new boot loader.
    reset run
}
```

--------------------------------

### Set JTAG Adapter Speed

Source: https://openocd.org/doc/html/FAQ.html

Use this command to set the JTAG adapter speed. The value is in kHz. For example, to set the speed to 1.234MHz, use 'adapter speed 1234'.

```bash
# Example: 1.234MHz
adapter speed 1234

```

--------------------------------

### Configure Trace Trigger Delay

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Sets a delay in clock cycles for starting or stopping trace collection relative to a trigger event. This allows capturing events immediately before or after a specific trigger.

```text
esirisc trace trigger delay ( trigger) [cycles]
```

--------------------------------

### Source OpenOCD Interface Configuration

Source: https://openocd.org/doc/html/Debug-Adapter-Configuration.html

Use this command to load the configuration for a specific debug adapter. Ensure the interface file path is correct.

```tcl
source [find interface/olimex-jtag-tiny.cfg]
```

--------------------------------

### Configure Trace Trigger Start Condition

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Defines the condition that initiates trace collection. Various conditions like PC match, load/store addresses, exceptions, or external signals can be used.

```text
esirisc trace trigger start ( condition) [start_data start_mask]
```

--------------------------------

### Configure Target Event for GDB Flash Erase Start

Source: https://openocd.org/doc/html/GDB-and-OpenOCD.html

Set a target event to configure the target before GDB programming begins. This ensures the target is in the correct state for flash operations.

```openocd
$_TARGETNAME configure -event gdb-flash-erase-start BODY

```

--------------------------------

### Specify Multiple Configuration Files

Source: https://openocd.org/doc/html/Running.html

Use the -f option to specify one or more configuration files for OpenOCD. The order matters as the first matching file found will be used.

```bash
openocd -f config1.cfg -f config2.cfg -f config3.cfg
```

--------------------------------

### Expose RISC-V CSR Command Examples

Source: https://openocd.org/doc/html/Architecture-and-Core-Commands.html

Demonstrates how to use the 'riscv expose_csrs' command to expose specific Control and Status Registers (CSRs) by number or range, with optional custom naming.

```tcl
# Expose a single RISC-V CSR number 128 under the name "csr128":
riscv expose_csrs 128

```

```tcl
# Expose multiple RISC-V CSRs 128..132 under names "csr128" through "csr132":
riscv expose_csrs 128-132

```

```tcl
# Expose a single RISC-V CSR number 1996 under custom name "csr_myregister":
riscv expose_csrs 1996=myregister

```
Tokens:
Raw