Francois Beaufort / microbit-ble-open

https://github.com/WebBluetoothCG/demos/pull/42

Dependencies:   BLE_API mbed-dev-bin nRF51822

Fork of microbit-dal by Lancaster University

inc/drivers/MicroBitSerial.h@22:23d7b9a4b082, 2016-07-13 (annotated)

Committer:
LancasterUniversity
Date:
Wed Jul 13 12:17:54 2016 +0100
Revision:
22:23d7b9a4b082
Parent:
1:8aa5cdb4ab67
Child:
23:6055f6c19fa6
Synchronized with git rev 7cf98c22

Author: James Devine

microbit-dal: patch for fiber_wake_on_event



fiber_wake_on_event used to crash after forking a FOB fiber.



It would attempt to obtain a new fiber context, and would place it on the wait queue.

Then when that fiber was paged in, the context of that fiber would not have been

initialised, as the function presumed schedule would be called immediately after

fiber initialisation.



This patch catches that edge case.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jonathan Austin 1:8aa5cdb4ab67 1 /*
Jonathan Austin 1:8aa5cdb4ab67 2 The MIT License (MIT)
Jonathan Austin 1:8aa5cdb4ab67 3
Jonathan Austin 1:8aa5cdb4ab67 4 Copyright (c) 2016 British Broadcasting Corporation.
Jonathan Austin 1:8aa5cdb4ab67 5 This software is provided by Lancaster University by arrangement with the BBC.
Jonathan Austin 1:8aa5cdb4ab67 6
Jonathan Austin 1:8aa5cdb4ab67 7 Permission is hereby granted, free of charge, to any person obtaining a
Jonathan Austin 1:8aa5cdb4ab67 8 copy of this software and associated documentation files (the "Software"),
Jonathan Austin 1:8aa5cdb4ab67 9 to deal in the Software without restriction, including without limitation
Jonathan Austin 1:8aa5cdb4ab67 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
Jonathan Austin 1:8aa5cdb4ab67 11 and/or sell copies of the Software, and to permit persons to whom the
Jonathan Austin 1:8aa5cdb4ab67 12 Software is furnished to do so, subject to the following conditions:
Jonathan Austin 1:8aa5cdb4ab67 13
Jonathan Austin 1:8aa5cdb4ab67 14 The above copyright notice and this permission notice shall be included in
Jonathan Austin 1:8aa5cdb4ab67 15 all copies or substantial portions of the Software.
Jonathan Austin 1:8aa5cdb4ab67 16
Jonathan Austin 1:8aa5cdb4ab67 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
Jonathan Austin 1:8aa5cdb4ab67 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
Jonathan Austin 1:8aa5cdb4ab67 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
Jonathan Austin 1:8aa5cdb4ab67 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
Jonathan Austin 1:8aa5cdb4ab67 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 23 DEALINGS IN THE SOFTWARE.
Jonathan Austin 1:8aa5cdb4ab67 24 */
Jonathan Austin 1:8aa5cdb4ab67 25
Jonathan Austin 1:8aa5cdb4ab67 26 #ifndef MICROBIT_SERIAL_H
Jonathan Austin 1:8aa5cdb4ab67 27 #define MICROBIT_SERIAL_H
Jonathan Austin 1:8aa5cdb4ab67 28
Jonathan Austin 1:8aa5cdb4ab67 29 #include "mbed.h"
Jonathan Austin 1:8aa5cdb4ab67 30 #include "ManagedString.h"
Jonathan Austin 1:8aa5cdb4ab67 31
Jonathan Austin 1:8aa5cdb4ab67 32 #define MICROBIT_SERIAL_DEFAULT_BAUD_RATE 115200
Jonathan Austin 1:8aa5cdb4ab67 33 #define MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE 20
Jonathan Austin 1:8aa5cdb4ab67 34
Jonathan Austin 1:8aa5cdb4ab67 35 #define MICROBIT_SERIAL_EVT_DELIM_MATCH 1
Jonathan Austin 1:8aa5cdb4ab67 36 #define MICROBIT_SERIAL_EVT_HEAD_MATCH 2
Jonathan Austin 1:8aa5cdb4ab67 37 #define MICROBIT_SERIAL_EVT_RX_FULL 3
Jonathan Austin 1:8aa5cdb4ab67 38
Jonathan Austin 1:8aa5cdb4ab67 39 #define MICROBIT_SERIAL_RX_IN_USE 1
Jonathan Austin 1:8aa5cdb4ab67 40 #define MICROBIT_SERIAL_TX_IN_USE 2
Jonathan Austin 1:8aa5cdb4ab67 41 #define MICROBIT_SERIAL_RX_BUFF_INIT 4
Jonathan Austin 1:8aa5cdb4ab67 42 #define MICROBIT_SERIAL_TX_BUFF_INIT 8
Jonathan Austin 1:8aa5cdb4ab67 43
Jonathan Austin 1:8aa5cdb4ab67 44
Jonathan Austin 1:8aa5cdb4ab67 45 enum MicroBitSerialMode
Jonathan Austin 1:8aa5cdb4ab67 46 {
Jonathan Austin 1:8aa5cdb4ab67 47 ASYNC,
Jonathan Austin 1:8aa5cdb4ab67 48 SYNC_SPINWAIT,
Jonathan Austin 1:8aa5cdb4ab67 49 SYNC_SLEEP
Jonathan Austin 1:8aa5cdb4ab67 50 };
Jonathan Austin 1:8aa5cdb4ab67 51
Jonathan Austin 1:8aa5cdb4ab67 52 /**
Jonathan Austin 1:8aa5cdb4ab67 53 * Class definition for MicroBitSerial.
Jonathan Austin 1:8aa5cdb4ab67 54 *
Jonathan Austin 1:8aa5cdb4ab67 55 * Represents an instance of RawSerial which accepts micro:bit specific data types.
Jonathan Austin 1:8aa5cdb4ab67 56 */
Jonathan Austin 1:8aa5cdb4ab67 57 class MicroBitSerial : public RawSerial
Jonathan Austin 1:8aa5cdb4ab67 58 {
Jonathan Austin 1:8aa5cdb4ab67 59
Jonathan Austin 1:8aa5cdb4ab67 60 //holds that state of the mutex locks for all MicroBitSerial instances.
Jonathan Austin 1:8aa5cdb4ab67 61 static uint8_t status;
Jonathan Austin 1:8aa5cdb4ab67 62
Jonathan Austin 1:8aa5cdb4ab67 63 //holds the state of the baudrate for all MicroBitSerial instances.
Jonathan Austin 1:8aa5cdb4ab67 64 static int baudrate;
Jonathan Austin 1:8aa5cdb4ab67 65
Jonathan Austin 1:8aa5cdb4ab67 66 //delimeters used for matching on receive.
Jonathan Austin 1:8aa5cdb4ab67 67 ManagedString delimeters;
Jonathan Austin 1:8aa5cdb4ab67 68
Jonathan Austin 1:8aa5cdb4ab67 69 //a variable used when a user calls the eventAfter() method.
Jonathan Austin 1:8aa5cdb4ab67 70 int rxBuffHeadMatch;
Jonathan Austin 1:8aa5cdb4ab67 71
Jonathan Austin 1:8aa5cdb4ab67 72 uint8_t *rxBuff;
Jonathan Austin 1:8aa5cdb4ab67 73 uint8_t rxBuffSize;
Jonathan Austin 1:8aa5cdb4ab67 74 volatile uint16_t rxBuffHead;
Jonathan Austin 1:8aa5cdb4ab67 75 uint16_t rxBuffTail;
Jonathan Austin 1:8aa5cdb4ab67 76
Jonathan Austin 1:8aa5cdb4ab67 77
Jonathan Austin 1:8aa5cdb4ab67 78 uint8_t *txBuff;
Jonathan Austin 1:8aa5cdb4ab67 79 uint8_t txBuffSize;
Jonathan Austin 1:8aa5cdb4ab67 80 uint16_t txBuffHead;
Jonathan Austin 1:8aa5cdb4ab67 81 volatile uint16_t txBuffTail;
Jonathan Austin 1:8aa5cdb4ab67 82
Jonathan Austin 1:8aa5cdb4ab67 83 /**
Jonathan Austin 1:8aa5cdb4ab67 84 * An internal interrupt callback for MicroBitSerial configured for when a
Jonathan Austin 1:8aa5cdb4ab67 85 * character is received.
Jonathan Austin 1:8aa5cdb4ab67 86 *
Jonathan Austin 1:8aa5cdb4ab67 87 * Each time a character is received fill our circular buffer!
Jonathan Austin 1:8aa5cdb4ab67 88 */
Jonathan Austin 1:8aa5cdb4ab67 89 void dataReceived();
Jonathan Austin 1:8aa5cdb4ab67 90
Jonathan Austin 1:8aa5cdb4ab67 91 /**
Jonathan Austin 1:8aa5cdb4ab67 92 * An internal interrupt callback for MicroBitSerial.
Jonathan Austin 1:8aa5cdb4ab67 93 *
Jonathan Austin 1:8aa5cdb4ab67 94 * Each time the Serial module's buffer is empty, write a character if we have
Jonathan Austin 1:8aa5cdb4ab67 95 * characters to write.
Jonathan Austin 1:8aa5cdb4ab67 96 */
Jonathan Austin 1:8aa5cdb4ab67 97 void dataWritten();
Jonathan Austin 1:8aa5cdb4ab67 98
Jonathan Austin 1:8aa5cdb4ab67 99 /**
Jonathan Austin 1:8aa5cdb4ab67 100 * An internal method to configure an interrupt on tx buffer and also
Jonathan Austin 1:8aa5cdb4ab67 101 * a best effort copy operation to move bytes from a user buffer to our txBuff
Jonathan Austin 1:8aa5cdb4ab67 102 *
Jonathan Austin 1:8aa5cdb4ab67 103 * @param string a pointer to the first character of the users' buffer.
Jonathan Austin 1:8aa5cdb4ab67 104 *
Jonathan Austin 1:8aa5cdb4ab67 105 * @param len the length of the string, and ultimately the maximum number of bytes
Jonathan Austin 1:8aa5cdb4ab67 106 * that will be copied dependent on the state of txBuff
Jonathan Austin 1:8aa5cdb4ab67 107 *
LancasterUniversity 22:23d7b9a4b082 108 * @param mode determines whether to configure the current fiber context or not. If
LancasterUniversity 22:23d7b9a4b082 109 * The mode is SYNC_SPINWAIT, the context will not be configured, otherwise
LancasterUniversity 22:23d7b9a4b082 110 * no context will be configured.
LancasterUniversity 22:23d7b9a4b082 111 *
Jonathan Austin 1:8aa5cdb4ab67 112 * @return the number of bytes copied into the buffer.
Jonathan Austin 1:8aa5cdb4ab67 113 */
LancasterUniversity 22:23d7b9a4b082 114 int setTxInterrupt(uint8_t *string, int len, MicroBitSerialMode mode);
Jonathan Austin 1:8aa5cdb4ab67 115
Jonathan Austin 1:8aa5cdb4ab67 116 /**
Jonathan Austin 1:8aa5cdb4ab67 117 * Locks the mutex so that others can't use this serial instance for reception
Jonathan Austin 1:8aa5cdb4ab67 118 */
Jonathan Austin 1:8aa5cdb4ab67 119 void lockRx();
Jonathan Austin 1:8aa5cdb4ab67 120
Jonathan Austin 1:8aa5cdb4ab67 121 /**
Jonathan Austin 1:8aa5cdb4ab67 122 * Locks the mutex so that others can't use this serial instance for transmission
Jonathan Austin 1:8aa5cdb4ab67 123 */
Jonathan Austin 1:8aa5cdb4ab67 124 void lockTx();
Jonathan Austin 1:8aa5cdb4ab67 125
Jonathan Austin 1:8aa5cdb4ab67 126 /**
Jonathan Austin 1:8aa5cdb4ab67 127 * Unlocks the mutex so that others can use this serial instance for reception
Jonathan Austin 1:8aa5cdb4ab67 128 */
Jonathan Austin 1:8aa5cdb4ab67 129 void unlockRx();
Jonathan Austin 1:8aa5cdb4ab67 130
Jonathan Austin 1:8aa5cdb4ab67 131 /**
Jonathan Austin 1:8aa5cdb4ab67 132 * Unlocks the mutex so that others can use this serial instance for transmission
Jonathan Austin 1:8aa5cdb4ab67 133 */
Jonathan Austin 1:8aa5cdb4ab67 134 void unlockTx();
Jonathan Austin 1:8aa5cdb4ab67 135
Jonathan Austin 1:8aa5cdb4ab67 136 /**
Jonathan Austin 1:8aa5cdb4ab67 137 * We do not want to always have our buffers initialised, especially if users to not
Jonathan Austin 1:8aa5cdb4ab67 138 * use them. We only bring them up on demand.
Jonathan Austin 1:8aa5cdb4ab67 139 */
Jonathan Austin 1:8aa5cdb4ab67 140 int initialiseRx();
Jonathan Austin 1:8aa5cdb4ab67 141
Jonathan Austin 1:8aa5cdb4ab67 142 /**
Jonathan Austin 1:8aa5cdb4ab67 143 * We do not want to always have our buffers initialised, especially if users to not
Jonathan Austin 1:8aa5cdb4ab67 144 * use them. We only bring them up on demand.
Jonathan Austin 1:8aa5cdb4ab67 145 */
Jonathan Austin 1:8aa5cdb4ab67 146 int initialiseTx();
Jonathan Austin 1:8aa5cdb4ab67 147
Jonathan Austin 1:8aa5cdb4ab67 148 /**
Jonathan Austin 1:8aa5cdb4ab67 149 * An internal method that either spin waits if mode is set to SYNC_SPINWAIT
Jonathan Austin 1:8aa5cdb4ab67 150 * or puts the fiber to sleep if the mode is set to SYNC_SLEEP
Jonathan Austin 1:8aa5cdb4ab67 151 *
Jonathan Austin 1:8aa5cdb4ab67 152 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP
Jonathan Austin 1:8aa5cdb4ab67 153 */
Jonathan Austin 1:8aa5cdb4ab67 154 void send(MicroBitSerialMode mode);
Jonathan Austin 1:8aa5cdb4ab67 155
Jonathan Austin 1:8aa5cdb4ab67 156 /**
Jonathan Austin 1:8aa5cdb4ab67 157 * Reads a single character from the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 158 *
Jonathan Austin 1:8aa5cdb4ab67 159 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 160 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 161 *
Jonathan Austin 1:8aa5cdb4ab67 162 * ASYNC - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 163 * are no characters to be read, a value of zero is returned immediately.
Jonathan Austin 1:8aa5cdb4ab67 164 *
Jonathan Austin 1:8aa5cdb4ab67 165 * SYNC_SPINWAIT - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 166 * are no characters to be read, this method will spin
Jonathan Austin 1:8aa5cdb4ab67 167 * (lock up the processor) until a character is available.
Jonathan Austin 1:8aa5cdb4ab67 168 *
Jonathan Austin 1:8aa5cdb4ab67 169 * SYNC_SLEEP - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 170 * are no characters to be read, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 171 * until there is a character available.
Jonathan Austin 1:8aa5cdb4ab67 172 *
Jonathan Austin 1:8aa5cdb4ab67 173 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 174 *
Jonathan Austin 1:8aa5cdb4ab67 175 * @return a character from the circular buffer, or MICROBIT_NO_DATA is there
Jonathan Austin 1:8aa5cdb4ab67 176 * are no characters in the buffer.
Jonathan Austin 1:8aa5cdb4ab67 177 */
Jonathan Austin 1:8aa5cdb4ab67 178 int getChar(MicroBitSerialMode mode);
Jonathan Austin 1:8aa5cdb4ab67 179
Jonathan Austin 1:8aa5cdb4ab67 180 /**
Jonathan Austin 1:8aa5cdb4ab67 181 * An internal method that copies values from a circular buffer to a linear buffer.
Jonathan Austin 1:8aa5cdb4ab67 182 *
Jonathan Austin 1:8aa5cdb4ab67 183 * @param circularBuff a pointer to the source circular buffer
Jonathan Austin 1:8aa5cdb4ab67 184 *
Jonathan Austin 1:8aa5cdb4ab67 185 * @param circularBuffSize the size of the circular buffer
Jonathan Austin 1:8aa5cdb4ab67 186 *
Jonathan Austin 1:8aa5cdb4ab67 187 * @param linearBuff a pointer to the destination linear buffer
Jonathan Austin 1:8aa5cdb4ab67 188 *
Jonathan Austin 1:8aa5cdb4ab67 189 * @param tailPosition the tail position in the circular buffer you want to copy from
Jonathan Austin 1:8aa5cdb4ab67 190 *
Jonathan Austin 1:8aa5cdb4ab67 191 * @param headPosition the head position in the circular buffer you want to copy to
Jonathan Austin 1:8aa5cdb4ab67 192 *
Jonathan Austin 1:8aa5cdb4ab67 193 * @note this method assumes that the linear buffer has the appropriate amount of
Jonathan Austin 1:8aa5cdb4ab67 194 * memory to contain the copy operation
Jonathan Austin 1:8aa5cdb4ab67 195 */
Jonathan Austin 1:8aa5cdb4ab67 196 void circularCopy(uint8_t *circularBuff, uint8_t circularBuffSize, uint8_t *linearBuff, uint16_t tailPosition, uint16_t headPosition);
Jonathan Austin 1:8aa5cdb4ab67 197
Jonathan Austin 1:8aa5cdb4ab67 198 public:
Jonathan Austin 1:8aa5cdb4ab67 199
Jonathan Austin 1:8aa5cdb4ab67 200 /**
Jonathan Austin 1:8aa5cdb4ab67 201 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 202 * Create an instance of MicroBitSerial
Jonathan Austin 1:8aa5cdb4ab67 203 *
Jonathan Austin 1:8aa5cdb4ab67 204 * @param tx the Pin to be used for transmission
Jonathan Austin 1:8aa5cdb4ab67 205 *
Jonathan Austin 1:8aa5cdb4ab67 206 * @param rx the Pin to be used for receiving data
Jonathan Austin 1:8aa5cdb4ab67 207 *
Jonathan Austin 1:8aa5cdb4ab67 208 * @param rxBufferSize the size of the buffer to be used for receiving bytes
Jonathan Austin 1:8aa5cdb4ab67 209 *
Jonathan Austin 1:8aa5cdb4ab67 210 * @param txBufferSize the size of the buffer to be used for transmitting bytes
Jonathan Austin 1:8aa5cdb4ab67 211 *
Jonathan Austin 1:8aa5cdb4ab67 212 * @code
Jonathan Austin 1:8aa5cdb4ab67 213 * MicroBitSerial serial(USBTX, USBRX);
Jonathan Austin 1:8aa5cdb4ab67 214 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 215 * @note the default baud rate is 115200. More API details can be found:
Jonathan Austin 1:8aa5cdb4ab67 216 * -https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/api/SerialBase.h
Jonathan Austin 1:8aa5cdb4ab67 217 * -https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/api/RawSerial.h
Jonathan Austin 1:8aa5cdb4ab67 218 *
Jonathan Austin 1:8aa5cdb4ab67 219 * Buffers aren't allocated until the first send or receive respectively.
Jonathan Austin 1:8aa5cdb4ab67 220 */
Jonathan Austin 1:8aa5cdb4ab67 221 MicroBitSerial(PinName tx, PinName rx, uint8_t rxBufferSize = MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE, uint8_t txBufferSize = MICROBIT_SERIAL_DEFAULT_BUFFER_SIZE);
Jonathan Austin 1:8aa5cdb4ab67 222
Jonathan Austin 1:8aa5cdb4ab67 223 /**
Jonathan Austin 1:8aa5cdb4ab67 224 * Sends a single character over the serial line.
Jonathan Austin 1:8aa5cdb4ab67 225 *
Jonathan Austin 1:8aa5cdb4ab67 226 * @param c the character to send
Jonathan Austin 1:8aa5cdb4ab67 227 *
Jonathan Austin 1:8aa5cdb4ab67 228 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 229 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 230 *
Jonathan Austin 1:8aa5cdb4ab67 231 * ASYNC - the character is copied into the txBuff and returns immediately.
Jonathan Austin 1:8aa5cdb4ab67 232 *
Jonathan Austin 1:8aa5cdb4ab67 233 * SYNC_SPINWAIT - the character is copied into the txBuff and this method
Jonathan Austin 1:8aa5cdb4ab67 234 * will spin (lock up the processor) until the character has
Jonathan Austin 1:8aa5cdb4ab67 235 * been sent.
Jonathan Austin 1:8aa5cdb4ab67 236 *
Jonathan Austin 1:8aa5cdb4ab67 237 * SYNC_SLEEP - the character is copied into the txBuff and the fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 238 * until the character has been sent. This allows other fibers
Jonathan Austin 1:8aa5cdb4ab67 239 * to continue execution.
Jonathan Austin 1:8aa5cdb4ab67 240 *
Jonathan Austin 1:8aa5cdb4ab67 241 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 242 *
Jonathan Austin 1:8aa5cdb4ab67 243 * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 244 * is using the serial instance for transmission.
Jonathan Austin 1:8aa5cdb4ab67 245 */
Jonathan Austin 1:8aa5cdb4ab67 246 int sendChar(char c, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 247
Jonathan Austin 1:8aa5cdb4ab67 248 /**
Jonathan Austin 1:8aa5cdb4ab67 249 * Sends a ManagedString over the serial line.
Jonathan Austin 1:8aa5cdb4ab67 250 *
Jonathan Austin 1:8aa5cdb4ab67 251 * @param s the string to send
Jonathan Austin 1:8aa5cdb4ab67 252 *
Jonathan Austin 1:8aa5cdb4ab67 253 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 254 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 255 *
Jonathan Austin 1:8aa5cdb4ab67 256 * ASYNC - bytes are copied into the txBuff and returns immediately.
Jonathan Austin 1:8aa5cdb4ab67 257 *
Jonathan Austin 1:8aa5cdb4ab67 258 * SYNC_SPINWAIT - bytes are copied into the txBuff and this method
Jonathan Austin 1:8aa5cdb4ab67 259 * will spin (lock up the processor) until all bytes
Jonathan Austin 1:8aa5cdb4ab67 260 * have been sent.
Jonathan Austin 1:8aa5cdb4ab67 261 *
Jonathan Austin 1:8aa5cdb4ab67 262 * SYNC_SLEEP - bytes are copied into the txBuff and the fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 263 * until all bytes have been sent. This allows other fibers
Jonathan Austin 1:8aa5cdb4ab67 264 * to continue execution.
Jonathan Austin 1:8aa5cdb4ab67 265 *
Jonathan Austin 1:8aa5cdb4ab67 266 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 267 *
Jonathan Austin 1:8aa5cdb4ab67 268 * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 269 * is using the serial instance for transmission.
Jonathan Austin 1:8aa5cdb4ab67 270 */
Jonathan Austin 1:8aa5cdb4ab67 271 int send(ManagedString s, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 272
Jonathan Austin 1:8aa5cdb4ab67 273 /**
Jonathan Austin 1:8aa5cdb4ab67 274 * Sends a buffer of known length over the serial line.
Jonathan Austin 1:8aa5cdb4ab67 275 *
Jonathan Austin 1:8aa5cdb4ab67 276 * @param buffer a pointer to the first character of the buffer
Jonathan Austin 1:8aa5cdb4ab67 277 *
Jonathan Austin 1:8aa5cdb4ab67 278 * @param len the number of bytes that are safely available to read.
Jonathan Austin 1:8aa5cdb4ab67 279 *
Jonathan Austin 1:8aa5cdb4ab67 280 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 281 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 282 *
Jonathan Austin 1:8aa5cdb4ab67 283 * ASYNC - bytes are copied into the txBuff and returns immediately.
Jonathan Austin 1:8aa5cdb4ab67 284 *
Jonathan Austin 1:8aa5cdb4ab67 285 * SYNC_SPINWAIT - bytes are copied into the txBuff and this method
Jonathan Austin 1:8aa5cdb4ab67 286 * will spin (lock up the processor) until all bytes
Jonathan Austin 1:8aa5cdb4ab67 287 * have been sent.
Jonathan Austin 1:8aa5cdb4ab67 288 *
Jonathan Austin 1:8aa5cdb4ab67 289 * SYNC_SLEEP - bytes are copied into the txBuff and the fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 290 * until all bytes have been sent. This allows other fibers
Jonathan Austin 1:8aa5cdb4ab67 291 * to continue execution.
Jonathan Austin 1:8aa5cdb4ab67 292 *
Jonathan Austin 1:8aa5cdb4ab67 293 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 294 *
Jonathan Austin 1:8aa5cdb4ab67 295 * @return the number of bytes written, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 296 * is using the serial instance for transmission.
Jonathan Austin 1:8aa5cdb4ab67 297 */
Jonathan Austin 1:8aa5cdb4ab67 298 int send(uint8_t *buffer, int bufferLen, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 299
Jonathan Austin 1:8aa5cdb4ab67 300 /**
Jonathan Austin 1:8aa5cdb4ab67 301 * Reads a single character from the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 302 *
Jonathan Austin 1:8aa5cdb4ab67 303 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 304 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 305 *
Jonathan Austin 1:8aa5cdb4ab67 306 * ASYNC - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 307 * are no characters to be read, a value of MICROBIT_NO_DATA is returned immediately.
Jonathan Austin 1:8aa5cdb4ab67 308 *
Jonathan Austin 1:8aa5cdb4ab67 309 * SYNC_SPINWAIT - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 310 * are no characters to be read, this method will spin
Jonathan Austin 1:8aa5cdb4ab67 311 * (lock up the processor) until a character is available.
Jonathan Austin 1:8aa5cdb4ab67 312 *
Jonathan Austin 1:8aa5cdb4ab67 313 * SYNC_SLEEP - A character is read from the rxBuff if available, if there
Jonathan Austin 1:8aa5cdb4ab67 314 * are no characters to be read, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 315 * until there is a character available.
Jonathan Austin 1:8aa5cdb4ab67 316 *
Jonathan Austin 1:8aa5cdb4ab67 317 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 318 *
Jonathan Austin 1:8aa5cdb4ab67 319 * @return a character, MICROBIT_SERIAL_IN_USE if another fiber is using the serial instance for reception,
Jonathan Austin 1:8aa5cdb4ab67 320 * MICROBIT_NO_RESOURCES if buffer allocation did not complete successfully, or MICROBIT_NO_DATA if
Jonathan Austin 1:8aa5cdb4ab67 321 * the rx buffer is empty and the mode given is ASYNC.
Jonathan Austin 1:8aa5cdb4ab67 322 */
Jonathan Austin 1:8aa5cdb4ab67 323 int read(MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 324
Jonathan Austin 1:8aa5cdb4ab67 325 /**
Jonathan Austin 1:8aa5cdb4ab67 326 * Reads multiple characters from the rxBuff and returns them as a ManagedString
Jonathan Austin 1:8aa5cdb4ab67 327 *
Jonathan Austin 1:8aa5cdb4ab67 328 * @param size the number of characters to read.
Jonathan Austin 1:8aa5cdb4ab67 329 *
Jonathan Austin 1:8aa5cdb4ab67 330 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 331 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 332 *
Jonathan Austin 1:8aa5cdb4ab67 333 * ASYNC - If the desired number of characters are available, this will return
Jonathan Austin 1:8aa5cdb4ab67 334 * a ManagedString with the expected size. Otherwise, it will read however
Jonathan Austin 1:8aa5cdb4ab67 335 * many characters there are available.
Jonathan Austin 1:8aa5cdb4ab67 336 *
Jonathan Austin 1:8aa5cdb4ab67 337 * SYNC_SPINWAIT - If the desired number of characters are available, this will return
Jonathan Austin 1:8aa5cdb4ab67 338 * a ManagedString with the expected size. Otherwise, this method will spin
Jonathan Austin 1:8aa5cdb4ab67 339 * (lock up the processor) until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 340 *
Jonathan Austin 1:8aa5cdb4ab67 341 * SYNC_SLEEP - If the desired number of characters are available, this will return
Jonathan Austin 1:8aa5cdb4ab67 342 * a ManagedString with the expected size. Otherwise, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 343 * until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 344 *
Jonathan Austin 1:8aa5cdb4ab67 345 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 346 *
Jonathan Austin 1:8aa5cdb4ab67 347 * @return A ManagedString, or an empty ManagedString if an error was encountered during the read.
Jonathan Austin 1:8aa5cdb4ab67 348 */
Jonathan Austin 1:8aa5cdb4ab67 349 ManagedString read(int size, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 350
Jonathan Austin 1:8aa5cdb4ab67 351 /**
Jonathan Austin 1:8aa5cdb4ab67 352 * Reads multiple characters from the rxBuff and fills a user buffer.
Jonathan Austin 1:8aa5cdb4ab67 353 *
Jonathan Austin 1:8aa5cdb4ab67 354 * @param buffer a pointer to a user allocated buffer.
Jonathan Austin 1:8aa5cdb4ab67 355 *
Jonathan Austin 1:8aa5cdb4ab67 356 * @param bufferLen the amount of data that can be safely stored
Jonathan Austin 1:8aa5cdb4ab67 357 *
Jonathan Austin 1:8aa5cdb4ab67 358 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 359 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 360 *
Jonathan Austin 1:8aa5cdb4ab67 361 * ASYNC - If the desired number of characters are available, this will fill
Jonathan Austin 1:8aa5cdb4ab67 362 * the given buffer. Otherwise, it will fill the buffer with however
Jonathan Austin 1:8aa5cdb4ab67 363 * many characters there are available.
Jonathan Austin 1:8aa5cdb4ab67 364 *
Jonathan Austin 1:8aa5cdb4ab67 365 * SYNC_SPINWAIT - If the desired number of characters are available, this will fill
Jonathan Austin 1:8aa5cdb4ab67 366 * the given buffer. Otherwise, this method will spin (lock up the processor)
Jonathan Austin 1:8aa5cdb4ab67 367 * and fill the buffer until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 368 *
Jonathan Austin 1:8aa5cdb4ab67 369 * SYNC_SLEEP - If the desired number of characters are available, this will fill
Jonathan Austin 1:8aa5cdb4ab67 370 * the given buffer. Otherwise, the calling fiber sleeps
Jonathan Austin 1:8aa5cdb4ab67 371 * until the desired number of characters have been read.
Jonathan Austin 1:8aa5cdb4ab67 372 *
Jonathan Austin 1:8aa5cdb4ab67 373 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 374 *
Jonathan Austin 1:8aa5cdb4ab67 375 * @return the number of characters read, or MICROBIT_SERIAL_IN_USE if another fiber
Jonathan Austin 1:8aa5cdb4ab67 376 * is using the instance for receiving.
Jonathan Austin 1:8aa5cdb4ab67 377 */
Jonathan Austin 1:8aa5cdb4ab67 378 int read(uint8_t *buffer, int bufferLen, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 379
Jonathan Austin 1:8aa5cdb4ab67 380 /**
Jonathan Austin 1:8aa5cdb4ab67 381 * Reads until one of the delimeters matches a character in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 382 *
Jonathan Austin 1:8aa5cdb4ab67 383 * @param delimeters a ManagedString containing a sequence of delimeter characters e.g. ManagedString("\r\n")
Jonathan Austin 1:8aa5cdb4ab67 384 *
Jonathan Austin 1:8aa5cdb4ab67 385 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 386 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 387 *
Jonathan Austin 1:8aa5cdb4ab67 388 * ASYNC - If one of the delimeters matches a character already in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 389 * this method will return a ManagedString up to the delimeter.
Jonathan Austin 1:8aa5cdb4ab67 390 * Otherwise, it will return an Empty ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 391 *
Jonathan Austin 1:8aa5cdb4ab67 392 * SYNC_SPINWAIT - If one of the delimeters matches a character already in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 393 * this method will return a ManagedString up to the delimeter.
Jonathan Austin 1:8aa5cdb4ab67 394 * Otherwise, this method will spin (lock up the processor) until a
Jonathan Austin 1:8aa5cdb4ab67 395 * received character matches one of the delimeters.
Jonathan Austin 1:8aa5cdb4ab67 396 *
Jonathan Austin 1:8aa5cdb4ab67 397 * SYNC_SLEEP - If one of the delimeters matches a character already in the rxBuff
Jonathan Austin 1:8aa5cdb4ab67 398 * this method will return a ManagedString up to the delimeter.
Jonathan Austin 1:8aa5cdb4ab67 399 * Otherwise, the calling fiber sleeps until a character matching one
Jonathan Austin 1:8aa5cdb4ab67 400 * of the delimeters is seen.
Jonathan Austin 1:8aa5cdb4ab67 401 *
Jonathan Austin 1:8aa5cdb4ab67 402 * Defaults to SYNC_SLEEP.
Jonathan Austin 1:8aa5cdb4ab67 403 *
Jonathan Austin 1:8aa5cdb4ab67 404 * @return A ManagedString containing the characters up to a delimeter, or an Empty ManagedString,
Jonathan Austin 1:8aa5cdb4ab67 405 * if another fiber is currently using this instance for reception.
Jonathan Austin 1:8aa5cdb4ab67 406 *
Jonathan Austin 1:8aa5cdb4ab67 407 * @note delimeters are matched on a per byte basis.
Jonathan Austin 1:8aa5cdb4ab67 408 */
Jonathan Austin 1:8aa5cdb4ab67 409 ManagedString readUntil(ManagedString delimeters, MicroBitSerialMode mode = MICROBIT_DEFAULT_SERIAL_MODE);
Jonathan Austin 1:8aa5cdb4ab67 410
Jonathan Austin 1:8aa5cdb4ab67 411 /**
Jonathan Austin 1:8aa5cdb4ab67 412 * A wrapper around the inherited method "baud" so we can trap the baud rate
Jonathan Austin 1:8aa5cdb4ab67 413 * as it changes and restore it if redirect() is called.
Jonathan Austin 1:8aa5cdb4ab67 414 *
Jonathan Austin 1:8aa5cdb4ab67 415 * @param baudrate the new baudrate. See:
Jonathan Austin 1:8aa5cdb4ab67 416 * - https://github.com/mbedmicro/mbed/blob/master/libraries/mbed/targets/hal/TARGET_NORDIC/TARGET_MCU_NRF51822/serial_api.c
Jonathan Austin 1:8aa5cdb4ab67 417 * for permitted baud rates.
Jonathan Austin 1:8aa5cdb4ab67 418 *
Jonathan Austin 1:8aa5cdb4ab67 419 * @return MICROBIT_INVALID_PARAMETER if baud rate is less than 0, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 420 *
Jonathan Austin 1:8aa5cdb4ab67 421 * @note the underlying implementation chooses the first allowable rate at or above that requested.
Jonathan Austin 1:8aa5cdb4ab67 422 */
Jonathan Austin 1:8aa5cdb4ab67 423 void baud(int baudrate);
Jonathan Austin 1:8aa5cdb4ab67 424
Jonathan Austin 1:8aa5cdb4ab67 425 /**
Jonathan Austin 1:8aa5cdb4ab67 426 * A way of dynamically configuring the serial instance to use pins other than USBTX and USBRX.
Jonathan Austin 1:8aa5cdb4ab67 427 *
Jonathan Austin 1:8aa5cdb4ab67 428 * @param tx the new transmission pin.
Jonathan Austin 1:8aa5cdb4ab67 429 *
Jonathan Austin 1:8aa5cdb4ab67 430 * @param rx the new reception pin.
Jonathan Austin 1:8aa5cdb4ab67 431 *
Jonathan Austin 1:8aa5cdb4ab67 432 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently transmitting or receiving, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 433 */
Jonathan Austin 1:8aa5cdb4ab67 434 int redirect(PinName tx, PinName rx);
Jonathan Austin 1:8aa5cdb4ab67 435
Jonathan Austin 1:8aa5cdb4ab67 436 /**
Jonathan Austin 1:8aa5cdb4ab67 437 * Configures an event to be fired after "len" characters.
Jonathan Austin 1:8aa5cdb4ab67 438 *
Jonathan Austin 1:8aa5cdb4ab67 439 * @param len the number of characters to wait before triggering the event.
Jonathan Austin 1:8aa5cdb4ab67 440 *
Jonathan Austin 1:8aa5cdb4ab67 441 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 442 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 443 *
Jonathan Austin 1:8aa5cdb4ab67 444 * ASYNC - Will configure the event and return immediately.
Jonathan Austin 1:8aa5cdb4ab67 445 *
Jonathan Austin 1:8aa5cdb4ab67 446 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
Jonathan Austin 1:8aa5cdb4ab67 447 *
Jonathan Austin 1:8aa5cdb4ab67 448 * SYNC_SLEEP - Will configure the event and block the current fiber until the
Jonathan Austin 1:8aa5cdb4ab67 449 * event is received.
Jonathan Austin 1:8aa5cdb4ab67 450 *
Jonathan Austin 1:8aa5cdb4ab67 451 * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 452 */
Jonathan Austin 1:8aa5cdb4ab67 453 int eventAfter(int len, MicroBitSerialMode mode = ASYNC);
Jonathan Austin 1:8aa5cdb4ab67 454
Jonathan Austin 1:8aa5cdb4ab67 455 /**
Jonathan Austin 1:8aa5cdb4ab67 456 * Configures an event to be fired on a match with one of the delimeters.
Jonathan Austin 1:8aa5cdb4ab67 457 *
Jonathan Austin 1:8aa5cdb4ab67 458 * @param delimeters the characters to match received characters against e.g. ManagedString("\r\n")
Jonathan Austin 1:8aa5cdb4ab67 459 *
Jonathan Austin 1:8aa5cdb4ab67 460 * @param mode the selected mode, one of: ASYNC, SYNC_SPINWAIT, SYNC_SLEEP. Each mode
Jonathan Austin 1:8aa5cdb4ab67 461 * gives a different behaviour:
Jonathan Austin 1:8aa5cdb4ab67 462 *
Jonathan Austin 1:8aa5cdb4ab67 463 * ASYNC - Will configure the event and return immediately.
Jonathan Austin 1:8aa5cdb4ab67 464 *
Jonathan Austin 1:8aa5cdb4ab67 465 * SYNC_SPINWAIT - will return MICROBIT_INVALID_PARAMETER
Jonathan Austin 1:8aa5cdb4ab67 466 *
Jonathan Austin 1:8aa5cdb4ab67 467 * SYNC_SLEEP - Will configure the event and block the current fiber until the
Jonathan Austin 1:8aa5cdb4ab67 468 * event is received.
Jonathan Austin 1:8aa5cdb4ab67 469 *
Jonathan Austin 1:8aa5cdb4ab67 470 * @return MICROBIT_INVALID_PARAMETER if the mode given is SYNC_SPINWAIT, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 471 *
Jonathan Austin 1:8aa5cdb4ab67 472 * @note delimeters are matched on a per byte basis.
Jonathan Austin 1:8aa5cdb4ab67 473 */
Jonathan Austin 1:8aa5cdb4ab67 474 int eventOn(ManagedString delimeters, MicroBitSerialMode mode = ASYNC);
Jonathan Austin 1:8aa5cdb4ab67 475
Jonathan Austin 1:8aa5cdb4ab67 476 /**
Jonathan Austin 1:8aa5cdb4ab67 477 * Determines whether there is any data waiting in our Rx buffer.
Jonathan Austin 1:8aa5cdb4ab67 478 *
Jonathan Austin 1:8aa5cdb4ab67 479 * @return 1 if we have space, 0 if we do not.
Jonathan Austin 1:8aa5cdb4ab67 480 *
Jonathan Austin 1:8aa5cdb4ab67 481 * @note We do not wrap the super's readable() method as we don't want to
Jonathan Austin 1:8aa5cdb4ab67 482 * interfere with communities that use manual calls to serial.readable().
Jonathan Austin 1:8aa5cdb4ab67 483 */
Jonathan Austin 1:8aa5cdb4ab67 484 int isReadable();
Jonathan Austin 1:8aa5cdb4ab67 485
Jonathan Austin 1:8aa5cdb4ab67 486 /**
Jonathan Austin 1:8aa5cdb4ab67 487 * Determines if we have space in our txBuff.
Jonathan Austin 1:8aa5cdb4ab67 488 *
Jonathan Austin 1:8aa5cdb4ab67 489 * @return 1 if we have space, 0 if we do not.
Jonathan Austin 1:8aa5cdb4ab67 490 *
Jonathan Austin 1:8aa5cdb4ab67 491 * @note We do not wrap the super's writeable() method as we don't want to
Jonathan Austin 1:8aa5cdb4ab67 492 * interfere with communities that use manual calls to serial.writeable().
Jonathan Austin 1:8aa5cdb4ab67 493 */
Jonathan Austin 1:8aa5cdb4ab67 494 int isWriteable();
Jonathan Austin 1:8aa5cdb4ab67 495
Jonathan Austin 1:8aa5cdb4ab67 496 /**
Jonathan Austin 1:8aa5cdb4ab67 497 * Reconfigures the size of our rxBuff
Jonathan Austin 1:8aa5cdb4ab67 498 *
Jonathan Austin 1:8aa5cdb4ab67 499 * @param size the new size for our rxBuff
Jonathan Austin 1:8aa5cdb4ab67 500 *
Jonathan Austin 1:8aa5cdb4ab67 501 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 502 * for reception, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 503 */
Jonathan Austin 1:8aa5cdb4ab67 504 int setRxBufferSize(uint8_t size);
Jonathan Austin 1:8aa5cdb4ab67 505
Jonathan Austin 1:8aa5cdb4ab67 506 /**
Jonathan Austin 1:8aa5cdb4ab67 507 * Reconfigures the size of our txBuff
Jonathan Austin 1:8aa5cdb4ab67 508 *
Jonathan Austin 1:8aa5cdb4ab67 509 * @param size the new size for our txBuff
Jonathan Austin 1:8aa5cdb4ab67 510 *
Jonathan Austin 1:8aa5cdb4ab67 511 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 512 * for transmission, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 513 */
Jonathan Austin 1:8aa5cdb4ab67 514 int setTxBufferSize(uint8_t size);
Jonathan Austin 1:8aa5cdb4ab67 515
Jonathan Austin 1:8aa5cdb4ab67 516 /**
Jonathan Austin 1:8aa5cdb4ab67 517 * The size of our rx buffer in bytes.
Jonathan Austin 1:8aa5cdb4ab67 518 *
Jonathan Austin 1:8aa5cdb4ab67 519 * @return the current size of rxBuff in bytes
Jonathan Austin 1:8aa5cdb4ab67 520 */
Jonathan Austin 1:8aa5cdb4ab67 521 int getRxBufferSize();
Jonathan Austin 1:8aa5cdb4ab67 522
Jonathan Austin 1:8aa5cdb4ab67 523 /**
Jonathan Austin 1:8aa5cdb4ab67 524 * The size of our tx buffer in bytes.
Jonathan Austin 1:8aa5cdb4ab67 525 *
Jonathan Austin 1:8aa5cdb4ab67 526 * @return the current size of txBuff in bytes
Jonathan Austin 1:8aa5cdb4ab67 527 */
Jonathan Austin 1:8aa5cdb4ab67 528 int getTxBufferSize();
Jonathan Austin 1:8aa5cdb4ab67 529
Jonathan Austin 1:8aa5cdb4ab67 530 /**
Jonathan Austin 1:8aa5cdb4ab67 531 * Sets the tail to match the head of our circular buffer for reception,
Jonathan Austin 1:8aa5cdb4ab67 532 * effectively clearing the reception buffer.
Jonathan Austin 1:8aa5cdb4ab67 533 *
Jonathan Austin 1:8aa5cdb4ab67 534 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 535 * for reception, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 536 */
Jonathan Austin 1:8aa5cdb4ab67 537 int clearRxBuffer();
Jonathan Austin 1:8aa5cdb4ab67 538
Jonathan Austin 1:8aa5cdb4ab67 539 /**
Jonathan Austin 1:8aa5cdb4ab67 540 * Sets the tail to match the head of our circular buffer for transmission,
Jonathan Austin 1:8aa5cdb4ab67 541 * effectively clearing the transmission buffer.
Jonathan Austin 1:8aa5cdb4ab67 542 *
Jonathan Austin 1:8aa5cdb4ab67 543 * @return MICROBIT_SERIAL_IN_USE if another fiber is currently using this instance
Jonathan Austin 1:8aa5cdb4ab67 544 * for transmission, otherwise MICROBIT_OK.
Jonathan Austin 1:8aa5cdb4ab67 545 */
Jonathan Austin 1:8aa5cdb4ab67 546 int clearTxBuffer();
Jonathan Austin 1:8aa5cdb4ab67 547
Jonathan Austin 1:8aa5cdb4ab67 548 /**
Jonathan Austin 1:8aa5cdb4ab67 549 * The number of bytes currently stored in our rx buffer waiting to be digested,
Jonathan Austin 1:8aa5cdb4ab67 550 * by the user.
Jonathan Austin 1:8aa5cdb4ab67 551 *
Jonathan Austin 1:8aa5cdb4ab67 552 * @return The currently buffered number of bytes in our rxBuff.
Jonathan Austin 1:8aa5cdb4ab67 553 */
Jonathan Austin 1:8aa5cdb4ab67 554 int rxBufferedSize();
Jonathan Austin 1:8aa5cdb4ab67 555
Jonathan Austin 1:8aa5cdb4ab67 556 /**
Jonathan Austin 1:8aa5cdb4ab67 557 * The number of bytes currently stored in our tx buffer waiting to be transmitted
Jonathan Austin 1:8aa5cdb4ab67 558 * by the hardware.
Jonathan Austin 1:8aa5cdb4ab67 559 *
Jonathan Austin 1:8aa5cdb4ab67 560 * @return The currently buffered number of bytes in our txBuff.
Jonathan Austin 1:8aa5cdb4ab67 561 */
Jonathan Austin 1:8aa5cdb4ab67 562 int txBufferedSize();
Jonathan Austin 1:8aa5cdb4ab67 563
Jonathan Austin 1:8aa5cdb4ab67 564 /**
Jonathan Austin 1:8aa5cdb4ab67 565 * Determines if the serial bus is currently in use by another fiber for reception.
Jonathan Austin 1:8aa5cdb4ab67 566 *
Jonathan Austin 1:8aa5cdb4ab67 567 * @return The state of our mutex lock for reception.
Jonathan Austin 1:8aa5cdb4ab67 568 *
Jonathan Austin 1:8aa5cdb4ab67 569 * @note Only one fiber can call read at a time
Jonathan Austin 1:8aa5cdb4ab67 570 */
Jonathan Austin 1:8aa5cdb4ab67 571 int rxInUse();
Jonathan Austin 1:8aa5cdb4ab67 572
Jonathan Austin 1:8aa5cdb4ab67 573 /**
Jonathan Austin 1:8aa5cdb4ab67 574 * Determines if the serial bus is currently in use by another fiber for transmission.
Jonathan Austin 1:8aa5cdb4ab67 575 *
Jonathan Austin 1:8aa5cdb4ab67 576 * @return The state of our mutex lock for transmition.
Jonathan Austin 1:8aa5cdb4ab67 577 *
Jonathan Austin 1:8aa5cdb4ab67 578 * @note Only one fiber can call send at a time
Jonathan Austin 1:8aa5cdb4ab67 579 */
Jonathan Austin 1:8aa5cdb4ab67 580 int txInUse();
Jonathan Austin 1:8aa5cdb4ab67 581
Jonathan Austin 1:8aa5cdb4ab67 582 /**
Jonathan Austin 1:8aa5cdb4ab67 583 * Detaches a previously configured interrupt
Jonathan Austin 1:8aa5cdb4ab67 584 *
Jonathan Austin 1:8aa5cdb4ab67 585 * @param interruptType one of Serial::RxIrq or Serial::TxIrq
Jonathan Austin 1:8aa5cdb4ab67 586 */
Jonathan Austin 1:8aa5cdb4ab67 587 void detach(Serial::IrqType interuptType);
Jonathan Austin 1:8aa5cdb4ab67 588
Jonathan Austin 1:8aa5cdb4ab67 589 };
Jonathan Austin 1:8aa5cdb4ab67 590
LancasterUniversity 22:23d7b9a4b082 591 #endif