diff options
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/serial_driver.md | 59 | ||||
| -rw-r--r-- | drivers/chibios/serial.h | 62 | ||||
| -rw-r--r-- | drivers/chibios/serial_usart.c | 234 |
4 files changed, 356 insertions, 0 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index b711ab7d9..0e82ab4f0 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -128,6 +128,7 @@ * [SPI Driver](spi_driver.md) * [WS2812 Driver](ws2812_driver.md) * [EEPROM Driver](eeprom_driver.md) + * ['serial' Driver](serial_driver.md) * [GPIO Controls](internals_gpio_control.md) * [Keyboard Guidelines](hardware_keyboard_guidelines.md) diff --git a/docs/serial_driver.md b/docs/serial_driver.md new file mode 100644 index 000000000..395b3ec3f --- /dev/null +++ b/docs/serial_driver.md @@ -0,0 +1,59 @@ +# 'serial' Driver +This driver powers the [Split Keyboard](feature_split_keyboard.md) feature. + +!> Serial in this context should be read as **sending information one bit at a time**, rather than implementing UART/USART/RS485/RS232 standards. + +All drivers in this category have the following characteristics: +* Provides data and signaling over a single conductor +* Limited to single master, single slave + +## Supported Driver Types + +| | AVR | ARM | +|-------------------|--------------------|--------------------| +| bit bang | :heavy_check_mark: | Soon™ | +| USART Half-duplex | | :heavy_check_mark: | + +## Driver configuration + +### Bitbang +Default driver, the absence of configuration assumes this driver. To configure it, add this to your rules.mk: + +```make +SERIAL_DRIVER = bitbang +``` + +Configure the driver via your config.h: +```c +#define SOFT_SERIAL_PIN D0 // or D1, D2, D3, E6 +#define SELECT_SOFT_SERIAL_SPEED 1 // or 0, 2, 3, 4, 5 + // 0: about 189kbps (Experimental only) + // 1: about 137kbps (default) + // 2: about 75kbps + // 3: about 39kbps + // 4: about 26kbps + // 5: about 20kbps +``` + +### USART Half-duplex +Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage is that this provides fast and accurate timings. `SOFT_SERIAL_PIN` for this driver is the configured USART TX pin. **The TX pin must have appropriate pull-up resistors**. To configure it, add this to your rules.mk: + +```make +SERIAL_DRIVER = usart +``` + +Configure the hardware via your config.h: +```c +#define SOFT_SERIAL_PIN B6 // USART TX pin +#define SELECT_SOFT_SERIAL_SPEED 1 // or 0, 2, 3, 4, 5 + // 0: about 460800 baud + // 1: about 230400 baud (default) + // 2: about 115200 baud + // 3: about 57600 baud + // 4: about 38400 baud + // 5: about 19200 baud +#define SERIAL_USART_DRIVER SD1 // USART driver of TX pin. default: SD1 +#define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 +``` + +You must also turn on the SERIAL feature in your halconf.h and mcuconf.h diff --git a/drivers/chibios/serial.h b/drivers/chibios/serial.h new file mode 100644 index 000000000..0c1857d52 --- /dev/null +++ b/drivers/chibios/serial.h @@ -0,0 +1,62 @@ +#pragma once + +#include <stdbool.h> + +// ///////////////////////////////////////////////////////////////// +// Need Soft Serial defines in config.h +// ///////////////////////////////////////////////////////////////// +// ex. +// #define SOFT_SERIAL_PIN ?? // ?? = D0,D1,D2,D3,E6 +// OPTIONAL: #define SELECT_SOFT_SERIAL_SPEED ? // ? = 1,2,3,4,5 +// // 1: about 137kbps (default) +// // 2: about 75kbps +// // 3: about 39kbps +// // 4: about 26kbps +// // 5: about 20kbps +// +// //// USE simple API (using signle-type transaction function) +// /* nothing */ +// //// USE flexible API (using multi-type transaction function) +// #define SERIAL_USE_MULTI_TRANSACTION +// +// ///////////////////////////////////////////////////////////////// + +// Soft Serial Transaction Descriptor +typedef struct _SSTD_t { + uint8_t *status; + uint8_t initiator2target_buffer_size; + uint8_t *initiator2target_buffer; + uint8_t target2initiator_buffer_size; + uint8_t *target2initiator_buffer; +} SSTD_t; +#define TID_LIMIT(table) (sizeof(table) / sizeof(SSTD_t)) + +// initiator is transaction start side +void soft_serial_initiator_init(SSTD_t *sstd_table, int sstd_table_size); +// target is interrupt accept side +void soft_serial_target_init(SSTD_t *sstd_table, int sstd_table_size); + +// initiator result +#define TRANSACTION_END 0 +#define TRANSACTION_NO_RESPONSE 0x1 +#define TRANSACTION_DATA_ERROR 0x2 +#define TRANSACTION_TYPE_ERROR 0x4 +#ifndef SERIAL_USE_MULTI_TRANSACTION +int soft_serial_transaction(void); +#else +int soft_serial_transaction(int sstd_index); +#endif + +// target status +// *SSTD_t.status has +// initiator: +// TRANSACTION_END +// or TRANSACTION_NO_RESPONSE +// or TRANSACTION_DATA_ERROR +// target: +// TRANSACTION_DATA_ERROR +// or TRANSACTION_ACCEPTED +#define TRANSACTION_ACCEPTED 0x8 +#ifdef SERIAL_USE_MULTI_TRANSACTION +int soft_serial_get_and_clean_status(int sstd_index); +#endif diff --git a/drivers/chibios/serial_usart.c b/drivers/chibios/serial_usart.c new file mode 100644 index 000000000..62b4913cb --- /dev/null +++ b/drivers/chibios/serial_usart.c @@ -0,0 +1,234 @@ +#include "quantum.h" +#include "serial.h" +#include "printf.h" + +#include "ch.h" +#include "hal.h" + +#ifndef USART_CR1_M0 +# define USART_CR1_M0 USART_CR1_M // some platforms (f1xx) dont have this so +#endif + +#ifndef USE_GPIOV1 +// The default PAL alternate modes are used to signal that the pins are used for USART +# ifndef SERIAL_USART_TX_PAL_MODE +# define SERIAL_USART_TX_PAL_MODE 7 +# endif +#endif + +#ifndef SERIAL_USART_DRIVER +# define SERIAL_USART_DRIVER SD1 +#endif + +#ifndef SERIAL_USART_CR1 +# define SERIAL_USART_CR1 (USART_CR1_PCE | USART_CR1_PS | USART_CR1_M0) // parity enable, odd parity, 9 bit length +#endif + +#ifndef SERIAL_USART_CR2 +# define SERIAL_USART_CR2 (USART_CR2_STOP_1) // 2 stop bits +#endif + +#ifndef SERIAL_USART_CR3 +# define SERIAL_USART_CR3 0 +#endif + +#ifdef SOFT_SERIAL_PIN +# define SERIAL_USART_TX_PIN SOFT_SERIAL_PIN +#endif + +#ifndef SELECT_SOFT_SERIAL_SPEED +# define SELECT_SOFT_SERIAL_SPEED 1 +#endif + +#ifdef SERIAL_USART_SPEED +// Allow advanced users to directly set SERIAL_USART_SPEED +#elif SELECT_SOFT_SERIAL_SPEED == 0 +# define SERIAL_USART_SPEED 460800 +#elif SELECT_SOFT_SERIAL_SPEED == 1 +# define SERIAL_USART_SPEED 230400 +#elif SELECT_SOFT_SERIAL_SPEED == 2 +# define SERIAL_USART_SPEED 115200 +#elif SELECT_SOFT_SERIAL_SPEED == 3 +# define SERIAL_USART_SPEED 57600 +#elif SELECT_SOFT_SERIAL_SPEED == 4 +# define SERIAL_USART_SPEED 38400 +#elif SELECT_SOFT_SERIAL_SPEED == 5 +# define SERIAL_USART_SPEED 19200 +#else +# error invalid SELECT_SOFT_SERIAL_SPEED value +#endif + +#define TIMEOUT 100 +#define HANDSHAKE_MAGIC 7 + +static inline msg_t sdWriteHalfDuplex(SerialDriver* driver, uint8_t* data, uint8_t size) { + msg_t ret = sdWrite(driver, data, size); + + // Half duplex requires us to read back the data we just wrote - just throw it away + uint8_t dump[size]; + sdRead(driver, dump, size); + + return ret; +} +#undef sdWrite +#define sdWrite sdWriteHalfDuplex + +static inline msg_t sdWriteTimeoutHalfDuplex(SerialDriver* driver, uint8_t* data, uint8_t size, uint32_t timeout) { + msg_t ret = sdWriteTimeout(driver, data, size, timeout); + + // Half duplex requires us to read back the data we just wrote - just throw it away + uint8_t dump[size]; + sdReadTimeout(driver, dump, size, timeout); + + return ret; +} +#undef sdWriteTimeout +#define sdWriteTimeout sdWriteTimeoutHalfDuplex + +static inline void sdClear(SerialDriver* driver) { + while (sdGetTimeout(driver, TIME_IMMEDIATE) != MSG_TIMEOUT) { + // Do nothing with the data + } +} + +static SerialConfig sdcfg = { + (SERIAL_USART_SPEED), // speed - mandatory + (SERIAL_USART_CR1), // CR1 + (SERIAL_USART_CR2), // CR2 + (SERIAL_USART_CR3) // CR3 +}; + +void handle_soft_serial_slave(void); + +/* + * This thread runs on the slave and responds to transactions initiated + * by the master + */ +static THD_WORKING_AREA(waSlaveThread, 2048); +static THD_FUNCTION(SlaveThread, arg) { + (void)arg; + chRegSetThreadName("slave_transport"); + + while (true) { + handle_soft_serial_slave(); + } +} + +__attribute__((weak)) void usart_init(void) { +#if defined(USE_GPIOV1) + palSetLineMode(SERIAL_USART_TX_PIN, PAL_MODE_STM32_ALTERNATE_OPENDRAIN); +#else + palSetLineMode(SERIAL_USART_TX_PIN, PAL_MODE_ALTERNATE(SERIAL_USART_TX_PAL_MODE) | PAL_STM32_OTYPE_OPENDRAIN); +#endif +} + +void usart_master_init(void) { + usart_init(); + + sdcfg.cr3 |= USART_CR3_HDSEL; + sdStart(&SERIAL_USART_DRIVER, &sdcfg); +} + +void usart_slave_init(void) { + usart_init(); + + sdcfg.cr3 |= USART_CR3_HDSEL; + sdStart(&SERIAL_USART_DRIVER, &sdcfg); + + // Start transport thread + chThdCreateStatic(waSlaveThread, sizeof(waSlaveThread), HIGHPRIO, SlaveThread, NULL); +} + +static SSTD_t* Transaction_table = NULL; +static uint8_t Transaction_table_size = 0; + +void soft_serial_initiator_init(SSTD_t* sstd_table, int sstd_table_size) { + Transaction_table = sstd_table; + Transaction_table_size = (uint8_t)sstd_table_size; + + usart_master_init(); +} + +void soft_serial_target_init(SSTD_t* sstd_table, int sstd_table_size) { + Transaction_table = sstd_table; + Transaction_table_size = (uint8_t)sstd_table_size; + + usart_slave_init(); +} + +void handle_soft_serial_slave(void) { + uint8_t sstd_index = sdGet(&SERIAL_USART_DRIVER); // first chunk is always transaction id + SSTD_t* trans = &Transaction_table[sstd_index]; + + // Always write back the sstd_index as part of a basic handshake + sstd_index ^= HANDSHAKE_MAGIC; + sdWrite(&SERIAL_USART_DRIVER, &sstd_index, sizeof(sstd_index)); + + if (trans->initiator2target_buffer_size) { + sdRead(&SERIAL_USART_DRIVER, trans->initiator2target_buffer, trans->initiator2target_buffer_size); + } + + if (trans->target2initiator_buffer_size) { + sdWrite(&SERIAL_USART_DRIVER, trans->target2initiator_buffer, trans->target2initiator_buffer_size); + } + + if (trans->status) { + *trans->status = TRANSACTION_ACCEPTED; + } +} + +///////// +// start transaction by initiator +// +// int soft_serial_transaction(int sstd_index) +// +// Returns: +// TRANSACTION_END +// TRANSACTION_NO_RESPONSE +// TRANSACTION_DATA_ERROR +#ifndef SERIAL_USE_MULTI_TRANSACTION +int soft_serial_transaction(void) { + uint8_t sstd_index = 0; +#else +int soft_serial_transaction(int index) { + uint8_t sstd_index = index; +#endif + + if (sstd_index > Transaction_table_size) return TRANSACTION_TYPE_ERROR; + SSTD_t* trans = &Transaction_table[sstd_index]; + msg_t res = 0; + + sdClear(&SERIAL_USART_DRIVER); + + // First chunk is always transaction id + sdWriteTimeout(&SERIAL_USART_DRIVER, &sstd_index, sizeof(sstd_index), TIME_MS2I(TIMEOUT)); + + uint8_t sstd_index_shake = 0xFF; + + // Which we always read back first so that we can error out correctly + // - due to the half duplex limitations on return codes, we always have to read *something* + // - without the read, write only transactions *always* succeed, even during the boot process where the slave is not ready + res = sdReadTimeout(&SERIAL_USART_DRIVER, &sstd_index_shake, sizeof(sstd_index_shake), TIME_MS2I(TIMEOUT)); + if (res < 0 || (sstd_index_shake != (sstd_index ^ HANDSHAKE_MAGIC))) { + dprintf("serial::usart_shake NO_RESPONSE\n"); + return TRANSACTION_NO_RESPONSE; + } + + if (trans->initiator2target_buffer_size) { + res = sdWriteTimeout(&SERIAL_USART_DRIVER, trans->initiator2target_buffer, trans->initiator2target_buffer_size, TIME_MS2I(TIMEOUT)); + if (res < 0) { + dprintf("serial::usart_transmit NO_RESPONSE\n"); + return TRANSACTION_NO_RESPONSE; + } + } + + if (trans->target2initiator_buffer_size) { + res = sdReadTimeout(&SERIAL_USART_DRIVER, trans->target2initiator_buffer, trans->target2initiator_buffer_size, TIME_MS2I(TIMEOUT)); + if (res < 0) { + dprintf("serial::usart_receive NO_RESPONSE\n"); + return TRANSACTION_NO_RESPONSE; + } + } + + return TRANSACTION_END; +} |