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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.