Merge pull request #401 from espressif/feat/msc_host_add_linux_build

feat(msc_host): Add linux target build

Author: peter-marcisovsky

.build-test-rules.yml

@@ -71,6 +71,9 @@ host/class/cdc/usb_host_cdc_acm/host_test:
 host/class/hid/usb_host_hid/host_test:
   <<: *host_test_enable_rules
 
+host/class/msc/usb_host_msc/host_test:
+  <<: *host_test_enable_rules
+
 host/class/uvc/usb_host_uvc/host_test:
   <<: *host_test_enable_rules
 

host/class/msc/usb_host_msc/host_test/CMakeLists.txt

@@ -0,0 +1,17 @@
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+set(COMPONENTS main)
+
+# Register usb component, must be registered before registering mock
+list(APPEND EXTRA_COMPONENT_DIRS "../../../../usb")
+
+list(APPEND EXTRA_COMPONENT_DIRS
+    "../../../../usb/test/mocks/usb_host_full_mock/usb"    # Full USB Host stack mock (all the layers are mocked)
+
+     # The following line would be needed to include the freertos mock component if this test used mocked FreeRTOS.
+     #"$ENV{IDF_PATH}/tools/mocks/freertos/"
+    )
+
+add_definitions("-DCMOCK_MEM_DYNAMIC")
+project(host_test_usb_msc)

host/class/msc/usb_host_msc/host_test/README.md

@@ -0,0 +1,35 @@
+| Supported Targets | Linux |
+| ----------------- | ----- |
+
+# Description
+
+This directory contains test code for `USB Host MSC` driver. Namely:
+
+- Simple public API call with mocked USB component to test Linux build and Cmock run for this class driver
+
+Tests are written using [Catch2](https://github.com/catchorg/Catch2) test framework, use CMock, so you must install Ruby on your machine to run them.
+
+# Build
+
+Tests build regularly like an idf project. Currently only working on Linux machines.
+
+```
+idf.py --preview set-target linux
+idf.py build
+```
+
+# Run
+
+The build produces an executable in the build folder.
+
+Just run:
+
+```
+idf.py monitor
+```
+
+or run the executable directly:
+
+```
+./build/host_test_usb_msc.elf
+```

host/class/msc/usb_host_msc/host_test/main/CMakeLists.txt

@@ -0,0 +1,8 @@
+idf_component_register(SRC_DIRS .
+                        REQUIRES cmock
+                        INCLUDE_DIRS .
+                        WHOLE_ARCHIVE)
+
+# We do not use main() from esp-idf as it discards argc and argv arguments
+# We wrap main so argc and argv are correctly passed to Catch2
+target_link_libraries(${COMPONENT_LIB} INTERFACE "-Wl,--wrap=main")

host/class/msc/usb_host_msc/host_test/main/idf_component.yml

@@ -0,0 +1,5 @@
+dependencies:
+  espressif/catch2: "^3.4.0"
+  usb_host_msc:
+    version: "*"
+    override_path: "../../"

host/class/msc/usb_host_msc/host_test/main/test_main.cpp

@@ -0,0 +1,50 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h>
+#include <catch2/catch_session.hpp>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+struct MainTaskArgs {
+    int argc;
+    const char **argv;
+};
+
+static void main_task(void *args)
+{
+    MainTaskArgs *task_args = (MainTaskArgs *)args;
+    auto result = Catch::Session().run(task_args->argc, task_args->argv);
+
+    fflush(stdout);
+    delete task_args;
+    exit(result);
+    vTaskDelete(NULL);
+}
+
+extern "C" int __wrap_main(int argc, const char **argv)
+{
+    // Following section is copied from components\freertos\FreeRTOS-Kernel\portable\linux\port_idf.c
+    // It starts the FreeRTOS scheduler and creates the main task to run Catch2 tests.
+    // Only difference from esp-idf implementation is passing of argc and argv to the main task.
+
+    // This makes sure that stdio is always synchronized so that idf.py monitor
+    // and other tools read text output on time.
+    setvbuf(stdout, NULL, _IONBF, 0);
+
+    usleep(1000);
+    MainTaskArgs *task_args = new MainTaskArgs{argc, argv};
+    BaseType_t res = xTaskCreatePinnedToCore(&main_task, "main",
+                                             ESP_TASK_MAIN_STACK, task_args,
+                                             ESP_TASK_MAIN_PRIO, NULL, ESP_TASK_MAIN_CORE);
+    assert(res == pdTRUE);
+    (void)res;
+
+    vTaskStartScheduler();
+
+    // This line should never be reached
+    assert(false);
+}

