UARTSerial.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2019 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 
00018 #ifndef MBED_UARTSERIAL_H
00019 #define MBED_UARTSERIAL_H
00020 
00021 #include "platform/platform.h"
00022 
00023 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
00024 
00025 #include "platform/FileHandle.h"
00026 #include "drivers/SerialBase.h"
00027 #include "drivers/InterruptIn.h"
00028 #include "platform/PlatformMutex.h"
00029 #include "platform/CircularBuffer.h"
00030 #include "platform/NonCopyable.h"
00031 
00032 #ifndef MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE
00033 #define MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE  256
00034 #endif
00035 
00036 #ifndef MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE
00037 #define MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE  256
00038 #endif
00039 
00040 namespace mbed {
00041 /**
00042  * \defgroup drivers_UARTSerial UARTSerial class
00043  * \ingroup drivers-public-api-uart
00044  * @{
00045  */
00046 
00047 /** Class providing buffered UART communication functionality using separate circular buffer for send and receive channels
00048  *
00049  */
00050 
00051 class UARTSerial : private SerialBase, public FileHandle, private NonCopyable<UARTSerial> {
00052 
00053 public:
00054 
00055     /** Create a UARTSerial port, connected to the specified transmit and receive pins, with a particular baud rate.
00056      *  @param tx Transmit pin
00057      *  @param rx Receive pin
00058      *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
00059      */
00060     UARTSerial(PinName tx, PinName rx, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
00061 
00062     /** Create a UARTSerial port, connected to the specified transmit and receive pins, with a particular baud rate.
00063      *  @param static_pinmap reference to structure which holds static pinmap
00064      *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
00065      */
00066     UARTSerial(const serial_pinmap_t &static_pinmap, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
00067 
00068     virtual ~UARTSerial();
00069 
00070     /** Equivalent to POSIX poll(). Derived from FileHandle.
00071      *  Provides a mechanism to multiplex input/output over a set of file handles.
00072      */
00073     virtual short poll(short events) const;
00074 
00075     /* Resolve ambiguities versus our private SerialBase
00076      * (for writable, spelling differs, but just in case)
00077      */
00078     using FileHandle::readable;
00079     using FileHandle::writable;
00080 
00081     /** Write the contents of a buffer to a file
00082      *
00083      *  Follows POSIX semantics:
00084      *
00085      * * if blocking, block until all data is written
00086      * * if no data can be written, and non-blocking set, return -EAGAIN
00087      * * if some data can be written, and non-blocking set, write partial
00088      *
00089      *  @param buffer   The buffer to write from
00090      *  @param length   The number of bytes to write
00091      *  @return         The number of bytes written, negative error on failure
00092      */
00093     virtual ssize_t write(const void *buffer, size_t length);
00094 
00095     /** Read the contents of a file into a buffer
00096      *
00097      *  Follows POSIX semantics:
00098      *
00099      *  * if no data is available, and non-blocking set return -EAGAIN
00100      *  * if no data is available, and blocking set, wait until data is available
00101      *  * If any data is available, call returns immediately
00102      *
00103      *  @param buffer   The buffer to read in to
00104      *  @param length   The number of bytes to read
00105      *  @return         The number of bytes read, 0 at end of file, negative error on failure
00106      */
00107     virtual ssize_t read(void *buffer, size_t length);
00108 
00109     /** Close a file
00110      *
00111      *  @return         0 on success, negative error code on failure
00112      */
00113     virtual int close();
00114 
00115     /** Check if the file in an interactive terminal device
00116      *
00117      *  @return         True if the file is a terminal
00118      *  @return         False if the file is not a terminal
00119      *  @return         Negative error code on failure
00120      */
00121     virtual int isatty();
00122 
00123     /** Move the file position to a given offset from from a given location
00124      *
00125      * Not valid for a device type FileHandle like UARTSerial.
00126      * In case of UARTSerial, returns ESPIPE
00127      *
00128      *  @param offset   The offset from whence to move to
00129      *  @param whence   The start of where to seek
00130      *      SEEK_SET to start from beginning of file,
00131      *      SEEK_CUR to start from current position in file,
00132      *      SEEK_END to start from end of file
00133      *  @return         The new offset of the file, negative error code on failure
00134      */
00135     virtual off_t seek(off_t offset, int whence);
00136 
00137     /** Flush any buffers associated with the file
00138      *
00139      *  @return         0 on success, negative error code on failure
00140      */
00141     virtual int sync();
00142 
00143     /** Set blocking or non-blocking mode
00144      *  The default is blocking.
00145      *
00146      *  @param blocking true for blocking mode, false for non-blocking mode.
00147      */
00148     virtual int set_blocking(bool blocking)
00149     {
00150         _blocking = blocking;
00151         return 0;
00152     }
00153 
00154     /** Check current blocking or non-blocking mode for file operations.
00155      *
00156      *  @return             true for blocking mode, false for non-blocking mode.
00157      */
00158     virtual bool is_blocking() const
00159     {
00160         return _blocking;
00161     }
00162 
00163     /** Enable or disable input
00164      *
00165      * Control enabling of device for input. This is primarily intended
00166      * for temporary power-saving; the overall ability of the device to operate for
00167      * input and/or output may be fixed at creation time, but this call can
00168      * allow input to be temporarily disabled to permit power saving without
00169      * losing device state.
00170      *
00171      *  @param enabled      true to enable input, false to disable.
00172      *
00173      *  @return             0 on success
00174      *  @return             Negative error code on failure
00175      */
00176     virtual int enable_input(bool enabled);
00177 
00178     /** Enable or disable output
00179      *
00180      * Control enabling of device for output. This is primarily intended
00181      * for temporary power-saving; the overall ability of the device to operate for
00182      * input and/or output may be fixed at creation time, but this call can
00183      * allow output to be temporarily disabled to permit power saving without
00184      * losing device state.
00185      *
00186      *  @param enabled      true to enable output, false to disable.
00187      *
00188      *  @return             0 on success
00189      *  @return             Negative error code on failure
00190      */
00191     virtual int enable_output(bool enabled);
00192 
00193     /** Register a callback on state change of the file.
00194      *
00195      *  The specified callback will be called on state changes such as when
00196      *  the file can be written to or read from.
00197      *
00198      *  The callback may be called in an interrupt context and should not
00199      *  perform expensive operations.
00200      *
00201      *  Note! This is not intended as an attach-like asynchronous api, but rather
00202      *  as a building block for constructing  such functionality.
00203      *
00204      *  The exact timing of when the registered function
00205      *  is called is not guaranteed and susceptible to change. It should be used
00206      *  as a cue to make read/write/poll calls to find the current state.
00207      *
00208      *  @param func     Function to call on state change
00209      */
00210     virtual void sigio(Callback<void()> func);
00211 
00212     /** Setup interrupt handler for DCD line
00213      *
00214      *  If DCD line is connected, an IRQ handler will be setup.
00215      *  Does nothing if DCD is NC, i.e., not connected.
00216      *
00217      *  @param dcd_pin         Pin-name for DCD
00218      *  @param active_high     a boolean set to true if DCD polarity is active low
00219      */
00220     void set_data_carrier_detect(PinName dcd_pin, bool active_high = false);
00221 
00222     /** Set the baud rate
00223      *
00224      *  @param baud   The baud rate
00225      */
00226     void set_baud(int baud);
00227 
00228     // Expose private SerialBase::Parity as UARTSerial::Parity
00229     using SerialBase::Parity;
00230     // In C++11, we wouldn't need to also have using directives for each value
00231     using SerialBase::None;
00232     using SerialBase::Odd;
00233     using SerialBase::Even;
00234     using SerialBase::Forced1;
00235     using SerialBase::Forced0;
00236 
00237     /** Set the transmission format used by the serial port
00238      *
00239      *  @param bits The number of bits in a word (5-8; default = 8)
00240      *  @param parity The parity used (None, Odd, Even, Forced1, Forced0; default = None)
00241      *  @param stop_bits The number of stop bits (1 or 2; default = 1)
00242      */
00243     void set_format(int bits = 8, Parity parity = UARTSerial::None, int stop_bits = 1);
00244 
00245 #if DEVICE_SERIAL_FC
00246     // For now use the base enum - but in future we may have extra options
00247     // such as XON/XOFF or manual GPIO RTSCTS.
00248     using SerialBase::Flow;
00249     // In C++11, we wouldn't need to also have using directives for each value
00250     using SerialBase::Disabled;
00251     using SerialBase::RTS;
00252     using SerialBase::CTS;
00253     using SerialBase::RTSCTS;
00254 
00255     /** Set the flow control type on the serial port
00256      *
00257      *  @param type the flow control type (Disabled, RTS, CTS, RTSCTS)
00258      *  @param flow1 the first flow control pin (RTS for RTS or RTSCTS, CTS for CTS)
00259      *  @param flow2 the second flow control pin (CTS for RTSCTS)
00260      */
00261     void set_flow_control(Flow type, PinName flow1 = NC, PinName flow2 = NC);
00262 #endif
00263 
00264 private:
00265 
00266     /** SerialBase lock override */
00267     virtual void lock(void);
00268 
00269     /** SerialBase unlock override */
00270     virtual void unlock(void);
00271 
00272     /** Acquire mutex */
00273     virtual void api_lock(void);
00274 
00275     /** Release mutex */
00276     virtual void api_unlock(void);
00277 
00278     /** Unbuffered write - invoked when write called from critical section */
00279     ssize_t write_unbuffered(const char *buf_ptr, size_t length);
00280 
00281     void enable_rx_irq();
00282     void disable_rx_irq();
00283     void enable_tx_irq();
00284     void disable_tx_irq();
00285 
00286     /** Software serial buffers
00287      *  By default buffer size is 256 for TX and 256 for RX. Configurable through mbed_app.json
00288      */
00289     CircularBuffer<char, MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE>  _rxbuf;
00290     CircularBuffer<char, MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE>  _txbuf;
00291 
00292     PlatformMutex _mutex;
00293 
00294     Callback<void()> _sigio_cb;
00295 
00296     bool _blocking;
00297     bool _tx_irq_enabled;
00298     bool _rx_irq_enabled;
00299     bool _tx_enabled;
00300     bool _rx_enabled;
00301     InterruptIn *_dcd_irq;
00302 
00303     /** Device Hanged up
00304      *  Determines if the device hanged up on us.
00305      *
00306      *  @return True, if hanged up
00307      */
00308     bool hup() const;
00309 
00310     /** ISRs for serial
00311      *  Routines to handle interrupts on serial pins.
00312      *  Copies data into Circular Buffer.
00313      *  Reports the state change to File handle.
00314      */
00315     void tx_irq(void);
00316     void rx_irq(void);
00317 
00318     void wake(void);
00319 
00320     void dcd_irq(void);
00321 
00322 };
00323 
00324 /** @}*/
00325 
00326 } //namespace mbed
00327 
00328 #endif //(DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
00329 #endif //MBED_UARTSERIAL_H