src/main/drivers/serial.h

   1 /*
   2  * This file is part of Cleanflight.
   3  *
   4  * Cleanflight is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 3 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * Cleanflight is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with Cleanflight.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #pragma once
  19 #include "drivers/io.h"
  20
  21 typedef struct {
  22     ioTag_t rxPin;
  23     ioTag_t txPin;
  24 } serialPortPins_t;
  25
  26 typedef enum portMode_t {
  27     MODE_RX = 1 << 0,
  28     MODE_TX = 1 << 1,
  29     MODE_RXTX = MODE_RX | MODE_TX
  30 } portMode_t;
  31
  32 typedef enum portOptions_t {
  33     SERIAL_NOT_INVERTED  = 0 << 0,
  34     SERIAL_INVERTED      = 1 << 0,
  35     SERIAL_STOPBITS_1    = 0 << 1,
  36     SERIAL_STOPBITS_2    = 1 << 1,
  37     SERIAL_PARITY_NO     = 0 << 2,
  38     SERIAL_PARITY_EVEN   = 1 << 2,
  39     SERIAL_UNIDIR        = 0 << 3,
  40     SERIAL_BIDIR         = 1 << 3,
  41
  42     /*
  43      * Note on SERIAL_BIDIR_PP
  44      * With SERIAL_BIDIR_PP, the very first start bit of back-to-back bytes
  45      * is lost and the first data byte will be lost by a framing error.
  46      * To ensure the first start bit to be sent, prepend a zero byte (0x00)
  47      * to actual data bytes.
  48      */
  49     SERIAL_BIDIR_OD      = 0 << 4,
  50     SERIAL_BIDIR_PP      = 1 << 4,
  51     SERIAL_BIDIR_NOPULL  = 1 << 5, // disable pulls in BIDIR RX mode
  52     SERIAL_BIDIR_UP      = 0 << 5, // enable pullup in BIDIR mode
  53
  54     SERIAL_LONGSTOP      = 0 << 6,
  55     SERIAL_SHORTSTOP     = 1 << 6,
  56 } portOptions_t;
  57
  58 typedef void (*serialReceiveCallbackPtr)(uint16_t data, void *rxCallbackData);   // used by serial drivers to return frames to app
  59
  60 typedef struct serialPort_s {
  61
  62     const struct serialPortVTable *vTable;
  63
  64     uint8_t identifier;
  65     portMode_t mode;
  66     portOptions_t options;
  67
  68     uint32_t baudRate;
  69
  70     uint32_t rxBufferSize;
  71     uint32_t txBufferSize;
  72     volatile uint8_t *rxBuffer;
  73     volatile uint8_t *txBuffer;
  74     uint32_t rxBufferHead;
  75     uint32_t rxBufferTail;
  76     uint32_t txBufferHead;
  77     uint32_t txBufferTail;
  78
  79     serialReceiveCallbackPtr rxCallback;
  80     void *rxCallbackData;
  81 } serialPort_t;
  82
  83 struct serialPortVTable {
  84     void (*serialWrite)(serialPort_t *instance, uint8_t ch);
  85
  86     uint32_t (*serialTotalRxWaiting)(const serialPort_t *instance);
  87     uint32_t (*serialTotalTxFree)(const serialPort_t *instance);
  88
  89     uint8_t (*serialRead)(serialPort_t *instance);
  90
  91     // Specified baud rate may not be allowed by an implementation, use serialGetBaudRate to determine actual baud rate in use.
  92     void (*serialSetBaudRate)(serialPort_t *instance, uint32_t baudRate);
  93
  94     bool (*isSerialTransmitBufferEmpty)(const serialPort_t *instance);
  95
  96     void (*setMode)(serialPort_t *instance, portMode_t mode);
  97
  98     void (*writeBuf)(serialPort_t *instance, const void *data, int count);
  99
 100     bool (*isConnected)(const serialPort_t *instance);
 101
 102     bool (*isIdle)(serialPort_t *instance);
 103
 104     // Optional functions used to buffer large writes.
 105     void (*beginWrite)(serialPort_t *instance);
 106     void (*endWrite)(serialPort_t *instance);
 107 };
 108
 109 void serialWrite(serialPort_t *instance, uint8_t ch);
 110 uint32_t serialRxBytesWaiting(const serialPort_t *instance);
 111 uint32_t serialTxBytesFree(const serialPort_t *instance);
 112 void serialWriteBuf(serialPort_t *instance, const uint8_t *data, int count);
 113 uint8_t serialRead(serialPort_t *instance);
 114 void serialSetBaudRate(serialPort_t *instance, uint32_t baudRate);
 115 void serialSetMode(serialPort_t *instance, portMode_t mode);
 116 bool isSerialTransmitBufferEmpty(const serialPort_t *instance);
 117 void serialPrint(serialPort_t *instance, const char *str);
 118 uint32_t serialGetBaudRate(serialPort_t *instance);
 119 bool serialIsConnected(const serialPort_t *instance);
 120 bool serialIsIdle(serialPort_t *instance);
 121
 122 // A shim that adapts the bufWriter API to the serialWriteBuf() API.
 123 void serialWriteBufShim(void *instance, const uint8_t *data, int count);
 124 void serialBeginWrite(serialPort_t *instance);
 125 void serialEndWrite(serialPort_t *instance);