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 UnbufferedSerial or BufferedSerial)
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  /** Generate a break condition on the serial line
109  * NOTE: Clear break needs to run at least one frame after set_break is called
110  */
111  void set_break();
112 
113  /** Clear a break condition on the serial line
114  * NOTE: Should be run at least one frame after set_break is called
115  */
116  void clear_break();
117 
118  /** Generate a break condition on the serial line
119  */
120  void send_break();
121 
122  /** Enable serial input
123  *
124  * If both serial input and serial output are disabled, the
125  * peripheral is freed. If either serial input or serial
126  * output is re-enabled, the peripheral is reinitialized.
127  *
128  * On re-initialization rx interrupts will be enabled if a
129  * rx handler is attached. The rx handler is called once
130  * during re-initialization.
131  */
132  void enable_input(bool enable = true);
133 
134  /** Enable serial output
135  *
136  * If both serial input and serial output are disabled, the
137  * peripheral is freed. If either serial input or serial
138  * output is re-enabled, the peripheral is reinitialized.
139  *
140  * On re-initialization tx interrupts will be enabled if a
141  * tx handler is attached. The tx handler is called once
142  * during re-initialization.
143  */
144  void enable_output(bool enable = true);
145 
146 #if !defined(DOXYGEN_ONLY)
147 protected:
148 
149  /** Acquire exclusive access to this serial port
150  */
151  virtual void lock(void);
152 
153  /** Release exclusive access to this serial port
154  */
155  virtual void unlock(void);
156 #endif
157 public:
158 
159 #if DEVICE_SERIAL_FC
160  /** Set the flow control type on the serial port
161  *
162  * @param type the flow control type (Disabled, RTS, CTS, RTSCTS)
163  * @param flow1 the first flow control pin (RTS for RTS or RTSCTS, CTS for CTS)
164  * @param flow2 the second flow control pin (CTS for RTSCTS)
165  */
166  void set_flow_control(Flow type, PinName flow1 = NC, PinName flow2 = NC);
167 
168  /** Set the flow control type on the serial port
169  *
170  * @param type the flow control type (Disabled, RTS, CTS, RTSCTS)
171  * @param pinmap reference to structure which holds static pinmap
172  */
173  void set_flow_control(Flow type, const serial_fc_pinmap_t &static_pinmap);
174 #endif
175 
176  static void _irq_handler(uint32_t id, SerialIrq irq_type);
177 
178 #if DEVICE_SERIAL_ASYNCH
179 
180  /** Begin asynchronous write using 8bit buffer.
181  *
182  * The write operation ends with any of the enabled events and invokes
183  * registered callback function (which can be empty to not receive callback at all).
184  * Events that are not enabled by event argument are simply ignored.
185  * Operation has to be ended explicitly by calling abort_write() when
186  * no events are enabled.
187  * This function locks the deep sleep until any event has occurred.
188  *
189  * @param buffer The buffer where received data will be stored
190  * @param length The buffer length in bytes
191  * @param callback The event callback function
192  * @param event The logical OR of TX events that should end operation
193  * @return Zero if new transaction was started, -1 if transaction is already on-going
194  */
195  int write(const uint8_t *buffer, int length, const event_callback_t &callback, int event = SERIAL_EVENT_TX_COMPLETE);
196 
197  /** Begin asynchronous write using 16bit buffer.
198  *
199  * The write operation ends with any of the enabled events and invokes
200  * registered callback function (which can be empty to not receive callback at all).
201  * Events that are not enabled by event argument are simply ignored.
202  * Operation has to be ended explicitly by calling abort_write() when
203  * no events are enabled.
204  * This function locks the deep sleep until any event has occurred.
205  *
206  * @param buffer The buffer where received data will be stored
207  * @param length The buffer length in bytes
208  * @param callback The event callback function
209  * @param event The logical OR of TX events that should end operation
210  * @return Zero if new transaction was started, -1 if transaction is already on-going
211  */
212  int write(const uint16_t *buffer, int length, const event_callback_t &callback, int event = SERIAL_EVENT_TX_COMPLETE);
213 
214  /** Abort the on-going write transfer
215  *
216  * It is safe to call abort_write() when there is no on-going transaction.
217  */
218  void abort_write();
219 
220  /** Begin asynchronous reading using 8bit buffer.
221  *
222  * The read operation ends with any of the enabled events and invokes registered
223  * callback function (which can be empty to not receive callback at all).
224  * Events that are not enabled by event argument are simply ignored.
225  * Operation has to be ended explicitly by calling abort_read() when
226  * no events are enabled.
227  * This function locks the deep sleep until any event has occurred.
228  *
229  * @param buffer The buffer where received data will be stored
230  * @param length The buffer length in bytes
231  * @param callback The event callback function
232  * @param event The logical OR of RX events that should end operation
233  * @param char_match The matching character
234  * @return Zero if new transaction was started, -1 if transaction is already on-going
235  */
236  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);
237 
238  /** Begin asynchronous reading using 16bit buffer.
239  *
240  * The read operation ends with any of the enabled events and invokes registered
241  * callback function (which can be empty to not receive callback at all).
242  * Events that are not enabled by event argument are simply ignored.
243  * Operation has to be ended explicitly by calling abort_read() when
244  * no events are enabled.
245  * This function locks the deep sleep until any event has occurred.
246  *
247  * @param buffer The buffer where received data will be stored
248  * @param length The buffer length in bytes
249  * @param callback The event callback function
250  * @param event The logical OR of RX events that should end operation
251  * @param char_match The matching character
252  * @return Zero if new transaction was started, -1 if transaction is already on-going
253  */
254  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);
255 
256  /** Abort the on-going read transfer
257  *
258  * It is safe to call abort_read() when there is no on-going transaction.
259  */
260  void abort_read();
261 
262  /** Configure DMA usage suggestion for non-blocking TX transfers
263  *
264  * @param usage The usage DMA hint for peripheral
265  * @return Zero if the usage was set, -1 if a transaction is on-going
266  */
267  int set_dma_usage_tx(DMAUsage usage);
268 
269  /** Configure DMA usage suggestion for non-blocking RX transfers
270  *
271  * @param usage The usage DMA hint for peripheral
272  * @return Zero if the usage was set, -1 if a transaction is on-going
273  */
274  int set_dma_usage_rx(DMAUsage usage);
275 
276 #if !defined(DOXYGEN_ONLY)
277 protected:
278  void start_read(void *buffer, int buffer_size, char buffer_width, const event_callback_t &callback, int event, unsigned char char_match);
279  void start_write(const void *buffer, int buffer_size, char buffer_width, const event_callback_t &callback, int event);
280  void interrupt_handler_asynch(void);
281 #endif
282 #endif
283 
284 #if !defined(DOXYGEN_ONLY)
285 protected:
286  SerialBase(PinName tx, PinName rx, int baud);
287  SerialBase(const serial_pinmap_t &static_pinmap, int baud);
288  virtual ~SerialBase();
289 
290  int _base_getc();
291 
292  int _base_putc(int c);
293 
294  /** Initialize serial port
295  */
296  void _init();
297  void _init_direct();
298  /* Pointer to serial init function */
299  void (SerialBase::*_init_func)();
300 
301  /** Deinitialize serial port
302  */
303  void _deinit();
304 
305 #if DEVICE_SERIAL_ASYNCH
306  CThunk<SerialBase> _thunk_irq;
307  DMAUsage _tx_usage = DMA_USAGE_NEVER;
308  DMAUsage _rx_usage = DMA_USAGE_NEVER;
309  event_callback_t _tx_callback;
310  event_callback_t _rx_callback;
311  bool _tx_asynch_set = false;
312  bool _rx_asynch_set = false;
313 #endif
314 
315  serial_t _serial {};
316  Callback<void()> _irq[IrqCnt];
317  int _baud;
318  bool _rx_enabled = true;
319  bool _tx_enabled = true;
320  const PinName _tx_pin;
321  const PinName _rx_pin;
322  const serial_pinmap_t *_static_pinmap = NULL;
323  void (SerialBase::*_set_flow_control_dp_func)(Flow, PinName, PinName) = NULL;
324 
325 #if DEVICE_SERIAL_FC
326  Flow _flow_type = Disabled;
327  PinName _flow1 = NC;
328  PinName _flow2 = NC;
329  const serial_fc_pinmap_t *_static_pinmap_fc = NULL;
330  void (SerialBase::*_set_flow_control_sp_func)(Flow, const serial_fc_pinmap_t &) = NULL;
331 #endif
332 
333 #endif
334 };
335 
336 /** @}*/
337 
338 } // namespace mbed
339 
340 #endif
341 
342 #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:162
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
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 UnbufferedSerial or ...
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.
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:53
Definition: ATHandler.h:46
int set_dma_usage_rx(DMAUsage usage)
Configure DMA usage suggestion for non-blocking RX transfers.
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.