Richard Osterloh / SerialDriver

RTOS safe buffered serial driver

Fork of SerialDriver by BlazeX .

SerialDriver.h@0:cd0d79be0c1a, 2015-01-14 (annotated)

Committer:
BlazeX
Date:
Wed Jan 14 16:30:14 2015 +0000
Revision:
0:cd0d79be0c1a
Child:
3:ea9719695b6a
Release :)

Who changed what in which revision?

UserRevisionLine numberNew contents of line
BlazeX 0:cd0d79be0c1a 1 /// @file SerialDriver.h
BlazeX 0:cd0d79be0c1a 2 /// @brief RTOS compatible buffered Serial port driver
BlazeX 0:cd0d79be0c1a 3 ///
BlazeX 0:cd0d79be0c1a 4 /// Examples:
BlazeX 0:cd0d79be0c1a 5 /// - @ref Example_printf.cpp
BlazeX 0:cd0d79be0c1a 6 /// - @ref Example_Nullmodem.cpp
BlazeX 0:cd0d79be0c1a 7 /// - @ref Example_Bridge.cpp
BlazeX 0:cd0d79be0c1a 8 /// - @ref Example_Blocking.cpp
BlazeX 0:cd0d79be0c1a 9 ///
BlazeX 0:cd0d79be0c1a 10 ///
BlazeX 0:cd0d79be0c1a 11 /// Dependencies:
BlazeX 0:cd0d79be0c1a 12 /// - cstdarg
BlazeX 0:cd0d79be0c1a 13 /// @see https://developer.mbed.org/users/mbed_official/code/mbed-rtos/
BlazeX 0:cd0d79be0c1a 14 /// @see https://developer.mbed.org/users/mbed_official/code/mbed/
BlazeX 0:cd0d79be0c1a 15
BlazeX 0:cd0d79be0c1a 16 #pragma once
BlazeX 0:cd0d79be0c1a 17
BlazeX 0:cd0d79be0c1a 18 #include "mbed.h"
BlazeX 0:cd0d79be0c1a 19 #include "rtos.h"
BlazeX 0:cd0d79be0c1a 20 #include <cstdarg>
BlazeX 0:cd0d79be0c1a 21
BlazeX 0:cd0d79be0c1a 22
BlazeX 0:cd0d79be0c1a 23 /// @class SerialDriver
BlazeX 0:cd0d79be0c1a 24 /// @brief RTOS compatible buffered Serial port driver
BlazeX 0:cd0d79be0c1a 25 ///
BlazeX 0:cd0d79be0c1a 26 /// - Based on SerialBase.
BlazeX 0:cd0d79be0c1a 27 /// - Can use external buffers.
BlazeX 0:cd0d79be0c1a 28 /// - ISR driven, ring buffered IO operation
BlazeX 0:cd0d79be0c1a 29 /// - Can Replace mbed RawSerial
BlazeX 0:cd0d79be0c1a 30 /// - IO operations are idle waiting, don't waste time in RTOS :D
BlazeX 0:cd0d79be0c1a 31 /// - Do not use attach methods for TxIrq or RxIrq! They are already in use.
BlazeX 0:cd0d79be0c1a 32 class SerialDriver : public SerialBase
BlazeX 0:cd0d79be0c1a 33 {
BlazeX 0:cd0d79be0c1a 34 protected:
BlazeX 0:cd0d79be0c1a 35 // ring buffered rx/tx
BlazeX 0:cd0d79be0c1a 36 unsigned char * txBuffer;
BlazeX 0:cd0d79be0c1a 37 unsigned char * rxBuffer;
BlazeX 0:cd0d79be0c1a 38 int txBufferLength, rxBufferLength;
BlazeX 0:cd0d79be0c1a 39
BlazeX 0:cd0d79be0c1a 40 // ring buffer cursors
BlazeX 0:cd0d79be0c1a 41 volatile int txIn, txOut;
BlazeX 0:cd0d79be0c1a 42 volatile int rxIn, rxOut;
BlazeX 0:cd0d79be0c1a 43 volatile int txCount, rxCount;
BlazeX 0:cd0d79be0c1a 44
BlazeX 0:cd0d79be0c1a 45 // semaphores for timeout (used as signals)
BlazeX 0:cd0d79be0c1a 46 Semaphore semTxBufferFull; // used by putc to wait
BlazeX 0:cd0d79be0c1a 47 Semaphore semRxBufferEmpty; // used by getc to wait
BlazeX 0:cd0d79be0c1a 48
BlazeX 0:cd0d79be0c1a 49
BlazeX 0:cd0d79be0c1a 50 public:
BlazeX 0:cd0d79be0c1a 51 /// @brief Prepares ring buffer and irq
BlazeX 0:cd0d79be0c1a 52 ///
BlazeX 0:cd0d79be0c1a 53 /// If no buffer was set, the buffer gets allocated.
BlazeX 0:cd0d79be0c1a 54 /// @param txPin TX PinName, e.g. USBTX
BlazeX 0:cd0d79be0c1a 55 /// @param rxPin RX PinName, e.g. USBRX
BlazeX 0:cd0d79be0c1a 56 /// @param txBufferLength_ size of TX buffer. Must be > 1!
BlazeX 0:cd0d79be0c1a 57 /// @param rxBufferLength_ size of RX buffer. Must be > 1!
BlazeX 0:cd0d79be0c1a 58 /// @param txBuffer_ TX buffer, if NULL, the buffer will be allocated
BlazeX 0:cd0d79be0c1a 59 /// @param rxBuffer_ RX buffer, if NULL, the buffer will be allocated
BlazeX 0:cd0d79be0c1a 60 SerialDriver(PinName txPin, PinName rxPin, int txBufferLength_= 256, int rxBufferLength_= 256, unsigned char * txBuffer_= NULL, unsigned char * rxBuffer_= NULL);
BlazeX 0:cd0d79be0c1a 61
BlazeX 0:cd0d79be0c1a 62
BlazeX 0:cd0d79be0c1a 63 ////////////////////////////////////////////////////////////////
BlazeX 0:cd0d79be0c1a 64 // Basic IO Operation
BlazeX 0:cd0d79be0c1a 65
BlazeX 0:cd0d79be0c1a 66 /// @brief Put a byte to the TX buffer
BlazeX 0:cd0d79be0c1a 67 ///
BlazeX 0:cd0d79be0c1a 68 /// If the TX buffer is full, it waits the defined timeout.
BlazeX 0:cd0d79be0c1a 69 /// Drops the byte, if TX buffer is still full after timeout.
BlazeX 0:cd0d79be0c1a 70 /// @param c The byte to write
BlazeX 0:cd0d79be0c1a 71 /// @param timeoutMs give TX buffer time to get writeable.
BlazeX 0:cd0d79be0c1a 72 /// @return 1 - success, 0 - if TX Buffer was full all the time
BlazeX 0:cd0d79be0c1a 73 int putc(int c, unsigned int timeoutMs= osWaitForever);
BlazeX 0:cd0d79be0c1a 74
BlazeX 0:cd0d79be0c1a 75
BlazeX 0:cd0d79be0c1a 76 /// @brief Get a byte from the RX buffer
BlazeX 0:cd0d79be0c1a 77 ///
BlazeX 0:cd0d79be0c1a 78 /// If the RX buffer is empty, it waits the defined timeout.
BlazeX 0:cd0d79be0c1a 79 /// @param timeoutMs give RX buffer time to get readable.
BlazeX 0:cd0d79be0c1a 80 /// @return next byte from RX buffer or -1 after timeout.
BlazeX 0:cd0d79be0c1a 81 int getc(unsigned int timeoutMs= osWaitForever);
BlazeX 0:cd0d79be0c1a 82
BlazeX 0:cd0d79be0c1a 83
BlazeX 0:cd0d79be0c1a 84 protected:
BlazeX 0:cd0d79be0c1a 85 ////////////////////////////////////////////////////////////////
BlazeX 0:cd0d79be0c1a 86 // Interrupts
BlazeX 0:cd0d79be0c1a 87
BlazeX 0:cd0d79be0c1a 88 // TX: Move data from txBuffer to SerialBase::putc
BlazeX 0:cd0d79be0c1a 89 void onTxIrq(); // serial base port now writeable, lets put some bytes
BlazeX 0:cd0d79be0c1a 90
BlazeX 0:cd0d79be0c1a 91 // RX: Move data from SerialBase::getc to rxBuffer
BlazeX 0:cd0d79be0c1a 92 void onRxIrq(); // serial base port now readable, lets get some bytes
BlazeX 0:cd0d79be0c1a 93
BlazeX 0:cd0d79be0c1a 94 // Enable / Disable
BlazeX 0:cd0d79be0c1a 95 inline void disableTxInterrupt() { serial_irq_set(&_serial, (SerialIrq)TxIrq, 0); }
BlazeX 0:cd0d79be0c1a 96 inline void enableTxInterrupt() { serial_irq_set(&_serial, (SerialIrq)TxIrq, 1); }
BlazeX 0:cd0d79be0c1a 97
BlazeX 0:cd0d79be0c1a 98 inline void disableRxInterrupt() { serial_irq_set(&_serial, (SerialIrq)RxIrq, 0); }
BlazeX 0:cd0d79be0c1a 99 inline void enableRxInterrupt() { serial_irq_set(&_serial, (SerialIrq)RxIrq, 1); }
BlazeX 0:cd0d79be0c1a 100
BlazeX 0:cd0d79be0c1a 101
BlazeX 0:cd0d79be0c1a 102 public:
BlazeX 0:cd0d79be0c1a 103 ////////////////////////////////////////////////////////////////
BlazeX 0:cd0d79be0c1a 104 // Extended IO Operation
BlazeX 0:cd0d79be0c1a 105
BlazeX 0:cd0d79be0c1a 106 /// @brief write a buck of bytes
BlazeX 0:cd0d79be0c1a 107 ///
BlazeX 0:cd0d79be0c1a 108 /// No timeout! To block, or not to block. That is the question.
BlazeX 0:cd0d79be0c1a 109 /// @param buffer buck of bytes
BlazeX 0:cd0d79be0c1a 110 /// @param length write how much bytes?
BlazeX 0:cd0d79be0c1a 111 /// @param block idle wait for every @ref putc to complete
BlazeX 0:cd0d79be0c1a 112 /// @return written bytes. For non block write it could be < length!
BlazeX 0:cd0d79be0c1a 113 int write(const unsigned char * buffer, const unsigned int length, bool block= true);
BlazeX 0:cd0d79be0c1a 114
BlazeX 0:cd0d79be0c1a 115 /// @brief read a buck of bytes
BlazeX 0:cd0d79be0c1a 116 ///
BlazeX 0:cd0d79be0c1a 117 /// No timeout! To block, or not to block. That is the question.
BlazeX 0:cd0d79be0c1a 118 /// @param buffer buck of bytes
BlazeX 0:cd0d79be0c1a 119 /// @param length read how much bytes?
BlazeX 0:cd0d79be0c1a 120 /// @param block idle wait for every @ref getc to complete
BlazeX 0:cd0d79be0c1a 121 /// @return read bytes. For non block read it could be < length!
BlazeX 0:cd0d79be0c1a 122 int read(unsigned char * buffer, const unsigned int length, bool block= true);
BlazeX 0:cd0d79be0c1a 123
BlazeX 0:cd0d79be0c1a 124
BlazeX 0:cd0d79be0c1a 125 /// @brief Write a string (without terminating null)
BlazeX 0:cd0d79be0c1a 126 ///
BlazeX 0:cd0d79be0c1a 127 /// For compatibility with mbed RawSerial
BlazeX 0:cd0d79be0c1a 128 /// @param str null terminated string
BlazeX 0:cd0d79be0c1a 129 /// @param block idle wait for every @ref putc to complete
BlazeX 0:cd0d79be0c1a 130 /// @return written chars (without terminating null)
BlazeX 0:cd0d79be0c1a 131 int puts(const char * str, bool block= true);
BlazeX 0:cd0d79be0c1a 132
BlazeX 0:cd0d79be0c1a 133 /// @brief Print a formatted string.
BlazeX 0:cd0d79be0c1a 134 ///
BlazeX 0:cd0d79be0c1a 135 /// Idle blocking!
BlazeX 0:cd0d79be0c1a 136 /// Dynamically allocates needed buffer.
BlazeX 0:cd0d79be0c1a 137 /// @param format null terminated format string
BlazeX 0:cd0d79be0c1a 138 /// @return written chars (without terminating null)
BlazeX 0:cd0d79be0c1a 139 int printf(const char * format, ...);
BlazeX 0:cd0d79be0c1a 140
BlazeX 0:cd0d79be0c1a 141
BlazeX 0:cd0d79be0c1a 142 ////////////////////////////////////////////////////////////////
BlazeX 0:cd0d79be0c1a 143 // Buffer Infos
BlazeX 0:cd0d79be0c1a 144
BlazeX 0:cd0d79be0c1a 145 /// @brief Checks if TX buffer is full
BlazeX 0:cd0d79be0c1a 146 /// @return true - TX buffer is full, false - else
BlazeX 0:cd0d79be0c1a 147 inline bool isTxBufferFull() { return txCount == txBufferLength; }
BlazeX 0:cd0d79be0c1a 148
BlazeX 0:cd0d79be0c1a 149 /// @brief Checks if RX buffer is full
BlazeX 0:cd0d79be0c1a 150 /// @return true - RX buffer is full, false - else
BlazeX 0:cd0d79be0c1a 151 inline bool isRxBufferFull() { return rxCount == rxBufferLength; }
BlazeX 0:cd0d79be0c1a 152
BlazeX 0:cd0d79be0c1a 153 /// @brief Checks if TX buffer is empty
BlazeX 0:cd0d79be0c1a 154 /// @return true - TX buffer is empty, false - else
BlazeX 0:cd0d79be0c1a 155 inline bool isTxBufferEmtpy() { return txCount == 0; }
BlazeX 0:cd0d79be0c1a 156
BlazeX 0:cd0d79be0c1a 157 /// @brief Checks if RX buffer is empty
BlazeX 0:cd0d79be0c1a 158 /// @return true - RX buffer is empty, false - else
BlazeX 0:cd0d79be0c1a 159 inline bool isRxBufferEmpty() { return rxCount == 0; }
BlazeX 0:cd0d79be0c1a 160
BlazeX 0:cd0d79be0c1a 161
BlazeX 0:cd0d79be0c1a 162 /// @brief Checks if TX buffer is writeable (= not full).
BlazeX 0:cd0d79be0c1a 163 ///
BlazeX 0:cd0d79be0c1a 164 /// For compatibility with mbed Serial.
BlazeX 0:cd0d79be0c1a 165 /// @return true - TX buffer is writeable, false - else
BlazeX 0:cd0d79be0c1a 166 inline bool writeable() { return !isTxBufferFull(); }
BlazeX 0:cd0d79be0c1a 167
BlazeX 0:cd0d79be0c1a 168 /// @brief Checks if RX buffer is readable (= not empty).
BlazeX 0:cd0d79be0c1a 169 ///
BlazeX 0:cd0d79be0c1a 170 /// For compatibility with mbed Serial.
BlazeX 0:cd0d79be0c1a 171 /// @return true - RX buffer is readable, false - else
BlazeX 0:cd0d79be0c1a 172 inline bool readable() { return !isRxBufferEmpty(); }
BlazeX 0:cd0d79be0c1a 173 };