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