/** * @file * @brief QXK preemptive kernel extended (blocking) thread functions * @ingroup qxk * @cond ****************************************************************************** * Last updated for version 5.7.4 * Last updated on 2016-11-02 * * Q u a n t u m L e a P s * --------------------------- * innovating embedded systems * * Copyright (C) Quantum Leaps, LLC. All rights reserved. * * This program is open source software: you can redistribute it and/or * modify it under the terms of the GNU General Public License as published * by the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * Alternatively, this program may be distributed and modified under the * terms of Quantum Leaps commercial licenses, which expressly supersede * the GNU General Public License and are specifically designed for * licensees interested in retaining the proprietary status of their code. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see . * * Contact information: * http://www.state-machine.com * mailto:info@state-machine.com ****************************************************************************** * @endcond */ #define QP_IMPL /* this is QP implementation */ #include "qf_port.h" /* QF port */ #include "qxk_pkg.h" /* QXK package-scope internal interface */ #include "qassert.h" /* QP embedded systems-friendly assertions */ #ifdef Q_SPY /* QS software tracing enabled? */ #include "qs_port.h" /* include QS port */ #else #include "qs_dummy.h" /* disable the QS software tracing */ #endif /* Q_SPY */ /* protection against including this source file in a wrong project */ #ifndef qxk_h #error "Source file included in a project NOT based on the QXK kernel" #endif /* qxk_h */ Q_DEFINE_THIS_MODULE("qxk_xthr") /****************************************************************************/ static void QXThread_init_(QMsm * const me, QEvt const * const e); static void QXThread_dispatch_(QMsm * const me, QEvt const * const e); static void QXThread_start_(QActive * const me, uint_fast8_t prio, QEvt const *qSto[], uint_fast16_t qLen, void *stkSto, uint_fast16_t stkSize, QEvt const *ie); #ifndef Q_SPY static bool QXThread_post_(QActive * const me, QEvt const * const e, uint_fast16_t const margin); #else static bool QXThread_post_(QActive * const me, QEvt const * const e, uint_fast16_t const margin, void const * const sender); #endif static void QXThread_postLIFO_(QActive * const me, QEvt const * const e); /****************************************************************************/ /** * @description * Performs the first step of QXThread initialization by assigning the * thread-handler function and the tick rate at which it will handle * the timeouts. * * @param[in,out] me pointer (see @ref oop) * @param[in] handler the thread-handler function * * @note Must be called only ONCE before QXTHREAD_START(). * * @usage * The following example illustrates how to invoke QXThread_ctor() in the * main() function * @include qxk_xthread_ctor.c */ void QXThread_ctor(QXThread * const me, QXThreadHandler handler, uint_fast8_t tickRate) { static QXThreadVtbl const vtbl = { /* QXThread virtual table */ { &QXThread_init_, /* not used in QXThread */ &QXThread_dispatch_ }, /* not used in QXThread */ &QXThread_start_, &QXThread_post_, &QXThread_postLIFO_ }; QActive_ctor(&me->super, Q_STATE_CAST(handler)); /* superclass' ctor */ me->super.super.vptr = &vtbl.super; /* set the vptr to QXThread v-table */ me->super.super.state.act = Q_ACTION_CAST(0); /* mark as extended thread */ /* construct the time event member added in the QXThread class */ QTimeEvt_ctorX(&me->timeEvt, &me->super, (enum_t)QXK_DELAY_SIG, tickRate); } /****************************************************************************/ /* QXThread virtual function implementations... */ static void QXThread_init_(QMsm * const me, QEvt const * const e) { (void)me; (void)e; Q_ERROR_ID(110); } /****************************************************************************/ static void QXThread_dispatch_(QMsm * const me, QEvt const * const e) { (void)me; (void)e; Q_ERROR_ID(120); } /****************************************************************************/ /** * @description * Starts execution of the extended thread and registers it with the framework. * The extended thread becomes ready-to-run immediately and is scheduled * if the QXK is already running. * * @param[in,out] me pointer (see @ref oop) * @param[in] prio priority at which to start the extended thread * @param[in] qSto pointer to the storage for the ring buffer of the * event queue. This cold be NULL, if this extended * thread does not use the built-in event queue. * @param[in] qLen length of the event queue [in events], * or zero if queue not used * @param[in] stkSto pointer to the stack storage (must be provided) * @param[in] stkSize stack size [in bytes] (must not be zero) * @param[in] ie pointer to the initial event (not used). * * @note This function should be called via the macro QXTHREAD_START(). * * @usage * The following example shows starting an extended thread: * @include qxk_xthread_start.c */ static void QXThread_start_(QActive * const me, uint_fast8_t prio, QEvt const *qSto[], uint_fast16_t qLen, void *stkSto, uint_fast16_t stkSize, QEvt const *ie) { QF_CRIT_STAT_ Q_REQUIRE_ID(200, (!QXK_ISR_CONTEXT_()) /* don't call from an ISR! */ && (prio <= (uint_fast8_t)QF_MAX_ACTIVE) && (stkSto != (void *)0) /* stack must be provided */ && (stkSize != (uint_fast16_t)0) && (me->super.state.act == (QActionHandler)0)); (void)ie; /* parameter not referenced */ /* is storage for the queue buffer provided? */ if (qSto != (QEvt const **)0) { QEQueue_init(&me->eQueue, qSto, qLen); } /* extended thread constructor puts the thread handerl in place of * the top-most initial transition 'me->super.temp.act' */ QXK_stackInit_(me, Q_XTHREAD_CAST(me->super.temp.act), stkSto, stkSize); me->prio = prio; QF_CRIT_ENTRY_(); QF_add_(me); /* make QF aware of this extended thread */ /* the new thread is not blocked on any object */ me->super.temp.obj = (QMState const *)0; /* extended-thread becomes ready immediately */ QPSet_insert(&QXK_attr_.readySet, me->prio); /* see if this thread needs to be scheduled in case QXK is running */ (void)QXK_sched_(); QF_CRIT_EXIT_(); } /****************************************************************************/ /** * @description * Direct event posting is the simplest asynchronous communication method * available in QF. The following example illustrates how the Philo active * object posts directly the HUNGRY event to the Table active object.@n * @n * The parameter @p margin specifies the minimum number of free slots in * the queue that must be available for posting to succeed. The function * returns 1 (success) if the posting succeeded (with the provided margin) * and 0 (failure) when the posting fails. * * @param[in,out] me pointer (see @ref oop) * @param[in] e pointer to the event to be posted * @param[in] margin number of required free slots in the queue * after posting the event. * * @note this function should be called only via the macro QXTHREAD_POST_X(). * * @note The zero value of the @p margin parameter is special and denotes * situation when the post() operation is assumed to succeed (event delivery * guarantee). An assertion fires, when the event cannot be delivered in * this case. * * @note * For compatibility with the V-table from the superclass QActive, the * me-pointer is typed as pointing to QActive. However, the me pointer * here actually points to the QXThread subclass. Therefore the downcast * (QXThread *)me is always correct. */ #ifndef Q_SPY static bool QXThread_post_(QActive * const me, QEvt const * const e, uint_fast16_t const margin) #else static bool QXThread_post_(QActive * const me, QEvt const * const e, uint_fast16_t const margin, void const * const sender) #endif { bool status; QF_CRIT_STAT_ /* is it the private time event? */ if (e == &((QXThread *)me)->timeEvt.super) { QF_CRIT_ENTRY_(); /* the private time event is disarmed and not in any queue, * so it is safe to change its signal. The signal of 0 means * that the time event has expired. */ ((QXThread *)me)->timeEvt.super.sig = (QSignal)0; QXThread_unblock_((QXThread *)me); QF_CRIT_EXIT_(); status = true; } /* is the event queue provided? */ else if (me->eQueue.end != (QEQueueCtr)0) { QEQueueCtr nFree; /* temporary to avoid UB for volatile access */ /** @pre event pointer must be valid */ Q_REQUIRE_ID(300, e != (QEvt const *)0); QF_CRIT_ENTRY_(); nFree = me->eQueue.nFree; /* get volatile into the temporary */ /* margin available? */ if (nFree > (QEQueueCtr)margin) { QS_BEGIN_NOCRIT_(QS_QF_ACTIVE_POST_FIFO, QS_priv_.aoObjFilter, me) QS_TIME_(); /* timestamp */ QS_OBJ_(sender); /* the sender object */ QS_SIG_(e->sig); /* the signal of the event */ QS_OBJ_(me); /* this active object (recipient) */ QS_2U8_(e->poolId_, e->refCtr_); /* pool Id & ref Count */ QS_EQC_(nFree); /* number of free entries */ QS_EQC_(me->eQueue.nMin); /* min number of free entries */ QS_END_NOCRIT_() /* is it a pool event? */ if (e->poolId_ != (uint8_t)0) { QF_EVT_REF_CTR_INC_(e); /* increment the reference counter */ } --nFree; /* one free entry just used up */ me->eQueue.nFree = nFree; /* update the volatile */ if (me->eQueue.nMin > nFree) { me->eQueue.nMin = nFree; /* update minimum so far */ } /* empty queue? */ if (me->eQueue.frontEvt == (QEvt const *)0) { me->eQueue.frontEvt = e; /* deliver event directly */ /* is this thread blocked on the queue? */ if (me->super.temp.obj == (QMState const *)&me->eQueue) { (void)QXThread_teDisarm_((QXThread *)me); QPSet_insert(&QXK_attr_.readySet, me->prio); if (!QXK_ISR_CONTEXT_()) { (void)QXK_sched_(); } } } /* queue is not empty, insert event into the ring-buffer */ else { /* insert event into the ring buffer (FIFO) */ QF_PTR_AT_(me->eQueue.ring, me->eQueue.head) = e; if (me->eQueue.head == (QEQueueCtr)0) { /*need to wrap head?*/ me->eQueue.head = me->eQueue.end; /* wrap around */ } --me->eQueue.head; /* advance the head (counter clockwise) */ } QF_CRIT_EXIT_(); status = true; /* event posted successfully */ } else { /** @note assert if event cannot be posted and dropping events is * not acceptable */ Q_ASSERT_ID(310, margin != (uint_fast16_t)0); QS_BEGIN_NOCRIT_(QS_QF_ACTIVE_POST_ATTEMPT, QS_priv_.aoObjFilter, me) QS_TIME_(); /* timestamp */ QS_OBJ_(sender); /* the sender object */ QS_SIG_(e->sig); /* the signal of the event */ QS_OBJ_(me); /* this active object (recipient) */ QS_2U8_(e->poolId_, e->refCtr_); /* pool Id & ref Count */ QS_EQC_(nFree); /* number of free entries */ QS_EQC_(margin); /* margin requested */ QS_END_NOCRIT_() QF_CRIT_EXIT_(); QF_gc(e); /* recycle the event to avoid a leak */ status = false; /* event not posted */ } } else { /* the queue is not available */ QF_gc(e); /* make sure the event is not leaked */ status = false; Q_ERROR_ID(320); /* extened thread does not expect events */ } return status; } /****************************************************************************/ /** * @description * Last-In-First-Out (LIFO) policy is not supported for extened threads. * * @param[in] me pointer (see @ref oop) * @param[in e pointer to the event to post to the queue * * @sa QActive_postLIFO_() */ static void QXThread_postLIFO_(QActive * const me, QEvt const * const e) { (void)me; (void)e; Q_ERROR_ID(410); } /****************************************************************************/ /** * @description * The QXThread_queueGet() operation allows the calling extended thread to * receive QP events directly into its own built-in event queue from an ISR, * basic thread (AO), or another extended thread. * * If QXThread_queueGet() is called when no events are present in the thread’s * event queue, the operation blocks the current extended thread until either * an event is received, or a user-specified timeout expires. * * @param[in] nTicks number of clock ticks (at the associated rate) * to wait for the event to arrive. The value of * QXTHREAD_NO_TIMEOUT indicates that no timeout will * occur and the queue will block indefinitely. * @param[in] tickRate system clock tick rate serviced in this call. * * @returns * Returns pointer to the event. If the pointer is not NULL, the event * was delivered. Otherwise the event pointer of NULL indicates that the * queue has timed out. */ QEvt const *QXThread_queueGet(uint_fast16_t const nTicks, uint_fast8_t const tickRate) { QXThread *thr; QEQueueCtr nFree; QEvt const *e; QF_CRIT_STAT_ QF_CRIT_ENTRY_(); thr = (QXThread *)QXK_attr_.curr; Q_REQUIRE_ID(500, (!QXK_ISR_CONTEXT_()) /* can't block inside an ISR */ && (thr != (QXThread *)0) /* current thread must be extended */ && (thr->super.super.temp.obj == (QMState const *)0)); /* !blocked */ /* is the queue empty? */ if (thr->super.eQueue.frontEvt == (QEvt *)0) { /* remember the blocking object (the thread's queue) */ thr->super.super.temp.obj = (QMState const *)&thr->super.eQueue; QXThread_teArm_(thr, (QSignal)QXK_QUEUE_SIG, nTicks, tickRate); QPSet_remove(&QXK_attr_.readySet, thr->super.prio); (void)QXK_sched_(); QF_CRIT_EXIT_(); QF_CRIT_EXIT_NOP(); /* BLOCK here */ QF_CRIT_ENTRY_(); /* the blocking object must be this queue */ Q_ASSERT_ID(510, thr->super.super.temp.obj == (QMState const *)&thr->super.eQueue); thr->super.super.temp.obj = (QMState const *)0; /* clear */ } /* is the queue not empty? */ if (thr->super.eQueue.frontEvt != (QEvt *)0) { e = thr->super.eQueue.frontEvt; /* always remove from the front */ nFree= thr->super.eQueue.nFree +(QEQueueCtr)1; /* volatile into tmp */ thr->super.eQueue.nFree = nFree; /* update the number of free */ /* any events in the ring buffer? */ if (nFree <= thr->super.eQueue.end) { /* remove event from the tail */ thr->super.eQueue.frontEvt = QF_PTR_AT_(thr->super.eQueue.ring, thr->super.eQueue.tail); if (thr->super.eQueue.tail == (QEQueueCtr)0) { /* need to wrap? */ thr->super.eQueue.tail = thr->super.eQueue.end; /* wrap */ } --thr->super.eQueue.tail; QS_BEGIN_NOCRIT_(QS_QF_ACTIVE_GET, QS_priv_.aoObjFilter, thr) QS_TIME_(); /* timestamp */ QS_SIG_(e->sig); /* the signal of this event */ QS_OBJ_(&thr->super); /* this active object */ QS_2U8_(e->poolId_, e->refCtr_); /* pool Id & ref Count */ QS_EQC_(nFree); /* number of free entries */ QS_END_NOCRIT_() } else { thr->super.eQueue.frontEvt = (QEvt const *)0; /* empty queue */ /* all entries in the queue must be free (+1 for fronEvt) */ Q_ASSERT_ID(520, nFree == (thr->super.eQueue.end +(QEQueueCtr)1)); QS_BEGIN_NOCRIT_(QS_QF_ACTIVE_GET_LAST, QS_priv_.aoObjFilter, thr) QS_TIME_(); /* timestamp */ QS_SIG_(e->sig); /* the signal of this event */ QS_OBJ_(&thr->super); /* this active object */ QS_2U8_(e->poolId_, e->refCtr_); /* pool Id & ref Count */ QS_END_NOCRIT_() } } else { /* the queue is still empty -- the timeout must have fired */ e = (QEvt const *)0; } QF_CRIT_EXIT_(); return e; } /****************************************************************************/ /** * @description * Intenral implementation of blocking the given extended thread. * * @note * must be called from within a critical section */ void QXThread_block_(QXThread const * const me) { /*! @pre the thread holding the lock cannot block! */ Q_REQUIRE_ID(600, me->super.prio != QXK_attr_.lockPrio); QPSet_remove(&QXK_attr_.readySet, me->super.prio); (void)QXK_sched_(); } /****************************************************************************/ /** * @description * Intenral implementation of un-blocking the given extended thread. * * @note * must be called from within a critical section */ void QXThread_unblock_(QXThread const * const me) { QPSet_insert(&QXK_attr_.readySet, me->super.prio); if ((!QXK_ISR_CONTEXT_()) /* not inside ISR? */ && (QF_active_[0] != (QActive *)0)) /* kernel started? */ { (void)QXK_sched_(); } } /****************************************************************************/ /** * @description * Intenral implementation of arming the private time event for a given * timeout at a given system tick rate. * * @note * must be called from within a critical section */ void QXThread_teArm_(QXThread * const me, QSignal sig, uint_fast16_t const nTicks, uint_fast8_t const tickRate) { /* the time event must be unused */ Q_REQUIRE_ID(700, me->timeEvt.ctr == (QTimeEvtCtr)0); me->timeEvt.super.sig = sig; if (nTicks != QXTHREAD_NO_TIMEOUT) { me->timeEvt.ctr = (QTimeEvtCtr)nTicks; me->timeEvt.interval = (QTimeEvtCtr)0; /* is the time event unlinked? * NOTE: For the duration of a single clock tick of the specified tick * rate a time event can be disarmed and yet still linked in the list, * because un-linking is performed exclusively in QF_tickX(). */ if ((me->timeEvt.super.refCtr_ & (uint8_t)0x80) == (uint8_t)0) { me->timeEvt.super.refCtr_ |= (uint8_t)0x80; /* mark as linked */ /* The time event is initially inserted into the separate * "freshly armed" list based on QF_timeEvtHead_[tickRate].act. * Only later, inside the QF_tickX() function, the "freshly armed" * list is appended to the main list of armed time events based on * QF_timeEvtHead_[tickRate].next. Again, this is to keep any * changes to the main list exclusively inside QF_tickX(). */ me->timeEvt.next = (QTimeEvt *)QF_timeEvtHead_[tickRate].act; QF_timeEvtHead_[tickRate].act = &me->timeEvt; } } } /****************************************************************************/ /** * @description * Intenral implementation of disarming the private time event. * * @note * must be called from within a critical section */ bool QXThread_teDisarm_(QXThread * const me) { bool wasArmed; /* is the time evt running? */ if (me->timeEvt.ctr != (QTimeEvtCtr)0) { wasArmed = true; me->timeEvt.ctr = (QTimeEvtCtr)0; /* schedule removal from list */ } /* the time event was already automatically disarmed */ else { wasArmed = false; } return wasArmed; } /****************************************************************************/ /*! delay (timed block) the current extended thread (static, no me-pointer) */ bool QXThread_delay(uint_fast16_t const nTicks, uint_fast8_t const tickRate) { QXThread *thr; QF_CRIT_STAT_ QF_CRIT_ENTRY_(); thr = (QXThread *)QXK_attr_.curr; /* the delaying thread must not be blocked on any object */ Q_REQUIRE_ID(900, thr->super.super.temp.obj == (QMState const *)0); /* remember the blocking object */ thr->super.super.temp.obj = (QMState const *)&thr->timeEvt; QXThread_teArm_(thr, (QSignal)QXK_DELAY_SIG, nTicks, tickRate); QXThread_block_(thr); QF_CRIT_EXIT_(); QF_CRIT_EXIT_NOP(); /* BLOCK here */ QF_CRIT_ENTRY_(); /* the blocking object must be the time event */ Q_ENSURE_ID(990, thr->super.super.temp.obj == (QMState const *)&thr->timeEvt); thr->super.super.temp.obj = (QMState const *)0; /* clear */ QF_CRIT_EXIT_(); /* signal of zero means that the time event was posted without * being canceled. */ return (bool)(thr->timeEvt.super.sig == (QSignal)0); } /****************************************************************************/ /*! cancel the delay */ bool QXThread_delayCancel(QXThread * const me) { bool wasArmed; QF_CRIT_STAT_ QF_CRIT_ENTRY_(); if (me->super.super.temp.obj == (QMState const *)&me->timeEvt) { wasArmed = QXThread_teDisarm_(me); QXThread_unblock_(me); } else { wasArmed = false; } QF_CRIT_EXIT_(); return wasArmed; } /****************************************************************************/ /** * @description * Called when the extended-thread handler function returns. * * @note * Most thread handler functions are structured as endless loops that never * return. But it is also possible to structure threads as one-shot functions * that perform their job and return. In that case this function peforms * cleanup after the thread. */ void QXK_threadRet_(void) { uint_fast8_t p; QF_CRIT_STAT_ QF_CRIT_ENTRY_(); p = ((QActive volatile *)QXK_attr_.curr)->prio; /* remove this thread from the QF */ QF_active_[p] = (QActive *)0; QPSet_remove(&QXK_attr_.readySet, p); (void)QXK_sched_(); QF_CRIT_EXIT_(); }