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