serial: uart_irq_tx_ready() needs better documentation or correction of the test

[anangl]

During a PR review, some confusion about the expected behavior of the uart_irq_tx_ready function popped out, see this comment and replies to it.

Apparently, some existing Zephyr code expects this function to return true only when the TX interrupt is enabled (see for instance drivers/bluetooth/hci/h4.c or subsys/shell/shell_uart.c) and this function returning true is even treated as an indication that some TX action should be done, while from reading the API description one can conclude that this only indicates that TX action is possible because "UART TX buffer can accept at least one character for transmission".
Indeed, most of UART drivers implement this function in the way described above, but some exceptions seems to be also present (see uart_stm32.c). And the basic UART API test seems to also not follow this approach.

To avoid further confusion, it should be clarified what is the actually required behavior of the function.

[tautologyclub]

I've tried to get this clarified from Nordic before.

Why should the UART fifo be ready to receive bytes if TX interrupts are disabled? That makes no sense. The API specifies clearly that calling fifo_fill from outside interrupt context is undefined. Thus, if TX interrupts are disabled, clearly the UART fifo can impossibly be in a state where it's ready to accept transfers.

Out of curiosity, would ANY samples/tests relying on interrupt-driven UART currently not fail horribly with the current nRF implementation?

[carlescufi]

@jarz-nordic or @Mierunski could you take a stab at this one please?

[tautologyclub]

Well the situation isn't as bad as I originally thought, I was under the impression that Nordic had misimplemented the API and then abandoned a broken implementation with the justification that "a new API is upcoming anyway". But it's not so bad.

[jakub-uC]

@tautologyclub : I apologize once more for being rude before.

Now lets digg into your concerns. First:

Why should the UART fifo be ready to receive bytes if TX interrupts are disabled? That makes no sense.

According to old Zephyr UART API description function uart_irq_tx_ready shall not be called outside of interrupt context. Please let me know why it bothers you what status it will return when called outside of interrupt context?

Thus, if TX interrupts are disabled, clearly the UART fifo can impossibly be in a state where it's ready to accept transfers.

Clearly. But there is no API function to check this readiness outside of interrupt context.

Out of curiosity, would ANY samples/tests relying on interrupt-driven UART currently not fail horribly with the current nRF implementation?

May you please elaborate a it more about that? What example? We are trying to fix all bugs as soon as possible.

[jakub-uC]

Yes, new API has been introduced to avoid future misunderstandings.

[tautologyclub]

@jarz-nordic You can call uart_irq_tx_ready from interrupt context without TX interrupts being enabled, no? From what I can recall, this seemed to be the pattern in plenty of samples. Maybe there's been a purge lately, or I am just misremembering. Anyway, the whole thing is solved by using uart_irq_is_pending(dev) appropriately so I don't think it's a terribly big deal. Documentation could be better regarding the whole UART api, but that seems to be on its way.

[jakub-uC]

@tautologyclub : yes it is inconsistency. uart_irq_tx_ready should not be called when uart tx interrupt is not active because it might return true in a special case. It will be after UART (not applicable for UARTE) initialization and before first transmission.