host/class/msc/usb_host_msc/host_test/main/test_unit_public_api.cpp

@@ -0,0 +1,145 @@
+/*
+ * SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h>
+#include <catch2/catch_test_macros.hpp>
+
+#include "usb/msc_host_vfs.h"
+#include "mock_add_usb_device.h"
+
+extern "C" {
+#include "Mockusb_host.h"
+}
+
+SCENARIO("MSC Host pre-uninstall")
+{
+    // No MSC Driver installed
+    GIVEN("NO MSC Host previously installed") {
+
+        // Uninstall not-installed MAC Host driver
+        SECTION("Uninstalling not installed MSC Host returns error") {
+            // Call the DUT function, expect ESP_ERR_INVALID_STATE
+            REQUIRE(ESP_ERR_INVALID_STATE == msc_host_uninstall());
+        }
+    }
+}
+
+SCENARIO("MSC Host install")
+{
+    msc_host_driver_config_t msc_host_driver_config = {
+        .create_backround_task = true,
+        .task_priority = 5,
+        .stack_size = 4096,
+        .core_id = 0,
+        .callback = (reinterpret_cast<msc_host_event_cb_t>(0xdeadbeef)),
+        .callback_arg = nullptr,
+    };
+
+    // MSC Host driver config set to nullptr
+    GIVEN("NO MSC Host driver config, driver not already installed") {
+
+        SECTION("Config is nullptr") {
+            // Call the DUT function msc_host_install with msc_host_driver_config set to nullptr
+            REQUIRE(ESP_ERR_INVALID_ARG == msc_host_install(nullptr));
+        }
+    }
+
+    // MSC Host driver config set to config from MSC Host example,
+    // but with various various changes causing MSC Host driver installation to fail
+    GIVEN("Minimal MSC Host driver config, driver not already installed") {
+
+        SECTION("Config error: no callback") {
+            msc_host_driver_config.callback = nullptr;
+            // Call the DUT function, expect ESP_ERR_INVALID_ARG
+            REQUIRE(ESP_ERR_INVALID_ARG == msc_host_install(&msc_host_driver_config));
+        }
+
+        SECTION("Config error: stack size is 0") {
+            msc_host_driver_config.stack_size = 0;
+            // Call the DUT function, expect ESP_ERR_INVALID_ARG
+            REQUIRE(ESP_ERR_INVALID_ARG == msc_host_install(&msc_host_driver_config));
+        }
+
+        SECTION("Config error: task priority is 0") {
+            msc_host_driver_config.task_priority = 0;
+            // Call the DUT function, expect ESP_ERR_INVALID_ARG
+            REQUIRE(ESP_ERR_INVALID_ARG == msc_host_install(&msc_host_driver_config));
+        }
+    }
+
+    // MSC Host driver config set to config from MSC Host example
+    GIVEN("Full MSC Host config, driver not already installed") {
+
+        // Unable to register client: Invalid state, goto fail
+        SECTION("Client register not successful: goto fail") {
+            // Register a client, return ESP_ERR_INVALID_STATE, so the client is not registered successfully
+            usb_host_client_register_ExpectAnyArgsAndReturn(ESP_ERR_INVALID_STATE);
+
+            // goto fail: delete the semaphore and deregister client
+            usb_host_client_deregister_ExpectAnyArgsAndReturn(ESP_OK);
+
+            // Call the DUT function, expect ESP_ERR_INVALID_STATE
+            REQUIRE(ESP_ERR_INVALID_STATE == msc_host_install(&msc_host_driver_config));
+        }
+
+        // Call msc_host_install and expect successful installation
+        SECTION("Client register successful: msc_host_install successful") {
+
+            // Register a client, return ESP_OK, so the client is registered successfully
+            usb_host_client_register_ExpectAnyArgsAndReturn(ESP_OK);
+            usb_host_client_register_AddCallback(usb_host_client_register_mock_callback);
+
+            // create USB Host Library client processing function
+            usb_host_client_handle_events_ExpectAnyArgsAndReturn(ESP_OK);
+            usb_host_client_handle_events_AddCallback(usb_host_client_handle_events_mock_callback);
+
+            // Call the DUT function, expect ESP_OK
+            REQUIRE(ESP_OK == msc_host_install(&msc_host_driver_config));
+        }
+    }
+
+    // MSC Host driver config set to config from MSC Host example
+    GIVEN("Full MSC Host config, driver already installed") {
+
+        // Driver is already installed
+        SECTION("Install error: driver already installed") {
+            // Call the DUT function, expect ESP_ERR_INVALID_STATE
+            REQUIRE(ESP_ERR_INVALID_STATE == msc_host_install(&msc_host_driver_config));
+        }
+    }
+}
+
+SCENARIO("MSC Host post-uninstall")
+{
+    // MSC Host driver successfully installed
+    GIVEN("MSC Host previously installed") {
+
+        // MSC Driver is installed, uninstall the driver
+        SECTION("MSC Host driver uninstall successful") {
+
+            // Unblock client, return ESP_OK, register callback for unblocking the USB Host Library client processing function
+            usb_host_client_unblock_ExpectAnyArgsAndReturn(ESP_OK);
+            usb_host_client_unblock_AddCallback(usb_host_client_unblock_mock_callback);
+
+            // Deregister the client
+            usb_host_client_deregister_ExpectAnyArgsAndReturn(ESP_OK);
+            usb_host_client_deregister_AddCallback(usb_host_client_deregister_mock_callback);
+
+            // Call the DUT function, expect ESP_OK
+            REQUIRE(ESP_OK == msc_host_uninstall());
+        }
+    }
+
+    // MSC Host driver successfully uninstalled
+    GIVEN("MSC Host successfully uninstalled") {
+
+        // MSC Driver already successfully uninstalled, uninstall it again
+        SECTION("Uninstall already uninstalled MSC Host driver") {
+            // Call the DUT function, expect error
+            REQUIRE(ESP_ERR_INVALID_STATE == msc_host_uninstall());
+        }
+    }
+}

host/class/msc/usb_host_msc/host_test/pytest_msc_host_linux.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Unlicense OR CC0-1.0
+import pytest
+from pytest_embedded import Dut
+from pytest_embedded_idf.utils import idf_parametrize
+
+
+@pytest.mark.host_test
+@idf_parametrize('target', ['linux'], indirect=['target'])
+def test_msc_host_linux(dut: Dut) -> None:
+    dut.expect_exact('All tests passed', timeout=5)

host/class/msc/usb_host_msc/host_test/sdkconfig.defaults

@@ -0,0 +1,8 @@
+# This file was generated using idf.py save-defconfig. It can be edited manually.
+# Espressif IoT Development Framework (ESP-IDF) 5.4.0 Project Minimal Configuration
+#
+CONFIG_IDF_TARGET="linux"
+CONFIG_COMPILER_CXX_EXCEPTIONS=y
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=12000
+CONFIG_FREERTOS_HZ=1000
+CONFIG_UNITY_ENABLE_IDF_TEST_RUNNER=n

host/class/msc/usb_host_msc/idf_component.yml

@@ -20,6 +20,8 @@ targets:
   - esp32s3
   - esp32p4
   - esp32h4
+  - linux
 files:
   exclude:
     - "test_app"
+    - "host_test"