Skip to content

Add debugging developer docs: AT32 recovery, bootlog, USB MSC, GCC preprocessing - #11733

Merged
sensei-hacker merged 4 commits into
iNavFlight:maintenance-10.xfrom
sensei-hacker:docs-extract-debugging
Jul 19, 2026
Merged

Add debugging developer docs: AT32 recovery, bootlog, USB MSC, GCC preprocessing#11733
sensei-hacker merged 4 commits into
iNavFlight:maintenance-10.xfrom
sensei-hacker:docs-extract-debugging

Conversation

@sensei-hacker

Copy link
Copy Markdown
Member

Summary

Adds developer-facing debugging documentation that previously only existed as informal notes:

  • docs/development/at32-flash-recovery.md — generic AT32F43x flash-protection recovery procedure (STM32CubeProgrammer, ST-Link/OpenOCD, serial bootloader), independent of any specific cause.
  • docs/development/bootlog-debugging.md — the logHasOutput()/log-port-required gating pitfall, an I2C/OLED init diagnostic table, and raw-register-read technique. Fills a real gap versus the existing serial_printf_debugging.md, which only briefly mentions bootlog in passing; cross-linked both directions.
  • docs/development/gcc-preprocessing-techniques.md — reducing/filtering arm-none-eabi-gcc -E output when comparing preprocessed target headers.
  • docs/development/performance-debugging.md — PID-loop rate-limiting pattern (citing the real armingStatusDivider example already in fc_core.c), the tasks CLI command, and a backup-domain GPIO drive-strength caveat.
  • docs/development/target-split-verification.md — multi-tool verification strategy (preprocessor diff + source-level dead-code check) for splitting one multi-board target directory into several.
  • docs/development/usb-msc-debugging.md — composite CDC+MSC USB descriptor conflicts, with the real usbDevConfig()->type == COMPOSITE gating mechanism.

Testing

Documentation-only change (no .c/.h files touched). Every checkable factual claim was verified against the current source tree in this checkout:

  • logIsEnabled()/logHasOutput() gating logic in src/main/common/log.c, and dashboardInit()/feature(FEATURE_DASHBOARD) gating in fc_init.c
  • DEVFLAGS_USE_RAW_REGISTERS behavior traced through bus.cbus_busdev_i2c.cbus_i2c_hal.c
  • updateArmingStatus() and its armingStatusDivider rate-limiting in fc_core.c
  • usbDevConfig()->type == COMPOSITE in usbd_conf_stm32h7xx.c and the standalone-MSC fallback comment in usb_msc_h7xx.c
  • All internal cross-links between the new/modified files resolve to real files in this PR

Two files from an earlier draft of this batch were dropped after verification: an AT32 EOPB0/SRAM investigation doc (the feature it investigates never landed in system_at32f43x.c — the branch was abandoned) and a bare debugging-scripts tips file (its one INAV-specific nugget was too narrow to justify a file on its own). An RP2350_PICO SWD debugging guide was also held back, since that target doesn't exist on maintenance-10.x yet — it'll land with that target's own PR instead.

Code Review

Reviewed with the inav-code-review agent, twice (once before, once after fixes). It caught and I fixed: a performance-debugging.md example that had updateArmingStatus() backwards (presented as an unaddressed rate-limiting opportunity when it's actually already rate-limited — corrected to cite the real pattern), and an OpenOCD command-namespace mismatch in the AT32 recovery doc (at32f4x unlock vs. the stm32f4x.cfg-based config actually shown). It also confirmed the batch is clean of vendor-datasheet reproduction and session-investigation narrative framing.

Several recurring debugging techniques (bootlog gating pitfalls, AT32
flash-protection recovery, composite-USB descriptor conflicts, gcc -E
verification for target splits) only existed as informal notes.
bootlog-debugging.md fills a real gap versus the existing terse
serial_printf_debugging.md bootlog mention.
@sensei-hacker sensei-hacker added this to the 10.0 milestone Jul 19, 2026
@qodo-code-review

Copy link
Copy Markdown
Contributor

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

Clarified lesson on using divider pattern for performance.
Removed section on checking DASHBOARD feature after full-erase flash.
@sensei-hacker
sensei-hacker merged commit 8a319b2 into iNavFlight:maintenance-10.x Jul 19, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant