inos_syn.h

Go to the documentation of this file.

//******************************************************************************
//******************************************************************************
 
#if !defined( __INOS_SYN_H )
#define __INOS_SYN_H
 
//--------------------------------------------------------------------------
//--- includes -----------------------------------------------------------------
//------------------------------------------------------------------------------
 
//------------------------------------------------------------------------------
//--- definitions --------------------------------------------------------------
//------------------------------------------------------------------------------
 
#define INOS_NO_WAIT        0x00000000  // don't wait
#define INOS_WAIT_FOREVER   0xFFFFFFFF  // wait forever
 
// --- locking cache -----------------------------------------------------------
 
#ifndef ICACHE
#ifdef INOS_CACHE_LOCK_SUPPORT 
#define ICACHE __attribute__ ((section (".icache")))
#define DCACHE __attribute__ ((section (".dcache")))
#else
#define ICACHE 
#define DCACHE 
#endif
#endif
 
//------------------------------------------------------------------------------
//--- forwards -----------------------------------------------------------------
//------------------------------------------------------------------------------
class CINOSSyncNode;
class CINOSTaskExMsg;
class CINOSBus;
 
//------------------------------------------------------------------------------
//--- class CINOSSync ----------------------------------------------------------
//------------------------------------------------------------------------------
 
class CINOSSync
{
    //--- user interface ---------------------------------------------------
 
    // constructor / destructor
    public :
        CINOSSync(
            const char* aName=0,
            uint32 aInitialCount=0,
            bool aManual=false
            );
 
        virtual ~CINOSSync();
 
    // public member functions
    public :
        virtual const char* GetName() { return m_pName;};
 
        ICACHE virtual uint32 Wait(uint32 aTimeout=INOS_WAIT_FOREVER);
 
        ICACHE virtual void Signal() { iSignal(false); }
 
        ICACHE virtual void SignalEx(CINOSTaskExMsg* apMsg, uint32 auRplId, uint32 auAppError) { Signal(); };
 
        ICACHE virtual bool MsgEvent(CINOSTaskExMsg* apMsg) { return false; };
 
 
        virtual void Reset();
 
        volatile uint32* GetLockAdr()
            { return m_Lock.GetAddr(); };
 
        // returns true if the event relies on polling to detect state transition.
        // this is necessary for 'raw' handled ports.
        virtual bool UsesPolling() const {return false;};
 
        bool IsSame(CINOSSync* i_pSync) {
          return this == i_pSync;
        }
 
        #if defined(INOS_SYNCGUARD)
        CINOSSync* operator& () {
            // remember that we're referenced
            m_uReferenced++;
            // return the address of the object
            return this;
        }
        #endif
 
    //--- internals --------------------------------------------------------
 
    friend class CINOSKernel;
    friend class CINOSScheduler;
    friend class CINOSTask;
    friend class CINOSMultiSync;
 
    // protected members
    protected:
        const char* m_pName;        
        uint32 m_uCount;            
        bool m_bManual;             
        tTaskId m_idFstWaiting;     
        tTaskId m_idLstWaiting;     
        SINOSCoreLock m_Lock;       
        CINOSSyncNode* m_pNode;     
        #if defined(INOS_SYNCGUARD)
        uint32 m_uReferenced{};     
        uint32 m_uReferencedByParent{};     
        #endif
 
    // operators
    public:
        int operator < (const CINOSSync& aSync) const
            { return (strcmp(m_pName, aSync.m_pName)<0);}
        int operator == (const CINOSSync& aSync) const
            { return (strcmp(m_pName, aSync.m_pName)==0);}
        int operator < (const char* aName) const
            { return (strcmp(m_pName, aName)<0);}
        int operator == (const char* aName) const
            { return (strcmp(m_pName, aName)==0);}
 
    // protected member functions
    protected :
        // parent checks signaled state
        ICACHE virtual  bool Signaled(CINOSSync*& aChild);
        // get pointer to object node
        /*ICACHE*/ virtual  CINOSSyncNode* GetNode() {return m_pNode;};
        // set pointer to object node
        /*ICACHE*/ virtual  void SetNode(CINOSSyncNode* aNode) {m_pNode = aNode;};
 
        ICACHE void SignalAndUnlock(uint32 auMsr) {
            iSignal(true, auMsr);
        }
 
    // private member functions
    private :
        void iSignal(bool abAlreadyLocked, uint32 uMsr = 0);
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSSync);
};
 
//------------------------------------------------------------------------------
//--- class CINOSMultiSync -----------------------------------------------------
//------------------------------------------------------------------------------
 
class CINOSExceptionCleanup;
class CINOSMultiSync : public CINOSSync
{
    //--- user interface ---------------------------------------------------
 
    // constructor / destructor
    public :
        CINOSMultiSync(const char* aName=0);
        virtual ~CINOSMultiSync();
 
    // public member functions
    public :
        void Or(CINOSSync* aChild);
        void And(CINOSSync* aChild);
        void Remove(CINOSSync* aChild, bool aDelete=false);
        void RemoveAll(bool aDelete=false);
 
        ICACHE virtual uint32 Wait(uint32 aTimeout=INOS_WAIT_FOREVER) override;
        ICACHE virtual uint32 Wait(CINOSSync*& aChild, uint32 aTimeout=INOS_WAIT_FOREVER);
 
        virtual void Reset() override;
 
        // returns true if the event relies on polling to detect state transition.
        // this is necessary for 'raw' handled ports.
        virtual bool UsesPolling() const override {return m_bUsesPolling;};
 
        CINOSBus* GetBus() { return m_pBus; }
        void SetBus(CINOSBus* apBus) { m_pBus = apBus; }
 
    //--- internals --------------------------------------------------------
 
    friend class CINOSSyncNode;
 
    // protected members
    protected:
        CINOSSyncNode* pFirstChild; // pointer to first child
        CINOSSyncNode* pLastChild;  // pointer to last child
 
        // exception handling
        CINOSExceptionCleanup* pCleanup;
 
        // Flag indicating if bit event is detected using polling
        bool m_bUsesPolling;
 
        // pointer to bus (if any) used for sleep
        CINOSBus* m_pBus;
 
    // protected member functions
    protected :
        // parent checks signaled state
        ICACHE virtual  bool Signaled(CINOSSync*& aChild) override;
        // wake up because child state changed
        void WakeUp();
        // cleanup 
        void Cleanup();
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSMultiSync);
};
 
//------------------------------------------------------------------------------
//--- class CINOSSyncNode ------------------------------------------------------
//------------------------------------------------------------------------------
 
class CINOSSyncNode
{
    friend class CINOSSync;
    friend class CINOSMultiSync;
    friend class CINOSBitSetEvent;
    friend class CINOSBitClearedEvent;
 
    // protected members
    protected:
        CINOSSync* pChild;          // pointer to sync object
        CINOSMultiSync* pParent;    // pointer to parent sync object
        CINOSSyncNode* pNext;       // pointer to next node on the same level
        // for the sake of simplicity (and runtime overhead), on multicore
        // system, we do not support 'groups' of sync nodes anymore.
        #ifndef INOS_MULTICORE
        CINOSSyncNode* pNextGroup;  // pointer to next sync group
        #endif
        bool mOrNode;               // 'or' node true/false
        
    // constructor / destructor
    public :
        CINOSSyncNode(CINOSMultiSync* aParent, CINOSSync* aChild, bool aOrNode);
        ~CINOSSyncNode();
 
    // protected member functions
    protected :
        // child changed to signaled state -> wake up parents
        ICACHE void WakeUp();
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSSyncNode);
};
 
 
//------------------------------------------------------------------------------
//--- class CINOSConditionVariable ---------------------------------------------
//------------------------------------------------------------------------------
#include <mutex>
class CINOSConditionVariable : public CINOSSync
{
    public :
        enum EStatus {
            eNoTimeout,
            eTimeout
        };
 
        CINOSConditionVariable(const char* aName=nullptr);
 
        virtual ~CINOSConditionVariable();
 
    public :
        template< class Rep, class Period >
        EStatus WaitFor(std::unique_lock<CINOSMutex>& lock,
                const std::chrono::duration<Rep, Period>& rel_time)
        {
            uint32 waitUs = std::chrono::duration_cast<std::chrono::microseconds>(rel_time).count();
            const uint32 uWaitTime = DoWait(lock, waitUs);
            return (uWaitTime == 0) ? eTimeout : eNoTimeout;
        }
 
        template< class Rep, class Period, class Predicate >
        bool WaitFor( std::unique_lock<CINOSMutex>& lock,
                       const std::chrono::duration<Rep, Period>& rel_time,
                       Predicate pred) {
            uint32 waitUs = checked_static_cast<uint32>(std::chrono::duration_cast<std::chrono::microseconds>(rel_time).count());
            while( !pred() ) {
                uint32 uWaitTime = DoWait(lock, waitUs);
                if( !uWaitTime ) {
                    // timeout occurred
                    return false;
                }
                waitUs = (waitUs - uWaitTime) > 0 ? waitUs - uWaitTime : 0;
            }
            return true;
        }
 
        void Wait( std::unique_lock<CINOSMutex>& lock ) {
            DoWait(lock);
        }
 
        template< class Predicate >
        void wait( std::unique_lock<CINOSMutex>& lock, Predicate pred ) {
            while( !pred() ) {
                DoWait(lock);
            }
        }
 
        void NotifyOne();
        void NotifyAll();
 
    private:
        uint32 DoWait(std::unique_lock<CINOSMutex>& lock, uint32 auTimeout = INOS_WAIT_FOREVER);
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSConditionVariable);
    // objects of CINOSConditionVariable need to be created very early during startup, when
    // the CTORs have not been executed. Therefore, in order to create such
    // objects, we need to provide the placement operator new.
    DECLARE_DYNAMIC_PLACEMENT(CINOSConditionVariable);
 
};
 
//------------------------------------------------------------------------------
//--- class CINOSSemaphore -----------------------------------------------------
//------------------------------------------------------------------------------
 
class CINOSSemaphore : public CINOSSync
{
    //--- user interface ---------------------------------------------------
 
    // public members
    public :
        CINOSSemaphore(
            const char* apName = 0,
            uint32 auInitialCount = 1,
            uint32 auMaxCount = 0xffffffff
            );
 
        virtual ~CINOSSemaphore();
 
        ICACHE uint32 Request(uint32 aTimeout=INOS_WAIT_FOREVER);
 
        ICACHE void Release();
 
        uint32 GetCount()
            { return m_uCount; }
 
        uint32 GetMaxCount()
            { return m_uMaxCount; }
 
    //--- internals --------------------------------------------------------
    
    private:
        uint32 m_uMaxCount;
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSSemaphore);
};
 
//------------------------------------------------------------------------------
//--- class CINOSQueue ---------------------------------------------------------
//------------------------------------------------------------------------------
 
class CINOSQueue : public CINOSSync
{
    //--- user interface ---------------------------------------------------
 
    // public members
    public :
        // create a queue with 'aNumber' entries of 'aSize' bytes
        CINOSQueue(const char* apName, uint32 auNumber, uint32 auSize);
 
        virtual ~CINOSQueue();
 
        ICACHE uint32 Put(void* aData, uint32 aTimeout=INOS_WAIT_FOREVER, uint32 auFlags=0);
 
        ICACHE uint32 Get(void* aData, uint32 aTimeout=INOS_WAIT_FOREVER);
 
        void Inquiry(void* aData, uint32& aCountOfElements);
 
        bool InquiryAt(void* aData, uint32 auIndex);
 
        void Flush();
 
        bool Empty();
 
        uint32 GetNumber();
 
        const uint32 GetSize() const {
            return mSize;
        }
 
        const uint32 GetMaxNumber() const {
            return mMaxNumber;
        }
 
        const uint32* GetAdrNumber() const {
            return &mNumber;
        }
 
        const uint64* GetAdrCount() const {
            return &mCount;
        }
 
        void SetFlag(uint32 auFlag)
        {
            mQueueFlags |= auFlag;
        }
 
        void ClrFlag(uint32 auFlag)
        {
            mQueueFlags &= ~auFlag;
        }
 
        uint32 BeginAccess();
 
