stuck on tinyusb_driver_uinstall and tinyusb_msc_storage_mount while trying to unexpose and mount back the storage (IEC-340)

[earthPerson-001]

Answers checklist.

• I have read the component documentation ESP-IDF Components and the issue is not addressed there.
• I am using target and esp-idf version as defined in component's idf_component.yml
• I have searched the issue tracker for a similar issue and not found any related issue.

Which component are you using? If you choose Other, provide details in More Information.

device/esp_tinyusb

ESP-IDF version.

v5.5.0

Development Kit.

Custom Board

Used Component version.

v1.7.6

More Information.

When i repeatedly expose and mount, the execution gets stopped (without any errors) around the mounting point.

The issue is mostly observed when usb is still connected to pc/other device.

I don't have vbus monitoring enabled as the intention is to never plug out the USB cable.

Reproducable code

#include <esp_log.h>
#include <esp_system.h>

#include "SDMMC_USB.hpp"
#include "driver/gpio.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

#define TAG "main"

#define MOUNT_POINT_M "/data"

extern "C" void app_main(void)
{
    SDMMC_USB::getInstance().initiate();

    vTaskDelay(1000 / portTICK_PERIOD_MS);

    SDMMC_USB::getInstance().mount();

    char srcFileName[64];
    char dstFileName[64];
    char outFileName[64];
    sprintf(srcFileName, "%s/hello.txt", MOUNT_POINT_M);
    sprintf(dstFileName, "hello.txt");
    sprintf(outFileName, "%s/out.txt", MOUNT_POINT_M);

    for (int i = 0; i < 10; i++) {
        FILE *f = fopen(srcFileName, "w");
        if (f == NULL) {
            ESP_LOGE(TAG, "Failed to open file for writing");
            return;
        }
        fprintf(f, "Hello World!  %d\n", i);
        fclose(f);
        ESP_LOGI(TAG, "Wrote the text on %s", srcFileName);

        vTaskDelay(1000 / portTICK_PERIOD_MS);
    }

    vTaskDelay(2000);
    SDMMC_USB::getInstance().deleteAllFiles();

    while (true) {
        vTaskDelay(5000 / portTICK_PERIOD_MS);
        SDMMC_USB::getInstance().expose();

        vTaskDelay(5000 / portTICK_PERIOD_MS);
        SDMMC_USB::getInstance().mount();
    }
}

The functions used

void SDMMC_USB::mount()
{
    if (!isMountedToESP) {
        ESP_LOGI(TAG, "Unexposing storage from host...");
        tud_disconnect();

        ESP_ERROR_CHECK(tinyusb_driver_uninstall());

        ESP_LOGI(TAG, "Mount storage...");
        ESP_ERROR_CHECK(tinyusb_msc_storage_mount(BASE_PATH));

        // List all the files in this directory
        ESP_LOGI(TAG, "\nls command output:");
        struct dirent *d;
        DIR *dh = opendir(BASE_PATH);
        if (!dh) {
            if (errno == ENOENT) {
                // If the directory is not found
                ESP_LOGE(TAG, "Directory doesn't exist %s", BASE_PATH);
            } else {
                // If the directory is not readable then throw error and exit
                ESP_LOGE(TAG, "Unable to read directory %s", BASE_PATH);
            }
            return;
        }
        // While the next entry is not readable we will print directory files
        while ((d = readdir(dh)) != NULL) {
            printf("%s\n", d->d_name);
        }
        isMountedToESP = true;
        return;
    }
}

void SDMMC_USB::expose()
{
    if (isMountedToESP) {
        ESP_LOGI(TAG, "Exposing storage to host...");
        ESP_ERROR_CHECK(tinyusb_driver_install(&tusb_cfg));
        tud_connect();
        isMountedToESP = false;
    }
}

The initialisation logic is the same as in tusb_msc_main.c example for sdmmc.

Previously, the program got stuck while calling the tinyusb_msc_storage_mount function, but when I tried to collect the log by setting the log level to verbose, it got stuck in tinyusb_driver_uninstall (intr_alloc: esp_intr_free: Disabling int, killing handler).
Log when verbose logging is enabled:

sdmmc_mount_stuck.log

[github-actions]

Hi @earthPerson-001! Please be aware that the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

Thank you for the detailed report and code. Based on the provided information and Espressif’s official documentation, here are some key points and recommendations regarding your issue with repeated calls to tinyusb_driver_uninstall and tinyusb_msc_storage_mount when toggling between exposing and mounting storage:

---

1. Intended Usage Pattern

The typical usage pattern for the TinyUSB MSC device stack is to initialize the USB device stack once, then expose or unexpose the storage by mounting or unmounting the filesystem, not by repeatedly uninstalling and reinstalling the TinyUSB driver. The official example exposes and unexposes storage by mounting/unmounting the filesystem, not by uninstalling the driver each time.

---

2. Driver Uninstall and Reinstall

The documentation for esp_tinyusb and the TinyUSB MSC example does not describe a workflow where tinyusb_driver_uninstall and tinyusb_driver_install are called repeatedly in a loop. Uninstalling the driver is a heavy operation and may not be designed for frequent toggling, especially while the USB cable remains connected and the host is still enumerating the device.

---

3. VBUS Monitoring

The documentation specifically notes that self-powered devices should monitor VBUS and use this to control USB stack state. Not monitoring VBUS while toggling the stack may lead to undefined behavior, especially if the host is still actively communicating with the device when you uninstall the driver. This could explain the system getting stuck in interrupt deallocation (esp_intr_free) during tinyusb_driver_uninstall if the USB hardware is still active or in use by the host at that moment esp_tinyusb documentation.

