QP/C  7.2.2
Real-Time Embedded Framework
Loading...
Searching...
No Matches
qxk.h File Reference

QXK/C (preemptive dual-mode kernel) platform-independent public interface. More...

#include "qequeue.h"
#include "qmpool.h"
#include "qf.h"

Go to the source code of this file.

Classes

class  QXK
 The QXK kernel class. More...
 
class  QXThread
 eXtended (blocking) thread of the QXK preemptive kernel More...
 
class  QXSemaphore
 Counting Semaphore of the QXK preemptive kernel. More...
 
class  QXMutex
 Blocking Mutex the QXK preemptive kernel. More...
 

Macros

#define QF_EQUEUE_TYPE   QEQueue
 
#define QF_OS_OBJECT_TYPE   void*
 
#define QF_THREAD_TYPE   void*
 
#define QXK_TLS(type_)   ((type_)QXK_current()->thread)
 
#define QXTHREAD_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
 
#define QXTHREAD_NO_TIMEOUT   ((uint_fast16_t)0)
 
#define QXTHREAD_POST_X(me_, e_, margin_, sender_)    QACTIVE_POST_X(&(me_)->super, (e_), (margin_), (sender_))
 
#define QXK_ISR_CONTEXT_()   (QF_intNest_ != 0U)
 
#define QF_SCHED_STAT_   QSchedStatus lockStat_;
 
#define QF_SCHED_LOCK_(ceil_)
 
#define QF_SCHED_UNLOCK_()
 
#define QACTIVE_EQUEUE_WAIT_(me_)    (Q_ASSERT_ID(110, (me_)->eQueue.frontEvt != (QEvt *)0))
 
#define QACTIVE_EQUEUE_SIGNAL_(me_)
 
#define QXK_PTR_CAST_(type_, ptr_)   ((type_)(ptr_))
 
#define QXTHREAD_CAST_(ptr_)   ((QXThread *)(ptr_))
 
#define QF_EPOOL_TYPE_   QMPool
 
#define QF_EPOOL_INIT_(p_, poolSto_, poolSize_, evtSize_)    (QMPool_init(&(p_), (poolSto_), (poolSize_), (evtSize_)))
 
#define QF_EPOOL_EVENT_SIZE_(p_)   ((uint_fast16_t)(p_).blockSize)
 
#define QF_EPOOL_GET_(p_, e_, m_, qs_id_)    ((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qs_id_)))
 
#define QF_EPOOL_PUT_(p_, e_, qs_id_)    (QMPool_put(&(p_), (e_), (qs_id_)))
 

Typedefs

typedef QActiveVtable QXThreadVtable
 Virtual Table for the QXThread class (inherited from QActiveVtable)
 

Variables

QXThread const * QXThread_dummy
 

Macro Definition Documentation

◆ QF_EQUEUE_TYPE

#define QF_EQUEUE_TYPE   QEQueue

Definition at line 50 of file qxk.h.

◆ QF_OS_OBJECT_TYPE

#define QF_OS_OBJECT_TYPE   void*

Definition at line 55 of file qxk.h.

◆ QF_THREAD_TYPE

#define QF_THREAD_TYPE   void*

Definition at line 58 of file qxk.h.

◆ QXK_TLS

#define QXK_TLS (   type_)    ((type_)QXK_current()->thread)

Access Thread-Local Storage (TLS) and cast it on the given type_

Definition at line 61 of file qxk.h.

◆ QXTHREAD_START

#define QXTHREAD_START (   me_,
  prioSpec_,
  qSto_,
  qLen_,
  stkSto_,
  stkSize_,
  par_ 
)
Value:
do { \
Q_ASSERT((me_)->super.super.vptr); \
((*((QActiveVtable const *)((me_)->super.super.vptr))->start)( \
&(me_)->super, (prioSpec_), (QEvt const **)(qSto_), (qLen_), \
(stkSto_), (stkSize_), (par_))); \
} while (false)
Virtual table for the QActive class.
Definition: qf.h:931
Event class.
Definition: qep.h:167

Virtual call to start an extened thread

Starts execution of the thread and registers the AO with the framework.

Parameters
[in,out]me_current instance pointer (see oop)
[in]prioSpec_priority specification at which to start the extended thread (see QPrioSpec)
[in]qSto_pointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLen_length of the event queue (in events)
[in]stkSto_pointer to the stack storage (used only when per-AO stack is needed)
[in]stkSize_stack size (in bytes)
[in]par_pointer to the additional port-specific parameter(s) (might be NULL).
Usage
#include "qpc.h"
Q_DEFINE_THIS_FILE
int main() {
. . .
QF_init(); /* initialize the framework */
BSP_init(); /* initialize the Board Support Package */
/* initialize publish-subscribe~~~ */
QF_psInit(subscrSto, Q_DIM(subscrSto));
/* initialize event pools~~~ */
QF_poolInit(smlPoolSto, sizeof(smlPoolSto), sizeof(smlPoolSto[0]));
/* start the active objects (basic threads)~~~ */
Table_ctor(); /* instantiate the Table AO */
QACTIVE_START(AO_Table, /* AO to start */
n + 1U, /* QF-priority */
tableQueueSto, /* event queue storage */
Q_DIM(tableQueueSto), /* queue length [events] */
tableStackSto, /* stack storage */
sizeof(tableStackSto), /* stack size [bytes] */
(void *)0); /* initialization param */
. . .
/* start the extended-threads~~~ */
Test_ctor(); /* instantiate the Test extended thread */
QXTHREAD_START(XT_Test, /* Thread to start */
10U, /* QF-priority */
testQueueSto, /* message queue storage */
Q_DIM(testQueueSto), /* message length [events] */
testStackSto, /* stack storage */
sizeof(testStackSto), /* stack size [bytes] */
(void *)0); /* initialization param */
return QF_run(); /* run the QF application */
}
#define Q_DIM(array_)
Definition: qassert.h:424
#define QACTIVE_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
Definition: qf.h:1907
static void QF_psInit(QSubscrList *const subscrSto, enum_t const maxSignal)
Definition: qf.h:1482
QP/C public interface including backwards-compatibility layer.
int_t QF_run(void)
Definition: qutest.c:190
void QF_init(void)
Definition: qutest.c:171
#define QXTHREAD_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_)
Definition: qxk.h:934

Definition at line 934 of file qxk.h.

◆ QXTHREAD_NO_TIMEOUT

#define QXTHREAD_NO_TIMEOUT   ((uint_fast16_t)0)

No-timeout when blocking on semaphores, mutextes, and queues

Definition at line 944 of file qxk.h.

◆ QXTHREAD_POST_X

#define QXTHREAD_POST_X (   me_,
  e_,
  margin_,
  sender_ 
)     QACTIVE_POST_X(&(me_)->super, (e_), (margin_), (sender_))

Asynchronous posting events to the event queue of an eXtended thread

This macro does not assert if the queue overflows and cannot accept the event with the specified margin of free slots remaining.

Parameters
[in,out]me_current instance pointer (see oop)
[in]e_pointer to the event to post
[in]margin_the minimum free slots in the queue, which must still be available after posting the event. The special value QF_NO_MARGIN causes asserting failure in case event allocation fails.
[in]sender_pointer to the sender object (used in QS tracing)
Returns
'true' if the posting succeeded, and 'false' if the posting failed due to insufficient margin of free slots available in the queue.
Note
The sender_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the QXTHREAD_POST_X() macro does not pass the sender_ parameter, so the overhead of passing this extra argument is entirely avoided.
The pointer to the sender object is not necessarily a pointer to an active object. In fact, if QXTHREAD_POST_X() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.
Usage
extern QActive * const AO_Table;
. . .
/* typically inside a state machine action */
TableEvt *pe;
Q_NEW_X(pe, TableEvt, 5U, HUNGRY_SIG); /* dynamic alloc, margin==5 */
if (pe != (TableEvt *)0) {
pe->philNum = me->num;
QACTIVE_POST_X(AO_Table, &pe->super, 3U, me); /* <--- */
}
. . .
#define Q_NEW_X(e_, evtT_, margin_, sig_,...)
Definition: qf.h:1834
#define QACTIVE_POST_X(me_, e_, margin_, sender_)
Definition: qf.h:1988
Active object class (based on the QHsm implementation strategy)
Definition: qf.h:372

Definition at line 979 of file qxk.h.

◆ QXK_ISR_CONTEXT_

#define QXK_ISR_CONTEXT_ ( )    (QF_intNest_ != 0U)

Internal macro that reports the execution context (ISR vs. thread)

Returns
true if the code executes in the ISR context and false otherwise

Definition at line 996 of file qxk.h.

◆ QF_SCHED_STAT_

#define QF_SCHED_STAT_   QSchedStatus lockStat_;

QXK scheduler lock status

Definition at line 1001 of file qxk.h.

◆ QF_SCHED_LOCK_

#define QF_SCHED_LOCK_ (   ceil_)
Value:
do { \
if (QXK_ISR_CONTEXT_()) { \
lockStat_ = 0xFFU; \
} else { \
lockStat_ = QXK_schedLock((ceil_)); \
} \
} while (false)
#define QXK_ISR_CONTEXT_()
Definition: qxk.h:996

QXK selective scheduler locking

Definition at line 1005 of file qxk.h.

◆ QF_SCHED_UNLOCK_

#define QF_SCHED_UNLOCK_ ( )
Value:
do { \
if (lockStat_ != 0xFFU) { \
QXK_schedUnlock(lockStat_); \
} \
} while (false)

QXK selective scheduler unlocking

Definition at line 1015 of file qxk.h.

◆ QACTIVE_EQUEUE_WAIT_

#define QACTIVE_EQUEUE_WAIT_ (   me_)     (Q_ASSERT_ID(110, (me_)->eQueue.frontEvt != (QEvt *)0))

QXK native event queue waiting

Definition at line 1023 of file qxk.h.

◆ QACTIVE_EQUEUE_SIGNAL_

#define QACTIVE_EQUEUE_SIGNAL_ (   me_)
Value:
do { \
QPSet_insert(&QF_readySet_, (uint_fast8_t)(me_)->prio); \
if (!QXK_ISR_CONTEXT_()) { \
if (QXK_sched_() != 0U) { \
QXK_activate_(); \
} \
} \
} while (false)

QXK native event queue signaling

Definition at line 1028 of file qxk.h.

◆ QXK_PTR_CAST_

#define QXK_PTR_CAST_ (   type_,
  ptr_ 
)    ((type_)(ptr_))

internal macro to encapsulate casting of pointers for MISRA deviations

This macro is specifically and exclusively used for casting pointers that are never de-referenced, but only used for internal bookkeeping and checking (via assertions) the correct operation of the QXK kernel. Such pointer casting is not compliant with MISRA-2012-Rule 11.3(req) as well as other messages (e.g., PC-Lint-Plus warning 826). Defining this specific macro for this purpose allows to selectively disable the warnings for this particular case.

Definition at line 1049 of file qxk.h.

◆ QXTHREAD_CAST_

#define QXTHREAD_CAST_ (   ptr_)    ((QXThread *)(ptr_))

internal macro to encapsulate casting of pointers for MISRA deviations

This macro is specifically and exclusively used for downcasting pointers to QActive to pointers to QXThread in situations when it is known that such downcasting is correct.However, such pointer casting is not compliant with MISRA-2012-Rule 11.3(req) as well as other messages (e.g., PC-Lint-Plus warning 826). Defining this specific macro for this purpose allows to selectively disable the warnings for this particular case.

Definition at line 1062 of file qxk.h.

◆ QF_EPOOL_TYPE_

#define QF_EPOOL_TYPE_   QMPool

Definition at line 1090 of file qxk.h.

◆ QF_EPOOL_INIT_

#define QF_EPOOL_INIT_ (   p_,
  poolSto_,
  poolSize_,
  evtSize_ 
)     (QMPool_init(&(p_), (poolSto_), (poolSize_), (evtSize_)))

Definition at line 1093 of file qxk.h.

◆ QF_EPOOL_EVENT_SIZE_

#define QF_EPOOL_EVENT_SIZE_ (   p_)    ((uint_fast16_t)(p_).blockSize)

Definition at line 1097 of file qxk.h.

◆ QF_EPOOL_GET_

#define QF_EPOOL_GET_ (   p_,
  e_,
  m_,
  qs_id_ 
)     ((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qs_id_)))

Definition at line 1100 of file qxk.h.

◆ QF_EPOOL_PUT_

#define QF_EPOOL_PUT_ (   p_,
  e_,
  qs_id_ 
)     (QMPool_put(&(p_), (e_), (qs_id_)))

Definition at line 1104 of file qxk.h.

Typedef Documentation

◆ QXThreadVtable

Note
QXThread inherits QActive without adding any new virtual functions and therefore, QXThreadVtable is typedef'ed as QActiveVtable.

Definition at line 595 of file qxk.h.

Variable Documentation

◆ QXThread_dummy

QXThread const* QXThread_dummy
extern

dummy static to force generation of "struct QXThread"