feat(transport): Add USB-Serial/JTAG and transport layer selection support

src/CMakeLists.txt

@@ -2,6 +2,7 @@ add_executable(${TARGET_NAME}
     "main.c"
     "slip.c"
     "command_handler.c"
+    "transport.c"
 )
 
 target_compile_options(${TARGET_NAME} PRIVATE

src/command_handler.c

@@ -240,7 +240,7 @@ static void s_mem_end(const uint8_t* buffer, uint16_t size)
 
     if (flag == 1) {
         // TODO: consider delay - was in previous code
-        stub_lib_uart_tx_flush();
+        stub_lib_uart_tx_flush(UART_NUM_0);
 
         // ROM loader firstly exits the loader routine and then executes the entrypoint,
         // but for our purposes, keeping a bit of extra stuff on the stack doesn't really matter.

src/main.c

@@ -8,9 +8,9 @@
 #include <stdbool.h>
 #include <stdint.h>
 #include <esp-stub-lib/flash.h>
-#include <esp-stub-lib/uart.h>
-#include "slip.h"
 #include "command_handler.h"
+#include "slip.h"
+#include "transport.h"
 
 #ifdef ESP8266
 __asm__(
@@ -22,26 +22,6 @@ __asm__(
     "j esp_main;");
 #endif //ESP8266
 
-static void uart_rx_interrupt_handler()
-{
-    // This also resets the interrupt flags
-    uint32_t intr_flags = stub_lib_uart_get_intr_flags(UART_NUM_0);
-
-    if ((intr_flags & UART_INTR_RXFIFO_FULL) || (intr_flags & UART_INTR_RXFIFO_TOUT)) {
-        uint32_t count = stub_lib_uart_get_rxfifo_count(UART_NUM_0);
-
-        for (uint32_t i = 0; i < count; ++i) {
-            uint8_t byte = stub_lib_uart_read_rxfifo_byte(UART_NUM_0);
-            slip_recv_byte(byte);
-
-            // Cannot process more bytes until frame is processed
-            if (slip_is_frame_complete() || slip_is_frame_error()) {
-                break;
-            }
-        }
-    }
-}
-
 void esp_main(void)
 {
     extern uint32_t _bss_start;
@@ -56,8 +36,7 @@ void esp_main(void)
     stub_lib_flash_init(&flash_state);
     stub_lib_flash_attach(0, false);
 
-    stub_lib_uart_wait_idle(UART_NUM_0); // Wait until ROM sends response to last command
-    stub_lib_uart_rominit_intr_attach(UART_NUM_0, 5, uart_rx_interrupt_handler, UART_INTR_RXFIFO_FULL | UART_INTR_RXFIFO_TOUT);
+    stub_transport_init();
 
     // Send OHAI greeting to signal stub is active
     const uint8_t greeting[4] = {'O', 'H', 'A', 'I'};

src/slip.c

@@ -6,15 +6,10 @@
 
 #include <stdint.h>
 #include <esp-stub-lib/uart.h>
+#include <esp-stub-lib/usb_serial_jtag.h>
 #include "command_handler.h"
 #include "slip.h"
 
-/* SLIP Protocol Constants */
-#define SLIP_END            0xC0    /* Frame delimiter */
-#define SLIP_ESC            0xDB    /* Escape character */
-#define SLIP_ESC_END        0xDC    /* Escaped frame delimiter */
-#define SLIP_ESC_ESC        0xDD    /* Escaped escape character */
-
 /* SLIP State Machine */
 typedef enum {
     STATE_NO_FRAME,          /* Not in a frame */
@@ -43,24 +38,34 @@ static slip_recv_ctx_t s_recv_ctx = {
 
 static slip_state_t s_state = STATE_NO_FRAME;
 
+/* TX function pointer set by transport init (defaults to UART) */
+static uint8_t (*s_tx_one_char)(uint8_t) = stub_lib_uart_tx_one_char;
+
+void slip_set_tx_fn(uint8_t (*tx_fn)(uint8_t))
+{
+    if (tx_fn) {
+        s_tx_one_char = tx_fn;
+    }
+}
+
 void slip_send_frame_delimiter(void)
 {
-    stub_lib_uart_tx_one_char(SLIP_END);
+    s_tx_one_char(SLIP_END);
 }
 
 void slip_send_frame_data(uint8_t byte)
 {
     switch (byte) {
     case SLIP_END:
-        stub_lib_uart_tx_one_char(SLIP_ESC);
-        stub_lib_uart_tx_one_char(SLIP_ESC_END);
+        s_tx_one_char(SLIP_ESC);
+        s_tx_one_char(SLIP_ESC_END);
         break;
     case SLIP_ESC:
-        stub_lib_uart_tx_one_char(SLIP_ESC);
-        stub_lib_uart_tx_one_char(SLIP_ESC_ESC);
+        s_tx_one_char(SLIP_ESC);
+        s_tx_one_char(SLIP_ESC_ESC);
         break;
     default:
-        stub_lib_uart_tx_one_char(byte);
+        s_tx_one_char(byte);
         break;
     }
 }

src/slip.h

@@ -14,6 +14,21 @@
 extern "C" {
 #endif
 
+/* SLIP Protocol Constants */
+#define SLIP_END            0xC0    /* Frame delimiter */
+#define SLIP_ESC            0xDB    /* Escape character */
+#define SLIP_ESC_END        0xDC    /* Escaped frame delimiter */
+#define SLIP_ESC_ESC        0xDD    /* Escaped escape character */
+
+/**
+ * @brief Register TX function used by SLIP to send bytes
+ *
+ * The function must transmit a single byte and return 0 on success.
+ *
+ * @param tx_fn Function pointer with signature: uint8_t (*)(uint8_t)
+ */
+void slip_set_tx_fn(uint8_t (*tx_fn)(uint8_t));
+
 /**
  * @brief Send SLIP frame delimiter
  */

src/transport.c

@@ -0,0 +1,67 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#include <stdint.h>
+#include <esp-stub-lib/uart.h>
+#include <esp-stub-lib/usb_serial_jtag.h>
+#include "transport.h"
+#include "slip.h"
+
+void uart_rx_interrupt_handler()
+{
+    // This also resets the interrupt flags
+    uint32_t intr_flags = stub_lib_uart_clear_intr_flags(UART_NUM_0);
+
+    if ((intr_flags & UART_INTR_RXFIFO_FULL) || (intr_flags & UART_INTR_RXFIFO_TOUT)) {
+        uint32_t count = stub_lib_uart_get_rxfifo_count(UART_NUM_0);
+
+        for (uint32_t i = 0; i < count; ++i) {
+            uint8_t byte = stub_lib_uart_read_rxfifo_byte(UART_NUM_0);
+            slip_recv_byte(byte);
+
+            // Cannot process more bytes until frame is processed
+            if (slip_is_frame_complete() || slip_is_frame_error()) {
+                break;
+            }
+        }
+    }
+}
+
+void usb_jtag_serial_interrupt_handler()
+{
+    stub_lib_usb_serial_jtag_clear_intr_flags();
+
+    while (stub_lib_usb_serial_jtag_is_data_available()) {
+        slip_recv_byte(stub_lib_usb_serial_jtag_read_rxfifo_byte());
+    }
+}
+
+uint8_t usb_serial_jtag_tx_one_char(uint8_t c)
+{
+    // Flush every 63 bytes (some Windows drivers have issues with >= 64 bytes)
+    // or when a frame delimiter is sent
+    // TODO: Proper fix with zero-length packets
+    static unsigned short transferred_without_flush = 0;
+    stub_lib_usb_serial_jtag_tx_one_char(c);
+    ++transferred_without_flush;
+    if (c == SLIP_END || transferred_without_flush >= 63) {
+        stub_lib_usb_serial_jtag_tx_flush();
+        transferred_without_flush = 0;
+    }
+    return 0;
+}
+
+void stub_transport_init(void)
+{
+    if (stub_lib_usb_serial_jtag_is_active()) {
+        stub_lib_usb_serial_jtag_rominit_intr_attach(17, usb_jtag_serial_interrupt_handler, USB_SERIAL_JTAG_OUT_RECV_PKT_INT_ENA);
+        slip_set_tx_fn(usb_serial_jtag_tx_one_char);
+    } else {
+        stub_lib_uart_wait_idle(UART_NUM_0); // Wait until ROM sends response to last command
+        stub_lib_uart_rominit_intr_attach(UART_NUM_0, 5, uart_rx_interrupt_handler, UART_INTR_RXFIFO_FULL | UART_INTR_RXFIFO_TOUT);
+        slip_set_tx_fn(stub_lib_uart_tx_one_char);
+    }
+}

src/transport.h

@@ -0,0 +1,39 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Initialize the transport layer
+ */
+void stub_transport_init(void);
+
+/**
+ * @brief UART interrupt handler
+ */
+void uart_rx_interrupt_handler();
+
+/**
+ * @brief USB-Serial/JTAG interrupt handler
+ */
+void usb_jtag_serial_interrupt_handler();
+
+/**
+ * @brief USB-Serial/JTAG transmit one character
+ */
+uint8_t usb_serial_jtag_tx_one_char(uint8_t c);
+
+#ifdef __cplusplus
+}
+#endif

unittests/target/TestTargetExample.c

@@ -168,15 +168,15 @@ void esp_main(void)
     int result = UNITY_END();
 
     // Send test completion marker for load-test.py
-    stub_lib_uart_tx_flush();
+    stub_lib_uart_tx_flush(UART_NUM_0);
     printf("\n--- UNITY TEST RUN COMPLETE ---\n");
     printf("Test Results: %s\n", (result == 0) ? "ALL TESTS PASSED" : "SOME TESTS FAILED");
     printf("--- END OF TESTS ---\n");
-    stub_lib_uart_tx_flush();
+    stub_lib_uart_tx_flush(UART_NUM_0);
 
     // Exit gracefully (could loop forever or halt depending on system requirements)
     while (1) {
-        stub_lib_uart_tx_flush();
+        stub_lib_uart_tx_flush(UART_NUM_0);
         stub_lib_delay_us(1000000);  // 1 second delay
     }
 }

unittests/target/minimal_system.c

@@ -57,7 +57,7 @@ void __system_init(void)
     stub_lib_uart_tx_one_char('\n');
 
     // Flush UART to ensure data is sent immediately
-    stub_lib_uart_tx_flush();
+    stub_lib_uart_tx_flush(UART_NUM_0);
 }
 
 // Simple sbrk implementation for heap management