OpenOCD + GDB
Flash & Debug STM32 from the CLI

# Debian / Ubuntu (distro build; fine for STM32L4)
sudo apt install openocd gdb-multiarch gcc-arm-none-eabi

# macOS
brew install open-ocd arm-none-eabi-gdb arm-none-eabi-gcc

# verify — need OpenOCD 0.11+ for ST-Link V3 and modern L4+ flash
openocd --version
arm-none-eabi-gdb --version

# interface first (the probe), then target (the chip)
openocd -f interface/stlink.cfg -f target/stm32l4x.cfg

# stm32l4x.cfg covers the WHOLE L4 / L4+ family incl. the STM32L4R5.
# The flash driver auto-probes size + bank layout over SWD.
#
# Expected startup log:
#  Info : STLINK V3J13M4 (API v3) VID:PID 0483:374E
#  Info : Target voltage: 3.285000
#  Info : stm32l4x.cpu: Cortex-M4 r0p1 processor detected
#  Info : starting gdb server for stm32l4x.cpu on 3333
#  Info : Listening on port 3333 for gdb connections
# Leave this running — it is now your GDB server. Ctrl-C to stop.

# -c runs an OpenOCD command; use it to set ports before init
openocd -f interface/stlink.cfg -f target/stm32l4x.cfg \
    -c "gdb_port 3333" \
    -c "telnet_port 4444" \
    -c "tcl_port 6666"

# expose the gdb server to other machines (default binds to localhost only)
    -c "bindto 0.0.0.0"

# headless flashing only — no gdb server, no telnet
    -c "gdb_port disabled" -c "telnet_port disabled"

# Symptom without this: "Error: libusb_open() failed ... LIBUSB_ERROR_ACCESS"
sudo cp /usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

# add yourself to plugdev, then LOG OUT / IN (or replug the board)
sudo usermod -aG plugdev $USER

#include <stdint.h>

/* NUCLEO-L4R5ZI: LD1 (green) = PC7 */
#define RCC_AHB2ENR  (*(volatile uint32_t *)0x4002104C)  /* GPIO port clocks */
#define GPIOC_MODER  (*(volatile uint32_t *)0x48000800)  /* PC pin modes     */
#define GPIOC_BSRR   (*(volatile uint32_t *)0x48000818)  /* PC atomic set/rst*/
#define LED          7u

static void delay(volatile uint32_t n) { while (n--) __asm__ volatile ("nop"); }

int main(void)
{
    RCC_AHB2ENR |= (1u << 2);              /* GPIOCEN: enable GPIOC clock  */
    GPIOC_MODER &= ~(3u << (LED * 2));     /* clear the 2 mode bits        */
    GPIOC_MODER |=  (1u << (LED * 2));     /* 01 = general-purpose output  */

    for (;;) {
        GPIOC_BSRR = (1u << LED);          /* BS7: drive PC7 high → LED on  */
        delay(400000);
        GPIOC_BSRR = (1u << (LED + 16));   /* BR7: drive PC7 low  → LED off */
        delay(400000);
    }
}

#include <stdint.h>

extern uint32_t _sidata, _sdata, _edata, _sbss, _ebss, _estack;
int  main(void);

void Reset_Handler(void)
{
    uint32_t *s = &_sidata, *d = &_sdata;
    while (d < &_edata) *d++ = *s++;         /* copy .data flash → RAM */
    for (d = &_sbss; d < &_ebss;) *d++ = 0;    /* zero .bss              */
    main();
    for (;;) { }                             /* main() never returns   */
}

void Default_Handler(void) { for (;;) { } }

typedef void (*vector_t)(void);

/* First 16 core vectors are enough to boot and to debug. */
__attribute__((section(".isr_vector"), used))
const vector_t g_vectors[] = {
    (vector_t)(&_estack),   /* 0x00 initial MSP  */
    Reset_Handler,          /* 0x04 reset        */
    Default_Handler,        /* NMI               */
    Default_Handler,        /* HardFault         */
    Default_Handler,        /* MemManage         */
    Default_Handler,        /* BusFault          */
    Default_Handler,        /* UsageFault        */
    0, 0, 0, 0,             /* reserved          */
    Default_Handler,        /* SVCall            */
    Default_Handler,        /* DebugMonitor      */
    0,                      /* reserved          */
    Default_Handler,        /* PendSV            */
    Default_Handler,        /* SysTick           */
};

ENTRY(Reset_Handler)

_estack = 0x200A0000;        /* top of 640 KB SRAM (0x20000000 + 640K) */

MEMORY
{
    FLASH (rx)  : ORIGIN = 0x08000000, LENGTH = 2048K
    RAM   (rwx) : ORIGIN = 0x20000000, LENGTH = 640K
}

SECTIONS
{
    .isr_vector : { KEEP(*(.isr_vector)) } > FLASH

    .text : {
        *(.text*)
        *(.rodata*)
    } > FLASH

    _sidata = LOADADDR(.data);
    .data : {
        _sdata = .;
        *(.data*)
        _edata = .;
    } > RAM AT > FLASH

    .bss : {
        _sbss = .;
        *(.bss*)
        *(COMMON)
        _ebss = .;
    } > RAM
}

# STM32L4R5 = Cortex-M4 with single-precision FPU → fpv4-sp-d16 / hard ABI
# -O0 -g3 gives 1:1 line stepping and full macro info for debugging
arm-none-eabi-gcc \
    -mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard \
    -O0 -g3 -Wall -ffreestanding -nostdlib \
    -T stm32l4r5.ld startup.c main.c -o blink.elf

