Bem-vindo ao OpenOCD

O OpenOCD fornece suporte de programação e depuração no chip com uma arquitetura em camadas de interface JTAG e suporte TAP, incluindo:

• (X)SVF para facilitar varredura de limite automatizada e programação de FPGA/CPLD;
• suporte a alvos de depuração (ex.: ARM, MIPS): execução passo a passo, breakpoints/watchpoints, perfilamento gprof, etc;
• drivers de chip flash (ex.: CFI, NAND, flash interno);
• interpretador Tcl embutido para script fácil.

Várias interfaces de rede estão disponíveis para interagir com o OpenOCD: telnet, Tcl e GDB. O servidor GDB permite que o OpenOCD funcione como um "alvo remoto" para depuração em nível de código-fonte de sistemas embarcados usando o programa GNU GDB (e outros que falam o protocolo GDB, ex.: IDA Pro).

Este arquivo README contém uma visão geral dos seguintes tópicos:

• instruções de início rápido,
• como encontrar e construir mais documentação do OpenOCD,
• lista do hardware suportado,
• o processo de instalação e compilação,
• dicas de empacotamento.

Início rápido para os impacientes

Se você tem uma placa popular, basta iniciar o OpenOCD com sua configuração, ex.:

openocd -f board/stm32f4discovery.cfg

Se você está conectando um adaptador específico com algum alvo específico, você precisa incluir as configurações da interface jtag e do alvo, ex.:

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

Após a inicialização do OpenOCD, conecte o GDB com

(gdb) target extended-remote localhost:3333

Instalando o OpenOCD

A maneira mais fácil de instalar o OpenOCD é através do gerenciador de pacotes do seu sistema operacional.

• Debian / Ubuntu

  root@kitploit:~

  sudo apt install openocd
  

• Fedora

  root@kitploit:~

  sudo dnf install openocd
  

• macOS (via Homebrew)

  root@kitploit:~

  brew install open-ocd
  

• Windows (via MSYS2)

  root@kitploit:~

  pacman -S mingw-w64-x86_64-openocd
  

Esses pacotes são frequentemente mais estáveis que a versão mais recente do Git (bleeding-edge), onde o desenvolvimento ativo ocorre. "Empacotadores" criam versões binárias do OpenOCD após os desenvolvedores publicarem novas versões do código-fonte. Versões antigas do OpenOCD não são adequadas para diagnosticar problemas na versão atual. Os usuários devem manter contato com seus mantenedores de distribuição ou fornecedores de interface para garantir que atualizações adequadas sejam fornecidas regularmente.

Se você usar um desses pacotes binários, deve entrar em contato com o Empacotador para obter suporte ou versões binárias mais recentes. Os desenvolvedores do OpenOCD não fornecem suporte direto para binários empacotados.

Uma Nota para Empacotadores do OpenOCD

Você é um EMPACOTADOR do OpenOCD se você:

• Vende dongles e inclui binários pré-construídos;
• Fornece ferramentas ou IDEs (uma solução de desenvolvimento que integra o OpenOCD);
• Cria pacotes (ex.: arquivos RPM ou DEB para uma distribuição GNU/Linux).

Como EMPACOTADOR, você receberá os primeiros relatos da maioria dos problemas. Quando você corrigir esses problemas para seus usuários, sua solução pode ajudar a prevenir centenas (senão milhares) de outras perguntas de outros usuários.

Se algo não funcionar para você, por favor, trabalhe para informar os desenvolvedores do OpenOCD como melhorar o sistema ou a documentação para evitar problemas futuros, e acompanhe para nos ajudar a garantir que o problema seja totalmente resolvido em nossas versões futuras.

Dito isso, os desenvolvedores do OpenOCD também gostariam que você seguisse algumas sugestões:

• Envie patches, incluindo arquivos de configuração, upstream, participe das discussões;
• Ative todas as opções que o OpenOCD suporta, mesmo aquelas não relacionadas ao seu hardware específico;
• Use o driver de adaptador de interface 'ftdi' para dispositivos baseados em FTDI.

Documentação do OpenOCD

Além da documentação na árvore, os manuais mais recentes podem ser visualizados online nos seguintes URLs:

• Guia do Usuário do OpenOCD: http://openocd.org/doc/html/index.html

• Manual do Desenvolvedor do OpenOCD: http://openocd.org/doc/doxygen/html/index.html

Eles refletem as versões de desenvolvimento mais recentes, então a seção a seguir introduz como construir a documentação completa a partir do pacote.

Para mais informações, consulte esses documentos ou entre em contato com os desenvolvedores inscrevendo-se na lista de e-mail dos desenvolvedores do OpenOCD: [email protected]

Construindo a Documentação do OpenOCD

Por padrão, o processo de compilação do OpenOCD prepara a documentação no "formato Info" e a instala da maneira padrão, para que info openocd possa acessá-la.

Além disso, o Guia do Usuário do OpenOCD pode ser produzido nos seguintes formatos diferentes:

Se PDFVIEWER estiver definido, isso cria e visualiza o Guia do Usuário em PDF.

make pdf && ${PDFVIEWER} doc/openocd.pdf

Se HTMLVIEWER estiver definido, isso cria e visualiza o Guia do Usuário em HTML.

make html && ${HTMLVIEWER} doc/openocd.html/index.html

O Manual do Desenvolvedor do OpenOCD contém informações sobre a arquitetura interna e outros detalhes sobre o código:

Nota: certifique-se de que o doxygen está instalado, digite doxygen --version

make doxygen && ${HTMLVIEWER} doxygen/index.html

Hardware suportado

Adaptadores JTAG

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 supported), 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.

Alvos de depuração

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.

