Major Refactoring & extensions

For keep supporting external APIs with the same name (supposedly there are a larger
number of users of those APIs), BufferedSerial and ATParser are being renamed.
BufferedSerial becomes UARTSerial, will complement a  future USBSerial etc.
ATParser becomes ATCmdParser.

* UARTSerial moves to /drivers

* APN_db.h is moved from platform to cellular/util/.

* Original CellularInterface is restored for backward compatability (again, supposedly there
  are users of that).

* A new file, CellularBase is added which will now servce as the base class for all
  upcoming drivers.

* Special restructuring for the driver has been undertaken. This makes a clear cut distinction
  between an on-board or an off-board implementation.
  	- PPPCellularInterface is a generic network interface that works with a generic FileHandle
          and PPP. A derived class is needed to pass that FileHandle.
        - PPPCellularInterface provides some base functionality like network registration, AT setup,
          PPP connection etc. Lower level job is delegated to the derived classes and various modem
          specific APIs are provided which are supposed to be overridden.
        - UARTCellularInterface is derived from PPPCellularInterface. It constructs a FileHandle and
          passes it back to PPPCellularInterface as well as provides modem hangupf functionality.
          In future we could proive a USBInterface that would derive from PPPCellularInterface and could
          pass the FileHandle back.
	- OnboardCellularInterface is derived from UARTCellularInterfae and provides hooks to
          the target provided implementation of onbard_modem_api.h. An off-board modem, i.e, a modem on
          a shield has to override the modem_init(), modem_power_up() etc as it cannot use
          onboard_modem_api.h.

Author: Hasnain Virk

platform/BufferedSerial.cpp renamed to drivers/UARTSerial.cpp

@@ -17,68 +17,68 @@
 #if DEVICE_SERIAL
 
 #include <errno.h>