        bool Access(void*&ptrData, uint32 auIndex);
 
        void EndAccess(uint32 msr);
 
        enum {
            eFlgOverflowCheck = 0x00000001, // check queue overflows
            eFlgOverflowFatal = 0x00000002, // fatal error in case of an overflow
            eFlgAccess        = 0x00000004, // data access active (queue locked)
            eFlgUnique        = 0x00000008, // only allow unique entries in queue
        };
 
    //--- internals --------------------------------------------------------
 
    // protected members
    protected :
        void* pBegin;   
        void* pEnd;     
        void* pPut;     
        void* pGet;     
        uint32 mNumber; 
        uint32 mSize;   
        uint32 mMaxNumber;  
        uint32 mQueueFlags; 
        CINOSSemaphore* pSemaphore; 
        uint64 mCount;  
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSQueue);
};
 
// include task queue handling
#include <cinostaskqueue.h>
 
//------------------------------------------------------------------------------
//--- class CINOSEvent ---------------------------------------------------------
//------------------------------------------------------------------------------
 
class CINOSEvent : public CINOSSync
{
    //--- user interface ---------------------------------------------------
 
    // constructor / destructor
    public :
        CINOSEvent(
            const char* aName=0,
            uint32 aInitialCount=0,
            bool aManual=false
            );
        virtual ~CINOSEvent();
 
    //--- internals --------------------------------------------------------
 
    friend class CINOSBitSetEvent;  
    friend class CINOSBitClearedEvent;  
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSEvent);
};
 
//------------------------------------------------------------------------------
//--- class CINOSBitSetEvent ---------------------------------------------------
//------------------------------------------------------------------------------
 
#ifndef INOS_NO_BIT_EVENT_SUPPORT
class CINOSBit;
class CINOSBitSetEvent : public CINOSSync
{
    friend class CINOSBit;  
 
    //--- user interface ---------------------------------------------------
 
    // constructor / destructor
    public :
        CINOSBitSetEvent(CINOSBit* apBit);
        virtual ~CINOSBitSetEvent();
 
    // public member functions
    public :
        // get name of sync object
        virtual const char* GetName() override {return m_pEvent->GetName();};
        // wait for signaled state for max. aTimeout usec
        virtual uint32 Wait(uint32 aTimeout=INOS_WAIT_FOREVER) override ;
        // put object into the signaled state
        virtual void Signal() override ;
        // reset object state
        virtual void Reset() override ;
        // returns true if the event relies on polling to detect state transition.
        // this is necessary for 'raw' handled ports.
        virtual bool UsesPolling() const override {return m_bUsesPolling;};
 
    //--- internals --------------------------------------------------------
 
    // protected members
    protected :
        CINOSBit* m_pBit;
        CINOSEvent* m_pEvent;
 
        // exception handling
        CINOSExceptionCleanup* m_pCleanup;
 
        // Flag indicating if bit event is detected using polling
        bool m_bUsesPolling;
 
    // protected member functions
    protected :
        // parent checks signaled state
        virtual bool Signaled(CINOSSync*& aChild) override;
        // get pointer to object node
        virtual CINOSSyncNode* GetNode() override {return m_pEvent->GetNode();};
        // set pointer to object node
        virtual void SetNode(CINOSSyncNode* aNode) override {m_pEvent->SetNode(aNode);};
        // cleanup 
        void Cleanup();
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSBitSetEvent);
};
 
//------------------------------------------------------------------------------
//--- class CINOSBitClearedEvent -----------------------------------------------
//------------------------------------------------------------------------------
 
class CINOSBitClearedEvent : public CINOSSync
{
    friend class CINOSBit;  
 
    //--- user interface ---------------------------------------------------
 
    // constructor / destructor
    public :
        CINOSBitClearedEvent(CINOSBit* apBit);
        virtual ~CINOSBitClearedEvent();
 
    // public member functions
    public :
        // get name of sync object
        virtual const char* GetName() override  {return m_pEvent->GetName();};
        // wait for signaled state for max. aTimeout usec
        virtual uint32 Wait(uint32 aTimeout=INOS_WAIT_FOREVER) override ;
        // put object into the signaled state
        virtual void Signal() override ;
        // reset object state
        virtual void Reset() override ;
        // returns true if the event relies on polling to detect state transition.
        // this is necessary for 'raw' handled ports.
        virtual bool UsesPolling() const override  {return m_bUsesPolling;};
 
