Update UART driver with specs, documentaion, and read/2

[UncleGrumpy]

Updates the UART driver to include function specs and documentation.
Fixes possible concurrency problems, and insufficient sized memory checks.
Now cleans up and returns errors when initializing with badarg parameters.
Adds new uart:read/2 with a timeout parameter.

Closes #1446

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

[petermm]

works, great! even when doing hundreds of uart:read per second!

[UncleGrumpy]

I pushed changes that eliminate the use of any timer or task in the C code, and instead added a cancel_read command, handling the timeout and sending the cancel command from erlang, following the suggestion @pguyot made.

I believe this is much more efficient, and less resource intensive than creating a timer.

[pguyot]

Thank you for this new version! Besides the little bug on timeout result, could you please fix potential concurrency issues?

[petermm]

Works great still.

nitpick:
Should it only take a positive integer as timeout value? pos_integer()

Tried :uart.read(port, 0) but it would never get a read, of course also a nonsensical value..

[UncleGrumpy]

Thank you for this new version! Besides the little bug on timeout result, could you please fix potential concurrency issues?

Yes. I see what you mean now, I thought your comment about concurrency was related to the previous implementation, but I see now that you were talking about pre-existing concurrency problems.

[pguyot]

Yes. I see what you mean now, I thought your comment about concurrency was related to the previous implementation, but I see now that you were talking about pre-existing concurrency problems.

Exactly. And issues could be amplified by the new code.

[UncleGrumpy]

This should be ready for another look. I made more bug fixes that should be checked.

[pguyot]

Do you want to take advantage of this PR to change the if (xQueueRemove(...)) into a while? It would make queue overflow less likely.

[UncleGrumpy]

Do you want to take advantage of this PR to change the if (xQueueRemove(...)) into a while? It would make queue overflow less likely.

I @almost overlooked this. Great idea, I added that change.

[robinchew]

httpd_example cannot load index.html if you open UART a certain way using this PR.

This issue does NOT occur in commit 4d38f90 of this PR.

Find my modified http_example code here robinchew/atomvm_lib@033a226 which is essentially the following code which spawns a process that opens UART a certain way before httpd:start:

    spawn(fun() ->
        Port = uart:open("UART2", [{rx, 16}, {tx, 17}]), % need to set rx and tx, and maybe UART2 as well
        io:format("port ~p~n", [Port]),
    end),
    
    httpd:start(....)

Trying to load index.html would result with:

~$ curl -v http://192.168.1.43:8080/index.html
*   Trying 192.168.1.43:8080...
* connect to 192.168.1.43 port 8080 from 192.168.1.4 port 37574 failed: Connection refused
* Failed to connect to 192.168.1.43 port 8080 after 306 ms: Couldn't connect to server
* Closing connection
curl: (7) Failed to connect to 192.168.1.43 port 8080 after 306 ms: Couldn't connect to server

[UncleGrumpy]

Do you want to take advantage of this PR to change the if (xQueueRemove(...)) into a while? It would make queue overflow less likely.

I did really want to do this, but realized we can't without a lot more rewriting, or requiring the uart_driver sit behind a gen_server... as we have it now if there is no message to read immediately, the caller can drop into a receive and get the next message, at which point they would likely use a read to get the next incoming message. There is no way for the application to know that we are about to send another message from the queue after the first message is received.

[UncleGrumpy]

I did add log errors for FIFO overflow, parity and frame errors, and a warning when the uart buffer is full. At least this way application developers will be aware when these events occur, and debugging communication problems may be easier knowing if the wrong parity is used.

[UncleGrumpy]

httpd_example cannot load index.html if you open UART a certain way using this PR.

This issue does NOT occur in commit 4d38f90 of this PR.
...

Thank you for testing and the follow up here. This was a mistake, I believe it should work much better now.