SerialBase.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Teknic, Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#ifndef __SERIALBASE_H__
#define __SERIALBASE_H__

#include <stdint.h>
#include <sam.h>
#include "DmaManager.h"
#include "ISerial.h"
#include "PeripheralRoute.h"

namespace ClearCore {

#ifndef SERIAL_BUFFER_SIZE
#define SERIAL_BUFFER_SIZE 64
#endif

#ifndef SERCOM_NVIC_RX_PRIORITY
#define SERCOM_NVIC_RX_PRIORITY (static_cast<IRQn_Type>(1))
#endif

#ifndef SERCOM_NVIC_TX_PRIORITY
#define SERCOM_NVIC_TX_PRIORITY (static_cast<IRQn_Type>(1))
#endif

#ifndef SERCOM_NVIC_ERR_PRIORITY
#define SERCOM_NVIC_ERR_PRIORITY (static_cast<IRQn_Type>(7))
#endif

class SerialBase : public ISerial {
    friend class TestIO;

public:
    static const int16_t BREAK_DETECTED = int16_t(0xBDBD);

    static const int16_t EOB = -1;

    union SerialErrorStatusRegister {
        uint32_t reg;

        struct {
            uint32_t SerialFrameError      : 1;
            uint32_t SerialParityError     : 1;
            uint32_t SerialOverflowError   : 1;
        } bit;

        SerialErrorStatusRegister() {
            reg = 0;
        }

        SerialErrorStatusRegister(uint32_t val) {
            reg = val;
        }

        operator bool() const {
            return reg > 0;
        }
    };

    typedef enum {
        COM_MSB_FIRST = 0,
        COM_LSB_FIRST = 1
    } DataOrders;

    typedef enum {
        UART,
        SPI
    } PortModes;

    typedef enum {
        SCK_LOW = 0,
        SCK_HIGH
    } SpiClockPolarities;

    typedef enum {
        LEAD_SAMPLE = 0,
        LEAD_CHANGE
    } SpiClockPhases;

    typedef enum {
        LINE_OFF,
        LINE_ON,
        LINE_HW,
    } CtrlLineModes;

    // ======================= MODE INDEPENDENT API ============================
    bool PortMode(PortModes newMode);

    // ========================== ISerial  API =================================
    void Flush() override;
    void FlushInput() override;

    virtual void PortOpen() override;

    virtual void PortClose() override;

    virtual bool Speed(uint32_t bitsPerSecond) override;

    virtual uint32_t Speed() override {
        return m_baudRate;
    }

    int16_t CharGet() override;

    int16_t CharPeek() override;

    bool SendChar(uint8_t charToSend) override;

    int32_t AvailableForRead() override;

    int32_t AvailableForWrite() override;

    void WaitForTransmitIdle() override;

    bool PortIsOpen() override;

    void FlowControl(bool useFlowControl);

    bool FlowControl() {
        return m_flowControl;
    };

    bool RtsMode(CtrlLineModes mode);

    bool CtsState();

    void SerialBreak(bool enable);

    bool Parity(Parities newParity) override;

    Parities Parity() override {
        return m_parity;
    }

    bool StopBits(uint8_t bits) override;

    bool CharSize(uint8_t size) override;

#ifndef HIDE_FROM_DOXYGEN

    operator bool() override {
        return true;
    }
#endif

    // =============================== SPI API =================================

    void SpiClock(SpiClockPolarities polarity, SpiClockPhases phase);

    bool SpiSsMode(CtrlLineModes mode);

    uint8_t SpiTransferData(uint8_t data);

    int32_t SpiTransferData(
        uint8_t const *writeBuf, uint8_t *readBuf, int32_t len);

    bool SpiTransferDataAsync(
        uint8_t const *writeBuf, uint8_t *readBuf, int32_t len);

    bool SpiAsyncWaitComplete();

    // ============================= SETUP API =================================

    void DataOrder(DataOrders newOrder);

    // ========================= ERROR HANDLING API ============================
    void HandleFrameError();

    void HandleParityError();

    void HandleOverflow();

    SerialErrorStatusRegister ErrorStatusAccum(SerialErrorStatusRegister mask =
                UINT32_MAX);

#ifndef HIDE_FROM_DOXYGEN
    //========================= INTERRUPT HANDLERS =============================

    void IrqHandlerTx();
    void IrqHandler1();
    void IrqHandlerRx();
    void IrqHandlerException();
#endif

protected:
    // Current format
    Parities m_parity;
    uint8_t m_stopBits;
    uint8_t m_charSize;
    PortModes m_portMode;
    SpiClockPolarities m_polarity;
    SpiClockPhases m_phase;
    CtrlLineModes m_ssMode;
    CtrlLineModes m_rtsMode;
    bool m_flowControl;

    // SERCOM instance
    Sercom *m_serPort;

    // Pin information
    const PeripheralRoute *m_ctsMisoInfo;
    const PeripheralRoute *m_rtsSsInfo;
    const PeripheralRoute *m_rxSckInfo;
    const PeripheralRoute *m_txMosiInfo;

    uint32_t m_baudRate;
    uint8_t m_peripheral;
    // Port open/close state
    bool m_portOpen;
    // Serial Break state
    bool m_serialBreak;
    // SERCOM DRE interrupt number
    IRQn_Type m_dreIrqN;
    // SPI dma channels
    DmaChannels m_dmaRxChannel;
    DmaChannels m_dmaTxChannel;

    SerialBase(const PeripheralRoute *ctsMisoInfo,
               const PeripheralRoute *rtsSsInfo,
               const PeripheralRoute *rxSckInfo,
               const PeripheralRoute *txMosiInfo,
               uint8_t peripheral);

    SerialBase() {};

    void WaitOneCharTime();

    // =========================== INTERRUPT API ===============================
    void EnableDreInterruptUart();
    void DisableDreInterruptUart();
    void EnableRxcInterruptUart();
    void DisableRxcInterruptUart();

private:
    // Serial Buffers
    int16_t m_bufferIn[SERIAL_BUFFER_SIZE];
    int16_t m_bufferOut[SERIAL_BUFFER_SIZE];
    // Indices for head and tails of the ring buffers

    volatile uint32_t m_inHead, m_inTail;
    volatile uint32_t m_outHead, m_outTail;

    // Clear-on-read accumulating error register.
    SerialErrorStatusRegister m_errorRegAccum;

    void PortEnable(bool initializing = false);
    void PortDisable();

    uint32_t NextIndex(uint32_t currentIndex) {
        return ((currentIndex + 1) & (SERIAL_BUFFER_SIZE - 1));
    }

    void RxProc();

    void TxPump();

    bool RtsSsPinState(CtrlLineModes mode);
};

} // ClearCore namespace
#endif // __SERIALBASE_H__