Minor bug? rxbuf/read_buf_len argument in machine.UART

[ekspla]

Board: NUCLEO F446RE
MPY: 1.20.0 built from release version tar ball

In my age old projects, I used read_buf_len to specify the length of receive buffer.
Now, I see in the latest docs that the recommended way is to use rxbuf, and the older one is Legacy and is there for compatibility in pyboards.

Today, I mistakenly used the following code.

MicroPython v1.20.0 on 2023-08-19; NUCLEO-F446RE with STM32F446xx
Type "help()" for more information.
>>> from machine import UART
>>> uart = UART(2, 115200, rxbuf=1000)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: UART is static and rxbuf can't be changed
>>>

The error was caused by UART2 assigned to REPL in mpconfigboard.h as follows:

// UART config
#define MICROPY_HW_UART2_TX     (pin_A2)
#define MICROPY_HW_UART2_RX     (pin_A3)
#define MICROPY_HW_UART6_TX     (pin_C6)
#define MICROPY_HW_UART6_RX     (pin_C7)
// UART 2 connects to the STM32F103 (STLINK) on the Nucleo board
// and this is exposed as a USB Serial port.
#define MICROPY_HW_UART_REPL        PYB_UART_2
#define MICROPY_HW_UART_REPL_BAUD   115200

However, the following code using the older argument does not show an error.

>>> uart = UART(2, 115200, read_buf_len=1000)
>>>

Is this an expected behaviour? What would happen if I changed the buffer length
of UART already attatched to REPL?

[peterhinch]

I can't explain the argument name issue and would want to check if the old arg had actually worked.

What would happen if I changed the buffer length of UART already attatched to REPL?

This is an instance of the more general case of calling .init() on any running UART instance. The buffer is a circular buffer populated by an interrupt service routine (ISR); it must occupy contiguous memory locations. If you change its size, a new buffer is allocated and the ISR pointed at it. The old buffer is de-allocated. I would assume that there is a risk of data loss. In the general case you cold disable interrupts, read the data, change the buffer size, and re-enable interrupts. If you did this quickly enough (relative to the baudrate) you could avoid loss.

[ekspla]

@peterhinch Thanks for the explanation. So, the arguments of rxbuf=n and read_buf_len=n are not necessarily equal each other, because the former one prohibits to re-init the buffer while the latter does not.

[robert-hh]

However, the following code using the older argument does not show an error.

Looking into the code, there is only one small difference in the handling of rxbuf vs. read_buf_len, if the UART is static. According to the error message, that seems to be the case for UART2 in your tests. For static UARTs, setting the buffer size via rxbuf raises en error, while any setting for read_buf_len seems to be ignored silently. For non-static UARTs the values for rxbuf and read_buf_len are treated identical.

[ekspla]

For static UARTs, setting the buffer size via rxbuf raises en error, while any setting for read_buf_len seems to be ignored silently. For non-static UARTs the values for rxbuf and read_buf_len are treated identical.

@robert-hh
I see. Thanks for the detailed explanation.