Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
SerialBase.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2013 ARM Limited 00003 * SPDX-License-Identifier: Apache-2.0 00004 * 00005 * Licensed under the Apache License, Version 2.0 (the "License"); 00006 * you may not use this file except in compliance with the License. 00007 * You may obtain a copy of the License at 00008 * 00009 * http://www.apache.org/licenses/LICENSE-2.0 00010 * 00011 * Unless required by applicable law or agreed to in writing, software 00012 * distributed under the License is distributed on an "AS IS" BASIS, 00013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00014 * See the License for the specific language governing permissions and 00015 * limitations under the License. 00016 */ 00017 #ifndef MBED_SERIALBASE_H 00018 #define MBED_SERIALBASE_H 00019 00020 #include "platform/platform.h" 00021 00022 #if DEVICE_SERIAL || defined(DOXYGEN_ONLY) 00023 00024 #include "platform/Callback.h" 00025 #include "hal/serial_api.h" 00026 #include "platform/mbed_toolchain.h" 00027 #include "platform/NonCopyable.h" 00028 00029 #if DEVICE_SERIAL_ASYNCH 00030 #include "platform/CThunk.h" 00031 #include "hal/dma_api.h" 00032 #endif 00033 00034 namespace mbed { 00035 /** 00036 * \defgroup drivers_SerialBase SerialBase class 00037 * \ingroup drivers-public-api-uart 00038 * @{ 00039 */ 00040 00041 /** A base class for serial port implementations 00042 * Can't be instantiated directly (use UnbufferedSerial or UARTSerial) 00043 * 00044 * @note Synchronization level: Set by subclass 00045 */ 00046 class SerialBase : private NonCopyable<SerialBase> { 00047 00048 public: 00049 /** Set the baud rate of the serial port 00050 * 00051 * @param baudrate The baudrate of the serial port (default = 9600). 00052 */ 00053 void baud(int baudrate); 00054 00055 enum Parity { 00056 None = 0, 00057 Odd, 00058 Even, 00059 Forced1, 00060 Forced0 00061 }; 00062 00063 enum IrqType { 00064 RxIrq = 0, 00065 TxIrq, 00066 00067 IrqCnt 00068 }; 00069 00070 enum Flow { 00071 Disabled = 0, 00072 RTS, 00073 CTS, 00074 RTSCTS 00075 }; 00076 00077 /** Set the transmission format used by the serial port 00078 * 00079 * @param bits The number of bits in a word (5-8; default = 8) 00080 * @param parity The parity used (SerialBase::None, SerialBase::Odd, SerialBase::Even, SerialBase::Forced1, SerialBase::Forced0; default = SerialBase::None) 00081 * @param stop_bits The number of stop bits (1 or 2; default = 1) 00082 */ 00083 void format(int bits = 8, Parity parity = SerialBase::None, int stop_bits = 1); 00084 00085 /** Determine if there is a character available to read 00086 * 00087 * @returns 00088 * 1 if there is a character available to read, 00089 * 0 otherwise 00090 */ 00091 int readable(); 00092 00093 /** Determine if there is space available to write a character 00094 * 00095 * @returns 00096 * 1 if there is space to write a character, 00097 * 0 otherwise 00098 */ 00099 int writeable(); 00100 00101 /** Attach a function to call whenever a serial interrupt is generated 00102 * 00103 * @param func A pointer to a void function, or 0 to set as none 00104 * @param type Which serial interrupt to attach the member function to (Serial::RxIrq for receive, TxIrq for transmit buffer empty) 00105 */ 00106 void attach(Callback<void()> func, IrqType type = RxIrq); 00107 00108 /** Attach a member function to call whenever a serial interrupt is generated 00109 * 00110 * @param obj pointer to the object to call the member function on 00111 * @param method pointer to the member function to be called 00112 * @param type Which serial interrupt to attach the member function to (Serial::RxIrq for receive, TxIrq for transmit buffer empty) 00113 * @deprecated 00114 * The attach function does not support cv-qualifiers. Replaced by 00115 * attach(callback(obj, method), type). 00116 */ 00117 template<typename T> 00118 MBED_DEPRECATED_SINCE("mbed-os-5.1", 00119 "The attach function does not support cv-qualifiers. Replaced by " 00120 "attach(callback(obj, method), type).") 00121 void attach(T *obj, void (T::*method)(), IrqType type = RxIrq) 00122 { 00123 attach(callback(obj, method), type); 00124 } 00125 00126 /** Attach a member function to call whenever a serial interrupt is generated 00127 * 00128 * @param obj pointer to the object to call the member function on 00129 * @param method pointer to the member function to be called 00130 * @param type Which serial interrupt to attach the member function to (Serial::RxIrq for receive, TxIrq for transmit buffer empty) 00131 * @deprecated 00132 * The attach function does not support cv-qualifiers. Replaced by 00133 * attach(callback(obj, method), type). 00134 */ 00135 template<typename T> 00136 MBED_DEPRECATED_SINCE("mbed-os-5.1", 00137 "The attach function does not support cv-qualifiers. Replaced by " 00138 "attach(callback(obj, method), type).") 00139 void attach(T *obj, void (*method)(T *), IrqType type = RxIrq) 00140 { 00141 attach(callback(obj, method), type); 00142 } 00143 00144 /** Generate a break condition on the serial line 00145 * NOTE: Clear break needs to run at least one frame after set_break is called 00146 */ 00147 void set_break(); 00148 00149 /** Clear a break condition on the serial line 00150 * NOTE: Should be run at least one frame after set_break is called 00151 */ 00152 void clear_break(); 00153 00154 /** Generate a break condition on the serial line 00155 */ 00156 void send_break(); 00157 00158 /** Enable serial input 00159 * 00160 * If both serial input and serial output are disabled, the 00161 * peripheral is freed. If either serial input or serial 00162 * output is re-enabled, the peripheral is reinitialized. 00163 * 00164 * On re-initialization rx interrupts will be enabled if a 00165 * rx handler is attached. The rx handler is called once 00166 * during re-initialization. 00167 */ 00168 void enable_input(bool enable = true); 00169 00170 /** Enable serial output 00171 * 00172 * If both serial input and serial output are disabled, the 00173 * peripheral is freed. If either serial input or serial 00174 * output is re-enabled, the peripheral is reinitialized. 00175 * 00176 * On re-initialization tx interrupts will be enabled if a 00177 * tx handler is attached. The tx handler is called once 00178 * during re-initialization. 00179 */ 00180 void enable_output(bool enable = true); 00181 00182 #if !defined(DOXYGEN_ONLY) 00183 protected: 00184 00185 /** Acquire exclusive access to this serial port 00186 */ 00187 virtual void lock(void); 00188 00189 /** Release exclusive access to this serial port 00190 */ 00191 virtual void unlock(void); 00192 #endif 00193 public: 00194 00195 #if DEVICE_SERIAL_FC 00196 /** Set the flow control type on the serial port 00197 * 00198 * @param type the flow control type (Disabled, RTS, CTS, RTSCTS) 00199 * @param flow1 the first flow control pin (RTS for RTS or RTSCTS, CTS for CTS) 00200 * @param flow2 the second flow control pin (CTS for RTSCTS) 00201 */ 00202 void set_flow_control(Flow type, PinName flow1 = NC, PinName flow2 = NC); 00203 00204 /** Set the flow control type on the serial port 00205 * 00206 * @param type the flow control type (Disabled, RTS, CTS, RTSCTS) 00207 * @param pinmap reference to structure which holds static pinmap 00208 */ 00209 void set_flow_control(Flow type, const serial_fc_pinmap_t &static_pinmap); 00210 #endif 00211 00212 static void _irq_handler(uint32_t id, SerialIrq irq_type); 00213 00214 #if DEVICE_SERIAL_ASYNCH 00215 00216 /** Begin asynchronous write using 8bit buffer. 00217 * 00218 * The write operation ends with any of the enabled events and invokes 00219 * registered callback function (which can be NULL to not receive callback at all). 00220 * Events that are not enabled by event argument are simply ignored. 00221 * Operation has to be ended explicitly by calling abort_write() when 00222 * no events are enabled. 00223 * This function locks the deep sleep until any event has occurred. 00224 * 00225 * @param buffer The buffer where received data will be stored 00226 * @param length The buffer length in bytes 00227 * @param callback The event callback function 00228 * @param event The logical OR of TX events that should end operation 00229 * @return Zero if new transaction was started, -1 if transaction is already on-going 00230 */ 00231 int write(const uint8_t *buffer, int length, const event_callback_t &callback, int event = SERIAL_EVENT_TX_COMPLETE); 00232 00233 /** Begin asynchronous write using 16bit buffer. 00234 * 00235 * The write operation ends with any of the enabled events and invokes 00236 * registered callback function (which can be NULL to not receive callback at all). 00237 * Events that are not enabled by event argument are simply ignored. 00238 * Operation has to be ended explicitly by calling abort_write() when 00239 * no events are enabled. 00240 * This function locks the deep sleep until any event has occurred. 00241 * 00242 * @param buffer The buffer where received data will be stored 00243 * @param length The buffer length in bytes 00244 * @param callback The event callback function 00245 * @param event The logical OR of TX events that should end operation 00246 * @return Zero if new transaction was started, -1 if transaction is already on-going 00247 */ 00248 int write(const uint16_t *buffer, int length, const event_callback_t &callback, int event = SERIAL_EVENT_TX_COMPLETE); 00249 00250 /** Abort the on-going write transfer 00251 * 00252 * It is safe to call abort_write() when there is no on-going transaction. 00253 */ 00254 void abort_write(); 00255 00256 /** Begin asynchronous reading using 8bit buffer. 00257 * 00258 * The read operation ends with any of the enabled events and invokes registered 00259 * callback function (which can be NULL to not receive callback at all). 00260 * Events that are not enabled by event argument are simply ignored. 00261 * Operation has to be ended explicitly by calling abort_read() when 00262 * no events are enabled. 00263 * This function locks the deep sleep until any event has occurred. 00264 * 00265 * @param buffer The buffer where received data will be stored 00266 * @param length The buffer length in bytes 00267 * @param callback The event callback function 00268 * @param event The logical OR of RX events that should end operation 00269 * @param char_match The matching character 00270 * @return Zero if new transaction was started, -1 if transaction is already on-going 00271 */ 00272 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); 00273 00274 /** Begin asynchronous reading using 16bit buffer. 00275 * 00276 * The read operation ends with any of the enabled events and invokes registered 00277 * callback function (which can be NULL to not receive callback at all). 00278 * Events that are not enabled by event argument are simply ignored. 00279 * Operation has to be ended explicitly by calling abort_read() when 00280 * no events are enabled. 00281 * This function locks the deep sleep until any event has occurred. 00282 * 00283 * @param buffer The buffer where received data will be stored 00284 * @param length The buffer length in bytes 00285 * @param callback The event callback function 00286 * @param event The logical OR of RX events that should end operation 00287 * @param char_match The matching character 00288 * @return Zero if new transaction was started, -1 if transaction is already on-going 00289 */ 00290 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); 00291 00292 /** Abort the on-going read transfer 00293 * 00294 * It is safe to call abort_read() when there is no on-going transaction. 00295 */ 00296 void abort_read(); 00297 00298 /** Configure DMA usage suggestion for non-blocking TX transfers 00299 * 00300 * @param usage The usage DMA hint for peripheral 00301 * @return Zero if the usage was set, -1 if a transaction is on-going 00302 */ 00303 int set_dma_usage_tx(DMAUsage usage); 00304 00305 /** Configure DMA usage suggestion for non-blocking RX transfers 00306 * 00307 * @param usage The usage DMA hint for peripheral 00308 * @return Zero if the usage was set, -1 if a transaction is on-going 00309 */ 00310 int set_dma_usage_rx(DMAUsage usage); 00311 00312 #if !defined(DOXYGEN_ONLY) 00313 protected: 00314 void start_read(void *buffer, int buffer_size, char buffer_width, const event_callback_t &callback, int event, unsigned char char_match); 00315 void start_write(const void *buffer, int buffer_size, char buffer_width, const event_callback_t &callback, int event); 00316 void interrupt_handler_asynch(void); 00317 #endif 00318 #endif 00319 00320 #if !defined(DOXYGEN_ONLY) 00321 protected: 00322 SerialBase(PinName tx, PinName rx, int baud); 00323 SerialBase(const serial_pinmap_t &static_pinmap, int baud); 00324 virtual ~SerialBase(); 00325 00326 int _base_getc(); 00327 00328 int _base_putc(int c); 00329 00330 /** Initialize serial port 00331 */ 00332 void _init(); 00333 void _init_direct(); 00334 /* Pointer to serial init function */ 00335 void (SerialBase::*_init_func)(); 00336 00337 /** Deinitialize serial port 00338 */ 00339 void _deinit(); 00340 00341 #if DEVICE_SERIAL_ASYNCH 00342 CThunk<SerialBase> _thunk_irq; 00343 DMAUsage _tx_usage = DMA_USAGE_NEVER; 00344 DMAUsage _rx_usage = DMA_USAGE_NEVER; 00345 event_callback_t _tx_callback; 00346 event_callback_t _rx_callback; 00347 bool _tx_asynch_set = false; 00348 bool _rx_asynch_set = false; 00349 #endif 00350 00351 serial_t _serial {}; 00352 Callback<void()> _irq[IrqCnt]; 00353 int _baud; 00354 bool _rx_enabled = true; 00355 bool _tx_enabled = true; 00356 const PinName _tx_pin; 00357 const PinName _rx_pin; 00358 const serial_pinmap_t *_static_pinmap = NULL; 00359 void (SerialBase::*_set_flow_control_dp_func)(Flow, PinName, PinName) = NULL; 00360 00361 #if DEVICE_SERIAL_FC 00362 Flow _flow_type = Disabled; 00363 PinName _flow1 = NC; 00364 PinName _flow2 = NC; 00365 const serial_fc_pinmap_t *_static_pinmap_fc = NULL; 00366 void (SerialBase::*_set_flow_control_sp_func)(Flow, const serial_fc_pinmap_t &) = NULL; 00367 #endif 00368 00369 #endif 00370 }; 00371 00372 /** @}*/ 00373 00374 } // namespace mbed 00375 00376 #endif 00377 00378 #endif
Generated on Tue Jul 12 2022 13:54:49 by