    //--- internals --------------------------------------------------------
 
    // protected members
    protected :
        CINOSBit* m_pBit;
        CINOSEvent* m_pEvent;
 
        // exception handling
        CINOSExceptionCleanup* m_pCleanup;
 
        // Flag indicating if bit event is detected using polling
        bool m_bUsesPolling;
 
    // protected member functions
    protected :
        // parent checks signaled state
        virtual bool Signaled(CINOSSync*& aChild) override ;
        // get pointer to object node
        virtual CINOSSyncNode* GetNode() override {return m_pEvent->GetNode();};
        // set pointer to object node
        virtual void SetNode(CINOSSyncNode* aNode) override {m_pEvent->SetNode(aNode);};
        // cleanup 
        void Cleanup();
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSBitClearedEvent);
};
#endif
 
//------------------------------------------------------------------------------
//--- class CINOSTimeEvent -----------------------------------------------------
//------------------------------------------------------------------------------
 
#ifndef INOS_NO_1MS_SUPPORT
class CINOSxmsHandler;
class CINOSTimeEvent : public CINOSSync
{
    //--- user interface ---------------------------------------------------
 
    // constructor / destructor
    public :
        enum {
            eEventDisabled = 0,
            eUsePreviousTime = 0
        };
 
        CINOSTimeEvent(uint32 aTime);
        virtual ~CINOSTimeEvent();
 
    // public member functions
    public :
        // reset event with new time (time = 0 -> reset with old time)
        void Reset(uint32 aTime=eUsePreviousTime);
        void Stop();
        // start event with new time (time = 0 -> reset with old time)
        void Start(uint32 aTime=eUsePreviousTime);
 
    //--- internals --------------------------------------------------------
 
    private:
        void iAddHandler();
        void iRemoveHandler();
 
    // protected members
    protected :
        uint32 mWaitTime = eEventDisabled;
        CINOSxmsHandler* pHandler = nullptr;
        // exception handling
        CINOSExceptionCleanup* pCleanup = nullptr;
 
    // protected member functions
    protected :
        // event handler
        void Handler();
        // cleanup 
        void Cleanup();
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSTimeEvent);
};
 
#endif
 
//--------------------------------------------------------------------------
// CINOSSyncObjects
//--------------------------------------------------------------------------
 
class CINOSSyncObjects
{
    //--- user interface ---------------------------------------------------
 
    public :
        // add sync object to the tree
        void Add(CINOSSync* aSync);
        // find sync object 'aName'
        CINOSSync* Find(char* aName);
 
    //--- internals --------------------------------------------------------
 
    private :
        // tree of all objects in the system
        TINOSNameBalancedBinaryTree<CINOSSync>* pSyncObjects;
 
    // constructor
    public:
        CINOSSyncObjects() ;
};
 
//--------------------------------------------------------------------------
// CINOSLockGuard
//--------------------------------------------------------------------------
 
template<typename TLock>
class CINOSLockGuard
{
    //--- user interface ---------------------------------------------------
 
    public :
        CINOSLockGuard(TLock& aLock):
            m_Lock(aLock), m_bLocked(false)
        {
            m_bLocked = (m_Lock.Request() != 0);
        }
        CINOSLockGuard(TLock& aLock, uint32 auTimeout/*usec*/):
            m_Lock(aLock), m_bLocked(false)
        {
            m_bLocked = (m_Lock.Request(auTimeout) != 0);
        }
        ~CINOSLockGuard() {
            if (m_bLocked) m_Lock.Release();
        }
        bool IsLocked() const {
            return m_bLocked;
        }
 
    //--- internals --------------------------------------------------------
 
    private :
        // Lock to be guarded
        TLock& m_Lock;
        // Flag indicating if the lock is held
        bool m_bLocked;
};
 
typedef CINOSLockGuard<CINOSSemaphore> CINOSSemaphoreGuard;
 
