Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/drivers/UARTSerial.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
marcozecchini 0:9fca2b23d0ba 1 /* mbed Microcontroller Library
marcozecchini 0:9fca2b23d0ba 2 * Copyright (c) 2006-2017 ARM Limited
marcozecchini 0:9fca2b23d0ba 3 *
marcozecchini 0:9fca2b23d0ba 4 * Licensed under the Apache License, Version 2.0 (the "License");
marcozecchini 0:9fca2b23d0ba 5 * you may not use this file except in compliance with the License.
marcozecchini 0:9fca2b23d0ba 6 * You may obtain a copy of the License at
marcozecchini 0:9fca2b23d0ba 7 *
marcozecchini 0:9fca2b23d0ba 8 * http://www.apache.org/licenses/LICENSE-2.0
marcozecchini 0:9fca2b23d0ba 9 *
marcozecchini 0:9fca2b23d0ba 10 * Unless required by applicable law or agreed to in writing, software
marcozecchini 0:9fca2b23d0ba 11 * distributed under the License is distributed on an "AS IS" BASIS,
marcozecchini 0:9fca2b23d0ba 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
marcozecchini 0:9fca2b23d0ba 13 * See the License for the specific language governing permissions and
marcozecchini 0:9fca2b23d0ba 14 * limitations under the License.
marcozecchini 0:9fca2b23d0ba 15 */
marcozecchini 0:9fca2b23d0ba 16
marcozecchini 0:9fca2b23d0ba 17 #ifndef MBED_UARTSERIAL_H
marcozecchini 0:9fca2b23d0ba 18 #define MBED_UARTSERIAL_H
marcozecchini 0:9fca2b23d0ba 19
marcozecchini 0:9fca2b23d0ba 20 #include "platform/platform.h"
marcozecchini 0:9fca2b23d0ba 21
marcozecchini 0:9fca2b23d0ba 22 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
marcozecchini 0:9fca2b23d0ba 23
marcozecchini 0:9fca2b23d0ba 24 #include "FileHandle.h"
marcozecchini 0:9fca2b23d0ba 25 #include "SerialBase.h"
marcozecchini 0:9fca2b23d0ba 26 #include "InterruptIn.h"
marcozecchini 0:9fca2b23d0ba 27 #include "PlatformMutex.h"
marcozecchini 0:9fca2b23d0ba 28 #include "serial_api.h"
marcozecchini 0:9fca2b23d0ba 29 #include "CircularBuffer.h"
marcozecchini 0:9fca2b23d0ba 30 #include "platform/NonCopyable.h"
marcozecchini 0:9fca2b23d0ba 31
marcozecchini 0:9fca2b23d0ba 32 #ifndef MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE
marcozecchini 0:9fca2b23d0ba 33 #define MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE 256
marcozecchini 0:9fca2b23d0ba 34 #endif
marcozecchini 0:9fca2b23d0ba 35
marcozecchini 0:9fca2b23d0ba 36 #ifndef MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE
marcozecchini 0:9fca2b23d0ba 37 #define MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE 256
marcozecchini 0:9fca2b23d0ba 38 #endif
marcozecchini 0:9fca2b23d0ba 39
marcozecchini 0:9fca2b23d0ba 40 namespace mbed {
marcozecchini 0:9fca2b23d0ba 41
marcozecchini 0:9fca2b23d0ba 42 /** \addtogroup drivers */
marcozecchini 0:9fca2b23d0ba 43
marcozecchini 0:9fca2b23d0ba 44 /** Class providing buffered UART communication functionality using separate circular buffer for send and receive channels
marcozecchini 0:9fca2b23d0ba 45 *
marcozecchini 0:9fca2b23d0ba 46 * @ingroup drivers
marcozecchini 0:9fca2b23d0ba 47 */
marcozecchini 0:9fca2b23d0ba 48
marcozecchini 0:9fca2b23d0ba 49 class UARTSerial : private SerialBase, public FileHandle, private NonCopyable<UARTSerial> {
marcozecchini 0:9fca2b23d0ba 50
marcozecchini 0:9fca2b23d0ba 51 public:
marcozecchini 0:9fca2b23d0ba 52
marcozecchini 0:9fca2b23d0ba 53 /** Create a UARTSerial port, connected to the specified transmit and receive pins, with a particular baud rate.
marcozecchini 0:9fca2b23d0ba 54 * @param tx Transmit pin
marcozecchini 0:9fca2b23d0ba 55 * @param rx Receive pin
marcozecchini 0:9fca2b23d0ba 56 * @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
marcozecchini 0:9fca2b23d0ba 57 */
marcozecchini 0:9fca2b23d0ba 58 UARTSerial(PinName tx, PinName rx, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
marcozecchini 0:9fca2b23d0ba 59 virtual ~UARTSerial();
marcozecchini 0:9fca2b23d0ba 60
marcozecchini 0:9fca2b23d0ba 61 /** Equivalent to POSIX poll(). Derived from FileHandle.
marcozecchini 0:9fca2b23d0ba 62 * Provides a mechanism to multiplex input/output over a set of file handles.
marcozecchini 0:9fca2b23d0ba 63 */
marcozecchini 0:9fca2b23d0ba 64 virtual short poll(short events) const;
marcozecchini 0:9fca2b23d0ba 65
marcozecchini 0:9fca2b23d0ba 66 /* Resolve ambiguities versus our private SerialBase
marcozecchini 0:9fca2b23d0ba 67 * (for writable, spelling differs, but just in case)
marcozecchini 0:9fca2b23d0ba 68 */
marcozecchini 0:9fca2b23d0ba 69 using FileHandle::readable;
marcozecchini 0:9fca2b23d0ba 70 using FileHandle::writable;
marcozecchini 0:9fca2b23d0ba 71
marcozecchini 0:9fca2b23d0ba 72 /** Write the contents of a buffer to a file
marcozecchini 0:9fca2b23d0ba 73 *
marcozecchini 0:9fca2b23d0ba 74 * @param buffer The buffer to write from
marcozecchini 0:9fca2b23d0ba 75 * @param length The number of bytes to write
marcozecchini 0:9fca2b23d0ba 76 * @return The number of bytes written, negative error on failure
marcozecchini 0:9fca2b23d0ba 77 */
marcozecchini 0:9fca2b23d0ba 78 virtual ssize_t write(const void* buffer, size_t length);
marcozecchini 0:9fca2b23d0ba 79
marcozecchini 0:9fca2b23d0ba 80 /** Read the contents of a file into a buffer
marcozecchini 0:9fca2b23d0ba 81 *
marcozecchini 0:9fca2b23d0ba 82 * Follows POSIX semantics:
marcozecchini 0:9fca2b23d0ba 83 *
marcozecchini 0:9fca2b23d0ba 84 * * if no data is available, and non-blocking set return -EAGAIN
marcozecchini 0:9fca2b23d0ba 85 * * if no data is available, and blocking set, wait until data is available
marcozecchini 0:9fca2b23d0ba 86 * * If any data is available, call returns immediately
marcozecchini 0:9fca2b23d0ba 87 *
marcozecchini 0:9fca2b23d0ba 88 * @param buffer The buffer to read in to
marcozecchini 0:9fca2b23d0ba 89 * @param length The number of bytes to read
marcozecchini 0:9fca2b23d0ba 90 * @return The number of bytes read, 0 at end of file, negative error on failure
marcozecchini 0:9fca2b23d0ba 91 */
marcozecchini 0:9fca2b23d0ba 92 virtual ssize_t read(void* buffer, size_t length);
marcozecchini 0:9fca2b23d0ba 93
marcozecchini 0:9fca2b23d0ba 94 /** Close a file
marcozecchini 0:9fca2b23d0ba 95 *
marcozecchini 0:9fca2b23d0ba 96 * @return 0 on success, negative error code on failure
marcozecchini 0:9fca2b23d0ba 97 */
marcozecchini 0:9fca2b23d0ba 98 virtual int close();
marcozecchini 0:9fca2b23d0ba 99
marcozecchini 0:9fca2b23d0ba 100 /** Check if the file in an interactive terminal device
marcozecchini 0:9fca2b23d0ba 101 *
marcozecchini 0:9fca2b23d0ba 102 * @return True if the file is a terminal
marcozecchini 0:9fca2b23d0ba 103 * @return False if the file is not a terminal
marcozecchini 0:9fca2b23d0ba 104 * @return Negative error code on failure
marcozecchini 0:9fca2b23d0ba 105 */
marcozecchini 0:9fca2b23d0ba 106 virtual int isatty();
marcozecchini 0:9fca2b23d0ba 107
marcozecchini 0:9fca2b23d0ba 108 /** Move the file position to a given offset from from a given location
marcozecchini 0:9fca2b23d0ba 109 *
marcozecchini 0:9fca2b23d0ba 110 * Not valid for a device type FileHandle like UARTSerial.
marcozecchini 0:9fca2b23d0ba 111 * In case of UARTSerial, returns ESPIPE
marcozecchini 0:9fca2b23d0ba 112 *
marcozecchini 0:9fca2b23d0ba 113 * @param offset The offset from whence to move to
marcozecchini 0:9fca2b23d0ba 114 * @param whence The start of where to seek
marcozecchini 0:9fca2b23d0ba 115 * SEEK_SET to start from beginning of file,
marcozecchini 0:9fca2b23d0ba 116 * SEEK_CUR to start from current position in file,
marcozecchini 0:9fca2b23d0ba 117 * SEEK_END to start from end of file
marcozecchini 0:9fca2b23d0ba 118 * @return The new offset of the file, negative error code on failure
marcozecchini 0:9fca2b23d0ba 119 */
marcozecchini 0:9fca2b23d0ba 120 virtual off_t seek(off_t offset, int whence);
marcozecchini 0:9fca2b23d0ba 121
marcozecchini 0:9fca2b23d0ba 122 /** Flush any buffers associated with the file
marcozecchini 0:9fca2b23d0ba 123 *
marcozecchini 0:9fca2b23d0ba 124 * @return 0 on success, negative error code on failure
marcozecchini 0:9fca2b23d0ba 125 */
marcozecchini 0:9fca2b23d0ba 126 virtual int sync();
marcozecchini 0:9fca2b23d0ba 127
marcozecchini 0:9fca2b23d0ba 128 /** Set blocking or non-blocking mode
marcozecchini 0:9fca2b23d0ba 129 * The default is blocking.
marcozecchini 0:9fca2b23d0ba 130 *
marcozecchini 0:9fca2b23d0ba 131 * @param blocking true for blocking mode, false for non-blocking mode.
marcozecchini 0:9fca2b23d0ba 132 */
marcozecchini 0:9fca2b23d0ba 133 virtual int set_blocking(bool blocking)
marcozecchini 0:9fca2b23d0ba 134 {
marcozecchini 0:9fca2b23d0ba 135 _blocking = blocking;
marcozecchini 0:9fca2b23d0ba 136 return 0;
marcozecchini 0:9fca2b23d0ba 137 }
marcozecchini 0:9fca2b23d0ba 138
marcozecchini 0:9fca2b23d0ba 139 /** Register a callback on state change of the file.
marcozecchini 0:9fca2b23d0ba 140 *
marcozecchini 0:9fca2b23d0ba 141 * The specified callback will be called on state changes such as when
marcozecchini 0:9fca2b23d0ba 142 * the file can be written to or read from.
marcozecchini 0:9fca2b23d0ba 143 *
marcozecchini 0:9fca2b23d0ba 144 * The callback may be called in an interrupt context and should not
marcozecchini 0:9fca2b23d0ba 145 * perform expensive operations.
marcozecchini 0:9fca2b23d0ba 146 *
marcozecchini 0:9fca2b23d0ba 147 * Note! This is not intended as an attach-like asynchronous api, but rather
marcozecchini 0:9fca2b23d0ba 148 * as a building block for constructing such functionality.
marcozecchini 0:9fca2b23d0ba 149 *
marcozecchini 0:9fca2b23d0ba 150 * The exact timing of when the registered function
marcozecchini 0:9fca2b23d0ba 151 * is called is not guaranteed and susceptible to change. It should be used
marcozecchini 0:9fca2b23d0ba 152 * as a cue to make read/write/poll calls to find the current state.
marcozecchini 0:9fca2b23d0ba 153 *
marcozecchini 0:9fca2b23d0ba 154 * @param func Function to call on state change
marcozecchini 0:9fca2b23d0ba 155 */
marcozecchini 0:9fca2b23d0ba 156 virtual void sigio(Callback<void()> func);
marcozecchini 0:9fca2b23d0ba 157
marcozecchini 0:9fca2b23d0ba 158 /** Setup interrupt handler for DCD line
marcozecchini 0:9fca2b23d0ba 159 *
marcozecchini 0:9fca2b23d0ba 160 * If DCD line is connected, an IRQ handler will be setup.
marcozecchini 0:9fca2b23d0ba 161 * Does nothing if DCD is NC, i.e., not connected.
marcozecchini 0:9fca2b23d0ba 162 *
marcozecchini 0:9fca2b23d0ba 163 * @param dcd_pin Pin-name for DCD
marcozecchini 0:9fca2b23d0ba 164 * @param active_high a boolean set to true if DCD polarity is active low
marcozecchini 0:9fca2b23d0ba 165 */
marcozecchini 0:9fca2b23d0ba 166 void set_data_carrier_detect(PinName dcd_pin, bool active_high = false);
marcozecchini 0:9fca2b23d0ba 167
marcozecchini 0:9fca2b23d0ba 168 /** Set the baud rate
marcozecchini 0:9fca2b23d0ba 169 *
marcozecchini 0:9fca2b23d0ba 170 * @param baud The baud rate
marcozecchini 0:9fca2b23d0ba 171 */
marcozecchini 0:9fca2b23d0ba 172 void set_baud(int baud);
marcozecchini 0:9fca2b23d0ba 173
marcozecchini 0:9fca2b23d0ba 174 // Expose private SerialBase::Parity as UARTSerial::Parity
marcozecchini 0:9fca2b23d0ba 175 using SerialBase::Parity;
marcozecchini 0:9fca2b23d0ba 176 // In C++11, we wouldn't need to also have using directives for each value
marcozecchini 0:9fca2b23d0ba 177 using SerialBase::None;
marcozecchini 0:9fca2b23d0ba 178 using SerialBase::Odd;
marcozecchini 0:9fca2b23d0ba 179 using SerialBase::Even;
marcozecchini 0:9fca2b23d0ba 180 using SerialBase::Forced1;
marcozecchini 0:9fca2b23d0ba 181 using SerialBase::Forced0;
marcozecchini 0:9fca2b23d0ba 182
marcozecchini 0:9fca2b23d0ba 183 /** Set the transmission format used by the serial port
marcozecchini 0:9fca2b23d0ba 184 *
marcozecchini 0:9fca2b23d0ba 185 * @param bits The number of bits in a word (5-8; default = 8)
marcozecchini 0:9fca2b23d0ba 186 * @param parity The parity used (None, Odd, Even, Forced1, Forced0; default = None)
marcozecchini 0:9fca2b23d0ba 187 * @param stop_bits The number of stop bits (1 or 2; default = 1)
marcozecchini 0:9fca2b23d0ba 188 */
marcozecchini 0:9fca2b23d0ba 189 void set_format(int bits=8, Parity parity=UARTSerial::None, int stop_bits=1);
marcozecchini 0:9fca2b23d0ba 190
marcozecchini 0:9fca2b23d0ba 191 #if DEVICE_SERIAL_FC
marcozecchini 0:9fca2b23d0ba 192 // For now use the base enum - but in future we may have extra options
marcozecchini 0:9fca2b23d0ba 193 // such as XON/XOFF or manual GPIO RTSCTS.
marcozecchini 0:9fca2b23d0ba 194 using SerialBase::Flow;
marcozecchini 0:9fca2b23d0ba 195 // In C++11, we wouldn't need to also have using directives for each value
marcozecchini 0:9fca2b23d0ba 196 using SerialBase::Disabled;
marcozecchini 0:9fca2b23d0ba 197 using SerialBase::RTS;
marcozecchini 0:9fca2b23d0ba 198 using SerialBase::CTS;
marcozecchini 0:9fca2b23d0ba 199 using SerialBase::RTSCTS;
marcozecchini 0:9fca2b23d0ba 200
marcozecchini 0:9fca2b23d0ba 201 /** Set the flow control type on the serial port
marcozecchini 0:9fca2b23d0ba 202 *
marcozecchini 0:9fca2b23d0ba 203 * @param type the flow control type (Disabled, RTS, CTS, RTSCTS)
marcozecchini 0:9fca2b23d0ba 204 * @param flow1 the first flow control pin (RTS for RTS or RTSCTS, CTS for CTS)
marcozecchini 0:9fca2b23d0ba 205 * @param flow2 the second flow control pin (CTS for RTSCTS)
marcozecchini 0:9fca2b23d0ba 206 */
marcozecchini 0:9fca2b23d0ba 207 void set_flow_control(Flow type, PinName flow1=NC, PinName flow2=NC);
marcozecchini 0:9fca2b23d0ba 208 #endif
marcozecchini 0:9fca2b23d0ba 209
marcozecchini 0:9fca2b23d0ba 210 private:
marcozecchini 0:9fca2b23d0ba 211
marcozecchini 0:9fca2b23d0ba 212 void wait_ms(uint32_t millisec);
marcozecchini 0:9fca2b23d0ba 213
marcozecchini 0:9fca2b23d0ba 214 /** SerialBase lock override */
marcozecchini 0:9fca2b23d0ba 215 virtual void lock(void);
marcozecchini 0:9fca2b23d0ba 216
marcozecchini 0:9fca2b23d0ba 217 /** SerialBase unlock override */
marcozecchini 0:9fca2b23d0ba 218 virtual void unlock(void);
marcozecchini 0:9fca2b23d0ba 219
marcozecchini 0:9fca2b23d0ba 220 /** Acquire mutex */
marcozecchini 0:9fca2b23d0ba 221 virtual void api_lock(void);
marcozecchini 0:9fca2b23d0ba 222
marcozecchini 0:9fca2b23d0ba 223 /** Release mutex */
marcozecchini 0:9fca2b23d0ba 224 virtual void api_unlock(void);
marcozecchini 0:9fca2b23d0ba 225
marcozecchini 0:9fca2b23d0ba 226 /** Software serial buffers
marcozecchini 0:9fca2b23d0ba 227 * By default buffer size is 256 for TX and 256 for RX. Configurable through mbed_app.json
marcozecchini 0:9fca2b23d0ba 228 */
marcozecchini 0:9fca2b23d0ba 229 CircularBuffer<char, MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE> _rxbuf;
marcozecchini 0:9fca2b23d0ba 230 CircularBuffer<char, MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE> _txbuf;
marcozecchini 0:9fca2b23d0ba 231
marcozecchini 0:9fca2b23d0ba 232 PlatformMutex _mutex;
marcozecchini 0:9fca2b23d0ba 233
marcozecchini 0:9fca2b23d0ba 234 Callback<void()> _sigio_cb;
marcozecchini 0:9fca2b23d0ba 235
marcozecchini 0:9fca2b23d0ba 236 bool _blocking;
marcozecchini 0:9fca2b23d0ba 237 bool _tx_irq_enabled;
marcozecchini 0:9fca2b23d0ba 238 bool _rx_irq_enabled;
marcozecchini 0:9fca2b23d0ba 239 InterruptIn *_dcd_irq;
marcozecchini 0:9fca2b23d0ba 240
marcozecchini 0:9fca2b23d0ba 241 /** Device Hanged up
marcozecchini 0:9fca2b23d0ba 242 * Determines if the device hanged up on us.
marcozecchini 0:9fca2b23d0ba 243 *
marcozecchini 0:9fca2b23d0ba 244 * @return True, if hanged up
marcozecchini 0:9fca2b23d0ba 245 */
marcozecchini 0:9fca2b23d0ba 246 bool hup() const;
marcozecchini 0:9fca2b23d0ba 247
marcozecchini 0:9fca2b23d0ba 248 /** ISRs for serial
marcozecchini 0:9fca2b23d0ba 249 * Routines to handle interrupts on serial pins.
marcozecchini 0:9fca2b23d0ba 250 * Copies data into Circular Buffer.
marcozecchini 0:9fca2b23d0ba 251 * Reports the state change to File handle.
marcozecchini 0:9fca2b23d0ba 252 */
marcozecchini 0:9fca2b23d0ba 253 void tx_irq(void);
marcozecchini 0:9fca2b23d0ba 254 void rx_irq(void);
marcozecchini 0:9fca2b23d0ba 255
marcozecchini 0:9fca2b23d0ba 256 void wake(void);
marcozecchini 0:9fca2b23d0ba 257
marcozecchini 0:9fca2b23d0ba 258 void dcd_irq(void);
marcozecchini 0:9fca2b23d0ba 259
marcozecchini 0:9fca2b23d0ba 260 };
marcozecchini 0:9fca2b23d0ba 261 } //namespace mbed
marcozecchini 0:9fca2b23d0ba 262
marcozecchini 0:9fca2b23d0ba 263 #endif //(DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
marcozecchini 0:9fca2b23d0ba 264 #endif //MBED_UARTSERIAL_H