---

4. Recommended Approach

• Do not repeatedly uninstall/install the TinyUSB driver. Instead, use the provided API to expose or unexpose storage by mounting or unmounting the filesystem, as shown in the tusb_msc example.
• If you must switch between host and device access, ensure the USB stack is in a safe state (e.g., VBUS is not present or the host is not actively communicating) before uninstalling the driver.
• Consider implementing VBUS monitoring, even if you do not intend to unplug the cable, to ensure proper USB state transitions.

---

5. Known Limitations

• The documentation does not guarantee that repeated uninstall/install cycles of the TinyUSB driver are supported or safe, especially with the USB cable connected and the host active.
• The esp_tinyusb changelog mentions fixes for uninstall behavior, but not for the use case of frequent toggling in a connected state.

---

6. Summary

Your current approach of uninstalling and reinstalling the TinyUSB driver in a loop while the USB cable remains connected is not the recommended or documented usage pattern. This can lead to the system getting stuck, as you observed. Instead, follow the example pattern: initialize the driver once, and use filesystem mount/unmount to control access. If you need to fully uninstall the driver, ensure the USB bus is idle and consider VBUS monitoring for robust operation.

If you need further clarification or if your use case requires dynamic driver reinstallation, please provide more details, and we can help escalate or clarify with the Espressif USB team.

---

References:

• esp_tinyusb documentation
• TinyUSB MSC device example

If you have additional logs or a minimal reproducible example, please share them for deeper analysis.

[roma-jam]

Hi @earthPerson-001,

thanks for reporting the problem.

From the code snoppet:

        ESP_ERROR_CHECK(tinyusb_driver_uninstall());

        ESP_LOGI(TAG, "Mount storage...");
        ESP_ERROR_CHECK(tinyusb_msc_storage_mount(BASE_PATH));

The TinyUSB MSC class API calls from esp_tinyusb are not suppose to be called after uninstalling the tinyusb driver itself.

So, to achieve your goal, the bot answer was correct: you do not need to uninstall tinyusb to change the mounting point.
Instead, please, install TinyUSB driver with tinyusb_driver_install() just once, and change the mounting point with tinyusb_msc_storage_mount and tinyusb_msc_storage_unmount API calls.

Feel free to re-open if there will be more problems.

[earthPerson-001]

The use case is to use the SDMMC as both a mass storage device and sdmmc, switching between them dynamically. Is it not possible ?

[roma-jam]

Hi @earthPerson-001,

if you meant to dynamically expose the filesystem from the SD/MMC:

1. to USB host via MSC class
2. to Application, via filesystem mounted at BASE_PATH

then yes, it is possible.

It can be done, by remouting the filesystem:

1. inside the driver logic, on connecton/disconnection events (vbus monitoring is required)
2. be performing calls tinyusb_msc_storage_mount and tinyusb_msc_storage_unmount , but without uninstalling the tinyusb driver completely.

If you meant something else, please let me know.

[earthPerson-001]

Hi @roma-jam,

We used the driver installation and uninstallation logic because it allowed us to use JTAG until we exposed the storage. Is there a workaround for that? I want to be able to use JTAG when the SDMMC isn't exposed as MSC to a PC.

And regarding tinyusb_msc_storage_mount and tinyusb_msc_storage_unmount, it enabled the auto-expose features when using without tud_disconnect and tud_connect. Is there documentation regarding this feature, and how can I enable/disable it?

[roma-jam]

Hi @earthPerson-001,

We used the driver installation and uninstallation logic because it allowed us to use JTAG until we exposed the storage

Ah, in this case you need to reconfigure the PHY back to the USB JTAG after calling tinyusb_driver_uninstall().
More details could be found in here: espressif/esp-idf#15932

But you also need the mounted filesystem at BASE_PATH during the moment, when USB JTAG is working? Is that correct?

[earthPerson-001]

Hi @roma-jam , thank you for your swift response.

The use case:

• Initially, the SDMMC must be mounted to the application at BASE_PATH, and JTAG should be operational
• esp32s3 dictates the role of this device (i.e. it shouldn't automatically behave as an exposed mass storage device when a PC is connected)
• Must be able to switch to an exposed mass storage device ( JTAG won't work here, and the SDMMC won't be mounted to the application at BASE_PATH)
• Must be able to mount back to application at BASE_PATH ( in this case, JTAG should work, and I must be able to use the sdmmc from application to read/write into the sdmmc )

[roma-jam]

Hi @earthPerson-001,

yes, this is possible with the current version of esp_tinyusb component.

The sequence could be created based on the following logic steps:

1. Install the TinyUSB driver with tinyusb_driver_install()
2. Init the storage with tinyusb_msc_storage_init_sdmmc()
3. Exposure the SD/MMC to the USB Host with tinyusb_msc_storage_unmount()
4. // Work with FS on the SD/MMC via USB
5. Exposure the SD/MMC back to the APP with tinyusb_msc_storage_mount(BASE_PATH)
6. Uninstall the TinyUSB driver with tinyusb_driver_uninstall()
7. Re-configure the USB PHY to connect it back to the USB JTAG with usb_new_phy(&(usb_phy_config_t){ .controller = USB_PHY_CTRL_SERIAL_JTAG, .target = USB_PHY_TARGET_INT }, &hdl);

This would help to build the logic that covers your use case without any problem.