GDB na Bancada: Download Oficial, Instalação e Como Ler uma Placa Travada

O GDB é o programa que, ligado ao OpenOCD e a um ST-Link de trinta reais, para o microcontrolador no ponto exato em que ele travou e mostra o que a placa estava fazendo na hora da pane: a função, a linha, o endereço que deu errado. Baixamos as versões oficiais, conferimos os checksums e montamos uma pane de verdade num Cortex-M3 para você ver a leitura inteira, comando por comando. Aqui está o download certo, a instalação por sistema, o primeiro diagnóstico e os cinco erros que mais travam a bancada. Última verificação: 8 de outubro de 2026.

O que é o GDB e para que ele serve na bancada

GDB é o GNU Debugger; a versão que importa aqui é a arm-none-eabi-gdb, compilada para falar com processadores Arm Cortex-M. Ele não encosta na placa sozinho: quem segura o fio é um servidor — OpenOCD, J-Link GDB Server, pyOCD — que abre a porta 3333 no seu computador. O GDB se conecta nessa porta e manda: para o processador, lê registradores, lê memória, mostra em que linha do código o chip estava.

Para quem repara, a utilidade é uma só e vale muito: a placa que “congela”. Um aparelho que trava sem motivo aparente quase sempre caiu num HardFault — o processador tentou ler um endereço que não existe, ou executar uma instrução inválida — e ficou preso no tratamento de erro. Com o GDB, são seis comandos até o endereço culpado.

Download oficial: três fontes e a versão que cada uma entrega

Existem três lugares honestos para pegar o arm-none-eabi-gdb, e eles entregam versões diferentes. Medimos cada uma hoje, baixando e rodando o binário:

Três detalhes que custam tempo. Primeiro: a página clássica de downloads da Arm mudou de lugar. Desde agosto de 2026 o endereço antigo em developer.arm.com redireciona para o GitLab da Arm, e os arquivos vivem no servidor de artefatos da empresa, numa listagem simples por versão. Os quatro pacotes da 15.3.Rel1 — Windows x86-64 em .zip, Linux x86-64, Linux Arm64 e macOS Apple Silicon em .tar.xz — têm data de 16 de julho de 2026. Nesse servidor não há instalador para Windows, só o .zip.

Segundo: o servidor não mostra checksum na página, mas entrega no cabeçalho HTTP. Um curl -sI no endereço do arquivo devolve a linha x-checksum-sha256; o valor publicado para o pacote Linux x86-64 é 563bebb2…9b5fa, e o arquivo que baixamos deu exatamente esse SHA-256. No xPack cada arquivo tem um .sha ao lado, e o pacote Linux que baixamos bateu com o publicado.

Terceiro: no Ubuntu não existe pacote gdb-arm-none-eabi desde a versão 16.04 — a última foi a 7.10, de 2015 — e instalar gcc-arm-none-eabi não traz o depurador. O caminho é o gdb-multiarch, que conhece todas as arquiteturas e, testado aqui contra o mesmo alvo, resolveu a mesma pane com a mesma saída.

Instalação, sistema por sistema

Linux (Debian, Ubuntu e derivados). O caminho de 10 segundos e o caminho oficial:

sudo apt install gdb-multiarch openocd        # caminho curto
# ou, com o pacote da Arm:
sudo mkdir -p /opt/arm && sudo tar xJf arm-gnu-toolchain-x86_64-arm-none-eabi.tar.xz -C /opt/arm
echo 'export PATH=/opt/arm/arm-gnu-toolchain-15.3.rel1-x86_64-arm-none-eabi/bin:$PATH' >> ~/.bashrc

A pegadinha está no segundo binário do pacote da Arm. Desde a 15.2.Rel1, todo pacote traz dois GDBs: o arm-none-eabi-gdb, sem Python, e o arm-none-eabi-gdb-py, com Python para scripts. A nota de versão da Arm avisa que o -py foi compilado contra Python 3.8.20 no Linux, 3.8.10 no Windows e 3.9.7 no macOS. Nenhuma distribuição atual tem o 3.8 — e aqui, num Ubuntu 24.04, ele morre na largada com libpython3.8.so.1.0: cannot open shared object file. O xPack resolveu isso levando o Python 3.13 dentro da pasta: o arm-none-eabi-gdb-py3 dele abriu de primeira.

Windows. Baixe o .zip (Arm ou xPack), descompacte numa pasta sem acento e sem espaço, como C:arm-gnu, e acrescente a subpasta bin ao PATH. O depurador não precisa de driver: quem fala com o ST-Link é o OpenOCD, e o driver é assunto do guia do ST-Link.

macOS. Mesmo roteiro, com o .tar.xz da Arm para Apple Silicon ou o xPack. Em qualquer sistema, o teste de vida é arm-none-eabi-gdb --version: a primeira linha diz a versão e a origem do pacote.

O primeiro diagnóstico: a placa travou, onde?

Para mostrar o roteiro inteiro sem depender de uma placa específica, escrevemos um firmware de 40 linhas que lê um “sensor” num endereço onde não existe nada — um ponteiro apontando para o lugar errado, o defeito mais comum do mundo real — e o rodamos num Cortex-M3 emulado pelo QEMU, que abre a mesma porta GDB que o OpenOCD abriria com a placa de verdade. A sequência de comandos é idêntica; só muda a porta (QEMU usa 1234, OpenOCD usa 3333).

Em um terminal, o servidor; no outro, o GDB com o arquivo .elf do firmware:

openocd -f interface/stlink.cfg -f target/stm32f1x.cfg      # terminal 1
arm-none-eabi-gdb firmware.elf                              # terminal 2
(gdb) target extended-remote :3333
(gdb) monitor reset halt
(gdb) break *HardFault_Handler
(gdb) continue

Quando a placa cai na pane, o GDB para e a leitura começa. O que vem abaixo é a saída real da nossa sessão:

Leia a captura de cima para baixo. O bt (backtrace) mostra a pilha de chamadas: main, linha 21, chamou ler_sensor, linha 12, e dali o chip caiu na exceção — a linha <signal handler called> é o GDB avisando que desenrolou a exceção para você. Muitas vezes isso já basta: função e linha.

Quando não basta, os três registradores de falha do Cortex-M contam o resto. CFSR = 0x8200: o bit 9 diz “erro de barramento preciso” e o bit 15 diz “o endereço em BFAR é válido”. HFSR = 0x40000000: o bit 30 diz que a falha foi escalada para HardFault — começou como BusFault. BFAR = 0x60000000: o endereço que o chip tentou ler e não existia. Os três ficam em endereços fixos (0xE000ED28, 0xE000ED2C e 0xE000ED38) em qualquer Cortex-M3, M4 ou M7, de qualquer fabricante.

O último bloco é o truque que funciona mesmo sem o código-fonte: ao entrar numa exceção, o Cortex-M empilha oito palavras — r0, r1, r2, r3, r12, lr, pc e xpsr, nessa ordem. O x/8xw $sp as mostra; a sétima é o PC na hora da pane, 0x76. Daí info line *0x76 traduz para “linha 12 do firmware.c” e x/i 0x76 mostra a instrução: ldr r3, [r3, #0], uma leitura pelo ponteiro em r3 — que valia 0x60000000, exatamente o BFAR. Para fechar, frame 2 sobe até a função culpada; tentar print *p ali devolve Cannot access memory at address 0x60000000, a mesma recusa que o chip deu.

Os cinco problemas que mais aparecem

1. “could not connect: Connection timed out” ou “Connection refused”. O GDB não achou o servidor: o OpenOCD não está rodando no outro terminal, ou você usou a porta errada — a 3333 é a do GDB, a 4444 é a do telnet.

2. “libpython3.8.so.1.0: cannot open shared object file”. Você abriu o arm-none-eabi-gdb-py da Arm num sistema sem Python 3.8 — isto é, em qualquer sistema atual. Use o binário sem -py, que faz tudo o que este guia mostra, ou o -py3 do xPack. Discussões como a do chamado 69939 do Arch Linux giram há anos em torno disso: o GDB com Python fica preso à versão de Python com que foi compilado.

3. “No symbol table is loaded. Use the “file” command.” Você abriu o .bin em vez do .elf: o .bin é só o conteúdo da flash, sem nomes de função nem números de linha. Sem o .elf — caso do aparelho do cliente — ainda dá para ler registradores, memória e o quadro empilhado; só não há tradução para linha de código.

4. “Remote ‘g’ packet reply is too long”. O servidor mandou mais registradores do que o GDB esperava: quase sempre você abriu o gdb do próprio sistema, que só entende x86, em vez do arm-none-eabi-gdb ou do gdb-multiarch. Com o binário certo, set architecture armv7 antes do target costuma resolver; o resto são servidores antigos, como nos relatos do fórum da Segger.

5. “<optimized out>”, “No symbol table info available” e breakpoint com duas localizações. O firmware foi compilado com otimização (-O2, -Os). Recompilamos o nosso assim e vimos os três sintomas de uma vez: ler_sensor foi embutida em dois lugares e a variável local sumiu. Para depurar, compile com -Og -g3; para produção, guarde o .elf de cada versão gravada.

E um bônus que derruba o iniciante: não use run num alvo remoto. O manual do GDB é direto — no modo target remote, “o comando run não é suportado”. Na nossa sessão, o run fez o QEMU encerrar e o GDB respondeu “Target disconnected”. Para pôr a placa a andar, continue; para recomeçar do zero, monitor reset halt.

Perguntas frequentes

O GDB funciona sem o OpenOCD? Não sozinho: ele sempre precisa de um servidor que fale com o adaptador. OpenOCD, J-Link GDB Server, pyOCD e o próprio QEMU são servidores; o GDB é o cliente.

Preciso da versão com Python? Para o diagnóstico deste guia, não. O Python só entra quando você usa extensões — visualizadores de tarefas de um RTOS, scripts de automação. Se precisar, o -py3 do xPack é o que roda sem instalar nada.

Qual versão baixar hoje? No Linux, o gdb-multiarch do apt; nos três sistemas, xPack ou o pacote da Arm. O GDB mais novo é o 18.1, de 25 de setembro de 2026, mas ainda não chegou a nenhum desses pacotes — e nada aqui depende dele.

O resumo que cabe na bancada

O GDB transforma “a placa trava” em “a placa tenta ler o endereço 0x60000000 na linha 12”. O download certo é o xPack ou o pacote da Arm, os dois com o mesmo GDB 16.3.90; no Linux, o gdb-multiarch do sistema dá conta. Fuja do binário -py da Arm, abra sempre o .elf, não use run, e guarde os três endereços de falha: 0xE000ED28, 0xE000ED2C e 0xE000ED38.

No próximo guia, o servidor que dispensa o OpenOCD para Cortex-M: o pyOCD — instalação por pip, pacotes de chips da própria CMSIS e a mesma porta 3333 que o GDB já conhece.

Se a sua dúvida seguinte for por onde começar a ler a placa que está esperando na bancada, o Mapa da Placa é o nosso material de leitura de placa; vale conhecer.