openocd

Attach OpenOCD session to a board with a configuration file

$ openocd [[-f|--file]] [config_file.cfg]

$ openocd [[-f|--file]] [config_file1.cfg] [[-f|--file]] [config_file2.cfg]

$ openocd [[-f|--file]] [config_file.cfg] [[-c|--command]] "[command]"

$ openocd [[-s|--search]] [path/to/search] [[-f|--file]] [config_file.cfg]

$ target extended-remote localhost

$ ls /usr/local/share/openocd/scripts

openocd [ options ] [ arguments ]

Common Usage:
openocd -f interface.cfg -f target.cfg

-f file
    Executes the specified file as an OpenOCD configuration script. Used to load interface and target definitions.

-s dir
    Adds dir to the list of directories where OpenOCD searches for configuration scripts.

-c command
    Executes the specified command directly, overriding any commands in config files or for interactive use.

-l file
    Redirects all OpenOCD output messages (logs) to the specified file instead of standard output.

-d [level]
    Sets the debug message verbosity level (0-3), with 3 being the most verbose. Default is 1.

--help
    Displays a brief help message with available command-line options and exits.

--version
    Shows the OpenOCD version information and exits.

OpenOCD (Open On-Chip Debugger) is essential open-source software providing powerful debugging and in-system programming capabilities for embedded systems. It bridges the gap between your development machine's debugger (like GDB) and the embedded target hardware, typically via a JTAG or SWD debug adapter.

It supports an extensive range of microcontrollers (including ARM, RISC-V, MIPS) and various debug probes, enabling critical development tasks such as flashing firmware, setting breakpoints, stepping through code, inspecting memory, and reading CPU registers. OpenOCD is a fundamental tool for embedded developers, crucial for prototyping, debugging, and production programming workflows.

Configuration Dependency: OpenOCD's functionality heavily relies on correctly written and selected configuration files (.cfg) that match your specific debug probe and target hardware.

Initial Setup Complexity: Can be challenging for newcomers, often requiring precise hardware connections and understanding of JTAG/SWD protocols.

Hardware Reliability: Issues frequently stem from poor electrical connections, incorrect wiring, or insufficient power to the target device.

OpenOCD primarily operates as a GDB server, enabling standard GDB clients to connect via TCP/IP (default port 3333). This seamless integration facilitates debugging from command-line GDB or integrated development environments (IDEs).

OpenOCD's behavior is defined by .cfg files. These files are typically split into interface configurations (describing the debug probe, e.g., ftdi.cfg) and target configurations (describing the microcontroller or board, e.g., stm32f4.cfg). Users often combine these or create custom ones.

Beyond GDB, OpenOCD offers a Telnet server (default port 4444) and a TCL server (default port 6666) for direct command execution, scripting, and advanced control of the debugging session. This allows for automated testing or complex flashing sequences.

OpenOCD was initiated by Dominic Rath in 2005, primarily to support ARM processor debugging. Its open-source nature and early support for cost-effective FT2232-based debug adapters quickly propelled its adoption within the embedded development community. Over time, contributions from a global community expanded its support to a vast array of microcontrollers (ARM, RISC-V, MIPS), diverse debug interfaces (JTAG, SWD, OCDLink, etc.), and various development boards, establishing it as a de-facto standard for open-source embedded debugging.

gdb(1): The GNU Debugger, commonly used as a client connecting to OpenOCD's GDB server., make(1): A build automation tool often used in conjunction with embedded projects compiled for debugging., arm-none-eabi-gdb: A specific cross-GDB variant for ARM bare-metal targets, frequently used with OpenOCD.