[riot-notifications] [RIOT-OS/RIOT] periph/uart: Fix doc, use errno for return values (#16632)

Marian Buschsieweke notifications at github.com
Sat Jul 10 07:00:53 CEST 2021

> I there's already an enum for return values, why try to match errno.h? errno.h is not consistent across platforms. and it does make creation of bindings quite a bit more difficult, because they're suddenly dependent on the C library headers.

IMO this is too late for this discussion, as there is already an agreement reached that this is how generally drivers should look like in https://github.com/RIOT-OS/RIOT/pull/15018 and other APIs already have been converted to match this.

But let me repeat the arguments:

1. It eases binding to POSIX APIs, which no longer have to magically convert custom error constats to errno constats
2. It reduces ROM size, as e.g. drivers using UART no longer need to convert UART specific error codes to driver specific error codes (a pattern often seen in RIOT when either periph or driver API is not using errno codes)
3. It eases debugging, as one does not have to look up driver specific error code.
4. User friendly error messages can be generated simply by using `strerror()` 
5. It aids consistency throughout RIOT

> changing it will cause extra work for others.

It worked fine when we changed the SPI API, why shouldn't it work fine again here?

> And for symbol rate - "baud rate" is so accepted everywhere, everyone understands it. "symbol rate" might be more correct, but where else is it used to specify the baud rate? It would confuse me to see this here.

A rate refers to a change over time. So baudrate would be measured e.g. in symbols per squaresecond. So while symbol rate is the speed of the UART, baudrate could only be understood as the acceleration of the UART. Hopefully the baudrate of the device is always zero, as otherwise the symbol rate of sender and receiver would diverge and communication becomes unsuitable.

Honestly, incorrect terminology never helped to avoid confusion, it only causes it. I can assure you that students are learning the correct terminology and are confused by the term "baudrate". I don't think blindly repeating mistakes so that older generation engineers don't have to learn correct terminology is a good option.

You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20210709/8a654435/attachment.htm>

More information about the notifications mailing list