# derive raw + Intel-HEX images from the ELF
arm-none-eabi-objcopy -O binary blink.elf blink.bin
arm-none-eabi-objcopy -O ihex   blink.elf blink.hex
arm-none-eabi-size blink.elf
#    text    data     bss     dec     hex filename
#     ~90       0       0      90      5a blink.elf

# program <file> [verify] [reset] [exit] [offset]
# ELF/HEX carry their own load address → no offset needed
openocd -f interface/stlink.cfg -f target/stm32l4x.cfg \
    -c "program blink.elf verify reset exit"

# A raw .bin has NO address — you MUST pass the flash base 0x08000000
openocd -f interface/stlink.cfg -f target/stm32l4x.cfg \
    -c "program blink.bin verify reset exit 0x08000000"

openocd -f interface/stlink.cfg -f target/stm32l4x.cfg \
    -c "init" \
    -c "reset halt" \
    -c "flash write_image erase blink.hex" \
    -c "verify_image blink.hex" \
    -c "reset run" \
    -c "shutdown"

# flash write_image [erase] [unlock] <file> [offset] [type]
#   erase  → erase the sectors the image covers first (required!)
#   unlock → also clear write protection if set

telnet localhost 4444
# Open On-Chip Debugger
> reset halt                         # stop the core at the reset vector
> flash probe 0                      # report detected flash: size, banks, page size
> flash write_image erase blink.hex  # erase + program
> verify_image blink.hex             # read back & compare
> mdw 0x08000000 4                   # dump 4 words at the vector table
> reg                                # dump core registers (r0..pc, xPSR)
> reset run                          # run the freshly-flashed firmware
> exit                               # close the telnet session (server stays up)

# Terminal A already runs: openocd -f interface/stlink.cfg -f target/stm32l4x.cfg
arm-none-eabi-gdb -q blink.elf

# connect to OpenOCD's gdb server. Use EXTENDED-remote so you can
# reset / rerun and stay attached after the program "exits".
(gdb) target extended-remote :3333

(gdb) monitor reset halt          # halt CPU before touching flash
(gdb) load                        # write ELF to flash via OpenOCD's memory map
#   Loading section .isr_vector, size 0x40 lma 0x8000000
#   Loading section .text, size 0x5c lma 0x8000040
#   Start address 0x08000041, load size 156
(gdb) monitor reset halt          # reset so PC = the new reset vector

(gdb) break main                  # hardware breakpoint (flash) — 6 available
(gdb) continue                    # run to main()

(gdb) info registers              # r0..r12, sp, lr, pc, xPSR
(gdb) next                        # step over one source line
(gdb) step                        # step into
(gdb) stepi                       # one machine instruction

(gdb) x/4xw 0x48000800            # examine GPIOC MODER..BSRR (4 words, hex)
(gdb) print/x $pc                 # current program counter
(gdb) watch *(uint32_t *)0x48000818   # DWT watchpoint on GPIOC_BSRR
(gdb) continue                    # stops when BSRR is written (LED toggles)

(gdb) monitor reset run           # let it run free on the board
(gdb) detach                      # release the target, keep it running
(gdb) quit

# one-shot: connect, flash, break at main, hand you the prompt
arm-none-eabi-gdb -q blink.elf \
    -ex "target extended-remote :3333" \
    -ex "monitor reset halt" \
    -ex "load" \
    -ex "monitor reset halt" \
    -ex "break main" \
    -ex "continue"

# or keep the recipe in a file and run: arm-none-eabi-gdb -x flash.gdb blink.elf

target extended-remote :3333
monitor reset halt
load
monitor reset halt
break main
continue

# ── Terminal A: the OpenOCD server (start once, leave running) ──
openocd -f interface/stlink.cfg -f target/stm32l4x.cfg
# ... Listening on port 3333 for gdb connections

# ── Terminal B: edit → build → reflash → debug, over and over ──
make                                   # rebuild blink.elf
arm-none-eabi-gdb -q blink.elf -ex "target extended-remote :3333"
(gdb) monitor reset halt
(gdb) load                             # reflash without restarting the server
(gdb) monitor reset halt
(gdb) break main
(gdb) continue

# run simply as: openocd
source [find interface/stlink.cfg]
transport select hla_swd            # ST-Link high-level SWD (default)
source [find target/stm32l4x.cfg]

adapter speed 1800                  # kHz; conservative for the on-board ST-Link
reset_config srst_only srst_nogate  # use NRST, keep it released between resets

# Optional: flash + halt at main automatically when this cfg is sourced.
# init
# reset halt
# program blink.elf verify

(gdb) monitor arm semihosting enable
# Now newlib's write()/printf() in firmware appears in this GDB console.
# Requires linking with a semihosting stub (e.g. --specs=rdimon.specs).

# Board runs code that kills SWD, or is RDP level 1 → hold in reset, unlock, wipe.
openocd -f interface/stlink.cfg -f target/stm32l4x.cfg \
    -c "reset_config connect_assert_srst" \
    -c "init" \
    -c "reset halt" \
    -c "stm32l4x unlock 0" \
    -c "stm32l4x mass_erase 0" \
    -c "reset run" \
    -c "shutdown"
# stm32l4x unlock 0 sets RDP to 0xAA (level 0); the option-byte change
# triggers a full mass erase, clearing whatever bricked the part.