Mistake on this page?
Report an issue in GitHub or email us
SerialBase.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2013 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 #ifndef MBED_SERIALBASE_H
18 #define MBED_SERIALBASE_H
19 
20 #include "platform/platform.h"
21 
22 #if DEVICE_SERIAL || defined(DOXYGEN_ONLY)
23 
24 #include "platform/Callback.h"
25 #include "hal/serial_api.h"
26 #include "platform/mbed_toolchain.h"
27 #include "platform/NonCopyable.h"
28 
29 #if DEVICE_SERIAL_ASYNCH
30 #include "platform/CThunk.h"
31 #include "hal/dma_api.h"
32 #endif
33 
34 namespace mbed {
35 /**
36  * \defgroup drivers_SerialBase SerialBase class
37  * \ingroup drivers-public-api-uart
38  * @{
39  */
40 
41 /** A base class for serial port implementations
42  * Can't be instantiated directly (use Serial or RawSerial)
43  *
44  * @note Synchronization level: Set by subclass
45  */
46 class SerialBase : private NonCopyable<SerialBase> {
47 
48 public:
49  /** Set the baud rate of the serial port
50  *
51  * @param baudrate The baudrate of the serial port (default = 9600).
52  */
53  void baud(int baudrate);
54 
55  enum Parity {
56  None = 0,
57  Odd,
58  Even,
59  Forced1,
60  Forced0
61  };
62 
63  enum IrqType {
64  RxIrq = 0,
65  TxIrq,
66 
67  IrqCnt
68  };
69 
70  enum Flow {
71  Disabled = 0,
72  RTS,
73  CTS,
74  RTSCTS
75  };
76 
77  /** Set the transmission format used by the serial port
78  *
79  * @param bits The number of bits in a word (5-8; default = 8)
80  * @param parity The parity used (SerialBase::None, SerialBase::Odd, SerialBase::Even, SerialBase::Forced1, SerialBase::Forced0; default = SerialBase::None)
81  * @param stop_bits The number of stop bits (1 or 2; default = 1)
82  */
83  void format(int bits = 8, Parity parity = SerialBase::None, int stop_bits = 1);
84 
85  /** Determine if there is a character available to read
86  *
87  * @returns
88  * 1 if there is a character available to read,
89  * 0 otherwise
90  */
91  int readable();
92 
93  /** Determine if there is space available to write a character
94  *
95  * @returns
96  * 1 if there is space to write a character,
97  * 0 otherwise
98  */
99  int writeable();
100 
101  /** Attach a function to call whenever a serial interrupt is generated
102  *
103  * @param func A pointer to a void function, or 0 to set as none
104  * @param type Which serial interrupt to attach the member function to (Serial::RxIrq for receive, TxIrq for transmit buffer empty)
105  */
106  void attach(Callback<void()> func, IrqType type = RxIrq);
107 
108  /** Attach a member function to call whenever a serial interrupt is generated
109  *
110  * @param obj pointer to the object to call the member function on
111  * @param method pointer to the member function to be called
112  * @param type Which serial interrupt to attach the member function to (Serial::RxIrq for receive, TxIrq for transmit buffer empty)
113  * @deprecated
114  * The attach function does not support cv-qualifiers. Replaced by
115  * attach(callback(obj, method), type).
116  */
117  template<typename T>
118  MBED_DEPRECATED_SINCE("mbed-os-5.1",
119  "The attach function does not support cv-qualifiers. Replaced by "
120  "attach(callback(obj, method), type).")
121  void attach(T *obj, void (T::*method)(), IrqType type = RxIrq)
122  {
123  attach(callback(obj, method), type);
124  }
125 
126  /** Attach a member function to call whenever a serial interrupt is generated
127  *
128  * @param obj pointer to the object to call the member function on
129  * @param method pointer to the member function to be called
130  * @param type Which serial interrupt to attach the member function to (Serial::RxIrq for receive, TxIrq for transmit buffer empty)
131  * @deprecated
132  * The attach function does not support cv-qualifiers. Replaced by
133  * attach(callback(obj, method), type).
134  */
135  template<typename T>
136  MBED_DEPRECATED_SINCE("mbed-os-5.1",
137  "The attach function does not support cv-qualifiers. Replaced by "
138  "attach(callback(obj, method), type).")
139  void attach(T *obj, void (*method)(T *), IrqType type = RxIrq)
140  {
141  attach(callback(obj, method), type);
142  }
143 
144  /** Generate a break condition on the serial line
145  * NOTE: Clear break needs to run at least one frame after set_break is called
146  */
147  void set_break();
148 
149  /** Clear a break condition on the serial line
150  * NOTE: Should be run at least one frame after set_break is called
151  */
152  void clear_break();
153 
154  /** Generate a break condition on the serial line
155  */
156  void send_break();
157 
158  /** Enable serial input
159  *
160  * If both serial input and serial output are disabled, the
161  * peripheral is freed. If either serial input or serial
162  * output is re-enabled, the peripheral is reinitialized.
163  *
164  * On re-initialization rx interrupts will be enabled if a
165  * rx handler is attached. The rx handler is called once
166  * during re-initialization.
167  */
168  void enable_input(bool enable = true);
169 
170  /** Enable serial output
171  *
172  * If both serial input and serial output are disabled, the
173  * peripheral is freed. If either serial input or serial
174  * output is re-enabled, the peripheral is reinitialized.
175  *
176  * On re-initialization tx interrupts will be enabled if a
177  * tx handler is attached. The tx handler is called once
178  * during re-initialization.
179  */
180  void enable_output(bool enable = true);
181 
182 #if !defined(DOXYGEN_ONLY)
183 protected:
184 
185  /** Acquire exclusive access to this serial port
186  */
187  virtual void lock(void);
188 
189  /** Release exclusive access to this serial port
190  */
191  virtual void unlock(void);
192 #endif
193 public:
194 
195 #if DEVICE_SERIAL_FC
196  /** Set the flow control type on the serial port
197  *
198  * @param type the flow control type (Disabled, RTS, CTS, RTSCTS)
199  * @param flow1 the first flow control pin (RTS for RTS or RTSCTS, CTS for CTS)
200  * @param flow2 the second flow control pin (CTS for RTSCTS)
201  */
202  void set_flow_control(Flow type, PinName flow1 = NC, PinName flow2 = NC);
203 
204  /** Set the flow control type on the serial port
205  *
206  * @param type the flow control type (Disabled, RTS, CTS, RTSCTS)
207  * @param pinmap reference to structure which holds static pinmap
208  */
209  void set_flow_control(Flow type, const serial_fc_pinmap_t &static_pinmap);
210 #endif
211 
212  static void _irq_handler(uint32_t id, SerialIrq irq_type);
213 
214 #if DEVICE_SERIAL_ASYNCH
215 
216  /** Begin asynchronous write using 8bit buffer.
217  *
218  * The write operation ends with any of the enabled events and invokes
219  * registered callback function (which can be NULL to not receive callback at all).
220  * Events that are not enabled by event argument are simply ignored.
221  * Operation has to be ended explicitly by calling abort_write() when
222  * no events are enabled.
223  * This function locks the deep sleep until any event has occurred.
224  *
225  * @param buffer The buffer where received data will be stored
226  * @param length The buffer length in bytes
227  * @param callback The event callback function
228  * @param event The logical OR of TX events that should end operation
229  * @return Zero if new transaction was started, -1 if transaction is already on-going
230  */
231  int write(const uint8_t *buffer, int length, const event_callback_t &callback, int event = SERIAL_EVENT_TX_COMPLETE);
232 
233  /** Begin asynchronous write using 16bit buffer.
234  *
235  * The write operation ends with any of the enabled events and invokes
236  * registered callback function (which can be NULL to not receive callback at all).
237  * Events that are not enabled by event argument are simply ignored.
238  * Operation has to be ended explicitly by calling abort_write() when
239  * no events are enabled.
240  * This function locks the deep sleep until any event has occurred.
241  *
242  * @param buffer The buffer where received data will be stored
243  * @param length The buffer length in bytes
244  * @param callback The event callback function
245  * @param event The logical OR of TX events that should end operation
246  * @return Zero if new transaction was started, -1 if transaction is already on-going
247  */
248  int write(const uint16_t *buffer, int length, const event_callback_t &callback, int event = SERIAL_EVENT_TX_COMPLETE);
249 
250  /** Abort the on-going write transfer
251  *
252  * It is safe to call abort_write() when there is no on-going transaction.
253  */
254  void abort_write();
255 
256  /** Begin asynchronous reading using 8bit buffer.
257  *
258  * The read operation ends with any of the enabled events and invokes registered
259  * callback function (which can be NULL to not receive callback at all).
260  * Events that are not enabled by event argument are simply ignored.
261  * Operation has to be ended explicitly by calling abort_read() when
262  * no events are enabled.
263  * This function locks the deep sleep until any event has occurred.
264  *
265  * @param buffer The buffer where received data will be stored
266  * @param length The buffer length in bytes
267  * @param callback The event callback function
268  * @param event The logical OR of RX events that should end operation
269  * @param char_match The matching character
270  * @return Zero if new transaction was started, -1 if transaction is already on-going
271  */
272  int read(uint8_t *buffer, int length, const event_callback_t &callback, int event = SERIAL_EVENT_RX_COMPLETE, unsigned char char_match = SERIAL_RESERVED_CHAR_MATCH);
273 
274  /** Begin asynchronous reading using 16bit buffer.
275  *
276  * The read operation ends with any of the enabled events and invokes registered
277  * callback function (which can be NULL to not receive callback at all).
278  * Events that are not enabled by event argument are simply ignored.
279  * Operation has to be ended explicitly by calling abort_read() when
280  * no events are enabled.
281  * This function locks the deep sleep until any event has occurred.
282  *
283  * @param buffer The buffer where received data will be stored
284  * @param length The buffer length in bytes
285  * @param callback The event callback function
286  * @param event The logical OR of RX events that should end operation
287  * @param char_match The matching character
288  * @return Zero if new transaction was started, -1 if transaction is already on-going
289  */
290  int read(uint16_t *buffer, int length, const event_callback_t &callback, int event = SERIAL_EVENT_RX_COMPLETE, unsigned char char_match = SERIAL_RESERVED_CHAR_MATCH);
291 
292  /** Abort the on-going read transfer
293  *
294  * It is safe to call abort_read() when there is no on-going transaction.
295  */
296  void abort_read();
297 
298  /** Configure DMA usage suggestion for non-blocking TX transfers
299  *
300  * @param usage The usage DMA hint for peripheral
301  * @return Zero if the usage was set, -1 if a transaction is on-going
302  */
303  int set_dma_usage_tx(DMAUsage usage);
304 
305  /** Configure DMA usage suggestion for non-blocking RX transfers
306  *
307  * @param usage The usage DMA hint for peripheral
308  * @return Zero if the usage was set, -1 if a transaction is on-going
309  */
310  int set_dma_usage_rx(DMAUsage usage);
311 
312 #if !defined(DOXYGEN_ONLY)
313 protected:
314  void start_read(void *buffer, int buffer_size, char buffer_width, const event_callback_t &callback, int event, unsigned char char_match);
315  void start_write(const void *buffer, int buffer_size, char buffer_width, const event_callback_t &callback, int event);
316  void interrupt_handler_asynch(void);
317 #endif
318 #endif
319 
320 #if !defined(DOXYGEN_ONLY)
321 protected:
322  SerialBase(PinName tx, PinName rx, int baud);
323  SerialBase(const serial_pinmap_t &static_pinmap, int baud);
324  virtual ~SerialBase();
325 
326  int _base_getc();
327 
328  int _base_putc(int c);
329 
330  /** Initialize serial port
331  */
332  void _init();
333  void _init_direct();
334  /* Pointer to serial init function */
335  void (SerialBase::*_init_func)();
336 
337  /** Deinitialize serial port
338  */
339  void _deinit();
340 
341 #if DEVICE_SERIAL_ASYNCH
342  CThunk<SerialBase> _thunk_irq;
343  DMAUsage _tx_usage = DMA_USAGE_NEVER;
344  DMAUsage _rx_usage = DMA_USAGE_NEVER;
345  event_callback_t _tx_callback;
346  event_callback_t _rx_callback;
347  bool _tx_asynch_set = false;
348  bool _rx_asynch_set = false;
349 #endif
350 
351  serial_t _serial {};
352  Callback<void()> _irq[IrqCnt];
353  int _baud;
354  bool _rx_enabled = true;
355  bool _tx_enabled = true;
356  const PinName _tx_pin;
357  const PinName _rx_pin;
358  const serial_pinmap_t *_static_pinmap = NULL;
359  void (SerialBase::*_set_flow_control_dp_func)(Flow, PinName, PinName) = NULL;
360 
361 #if DEVICE_SERIAL_FC
362  Flow _flow_type = Disabled;
363  PinName _flow1 = NC;
364  PinName _flow2 = NC;
365  const serial_fc_pinmap_t *_static_pinmap_fc = NULL;
366  void (SerialBase::*_set_flow_control_sp_func)(Flow, const serial_fc_pinmap_t &) = NULL;
367 #endif
368 
369 #endif
370 };
371 
372 /** @}*/
373 
374 } // namespace mbed
375 
376 #endif
377 
378 #endif
void send_break()
Generate a break condition on the serial line.
void baud(int baudrate)
Set the baud rate of the serial port.
int write(const uint8_t *buffer, int length, const event_callback_t &callback, int event=SERIAL_EVENT_TX_COMPLETE)
Begin asynchronous write using 8bit buffer.
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:169
int writeable()
Determine if there is space available to write a character.
SerialIrq
Serial interrupt sources.
Definition: serial_api.h:75
A base class for serial port implementations Can&#39;t be instantiated directly (use Serial or RawSerial)...
Definition: SerialBase.h:46
void clear_break()
Clear a break condition on the serial line NOTE: Should be run at least one frame after set_break is ...
void set_flow_control(Flow type, PinName flow1=NC, PinName flow2=NC)
Set the flow control type on the serial port.
int readable()
Determine if there is a character available to read.
int read(uint8_t *buffer, int length, const event_callback_t &callback, int event=SERIAL_EVENT_RX_COMPLETE, unsigned char char_match=SERIAL_RESERVED_CHAR_MATCH)
Begin asynchronous reading using 8bit buffer.
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=0)
Create a callback class with type inferred from the arguments.
Definition: Callback.h:709
void enable_input(bool enable=true)
Enable serial input.
void enable_output(bool enable=true)
Enable serial output.
void attach(Callback< void()> func, IrqType type=RxIrq)
Attach a function to call whenever a serial interrupt is generated.
Asynch serial HAL structure.
Definition: serial_api.h:92
void format(int bits=8, Parity parity=SerialBase::None, int stop_bits=1)
Set the transmission format used by the serial port.
Class for created a pointer with data bound to it.
Definition: CThunk.h:45
void set_break()
Generate a break condition on the serial line NOTE: Clear break needs to run at least one frame after...
void abort_read()
Abort the on-going read transfer.
int set_dma_usage_tx(DMAUsage usage)
Configure DMA usage suggestion for non-blocking TX transfers.
Callback class based on template specialization.
Definition: Callback.h:39
int set_dma_usage_rx(DMAUsage usage)
Configure DMA usage suggestion for non-blocking RX transfers.
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
void abort_write()
Abort the on-going write transfer.
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.