esp-s3 jtag serial drive write function loses characters when rx ring buffer is full (IDFGH-10926)

[jjsch-dev]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

IDF version.

v5.2-dev-2318-ga58547b8c6

Operating System used.

Linux

How did you build your project?

Command line with idf.py

If you are using Windows, please specify command line type.

None

Development Kit.

custom board

Power Supply used.

USB

What is the expected behavior?

Have the write function wait 50 mS in the tx ring buffer for the USB host to flush and not lose character.

What is the actual behavior?

Upon examining the code, I noticed that the usbjtag_tx_char_via_driver function contains a comparison that checks whether an immediate send operation succeeds. However, the return value from usb_serial_jtag_write_bytes is always 1, which prevents the intended logic to try blocking for 50 mS, but also a return that always skyp the bloking try.

Steps to reproduce.

this issue is very similar.

Debug Logs.

No response

More Information.

Proposed Solution:
To resolve this issue, I recommend implementing the following adjustments and have already submitted a corresponding pull request:

Modify the usb_serial_jtag_write_bytes function to return -1 on failure and 0 on success.

int usb_serial_jtag_write_bytes(const void* src, size_t size, TickType_t ticks_to_wait)
{
    ESP_RETURN_ON_FALSE(size != 0, ESP_ERR_INVALID_ARG, USB_SERIAL_JTAG_TAG, "size should be larger than 0");
    ESP_RETURN_ON_FALSE(src != NULL, ESP_ERR_INVALID_ARG, USB_SERIAL_JTAG_TAG, "Invalid buffer pointer.");
    ESP_RETURN_ON_FALSE(p_usb_serial_jtag_obj != NULL, ESP_ERR_INVALID_ARG, USB_SERIAL_JTAG_TAG, "The driver hasn't been initialized");

    const uint8_t *buff = (const uint8_t *)src;
    // Blocking method, Sending data to ringbuffer, and handle the data in ISR.
    BaseType_t result = xRingbufferSend(p_usb_serial_jtag_obj->tx_ring_buf, (void*) (buff), size, ticks_to_wait);

    // Now trigger the ISR to read data from the ring buffer.
    usb_serial_jtag_ll_ena_intr_mask(USB_SERIAL_JTAG_INTR_SERIAL_IN_EMPTY);
       
    // Return -1 on failure, 0 on success.
    return (result == pdFALSE) ? -1 : 0;
}

Update the usbjtag_tx_char_via_driver function to accommodate the adjusted return values and logic.

static void usbjtag_tx_char_via_driver(int fd, int c)
{
    char ch = (char) c;
    TickType_t ticks = (TX_FLUSH_TIMEOUT_US / 1000) / portTICK_PERIOD_MS;
    // Attempt to send the character immediately without blocking.
    if (usb_serial_jtag_write_bytes(&ch, 1, 0) != 0) {
        s_ctx.tx_tried_blocking = false;
    } else {
        return;
    }

    // If immediate send fails, try blocking with a timeout.
    if (s_ctx.tx_tried_blocking == false) {
        if (usb_serial_jtag_write_bytes(&ch, 1, ticks) != 0) {
            return;
        } else {
            s_ctx.tx_tried_blocking = true;
        }
    } 
}

[jjsch-dev]

More information about it can be found in the PR conversation, where @ginkgm clarifies the behavior of the ring buffer.