Migrate MCUboot Zephyr USB support to USB_DEVICE_STACK_NEXT before Zephyr v4.5.0

[JayToltTech]

Problem

MCUboot's Zephyr USB serial recovery and USB DFU features currently use the legacy USB_DEVICE_STACK API, which has been deprecated in Zephyr and is scheduled for removal in Zephyr v4.5.0.

Current Impact (Zephyr v4.3.0)

Building MCUboot with USB features enabled generates numerous deprecation warnings:

warning: 'usb_enable' is deprecated [-Wdeprecated-declarations]
warning: 'usb_disable' is deprecated [-Wdeprecated-declarations]
warning: 'usb_dc_ep_write' is deprecated [-Wdeprecated-declarations]
warning: 'usb_dc_ep_read' is deprecated [-Wdeprecated-declarations]
... (50+ similar warnings from zephyr/subsys/usb/device/)

These warnings occur throughout Zephyr's USB subsystem code when compiling MCUboot with:

• CONFIG_BOOT_SERIAL_CDC_ACM=y (USB serial recovery)
• CONFIG_BOOT_USB_DFU_WAIT=y (USB DFU mode)

Timeline

• Zephyr v4.3.0 (current): Legacy USB stack deprecated, warnings generated
• Zephyr v4.5.0 (upcoming): Legacy USB stack will be removed entirely
• Result: MCUboot's USB features will break unless migrated

Workaround Currently in Place

Zephyr has a temporary workaround that prevents the new stack from being used with MCUboot:

boards/common/usb/Kconfig.cdc_acm_serial.defconfig

config USB_DEVICE_STACK_NEXT
default y if !MCUBOOT # Explicitly disabled when MCUboot is present

This confirms the Zephyr team is aware of the incompatibility but cannot fix it directly since MCUboot is a separate project.

Proposed Solution

Migrate MCUboot's USB implementation to use the new USB_DEVICE_STACK_NEXT API.

API Changes Required

Files to modify:

• boot/zephyr/main.c - 3 locations using usb_enable() / usb_disable()
• boot/zephyr/serial_adapter.c - 1 location using usb_enable()

Legacy API:
usb_enable(NULL);
usb_disable();

New API:
struct usbd_context uds_ctx = / context */;
usbd_init(uds_ctx);
usbd_enable(uds_ctx);
usbd_disable(uds_ctx);

Device Tree Changes

The new stack requires USB device context definition via device tree:

USBD_DEVICE_DEFINE(mcuboot_usbd,
DEVICE_DT_GET(DT_NODELABEL(zephyr_udc0)),
VENDOR_ID,
PRODUCT_ID);

CDC-ACM configuration also moves from Kconfig to device tree.

Kconfig Changes

Replace:
CONFIG_USB_DEVICE_STACK=y

With:
CONFIG_USB_DEVICE_STACK_NEXT=y
CONFIG_USBD_CDC_ACM_CLASS=y

Estimated Scope

• Lines of code: ~50-100 modifications
• Complexity: Low to moderate (mostly mechanical API replacement)
• Testing required: Critical - must verify USB serial recovery and DFU work on multiple platforms

References

• USB device next follow-up zephyrproject-rtos/zephyr#95649
• Planned USB device/host support rework/enhancements zephyrproject-rtos/zephyr#42066
• usb: device_next: implement USB DFU class for the new device support zephyrproject-rtos/zephyr#79794 - Shows precedent for migrating USB classes
• https://docs.zephyrproject.org/latest/connectivity/usb/device/usb_device.html
• https://docs.zephyrproject.org/latest/connectivity/usb/device_next/api/usbd.html

Hardware Tested

I can test and validate this migration on:

• nRF5340 (nrfx_usbd controller with UDC support)

Volunteers

I'm willing to contribute this migration if the maintainers would accept the PR. Please advise on:

1. Whether this migration is desired
2. Any specific requirements or constraints
3. Testing expectations beyond nRF5340

[nordicjm]

I'm willing to contribute this migration if the maintainers would accept the PR. Please advise on:

Whether this migration is desired

Absolutely, yes please. You will need to bring in the commits from #2346 also which updates the USB CDC parts to the next stack as part of the PR.

Any specific requirements or constraints

Just that it should work as a drop in replacement

Testing expectations beyond nRF5340

Once it is posted here, we can ask people to test it on their platforms

[henrikbrixandersen]

3. Testing expectations beyond nRF5340

I'll be happy to assist with testing and review. I have previously implemented USB DFU support via device_next in CANnectivity (see https://github.com/CANnectivity/cannectivity/blob/main/app/src/usb.c), perhaps you can find some inspiration there.

[JayToltTech]

Very good. I will get on this in a couple of weeks after I get a release out. Thanks folks.

[nordicjm]

Very good. I will get on this in a couple of weeks after I get a release out. Thanks folks.

Hi @JayToltTech any updates?

[JayToltTech]

Still chewing on a product release. Getting close, but not there yet.

Is there a timeline that needs to be hit?

[nordicjm]

Still chewing on a product release. Getting close, but not there yet.

Is there a timeline that needs to be hit?

As soon as possible really, so that people can try it and open issues and fix them before nearing the zephyr release

[henrikbrixandersen]

Still chewing on a product release. Getting close, but not there yet.
Is there a timeline that needs to be hit?

As soon as possible really, so that people can try it and open issues and fix them before nearing the zephyr release

Agreed. This will need to go in well before the feature freeze for Zephyr v4.4 as the Zephyr legacy USB stack can be removed just after Zephyr v4.4.0 is released.

