src/main/drivers/serial.h

   1 /*
   2  * This file is part of Cleanflight and Betaflight.
   3  *
   4  * Cleanflight and Betaflight are free software. You can redistribute
   5  * this software and/or modify this software under the terms of the
   6  * GNU General Public License as published by the Free Software
   7  * Foundation, either version 3 of the License, or (at your option)
   8  * any later version.
   9  *
  10  * Cleanflight and Betaflight are distributed in the hope that they
  11  * will be useful, but WITHOUT ANY WARRANTY; without even the implied
  12  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  13  * See the GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this software.
  17  *
  18  * If not, see <http://www.gnu.org/licenses/>.
  19  */
  20
  21 #pragma once
  22
  23 #include "drivers/io.h"
  24 #include "drivers/io_types.h"
  25 #include "drivers/resource.h"
  26 // TODO(hertz@): uncomment and use UARTDevice_e::MAX_UARTDEV
  27 // #include "drivers/serial_uart.h"
  28
  29 #include "pg/pg.h"
  30
  31 typedef enum {
  32     MODE_RX = 1 << 0,
  33     MODE_TX = 1 << 1,
  34     MODE_RXTX = MODE_RX | MODE_TX
  35 } portMode_e;
  36
  37 typedef enum {
  38     SERIAL_NOT_INVERTED  = 0 << 0,
  39     SERIAL_INVERTED      = 1 << 0,
  40     SERIAL_STOPBITS_1    = 0 << 1,
  41     SERIAL_STOPBITS_2    = 1 << 1,
  42     SERIAL_PARITY_NO     = 0 << 2,
  43     SERIAL_PARITY_EVEN   = 1 << 2,
  44     SERIAL_UNIDIR        = 0 << 3,
  45     SERIAL_BIDIR         = 1 << 3,
  46
  47     /*
  48      * Note on SERIAL_BIDIR_PP
  49      * With SERIAL_BIDIR_PP, the very first start bit of back-to-back bytes
  50      * is lost and the first data byte will be lost by a framing error.
  51      * To ensure the first start bit to be sent, prepend a zero byte (0x00)
  52      * to actual data bytes.
  53      */
  54     SERIAL_BIDIR_OD        = 0 << 4,
  55     SERIAL_BIDIR_PP        = 1 << 4,
  56     SERIAL_BIDIR_NOPULL    = 1 << 5, // disable pulls in BIDIR RX mode
  57     SERIAL_BIDIR_PP_PD     = 1 << 6, // PP mode, normall inverted, but with PullDowns, to fix SA after bidir issue fixed (#10220)
  58
  59     // If this option is set then switch the TX line to input when not in use to detect it being pulled low
  60     SERIAL_CHECK_TX        = 1 << 7,
  61 } portOptions_e;
  62
  63 // Define known line control states which may be passed up by underlying serial driver callback
  64 #define CTRL_LINE_STATE_DTR (1 << 0)
  65 #define CTRL_LINE_STATE_RTS (1 << 1)
  66
  67 typedef void (*serialReceiveCallbackPtr)(uint16_t data, void *rxCallbackData);   // used by serial drivers to return frames to app
  68 typedef void (*serialIdleCallbackPtr)();
  69
  70 typedef struct serialPort_s {
  71
  72     const struct serialPortVTable *vTable;
  73
  74     portMode_e mode;
  75     portOptions_e options;
  76
  77     uint32_t baudRate;
  78
  79     uint32_t rxBufferSize;
  80     uint32_t txBufferSize;
  81     volatile uint8_t *rxBuffer;
  82     volatile uint8_t *txBuffer;
  83     uint32_t rxBufferHead;
  84     uint32_t rxBufferTail;
  85     uint32_t txBufferHead;
  86     uint32_t txBufferTail;
  87
  88     serialReceiveCallbackPtr rxCallback;
  89     void *rxCallbackData;
  90
  91     serialIdleCallbackPtr idleCallback;
  92
  93     uint8_t identifier;
  94 } serialPort_t;
  95
  96 #define SERIAL_PORT_MAX_INDEX 11
  97
  98 typedef struct serialPinConfig_s {
  99     ioTag_t ioTagTx[SERIAL_PORT_MAX_INDEX];
 100     ioTag_t ioTagRx[SERIAL_PORT_MAX_INDEX];
 101     ioTag_t ioTagInverter[SERIAL_PORT_MAX_INDEX];
 102 } serialPinConfig_t;
 103
 104 PG_DECLARE(serialPinConfig_t, serialPinConfig);
 105
 106 #if defined(USE_SOFTSERIAL)
 107 #define SOFTSERIAL_COUNT 2
 108
 109 typedef struct softSerialPinConfig_s {
 110     ioTag_t ioTagTx[SOFTSERIAL_COUNT];
 111     ioTag_t ioTagRx[SOFTSERIAL_COUNT];
 112 } softSerialPinConfig_t;
 113
 114 PG_DECLARE(softSerialPinConfig_t, softSerialPinConfig);
 115 #endif
 116
 117 struct serialPortVTable {
 118     void (*serialWrite)(serialPort_t *instance, uint8_t ch);
 119
 120     uint32_t (*serialTotalRxWaiting)(const serialPort_t *instance);
 121     uint32_t (*serialTotalTxFree)(const serialPort_t *instance);
 122
 123     uint8_t (*serialRead)(serialPort_t *instance);
 124
 125     // Specified baud rate may not be allowed by an implementation, use serialGetBaudRate to determine actual baud rate in use.
 126     void (*serialSetBaudRate)(serialPort_t *instance, uint32_t baudRate);
 127
 128     bool (*isSerialTransmitBufferEmpty)(const serialPort_t *instance);
 129
 130     void (*setMode)(serialPort_t *instance, portMode_e mode);
 131     void (*setCtrlLineStateCb)(serialPort_t *instance, void (*cb)(void *instance, uint16_t ctrlLineState), void *context);
 132     void (*setBaudRateCb)(serialPort_t *instance, void (*cb)(serialPort_t *context, uint32_t baud), serialPort_t *context);
 133
 134     void (*writeBuf)(serialPort_t *instance, const void *data, int count);
 135     // Optional functions used to buffer large writes.
 136     void (*beginWrite)(serialPort_t *instance);
 137     void (*endWrite)(serialPort_t *instance);
 138 };
 139
 140 void serialWrite(serialPort_t *instance, uint8_t ch);
 141 uint32_t serialRxBytesWaiting(const serialPort_t *instance);
 142 uint32_t serialTxBytesFree(const serialPort_t *instance);
 143 void serialWriteBuf(serialPort_t *instance, const uint8_t *data, int count);
 144 uint8_t serialRead(serialPort_t *instance);
 145 void serialSetBaudRate(serialPort_t *instance, uint32_t baudRate);
 146 void serialSetMode(serialPort_t *instance, portMode_e mode);
 147 void serialSetCtrlLineStateCb(serialPort_t *instance, void (*cb)(void *context, uint16_t ctrlLineState), void *context);
 148 void serialSetBaudRateCb(serialPort_t *instance, void (*cb)(serialPort_t *context, uint32_t baud), serialPort_t *context);
 149 bool isSerialTransmitBufferEmpty(const serialPort_t *instance);
 150 void serialPrint(serialPort_t *instance, const char *str);
 151 uint32_t serialGetBaudRate(serialPort_t *instance);
 152
 153 // A shim that adapts the bufWriter API to the serialWriteBuf() API.
 154 void serialWriteBufShim(void *instance, const uint8_t *data, int count);
 155 void serialBeginWrite(serialPort_t *instance);
 156 void serialEndWrite(serialPort_t *instance);