O que é o GDB no mundo STM32 e como montar o “pipeline” de depuração
Table of Contents
- O que é o GDB no mundo STM32 e como montar o “pipeline” de depuração
- Comandos Fundamentais do GDB no STM32 (Breakpoints, Step, Memória e Registradores)
- 2.1 Breakpoints: o ponto de controle do firmware
- 2.2 Execução controlada: continue, step, next, finish
- 2.3 Inspeção de variáveis
- 2.4 Watchpoints: parar quando algo mudar
- 2.5 Registradores do Cortex-M
- 2.6 Leitura e escrita de memória
- 2.7 Backtrace e stack
- 2.8 Comandos monitor (OpenOCD)
- 2.9 Comandos de controle geral do GDB
- Casos Reais de Depuração em STM32 com GDB
- 3.1 Debug de HardFault no Cortex-M (passo a passo real)
- 3.2 Detectando Stack Overflow
- 3.3 Debug de Interrupção que trava o sistema
- 3.4 Debug de variáveis sendo alteradas por DMA
- 3.5 Depuração com FreeRTOS
- 3.6 Debug de código otimizado (-O2 / -O3)
- 3.7 Arquivo .gdbinit para automatizar sessão
- 3.8 Diagnóstico de travamento por clock ou PLL
- 3.9 Quando o STM32 não conecta mais
- Depuração de Periféricos, Barramentos e Técnicas Profissionais com GDB no STM32
- 4.1 Depuração de GPIO via registradores
- 4.2 Depuração de USART (UART)
- 4.3 Depuração de ADC + DMA
- 4.4 Depuração de Timer (TIM)
- 4.5 Inspeção de mapa de memória completo
- 4.6 Debug de barramento e alinhamento
- 4.7 Profiling simples com GDB
- 4.8 Macros e automação avançada no GDB
- 4.9 Integração com VSCode (modo profissional)
- 4.10 Técnicas Profissionais de Depuração
- Debug Avançado: Bootloader, Dual-Core, SWO/ITM, Semihosting e Estratégias para Produção
- 5.1 Depuração de Bootloader (vetor de interrupção e salto para aplicação)
- 5.2 Debug em STM32 Dual-Core (ex: STM32H7)
- 5.3 Semihosting
- 5.4 SWO e ITM (Tracing em tempo real)
- 5.5 Debug de firmware já em produção
- 5.6 Debug de sistema com Watchdog
- 5.7 Estratégias para sistemas OTA
- 5.8 Debug sem parar o sistema (modo observacional)
- 5.9 Técnicas de Engenharia de Depuração
- Encerramento Técnico
- Laboratório Prático Completo de Depuração com STM32 + GDB (Do Zero ao HardFault)
- 6.1 Código com erro proposital
- 6.2 Executando passo a passo
- 6.3 Investigando o HardFault profissionalmente
- 6.4 Corrigindo e validando
- 6.5 Segundo laboratório: Stack Overflow real
- 6.6 Terceiro laboratório: Corrupção silenciosa
- 6.7 Analisando registradores de fault (SCB)
- 6.8 Laboratório com periférico: GPIO que não responde
- 6.9 Método Profissional de Debug (Modelo Mental)
- 6.10 Consolidação: Checklist de Depuração STM32
- GDB + STM32 — Cheat Sheet Profissional de Depuração
- 1️⃣ Inicialização Padrão da Sessão
- 2️⃣ Controle de Execução
- 3️⃣ Breakpoints
- 4️⃣ Watchpoints (Detecção de Corrupção)
- 5️⃣ Inspeção de Variáveis
- 6️⃣ Registradores Cortex-M
- 7️⃣ Leitura e Escrita de Memória
- 8️⃣ HardFault — Procedimento Profissional
- 9️⃣ Verificação de Stack
- 🔟 Debug de Periféricos
- 1️⃣1️⃣ FreeRTOS
- 1️⃣2️⃣ Bootloader Debug
- 1️⃣3️⃣ Dual Core (STM32H7)
- 1️⃣4️⃣ Semihosting
- 1️⃣5️⃣ SWO / ITM
- 1️⃣6️⃣ Macros Úteis
- 1️⃣7️⃣ Debug de Clock
- 1️⃣8️⃣ Diagnóstico Rápido (Checklist de Emergência)
- 🧠 Modelo Mental Profissional
Table of Contents
- O que é o GDB no mundo STM32 e como montar o “pipeline” de depuração
- Comandos Fundamentais do GDB no STM32 (Breakpoints, Step, Memória e Registradores)
- 2.1 Breakpoints: o ponto de controle do firmware
- 2.2 Execução controlada: continue, step, next, finish
- 2.3 Inspeção de variáveis
- 2.4 Watchpoints: parar quando algo mudar
- 2.5 Registradores do Cortex-M
- 2.6 Leitura e escrita de memória
- 2.7 Backtrace e stack
- 2.8 Comandos monitor (OpenOCD)
- 2.9 Comandos de controle geral do GDB
- Casos Reais de Depuração em STM32 com GDB
- 3.1 Debug de HardFault no Cortex-M (passo a passo real)
- 3.2 Detectando Stack Overflow
- 3.3 Debug de Interrupção que trava o sistema
- 3.4 Debug de variáveis sendo alteradas por DMA
- 3.5 Depuração com FreeRTOS
- 3.6 Debug de código otimizado (-O2 / -O3)
- 3.7 Arquivo .gdbinit para automatizar sessão
- 3.8 Diagnóstico de travamento por clock ou PLL
- 3.9 Quando o STM32 não conecta mais
- Depuração de Periféricos, Barramentos e Técnicas Profissionais com GDB no STM32
- 4.1 Depuração de GPIO via registradores
- 4.2 Depuração de USART (UART)
- 4.3 Depuração de ADC + DMA
- 4.4 Depuração de Timer (TIM)
- 4.5 Inspeção de mapa de memória completo
- 4.6 Debug de barramento e alinhamento
- 4.7 Profiling simples com GDB
- 4.8 Macros e automação avançada no GDB
- 4.9 Integração com VSCode (modo profissional)
- 4.10 Técnicas Profissionais de Depuração
- Debug Avançado: Bootloader, Dual-Core, SWO/ITM, Semihosting e Estratégias para Produção
- 5.1 Depuração de Bootloader (vetor de interrupção e salto para aplicação)
- 5.2 Debug em STM32 Dual-Core (ex: STM32H7)
- 5.3 Semihosting
- 5.4 SWO e ITM (Tracing em tempo real)
- 5.5 Debug de firmware já em produção
- 5.6 Debug de sistema com Watchdog
- 5.7 Estratégias para sistemas OTA
- 5.8 Debug sem parar o sistema (modo observacional)
- 5.9 Técnicas de Engenharia de Depuração
- Encerramento Técnico
- Laboratório Prático Completo de Depuração com STM32 + GDB (Do Zero ao HardFault)
- 6.1 Código com erro proposital
- 6.2 Executando passo a passo
- 6.3 Investigando o HardFault profissionalmente
- 6.4 Corrigindo e validando
- 6.5 Segundo laboratório: Stack Overflow real
- 6.6 Terceiro laboratório: Corrupção silenciosa
- 6.7 Analisando registradores de fault (SCB)
- 6.8 Laboratório com periférico: GPIO que não responde
- 6.9 Método Profissional de Debug (Modelo Mental)
- 6.10 Consolidação: Checklist de Depuração STM32
- GDB + STM32 — Cheat Sheet Profissional de Depuração
- 1️⃣ Inicialização Padrão da Sessão
- 2️⃣ Controle de Execução
- 3️⃣ Breakpoints
- 4️⃣ Watchpoints (Detecção de Corrupção)
- 5️⃣ Inspeção de Variáveis
- 6️⃣ Registradores Cortex-M
- 7️⃣ Leitura e Escrita de Memória
- 8️⃣ HardFault — Procedimento Profissional
- 9️⃣ Verificação de Stack
- 🔟 Debug de Periféricos
- 1️⃣1️⃣ FreeRTOS
- 1️⃣2️⃣ Bootloader Debug
- 1️⃣3️⃣ Dual Core (STM32H7)
- 1️⃣4️⃣ Semihosting
- 1️⃣5️⃣ SWO / ITM
- 1️⃣6️⃣ Macros Úteis
- 1️⃣7️⃣ Debug de Clock
- 1️⃣8️⃣ Diagnóstico Rápido (Checklist de Emergência)
- 🧠 Modelo Mental Profissional
Quando você depura um firmware STM32 “de verdade”, quase nunca é só o GDB sozinho. O que funciona bem na prática é um encadeamento de peças: o seu binário ELF com símbolos de depuração, o GDB (cliente), um servidor de debug (normalmente OpenOCD ou o servidor do ST-LINK), e o hardware de debug (ST-LINK/J-LINK) falando SWD (Serial Wire Debug) ou JTAG com o microcontrolador. O GDB é quem dá os comandos (parar, continuar, inspecionar memória, ler registradores, dar step, colocar breakpoints), mas ele conversa com o alvo por meio de um “servidor GDB” (GDB server) que traduz essas intenções para transações no barramento de debug do chip.
O primeiro ponto que separa uma depuração tranquila de uma sofrida é o seu build. Em STM32, o ideal é compilar com símbolos e com otimizações amigáveis à depuração. Na prática, isso significa incluir -g e preferir -Og (em vez de -O2/-O3) durante a fase de debug, porque -Og tenta manter o código legível para o depurador sem virar um firmware “tartaruga”. Em projetos com CMake, Makefile ou no próprio STM32CubeIDE, a ideia é a mesma: gerar um ELF (não apenas .bin/.hex) e garantir que ele carregue DWARF de debug. Sem ELF com símbolos, o GDB até conecta, mas você perde o principal: nomes de variáveis, linhas de código e backtraces confiáveis.
A segunda base é decidir qual servidor você vai usar. Com STM32, o caminho mais comum (e bem compatível com GDB puro) é OpenOCD. Ele sobe um servidor local que expõe uma porta TCP para o GDB (tipicamente :3333) e, em paralelo, expõe uma porta telnet (:4444) para comandos próprios do OpenOCD. Esse detalhe é importante porque, durante a depuração, você vai misturar dois “dialetos”: comandos do GDB e comandos “monitor” (que o GDB repassa ao servidor). Em outras palavras, quando você digita monitor reset halt, isso não é GDB nativo; é o GDB dizendo para o OpenOCD executar um reset e parar o core.
A seguir está o fluxo mínimo, bem “pé no chão”, que você usa em qualquer STM32 com ST-LINK via SWD, assumindo que você já tem arm-none-eabi-gdb (ou gdb-multiarch) e OpenOCD instalados, e que seu projeto já gerou firmware.elf.
- Em um terminal, suba o OpenOCD (exemplo genérico; o arquivo de target muda conforme a família STM32 e o probe):
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg
Se tudo estiver ok, você verá o OpenOCD dizendo que abriu a porta do GDB server (geralmente 3333). Agora, em outro terminal, você entra com o GDB apontando para o seu ELF:
arm-none-eabi-gdb firmware.elf
Dentro do GDB, o “ritual” inicial que mais evita dor de cabeça é: conectar no servidor remoto, garantir reset/halt, configurar break no main, carregar o binário (quando apropriado) e rodar:
target extended-remote :3333
monitor reset halt
break main
load
continue
Aqui entram três observações práticas que você vai agradecer depois. Primeiro, target extended-remote é útil porque permite alguns recursos a mais (como reconectar melhor e usar run em certos cenários), mas target remote também funciona na maioria dos casos. Segundo, load grava flash via servidor de debug; se você já gravou o firmware por outro meio (CubeProgrammer, por exemplo) e só quer depurar, você pode pular o load e apenas anexar e rodar. Terceiro, monitor reset halt é o “seguro de vida” quando o firmware está resetando rápido, travando o barramento, mexendo em clock ou entrando em low-power agressivo; você força o core a ficar parado antes do estrago acontecer.
Casos de uso típicos que esse setup já resolve
Um caso muito comum é “meu firmware dá boot e reseta em loop, não consigo nem ver a primeira mensagem na UART”. Com o fluxo acima, você conecta, dá monitor reset halt, coloca break main (ou até break Reset_Handler/break SystemInit se precisar pegar antes), e então continue para ir soltando o código sob controle. Outro caso clássico é “minha interrupção está disparando e eu não sei quem mexe nessa variável”. Assim que você tiver o core sob controle, você coloca breakpoints e watchpoints (a gente chega neles nas próximas seções) e transforma a depuração em um processo determinístico, em vez de “chute”.