Drivers de flash

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.

Compilando o OpenOCD

O arquivo INSTALL contém instruções genéricas para executar configure e compilar o código-fonte do OpenOCD. Esse arquivo é fornecido por padrão para todos os pacotes GNU autotools. Se você não está familiarizado com o GNU autotools, então deve ler essas instruções primeiro.

Nota: se o arquivo INSTALL não estiver presente, significa que você está usando o código-fonte de um branch de desenvolvimento, não de uma versão do OpenOCD. Nesse caso, siga as instruções 'Compilando o OpenOCD' abaixo e o arquivo será criado pelo primeiro comando ./bootstrap.

O restante deste documento tenta fornecer algumas instruções para aqueles que procuram uma instalação rápida.

Dependências do OpenOCD

GCC ou Clang é atualmente necessário para compilar o OpenOCD. Os desenvolvedores começaram a aplicar avisos de código rigorosos (-Wall, -Werror, -Wextra, e mais) e usar recursos específicos do C99: funções inline, inicializadores nomeados, mistura de declarações com código, e outros truques. Embora possa ser possível usar outros compiladores, eles devem ser relativamente modernos e podem exigir extensão de suporte para remover condicionalmente extensões específicas do GCC.

Você também precisará de:

• make
• libtool
• pkg-config >= 0.23 or pkgconf
• libjim >= 0.79

Adicionalmente, para compilar a partir do Git:

• autoconf >= 2.69
• automake >= 1.14
• texinfo >= 5.0

Drivers de adaptador USB opcionais precisam de libusb-1.0.

Drivers de adaptador de interface USB-Blaster, ASIX Presto e OpenJTAG opcionais precisam da biblioteca libftdi.

Driver de adaptador CMSIS-DAP opcional precisa da biblioteca HIDAPI.

Driver de adaptador linuxgpiod opcional precisa da biblioteca libgpiod.

Driver de adaptador J-Link opcional precisa da biblioteca libjaylink.

Desmontagem ARM opcional precisa da biblioteca capstone.

Script de desenvolvimento checkpatch opcional precisa de:

• perl
• python
• python-ply
• pymarkdownlnt

Compilando o OpenOCD

Para compilar o OpenOCD, use a seguinte sequência de comandos:

./bootstrap
./configure [opções]
make
sudo make install

O comando bootstrap só é necessário ao compilar a partir do repositório Git. A etapa configure gera os Makefiles necessários para compilar o OpenOCD, geralmente com uma ou mais opções fornecidas a ele. A primeira etapa 'make' compilará o OpenOCD e colocará o executável final em './src/'. A etapa final (opcional), make install, coloca todos os arquivos no local necessário.

Para ver a lista de todas as opções suportadas, execute ./configure --help

Opções de Compilação Cruzada

A compilação cruzada é suportada da maneira padrão do autotools, você só precisa especificar o triplet do alvo de compilação cruzada na opção --host, ex.: para compilar cruzadamente para Windows 32-bit com MinGW no Debian:

./configure --host=i686-w64-mingw32 [opções]

Para fazer o pkg-config funcionar bem para compilação cruzada, você pode precisar de um script wrapper adicional conforme descrito em https://autotools.io/pkgconfig/cross-compiling.html.

Isso é necessário para informar ao pkg-config onde procurar pelas bibliotecas alvo das quais o OpenOCD depende. Alternativamente, você pode especificar as variáveis de ambiente *_CFLAGS e *_LIBS diretamente, veja ./configure --help para detalhes.

Para um script mais ou menos completo que faz tudo isso para você, veja contrib/cross-build.sh.

Dongles de Porta Paralela

Se você quiser acessar a porta paralela usando a interface PPDEV, deve especificar ambos --enable-parport e --enable-parport-ppdev, já que a última opção é uma opção para o driver parport.

O mesmo vale para a opção --enable-parport-giveio, você deve usar ambos --enable-parport e --enable-parport-giveio se quiser usar giveio em vez do método de acesso à porta paralela ioperm.

Obtendo o OpenOCD do Git

Você pode baixar a versão atual do Git com um cliente Git de sua escolha do repositório principal: git://git.code.sf.net/p/openocd/code

Você pode preferir usar um espelho:

• http://repo.or.cz/r/openocd.git
• git://repo.or.cz/openocd.git

Usando o cliente de linha de comando Git, você pode usar o seguinte comando para configurar uma cópia local do repositório atual (certifique-se de que não há um diretório chamado "openocd" no diretório atual):

git clone git://git.code.sf.net/p/openocd/code openocd

Então você pode atualizá-lo conforme sua conveniência usando git pull.

Há também uma interface gitweb, que você pode usar para navegar pelo repositório ou baixar snapshots arbitrários usando HTTP: http://repo.or.cz/w/openocd.git.

Snapshots são tarballs comprimidos da árvore de fontes, cerca de 1,3 MBytes cada no momento desta escrita.

Delegação de permissões

Executar o OpenOCD com permissões de root/administrativo é fortemente desencorajado por razões de segurança.

Para dispositivos USB em GNU/Linux, você deve usar o arquivo contrib/60-openocd.rules. Ele provavelmente pertence a algum lugar em /etc/udev/rules.d, mas consulte a documentação do seu sistema operacional para ter certeza. Não se esqueça de se adicionar ao grupo "plugdev".

Para adaptadores de porta paralela em GNU/Linux e FreeBSD, altere as permissões do nó de dispositivo "ppdev" (parport* ou ppi*) de acordo.

Para adaptadores de porta paralela no Windows, você precisa executar install_giveio.bat (também é possível usar "ioperm" com Cygwin) para dar permissões a usuários comuns para acessar os registros "LPT" diretamente.