openocd-org/openocdOffizieller OpenOCD-Nur-Lese-Mirror (keine Pull-Requests)
OpenOCD bietet Unterstützung für On-Chip-Programmierung und Debugging mit einer geschichteten Architektur aus JTAG-Schnittstelle und TAP-Unterstützung, einschließlich:
Für die Interaktion mit OpenOCD stehen mehrere Netzwerkschnittstellen zur Verfügung: Telnet, Tcl und GDB. Der GDB-Server ermöglicht es OpenOCD, als "Remote-Ziel" für das Debugging auf Quellcode-Ebene eingebetteter Systeme mit dem GNU GDB-Programm (und anderen, die das GDB-Protokoll sprechen, z. B. IDA Pro) zu fungieren.
Diese README-Datei enthält eine Übersicht über folgende Themen:
Wenn Sie ein gängiges Board haben, starten Sie OpenOCD einfach mit dessen Konfiguration, z. B.:
openocd -f board/stm32f4discovery.cfg
Wenn Sie einen bestimmten Adapter mit einem spezifischen Ziel verbinden, müssen Sie sowohl die JTAG-Schnittstellen- als auch die Zielkonfiguration einbinden, z. B.:
openocd -f interface/ftdi/jtagkey2.cfg -c "transport select jtag" \
-f target/ti/calypso.cfg
openocd -f interface/stlink.cfg -c "transport select swd" \
-f target/stm32l0.cfg
Nach dem Start von OpenOCD verbinden Sie GDB mit
(gdb) target extended-remote localhost:3333
Der einfachste Weg, OpenOCD zu installieren, ist über den Paketmanager Ihres Betriebssystems.
Debian / Ubuntu
sudo apt install openocd
Fedora
sudo dnf install openocd
macOS (via Homebrew)
brew install open-ocd
Windows (via MSYS2)
pacman -S mingw-w64-x86_64-openocd
Diese Pakete sind oft stabiler als der neueste Git-Mainline-Zweig, in dem die aktive Entwicklung stattfindet. "Paketersteller" erstellen binäre Veröffentlichungen von OpenOCD, nachdem die Entwickler neue Quellcode-Versionen veröffentlicht haben. Ältere OpenOCD-Versionen sind nicht geeignet, um Probleme in der aktuellen Version zu diagnostizieren. Benutzer sollten mit ihren Distributionsbetreuern oder Schnittstellenanbietern in Kontakt bleiben, um sicherzustellen, dass regelmäßig geeignete Updates bereitgestellt werden.
Wenn Sie eines dieser binären Pakete verwenden, müssen Sie sich für Support oder neuere binäre Versionen an den Paketersteller wenden. Die OpenOCD-Entwickler bieten keine direkte Unterstützung für gepackte Binärdateien.
Sie sind ein PAKETIERER von OpenOCD, wenn Sie:
Als PAKETIERER werden Sie die ersten Berichte über die meisten Probleme erhalten. Wenn Sie diese Probleme für Ihre Benutzer beheben, kann Ihre Lösung dazu beitragen, Hunderte (wenn nicht Tausende) von Fragen anderer Benutzer zu verhindern.
Wenn etwas bei Ihnen nicht funktioniert, informieren Sie bitte die OpenOCD-Entwickler darüber, wie das System oder die Dokumentation verbessert werden kann, um zukünftige Probleme zu vermeiden, und helfen Sie uns, sicherzustellen, dass das Problem in unseren zukünftigen Veröffentlichungen vollständig behoben wird.
Trotzdem möchten die OpenOCD-Entwickler, dass Sie einige Vorschläge befolgen:
Zusätzlich zur im Source-Baum enthaltenen Dokumentation können die neuesten Handbücher online unter den folgenden URLs eingesehen werden:
OpenOCD-Benutzerhandbuch: http://openocd.org/doc/html/index.html
OpenOCD-Entwicklerhandbuch: http://openocd.org/doc/doxygen/html/index.html
Diese spiegeln die neuesten Entwicklungsversionen wider. Der folgende Abschnitt erläutert, wie die vollständige Dokumentation aus dem Paket erstellt wird.
Weitere Informationen finden Sie in diesen Dokumenten oder kontaktieren Sie die Entwickler, indem Sie die OpenOCD-Entwickler-Mailingliste abonnieren: [email protected]
Standardmäßig bereitet der OpenOCD-Build-Prozess die Dokumentation im
"Info-Format" vor und installiert sie auf dem üblichen Weg, sodass info openocd
darauf zugreifen kann.
Zusätzlich kann das OpenOCD-Benutzerhandbuch in den folgenden Formaten erstellt werden:
Wenn PDFVIEWER gesetzt ist, wird das PDF-Benutzerhandbuch erstellt und angezeigt.
make pdf && ${PDFVIEWER} doc/openocd.pdf
Wenn HTMLVIEWER gesetzt ist, wird das HTML-Benutzerhandbuch erstellt und angezeigt.
make html && ${HTMLVIEWER} doc/openocd.html/index.html
Das OpenOCD-Entwicklerhandbuch enthält Informationen über die interne Architektur und andere Details zum Code:
Hinweis: Stellen Sie sicher, dass doxygen installiert ist, geben Sie doxygen --version ein.
make doxygen && ${HTMLVIEWER} doxygen/index.html
AM335x, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432, BCM2835, Bus Blaster, Buspirate, Cadence DPI, Cadence vdebug, Chameleon, CMSIS-DAP, Cortino, Cypress KitProg, DENX, Digilent JTAG-SMT2, DLC 5, DLP-USB1232H, embedded projects, Espressif USB JTAG Programmer, eStick, FlashLINK, FlossJTAG, Flyswatter, Flyswatter2, FTDI FT232R, Gateworks, Hoegl, ICDI, ICEBear, J-Link, JTAG VPI, JTAGkey, JTAGkey2, JTAG-lock-pick, KT-Link, Linux GPIOD, Lisa/L, LPC1768-Stick, Mellanox rshim, MiniModule, NGX, Nuvoton Nu-Link, Nu-Link2, NXHX, NXP IMX GPIO, OOCDLink, Opendous, OpenJTAG, Openmoko, OpenRD, OSBDM, Presto, Redbee, Remote Bitbang, RLink, SheevaPlug devkit, Stellaris evkits, ST-LINK (SWO-Tracing unterstützt), STM32-PerformanceStick, STR9-comStick, sysfsgpio, Tigard, TI XDS110, TUMPA, Turtelizer, ULINK, USB-A9260, USB-Blaster, USB-JTAG, USBprog, VPACLink, VSLLink, Wiggler, XDS100v2, Xilinx XVC/PCIe, Xverve.
ARM: AArch64, ARM11, ARM7, ARM9, Cortex-A/R (v7-A/R), Cortex-M (ARMv{6/7/8}-M), FA526, Feroceon/Dragonite, XScale. ARCv2, AVR32, DSP563xx, DSP5680xx, EnSilica eSi-RISC, EJTAG (MIPS32, MIPS64), ESP32, ESP32-S2, ESP32-S3, Intel Quark, LS102x-SAP, RISC-V, ST STM8, Xtensa.
ADUC702x, AT91SAM, AT91SAM9 (NAND), ATH79, ATmega128RFA1, Atmel SAM, AVR, CFI, DSP5680xx, EFM32, EM357, eSi-RISC, eSi-TSMC, EZR32HG, FM3, FM4, Freedom E SPI, GD32, i.MX31, Kinetis, LPC8xx/LPC1xxx/LPC2xxx/LPC541xx, LPC2900, LPC3180, LPC32xx, LPCSPIFI, Marvell QSPI, MAX32, Milandr, MXC, NIIET, nRF51, nRF52 , NuMicro, NUC910, Nuvoton NPCX, onsemi RSL10, Orion/Kirkwood, PIC32mx, PSoC4/5LP/6, Raspberry RP2040, Renesas RPC HF and SH QSPI, S3C24xx, S3C6400, SiM3x, SiFive Freedom E, Stellaris, ST BlueNRG, STM32, STM32 QUAD/OCTO-SPI for Flash/FRAM/EEPROM, STMSMI, STR7x, STR9x, SWM050, TI CC13xx, TI CC26xx, TI CC32xx, TI MSP432, Winner Micro w600, Xilinx XCF, XMC1xxx, XMC4xxx.
Die Datei INSTALL enthält allgemeine Anweisungen zum Ausführen von configure
und zum Kompilieren des OpenOCD-Quellcodes. Diese Datei wird standardmäßig für
alle GNU-Autotools-Pakete bereitgestellt. Wenn Sie mit den
GNU-Autotools nicht vertraut sind, sollten Sie diese Anweisungen zuerst lesen.
Hinweis: Wenn die Datei INSTALL nicht vorhanden ist, verwenden Sie den
Quellcode aus einem Entwicklungszweig, nicht aus einer OpenOCD-Veröffentlichung.
Folgen Sie in diesem Fall den Anweisungen unter 'Kompilieren von OpenOCD' unten, und
die Datei wird durch den ersten Befehl ./bootstrap erstellt.
Der Rest dieses Dokuments versucht, einige Anweisungen für diejenigen zu geben, die eine Schnellinstallation wünschen.
GCC oder Clang wird derzeit zum Erstellen von OpenOCD benötigt. Die Entwickler haben begonnen, strenge Code-Warnungen (-Wall, -Werror, -Wextra, und mehr) durchzusetzen und C99-spezifische Funktionen zu verwenden: Inline-Funktionen, benannte Initialisierer, Mischen von Deklarationen mit Code und andere Tricks. Auch wenn es möglich ist, andere Compiler zu verwenden, müssen diese einigermaßen modern sein und könnten eine erweiterte Unterstützung erfordern, um GCC-spezifische Erweiterungen bedingt zu entfernen.
Sie benötigen außerdem:
Zusätzlich für die Erstellung aus Git:
Optionale USB-basierte Adaptertreiber benötigen libusb-1.0.
Optionale USB-Blaster-, ASIX-Presto- und OpenJTAG-Schnittstellenadaptertreiber benötigen die libftdi-Bibliothek.
Optionale CMSIS-DAP-Adaptertreiber benötigen die HIDAPI-Bibliothek.
Optionaler linuxgpiod-Adaptertreiber benötigt die libgpiod-Bibliothek.
Optionaler J-Link-Adaptertreiber benötigt die libjaylink-Bibliothek.
Optionale ARM-Disassemblierung benötigt die capstone-Bibliothek.
Optionale Entwicklungsskripte für checkpatch benötigen:
Um OpenOCD zu erstellen, verwenden Sie die folgende Befehlssequenz:
./bootstrap
./configure [options]
make
sudo make install
Der Befehl bootstrap ist nur erforderlich, wenn Sie aus dem Git-Repository erstellen.
Der Schritt configure erzeugt die Makefiles, die zum Erstellen von OpenOCD erforderlich sind, normalerweise
mit einer oder mehreren Optionen.
Der erste 'make'-Schritt erstellt OpenOCD und platziert die endgültige ausführbare Datei in './src/'.
Der letzte (optionale) Schritt, make install, platziert alle Dateien am
erforderlichen Ort.
Um die Liste aller unterstützten Optionen anzuzeigen, führen Sie ./configure --help aus.
Cross-Compiling wird auf die übliche Autotools-Weise unterstützt; Sie müssen lediglich das Cross-Compile-Target-Triplet in der --host-Option angeben, z. B. für das Cross-Build für Windows 32-bit mit MinGW auf Debian:
./configure --host=i686-w64-mingw32 [options]
Damit pkg-config beim Cross-Compiling gut funktioniert, benötigen Sie möglicherweise ein zusätzliches Wrapper-Skript, wie unter https://autotools.io/pkgconfig/cross-compiling.html beschrieben.
Dies ist erforderlich, um pkg-config mitzuteilen, wo die Zielbibliotheken zu finden sind,
von denen OpenOCD abhängt. Alternativ können Sie die Umgebungsvariablen
*_CFLAGS und *_LIBS direkt angeben, siehe ./configure --help für Details.
Ein mehr oder weniger vollständiges Skript, das all dies für Sie erledigt, finden Sie unter contrib/cross-build.sh.
Wenn Sie auf den Parallelport über die PPDEV-Schnittstelle zugreifen möchten,
müssen Sie sowohl --enable-parport als auch --enable-parport-ppdev angeben, da
die letztere Option eine Option für den Parport-Treiber ist.
Das Gleiche gilt für die Option --enable-parport-giveio; Sie müssen
sowohl die Option --enable-parport als auch --enable-parport-giveio verwenden,
wenn Sie giveio anstelle der ioperm-Parallelport-Zugriffsmethode verwenden möchten.
Sie können die aktuelle Git-Version mit einem Git-Client Ihrer
Wahl aus dem Haupt-Repository herunterladen: git://git.code.sf.net/p/openocd/code
Sie bevorzugen möglicherweise einen Spiegel:
Mit dem Git-Befehlszeilenclient könnten Sie den folgenden Befehl verwenden, um eine lokale Kopie des aktuellen Repositorys zu erstellen (stellen Sie sicher, dass sich kein Verzeichnis namens "openocd" im aktuellen Verzeichnis befindet):
git clone git://git.code.sf.net/p/openocd/code openocd
Dann können Sie dies nach Belieben mit git pull aktualisieren.
Es gibt auch eine gitweb-Oberfläche, mit der Sie entweder das Repository durchsuchen oder beliebige Schnappschüsse über HTTP herunterladen können: http://repo.or.cz/w/openocd.git.
Schnappschüsse sind komprimierte Tarballs des Quellbaums mit jeweils etwa 1,3 MB Größe.
Das Ausführen von OpenOCD mit Root-Administratorrechten wird aus Sicherheitsgründen dringend empfohlen.
Für USB-Geräte unter GNU/Linux sollten Sie die Datei contrib/60-openocd.rules verwenden. Sie gehört wahrscheinlich in /etc/udev/rules.d, aber konsultieren Sie die Dokumentation Ihres Betriebssystems, um sicherzugehen. Vergessen Sie nicht, sich selbst zur Gruppe "plugdev" hinzuzufügen.
Für Parallelport-Adapter unter GNU/Linux und FreeBSD ändern Sie bitte die Berechtigungen Ihres "ppdev"- (parport* oder ppi*) Geräteknotens entsprechend.
Für Parport-Adapter unter Windows müssen Sie install_giveio.bat ausführen (alternativ kann "ioperm" mit Cygwin verwendet werden), um normalen Benutzern Berechtigungen zum direkten Zugriff auf die "LPT"-Register zu gewähren.