//------------------------------------------------------------------------------
//--- class CINOSRefCount ------------------------------------------------------
//------------------------------------------------------------------------------
 
class CINOSRefCount
{
    //--- user interface ---------------------------------------------------
 
    // public members
    public :
        CINOSRefCount(
            const char* apParentName,
            const char* apBaseName,
            int32 aiInitialCount = 0,
            void* apHandlerObj = NULL,
            void* apHandlerFunc = NULL
        );
 
        virtual ~CINOSRefCount();
 
        int32 Increment();
 
        int32 Decrement();
 
        int32 GetCount();
 
        void SetCount(int32 aiNewCount);
 
    //--- internals --------------------------------------------------------
 
    protected :
 
        friend class CINOSLockGuard<CINOSRefCount>;
        uint32 Request();
        void Release();
 
    protected :
        inosName32 m_sName;
        int32 m_iCount;
        void* m_pHandlerObj;
        void* m_pHandlerFunc;
 
    // allow dynamic object handling (new/delete)
    DECLARE_DYNAMIC(CINOSRefCount);
};
 
typedef CINOSLockGuard<CINOSRefCount> CINOSRefCountGuard;
 
inline CINOSTask* ActualTask();
 
//------------------------------------------------------------------------------
//--- class CINOSReadWriteLock -------------------------------------------------
//------------------------------------------------------------------------------
class CINOSReadWriteLock {
    public:
        void ReadLock() {
            std::unique_lock<CINOSMutex> lock(m_Mutex);
            while (HasForeignWriter()) {
                m_Unlocked.wait(lock, [this]() { return !HasForeignWriter(); });
            }
            m_uReaders++;
        }
        void ReadUnlock() {
            std::unique_lock<CINOSMutex> lock(m_Mutex);
            m_uReaders--;
            if (m_uReaders == 0)
                m_Unlocked.NotifyAll();
        }
        void WriteLock() {
            std::unique_lock<CINOSMutex> lock(m_Mutex);
            while (HasForeignWriter() || HasReaders()) {
                m_Unlocked.wait(lock, [this]() { return !(HasForeignWriter() || HasReaders()); });
            }
            ++m_nWriter;
            m_pWriter = ActualTask();
        }
        void WriteUnlock() {
            std::unique_lock<CINOSMutex> lock(m_Mutex);
            --m_nWriter;
            if (m_nWriter == 0) {
                m_pWriter = nullptr;
                m_Unlocked.NotifyAll();
            }
        }
    private:
        bool HasReaders() const {
            return m_uReaders > 0;
        }
        bool HasForeignWriter() const {
            const bool bHasWriter = m_nWriter > 0;
            const bool bWriterIsMe = ActualTask() == m_pWriter;
            return bHasWriter && !bWriterIsMe;
        }
    private:
        size_t m_uReaders{};
        size_t m_nWriter{0};
        CINOSTask* m_pWriter{nullptr};
        CINOSMutex m_Mutex;
        CINOSConditionVariable m_Unlocked;
};
//------------------------------------------------------------------------------
//--- class CINOSWriteLock -----------------------------------------------------
//------------------------------------------------------------------------------
class CINOSWriteLock {
    public:
        CINOSWriteLock(CINOSReadWriteLock& aLock)
        : m_Lock(aLock)
        {
            m_Lock.WriteLock();
        }
        ~CINOSWriteLock() {
            m_Lock.WriteUnlock();
        }
        CINOSReadWriteLock& m_Lock;
};
//------------------------------------------------------------------------------
//--- class CINOSReadLock ------------------------------------------------------
//------------------------------------------------------------------------------
class CINOSReadLock {
    public:
        CINOSReadLock(CINOSReadWriteLock& aLock)
        : m_Lock(aLock)
        {
            m_Lock.ReadLock();
        }
        ~CINOSReadLock() {
            m_Lock.ReadUnlock();
        }
        CINOSReadWriteLock& m_Lock;
};
 
//--------------------------------------------------------------------------
// global variables
//--------------------------------------------------------------------------
 
extern CINOSSyncObjects* pINOSSyncObjects;  // binary tree of INOS sync objects
 
#endif  // __INOS_SYN_H