Unsure, how to use interrupt UART API

[TorstenRobitzki]

Hello,
for the nrf53 the asynchronous UART API is not supported for USB ACM. Now I try to figure out, how to pass data received from the UART to the main thread of the application and vise versa.

I think I should use a k_pipe to pass data from the interrupt service routine to the main thread (feedback on that is welcome).

As there is no API to get access to a put area of the pipe, I request the available room in the pipe used to received data (k_pipe_write_avail()), copy data from the UART to a local buffer (uart_fifo_read()) and then write that local buffer to the pipe (k_pipe_put()). This extra copy through the local data feels already clumsy and I wonder, if it could be avoided.

On the other side, where I receive data from the main thread, to be send in the ISR, I can request a minimum size of data in the pipe (k_pipe_read_avail()), but when feeding that data to the uart, I could end up in a situation, where uart_fifo_fill() will return a size less than what has been read from the pipe. I would have to store that data, that was read from the pipe but was not filled into the fifo somewhere, and feed that second buffer to the fifo, once there is room again in the uart. This feels super clumsy and unnecessary complicated.

Am I'm missing something here? I'm super new to Zephyr and maybe I have picked the wrong primitives, or even using the totally wrong approach here?

thanks in advance,
Torsten

[ndrs-pst]

@TorstenRobitzki, To get a better understanding of the UART API, I suggest searching the code base for instances of the functions uart_fifo_fill and uart_fifo_read. This will provide you with real-world usage examples.

Additionally, for a practical demonstration, take a look at the CDC ACM sample in the Zephyr Project repository.

[TorstenRobitzki]

Hi @ndrs-pst
basically, I found 3 different usages. Some, which simply ignore the result of uart_fifo_fill, some that did their own buffer management and a few used net_buf_pull.

The CDC ACM sample, just copies the received data via a ring buffer to the output, and just logs the case, where uart_fifo_fill returns less than what was read from the ring buffer before.

So, I'm going to read the net_buf_pull documentation. Maybe k_pipe is not the right device for the task.

Thank you!

Torsten

[metratec-mkoehler]

I ran into the same issue right now. I used to use ring buffers (which usually should be safe but technically are not). Adding a semaphore makes it even more obvious: If anything prevents me from putting my read data to it's buffer (or the other way around, prevents me from taking data from the buffer to send it) the API gets kind of stuck as all it's functions require by API definition to be called from the UART ISR (otherwise behaviour is undefined). So in case of RX the data will be processed when the next data arrives, causing a new interrupt. In case of TX it is even stuck as there won't be a new even at all (the IRQ must be disabled while the UART is still in transmit, this is especially bad if the TX Done is needed for some reason).

Overall it seems unsave. The sample for UART and USB CDC ACM both just loop inside their ISR (which means the TX handler has to disable the TX IRQ or the ISR will stay in the loop). I can't get another TX interrupt if I can't fill it immediately and a fill without interrupt is not supported.

[TorstenRobitzki]

I finally solve my issue with the API, by writing a thread safe queue (ring buffer), that gives me access to the size of put and get areas. For example, on the reading end of the UART:

        if ( uart_irq_rx_ready( uart ) )
        {
            std::size_t receive_length = 0;
            auto& buffer = usb_cdc_instance->get_receive_buffer();
            auto put_area = buffer.put_area();

            do {
                const auto receive_length = uart_fifo_read( uart, put_area.data(), put_area.size() );
                assert( receive_length >= 0 );

                buffer.advance_put_area( receive_length );
                put_area = buffer.put_area();

            } while ( receive_length != 0 && !put_area.empty() );

            if ( put_area.empty() )
                uart_irq_rx_disable( uart );
        }

As long, as there is only one producer, putting data into the buffer, it is safe to assume, that the area, the data can be put into, only grows if there are concurrent access from the consumer. The loop in this example is just to cover the case, where the ring is split and a second call to buffer.put_area() would yield an other free part of the ring.

From a user perspective, having the choise between 3 different APIs sounds very promising. But when I have to take into account, that a vendor could always skip one of the implementation, I end up with implementing all 3 APIs if I want to be platform neutral.

Given the implementation above, one could argue that implementing that directly on the peripherals would probably end up in way less code, that would be easier to understand.

[metratec-mkoehler]

That's definitely an improvement, but it does not solve the case of a put_area == 0
Also Is see the disable, but it would only work if the end of the current data in uart buffer isn't the last byte. If it is there will be no new rx interrupt when reenabled.

[TorstenRobitzki]

If the available size on the devices receiving side, is zero (put_area == 0), then uart_fifo_read is called with zero size and thus, none of the internally stored data is removed. And that is the point: just accept that amount of data, that really can be handled.

The interrupt is disabled, because there is no point in receiving this interrupt again as long as there is no available buffer on the receiving side. As soon, as new room becomes available, the interrupt will be enabled again and this will then (if there is still data pending) trigger the interrupt again.