Skip to content

xtensa/esp32s3: Fix CONSOLE_DEV clobbered by USBSERIAL macro. - #20053

Merged
xiaoxiang781216 merged 1 commit into
apache:masterfrom
FelipeMdeO:fix/esp32s3-usbserial-console-clobber
Sep 4, 2026
Merged

xtensa/esp32s3: Fix CONSOLE_DEV clobbered by USBSERIAL macro.#20053
xiaoxiang781216 merged 1 commit into
apache:masterfrom
FelipeMdeO:fix/esp32s3-usbserial-console-clobber

Conversation

@FelipeMdeO

@FelipeMdeO FelipeMdeO commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Why change is necessary (fix, update, new feature)? Fix — a boot-time
    hang/reset-loop bug.
  • What functional part of the code is being changed?
    arch/xtensa/src/esp32s3/esp32s3_serial.c, the CONSOLE_DEV macro
    selection logic used by the ESP32-S3 serial driver.
  • How does the change exactly work (what will change and how)?
    When CONFIG_ESP32S3_USBSERIAL is enabled at the same time as a real
    UART is selected as the system console (CONFIG_UARTx_SERIAL_CONSOLE),
    an unconditional #define CONSOLE_DEV g_uart_usbserial silently
    overrides the correct earlier definition that pointed CONSOLE_DEV at
    the chosen UART device. xtensa_earlyserialinit() then calls
    esp32s3_setup(&CONSOLE_DEV) — a function only valid for a
    struct esp32s3_uart_s — on what is actually g_uart_usbserial, whose
    priv points to an unrelated struct esp32s3_usbserial_s. Reading
    priv->id off the wrong struct returns garbage, which is then used to
    compute a UART register address; the resulting access to invalid IO
    hangs the CPU until the RTC watchdog resets the board, in a loop,
    before NSH ever starts. The fix guards the USBSERIAL assignment with
    !defined(CONSOLE_DEV), mirroring the pattern already used a few lines
    below in the same file for TTYS1_DEV/TTYS2_DEV.
  • Related NuttX Issue: none filed yet.

Impact

  • Is new feature added?
    Is existing feature changed? NO — pure bug fix,
    no behavior change for any config that was working correctly before
    (the only configs affected are ones where CONSOLE_DEV was silently
    wrong, i.e. already broken).

Testing

I confirm that changes are verified on local setup and works as intended:

  • Build Host(s): Linux (x86_64), GCC via the xtensa-esp32s3-elf
    toolchain (esp-elf 14.2.0).
  • Target(s): xtensa, Seeed XIAO ESP32-S3 (esp32s3-xiao), custom
    out-of-tree defconfig with CONFIG_ESP32S3_UART0=y,
    CONFIG_UART0_SERIAL_CONSOLE=y, CONFIG_ESP32S3_USBSERIAL=y.
  • Reproduction: flash a config with a UART selected as
    SERIAL_CONSOLE while CONFIG_ESP32S3_USBSERIAL is also enabled, and
    watch the UART console — it boot-loops instead of reaching NSH.

Testing logs before change:

ESP-ROM:esp32s3-20210327
Build:Mar 27 2021
rst:0x10 (RTCWDT_RTC_RST),boot:0x9 (SPI_FAST_FLASH_BOOT)
...
*** Booting NuttX ***
dram: lma 0x00000020 vma 0x3fc8e7e0 len 0x184c   (6220)
iram: lma 0x00001874 vma 0x40374000 len 0x8494   (33940)
...
total segments stored 7
<hang here -- nothing else is ever printed>

<~8s later, resets and repeats identically, forever>

Testing logs after change:

nsh> uname -a
NuttX 13.0.1-RC0 734c06c4f3-dirty Sep  3 2026 11:50:28 xtensa esp32s3-xiao
nsh> ls /dev
/dev:
 console
 i2c0
 mmcsd0
 null
 ttyACM0
 ttyS0
 uorb/
 usensor
 zero
nsh>

@github-actions github-actions Bot added Arch: xtensa Issues related to the Xtensa architecture Size: XS The size of the change in this PR is very small labels Sep 3, 2026
When a real UART (CONFIG_UARTx_SERIAL_CONSOLE) is selected as the
system console while CONFIG_ESP32S3_USBSERIAL is also enabled (e.g. to
keep /dev/ttyACM0 available as a secondary device alongside an
external console UART), the unconditional

  #ifdef CONFIG_ESP32S3_USBSERIAL
  #  define CONSOLE_DEV g_uart_usbserial
  #endif

block silently redefines CONSOLE_DEV, clobbering the correct earlier
definition that pointed it at the chosen UART device.

Confirmed on real hardware (Seeed XIAO ESP32-S3): with UART0 selected
as console and USBSERIAL also enabled, the board boot-looped on
RTCWDT_RTC_RST every ~8s, never reaching NSH. With this fix, NSH comes
up normally over UART0 and /dev/ttyACM0 remains available.

Signed-off-by: Felipe Moura <moura.fmo@gmail.com>
Assisted-by: Claude:claude-sonnet-5
@FelipeMdeO
FelipeMdeO force-pushed the fix/esp32s3-usbserial-console-clobber branch from 01d6a73 to 8ededdb Compare September 3, 2026 15:32
@github-actions github-actions Bot added Size: M The size of the change in this PR is medium and removed Size: XS The size of the change in this PR is very small labels Sep 3, 2026
@FelipeMdeO

Copy link
Copy Markdown
Contributor Author

@acassis , can you review this PR too, please?

@xiaoxiang781216
xiaoxiang781216 merged commit 673b424 into apache:master Sep 4, 2026
27 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Arch: xtensa Issues related to the Xtensa architecture Size: M The size of the change in this PR is medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants