Scott Hoppe / MTS_SPI

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of MTS-Serial by Scott Hoppe

MTSBufferedIO.h@2:d2cb8c8ecd6e, 2014-05-19 (annotated)

Committer:
Mike Fiore
Date:
Mon May 19 12:35:18 2014 -0500
Revision:
2:d2cb8c8ecd6e
Parent:
1:d34b566d6f47
Child:
4:d348d001283b
add "mbed.h" to headers

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mfiore 0:6585b7c8cd41 1 #ifndef MTSBUFFEREDIO_H
mfiore 0:6585b7c8cd41 2 #define MTSBUFFEREDIO_H
mfiore 0:6585b7c8cd41 3
Mike Fiore 2:d2cb8c8ecd6e 4 #include "mbed.h"
Mike Fiore 1:d34b566d6f47 5 #include "MTSCircularBuffer.h"
Mike Fiore 1:d34b566d6f47 6
Mike Fiore 1:d34b566d6f47 7 namespace mts {
Mike Fiore 1:d34b566d6f47 8
Mike Fiore 1:d34b566d6f47 9 /** This is an abstract class for lightweight buffered io to an underlying
Mike Fiore 1:d34b566d6f47 10 * data interface. Specifically the inheriting class will need to override
Mike Fiore 1:d34b566d6f47 11 * both the handleRead and handleWrite methods which transfer data between
Mike Fiore 1:d34b566d6f47 12 * the class's internal read and write buffers and the physical communications
Mike Fiore 1:d34b566d6f47 13 * link and its HW buffers.
Mike Fiore 1:d34b566d6f47 14 */
Mike Fiore 1:d34b566d6f47 15
Mike Fiore 1:d34b566d6f47 16 class MTSBufferedIO
Mike Fiore 1:d34b566d6f47 17 {
Mike Fiore 1:d34b566d6f47 18 public:
Mike Fiore 1:d34b566d6f47 19 /** Creates a new BufferedIO object with the passed in static buffer sizes.
Mike Fiore 1:d34b566d6f47 20 * Note that because this class is abstract you cannot construct it directly.
Mike Fiore 1:d34b566d6f47 21 * Instead, please construct one of its derived classes like MTSSerial or
Mike Fiore 1:d34b566d6f47 22 * MTSSerialFlowControl.
Mike Fiore 1:d34b566d6f47 23 *
Mike Fiore 1:d34b566d6f47 24 * @param txBufferSize the size of the Tx or write buffer in bytes. The default is
Mike Fiore 1:d34b566d6f47 25 * 256 bytes.
Mike Fiore 1:d34b566d6f47 26 * @param rxBufferSize the size of the Rx or read buffer in bytes. The default is
Mike Fiore 1:d34b566d6f47 27 * 256 bytes.
Mike Fiore 1:d34b566d6f47 28 */
Mike Fiore 1:d34b566d6f47 29 MTSBufferedIO(int txBufferSize = 256, int rxBufferSize = 256);
Mike Fiore 1:d34b566d6f47 30
Mike Fiore 1:d34b566d6f47 31 /** Destructs an MTSBufferedIO object and frees all related resources.
Mike Fiore 1:d34b566d6f47 32 */
Mike Fiore 1:d34b566d6f47 33 ~MTSBufferedIO();
Mike Fiore 1:d34b566d6f47 34
Mike Fiore 1:d34b566d6f47 35 /** This method enables bulk writes to the Tx or write buffer. If more data
Mike Fiore 1:d34b566d6f47 36 * is requested to be written then space available the method writes
Mike Fiore 1:d34b566d6f47 37 * as much data as possible within the timeout period and returns the actual amount written.
Mike Fiore 1:d34b566d6f47 38 *
Mike Fiore 1:d34b566d6f47 39 * @param data the byte array to be written.
Mike Fiore 1:d34b566d6f47 40 * @param length the length of data to be written from the data parameter.
Mike Fiore 1:d34b566d6f47 41 * @timeoutMillis amount of time in milliseconds to complete operation.
Mike Fiore 1:d34b566d6f47 42 * @returns the number of bytes written to the buffer, which is 0 if
Mike Fiore 1:d34b566d6f47 43 * the buffer is full.
Mike Fiore 1:d34b566d6f47 44 */
Mike Fiore 1:d34b566d6f47 45 int write(const char* data, int length, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 46
Mike Fiore 1:d34b566d6f47 47 /** This method enables bulk writes to the Tx or write buffer. This method
Mike Fiore 1:d34b566d6f47 48 * blocks until all the bytes are written.
Mike Fiore 1:d34b566d6f47 49 *
Mike Fiore 1:d34b566d6f47 50 * @param data the byte array to be written.
Mike Fiore 1:d34b566d6f47 51 * @param length the length of data to be written from the data parameter.
Mike Fiore 1:d34b566d6f47 52 * @returns the number of bytes written to the buffer, which should be
Mike Fiore 1:d34b566d6f47 53 * equal to the length parameter since this method blocks.
Mike Fiore 1:d34b566d6f47 54 */
Mike Fiore 1:d34b566d6f47 55 int write(const char* data, int length);
Mike Fiore 1:d34b566d6f47 56
Mike Fiore 1:d34b566d6f47 57 /** This method attempts to write a single byte to the tx buffer
Mike Fiore 1:d34b566d6f47 58 * within the timeout period.
Mike Fiore 1:d34b566d6f47 59 *
Mike Fiore 1:d34b566d6f47 60 * @param data the byte to be written as a char.
Mike Fiore 1:d34b566d6f47 61 * @timeoutMillis amount of time in milliseconds to complete operation.
Mike Fiore 1:d34b566d6f47 62 * @returns 1 if the byte was written or 0 if the buffer was full and the timeout
Mike Fiore 1:d34b566d6f47 63 * expired.
Mike Fiore 1:d34b566d6f47 64 */
Mike Fiore 1:d34b566d6f47 65 int write(char data, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 66
Mike Fiore 1:d34b566d6f47 67 /** This method writes a signle byte as a char to the Tx or write buffer.
Mike Fiore 1:d34b566d6f47 68 * This method blocks until the byte is written.
Mike Fiore 1:d34b566d6f47 69 *
Mike Fiore 1:d34b566d6f47 70 * @param data the byte to be written as a char.
Mike Fiore 1:d34b566d6f47 71 * @returns 1 once the byte has been written.
Mike Fiore 1:d34b566d6f47 72 */
Mike Fiore 1:d34b566d6f47 73 int write(char data);
Mike Fiore 1:d34b566d6f47 74
Mike Fiore 1:d34b566d6f47 75 /** This method is used to get the space available to write bytes to the Tx buffer.
Mike Fiore 1:d34b566d6f47 76 *
Mike Fiore 1:d34b566d6f47 77 * @returns the number of bytes that can be written, 0 if the buffer is full.
Mike Fiore 1:d34b566d6f47 78 */
Mike Fiore 1:d34b566d6f47 79 int writeable();
Mike Fiore 1:d34b566d6f47 80
Mike Fiore 1:d34b566d6f47 81 /** This method enables bulk reads from the Rx or read buffer. It attempts
Mike Fiore 1:d34b566d6f47 82 * to read the amount specified, but will complete early if the specified timeout
Mike Fiore 1:d34b566d6f47 83 * expires.
Mike Fiore 1:d34b566d6f47 84 *
Mike Fiore 1:d34b566d6f47 85 * @param data the buffer where data read will be added to.
Mike Fiore 1:d34b566d6f47 86 * @param length the amount of data in bytes to be read into the buffer.
Mike Fiore 1:d34b566d6f47 87 * @timeoutMillis amount of time to complete operation.
Mike Fiore 1:d34b566d6f47 88 * @returns the total number of bytes that were read.
Mike Fiore 1:d34b566d6f47 89 */
Mike Fiore 1:d34b566d6f47 90 int read(char* data, int length, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 91
Mike Fiore 1:d34b566d6f47 92 /** This method enables bulk reads from the Rx or read buffer. This method
Mike Fiore 1:d34b566d6f47 93 * blocks until the amount of data requested is received.
Mike Fiore 1:d34b566d6f47 94 *
Mike Fiore 1:d34b566d6f47 95 * @param data the buffer where data read will be added to.
Mike Fiore 1:d34b566d6f47 96 * @param length the amount of data in bytes to be read into the buffer.
Mike Fiore 1:d34b566d6f47 97 * @returns the total number of bytes that were read. This should be equal
Mike Fiore 1:d34b566d6f47 98 * to the length parameter since this is a blocking call.
Mike Fiore 1:d34b566d6f47 99 */
Mike Fiore 1:d34b566d6f47 100 int read(char* data, int length);
Mike Fiore 1:d34b566d6f47 101
Mike Fiore 1:d34b566d6f47 102 /** This method reads a single byte from the Rx or read buffer. This method
Mike Fiore 1:d34b566d6f47 103 * attempts to read a byte, but will return without reading one if the specified
Mike Fiore 1:d34b566d6f47 104 * timeout is reached.
Mike Fiore 1:d34b566d6f47 105 *
Mike Fiore 1:d34b566d6f47 106 * @param data char where the read byte will be stored.
Mike Fiore 1:d34b566d6f47 107 * @timeoutMillis amount of time to complete operation.
Mike Fiore 1:d34b566d6f47 108 * @returns 1 if byte is read or 0 if no byte is available.
Mike Fiore 1:d34b566d6f47 109 */
Mike Fiore 1:d34b566d6f47 110 int read(char& data, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 111
Mike Fiore 1:d34b566d6f47 112 /** This method reads a single byte from the Rx or read buffer.
Mike Fiore 1:d34b566d6f47 113 * This method blocks until the single byte is read.
Mike Fiore 1:d34b566d6f47 114 *
Mike Fiore 1:d34b566d6f47 115 * @param data char where the read byte will be stored.
Mike Fiore 1:d34b566d6f47 116 * @returns 1 once the byte has been read.
Mike Fiore 1:d34b566d6f47 117 */
Mike Fiore 1:d34b566d6f47 118 int read(char& data);
Mike Fiore 1:d34b566d6f47 119
Mike Fiore 1:d34b566d6f47 120 /** This method is used to get the number of bytes available to read from
Mike Fiore 1:d34b566d6f47 121 * the Rx or read buffer.
Mike Fiore 1:d34b566d6f47 122 *
Mike Fiore 1:d34b566d6f47 123 * @returns the number of bytes available, 0 if there are no bytes to read.
Mike Fiore 1:d34b566d6f47 124 */
Mike Fiore 1:d34b566d6f47 125 int readable();
Mike Fiore 1:d34b566d6f47 126
Mike Fiore 1:d34b566d6f47 127 /** This method determines if the Tx or write buffer is empty.
Mike Fiore 1:d34b566d6f47 128 *
Mike Fiore 1:d34b566d6f47 129 * @returns true if empty, otherwise false.
Mike Fiore 1:d34b566d6f47 130 */
Mike Fiore 1:d34b566d6f47 131 bool txEmpty();
Mike Fiore 1:d34b566d6f47 132
Mike Fiore 1:d34b566d6f47 133 /** This method determines if the Rx or read buffer is empty.
Mike Fiore 1:d34b566d6f47 134 *
Mike Fiore 1:d34b566d6f47 135 * @returns true if empty, otherwise false.
Mike Fiore 1:d34b566d6f47 136 */
Mike Fiore 1:d34b566d6f47 137 bool rxEmpty();
Mike Fiore 1:d34b566d6f47 138
Mike Fiore 1:d34b566d6f47 139 /** This method determines if the Tx or write buffer is full.
Mike Fiore 1:d34b566d6f47 140 *
Mike Fiore 1:d34b566d6f47 141 * @returns true if full, otherwise false.
Mike Fiore 1:d34b566d6f47 142 */
Mike Fiore 1:d34b566d6f47 143 bool txFull();
Mike Fiore 1:d34b566d6f47 144
Mike Fiore 1:d34b566d6f47 145 /** This method determines if the Rx or read buffer is full.
Mike Fiore 1:d34b566d6f47 146 *
Mike Fiore 1:d34b566d6f47 147 * @returns true if full, otherwise false.
Mike Fiore 1:d34b566d6f47 148 */
Mike Fiore 1:d34b566d6f47 149 bool rxFull();
Mike Fiore 1:d34b566d6f47 150
Mike Fiore 1:d34b566d6f47 151 /** This method clears all the data from the internal Tx or write buffer.
Mike Fiore 1:d34b566d6f47 152 */
Mike Fiore 1:d34b566d6f47 153 virtual void txClear();
Mike Fiore 1:d34b566d6f47 154
Mike Fiore 1:d34b566d6f47 155 /** This method clears all the data from the internal Rx or read buffer.
Mike Fiore 1:d34b566d6f47 156 */
Mike Fiore 1:d34b566d6f47 157 virtual void rxClear();
Mike Fiore 1:d34b566d6f47 158
Mike Fiore 1:d34b566d6f47 159 /** This abstract method should be used by the deriving class to transfer
Mike Fiore 1:d34b566d6f47 160 * data from the internal write buffer (txBuffer) to the physical interface.
Mike Fiore 1:d34b566d6f47 161 * Note that this function is called everytime new data is written to the
Mike Fiore 1:d34b566d6f47 162 * txBuffer through one of the write calls.
Mike Fiore 1:d34b566d6f47 163 */
Mike Fiore 1:d34b566d6f47 164 virtual void handleWrite() = 0;
Mike Fiore 1:d34b566d6f47 165
Mike Fiore 1:d34b566d6f47 166 /** This abstract method should be used by the deriving class to transfer
Mike Fiore 1:d34b566d6f47 167 * data from the physical interface ot the internal read buffer (rxBuffer).
Mike Fiore 1:d34b566d6f47 168 * Note that this function is never called in this class and typically should
Mike Fiore 1:d34b566d6f47 169 * be called as part of a receive data interrupt routine.
Mike Fiore 1:d34b566d6f47 170 */
Mike Fiore 1:d34b566d6f47 171 virtual void handleRead() = 0;
Mike Fiore 1:d34b566d6f47 172
Mike Fiore 1:d34b566d6f47 173 protected:
Mike Fiore 1:d34b566d6f47 174 MTSCircularBuffer txBuffer; // Internal write or transmit circular buffer
Mike Fiore 1:d34b566d6f47 175 MTSCircularBuffer rxBuffer; // Internal read or receieve circular buffer
Mike Fiore 1:d34b566d6f47 176 };
Mike Fiore 1:d34b566d6f47 177
Mike Fiore 1:d34b566d6f47 178 }
Mike Fiore 1:d34b566d6f47 179
Mike Fiore 1:d34b566d6f47 180 #endif /* MTSBUFFEREDIO_H */