mirror
/
esp-idf
kopia lustrzana https://github.com/espressif/esp-idf
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

fix(driver): Add docs and driver fix for the case where a full EP does not cause the host to pickup the data

pull/14633/head
Jeroen Domburg 2023-11-24 17:37:22 +08:00 zatwierdzone przez Cao Sen Miao
rodzic 46d402d22e
commit 28e2ab09ea
7 zmienionych plików z 55 dodań i 12 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

12
components/driver/usb_serial_jtag/usb_serial_jtag.c
Wyświetl plik

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@ -86,7 +86,7 @@ static void usb_serial_jtag_isr_handler_default(void *arg) {
uint32_t sent_size = usb_serial_jtag_write_and_flush(queued_buff, queued_size);
if (sent_size < queued_size) {
// Not all bytes could be sent at once, stash the unwritten bytes in a tx buffer
// Not all bytes could be sent at once; stash the unwritten bytes in a tx buffer
// stash_size will not larger than USB_SER_JTAG_ENDP_SIZE because queued_size is got from xRingbufferReceiveUpToFromISR
size_t stash_size = queued_size - sent_size;
memcpy(p_usb_serial_jtag_obj->tx_data_buf, &queued_buff[sent_size], stash_size);
@ -101,6 +101,14 @@ static void usb_serial_jtag_isr_handler_default(void *arg) {
vRingbufferReturnItemFromISR(p_usb_serial_jtag_obj->tx_ring_buf, queued_buff, &xTaskWoken);
}
usb_serial_jtag_ll_ena_intr_mask(USB_SERIAL_JTAG_INTR_SERIAL_IN_EMPTY);
} else {
// The last transmit may have sent a full EP worth of data. The host will interpret
// this as a transaction that hasn't finished yet and keep the data in its internal
// buffers rather than releasing it to the program listening on the CDC serial port.
// We need to flush again in order to send a 0-byte packet that ends the transaction.
usb_serial_jtag_ll_txfifo_flush();
// Note that since this doesn't re-enable USB_SERIAL_JTAG_INTR_SERIAL_IN_EMPTY, the
// flush will not by itself cause this ISR to be called again.
}
} else {
usb_serial_jtag_ll_clr_intsts_mask(USB_SERIAL_JTAG_INTR_SERIAL_IN_EMPTY);

12
components/hal/esp32c3/include/hal/usb_serial_jtag_ll.h
Wyświetl plik

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@ -161,8 +161,14 @@ static inline int usb_serial_jtag_ll_txfifo_writable(void)
* @brief Flushes the TX buffer, that is, make it available for the
* host to pick up.
*
* @note When fifo is full (with 64 byte), HW will flush the buffer automatically.
* It won't be executed if there is nothing in the fifo.
* @note When fifo is full (with 64 byte), HW will flush the buffer automatically,
* if this function is called directly after, this effectively turns into a
* no-op. Because a 64-byte packet will be interpreted as a not-complete USB
* transaction, you need to transfer either more data or a zero-length packet
* for the data to actually end up at the program listening to the CDC-ACM
* serial port. To send a zero-length packet, call
* usb_serial_jtag_ll_txfifo_flush() again when
* usb_serial_jtag_ll_txfifo_writable() returns true.
*
* @return na
*/

12
components/hal/esp32c6/include/hal/usb_serial_jtag_ll.h
Wyświetl plik

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@ -161,8 +161,14 @@ static inline int usb_serial_jtag_ll_txfifo_writable(void)
* @brief Flushes the TX buffer, that is, make it available for the
* host to pick up.
*
* @note When fifo is full (with 64 byte), HW will flush the buffer automatically.
* It won't be executed if there is nothing in the fifo.
* @note When fifo is full (with 64 byte), HW will flush the buffer automatically,
* if this function is called directly after, this effectively turns into a
* no-op. Because a 64-byte packet will be interpreted as a not-complete USB
* transaction, you need to transfer either more data or a zero-length packet
* for the data to actually end up at the program listening to the CDC-ACM
* serial port. To send a zero-length packet, call
* usb_serial_jtag_ll_txfifo_flush() again when
* usb_serial_jtag_ll_txfifo_writable() returns true.
*
* @return na
*/

12
components/hal/esp32h2/include/hal/usb_serial_jtag_ll.h
Wyświetl plik

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@ -161,8 +161,14 @@ static inline int usb_serial_jtag_ll_txfifo_writable(void)
* @brief Flushes the TX buffer, that is, make it available for the
* host to pick up.
*
* @note When fifo is full (with 64 byte), HW will flush the buffer automatically.
* It won't be executed if there is nothing in the fifo.
* @note When fifo is full (with 64 byte), HW will flush the buffer automatically,
* if this function is called directly after, this effectively turns into a
* no-op. Because a 64-byte packet will be interpreted as a not-complete USB
* transaction, you need to transfer either more data or a zero-length packet
* for the data to actually end up at the program listening to the CDC-ACM
* serial port. To send a zero-length packet, call
* usb_serial_jtag_ll_txfifo_flush() again when
* usb_serial_jtag_ll_txfifo_writable() returns true.
*
* @return na
*/

11
components/hal/esp32s3/include/hal/usb_serial_jtag_ll.h
Wyświetl plik

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@ -161,6 +161,15 @@ static inline int usb_serial_jtag_ll_txfifo_writable(void)
* @brief Flushes the TX buffer, that is, make it available for the
* host to pick up.
*
* @note When fifo is full (with 64 byte), HW will flush the buffer automatically,
* if this function is called directly after, this effectively turns into a
* no-op. Because a 64-byte packet will be interpreted as a not-complete USB
* transaction, you need to transfer either more data or a zero-length packet
* for the data to actually end up at the program listening to the CDC-ACM
* serial port. To send a zero-length packet, call
* usb_serial_jtag_ll_txfifo_flush() again when
* usb_serial_jtag_ll_txfifo_writable() returns true.
*
* @return na
*/
static inline void usb_serial_jtag_ll_txfifo_flush(void)

4
components/vfs/vfs_usb_serial_jtag.c
Wyświetl plik

@ -270,6 +270,10 @@ static int usb_serial_jtag_fsync(int fd)
while ((esp_timer_get_time() - s_ctx.last_tx_ts) < TX_FLUSH_TIMEOUT_US) {
if (usb_serial_jtag_ll_txfifo_writable()) {
s_ctx.last_tx_ts = esp_timer_get_time();
//The last transfer may have been a 64-byte one. Flush again in order to
//send a 0-byte packet to indicate the end of the USB transfer, otherwise
//those 64 bytes will get stuck in the hosts buffer.
usb_serial_jtag_ll_txfifo_flush();
break;
}
}

4
docs/en/api-guides/usb-serial-jtag-console.rst
Wyświetl plik

@ -58,6 +58,10 @@ There are several limitations to the USB Serial/JTAG console feature. These may
{IDF_TARGET_BOOT_PIN:default = "Not Updated!", esp32c3 = "GPIO9", esp32s3 = "GPIO0", esp32c6 = "GPIO9"}
1. If the application accidentally reconfigures the USB peripheral pins, or disables the USB Serial/JTAG Controller, the device will disappear from the system. After fixing the issue in the application, you will need to manually put the {IDF_TARGET_NAME} into download mode by pulling low {IDF_TARGET_BOOT_PIN} and resetting the chip.
.. note::
In rare cases it's possible that data sent from the {IDF_TARGET_NAME} to the host gets 'stuck' in host memory. Sending more data will get it 'unstuck', but if the application does not send more data, depending on the driver, this data needs to be flushed to the host manually. The non-blocking (default) driver and the VFS implementation will flush automatically after a newline. The blocking (interrupt-based) driver will automatically flush when its transmit buffer becomes empty.
2. If the application enters deep sleep mode, the USB Serial/JTAG device will disappear from the system.