yateradio.h

 
#ifndef __YATERADIO_H
#define __YATERADIO_H
 
#include <yateclass.h>
#include <yatexml.h>
 
#ifdef _WINDOWS
 
#ifdef LIBYRADIO_EXPORTS
#define YRADIO_API __declspec(dllexport)
#else
#ifndef LIBYRADIO_STATIC
#define YRADIO_API __declspec(dllimport)
#endif
#endif
 
#endif /* _WINDOWS */
 
#ifndef YRADIO_API
#define YRADIO_API
#endif
 
 
namespace TelEngine {
 
class GSML3Codec;                        // GSM Layer codec
class RadioCapability;                   // Radio device capabilities
class RadioInterface;                    // Generic radio interface
 
class YRADIO_API GSML3Codec
{
    YNOCOPY(GSML3Codec);
public:
    enum Flags {
        XmlDumpMsg = 0x01,
        XmlDumpIEs = 0x02,
        MSCoder    = 0x04,
    };

    enum Status {
        NoError = 0,
        MsgTooShort,
        UnknownProto,
        ParserErr,
        MissingParam,
        IncorrectOptionalIE,
        IncorrectMandatoryIE,
        MissingMandatoryIE,
        UnknownMsgType,
    };

    enum Protocol {
        GCC       = 0x00, // Group Call Control
        BCC       = 0x01, // Broadcast Call Control
        EPS_SM    = 0x02, // EPS Session Management
        CC        = 0x03, // Call Control; Call Related SS messages
        GTTP      = 0x04, // GPRS Transparent Transport Protocol (GTTP)
        MM        = 0x05, // Mobility Management
        RRM       = 0x06, // Radio Resources Management
        EPS_MM    = 0x07, // EPS Mobility Management
        GPRS_MM   = 0x08, // GPRS Mobility Management
        SMS       = 0x09, // SMS
        GPRS_SM   = 0x0a, // GPRS Session Management
        SS        = 0x0b, // Non Call Related SS messages
        LCS       = 0x0c, // Location services
        Extension = 0x0e, // reserved for extension of the PD to one octet length
        Test      = 0x0f, // used by tests procedures described in 3GPP TS 44.014, 3GPP TS 34.109 and 3GPP TS 36.509
        Unknown   = 0xff,
    };

    enum Type {
        NoType = 0,
        T,
        V,
        TV,
        LV,
        TLV,
        LVE,
        TLVE,
    };

    enum XmlType {
        Skip,
        XmlElem,
        XmlRoot,
    };

    enum EPSSecurityHeader {
        PlainNAS                           = 0x00,
        IntegrityProtect                   = 0x01,
        IntegrityProtectCiphered           = 0x02,
        IntegrityProtectNewEPSCtxt         = 0x03,
        IntegrityProtectCipheredNewEPSCtxt = 0x04,
        ServiceRequestHeader               = 0xa0,
    };

    GSML3Codec(DebugEnabler* dbg = 0);

    unsigned int decode(const uint8_t* in, unsigned int len, XmlElement*& out, const NamedList& params = NamedList::empty());

    unsigned int encode(const XmlElement* in, DataBlock& out, const NamedList& params = NamedList::empty());

    unsigned int decode(XmlElement* xml, const NamedList& params = NamedList::empty());

    unsigned int encode(XmlElement* xml, const NamedList& params = NamedList::empty());

    void setCodecDebug(DebugEnabler* enabler = 0, void* ptr = 0);

    inline uint8_t flags() const
        { return m_flags; }

    inline void setFlags(uint8_t flgs, bool reset = false)
    {
        if (reset)
            resetFlags();
        m_flags |= flgs;
    }

    inline void resetFlags(uint8_t flgs = 0)
    {
        if (flgs)
            m_flags &= ~flgs;
        else
            m_flags = 0;
    }

    inline void setPrintDbg(bool on = false)
        { m_printDbg = on; }

    inline bool printDbg() const
        { return m_printDbg; }

    inline DebugEnabler* dbg() const
        { return m_dbg; }

    inline void* ptr() const
        { return m_ptr; }