-#include "platform/BufferedSerial.h"
+#include "UARTSerial.h"
 #include "platform/mbed_poll.h"
 #include "platform/mbed_wait_api.h"
 
 namespace mbed {
 
-BufferedSerial::BufferedSerial(PinName tx, PinName rx, int baud) :
+UARTSerial::UARTSerial(PinName tx, PinName rx, int baud) :
         SerialBase(tx, rx, baud),
         _blocking(true),
         _tx_irq_enabled(false),
-        _dcd(NULL)
+        _dcd_irq(NULL)
 {
     /* Attatch IRQ routines to the serial device. */
-    SerialBase::attach(callback(this, &BufferedSerial::rx_irq), RxIrq);
+    SerialBase::attach(callback(this, &UARTSerial::rx_irq), RxIrq);
 }
 
-BufferedSerial::~BufferedSerial()
+UARTSerial::~UARTSerial()
 {
-    delete _dcd;
+    delete _dcd_irq;
 }
 
-void BufferedSerial::DCD_IRQ()
+void UARTSerial::dcd_irq()
 {
     wake();
 }
 
-void BufferedSerial::set_data_carrier_detect(PinName DCD_pin, bool active_high)
+void UARTSerial::set_data_carrier_detect(PinName dcd_pin, bool active_high)
 {
-    delete _dcd;
-    _dcd = NULL;
+     delete _dcd_irq;
+    _dcd_irq = NULL;
 
-    if (DCD_pin != NC) {
-        _dcd = new InterruptIn(DCD_pin);
+    if (dcd_pin != NC) {
+        _dcd_irq = new InterruptIn(dcd_pin);
         if (active_high) {
-            _dcd->fall(callback(this, &BufferedSerial::DCD_IRQ));
+            _dcd_irq->fall(callback(this, &UARTSerial::dcd_irq));
         } else {
-            _dcd->rise(callback(this, &BufferedSerial::DCD_IRQ));
+            _dcd_irq->rise(callback(this, &UARTSerial::dcd_irq));
         }
     }
 }
 
-int BufferedSerial::close()
+int UARTSerial::close()
 {
     /* Does not let us pass a file descriptor. So how to close ?
      * Also, does it make sense to close a device type file descriptor*/
     return 0;
 }
 
-int BufferedSerial::isatty()
+int UARTSerial::isatty()
 {
     return 1;
 
 }
 
-off_t BufferedSerial::seek(off_t offset, int whence)
+off_t UARTSerial::seek(off_t offset, int whence)
 {
     /*XXX lseek can be done theoratically, but is it sane to mark positions on a dynamically growing/shrinking
      * buffer system (from an interrupt context) */
     return -ESPIPE;
 }
 
-int BufferedSerial::sync()
+int UARTSerial::sync()
 {
     lock();
 
@@ -94,7 +94,7 @@ int BufferedSerial::sync()
     return 0;
 }
 
-void BufferedSerial::sigio(Callback<void()> func) {
+void UARTSerial::sigio(Callback<void()> func) {
     core_util_critical_section_enter();
     _sigio_cb = func;
     if (_sigio_cb) {
@@ -106,7 +106,7 @@ void BufferedSerial::sigio(Callback<void()> func) {
     core_util_critical_section_exit();
 }
 
-ssize_t BufferedSerial::write(const void* buffer, size_t length)
+ssize_t UARTSerial::write(const void* buffer, size_t length)
 {
     size_t data_written = 0;
     const char *buf_ptr = static_cast<const char *>(buffer);
@@ -130,9 +130,9 @@ ssize_t BufferedSerial::write(const void* buffer, size_t length)
 
     core_util_critical_section_enter();
     if (!_tx_irq_enabled) {
-        BufferedSerial::tx_irq();                // only write to hardware in one place
+        UARTSerial::tx_irq();                // only write to hardware in one place
         if (!_txbuf.empty()) {
-            SerialBase::attach(callback(this, &BufferedSerial::tx_irq), TxIrq);
+            SerialBase::attach(callback(this, &UARTSerial::tx_irq), TxIrq);
             _tx_irq_enabled = true;
         }
     }
@@ -143,7 +143,7 @@ ssize_t BufferedSerial::write(const void* buffer, size_t length)
     return data_written;
 }
 
-ssize_t BufferedSerial::read(void* buffer, size_t length)
+ssize_t UARTSerial::read(void* buffer, size_t length)
 {
     size_t data_read = 0;
 
@@ -171,19 +171,19 @@ ssize_t BufferedSerial::read(void* buffer, size_t length)
     return data_read;
 }
 
-bool BufferedSerial::hup() const
+bool UARTSerial::hup() const
 {
-    return _dcd && _dcd->read() != 0;
+    return _dcd_irq && _dcd_irq->read() != 0;
 }
 
-void BufferedSerial::wake()
+void UARTSerial::wake()
 {
     if (_sigio_cb) {
         _sigio_cb();
     }
 }
 
-short BufferedSerial::poll(short events) const {
+short UARTSerial::poll(short events) const {
 
     short revents = 0;
     /* Check the Circular Buffer if space available for writing out */
@@ -205,17 +205,17 @@ short BufferedSerial::poll(short events) const {
     return revents;
 }
 
-void BufferedSerial::lock(void)
+void UARTSerial::lock(void)
 {
     _mutex.lock();
 }
 
-void BufferedSerial::unlock(void)
+void UARTSerial::unlock(void)
 {
     _mutex.unlock();
 }
 
-void BufferedSerial::rx_irq(void)
+void UARTSerial::rx_irq(void)
 {
     bool was_empty = _rxbuf.empty();
 
@@ -237,7 +237,7 @@ void BufferedSerial::rx_irq(void)
 }
 
 // Also called from write to start transfer
-void BufferedSerial::tx_irq(void)
+void UARTSerial::tx_irq(void)
 {
     bool was_full = _txbuf.full();
 

drivers/UARTSerial.h

@@ -0,0 +1,198 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef MBED_UARTSERIAL_H
+#define MBED_UARTSERIAL_H
+
+#include "platform/platform.h"
+
+#if DEVICE_SERIAL
+
+#include "FileHandle.h"
+#include "SerialBase.h"
+#include "InterruptIn.h"
+#include "PlatformMutex.h"
+#include "serial_api.h"
+#include "CircularBuffer.h"
+
+#ifndef MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE
+#define MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE  256
+#endif
+
+#ifndef MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE
+#define MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE  256
+#endif
+
+namespace mbed {
+
+class UARTSerial : private SerialBase, public FileHandle {
+
+public:
+
+    /** Create a UARTSerial port, connected to the specified transmit and receive pins, with a particular baud rate.
+     *  @param tx Transmit pin
+     *  @param rx Receive pin
+     *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
+     */
+    UARTSerial(PinName tx, PinName rx, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
+    virtual ~UARTSerial();
+
+    /** Equivalent to POSIX poll(). Derived from FileHandle.
+     *  Provides a mechanism to multiplex input/output over a set of file handles.
+     */
+    virtual short poll(short events) const;
+
+    /** Write the contents of a buffer to a file
+     *
+     *  @param buffer   The buffer to write from
+     *  @param size     The number of bytes to write
+     *  @return         The number of bytes written, negative error on failure
+     */
+    virtual ssize_t write(const void* buffer, size_t length);
+
+    /** Read the contents of a file into a buffer
+     *
+     *  Follows POSIX semantics:
+     *
+     *  * if no data is available, and non-blocking set return -EAGAIN
+     *  * if no data is available, and blocking set, wait until data is available
+     *  * If any data is available, call returns immediately
+     *
+     *  @param buffer   The buffer to read in to
+     *  @param size     The number of bytes to read
+     *  @return         The number of bytes read, 0 at end of file, negative error on failure
+     */
+    virtual ssize_t read(void* buffer, size_t length);
+
+    /** Acquire mutex */
+    virtual void lock(void);
+
+    /** Release mutex */
+    virtual void unlock(void);
+
+    /** Close a file
+     *
+     *  @return         0 on success, negative error code on failure
+     */
+    virtual int close();
+
+    /** Check if the file in an interactive terminal device
+     *
+     *  @return         True if the file is a terminal
+     *  @return         False if the file is not a terminal
+     *  @return         Negative error code on failure
+     */
+    virtual int isatty();
+
+    /** Move the file position to a given offset from from a given location
+     *
+     * Not valid for a device type FileHandle like UARTSerial.
+     * In case of UARTSerial, returns ESPIPE
+     *
+     *  @param offset   The offset from whence to move to
+     *  @param whence   The start of where to seek
+     *      SEEK_SET to start from beginning of file,
+     *      SEEK_CUR to start from current position in file,
+     *      SEEK_END to start from end of file
+     *  @return         The new offset of the file, negative error code on failure
+     */
+    virtual off_t seek(off_t offset, int whence);
+
+    /** Flush any buffers associated with the file
+     *
+     *  @return         0 on success, negative error code on failure
+     */
+    virtual int sync();
+
+    /** Set blocking or non-blocking mode
+     *  The default is blocking.
+     *
+     *  @param blocking true for blocking mode, false for non-blocking mode.
+     */
+    virtual int set_blocking(bool blocking)
+    {
+        _blocking = blocking;
+        return 0;
+    }
+
+    /** Register a callback on state change of the file.
+     *
+     *  The specified callback will be called on state changes such as when
+     *  the file can be written to or read from.
+     *
+     *  The callback may be called in an interrupt context and should not
+     *  perform expensive operations.
+     *
+     *  Note! This is not intended as an attach-like asynchronous api, but rather
+     *  as a building block for constructing  such functionality.
+     *
+     *  The exact timing of when the registered function
+     *  is called is not guaranteed and susceptible to change. It should be used
+     *  as a cue to make read/write/poll calls to find the current state.
+     *
+     *  @param func     Function to call on state change
+     */
+    virtual void sigio(Callback<void()> func);
+
+    /** Setup interrupt handler for DCD line
+     *
+     *  If DCD line is connected, an IRQ handler will be setup.
+     *  Does nothing if DCD is NC, i.e., not connected.
+     *
+     *  @param dcd_pin         Pin-name for DCD
+     *  @param active_high     a boolean set to true if DCD polarity is active low
+     */
+    void set_data_carrier_detect(PinName dcd_pin, bool active_high = false);
+
+private:
+
+    /** Software serial buffers
+     *  By default buffer size is 256 for TX and 256 for RX. Configurable through mbed_app.json
+     */
+    CircularBuffer<char, MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE> _rxbuf;
+    CircularBuffer<char, MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE> _txbuf;
+
+    PlatformMutex _mutex;
+
+    Callback<void()> _sigio_cb;
+
+    bool _blocking;
+    bool _tx_irq_enabled;
+    InterruptIn *_dcd_irq;
+
+    /** Device Hanged up
+     *  Determines if the device hanged up on us.
+     *
+     *  @return True, if hanged up
+     */
+    bool hup() const;
+
+    /** ISRs for serial
+     *  Routines to handle interrupts on serial pins.
+     *  Copies data into Circular Buffer.
+     *  Reports the state change to File handle.
+     */
+    void tx_irq(void);
+    void rx_irq(void);
+
+    void wake(void);
+
+    void dcd_irq(void);
+};
+} //namespace mbed
+
+#endif //DEVICE_SERIAL
+#endif //MBED_UARTSERIAL_H

drivers/mbed_lib.json

@@ -0,0 +1,13 @@
+{
+    "name": "drivers",
+    "config": {
+        "uart-serial-txbuf-size": {
+            "help": "Default TX buffer size for a UARTSerial instance (unit Bytes))",
+            "value": 256
+        },
+        "uart-serial-rxbuf-size": {
+            "help": "Default RX buffer size for a UARTSerial instance (unit Bytes))",
+            "value": 256
+        }
+    }
+}