Add debugging developer docs: AT32 recovery, bootlog, USB MSC, GCC preprocessing - #11733
Merged
sensei-hacker merged 4 commits intoJul 19, 2026
Merged
Conversation
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.
Contributor
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
Clarified lesson on using divider pattern for performance.
Removed section on checking DASHBOARD feature after full-erase flash.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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— thelogHasOutput()/log-port-required gating pitfall, an I2C/OLED init diagnostic table, and raw-register-read technique. Fills a real gap versus the existingserial_printf_debugging.md, which only briefly mentionsbootlogin passing; cross-linked both directions.docs/development/gcc-preprocessing-techniques.md— reducing/filteringarm-none-eabi-gcc -Eoutput when comparing preprocessed target headers.docs/development/performance-debugging.md— PID-loop rate-limiting pattern (citing the realarmingStatusDividerexample already infc_core.c), thetasksCLI 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 realusbDevConfig()->type == COMPOSITEgating mechanism.Testing
Documentation-only change (no
.c/.hfiles touched). Every checkable factual claim was verified against the current source tree in this checkout:logIsEnabled()/logHasOutput()gating logic insrc/main/common/log.c, anddashboardInit()/feature(FEATURE_DASHBOARD)gating infc_init.cDEVFLAGS_USE_RAW_REGISTERSbehavior traced throughbus.c→bus_busdev_i2c.c→bus_i2c_hal.cupdateArmingStatus()and itsarmingStatusDividerrate-limiting infc_core.cusbDevConfig()->type == COMPOSITEinusbd_conf_stm32h7xx.cand the standalone-MSC fallback comment inusb_msc_h7xx.cTwo 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 onmaintenance-10.xyet — it'll land with that target's own PR instead.Code Review
Reviewed with the
inav-code-reviewagent, twice (once before, once after fixes). It caught and I fixed: aperformance-debugging.mdexample that hadupdateArmingStatus()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 unlockvs. thestm32f4x.cfg-based config actually shown). It also confirmed the batch is clean of vendor-datasheet reproduction and session-investigation narrative framing.