    static void decodeGSM7Bit(unsigned char* buf, unsigned int len, String& text,
        unsigned int heptets = (unsigned int)-1);

    static bool encodeGSM7Bit(const String& text, DataBlock& buf);

    static const TokenDict s_typeDict[];

    static const TokenDict s_protoDict[];

    static const TokenDict s_securityHeaders[];

    static const TokenDict s_errorsDict[];

    static const TokenDict s_mmRejectCause[];

    static const TokenDict s_gmmRejectCause[];
 
private:
 
    unsigned int decodeXml(XmlElement* xml, const NamedList& params, const String& pduTag);
    unsigned int encodeXml(XmlElement* xml, const NamedList& params, const String& pduTag);
    void printDbg(int dbgLevel, const uint8_t* in, unsigned int len, XmlElement* xml, bool encode = false);
 
    uint8_t m_flags;                 // Codec flags
    // data used for debugging messages
    DebugEnabler* m_dbg;
    void* m_ptr;
    // activate debug
    bool m_printDbg;
};
 

class YRADIO_API RadioCapability
{
public:
    RadioCapability();
 
    unsigned maxPorts;                   // Available number of ports
    unsigned currPorts;                  // Number of used (available) ports
    uint64_t maxTuneFreq;                // Maximum allowed tuning frequency (in Hz)
    uint64_t minTuneFreq;                // Minimum allowed tuning frequency (in Hz)
    unsigned maxSampleRate;              // Maximum allowed sampling rate (in Hz)
    unsigned minSampleRate;              // Minimum allowed sampling rate (in Hz)
    unsigned maxFilterBandwidth;         // Maximum allowed anti-alias filter bandwidth (in Hz)
    unsigned minFilterBandwidth;         // Minimum allowed anti-alias filter bandwidth (in Hz)
    unsigned rxLatency;                  // Estimated radio latency (in samples)
    unsigned txLatency;                  // Estimated transmit latency (in samples)
};
 

class RadioBufDesc
{
public:
    inline RadioBufDesc()
        : samples(0), offs(0), valid(0)
        {}

    inline void reset(unsigned int value = 0)
        { offs = valid = value; }

    inline void reset(unsigned int offset, unsigned int validS) {
            offs = offset;
            valid = validS;
        }

    inline bool validSamples(unsigned int minSamples) const
        { return !minSamples || minSamples >= offs || minSamples >= valid; }
 
    float* samples;                      // Current read buffer
    unsigned int offs;                   // Current buffer offset (in sample periods)
    unsigned int valid;                  // The number of valid samples in buffer
};
 

class RadioReadBufs : public GenObject
{
public:
    inline RadioReadBufs(unsigned int len = 0, unsigned int validThres = 0)
        : m_bufSamples(len), m_validMin(validThres)
        {}

    inline void reset(unsigned int len, unsigned int validThres) {
            m_bufSamples = len;
            m_validMin = validThres;
            crt.reset();
            aux.reset();
            extra.reset();
        }

    inline unsigned int bufSamples() const
        { return m_bufSamples; }

    inline bool full(RadioBufDesc& buf) const
        { return buf.offs >= m_bufSamples; }

    inline bool valid(RadioBufDesc& buf) const
        { return buf.validSamples(m_validMin); }

    String& dump(String& buf);
 