According to the current release schedule (see https://github.com/zephyrproject-rtos/zephyr/wiki/Release-Management), Zephyr v4.4 feature freeze will be in effect starting 2026-03-23.

[JayToltTech]

Ok, I hear you. Will get on it.

…

On Tue, Feb 3, 2026 at 11:10 Henrik Brix Andersen ***@***.***> wrote: *henrikbrixandersen* left a comment (mcu-tools/mcuboot#2596) <#2596 (comment)> Still chewing on a product release. Getting close, but not there yet. Is there a timeline that needs to be hit? As soon as possible really, so that people can try it and open issues and fix them before nearing the zephyr release Agreed. This will need to go in well before the feature freeze for Zephyr v4.4 as the Zephyr legacy USB stack can be removed just after Zephyr v4.4.0 is released. According to the current release schedule (see https://github.com/zephyrproject-rtos/zephyr/wiki/Release-Management), Zephyr v4.4 feature freeze will be in effect starting 2026-03-23. — Reply to this email directly, view it on GitHub <#2596 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AQPEJMVBVV7CBARKOEMCVE34KDXCXAVCNFSM6AAAAACRPUWFACVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQNBTGE2DOOBXGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[JayToltTech]

OK, here are some thoughts/questions based on my first pass of what is needed:

• USBD-Next changes will affect two features, Serial Recovery and DFU
• Serial Recovery is a straight port to USBD-Next CDC-ACM, but DFU looks like a significant departure from USB-Device to USBD-Next
• There are automated tests for Sim and Twister, but none of these automated tests are functional tests of Serial Recovery or DFU, they will only catch general build break/regression issues. The only Serial Recovery functional tests I saw are in the Mynewt test harness using a mocked UART
• References to manual tests refer to the nRF52840 Dongle/DK

So clarifying questions:

• Can we/I scope this work to CDC-ACM / Serial Recovery on USBD-Next and leave the DFU port to a future task?

• MyNewt is out of my area of knowledge / interest and I'd rather not learn their test harness. Can I focus my acceptance testing on Sim/Twister and a suite of newly documented manual functional tests against actual hardware? (e.g. may I skip creating new Serial Recovery automated tests since they will require actual hardware attached instead of Sim and automated serial recovery tests don't exist today?)

• If I test against the nRF52840DK, is that sufficient device coverage for an acceptance test? I'll test against the nRF5340 as that's the MCU I'm using in my project today. I could add a nRF5340DK for a bit more 'generally applicable' coverage as well.

[nordicjm]

Ignore mynewt, that has no relation to zephyr. Also ignore serial recovery, that has a commit here which can be used directly #2346 the only one that needs porting is USB DFU support and for zephyr, there are no tests for that in MCUboot. It's fine if you just get nrf52840dk working with USB DFU support, then others can be invited to test on their own boards and submit fixes

[JayToltTech]

So 2346 is the work I was planning on doing (that is the feature I am using in my mcuboot), but it was closed with the message "we will reconsider" @nordicjm @jfischer-no . I see the note about additional flash needed to support the requirements of the new stack. Was this the blocker? Has anything resolved in the mean time?

If I migrate DFU and add 2346, won't the flash requirements increase further than was the case with #2346?

[nordicjm]

So 2346 is the work I was planning on doing (that is the feature I am using in my mcuboot), but it was closed with the message "we will reconsider" @nordicjm @jfischer-no . I see the note about additional flash needed to support the requirements of the new stack. Was this the blocker? Has anything resolved in the mean time?

If I migrate DFU and add 2346, won't the flash requirements increase further than was the case with #2346?

It's fine to use the commits from that PR, but you need to do the porting for USB DFU (not the same as serial recovery, which is ported in the other PR), if the flash usage increases then it increases, can't really avoid that if it's the stack

[henrikbrixandersen]

So 2346 is the work I was planning on doing (that is the feature I am using in my mcuboot), but it was closed with the message "we will reconsider" @nordicjm @jfischer-no . I see the note about additional flash needed to support the requirements of the new stack. Was this the blocker? Has anything resolved in the mean time?

If I migrate DFU and add 2346, won't the flash requirements increase further than was the case with #2346?

The flash footprint will only increase further if USB DFU is enabled.

The increased footprint is being tracked in Zephyr (see zephyrproject-rtos/zephyr#83309), but could be a concern when it comes to the flash/ROM footprint taken up by MCUboot. We won't know for sure until we have the port to test with.

[JayToltTech]

As a datapoint, my version of mcuboot has cdc-acm serial recovery enabled. I cherry picked the changes from #2346 into my codebase and recompiled. Note that I also made a second change to add CONFIG_BOOT_SHARE_DATA=y, so this is not just the change from USB-DEVICE to USBD-NEXT. I have a lot of diagnostic features turned on in my mcuboot prj.conf, so my build size is rather large compared to vanilla. I repartitioned my flash between the two versions to give a little more headroom to mcuboot (92kb partition instead of 84 kb), so my % used didn't change much.

USB-DEVICE Serial Recovery:

Memory region Used Size Region Size %age Used
FLASH: 78748 B 84 KB 91.55%
RAM: 53632 B 382 KB 13.71%
RetainedMem: 0 GB 66600 B 0.00%
IDT_LIST: 0 GB 32 KB 0.00%

USBD-NEXT Serial Recovery:

Memory region Used Size Region Size %age Used
FLASH: 84756 B 92 KB 89.97%
RAM: 51 KB 382 KB 13.35%
RetainedMem: 0 GB 66856 B 0.00%
IDT_LIST: 0 GB 32 KB 0.00%