[Core] Split ChibiOS usart split driver in protocol and hardware driver part

[KarlK90]

This PR builds upon #15907 and #16647 for review please ignore the commits belonging to these.

Description

Goal of this PR is to re-use the protocol logic of the existing ChibiOS usart driver for other means of transportation. Drivers implementing the protocol just need to provide the following methods to work:

/**
 * @brief Clears any intermediate sending or receiving state of the driver to a known good
 * state. This happens after errors in the middle of transactions, to start with
 * a clean slate.
 */
void serial_transport_driver_clear(void);

/**
 * @brief Driver specific initialization on the slave half.
 */
void serial_transport_driver_slave_init(void);

/**
 * @brief Driver specific specific initialization on the master half.
 */
void serial_transport_driver_master_init(void);

/**
 * @brief  Blocking receive of size * bytes.
 *
 * @return true Receive success.
 * @return false Receive failed, e.g. by bit errors.
 */
bool __attribute__((nonnull, hot)) serial_transport_receive(uint8_t* destination, const size_t size);

/**
 * @brief Blocking receive of size * bytes with an implicitly defined timeout.
 *
 * @return true Receive success.
 * @return false Receive failed, e.g. by timeout or bit errors.
 */
bool __attribute__((nonnull, hot)) serial_transport_receive_blocking(uint8_t* destination, const size_t size);

/**
 * @brief Blocking send of buffer with timeout.
 *
 * @return true Send success.
 * @return false Send failed, e.g. by timeout or bit errors.
 */
bool __attribute__((nonnull, hot)) serial_transport_send(const uint8_t* source, const size_t size);

The first successful use-case is the usage of the PIO peripheral on the RP2040 MCU to implement Half-duplex and Full-duplex UART split keyboard communication.

I have tested these changes successfully with both SIO, SERIAL and PIO drivers.

Types of Changes

• Core
• Bugfix
• New feature
• Enhancement/optimization
• Keyboard (addition or update)
• Keymap/layout/userspace (addition or update)
• Documentation

Issues Fixed or Closed by This PR

• Part of [Core] Add Raspberry Pi RP2040 support #14877

Checklist

• My code follows the code style of this project: C, Python
• I have read the PR Checklist document and have made the appropriate changes.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• I have tested the changes and verified that they work and don't break anything (as well as I can manage).

[drashna]

This depends on the other prs mentioned, correct?

[KarlK90]

Correct :-)

[preisi]

I've used this PR for a "quick-and-dirty" implementation of an FDCAN-driver.
The given serial_protocol-driver interface is simple and creating my own implementation worked just fine.
(see preisi@c91e6b5)

[KarlK90]

@preisi Thanks for the feedback and recommendations, I integrated those 👍

[KarlK90]

Two notable changes that might be missed in review:

1. The previous handshake magic number 0x7 was replaced with the current number of registered transaction entries NUM_TOTAL_TRANSACTIONS this provides some simple sanity check that both firmware versions are identical. (this will fail if the transactions differ in content but not in number though)
2. The VLA in send for half-duplex serial was replaced with a fixed size buffer:

from

uint8_t dump[size];
return receive(dump, size);

to

uint8_t dump[64];
size_t  bytes_left = size;

while (unlikely(bytes_left > 64)) {
    if (unlikely(!receive(dump, 64))) {
         return false;
     }
     bytes_left -= 64;
}
receive(dump, bytes_left);

[preisi]

Looks good to me

[tzarc]

Will need to #include "util.h" if it's not already present.

Suggested change

	if (unlikely(!receive(dump, 64))) {
	if (unlikely(!receive(dump, MIN(bytes_left, 64)))) {

Prevents reading extra if the slave just happens to respond within SERIAL_USART_TIMEOUT.

[KarlK90]

I don't think that change is correct? This branch will only be executed if bytes_left > 64 so we can safely always read 64 byte. But I could make the condition bytes_left >= 64.

[tzarc]

Kiiiiiinda allergic to generic names like these.
What about:

• receive => serial_transport_receive
• receive_blocking => serial_transport_receive_blocking
• send => serial_transport_send

......just don't get me started about the naming of serial.

[KarlK90]

Ah yes, forgot about C-style namespacing. Will apply that.

[KarlK90]

Done, applied the prefix to all public methods that are part of the protocol.