    RadioBufDesc crt;
    RadioBufDesc aux;
    RadioBufDesc extra;
 
protected:
    unsigned int m_bufSamples;           // Buffers length in sample periods
    unsigned int m_validMin;             // Valid samples threshold
};
 

class YRADIO_API RadioInterface : public RefObject, public DebugEnabler
{
    YCLASS(RadioInterface,RefObject);
public:
    enum ErrorCode {
        NoError = 0,
        Failure = (1 << 1),              // Unknown error
        HardwareIOError = (1 << 2),      // Communication error with HW
        NotInitialized = (1 << 3),       // Interface not initialized
        NotSupported = (1 << 4),         // Feature not supported
        NotCalibrated = (1 << 5),        // The radio is not calibrated
        TooEarly = (1 << 6),             // Timestamp is in the past
        TooLate = (1 << 7),              // Timestamp is in the future
        OutOfRange = (1 << 8),           // A requested parameter setting is out of range
        NotExact = (1 << 9),             // The affected value is not an exact match to the requested one
        DataLost = (1 << 10),            // Received data lost due to slow reads
        Saturation = (1 << 11),          // Data contain values outside of +/-1+/-j
        RFHardwareFail = (1 << 12),      // Failure in RF hardware
        RFHardwareChange = (1 << 13),    // Change in RF hardware, not outright failure
        EnvironmentalFault = (1 << 14),  // Environmental spec exceeded for radio HW
        InvalidPort = (1 << 15),         // Invalid port number
        Pending = (1 << 16),             // Operation is pending
        Cancelled = (1 << 17),           // Operation cancelled
        Timeout = (1 << 18),             // Operation timeout
        HardwareNotAvailable = (1 << 19),// Device not found
        InsufficientSpeed = (1 << 20),   // Device has insufficient speed to fulfill required transfer rate
        // Masks
        // Errors indicating automatic application restart should not be performed
        // These may indicate misconfig or hardware failures requiring system restart
        NoAutoRestartMask = HardwareNotAvailable | InsufficientSpeed,
        // Errors requiring radio or port shutdown
        FatalErrorMask = HardwareIOError | RFHardwareFail | EnvironmentalFault | Failure |
            NoAutoRestartMask,
        // Errors that can be cleared
        ClearErrorMask = TooEarly | TooLate | NotExact | DataLost | Saturation |
            InvalidPort | Timeout,
        // Errors that are specific to a single call
        LocalErrorMask = NotInitialized | NotCalibrated | TooEarly | TooLate | OutOfRange |
            NotExact | DataLost | Saturation | RFHardwareChange | InvalidPort,
    };

    enum Operation {
        PendingInitialize = 0,           // initialize() is pending
        PendingCount,
    };

    unsigned int pollPending(unsigned int oper, unsigned int waitMs = 0);

    virtual unsigned int getInterface(String& devicePath) const
        { return NotSupported; }

    virtual const RadioCapability* capabilities() const
        { return m_radioCaps; }

    virtual unsigned int initialize(const NamedList& params = NamedList::empty()) = 0;

    virtual unsigned int setLoopback(const char* name = 0)
        { return NotSupported; }

    virtual unsigned int setParams(NamedList& params, bool shareFate = true) = 0;

    virtual unsigned int setDataDump(int dir = 0, int level = 0,
        const NamedList* params = 0) = 0;

    virtual unsigned int calibrate()
        { return NotSupported; }

    virtual unsigned int setPorts(unsigned count) = 0;

    virtual unsigned int status(int port = -1) const = 0;

    virtual void clearErrors()
        { m_lastErr &= ~ClearErrorMask; }

    virtual unsigned int send(uint64_t when, float* samples, unsigned size,
        float* powerScale = 0) = 0;

    virtual unsigned int recv(uint64_t& when, float* samples, unsigned& size) = 0;

    virtual unsigned int read(uint64_t& when, RadioReadBufs& bufs,
        unsigned int& skippedBufs);

    virtual unsigned int getRxTime(uint64_t& when) const = 0;

    virtual unsigned int getTxTime(uint64_t& when) const = 0;

    virtual unsigned int setFreqOffset(float offs, float* newVal = 0) = 0;

    virtual unsigned int setSampleRate(uint64_t hz) = 0;

    virtual unsigned int getSampleRate(uint64_t& hz) const = 0;

    virtual unsigned int setFilter(uint64_t hz) = 0;

    virtual unsigned int getFilterWidth(uint64_t& hz) const = 0;

    virtual unsigned int setTxFreq(uint64_t hz) = 0;

    virtual unsigned int getTxFreq(uint64_t& hz) const = 0;

    virtual unsigned int setTxPower(unsigned dBm) = 0;

    virtual unsigned int setRxFreq(uint64_t hz) = 0;

    virtual unsigned int getRxFreq(uint64_t& hz) const = 0;

    virtual unsigned int setTxGain1(int val, unsigned port)
        { return NotSupported; }

    virtual unsigned int setTxGain2(int val, unsigned port)
        { return NotSupported; }

    virtual unsigned int setRxGain1(int val, unsigned port)
        { return NotSupported; }

    virtual unsigned int setRxGain2(int val, unsigned port)
        { return NotSupported; }

    virtual unsigned int setGain(bool tx, int val, unsigned int port,
        int* newVal = 0) const
        { return NotSupported; }

    virtual const String& toString() const;

    virtual void completeDevInfo(NamedList& p, bool full = false, bool retData = false);

    virtual void setError(NamedList& p, unsigned int code, const char* str = 0);

    static inline const char* errorName(int code, const char* defVal = 0)
        { return lookup(code,errorNameDict(),defVal); }

    static const TokenDict* errorNameDict();
 
protected:
    RadioInterface(const char* name);

    inline void setPending(unsigned int oper, unsigned int code = Pending) {
            Lock lck(m_mutex);
            if (oper < PendingCount)
                m_pendingCode[oper] = code;
        }
        
    unsigned int m_lastErr;               // Last error that appeared during functioning
    unsigned int m_totalErr;              // All the errors that appeared
    RadioCapability* m_radioCaps;         // Radio capabilities
 
private:
    String m_name;
    Mutex m_mutex;
    unsigned int m_pendingCode[PendingCount];
};
 

class YRADIO_API RadioDataDesc
{
public:
    enum ElementType {
        Float = 0,
        Int16 = 1,
    };

    enum TsType {
        TsApp = 0,                       // Application level timestamp
        TsBoard = 1,                     // Board (device) level timestamp
    };

    inline RadioDataDesc(uint8_t eType = Float, uint8_t tsType = TsApp,
        uint8_t sLen = 2, uint8_t ports = 1)
        : m_elementType(eType), m_sampleLen(sLen), m_ports(ports ? ports : 1),
        m_tsType(tsType),
#ifdef LITTLE_ENDIAN
        m_littleEndian(true)
#else
        m_littleEndian(false)
#endif
        {
            m_signature[0] = 'Y';
            m_signature[1] = 'R';
            m_signature[2] = 0;
        }
 
    uint8_t m_signature[3];              // File signature
    uint8_t m_elementType;               // Element data type
    uint8_t m_sampleLen;                 // Sample length in elements
    uint8_t m_ports;                     // The number of ports
    uint8_t m_tsType;                    // Records timestamp type
    bool m_littleEndian;                 // Endiannes
};
 

class YRADIO_API RadioDataFile : public String
{
public:
    RadioDataFile(const char* name, bool dropOnError = true);

    virtual ~RadioDataFile();

    inline const RadioDataDesc& desc() const
        { return m_header; }

    inline bool valid() const
        { return m_file.valid(); }

    inline bool sameEndian() const
        { return m_littleEndian == m_header.m_littleEndian; }

    bool open(const char* fileName, const RadioDataDesc* data,
        DebugEnabler* dbg = 0, int* error = 0);

    bool write(uint64_t ts, const void* buf, uint32_t len, DebugEnabler* dbg = 0,
        int* error = 0);

    bool read(uint64_t& ts, DataBlock& buffer, DebugEnabler* dbg = 0, int* error = 0);

    void terminate(DebugEnabler* dbg = 0);

    static bool fixEndian(DataBlock& buf, unsigned int bytes);
 
protected:
    bool ioError(bool send, DebugEnabler* dbg, int* error, const char* extra);
 
    bool m_littleEndian;                 // Machine endiannes
    bool m_dropOnError;                  // Terminate (close file) on error
    uint32_t m_chunkSize;                // Item size (used to check data validity)
    RadioDataDesc m_header;              // File header
    File m_file;                         // File to use
    DataBlock m_writeBuf;
};
 
}; // namespace TelEngine
 
#endif /* __YATERADIO_H */
 
/* vi: set ts=8 sw=4 sts=4 noet: */